@celilo/e2e 0.7.14 → 0.7.16

package/config/dns/knot-namecheap.conf

@@ -10,8 +10,8 @@ zone:
     file: "/config/celilo.computer.zone"
     storage: "/var/lib/knot"
 
-  - domain: "lunacycle.net"
-    file: "/config/lunacycle.net.zone"
+  - domain: "example.net"
+    file: "/config/example.net.zone"
     storage: "/var/lib/knot"
 
   - domain: "park-your-domain.com"

package/config/dns/net.zone

@@ -7,5 +7,5 @@ $TTL 86400
 
 net.                    IN NS   tld-dns.lab.
 
-lunacycle               IN NS   ns1.lunacycle.net.
-ns1.lunacycle.net.      IN A    100.64.0.55
+example                 IN NS   ns1.example.net.
+ns1.example.net.      IN A    100.64.0.55

package/config/dns/{lunacycle.net.zone → templates/example.net.zone}

@@ -1,7 +1,7 @@
-$ORIGIN lunacycle.net.
+$ORIGIN example.net.
 $TTL 300
 
-@ IN SOA ns1.lunacycle.net. admin.lunacycle.net. (
+@ IN SOA ns1.example.net. admin.example.net. (
     2024020108 300 60 604800 300
 )
 
@@ -10,7 +10,7 @@ $TTL 300
 ; 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.lunacycle.net.
+@       IN NS   ns1.example.net.
 ns1     IN A    100.64.0.55
 @       IN A    100.100.0.100
 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/resolver/unbound.conf

@@ -34,11 +34,11 @@ stub-zone:
     stub-addr: 100.64.0.55
 
 stub-zone:
-    name: "lunacycle.net."
+    name: "example.net."
     stub-addr: 100.64.0.55
 
 # celilo.computer hosts the website + install.sh (served by the website-sim).
-# Without this stub it falls through to the real internet (71.36.115.155), so the
+# Without this stub it falls through to the real internet (203.0.113.11), so the
 # website-sim's ACME challenge can't be validated in-topology and the bake's
 # `curl https://celilo.computer/install.sh` never sees a cert. Covers
 # www.celilo.computer too. (ISS-0063)

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/config/routing/observer-setup.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Observer vantage setup (ISS-0117).
+#
+# Installs the routing profile that makes this container a FAITHFUL vantage — the
+# load-bearing part of the framework. A vantage's correctness is its routing table:
+# an internalDevice must reach a fronted service only via the firewall natIp, never a
+# segmented-zone container IP directly. Driven by env from the compose generator:
+#   OBSERVER_GATEWAY   - default route (the home router for internalDevice, the zone
+#                        firewall for dmz/app/secure, fw-ext for publicInternet)
+#   OBSERVER_INTERZONE - "1" to add the management-style explicit inter-zone routes
+#                        (the all-VLAN trap). "0" for every faithful consumer vantage.
+#   OBSERVER_RESOLVERS - space-separated nameservers for /etc/resolv.conf, in order
+set -u
+
+GATEWAY="${OBSERVER_GATEWAY:?OBSERVER_GATEWAY is required}"
+INTERZONE="${OBSERVER_INTERZONE:-0}"
+RESOLVERS="${OBSERVER_RESOLVERS:-100.100.0.1}"
+
+echo "Observer starting: gateway=${GATEWAY} interzone=${INTERZONE} resolvers='${RESOLVERS}'"
+
+# --- Default route ---
+# Docker seeds a default via the network's own gateway; replace it with the gateway a
+# real device at this location would use.
+ip route del default 2>/dev/null || true
+ip route add default via "${GATEWAY}"
+
+# --- Inter-zone routes (the management trap; only when explicitly requested) ---
+# A real consumer vantage NEVER has these — that is the whole point. Present only so a
+# `management`-style all-VLAN box can be modelled deliberately.
+if [ "${INTERZONE}" = "1" ]; then
+  ip route add 10.0.10.0/24 via 192.168.0.254 2>/dev/null || true  # dmz via fw-main
+  ip route add 10.0.20.0/24 via 192.168.0.254 2>/dev/null || true  # app via fw-main
+  ip route add 10.0.30.0/24 via 192.168.0.254 2>/dev/null || true  # secure via fw-main
+fi
+
+# --- Resolver ---
+: > /etc/resolv.conf
+for ns in ${RESOLVERS}; do
+  echo "nameserver ${ns}" >> /etc/resolv.conf
+done
+
+# --- Pebble runtime ACME root CA ---
+# Pebble mints a fresh root each startup, so the build-time CA can't verify certs Caddy
+# obtained at runtime. Fetch the live root so curl/openssl can validate real chains —
+# the no-self-signed / CA-provenance assertions depend on a correct trust store.
+echo "Fetching Pebble ACME root CA..."
+for _ in $(seq 1 30); do
+  if curl -sk https://100.64.0.100:15000/roots/0 -o /usr/local/share/ca-certificates/pebble-acme-root.crt 2>/dev/null; then
+    if [ -s /usr/local/share/ca-certificates/pebble-acme-root.crt ]; then
+      update-ca-certificates 2>/dev/null
+      echo "Pebble ACME root CA installed"
+      break
+    fi
+  fi
+  sleep 2
+done
+
+echo "Observer ready: $(hostname)"
+ip route
+sleep infinity

package/config/routing/resolver-internal-routes.sh

@@ -9,9 +9,9 @@ CADDY_IP="${CADDY_IP:-10.0.10.10}"
 # DOMAINS: comma-separated list of e2e test domains that should be
 # split-horizon redirected to caddy. Default covers the canonical
 # (iamtheinternet.org) plus the cross-domain test's second domain
-# (lunacycle.net). Tests can override via DEFAULT_GATEWAY/DOMAINS env
+# (example.net). Tests can override via DEFAULT_GATEWAY/DOMAINS env
 # vars in docker-compose.
-DOMAINS="${DOMAINS:-iamtheinternet.org,lunacycle.net}"
+DOMAINS="${DOMAINS:-iamtheinternet.org,example.net}"
 
 # Routing — reach comcast-resolver (100.100.0.1) via fw-main or fw-isp.
 # DEFAULT_GATEWAY is set by docker-compose from the topology config.

package/docker/Dockerfile.observer

@@ -0,0 +1,26 @@
+# Observer — a passive vantage-point spy (ISS-0117).
+#
+# Carries the full probe toolbox (dig, curl, openssl, nc, ping, ip) so a single image
+# can be injected at any network location and assert resolve/reach/TLS from that seat.
+# It runs NO services and deploys NO modules — it never perturbs the system under test.
+# Its faithfulness as a vantage comes from the routing profile installed at startup
+# (see config/routing/observer-setup.sh), driven by the OBSERVER_* env the compose
+# generator sets per vantage.
+FROM ubuntu:22.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && apt-get install -y \
+    dnsutils \
+    curl \
+    openssl \
+    netcat-openbsd \
+    iputils-ping \
+    iproute2 \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY config/routing/observer-setup.sh /startup.sh
+RUN chmod +x /startup.sh
+
+CMD ["/startup.sh"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/e2e",
-  "version": "0.7.14",
+  "version": "0.7.16",
   "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",
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "@celilo/cli-display": "^0.1.9",
-    "@celilo/event-bus": "^0.1.6",
+    "@celilo/event-bus": "^0.1.7",
     "yaml": "^2.8.0",
     "zod": "^3.24.1"
   },

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');
+  });
+});

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

