@atbash/sdk 0.20.0-dev.0 → 0.22.0-dev.0

package/README.md

@@ -68,7 +68,7 @@ Two ways to create an agent:
 
 ## Secret storage
 
-- Load the private key from an environment variable (`ATBASH_AGENT_KEY`) or a secret manager — never hardcode it.
+- Keep the private key in the key file (`~/.config/atbash/guard-client-key`, or a file named by `keyPath`), in `ATBASH_AGENT_KEY`, or in a secret manager — never hardcode it. See [Which key signs](#which-key-signs).
 - Never commit `.env` files containing the key.
 - If a key leaks, stop using it and create a new agent in the dashboard.
 
@@ -127,31 +127,71 @@ Standalone helpers for keypair handling.
 | `isValidPrivateKey(hex)` | Validate a private-key string |
 | `loadAgent(privkey)` | Validate the key + return `{ pubkey, privkey }` |
 
-## Configuration
+## Configuration resolution
 
-Configuration is resolved with priority: **constructor arg > env var > config file** (`~/.config/atbash/config.json`).
+`new Atbash(privkey, options)` takes everything explicitly. `Atbash.fromConfig(options)` fills in what you did not pass from the environment and then from `~/.config/atbash/config.json`, and finds the signing key for you.
 
 ```ts
 import { Atbash } from "@atbash/sdk";
-const atbash = Atbash.fromConfig();   // reads env + config file
+const atbash = Atbash.fromConfig();   // key file + env + config.json
 ```
 
-| Config key | Env var |
-|---|---|
-| `agentKey` | `ATBASH_AGENT_KEY` |
-| `orgName` | `ATBASH_ORG_NAME` |
-| `judgeEndpoint` | `ATBASH_ENDPOINT` |
-| `judgeVerifyPubKey` | `ATBASH_JUDGE_VERIFY_PUBKEY` (self-hosted judge response-signing key; selects the self-hosted policy) |
-| `blockchainRid` | `ATBASH_BLOCKCHAIN_RID` |
+### Settings: option, then env, then `config.json`
+
+Each setting is read from the first place that has it: the `fromConfig` option, then the environment variable, then the key in `config.json`.
+
+`judge` is taken whole. Pass it complete, or leave it out and use the environment or `config.json`: a `judge` with only an `endpoint` ignores `ATBASH_JUDGE_VERIFY_PUBKEY`, so a self-hosted host then fails the allowlist.
+
+| `fromConfig` option | Env var | `config.json` key | Notes |
+|---|---|---|---|
+| `judge.endpoint` | `ATBASH_ENDPOINT` | `judgeEndpoint` | Must pass the endpoint rules below. |
+| `judge.verifyPubKey` | `ATBASH_JUDGE_VERIFY_PUBKEY` | `judgeVerifyPubKey` | 66-hex response-signing key of a self-hosted judge. Set through the environment or `config.json` without an endpoint, it throws; passed in `judge` without an endpoint, the default endpoint is used. |
+| `network` | `ATBASH_DEFAULT_CHAIN_NETWORK` | `defaultChainNetwork` | Only `"private"` is accepted; anything else throws. A client that names no chain is pinned to it, even for an org the dashboard places on another chain. |
+| `debug` | `ATBASH_DEBUG` | `debug` | `1`, `true` or `yes` turns diagnostics on. |
+| `orgName` | `ATBASH_ORG_NAME` | `orgName` | `fromConfig` reads the option only. The env var and file key are read by `resolve("orgName")`, which the CLI and plugins use. |
+
+`agentKey` is not in this table on purpose: the signing key is never read from `config.json` (next section).
+
+Helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
+
+### Which key signs
+
+`fromConfig` picks the first of these that is set:
+
+1. `agentKey` option (hex private key in code).
+2. `keyPath` option. A path that does not exist throws; the SDK never falls through to another key when you named one.
+3. `ATBASH_AGENT_KEY` environment variable.
+4. `~/.config/atbash/guard-client-key`.
+5. `~/.config/atbash/atbash-client-key`.
+
+If none exists `fromConfig` throws `atbash key file not found. Looked for: <both default paths>`. The bare constructor never reads a key file.
+
+An `agentKey` inside `config.json` is ignored. A settings file is writable by anything on the machine and is shared by every Atbash integration, so it is not allowed to choose who you sign as. When you pass a `logger`, `fromConfig` warns:
+
+```
+[atbash] "agentKey" in config.json is ignored — settings do not choose the signing key. It holds <pubkey>; this client signs as the key file or ATBASH_AGENT_KEY instead. ...
+```
+
+and when no key file exists at all, the "not found" error names the pubkey stranded in `config.json` so you know where it went.
+
+A key file is either `key=value` lines or JSON. Both fields must be present; the public key is re-derived from the private key, and a `0x` prefix is accepted.
+
+```
+privkey=<64 hex>
+pubkey=<66 hex>
+```
+
+```json
+{ "privKey": "<64 hex>", "pubKey": "<66 hex>" }
+```
 
-Persistent config helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
+For adapters and CI, keep the key in a file and point at it with `keyPath` (or let the default path be found). Passing the key on a command line puts it in shell history and process listings.
 
-### Judge endpoint policy
+### What `orgName` does
 
-Both `Atbash.fromConfig()` and the direct constructor validate the judge endpoint before any request is made. `new Atbash(privkey, { endpoint })` accepts only an `https://` allowlisted judge host, or a self-hosted judge when `verifyPubKey` is also given (the 66-hex response-signing key, which then verifies every judge response). Plaintext `http://` is accepted only for loopback (`localhost`, `127.0.0.1`, `::1`) local development. Anything else throws at construction, so a misconfigured or injected endpoint can no longer receive the agent's signed actions or return unsigned verdicts. `validateJudgeEndpoint(...)` exposes the same check.
+`orgName` tells the SDK which chain to sign the call for: the org's network is looked up once through the dashboard, cached per client, and every judge and log call is signed for that chain. The SDK does not check that the name matches the org the agent was registered under; which org's policy judges the action is decided by the agent's registration, not by this string. On a deployment with a single chain a missing or different `orgName` therefore does not change the verdict. Org-scoped reads such as `getOrgTierInfo(orgName)` send the name as given; the dashboard answers an agent-authenticated call for the agent's own org, whatever name was passed.
 
-Agent policy and detail reads can resolve the organization's active network, or
-accept an explicit network override:
+Agent policy and detail reads can take the org, or an explicit chain:
 
 ```ts
 await atbash.getAgentPolicy(atbash.pubkey, { orgName: "acme" });
@@ -160,6 +200,41 @@ await atbash.getAgentDetail(atbash.pubkey, {
 });
 ```
 
+### Judge endpoint rules
+
+Both `fromConfig` and the constructor validate the endpoint before any request. `validateJudgeEndpoint(...)` exposes the same check.
+
+- With no endpoint configured the SDK talks to the endpoint compiled into the build (`https://atbash.ai` for a release build).
+- An `https://` endpoint is accepted without further setup only on the trusted hosts: `atbash.ai`, `www.atbash.ai` and the build's own default host.
+- Any other `https://` endpoint is a self-hosted judge. It needs `policy: "self-hosted"` plus `verifyPubKey` (the judge's 66-hex compressed response-signing key), or `ATBASH_ENDPOINT` plus `ATBASH_JUDGE_VERIFY_PUBKEY`. Every judge response is then signature-checked against that key. Without the key the constructor throws `judge endpoint hostname "<host>" is not in the trusted allowlist`.
+- Plain `http://` is accepted only for loopback (`localhost`, `127.0.0.1`, `::1`), for a dashboard running on the same machine. Any other `http://` endpoint throws.
+- A URL with embedded credentials (`user:pass@host`) throws.
+
+```ts
+const atbash = Atbash.fromConfig({
+  judge: {
+    policy: "self-hosted",
+    endpoint: "https://judge.example.com",
+    verifyPubKey: "02…66 hex…",
+  },
+});
+```
+
+### From a key file to a first ALLOW
+
+1. Download the key file the onboarding wizard offers at its Deploy step (it is in the `key=value` form above) and save it, for example as `./agent.key`.
+2. Build the client from that file and judge an action:
+
+```ts
+import { Atbash } from "@atbash/sdk";
+
+const atbash = Atbash.fromConfig({ keyPath: "./agent.key" });
+const result = await atbash.judgeAction("read file", "list the files in ./src");
+console.log(result.allow, result.enforced, result.reason);
+```
+
+Dropping the same file at `~/.config/atbash/guard-client-key` lets `Atbash.fromConfig()` find it with no options at all.
+
 ## Error handling
 
 The SDK throws standard `Error` objects. Known failure modes are enriched with a pointer to the dashboard page that fixes them:

package/dist/browser.d.mts

@@ -38,8 +38,12 @@ interface ChainConfig {
     readonly blockchainRid: string;
     readonly nodeUrls: readonly string[];
 }
-declare const PUBLIC_CHAIN: ChainConfig;
 declare const PRIVATE_CHAIN: ChainConfig;
+/**
+ * The chain a network name selects. Only `"private"` exists; any other value,
+ * including `"public"` from an untyped caller, is refused with the same
+ * message the config switch gives, never routed to private in silence.
+ */
 declare function chainForNetwork(network: Network): ChainConfig;
 
 /**
@@ -130,13 +134,11 @@ interface MemoryScanOptions {
     toolArgsJson?: string;
 }
 /**
- * Which Atbash chain an action runs against. `public` is the shared
- * testnet (Free plan); `private` is reserved for Private / Swarm /
- * Enterprise tier subscribers. The SDK resolves which one to use from
- * the org's subscription via `orgName` — callers normally don't need
- * to pass this manually.
+ * Chain selector. Only `"private"` exists: the public testnet chains are
+ * retired. The SDK resolves an org's chain through the Dashboard via
+ * `orgName` — callers normally don't need to pass this manually.
  */
-type Network = "public" | "private";
+type Network = "private";
 /**
  * Per-call chain overrides. Pass exactly what you need to override —
  * `network` selects between the SDK's known chains, `blockchainRid` pins a
@@ -340,7 +342,7 @@ interface AtbashOptions {
      */
     chain?: ChainConfig;
     /**
-     * Preset chain selector — `"public"` or `"private"`. Resolves to the
+     * Preset chain selector — `"private"` is the only value. Resolves to the
      * matching `ChainConfig` via `chainForNetwork()`. Overridden by `chain`,
      * overrides env `ATBASH_DEFAULT_CHAIN_NETWORK` and the config file.
      */
@@ -748,12 +750,9 @@ declare class Atbash {
      * Resolve which chain an org's actions should run against. Cached
      * per-client by orgName. Resolution order:
      *   1. `org_networks` map (authoritative).
-     *   2. Per-chain subscription fallback — public + private records
-     *      are fetched in parallel, with `is_private_blockchain` and
-     *      `assigned_at` reconciling mixed states.
-     * A lookup that names exactly one chain wins outright. Where it names
-     * neither (a brand-new org) or cannot choose between them, the client's
-     * configured default decides.
+     *   2. Subscription fallback — the org's subscription row on the chain.
+     * A lookup that finds the org wins outright. Where it finds nothing (a
+     * brand-new org), the client's configured default decides.
      */
     resolveChainForOrg(orgName: string): Promise<ChainConfig>;
     /**
@@ -870,8 +869,6 @@ declare function releaseJailHolds(): void;
 declare function configureJailHold(next: Partial<typeof DEFAULTS>): void;
 
 declare const DEFAULT_ENDPOINT: string;
-declare const DEFAULT_CHROMIA_NODE_URLS: readonly string[];
-declare const DEFAULT_BLOCKCHAIN_RID: string;
 
 declare class AtbashAPIError extends Error {
     /** HTTP status code (or 0 if the request never completed). */
@@ -1157,11 +1154,18 @@ declare function getRecentAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts, fi
  * when you need every active version regardless of age.
  */
 declare function getActiveAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
+interface MemoryHistoryPage {
+    /** Most versions to return, at most 200. Omit for the full history. */
+    maxCount?: number;
+    /** Return only versions with a lower id: the last id of the previous page. */
+    beforeId?: number;
+}
 /**
  * Full version history — active + inactive, most recent first. Used
- * by rollback UX to choose a target version.
+ * by rollback UX to choose a target version. Pass `page` to read it in
+ * pages; this needs a Dashboard and chain that support paging.
  */
-declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
+declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null, page?: MemoryHistoryPage): Promise<AgentMemoryEntry[]>;
 /**
  * Fetch a single memory entry by version id, including its current
  * `is_active` state. Version ids are agent-unique on chain (not
@@ -1991,4 +1995,4 @@ declare function containsSecret(text: string): boolean;
 declare function createMemorySnapshot(entries: MemoryEntry[], takenAt: number): MemorySnapshot;
 declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
 
-export { type ActionType, type AgentAuth, type AgentLookupOptions, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, JudgeRefusalError, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OperationEvent, type OrgSubscription, PRIVATE_CHAIN, PUBLIC_CHAIN, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, canonicalAllow, chainForNetwork, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, configureEvents, configureJailHold, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, eventsAreOn, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, guardMemoryWrite, isEnvelope, isJailHeld, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, memorySlotOf, normalizeActionForHash, normalizeActionType, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, recordEvent, redactJsonStrings, redactSecrets, releaseJailHolds, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };
+export { type ActionType, type AgentAuth, type AgentLookupOptions, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, JudgeRefusalError, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, type MemoryHistoryPage, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OperationEvent, type OrgSubscription, PRIVATE_CHAIN, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, canonicalAllow, chainForNetwork, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, configureEvents, configureJailHold, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, eventsAreOn, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, guardMemoryWrite, isEnvelope, isJailHeld, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, memorySlotOf, normalizeActionForHash, normalizeActionType, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, recordEvent, redactJsonStrings, redactSecrets, releaseJailHolds, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };