@botiverse/hands-cli 0.5.15 → 0.5.17

package/dist/lib/agent_auth.js

@@ -0,0 +1,318 @@
+/**
+ * Agent CLI login flow (RFC 057, CP3): the non-interactive `hands login` used inside
+ * a managed Raft agent. No browser, no paste.
+ *
+ *   1. Generate a PKCE code_verifier locally; send only its S256 challenge to Raft.
+ *   2. Run the EXACT wrapper `$SLOCK_CLI_TRANSPORT_DIR/raft integration invoke
+ *      --action agent-login --json` (never PATH `raft`); require exit 0; STRICTLY
+ *      validate the result (outer success + exact service/action/status + closed grant
+ *      result schema + RFC3339/future expiry within a bounded client sanity window). The
+ *      server issues a 300s TTL (RFC 057) and enforces the real expiry; the client accepts
+ *      up to 300s + clock-skew headroom so a boundary grant is not rejected under skew.
+ *      Errors carry only stable reasons
+ *      — never the raw stdout/stderr/body (which could contain grant/action payload).
+ *   3. Exchange { grant, code_verifier } at the Hands PUBLIC endpoint for a
+ *      raft-cli-agent-session.v1; strictly validate it (closed keys + RFC3339 expiries).
+ *   4. Atomically persist under $SLOCK_HOME (O_EXCL temp + fsync + rename; 0600 file /
+ *      verified-0700 dirs), recording the api base so the resolver never needs config.
+ *
+ * The verifier never reaches Raft, logs, or the store. Only the Hands token is stored.
+ */
+import { spawnSync } from "node:child_process";
+import { openSync, writeSync, fsyncSync, closeSync, renameSync, rmSync, mkdirSync, statSync, chmodSync, } from "node:fs";
+import { join } from "node:path";
+import { randomBytes, createHash } from "node:crypto";
+import { getApiBase } from "./api.js";
+import { agentAuthPath, HANDS_SERVICE } from "./agent_env.js";
+function base64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** PKCE S256: 64-byte verifier → 86 unreserved base64url chars (within RFC 7636's
+ *  43–128), challenge = unpadded base64url SHA-256. */
+export function generatePkce() {
+    const verifier = base64url(randomBytes(64));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+function hasExactKeys(o, keys) {
+    const k = Object.keys(o);
+    return k.length === keys.length && keys.every((key) => Object.prototype.hasOwnProperty.call(o, key));
+}
+/** Parse an RFC3339 date-time to epoch ms, or null. Rejects bare dates / bad offsets. */
+function parseRfc3339(s) {
+    if (typeof s !== "string")
+        return null;
+    if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?(Z|[+-]\d\d:\d\d)$/.test(s))
+        return null;
+    const t = Date.parse(s);
+    return Number.isFinite(t) ? t : null;
+}
+// Client-side sanity ceiling on the grant lifetime: the server issues expiry =
+// server_now + 300s (RFC 057). We allow generous clock-skew headroom above that so a
+// legitimate grant is never rejected at the exact boundary; the server enforces the
+// real, shorter expiry, so this bound only rejects an absurdly long-lived grant.
+const AGENT_GRANT_TTL_CEILING_MS = 300_000 + 120_000; // 300s + 120s skew
+/**
+ * Strictly validate a `raft integration invoke --action agent-login --json` result.
+ * Real envelope (verified against the live daemon):
+ *   { ok:true, data:{ service, action, status, result:{schema,service,grant,expires_at} } }
+ * The Hands-owned `result` is closed-key validated; the Raft envelope (outer/data) is
+ * validated by exact required values. NO part of stdout is ever echoed in an error.
+ */
+export function parseAgentLoginInvoke(stdout, service, now) {
+    let outer;
+    try {
+        outer = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error("agent-login: `raft integration invoke` did not return JSON");
+    }
+    if (!outer || typeof outer !== "object")
+        throw new Error("agent-login: invoke output is not an object");
+    // Check success first: a failed invoke may legitimately carry a different shape
+    // (e.g. {ok:false, error}); only the success wrapper is the closed {ok, data}.
+    if (outer.ok !== true)
+        throw new Error("agent-login: invoke did not succeed");
+    // Closed envelope: an unexpected extra field means the wire drifted from the
+    // checkpoint contract; fail rather than ignore.
+    if (!hasExactKeys(outer, ["ok", "data"]))
+        throw new Error("agent-login: invoke envelope has unexpected fields");
+    const data = outer.data;
+    if (!data || typeof data !== "object")
+        throw new Error("agent-login: invoke result is missing data");
+    if (!hasExactKeys(data, ["service", "action", "status", "result"])) {
+        throw new Error("agent-login: invoke data has unexpected fields");
+    }
+    if (data.service !== service)
+        throw new Error("agent-login: invoke service does not match the requested service");
+    if (data.action !== "agent-login")
+        throw new Error("agent-login: invoke action is not agent-login");
+    if (data.status !== 200)
+        throw new Error("agent-login: agent-login action did not return HTTP 200");
+    const result = data.result;
+    if (!result || typeof result !== "object")
+        throw new Error("agent-login: invoke result is missing the grant body");
+    if (!hasExactKeys(result, ["schema", "service", "grant", "expires_at"])) {
+        throw new Error("agent-login: grant result has unexpected fields");
+    }
+    if (result.schema !== "raft-cli-agent-login-grant.v1")
+        throw new Error("agent-login: unexpected grant result schema");
+    if (result.service !== service)
+        throw new Error("agent-login: grant result service mismatch");
+    if (typeof result.grant !== "string" || result.grant.length === 0)
+        throw new Error("agent-login: grant is missing");
+    const exp = parseRfc3339(result.expires_at);
+    if (exp === null)
+        throw new Error("agent-login: grant expires_at is not an RFC3339 timestamp");
+    if (exp <= now)
+        throw new Error("agent-login: grant is already expired");
+    // The server issues expiry = server_now + 300s (RFC 057). The client parses it later and
+    // its clock may differ, so a zero-tolerance ceiling flakes at the exact boundary. This is
+    // a sanity bound (the server enforces the real expiry), so allow clock-skew headroom.
+    if (exp > now + AGENT_GRANT_TTL_CEILING_MS)
+        throw new Error("agent-login: grant expiry exceeds the ceiling");
+    return { grant: result.grant, expires_at: result.expires_at };
+}
+/**
+ * Strictly validate the exchange/refresh success body (closed keys + RFC3339).
+ * `now` is injected so validation is deterministic: a freshly issued session MUST
+ * have a strictly-future access expiry (and refresh expiry, when present) — otherwise
+ * we would persist an already-dead session that the very next request must refresh.
+ */
+export function parseAgentSession(body, now) {
+    if (!body || typeof body !== "object")
+        throw new Error("agent-login: exchange response is not an object");
+    if (!hasExactKeys(body, ["schema", "token_type", "access_token", "access_expires_at", "refresh_token", "refresh_expires_at"])) {
+        throw new Error("agent-login: session has unexpected fields");
+    }
+    if (body.schema !== "raft-cli-agent-session.v1")
+        throw new Error("agent-login: unexpected session schema");
+    if (body.token_type !== "Bearer")
+        throw new Error("agent-login: unexpected token_type");
+    for (const k of ["access_token", "refresh_token"]) {
+        if (typeof body[k] !== "string" || body[k].length === 0)
+            throw new Error(`agent-login: session missing ${k}`);
+    }
+    const accessExp = parseRfc3339(body.access_expires_at);
+    if (accessExp === null)
+        throw new Error("agent-login: session access_expires_at is not RFC3339");
+    if (accessExp <= now)
+        throw new Error("agent-login: session access token is already expired");
+    if (body.refresh_expires_at !== null) {
+        const refreshExp = parseRfc3339(body.refresh_expires_at);
+        if (refreshExp === null)
+            throw new Error("agent-login: session refresh_expires_at must be RFC3339 or null");
+        if (refreshExp <= now)
+            throw new Error("agent-login: session refresh token is already expired");
+    }
+    return body;
+}
+/** mkdir (if needed) + verify/repair 0700 (no group/other) on one path component. */
+function ensureSecureDir(dir) {
+    try {
+        mkdirSync(dir, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e?.code !== "EEXIST")
+            throw e;
+    }
+    const st = statSync(dir);
+    if (!st.isDirectory())
+        throw new Error("agent-login: store path component is not a directory");
+    if ((st.mode & 0o077) !== 0)
+        chmodSync(dir, 0o700); // repair a pre-existing wide dir
+}
+/**
+ * Atomic, hardened store write: O_EXCL unique temp in the same dir, 0600, write +
+ * fsync + close, atomic rename. Each dir component under $SLOCK_HOME is ensured AND
+ * verified 0700 (repairing a pre-existing wide dir). $SLOCK_HOME itself is not chmod'd.
+ * On any failure the temp is removed and the previous file is left intact.
+ */
+export function writeAgentSession(a, service, session, apiBase, now = () => new Date().toISOString()) {
+    const path = agentAuthPath(a, service); // validates slug + agent id + containment
+    let dir = a.slockHome;
+    for (const seg of ["agents", a.agentId, "integrations", service]) {
+        dir = join(dir, seg);
+        ensureSecureDir(dir);
+    }
+    const record = { ...session, service, api_base: apiBase, updated_at: now() };
+    const payload = JSON.stringify(record, null, 2) + "\n";
+    const tmp = join(dir, `.auth.${randomBytes(8).toString("hex")}.tmp`);
+    let fd = null;
+    try {
+        fd = openSync(tmp, "wx", 0o600); // 'wx' = O_CREAT|O_EXCL|O_WRONLY
+        writeSync(fd, payload);
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = null;
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch { /* ignore */ }
+        throw e; // previous auth.json (if any) is left intact
+    }
+    return path;
+}
+// Token responses are small JSON; cap the read so a hostile/broken endpoint cannot
+// stream an unbounded body. Shared by the exchange and refresh token requests.
+export const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+/**
+ * Read a response body with a hard byte cap. If an AbortController is supplied it is
+ * aborted when the cap is exceeded (so a still-open connection is torn down, and — in
+ * `rotate` — the same controller's deadline keeps covering this read). Falls back to
+ * `.text()` for response doubles that expose no stream (still cap-checked).
+ */
+export async function readBoundedText(res, controller) {
+    const declared = Number(res.headers?.get?.("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_TOKEN_RESPONSE_BYTES) {
+        controller?.abort();
+        throw new Error("agent-login: token response exceeds the size limit");
+    }
+    const reader = res.body?.getReader?.();
+    if (!reader) {
+        const t = await res.text();
+        if (t.length > MAX_TOKEN_RESPONSE_BYTES)
+            throw new Error("agent-login: token response exceeds the size limit");
+        return t;
+    }
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            total += value.byteLength;
+            if (total > MAX_TOKEN_RESPONSE_BYTES) {
+                controller?.abort();
+                try {
+                    await reader.cancel();
+                }
+                catch { /* ignore */ }
+                throw new Error("agent-login: token response exceeds the size limit");
+            }
+            chunks.push(value);
+        }
+    }
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.byteLength;
+    }
+    return new TextDecoder().decode(out);
+}
+function defaultInvoke(raftBin, args) {
+    const res = spawnSync(raftBin, args, { encoding: "utf8" });
+    return {
+        status: res.error ? null : res.status,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+    };
+}
+/**
+ * Full agent-login flow: invoke the pinned wrapper → strict-validate grant → exchange
+ * → strict-validate session → atomic store. Returns the stored session on success.
+ */
+export async function runAgentLogin(a, opts = {}) {
+    const service = opts.service ?? HANDS_SERVICE;
+    const now = opts.now ?? Date.now();
+    const { verifier, challenge } = generatePkce();
+    const args = [
+        "integration", "invoke",
+        "--service", service,
+        "--action", "agent-login",
+        "--json",
+        "--data-json", JSON.stringify({
+            schema: "raft-cli-agent-login-request.v1",
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+        }),
+    ];
+    const runner = opts.invoke ?? ((a2) => defaultInvoke(a.raftBin, a2));
+    const res = runner(args);
+    if (res.status !== 0) {
+        // Require a clean exit; never echo stdout/stderr (may carry grant/action payload).
+        throw new Error(`agent-login: raft invoke exited with a non-zero status (${res.status ?? "spawn error"})`);
+    }
+    const { grant } = parseAgentLoginInvoke(res.stdout, service, now);
+    // Independent token request: NO stored Bearer, NO auto-refresh. `hands login` is the
+    // recovery path when the stored refresh has reached a terminal state
+    // (expired/reused/revoked); routing this exchange through the api client would first
+    // try to refresh that dead token and throw before the fresh grant is ever spent.
+    const apiBase = getApiBase();
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const exchangeRes = await fetchImpl(new URL("/api/auth/agent/exchange", apiBase).toString(), {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify({ schema: "raft-cli-agent-login-exchange.v1", grant, code_verifier: verifier }),
+        // Never follow a redirect: a 307/308 would forward the grant + code_verifier body
+        // to the redirect target. `manual` leaves a 3xx as a non-ok status we reject below.
+        redirect: "manual",
+    });
+    if (!exchangeRes.ok) {
+        // Stable reason only; never echo the response body (may carry token material).
+        throw new Error(`agent-login: grant exchange failed (HTTP ${exchangeRes.status})`);
+    }
+    const exchangeText = await readBoundedText(exchangeRes);
+    let exchangeBody;
+    try {
+        exchangeBody = JSON.parse(exchangeText);
+    }
+    catch {
+        throw new Error("agent-login: exchange response was not JSON");
+    }
+    const session = parseAgentSession(exchangeBody, now);
+    writeAgentSession(a, service, session, apiBase);
+    return session;
+}
+//# sourceMappingURL=agent_auth.js.map