@@ -0,0 +1,110 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { hashToken } from './auth';
+
+/**
+ * Persisted store of minted, package-scoped publish tokens (build-bus Phase 3,
+ * ISS-0140). The `registry_publish` capability mints one token per registered
+ * repo, scoped to the single package that repo publishes — so a compromised
+ * runner can ship only its own module, never another.
+ *
+ * Only the token HASH is persisted (never cleartext) — the raw token is returned
+ * exactly once at mint time, for the caller to set as the repo's Forgejo Actions
+ * secret. At startup the server loads this store into its {@link TokenAuth} via
+ * `addHashed`; mint/revoke update both the in-memory auth and this file, so a
+ * minted token works without a server restart.
+ */
+
+export interface ScopedTokenEntry {
+  /** SHA-256 of the raw token. */
+  hash: string;
+  /** Package this token may publish. */
+  scope: string;
+  /** Repo path on the source forge this token was minted for (the reconcile key). */
+  repo: string;
+  /** ISO timestamp of mint. */
+  mintedAt: string;
+}
+
+export interface MintResult {
+  /** The raw token — returned ONCE; never persisted in cleartext. */
+  token: string;
+  entry: ScopedTokenEntry;
+  /** Hashes of tokens this mint superseded for the same repo (revoke them in auth). */
+  revokedHashes: string[];
+}
+
+/** I/O seam (Rule 2.3) so the store is unit-testable without the filesystem. */
+export interface ScopedTokenPersistence {
+  load(): ScopedTokenEntry[];
+  save(entries: ScopedTokenEntry[]): void;
+}
+
+/** File-backed persistence: a JSON array at `filePath`, tolerant of a missing file. */
+export function fileScopedTokenPersistence(filePath: string): ScopedTokenPersistence {
+  return {
+    load() {
+      if (!existsSync(filePath)) return [];
+      try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+        return Array.isArray(parsed) ? (parsed as ScopedTokenEntry[]) : [];
+      } catch {
+        return [];
+      }
+    },
+    save(entries) {
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, JSON.stringify(entries, null, 2));
+    },
+  };
+}
+
+function defaultGenToken(): string {
+  return `cpt_${randomBytes(32).toString('base64url')}`;
+}
+
+export class ScopedTokenStore {
+  private entries: ScopedTokenEntry[];
+
+  constructor(
+    private readonly persistence: ScopedTokenPersistence,
+    private readonly genToken: () => string = defaultGenToken,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {
+    this.entries = persistence.load();
+  }
+
+  list(): ScopedTokenEntry[] {
+    return [...this.entries];
+  }
+
+  /**
+   * Mint a fresh scoped token for `repo`, reconciling: any existing token for the
+   * same repo is superseded (its hash returned in `revokedHashes`). Idempotent at
+   * the repo level — re-running rotates the token cleanly.
+   */
+  mint(repo: string, scope: string): MintResult {
+    const revokedHashes = this.entries.filter((e) => e.repo === repo).map((e) => e.hash);
+    const token = this.genToken();
+    const entry: ScopedTokenEntry = {
+      hash: hashToken(token),
+      scope,
+      repo,
+      mintedAt: this.now(),
+    };
+    this.entries = [...this.entries.filter((e) => e.repo !== repo), entry];
+    this.persistence.save(this.entries);
+    return { token, entry, revokedHashes };
+  }
+
+  /** Revoke all tokens for `repo`. Returns the removed hashes. */
+  revoke(repo: string): string[] {
+    const removed = this.entries.filter((e) => e.repo === repo).map((e) => e.hash);
+    if (removed.length > 0) {
+      this.entries = this.entries.filter((e) => e.repo !== repo);
+      this.persistence.save(this.entries);
+    }
+    return removed;
+  }
+}