@atbash/sdk 0.10.13-dev.0 → 0.13.0-dev.0

package/README.md

@@ -142,12 +142,17 @@ const atbash = Atbash.fromConfig();   // reads env + config file
 | `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` |
 | `provider` | `ATBASH_PROVIDER` |
 | `providerModel` | `ATBASH_PROVIDER_MODEL` |
 
 Persistent config helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
 
+### Judge endpoint policy
+
+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.
+
 Agent policy and detail reads can resolve the organization's active network, or
 accept an explicit network override:
 

package/dist/browser.d.mts

@@ -30,6 +30,15 @@ interface ValidatedEndpoint {
 declare function buildAllowedJudgeHosts(): ReadonlySet<string>;
 declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
 
+interface ChainConfig {
+    readonly network: Network;
+    readonly blockchainRid: string;
+    readonly nodeUrls: readonly string[];
+}
+declare const PUBLIC_CHAIN: ChainConfig;
+declare const PRIVATE_CHAIN: ChainConfig;
+declare function chainForNetwork(network: Network): ChainConfig;
+
 /**
  * User-facing types. Two groups:
  *  - Core types — the exact shapes the Rust core emits across the NAPI
@@ -290,7 +299,24 @@ interface AtbashLogger {
 interface AtbashOptions {
     endpoint?: string;
     timeoutMs?: number;
+    /**
+     * Full chain override — BRID + nodeUrls in one object. Wins over every
+     * other chain selector. Prefer this over paired `nodeUrls`/`blockchainRid`
+     * for anything but backwards compatibility.
+     */
+    chain?: ChainConfig;
+    /**
+     * Preset chain selector — `"public"` or `"private"`. Resolves to the
+     * matching `ChainConfig` via `chainForNetwork()`. Overridden by `chain`,
+     * overrides env `ATBASH_DEFAULT_CHAIN_NETWORK` and the config file.
+     */
+    network?: Network;
+    /**
+     * Explicit node URLs. Must be paired with `blockchainRid`. Passing one
+     * without the other throws — a BRID/nodes mismatch 404s every request.
+     */
     nodeUrls?: readonly string[];
+    /** Explicit BRID. Must be paired with `nodeUrls`. See {@link nodeUrls}. */
     blockchainRid?: string;
     /**
      * Default org name. When set, `judgeAction` / `auditToolCall` resolve
@@ -357,6 +383,10 @@ interface FromConfigOptions {
     keyPath?: string;
     /** Judge endpoint config — validated against the allowlist / self-hosted policy. */
     judge?: JudgeEndpointConfig;
+    /** See {@link AtbashOptions.chain}. */
+    chain?: ChainConfig;
+    /** See {@link AtbashOptions.network}. */
+    network?: Network;
     blockchainRid?: string;
     timeoutMs?: number;
     nodeUrls?: readonly string[];
@@ -408,12 +438,6 @@ interface LogToolCallOptions {
     orgEncryptionPubKey?: string;
 }
 
-interface ChainConfig {
-    readonly network: Network;
-    readonly blockchainRid: string;
-    readonly nodeUrls: readonly string[];
-}
-
 declare class Atbash {
     readonly auth: AgentAuth;
     readonly endpoint: string;
@@ -437,6 +461,27 @@ declare class Atbash {
      * calls don't re-hit the dashboard. Cleared by `clearChainCache()`.
      */
     private readonly _chainCache;
+    /**
+     * The chain the constructor settled on. Used only where a lookup returns no
+     * answer — see {@link resolveChainFromMap}.
+     */
+    private readonly _defaultChain;
+    /**
+     * True when the caller named a chain outright — `chain`, `network`, or the
+     * paired `blockchainRid` + `nodeUrls`.
+     *
+     * Such a client is never re-pointed: not by the migration switch, and not by
+     * where an org turns out to live. Naming a chain is the caller saying "talk
+     * to this one", and silently routing elsewhere would make the argument a
+     * suggestion. A client that names nothing is the one that follows the org.
+     */
+    private readonly _explicitChain;
+    /**
+     * The fleet-wide chain switch, read once at construction. `resolve()` hits
+     * the config file on disk, so re-reading it per call would put a file read
+     * on every judge.
+     */
+    private readonly _forcedNetwork;
     /**
      * Short-TTL cache for `/api/ai/exists`. The `registered` field is
      * monotonic (once true, stays true), so most calls in a burst re-fetch
@@ -552,7 +597,9 @@ declare class Atbash {
      *   2. Per-chain subscription fallback — public + private records
      *      are fetched in parallel, with `is_private_blockchain` and
      *      `assigned_at` reconciling mixed states.
-     * Defaults to the public chain when nothing else resolves.
+     * 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.
      */
     resolveChainForOrg(orgName: string): Promise<ChainConfig>;
     /**
@@ -606,6 +653,25 @@ declare class Atbash {
      * back to the client default (best-effort discovery).
      */
     private bridForOrg;
+    /**
+     * BRID for the client's configured default org, if it has one.
+     *
+     * Calls that carry no `orgName` argument are not chain-less: they still
+     * belong to `this.orgName`, and that org lives on exactly one chain. Routing
+     * them by the constructor's chain instead means a client configured
+     * `network: "private"` reads the private chain for an org that lives on
+     * public, and gets an empty answer rather than an error. So where an org is
+     * known the org decides the chain, and the constructor's chain is what is
+     * left when no org is known at all — the order `resolveAgentLookupNetwork`
+     * already applies to agent metadata reads, and the order the dashboard
+     * applies in `resolveChainForWallet`.
+     *
+     * Undefined when there is no default org, so callers keep falling back to
+     * the client default.
+     */
+    /** The switch's chain, unless this client named one of its own. */
+    private forcedNetwork;
+    private defaultOrgBrid;
     private raiseIfError;
     /** Wrap a failed HTTP *response* (non-2xx / non-200) as an AtbashAPIError. */
     private httpError;
@@ -689,7 +755,20 @@ interface AtbashUserConfig {
     agentKey?: string;
     orgName?: string;
     judgeEndpoint?: string;
-    blockchainRid?: string;
+    /**
+     * Response-signing pubkey of a self-hosted judge (66 hex). Setting it makes
+     * `fromConfig` use the self-hosted policy for `judgeEndpoint`, which is the
+     * only way a non-allowlisted judge host is accepted.
+     */
+    judgeVerifyPubKey?: string;
+    /**
+     * `"private"` pins every org to the private chain regardless of where the
+     * dashboard says it lives — the migration switch. Leave it unset for the
+     * normal mode, where each org's own chain decides. There is no `"public"`
+     * value; a caller that wants one specific chain passes `chain` or `network`
+     * at construction instead.
+     */
+    defaultChainNetwork?: Network;
     provider?: string;
     providerModel?: string;
     /** "1" / "true" turns on verbose diagnostics. See AtbashOptions.debug. */
@@ -791,15 +870,26 @@ declare function scanMemoryBatch(entries: MemoryEntry[], auth: AgentAuth, opts?:
 interface CommitMemoryOptions {
     /** Score in [1, 10]. Defaults to 5 (matches the Rell entity default). */
     score?: number;
+    /**
+     * Which memory file this commit targets. Defaults to `""` — the
+     * un-pathed slot, matching Rell's `file_path: text = ""` default.
+     * Pass an explicit filename (e.g. `"AGENTS.md"`) to keep files
+     * versioned independently on chain.
+     */
+    filePath?: string;
     /** Org name — when set, the SDK resolves which chain the agent lives on. */
     orgName?: string;
     /** Atbash service endpoint for org→chain lookup. */
     endpoint?: string;
+    /** Self-hosted judge response-signing pubkey; required with a non-allowlisted `endpoint`. */
+    verifyPubKey?: string;
     chainOpts?: ChainOpts;
 }
 interface RollbackMemoryOptions {
     orgName?: string;
     endpoint?: string;
+    /** Self-hosted judge response-signing pubkey; required with a non-allowlisted `endpoint`. */
+    verifyPubKey?: string;
     chainOpts?: ChainOpts;
 }
 /**
@@ -821,6 +911,7 @@ declare function commitMemoryVersion(plaintext: string, auth: AgentAuth, opts?:
  */
 interface AgentMemoryEntry {
     id: number;
+    filePath: string;
     content: string;
     decryptError?: string;
     score: number;
@@ -832,6 +923,7 @@ interface AgentMemoryEntry {
 interface MemoryRollbackEvent {
     fromId: number;
     toId: number;
+    filePath: string;
     reason: string;
     signer: string;
     createdAt: number;
@@ -842,36 +934,39 @@ interface MemoryRollbackEvent {
  * response is a single integer, so this is safe to call on every
  * memory-read hot path.
  */
-declare function getActiveMemoryId(auth: AgentAuth, chainOpts?: ChainOpts): Promise<number | null>;
+declare function getActiveMemoryId(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<number | null>;
 /**
  * Recent active memory entries — subset of active versions filtered
  * by the chain's `MEMORY_RECENT_WINDOW_MS`. For a time-unbounded view
- * of every currently active version, use `getAllAgentMemory`.
+ * of every currently active version, use `getActiveAgentMemory`.
  */
-declare function getActiveMemory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getRecentAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
 /**
  * All currently-active memory entries with no time cutoff. Use this
  * when you need every active version regardless of age.
  */
-declare function getAllAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getActiveAgentMemory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
 /**
  * Full version history — active + inactive, most recent first. Used
  * by rollback UX to choose a target version.
  */
-declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry[]>;
+declare function getMemoryHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<AgentMemoryEntry[]>;
 /**
  * Fetch a single memory entry by version id, including its current
- * `is_active` state.
+ * `is_active` state. Version ids are agent-unique on chain (not
+ * per-file), so `id` alone resolves the target row.
  */
 declare function getMemoryById(id: number, auth: AgentAuth, chainOpts?: ChainOpts): Promise<AgentMemoryEntry>;
 /**
  * Audit trail of rollback events for this agent, most recent first.
+ * Scope by file with `filePath`; omit for a cross-file view.
  */
-declare function getRollbackHistory(auth: AgentAuth, chainOpts?: ChainOpts): Promise<MemoryRollbackEvent[]>;
+declare function getRollbackHistory(auth: AgentAuth, chainOpts?: ChainOpts, filePath?: string | null): Promise<MemoryRollbackEvent[]>;
 /**
  * Roll back to a previously-committed memory version. The target
- * `toId` must exist and be currently inactive. `reason` is required
- * and is recorded on-chain in `memory_rollback_log`.
+ * `toId` must exist and be currently inactive. The chain resolves the
+ * target row's `file_path` from `toId` — no file path is passed in.
+ * `reason` is required and is recorded on-chain in `memory_rollback_log`.
  */
 declare function rollbackMemory(toId: number, reason: string, auth: AgentAuth, opts?: RollbackMemoryOptions): Promise<void>;
 
@@ -956,8 +1051,6 @@ interface GuardMemoryWriteInput extends ClassifyMemoryWriteOptions {
     debug?: boolean;
     /** Optional logger for debug probe + persist-failure warnings. */
     logger?: GuardLogger;
-    /** Absolute path of the agent's managed memory file. Required for chain commits — omitted skips them. */
-    memoryFilePath?: string;
 }
 /** Plugin-facing decision. Shape mirrors what plugins return from `before_tool_call`. */
 interface GuardMemoryDecision {
@@ -1378,4 +1471,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 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, 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 OrgSubscription, 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, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, 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_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, 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 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, chainForNetwork, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };