Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
570 changes: 459 additions & 111 deletions apiary.apib

Large diffs are not rendered by default.

35 changes: 27 additions & 8 deletions endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,13 +95,31 @@ Used by: `mix hex.publish`, `rebar3 hex publish`, `gleam publish`
| API | `GET /packages/NAME` | Check if package exists |
| API | `GET /users/me` | Get current user (for new packages) |
| API | `PUT /packages/NAME/owners/USERNAME` | Add first owner (for new packages) |
| API | `GET /packages/NAME/releases/VERSION/staged` | Poll a staged release until a person approves it |
| API | `GET /packages/NAME/releases/VERSION/docs/staged` | Poll staged documentation until a person approves it |

When staged publishing applies (see the Staged Publishing section of the HTTP API), the publish endpoints answer with a staged release instead of a release. The `Location` header has the URL to poll.

### Publishing from CI with Workload Identity

Used by: `mix hex.publish`, `rebar3 hex publish` in GitHub Actions

| Type | Endpoint | Purpose |
|------|----------|---------|
| API | `GET /oidc/audience` | Check that the server expects the configured audience (`hexpm` by default) before requesting the GitHub Actions OIDC token |
| API | `POST /oauth/token` | Exchange the OIDC token with the JWT Bearer Grant (`scope=package:REPOSITORY/PACKAGE`) |
| API | `POST /publish` | Publish with `Authorization: Bearer TOKEN` |
| API | `POST /oauth/revoke` | Revoke the token before it expires (optional) |

To fetch from a private repository, exchange with `scope=repository:ORGANIZATION` and send the token to the repository endpoint.

### Package Retirement

Used by: `mix hex.retire`, `rebar3 hex retire`, `gleam retire`

| Type | Endpoint | Purpose |
|------|----------|---------|
| API | `POST /packages/NAME/retire` | Retire all releases |
| API | `POST /packages/NAME/releases/VERSION/retire` | Retire a release |
| API | `DELETE /packages/NAME/releases/VERSION/retire` | Unretire a release |

Expand All @@ -118,20 +136,23 @@ Used by: `mix hex.owner`, `rebar3 hex owner`, `gleam owner`

### Authentication

**OAuth2 Device Authorization** (used by: `mix hex.user auth`, `gleam authenticate`):
**OAuth2 Device Authorization** (used by: `mix hex.user auth`, `rebar3 hex user auth`, `gleam authenticate`):

| Type | Endpoint | Purpose |
|------|----------|---------|
| API | `POST /oauth/device_authorization` | Start device authorization flow |
| API | `POST /oauth/token` | Poll for token / refresh token |
| API | `POST /oauth/revoke` | Revoke token |
| API | `POST /oauth/revoke_by_hash` | Revoke token by hash |
| API | `POST /oauth/organization_authorization` | Sign in to organizations that require single sign-on |

**API Key Generation** (used by: `rebar3 hex user auth`):
**API Key Exchange** (used by: `mix hex.organization auth`):

| Type | Endpoint | Purpose |
|------|----------|---------|
| API | `POST /keys` | Create API key (with Basic Auth) |
| API | `POST /oauth/token` | Exchange an organization API key for a short-lived token (`grant_type=client_credentials`) |

The API does not accept Basic authentication.

### API Key Management

