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

package/README.md

@@ -84,6 +84,10 @@ Every `judgeAction` call returns one of three verdicts:
 
 > **Gate on `allow`, not on `verdict`.** `allow` is the canonical permission the SDK computes from every signal in the response; `verdict` is one of those signals, and reads as the reason. The two differ when an organisation does not enforce an agent's verdicts — Shadow Mode on an agent, or org-wide Monitor mode — where the action is judged and recorded on chain but deliberately not applied. Branching on `verdict` re-derives a denial the organisation chose not to make.
 
+> **Shadow and Monitor mode.** On a judge host whose replies are signature-checked, `auditToolCall` asks the judge for its true verdict and the organisation's mode, and applies the mode itself. Under a signed `shadow`, `monitor` or `off` mode, a BLOCK or HOLD still runs (`allow: true`, `verdict: "ALLOW"`) and `decision.wouldVerdict` says what would have happened; it is also logged as a warning. A missing, unsigned or unknown mode enforces. Set `enforceLocally: true` to enforce every verdict whatever the mode; the SDK then asks the judge to judge every call before answering, and refuses a reply that does not confirm it, so against a judge without client enforcement every call is refused. `getJudgmentStatus` applies the mode the same way, so a shadow call polled later reports its `wouldVerdict` while `allow` stays true. `judgeAction` does not opt in and returns what the server sends. To poll a HOLD, call `getJudgmentStatus(decision.judgmentId || decision.toolCallId)` (or the same fields of a `judgeAction` result): on the on-chain judge path the verdict is recorded under its own id.
+
+> **Verdict record.** `decision.record` says what the judge stated about recording the verdict: `onChain`, `status` (its `on_chain_status`, such as `pending`), `boundToCall` (the reply names this call's ids), `signatureChecked` (a judge key verified the reply) and `judgeStatus` (`shadow_recorded` for a shadow ack, which has no verdict yet). A host that must not run an unrecorded action gates on `verdictRecorded`: a signed reply about this call that states `on_chain` and carries a verdict, so a shadow ack or a logged-only answer is never one. `undefined` means unknown: treat it as not recorded. It is informational; `allow` remains the gate.
+
 > **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.
 
 ## API
@@ -111,7 +115,7 @@ Read-only methods that read from the Chromia blockchain and dashboard.
 | `getToolCallFull(toolCallId)` | Full details of a single tool call |
 | `getOrgTierInfo(orgName)` | Check an org's tier and whether verdicts are enabled |
 | `getAgentDetail(pubkey, options?)` | Get agent metadata (org, status, creation date) |
-| `getAgentPolicy(pubkey, options?)` | Check the agent's policy pack and jail status |
+| `getAgentPolicy(pubkey, options?)` | Check the agent's jail status; the policy text is served to the org owner only |
 | `getPendingHeldActions(orgName, maxCount)` | List actions waiting for operator approval |
 | `getHeldActionReviews(orgName, maxCount)` | List completed operator reviews |
 | `getSafetyStats()` | Chain-wide safety statistics |
@@ -206,6 +210,7 @@ Both `fromConfig` and the constructor validate the endpoint before any request.
 
 - 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.
+- On the trusted hosts, every judge response and status poll must carry a valid signature from one of the response-signing keys built into the SDK; an unsigned or forged reply is denied, whatever `failClosed` says. No setup is needed. A `verifyPubKey` set for such a host must be one of those keys, or the constructor throws `not the response-signing key pinned for <host>`. A build with no keys for its host leaves replies unchecked, as before.
 - 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.

package/dist/browser.d.mts

@@ -31,6 +31,31 @@ interface ValidatedEndpoint {
  * @internal
  */
 declare function buildAllowedJudgeHosts(): ReadonlySet<string>;
+/**
+ * Pin keys for a loopback judge, so tests can drive the pinned-host path
+ * against a local server.
+ *
+ * Only loopback hosts read this, and their traffic never leaves the machine,
+ * so it cannot loosen the check on a real Atbash host.
+ *
+ * @internal
+ * @param keys - Compressed pubkeys to pin; `[]` clears them.
+ */
+declare function setLoopbackJudgePinsForTests(keys: readonly string[]): void;
+/**
+ * The keys a judge reply must be signed by, for one endpoint.
+ *
+ * An Atbash host's pinned keys always decide: a configured `verifyPubKey` on
+ * such a host must be one of them, or the client refuses to start, because a
+ * key that only had to come from config could be anyone's. A host with no pins
+ * uses the configured key, or none.
+ *
+ * @param endpoint - The validated judge endpoint URL.
+ * @param configuredKey - The `verifyPubKey` the caller configured, if any.
+ * @returns The accepted keys, current first; empty means replies are not checked.
+ * @throws When `configuredKey` is not one of the host's pinned keys.
+ */
+declare function judgeVerifyKeys(endpoint: string, configuredKey?: string): readonly string[];
 declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
 
 interface ChainConfig {
@@ -195,7 +220,15 @@ interface JudgeResult {
     provider: string;
     latencyMs: number;
     toolCallId: string;
+    /**
+     * The id the judge recorded this verdict under, when it differs from
+     * `toolCallId` (the on-chain judge path). Poll `getJudgmentStatus` with
+     * `judgmentId || toolCallId`. Absent when the reply names none.
+     */
+    judgmentId?: string;
     onChain: boolean;
+    /** What the reply stated about the chain; see {@link VerdictRecord}. */
+    record?: VerdictRecord;
     /** Severity 1 (poisonous) → 10 (benign). Present on memory-scan responses; absent for regular tool-call judgments. */
     score?: number;
     /**
@@ -231,6 +264,12 @@ interface JudgmentStatus {
     onChain?: boolean;
     cached?: boolean;
     responseTimeMs?: number;
+    /**
+     * The verdict the judge reached (`"BLOCK"` or `"HOLD"`) when the
+     * organisation's signed mode (`shadow`, `monitor`, `off`) let the action run
+     * anyway, as {@link Decision.wouldVerdict}. Absent when the status is the verdict.
+     */
+    wouldVerdict?: "BLOCK" | "HOLD";
 }
 interface TierInfo {
     orgName: string;
@@ -398,6 +437,14 @@ interface AtbashOptions {
      * off).
      */
     requireEnforcement?: boolean;
+    /**
+     * When true, `auditToolCall` enforces the judge's verdict whatever
+     * enforcement mode the organisation is in. Default false: on a judge host
+     * whose replies are signature-checked, a signed `shadow`, `monitor` or `off`
+     * mode lets a BLOCK or HOLD run, reported in `Decision.wouldVerdict`. This
+     * can only make the client stricter.
+     */
+    enforceLocally?: boolean;
     /**
      * Verbose diagnostics. Off by default. When on, a failed judge call also
      * logs the response body, which is the difference between "judge API failed"
@@ -406,6 +453,44 @@ interface AtbashOptions {
     debug?: boolean;
     logger?: AtbashLogger;
 }
+/**
+ * What the judge stated about recording this verdict. A host that must not run
+ * an unrecorded action gates on `verdictRecorded`. `onChain` is the judge's
+ * statement: the SDK does not read the chain.
+ */
+interface VerdictRecord {
+    /** The judge's `on_chain`: the verdict is recorded on chain. */
+    onChain: boolean;
+    /** The judge's `on_chain_status`, such as `pending` or `skipped`; absent when not stated. */
+    status?: string;
+    /**
+     * The reply names the ids this call generated. False when it names another
+     * call, or none: `toolCallId` then falls back to this client's own id, which
+     * proves nothing about what the judge recorded.
+     */
+    boundToCall: boolean;
+    /**
+     * This reply's signature was checked against a judge key before it was read.
+     * False means nothing proves who wrote the reply: it can echo this call's ids
+     * and still read as bound, because the ids travel in the request.
+     */
+    signatureChecked: boolean;
+    /**
+     * The judge's own `status`, absent when not stated. `shadow_recorded` is a
+     * shadow ack: the call was stored and has no verdict yet, which is what
+     * separates it from an ALLOW whose `status` here is `pending`. Read it with
+     * `boundToCall` and `signatureChecked`: unsigned, it is only a claim.
+     */
+    judgeStatus?: string;
+    /**
+     * The judge answered this call with a verdict it states is recorded on chain,
+     * in a signature-checked reply: `onChain`, `boundToCall` and `signatureChecked`
+     * all true, and no `judgeStatus`, which only a reply without a verdict carries
+     * (a shadow ack, or an answer that was only logged). Still the judge's word:
+     * the SDK does not read the chain.
+     */
+    verdictRecorded: boolean;
+}
 /** Canonical decision returned by `auditToolCall`. */
 type DecisionVerdict = "ALLOW" | "HOLD" | "BLOCK" | "ERROR";
 interface Decision {
@@ -422,6 +507,25 @@ interface Decision {
     enforced?: boolean;
     /** Server-reported protection mode (`off`, `monitor`, `enforce`); absent when unknown. */
     enforcementMode?: string;
+    /**
+     * The verdict the judge reached when the organisation's signed mode
+     * (`shadow`, `monitor`, `off`) let the action run anyway: what would have
+     * happened under enforcement. Absent when the decision is the verdict.
+     */
+    wouldVerdict?: "BLOCK" | "HOLD";
+    /**
+     * The id the judge recorded this verdict under, when it differs from
+     * `toolCallId` (the on-chain judge path), as {@link JudgeResult.judgmentId}.
+     * Poll `getJudgmentStatus` with `judgmentId || toolCallId`.
+     */
+    judgmentId?: string;
+    /**
+     * What the judge stated about recording this verdict. Absent means unknown:
+     * a transport error, a local jail hold, or a reply that did not state
+     * `on_chain`. Treat absent as not recorded. Informational only; `allow`
+     * remains the gate.
+     */
+    record?: VerdictRecord;
 }
 /** Input to `auditToolCall`. */
 interface ToolCallInput {
@@ -459,6 +563,8 @@ interface FromConfigOptions {
     failClosed?: boolean;
     /** See {@link AtbashOptions.requireEnforcement}. Default true. */
     requireEnforcement?: boolean;
+    /** See {@link AtbashOptions.enforceLocally}. Default false. */
+    enforceLocally?: boolean;
     /** See {@link AtbashOptions.decisionTimeoutMs}. Default 60 000 ms. */
     decisionTimeoutMs?: number;
     /** See {@link AtbashOptions.debug}. */
@@ -513,12 +619,21 @@ declare class Atbash {
     readonly orgName?: string;
     /** Default judge response-signing pubkey, if configured (see fromConfig). */
     readonly verifyPubKey?: string;
+    /**
+     * The keys every judge reply must be signed by: the host's pinned keys, or
+     * the configured `verifyPubKey` on a host with none. Empty means unchecked.
+     */
+    private readonly verifyKeys;
     /** Default org encryption key — see {@link AtbashOptions.orgEncryptionPubKey}. */
     readonly orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     readonly failClosed: boolean;
     /** When true (default), an unenforced (audit-tier) answer is refused. */
     readonly requireEnforcement: boolean;
+    /** When true, a signed non-enforcing mode never relaxes a verdict. */
+    readonly enforceLocally: boolean;
+    /** Results whose enforcement mode came signed and bound to their call. */
+    private readonly modeTrusted;
     /** Overall deadline for one auditToolCall decision, in ms. */
     readonly decisionTimeoutMs: number;
     /** Org key learned from the last agent-exists check, for this agent only. */
@@ -659,12 +774,25 @@ declare class Atbash {
      * response bytes via the Rust core's `verifySignature`.
      */
     judgeAction(action: string, context?: string, options?: JudgeOptions): Promise<JudgeResult>;
+    /**
+     * judgeAction, optionally asking the judge for the true verdict and the
+     * organisation's enforcement mode so this client applies the mode itself.
+     *
+     * Only auditToolCall opts in: judgeAction's callers keep the server-side
+     * downgrade they gate on today.
+     *
+     * @param clientEnforces - Send `X-Atbash-Client-Enforcement` when the reply can be trusted.
+     */
+    private judgeTracked;
     private _judgeAction;
     /**
-     * Start a local hold on an enforced, on-chain BLOCK (the verdict that jails).
-     * Refuse any other result that lands while the agent is held, or whose
-     * request was already in flight when the block arrived: the server judged it
-     * on pre-jail state.
+     * Start a local hold on an enforced BLOCK that jails: one already on chain,
+     * or one the judge answered before its chain write landed
+     * (`on_chain_status: "pending"`), which jails once it lands. Refuse any other
+     * result that lands while the agent is held, or whose request was already in
+     * flight when the block arrived: the server judged it on pre-jail state.
+     *
+     * @param onChainStatus - The reply's `on_chain_status`; empty when absent.
      */
     private applyJailHold;
     /** The server's jailed refusal, produced locally while the agent is held. */
@@ -677,12 +805,12 @@ declare class Atbash {
      */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
     /**
-     * The verify key for one call (R4, governor tier-2 review). A per-call key
-     * may only narrow what the client accepts: on a client pinned to a judge
-     * key it must be that same key, never a replacement; on an unpinned client
-     * it adds the check.
+     * The verify keys for one call (R4, governor tier-2 review). A per-call key
+     * may only narrow what the client accepts: on a client pinned to judge keys
+     * it must be one of them, never a replacement; on an unpinned client it
+     * adds the check.
      */
-    private effectiveVerifyKey;
+    private effectiveVerifyKeys;
     /**
      * Collapse a judge result into a {@link Decision}. The most restrictive
      * signal wins (security review 2026-09-30, H1): `action_type`, `verdict`
@@ -693,6 +821,15 @@ declare class Atbash {
      * never overrides a refusal.
      */
     private decide;
+    /**
+     * Apply the organisation's enforcement mode to the judge's true verdict.
+     *
+     * Only a mode that arrived signed and bound to this call counts; a missing,
+     * unsigned or unknown mode, or enforceLocally, means enforce. Under
+     * `shadow`, `monitor` or `off` a BLOCK or HOLD runs, reported in
+     * `wouldVerdict`. An ERROR stays an error: it is not a verdict.
+     */
+    private applyMode;
     private decideInner;
     /**
      * One exit for every judge failure.
@@ -1995,4 +2132,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_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 };
+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 VerdictRecord, 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, judgeVerifyKeys, 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, setLoopbackJudgePinsForTests, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };