talon-agent 5.14.0 → 5.18.2

package/src/frontend/native/bridge/auth.ts

@@ -16,7 +16,7 @@ import { randomBytes } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { dirs } from "../../../util/paths.js";
-import { log } from "../../../util/log.js";
+import { log, logWarn } from "../../../util/log.js";
 
 const TOKEN_FILE = "bridge-token";
 /** 32 random bytes → 43 base64url chars; comfortably beyond brute force. */
@@ -50,3 +50,86 @@ export function loadOrCreateBridgeToken(dir: string = dirs.keys): string {
   );
   return token;
 }
+
+// ── Token strength ─────────────────────────────────────────────────────────
+
+/** Below this estimate a configured token is treated as guessable. */
+export const MIN_TOKEN_BITS = 128;
+
+/**
+ * Rough entropy estimate for a configured bridge token: length × bits per
+ * character, where the per-character figure comes from the alphabet the
+ * token visibly uses. It errs low on purpose:
+ *
+ *   - digits only                     → log2(10) ≈ 3.3 bits/char
+ *   - hex                             → 4 bits/char
+ *   - one letter case, nothing else   → log2(26) ≈ 4.7 bits/char
+ *   - base64 / base64url (≥2 classes) → 6 bits/char (padding ignored)
+ *   - anything else (spaces, punctuation — i.e. human-typed) → 3 bits/char
+ *
+ * A token with fewer than 8 distinct characters is capped at log2(distinct)
+ * bits/char, so "aaaa…" can't pass on length alone.
+ *
+ * This is a heuristic for catching `hunter2`-grade secrets, not a
+ * dictionary checker; the real fix is to let Talon generate the token.
+ */
+export function estimateTokenBits(token: string): number {
+  const body = token.replace(/={1,2}$/, "");
+  if (body.length === 0) return 0;
+  const classes = [/[a-z]/, /[A-Z]/, /[0-9]/].filter((re) =>
+    re.test(body),
+  ).length;
+  let perChar: number;
+  if (/^[0-9]+$/.test(body)) perChar = Math.log2(10);
+  else if (/^[0-9a-fA-F]+$/.test(body)) perChar = 4;
+  else if (/^[a-z]+$/.test(body) || /^[A-Z]+$/.test(body))
+    perChar = Math.log2(26);
+  else if (/^[A-Za-z0-9+/_-]+$/.test(body) && classes >= 2) perChar = 6;
+  else perChar = 3;
+  const distinct = new Set(body).size;
+  if (distinct < 8) perChar = Math.min(perChar, Math.log2(distinct));
+  return Math.floor(body.length * perChar);
+}
+
+/**
+ * Startup gate for a configured `native.token`.
+ *
+ * - Strong enough (≥ MIN_TOKEN_BITS), or no token → nothing to say.
+ * - Weak on a loopback bind → warn: nothing off-box can reach it.
+ * - Weak on any other bind → throw, unless the operator opted in with
+ *   `native.allowWeakToken: true`, in which case warn loudly every start.
+ *
+ * Neither the token nor any part of it is ever logged.
+ */
+export function checkBridgeTokenStrength(opts: {
+  token: string | undefined;
+  loopback: boolean;
+  allowWeakToken?: boolean;
+}): void {
+  if (!opts.token) return;
+  const bits = estimateTokenBits(opts.token);
+  if (bits >= MIN_TOKEN_BITS) return;
+  const fix =
+    `Remove native.token so Talon mints a 256-bit token into ${bridgeTokenPath()}, ` +
+    "or replace it with the output of `openssl rand -hex 32`.";
+  const what = `native.token looks weak (~${bits} bits estimated, want ≥ ${MIN_TOKEN_BITS})`;
+  if (opts.loopback) {
+    logWarn(
+      "native",
+      `${what}. The bridge is loopback-only, so continuing. ${fix}`,
+    );
+    return;
+  }
+  if (opts.allowWeakToken) {
+    logWarn(
+      "native",
+      `SECURITY: ${what} on a network-reachable bind, allowed by native.allowWeakToken. ` +
+        `Anyone who can reach this port can try to guess it. ${fix}`,
+    );
+    return;
+  }
+  throw new Error(
+    `Refusing to start the bridge: ${what} on a network-reachable bind. ${fix} ` +
+      "(To accept the risk anyway, set native.allowWeakToken: true.)",
+  );
+}

