@nookplot/mcp 0.4.90 → 0.4.92

package/dist/applyConfig.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `nookplot-mcp apply-config` — redeem + decrypt + apply a Nookplot config
+ * bundle to the user's local Hermes installation.
+ *
+ * This is the final mile of the one-stop-shop installer flow:
+ *
+ *   1. User configured BYOK / model / messaging on the Nookplot web UI.
+ *   2. The browser encrypted it with AES-256-GCM and a random 256-bit key,
+ *      POSTed the ciphertext to `/v1/agent-config/stage`, and got back a
+ *      one-time token.
+ *   3. The install command exposed both as terminal env vars:
+ *        NOOKPLOT_CONFIG_TOKEN=<token>
+ *        NOOKPLOT_CONFIG_KEY=<base64url-encoded key>
+ *   4. The installer bash script calls this command with those values.
+ *
+ * We then:
+ *   - Fetch the ciphertext via GET /v1/agent-config/redeem/:token. The
+ *     gateway deletes the row as it returns the payload, so replays fail.
+ *   - Decrypt locally using the key (which never left the terminal).
+ *   - For each (key, value) pair in the JSON config, run
+ *     `hermes config set KEY VALUE`. Hermes auto-routes secrets (API keys,
+ *     bot tokens) to ~/.hermes/.env and other settings to ~/.hermes/config.yaml.
+ *
+ * @module applyConfig
+ */
+export interface ApplyConfigOptions {
+    /** Opaque token returned by /stage. 64 hex chars. */
+    token: string;
+    /** base64url-encoded AES-256 key. 43 chars (32 bytes, no padding). */
+    key: string;
+    /** Gateway base URL. Defaults to the public gateway. */
+    gatewayUrl?: string;
+    /** Max time per HTTP request in ms. */
+    timeoutMs?: number;
+    /** Override for the Hermes CLI binary. Defaults to `hermes` on PATH. */
+    hermesBin?: string;
+    /**
+     * Target a specific Hermes profile instead of the default. When set,
+     * every `hermes config set ...` becomes `hermes --profile <name>
+     * config set ...`, so the BYOK keys + model + messaging tokens land
+     * in `~/.hermes/profiles/<name>/config.yaml` (isolated from other
+     * forged agents).
+     */
+    profile?: string;
+    /**
+     * Dependency-injection seams for tests — real callers never pass these.
+     * Production code uses global fetch + child_process.execFileSync +
+     * filesystem reads from ~/.nookplot/credentials.json.
+     */
+    _fetch?: typeof fetch;
+    _exec?: (bin: string, args: string[]) => void;
+    _credentialsReader?: () => {
+        apiKey: string;
+    } | null;
+}
+export interface ApplyConfigResult {
+    /** How many hermes-config-set invocations succeeded. */
+    applied: number;
+    /** Keys that could not be applied (with the reason why). */
+    failures: Array<{
+        key: string;
+        error: string;
+    }>;
+    /** The address the bundle was scoped to (comes from the stage payload). */
+    agentAddress: string;
+}
+export declare function isAllowedGatewayBase(candidate: string, installerGatewayUrl: string): boolean;
+/**
+ * Main orchestration: fetch → decrypt → apply. Returns a result with per-key
+ * success/failure so the caller can surface what happened to the user.
+ */
+export declare function applyConfig(opts: ApplyConfigOptions): Promise<ApplyConfigResult>;
+//# sourceMappingURL=applyConfig.d.ts.map

package/dist/applyConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyConfig.d.ts","sourceRoot":"","sources":["../src/applyConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAYH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,KAAK,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC9C,kBAAkB,CAAC,EAAE,MAAM;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,QAAQ,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;CACtB;AAgRD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,OAAO,CAe5F;AAuGD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA4D5B"}

package/dist/applyConfig.js

