@securespoon/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,64 @@
+# @securespoon/sdk
+
+Typed client and CLI for the [SecureSpoon](https://securespoon.com) governed
+control plane. Zero dependencies; Node 18+ (uses the global `fetch`).
+
+SecureSpoon's server-side AND-gate does all enforcement — an SDK call can do
+exactly what its API key's access scopes allow (`read` / `run` / `manage`),
+never more, and never anything admin-only. The client adds no privilege; it
+only speaks the protocol.
+
+## Install
+
+```bash
+npm install @securespoon/sdk
+```
+
+## Getting a key
+
+Console → **Settings → API keys** → create. The secret (`ss_live_…`) is shown
+**once**; the server stores only a hash. Pick the narrowest scopes that work:
+
+| scope    | grants |
+|----------|--------|
+| `read`   | read-only across the workspace + verifying receipts |
+| `run`    | asking agents; running workflows, applications, MCP tools, triggers |
+| `manage` | everything an operator can do (never admin) |
+
+## Client
+
+```ts
+import { SecureSpoon } from "@securespoon/sdk";
+
+const client = new SecureSpoon({
+  apiKey: process.env.SECURESPOON_API_KEY,
+  baseUrl: "https://console.example.com",
+});
+
+const turn = await client.ask({ agent: "support-copilot", question: "Status of order 10432?" });
+console.log(turn.answer, turn.risk?.label);
+
+const receipts = await client.receipts.list();
+const verdict = await client.receipts.verify(receipts[0]); // server-side re-sign + compare
+```
+
+Errors throw `SecureSpoonError` with `.status` (401 bad/expired key, 403 out
+of scope, 400 invalid input) and `.messages` (the server's own words).
+
+## CLI — `securespoon` (ships in this package)
+
+```
+securespoon login                      # paste console URL + key; verified, then saved 0600
+securespoon ask "…" --agent support-copilot
+securespoon servers                    # includes each server's red-team verdict
+securespoon servers redteam <id>       # exit 0 = passed, 1 = findings
+securespoon receipts verify <id>       # exit 0 = signature valid
+securespoon keys
+```
+
+Config lives in `~/.securespoon.json` (written `0600`). Environment overrides
+for CI: `SECURESPOON_API_KEY`, `SECURESPOON_BASE_URL`, `SECURESPOON_CONFIG`.
+
+## License
+
+Apache-2.0

package/bin/securespoon.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ *  securespoon — CLI over @securespoon/sdk.
+ *
+ *  Auth: `securespoon login` stores the console URL + API key in
+ *  ~/.securespoon.json (0600). SECURESPOON_API_KEY / SECURESPOON_BASE_URL
+ *  override the stored config; SECURESPOON_CONFIG relocates the file (CI).
+ *  The key is minted in the console (Settings → API keys) and shown once —
+ *  the CLI never sees or stores anything the server could re-reveal.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { SecureSpoon, SecureSpoonError } from "../src/index.mjs";
+
+const CONFIG_PATH = process.env.SECURESPOON_CONFIG ?? path.join(os.homedir(), ".securespoon.json");
+
+const HELP = `securespoon — the SecureSpoon control-plane CLI
+
+USAGE
+  securespoon login [--url <console-url>] [--key <api-key>]
+  securespoon whoami
+  securespoon ask "<question>" [--agent <agent-id>]
+  securespoon servers [--json]
+  securespoon servers redteam <server-id>
+  securespoon receipts [--json]
+  securespoon receipts verify <receipt-id>
+  securespoon keys
+
+AUTH
+  Keys are minted in the console (Settings → API keys). "login" verifies the
+  key against the console before saving. Env overrides: SECURESPOON_API_KEY,
+  SECURESPOON_BASE_URL, SECURESPOON_CONFIG.`;
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")); } catch { return {}; }
+}
+function writeConfig(cfg) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+}
+function flag(args, name) {
+  const i = args.indexOf(name);
+  if (i === -1) return undefined;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+function prompt(q, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    if (hidden && process.stdin.isTTY) {
+      // mask key entry: echo nothing after the prompt
+      process.stdout.write(q);
+      const chars = [];
+      process.stdin.setRawMode(true);
+      process.stdin.on("data", function onData(b) {
+        const s = b.toString("utf8");
+        if (s === "\r" || s === "\n" || s === "\u0004") {
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener("data", onData);
+          rl.close();
+          process.stdout.write("\n");
+          resolve(chars.join(""));
+        } else if (s === "\u0003") {
+          process.exit(130);
+        } else if (s === "\u007f") {
+          chars.pop();
+        } else {
+          chars.push(s);
+        }
+      });
+    } else {
+      rl.question(q, (a) => { rl.close(); resolve(a.trim()); });
+    }
+  });
+}
+function client() {
+  const cfg = readConfig();
+  const apiKey = process.env.SECURESPOON_API_KEY ?? cfg.apiKey;
+  const baseUrl = process.env.SECURESPOON_BASE_URL ?? cfg.baseUrl;
+  if (!apiKey || !baseUrl) {
+    console.error("Not logged in. Run: securespoon login");
+    process.exit(2);
+  }
+  return new SecureSpoon({ apiKey, baseUrl });
+}
+const mask = (k) => `${k.slice(0, 14)}••••••••`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args.shift();
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  if (cmd === "login") {
+    const url = flag(args, "--url") ?? (await prompt("Console URL (https://…): "));
+    const key = flag(args, "--key") ?? (await prompt("API key (orx_live_…): ", { hidden: true }));
+    const c = new SecureSpoon({ apiKey: key, baseUrl: url });
+    // Verify before saving: a read call. 403 means valid key without read
+    // scope (a run-only key) — still worth saving; 401 means a bad key.
+    try {
+      await c.workspaces.list();
+    } catch (e) {
+      if (e instanceof SecureSpoonError && e.status === 401) {
+        console.error("That key was refused by the console (401) — not saved.");
+        process.exit(1);
+      }
+      if (!(e instanceof SecureSpoonError && e.status === 403)) throw e;
+    }
+    writeConfig({ baseUrl: c.baseUrl, apiKey: key });
+    console.log(`Logged in to ${c.baseUrl} as ${mask(key)} (saved to ${CONFIG_PATH}).`);
+    return;
+  }
+
+  if (cmd === "whoami") {
+    const cfg = readConfig();
+    const apiKey = process.env.SECURESPOON_API_KEY ?? cfg.apiKey;
+    const baseUrl = process.env.SECURESPOON_BASE_URL ?? cfg.baseUrl;
+    if (!apiKey || !baseUrl) { console.log("Not logged in."); process.exit(2); }
+    console.log(`${baseUrl}  ${mask(apiKey)}`);
+    return;
+  }
+
+  if (cmd === "ask") {
+    const agent = flag(args, "--agent");
+    const json = args.includes("--json");
+    const question = args.filter((a) => a !== "--json").join(" ").trim();
+    if (!question) { console.error('Usage: securespoon ask "<question>" [--agent <id>]'); process.exit(2); }
+    const turn = await client().ask({ agent, question });
+    if (json) { console.log(JSON.stringify(turn, null, 2)); return; }
+    console.log(turn.answer);
+    if (turn.risk) console.error(`\n[risk: ${turn.risk.label}]  [agent: ${turn.agentId} v${turn.agentVersion}]`);
+    return;
+  }
+
+  if (cmd === "servers") {
+    const sub = args[0];
+    if (sub === "redteam") {
+      const id = args[1];
+      if (!id) { console.error("Usage: securespoon servers redteam <server-id>"); process.exit(2); }
+      const out = await client().mcpServers.redteam(id);
+      console.log(JSON.stringify(out, null, 2));
+      process.exit(out.result?.status === "passed" ? 0 : 1);
+    }
+    const servers = await client().mcpServers.list();
+    if (args.includes("--json")) { console.log(JSON.stringify(servers, null, 2)); return; }
+    for (const s of servers) {
+      const rt = s.redTeam ? `red-team ${s.redTeam.status} (${s.redTeam.checksRun} checks)` : "red-team not run";
+      console.log(`${s.id}  ${s.status.padEnd(8)}  ${rt.padEnd(32)}  ${s.name}`);
+    }
+    return;
+  }
+
+  if (cmd === "receipts") {
+    const sub = args[0];
+    const c = client();
+    if (sub === "verify") {
+      const id = args[1];
+      if (!id) { console.error("Usage: securespoon receipts verify <receipt-id>"); process.exit(2); }
+      const receipt = await c.receipts.get(id);
+      if (!receipt) { console.error(`No receipt ${id}.`); process.exit(1); }
+      const v = await c.receipts.verify(receipt);
+      console.log(JSON.stringify(v, null, 2));
+      process.exit(v.verified ? 0 : 1);
+    }
+    const receipts = await c.receipts.list();
+    if (args.includes("--json")) { console.log(JSON.stringify(receipts, null, 2)); return; }
+    for (const r of receipts) console.log(`${r.id}  ${r.issuedAtIso}  ${r.actor}  ${(r.run?.question ?? "").slice(0, 60)}`);
+    return;
+  }
+
+  if (cmd === "keys") {
+    const keys = await client().apiKeys.list();
+    for (const k of keys) console.log(`${k.id}  ${k.prefix}  scopes=${(k.accessScopes ?? []).join(",")}  expires=${k.expiresAtIso ?? "never"}`);
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}\n`);
+  console.log(HELP);
+  process.exit(2);
+}
+
+main().catch((e) => {
+  if (e instanceof SecureSpoonError) {
+    console.error(`Error ${e.status}: ${e.message}`);
+    process.exit(1);
+  }
+  console.error(e.message ?? String(e));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@securespoon/sdk",
+  "version": "0.1.0",
+  "description": "Typed client and CLI for the SecureSpoon governed control plane.",
+  "license": "Apache-2.0",
+  "homepage": "https://securespoon.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gittergov/multitenant.git",
+    "directory": "sdk/typescript"
+  },
+  "keywords": [
+    "securespoon",
+    "mcp",
+    "agents",
+    "governance",
+    "api-client",
+    "cli"
+  ],
+  "type": "module",
+  "main": "src/index.mjs",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "bin": {
+    "securespoon": "bin/securespoon.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Type declarations for @securespoon/sdk. The wire shapes are the console's
+ * REST responses; fields beyond the ones named here ride through untyped.
+ */
+
+export interface SecureSpoonOptions {
+  /** A minted API key (`ss_live_…`). Falls back to SECURESPOON_API_KEY. */
+  apiKey?: string;
+  /** Console origin, e.g. "https://console.example.com". Falls back to SECURESPOON_BASE_URL. */
+  baseUrl?: string;
+  /** Override fetch (tests). */
+  fetch?: typeof fetch;
+}
+
+/** One governed run through the five-gate pipeline. */
+export interface AgentTurn {
+  question: string;
+  answer: string;
+  agentId: string;
+  agentVersion: number;
+  risk?: { label: string; reasons: string[] };
+  guardrail: Record<string, unknown>;
+  classification: Record<string, unknown>;
+  residency: Record<string, unknown>;
+  resilience: Record<string, unknown>;
+  quota: Record<string, unknown>;
+  cost: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/** A signed, shareable run receipt. */
+export interface Receipt {
+  id: string;
+  workspaceId: string;
+  actor: string;
+  issuedAtIso: string;
+  run: AgentTurn;
+  pricesArePlaceholder: boolean;
+  signature: string;
+  signatureAlg: string;
+  [key: string]: unknown;
+}
+
+export interface ReceiptVerification {
+  receiptId: string;
+  verified: boolean;
+  reason: string;
+}
+
+export interface McpServer {
+  id: string;
+  name: string;
+  status: string;
+  endpoint?: string;
+  redTeam?: {
+    status: "passed" | "failed";
+    checksRun: number;
+    findings: { check: string; tool: string; detail: string }[];
+    atIso: string;
+    corpusVersion: string;
+  };
+  tools?: { id: string; name: string; description?: string }[];
+  [key: string]: unknown;
+}
+
+export declare class SecureSpoonError extends Error {
+  status: number;
+  messages: string[];
+  constructor(status: number, messages: string[]);
+}
+
+export declare class SecureSpoon {
+  constructor(options?: SecureSpoonOptions);
+  apiKey: string;
+  baseUrl: string;
+
+  /** Ask an agent through the governed path. */
+  ask(input: { agent?: string; question: string }): Promise<AgentTurn>;
+
+  receipts: {
+    list(): Promise<Receipt[]>;
+    get(id: string): Promise<Receipt | null>;
+    create(input: { workspaceId: string; run: AgentTurn } & Record<string, unknown>): Promise<Receipt>;
+    verify(receipt: Receipt): Promise<ReceiptVerification>;
+  };
+
+  mcpServers: {
+    list(): Promise<McpServer[]>;
+    create(input: Record<string, unknown>): Promise<McpServer>;
+    redteam(id: string): Promise<{ result: NonNullable<McpServer["redTeam"]>; status: string; regression: boolean }>;
+    call(id: string, input: { toolId: string; input: string }): Promise<unknown>;
+  };
+
+  workspaces: {
+    list(): Promise<Record<string, unknown>[]>;
+    create(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+  };
+
+  agents: { list(): Promise<Record<string, unknown>[]> };
+  apiKeys: { list(): Promise<Record<string, unknown>[]> };
+}
+
+export default SecureSpoon;

package/src/index.mjs

@@ -0,0 +1,105 @@
+/**
+ *  @securespoon/sdk — a thin, typed client over the SecureSpoon console's REST
+ *  API. Zero dependencies; Node 18+ (global fetch).
+ *
+ *  Every call authenticates with a minted API key (Settings → API keys). The
+ *  key's ACCESS SCOPES bound what the client may do server-side — read / run /
+ *  manage — and the server's AND-gate enforces them on every route; this
+ *  client adds no privilege, it only speaks the protocol.
+ *
+ *      import { SecureSpoon } from "@securespoon/sdk";
+ *      const client = new SecureSpoon({
+ *        apiKey: process.env.SECURESPOON_API_KEY,
+ *        baseUrl: "https://console.example.com",
+ *      });
+ *      const turn = await client.ask({ agent: "support-copilot", question: "…" });
+ *      console.log(turn.answer);
+ */
+
+export class SecureSpoonError extends Error {
+  constructor(status, messages) {
+    super(messages.length ? messages.join("; ") : `HTTP ${status}`);
+    this.name = "SecureSpoonError";
+    /** HTTP status of the failed call (401 bad/expired key, 403 out of scope, 400 invalid input). */
+    this.status = status;
+    /** Server-supplied error messages, verbatim. */
+    this.messages = messages;
+  }
+}
+
+export class SecureSpoon {
+  constructor({ apiKey, baseUrl, fetch: fetchImpl } = {}) {
+    this.apiKey = apiKey ?? process.env.SECURESPOON_API_KEY;
+    this.baseUrl = (baseUrl ?? process.env.SECURESPOON_BASE_URL ?? "").replace(/\/+$/, "");
+    if (!this.apiKey) throw new Error("SecureSpoon: apiKey is required (or set SECURESPOON_API_KEY).");
+    if (!this.baseUrl) throw new Error("SecureSpoon: baseUrl is required (or set SECURESPOON_BASE_URL).");
+    this._fetch = fetchImpl ?? globalThis.fetch;
+
+    /** Signed run receipts: list, fetch one, mint from a run, verify an artifact. */
+    this.receipts = {
+      list: () => this._req("GET", "/api/receipts"),
+      get: (id) => this._req("GET", `/api/receipts/${encodeURIComponent(id)}`),
+      create: (input) => this._req("POST", "/api/receipts", input),
+      /** Server-side re-sign + compare of the FULL artifact you hold. */
+      verify: (receipt) => this._req("POST", `/api/receipts/${encodeURIComponent(receipt.id)}/verify`, receipt),
+    };
+
+    /** Registered MCP servers (every registration is red-teamed before trust). */
+    this.mcpServers = {
+      list: () => this._req("GET", "/api/mcp-servers"),
+      create: (input) => this._req("POST", "/api/mcp-servers", input),
+      /** Re-run the red-team gate; a regression pauses the server + alerts. */
+      redteam: (id) => this._req("POST", `/api/mcp-servers/${encodeURIComponent(id)}/redteam`, {}),
+      call: (id, input) => this._req("POST", `/api/mcp-servers/${encodeURIComponent(id)}/call`, input),
+    };
+
+    this.workspaces = {
+      list: () => this._req("GET", "/api/workspaces"),
+      create: (input) => this._req("POST", "/api/workspaces", input),
+    };
+
+    this.agents = {
+      list: () => this._req("GET", "/api/agents"),
+    };
+
+    /** Key metadata — masked prefixes only; the server never returns a secret. */
+    this.apiKeys = {
+      list: () => this._req("GET", "/api/api-keys"),
+    };
+  }
+
+  /**
+   * Ask an agent through the governed path — the same five-gate pipeline the
+   * console runs (guardrails, classification, residency, resilience, quota).
+   * Returns the full turn; `answer` is the reply, `risk` the server's scoring.
+   */
+  async ask({ agent, question }) {
+    const body = { question };
+    if (agent && agent !== "current") body.target = { type: "agent", id: agent };
+    return this._req("POST", "/api/ask", body);
+  }
+
+  async _req(method, path, body) {
+    const headers = { authorization: `Bearer ${this.apiKey}` };
+    if (body !== undefined) headers["content-type"] = "application/json";
+    const res = await this._fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON error body */ }
+    if (!res.ok) {
+      const messages = Array.isArray(json?.issues) && json.issues.length
+        ? json.issues
+        : json?.error
+          ? [json.error]
+          : [];
+      throw new SecureSpoonError(res.status, messages);
+    }
+    return json;
+  }
+}
+
+export default SecureSpoon;