package/src/frontend/native/bridge/credentials/claims.ts

@@ -0,0 +1,51 @@
+/**
+ * Device-id claims — the spoofing check.
+ *
+ * Mesh requests name a device: `?deviceId=` on /events and /devices/file,
+ * `id` on /devices/register, `deviceId` on /location and
+ * /devices/command-result. A per-device credential may only ever name its
+ * own device; an unbound pairing/installer credential is bound by the first
+ * id it names (and refused one another credential already holds). The
+ * shared token and an open bridge name whatever they like — that is the
+ * legacy trust model — but a remote shared-token claim is recorded so the
+ * operator can see which devices still need upgrading.
+ */
+
+import type { BridgeCredentials, BridgePrincipal } from "./principal.js";
+
+export type ClaimResult =
+  { ok: true; deviceId: string | undefined } | { ok: false; error: string };
+
+export function claimDevice(
+  principal: BridgePrincipal | null,
+  claimed: string | undefined,
+  credentials: BridgeCredentials | undefined,
+): ClaimResult {
+  if (principal === null || principal.kind === "open") {
+    return { ok: true, deviceId: claimed };
+  }
+  if (principal.kind === "shared") {
+    if (claimed && !principal.local && credentials) {
+      credentials.authority.noteLegacy(claimed);
+    }
+    return { ok: true, deviceId: claimed };
+  }
+  const bound = principal.deviceId;
+  if (bound !== null) {
+    return claimed === undefined || claimed === bound
+      ? { ok: true, deviceId: bound }
+      : {
+          ok: false,
+          error: `This credential belongs to device ${bound}; it cannot act as ${claimed}.`,
+        };
+  }
+  if (claimed === undefined) return { ok: true, deviceId: undefined };
+  const bind = credentials?.authority.bind(principal.credentialId, claimed);
+  if (!bind || !bind.ok) {
+    return { ok: false, error: bind?.error ?? "Credential cannot be bound" };
+  }
+  // The rest of this request (and the SSE session it may open) acts as the
+  // device it just became.
+  principal.deviceId = claimed;
+  return { ok: true, deviceId: claimed };
+}

package/src/frontend/native/bridge/credentials/principal.ts

