Pantry registry

This reference is reproduced from Pantry v0.10.36 at immutable commit a6bdc42071cc659896d1b9ff9d7ab6862c72954d. The copied contract and its executable evidence are checksummed in evidence/pantry/evidence.lock.json. Stacks relies on this boundary; it does not redefine Pantry behavior.

The text below is the upstream implementation contract. Normative words apply to Pantry at the pinned revision, not to every historical Pantry version.

This is the authoritative technical and operational reference for the registry implemented in packages/registry. Route handlers remain the executable source of truth. bun run docs:contracts:check verifies that critical routes, methods, authentication boundaries, limits, storage semantics, and test links remain represented here.

Responsibilities and trust boundaries

The registry provides five distribution surfaces:

1. Pantry/npm-compatible package metadata and tarballs.
2. Commit-addressed preview packages used by pantry publish:commit.
3. Content-addressed Zig packages.
4. PHP/Composer packages.
5. Native binary, desktop application, and font metadata/tarball proxying.

It also serves search, analytics, publisher accounts/tokens, build status, and the Pantry website. These surfaces share a process but not identical auth or integrity semantics; clients must use the contract for the selected surface.

Core package API

Publishing validates package name, version, metadata size, content type, and a 50 MiB tarball limit. A duplicate {name, version} returns 409 before the tarball is buffered where possible. Successful publication returns 201; it does not overwrite an existing immutable version.

The registry computes SHA-256 over uploaded bytes and records it as sha256:{hex} alongside the canonical public proxy URL. This is integrity evidence for the bytes received. It does not authenticate the publisher; publisher identity comes from the accepted credential.

Commit package API

Each commit tarball is limited to 50 MiB. Production object storage applies the documented expiry policy to the commits/ prefix. Commit packages are previews, not permanent semantic-version releases. Consumers should retain the commit SHA, source repository, checksum, and test evidence.

Zig API

Zig publication computes the 1220 SHA-256 multihash over received bytes. Manifest names using underscores are canonicalized to hyphens. The auth token is read per request so a rotated token takes effect without re-importing the route module; comparison is timing-safe and missing server configuration fails closed.

PHP/Composer API

PHP token lookup is per request and fails closed when the server token is missing. The registry checksum is SHA-256 over the uploaded archive.

Bulk resolver and native binary surfaces

Binary paths are allowlisted and normalized before proxying. Public URLs may use the registry proxy while storage remains private. A binary checksum is evidence only when the client verifies it; availability metadata alone is not verification.

Authentication and authorization

The registry supports:

• a legacy operator token from PANTRY_REGISTRY_TOKEN or PANTRY_TOKEN;
• account API tokens prefixed ptry_, stored only as hashes and scoped with publish and/or read permissions;
• HTTP-only web sessions for publisher/dashboard operations;
• npm trusted-publisher/OIDC flows in the Pantry CLI for compatible targets.

Core and commit publication accept the legacy token or a valid user publish token. Build-event, build-log, and rebuild mutations accept an authorized bearer token or signed-in session. Zig and PHP mutation routes currently accept the operator token, not user API tokens. This is current behavior, not uniform auth.

Passwords are hashed. Login performs a dummy hash for missing users to reduce timing enumeration. Session/API secrets are stored as hashes, token expiry is enforced, and legacy token comparisons use constant-time primitives.

Publication validation and ownership

Package names and versions are normalized and validated before they influence a storage key. Metadata field sizes are bounded. Multipart and JSON publication share the same name, version, duplicate, and metadata validation. JSON base64 is decoded only after those cheap checks, and malformed data returns 400.

When a user API token publishes a core or commit package, the registry records the authenticated publisher. The legacy operator token represents _admin and does not fabricate a normal publisher identity. Publisher dashboard mutations verify ownership unless the account is an administrator.

Deletion is deliberately narrower than publication: Zig/PHP deletion currently uses the operator token, while publisher-account package settings use the account authorization path. Operators should not expose the legacy token to ordinary CI jobs when a scoped API token is supported.

Storage model

The registry separates tarball/blob storage from metadata and analytics:

Production supports AWS-compatible and Hetzner object storage. The bucket may remain private because the server exposes canonical proxy routes. Writes upload bytes before version metadata. Operators must monitor both steps; an interrupted operation can require reconciliation even though the API returns success only after both complete.

METADATA_BACKEND explicitly selects object, dynamodb, or file. When it is unset, an object provider selects the portable object snapshot, a configured AWS table may retain DynamoDB compatibility, and local operation uses the file backend. Zig, PHP, authentication, and analytics factories follow the same deployment distinction: object snapshots are the portable path, while the DynamoDB implementations remain available when their table variables are set. Do not mix independently restored generations of these stores.

Important variables include BASE_URL, REGISTRY_INTERNAL_URL, S3_BUCKET, S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, METADATA_BACKEND, DYNAMODB_TABLE, DYNAMODB_ANALYTICS_TABLE, PANTRY_REGISTRY_TOKEN, PANTRY_TOKEN, and NPM_FALLBACK. NPM_FALLBACK=false turns missing Pantry metadata into a local miss instead of querying npm. Prefer the S3_* names for portable object storage; legacy AWS_* credentials remain relevant to the AWS-specific backends.

The public BASE_URL is stored in metadata and returned to clients. The internal URL is used for server-side storage proxying when public routing would be inefficient or recursive. Operators must configure both with valid schemes and must not point the internal URL at an untrusted host.

npm fallback and outbound request safety

When enabled, npm fallback can supplement search, metadata, version lists, and tarball downloads. Local results win and duplicate npm search results are removed. External tarball URLs must use HTTPS and pass blocked-host checks; local/private-address targets are rejected to limit SSRF. Pantry-owned tarballs use a canonical internal storage key derived from validated name and version, not a user-supplied object key embedded in metadata.

Fallback is a read behavior. A miss in Pantry does not cause an npm package to be copied or published into Pantry. Disabling fallback is the correct mode for operators who require the registry to serve only explicitly stored artifacts.

Analytics and build operations

Public read routes include /analytics/{name}, /analytics/top, category period views, /api/packages, /api/build-status, /api/github-actions-status, /api/build-events-stream, /api/rebuild-queue, /api/unavailable-versions, and bounded build-log reads. State-changing routes /analytics/events, /api/build-events, /api/build-logs, and /api/rebuild validate bodies and apply the auth policy in their handler.

The SSE endpoint sends an initial snapshot, event updates, and heartbeat comments, then cleans up subscriptions and timers on disconnect. Builder ingestion bounds event batches and log lines to prevent one request from growing memory without limit. Rebuild package/domain inputs use a restricted character and length set.

Analytics failure must not corrupt package bytes. Download/publish analytics are best-effort in route families where the handler explicitly catches tracking errors. Operators should alert on persistent analytics failures without misreporting them as package-integrity failures.

HTTP and error contract

CORS allows public browser reads and declared mutation methods/headers. Cache headers vary: volatile build state is no-store, bounded catalog views use short public caching, and package bytes are served with explicit content types.

Operational deployment and recovery

Production deployment must provide a writable metadata/blob backend, stable public URL, internal URL, operator token, and storage credentials. Keep the object bucket private unless a separate policy explicitly requires public access. Use the storage configuration script only with reviewed environment values.

Back up the active metadata backend and package prefixes together. For object mode this means the metadata snapshots; for DynamoDB mode this means a consistent table backup. Restoring metadata without corresponding tarballs creates visible versions that cannot be downloaded; restoring tarballs without metadata leaves unreachable objects. Reconciliation should compare metadata keys, object keys, checksums, and public proxy reads before traffic is promoted.

Token rotation is effective immediately for core, commit, Zig, PHP, and admin handlers that read the current environment; the service environment must itself be updated. Existing account sessions/API tokens have their own persisted expiry and revocation lifecycle.

Before a production deployment:

bun run docs:contracts:check
bun test packages/registry/src
bun run --cwd packages/registry typecheck
curl -fsS https://registry.pantry.dev/health

Then verify one real metadata lookup and tarball checksum through the public proxy. A green health route without a storage read is not end-to-end health.

Test and evidence map