Registry protocol

The registry protocol is part of the standard. ctxpkg.com is one implementation — any organization MAY run a private or public registry speaking the same protocol, and any client speaking it works against all of them.

1Model#

In plain terms: a registry is where packages live online — an app store for agent knowledge. This protocol is open so anyone can run one, and every tool works with every registry.

A registry is an HTTP service rooted at a configurable base URL (clients accept --registry <url>; the reference CLI defaults to https://ctxpkg.com/api). All routes below are relative to that base. Responses are JSON unless stated otherwise. Package identity is the scoped name @namespace/name plus a SemVer version; artifacts are immutable — a published version is never replaced, only superseded.

2Endpoints#

Method & path	Auth	Purpose
GET /v1/index.json	—	Catalog: all packages with latest version, description, price, quality
GET /v1/search?q=…	—	Full-text search over names, descriptions, tags
GET /v1/packages/{ns}/{name}/index.json	—	Package detail: versions, readme, quality, ROI, price
GET /v1/packages/{ns}/{name}/{ver}/download	conditional	The .ctxpkg artifact (§5)
PUT /v1/packages/{ns}/{name}/{ver}	ctxp_	Publish a signed artifact (§3)
GET /v1/badge/{ns}/{name}	—	SVG badge for READMEs
GET /v1/publishers/{ns}/index.json	—	Publisher profile: packages, verified domains

A registry MUST serve index.json, package detail and download; everything else is OPTIONAL but RECOMMENDED for parity with the reference.

3Publishing#

The publish request body is the raw .ctxpkg bytes. The registry MUST verify, in order:

1. Token — a publish-scoped bearer token bound to the namespace.
2. Shape — valid JSON against the published schema; scoped name matches the URL.
3. Integrity — recomputed hashes match the manifest.
4. Signature — Ed25519 signature verifies; the registry records the public key.
5. Secret scan — content is scanned for credential-shaped strings; high-confidence findings MUST reject with 422 and a findings report. No override.
6. Immutability — the version does not already exist (409 otherwise).

4Tokens#

Prefix	Scope	Use
ctxp_	publish	Authorization: Bearer on publish requests
ctxr_	read	Installing private or purchased packages

Registries MUST store only token digests (SHA-256), never plaintext. Tokens are displayed once at mint time. The prefix convention lets clients fail fast on scope mismatches before any network call.

5Paid packages#

A registry MAY price packages. The download endpoint then responds 402 Payment Required with a JSON body carrying a buy_url. Free packages SHOULD be downloadable anonymously (rate-limited) — frictionless installs are how an ecosystem grows. Purchased access is granted to authenticated, entitled accounts via ctxr_ tokens.

6Safety obligations#

• Serve artifacts byte-identical to what was published (content-addressable storage RECOMMENDED).
• Reject unsigned publishes; expose the verified public key on the package detail.
• Run server-side secret scanning — client-side scanning is a courtesy, server-side is the guarantee.
• Rate-limit anonymous downloads and magic-link/auth endpoints.
• Quality scoring, trust reports and verified-publisher domains (DNS challenge) as implemented by the reference registry are RECOMMENDED.

7Running your own#

The reference registry is a single Rust/Axum service with PostgreSQL and a blob volume — no external dependencies beyond SMTP and (optionally) Stripe. Point any client at it with:

lean-ctx pack publish my-pkg.ctxpkg --registry https://registry.internal.acme.com/api
lean-ctx pack install @acme/platform-context --registry https://registry.internal.acme.com/api

Conformance for registries is part of the conformance program: a registry claiming CTXPKG conformance must implement §2's required endpoints and all of §3's publish verification steps.