@@ -0,0 +1,200 @@
+/**
+ * Who is calling the bridge, and what they may do.
+ *
+ * A request authenticates as one of:
+ *
+ *   open    no token is configured (loopback-only bind) — every scope,
+ *           exactly as before per-device credentials existed.
+ *   shared  the shared `native.token` — every scope. From a non-local
+ *           client it is the LEGACY path: accepted only while
+ *           `native.legacySharedToken` is on, and every device that uses
+ *           it is offered an in-band upgrade to its own credential.
+ *   device  a per-device credential (core/mesh/credentials): the scopes it
+ *           was granted, bound to one device id.
+ *
+ * Transport-pure like the server: the credential store is reached through
+ * the structural `BridgeCredentialAuthority` slice, injected at startup.
+ */
+
+import type { IncomingMessage } from "node:http";
+import { isDeviceCredentialToken } from "../../../../core/mesh/credentials/index.js";
+import { logWarn } from "../../../../util/log.js";
+
+/**
+ * What a credential may do (see core/mesh/credentials/types.ts):
+ *   device    act as ITSELF on the mesh — register, report, answer its own
+ *             commands, move the files the daemon asked for.
+ *   client    the chat UI — chats, history, sending, non-secret reads.
+ *   operator  config / extension writes, daemon control, logs.
+ * The shared `native.token` and an open loopback bridge hold all three.
+ */
+export type BridgeScope = "device" | "client" | "operator";
+
+/**
+ * A route's tier in routes/table.ts. "public": served without a
+ * credential — every such entry is gated some other way (a single-use
+ * grant minted by the daemon, or for /health by answering only what
+ * pairing needs until a token is presented). A scope: the request's
+ * credential must hold it. A scope list: it must hold at least one.
+ */
+export type BridgeRouteAuth = "public" | BridgeScope | readonly BridgeScope[];
+
+export type BridgePrincipal =
+  | { kind: "open" }
+  | { kind: "shared"; local: boolean }
+  | {
+      kind: "device";
+      credentialId: string;
+      /** Null until an unbound pairing/installer credential names a device. */
+      deviceId: string | null;
+      scopes: readonly BridgeScope[];
+    };
+
+type AuthenticatedCredential = {
+  id: string;
+  deviceId: string | null;
+  scopes: readonly BridgeScope[];
+};
+
+/** The slice of core's DeviceCredentialStore the bridge depends on. */
+type BridgeCredentialAuthority = {
+  authenticate(token: string): AuthenticatedCredential | null;
+  bind(
+    credentialId: string,
+    deviceId: string,
+  ): { ok: true } | { ok: false; error: string };
+  rotationDue(credentialId: string): boolean;
+  noteLegacy(deviceId: string): boolean;
+  onRevoked(listener: (credentialIds: readonly string[]) => void): () => void;
+  mint(input: {
+    deviceId: string | null;
+    scopes: readonly BridgeScope[];
+    origin: "upgrade" | "rotate";
+  }): Promise<{ token: string; credential: AuthenticatedCredential }>;
+};
+
+type BridgeCredentialPolicy = {
+  /** Accept the shared `native.token` from non-local clients. */
+  legacySharedToken: boolean;
+  /** The most a companion may be granted in-band (`native.companionScopes`). */
+  companionScopes: readonly BridgeScope[];
+};
+
+/** Per-device credential support, as injected into the bridge server. */
+export type BridgeCredentials = {
+  authority: BridgeCredentialAuthority;
+  policy: BridgeCredentialPolicy;
+};
+
+const ALL_SCOPES: readonly BridgeScope[] = ["device", "client", "operator"];
+
+function principalScopes(p: BridgePrincipal): readonly BridgeScope[] {
+  return p.kind === "device" ? p.scopes : ALL_SCOPES;
+}
+
+export function hasScope(p: BridgePrincipal, scope: BridgeScope): boolean {
+  return principalScopes(p).includes(scope);
+}
+
+/** Whether `p` clears a route's declared tier. */
+export function routeAllows(
+  tier: BridgeRouteAuth,
+  p: BridgePrincipal,
+): boolean {
+  if (tier === "public") return true;
+  const needed: readonly BridgeScope[] =
+    typeof tier === "string" ? [tier] : tier;
+  return needed.some((scope) => hasScope(p, scope));
+}
+
+/** Human form of a tier for a 403 body: `"operator"` / `"device" or "client"`. */
+export function describeTier(tier: BridgeRouteAuth): string {
+  const scopes = typeof tier === "string" ? [tier] : tier;
+  return scopes.map((s) => `"${s}"`).join(" or ");
+}
+
+/**
+ * Same-machine and not relayed. The shared token is how the local desktop
+ * app and CLI authenticate (they read it from the 0600 discovery file), so
+ * it keeps working for them with legacy mode off. A reverse proxy on the
+ * same host also connects from loopback, so any forwarding header makes the
+ * request remote — a proxied internet client must never pass as local.
+ */
+function isLocalRequest(req: IncomingMessage): boolean {
+  const addr = req.socket.remoteAddress ?? "";
+  const loopback =
+    addr === "127.0.0.1" ||
+    addr === "::1" ||
+    addr === "::ffff:127.0.0.1" ||
+    addr.startsWith("127.");
+  if (!loopback) return false;
+  const h = req.headers;
+  return !(
+    h["x-forwarded-for"] ||
+    h["forwarded"] ||
+    h["x-real-ip"] ||
+    h["x-forwarded-host"]
+  );
+}
+
+/** Addresses already warned about a refused legacy token (bounded). */
+const refusedLegacy = new Set<string>();
+
+/**
+ * Resolve a presented bearer to a principal, or null when it must be
+ * refused. `sharedMatches` is the server's constant-time check against
+ * `native.token`.
+ */
+export function resolvePrincipal(
+  candidate: string,
+  req: IncomingMessage,
+  sharedMatches: (candidate: string) => boolean,
+  credentials: BridgeCredentials | undefined,
+): BridgePrincipal | null {
+  if (credentials && isDeviceCredentialToken(candidate)) {
+    const cred = credentials.authority.authenticate(candidate);
+    return cred
+      ? {
+          kind: "device",
+          credentialId: cred.id,
+          deviceId: cred.deviceId,
+          scopes: cred.scopes,
+        }
+      : null;
+  }
+  if (!sharedMatches(candidate)) return null;
+  const local = isLocalRequest(req);
+  if (!local && credentials && !credentials.policy.legacySharedToken) {
+    const remote = req.socket.remoteAddress ?? "unknown";
+    if (!refusedLegacy.has(remote) && refusedLegacy.size < 256) {
+      refusedLegacy.add(remote);
+      logWarn(
+        "native",
+        `Refused the shared bridge token from ${remote}: native.legacySharedToken is off, so remote clients need a per-device credential (pair the device again).`,
+      );
+    }
+    return null;
+  }
+  return { kind: "shared", local };
+}
+
+/** What `GET /auth/whoami` answers. */
+export function describePrincipal(
+  p: BridgePrincipal,
+  credentials: BridgeCredentials | undefined,
+): Record<string, unknown> {
+  const base = { ok: true, kind: p.kind, scopes: [...principalScopes(p)] };
+  if (p.kind !== "device") {
+    // A shared-token client can trade up to its own credential; clients
+    // that read the token from the local discovery file simply do not.
+    const upgrade = p.kind === "shared" && credentials !== undefined;
+    return upgrade ? { ...base, action: "upgrade" } : base;
+  }
+  const rotate = credentials?.authority.rotationDue(p.credentialId) ?? false;
+  return {
+    ...base,
+    credentialId: p.credentialId,
+    deviceId: p.deviceId,
+    ...(rotate ? { action: "rotate" } : {}),
+  };
+}

package/src/frontend/native/bridge/credentials/upgrade.ts

@@ -0,0 +1,129 @@
+/**
+ * The in-band credential upgrade — `POST /auth/upgrade`.
+ *
+ * Two callers, one endpoint:
+ *
+ *   shared token → a per-device credential bound to the device id in the
+ *     body (the migration path off `native.token`). Scopes are what the
+ *     client asks for, capped by policy: a node gets `device`; a companion
+ *     at most `native.companionScopes` (default device + client). Operator
+ *     is never granted in-band unless the operator put it in that list.
+ *
+ *   per-device credential → a replacement with the same device and scopes
+ *     (rotation, when the operator asked for it or the client wants one).
+ *
+ * The replaced credential stays valid until the new one is first used, so a
+ * reply lost in transit never strands a device; it is revoked on that first
+ * use. The reply carries the only copy of the new token and is `no-store`.
+ */
+
+import { log } from "../../../../util/log.js";
+import { claimDevice } from "./claims.js";
+import type {
+  BridgeCredentials,
+  BridgePrincipal,
+  BridgeScope,
+} from "./principal.js";
+
+export type UpgradeReply = { status: number; body: Record<string, unknown> };
+
+const DEVICE_ID_RE = /^[A-Za-z0-9._:@-]{1,128}$/;
+const SCOPES: readonly BridgeScope[] = ["device", "client", "operator"];
+
+function fail(status: number, error: string): UpgradeReply {
+  return { status, body: { ok: false, error } };
+}
+
+function requestedScopes(value: unknown): BridgeScope[] {
+  if (!Array.isArray(value)) return [];
+  return SCOPES.filter((s) => value.includes(s));
+}
+
+/** What a shared-token client may be granted, given what it asked for. */
+function grantFor(
+  credentials: BridgeCredentials,
+  client: unknown,
+  asked: BridgeScope[],
+): BridgeScope[] {
+  const ceiling: readonly BridgeScope[] =
+    client === "node" ? ["device"] : credentials.policy.companionScopes;
+  if (asked.length === 0) return [...ceiling];
+  return asked.filter((s) => ceiling.includes(s));
+}
+
+export async function upgradeCredential(
+  credentials: BridgeCredentials | undefined,
+  principal: BridgePrincipal,
+  body: Record<string, unknown>,
+  remote: string,
+): Promise<UpgradeReply> {
+  if (!credentials) {
+    return fail(404, "Per-device credentials are not enabled on this bridge");
+  }
+  if (principal.kind === "open") {
+    return fail(
+      409,
+      "This bridge requires no token; there is nothing to upgrade",
+    );
+  }
+  const deviceId =
+    typeof body.deviceId === "string" ? body.deviceId.trim() : "";
+  if (!DEVICE_ID_RE.test(deviceId)) {
+    return fail(400, "deviceId is required (1-128 of A-Z a-z 0-9 . _ : @ -)");
+  }
+  const rotating = principal.kind === "device";
+  if (rotating) {
+    // A credential can only re-issue itself: same device, same scopes.
+    const claim = claimDevice(principal, deviceId, credentials);
+    if (!claim.ok) return fail(403, claim.error);
+  }
+
+  const scopes = rotating
+    ? [...principal.scopes]
+    : grantFor(credentials, body.client, requestedScopes(body.scopes));
+  if (scopes.length === 0) {
+    return fail(403, "None of the requested scopes can be granted in-band");
+  }
+  const minted = await credentials.authority.mint({
+    deviceId,
+    scopes,
+    origin: rotating ? "rotate" : "upgrade",
+  });
+  log(
+    "native",
+    `Issued credential ${minted.credential.id} to device ${deviceId} (${scopes.join(", ")}) — ` +
+      (rotating
+        ? `rotated from ${principal.credentialId}`
+        : `in-band upgrade from the shared token`) +
+      ` via ${remote}`,
+  );
+  return {
+    status: 200,
+    body: {
+      ok: true,
+      token: minted.token,
+      credentialId: minted.credential.id,
+      deviceId,
+      scopes,
+    },
+  };
+}
+
+/**
+ * The `credential` hint on a /devices/register reply — how a heartbeating
+ * device learns it should upgrade or rotate without an extra request.
+ */
+export function credentialHint(
+  credentials: BridgeCredentials | undefined,
+  principal: BridgePrincipal | null,
+): { action: "upgrade" | "rotate" } | undefined {
+  if (!credentials || principal === null) return undefined;
+  if (principal.kind === "shared") return { action: "upgrade" };
+  if (
+    principal.kind === "device" &&
+    credentials.authority.rotationDue(principal.credentialId)
+  ) {
+    return { action: "rotate" };
+  }
+  return undefined;
+}

