@bluenotelogic/harness 0.1.0

package/dist/index.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+/**
+ * bnl-harness — point this machine at Blue Note Memory in one command.
+ *
+ *     npx @bluenotelogic/harness init
+ *
+ * THE PROBLEM THIS SOLVES: configuring a machine used to mean pasting a bearer token by
+ * hand into `.mcp.json`, `~/.claude.json`, `~/.codex/config.toml` and a VS Code roaming
+ * profile — and rotating anything meant editing every one of them again.
+ *
+ * THE IMPORTANT PART — the `.mcp.json` this writes carries NO TOKEN:
+ *
+ *     { "mcpServers": { "mem": { "type": "http", "url": "https://mem.bnlgit.com/mcp" } } }
+ *
+ * OAuth-capable hosts (Claude Code, VS Code) discover auth from the endpoint's 401 +
+ * WWW-Authenticate, run the browser flow against Blue Note ID, and store their own
+ * credentials. Nothing secret is written into a repo file, so the file is safe to commit
+ * and there is nothing to rotate.
+ *
+ * Codex and CI cannot do that yet, so `--mint-token` exists for them — and it writes the
+ * token to `~/.codex/.env`, never into a repo. Minting is OPT-IN precisely so the default
+ * path creates no credential and no database row.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { discover, registerClient, authorizeViaBrowser, authorizeViaDevice, } from "./oauth.js";
+import { exchangeForTenantToken, fetchBundle, SubscriptionRequiredError, } from "./bundle.js";
+import { planMcpJson, planSettingsLocal, planCodexConfig, planEnvVar, planRoutingFile, assertNoSecret, readIfExists, isNoop, apply, } from "./writers.js";
+const DEFAULT_BASE_URL = "https://mem.bnlgit.com";
+const DEFAULT_CLIENT_ID = "blue-note-mem-mcp";
+/**
+ * `blue_note_identity`, NOT `email`. The two are easy to confuse and the failure is silent
+ * until the very last step:
+ *
+ * The `blue-note-mem-mcp` provider has exactly four scope mappings attached — openid, profile,
+ * offline_access and blue_note_identity. The stock `email` mapping is deliberately NOT among
+ * them, and Authentik ignores a scope it has no mapping for rather than refusing it. So asking
+ * for `email` succeeded all the way through consent and the code exchange, then produced a
+ * userinfo document with no `email_verified`, which `/api/oidc_exchange.php` rejects as
+ * "A verified email is required" — surfaced to the user as a 401 that reads like a bad token.
+ *
+ * `blue_note_identity` ("Blue Note verified identity") is the mapping that supplies email and
+ * email_verified. This matches what the browser login has always requested — see
+ * BlueNoteOidc.php:201 in caveau-mem, which is the same identity resolution this trades into.
+ */
+const DEFAULT_SCOPE = "openid profile blue_note_identity offline_access";
+const TOKEN_ENV_VAR = "BNL_MEMORY_MCP_TOKEN";
+/**
+ * `--timeout`, in seconds. Refused rather than coerced: a typo'd `--timeout abc` silently
+ * becoming NaN — and therefore an instant timeout — would be a second, quieter version of the
+ * exact failure this flag exists to fix.
+ */
+function parseTimeout(raw) {
+    const sec = Number(raw);
+    if (!Number.isInteger(sec) || sec < 30 || sec > 3600) {
+        fail(`--timeout wants whole seconds between 30 and 3600, got: ${raw}`);
+    }
+    return sec * 1000;
+}
+function parseArgs(argv) {
+    const opts = {
+        baseUrl: DEFAULT_BASE_URL,
+        dir: process.cwd(),
+        dryRun: false,
+        device: false,
+        token: null,
+        mintToken: false,
+        harnessHome: null,
+        serverName: null,
+        clientId: DEFAULT_CLIENT_ID,
+        openBrowser: true,
+        codex: false,
+        timeoutMs: null,
+    };
+    let command = "init";
+    const rest = [...argv];
+    if (rest[0] && !rest[0].startsWith("-"))
+        command = rest.shift();
+    while (rest.length) {
+        const arg = rest.shift();
+        const next = () => {
+            const v = rest.shift();
+            if (v === undefined)
+                fail(`${arg} needs a value`);
+            return v;
+        };
+        switch (arg) {
+            case "--url":
+                opts.baseUrl = next().replace(/\/$/, "");
+                break;
+            case "--dir":
+                opts.dir = resolve(next());
+                break;
+            case "--dry-run":
+                opts.dryRun = true;
+                break;
+            case "--device":
+                opts.device = true;
+                break;
+            case "--token":
+                opts.token = next();
+                break;
+            case "--mint-token":
+                opts.mintToken = true;
+                break;
+            case "--codex":
+                opts.codex = true;
+                opts.mintToken = true;
+                break;
+            case "--harness-home":
+                opts.harnessHome = resolve(next());
+                break;
+            case "--server-name":
+                opts.serverName = next();
+                break;
+            case "--client-id":
+                opts.clientId = next();
+                break;
+            case "--no-browser":
+                opts.openBrowser = false;
+                break;
+            case "--timeout":
+                opts.timeoutMs = parseTimeout(next());
+                break;
+            case "-h":
+            case "--help":
+                command = "help";
+                break;
+            case "-v":
+            case "--version":
+                command = "version";
+                break;
+            default: fail(`unknown argument: ${arg}\nRun \`bnl-harness --help\`.`);
+        }
+    }
+    return { command, opts };
+}
+const HELP = `
+bnl-harness — configure this machine for Blue Note Memory
+
+  npx @bluenotelogic/harness init [options]
+
+Options
+  --url <base>          Server base URL (default ${DEFAULT_BASE_URL})
+  --dir <path>          Repo to configure (default: current directory)
+  --dry-run             Show every file that would change; write nothing
+  --device              Device-code login, for headless boxes and SSH sessions
+  --token <token>       Use an existing cmem_ token instead of logging in (CI)
+  --mint-token          Also mint a token for hosts that cannot do OAuth
+  --codex               Configure Codex too (implies --mint-token)
+  --harness-home <dir>  Also materialize hosted routing into <dir>/state/routing/
+  --server-name <name>  Override the MCP server key written into .mcp.json
+  --client-id <id>      OAuth client_id (default ${DEFAULT_CLIENT_ID})
+  --no-browser          Print the login URL instead of opening a browser
+  --timeout <seconds>   How long to wait for you to sign in (default 300, max 3600).
+                        With --device the server's own device-code lifetime still wins.
+  -h, --help            This text
+  -v, --version         Version
+
+By default nothing secret is written: Claude Code and VS Code authenticate over OAuth and
+keep their own credentials, so the .mcp.json this produces is safe to commit.
+`;
+async function main() {
+    const { command, opts } = parseArgs(process.argv.slice(2));
+    if (command === "help") {
+        console.log(HELP.trim());
+        return;
+    }
+    if (command === "version") {
+        console.log(await version());
+        return;
+    }
+    if (command !== "init")
+        fail(`unknown command: ${command}\nRun \`bnl-harness --help\`.`);
+    const bundle = await getBundle(opts);
+    const changes = planAll(bundle, opts);
+    report(changes, opts, bundle);
+    for (const c of changes)
+        assertNoSecret2(c, opts);
+    apply(changes, opts.dryRun);
+    if (!opts.dryRun)
+        printNextSteps(bundle, opts, changes);
+}
+/** Authenticate (unless given a token) and fetch the bundle. */
+async function getBundle(opts) {
+    if (opts.token) {
+        log(`Using the token supplied on the command line (skipping login).`);
+        return fetchBundle(opts.baseUrl, opts.token, { mintToken: opts.mintToken });
+    }
+    log(`Discovering ${opts.baseUrl}…`);
+    const meta = await discover(opts.baseUrl);
+    const clientId = await registerClient(meta, opts.clientId);
+    const tokens = opts.device
+        ? await authorizeViaDevice({
+            meta, clientId, scope: DEFAULT_SCOPE, resource: `${opts.baseUrl}/mcp`,
+            timeoutMs: opts.timeoutMs ?? undefined, log,
+        })
+        : await authorizeViaBrowser({
+            meta, clientId, scope: DEFAULT_SCOPE, resource: `${opts.baseUrl}/mcp`,
+            timeoutMs: opts.timeoutMs ?? undefined, openBrowser: opts.openBrowser, log,
+        });
+    log("Signed in. Resolving your memory tenant…");
+    let tenantToken;
+    try {
+        tenantToken = await exchangeForTenantToken(opts.baseUrl, tokens.access_token);
+    }
+    catch (e) {
+        if (e instanceof SubscriptionRequiredError) {
+            // Authenticated fine — they just do not have the product. Say that, and say where to
+            // go, rather than leaving them re-trying a login that already worked.
+            fail(`${e.message}\n\n` +
+                `Your Blue Note Account signed in successfully — it just has no Blue Note Memory\n` +
+                `subscription attached. Start one at ${opts.baseUrl}/pricing.php`);
+        }
+        throw e;
+    }
+    return fetchBundle(opts.baseUrl, tenantToken, { mintToken: opts.mintToken });
+}
+/** Everything this run would write, as data. Nothing here touches the filesystem twice. */
+function planAll(bundle, opts) {
+    const changes = [];
+    // --- The tokenless repo config: the whole point of the tool. --------------------------
+    let servers = bundle.mcp_json.mcpServers;
+    if (opts.serverName) {
+        const [firstKey] = Object.keys(servers);
+        if (firstKey)
+            servers = { [opts.serverName]: servers[firstKey] };
+    }
+    const mcpPath = join(opts.dir, ".mcp.json");
+    changes.push(planMcpJson(mcpPath, readIfExists(mcpPath), servers));
+    // --- Optional: a real credential, for hosts that cannot do OAuth. ---------------------
+    const minted = bundle.token?.value;
+    if (minted) {
+        const codexHome = process.env["CODEX_HOME"] ?? join(homedir(), ".codex");
+        const serverName = opts.serverName ?? Object.keys(servers)[0] ?? "mem";
+        if (opts.codex) {
+            const cfg = join(codexHome, "config.toml");
+            changes.push(planCodexConfig(cfg, readIfExists(cfg), serverName, bundle.endpoint.mcp_url, TOKEN_ENV_VAR));
+        }
+        const envPath = join(codexHome, ".env");
+        changes.push(planEnvVar(envPath, readIfExists(envPath), TOKEN_ENV_VAR, minted));
+        // The VS Code extension launches `claude` without a shell, so an env block in
+        // settings.local.json is what makes a token-based setup work from the editor button.
+        const settings = join(opts.dir, ".claude", "settings.local.json");
+        changes.push(planSettingsLocal(settings, readIfExists(settings), { [TOKEN_ENV_VAR]: minted }));
+    }
+    // --- Optional: materialize the hosted routing the console edits. -----------------------
+    if (opts.harnessHome && bundle.routing) {
+        const dir = join(opts.harnessHome, "state", "routing");
+        if (bundle.routing.providers_yaml) {
+            const p = join(dir, "providers.server.yaml");
+            changes.push(planRoutingFile(p, readIfExists(p), bundle.routing.providers_yaml));
+        }
+        if (bundle.routing.profiles_yaml) {
+            const p = join(dir, "profiles.server.yaml");
+            changes.push(planRoutingFile(p, readIfExists(p), bundle.routing.profiles_yaml));
+        }
+    }
+    return changes;
+}
+/**
+ * The secret guard applies to REPO files only. `~/.codex/.env` and
+ * `.claude/settings.local.json` are where a minted token is supposed to live — asserting
+ * against them would forbid the very thing `--mint-token` is for.
+ */
+function assertNoSecret2(c, opts) {
+    const credentialStores = [
+        join(opts.dir, ".claude", "settings.local.json"),
+        join(process.env["CODEX_HOME"] ?? join(homedir(), ".codex"), ".env"),
+    ];
+    if (credentialStores.includes(c.path))
+        return;
+    assertNoSecret(c);
+}
+function report(changes, opts, bundle) {
+    console.log("");
+    console.log(`  tenant   ${bundle.tenant.slug || bundle.tenant.id}`);
+    console.log(`  endpoint ${bundle.endpoint.mcp_url}`);
+    if (bundle.routing?.source)
+        console.log(`  routing  ${bundle.routing.source}`);
+    console.log("");
+    for (const c of changes) {
+        if (c.skipped) {
+            console.log(`  SKIP   ${c.path}\n         ${c.skipped.replace(/\n/g, "\n         ")}`);
+            continue;
+        }
+        if (isNoop(c)) {
+            console.log(`  same   ${c.path}`);
+            continue;
+        }
+        console.log(`  ${c.before === null ? "create" : "update"} ${c.path}`);
+        if (opts.dryRun && c.after) {
+            const body = c.after.split("\n").map((l) => `         │ ${l}`).join("\n");
+            console.log(body.replace(/\n\s+│\s*$/, ""));
+        }
+    }
+    console.log("");
+    if (opts.dryRun)
+        console.log("  --dry-run: nothing was written.\n");
+}
+function printNextSteps(bundle, opts, changes) {
+    const oauth = !bundle.token;
+    console.log("Done.\n");
+    if (oauth) {
+        console.log("  Your .mcp.json carries no token — Claude Code and VS Code will authenticate");
+        console.log("  over OAuth on first use and keep their own credentials. It is safe to commit.\n");
+    }
+    console.log(`  1. Open ${opts.dir} in Claude Code or VS Code`);
+    console.log(`  2. The '${Object.keys(bundle.mcp_json.mcpServers)[0]}' server appears automatically`);
+    if (bundle.token) {
+        console.log(`  3. A token was minted into ${TOKEN_ENV_VAR} — it is in your Codex env file, not this repo`);
+    }
+    const notes = changes.filter((c) => c.note && !isNoop(c));
+    if (notes.length) {
+        console.log("");
+        for (const c of notes)
+            console.log(`  NOTE ${c.path}: ${c.note}`);
+    }
+    console.log("");
+}
+async function version() {
+    try {
+        const pkg = await import("node:fs").then((fs) => JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")));
+        return String(pkg.version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function log(msg) {
+    console.log(msg);
+}
+function fail(msg) {
+    console.error(`\nbnl-harness: ${msg}\n`);
+    process.exit(1);
+}
+main().catch((e) => {
+    fail(e instanceof Error ? e.message : String(e));
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/oauth.d.ts

@@ -0,0 +1,96 @@
+/**
+ * OAuth 2.1 client for Blue Note Memory — authorization-code + PKCE over a loopback
+ * redirect, with a device-code fallback for headless machines.
+ *
+ * WHY LOOPBACK AND NOT A FIXED PORT: this is a public native client, so RFC 8252 §7.3
+ * applies — bind an ephemeral port and register a regex redirect. The `blue-note-mem-mcp`
+ * client on Blue Note ID already has `http://(127\.0\.0\.1|localhost):[0-9]{1,5}/.*`
+ * registered for exactly this. A fixed port would collide with whatever else is running.
+ *
+ * WHY WE STILL CALL /register: Authentik has no RFC 7591 dynamic client registration, so
+ * mem-mcp serves a shim that hands back the pre-registered public client_id. Calling it is
+ * the spec-correct discovery path and costs one request; `--client-id` skips it.
+ *
+ * NO CLIENT SECRET ANYWHERE. A public client cannot keep one, which is the whole point:
+ * PKCE is what binds the authorization code to this process.
+ */
+/** Endpoints as advertised by the resource + authorization-server metadata documents. */
+export interface AsMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    device_authorization_endpoint?: string;
+    registration_endpoint?: string;
+    code_challenge_methods_supported?: string[];
+}
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/**
+ * PKCE S256. The verifier is 32 random bytes base64url-encoded (43 chars — comfortably
+ * inside RFC 7636's 43..128 range); the challenge is its SHA-256, also base64url.
+ */
+export declare function createPkce(): PkcePair;
+export declare function base64url(buf: Buffer): string;
+/**
+ * Constant-time compare for the `state` parameter. Not strictly required — state is an
+ * integrity check, not a secret — but a length-independent comparison keeps the callback
+ * handler free of an early-exit oracle, and it costs nothing.
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Every discovered endpoint must be https and live on the same host as the issuer, and
+ * must not smuggle credentials in the userinfo part. Same rule the PHP side applies in
+ * lib/Auth/BlueNoteOidc.php — a metadata document is attacker-influencable input, so a
+ * redirected authorization_endpoint is a credential-phishing primitive if left unchecked.
+ *
+ * Loopback (http://127.0.0.1) is exempt because that is our OWN redirect target, never a
+ * discovered endpoint.
+ */
+export declare function assertSafeEndpoint(url: string, issuer: string, what: string): void;
+/**
+ * RFC 9728 protected-resource metadata -> RFC 8414 authorization-server metadata.
+ *
+ * The resource document is what a spec-compliant MCP client finds from the endpoint's
+ * `401 + WWW-Authenticate: Bearer resource_metadata="..."`. We follow the same chain
+ * rather than hardcoding paths, so a self-hosted deployment works with only `--url`.
+ */
+export declare function discover(baseUrl: string): Promise<AsMetadata>;
+/** The DCR shim. Any failure falls back to the caller's default client_id. */
+export declare function registerClient(meta: AsMetadata, fallbackClientId: string): Promise<string>;
+export interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+}
+/**
+ * Browser flow. Resolves with an access token, or rejects on timeout / user denial.
+ *
+ * The listener binds 127.0.0.1 EXPLICITLY (not 0.0.0.0) so nothing off-box can reach the
+ * callback, and it shuts down the moment it has an answer — a lingering listener holding a
+ * valid `state` is a needless window.
+ */
+export declare function authorizeViaBrowser(opts: {
+    meta: AsMetadata;
+    clientId: string;
+    scope: string;
+    resource: string;
+    timeoutMs?: number;
+    openBrowser?: boolean;
+    log?: (msg: string) => void;
+}): Promise<TokenResponse>;
+/**
+ * Device-code flow — for a headless box, an SSH session, or any machine where opening a
+ * browser is not possible. Authentik supports this grant natively and `blue-note-mem-mcp`
+ * already has it enabled, so there is no server-side work behind this path.
+ */
+export declare function authorizeViaDevice(opts: {
+    meta: AsMetadata;
+    clientId: string;
+    scope: string;
+    resource: string;
+    timeoutMs?: number;
+    log?: (msg: string) => void;
+}): Promise<TokenResponse>;