@monster-orange/den 0.4.20 → 0.4.22

package/service/install.sh

@@ -1,24 +1,42 @@
 #!/usr/bin/env bash
-# Run the web UI as a long-lived macOS service (a launchd LaunchAgent):
-# started at login, restarted if it exits, not tied to any terminal.
+# Run the web UI and the session host as long-lived macOS launchd jobs:
+# started at boot or login, restarted if they exit, not tied to a terminal.
 #
-#   service/install.sh            install (or refresh) and start it
-#   service/install.sh uninstall  stop it and remove the LaunchAgent
-#   service/install.sh status     launchd's view of it
-#   service/install.sh print      write the LaunchAgent plist to stdout only
+#   service/install.sh            install (or refresh) and start them
+#   service/install.sh uninstall  stop them and remove their plists
+#   service/install.sh status     launchd's view of them
+#   service/install.sh print      write the web plist to stdout only
+#   service/install.sh print-host write the session host plist to stdout only
+#
+# Two modes (D18), DEN_SERVICE_MODE:
+#   login   (default) LaunchAgents in the desktop session (gui/<uid>): they
+#           start at login and stop at logout, with every agent.
+#   always  LaunchDaemons that run as you (UserName): they start at boot and
+#           keep running across logout, so agents do too. One sudo writes
+#           and loads them. No login keychain, no GUI there: agents use the
+#           1Password service-account token, headless browsers, and Full
+#           Disk Access for protected folders.
+#
+# The session host job runs DEN_SERVICE_HOST_EXE, a copy of node Den owns
+# (<stateDir>/bin/<cli>-sessions-host): Full Disk Access is granted to that
+# path, so it never goes to the shared node. A node change replaces the
+# copy; the grant holds when the code signature's requirement is the same
+# (an official node build), and install says to grant it again when not.
 #
 # Works from Den's checkout and from a distribution, where it lives in
 # node_modules/@monster-orange/den/service/. The distribution root is
-# DEN_ROOT, else this checkout when it holds den.yml. The agent runs the
-# engine's server with the node found on PATH now, from the distribution
-# root; re-run install after changing node versions.
+# DEN_ROOT, else this checkout when it holds den.yml.
 #
-#   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
-#   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
-#   DEN_SERVICE_NODE   the node the agent runs (default: see pick_node)
+#   DEN_SERVICE_LABEL       web job label (default local.<dist dir name>.web)
+#   DEN_SERVICE_HOST_LABEL  host job label (default: the web label's .web → .sessions)
+#   DEN_SERVICE_LOGS        log directory (default ~/Library/Logs/<dist dir name>)
+#   DEN_SERVICE_NODE        the node the jobs run (default: see pick_node)
+#   DEN_SERVICE_HOST_EXE    the host's node copy (default: none, the host runs that node)
 #   DEN_SERVICE_READY_CHECK=external  install does not print "running": the
 #                      caller (`<cli> service install`) checks the server
 #                      answers first.
+#   DEN_SERVICE_DAEMON_DIR, DEN_SERVICE_SUDO  (tests) where LaunchDaemons go
+#                      and what runs as root (default /Library/LaunchDaemons, sudo)
 set -euo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
@@ -34,9 +52,31 @@ fi
 [ -f "$DIST/den.yml" ] || { echo "✗ $DIST has no den.yml" >&2; exit 1; }
 NAME="$(basename "$DIST")"
 LABEL="${DEN_SERVICE_LABEL:-local.$NAME.web}"
+HOST_LABEL="${DEN_SERVICE_HOST_LABEL:-${LABEL%.web}.sessions}"
 LOGS="${DEN_SERVICE_LOGS:-$HOME/Library/Logs/$NAME}"
-PLIST="$HOME/Library/LaunchAgents/$LABEL.plist"
-DOMAIN="gui/$(id -u)"
+SVC_MODE="${DEN_SERVICE_MODE:-login}"
+case "$SVC_MODE" in
+  login|always) ;;
+  *) echo "✗ DEN_SERVICE_MODE must be login or always, not \"$SVC_MODE\"" >&2; exit 2 ;;
+esac
+UID_N="$(id -u)"
+USER_N="$(id -un)"
+AGENT_DIR="$HOME/Library/LaunchAgents"
+DAEMON_DIR="${DEN_SERVICE_DAEMON_DIR:-/Library/LaunchDaemons}"
+SUDO="${DEN_SERVICE_SUDO-sudo}"
+GUI="gui/$UID_N"
+
+# The plist and domain for a label in a mode.
+plist_for() { # $1 label $2 mode
+  if [ "$2" = always ]; then echo "$DAEMON_DIR/$1.plist"; else echo "$AGENT_DIR/$1.plist"; fi
+}
+domain_for() { if [ "$1" = always ]; then echo system; else echo "$GUI"; fi; }
+other_mode() { if [ "$1" = always ]; then echo login; else echo always; fi; }
+# Root runs it in the system domain (a LaunchDaemon); else as you.
+as_mode() { # $1 mode, then the command
+  local m="$1"; shift
+  if [ "$m" = always ] && [ -n "$SUDO" ]; then "$SUDO" "$@"; else "$@"; fi
+}
 
 # tsx: the nearest node_modules/tsx at or above the engine (hoisted installs).
 find_tsx() {
@@ -76,20 +116,75 @@ pick_node() {
   echo "$node"
 }
 
-write_plist() { # $1 = output file
+# The code signature's designated requirement, or "" (unsigned, no codesign).
+requirement() { codesign -d -r- "$1" 2>&1 | sed -n 's/^designated => //p' || true; }
+
+# The host's node copy (D18): refreshed when node changed. Prints the path
+# the host job runs: the copy, or node itself when it cannot be copied.
+# A node linked to libraries beside it (Homebrew's) does not run copied.
+self_contained() {
+  ! { command -v otool >/dev/null 2>&1 && otool -L "$1" 2>/dev/null | grep -q '@rpath/\|/opt/homebrew/\|/usr/local/opt/'; }
+}
+
+host_exe() { # $1 node
+  local node="$1" exe="${DEN_SERVICE_HOST_EXE:-}" c src=""
+  if [ -z "$exe" ]; then echo "$node"; return; fi
+  # The node the jobs run, else (unless DEN_SERVICE_NODE names one) the
+  # PATH's: a version manager's is fine here, since the copy outlives it.
+  for c in "$node" $([ -z "${DEN_SERVICE_NODE:-}" ] && command -v node 2>/dev/null); do
+    if self_contained "$c"; then src="$c"; break; fi
+  done
+  if [ -z "$src" ]; then
+    echo "⚠ $node is not self-contained (it loads libraries beside it), so the session host" >&2
+    echo "  runs it directly: grant Full Disk Access to $node, and again after each node" >&2
+    echo "  upgrade. An official node build (nodejs.org, nvm) avoids that: set DEN_SERVICE_NODE." >&2
+    echo "$node"; return
+  fi
+  node="$src"
+  if [ -f "$exe" ] && cmp -s "$node" "$exe"; then echo "$exe"; return; fi
+  local before="" after
+  [ -f "$exe" ] && before="$(requirement "$exe")"
+  mkdir -p "$(dirname "$exe")"
+  chmod 700 "$(dirname "$exe")"
+  cp "$node" "$exe.new"
+  chmod 700 "$exe.new"
+  mv -f "$exe.new" "$exe"
+  after="$(requirement "$exe")"
+  case "$after" in
+    "" | cdhash*)
+      echo "⚠ $exe is a copy of $node, which has no stable code signature: Full Disk" >&2
+      echo "  Access must be granted to it again after every node change. An official" >&2
+      echo "  node build (nodejs.org, nvm) keeps the grant: set DEN_SERVICE_NODE." >&2 ;;
+    *)
+      if [ -n "$before" ] && [ "$before" != "$after" ]; then
+        echo "⚠ $exe changed signer: grant it Full Disk Access again" >&2
+        echo "  (System Settings → Privacy & Security → Full Disk Access)." >&2
+      fi ;;
+  esac
+  echo "$exe"
+}
+
+write_plist() { # $1 = output file, $2 = web|host, $3 = mode
   NODE="$(pick_node "$MODE")"
   TSX="$(find_tsx)" || { echo "✗ tsx not installed: run npm ci in $DIST" >&2; exit 1; }
+  local exe="$NODE" label="$LABEL" log="web.log"
+  if [ "$2" = host ]; then
+    if [ "$MODE" = install ]; then exe="$(host_exe "$NODE")"; else exe="${DEN_SERVICE_HOST_EXE:-$NODE}"; fi
+    label="$HOST_LABEL"; log="sessions-host.log"
+  fi
   DOCKER_DIR="$(dirname "$(command -v docker || echo /usr/local/bin/docker)")"
   SVC_PATH="$(dirname "$NODE"):$DOCKER_DIR:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-  python3 -I - "$1" "$LABEL" "$NODE" "$TSX" "$ENGINE" "$DIST" "$SVC_PATH" "$HOME" "$LOGS" <<'PY'
+  python3 -I - "$1" "$2" "$3" "$label" "$exe" "$TSX" "$ENGINE" "$DIST" "$SVC_PATH" "$HOME" "$LOGS/$log" "$USER_N" <<'PY'
 import plistlib, sys
-out, label, node, tsx, engine, dist, path, home, logs = sys.argv[1:]
+out, kind, mode, label, exe, tsx, engine, dist, path, home, log, user = sys.argv[1:]
+entry = (f"{engine}/src/ui/server/index.ts", "--silent") if kind == "web" \
+    else (f"{engine}/src/ui/cli/index.ts", "sessions", "host", "--stand-by")
 data = {
     "Label": label,
-    "ProgramArguments": [node, "--import", f"{tsx}/dist/loader.mjs",
-                         f"{engine}/src/ui/server/index.ts", "--silent"],
+    "ProgramArguments": [exe, "--import", f"{tsx}/dist/loader.mjs", *entry],
     "WorkingDirectory": dist,
-    "EnvironmentVariables": {"PATH": path, "HOME": home,
+    "EnvironmentVariables": {"PATH": path, "HOME": home, "USER": user,
+                             "LOGNAME": user,
                              "DEN_ROOT": dist, "DEN_ENGINE_ROOT": engine},
     "RunAtLoad": True,
     "KeepAlive": True,
@@ -97,9 +192,12 @@ data = {
     # Interactive, not Background: macOS gives Background agents efficiency
     # cores and throttled I/O, and the UI stalled for seconds under load.
     "ProcessType": "Interactive",
-    "StandardOutPath": f"{logs}/web.log",
-    "StandardErrorPath": f"{logs}/web.log",
+    "StandardOutPath": log,
+    "StandardErrorPath": log,
 }
+if mode == "always":
+    # A LaunchDaemon runs as root unless told otherwise: run as the person.
+    data["UserName"] = user
 if out == "-":
     sys.stdout.buffer.write(plistlib.dumps(data))
 else:
@@ -108,58 +206,110 @@ else:
 PY
 }
 
+# Stop and remove a job (any mode), quietly when it is not there.
+remove_job() { # $1 label $2 mode
+  local plist; plist="$(plist_for "$1" "$2")"
+  if [ "$2" = always ]; then
+    [ -f "$plist" ] || return 0
+  fi
+  as_mode "$2" launchctl bootout "$(domain_for "$2")/$1" 2>/dev/null || true
+  [ -f "$plist" ] && as_mode "$2" rm -f "$plist"
+  return 0
+}
+
+# Install and start one job in SVC_MODE.
+load_job() { # $1 label $2 web|host
+  local label="$1" plist domain tmp
+  plist="$(plist_for "$label" "$SVC_MODE")"
+  domain="$(domain_for "$SVC_MODE")"
+  tmp="$(mktemp "${TMPDIR:-/tmp}/den-plist.XXXXXX")"
+  write_plist "$tmp" "$2" "$SVC_MODE"
+  plutil -lint "$tmp" >/dev/null
+  # The other mode's job is the same service: never both.
+  remove_job "$label" "$(other_mode "$SVC_MODE")"
+  as_mode "$SVC_MODE" launchctl bootout "$domain/$label" 2>/dev/null || true
+  # bootout returns before launchd has let go of the label; a bootstrap
+  # straight after fails ("Bootstrap failed: 5") and leaves NO service.
+  # Wait for it to go, then retry bootstrap a few times.
+  for _ in $(seq 1 50); do
+    as_mode "$SVC_MODE" launchctl print "$domain/$label" >/dev/null 2>&1 || break
+    sleep 0.2
+  done
+  if [ "$SVC_MODE" = always ]; then
+    as_mode always install -o root -g wheel -m 644 "$tmp" "$plist"
+    rm -f "$tmp"
+  else
+    mkdir -p "$(dirname "$plist")"
+    mv "$tmp" "$plist"
+  fi
+  local loaded=0
+  for _ in 1 2 3 4 5; do
+    if as_mode "$SVC_MODE" launchctl bootstrap "$domain" "$plist" 2>/dev/null; then loaded=1; break; fi
+    sleep 1
+  done
+  [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $label (plist: $plist)" >&2; exit 1; }
+  as_mode "$SVC_MODE" launchctl kickstart -k "$domain/$label"
+}
+
+# The job's state, as status shows it.
+job_status() { # $1 label
+  local m plist domain svc_node out
+  for m in always login; do
+    plist="$(plist_for "$1" "$m")"
+    [ -f "$plist" ] || continue
+    domain="$(domain_for "$m")"
+    # The node it was installed with may be gone (a removed nvm version):
+    # launchd then restarts it forever with no useful message.
+    if command -v plutil >/dev/null 2>&1; then
+      svc_node="$(plutil -extract ProgramArguments.0 raw -o - "$plist" 2>/dev/null || true)"
+      if [ -n "$svc_node" ] && [ ! -x "$svc_node" ]; then
+        echo "✗ $1 runs $svc_node, which no longer exists: re-run service install" >&2
+        return 1
+      fi
+    fi
+    echo "$1 ($m: $domain)"
+    if out="$(launchctl print "$domain/$1" 2>/dev/null)"; then
+      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs|spawn type)'
+    else
+      echo "  plist present, job not loaded: $([ "$m" = always ] && echo "sudo ")launchctl bootstrap $domain $plist"
+    fi
+    return 0
+  done
+  # launchctl's own "Could not find service" is noise when it isn't loaded.
+  echo "$1 is not loaded"
+}
+
 MODE="${1:-install}"
 case "$MODE" in
   install)
-    mkdir -p "$LOGS" "$(dirname "$PLIST")"
-    write_plist "$PLIST.new"
-    plutil -lint "$PLIST.new" >/dev/null
-    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
-    # bootout returns before launchd has let go of the label; a bootstrap
-    # straight after fails ("Bootstrap failed: 5") and leaves NO service.
-    # Wait for it to go, then retry bootstrap a few times.
-    for _ in $(seq 1 50); do
-      launchctl print "$DOMAIN/$LABEL" >/dev/null 2>&1 || break
-      sleep 0.2
-    done
-    mv "$PLIST.new" "$PLIST"
-    loaded=0
-    for _ in 1 2 3 4 5; do
-      if launchctl bootstrap "$DOMAIN" "$PLIST" 2>/dev/null; then loaded=1; break; fi
-      sleep 1
-    done
-    [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $LABEL (plist: $PLIST)" >&2; exit 1; }
-    launchctl kickstart -k "$DOMAIN/$LABEL"
+    mkdir -p "$LOGS"
+    if [ "$SVC_MODE" = always ] && [ -n "$SUDO" ]; then
+      echo "… $SVC_MODE: LaunchDaemons running as $USER_N need your admin password once (sudo)"
+    fi
+    load_job "$HOST_LABEL" host
+    load_job "$LABEL" web
     if [ "${DEN_SERVICE_READY_CHECK:-}" = external ]; then
-      echo "… $LABEL started; waiting for it to answer"
+      echo "… $LABEL started ($SVC_MODE); waiting for it to answer"
     else
-      echo "✓ $LABEL running (logs: $LOGS/web.log)"
+      echo "✓ $LABEL running ($SVC_MODE; logs: $LOGS/web.log)"
     fi
     ;;
   uninstall)
-    launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
-    rm -f "$PLIST"
-    echo "✓ $LABEL removed"
+    for m in login always; do
+      remove_job "$LABEL" "$m"
+      remove_job "$HOST_LABEL" "$m"
+    done
+    echo "✓ $LABEL and $HOST_LABEL removed"
     ;;
   print)
