@symbols-cli/cli 0.0.1

package/dist/auth/credentials.js

@@ -0,0 +1,293 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// Where the device credential lives.
+//
+// TWO STORES, and which one is in use is reported by `symbols whoami` rather than
+// assumed:
+//
+//   * macOS: the login keychain, via `security(1)`. Not because it stops a
+//     same-uid process — it does not; `security find-generic-password` succeeds
+//     for anything running as this user without a prompt — but because it keeps
+//     the refresh token out of the filesystem, off Time Machine, out of `tar`
+//     backups, out of an accidental `git add ~`, and away from every tool that
+//     walks $HOME looking for dotfiles. That is the realistic exposure.
+//   * Everywhere else: `~/.symbols/credentials` at 0600, written 0600 from
+//     creation via `mode` + an explicit `fchmod`, never 0644-then-tightened.
+//
+// ⚠ Do not describe either as containment against the local agent. It runs as
+// the same uid and can read both. The properties that actually bound a stolen
+// credential are elsewhere: a 15-minute access TTL, server-side durable device
+// revocation (`cli_device.revoked_at`, which survives an API restart), refresh
+// reuse-detection that revokes the device on a PROVEN replay (a token the server
+// can show it issued — see `cli_token_history`), and the fact that the CLI token
+// carries no money scope at all.
+//
+// The ANTI-ROLLBACK COUNTER (S1) belongs here too, in the keychain half, for
+// exactly the reason the plan gives: a counter the agent can rewind is theatre.
+// It is a separate item so a bundle rollback cannot be achieved by deleting the
+// credential and logging in again.
+import { promises as fs } from "node:fs";
+import { hostname, platform } from "node:os";
+import { join, dirname } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { symbolsHome } from "../util/platform.js";
+import { eprint } from "../util/log.js";
+const exec = promisify(execFile);
+const SERVICE = "com.symbols.cli";
+const ACCOUNT = "device-credential";
+/**
+ * S1's anti-rollback counter — a SEPARATE keychain item, deliberately.
+ *
+ * Sharing the credential's item would make "downgrade the skills bundle" as easy
+ * as `symbols logout && symbols login`: the counter would be destroyed with the
+ * credential and the highest-sequence memory with it.
+ */
+const SEQUENCE_ACCOUNT = "skills-bundle-sequence";
+export function credentialsPath() {
+    return join(symbolsHome(), "credentials");
+}
+/**
+ * Which store this process will use.
+ *
+ * `SYMBOLS_CREDENTIAL_STORE=file` forces the file store — needed for CI and for
+ * the conformance harness, where no keychain is unlocked.
+ */
+export function storeKind() {
+    const forced = process.env["SYMBOLS_CREDENTIAL_STORE"];
+    if (forced === "file")
+        return "file";
+    if (forced === "keychain")
+        return "keychain";
+    return platform() === "darwin" ? "keychain" : "file";
+}
+export async function save(cred) {
+    const kind = storeKind();
+    const blob = JSON.stringify(cred);
+    if (kind === "keychain") {
+        try {
+            await keychainWrite(blob);
+            // Belt and braces: if a file store was in use before (or the user switched
+            // platforms with a synced home), do not leave a stale credential behind
+            // where a later downgrade would silently pick it up.
+            await fs.rm(credentialsPath(), { force: true });
+            return "keychain";
+        }
+        catch (err) {
+            // A locked or absent keychain must not be fatal — fall back and SAY SO, so
+            // the user is never told their token is in the keychain when it is on disk.
+            eprint(`symbols: keychain unavailable (${err instanceof Error ? err.message : String(err)}); ` +
+                `falling back to ${credentialsPath()} at 0600\n`);
+        }
+    }
+    await fileWrite(blob);
+    return "file";
+}
+export async function load() {
+    if (storeKind() === "keychain") {
+        const fromKeychain = await keychainRead();
+        if (fromKeychain)
+            return parse(fromKeychain);
+    }
+    try {
+        return parse(await fs.readFile(credentialsPath(), "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function clear() {
+    // Both stores, unconditionally. `logout` that leaves a copy behind in the
+    // other store is the worst possible outcome of this function.
+    await keychainDelete();
+    await fs.rm(credentialsPath(), { force: true });
+}
+function parse(blob) {
+    try {
+        const v = JSON.parse(blob);
+        if (!v.refreshToken || !v.deviceId || !v.origin || !v.userId)
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+/** A stable, human-recognisable name for this machine in the device list. */
+export function deviceLabel() {
+    return `${hostname()} (${platform()})`;
+}
+export function bundleSequenceStore() {
+    return storeKind() === "keychain" ? "keychain" : "file";
+}
+function sequencePath() {
+    return join(symbolsHome(), "bundle-sequence");
+}
+/**
+ * The highest bundle sequence this machine has ever accepted. 0 when unset.
+ *
+ * ⚠ THE PAYLOAD IS JSON, NOT A BARE INTEGER.
+ *
+ * It was originally JSON to dodge a bug: `keychainReadAccount` hex-decoded any
+ * all-hex, even-length value, so a bare `"12"` came back as `"\x12"` and the
+ * counter silently reset to 0 on exactly the values that look like hex — 12, 20,
+ * 22, 30, …  **That branch has since been DELETED at the source**, so the
+ * workaround is no longer load-bearing; JSON is kept because it is
+ * self-describing and lets the payload gain a field without a format change.
+ *
+ * (Recording the correction rather than deleting it: a comment that describes a
+ * mechanism which no longer exists is what made the SEC-8 gamble look safe in
+ * `client.ts`. Stale reasoning outlives stale code.)
+ */
+export async function readBundleSequence() {
+    const raw = bundleSequenceStore() === "keychain"
+        ? await keychainReadAccount(SEQUENCE_ACCOUNT)
+        : await fs.readFile(sequencePath(), "utf8").catch(() => null);
+    if (!raw)
+        return 0;
+    let n = 0;
+    try {
+        const v = JSON.parse(raw);
+        n = typeof v.sequence === "number" ? v.sequence : 0;
+    }
+    catch {
+        n = 0;
+    }
+    // A corrupt or missing counter reads as 0 — permissive, and deliberately so:
+    // failing closed here would brick the CLI on a keychain hiccup, while failing
+    // open costs only the rollback floor, which is re-established on the next
+    // accepted bundle. The bundle still has to VERIFY, which is the control that
+    // may never degrade.
+    return Number.isInteger(n) && n > 0 ? n : 0;
+}
+/**
+ * Raise the floor. Never lowers it, even if asked.
+ *
+ * Returns the value now in force, so a caller can log what actually happened
+ * rather than what it requested.
+ */
+export async function recordBundleSequence(seq) {
+    const current = await readBundleSequence();
+    if (!Number.isInteger(seq) || seq <= current)
+        return current;
+    const blob = JSON.stringify({ sequence: seq });
+    if (bundleSequenceStore() === "keychain") {
+        try {
+            await keychainWriteAccount(SEQUENCE_ACCOUNT, blob);
+            return seq;
+        }
+        catch (err) {
+            eprint(`symbols: keychain unavailable for the bundle counter ` +
+                `(${err instanceof Error ? err.message : String(err)}); using ${sequencePath()}\n`);
+        }
+    }
+    await fs.mkdir(dirname(sequencePath()), { recursive: true, mode: 0o700 });
+    await fs.writeFile(sequencePath(), `${blob}\n`, { mode: 0o600 });
+    return seq;
+}
+// ── file store ───────────────────────────────────────────────────────────────
+async function fileWrite(blob) {
+    const path = credentialsPath();
+    await fs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    // Write-then-rename so a crash never leaves a truncated credential, and open
+    // the temp file 0600 from creation — a 0644 window, however brief, is enough
+    // for another local user to win a read on a shared machine.
+    const tmp = `${path}.${process.pid}.tmp`;
+    const handle = await fs.open(tmp, "wx", 0o600);
+    try {
+        await handle.writeFile(blob, "utf8");
+        // `mode` on open is masked by umask; fchmod is not.
+        await handle.chmod(0o600);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(tmp, path);
+    await fs.chmod(path, 0o600);
+}
+// ── keychain store (macOS) ───────────────────────────────────────────────────
+// Two items live in this keychain service — the device credential and S1's
+// anti-rollback counter — so every helper takes the ACCOUNT. `keychainWrite`
+// and friends keep their old signatures for the credential's call sites.
+async function keychainWrite(blob) {
+    return keychainWriteAccount(ACCOUNT, blob);
+}
+async function keychainRead() {
+    return keychainReadAccount(ACCOUNT);
+}
+async function keychainWriteAccount(account, blob) {
+    // ⚠ VERIFIED on macOS 25.2, because the obvious "safer" form is a trap:
+    // `security add-generic-password … -w -` does NOT read stdin — it stores the
+    // literal one-character string "-", so a credential written that way is
+    // silently garbage. Both supported forms (`-w <secret>` and `-X <hex>`) pass
+    // the secret as an ARGV VALUE, briefly visible in `ps` to this uid and to
+    // root. Both are already inside the trust boundary, so this is noted rather
+    // than defended; eliminating it needs the native Keychain API (a native
+    // module), which is not worth a build dependency in v1.
+    //
+    // `-X` is chosen over `-w` anyway: hex keeps the token out of anything that
+    // scrapes process lists for token-shaped strings, and it is byte-exact for
+    // payloads `-w` would mangle.
+    await exec("security", [
+        "add-generic-password",
+        "-a",
+        account,
+        "-s",
+        SERVICE,
+        "-U", // update in place; without it a second login errors with a duplicate
+        "-D",
+        account === SEQUENCE_ACCOUNT
+            ? "Symbols CLI skills-bundle anti-rollback counter"
+            : "Symbols CLI device credential",
+        "-X",
+        Buffer.from(blob, "utf8").toString("hex"),
+    ]);
+}
+async function keychainReadAccount(account) {
+    try {
+        const { stdout } = await exec("security", [
+            "find-generic-password",
+            "-a",
+            account,
+            "-s",
+            SERVICE,
+            "-w",
+        ]);
+        const raw = stdout.trim();
+        if (!raw)
+            return null;
+        // ⚠ RETURNED VERBATIM. There is deliberately NO hex-decode branch.
+        //
+        // An earlier version added one "so a future non-JSON payload cannot fail
+        // silently", guarded by `all-hex && even length`. That guard matches far more
+        // than intended: the string "12" is all-hex and even-length, so a stored
+        // value of `12` came back as `"\x12"`. The P2 agent hit it storing an
+        // anti-rollback counter — the floor silently vanished on 12, 20, 22, 30…
+        // and a rollback protection that evaporates on some values is worse than one
+        // that is absent, because it is believed.
+        //
+        // `-w` prints the secret as text whenever it is valid UTF-8, including one
+        // written with `-X` (verified on macOS 25.2). Every payload this CLI stores
+        // is UTF-8 JSON, so the text path is the only path. A future caller needing
+        // binary must base64 it BEFORE storing rather than reintroducing a guess
+        // here — a heuristic that inspects the value cannot distinguish encodings it
+        // was never told about.
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+async function keychainDelete() {
+    try {
+        await exec("security", ["delete-generic-password", "-a", ACCOUNT, "-s", SERVICE]);
+    }
+    catch {
+        // Not present is the desired end state.
+    }
+}

package/dist/auth/hosts.js

@@ -0,0 +1,85 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// S3 — host pinning for every credential-bearing request.
+//
+// Any process running as this user can set SYMBOLS_API_URL and redirect the next
+// refresh — and the rotating refresh token with it — to a host it controls. So
+// the API origin is an allowlist, not configuration.
+//
+// ⚠ SCOPE, stated honestly: this closes the REMOTE redirect (a stray env var, a
+// network attacker). It does NOT bind an agent running as the same uid, which
+// can read the credential file outright or replace this binary. Never describe
+// host-pinning as containment against the agent — the credential's real defences
+// are its 15-minute TTL, durable device revocation, and the fact that it carries
+// no money scope at all.
+//
+// Mirrors the discipline `google_signin` already applies to `web_base`
+// (apps/desktop/src-tauri/src/main.rs:408-419).
+const ALLOWED_ORIGINS = ["https://symbols.finance", "https://www.symbols.finance"];
+/** Localhost is permitted only when explicitly opted into, for development. */
+function devOriginAllowed(origin) {
+    if (process.env["SYMBOLS_ALLOW_INSECURE_ORIGIN"] !== "1")
+        return false;
+    try {
+        const u = new URL(origin);
+        return ((u.protocol === "http:" || u.protocol === "https:") &&
+            (u.hostname === "127.0.0.1" || u.hostname === "localhost"));
+    }
+    catch {
+        return false;
+    }
+}
+export class DisallowedOriginError extends Error {
+    constructor(origin) {
+        super(`refusing to use API origin '${origin}'. Allowed: ${ALLOWED_ORIGINS.join(", ")}. ` +
+            `Set SYMBOLS_ALLOW_INSECURE_ORIGIN=1 to permit http://127.0.0.1 for development.`);
+        this.name = "DisallowedOriginError";
+    }
+}
+/**
+ * The API origin for this process, validated.
+ *
+ * Structural comparison on a parsed URL — never a prefix or substring test, which
+ * is what lets `https://symbols.finance.evil.com` through.
+ */
+export function apiOrigin() {
+    const raw = (process.env["SYMBOLS_API_URL"] ?? ALLOWED_ORIGINS[0]).trim().replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new DisallowedOriginError(raw);
+    }
+    // Compare the normalised origin, so userinfo, a path, or a query cannot smuggle
+    // an allowed hostname past the check.
+    const origin = parsed.origin;
+    if (parsed.username || parsed.password)
+        throw new DisallowedOriginError(raw);
+    if (ALLOWED_ORIGINS.includes(origin))
+        return origin;
+    if (devOriginAllowed(origin))
+        return origin;
+    throw new DisallowedOriginError(raw);
+}
+export function isAllowedOrigin(candidate) {
+    try {
+        const saved = process.env["SYMBOLS_API_URL"];
+        process.env["SYMBOLS_API_URL"] = candidate;
+        try {
+            apiOrigin();
+            return true;
+        }
+        finally {
+            if (saved === undefined)
+                delete process.env["SYMBOLS_API_URL"];
+            else
+                process.env["SYMBOLS_API_URL"] = saved;
+        }
+    }
+    catch {
+        return false;
+    }
+}

package/dist/auth/loopback.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// The loopback listener that receives the exchange code from the browser.
+//
+// Ported from the Tauri desktop flow (apps/desktop/src-tauri/src/main.rs:403-494),
+// keeping its properties rather than its code. Each one is here for a reason:
+//
+//   * BIND THE PORT BEFORE OPENING THE BROWSER. That ownership is the security
+//     boundary — the desktop source says so in as many words. Open the browser
+//     first and there is a window where another local process can bind the port
+//     the redirect is about to target.
+//   * A 16-byte CSPRNG nonce, echoed by the browser and checked here. Combined
+//     with PKCE this means a racing process needs both the port AND the nonce AND
+//     the verifier.
+//   * ONLY `/cb`. Everything else is a 404, so the listener is not a general
+//     local HTTP surface for the duration.
+//   * `Referrer-Policy: no-referrer` on the response, so the code cannot leak via
+//     the Referer header when the success page links onward.
+//   * `Cache-Control: no-store`, so it does not sit in a disk cache.
+//   * One shot, five-minute deadline. The listener closes after the first valid
+//     callback or the timeout, whichever comes first.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+const DEADLINE_MS = 5 * 60 * 1000;
+const SUCCESS_HTML = `<!doctype html><meta charset="utf-8">
+<title>Signed in</title>
+<body style="font:16px system-ui;padding:3rem;text-align:center">
+<h1>Signed in</h1><p>You can close this tab and return to your terminal.</p>`;
+/**
+ * Start the listener. **Await this before opening the browser** — the returned
+ * `redirectUri` is only valid because the port is already bound.
+ */
+export async function startLoopback() {
+    const nonce = randomBytes(16).toString("hex");
+    let settle;
+    let fail;
+    const received = new Promise((res, rej) => {
+        settle = res;
+        fail = rej;
+    });
+    const server = createServer((req, res) => {
+        // The listener exists for exactly one path. Anything else is not ours.
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/cb") {
+            res.writeHead(404, { "cache-control": "no-store" }).end();
+            return;
+        }
+        const code = url.searchParams.get("code");
+        const gotNonce = url.searchParams.get("nonce");
+        if (!gotNonce || gotNonce !== nonce) {
+            // Someone else's callback, or a probe. Do not reveal which.
+            res.writeHead(400, { "cache-control": "no-store" }).end("bad request");
+            return;
+        }
+        if (!code) {
+            res.writeHead(400, { "cache-control": "no-store" }).end("missing code");
+            return;
+        }
+        res
+            .writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            // The code is in this request's URL; no-referrer stops it riding along
+            // to any host the success page might reference.
+            "referrer-policy": "no-referrer",
+            "cache-control": "no-store",
+        })
+            .end(SUCCESS_HTML);
+        settle({ code });
+        close();
+    });
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearTimeout(timer);
+        // ⚠ `close()` alone only stops NEW connections — keep-alive sockets stay
+        // open and keep being served, so the listener would still answer after the
+        // code was delivered. That makes "one shot" nominal rather than real, and it
+        // leaves a local HTTP surface open for the rest of the process's life.
+        // `closeAllConnections` is what actually ends it. Caught by the
+        // "one shot" test, which used a keep-alive fetch and got a 404 instead of a
+        // connection refusal.
+        server.closeAllConnections?.();
+        server.close();
+    };
+    const timer = setTimeout(() => {
+        fail(new Error("timed out waiting for the browser (5 minutes)"));
+        close();
+    }, DEADLINE_MS);
+    // Do not hold the process open on this timer alone.
+    timer.unref?.();
+    // 127.0.0.1 explicitly — NOT `::` and not 0.0.0.0, which would accept the
+    // callback from off-machine.
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const addr = server.address();
+    return {
+        redirectUri: `http://127.0.0.1:${addr.port}/cb`,
+        nonce,
+        received,
+        close,
+    };
+}

package/dist/auth/pkce.js

@@ -0,0 +1,33 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// PKCE (RFC 7636), S256 only.
+//
+// The CLI is a PUBLIC client: it ships to users' machines and holds no secret, so
+// "prove you are the app" is impossible. PKCE proves something weaker and
+// sufficient instead — "you are the same process that STARTED this login."
+//
+// That is exactly the property needed here. The exchange code travels back over
+// a loopback port that any local process could race for. Without PKCE, winning
+// that race is enough to redeem the code; with it, the winner also needs the
+// verifier, which never leaves this process's memory.
+//
+// `plain` is in the RFC and is deliberately not implemented: it makes the
+// challenge equal the verifier, so anyone who observes one has the other, which
+// defeats the entire mechanism. The server refuses anything but S256 too.
+import { createHash, randomBytes } from "node:crypto";
+/** RFC 7636 §4.1: 43–128 chars from the unreserved set. 32 bytes → 43 chars. */
+export function createPkce() {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge, method: "S256" };
+}
+/** base64url without padding — `+/=` are not URL-safe and the RFC forbids `=`. */
+function base64url(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Exported for the test: recompute a challenge the way the server will. */
+export function challengeFor(verifier) {
+    return base64url(createHash("sha256").update(verifier).digest());
+}

package/dist/auth/wire.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+/**
+ * Redeem the exchange code.
+ *
+ * ⚠ NO `device_id`. The server assigns it and returns it. An earlier client
+ * generated one here and sent it, where it was silently ignored — so the client
+ * stored an id that named no row, and `symbols logout` revoked nothing.
+ */
+export function tokenBody(args) {
+    return {
+        code: args.code,
+        code_verifier: args.verifier,
+        next_token_hash: args.nextTokenHash,
+        device_name: args.deviceName,
+        device_platform: args.devicePlatform,
+        client_version: args.clientVersion,
+    };
+}
+/**
+ * Rotate, write-ahead.
+ *
+ * `next_token_hash` names a token the client has ALREADY written to disk, so the
+ * server never has to hand a credential back — which is the capability that made
+ * an earlier `refresh` a session takeover.
+ */
+export function refreshBody(cred, nextTokenHash) {
+    return { refresh_token: cred.refreshToken, next_token_hash: nextTokenHash };
+}
+/**
+ * Revoke this device.
+ *
+ * The refresh token, NOT the device id — the id is an identifier, not a secret,
+ * and accepting it would let anyone who learned one sign that laptop out.
+ */
+export function logoutBody(cred) {
+    return { refresh_token: cred.refreshToken };
+}