my-durable 0.0.7 → 0.0.8

package/apps/dpi-playground/apps/dpi-playground-fe/src/components/PairDeviceWizard.vue

@@ -18,8 +18,16 @@
  */
 import { computed, onBeforeUnmount, onMounted, ref, watch } from "vue";
 import { CheckCircle2, Copy, RefreshCw, ShieldAlert, X } from "lucide-vue-next";
-import { createPairingSession, pairingAdmin, pollCode, type PairingSession } from "../client/pair";
+import {
+  createPairingSession,
+  pairingAdmin,
+  pollCode,
+  qrPayload,
+  type PairingSession,
+  type PendingPairing,
+} from "../client/pair";
 import { qrSvg } from "../client/qrcode";
+import DeviceHandoff from "./DeviceHandoff.vue";
 import type { PairCodeIssue, PairCodeState } from "@sdk/api";
 import { DpiError } from "@sdk/errors";
 import { isPairCode } from "@sdk/protocol/pairing";
@@ -44,6 +52,8 @@ const replaceKey = ref(false);
 const copied = ref(false);
 const linkCopied = ref(false);
 const watcher = ref<(() => void) | undefined>();
+/** Machines that asked the hub for a code themselves (device-initiated enrollment). */
+const pending = ref<PendingPairing[]>([]);
 
 const grouped = computed(() => {
   const code = issue.value?.code ?? "";
@@ -55,7 +65,9 @@ const grouped = computed(() => {
 });
 const qrData = computed(() => {
   if (!issue.value) return "";
-  return issue.value.pairUrl;
+  // Gap #3: the QR rides the #offer= fragment (qrPayload) — never the v1
+  // pairUrl, whose ?code= query would land the pairing code in server logs.
+  return qrPayload(issue.value);
 });
 const qr = computed(() => (qrData.value ? qrSvg(qrData.value, 148) : ""));
 const fingerprint = computed(() => state.value?.enrollment?.keyFingerprint ?? "");
@@ -249,7 +261,40 @@ async function close(): Promise<void> {
 
 defineExpose({ close });
 
+let pendingTimer: ReturnType<typeof setInterval> | undefined;
+async function refreshPending(): Promise<void> {
+  try {
+    pending.value = (await pairingAdmin.pending()).codes;
+  } catch {
+    // The list is a convenience; a failure must never break the manual flow.
+  }
+}
+/** Open the approval flow for a machine that already asked (no code to carry). */
+async function reviewPending(p: PendingPairing): Promise<void> {
+  issue.value = undefined;
+  state.value = undefined;
+  error.value = "";
+  const s = createPairingSession();
+  session.value = s;
+  step.value = p.phase === "approved_ready" ? "approve" : "proof";
+  void pollCode(s, p.codeId, {
+    intervalMs: 1_000,
+    onState: (st) => {
+      state.value = st;
+      if (st.phase === "awaiting_proof") step.value = "proof";
+      else if (st.phase === "awaiting_approval" || st.phase === "approved") step.value = "approve";
+      else if (st.phase === "issued" || st.phase === "connected") step.value = "issued";
+      else if (st.phase === "cancelled") step.value = "cancelled";
+      else if (st.phase === "expired") step.value = "expired";
+    },
+  }).catch((e) => {
+    error.value = e instanceof Error ? e.message : String(e);
+  });
+}
+
 onMounted(() => {
+  void refreshPending();
+  pendingTimer = setInterval(() => void refreshPending(), 3_000);
   if (props.handoff && "error" in props.handoff) {
     error.value = props.handoff.error;
     step.value = "expired";
@@ -258,6 +303,7 @@ onMounted(() => {
   void createCode(props.handoff?.code);
 });
 onBeforeUnmount(() => {
+  clearInterval(pendingTimer);
   const s = session.value;
   if (s && !s.closed() && issue.value && !settled()) {
     void cancelLive(true).then((result) => {
@@ -280,6 +326,37 @@ onBeforeUnmount(() => {
         </button>
       </header>
 
+      <DeviceHandoff
+        v-if="props.handoff && 'offerFragment' in props.handoff && props.handoff.offerFragment"
+        :offer-fragment="props.handoff.offerFragment"
+      />
+
+      <!-- Machines that asked the hub for a code themselves. This is the
+           device-initiated enrollment: the operator reads WHO is asking (name,
+           host, platform, hub-computed fingerprint) before approving — the shape
+           the reference clients put in their QR/offer. -->
+      <section v-if="pending.length" class="pair-pending" aria-label="Machines waiting for approval">
+        <h3>Machines waiting for you</h3>
+        <ul>
+          <li v-for="p in pending" :key="p.codeId">
+            <div class="who">
+              <strong>{{ p.deviceName ?? "unnamed device" }}</strong>
+              <span v-if="p.hostname" class="muted">{{ p.hostname }}</span>
+              <span v-if="p.platform" class="muted">{{ p.platform }}</span>
+            </div>
+            <div class="fp">{{ p.keyFingerprint }}</div>
+            <div class="row">
+              <span class="phase">{{ p.phase.replaceAll("_", " ") }}</span>
+              <button type="button" class="small" @click="reviewPending(p)">Review</button>
+            </div>
+          </li>
+        </ul>
+        <p class="hint">
+          Compare each fingerprint with the machine's own terminal before approving. Codes are
+          minted by the hub — nothing has to be copied to the machine.
+        </p>
+      </section>
+
       <p v-if="step === 'boot'" class="hint">Minting a pairing code…</p>
 
       <template v-else-if="issue">
@@ -297,7 +374,12 @@ onBeforeUnmount(() => {
               <button type="button" class="small" @click="copyCode">
                 <Copy :size="14" /> {{ copied ? "Copied" : "Copy code" }}
               </button>
-              <button type="button" class="small" @click="copyLink" title="Self-contained link: hub, code and expiry all in the fragment — it never reaches server logs">
+              <button
+                type="button"
+                class="small"
+                @click="copyLink"
+                title="Self-contained link: hub, code and expiry all in the fragment — it never reaches server logs"
+              >
                 <Copy :size="14" /> {{ linkCopied ? "Copied link" : "Copy link" }}
               </button>
             </div>
@@ -305,7 +387,12 @@ onBeforeUnmount(() => {
               Run the device pairing command and scan, or enter this code on the device. Expires in
               5 minutes.
             </p>
-            <div class="pair-qr" aria-label="Pairing QR code" v-html="qr" />
+            <div
+              class="pair-qr"
+              aria-label="Pairing QR code"
+              title="Same offer link as Copy link: hub, code and expiry all in the #offer= fragment — it never reaches server logs"
+              v-html="qr"
+            />
           </div>
 
           <div class="pair-side">
@@ -458,4 +545,19 @@ onBeforeUnmount(() => {
     transform: rotate(360deg);
   }
 }
-</style>
+
+.pair-pending {
+  margin: 0 0 18px;
+  padding: 14px 16px;
+  border: 1px solid #2a3442;
+  border-radius: 12px;
+}
+.pair-pending h3 { margin: 0 0 10px; font-size: 14px; }
+.pair-pending ul { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
+.pair-pending li { display: grid; gap: 4px; padding-bottom: 10px; border-bottom: 1px solid #222b36; }
+.pair-pending li:last-child { border-bottom: 0; padding-bottom: 0; }
+.pair-pending .who { display: flex; gap: 8px; align-items: baseline; flex-wrap: wrap; }
+.pair-pending .fp { font-family: ui-monospace, monospace; font-size: 12px; word-break: break-all; color: #7ee2a8; }
+.pair-pending .row { display: flex; gap: 10px; align-items: center; justify-content: space-between; }
+.pair-pending .phase { font-size: 12px; color: #8fa0b5; }
+</style>

package/apps/dpi-playground/apps/dpi-playground-fe/src/components/TreeRow.vue

@@ -60,7 +60,9 @@ const dot = computed(() => {
   const s = device.value?.status;
   return s === "online" ? "on" : s === "checking" ? "chk" : s === "offline" ? "off" : "err";
 });
-const label = computed(() => device.value?.id ?? session.value?.name ?? agent.value?.name ?? "");
+const label = computed(
+  () => device.value?.name ?? device.value?.id ?? session.value?.name ?? agent.value?.name ?? "",
+);
 const title = computed(() => {
   if (device.value)
     return `${device.value.name} · ${device.value.url}${device.value.error ? `\n${device.value.error}` : ""}`;

package/apps/dpi-playground/apps/dpi-playground-hub/src/admin-auth.ts

@@ -7,7 +7,8 @@
  *   configuration mistake and REFUSES to boot — it is never silently replaced.
  * - Otherwise the token is minted at first boot (`adm_` + 32 random bytes,
  *   base64url) into `<DPI_HOME>/admin.token` (or `DPI_ADMIN_TOKEN_FILE`),
- *   owner-only 0600, and logged once.
+ *   owner-only 0600, and its value is logged exactly once — at mint time only;
+ *   every later boot logs just the file path.
  *
  * Presentation:
  * - Browsers: `POST /api/session {token}` sets a stateless cookie `dpi_admin` =
@@ -23,7 +24,8 @@
  * both compared in constant time.
  */
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-import { chmodSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { writePrivateFileAtomic, restrictToOwner } from "../../../../dpi-sdk/src/node/private-file.js";
 import { dirname, join } from "node:path";
 import type { RequestHandler } from "express";
 import { homedir } from "node:os";
@@ -57,9 +59,9 @@ export interface AdminTokenInfo {
  * Resolve the admin token at boot: env override (>= 32 chars or throw), the
  * existing token file, or a freshly minted one written 0600.
  */
-export function bootstrapAdminToken(
+export async function bootstrapAdminToken(
   home = process.env.DPI_HOME ?? join(homedir(), ".dpi"),
-): AdminTokenInfo {
+): Promise<AdminTokenInfo> {
   const path = process.env.DPI_ADMIN_TOKEN_FILE ?? join(home, "admin.token");
   const env = process.env.DPI_ADMIN_TOKEN;
   if (env !== undefined && env !== "") {
@@ -77,22 +79,22 @@ export function bootstrapAdminToken(
     /* first run (or an unreadable file): mint below */
   }
   if (existing) {
-    // The token file must stay 0600 — tighten quietly if a copy restored looser bits
-    // (the same quiet re-tightening Audit applies to the registry file).
-    try {
-      if ((statSync(path).mode & 0o777) !== 0o600) chmodSync(path, 0o600);
-    } catch {
-      /* best effort */
-    }
+    // The token file must stay owner-only — tighten quietly if a copy restored
+    // looser bits (POSIX mode or, on Windows, the owner-only DACL — the same
+    // shared primitive every secret write in the stack uses).
+    void restrictToOwner(path);
     return { token: existing, path, created: false };
   }
   const token = `adm_${randomBytes(32).toString("base64url")}`;
-  // DPI_ADMIN_TOKEN_FILE may name a directory that does not exist yet — create it
-  // owner-only rather than refusing the operator's explicit choice of location.
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  writeFileSync(path, `${token}\n`, { mode: 0o600 });
-  chmodSync(path, 0o600); // a pre-existing (e.g. empty) file may carry wider bits
-  console.log(`first run: created admin token in ${path}`);
+  // Atomic, owner-only mint (DPI_ADMIN_TOKEN_FILE may name a directory that does
+  // not exist yet — the shared writer creates it owner-only rather than refusing
+  // the operator's explicit choice of location).
+  await writePrivateFileAtomic(path, `${token}\n`);
+  // Gap #5: first-login friction — the value appears exactly once, here at
+  // mint time (this line only ever runs on a first boot), so the operator can
+  // log into the web UI without reading a file off the hub machine. Restarts
+  // print only the file path (see the banner in main.ts).
+  console.log(`first run: created admin token: ${token}`);
   return { token, path, created: true };
 }
 

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

@@ -39,6 +39,7 @@ export const AUDIT_ACTIONS = [
   "tunnel.connect",
   "tunnel.disconnect",
   "admin.token_created",
+  "hub.identity_created",
   "admin.login",
   "auth.denied",
   "rate_limited",

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

@@ -22,6 +22,7 @@ import type { Audit } from "./audit.js";
 import { observeIdentity } from "./identity.js";
 import { newTunnelToken } from "./tunnel-token.js";
 import type { TokenIssue } from "../../../../dpi-sdk/src/protocol/pairing.js";
+import type { HubIdentity } from "./hub-identity.js";
 
 export interface IssueInput {
   enrollmentId: string;
@@ -50,6 +51,8 @@ export class CredentialService {
     private readonly hubOrigin: string,
     private readonly hubId: string,
     private readonly failAt?: IssueFailPoint,
+    /** Offer-v3 pinning: stamped into every issued TokenIssue. */
+    private readonly identity?: HubIdentity,
   ) {}
 
   /**
@@ -195,6 +198,7 @@ export class CredentialService {
       tunnelToken: token,
       issuedAt: now,
       expiresAt: null,
+      ...(this.identity ? { hubKeyFingerprint: this.identity.fingerprint } : {}),
     };
   }
 

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

@@ -0,0 +1,98 @@
+/**
+ * Hub identity key (offer v3 pinning, comparison gap #6).
+ *
+ * The hub keeps a persistent Ed25519 keypair in <DPI_HOME>/hub-identity.pem
+ * (owner-only 0600) + hub-identity.pub.pem. Its sha256-of-SPKI fingerprint is
+ * the `kfp` that rides every v3 pairing offer: devices pin it and demand a
+ * proof of possession both at the ceremony (pair.challenge) and on every
+ * tunnel connect (hello), so a hub swap is detectable even with TLS intact.
+ *
+ * First boot mints the key and audits `hub.identity_created` ONCE; later
+ * boots load the same key. Like admin-auth, an unreadable/corrupt file is a
+ * hard failure — a hub that silently re-minted its identity would strand
+ * every pinned device.
+ */
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as edSign,
+} from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { restrictToOwner, writePrivateFileAtomic } from "../../../../dpi-sdk/src/node/private-file.js";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Audit } from "./audit.js";
+
+export interface HubIdentity {
+  /** Ed25519 SPKI PEM — sent to devices in the ceremony/hello proofs. */
+  publicKeyPem: string;
+  /** `sha256:<64 hex>` of the SPKI DER — the value devices pin (offer kfp). */
+  fingerprint: string;
+  /** Ed25519 signature over a canonical payload, base64url. */
+  signPayload: (payload: string) => string;
+}
+
+function fingerprintOf(publicKeyPem: string): string {
+  const der = createPublicKey(publicKeyPem).export({ format: "der", type: "spki" }) as Buffer;
+  return `sha256:${createHash("sha256").update(der).digest("hex")}`;
+}
+
+export async function bootstrapHubIdentity(
+  home: string = process.env.DPI_HOME ?? join(homedir(), ".dpi"),
+  audit?: Audit,
+  hooks: { envFile?: string | undefined; existsSync?: typeof existsSync; now?: () => number } = {},
+): Promise<HubIdentity> {
+  const privPath =
+    hooks.envFile ?? process.env.DPI_HUB_IDENTITY_FILE ?? join(home, "hub-identity.pem");
+  const pubPath = `${privPath}.pub.pem`;
+  const exists = hooks.existsSync ?? existsSync;
+  let privateKeyPem: string;
+  let created = false;
+  if (exists(privPath)) {
+    privateKeyPem = readFileSync(privPath, "utf8");
+    try {
+      createPrivateKey(privateKeyPem); // unreadable/corrupt → hard failure, never re-mint
+    } catch (e) {
+      throw new Error(
+        `hub identity key ${privPath} is unreadable; refusing to boot (a silent re-mint would strand every pinned device): ${(e as Error).message}`,
+      );
+    }
+  } else {
+    const kp = generateKeyPairSync("ed25519");
+    privateKeyPem = kp.privateKey.export({ type: "pkcs8", format: "pem" }) as string;
+    mkdirSync(dirname(privPath), { recursive: true, mode: 0o700 });
+    // The hub's signing key is the highest-value secret on disk: publish it
+    // atomically and owner-only on every platform (Windows DACL included).
+    await writePrivateFileAtomic(privPath, privateKeyPem);
+    writeFileSync(pubPath, kp.publicKey.export({ type: "spki", format: "pem" }) as string, {
+      mode: 0o600,
+    });
+    created = true;
+  }
+  await restrictToOwner(privPath); // 0600 on POSIX, owner-only DACL on Windows
+  const publicKeyPem = createPublicKey(createPrivateKey(privateKeyPem)).export({
+    type: "spki",
+    format: "pem",
+  }) as unknown as string;
+  const identity: HubIdentity = {
+    publicKeyPem,
+    fingerprint: fingerprintOf(publicKeyPem),
+    signPayload: (payload: string) =>
+      edSign(null, Buffer.from(payload), createPrivateKey(privateKeyPem)).toString("base64url"),
+  };
+  if (created)
+    try {
+      audit?.append({
+        actor: "hub",
+        action: "hub.identity_created",
+        outcome: "ok",
+        detail: { fingerprint: identity.fingerprint },
+      });
+    } catch {
+      // GA-02: an audit volume under its free-space floor must not kill hub
+      // boot — the identity file is already durable; the row is best-effort.
+    }
+  return identity;
+}

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

@@ -23,6 +23,7 @@ import {
   signSession,
   tokenEquals,
 } from "./admin-auth.js";
+import { bootstrapHubIdentity } from "./hub-identity.js";
 import { body as failureBody, describeFailure, errorMiddleware, safe } from "./http-errors.js";
 import { TokenBuckets } from "./limiter.js";
 import { PairingService } from "./pairing.js";
@@ -67,7 +68,10 @@ 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 adminToken = await bootstrapAdminToken();
+// Gap #5: later boots point the operator at the file — the value itself only
+// ever appears on the first-boot mint line (admin-auth.ts).
+if (!adminToken.created) console.log(`admin: login with the token in ${adminToken.path}`);
 const configFile = seedFromConfig(registry, appDir);
 const monitor = new DeviceMonitor(registry);
 monitor.start();
@@ -120,6 +124,9 @@ function auditFloorFromEnv(): { minFreeBytes?: number } {
 }
 const audit = new Audit(registry, auditFloorFromEnv());
 audit.startSweeper();
+// Gap #6: the hub's persistent identity key — its fingerprint is the `kfp`
+// pinned inside every v3 pairing offer and proven at ceremony + tunnel connect.
+const identity = await bootstrapHubIdentity(undefined, audit);
 if (adminToken.created)
   audit.append({
     actor: "hub",
@@ -164,12 +171,13 @@ const hubId = (
   registry.db.prepare("SELECT value FROM hub_meta WHERE key='hub_id'").get() as { value: string }
 ).value;
 const hubOrigin = process.env.DPI_HUB_ORIGIN ?? `https://${hostname().toLowerCase()}`;
-const credentials = new CredentialService(registry, audit, hubOrigin, hubId);
+const credentials = new CredentialService(registry, audit, hubOrigin, hubId, undefined, identity);
 const pairing = new PairingService({
   registry,
   audit,
   hubOrigin,
   hubId,
+  identity,
   issue: async (e) => {
     const ticket = await credentials.issue(e);
     tunnel.closeConnection(ticket.deviceId, 1000, "pairing replaced");
@@ -219,6 +227,17 @@ 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);
 });
+/**
+ * Device-INITIATED enrollment (public, same guard stack as pair/start): the
+ * machine asks for a code, so the operator reads its full identity in the list
+ * below instead of carrying a secret between machines.
+ */
+app.post("/api/pair/request", ...pairGuard, express.json({ limit: "16kb" }), (req, res) => {
+  const r = pairing.requestForDevice(req.body, req.ip ?? "unknown");
+  return r.ok ? res.json(r.value) : pairErr(r, res);
+});
+/** Every live request with the identity to approve against (no codes, no key material). */
+app.get("/api/pair/codes", ...adminPairGuard, (_req, res) => res.json({ codes: pairing.listPending() }));
 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);
@@ -451,7 +470,16 @@ app.use(errorMiddleware);
 // Tunnel endpoint (04 §4): /api/tunnel upgrades after hash-first credential
 // auth. In --dev mode Vite owns its own HMR upgrade path, so only the exact
 // tunnel path is claimed here and other upgrades are left alone.
-const tunnel = new TunnelServer(registry, audit, hubId, {}, { requireTls: requireTlsEnabled });
+const tunnel = new TunnelServer(
+  registry,
+  audit,
+  hubId,
+  {},
+  { requireTls: requireTlsEnabled },
+  {},
+  hubOrigin,
+  identity,
+);
 const dispatcher = new TunnelDispatcher(tunnel, { audit, budget: bufferBudget });
 const rotation = new RotationService(registry, audit, tunnel, {
   onChange: () => monitor.refresh(),