@celilo/e2e 0.7.15 → 0.7.16

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.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",

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

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

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { TokenAuth } from './auth';
+import { ADMIN_SCOPE, TokenAuth } from './auth';
 import { createRateLimiter } from './rate-limit';
 import { startServer } from './server';
 
@@ -17,7 +17,7 @@ beforeEach(() => {
     port: 0, // let Bun pick an ephemeral port
     pathPrefix: '',
     publicUrl: 'https://example.test',
-    auth: new TokenAuth(['valid-token']),
+    auth: new TokenAuth([{ token: 'valid-token', scope: ADMIN_SCOPE }]),
   });
   baseUrl = `http://localhost:${server.port}`;
 });
@@ -107,9 +107,10 @@ describe('PUT /api/v1/modules/new', () => {
     const res = await publish('homebridge', '1.0.0+1', 'valid-token');
     expect(res.status).toBe(200);
 
-    const meta = (await fetch(`${baseUrl}/api/v1/modules/homebridge`).then((r) =>
-      r.json(),
-    )) as { name: string; versions: { num: string }[] };
+    const meta = (await fetch(`${baseUrl}/api/v1/modules/homebridge`).then((r) => r.json())) as {
+      name: string;
+      versions: { num: string }[];
+    };
     expect(meta.name).toBe('homebridge');
     expect(meta.versions).toHaveLength(1);
     expect(meta.versions[0].num).toBe('1.0.0+1');
@@ -258,9 +259,10 @@ describe('GET /api/v1/modules/{name} (metadata) — total_downloads', () => {
     await fetch(`${baseUrl}/api/v1/modules/homebridge/1.0.0+1/download`);
     await fetch(`${baseUrl}/api/v1/modules/homebridge/1.0.0+1/download`);
 
-    const meta = (await fetch(`${baseUrl}/api/v1/modules/homebridge`).then((r) =>
-      r.json(),
-    )) as { name: string; total_downloads: number };
+    const meta = (await fetch(`${baseUrl}/api/v1/modules/homebridge`).then((r) => r.json())) as {
+      name: string;
+      total_downloads: number;
+    };
     expect(meta.total_downloads).toBe(2);
   });
 });
@@ -344,7 +346,7 @@ describe('write endpoints are rate limited', () => {
       port: 0,
       pathPrefix: '',
       publicUrl: 'https://example.test',
-      auth: new TokenAuth(['tok']),
+      auth: new TokenAuth([{ token: 'tok', scope: ADMIN_SCOPE }]),
       rateLimiter: createRateLimiter({ max: 2, windowMs: 60_000 }),
     });
     try {
@@ -386,7 +388,7 @@ describe('path prefix routing', () => {
       port: 0,
       pathPrefix: '/registry',
       publicUrl: 'https://example.test/registry',
-      auth: new TokenAuth(['valid-token']),
+      auth: new TokenAuth([{ token: 'valid-token', scope: ADMIN_SCOPE }]),
     });
     try {
       const base = `http://localhost:${prefixed.port}`;
@@ -400,6 +402,86 @@ describe('path prefix routing', () => {
   });
 });
 