-    write_plist -
+    write_plist - web "$SVC_MODE"
+    ;;
+  print-host)
+    write_plist - host "$SVC_MODE"
     ;;
   status)
-    # The node the agent was installed with may be gone (a removed nvm
-    # version): launchd then restarts it forever with no useful message.
-    if [ -f "$PLIST" ] && command -v plutil >/dev/null 2>&1; then
-      svc_node="$(plutil -extract ProgramArguments.0 raw -o - "$PLIST" 2>/dev/null || true)"
-      if [ -n "$svc_node" ] && [ ! -x "$svc_node" ]; then
-        echo "✗ $LABEL runs $svc_node, which no longer exists: re-run service install" >&2
-        exit 1
-      fi
-    fi
-    # launchctl's own "Could not find service" is noise when it isn't loaded.
-    if out="$(launchctl print "$DOMAIN/$LABEL" 2>/dev/null)"; then
-      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs|spawn type)'
-    else
-      echo "$LABEL is not loaded"
-    fi
+    job_status "$LABEL"
+    job_status "$HOST_LABEL"
     ;;
-  *) echo "usage: $0 [install|uninstall|status|print]" >&2; exit 2 ;;
+  *) echo "usage: $0 [install|uninstall|status|print|print-host]" >&2; exit 2 ;;
 esac