package/dist/lib/agent_auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_auth.js","sourceRoot":"","sources":["../../src/lib/agent_auth.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent_env.d.ts

@@ -0,0 +1,33 @@
+export declare const HANDS_SERVICE = "hands-4cc7a2";
+export interface AgentEnv {
+    transportDir: string;
+    slockHome: string;
+    agentId: string;
+    raftBin: string;
+}
+export type Admission = {
+    kind: "human";
+} | {
+    kind: "agent";
+    env: AgentEnv;
+} | {
+    kind: "fail_closed";
+    reason: string;
+};
+/**
+ * Decide human vs agent vs fail-closed. Once ANY agent marker is present we never
+ * return `human` — a partial/invalid environment fails closed rather than silently
+ * using ambient human credentials.
+ */
+export declare function admitAgent(env?: NodeJS.ProcessEnv): Admission;
+/** Canonical per-agent store path, with slug validation + root containment. */
+export declare function agentAuthPath(a: AgentEnv, service?: string): string;
+/**
+ * Read the stored Hands access token for this agent, or null if absent/unreadable.
+ * Dependency-free (fs + path only) so `config.ts` can call it without an import cycle
+ * through the api client. Auto-refresh-on-expiry lands in CP3 checkpoint-2.
+ */
+export declare function readAgentAccessToken(a: AgentEnv, service?: string): string | null;
+/** Read the api base recorded in the agent store (so the resolver never reads the
+ *  human config in agent mode), or null. */
+export declare function readAgentApiBase(a: AgentEnv, service?: string): string | null;

package/dist/lib/agent_env.js

@@ -0,0 +1,112 @@
+/**
+ * Agent runtime admission + credential-store path (RFC 057 agent login, CP3).
+ *
+ * Admission is TRI-STATE (Volta): no markers → normal human/CI; any agent marker but
+ * incomplete/invalid/no-executable-wrapper → FAIL CLOSED (never fall back to human
+ * credentials); complete + valid → agent mode, pinned to the exact `raft` wrapper
+ * inside $SLOCK_CLI_TRANSPORT_DIR (never the PATH `raft`).
+ */
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+// Compiled-fixed exact installed Raft client key. NOT environment-overridable: it is
+// both the invoke target AND part of the on-disk store path, so an override would be a
+// cross-service / path-injection vector. Tests inject a service via function params.
+export const HANDS_SERVICE = "hands-4cc7a2";
+// RFC 057 service slug.
+const SERVICE_SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+// Daemon-issued agent id: a conservative safe token (no separators/traversal).
+const AGENT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+function isExecutableFile(p) {
+    try {
+        if (!statSync(p).isFile())
+            return false;
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide human vs agent vs fail-closed. Once ANY agent marker is present we never
+ * return `human` — a partial/invalid environment fails closed rather than silently
+ * using ambient human credentials.
+ */
+export function admitAgent(env = process.env) {
+    const transportDir = env.SLOCK_CLI_TRANSPORT_DIR;
+    const slockHome = env.SLOCK_HOME;
+    const agentId = env.SLOCK_AGENT_ID;
+    if (!transportDir && !slockHome && !agentId)
+        return { kind: "human" };
+    if (!transportDir || !slockHome || !agentId) {
+        return { kind: "fail_closed", reason: "incomplete agent markers" };
+    }
+    if (!AGENT_ID_RE.test(agentId)) {
+        return { kind: "fail_closed", reason: "invalid SLOCK_AGENT_ID" };
+    }
+    const raftBin = join(transportDir, "raft");
+    if (!isExecutableFile(raftBin)) {
+        return { kind: "fail_closed", reason: "raft wrapper missing or not executable in transport dir" };
+    }
+    return { kind: "agent", env: { transportDir, slockHome, agentId, raftBin } };
+}
+/** Canonical per-agent store path, with slug validation + root containment. */
+export function agentAuthPath(a, service = HANDS_SERVICE) {
+    if (!SERVICE_SLUG_RE.test(service))
+        throw new Error("invalid service slug");
+    if (!AGENT_ID_RE.test(a.agentId))
+        throw new Error("invalid agent id");
+    const root = resolve(a.slockHome, "agents", a.agentId, "integrations");
+    const path = resolve(root, service, "auth.json");
+    // Belt-and-suspenders containment (agentId/service are already regex-validated).
+    if (path !== join(root, service, "auth.json") || !path.startsWith(root + sep)) {
+        throw new Error("resolved store path escapes the integrations root");
+    }
+    return path;
+}
+/**
+ * Read the stored Hands access token for this agent, or null if absent/unreadable.
+ * Dependency-free (fs + path only) so `config.ts` can call it without an import cycle
+ * through the api client. Auto-refresh-on-expiry lands in CP3 checkpoint-2.
+ */
+export function readAgentAccessToken(a, service = HANDS_SERVICE) {
+    let path;
+    try {
+        path = agentAuthPath(a, service);
+    }
+    catch {
+        return null;
+    }
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed?.access_token === "string" && parsed.access_token.length > 0
+            ? parsed.access_token
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the api base recorded in the agent store (so the resolver never reads the
+ *  human config in agent mode), or null. */
+export function readAgentApiBase(a, service = HANDS_SERVICE) {
+    let path;
+    try {
+        path = agentAuthPath(a, service);
+    }
+    catch {
+        return null;
+    }
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return typeof parsed?.api_base === "string" && parsed.api_base.length > 0 ? parsed.api_base : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=agent_env.js.map

package/dist/lib/agent_env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_env.js","sourceRoot":"","sources":["../../src/lib/agent_env.ts"],"names":[],"mappings":"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"}

package/dist/lib/agent_refresh.d.ts

@@ -0,0 +1,32 @@
+import { type AgentEnv } from "./agent_env.js";
+export declare const REFRESH_SKEW_MS = 60000;
+export interface RefreshOptions {
+    service?: string;
+    now?: number;
+    fetchImpl?: typeof fetch;
+    /** Injectable sleep for tests (defaults to real setTimeout). */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injectable refresh deadline for tests (defaults to REFRESH_DEADLINE_MS). */
+    deadlineMs?: number;
+}
+/**
+ * Return a valid access token, refreshing (single-flight) if it is within the skew
+ * window. Returns null if there is no stored session (caller must `hands login`).
+ */
+export declare function getFreshAgentAccessToken(a: AgentEnv, opts?: RefreshOptions): Promise<string | null>;
+/**
+ * Force one refresh (used on a 401 even if the token looked unexpired), single-flight.
+ * Returns null if there is no stored session.
+ */
+export declare function forceRefreshAgentToken(a: AgentEnv, opts?: RefreshOptions): Promise<string | null>;
+/** Delete the lock only if it still carries OUR owner id (never a foreign holder's). */
+export declare function releaseOwnLock(lock: string, ownerId: string): void;
+/**
+ * Recover a lock whose owner process is provably dead and acquire it, serialized by an
+ * exclusive reaper fence. Judge-dead → unlink → re-acquire all happen WHILE the fence is
+ * held, so at most one recoverer reaps-and-rebuilds — two concurrent recoverers can never
+ * both re-acquire (→ never double-rotate). A LIVE owner (incl. suspended/stalled — pid
+ * still exists) is never touched. Any uncertainty fails closed. Returns true iff WE now
+ * hold the main lock carrying `ownerId`; false → the caller is a loser.
+ */
+export declare function acquireIfDeadOwner(lock: string, ownerId: string): boolean;