package/src/frontend/native/bridge/routes/auth.ts

@@ -0,0 +1,37 @@
+import type { RouteHost } from "./host.js";
+import type { BridgeRoutes } from "./table.js";
+import { describePrincipal } from "../credentials/principal.js";
+import { upgradeCredential } from "../credentials/upgrade.js";
+
+export function authRoutes(
+  host: RouteHost,
+): Pick<BridgeRoutes, "GET /auth/whoami" | "POST /auth/upgrade"> {
+  const { json, readJson } = host;
+  return {
+    // ── Credential self-service ────────────────────────────────────────
+
+    // Which credential this is, what it may do, and whether the daemon
+    // wants it upgraded (shared token) or rotated (operator request).
+    "GET /auth/whoami": ({ res, principal }) => {
+      if (!principal)
+        return json(res, 401, { ok: false, error: "Unauthorized" });
+      json(res, 200, describePrincipal(principal, host.credentials));
+    },
+
+    // Trade the shared token (or this credential) for a per-device one.
+    // The reply is the only copy of the new token anywhere.
+    "POST /auth/upgrade": async ({ req, res, principal }) => {
+      if (!principal)
+        return json(res, 401, { ok: false, error: "Unauthorized" });
+      const body = await readJson(req);
+      const reply = await upgradeCredential(
+        host.credentials,
+        principal,
+        body,
+        req.socket.remoteAddress ?? "unknown",
+      );
+      res.setHeader("Cache-Control", "no-store");
+      json(res, reply.status, reply.body);
+    },
+  };
+}

