@atbash/sdk 0.5.1-dev.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +148 -107
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,143 +1,184 @@
1
- # @atbash/sdk (Node)
1
+ # @atbash/sdk
2
2
 
3
- The Node.js Atbash SDK. One package, two layers:
3
+ TypeScript SDK for Atbash — the safety layer that evaluates AI agent actions against operator-defined policies before execution.
4
4
 
5
- - **Rust core via NAPI-RS** — signing, key derivation, redaction, unicode
6
- normalization, memory diff. Byte-identical to the TypeScript reference.
7
- - **Judge / risk-engine HTTP client** — types generated from
8
- [`spec/openapi.yaml`](../../spec/openapi.yaml), transport in
9
- [src-ts/http/client.ts](src-ts/http/client.ts).
5
+ ## Installation
10
6
 
11
- The high-level `Atbash` class composes the two, mirroring the TS reference at
12
- [atbash-sdk/src/client.ts](../../atbash-sdk/src/client.ts) and the Python
13
- surface at [bindings/python/python/atbash/client.py](../../bindings/python/python/atbash/client.py).
7
+ ```bash
8
+ npm install @atbash/sdk
9
+ ```
14
10
 
15
- ## Layout
11
+ Requires Node.js 18+. Server-side only — private keys are used for local signing and must never be exposed to browsers.
16
12
 
17
- ```
18
- bindings/node/
19
- ├── src/lib.rs # NAPI-RS Rust bindings → atbash.<triple>.node + index.{js,d.ts}
20
- ├── index.js / index.d.ts # NAPI-generated native glue (gitignored)
21
- ├── src-ts/ # TypeScript SDK surface
22
- │ ├── index.ts # public exports (Atbash + native re-exports)
23
- │ ├── client.ts # Atbash class (judge / log / queries)
24
- │ ├── native.ts # typed loader for the NAPI addon
25
- │ ├── http/ # schema.ts (generated) + thin fetch client
26
- │ ├── types.ts, constants.ts, errors.ts, normalize.ts
27
- │ └── ...
28
- ├── dist/ # tsup output (gitignored) — what gets published
29
- └── __test__/ # native parity, config, and live health tests
30
- ```
13
+ ## Quickstart
31
14
 
32
- ## Setup
15
+ ```ts
16
+ import { Atbash } from "@atbash/sdk";
33
17
 
34
- ```bash
35
- cd bindings/node
36
- npm install
18
+ // 1. Construct with your agent's private key.
19
+ // The SDK validates the key and derives the matching public key.
20
+ const atbash = new Atbash(process.env.ATBASH_AGENT_KEY!, {
21
+ orgName: "my_org",
22
+ });
23
+
24
+ // 2. Submit an action for judgment, before executing it.
25
+ // The SDK signs the transaction locally and sends it to the judge API.
26
+ // The private key stays on your machine — never sent over HTTP.
27
+ const result = await atbash.judgeAction(
28
+ "Transfer $50,000 to external wallet 0xabc",
29
+ "Outbound AML check — new recipient, over threshold",
30
+ );
31
+
32
+ // 3. Enforce the verdict
33
+ switch (result.verdict) {
34
+ case "ALLOW":
35
+ // Proceed with the action
36
+ break;
37
+ case "HOLD":
38
+ // Held — operator must approve in the dashboard
39
+ console.log("Held for review:", result.toolCallId);
40
+ break;
41
+ case "BLOCK":
42
+ // Refused — agent is jailed in Enforcement tier
43
+ throw new Error(`Blocked: ${result.reason}`);
44
+ }
37
45
  ```
38
46
 
39
- ## Build
47
+ Before this works, the agent must be onboarded at [atbash.ai](https://atbash.ai/) — assigned to an org, with a policy pack attached, and the org on an active subscription plan.
40
48
 
41
- ```bash
42
- npm run gen:http # regenerate src-ts/http/schema.ts from spec/openapi.yaml
43
- npm run build:native # atbash.<triple>.node + index.{js,d.ts}
44
- npm run build:ts # tsup → dist/{index.js,index.mjs,index.d.ts}
45
- npm run build # native + ts
46
- ```
49
+ ## How it works
47
50
 
48
- Native artifacts (`*.node`, `index.js`, `index.d.ts`) and `dist/` are
49
- `.gitignore`d — build locally.
51
+ `judgeAction()` performs a two-step flow:
50
52
 
51
- ## Test
53
+ 1. **Sign locally** — signs the request using the agent's private key. The key never leaves your machine.
54
+ 2. **Request verdict** — sends the signed request and agent pubkey to the Atbash judge API. The server broadcasts it to the Chromia blockchain and returns a verdict.
52
55
 
53
- ```bash
54
- npm run test:native # native vector parity
55
- npm run test:live # real SDK health, skipped unless ATBASH_LIVE_HEALTH=1
56
- ```
56
+ ## Don't have an agent yet?
57
57
 
58
- The live SDK health test uses real HTTP responses only. It verifies BRID
59
- signing, key loading, and a real judge call when live credentials are present.
58
+ Two ways to create an agent:
60
59
 
61
- ## Usage
60
+ 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.
62
61
 
63
- ```ts
64
- import { Atbash } from "@atbash/sdk";
62
+ 2. **Programmatic** — generate a keypair locally, then onboard it via the dashboard:
65
63
 
66
- const client = new Atbash(privkey, { endpoint: "https://atbash.ai" });
64
+ ```ts
65
+ import { generateKeypair } from "@atbash/sdk";
66
+ const { privKey, pubKey } = generateKeypair();
67
+ console.log("Save this private key somewhere safe:", privKey);
68
+ ```
67
69
 
68
- // Sign + submit for judgement (verdict normalized to ALLOW/HOLD/BLOCK).
69
- const verdict = await client.judgeAction("read_file", "reading config", {
70
- toolName: "fs.read",
71
- });
70
+ Paste the public key into the **Onboard agent** form on the dashboard, assign it to an org, and attach a policy pack before calling `judgeAction`.
72
71
 
73
- // Sign a tool call locally (server broadcasts to chain).
74
- const logged = await client.logToolCall("write_file", "patching deps");
72
+ ## Secret storage
75
73
 
76
- // Read-only queries.
77
- const tier = await client.getOrgTierInfo("acme");
78
- ```
74
+ - Load the private key from an environment variable (`ATBASH_AGENT_KEY`) or a secret manager — never hardcode it.
75
+ - Never commit `.env` files containing the key.
76
+ - If a key leaks, stop using it and create a new agent in the dashboard.
79
77
 
80
- Crypto / redaction / memory primitives are also exported as plain functions
81
- (byte-identical to the TS reference):
78
+ ## Verdicts
82
79
 
83
- ```ts
84
- import {
85
- generateKeypair,
86
- derivePublicKey,
87
- signLogToolCall,
88
- redactSecrets,
89
- diffMemorySnapshots,
90
- DEFAULT_BLOCKCHAIN_RID,
91
- } from "@atbash/sdk";
92
-
93
- const kp = generateKeypair(); // { priv_key, pub_key }
94
- const { redacted, found } = redactSecrets("token=sk-abc123…");
95
- ```
80
+ Every `judgeAction` call returns one of three verdicts:
81
+
82
+ | Verdict | Meaning | What your code should do |
83
+ |---|---|---|
84
+ | `ALLOW` | Action is within policy | Proceed with execution |
85
+ | `HOLD` | Requires operator review | Pause — poll `getJudgmentStatus` until resolved |
86
+ | `BLOCK` | Violates a red line | Abort — agent is jailed in Enforcement tier |
87
+
88
+ > **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 by an AI provider. Assign a plan at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) for active verdicts.
96
89
 
97
- ## Config loading
90
+ ## API
98
91
 
99
- Construct from environment / config file / key file instead of an inline key.
100
- Resolution precedence is flag → `ATBASH_*` env → `~/.config/atbash/config.json`
101
- (camelCase keys, shared with the Python SDK) → default.
92
+ The `Atbash` class is the main entry point. Construct it once with your agent's private key and (optionally) a default `orgName`, then call methods on it.
93
+
94
+ ### Operations
95
+
96
+ | Method | Use case |
97
+ |---|---|
98
+ | `judgeAction(action, context, opts?)` | Sign locally + request a verdict from the judge API |
99
+
100
+ ### Queries
101
+
102
+ Read-only methods that read from the Chromia blockchain and dashboard.
103
+
104
+ | Method | Use case |
105
+ |---|---|
106
+ | `checkAgentExists(pubkey?)` | Check if an agent is onboarded before signing |
107
+ | `getJudgmentStatus(judgmentId, pubkey)` | Poll whether a held action has been approved or rejected |
108
+ | `getToolCalls(maxCount)` | List recent tool calls across all agents |
109
+ | `getOrgToolCalls(orgName, maxCount)` | List tool calls for a specific org |
110
+ | `getAgentToolCalls(pubkey, maxCount)` | List tool calls for a specific agent |
111
+ | `getToolCallCount()` | Total number of tool calls on-chain |
112
+ | `getToolCallFull(toolCallId)` | Full details of a single tool call |
113
+ | `getOrgTierInfo(orgName)` | Check an org's tier and whether verdicts are enabled |
114
+ | `getAgentDetail(pubkey)` | Get agent metadata (org, status, creation date) |
115
+ | `getAgentPolicy(pubkey)` | Check the agent's policy pack and jail status |
116
+ | `getPendingHeldActions(orgName, maxCount)` | List actions waiting for operator approval |
117
+ | `getHeldActionReviews(orgName, maxCount)` | List completed operator reviews |
118
+ | `getSafetyStats()` | Chain-wide safety statistics |
119
+
120
+ ### Agent identity
121
+
122
+ Standalone helpers for keypair handling.
123
+
124
+ | Function | Use case |
125
+ |---|---|
126
+ | `generateKeypair()` | Generate a fresh secp256k1 keypair |
127
+ | `derivePublicKey(privkey)` | Derive the public key from a private key |
128
+ | `isValidPrivateKey(hex)` | Validate a private-key string |
129
+ | `loadAgent(privkey)` | Validate the key + return `{ pubkey, privkey }` |
130
+
131
+ ## Configuration
132
+
133
+ Configuration is resolved with priority: **constructor arg > env var > config file** (`~/.config/atbash/config.json`).
102
134
 
103
135
  ```ts
