Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

@enc-protocol npm registry

Private npm registry for @enc-protocol/* packages. Runs on a single Cloudflare Worker + KV namespace. Auth via Ed25519 signed tokens.

Live: https://npm-registry.ocrybit.workers.dev

Setup

npm install
npm run keygen

This generates an Ed25519 keypair in keys/. Add the public key to .dev.vars:

ORG_PUBLIC_KEY=<contents of keys/org.pub>

Development

npm run dev

Opens the registry at http://localhost:8787. The web UI is at the root.

Commands

CommandDescription
npm run devStart local registry server
npm run testRun all tests
npm run keygenGenerate Ed25519 keypair
npm run sign-tokenGenerate a 1-hour auth token
npm run seedPublish sample packages
npm run deployDeploy to Cloudflare

Deploy

npm run deploy

First-time setup requires creating the KV namespace and setting the secret:

npx wrangler kv namespace create PACKAGES
cat keys/org.pub | npx wrangler secret put ORG_PUBLIC_KEY

Update the KV id in wrangler.toml with the output from the first command.

Publishing

Generate a token and configure npm:

npm run sign-token

Add to your project's .npmrc:

# production
@enc-protocol:registry=https://npm-registry.ocrybit.workers.dev/
//npm-registry.ocrybit.workers.dev/:_authToken=<token>
 
# local dev
@enc-protocol:registry=http://localhost:8787/
//localhost:8787/:_authToken=<token>

Then publish as usual:

npm publish

Tokens expire after 1 hour. Reads (install/info) don't require auth.

Unpublish

# entire package
npm unpublish @enc-protocol/my-pkg --registry https://npm-registry.ocrybit.workers.dev/
 
# single version
npm unpublish @enc-protocol/my-pkg@1.0.0 --registry https://npm-registry.ocrybit.workers.dev/

Installing packages

# one-time .npmrc setup
echo "@enc-protocol:registry=https://npm-registry.ocrybit.workers.dev/" >> .npmrc
 
# then just
npm install @enc-protocol/crypto

API

All endpoints enforce @enc-protocol/* scope.

MethodPathAuthDescription
GET/NoWeb UI — package listing
GET/package/:nameNoWeb UI — package detail
GET/search?q=NoWeb UI — search
GET/-/pingNoHealth check
GET/:packageNoPackage metadata (packument)
GET/:package/:versionNoVersion metadata
GET/:package/-/:fileNoDownload tarball
PUT/:packageYesPublish
DELETE/:packageYesUnpublish entire package
DELETE/:package/:versionYesUnpublish single version

Auth

Auth uses Ed25519 signature verification. The token format is:

base64url({"sub":"@enc-protocol","iat":<unix_ts>}).<base64url(signature)>

The server verifies the signature against ORG_PUBLIC_KEY. Tokens are valid for 1 hour.

Project structure

src/
  index.ts              Router
  types.ts              TypeScript interfaces
  utils.ts              JSON responses, hashing, base64
  auth.ts               Ed25519 token verification
  routes/
    ping.ts             GET /-/ping
    metadata.ts         GET /:package, GET /:package/:version
    tarball.ts          GET /:package/-/:file
    publish.ts          PUT /:package
    unpublish.ts        DELETE /:package, DELETE /:package/:version
  web/
    layout.ts           HTML shell + CSS
    pages.ts            Homepage, package detail, search
scripts/
  keygen.ts             Generate Ed25519 keypair
  sign-token.ts         Sign an auth token
  seed.ts               Publish sample packages
test/
  registry.test.ts      Unit tests (34 tests)
  e2e.test.ts           End-to-end: publish, npm install, run (5 tests)

Tests

npm test

39 tests covering: auth (Ed25519 signatures, expiry, wrong key), scope enforcement, publish/retrieve lifecycle, multiple versions, version conflicts, tarball integrity, unpublish, and a full e2e test that runs npm install and executes the installed package.