Techniques

Publishing Extensions

The complete publish pipeline: login, pack, sign, publish, and token management.

Publishing an OXP extension involves four steps: authenticate, generate a signing key, pack the bundle, and upload. Every bundle is cryptographically signed and verified end-to-end.

Step 1: Authenticate

bash
oxp login                   # email + password in the terminal
oxp login --browser          # OAuth device flow via the browser

The terminal login flow works like Expo — type your email and password directly. The browser flow generates a short code you enter on the web, then the CLI polls until authorized.

Tokens are stored at ~/.oxp/credentials (mode 0600).

Step 2: Generate a Signing Key

bash
oxp keygen
# → ed25519:0xABCD1234...

This creates an Ed25519 keypair at ~/.oxp/keys/ and prints the public key ID. The public key is registered with the registry on your first publish.

Step 3: Pack the Bundle

bash
oxp pack
# → dist/my-ext-0.1.0.oxp (sha256:a1b2c3...)

oxp pack does the following:

  1. Validates oxp.json against the JSON Schema
  2. Enforces bundle policy (no code in ui-v1, WIT pin check for component-v1)
  3. Packs into a deterministic tar+zstd archive
  4. Hashes the uncompressed tar → bundle digest
  5. Signs with your Ed25519 key
  6. Writes dist/<slug>-<version>.oxp

Step 4: Publish

bash
oxp publish
# or
oxp publish dist/my-ext-0.1.0.oxp

The registry:

  1. Authenticates your token and checks scope (publish:@handle/* or per-package)
  2. Re-validates the manifest and bundle policy server-side
  3. Verifies the WIT pin matches the server's world (for component bundles)
  4. Checks TOFU key pinning — if you've published before, the key must match
  5. Stores the bundle, manifest, and signature
  6. Returns the published version details

Token Management

Scoped Tokens

Publish tokens are scoped. You can create tokens that only allow publishing to specific packages:

  • publish:@acme/* — publish any package under @acme
  • publish:@acme/specific-ext — publish only @acme/specific-ext
  • publish:* — publish anything (admin, legacy)

Token Rotation

bash
oxp token rotate [--days 90] [--name "CI token"] [--scope "publish:@acme/*"]

Rotation mints a successor token, retires the old one with a 5-minute grace window (so in-flight publishes finish), and atomically updates ~/.oxp/credentials.

Default Expiry

Tokens expire after 90 days by default. Use --days N to customize.

TOFU Key Pinning

On your first publish, the registry pins your Ed25519 public key to your publisher handle. Subsequent publishes must use the same key. If you need to rotate your signing key, follow the key rotation flow (requires re-authentication).

The host also maintains a local TOFU store at ~/.oxp/trust.json. If a known publisher suddenly publishes with a different key, installation is blocked with a KEY_PINNING_VIOLATION error.

Versioning Strategy

OXP uses strict semver 2.0.0. The registry enforces:

  • Versions must be valid semver
  • Versions cannot be re-published (immutable)
  • Yanked versions can be marked but not deleted