+// ── scoped publish tokens (ISS-0140) ──────────────────────────────────────────
+
+describe('POST /api/v1/modules/tokens/mint + scoped publish', () => {
+  async function mint(repo: string, scope: string, token: string): Promise<Response> {
+    return fetch(`${baseUrl}/api/v1/modules/tokens/mint`, {
+      method: 'POST',
+      headers: token ? { Authorization: token, 'Content-Type': 'application/json' } : {},
+      body: JSON.stringify({ repo, scope }),
+    });
+  }
+
+  test('admin token mints a scoped token; non-admin / no token is 401', async () => {
+    const noTok = await mint('celilo/lunacycle', 'lunacycle', '');
+    expect(noTok.status).toBe(401);
+
+    const ok = await mint('celilo/lunacycle', 'lunacycle', 'valid-token');
+    expect(ok.status).toBe(200);
+    const body = (await ok.json()) as { ok: boolean; token: string; scope: string };
+    expect(body.ok).toBe(true);
+    expect(body.scope).toBe('lunacycle');
+    expect(body.token.length).toBeGreaterThan(10);
+  });
+
+  test('a minted scoped token publishes ONLY its package', async () => {
+    const minted = (await (await mint('celilo/lunacycle', 'lunacycle', 'valid-token')).json()) as {
+      token: string;
+    };
+
+    // Can publish its own package…
+    const ok = await publish('lunacycle', '1.0.0+1', minted.token);
+    expect(ok.status).toBe(200);
+
+    // …but NOT another module.
+    const denied = await publish('caddy', '1.0.0+1', minted.token);
+    expect(denied.status).toBe(401);
+  });
+
+  test('a scoped token cannot mint (not admin)', async () => {
+    const minted = (await (await mint('celilo/lunacycle', 'lunacycle', 'valid-token')).json()) as {
+      token: string;
+    };
+    const reMint = await mint('celilo/caddy', 'caddy', minted.token);
+    expect(reMint.status).toBe(401);
+  });
+
+  test('re-minting rotates: the old token stops working, the new one publishes', async () => {
+    const first = (await (await mint('celilo/lunacycle', 'lunacycle', 'valid-token')).json()) as {
+      token: string;
+    };
+    const second = (await (await mint('celilo/lunacycle', 'lunacycle', 'valid-token')).json()) as {
+      token: string;
+    };
+    expect(second.token).not.toBe(first.token);
+
+    const oldDenied = await publish('lunacycle', '2.0.0+1', first.token);
+    expect(oldDenied.status).toBe(401);
+    const newOk = await publish('lunacycle', '2.0.0+1', second.token);
+    expect(newOk.status).toBe(200);
+  });
+
+  test('revoke disables the token', async () => {
+    const minted = (await (await mint('celilo/lunacycle', 'lunacycle', 'valid-token')).json()) as {
+      token: string;
+    };
+    const revoke = await fetch(`${baseUrl}/api/v1/modules/tokens/revoke`, {
+      method: 'POST',
+      headers: { Authorization: 'valid-token', 'Content-Type': 'application/json' },
+      body: JSON.stringify({ repo: 'celilo/lunacycle' }),
+    });
+    expect(revoke.status).toBe(200);
+    const denied = await publish('lunacycle', '1.0.0+1', minted.token);
+    expect(denied.status).toBe(401);
+  });
+
+  test('mint rejects an invalid scope (not a valid package name)', async () => {
+    const res = await mint('celilo/lunacycle', 'Bad_Scope', 'valid-token');
+    expect(res.status).toBe(400);
+  });
+});
+
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
 async function publish(

package/registry-server/src/server.ts

@@ -19,19 +19,19 @@
  * can publish-then-import against a live registry.
  */
 
-import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { TokenAuth } from './auth';
-import { landingResponse } from './landing';
 import {
+  type BootstrapEntry,
   bootstrapIndexEntry,
   packageBootstrapModule,
   scanBootstrapDir,
   scanUploadsDir,
-  type BootstrapEntry,
 } from './bootstrap';
-import { clientIp, createRateLimiter, type RateLimiter } from './rate-limit';
-import { RegistryStorage, type IndexEntry } from './storage';
+import { landingResponse } from './landing';
+import { type RateLimiter, clientIp, createRateLimiter } from './rate-limit';
+import { ScopedTokenStore, fileScopedTokenPersistence } from './scoped-token-store';
+import { type IndexEntry, RegistryStorage } from './storage';
 import { isValidName, isValidVersion, validateNameAndVersion } from './validation';
 
 /** Max total publish body size. Real modules are a few MB; 100MB is generous. */
@@ -70,14 +70,26 @@ interface ServerOptions {
    * to slow a bad actor to a crawl.
    */
   rateLimiter?: RateLimiter;
+  /**
+   * Store of minted, per-repo package-scoped tokens (build-bus Phase 3,
+   * ISS-0140). Defaults to a JSON file in `dataDir`. Its persisted hashes are
+   * loaded into `auth` at startup so minted tokens survive a restart.
+   */
+  scopedTokenStore?: ScopedTokenStore;
 }
 
 export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve> {
   const { dataDir, port, pathPrefix, publicUrl, auth } = options;
   const storage = new RegistryStorage(dataDir);
+  const scopedTokenStore =
+    options.scopedTokenStore ??
+    new ScopedTokenStore(fileScopedTokenPersistence(join(dataDir, 'scoped-tokens.json')));
+  // Load persisted minted tokens into the in-memory authorizer.
+  for (const entry of scopedTokenStore.list()) {
+    auth.addHashed(entry.hash, entry.scope);
+  }
   const bootstrapCacheDir = options.bootstrapCacheDir ?? join(dataDir, '.bootstrap-cache');
-  const rateLimiter =
-    options.rateLimiter ?? createRateLimiter({ max: 30, windowMs: 60_000 });
+  const rateLimiter = options.rateLimiter ?? createRateLimiter({ max: 30, windowMs: 60_000 });
 
   /**
    * Rescan every request so .netapps dropped into bootstrapUploadsDir at
@@ -122,15 +134,24 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
     return err('Unauthorized — provide a valid publish token in the Authorization header', 401);
   }
 
-  function requireAuth(req: Request): boolean {
-    return auth.verify(req.headers.get('Authorization') ?? '');
+  /** True when the request's token may publish/yank `pkg` (admin or exact scope). */
+  function authorizePackage(req: Request, pkg: string): boolean {
+    return auth.authorize(req.headers.get('Authorization') ?? '', pkg);
+  }
+
+  /** True when the request carries an admin (`*`-scoped) token — required to mint. */
+  function authorizeAdmin(req: Request): boolean {
+    return auth.isAdmin(req.headers.get('Authorization') ?? '');
   }
 
   /**
    * Rate-limit check for write endpoints. Returns a 429 response when
    * exceeded (with Retry-After), null when allowed.
    */
-  function rateLimitOrNull(req: Request, srv: { requestIP(r: Request): { address: string } | null }): Response | null {
+  function rateLimitOrNull(
+    req: Request,
+    srv: { requestIP(r: Request): { address: string } | null },
+  ): Response | null {
     const ip = clientIp(req, srv);
     const result = rateLimiter.take(ip);
     if (result.ok) return null;
@@ -214,12 +235,15 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
     // celilo CLI reads manifest.yml#description and includes it). When
     // not provided we leave it undefined; the search endpoint falls
     // back to bootstrap data or empty.
-    const description =
-      typeof meta.description === 'string' ? meta.description : undefined;
+    const description = typeof meta.description === 'string' ? meta.description : undefined;
 
     const validation = validateNameAndVersion(name, vers);
     if (!validation.ok) return err(validation.message);
 
+    // Scope check AFTER the name is known: a package-scoped token may publish
+    // only its own package; an admin token publishes anything (ISS-0140).
+    if (!authorizePackage(req, name)) return unauthorized();
+
     const fileOffset = 4 + metaLen;
     const fileLen = buf.readUInt32LE(fileOffset);
     if (buf.length < fileOffset + 4 + fileLen) return err('Request body truncated (file)');
@@ -253,6 +277,51 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
     return Response.json({ ok: true });
   }
 
+  /**
+   * Mint a per-repo, package-scoped publish token (ISS-0140). Admin-only. The
+   * `registry_publish` capability calls this on behalf of `source_forge.
+   * registerRepo`. Reconciled: re-minting for the same repo rotates the token.
+   * The raw token is returned ONCE — the caller sets it as the repo's Actions
+   * secret; the server keeps only its hash.
+   */
+  async function handleMintToken(req: Request): Promise<Response> {
+    if (!authorizeAdmin(req)) return unauthorized();
+    let body: { repo?: unknown; scope?: unknown };
+    try {
+      body = (await req.json()) as { repo?: unknown; scope?: unknown };
+    } catch {
+      return err('Invalid JSON body');
+    }
+    const repo = typeof body.repo === 'string' ? body.repo.trim() : '';
+    const scope = typeof body.scope === 'string' ? body.scope.trim() : '';
+    if (!repo) return err('repo is required');
+    if (!scope || !isValidName(scope)) return err('scope must be a valid package name');
+
+    const { token, entry, revokedHashes } = scopedTokenStore.mint(repo, scope);
+    for (const h of revokedHashes) auth.removeHashed(h);
+    auth.addHashed(entry.hash, entry.scope);
+    console.log(`[registry] minted scoped token for ${repo} → ${scope}`);
+    return Response.json({ ok: true, token, scope, repo });
+  }
+
+  /** Revoke all scoped tokens for a repo (ISS-0140). Admin-only. */
+  async function handleRevokeToken(req: Request): Promise<Response> {
+    if (!authorizeAdmin(req)) return unauthorized();
+    let body: { repo?: unknown };
+    try {
+      body = (await req.json()) as { repo?: unknown };
+    } catch {
+      return err('Invalid JSON body');
+    }
+    const repo = typeof body.repo === 'string' ? body.repo.trim() : '';
+    if (!repo) return err('repo is required');
+
+    const removed = scopedTokenStore.revoke(repo);
+    for (const h of removed) auth.removeHashed(h);
+    console.log(`[registry] revoked ${removed.length} scoped token(s) for ${repo}`);
+    return Response.json({ ok: true, repo, revoked: removed.length });
+  }
+
   const server = Bun.serve({
     port,
     async fetch(req, srv) {
@@ -273,10 +342,7 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
       //   - suffix='/'       → request was prefix + '/', or just '/'
       //   - suffix='/index.html'
       // See apps/celilo/designs/REGISTRY_BROWSE_UI.md (decision D2).
-      if (
-        method === 'GET' &&
-        (suffix === '' || suffix === '/' || suffix === '/index.html')
-      ) {
+      if (method === 'GET' && (suffix === '' || suffix === '/' || suffix === '/index.html')) {
         return landingResponse(publicUrl);
       }
 
@@ -329,10 +395,7 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
           //   3. Empty string (older publishes that pre-date the
           //      description capture and haven't been republished).
           const bootstrapEntry = bootstrap.get(name);
-          const description =
-            latest?.description ??
-            bootstrapEntry?.description ??
-            '';
+          const description = latest?.description ?? bootstrapEntry?.description ?? '';
           return {
             name,
             max_version: latest?.vers ?? '0.0.0',
@@ -359,14 +422,26 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
       }
 
       // Publish — rate-limit before even checking auth so a bad-token flood
-      // can't crowd out legitimate traffic on the shared buckets.
+      // can't crowd out legitimate traffic on the shared buckets. The scope
+      // check happens inside handlePublish, once the package name is known.
       if (method === 'PUT' && suffix === `${apiBase}/new`) {
         const rl = rateLimitOrNull(req, srv);
         if (rl) return rl;
-        if (!requireAuth(req)) return unauthorized();
         return handlePublish(req);
       }
 
+      // Mint / revoke per-repo scoped publish tokens (admin-only — ISS-0140).
+      if (method === 'POST' && suffix === `${apiBase}/tokens/mint`) {
+        const rl = rateLimitOrNull(req, srv);
+        if (rl) return rl;
+        return handleMintToken(req);
+      }
+      if (method === 'POST' && suffix === `${apiBase}/tokens/revoke`) {
+        const rl = rateLimitOrNull(req, srv);
+        if (rl) return rl;
+        return handleRevokeToken(req);
+      }
+
       if (suffix.startsWith(`${apiBase}/`)) {
         const modulePath = suffix.slice(apiBase.length + 1);
         // URL-decode path segments — module versions use a literal '+' to
@@ -387,10 +462,7 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
           // endpoint — see notes there.
           const latest = entries.filter((v) => !v.yanked).at(-1) ?? entries.at(-1);
           const bootstrapEntry = resolveBootstrap().get(name);
-          const description =
-            latest?.description ??
-            bootstrapEntry?.description ??
-            '';
+          const description = latest?.description ?? bootstrapEntry?.description ?? '';
           return Response.json({
             name,
             description,
@@ -434,9 +506,9 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
         if (method === 'DELETE' && parts.length === 3 && parts[2] === 'yank') {
           const rl = rateLimitOrNull(req, srv);
           if (rl) return rl;
-          if (!requireAuth(req)) return unauthorized();
           const [name, version] = parts;
           if (!isValidName(name) || !isValidVersion(version)) return notFound();
+          if (!authorizePackage(req, name)) return unauthorized();
           return setYanked(name, version, true);
         }
 
@@ -444,9 +516,9 @@ export function startServer(options: ServerOptions): ReturnType<typeof Bun.serve
         if (method === 'PUT' && parts.length === 3 && parts[2] === 'unyank') {
           const rl = rateLimitOrNull(req, srv);
           if (rl) return rl;
-          if (!requireAuth(req)) return unauthorized();
           const [name, version] = parts;
           if (!isValidName(name) || !isValidVersion(version)) return notFound();
+          if (!authorizePackage(req, name)) return unauthorized();
           return setYanked(name, version, false);
         }
       }
@@ -464,8 +536,7 @@ export function startFromEnv(): void {
   const port = Number(process.env.PORT ?? 3000);
   const pathPrefix = (process.env.PATH_PREFIX ?? '').replace(/\/$/, '');
   const publicUrl =
-    process.env.PUBLIC_URL ??
-    `https://${process.env.DOMAIN ?? 'celilo.computer'}${pathPrefix}`;
+    process.env.PUBLIC_URL ?? `https://${process.env.DOMAIN ?? 'celilo.computer'}${pathPrefix}`;
   const bootstrapModulesDir = process.env.BOOTSTRAP_MODULES_DIR || undefined;
   const bootstrapUploadsDir = process.env.BOOTSTRAP_UPLOADS_DIR || undefined;
   const bootstrapCacheDir = process.env.BOOTSTRAP_CACHE_DIR || undefined;
@@ -485,7 +556,9 @@ export function startFromEnv(): void {
   const bootstrapBits = [
     bootstrapModulesDir ? `modulesDir=${bootstrapModulesDir}` : '',
     bootstrapUploadsDir ? `uploadsDir=${bootstrapUploadsDir}` : '',
-  ].filter(Boolean).join(', ');
+  ]
+    .filter(Boolean)
+    .join(', ');
   console.log(
     `[registry] listening on :${server.port} (prefix=${pathPrefix || '(none)'}, publicUrl=${publicUrl}${
       bootstrapBits ? `, bootstrap=[${bootstrapBits}]` : ''

package/scripts/pack-celilo-packages.ts

@@ -13,9 +13,14 @@
  *   @celilo/capabilities → (none)
  *   @celilo/cli-display → (none)
  *
- * So 5 workspace packages need to land in the simulator. We rely on
- * `bun pm pack` to rewrite `workspace:^` deps to concrete versions, so
- * the published tarballs resolve cleanly without real npm.
+ * So 5 workspace packages need to land in the simulator. We rewrite each
+ * package's `workspace:^` deps to concrete `^<workspace-version>` ranges
+ * OURSELVES before `bun pm pack` — we do NOT rely on bun's lock-based
+ * expansion, which goes stale after a cross-caret version bump and pins
+ * dependents to an unresolvable old range (ISS-0103: a `0.3→0.4`
+ * capabilities bump left the lock at 0.3, so packed cli pinned
+ * `^0.3.0-alpha.0`, excluding the 0.4.x the sim served). package.json is
+ * restored after packing so `workspace:^` stays in source.
  *
  * Output directory is typically `packages/e2e/.npm-registry-cache/` —
  * staged into the npm-registry-sim Docker image at build time.
@@ -25,11 +30,73 @@
  */
 
 import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 const REPO_ROOT = join(import.meta.dir, '..', '..', '..');
 
+interface PackageJson {
+  name?: string;
+  version?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+}
+
+export interface WorkspaceRewrite {
+  depName: string;
+  oldSpec: string;
+  newSpec: string;
+}
+
+const DEP_BUCKETS = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+] as const;
+
+/**
+ * Rewrite `workspace:` deps in `pkg` to concrete ranges using the
+ * name→version map, mutating `pkg`. Mirrors the publish flow's
+ * `rewriteWorkspaceDeps`:
+ *   workspace:^      → ^<version>
+ *   workspace:~      → ~<version>
+ *   workspace:*  / workspace:  → *           (any version)
+ *   workspace:X.Y.Z  → X.Y.Z                 (explicit, passes through)
+ *
+ * We do this ourselves rather than trust `bun pm pack`'s lock-based
+ * expansion, which goes stale after a cross-caret version bump (ISS-0103).
+ * Only deps present in `versions` (our own @celilo/* set) are touched.
+ * Returns the rewrites applied.
+ */
+export function rewriteWorkspacePins(
+  pkg: PackageJson,
+  versions: Map<string, string>,
+): WorkspaceRewrite[] {
+  const rewrites: WorkspaceRewrite[] = [];
+  for (const bucket of DEP_BUCKETS) {
+    const deps = pkg[bucket];
+    if (!deps) continue;
+    for (const [name, spec] of Object.entries(deps)) {
+      if (!spec.startsWith('workspace:')) continue;
+      const version = versions.get(name);
+      if (!version) continue;
+      const range = spec.slice('workspace:'.length);
+      let newSpec: string;
+      if (range === '*' || range === '') newSpec = '*';
+      else if (range === '^') newSpec = `^${version}`;
+      else if (range === '~') newSpec = `~${version}`;
+      else newSpec = range;
+      if (newSpec === spec) continue;
+      deps[name] = newSpec;
+      rewrites.push({ depName: name, oldSpec: spec, newSpec });
+    }
+  }
+  return rewrites;
+}
+
 /**
  * Workspace packages that install.sh's transitive @celilo/* closure depends
  * on. Hardcoded by name → relative path so a typo in package.json or a future
@@ -63,27 +130,46 @@ function parseArgs(): CliArgs {
   return { destination };
 }
 
-function pack(pkgPath: string, destination: string): string {
+function pack(pkgPath: string, destination: string, versions: Map<string, string>): string {
   const fullPath = join(REPO_ROOT, pkgPath);
-  if (!existsSync(join(fullPath, 'package.json'))) {
+  const pkgJsonPath = join(fullPath, 'package.json');
+  if (!existsSync(pkgJsonPath)) {
     throw new Error(`No package.json in ${fullPath}`);
   }
-  // Capture filenames before/after so we can identify the tarball this
-  // pack call produced even when the destination already contains tarballs
-  // from earlier packages in the loop.
-  const before = new Set(readdirSync(destination).filter((f) => f.endsWith('.tgz')));
-  execSync(`bun pm pack --destination=${destination}`, {
-    cwd: fullPath,
-    stdio: 'inherit',
-  });
-  const after = readdirSync(destination).filter((f) => f.endsWith('.tgz'));
-  const produced = after.filter((f) => !before.has(f));
-  if (produced.length !== 1) {
-    throw new Error(
-      `Expected exactly one new tarball from packing ${pkgPath}, got ${produced.length}: ${produced.join(', ')}`,
-    );
+
+  // Rewrite workspace:^ deps to concrete ranges ourselves (see header /
+  // ISS-0103), then restore the original so workspace:^ stays in source.
+  const originalPkgJson = readFileSync(pkgJsonPath, 'utf-8');
+  const parsed = JSON.parse(originalPkgJson) as PackageJson;
+  const rewrites = rewriteWorkspacePins(parsed, versions);
+  if (rewrites.length > 0) {
+    const trailingNl = originalPkgJson.endsWith('\n') ? '\n' : '';
+    writeFileSync(pkgJsonPath, JSON.stringify(parsed, null, 2) + trailingNl);
+    for (const r of rewrites) {
+      console.log(`  rewrote ${r.depName}: ${r.oldSpec} → ${r.newSpec}`);
+    }
+  }
+
+  try {
+    // Capture filenames before/after so we can identify the tarball this
+    // pack call produced even when the destination already contains tarballs
+    // from earlier packages in the loop.
+    const before = new Set(readdirSync(destination).filter((f) => f.endsWith('.tgz')));
+    execSync(`bun pm pack --destination=${destination}`, {
+      cwd: fullPath,
+      stdio: 'inherit',
+    });
+    const after = readdirSync(destination).filter((f) => f.endsWith('.tgz'));
+    const produced = after.filter((f) => !before.has(f));
+    if (produced.length !== 1) {
+      throw new Error(
+        `Expected exactly one new tarball from packing ${pkgPath}, got ${produced.length}: ${produced.join(', ')}`,
+      );
+    }
+    return produced[0];
+  } finally {
+    writeFileSync(pkgJsonPath, originalPkgJson);
   }
-  return produced[0];
 }
 
 function workspaceVersion(pkgPath: string): string {
@@ -104,11 +190,17 @@ function main(): void {
   console.log(`Packing @celilo/* packages → ${destination}`);
   console.log('');
 
+  // The name→version map used to rewrite each package's workspace:^ deps to
+  // concrete ranges that resolve against the co-packed versions (ISS-0103).
+  const versions = new Map<string, string>(
+    PACKAGES_TO_PACK.map(({ name, path }) => [name, workspaceVersion(path)]),
+  );
+
   const results: Array<{ name: string; version: string; tarball: string }> = [];
   for (const { name, path } of PACKAGES_TO_PACK) {
     const version = workspaceVersion(path);
     console.log(`▸ ${name}@${version}  (${path})`);
-    const tarball = pack(path, destination);
+    const tarball = pack(path, destination, versions);
     results.push({ name, version, tarball });
     console.log(`  → ${tarball}`);
     console.log('');

package/src/shared-infra.ts

@@ -12,7 +12,7 @@
 
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
-import { writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { generateSharedInfraYaml, SHARED_PROJECT_NAME, SHARED_NETWORKS } from './docker-compose-generator';
 import { ensureRegistryServerBundle } from './registry-bundle';
 
@@ -146,6 +146,23 @@ export async function ensureSharedInfra(): Promise<void> {
   const yaml = generateSharedInfraYaml();
   writeFileSync(join(e2eDir, SHARED_COMPOSE_FILE), yaml);
 
+  // Seed the live DNS zone files from their templates BEFORE the compose
+  // mounts them. config/dns/{iamtheinternet.org,example.net}.zone are
+  // gitignored runtime state (scrubDnsZones rewrites them per-test); on a
+  // fresh checkout they don't exist yet, and a Docker bind-mount of a missing
+  // host path silently creates an empty DIRECTORY — so Knot serves no zone and
+  // DNS convergence times out. Seeding here makes the bind-mount targets real
+  // files, so shared infra bootstraps from a clean checkout (e.g. CI builder).
+  for (const zone of ['iamtheinternet.org', 'example.net']) {
+    const tpl = join(e2eDir, 'config', 'dns', 'templates', `${zone}.zone`);
+    const live = join(e2eDir, 'config', 'dns', `${zone}.zone`);
+    // Remove an empty dir left by a prior bind-mount on a missing path.
+    if (existsSync(live) && statSync(live).isDirectory()) {
+      rmSync(live, { recursive: true, force: true });
+    }
+    copyFileSync(tpl, live);
+  }
+
   // Build and start
   console.log('[progress:start] building shared infrastructure images | shared images built');
   run(`docker compose -f ${SHARED_COMPOSE_FILE} -p ${SHARED_PROJECT_NAME} build`,