package/src/shared/agents/den-claude.ts

@@ -455,6 +455,11 @@ export function firstPromptArg(text: string | undefined): string[] {
   return [t.startsWith("-") ? `Prompt: ${t}` : t];
 }
 
+/** D24: `--name <label>`, so peers tell Den's agents apart; or nothing. */
+function nameArg(label: string | undefined): string[] {
+  return label ? ["--name", label] : [];
+}
+
 const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 
 /**
@@ -503,6 +508,7 @@ export const denClaude: Runtime = {
         bin,
         "--session-id",
         id,
+        ...nameArg(input.sessionLabel),
         ...c.argv,
         ...firstPromptArg(input.firstPrompt),
       ],
@@ -517,7 +523,13 @@ export const denClaude: Runtime = {
     const bin = binFor(input);
     const c = common(input);
     return {
-      argv: [bin, "--resume", input.resumeToken, ...c.argv],
+      argv: [
+        bin,
+        "--resume",
+        input.resumeToken,
+        ...nameArg(input.sessionLabel),
+        ...c.argv,
+      ],
       env: {},
       files: c.files,
       warnings: c.warnings,

package/src/shared/agents/records.ts

@@ -86,6 +86,12 @@ export interface AgentRecord {
   displayName?: string;
   /** When displayName was given (ISO 8601): the latest rename wins (AG-4b). */
   displayNameAt?: string;
