@atbash/sdk 0.3.25 → 0.4.0-dev.0

package/README.md

@@ -1,366 +1,144 @@
-# @atbash/sdk
+# @atbash/sdk (Node)
 
-TypeScript SDK for Atbash — the safety layer that evaluates AI agent actions against operator-defined policies before execution.
+The Node.js Atbash SDK. One package, two layers:
 
-## Installation
+- **Rust core via NAPI-RS** — signing, key derivation, redaction, unicode
+  normalization, memory diff. Byte-identical to the TypeScript reference.
+- **Judge / risk-engine HTTP client** — types generated from
+  [`spec/openapi.yaml`](../../spec/openapi.yaml), transport in
+  [src-ts/http/client.ts](src-ts/http/client.ts).
 
-```bash
-npm install @atbash/sdk
-```
-
-Requires Node.js 18+. Server-side only — private keys are used for local signing and must never be exposed to browsers.
-
-## Quickstart
-
-```ts
-import { loadAgent, judgeAction } from "@atbash/sdk";
-
-// 1. Load your agent identity using the private key you saved during
-//    agent creation. loadAgent() validates the key and derives the
-//    matching public key for you.
-const agent = loadAgent(process.env.ATBASH_AGENT_PRIVKEY!);
-
-// 2. Submit an action for judgment, before executing it.
-//    The SDK signs the transaction locally and sends it to the judge API.
-//    Private key stays on your machine — never sent over HTTP.
-//    Pass orgName so the SDK auto-resolves the correct chain (public or private).
-const result = await judgeAction(
-  "Transfer $50,000 to external wallet 0xabc",
-  "Outbound AML check — new recipient, over threshold",
-  agent,
-  { orgName: "my_org" },
-);
-
-// 3. Enforce the verdict
-switch (result.verdict) {
-  case "ALLOW":
-    // Proceed with the action
-    break;
-  case "HOLD":
-    // Held — operator must approve in the dashboard
-    console.log("Held for review:", result.tool_call_id);
-    break;
-  case "BLOCK":
-    // Refused — agent is auto-jailed
-    throw new Error(`Blocked: ${result.reason}`);
-}
-```
-
-Before this works, the agent must be onboarded at [atbash.ai](https://atbash.ai/) — assigned to an org with an active subscription and a policy pack attached.
-
-### How it works
-
-`judgeAction()` performs a two-step flow:
-
-1. **Sign locally** — signs the transaction using the agent's private key. The key never leaves your machine.
-2. **Request verdict** — sends the signed payload to the Atbash judge API, which records it on the Chromia blockchain and returns a verdict.
-
-
-### Don't have an agent yet?
-
-There are two ways to create an agent:
-
-1. **Dashboard (recommended)** — create an agent at [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents). The dashboard generates the keypair, assigns the agent to your org, and lets you attach a policy pack — all in one step.
-
-2. **Programmatic** — generate a new keypair locally or bring an existing secp256k1 private key from another platform, then onboard it via the dashboard:
-
-```ts
-import { generateKeyPair, loadAgent } from "@atbash/sdk";
-
-const { privKey } = generateKeyPair();
-console.log("Save this private key somewhere safe:", privKey);
-const agent = loadAgent(privKey);
-```
-
-> **Note:** After generating a key programmatically, you must still onboard the agent at [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) — assign it to an org and attach a policy pack before `judgeAction` will work.
+The high-level `Atbash` class composes the two, mirroring the TS reference at
+[atbash-sdk/src/client.ts](../../atbash-sdk/src/client.ts) and the Python
+surface at [bindings/python/python/atbash/client.py](../../bindings/python/python/atbash/client.py).
 
-### Secret storage
+## Layout
 
-- Load the private key from an environment variable (`ATBASH_AGENT_KEY`) or a secret manager — never hardcode it.
-- Never commit `.env` files containing the key.
-- If a key leaks, stop using it and create a new agent in the [dashboard](https://atbash.ai/risk-engine/agents).
-
-## Verdicts
-
-Every `judgeAction` call returns one of three verdicts:
-
-| Verdict | Meaning | What your code should do |
-|---------|---------|-------------------------|
-| `ALLOW` | Action is within policy | Proceed with execution |
-| `HOLD` | Requires operator review | Pause — poll `getJudgmentStatus` until resolved |
-| `BLOCK` | Violates a red line | Abort — agent is auto-jailed |
-
-> **NB:** If your org has **no active subscription**, the judge returns `"No verdict"` — actions are logged on-chain for the audit trail but not evaluated. Assign a subscription plan at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) for active verdicts. All subscription plans (including Free) get full enforcement.
-
-## API
-
-### Judge
-
-```ts
-judgeAction(
-  action: string,
-  context: string,
-  auth: AgentAuth,
-  opts?: JudgeOptions,
-): Promise<JudgeResult>
 ```
-
-Submit an action for judgment before execution. Signs the transaction locally and sends it to the judge API for a verdict.
-
-```ts
-interface AgentAuth {
-  pubkey: string;   // 66-char hex, secp256k1 compressed public key
-  privkey: string;  // 64-char hex private key (used for local signing only)
-}
-
-interface JudgeOptions {
-  endpoint?: string;          // API base URL (default: https://atbash.ai)
-  timeout?: number;           // Request timeout in ms
-  provider?: string;          // "openai" | "google" | "microsoft" | "custom"
-  model?: string;             // Model override (e.g. "gpt-4o-mini")
-  toolName?: string;          // Tool name for audit trail
-  toolArgsJson?: string;      // Tool arguments JSON for audit trail
-  orgName?: string;           // Org name — SDK auto-resolves the correct chain
-}
-
-interface JudgeResult {
-  verdict: string;       // "ALLOW", "HOLD", or "BLOCK"
-  reason: string;        // Human-readable explanation
-  confidence: number;    // 0–1
-  provider: string;      // Which provider evaluated the action
-  latency_ms: number;    // Inference time
-  tool_call_id: string;  // Unique ID for this judgment
-  on_chain: boolean;     // Whether the record was written on-chain
-}
+bindings/node/
+├── src/lib.rs            # NAPI-RS Rust bindings → atbash.<triple>.node + index.{js,d.ts}
+├── index.js / index.d.ts # NAPI-generated native glue (gitignored)
+├── src-ts/               # TypeScript SDK surface
+│   ├── index.ts          # public exports (Atbash + native re-exports)
+│   ├── client.ts         # Atbash class (judge / log / queries)
+│   ├── native.ts         # typed loader for the NAPI addon
+│   ├── http/             # schema.ts (generated) + thin fetch client
+│   ├── types.ts, constants.ts, errors.ts, normalize.ts
+│   └── ...
+├── dist/                 # tsup output (gitignored) — what gets published
+└── __test__/             # native parity + SDK (http / body-parity) tests
 ```
 
-### Poll judgment status
+## Setup
 
-```ts
-getJudgmentStatus(judgmentId: string, agentPubkey: string, opts?: ClientOpts): Promise<JudgmentStatus>
-```
-
-Check whether a held action has been approved or rejected by an operator.
-
-```ts
-interface JudgmentStatus {
-  status: "pending" | "answered" | "error";
-  verdict: string;
-  reason: string;
-  judgmentId: string;
-  onChain?: boolean;
-  cached?: boolean;
-  responseTimeMs?: number;
-}
+```bash
+cd bindings/node
+npm install
 ```
 
-### Agent identity
+## Build
 
-```ts
-loadAgent(privkey: string): AgentAuth
-generateKeyPair(): { privKey: string; pubKey: string }
-derivePublicKey(privKeyHex: string): string
-isValidPrivateKey(hex: string): boolean
-toPubkeyHex(val: unknown): string
+```bash
+npm run gen:http       # regenerate src-ts/http/schema.ts from spec/openapi.yaml
+npm run build:native   # atbash.<triple>.node + index.{js,d.ts}
+npm run build:ts       # tsup → dist/{index.js,index.mjs,index.d.ts}
+npm run build          # native + ts
 ```
 
-`loadAgent(privkey)` is the canonical loader — pass in the private key from the dashboard, get back `{ pubkey, privkey }` ready for `judgeAction`. It accepts `0x`-prefixed, padded, or mixed-case input and throws on malformed keys. Use `generateKeyPair()` only for local development; for production, create agents in the dashboard so operators can attach policies.
-
-### Operations
-
-Functions that sign transactions and write to the Chromia blockchain.
+Native artifacts (`*.node`, `index.js`, `index.d.ts`) and `dist/` are
+`.gitignore`d — build locally.
 
-| Function | Use case |
-|----------|----------|
-| `judgeAction(action, context, auth, opts?)` | Sign locally + request a verdict from the judge API |
+## Test
 
-### Queries
-
-| Function | Use case |
-|----------|----------|
-| `checkAgentExists(pubkey, opts?)` | Check if an agent is onboarded before signing |
-| `getJudgmentStatus(judgmentId, agentPubkey, opts?)` | Poll whether a held action has been approved or rejected |
-| `getToolCalls(maxCount)` | List recent tool calls across all agents |
-| `getOrgToolCalls(orgName, maxCount)` | List tool calls for a specific org |
-| `getAgentToolCalls(pubkey, maxCount)` | List tool calls for a specific agent |
-| `getToolCallCount()` | Get total number of tool calls on-chain |
-| `getToolCallFull(toolCallId)` | Get full details of a single tool call (verdict, context, timing) |
-| `getOrgSubscription(orgName)` | Check an org's subscription plan, network, and active status |
-| `getAgentDetail(pubkey)` | Get agent metadata (org, status, creation date) |
-| `getAgentPolicy(pubkey)` | Check agent's policy pack and jail status |
-| `getPendingHeldActions(orgName, maxCount)` | List actions waiting for operator approval |
-| `getHeldActionReviews(orgName, maxCount)` | List completed operator reviews |
-| `getSafetyStats()` | Get chain-wide safety statistics (total judgments, verdicts, etc.) |
-
-## Configuration
-
-You can pass configuration inline or use the built-in config module that reads from `~/.config/atbash/config.json`.
-
-### Inline
-
-```ts
-const result = await judgeAction(action, context, auth, {
-  endpoint: "https://your-instance.example.com",
-  provider: "openai",
-  model: "gpt-4o",
-});
+```bash
+npm test               # node --test __test__/*.test.mjs
+# native vector parity (91) + SDK http/body-parity (30) = 121 cases
 ```
 
-### Persistent config
+The SDK tests stand a real loopback HTTP server up (see
+[__test__/_mock_server.mjs](__test__/_mock_server.mjs)) so `fetch` runs
+end-to-end; signing is real through the NAPI core.
 
-Save configuration once — the SDK resolves values with priority: **flag > env var > config file**.
+## Usage
 
 ```ts
-import { saveUserConfig, resolve, loadAgent, judgeAction } from "@atbash/sdk";
+import { Atbash } from "@atbash/sdk";
 
-// Save once
-saveUserConfig({
-  agentKey: "9cd07a...",
-  orgName: "my_org",
-  provider: "openai",
-});
+const client = new Atbash(privkey, { endpoint: "https://atbash.ai" });
 
-// Then use resolve() anywhere
-const agent = loadAgent(resolve("agentKey"));
-const result = await judgeAction("Transfer $500", "finance", agent, {
-  orgName: resolve("orgName"),
-  provider: resolve("provider"), // omit to use the on-chain ATBASH judge
+// Sign + submit for judgement (verdict normalized to ALLOW/HOLD/BLOCK).
+const verdict = await client.judgeAction("read_file", "reading config", {
+  toolName: "fs.read",
 });
-```
-
-Config file location: `~/.config/atbash/config.json`
 
-| Function | Purpose |
-|----------|---------|
-| `saveUserConfig(config)` | Write config to disk |
-| `loadUserConfig()` | Read config from disk |
-| `resolve(key, flagValue?)` | Resolve a value: flag > env > file > `""` |
-| `getConfigPath()` | Returns the config file path |
-
-| Config key | Env var |
-|------------|--------|
-| `agentKey` | `ATBASH_AGENT_KEY` |
-| `orgName` | `ATBASH_ORG_NAME` |
-| `judgeEndpoint` | `ATBASH_ENDPOINT` |
-| `blockchainRid` | `ATBASH_BLOCKCHAIN_RID` |
-| `provider` | `ATBASH_PROVIDER` |
-| `providerModel` | `ATBASH_PROVIDER_MODEL` |
-
-> **Chain routing:** When you pass `orgName`, the SDK automatically connects to the correct chain for your org's subscription plan. You don't need to configure chain details manually.
-
-## Secret redaction
-
-Before each `auditToolCall` signs anything, the SDK scans `args` and `context` for secret-shaped values (API keys, tokens, JWTs, PEM blocks, etc.) and replaces matches with `[REDACTED:<kind>]`. Redaction happens **before signing**, so secrets never reach the signed bytes, the request body, the on-chain log, or the prompt sent to the AI provider.
-
-When the redactor fires, you'll see a warning via the configured `logger`:
+// Sign a tool call locally (server broadcasts to chain).
+const logged = await client.logToolCall("write_file", "patching deps");
 
+// Read-only queries.
+const tier = await client.getOrgTierInfo("acme");
 ```
-[atbash] redacted secrets before judge call { tool: "exec", count: 2, kinds: ["anthropic", "generic_token"] }
-```
-
-Common `kinds`:
-
-- `anthropic`, `openai`, `github`, `google`, `aws_access_key`, `stripe`, `slack`, `jwt`, `private_key_pem` — high-confidence vendor patterns; if you see these, a real secret was almost certainly in your input
-- `context_secret` — a value next to a label like `api_key=`, `token:`, `password=`, etc.
-- `generic_token` — long random-looking strings (32+ alphanumeric chars). Catches unknown-vendor secrets, but can also match UUIDs, content hashes, and other opaque identifiers. The judge sees `[REDACTED:generic_token]` instead of the original; for verdict purposes the shape of the action matters more than the exact ID, so this is generally safe — but worth knowing if you see it unexpectedly.
-- `base64` — long base64-encoded values; can match legitimate image/file data
-
-Redaction is silent at the consumer level — the SDK's caller still has the original arguments. Only what's sent to the judge (and persisted on chain via the verdict log) is scrubbed.
-
-## High-level client
 
-For framework integrations, `createAtbashClient` wraps key loading, secret redaction, and verdict handling into a single `auditToolCall` method:
+Crypto / redaction / memory primitives are also exported as plain functions
+(byte-identical to the TS reference):
 
 ```ts
-import { createAtbashClient } from "@atbash/sdk";
+import {
+  generateKeypair,
+  derivePublicKey,
+  signLogToolCall,
+  redactSecrets,
+  diffMemorySnapshots,
+  DEFAULT_BLOCKCHAIN_RID,
+} from "@atbash/sdk";
 
-const atbash = createAtbashClient({
-  orgName: "my_org",
-  keyPair: { privKey: process.env.ATBASH_AGENT_KEY!, pubKey: "" },
-  failClosed: true,  // block on errors (default: true)
-});
-
-const decision = await atbash.auditToolCall({
-  toolName: "send_email",
-  args: { to: "user@example.com", subject: "Reset" },
-  context: "Password reset flow",
-});
-
-if (!decision.allow) {
-  console.log(`${decision.verdict}: ${decision.reason}`);
-}
-```
-
-The client auto-resolves the correct chain from the org's subscription on the first call and caches the result. Secret redaction runs automatically before signing.
-
-## Integration patterns
-
-### Pre-execution gate
-
-```ts
-async function safeExecute(action: string, context: string, execute: () => Promise<void>) {
-  const result = await judgeAction(action, context, auth);
-  if (result.verdict === "BLOCK") throw new Error(`Blocked: ${result.reason}`);
-  if (result.verdict === "HOLD") throw new Error(`Held for review: ${result.tool_call_id}`);
-  await execute();
-}
+const kp = generateKeypair(); // { priv_key, pub_key }
+const { redacted, found } = redactSecrets("token=sk-abc123…");
 ```
 
-### Polling a held action
+## Config loading
 
-```ts
-async function waitForApproval(toolCallId: string): Promise<string> {
-  while (true) {
-    const status = await getJudgmentStatus(toolCallId, auth.pubkey);
-    if (status.status === "answered") return status.verdict;
-    if (status.status === "error") throw new Error(status.reason);
-    await new Promise((r) => setTimeout(r, 5000));
-  }
-}
-```
-
-### Checking agent jail status
+Construct from environment / config file / key file instead of an inline key.
+Resolution precedence is flag → `ATBASH_*` env → `~/.config/atbash/config.json`
+(camelCase keys, shared with the Python SDK) → default.
 
 ```ts
-const policy = await getAgentPolicy(pubKey);
-if (policy.is_jailed) {
-  console.error("Agent is jailed — unjail via dashboard before retrying.");
-  process.exit(1);
-}
+import { Atbash } from "@atbash/sdk";
+
+// Reads agentKey/judgeEndpoint/blockchainRid from env or config.json; falls
+// back to the key file at ~/.config/atbash/guard-client-key.
+const client = Atbash.fromConfig();
+
+// Self-hosted judge: endpoint is validated and its response-signing pubkey
+// becomes the default verifyPubKey for judgeAction.
+const selfHosted = Atbash.fromConfig({
+  judge: {
+    policy: "self-hosted",
+    endpoint: "https://judge.internal",
+    verifyPubKey: "02…", // 66-hex compressed secp256k1
+  },
+});
 ```
 
-## Error handling
-
-The SDK throws standard `Error` objects. Known failure modes are enriched with a pointer to the relevant dashboard page, so the error message tells you where to fix the problem:
+Lower-level helpers are also exported: `loadUserConfig`, `saveUserConfig`,
+`resolve`, `validateJudgeEndpoint`, `resolveKeyPath`, `loadAgentFromFile`.
 
-```
-API error 404: {"error":"Agent not registered..."}
-  → Onboard the agent at https://atbash.ai/risk-engine/agents
-```
+## One-call guard: `auditToolCall`
 
-| Error | Cause | Where to fix |
-|---|---|---|
-| `API error 404: Agent not registered` | Agent not onboarded | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
-| `API error 400: Agent has no policy` | No policy attached to agent | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
-| `Agent is jailed` | BLOCK verdict triggered auto-jail | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
-| `Verdicts are disabled` | Org has no active subscription | [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |
-| `API error 400: action is required` | Empty action string | Fix caller |
-| `API error 502: Incorrect API key` | Invalid provider API key | Check saved key at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |
+Redact secrets → sign → judge → allow/deny `Decision`, failing closed by
+default (any error denies unless `failClosed: false`):
 
 ```ts
-try {
-  const result = await judgeAction(action, context, auth);
-} catch (err) {
-  if (err.message.includes("Agent not registered")) {
-    // Point the user at https://atbash.ai/risk-engine/agents to onboard.
-  }
-}
+const client = Atbash.fromConfig({ logger: console });
+const decision = await client.auditToolCall({
+  toolName: "shell.exec",
+  args: { cmd: "rm -rf /tmp/cache" },
+  context: "cleaning build cache",
+});
+if (!decision.allow) throw new Error(`${decision.verdict}: ${decision.reason}`);
 ```
 
-## Dashboard
-
-Policy authoring, operator reviews, and agent management happen at [atbash.ai](https://atbash.ai/). The SDK is the programmatic interface; the dashboard is the operator interface.
-
-## License
+Secret-shaped values in `args`/`context` are redacted before signing, so they
+never reach the signed bytes, the request, the on-chain log, or the LLM prompt.
 
-Proprietary — all rights reserved. See [LICENSE](https://atbash.ai/license).
+The raw native addon is also reachable at `@atbash/sdk/native` for advanced
+callers who want the un-wrapped functions.