package/src/frontend/native/bridge/routes/chats.ts

@@ -1,5 +1,6 @@
 import type { RouteHost } from "./host.js";
-import type { BridgeRoutes } from "./table.js";
+import { claimDevice } from "../credentials/claims.js";
+import type { BridgeRoutes, RouteContext } from "./table.js";
 import {
   asAttachmentRefs,
   asPositiveInt,
@@ -8,6 +9,23 @@ import {
 } from "./params.js";
 import { log, logWarn } from "../../../../util/log.js";
 
+/**
+ * GET /events. A per-device credential can only name its own device (and
+ * is named by it when it omits the claim) — see credentials/claims.ts.
+ */
+function openEvents(host: RouteHost, ctx: RouteContext): void {
+  const { res, url, principal } = ctx;
+  const claim = claimDevice(principal, deviceIdParam(url), host.credentials);
+  if (!claim.ok || !principal) {
+    host.json(res, 403, {
+      ok: false,
+      error: claim.ok ? "Forbidden" : claim.error,
+    });
+    return;
+  }
+  host.openStream(res, claim.deviceId, principal);
+}
+
 export function chatRoutes(
   host: RouteHost,
 ): Pick<
@@ -33,7 +51,7 @@ export function chatRoutes(
 
     // A mesh client names itself here so device-addressed events reach
     // it alone (see sendToDevice); UI clients simply omit it.
-    "GET /events": ({ res, url }) => host.openStream(res, deviceIdParam(url)),
+    "GET /events": (ctx) => openEvents(host, ctx),
     "GET /chats": ({ res }) => json(res, 200, { chats: h.listChats() }),
     "POST /chats": async ({ req, res }) => {
       const body = await readJson(req);

package/src/frontend/native/bridge/routes/host.ts

@@ -1,6 +1,10 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Readable } from "node:stream";
 import type { AttachmentRef } from "./params.js";
+import type {
+  BridgeCredentials,
+  BridgePrincipal,
+} from "../credentials/principal.js";
 import type {
   BackendOption,
   ClientAttachment,
@@ -170,6 +174,12 @@ export type RouteHost = {
     file: { path: string; size: number },
   ) => void;
   serveMedia: (res: ServerResponse, id: string) => Promise<void>;
-  openStream: (res: ServerResponse, deviceId?: string) => void;
+  openStream: (
+    res: ServerResponse,
+    deviceId: string | undefined,
+    principal: BridgePrincipal,
+  ) => void;
   unknownProvision: (res: ServerResponse) => void;
+  /** Per-device credential support; undefined = shared token only. */
+  credentials: BridgeCredentials | undefined;
 };

package/src/frontend/native/bridge/routes/index.ts

@@ -11,6 +11,7 @@ import { memoryRoutes } from "./memory.js";
 import { modelRoutes } from "./models.js";
 import { daemonRoutes } from "./daemon.js";
 import { meshRoutes } from "./mesh.js";
+import { authRoutes } from "./auth.js";
 
 export function buildRoutes(host: RouteHost): BridgeRoutes {
   return {
@@ -20,5 +21,6 @@ export function buildRoutes(host: RouteHost): BridgeRoutes {
     ...modelRoutes(host),
     ...daemonRoutes(host),
     ...meshRoutes(host),
+    ...authRoutes(host),
   };
 }