+  /**
+   * D24: the name Den last gave its runtime session (Claude Code's
+   * `--name`, peerSessionName), so reading it back is never taken for a
+   * rename.
+   */
+  peerName?: string;
   /**
    * The model version it runs (AG-12.3): "latest" (the model's newest), or
    * a pinned version. Absent: before AG-12, `model` as given.

package/src/shared/agents/runtime.ts

@@ -120,6 +120,12 @@ export interface LaunchInput {
    * Only a runtime with `firstPrompt: true` is given one.
    */
   firstPrompt?: string;
+  /**
+   * D24: the name other sessions see this one by (peerSessionName:
+   * `<cli>-<ws>:<name>`). A runtime that can name its session (den-claude:
+   * `--name`) does, at launch and at resume.
+   */
+  sessionLabel?: string;
 }
 
 export interface LaunchOutput {

package/src/shared/agents/session-name.ts

@@ -12,7 +12,10 @@
  *     token: Start fresh forgets it). An adapter that fails or throws is no
  *     name; it never breaks the list.
  *
- * Den never writes a name back into the runtime.
+ * D24: Den names the runtime's session for other sessions to see
+ * (peerSessionName: `<cli>-<ws>:<name>`, Claude Code's `--name`) at launch
+ * and resume. That name read back is Den's own (the record's peerName),
+ * never a rename.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -71,6 +74,8 @@ function runtimeName(
   } catch {
     name = null;
   }
