acbridge 0.0.1 → 1.0.0

package/plugin/plugins/alexa/scripts/scope.mjs

@@ -0,0 +1,270 @@
+// Shared scope helper for the Alexa voice-bridge hook scripts (signal.mjs + statusline.mjs) — AS-T9f.
+//
+// TWO jobs, both born from AS-T9's "one identity authority" move (the relay credential + hub-token go
+// under SECRET_DIR/users/<segment>/ so the active-user pointer, the credential, and the hub's pinned
+// scope can never name different accounts):
+//
+//   A. SCOPED HUB-TOKEN FALLBACK — resolveHubTokenFile() extends the hooks' hub-token read chain with a
+//      scoped step: env (BRIDGE_HUB_TOKEN_FILE) → handshake.hubTokenFile → users/<seg>/hub-token (from the
+//      active-user pointer) → machine-global SECRET_DIR/hub-token. At layout <3 there are no users/<seg>/
+//      dirs, so the scoped step finds nothing and falls to machine-global — byte-identical to today.
+//
+//   B. ACCOUNT-STAMPED PLAIN-SESSION HANDSHAKE (the owner-approved restore) — a plain `claude` (no
+//      --channels) has NO handshake file, so AS-T8b's adoption gate classifies its session-state POSTs as
+//      "absent" under a pinned hub and DROPS them → auto-profiles stopped firing. writePlainSessionHandshake
+//      IfAbsent() re-attributes such a session to the SIGNED-IN account by writing a stamped handshake the
+//      hub adopts (sub === pinned scope). No signed-in account ⇒ nothing is written (an unattributable
+//      session must never be adopted). It NEVER overwrites an `acbridge run` / channel file (those own their
+//      own identity + cleanup); its `selfWritten:true` marker also lets gate.mjs keep dev-freedom (a plain
+//      session is not voice-reachable — no Alexa `reply` egress).
+//
+// LEAF DISCIPLINE: like the scripts that import it, this file is shipped in the plugin and runs OUTSIDE the
+// monorepo, so it imports ONLY node builtins — never @bridge/* (which won't resolve in Claude's plugin
+// cache). userScopeSegment REPLICATES @bridge/node-core's (credential-paths.ts); the node-core drift
+// cross-check test pins the two in agreement so this copy can't silently diverge.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// ── sub → segment — a VERBATIM replica of @bridge/node-core credential-paths.ts userScopeSegment ────────
+// A WorkOS `sub` is normally short + URL-safe (`user_01H...`) but it's still external input: verbatim only
+// when it matches this safe, bounded charset (and has no interior `..`, which the path guard forbids), else
+// a deterministic content hash so an anomalous sub can never escape users/ or collide across accounts.
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/;
+
+export function userScopeSegment(sub) {
+  if (SAFE_SEGMENT.test(sub) && !sub.includes("..")) return sub;
+  return `h_${createHash("sha256").update(sub, "utf8").digest("hex").slice(0, 24)}`;
+}
+
+// ── active-user pointer (sub only) ─────────────────────────────────────────────────────────────────────
+/** The active-user pointer's `sub`, or null — absent/corrupt/sub-less all degrade to null, never a throw. */
+export function readActiveUserSub(secretDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(path.join(secretDir, "active-user.json"), "utf8"));
+    return parsed && typeof parsed.sub === "string" && parsed.sub ? parsed.sub : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── Part A: the scoped hub-token step + the full fallback resolver ──────────────────────────────────────
+/** The account's scoped hub-token file IF the pointer selects one AND it exists on disk, else null. Its
+ *  mere-existence gate is what makes layout <3 (no users/<seg>/ dir) fall straight through to machine-global,
+ *  matching cli/node-process.ts resolveHubTokenPath's layout<3 → HUB_TOKEN_FILE behavior. */
+export function scopedHubTokenFile(secretDir) {
+  const sub = readActiveUserSub(secretDir);
+  if (!sub) return null;
+  const p = path.join(secretDir, "users", userScopeSegment(sub), "hub-token");
+  return existsSync(p) ? p : null;
+}
+
+/** The hub-token path a hook should read. `explicit` (the env var or the handshake file's hubTokenFile
+ *  field) is authoritative when present; otherwise scoped-first, then the machine-global fallback. */
+export function resolveHubTokenFile(secretDir, explicit) {
+  if (explicit) return explicit;
+  return scopedHubTokenFile(secretDir) ?? path.join(secretDir, "hub-token");
+}
+
+// ── Part B: the account-stamped plain-session handshake self-write + its clean-exit cleanup ─────────────
+/**
+ * Atomically write `sessions/<claudeSessionId>.json` stamped for the signed-in account, so the hub's
+ * adoption gate (resolveHandshakeSub → classifyHandshakeAdoption) accepts a plain session's signals when
+ * its `sub` matches the pinned scope. Returns the written path, or null when it wrote nothing:
+ *   - no `claudeSessionId` → no adoption key (the hub joins the POST's claudeSessionId to this file's name);
+ *   - no `sub` → an unattributable session must NEVER be adopted (the standing account-isolation rule);
+ *   - an EXISTING file → an `acbridge run` / channel voice writer already owns this session's identity +
+ *     its cleanup; never clobber it (that would also strip the file's voice-ness from gate.mjs's view).
+ * The shape matches the canonical writers (cli run.ts buildHandshakeRecord / channel handshake.ts) PLUS a
+ * `selfWritten:true` marker. Best-effort — an unwritable sessions dir degrades to "no handshake" (dormant,
+ * exactly the pre-restore behavior), never a throw (a hook must never block Claude).
+ */
+export function writePlainSessionHandshakeIfAbsent({ secretDir, id, hubPort, hubTokenFile, cwd, claudeSessionId, sub }) {
+  if (!claudeSessionId || !sub) return null;
+  const file = path.join(secretDir, "sessions", `${claudeSessionId}.json`);
+  if (existsSync(file)) return null;
+  const record = {
+    id,
+    sub,
+    hubTokenFile,
+    hubPort,
+    ...(cwd ? { cwd } : {}),
+    claudeSessionId,
+    selfWritten: true,
+  };
+  try {
+    mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+    renameSync(tmp, file);
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+/** Clean-exit cleanup: remove a plain-session handshake THIS hook wrote (selfWritten only — a voice
+ *  writer's file is left for the channel / `acbridge run` to clean). Best-effort; a crash that skips
+ *  SessionEnd leaves a harmless stale file (its claudeSessionId — a UUID — never recurs, so it can't be
+ *  re-adopted; a future sessions-dir sweep can reap the accumulation). */
+export function cleanupPlainSessionHandshake(secretDir, claudeSessionId) {
+  if (!claudeSessionId) return false;
+  const file = path.join(secretDir, "sessions", `${claudeSessionId}.json`);
+  try {
+    const h = JSON.parse(readFileSync(file, "utf8"));
+    if (!h || h.selfWritten !== true) return false;
+    rmSync(file, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Part C: WHICH `.claude-bridge` home holds the live hub ───────────────────────────────────────────
+// A VERBATIM behavioural replica of @bridge/node-core's bridge-home.ts (leaf discipline again: a shipped
+// plugin script cannot import the workspace). node-core/test/bridge-home-drift.test.ts is the ONE place
+// both run under a single runtime, and it pins them scenario-for-scenario.
+//
+// Why any of this exists: with WSL mirrored networking the hooks' POST to 127.0.0.1:8790 reaches a hub
+// running on WINDOWS, while every piece of state they resolve (hub-token, active-user.json, sessions/)
+// comes from the WSL home the Windows hub has never heard of. Live on 2026-07-24 that produced a 401 on
+// every signal, and — once the token was right — an account-scope "absent" drop, because the handshake
+// was written on the wrong side of the boundary. Both failures are silent (hooks exit 0 by contract), so
+// "my lights stopped working" had no evidence anywhere.
+
+/** The hub's liveness beacon, written in its own home at boot and removed on a clean exit. */
+export const HUB_BEACON_BASENAME = "hub-endpoint.json";
+/** Bound on peer probing: a Windows box with hundreds of profiles must never turn a hook into a 9P crawl. */
+const PEER_PROBE_CAP = 24;
+const SYSTEM_PROFILES = new Set(["public", "default", "default user", "all users", "defaultapppool", "administrator"]);
+
+function parseBeacon(raw) {
+  if (!raw) return null;
+  try {
+    const j = JSON.parse(raw);
+    if (typeof j?.pid !== "number" || typeof j?.port !== "number") return null;
+    return {
+      pid: j.pid,
+      port: j.port,
+      startedAt: typeof j.startedAt === "number" ? j.startedAt : 0,
+      ...(typeof j.sub === "string" && j.sub ? { sub: j.sub } : {}),
+    };
+  } catch {
+    return null; // corrupt/partial write → no beacon, never a throw
+  }
+}
+
+/** `/etc/wsl.conf`'s `[automount] root` (default `/mnt`) — a WSL user can move the Windows drives. */
+function automountRoot(deps) {
+  const conf = deps.readFile("/etc/wsl.conf");
+  const m = conf?.match(/^\s*root\s*=\s*(\S+)\s*$/m);
+  const root = m?.[1] ?? "/mnt";
+  return root.length > 1 && root.endsWith("/") ? root.slice(0, -1) : root;
+}
+
+function peerCandidates(deps) {
+  const out = [];
+  const push = (p) => {
+    if (out.length < PEER_PROBE_CAP && !out.includes(p)) out.push(p);
+  };
+  const usable = (name) => !SYSTEM_PROFILES.has(name.toLowerCase());
+
+  if (deps.isWsl) {
+    const root = automountRoot(deps);
+    for (const drive of deps.listDir(root).filter((d) => /^[a-zA-Z]$/.test(d))) {
+      const users = `${root}/${drive}/Users`;
+      if (usable(deps.userName)) push(`${users}/${deps.userName}/.claude-bridge`);
+      for (const name of deps.listDir(users)) if (usable(name)) push(`${users}/${name}/.claude-bridge`);
+    }
+    return out;
+  }
+
+  if (deps.platform === "win32") {
+    for (const root of ["\\\\wsl.localhost", "\\\\wsl$"]) {
+      for (const distro of deps.listDir(`${root}\\`)) {
+        const homes = `${root}\\${distro}\\home`;
+        push(`${homes}\\${deps.userName}\\.claude-bridge`);
+        for (const name of deps.listDir(homes)) push(`${homes}\\${name}\\.claude-bridge`);
+      }
+    }
+  }
+  return out;
+}
+
+/** The pure resolver — same contract as node-core's: env → live local → live peer → local fallback. */
+export function resolveBridgeHomeWith(deps) {
+  const beaconIn = (dir) =>
+    parseBeacon(
+      deps.readFile(
+        dir.endsWith("\\") || dir.endsWith("/")
+          ? `${dir}${HUB_BEACON_BASENAME}`
+          : `${dir}${deps.platform === "win32" ? "\\" : "/"}${HUB_BEACON_BASENAME}`,
+      ),
+    );
+
+  const explicit = deps.env["BRIDGE_SECRET_DIR"];
+  if (explicit) return { dir: explicit, source: "env", beacon: beaconIn(explicit) };
+
+  const local = beaconIn(deps.secretDir);
+  if (local && deps.pidAlive(local.pid)) return { dir: deps.secretDir, source: "local", beacon: local };
+
+  let best = null;
+  for (const dir of peerCandidates(deps)) {
+    const b = beaconIn(dir);
+    if (b && (!best || b.startedAt > best.beacon.startedAt)) best = { dir, beacon: b };
+  }
+  if (best) return { dir: best.dir, source: deps.isWsl ? "peer-wsl" : "peer-windows", beacon: best.beacon };
+
+  return { dir: deps.secretDir, source: "local", beacon: null };
+}
+
+/** Are we inside WSL? Env markers first (set by every modern WSL), /proc/version as the fallback. */
+function detectWslSync(env, platform, readFile) {
+  if (platform !== "linux") return false;
+  if (env["WSL_DISTRO_NAME"] || env["WSL_INTEROP"]) return true;
+  return /microsoft/i.test(readFile("/proc/version") ?? "");
+}
+
+/** The real resolution for this hook run. Cheap by construction: a peer is probed ONLY when no hub is
+ *  alive in the local home, and then at most PEER_PROBE_CAP small reads. */
+export function resolveBridgeHome() {
+  const readFile = (f) => {
+    try {
+      return readFileSync(f, "utf8").trim() || null;
+    } catch {
+      return null;
+    }
+  };
+  const listDir = (dir) => {
+    try {
+      return readdirSync(dir);
+    } catch {
+      return [];
+    }
+  };
+  let userName = "";
+  try {
+    userName = os.userInfo().username;
+  } catch {
+    userName = process.env.USER || process.env.USERNAME || "";
+  }
+  return resolveBridgeHomeWith({
+    secretDir: path.join(os.homedir(), ".claude-bridge"),
+    env: process.env,
+    platform: process.platform,
+    userName,
+    isWsl: detectWslSync(process.env, process.platform, readFile),
+    pidAlive: (pid) => {
+      try {
+        process.kill(pid, 0);
+        return true;
+      } catch (e) {
+        return e?.code === "EPERM"; // alive, just not ours to signal
+      }
+    },
+    readFile,
+    listDir,
+  });
+}