104
136
  import { Atbash } from "@atbash/sdk";
105
-
106
- // Reads agentKey/judgeEndpoint/blockchainRid from env or config.json; falls
107
- // back to the key file at ~/.config/atbash/guard-client-key.
108
- const client = Atbash.fromConfig();
109
-
110
- // Self-hosted judge: endpoint is validated and its response-signing pubkey
111
- // becomes the default verifyPubKey for judgeAction.
112
- const selfHosted = Atbash.fromConfig({
113
- judge: {
114
- policy: "self-hosted",
115
- endpoint: "https://judge.internal",
116
- verifyPubKey: "02…", // 66-hex compressed secp256k1
117
- },
118
- });
137
+ const atbash = Atbash.fromConfig(); // reads env + config file
119
138
  ```
120
139
 
121
- Lower-level helpers are also exported: `loadUserConfig`, `saveUserConfig`,
122
- `resolve`, `validateJudgeEndpoint`, `resolveKeyPath`, `loadAgentFromFile`.
140
+ | Config key | Env var |
141
+ |---|---|
142
+ | `agentKey` | `ATBASH_AGENT_KEY` |
143
+ | `orgName` | `ATBASH_ORG_NAME` |
144
+ | `judgeEndpoint` | `ATBASH_ENDPOINT` |
145
+ | `blockchainRid` | `ATBASH_BLOCKCHAIN_RID` |
146
+ | `provider` | `ATBASH_PROVIDER` |
147
+ | `providerModel` | `ATBASH_PROVIDER_MODEL` |
148
+
149
+ Persistent config helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
150
+
151
+ ## Error handling
152
+
153
+ The SDK throws standard `Error` objects. Known failure modes are enriched with a pointer to the dashboard page that fixes them:
123
154
 
124
- ## One-call guard: `auditToolCall`
155
+ ```
156
+ API error 404: {"error":"Agent not registered..."}
157
+ → Onboard the agent at https://atbash.ai/risk-engine/agents
158
+ ```
125
159
 
126
- Redact secrets → sign → judge → allow/deny `Decision`, failing closed by
127
- default (any error denies unless `failClosed: false`):
160
+ | Error | Cause | Where to fix |
161
+ |---|---|---|
162
+ | `API error 404: Agent not registered` | Agent not onboarded | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
163
+ | `API error 400: Agent has no policy` | No policy attached to agent | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
164
+ | `Agent is jailed` | BLOCK verdict triggered auto-jail | [atbash.ai/risk-engine/agents](https://atbash.ai/risk-engine/agents) |
165
+ | `Verdicts are disabled` | Org has no active subscription | [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) |
166
+ | `API error 400: action is required` | Empty action string | Fix caller |
128
167
 
129
168
  ```ts
130
- const client = Atbash.fromConfig({ logger: console });
131
- const decision = await client.auditToolCall({
132
- toolName: "shell.exec",
133
- args: { cmd: "rm -rf /tmp/cache" },
134
- context: "cleaning build cache",
135
- });
136
- if (!decision.allow) throw new Error(`${decision.verdict}: ${decision.reason}`);
169
+ try {
170
+ const result = await atbash.judgeAction(action, context);
171
+ } catch (err) {
172
+ if (err.message.includes("Agent not registered")) {
173
+ // Point the user at https://atbash.ai/risk-engine/agents to onboard.
174
+ }
175
+ }
137
176
  ```
138
177
 
139
- Secret-shaped values in `args`/`context` are redacted before signing, so they
140
- never reach the signed bytes, the request, the on-chain log, or the LLM prompt.
178
+ ## Dashboard
179
+
180
+ 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.
181
+
182
+ ## License
141
183
 
142
- The raw native addon is also reachable at `@atbash/sdk/native` for advanced
143
- callers who want the un-wrapped functions.
184
+ Apache-2.0. See [LICENSE](https://github.com/Atbash-Ai/atbash-sdk/blob/main/LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atbash/sdk",
3
- "version": "0.5.1-dev.0",
3
+ "version": "0.5.2",
4
4
  "description": "Atbash SDK for Node.js — Rust core (signing, redaction, memory diff) via NAPI-RS + judge/risk-engine HTTP client generated from spec/openapi.yaml.",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -81,8 +81,8 @@
81
81
  "typescript-eslint": "^8.62.1"
82
82
  },
83
83
  "optionalDependencies": {
84
- "@atbash/sdk-linux-x64-gnu": "0.5.1-dev.0",
85
- "@atbash/sdk-linux-arm64-gnu": "0.5.1-dev.0",
86
- "@atbash/sdk-darwin-arm64": "0.5.1-dev.0"
84
+ "@atbash/sdk-linux-x64-gnu": "0.5.1",
85
+ "@atbash/sdk-linux-arm64-gnu": "0.5.1",
86
+ "@atbash/sdk-darwin-arm64": "0.5.1"
87
87
  }
88
88
  }