my-durable 0.0.3 → 0.0.5

package/apps/dpi-playground/apps/dpi-playground-hub/src/main.ts

@@ -12,8 +12,17 @@ import { DeviceMonitor } from "./monitor.js";
 import { StreamMux } from "./mux.js";
 import { proxy } from "./proxy.js";
 import { guard, requireTls } from "./guard.js";
-import { ipKey, isTrustedProxy } from "./client-ip.js";
+import { ipKey, isTrustedProxy, viaTls } from "./client-ip.js";
 import { Audit, denialLogging } from "./audit.js";
+import {
+  ADMIN_COOKIE,
+  LOGIN_RATE,
+  SESSION_TTL_MS,
+  bootstrapAdminToken,
+  requireAdmin,
+  signSession,
+  tokenEquals,
+} from "./admin-auth.js";
 import { body as failureBody, describeFailure, errorMiddleware, safe } from "./http-errors.js";
 import { TokenBuckets } from "./limiter.js";
 import { PairingService } from "./pairing.js";
@@ -56,6 +65,9 @@ const requireTlsEnabled = tlsRequired();
 
 const registry = new NetworkRegistry();
 registry.clearTunnelState(); // live tunnel state is RAM-only; never resurrect from DB
+// The operator's own credential: minted at first boot into DPI_HOME/admin.token (0600),
+// overridable via DPI_ADMIN_TOKEN. A set-but-short token refuses to boot (admin-auth.ts).
+const adminToken = bootstrapAdminToken();
 const configFile = seedFromConfig(registry, appDir);
 const monitor = new DeviceMonitor(registry);
 monitor.start();
@@ -108,6 +120,15 @@ function auditFloorFromEnv(): { minFreeBytes?: number } {
 }
 const audit = new Audit(registry, auditFloorFromEnv());
 audit.startSweeper();
+if (adminToken.created)
+  audit.append({
+    actor: "hub",
+    action: "admin.token_created",
+    outcome: "ok",
+    detail: { file: adminToken.path },
+  });
+/** Every admin route requires this: the dpi_admin cookie or the raw token as a bearer. */
+const adminAuth = requireAdmin(adminToken.token);
 // Everything registered below needs proof of TLS; /healthz (above) stays reachable for supervisors.
 if (requireTlsEnabled) app.use(denialLogging(audit), requireTls());
 
