my-durable 0.0.6 → 0.0.8

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

@@ -33,6 +33,8 @@ import {
   PAIR_SIGNATURE_FAIL_LIMIT,
   PAIR_POLL_MS,
 } from "../../../../dpi-sdk/src/protocol/limits.js";
+import { hubProofSigningPayload, PairDeviceRequest as PairDeviceRequestSchema } from "../../../../dpi-sdk/src/protocol/pairing.js";
+import type { HubIdentity } from "./hub-identity.js";
 import {
   PairApproval as PairApprovalSchema,
   PairCodeState as PairCodeStateSchema,
@@ -80,6 +82,9 @@ interface Enrollment {
   code: string;
   deviceUid: string;
   deviceName: string;
+  /** Machine description shown to the operator before approval (device-initiated flow). */
+  hostname?: string;
+  platform?: string;
   publicKeyPem: string;
   computedFingerprint: string;
   declaredFingerprint: string;
@@ -109,11 +114,39 @@ interface CodeEntry {
   enrollmentId?: string;
 }
 
+/** One live pairing request as the admin list renders it (no secrets). */
+export interface PendingPairing {
+  codeId: string;
+  expiresAt: number;
+  phase: "awaiting_device" | "awaiting_proof" | "approved_ready" | "cancelled";
+  enrollmentId?: string;
+  deviceUid?: string;
+  deviceName?: string;
+  hostname?: string;
+  platform?: string;
+  keyFingerprint?: string;
+  proofVerified?: boolean;
+  startedAt?: number;
+}
+
+export interface PairDeviceAck {
+  type: "pair.device-ack";
+  v: 1;
+  codeId: string;
+  code: string;
+  expiresAt: number;
+  hubOrigin: string;
+  hubId: string;
+  challenge: unknown;
+}
+
 export interface PairingDeps {
   registry: NetworkRegistry;
   audit: Audit;
   hubOrigin: string;
   hubId: string;
+  /** Offer-v3 pinning: present on every real hub; absent only in legacy harnesses. */
+  identity?: HubIdentity;
   /**
    * Issuance boundary (P2-10 CredentialService). Returns the committed TokenIssue. It must reject with
    * `code: "identity_changed"` when `expectedIdentity` no longer matches the registry (GA-05).
@@ -206,27 +239,30 @@ export class PairingService {
   }
 
   /**
-   * 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.
+   * v3 offer link (v2 without an identity key), minted from the SAME values
+   * the v1 pairUrl uses (same code, same expiry): the whole handoff — hub
+   * origin, hubId, code, expiry, pinned hub-key fingerprint — 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,
-    })}`;
+    const identity = this.deps.identity;
+    return `${this.deps.hubOrigin}/pair#offer=${encodePairOffer(
+      identity
+        ? {
+            v: 3,
+            hub: this.deps.hubOrigin,
+            id: this.deps.hubId,
+            code,
+            exp: expiresAt,
+            kfp: identity.fingerprint,
+          }
+        : { 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 {
+  /** Mint a single-use code entry (shared by the admin and device-initiated flows). */
+  private mintEntry(actor: "admin" | "device"): CodeEntry {
     const now = this.now();
-    const taken = this.createLimiter.take(ipKey(address));
-    if (!taken.ok) return this.rateLimited(taken, "Too many codes; slow down");
-    if (this.codes.size >= PAIR_RAM_CAPS.codes)
-      return this.fail(429, "rate_limited", "Pairing capacity reached; retry later", 60_000);
     let code = "";
     do {
       // A code is a bearer secret authorising one enrollment: canonical UUID v4 = 122 random bits.
@@ -239,15 +275,25 @@ export class PairingService {
       expiresAt: now + CODE_TTL_MS,
       cancelled: false,
     };
-    // Audit row first: a code that cannot be audited must not exist (and must not eat the code capacity).
     this.deps.audit.append({
-      actor: "admin",
+      actor,
       action: "pair.code_created",
       outcome: "ok",
-      detail: { codeId: entry.codeId, expiresAt: entry.expiresAt },
+      detail: { codeId: entry.codeId, expiresAt: entry.expiresAt, ...(actor === "device" ? { initiated: "device" } : {}) },
     });
     this.codes.set(entry.codeId, entry);
     this.byCode.set(code, entry.codeId);
+    return entry;
+  }
+
+  /** POST /api/pair/code (admin) — mint a fresh single-use code. */
+  createCode(address: string): { ok: true; value: PairCodeIssue } | PairingFailure {
+    const taken = this.createLimiter.take(ipKey(address));
+    if (!taken.ok) return this.rateLimited(taken, "Too many codes; slow down");
+    if (this.codes.size >= PAIR_RAM_CAPS.codes)
+      return this.fail(429, "rate_limited", "Pairing capacity reached; retry later", 60_000);
+    const entry = this.mintEntry("admin");
+    const code = entry.code;
     return this.ok({
       type: "pair.code",
       v: 1,
@@ -260,16 +306,92 @@ export class PairingService {
     });
   }
 
+  /**
+   * POST /api/pair/request (public, rate-limited) — DEVICE-INITIATED enrollment.
+   *
+   * The machine that wants to pair asks for a code instead of receiving one, so
+   * the request carries its whole identity (name, hostname, platform, public
+   * key) and the operator reads it in the approval list — the shape orca/paseo
+   * offers have. Nothing gets weaker: the hub mints the same 122-bit single-use
+   * code, parses the key itself, owns the challenge nonce, and the credential is
+   * still issued only by a human approval carrying the hub-computed fingerprint.
+   */
+  requestForDevice(body: unknown, address: string): { ok: true; value: PairDeviceAck } | PairingFailure {
+    const ip = ipKey(address);
+    if (this.failureBlocked(ip))
+      return this.fail(429, "rate_limited", "Too many pairing failures; slow down", 60_000);
+    const taken = this.createLimiter.take(ip);
+    if (!taken.ok) return this.rateLimited(taken, "Too many pairing requests; slow down");
+    if (this.codes.size >= PAIR_RAM_CAPS.codes)
+      return this.fail(429, "rate_limited", "Pairing capacity reached; retry later", 60_000);
+    const request = body as { type?: unknown } | null;
+    if (request?.type !== "pair.device-request" || !checkPairingDto(PairDeviceRequestSchema, request))
+      return this.fail(400, "invalid", "pair.device-request body failed schema validation");
+
+    const entry = this.mintEntry("device");
+    const started = this.start({ ...(request as object), type: "pair.request", v: 1, code: entry.code }, address);
+    if (!started.ok) {
+      // The enrollment never existed: drop the code so a failed request leaves nothing behind.
+      this.codes.delete(entry.codeId);
+      this.byCode.delete(entry.code);
+      return started;
+    }
+    return this.ok({
+      type: "pair.device-ack",
+      v: 1,
+      codeId: entry.codeId,
+      code: entry.code,
+      expiresAt: entry.expiresAt,
+      hubOrigin: this.deps.hubOrigin,
+      hubId: this.deps.hubId,
+      challenge: started.value,
+    });
+  }
+
+  /**
+   * GET /api/pair/codes (admin) — every live code with the machine identity the
+   * operator needs to decide. Deliberately carries NO code, token or key
+   * material: identity + hub-computed fingerprint + phase only.
+   */
+  listPending(): PendingPairing[] {
+    const now = this.now();
+    const out: PendingPairing[] = [];
+    for (const entry of this.codes.values()) {
+      if (entry.cancelled || now >= entry.expiresAt) continue;
+      const enrollment = entry.enrollmentId ? this.enrollments.get(entry.enrollmentId) : undefined;
+      const phase = !enrollment
+        ? "awaiting_device"
+        : enrollment.cancelled
+          ? "cancelled"
+          : enrollment.proofVerified
+            ? "approved_ready"
+            : "awaiting_proof";
+      out.push({
+        codeId: entry.codeId,
+        expiresAt: entry.expiresAt,
+        phase,
+        ...(enrollment
+          ? {
+              enrollmentId: enrollment.enrollmentId,
+              deviceUid: enrollment.deviceUid,
+              deviceName: enrollment.deviceName,
+              ...(enrollment.hostname ? { hostname: enrollment.hostname } : {}),
+              ...(enrollment.platform ? { platform: enrollment.platform } : {}),
+              keyFingerprint: enrollment.computedFingerprint,
+              proofVerified: enrollment.proofVerified,
+              startedAt: enrollment.nonceIssuedAt,
+            }
+          : {}),
+      });
+    }
+    return out;
+  }
+
   /** Admin handoff lookup. Reuses a code; never creates an enrollment or approves it. */
   resolveCode(body: unknown): { ok: true; value: PairCodeIssue } | PairingFailure {
     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 ||
-      !isPairCode(code)
-    )
+    if (!body || typeof body !== "object" || Object.keys(body).length !== 1 || !isPairCode(code))
       return this.fail(400, "code_invalid", "Invalid pairing handoff");
     const codeId = this.byCode.get(code);
     const entry = codeId ? this.codes.get(codeId) : undefined;
@@ -297,6 +419,24 @@ export class PairingService {
     return entry;
   }
 
+  /** Hub-identity proof for a device that pinned kfp (offer v3): sign the canonical payload over the enrollment. */
+  private hubProof(hubNonce: string, enrollmentId: string) {
+    const identity = this.deps.identity;
+    if (!identity) return undefined;
+    return {
+      hubPublicKey: identity.publicKeyPem,
+      hubKeyFingerprint: identity.fingerprint,
+      hubSignature: identity.signPayload(
+        hubProofSigningPayload({
+          hubOrigin: this.deps.hubOrigin,
+          hubId: this.deps.hubId,
+          subject: `pair:${enrollmentId}`,
+          nonce: hubNonce,
+        }),
+      ),
+    };
+  }
+
   /** POST /api/pair/start — issue a challenge bound to one immutable tuple. */
   start(body: unknown, address: string): { ok: true; value: PairChallengeOut } | PairingFailure {
     const now = this.now();
@@ -316,9 +456,12 @@ export class PairingService {
       code: string;
       deviceUid: string;
       deviceName: string;
+      hostname?: string;
+      platform?: string;
       publicKey: string;
       keyFingerprint: string;
       clientTime: number;
+      hubNonce?: string;
     };
     const live = this.liveCode(req.code, now);
     if (live === "invalid") {
@@ -352,6 +495,7 @@ export class PairingService {
         nonce: existing.nonce,
         issuedAt: existing.nonceIssuedAt,
         hubId: this.deps.hubId,
+        ...(req.hubNonce ? this.hubProof(req.hubNonce, existing.enrollmentId) : {}),
       });
     }
 
@@ -388,6 +532,8 @@ export class PairingService {
       code: req.code,
       deviceUid: req.deviceUid,
       deviceName: req.deviceName,
+      ...(req.hostname ? { hostname: req.hostname } : {}),
+      ...(req.platform ? { platform: req.platform } : {}),
       publicKeyPem: req.publicKey,
       computedFingerprint: fingerprint,
       declaredFingerprint: req.keyFingerprint,
@@ -407,6 +553,7 @@ export class PairingService {
       nonce: enrollment.nonce,
       issuedAt: enrollment.nonceIssuedAt,
       hubId: this.deps.hubId,
+      ...(req.hubNonce ? this.hubProof(req.hubNonce, enrollment.enrollmentId) : {}),
     });
   }
 

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

@@ -32,6 +32,8 @@ import {
   type TunnelFrame,
   type TunnelWireMessage,
 } from "../../../../dpi-sdk/src/protocol/tunnel.js";
+import { hubProofSigningPayload } from "../../../../dpi-sdk/src/protocol/pairing.js";
+import type { HubIdentity } from "./hub-identity.js";
 import {
   HANDSHAKE_DEADLINE_MS,
   IDLE_TIMEOUT_MS,
@@ -162,6 +164,9 @@ export class TunnelServer {
     handlers: TunnelHandlers = {},
     policy: Partial<TunnelPolicy> = {},
     hooks: TunnelTestHooks = {},
+    /** Offer-v3 pinning: signs hello proofs for proofNonce-carrying handshakes. */
+    private readonly hubOrigin: string = "",
+    private readonly identity?: HubIdentity,
   ) {
     this.policy = { ...DEFAULT_TUNNEL_POLICY, ...policy };
     if (policy.ipCapacity === undefined)
@@ -753,6 +758,25 @@ export class TunnelServer {
         hubId: this.hubId,
         connectionId: conn.connectionId,
         serverTime: this.now(),
+        // Offer-v3 pinning: a device that sent proofNonce gets the hub identity
+        // proof bound to ITS device+epoch, so a captured proof cannot replay.
+        ...(hs.proofNonce && this.identity && pairing
+          ? (() => {
+              const i = this.identity!;
+              return {
+                hubPublicKey: i.publicKeyPem,
+                hubKeyFingerprint: i.fingerprint,
+                hubSignature: i.signPayload(
+                  hubProofSigningPayload({
+                    hubOrigin: this.hubOrigin,
+                    hubId: this.hubId,
+                    subject: `tunnel:${conn.auth.device_id}:${pairing.pairing_epoch}`,
+                    nonce: hs.proofNonce,
+                  }),
+                ),
+              };
+            })()
+          : {}),
       } satisfies TunnelFrame),
     );
     this.handlers.onOpen?.(this.asConnection(conn));

package/apps/dpi-sdk/src/api.ts

@@ -94,6 +94,8 @@ export interface DeviceInfo {
   startDirs: string[];
   models: ModelInfo[];
   defaultModel: string;
+  /** Provider id of this device ("openrouter" | "faux"); FE model fallback. */
+  provider?: string;
   storage: { dataDir: string; catalogPath: string; appStatePath: string };
   /** The checkout the backend runs from (repo root locally, `code_dir` on deployed devices). */
   codeDir?: string;

package/apps/dpi-sdk/src/node/private-file.ts

@@ -0,0 +1,140 @@
+/**
+ * Private-file hygiene shared by every app (device backend, hub, sdk registry):
+ * atomic writes for credentials and owner-only access on every platform.
+ *
+ * POSIX gets file modes (0600/0700). Windows ignores them, so the same calls
+ * install the hardened DACL Orca uses (`windows-secure-dacl.ts`): protected
+ * from inheritance, full control for SYSTEM, Administrators and the user —
+ * nobody else. `icacls` ships with every Windows box, so no native addon is
+ * needed. Like Orca (and paseo's applyPrivateMode) a restriction failure never
+ * crashes the caller: it reports and returns false so the boot can continue and
+ * a later pass can retry.
+ */
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, renameSync, rmSync, writeSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { basename, dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface RestrictDeps {
+  platform?: NodeJS.Platform;
+  /** Injectable for tests: run a command, resolve stdout or reject. */
+  execFile?: (cmd: string, args: string[]) => Promise<string>;
+}
+
+/** orca's SIDs: SYSTEM and local Administrators can take ownership anyway. */
+const LOCAL_SYSTEM_SID = "S-1-5-18";
+const BUILTIN_ADMINISTRATORS_SID = "S-1-5-32-544";
+
+const execDefault = (cmd: string, args: string[]) =>
+  new Promise<string>((resolve, reject) => {
+    execFile(cmd, args, { timeout: 15_000, windowsHide: true }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(String(stdout ?? ""));
+    });
+  });
+
+/** The current user's SID via `whoami` (locale-proof: extract the S-1-5-* token). */
+async function userSid(deps: RestrictDeps): Promise<string> {
+  const out = await deps.execFile!("whoami", ["/user", "/fo", "csv", "/nh"]);
+  const m = out.match(/S-1-5-[0-9-]+/);
+  if (!m) throw Error(`whoami returned no SID: ${out.trim()}`);
+  return m[0];
+}
+
+/**
+ * Restrict one FILE to its owner. POSIX: chmod 0600 (idempotent). Windows:
+ * strip inheritance, grant SYSTEM + Administrators + the user. Never throws.
+ */
+export async function restrictToOwner(path: string, deps: RestrictDeps = {}): Promise<boolean> {
+  const platform = deps.platform ?? process.platform;
+  const exec = deps.execFile ?? execDefault;
+  if (platform === "win32") {
+    try {
+      const sid = await userSid({ execFile: exec });
+      const grants = [LOCAL_SYSTEM_SID, BUILTIN_ADMINISTRATORS_SID, sid].map(
+        (s) => `*${s}:F`,
+      );
+      await exec("icacls", [path, "/inheritance:r", "/grant:r", ...grants]);
+      return true;
+    } catch (e) {
+      console.error(`private-file: could not restrict ${path} (${(e as Error).message})`);
+      return false;
+    }
+  }
+  try {
+    chmodSync(path, 0o600);
+    return true;
+  } catch (e) {
+    console.error(`private-file: could not restrict ${path} (${(e as Error).message})`);
+    return false;
+  }
+}
+
+/** Restrict a DIRECTORY (children inherit on Windows via (OI)(CI)). Never throws. */
+export async function restrictDirToOwner(path: string, deps: RestrictDeps = {}): Promise<boolean> {
+  const platform = deps.platform ?? process.platform;
+  const exec = deps.execFile ?? execDefault;
+  if (platform === "win32") {
+    try {
+      const sid = await userSid({ execFile: exec });
+      const grants = [LOCAL_SYSTEM_SID, BUILTIN_ADMINISTRATORS_SID, sid].map(
+        (s) => `*${s}:(OI)(CI)F`,
+      );
+      await exec("icacls", [path, "/inheritance:r", "/grant:r", ...grants]);
+      return true;
+    } catch (e) {
+      console.error(`private-file: could not restrict ${path} (${(e as Error).message})`);
+      return false;
+    }
+  }
+  try {
+    chmodSync(path, 0o700);
+    return true;
+  } catch (e) {
+    console.error(`private-file: could not restrict ${path} (${(e as Error).message})`);
+    return false;
+  }
+}
+
+/**
+ * Atomic write for credential files (orca STA-3941 / paseo writePrivateFileAtomicSync):
+ * temp file 0600 + fsync + rename, so readers only ever see the old bytes or the
+ * complete new ones — a crash mid-write can never truncate a token. Then the
+ * owner restriction runs on every platform. Throws only if the disk write
+ * itself fails.
+ */
+export async function writePrivateFileAtomic(
+  path: string,
+  contents: string,
+  deps: RestrictDeps = {},
+): Promise<void> {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}.tmp`);
+  let fd: number | undefined;
+  try {
+    fd = openSync(temp, "w", 0o600);
+    writeSync(fd, Buffer.from(contents, "utf8"));
+    closeSync(fd);
+    fd = undefined;
+    renameSync(temp, path);
+  } catch (e) {
+    if (fd !== undefined) closeSync(fd);
+    rmSync(temp, { force: true });
+    throw e;
+  }
+  // POSIX: fsync the directory so the rename itself is durable (Windows dir
+  // fds cannot be fsynced — EPERM; NTFS journaling carries it there).
+  if ((deps.platform ?? process.platform) !== "win32") {
+    try {
+      const dirFd = openSync(dirname(path), "r");
+      try {
+        fsyncSync(dirFd);
+      } finally {
+        closeSync(dirFd);
+      }
+    } catch {
+      /* best effort, like pairing-files' fsyncReadOnlySupported probe */
+    }
+  }
+  await restrictToOwner(path, deps);
+}

package/apps/dpi-sdk/src/node/registry-migration.ts

@@ -388,7 +388,15 @@ function preflightV0(db: DatabaseSync): void {
   }
 }
 
+/**
+ * Windows cannot fsync read-only or directory handles (FlushFileBuffers needs a write
+ * handle; directory handles cannot be flushed at all — EPERM, errno -4048). POSIX-only
+ * durability steps are skipped there: NTFS journaling plus the atomic rename carry it.
+ */
+export const fsyncReadOnlySupported = process.platform !== "win32";
+
 function syncFile(file: string): void {
+  if (!fsyncReadOnlySupported) return;
   const fd = openSync(file, "r");
   try {
     fsyncSync(fd);
@@ -405,6 +413,7 @@ function syncFile(file: string): void {
  * Exported for a focused unit test — the fsync itself is not observable from JS.
  */
 export function syncDirectory(dir: string): void {
+  if (!fsyncReadOnlySupported) return; // Windows: directory fds cannot be fsynced (EPERM)
   const fd = openSync(dir, "r");
   try {
     if (!fstatSync(fd).isDirectory()) throw new Error(`not a directory: ${dir}`);

package/apps/dpi-sdk/src/node/registry.ts

@@ -1,6 +1,7 @@
 // The client-side device registry: ~/.dpi/network.sqlite. Shared by the playground hub,
 // dpi-tui and scripts/net.ts on this machine. Holds tokens (mode 0600), live status and UI state.
 import { DatabaseSync } from "node:sqlite";
+import { restrictToOwner } from "./private-file.js";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { migrateRegistryFile } from "./registry-migration.js";
@@ -100,6 +101,11 @@ export class NetworkRegistry {
     // migration). Any failure throws — the hub/TUI must not boot on it.
     migrateRegistryFile(path);
     this.db = new DatabaseSync(path);
+    // The registry carries device tokens: sqlite owns the file's creation mode,
+    // so tighten it here — 0600 on POSIX is ensurePrivateDir's job for the
+    // directory; on Windows this installs the owner-only DACL (registry.ts is
+    // shared by the hub, so keep it fire-and-forget and non-fatal).
+    void restrictToOwner(path);
     this.db.exec("PRAGMA journal_mode=WAL; PRAGMA busy_timeout=3000; PRAGMA foreign_keys=ON;");
   }