@@ -0,0 +1,418 @@
+/**
+ * `nookplot-mcp apply-config` — redeem + decrypt + apply a Nookplot config
+ * bundle to the user's local Hermes installation.
+ *
+ * This is the final mile of the one-stop-shop installer flow:
+ *
+ *   1. User configured BYOK / model / messaging on the Nookplot web UI.
+ *   2. The browser encrypted it with AES-256-GCM and a random 256-bit key,
+ *      POSTed the ciphertext to `/v1/agent-config/stage`, and got back a
+ *      one-time token.
+ *   3. The install command exposed both as terminal env vars:
+ *        NOOKPLOT_CONFIG_TOKEN=<token>
+ *        NOOKPLOT_CONFIG_KEY=<base64url-encoded key>
+ *   4. The installer bash script calls this command with those values.
+ *
+ * We then:
+ *   - Fetch the ciphertext via GET /v1/agent-config/redeem/:token. The
+ *     gateway deletes the row as it returns the payload, so replays fail.
+ *   - Decrypt locally using the key (which never left the terminal).
+ *   - For each (key, value) pair in the JSON config, run
+ *     `hermes config set KEY VALUE`. Hermes auto-routes secrets (API keys,
+ *     bot tokens) to ~/.hermes/.env and other settings to ~/.hermes/config.yaml.
+ *
+ * @module applyConfig
+ */
+import { createDecipheriv } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Decode a base64url string (`-` `_`, no padding) to a Buffer.
+ * Web Crypto emits base64url by default, so our browser-side encryption
+ * produces keys in this form.
+ */
+function fromBase64Url(value) {
+    // Convert base64url → base64 by replacing URL-safe chars and
+    // re-padding to a multiple of 4.
+    let b64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = b64.length % 4;
+    if (pad)
+        b64 += "=".repeat(4 - pad);
+    return Buffer.from(b64, "base64");
+}
+/**
+ * Redeem the ciphertext from the gateway. The endpoint deletes the row as
+ * it returns the payload, so replays will 404.
+ */
+async function redeemCiphertext(gatewayUrl, token, fetchFn, timeoutMs) {
+    const url = `${gatewayUrl.replace(/\/$/, "")}/v1/agent-config/redeem/${encodeURIComponent(token)}`;
+    // AbortController gives us a hard ceiling on wait time so a hung
+    // gateway can't freeze the installer.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchFn(url, { signal: controller.signal });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            if (res.status === 404) {
+                throw new Error("Config token not found, already used, or expired. " +
+                    "Regenerate the install command on your agent's Nookplot page.");
+            }
+            throw new Error(`Gateway returned ${res.status}: ${body.slice(0, 200)}`);
+        }
+        const payload = (await res.json());
+        if (typeof payload.ciphertext !== "string" ||
+            typeof payload.iv !== "string" ||
+            typeof payload.authTag !== "string" ||
+            typeof payload.agentAddress !== "string") {
+            throw new Error("Gateway returned an unexpected payload shape.");
+        }
+        return payload;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Decrypt an AES-256-GCM ciphertext. Throws on auth-tag mismatch (i.e.
+ * wrong key or tampered ciphertext).
+ */
+function decryptBundle(stage, key) {
+    if (key.length !== 32) {
+        throw new Error(`AES-256 key must be 32 bytes (got ${key.length}). ` +
+            `Check NOOKPLOT_CONFIG_KEY is the full base64url value.`);
+    }
+    const iv = Buffer.from(stage.iv, "base64");
+    const authTag = Buffer.from(stage.authTag, "base64");
+    const ciphertext = Buffer.from(stage.ciphertext, "base64");
+    if (iv.length !== 12) {
+        throw new Error(`Invalid IV length (${iv.length}) — expected 12 bytes.`);
+    }
+    if (authTag.length !== 16) {
+        throw new Error(`Invalid auth tag length (${authTag.length}) — expected 16 bytes.`);
+    }
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(authTag);
+    let plaintext;
+    try {
+        plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    catch (err) {
+        // Auth-tag failure → either wrong key or tampered bytes. In practice
+        // the first is common (user pasted the wrong install command), the
+        // second means someone was intercepting — either way, bail loud.
+        throw new Error("Decryption failed — auth tag mismatch. " +
+            "This usually means NOOKPLOT_CONFIG_KEY doesn't match the token " +
+            "(regenerate the install command on your agent page).");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        throw new Error("Decrypted payload was not valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Decrypted payload was not a JSON object.");
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+//  Apply to Hermes
+// ---------------------------------------------------------------------------
+/**
+ * Valid Hermes config key shape.
+ *
+ * Hermes accepts:
+ *   - Dotted lowercase keys (e.g. `model.default`, `terminal.backend`)
+ *   - SCREAMING_SNAKE_CASE (auto-routed to ~/.hermes/.env, for API keys)
+ *   - Simple `a-z0-9_` keys for top-level settings
+ *
+ * We gate strictly here because we're about to exec a subprocess: anything
+ * that smells like a shell metachar gets dropped with a recorded failure
+ * rather than quietly becoming an argv surprise.
+ */
+function isValidHermesKey(key) {
+    return /^[A-Za-z][A-Za-z0-9_.]{0,127}$/.test(key);
+}
+/**
+ * Run `hermes config set <key> <value>` for each entry in the config.
+ *
+ * We skip — and record — anything whose value isn't serializable as a flat
+ * string, as well as anything whose key fails our whitelist. The Hermes
+ * CLI itself does the routing between config.yaml (plain settings) and
+ * .env (API keys), so we don't have to duplicate that logic here.
+ */
+function applyToHermes(config, hermesBin, execFn, profile) {
+    let applied = 0;
+    const failures = [];
+    // When a profile is set, every `hermes config set` call is prefixed
+    // with `--profile <name>` so the writes land in
+    // ~/.hermes/profiles/<name>/config.yaml rather than the default
+    // ~/.hermes/config.yaml. This is how multi-agent installs stay
+    // isolated: Agent A's BYOK keys don't clobber Agent B's.
+    const profilePrefix = profile ? ["--profile", profile] : [];
+    for (const [key, rawValue] of Object.entries(config)) {
+        if (!isValidHermesKey(key)) {
+            failures.push({ key, error: "Invalid key format (must match /^[A-Za-z][A-Za-z0-9_.]*$/)" });
+            continue;
+        }
+        // Flatten to string. Booleans/numbers become their textual form;
+        // nested objects are rejected — Hermes uses dotted keys for nesting.
+        let value;
+        if (typeof rawValue === "string") {
+            value = rawValue;
+        }
+        else if (typeof rawValue === "number" || typeof rawValue === "boolean") {
+            value = String(rawValue);
+        }
+        else if (rawValue === null || rawValue === undefined) {
+            failures.push({ key, error: "Value is null or undefined" });
+            continue;
+        }
+        else {
+            failures.push({
+                key,
+                error: "Value must be a string, number, or boolean (use dotted keys for nesting)",
+            });
+            continue;
+        }
+        try {
+            // We pass each arg as a separate argv element — no shell involved,
+            // so there's no shell-injection surface even if `value` contains
+            // funky characters. (Which it will, for API keys.)
+            execFn(hermesBin, [...profilePrefix, "config", "set", key, value]);
+            applied += 1;
+        }
+        catch (err) {
+            failures.push({
+                key,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { applied, failures };
+}
+// ---------------------------------------------------------------------------
+//  Entry point
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+//  Platform-mode expansion
+// ---------------------------------------------------------------------------
+/**
+ * Expand a "platform" mode bundle into concrete Hermes inference config.
+ *
+ * When the user picked "Fast & cheap" or "Smart max-effort" on Forge, the
+ * bundle from the web UI doesn't carry a real API key — those presets use
+ * Nookplot's gateway proxy (OpenAI-compat at /v1/openai/v1/chat/completions),
+ * which charges the user's NOOK balance. The bundle instead carries SENTINEL
+ * keys that signal "expand me locally":
+ *
+ *   __nookplot_inference_mode  = "platform"
+ *   __nookplot_platform_model  = "hermes-3-llama-3.1-8b" (or whichever model)
+ *   __nookplot_gateway_base    = "https://gateway.nookplot.com" (optional)
+ *
+ * This function:
+ *   1. Detects the platform-mode marker.
+ *   2. Reads the user's Nookplot API key from local ~/.nookplot/credentials.json.
+ *      The API key NEVER touches the bundle (so it never lands on the gateway
+ *      staging table or in transit). The web-staged bundle only has the
+ *      metadata above; expansion happens at install time on the user's machine.
+ *   3. Returns a NEW config object with sentinels stripped + gateway-proxy
+ *      Hermes config keys added (model.base_url, OPENAI_API_KEY, model.default).
+ *
+ * Returns the original config unchanged when no platform marker is present —
+ * BYOK + messaging-only bundles continue to work exactly as before.
+ *
+ * Why the indirection vs. just including the API key in the bundle:
+ *   - Bundle ciphertext lands on the gateway briefly (15-minute TTL). Even
+ *     though it's encrypted client-side, fewer copies of the user's API key
+ *     in transit = less attack surface.
+ *   - Bundle is one-time-use; a user re-installing on a new machine would
+ *     need a new bundle. Reading from local creds avoids that round-trip.
+ *   - Future per-agent scoped tokens slot in here without changing the
+ *     bundle protocol.
+ */
+/**
+ * Whitelist of trusted gateway origins for the `__nookplot_gateway_base`
+ * override. This guards against bundle-tamper key exfiltration.
+ *
+ * The installer's own `gatewayUrl` argument is always trusted (it was
+ * baked into the install script by the gateway that served it), so we
+ * also accept any URL whose origin matches `gatewayUrl`'s origin —
+ * that covers staging environments transparently.
+ */
+const TRUSTED_GATEWAY_ORIGINS = new Set([
+    "https://gateway.nookplot.com",
+    "https://gateway-dev.nookplot.com",
+    "http://localhost:8080",
+    "http://localhost:3000",
+    "http://127.0.0.1:8080",
+    "http://127.0.0.1:3000",
+]);
+export function isAllowedGatewayBase(candidate, installerGatewayUrl) {
+    let candidateOrigin;
+    try {
+        candidateOrigin = new URL(candidate).origin;
+    }
+    catch {
+        return false; // malformed URL
+    }
+    if (TRUSTED_GATEWAY_ORIGINS.has(candidateOrigin))
+        return true;
+    // Also accept anything matching the installer's own gateway origin.
+    try {
+        if (new URL(installerGatewayUrl).origin === candidateOrigin)
+            return true;
+    }
+    catch {
+        /* fall through */
+    }
+    return false;
+}
+function expandPlatformInference(config, gatewayUrl, credentialsReader) {
+    const mode = config["__nookplot_inference_mode"];
+    if (mode !== "platform") {
+        // Fast path: nothing to expand. Strip any rogue __nookplot_* keys
+        // anyway so they never reach the Hermes key-validity check.
+        const stripped = {};
+        for (const [k, v] of Object.entries(config)) {
+            if (!k.startsWith("__nookplot_"))
+                stripped[k] = v;
+        }
+        return stripped;
+    }
+    const model = typeof config["__nookplot_platform_model"] === "string"
+        ? config["__nookplot_platform_model"]
+        : null;
+    // The bundle MAY override the gateway base for staging / dev contexts, but
+    // we whitelist the host because this URL becomes `model.base_url` in Hermes
+    // — which means the user's freshly-written `OPENAI_API_KEY` (read from
+    // local credentials) will be sent there on every inference. A bundle that
+    // smuggles `__nookplot_gateway_base: "https://evil.example/..."` would
+    // exfiltrate the user's API key on first call.
+    //
+    // Trust set: production gateway, dev gateway, localhost (development),
+    // plus whatever was passed as `gatewayUrl` (the installer's argument —
+    // already validated upstream). Anything else is silently ignored, falling
+    // back to `gatewayUrl`.
+    const rawBaseOverride = typeof config["__nookplot_gateway_base"] === "string"
+        ? config["__nookplot_gateway_base"]
+        : null;
+    const baseOverride = rawBaseOverride && isAllowedGatewayBase(rawBaseOverride, gatewayUrl)
+        ? rawBaseOverride
+        : null;
+    if (rawBaseOverride && !baseOverride) {
+        console.error(`[nookplot-mcp] Ignoring untrusted __nookplot_gateway_base override (${rawBaseOverride}). Using ${gatewayUrl} instead. ` +
+            `This protects your API key from being sent to an attacker-controlled gateway.`);
+    }
+    // Read local API key. If not found, abort the expansion — the user needs
+    // to register first via `nookplot register` or by deploying their first
+    // agent through the web flow.
+    const creds = credentialsReader();
+    if (!creds || !creds.apiKey) {
+        throw new Error("Platform inference mode requires a registered Nookplot account, " +
+            "but no credentials were found at ~/.nookplot/credentials.json. " +
+            "Run `nookplot register` first, or deploy your first agent on nookplot.com.");
+    }
+    // Build the expanded config. Strip ALL __nookplot_* sentinels so the
+    // downstream Hermes-key validator never sees them.
+    const expanded = {};
+    for (const [k, v] of Object.entries(config)) {
+        if (!k.startsWith("__nookplot_"))
+            expanded[k] = v;
+    }
+    // Trailing-slash-safe base URL. Hermes will append /chat/completions to
+    // model.base_url, so we end at /v1/openai/v1 (path includes the inner /v1
+    // because OpenAI-compat clients expect it — see openaiAdapter.ts mounting).
+    const base = (baseOverride ?? gatewayUrl).replace(/\/+$/, "");
+    expanded["model.base_url"] = `${base}/v1/openai/v1`;
+    // Use OPENAI_API_KEY because the gateway adapter speaks OpenAI's protocol;
+    // Hermes routes auth via the OpenAI provider config when model.base_url
+    // is set. Hermes auto-routes SCREAMING_SNAKE_CASE keys to ~/.hermes/.env
+    // (or the per-profile .env).
+    expanded["OPENAI_API_KEY"] = creds.apiKey;
+    // Default model — only set if the bundle specified one. (Forge always
+    // does, but we don't blow up if it's missing.)
+    if (model && !expanded["model.default"]) {
+        expanded["model.default"] = model;
+    }
+    return expanded;
+}
+/**
+ * Default credentials reader — reads ~/.nookplot/credentials.json and returns
+ * { apiKey } or null. Isolated from applyConfig main logic so tests can
+ * inject a stub without filesystem access.
+ */
+function defaultCredentialsReader() {
+    try {
+        const credsPath = join(homedir(), ".nookplot", "credentials.json");
+        if (!existsSync(credsPath))
+            return null;
+        const raw = readFileSync(credsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.apiKey !== "string" || !parsed.apiKey)
+            return null;
+        return { apiKey: parsed.apiKey };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Main orchestration: fetch → decrypt → apply. Returns a result with per-key
+ * success/failure so the caller can surface what happened to the user.
+ */
+export async function applyConfig(opts) {
+    if (!opts.token || !/^[a-f0-9]{64}$/i.test(opts.token)) {
+        throw new Error("Invalid NOOKPLOT_CONFIG_TOKEN (must be 64 hex chars). " +
+            "Regenerate the install command on your agent's Nookplot page.");
+    }
+    if (!opts.key) {
+        throw new Error("Missing NOOKPLOT_CONFIG_KEY env var.");
+    }
+    const gatewayUrl = opts.gatewayUrl ?? "https://gateway.nookplot.com";
+    const timeoutMs = opts.timeoutMs ?? 15_000;
+    const hermesBin = opts.hermesBin ?? "hermes";
+    const fetchFn = opts._fetch ?? fetch;
+    const execFn = opts._exec ??
+        ((bin, args) => {
+            execFileSync(bin, args, { stdio: "pipe" });
+        });
+    // Parse the key from base64url.
+    let keyBytes;
+    try {
+        keyBytes = fromBase64Url(opts.key);
+    }
+    catch (err) {
+        throw new Error(`Could not decode NOOKPLOT_CONFIG_KEY as base64url: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // 1. Fetch the encrypted bundle (one-time-use token — gateway deletes
+    //    the row as it responds).
+    const stage = await redeemCiphertext(gatewayUrl, opts.token, fetchFn, timeoutMs);
+    // 2. Decrypt locally. Auth-tag failures are surfaced as a clear error
+    //    so the user can regenerate the install command.
+    const config = decryptBundle(stage, keyBytes);
+    // 2b. Expand platform-mode bundles. For Fast/Smart presets, the bundle
+    //     contains __nookplot_* sentinel keys that we resolve locally —
+    //     fetching the user's API key from ~/.nookplot/credentials.json
+    //     (NEVER from the bundle) and rewriting to concrete model.base_url
+    //     + OPENAI_API_KEY + model.default config that points Hermes at
+    //     our gateway's OpenAI-compat adapter.
+    //
+    //     For BYOK + messaging-only bundles this is a no-op (just strips
+    //     any rogue __nookplot_* keys defensively).
+    const credsReader = opts._credentialsReader ?? defaultCredentialsReader;
+    const expanded = expandPlatformInference(config, gatewayUrl, credsReader);
+    // 3. Apply each entry via `hermes config set`. Hermes routes secrets
+    //    to .env and other settings to config.yaml.
+    const { applied, failures } = applyToHermes(expanded, hermesBin, execFn, opts.profile);
+    return {
+        applied,
+        failures,
+        agentAddress: stage.agentAddress,
+    };
+}
+//# sourceMappingURL=applyConfig.js.map

package/dist/applyConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyConfig.js","sourceRoot":"","sources":["../src/applyConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAuDjC;;;;GAIG;AACH,SAAS,aAAa,CAAC,KAAa;IAClC,6DAA6D;IAC7D,iCAAiC;IACjC,IAAI,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3B,IAAI,GAAG;QAAE,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,gBAAgB,CAC7B,UAAkB,EAClB,KAAa,EACb,OAAqB,EACrB,SAAiB;IAEjB,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,2BAA2B,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;IAEnG,iEAAiE;IACjE,sCAAsC;IACtC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9C,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CACb,oDAAoD;oBACpD,+DAA+D,CAChE,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,oBAAoB,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAkB,CAAC;QACpD,IACE,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;YACtC,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ;YAC9B,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;YACnC,OAAO,OAAO,CAAC,YAAY,KAAK,QAAQ,EACxC,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa,CACpB,KAAoB,EACpB,GAAW;IAEX,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,qCAAqC,GAAG,CAAC,MAAM,KAAK;YACpD,wDAAwD,CACzD,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAE3D,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,sBAAsB,EAAE,CAAC,MAAM,wBAAwB,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,4BAA4B,OAAO,CAAC,MAAM,wBAAwB,CAAC,CAAC;IACtF,CAAC;IAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,aAAa,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC1D,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAE7B,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC7E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qEAAqE;QACrE,mEAAmE;QACnE,iEAAiE;QACjE,MAAM,IAAI,KAAK,CACb,yCAAyC;YACzC,iEAAiE;YACjE,sDAAsD,CACvD,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,OAAO,gCAAgC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CACpB,MAA+B,EAC/B,SAAiB,EACjB,MAA6C,EAC7C,OAAgB;IAEhB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,QAAQ,GAA0C,EAAE,CAAC;IAE3D,oEAAoE;IACpE,gDAAgD;IAChD,gEAAgE;IAChE,+DAA+D;IAC/D,yDAAyD;IACzD,MAAM,aAAa,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5D,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,4DAA4D,EAAE,CAAC,CAAC;YAC5F,SAAS;QACX,CAAC;QAED,iEAAiE;QACjE,qEAAqE;QACrE,IAAI,KAAa,CAAC;QAClB,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,KAAK,GAAG,QAAQ,CAAC;QACnB,CAAC;aAAM,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzE,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAC;YAC5D,SAAS;QACX,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC;gBACZ,GAAG;gBACH,KAAK,EAAE,0EAA0E;aAClF,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,mEAAmE;YACnE,iEAAiE;YACjE,mDAAmD;YACnD,MAAM,CAAC,SAAS,EAAE,CAAC,GAAG,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;YACnE,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC;gBACZ,GAAG;gBACH,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;GAQG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAS;IAC9C,8BAA8B;IAC9B,kCAAkC;IAClC,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;CACxB,CAAC,CAAC;AAEH,MAAM,UAAU,oBAAoB,CAAC,SAAiB,EAAE,mBAA2B;IACjF,IAAI,eAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,eAAe,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,gBAAgB;IAChC,CAAC;IACD,IAAI,uBAAuB,CAAC,GAAG,CAAC,eAAe,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9D,oEAAoE;IACpE,IAAI,CAAC;QACH,IAAI,IAAI,GAAG,CAAC,mBAAmB,CAAC,CAAC,MAAM,KAAK,eAAe;YAAE,OAAO,IAAI,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,uBAAuB,CAC9B,MAA+B,EAC/B,UAAkB,EAClB,iBAAkD;IAElD,MAAM,IAAI,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,kEAAkE;QAClE,4DAA4D;QAC5D,MAAM,QAAQ,GAA4B,EAAE,CAAC;QAC7C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5C,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC;gBAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,MAAM,CAAC,2BAA2B,CAAC,KAAK,QAAQ;QACnE,CAAC,CAAE,MAAM,CAAC,2BAA2B,CAAY;QACjD,CAAC,CAAC,IAAI,CAAC;IACT,2EAA2E;IAC3E,4EAA4E;IAC5E,uEAAuE;IACvE,0EAA0E;IAC1E,uEAAuE;IACvE,+CAA+C;IAC/C,EAAE;IACF,uEAAuE;IACvE,uEAAuE;IACvE,0EAA0E;IAC1E,wBAAwB;IACxB,MAAM,eAAe,GAAG,OAAO,MAAM,CAAC,yBAAyB,CAAC,KAAK,QAAQ;QAC3E,CAAC,CAAE,MAAM,CAAC,yBAAyB,CAAY;QAC/C,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,YAAY,GAAG,eAAe,IAAI,oBAAoB,CAAC,eAAe,EAAE,UAAU,CAAC;QACvF,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,eAAe,IAAI,CAAC,YAAY,EAAE,CAAC;QACrC,OAAO,CAAC,KAAK,CACX,uEAAuE,eAAe,YAAY,UAAU,YAAY;YACxH,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,wEAAwE;IACxE,8BAA8B;IAC9B,MAAM,KAAK,GAAG,iBAAiB,EAAE,CAAC;IAClC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,kEAAkE;YAClE,iEAAiE;YACjE,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,mDAAmD;IACnD,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC;YAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,wEAAwE;IACxE,0EAA0E;IAC1E,4EAA4E;IAC5E,MAAM,IAAI,GAAG,CAAC,YAAY,IAAI,UAAU,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,GAAG,GAAG,IAAI,eAAe,CAAC;IAEpD,2EAA2E;IAC3E,wEAAwE;IACxE,yEAAyE;IACzE,6BAA6B;IAC7B,QAAQ,CAAC,gBAAgB,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;IAE1C,sEAAsE;IACtE,+CAA+C;IAC/C,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACxC,QAAQ,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC;IACpC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAS,wBAAwB;IAC/B,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,kBAAkB,CAAC,CAAC;QACnE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;QACvD,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;QACrE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB;IAExB,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CACb,wDAAwD;YACxD,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,8BAA8B,CAAC;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;IACrC,MAAM,MAAM,GACV,IAAI,CAAC,KAAK;QACV,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YACb,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IAEL,gCAAgC;IAChC,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,sDAAsD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACzG,CAAC;IACJ,CAAC;IAED,sEAAsE;IACtE,8BAA8B;IAC9B,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAEjF,sEAAsE;IACtE,qDAAqD;IACrD,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE9C,uEAAuE;IACvE,oEAAoE;IACpE,oEAAoE;IACpE,uEAAuE;IACvE,oEAAoE;IACpE,2CAA2C;IAC3C,EAAE;IACF,qEAAqE;IACrE,gDAAgD;IAChD,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,IAAI,wBAAwB,CAAC;IACxE,MAAM,QAAQ,GAAG,uBAAuB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;IAE1E,qEAAqE;IACrE,gDAAgD;IAChD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,aAAa,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvF,OAAO;QACL,OAAO;QACP,QAAQ;QACR,YAAY,EAAE,KAAK,CAAC,YAAY;KACjC,CAAC;AACJ,CAAC"}

package/dist/auth.d.ts

@@ -1,7 +1,21 @@
 /**
  * Credential management for the Nookplot MCP server.
  *
- * Stores credentials in ~/.nookplot/credentials.json (chmod 600).
+ * Single source of API-key truth lives at `~/.nookplot/credentials.json`
+ * (chmod 600) — creator's API key, private key, gateway URL. Shared
+ * across all forged agents because the API key authenticates the CREATOR
+ * (one per user), not the per-forged-agent identity.
+ *
+ * Multi-agent scoping lives in per-profile files:
+ *   `~/.nookplot/profiles/<name>/profile.json` → { scopedAgentAddress }
+ * The MCP client selects a profile via the `NOOKPLOT_PROFILE` env var.
+ * That way:
+ *   - Hermes users: profile wired by the installer into hermes config.yaml
+ *     as `env.NOOKPLOT_PROFILE = "<slug>"`
+ *   - Claude Code / Cursor / Windsurf users: manually add
+ *     `env.NOOKPLOT_PROFILE = "<slug>"` to their MCP config
+ *   - CLI users: `NOOKPLOT_PROFILE=<slug> nookplot <cmd>` or
+ *     `nookplot --profile <slug> <cmd>` (set via CLI layer)
  *
  * @module auth
  */
@@ -11,12 +25,117 @@ export interface NookplotCredentials {
     address: string;
     gatewayUrl: string;
     displayName?: string;
+    /**
+     * Present only when credentials were loaded through a profile.
+     * Set from `~/.nookplot/profiles/<name>/profile.json::scopedAgentAddress`.
+     * The server context reads this to populate `ctx.scopedAgentAddress`
+     * for tools that forward it to the gateway (capture tools, etc.).
+     *
+     * Overridden by `NOOKPLOT_AGENT_ADDRESS` env var if that's set.
+     */
+    scopedAgentAddress?: string;
+    /** Name of the profile the creds were loaded through, for logging. */
+    profileName?: string;
+}
+/** Per-profile metadata file (just scope, not creds). */
+export interface NookplotProfile {
+    scopedAgentAddress: string;
+    /** Optional display name of the forged agent, for nicer log output. */
+    displayName?: string;
+    /** Optional Hermes profile name if this was installed via the Hermes flow. */
+    hermesProfile?: string;
+    /** When the profile was created (ISO). For `nookplot profile list`. */
+    createdAt?: string;
 }
+/** Path to a specific profile's metadata file. */
+export declare function profilePath(profileName: string): string;
+/** Path to the root profiles dir (where all profiles live). */
+export declare function profilesDir(): string;
+/**
+ * Load credentials — profile-aware.
+ *
+ * Resolution order (first match wins):
+ *   1. `NOOKPLOT_PROFILE` env var → `~/.nookplot/profiles/<name>/profile.json`
+ *      merged with default `credentials.json`. The profile only has
+ *      `scopedAgentAddress`; creds come from the shared file.
+ *   2. Default `~/.nookplot/credentials.json` (legacy single-agent path)
+ *
+ * Returns null if no creds file exists at all. Invalid profile name or
+ * missing profile.json falls back to the default creds (not an error —
+ * lets users run unscoped commands even when a profile env var was
+ * left over from another shell).
+ */
+export declare function loadCredentials(opts?: {
+    profile?: string;
+}): NookplotCredentials | null;
+/**
+ * Load a profile's metadata file (`profile.json`). Returns null if the
+ * profile doesn't exist or the file is malformed. Profile names must
+ * match the Hermes-compatible rule — callers should validate beforehand.
+ */
+export declare function loadProfile(profileName: string): NookplotProfile | null;
+/**
+ * Save (or overwrite) a profile's metadata file. Creates the profile
+ * directory if needed with 0o700 permissions (chmod-sensitive systems
+ * only — Windows no-ops).
+ *
+ * Callers:
+ *   - Installer bash writes this after apply-config
+ *   - CLI `nookplot profile create` writes this
+ *   - SDK helpers for programmatic profile setup
+ */
+export declare function saveProfile(profileName: string, profile: NookplotProfile): void;
+/**
+ * Result of a safeSaveProfile call. Three outcomes: a new profile was
+ * created, an existing same-address profile was re-written (idempotent),
+ * or a collision was detected (different address for same name).
+ */
+export type SafeSaveProfileResult = {
+    kind: "created";
+    profileName: string;
+} | {
+    kind: "updated";
+    profileName: string;
+    previousCreatedAt?: string;
+} | {
+    kind: "collision";
+    profileName: string;
+    existingAddress: string;
+    attemptedAddress: string;
+};
+/**
+ * Safer wrapper around `saveProfile` that detects slug collisions before
+ * overwriting. Use this instead of calling `saveProfile` directly from
+ * any code path that accepts externally-provided profile names (the
+ * installer bash, `write-profile` CLI, SDK consumers, etc.).
+ *
+ * Why: two forged agents whose display names slugify to the same string
+ * (e.g. "Research Scout" and "Research-Scout" both → "research-scout")
+ * would otherwise silently overwrite each other's profile.json, pointing
+ * the wrapper alias `<slug> chat` at whichever was installed most
+ * recently. The user has no signal the first install was orphaned.
+ *
+ * Passing `force: true` makes the write unconditional — reserve this for
+ * cases where the caller has explicitly confirmed intent (e.g. the user
+ * typed `write-profile --force`).
+ *
+ * Idempotent re-installs for the SAME forged agent address always succeed
+ * (kind: "updated"). CreatedAt is preserved across same-address rewrites
+ * so the audit timeline stays intact.
+ */
+export declare function safeSaveProfile(profileName: string, profile: NookplotProfile, opts?: {
+    force?: boolean;
+}): SafeSaveProfileResult;
 /**
- * Load credentials from ~/.nookplot/credentials.json.
- * Returns null if the file doesn't exist.
+ * List every profile that has a valid profile.json. Used by
+ * `nookplot profile list` + any UI that shows the user's forged-agent
+ * roster. Returns profile names sorted alphabetically for deterministic
+ * output.
  */
-export declare function loadCredentials(): NookplotCredentials | null;
+export declare function listProfiles(): Array<{
+    name: string;
+    profile: NookplotProfile;
+}>;
 /**
  * Save credentials to ~/.nookplot/credentials.json with restrictive permissions.
  */

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,mBAAmB,GAAG,IAAI,CAoB5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAWhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI,GAAG,MAAM,CAIxE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiDH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD,kDAAkD;AAClD,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AA2BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,mBAAmB,GAAG,IAAI,CAmCvF;AAmDD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAgBvE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAe/E;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,qBAAqB,CA8BvB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC,CAiBhF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CA4BhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI,GAAG,MAAM,CAIxE"}