@@ -181,7 +202,11 @@ const pairErr = (
 // PairingService enforces its own per-IP code/verify buckets + fail-window
 // here. Host-allowlist + denial logging still apply.
 const pairGuard = [denialLogging(audit), guard(allowedHosts)] as const;
-app.post("/api/pair/code", ...pairGuard, express.json({ limit: "16kb" }), (req, res) => {
+// The operator side of pairing (mint/state/approve/cancel) is admin surface:
+// it needs the admin cookie or bearer too. pair/start + pair/verify stay public
+// — their bearer is the pairing code, presented by the DEVICE, not the operator.
+const adminPairGuard = [denialLogging(audit), guard(allowedHosts), adminAuth] as const;
+app.post("/api/pair/code", ...adminPairGuard, express.json({ limit: "16kb" }), (req, res) => {
   const r = pairing.createCode(req.ip ?? "unknown");
   return r.ok ? res.status(201).json(r.value) : pairErr(r, res);
 });
@@ -194,31 +219,76 @@ app.post("/api/pair/verify", ...pairGuard, express.json({ limit: "16kb" }), asyn
   if (r.ok) return res.status(r.status).json(r.value);
   pairErr(r, res);
 });
-app.get("/api/pair/codes/:codeId", ...pairGuard, (req, res) => {
+app.get("/api/pair/codes/:codeId", ...adminPairGuard, (req, res) => {
   const r = pairing.status(String(req.params.codeId));
   return r.ok ? res.json(r.value) : pairErr(r, res);
 });
 app.post(
   "/api/pair/codes/:codeId/approve",
-  ...pairGuard,
+  ...adminPairGuard,
   express.json({ limit: "16kb" }),
   (req, res) => {
     const r = pairing.approve(String(req.params.codeId), req.body);
     return r.ok ? res.json(r.value) : pairErr(r, res);
   },
 );
-app.post("/api/pair/codes/:codeId/cancel", ...pairGuard, (req, res) => {
+app.post("/api/pair/codes/:codeId/cancel", ...adminPairGuard, (req, res) => {
   const r = pairing.cancel(String(req.params.codeId));
   return r.ok ? res.json(r.value) : pairErr(r, res);
 });
 
-// Admin /api surface: guarded, rate-bucketed per real client IP, 256 KiB JSON.
+// Admin login: POST /api/session {token} → the dpi_admin cookie. Own per-IP bucket
+// (5/min burst 5) — a failed guess must never be retried at line rate. Audited as
+// admin.login ok|denied with the client address as the actor and no token material.
+const loginBuckets = new TokenBuckets({
+  capacity: LOGIN_RATE.capacity,
+  perMinute: LOGIN_RATE.perMinute,
+  maxKeys: 10_000,
+  idleTtlMs: 15 * 60_000,
+});
+setInterval(() => loginBuckets.sweep(), 60_000).unref();
+app.post(
+  "/api/session",
+  denialLogging(audit),
+  guard(allowedHosts),
+  (req, res, next) => {
+    const taken = loginBuckets.take(ipKey(req.ip ?? req.socket.remoteAddress ?? "?"));
+    if (taken.ok) return void next();
+    res.set("Retry-After", String(Math.max(1, Math.ceil(taken.retryAfterMs / 1000))));
+    res.status(429).json(err("rate_limited", "Too many login attempts; slow down"));
+  },
+  express.json({ limit: "16kb" }),
+  (req, res) => {
+    const presented = typeof req.body?.token === "string" ? req.body.token : "";
+    const ip = req.ip ?? "unknown";
+    if (!presented || !tokenEquals(presented, adminToken.token)) {
+      audit.denied("admin.login", ip, { reason: "bad_token" });
+      return void res.status(401).json(err("unauthorized", "Missing or invalid admin token"));
+    }
+    const exp = Date.now() + SESSION_TTL_MS;
+    audit.append({ actor: `ip:${ipKey(ip)}`, action: "admin.login", outcome: "ok" });
+    // Secure only when the request arrived via the TLS proxy: on plain loopback
+    // (local development, tests) the flag would just break the cookie.
+    res.cookie(ADMIN_COOKIE, signSession(adminToken.token, exp), {
+      httpOnly: true,
+      sameSite: "strict",
+      secure: viaTls(req),
+      path: "/",
+      maxAge: SESSION_TTL_MS,
+    });
+    res.json({ ok: true, exp });
+  },
+);
+
+// Admin /api surface: guarded, rate-bucketed per real client IP, 256 KiB JSON,
+// and behind the admin credential (cookie or bearer).
 app.use(
   "/api",
   denialLogging(audit),
   guard(allowedHosts),
   apiRate,
   express.json({ limit: "256kb" }),
+  adminAuth,
 );
 app.post("/api/pair/resolve", (req, res) => {
   const r = pairing.resolveCode(req.body);
@@ -435,6 +505,9 @@ server.listen(port, host, () => {
     console.log(
       "TLS required: only requests the loopback TLS proxy marks X-Forwarded-Proto: https are served",
     );
+  console.log(
+    `admin: login with the token in ${adminToken.path} (POST /api/session sets the browser cookie)`,
+  );
   if (host !== "127.0.0.1" && host !== "localhost")
     console.warn(
       `WARNING: the hub is listening on ${host}. Anyone who can reach it can drive every device it holds tokens for.`,

package/apps/dpi-playground/apps/dpi-playground-hub/src/pairing.ts

@@ -39,6 +39,9 @@ import {
   PairRequest as PairRequestSchema,
   PairResponse as PairResponseSchema,
   checkPairingDto,
+  encodePairOffer,
+  isPairCode,
+  normalizePairCode,
   pairingSigningPayload,
 } from "../../../../dpi-sdk/src/protocol/pairing.js";
 import type { PairCodeIssue, TokenIssue } from "../../../../dpi-sdk/src/protocol/pairing.js";
@@ -52,7 +55,18 @@ import type { PairCodeState } from "../../../../dpi-sdk/src/protocol/pairing.js"
 const CODE_TTL_MS = 300_000;
 const NONCE_TTL_MS = 60_000;
 const RECEIPT_GRACE_MS = 120_000;
-const CODE_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/**
+ * A code as a human types it (`abcd-2345-ef67`) is canonicalised before the strict wire
+ * schema sees it: only the code field is rewritten, so unknown fields are still rejected.
+ */
+function withCanonicalCode(body: unknown): unknown {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return body;
+  const raw = (body as { code?: unknown }).code;
+  if (typeof raw !== "string") return body;
+  const code = normalizePairCode(raw);
+  return code && code !== raw ? { ...(body as Record<string, unknown>), code } : body;
+}
 
 export type PairingFailure = {
   ok: false;
@@ -191,6 +205,21 @@ export class PairingService {
     return { ok: true, value };
   }
 
+  /**
+   * v2 offer link, minted from the SAME values the v1 pairUrl uses (same code,
+   * same expiry): the whole handoff — hub origin, hubId, code, expiry — rides
+   * the #offer= fragment, which no server or CDN ever sees in a log.
+   */
+  private offerUrlFor(code: string, expiresAt: number): string {
+    return `${this.deps.hubOrigin}/pair#offer=${encodePairOffer({
+      v: 2,
+      hub: this.deps.hubOrigin,
+      id: this.deps.hubId,
+      code,
+      exp: expiresAt,
+    })}`;
+  }
+
   /** POST /api/pair/code (admin) — mint a fresh single-use code. */
   createCode(address: string): { ok: true; value: PairCodeIssue } | PairingFailure {
     const now = this.now();
@@ -200,7 +229,9 @@ export class PairingService {
       return this.fail(429, "rate_limited", "Pairing capacity reached; retry later", 60_000);
     let code = "";
     do {
-      code = [...randomBytes(8)].map((b) => CODE_ALPHABET[b % 32]).join("");
+      // A code is a bearer secret authorising one enrollment: canonical UUID v4 = 122 random bits.
+      // The re-mint guard is kept: it costs nothing and makes "two live codes share a string" impossible.
+      code = randomUUID();
     } while (this.byCode.has(code));
     const entry: CodeEntry = {
       codeId: randomUUID(),
@@ -225,18 +256,19 @@ export class PairingService {
       expiresAt: entry.expiresAt,
       hubOrigin: this.deps.hubOrigin,
       pairUrl: `${this.deps.hubOrigin}/pair?code=${code}&v=1`,
+      offerUrl: this.offerUrlFor(code, entry.expiresAt),
     });
   }
 
   /** Admin handoff lookup. Reuses a code; never creates an enrollment or approves it. */
   resolveCode(body: unknown): { ok: true; value: PairCodeIssue } | PairingFailure {
-    const code = (body as { code?: unknown } | null)?.code;
+    const raw = (body as { code?: unknown } | null)?.code;
+    const code = typeof raw === "string" ? normalizePairCode(raw) : undefined;
     if (
       !body ||
       typeof body !== "object" ||
       Object.keys(body).length !== 1 ||
-      typeof code !== "string" ||
-      !/^[A-Z2-7]{8}$/.test(code)
+      !isPairCode(code)
     )
       return this.fail(400, "code_invalid", "Invalid pairing handoff");
     const codeId = this.byCode.get(code);
@@ -252,6 +284,7 @@ export class PairingService {
       expiresAt: entry.expiresAt,
       hubOrigin: this.deps.hubOrigin,
       pairUrl: `${this.deps.hubOrigin}/pair?code=${entry.code}&v=1`,
+      offerUrl: this.offerUrlFor(entry.code, entry.expiresAt),
     });
   }
 
@@ -272,11 +305,13 @@ export class PairingService {
       return this.fail(429, "rate_limited", "Too many pairing failures; slow down", 60_000);
     const taken = this.startLimiter.take(ip);
     if (!taken.ok) return this.rateLimited(taken, "Too many pairing starts; slow down");
-    if (!checkPairingDto(PairRequestSchema, body)) {
+    // A grouped or lower-case code from a client is the same code: canonicalise it first.
+    const request = withCanonicalCode(body);
+    if (!checkPairingDto(PairRequestSchema, request)) {
       this.noteFailure(ip);
       return this.fail(400, "invalid", "pair.request body failed schema validation");
     }
-    const req = body as {
+    const req = request as {
       requestId: string;
       code: string;
       deviceUid: string;

package/apps/dpi-sdk/src/protocol/limits.ts

@@ -72,6 +72,17 @@ export const RECONNECT_BACKOFF_S = { initS: 1, capS: 15 } as const;
 /** Monitor probe backoff: the same curve with a 30 s cap. */
 export const MONITOR_BACKOFF_S = { initS: 1, capS: 30 } as const;
 
+/**
+ * Pairing codes are minted as canonical lower-case UUID v4 (122 random bits): the code is a
+ * bearer secret that authorises one enrollment, so 40/60-bit base32 was too short.
+ * `PAIR_CODE_LENGTH` and `PAIR_CODE_LEGACY_LENGTH` are the base32 lengths PARSING still accepts
+ * for links already in flight; the hub never mints them anymore.
+ */
+export const PAIR_CODE_UUID_LENGTH = 36;
+/** Legacy base32 code length (60 bits), accepted when parsing only. */
+export const PAIR_CODE_LENGTH = 12;
+/** Oldest legacy base32 code length (40 bits), accepted when parsing only. */
+export const PAIR_CODE_LEGACY_LENGTH = 8;
 /** Pairing code TTL by hub clock. 5 min. */
 export const PAIR_CODE_TTL_MS = 300_000;
 /** Challenge nonce TTL. 60 s. */
@@ -82,6 +93,12 @@ export const PAIR_RECEIPT_GRACE_MS = 120_000;
 export const PAIR_SIGNATURE_FAIL_LIMIT = 3;
 /** Clock-skew tolerance for challenges accepted by the device. ±60 s. */
 export const PAIR_CLOCK_SKEW_MS = 60_000;
+/** Pair-offer decode window: exp may sit this far in the PAST (clock skew). 30 s. */
+export const PAIR_OFFER_SKEW_MS = 30_000;
+/** Pair-offer decode window: exp may sit at most this far in the FUTURE. 10 min. */
+export const PAIR_OFFER_MAX_AHEAD_MS = 600_000;
+/** Decoded pair-offer JSON byte cap — minted offers are ~180 bytes; anything bigger is not ours. */
+export const PAIR_OFFER_MAX_JSON_BYTES = 1_024;
 
 /** Rate limits (per real-IP, hub-side token buckets). */
 export const PAIR_RATE_LIMITS = {

package/apps/dpi-sdk/src/protocol/pairing.ts

@@ -10,6 +10,14 @@
  */
 import { Type, type Static } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
+import {
+  PAIR_CODE_LENGTH,
+  PAIR_CODE_LEGACY_LENGTH,
+  PAIR_CODE_UUID_LENGTH,
+  PAIR_OFFER_MAX_AHEAD_MS,
+  PAIR_OFFER_MAX_JSON_BYTES,
+  PAIR_OFFER_SKEW_MS,
+} from "./limits.js";
 
 const Strict = { additionalProperties: false } as const;
 
@@ -29,7 +37,57 @@ const DeviceId = Type.String({
 const Fingerprint = Type.String({ pattern: "^sha256:[0-9a-f]{64}$", minLength: 71, maxLength: 71 });
 const Nonce = Type.String({ pattern: "^[A-Za-z0-9_-]{43}$", minLength: 43, maxLength: 43 });
 const TunnelToken = Type.String({ pattern: "^dpt_[A-Za-z0-9_-]{43}$", minLength: 47, maxLength: 47 });
-const PairCode = Type.String({ pattern: "^[A-Z2-7]{8}$", minLength: 8, maxLength: 8 });
+/**
+ * Canonical lower-case UUID v4: any hex is NOT a code, so the version nibble must be 4 and the
+ * variant nibble 8/9/a/b.
+ */
+const UUID_V4 = "[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}";
+/**
+ * One pattern for every accepted code shape: the minted UUID v4, plus the 12- and 8-char base32
+ * forms that links already in flight still carry. `$` alone can match before a final newline, so
+ * the pattern ends with an explicit lookahead — the length clamp below cannot catch a newline
+ * when min and max differ.
+ */
+export const PAIR_CODE_PATTERN = `^(?:${UUID_V4}|[A-Z2-7]{12}|[A-Z2-7]{8})(?![\\s\\S])`;
+const PairCode = Type.String({
+  pattern: PAIR_CODE_PATTERN,
+  minLength: PAIR_CODE_LEGACY_LENGTH,
+  maxLength: PAIR_CODE_UUID_LENGTH,
+});
+
+const PAIR_CODE_RE = new RegExp(PAIR_CODE_PATTERN);
+/** Shape test for the UUID family — used to pick the normalisation rule, never to accept on its own. */
+const UUID_SHAPED_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+
+/**
+ * Exact-shape check for a pairing code, with NO trimming: a value with a leading/trailing space
+ * or a newline is not a code. Consumers that accept a typed value use `normalizePairCode`.
+ */
+export function isPairCode(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > PAIR_CODE_UUID_LENGTH) return false;
+  return PAIR_CODE_RE.test(value);
+}
+
+/**
+ * Canonicalise a code a human typed or pasted. The two families canonicalise differently, so the
+ * shape decides first:
+ * - UUID v4 (`A1B2…-E5F6-4789-ABCD-EFF012345678`): hyphens are structure — only the case changes.
+ * - base32 (`abcd-2345-ef67`, `ABCD 2345 EF67`): hyphens/spaces are group separators — they go
+ *   and the result is upper case.
+ * Anything that does not fit either family exactly (a hyphen-less hex run, a 10/11/13-char run,
+ * non-alphabet characters, a truncated group like `ABCD-2345`) is refused.
+ */
+export function normalizePairCode(raw: string): string | undefined {
+  if (typeof raw !== "string") return undefined;
+  if (UUID_SHAPED_RE.test(raw)) {
+    const lower = raw.toLowerCase();
+    return isPairCode(lower) ? lower : undefined; // version/variant nibbles must be v4
+  }
+  const compact = raw.replace(/[\s-]+/g, "").toUpperCase();
+  if (!isPairCode(compact)) return undefined;
+  if (/[\s-]/.test(raw) && compact.length !== PAIR_CODE_LENGTH) return undefined;
+  return compact;
+}
 
 export const PairRequest = Type.Object(
   {
@@ -163,6 +221,8 @@ export const PairCodeIssue = Type.Object(
     expiresAt: Type.Integer(),
     hubOrigin: Type.String({ maxLength: 2048 }),
     pairUrl: Type.String({ maxLength: 4096 }),
+    /** v2 offer link: the whole handoff rides the #offer= fragment (never a query). */
+    offerUrl: Type.Optional(Type.String({ maxLength: 2048 })),
   },
   Strict,
 );
@@ -270,6 +330,146 @@ export function parseHubOrigin(
   return { ok: true, origin: url.origin, tunnelUrl: `${url.origin}/api/tunnel` };
 }
 
+/**
+ * v2 pairing offer — ONE artifact carrying identity, trust anchor and transport:
+ * hub origin + hubId + code + expiry, base64url-encoded into the URL FRAGMENT
+ * (`<hubOrigin>/pair#offer=…`). A fragment never leaves the client, so the
+ * code cannot reach server/CDN query logs, and the origin travels inside the
+ * link (no --hub needed on the device).
+ */
+export interface PairOffer {
+  v: 2;
+  /** Canonical HTTPS hub origin (the transport the device pairs against). */
+  hub: string;
+  /** hubId trust anchor (deployment id), a canonical UUID. */
+  id: string;
+  /** The single-use pairing code — canonical UUID v4, the only minted family. */
+  code: string;
+  /** Expiry, hub epoch ms. */
+  exp: number;
+}
+
+/** base64url (no padding) of UTF-8 bytes — browser-safe, no Node builtins. */
+function offerEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function offerDecode(raw: string): Uint8Array | undefined {
+  if (raw === "" || !/^[A-Za-z0-9_-]+$/.test(raw)) return undefined;
+  try {
+    const binary = atob(raw.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return undefined;
+  }
+}
+
+const OFFER_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The minted family only: offer links carry a UUID v4 code, never legacy base32. */
+const OFFER_CODE_RE = new RegExp(`^${UUID_V4}$`);
+
+/**
+ * Encode an offer to the exact fragment payload: canonical JSON (field order
+ * v,hub,id,code,exp — byte-lean and deterministic), base64url, no padding.
+ * Pure encoder: it does not validate; callers mint from live hub values.
+ */
+export function encodePairOffer(offer: PairOffer): string {
+  return offerEncode(
+    new TextEncoder().encode(
+      JSON.stringify({ v: offer.v, hub: offer.hub, id: offer.id, code: offer.code, exp: offer.exp }),
+    ),
+  );
+}
+
+/**
+ * Structural decode (freshness-blind): exactly the five known fields, v===2,
+ * canonical HTTPS origin (byte-exact, reusing the parseHubOrigin rules),
+ * canonical UUIDs for id and code, safe-integer exp. Unknown or malformed
+ * input → undefined, never a throw. Exported so a caller can tell an EXPIRED
+ * offer apart from junk (decodePairOffer refuses both).
+ */
+export function readPairOffer(raw: string): PairOffer | undefined {
+  const bytes = offerDecode(raw);
+  if (!bytes || bytes.length > PAIR_OFFER_MAX_JSON_BYTES) return undefined;
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return undefined;
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json)) return undefined;
+  const o = json as Record<string, unknown>;
+  if (Object.keys(o).length !== 5 || o.v !== 2) return undefined; // unknown/missing fields refuse
+  if (typeof o.hub !== "string") return undefined;
+  const origin = parseHubOrigin(o.hub);
+  if (!origin.ok || origin.origin !== o.hub) return undefined; // canonical form, byte-exact
+  if (typeof o.id !== "string" || !OFFER_UUID_RE.test(o.id)) return undefined;
+  if (typeof o.code !== "string" || !OFFER_CODE_RE.test(o.code)) return undefined;
+  if (typeof o.exp !== "number" || !Number.isSafeInteger(o.exp)) return undefined;
+  return { v: 2, hub: o.hub, id: o.id, code: o.code, exp: o.exp };
+}
+
+/**
+ * Strict decode: the structural rules above PLUS freshness — exp is in the
+ * future (30 s clock skew allowed) and no further ahead than 10 minutes.
+ * Unknown/malformed/stale → undefined, never a throw.
+ */
+export function decodePairOffer(raw: string, now: number = Date.now()): PairOffer | undefined {
+  const offer = readPairOffer(raw);
+  if (!offer) return undefined;
+  if (offer.exp < now - PAIR_OFFER_SKEW_MS) return undefined;
+  if (offer.exp > now + PAIR_OFFER_MAX_AHEAD_MS) return undefined;
+  return offer;
+}
+
+export interface ParsedPairOfferUrl {
+  offer: PairOffer;
+  /** The URL minus its fragment (`<origin>/pair`) — safe to keep in history. */
+  rest: string;
+}
+
+/**
+ * The raw `#offer=` payload of a URL, when the fragment is exactly one
+ * unpadded base64url run — undefined otherwise. The cheap first look a caller
+ * uses to tell "this is an offer link" apart from a v1 pair URL.
+ */
+export function pairOfferFragment(url: string): string | undefined {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    return undefined;
+  }
+  if (!u.hash.startsWith("#offer=")) return undefined;
+  const payload = u.hash.slice("#offer=".length);
+  return /^[A-Za-z0-9_-]+$/.test(payload) ? payload : undefined;
+}
+
+/**
+ * Parse an offer LINK: only `<origin>/pair` (or `/pair/`) with the fragment
+ * `#offer=<payload>` and nothing else — a stray query or any other path →
+ * undefined. The offer's hub must equal the link's own origin (the hub minted
+ * this link); the fragment never travels server-side.
+ */
+export function parsePairOfferUrl(url: string, now: number = Date.now()): ParsedPairOfferUrl | undefined {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    return undefined;
+  }
+  if (!/^\/pair\/?$/.test(u.pathname)) return undefined;
+  if (u.username || u.password || u.search) return undefined; // the payload rides the fragment only
+  if (!u.hash.startsWith("#offer=")) return undefined;
+  const offer = decodePairOffer(u.hash.slice("#offer=".length), now);
+  if (!offer || offer.hub !== u.origin) return undefined;
+  return { offer, rest: `${u.origin}/pair` };
+}
+
 /** Exact Ed25519 signing payload — element order is normative (03 §4.2). */
 export function pairingSigningPayload(parts: {
   hubOrigin: string;

package/apps/dpi-tui/src/app.ts

@@ -26,7 +26,7 @@ import {
 } from "../../dpi-sdk/src/api.ts";
 import type { NetworkRegistry } from "../../dpi-sdk/src/node/registry.ts";
 import { COMMANDS, runCommand } from "./commands.ts";
-import { pickModel, pickSession, Prompt } from "./pickers.ts";
+import { pickModel, pickSession, Prompt, SecretPrompt } from "./pickers.ts";
 import { Line, spinner, TranscriptView } from "./render.ts";
 import { c, editorTheme } from "./theme.ts";
 
@@ -249,6 +249,11 @@ export class App {
     this.tui.requestRender();
   }
 
+  /** How many overlays are open (the welcome screen waits for panels to close). */
+  get overlayCount() {
+    return this.overlays.length;
+  }
+
   closeOverlay(exitIfNothing = false) {
     const overlay = this.overlays.pop();
     overlay?.handle.hide();
@@ -277,6 +282,25 @@ export class App {
     });
   }
 
+  /** Like prompt(), but the value is only ever rendered as bullets (tokens). */
+  promptSecret(label: string) {
+    return new Promise<string | undefined>((done) => {
+      this.overlay(
+        new SecretPrompt(
+          label,
+          (value) => {
+            this.closeOverlay();
+            done(value.trim());
+          },
+          () => {
+            this.closeOverlay();
+            done(undefined);
+          },
+        ),
+      );
+    });
+  }
+
   flash(text: string, error = false) {
     this.notice = { text, error, at: Date.now() };
     this.redraw(false);