@celilo/e2e 0.7.15 → 0.7.17

package/AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md — `@celilo/e2e`
+
+`@celilo/e2e` is a **simulated internet in Docker** for end-to-end testing of
+[celilo](https://celilo.computer)-deployed apps. It stands up a DNS hierarchy
+(root → TLD → registrar → recursive resolver), an ACME server (Pebble, standing
+in for Let's Encrypt), an ISP router + customer firewall with real iptables NAT,
+zoned LAN networks, and systemd target machines — then runs celilo *inside* it as
+if it were deploying to a real home lab. This file orients an AI agent to write
+and run those tests. **Read the in-package docs below before searching the web** —
+they are the source of truth.
+
+This file ships **inside the npm package**: the `./`-prefixed docs in the doc map
+are installed alongside it (grep them offline). Repo-relative entries point at the
+source repository, which the tarball does not carry.
+
+## Mental model (learn these five things)
+
+- **The sim is a faithful internet, not a convenience harness.** Public DNS only
+  ever answers with the customer firewall's *external* IP; the firewall DNATs
+  inbound to the right internal host. ACME challenges validate over the public
+  path. A test that "passes" by short-circuiting any of this is testing a placebo
+  — see **Inviolable rules** below.
+- **`network()` builder** — declare zones and the machines in them, `.start()` the
+  topology, drive celilo with `.celilo(...)`, assert, then `.stop()`. This is the
+  whole library surface (`import { network } from '@celilo/e2e'`).
+- **Zones** — `internal` (home LAN), `dmz`, `app`, `secure` are the customer-side
+  networks; `isp-external` / `internet-external` model the public internet. Public
+  IPs live only on the public networks; the firewall containers are the only place
+  the two address spaces meet (via NAT/DNAT).
+- **Two consumption modes** — as a **library** (`network()` in a `bun test` file)
+  or via the **`cele2e` CLI** (`cele2e run <test>`, `build-infra`, `list`). The
+  shared infra (`celilo-e2e-shared`) is a *global* Docker compose project,
+  independent of which checkout started it.
+- **`build-infra` gate** — anything baked into a Docker image (`docker/`,
+  `config/`, `simulators/`, installed package tarballs) needs `cele2e build-infra`
+  before it takes effect. Pure `src/*.ts` changes do not (bun runs TS directly).
+
+## Writing a test (the happy path)
+
+```ts
+import { test, expect } from 'bun:test';
+import { network } from '@celilo/e2e';
+
+test('caddy serves TLS in the dmz', async () => {
+  const net = await network()
+    .dmz({ caddy: '10.0.10.10' })   // machine name → zone-side IP
+    .start();
+  try {
+    await net.celilo('module import caddy');
+    await net.celilo('module deploy caddy --no-interactive');
+    // assert against the deployed service via the public path, not the container IP
+  } finally {
+    await net.stop();
+  }
+});
+```
+
+- Prefer the **fixtures** in `./src/fixtures.ts` (`CADDY_DEPLOYMENT`,
+  `FULL_STACK`, `TECHNITIUM_STACK`, …) over hand-rolling topology.
+- Drive **everything through the celilo CLI** or the module's documented surface —
+  never `docker exec` to hand-edit a deployed container's config (that's the bug
+  you're trying to catch).
+- Poll on the **observable condition** the deploy is meant to satisfy
+  (`VantageProbe`, DNS resolution, an HTTP header) — never `setTimeout` to mask a
+  race.
+
+## CLI you'll use
+
+```
+cele2e list                     # enumerate every test (module suites + top-level)
+cele2e build-infra              # rebuild Docker images (required after image-baked changes)
+cele2e run <test> [--keep]      # run one test; --keep leaves the network up for debugging
+cele2e run --all                # full regression (every suite); --all-modules = modules only
+```
+
+For Claude-driven / detached runs, fire via the repo wrapper
+`infra/scripts/cele2e-run.sh <test> [--keep|--build]` (fire-and-forget RUNID/LOG
+contract) rather than calling `cele2e run` from a long-lived watcher.
+
+## Inviolable rules (breaking any turns the suite into a placebo)
+
+1. **No RFC 1918 leaks past the public boundary.** Public DNS never serves an A
+   record pointing at `10/8`, `172.16/12`, or `192.168/16` — only the firewall's
+   external IP.
+2. **Don't collapse the topology to fix a timing/connectivity bug.** Fix the
+   *deployment ordering* (DNS record / DNAT rule / firewall opening in place
+   before the dependent step), not the simulation.
+3. **Public IPs only on the public networks.** Firewall containers bridge public
+   and private — the only place those spaces meet, and only via NAT/DNAT.
+4. **ACME challenges go through the public path** to the firewall's external IP.
+5. **DDNS updates modify *public* DNS** with the firewall's external IP, never an
+   internal target IP.
+
+Cheats (`/etc/hosts` overrides, `iptables -F`, `--insecure` in module code,
+hardcoded internal IPs, `|| true` on a celilo command, sleeping past a race) are
+fine for **bisecting** a failure but are never a **final solution** — confirm the
+hypothesis, then ship the real fix. Full list + rationale in `./README.md` and the
+repo `CLAUDE.md`.
+
+## Doc map (read in this order)
+
+Shipped **inside this package** (offline, grep-friendly):
+
+- `./README.md` — network architecture, machines, routing, DNS, simulators,
+  manual usage. Start here.
+- `./COVERAGE.md` — the array/object/map coverage audit (where N>1 paths are or
+  aren't exercised). Consult before adding a multi-element feature test.
+- `./src/index.ts` — the public library exports (`network`, types, probes).
+- `./src/fixtures.ts` — ready-made topology presets to build tests on.
+- `./src/types.ts` — `NetworkHandle`, `Zone`, `MachineSpec`, `Vantage`, and the
+  zone subnet/gateway constants.
+
+In the **source repo** (not carried in the tarball):
+
+- `infra/docs/RUNNING_CELE2E_TESTS.md` — the full operator guide; read before
+  running the suite for real.
+- `https://celilo.computer/docs` — hosted docs (LAN; the repo docs lead).

package/COVERAGE.md

@@ -0,0 +1,60 @@
+# E2E Test Coverage Audit
+
+This document tracks how well the e2e suite exercises capability and module
+fields whose type is `array`, `object`, or `map` — anywhere the framework's
+public API admits "more than one of X."
+
+## Why this exists
+
+A test that only ever uses N=1 will pass even when the multi-element path is
+broken. The bug fixed by `dns_registrar` 4.0.0 (see
+`apps/celilo/designs/DNS_REGISTRAR_MULTI_DOMAIN.md`) escaped the existing e2e
+suite for exactly this reason: the website-deploy-simple test put caddy, namecheap,
+and the website all on a single domain, and the multi-domain code path was
+never exercised.
+
+## Audit checklist
+
+For every capability and every module manifest, identify each field whose
+type is `array`, `object`, or `map`. For each one, ask:
+
+1. Does at least one e2e test exercise this field with **N > 1** distinct
+   values?
+2. Are those values **meaningfully different** (different domains, different
+   zones, different ports — not just "two of the same kind of thing")?
+3. Does the test assert behavior that would be **wrong if only the first
+   element worked**?
+
+Anywhere all three answers aren't "yes," that's a gap to either close (write
+the test) or document why it's intentionally deferred.
+
+## Coverage table
+
+| Field | N>1? | Meaningfully different? | Asserts non-first works? | Status |
+|---|---|---|---|---|
+| `namecheap.domains` | yes (`website-deploy-cross-domain`) | yes (different TLDs: `iamtheinternet.org` + `example.net`) | yes (verifies example.net DNS+TLS while iamtheinternet.org is canonical) | covered |
+| `namecheap.ddns_passwords` (per-domain map) | yes (same test) | yes (distinct passwords per domain) | yes (uses example.net's own password to update its A record) | covered |
+| `caddy.hostnames` | yes (`website-deploy-simple`) | partial (same domain in `website-deploy-simple.test.ts`); yes (cross-TLD in cross-domain test) | yes (cross-domain test serves a hostname that isn't `hostnames[0]`) | covered |
+| `iptables.exposed_services` | unclear — needs audit | — | — | **GAP** |
+| `public_web` registrations across modules | partial (`website-deploy-simple.test.ts` registers auth + website on the same domain) | needs cross-domain variant | partial | **GAP** |
+| `<every secret: object field>` | typically only one key | usually no | — | **AUDIT EACH** |
+
+## Closing the gaps
+
+- **`iptables.exposed_services`**: write an e2e that exposes two services
+  on the same machine via different ports and verifies both are reachable
+  from outside.
+- **`public_web` cross-domain**: extend `website-deploy-simple.test.ts` (or a new
+  test) to register routes on two different domains and verify each is
+  served by the right backend.
+- **secret object fields**: as modules using these grow (e.g. third-party
+  API integrations with multiple keys), add per-key tests.
+
+## New-module checklist
+
+When authoring a module, list every field whose type permits multiple
+values. For each, write at least one e2e or integration test that uses
+**N ≥ 2** with meaningfully different values. Add a row to the table
+above (or document why you've deferred it).
+
+See `design/MODULE_DEVELOPMENT_GUIDE.md` for the full new-module checklist.

package/bin/e2e-build

@@ -22,6 +22,7 @@ NETAPPS_DIR="$E2E_DIR/netapps"
 cd "$E2E_DIR"
 
 GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
 DIM='\033[2m'
 BOLD='\033[1m'
 NC='\033[0m'
@@ -160,6 +161,25 @@ BAKE_END=$(date +%s)
 echo -e "${GREEN}Baked in $((BAKE_END - BAKE_START))s${NC}"
 echo ""
 
+# ── Step 2d: Pre-seed heavy app images into the app-zone preload cache ─────────
+#
+# Heavy application images (authentik server, postgres, redis) are pulled ONCE
+# on the host here and saved to docker-image-cache/, which app-zone target
+# machines bind-mount and load at startup via docker-image-preload.service.
+# Without this the cache is empty on a fresh checkout / the builder, so every
+# app-module deploy pulls GB through the simulated internet — slow enough to
+# time the authentik deploy out (exit 124) and take down forgejo-deploy +
+# full-stack-pipeline (ISS-0154). Best-effort: e2e-cache-images is per-image
+# resilient and the preload service skips a missing tarball, so a transient
+# registry hiccup degrades to a slow pull rather than failing build-infra.
+echo -e "${BOLD}Pre-seeding app-zone image cache...${NC}"
+if bash "$E2E_DIR/bin/e2e-cache-images"; then
+  :
+else
+  echo -e "${YELLOW}⚠ image cache step failed — app-zone deploys may pull over the sim${NC}" >&2
+fi
+echo ""
+
 # ── Step 3: Optionally save images to tarball ─────────────────────────────────
 
 if [ "$1" = "--save" ]; then

package/bin/e2e-cache-images

@@ -23,6 +23,7 @@ mkdir -p "$CACHE_DIR"
 
 BOLD='\033[1m'
 GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
 DIM='\033[2m'
 NC='\033[0m'
 
@@ -44,12 +45,18 @@ for filename in "${!IMAGES[@]}"; do
   printf "  %-50s " "$image"
   START=$(date +%s)
 
-  docker pull "$image" > /dev/null 2>&1
-  docker save "$image" -o "$tarball"
-
-  END=$(date +%s)
-  SIZE=$(du -h "$tarball" | cut -f1)
-  echo -e "${GREEN}✔${NC} ${DIM}$((END - START))s  ${SIZE}${NC}"
+  # Per-image best-effort: a transient registry failure for one image must not
+  # abort caching the others (this runs inside build-infra now). A guarded
+  # command does not trip `set -e`. The preload service skips a missing tarball
+  # gracefully — that module just pulls over the sim at deploy time.
+  if docker pull "$image" > /dev/null 2>&1 && docker save "$image" -o "$tarball"; then
+    END=$(date +%s)
+    SIZE=$(du -h "$tarball" | cut -f1)
+    echo -e "${GREEN}✔${NC} ${DIM}$((END - START))s  ${SIZE}${NC}"
+  else
+    rm -f "$tarball"
+    echo -e "${YELLOW}✘ failed — will pull over the sim at deploy time${NC}"
+  fi
 done
 
 echo ""

package/config/dns/iamtheinternet.org.zone

@@ -0,0 +1,16 @@
+$ORIGIN iamtheinternet.org.
+$TTL 300
+
+@ IN SOA ns1.iamtheinternet.org. admin.iamtheinternet.org. (
+    2024020247 300 60 604800 300
+)
+
+; Public DNS — RFC 1918 addresses NEVER appear here. The whole point of
+; the e2e simulation is to model real internet connectivity, where
+; private IPs are unreachable from outside. All public-facing names
+; resolve to the firewall's external IP (100.100.0.100), which DNATs
+; inbound to the right internal host.
+@       IN NS   ns1.iamtheinternet.org.
+ns1     IN A    100.64.0.55
+@       IN A    0.0.0.0
+www     IN A    100.100.0.100

package/config/proxy/startup.sh

@@ -7,5 +7,19 @@ ip route add default via 172.30.0.1
 
 rm -f /run/squid.pid
 
+# Initialize the cache swap directories before starting Squid. The image's
+# build-time `squid -z` can leave an INCOMPLETE L1/L2 set (observed: 00–0C
+# present, 0D–0F missing); on a fresh container Squid then FATALs with "Failed
+# to verify one of the swap directories" and exits. With Squid dead, the
+# transparent-proxy REDIRECT (:80→3128, :443→3129) forwards every apt fetch to
+# a closed port → "connection refused" — which surfaced as flaky, non-warming
+# `apt install` failures during module deploys (e.g. knot). `squid -z` is
+# idempotent (creates only missing dirs). `--foreground` is REQUIRED: a bare
+# `squid -z` daemonizes and lingers (holding /run/squid.pid), so the following
+# `squid -N` would FATAL "Squid is already running"; with --foreground, -z runs
+# synchronously, removes the pid file, and exits clean.
+squid --foreground -z -f /etc/squid/squid.conf
+rm -f /run/squid.pid
+
 echo "forward-proxy ready on ports 3128 (HTTP) / 3129 (HTTPS)"
 exec squid -N -f /etc/squid/squid.conf

package/config/routing/fw-ext-routes.sh

@@ -19,6 +19,19 @@ iptables -P FORWARD ACCEPT
 
 # Start Squid transparent proxy (runs on fw-ext itself)
 rm -f /run/squid.pid
+# Complete the cache swap directories before starting. The image's build-time
+# `squid -z` (Dockerfile.router) is killed after a fixed `sleep 1`, which can
+# interrupt it and leave an INCOMPLETE L1/L2 set (observed: 00–0C present,
+# 0D–0F missing). `squid -N` then FATALs ("Failed to verify one of the swap
+# directories") and never binds — so the transparent-proxy REDIRECT below sends
+# every apt fetch to a closed port and target deploys fail with intermittent,
+# non-warming "connection refused" (e.g. knot's `apt install`). `squid -z` is
+# idempotent, so running it here guarantees a complete tree. `--foreground` is
+# REQUIRED: a bare `squid -z` daemonizes and lingers (holding /run/squid.pid),
+# so the following `squid -N` would FATAL "Squid is already running"; with
+# --foreground, -z runs synchronously, removes the pid file, and exits clean.
+squid --foreground -z -f /etc/squid/squid.conf
+rm -f /run/squid.pid
 squid -N -f /etc/squid/squid.conf &
 
 # Wait for Squid to be listening on both 3128 (HTTP) and 3129 (HTTPS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "E2E test infrastructure for Celilo-deployed applications. Provides a simulated internet with DNS hierarchy, ACME server, firewalls, and target machines in Docker.",
   "type": "module",
   "main": "./src/index.ts",
@@ -19,7 +19,8 @@
   },
   "scripts": {
     "test": "bun test tests/",
-    "test:completion": "bun test tests/completion"
+    "test:completion": "bun test tests/completion",
+    "test:integration": "bun test tests-integration/"
   },
   "files": [
     "src/",
@@ -33,7 +34,9 @@
     "npm-registry-server/tsconfig.json",
     "npm-registry-server/src/",
     "scripts/",
-    "README.md"
+    "README.md",
+    "AGENTS.md",
+    "COVERAGE.md"
   ],
   "dependencies": {
     "@celilo/cli-display": "^0.1.9",

package/registry-server/src/auth.test.ts

@@ -1,50 +1,76 @@
 import { describe, expect, test } from 'bun:test';
-import { TokenAuth } from './auth';
+import { ADMIN_SCOPE, TokenAuth, hashToken } from './auth';
 
-describe('TokenAuth', () => {
-  test('empty tokens list → no tokens, verify always false', () => {
+describe('TokenAuth (package-scoped — ISS-0140)', () => {
+  test('empty specs → no tokens; nothing authorizes', () => {
     const auth = new TokenAuth([]);
     expect(auth.hasTokens()).toBe(false);
-    expect(auth.verify('anything')).toBe(false);
+    expect(auth.authorize('anything', 'caddy')).toBe(false);
+    expect(auth.isAdmin('anything')).toBe(false);
   });
 
-  test('verify returns true for matching token, false for non-matching', () => {
-    const auth = new TokenAuth(['secret-token']);
-    expect(auth.verify('secret-token')).toBe(true);
-    expect(auth.verify('wrong-token')).toBe(false);
+  test('admin-scoped token publishes ANY package', () => {
+    const auth = new TokenAuth([{ token: 'admin-tok', scope: ADMIN_SCOPE }]);
+    expect(auth.authorize('admin-tok', 'caddy')).toBe(true);
+    expect(auth.authorize('admin-tok', 'lunacycle')).toBe(true);
+    expect(auth.isAdmin('admin-tok')).toBe(true);
+  });
+
+  test('package-scoped token publishes ONLY its package', () => {
+    const auth = new TokenAuth([{ token: 'luna-tok', scope: 'lunacycle' }]);
+    expect(auth.authorize('luna-tok', 'lunacycle')).toBe(true);
+    expect(auth.authorize('luna-tok', 'caddy')).toBe(false);
+    // A scoped token is NOT an admin token — it cannot mint.
+    expect(auth.isAdmin('luna-tok')).toBe(false);
+  });
+
+  test('unknown token never authorizes', () => {
+    const auth = new TokenAuth([{ token: 'known', scope: 'lunacycle' }]);
+    expect(auth.authorize('unknown', 'lunacycle')).toBe(false);
   });
 
   test('tokens are stored hashed, not in cleartext', () => {
-    const auth = new TokenAuth(['secret-token']);
-    // Internal property access is a smoke check — if tokens were stored raw,
-    // 'secret-token' would appear in the Set. Only hashes should be present.
-    const rawDump = JSON.stringify(auth);
-    expect(rawDump).not.toContain('secret-token');
+    const auth = new TokenAuth([{ token: 'secret-token', scope: ADMIN_SCOPE }]);
+    expect(JSON.stringify(auth)).not.toContain('secret-token');
   });
 
-  test('verify trims whitespace to tolerate header formatting variance', () => {
-    const auth = new TokenAuth(['clean']);
-    expect(auth.verify('  clean  ')).toBe(true);
+  test('tolerates a Bearer prefix and surrounding whitespace', () => {
+    const auth = new TokenAuth([{ token: 'clean', scope: ADMIN_SCOPE }]);
+    expect(auth.authorize('  clean  ', 'caddy')).toBe(true);
+    expect(auth.authorize('Bearer clean', 'caddy')).toBe(true);
   });
 
-  test('verify rejects empty string', () => {
-    const auth = new TokenAuth(['secret']);
-    expect(auth.verify('')).toBe(false);
+  test('empty header rejected', () => {
+    const auth = new TokenAuth([{ token: 'secret', scope: ADMIN_SCOPE }]);
+    expect(auth.authorize('', 'caddy')).toBe(false);
+    expect(auth.scopeOf('')).toBe(null);
   });
 
-  test('multiple tokens — any match verifies', () => {
-    const auth = new TokenAuth(['t1', 't2', 't3']);
-    expect(auth.verify('t1')).toBe(true);
-    expect(auth.verify('t2')).toBe(true);
-    expect(auth.verify('t3')).toBe(true);
-    expect(auth.verify('t4')).toBe(false);
+  test('addHashed / removeHashed manage minted tokens at runtime', () => {
+    const auth = new TokenAuth([]);
+    const hash = hashToken('minted-tok');
+    auth.addHashed(hash, 'lunacycle');
+    expect(auth.authorize('minted-tok', 'lunacycle')).toBe(true);
+    auth.removeHashed(hash);
+    expect(auth.authorize('minted-tok', 'lunacycle')).toBe(false);
+  });
+});
+
+describe('TokenAuth.fromEnv (PUBLISH_TOKENS format)', () => {
+  test('bare line → admin scope; "token pkg" line → scoped', () => {
+    process.env.PUBLISH_TOKENS = 'admin-tok\nluna-tok lunacycle\n';
+    const auth = TokenAuth.fromEnv();
+    expect(auth.isAdmin('admin-tok')).toBe(true);
+    expect(auth.authorize('luna-tok', 'lunacycle')).toBe(true);
+    expect(auth.authorize('luna-tok', 'caddy')).toBe(false);
+    process.env.PUBLISH_TOKENS = '';
   });
 
-  test('empty lines in input are ignored', () => {
-    const auth = new TokenAuth(['t1', '', '  ', 't2']);
+  test('blank lines ignored', () => {
+    process.env.PUBLISH_TOKENS = '\n  \nt1\n';
+    const auth = TokenAuth.fromEnv();
     expect(auth.hasTokens()).toBe(true);
-    expect(auth.verify('t1')).toBe(true);
-    expect(auth.verify('t2')).toBe(true);
-    expect(auth.verify('')).toBe(false);
+    expect(auth.isAdmin('t1')).toBe(true);
+    process.env.PUBLISH_TOKENS = '';
   });
 });

package/registry-server/src/auth.ts

@@ -1,36 +1,105 @@
 import { createHash } from 'node:crypto';
 
 /**
- * SHA-256 hashed token auth. Tokens never leave the caller's memory in cleartext
- * once the server starts — the set stores only hashes. Rotation = restart with
- * a new PUBLISH_TOKENS env var.
+ * Package-scoped token auth (build-bus Phase 3, ISS-0140).
+ *
+ * Each token carries a SCOPE — either a single package name (the token may
+ * publish only that module) or the admin scope `*` (publish anything + mint
+ * scoped tokens). Tokens are stored SHA-256 hashed; cleartext never lives in
+ * the auth set once the server starts.
+ *
+ *   PUBLISH_TOKENS env (newline-separated), per line:
+ *     <token>              → admin scope `*` (publish any package, mint tokens)
+ *     <token> <package>    → scoped to that one package
+ *
+ * A bare `<token>` line is the admin/bootstrap token — this preserves the
+ * pre-scoping behavior (any configured token publishes anything) AND is the
+ * privilege that the `registry_publish` capability uses to mint per-repo
+ * scoped tokens. Minted scoped tokens are added at runtime via {@link addHashed}
+ * (loaded from the persisted store) and removed via {@link removeHashed}.
  */
+
+/** Admin scope: publish any package + mint scoped tokens. */
+export const ADMIN_SCOPE = '*';
+
+export interface TokenSpec {
+  token: string;
+  /** Package name, or {@link ADMIN_SCOPE}. */
+  scope: string;
+}
+
+/** SHA-256 of a token (trimmed). The persisted scoped-token store hashes too. */
+export function hashToken(token: string): string {
+  return createHash('sha256').update(token.trim()).digest('hex');
+}
+
+/** Strip an optional `Bearer ` prefix and surrounding whitespace from a header. */
+function bareToken(header: string): string {
+  return header.replace(/^Bearer\s+/i, '').trim();
+}
+
 export class TokenAuth {
-  private readonly hashedTokens: Set<string>;
+  /** hash → scope. */
+  private readonly scopeByHash = new Map<string, string>();
 
-  constructor(rawTokens: string[]) {
-    this.hashedTokens = new Set(
-      rawTokens
-        .map((t) => t.trim())
-        .filter(Boolean)
-        .map((t) => createHash('sha256').update(t).digest('hex')),
-    );
+  constructor(specs: TokenSpec[]) {
+    for (const s of specs) this.addRaw(s.token, s.scope);
   }
 
+  /**
+   * Parse the `PUBLISH_TOKENS` env format into the scoped auth set. Each line is
+   * `<token>` (admin scope) or `<token> <package>` (scoped to one package).
+   */
   static fromEnv(): TokenAuth {
     const raw = process.env.PUBLISH_TOKENS ?? '';
-    const tokens = raw.split('\n').filter(Boolean);
-    return new TokenAuth(tokens);
+    const specs: TokenSpec[] = [];
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const [token, scope] = trimmed.split(/\s+/, 2);
+      specs.push({ token, scope: scope || ADMIN_SCOPE });
+    }
+    return new TokenAuth(specs);
+  }
+
+  /** Add a cleartext token (hashes it). Empty tokens are ignored. */
+  addRaw(rawToken: string, scope: string): void {
+    const t = rawToken.trim();
+    if (!t) return;
+    this.scopeByHash.set(hashToken(t), scope.trim() || ADMIN_SCOPE);
+  }
+
+  /** Add an already-hashed token (used when loading the persisted minted-token store). */
+  addHashed(hash: string, scope: string): void {
+    this.scopeByHash.set(hash, scope);
+  }
+
+  /** Remove a token by its hash (token revocation). */
+  removeHashed(hash: string): void {
+    this.scopeByHash.delete(hash);
   }
 
-  /** If no tokens are configured, the server treats every publish as unauthorized. */
+  /** If no tokens are configured, the server treats every write as unauthorized. */
   hasTokens(): boolean {
-    return this.hashedTokens.size > 0;
+    return this.scopeByHash.size > 0;
+  }
+
+  /** The scope of a token (from an Authorization header value), or null if unknown. */
+  scopeOf(header: string): string | null {
+    const t = bareToken(header);
+    if (!t) return null;
+    return this.scopeByHash.get(hashToken(t)) ?? null;
+  }
+
+  /** True when the token may publish/yank the given package (admin or exact scope). */
+  authorize(header: string, pkg: string): boolean {
+    const scope = this.scopeOf(header);
+    if (scope === null) return false;
+    return scope === ADMIN_SCOPE || scope === pkg;
   }
 
-  verify(token: string): boolean {
-    if (!token) return false;
-    const hashed = createHash('sha256').update(token.trim()).digest('hex');
-    return this.hashedTokens.has(hashed);
+  /** True when the token is an admin token (scope `*`) — required to mint scoped tokens. */
+  isAdmin(header: string): boolean {
+    return this.scopeOf(header) === ADMIN_SCOPE;
   }
 }

package/registry-server/src/scoped-token-store.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test';
+import { hashToken } from './auth';
+import {
+  type ScopedTokenEntry,
+  type ScopedTokenPersistence,
+  ScopedTokenStore,
+} from './scoped-token-store';
+
+/** In-memory persistence so the store is testable without the filesystem. */
+function memoryPersistence(seed: ScopedTokenEntry[] = []): ScopedTokenPersistence & {
+  saved: ScopedTokenEntry[];
+} {
+  const state = { saved: [...seed] };
+  return {
+    saved: state.saved,
+    load() {
+      return [...state.saved];
+    },
+    save(entries) {
+      state.saved.length = 0;
+      state.saved.push(...entries);
+    },
+  };
+}
+
+/** Deterministic token generator (avoids randomness in assertions). */
+function seqGen() {
+  let n = 0;
+  return () => `tok-${++n}`;
+}
+
+describe('ScopedTokenStore.mint (ISS-0140)', () => {
+  test('mints a scoped token and persists only the hash', () => {
+    const p = memoryPersistence();
+    const store = new ScopedTokenStore(p, seqGen(), () => '2026-06-20T00:00:00Z');
+    const { token, entry, revokedHashes } = store.mint('celilo/lunacycle', 'lunacycle');
+
+    expect(token).toBe('tok-1');
+    expect(entry.scope).toBe('lunacycle');
+    expect(entry.repo).toBe('celilo/lunacycle');
+    expect(entry.hash).toBe(hashToken('tok-1'));
+    expect(revokedHashes).toEqual([]);
+    // Persisted form holds the hash, never the cleartext token.
+    expect(JSON.stringify(p.saved)).not.toContain('tok-1');
+    expect(p.saved).toHaveLength(1);
+  });
+
+  test('re-minting for the same repo rotates the token (reconcile)', () => {
+    const p = memoryPersistence();
+    const store = new ScopedTokenStore(p, seqGen(), () => 't');
+    const first = store.mint('celilo/lunacycle', 'lunacycle');
+    const second = store.mint('celilo/lunacycle', 'lunacycle');
+
+    expect(second.token).toBe('tok-2');
+    expect(second.revokedHashes).toEqual([first.entry.hash]);
+    // Still exactly one active token for the repo.
+    expect(store.list().filter((e) => e.repo === 'celilo/lunacycle')).toHaveLength(1);
+    expect(store.list()).toHaveLength(1);
+  });
+
+  test('different repos coexist independently', () => {
+    const store = new ScopedTokenStore(memoryPersistence(), seqGen(), () => 't');
+    store.mint('celilo/lunacycle', 'lunacycle');
+    store.mint('celilo/caddy', 'caddy');
+    expect(store.list()).toHaveLength(2);
+  });
+});
+
+describe('ScopedTokenStore.revoke', () => {
+  test('removes all tokens for a repo and returns their hashes', () => {
+    const store = new ScopedTokenStore(memoryPersistence(), seqGen(), () => 't');
+    const { entry } = store.mint('celilo/lunacycle', 'lunacycle');
+    const removed = store.revoke('celilo/lunacycle');
+    expect(removed).toEqual([entry.hash]);
+    expect(store.list()).toHaveLength(0);
+  });
+
+  test('revoking an unknown repo is a no-op', () => {
+    const store = new ScopedTokenStore(memoryPersistence(), seqGen(), () => 't');
+    expect(store.revoke('celilo/nope')).toEqual([]);
+  });
+});
+
+describe('ScopedTokenStore startup load', () => {
+  test('loads persisted entries on construction', () => {
+    const seed: ScopedTokenEntry[] = [
+      { hash: hashToken('x'), scope: 'caddy', repo: 'celilo/caddy', mintedAt: 't' },
+    ];
+    const store = new ScopedTokenStore(memoryPersistence(seed), seqGen(), () => 't');
+    expect(store.list()).toHaveLength(1);
+    expect(store.list()[0]?.repo).toBe('celilo/caddy');
+  });
+});