+  // D24: Den's own --name, read back, is not the runtime's rename.
+  if (name && name === rec.peerName) name = null;
   // null: nothing new (not caught up, not found); the last name stays.
   if (name && name !== seen?.name) {
     seen = { token, name, at: now() };
@@ -83,6 +88,21 @@ function runtimeName(
   return seen;
 }
 
+/**
+ * D24: the name other sessions (ListAgents) see agent `rec` by:
+ * `<cli>-<ws>:<its name, else its id>`. No control characters: it is a
+ * process argument.
+ */
+export function peerSessionName(
+  cli: string,
+  ws: string,
+  rec: Pick<AgentRecord, "id" | "displayName">,
+): string {
+  // eslint-disable-next-line no-control-regex
+  const name = (rec.displayName ?? "").replace(/[\u0000-\u001f\u007f]/g, "");
+  return `${cli}-${ws}:${name.trim() || rec.id}`;
+}
+
 /**
  * The agent's session name: the latest of Den's rename and the runtime's,
  * or undefined when neither has one. Never throws.

package/src/shared/attest-code.ts

@@ -0,0 +1,125 @@
+/**
+ * "This is my computer" (D17, fix A): how a browser on the machine Den runs
+ * on proves it, when the edge can't tell (Docker Desktop, OrbStack or a TCP
+ * passthrough hand the edge a gateway's address, so edgeClient says
+ * `unattested`).
+ *
+ * The signed-out edge page navigates the top level to
+ * `http://localhost:<port>/attest?return=<its own edge URL>`. Only a browser
+ * on this machine reaches this server there: a browser elsewhere reaches
+ * nothing, or its own machine's Den, whose web.secret doesn't verify here.
+ * The server answers 303 to the edge URL with the code in the fragment
+ * (`#den-attest=<code>`: never sent to a server, never in a log), and the
+ * page starts Sign in with GitHub with it.
+ *
+ * The proof alone never makes a session. Any program running as this OS
+ * user (an agent with a shell, too) can reach localhost, so a session from
+ * it would let an agent approve its own changes. It only lets a GitHub
+ * sign-in claim a Den that has no owner, for a member of
+ * web.allowed_github_org (github-routes.ts decideFlow): the person still
+ * approves on github.com.
+ *
+ *  - `a1.<nonce>.<expiry>.<mac>`, the mac HMAC-SHA256(web.secret, context +
+ *    the rest + the edge host it is for), its context its own: never a
+ *    login or a claim code. A code minted for one host fails on another.
+ *  - Valid for ATTEST_CODE_TTL_MS (2 minutes): the page uses it at once.
+ *  - Single use: its nonce is spent when the sign-in starts (ClaimNonces,
+ *    a file, so a restart can't revive one).
+ *  - `return` must be one of this server's own edge hosts (attestReturn).
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+
+export const ATTEST_CODE_TTL_MS = 2 * 60_000;
+const SKEW_MS = 5_000;
+const CONTEXT = "den-attest-v1:";
+/** Where the spent attest nonces are kept (ClaimNonces' format). */
+export const ATTEST_NONCES_FILE = "attest-nonces.json";
+
+function mac(secret: Buffer, body: string, host: string): Buffer {
+  return createHmac("sha256", secret)
+    .update(`${CONTEXT}${body}\n${host.toLowerCase()}`)
+    .digest();
+}
+
+/** A fresh attest code for `host` (the edge hostname, no port). */
+export function mintAttestCode(
+  secret: Buffer,
+  host: string,
+  now: number = Date.now(),
+): string {
+  const nonce = randomBytes(16).toString("base64url");
+  const body = `a1.${nonce}.${(now + ATTEST_CODE_TTL_MS).toString(36)}`;
+  return `${body}.${mac(secret, body, host).toString("base64url")}`;
+}
+
+export type AttestCodeCheck =
+  | { ok: true; nonce: string; expiresAt: number }
+  | { ok: false; reason: "malformed" | "bad_mac" | "expired" };
+
+/**
+ * Whether `code` is an attest code this secret minted for `host`, still in
+ * its time. Constant-time mac. Single use is the caller's.
+ */
+export function checkAttestCode(
+  code: string,
+  secret: Buffer,
+  host: string,
+  now: number = Date.now(),
+): AttestCodeCheck {
+  const m =
+    /^(a1\.([A-Za-z0-9_-]{22})\.([0-9a-z]{1,11}))\.([A-Za-z0-9_-]{43})$/.exec(
+      code,
+    );
+  if (!m) return { ok: false, reason: "malformed" };
+  const given = Buffer.from(m[4], "base64url");
+  const want = mac(secret, m[1], host);
+  if (given.length !== want.length || !timingSafeEqual(given, want))
+    return { ok: false, reason: "bad_mac" };
+  const expiresAt = parseInt(m[3], 36);
+  if (
+    !Number.isFinite(expiresAt) ||
+    now >= expiresAt ||
+    expiresAt - now > ATTEST_CODE_TTL_MS + SKEW_MS
+  )
+    return { ok: false, reason: "expired" };
+  return { ok: true, nonce: m[2], expiresAt };
+}
+
+/**
+ * `/attest`'s `return`, checked: an http(s) URL whose host is one of
+ * `edgeHosts` (this server's own edge hostnames), no credentials in it.
+ * Its origin and same-origin path, or null for anything else.
+ */
+export function attestReturn(
+  raw: string | null | undefined,
+  edgeHosts: readonly string[],
+): { origin: string; host: string; next: string } | null {
+  if (!raw) return null;
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" && u.protocol !== "http:") return null;
+  if (u.username || u.password) return null;
+  const host = u.hostname.toLowerCase();
+  if (!edgeHosts.map((h) => h.toLowerCase()).includes(host)) return null;
+  const next = `${u.pathname}${u.search}`;
+  return {
+    origin: u.origin,
+    host,
+    next: next.startsWith("/auth") ? "/" : next,
+  };
+}
+
+/** The fragment key the code rides in back to the edge page. */
+export const ATTEST_FRAGMENT = "den-attest";
+
+/** Where /attest sends the browser: the edge page, the code in the fragment. */
+export function attestRedirect(
+  ret: { origin: string; next: string },
+  code: string,
+): string {
+  return `${ret.origin}${ret.next}#${ATTEST_FRAGMENT}=${encodeURIComponent(code)}`;
+}

package/src/shared/claim-code.ts

@@ -108,10 +108,14 @@ export function claimRefusalForAgent(env: NodeJS.ProcessEnv): string | null {
 
 /** The used claim nonces, kept until they expire (a file, 0600). */
 export class ClaimNonces {
-  constructor(private readonly stateDir: string) {}
+  constructor(
+    private readonly stateDir: string,
+    /** The file's name (D17: the attest codes keep their own). */
+    private readonly fileName: string = CLAIM_NONCES_FILE,
+  ) {}
 
   private file(): string {
-    return path.join(this.stateDir, CLAIM_NONCES_FILE);
+    return path.join(this.stateDir, this.fileName);
   }
 
   /** The used nonces; null when the file is there but won't parse (fail closed). */

package/src/{ui/server/edge-exposure.ts → shared/edge/exposure.ts}

@@ -15,7 +15,13 @@
  */
 import { execFile } from "child_process";
 import { promises as dns } from "dns";
-import { isLoopbackAddress } from "./request-guard.js";
+import * as net from "net";
+
+/** A loopback IP (127/8, ::1, or either IPv4-mapped); request-guard.ts has the same. */
+function isLoopbackAddress(addr: string): boolean {
+  const a = addr.toLowerCase().replace(/^::ffff:/, "");
+  return a === "::1" || (net.isIPv4(a) && a.startsWith("127."));
+}
 
 /**
  * The warning, by `web.edge_unattested` (SEC-2a): with `signin` (the

package/src/shared/github-app.ts

@@ -41,6 +41,8 @@ export interface GithubEndpoints {
   deviceCode: string;
   accessToken: string;
   user: string;
+  /** The REST API's base (D17: an org's membership), no trailing slash. */
+  api: string;
   /** A test's fake GitHub is in use (GITHUB_TEST_BASE_ENV). */
   fake: boolean;
 }
@@ -68,12 +70,14 @@ export function githubEndpoints(
       deviceCode: `${fake}/login/device/code`,
       accessToken: `${fake}/login/oauth/access_token`,
       user: `${fake}/user`,
+      api: fake,
       fake: true,
     };
   return {
     deviceCode: "https://github.com/login/device/code",
     accessToken: "https://github.com/login/oauth/access_token",
     user: "https://api.github.com/user",
+    api: "https://api.github.com",
     fake: false,
   };
 }