Expand All @@ -146,7 +167,7 @@ Used by: `mix hex.organization key`, `rebar3 hex user key`, `rebar3 hex organiza
| API | `DELETE /keys` | Delete all keys |
| API | `GET /auth` | Test key permissions |

For organization keys, use `/orgs/ORG/keys` instead.
For organization keys, use `/orgs/ORG/keys` instead. Creating and deleting keys requires an OAuth token from the Device Authorization Grant. The API refuses API keys for these requests.

### Package Information

Expand Down Expand Up @@ -180,11 +201,9 @@ Used by: `mix hex.docs`

### User Management

Used by: `rebar3 hex user register`, `rebar3 hex user reset_password`

| Type | Endpoint | Purpose |
|------|----------|---------|
| API | `POST /users` | Create new user account |
| API | `GET /users/NAME` | Get user information |
| API | `GET /users/me` | Get authenticated user |
| API | `POST /users/NAME/reset` | Request password reset |

Users register and reset passwords on the web interface. The API does not support these actions.
3 changes: 1 addition & 2 deletions security/sdlc/risk-register.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ This document tracks accepted security risks and their mitigations for Hex regis

| ID | Risk | Severity | Status | Threats | Mitigation | Reference |
|----|------|----------|--------|---------|------------|-----------|
| R-001 | Basic Authentication maintained for backward compatibility | Medium | Mitigating | [T4](../threat-model/threats.md#t4-account-takeover) | OAuth2 migration planned; rate limiting in place | Security Audit 2026 |
| R-002 | Documentation hosted as full websites (HTML/JS) | Low | Accepted | [T5](../threat-model/threats.md#t5-documentation-based-attacks) | Malicious content removed upon report | Security Audit 2026 |
| R-003 | User enumeration via API | Low | Accepted | [T4](../threat-model/threats.md#t4-account-takeover) | Users are public for package publication; profile info is user-provided | Security Audit 2026 |
| R-004 | No WAF | Low | Accepted | [T6](../threat-model/threats.md#t6-registry-infrastructure-compromise) | SQL injection prevented by Ecto; XSS prevented by CSP; little added value expected | Security Audit 2026 |
Expand Down Expand Up @@ -40,4 +39,4 @@ This document tracks accepted security risks and their mitigations for Hex regis

| ID | Risk | Resolution Date | Resolution |
|----|------|-----------------|------------|
| - | - | - | - |
| R-001 | Basic Authentication maintained for backward compatibility | 2026-11-01 | The API refuses Basic authentication. Mix, Rebar3, and Gleam use the OAuth2 Device Authorization Grant |
7 changes: 4 additions & 3 deletions security/supply-chain/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,8 @@ flowchart LR
| Audit logging | All publishing actions are logged | Implemented |
| Owner notifications | All package owners are notified by email when a new version is published or when owners are added or removed | Implemented |
| 2FA for publishing | OTP required for write operations via OAuth | Implemented |
| Trusted publishing (OIDC) | Short-lived CI credentials | Planned |
| Workload Identity (OIDC) | Short-lived CI credentials from GitHub Actions | Implemented |
| Staged publishing | Human approval with 2FA for publishes from API keys and workload identities | Implemented |
| Build provenance (SLSA) | Cryptographic proof of build origin | Planned |

### Distribution Side
Expand All @@ -74,8 +75,8 @@ flowchart LR
| Stage | Threats | Current Mitigations |
|-------|---------|---------------------|
| Maintainer | Compromised credentials, malicious insider | 2FA, OAuth, audit logs |
| Build | Compromised build environment | None (planned: trusted publishing, SLSA provenance) |
| Publishing | Unauthorized publish, tampering | Authentication, authorization |
| Build | Compromised build environment | Workload Identity binds publishes to a GitHub workflow, staged publishing (planned: SLSA provenance) |
| Publishing | Unauthorized publish, tampering | Authentication, authorization, staged publishing |
| Distribution | CDN/mirror tampering, MITM | Signed registry, checksums |
| Consumption | Dependency confusion, typosquatting, vulnerable/retired versions | Repository field verification, typosquatting detection, advisory CLI reporting and dependency policies (Hex/Mix) |

Expand Down
33 changes: 20 additions & 13 deletions security/supply-chain/provenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,34 +18,40 @@ Provenance answers:
| Attribute | Tracked | Verifiable | Notes |
|-----------|---------|------------|-------|
| Publishing user | Yes | Via audit log | Account that initiated publish |
| CI identity | Yes, for Workload Identity publishes | Via API (`oidc_claims`) | Verified GitHub repository, commit, workflow, ref, environment, run, and actor |
| Approver | Yes, for staged releases | Via audit log | Person who approved the staged release |
| Publish timestamp | Yes | Via API | Stored on the release record and exposed via the HTTP API; not part of the signed registry |
| Publishing IP/client | Yes | Via audit log | Internal only |
| Source repository | Yes | Metadata only | Maintainer-provided, not verified |
| Source repository | Yes | Metadata only, or `oidc_claims` | Maintainer-provided and not verified, except the repository in `oidc_claims` |
| Build environment | No | No | Planned with SLSA provenance |
| Build commands | No | No | Planned with SLSA provenance |

### Limitations
### Workload Identity (OIDC)

- No cryptographic proof of build origin
- Source link is maintainer-provided metadata (not verified)
- Build environment is not attested
- No way to verify package was built from claimed source

## Planned Improvements

### Trusted Publishing (OIDC)
Workload Identity, sometimes also known as Trusted Publishing, lets a GitHub Actions job publish without a stored API key. Hex.pm verifies the job's OIDC token, matches it against a workload identity that the package owners configured, and records the verified claims on the release. The release API exposes them as `oidc_claims`. The package page shows them in a Provenance card.

| Feature | Description | Status |
|---------|-------------|--------|
| GitHub Actions | OIDC-based publishing from GitHub CI | Planned |
| GitHub Actions | OIDC-based publishing from GitHub CI | Implemented |
| GitLab CI | OIDC-based publishing from GitLab | Planned |
| Other providers | Extensible OIDC provider support | Future |

Benefits:
- No long-lived secrets needed in CI
- Verifiable link to source repository
- Verified link to the source repository and commit
- Repository-bound publishing authority

The claims say which workflow run published the release. They do not prove what the workflow built. The record is in the hex.pm database and the API, and is not part of the signed registry.

### Limitations

- No cryptographic proof of build origin that clients can verify offline
- Source link is maintainer-provided metadata (not verified), except for Workload Identity publishes
- Build environment is not attested
- No way to verify package was built from claimed source

## Planned Improvements

### SLSA Build Provenance

SLSA (Supply-chain Levels for Software Artifacts) provenance provides
Expand Down Expand Up @@ -82,7 +88,8 @@ All publication events will be recorded in an append-only transparency log:
|-------------------|-------------|----------------------|
| Manual (API key) | Low | Account only |
| OAuth with 2FA | Medium | Account + 2FA |
| Trusted Publishing | High | Account + CI identity + repository |
| API key or Workload Identity with staged publishing | Medium | Credential + approval by a maintainer with 2FA |
| Workload Identity | High | Package owner configuration + CI identity + repository |
| SLSA Provenance | Highest | Full build chain verification |

## Consumer Guidance
Expand Down
22 changes: 17 additions & 5 deletions security/threat-model/actors.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Developers and CI/CD systems that install and use packages.

| Attribute | Description |
|-----------|-------------|
| Access | Unauthenticated read access to public packages; API key for private |
| Access | Unauthenticated read access to public packages. API key, OAuth token, or workload identity token for private packages |
| Trust level | Untrusted (no write access) |
| Capabilities | Download packages, read registry metadata, view documentation |

Expand All @@ -21,13 +21,25 @@ Developers and CI/CD systems that install and use packages.
Developers who publish and manage packages. There are two ownership levels:

- **Maintainer** — publish, retire/unretire releases, upload documentation
- **Owner** — all maintainer capabilities, plus manage package ownership
- **Owner** — all maintainer capabilities, plus manage package ownership, workload identities, and staged publishing settings

A maintainer with 2FA approves or rejects staged releases.

| Attribute | Description |
|-----------|-------------|
| Access | Authenticated API access, publishing permissions |
| Trust level | Trusted for their own packages |

### CI Workload

A GitHub Actions job that authenticates with a workload identity instead of a stored API key.

| Attribute | Description |
|-----------|-------------|
| Access | Short-lived token from an OIDC token exchange, scoped to one package or one organization repository |
| Trust level | Trusted for the package or repository that the workload identity covers |
| Capabilities | Publish releases and documentation, or fetch from a private repository. Cannot revert, retire, or change owners, keys, members, or settings |

### Organization Administrator

Manages private repositories and teams within an organization.
Expand All @@ -36,7 +48,7 @@ Manages private repositories and teams within an organization.
|-----------|-------------|
| Access | Elevated permissions within organization scope |
| Trust level | Trusted for organization resources |
| Capabilities | Manage members, configure billing, access private packages |
| Capabilities | Manage members, configure billing, access private packages, configure organization workload identities, require staged publishing for the private repository |

### Hex.pm Operator

Expand All @@ -46,7 +58,7 @@ Maintains and operates the registry infrastructure.
|-----------|-------------|
| Access | Infrastructure and administrative access |
| Trust level | Highly trusted |
| Capabilities | System administration, incident response, policy enforcement |
| Capabilities | System administration, incident response, policy enforcement, emergency publishing mode |

## Adversarial Actors

Expand Down Expand Up @@ -80,7 +92,7 @@ Maintains and operates the registry infrastructure.
|-----------|-------------|
| Goal | Compromise build/release pipeline |
| Access | Indirect via dependencies or tooling |
| Capabilities | Compromise CI systems, tamper with build artifacts, inject backdoors via dependencies |
| Capabilities | Compromise CI systems, tamper with build artifacts, inject backdoors via dependencies, run a workflow that matches a workload identity |

### Insider Threat

Expand Down
24 changes: 18 additions & 6 deletions security/threat-model/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,17 +50,17 @@ C4Context
System_Ext(fastly, "Fastly CDN", "Global content delivery and edge compute")
System_Ext(storage, "Cloud Storage", "Package artifacts and registry files")

System_Ext(github, "GitHub", "OAuth authentication and source code hosting")
System_Ext(github, "GitHub", "OAuth authentication, source code hosting, and Actions OIDC issuer")
System_Ext(email, "Email Service", "Sends notifications and password resets")

Rel(consumer, hex, "API requests", "HTTPS")
Rel(consumer, fastly, "Repository requests", "HTTPS")
Rel(maintainer, hex, "Publishes packages", "HTTPS + API Key")
Rel(maintainer, hex, "Publishes packages", "HTTPS + OAuth, API Key, or Workload Identity")
Rel(operator, hex, "Administers", "Internal")

Rel(fastly, storage, "Serves registry + tarballs", "HTTPS cached")

Rel(hex, github, "OAuth authentication")
Rel(hex, github, "OAuth authentication, OIDC key and repository lookups")
Rel(hex, email, "Sends notifications")
Rel(hex, storage, "Stores packages")

Expand All @@ -74,7 +74,7 @@ C4Context
- **Hex.pm Operators** - Maintain and operate the registry infrastructure

**External Systems:**
- **GitHub** provides OAuth authentication and hosts package source code
- **GitHub** provides OAuth authentication, hosts package source code, and issues the OIDC tokens that GitHub Actions jobs exchange for workload identity tokens
- **Email Service** sends password resets, ownership notifications, etc.
- **Fastly CDN** caches and delivers registry files and package tarballs globally

Expand Down Expand Up @@ -273,6 +273,12 @@ C4Context
- **Controls**: Signed registry, checksums, signature verification
- **Critical**: Clients must NEVER send credentials to untrusted mirrors

### Boundary 2a: CI Provider to Registry API

- **Crosses**: GitHub Actions OIDC tokens, workload identity tokens
- **Controls**: OIDC signature verification against GitHub's keys, audience check, single-use `jti`, refusal of privileged triggers, match against pinned GitHub IDs, workflow, and environment, 15 minute token lifetime, staged publishing
- **Critical**: Hex.pm trusts GitHub to issue OIDC tokens only to the workflow runs that the claims describe

### Boundary 3: Internal Services

- **Crosses**: Database connections, internal APIs
Expand All @@ -289,7 +295,8 @@ C4Context
|------|----------|--------|----------------|-----------|
| Client → Registry files | HTTPS | Protobuf + gzip | None (public) or API key (private) or OAuth2 (private) | RSA-PKCS1-SHA512 signatures |
| Client → Tarballs | HTTPS | tar | None (public) or API key (private) or OAuth2 (private) | Checksums |
| Client → API | HTTPS | JSON | API key (Bearer token) or OAuth | TLS |
| Client → API | HTTPS | JSON | API key or OAuth access token (Bearer). OAuth access tokens come from the device code, client credentials, or JWT Bearer grant | TLS |
| CI job → API (token exchange) | HTTPS | Form + JSON | GitHub Actions OIDC token as the JWT Bearer Grant assertion | TLS |
| Browser → Web | HTTPS | HTML | Session cookie | TLS |
| Browser → Docs | HTTPS | HTML | None | TLS + CSP |
| hex.pm → PostgreSQL | TCP | PostgreSQL protocol | Connection credentials | - |
Expand All @@ -308,8 +315,13 @@ sequenceDiagram
participant Worker as Registry Builder
participant CDN as Fastly CDN

Client->>API: Publish package (Bearer: API key or OAuth access token; OAuth tokens additionally require x-hex-otp)
Client->>API: Publish package (Bearer: API key or OAuth access token, user OAuth tokens also require x-hex-otp)
API->>API: Validate authentication & authorization
opt Staged publishing applies (API key, organization key token, or workload identity)
API->>DB: Store staged release
API-->>Client: 201 Created (staged release)
Note over API: A maintainer with 2FA approves on the dashboard, then the flow below continues
end
API->>DB: Store package metadata
API->>S3: Upload tarball
API->>Worker: Trigger registry rebuild
Expand Down
13 changes: 12 additions & 1 deletion security/threat-model/assets.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,17 @@ Bearer tokens for API access.
|-----------|-------------|
| Location | Database (hashed), client machines (plaintext/encrypted) |
| Impact if compromised | Unauthorized actions within token scope |
| Protection | Scoping, revocation, short-lived OAuth tokens |
| Protection | Scoping, revocation, short-lived OAuth and workload identity tokens, `hex_` prefix for secret scanning, staged publishing |

### Workload Identity Configuration

The GitHub owner, repositories, workflow, and environment that a package or organization trusts to publish or fetch.

| Attribute | Description |
|-----------|-------------|
| Location | Database |
| Impact if compromised | An attacker-controlled workflow can publish the covered packages or fetch private packages |
| Protection | Full ownership or organization admin role with 2FA to change, pinned GitHub IDs, email notifications, audit log |

## High Value Assets

Expand Down Expand Up @@ -134,6 +144,7 @@ Impact ratings use [CVSS v4.0](https://www.first.org/cvss/v4.0/specification-doc
| Registry Signing Key | High | High | High |
| Maintainer Accounts | High | High | Low |
| API Tokens | High | High | Low |
| Workload Identity Configuration | Low | High | Low |
| Documentation Content | None | Low | Low |
| Package Ownership | Low | High | Low |
| Organization Data | High | High | Low |
Expand Down
Loading
Loading