@atbash/sdk 0.3.24 → 0.4.0-dev.0

package/dist/index.d.ts

@@ -1,58 +1,126 @@
-type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
-type Provider = "openai" | "google" | "microsoft" | "custom" | (string & {});
-type ActionType = "allow" | "hold_for_user_confirm" | "block" | (string & {});
-type PubkeyValue = string | Buffer | {
-    data: number[];
+type JudgeEndpointConfig = {
+    policy?: "default";
+    endpoint?: string;
+} | {
+    policy: "self-hosted";
+    endpoint: string;
+    verifyPubKey: string;
 };
-type JudgmentStatusState = "pending" | "answered" | "error";
-interface Subscription {
-    subscription_name: string;
-    agent_number: number;
-    is_private_blockchain: boolean;
-    monthly_price: number;
-    yearly_price: number;
+interface ValidatedEndpoint {
+    url: string;
+    policy: "default" | "self-hosted";
+    verifyPubKey: string | null;
 }
-interface OrgSubscription extends Subscription {
-    org_name: string;
-    duration_months: number;
-    assigned_at: number;
-    expires_at: number;
-    is_active: boolean;
+declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
+
+/**
+ * User-facing types. Two groups:
+ *  - Core types — the exact shapes the Rust core emits across the NAPI
+ *    boundary (field names match the serde output byte-for-byte).
+ *  - SDK types — the HTTP-facing result shapes the `Atbash` client returns,
+ *    already normalized (verdict casing, status).
+ */
+/** `generate_keypair` result. Note the `priv_key` / `pub_key` field names. */
+interface KeyPair {
+    priv_key: string;
+    pub_key: string;
 }
+/** `load_agent` result. Note the `privkey` / `pubkey` field names. */
 interface AgentAuth {
-    pubkey: string;
     privkey: string;
+    pubkey: string;
 }
-interface ClientOpts {
-    endpoint?: string;
-    timeout?: number;
-    auth?: AgentAuth;
+interface SecretMatch {
+    kind: string;
+    length: number;
+}
+interface RedactResult {
+    redacted: string;
+    found: SecretMatch[];
+}
+interface MemoryEntry {
+    key: string;
+    value: string;
+    source?: string;
+    timestamp?: number;
+}
+interface MemorySnapshot {
+    entries: MemoryEntry[];
+    takenAt: number;
+}
+interface ModifiedEntry {
+    key: string;
+    before: string;
+    after: string;
 }
+type AnomalyType = "behavioral_override" | "bulk_insertion" | "safety_bypass" | "privilege_escalation" | "gradual_drift";
+type AnomalySeverity = "low" | "medium" | "high" | "critical";
+interface MemoryAnomaly {
+    type: AnomalyType;
+    severity: AnomalySeverity;
+    description: string;
+    entries: string[];
+}
+interface MemoryDiffResult {
+    safe: boolean;
+    added: MemoryEntry[];
+    removed: MemoryEntry[];
+    modified: ModifiedEntry[];
+    anomalies: MemoryAnomaly[];
+}
+/**
+ * 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.
+ */
+type Network = "public" | "private";
+/**
+ * Per-call chain overrides. Pass exactly what you need to override —
+ * `network` selects between the SDK's known chains, `blockchainRid` /
+ * `nodeUrls` pin a fully custom chain. Pass none of these to fall back
+ * to the SDK's defaults (or to org-resolved chain when `orgName` is set).
+ */
 interface ChainOpts {
-    nodeUrls?: string[];
+    network?: Network;
     blockchainRid?: string;
+    nodeUrls?: readonly string[];
+}
+/** Canonical verdict after normalization. */
+type Verdict = "ALLOW" | "HOLD" | "BLOCK" | "No verdict";
+/** Canonical judgment status after normalization. */
+type JudgmentState = "pending" | "answered" | "error";
+/**
+ * Provider attribution on a judged action. The trailing `string & {}`
+ * accepts custom provider names without losing autocompletion on the
+ * canonical ones.
+ */
+type Provider = "openai" | "google" | "microsoft" | "custom" | (string & {});
+/** Verdict action_type carried in the judge response. */
+type ActionType = "allow" | "hold_for_user_confirm" | "block" | (string & {});
+/** Pubkey value as accepted on the wire — hex string, Buffer, or GTV bytes. */
+type PubkeyValue = string | Buffer | {
+    data: number[];
+};
+interface LogToolCallResult {
+    success: boolean;
+    toolCallId: string | null;
+    signedHex?: string;
+    error?: string;
 }
 interface JudgeResult {
     verdict: Verdict;
-    action_type: ActionType;
+    actionType: string;
     reason: string;
     confidence: number;
-    provider: Provider;
-    latency_ms: number;
-    tool_call_id: string;
-    on_chain: boolean;
-}
-interface JudgeOptions extends ClientOpts {
-    provider?: Provider;
-    model?: string;
-    toolName?: string;
-    toolArgsJson?: string;
-    orgName?: string;
-    chainOpts?: ChainOpts;
-    verifyPubKey?: string;
+    provider: string;
+    latencyMs: number;
+    toolCallId: string;
+    onChain: boolean;
 }
 interface JudgmentStatus {
-    status: JudgmentStatusState;
+    status: JudgmentState;
     verdict: Verdict;
     reason: string;
     judgmentId: string;
@@ -60,56 +128,115 @@ interface JudgmentStatus {
     cached?: boolean;
     responseTimeMs?: number;
 }
-interface ToolCallRecord {
-    tool_call_id: string;
-    agent_pubkey: PubkeyValue;
-    tool_name: string;
-    command_text: string;
-    tool_args_json: string;
-    context_text: string;
+interface TierInfo {
+    orgName: string;
+    tier: string;
+    verdictEnabled: boolean;
+    enforcementEnabled: boolean;
+}
+/**
+ * Plan-level subscription metadata. Returned by `org-subscription` —
+ * field names match the on-chain shape (snake_case) so the response
+ * can be inspected without renaming.
+ */
+interface Subscription {
+    subscription_name: string;
+    agent_number: number;
+    is_private_blockchain: boolean;
+    monthly_price: number;
+    yearly_price: number;
+}
+/**
+ * Org's binding to a subscription on a specific chain. The chain is
+ * implied by which BRID the query hit (controlled by the `network`
+ * query param when fetching).
+ */
+interface OrgSubscription extends Subscription {
     org_name: string;
+    duration_months: number;
+    assigned_at: number;
+    expires_at: number;
+    is_active: boolean;
+}
+interface ToolCallRecord {
+    toolCallId: string;
+    agentPubkey: string;
+    toolName: string;
+    commandText: string;
+    toolArgsJson: string;
+    contextText: string;
+    orgName: string;
     rowid: number;
 }
 interface ToolCallFull {
-    tool_call_id: string;
-    agent_pubkey: PubkeyValue;
-    tool_name: string;
-    command_text: string;
-    context_text: string;
-    tool_args_json?: string;
-    org_name: string;
-    created_at?: number;
-    action_type?: ActionType;
-    result_status?: string;
-    verdict_color?: string;
-    verdict_reason?: string;
-    verdict_source?: string;
-    verdict_response_time_ms?: number;
+    toolCallId: string;
+    agentPubkey: string;
+    toolName: string;
+    commandText: string;
+    contextText: string;
+    orgName: string;
+    toolArgsJson?: string;
+    createdAt?: number;
+    actionType?: string;
+    resultStatus?: string;
+    verdictColor?: string;
+    verdictReason?: string;
+    verdictSource?: string;
+    verdictResponseTimeMs?: number;
 }
 interface HeldAction {
-    judgment_id: string;
-    agent_pubkey: PubkeyValue;
-    action_text: string;
-    action_context: string;
+    judgmentId: string;
+    agentPubkey: string;
+    actionText: string;
+    actionContext: string;
     verdict: Verdict;
     reason: string;
-    created_at: number;
+    createdAt: number;
 }
 interface HeldActionReview {
-    judgment_id: string;
-    action_text: string;
+    judgmentId: string;
+    actionText: string;
     status: string;
-    review_note: string;
-    reviewed_by: PubkeyValue | null;
-    reviewed_at: number;
-    created_at: number;
+    reviewNote: string;
+    reviewedAt: number;
+    createdAt: number;
+    reviewedBy?: string;
 }
 interface AgentPolicy {
     policy: string;
-    is_jailed: boolean;
-    is_custom: boolean;
-    default_policy: string;
+    isJailed: boolean;
+    isCustom: boolean;
+    defaultPolicy: string;
+}
+/** Optional structured logger. */
+interface AtbashLogger {
+    info?(...args: unknown[]): void;
+    warn?(...args: unknown[]): void;
+}
+/** Options accepted by the `Atbash` constructor. */
+interface AtbashOptions {
+    endpoint?: string;
+    timeoutMs?: number;
+    nodeUrls?: readonly string[];
+    blockchainRid?: string;
+    /**
+     * Default org name. When set, `judgeAction` / `auditToolCall` resolve
+     * the chain via the `org_networks` map on every call (with the
+     * per-client cache short-circuiting the second hit onwards). Per-call
+     * overrides on the method options still win.
+     */
+    orgName?: string;
+    /**
+     * Default response-signing pubkey for `judgeAction` verification. Set
+     * automatically by `Atbash.fromConfig` for self-hosted endpoints; a
+     * per-call `verifyPubKey` still overrides it.
+     */
+    verifyPubKey?: string;
+    /** When true (default), `auditToolCall` denies on any error. */
+    failClosed?: boolean;
+    logger?: AtbashLogger;
 }
+/** Canonical decision returned by `auditToolCall`. */
 type DecisionVerdict = "ALLOW" | "HOLD" | "BLOCK" | "ERROR";
 interface Decision {
     allow: boolean;
@@ -117,120 +244,259 @@ interface Decision {
     reason?: string;
     toolCallId?: string;
 }
+/** Input to `auditToolCall`. */
 interface ToolCallInput {
     toolName: string;
     args?: unknown;
     context?: string;
 }
-type JudgeEndpointConfig = {
-    policy?: "default";
-    endpoint?: string;
-} | {
-    policy: "self-hosted";
-    endpoint: string;
-    verifyPubKey: string;
-};
-interface ValidatedEndpoint {
-    url: string;
-    policy: "default" | "self-hosted";
-    verifyPubKey: string | null;
-}
-interface MemoryEntry {
-    key: string;
-    value: string;
-    source?: string;
-    timestamp?: number;
-}
-type MemoryScanVerdict = "green" | "yellow" | "red";
-type AnomalySeverity = "low" | "medium" | "high" | "critical";
-type AnomalyType = "behavioral_override" | "bulk_insertion" | "safety_bypass" | "privilege_escalation" | "gradual_drift";
-interface MemoryScanResult {
-    safe: boolean;
-    verdict: MemoryScanVerdict;
-    reason: string;
-    confidence: number;
-    toolCallId?: string;
-}
-interface MemoryScanOptions extends JudgeOptions {
-    /** Confidence threshold below which the entry is allowed (default 0.6). */
-    threshold?: number;
-    /** Stop batch scanning on the first red verdict (default true). */
-    stopOnRed?: boolean;
-}
-interface MemorySnapshot {
-    entries: MemoryEntry[];
-    takenAt: number;
-}
-interface MemoryAnomaly {
-    type: AnomalyType;
-    severity: AnomalySeverity;
-    description: string;
-    entries: string[];
-}
-interface MemoryDiffResult {
-    safe: boolean;
-    added: MemoryEntry[];
-    removed: MemoryEntry[];
-    modified: Array<{
-        key: string;
-        before: string;
-        after: string;
-    }>;
-    anomalies: MemoryAnomaly[];
-}
-interface AtbashClientConfig {
+/** Options accepted by `Atbash.fromConfig`. All fields are explicit overrides. */
+interface FromConfigOptions {
+    /** Inline private key. Overrides env / config-file / key-file resolution. */
+    agentKey?: string;
+    /** Path to the agent key file (default `~/.config/atbash/guard-client-key`). */
+    keyPath?: string;
+    /** Judge endpoint config — validated against the allowlist / self-hosted policy. */
     judge?: JudgeEndpointConfig;
-    nodeUrls?: string[];
     blockchainRid?: string;
+    timeoutMs?: number;
+    nodeUrls?: readonly string[];
+    /** Default org name — see {@link AtbashOptions.orgName}. */
     orgName?: string;
-    keyPath?: string;
-    keyPair?: {
-        privKey: string;
-        pubKey: string;
-    };
     failClosed?: boolean;
-    logger?: {
-        info?(...a: unknown[]): void;
-        warn?(...a: unknown[]): void;
-    };
+    logger?: AtbashLogger;
+}
+/** Options accepted by `judgeAction`. */
+interface JudgeOptions {
+    toolName?: string;
+    toolArgsJson?: string;
+    provider?: string;
+    model?: string;
+    verifyPubKey?: string;
+    /**
+     * Org name — when set, the SDK resolves which chain the agent lives
+     * on via the off-chain `org_networks` map (authoritative) before
+     * signing. Overrides any `chainOpts.blockchainRid` hint when the map
+     * has an entry.
+     */
+    orgName?: string;
+    /**
+     * Explicit per-call chain override. Use to pin a specific chain for
+     * one call; otherwise the SDK uses the constructor defaults or the
+     * org-resolved chain.
+     */
+    chainOpts?: ChainOpts;
+}
+/** Options accepted by `logToolCall`. */
+interface LogToolCallOptions {
+    toolName?: string;
+    toolArgsJson?: string;
+    /** Per-call chain override — same semantics as `JudgeOptions.chainOpts`. */
+    chainOpts?: ChainOpts;
 }
 
-declare const DEFAULT_ENDPOINT = "https://atbash.ai";
-declare const DEFAULT_CHROMIA_NODE_URLS: string[];
-declare const DEFAULT_BLOCKCHAIN_RID = "B91106947F1EAED7B5D789C7D35755330A8A7DD7CB990D59366114EFFB79ED10";
-declare function isValidPrivateKey(hex: string): boolean;
-declare function derivePublicKey(privKeyHex: string): string;
-declare function generateKeyPair(): {
-    privKey: string;
-    pubKey: string;
-};
-declare function loadAgent(privkey: string): AgentAuth;
-declare function toPubkeyHex(val: unknown): string;
-declare function checkAgentExists(pubkey: string, opts?: ClientOpts): Promise<boolean>;
-declare function judgeAction(action: string, context: string | undefined, auth: AgentAuth, opts?: JudgeOptions): Promise<JudgeResult>;
-declare function getJudgmentStatus(judgmentId: string, agentPubkey: string, opts?: ClientOpts): Promise<JudgmentStatus>;
-declare function getToolCalls(maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
-declare function getOrgToolCalls(orgName: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
-declare function getAgentToolCalls(agentPubkey: string, maxCount: number, opts?: ClientOpts): Promise<ToolCallRecord[]>;
-declare function getToolCallCount(opts?: ClientOpts): Promise<number>;
-declare function getToolCallFull(toolCallId: string, opts?: ClientOpts): Promise<ToolCallFull | null>;
-declare function getOrgSubscription(orgName: string, opts?: ClientOpts): Promise<OrgSubscription | null>;
-declare function getPendingHeldActions(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldAction[]>;
-declare function getHeldActionReviews(orgName: string, maxCount: number, opts?: ClientOpts): Promise<HeldActionReview[]>;
-declare function getAgentDetail(agentPubkey: string, opts?: ClientOpts): Promise<Record<string, unknown>>;
-declare function getAgentPolicy(agentPubkey: string, opts?: ClientOpts): Promise<AgentPolicy>;
-declare function getSafetyStats(opts?: ClientOpts): Promise<Record<string, unknown>>;
+interface ChainConfig {
+    readonly network: Network;
+    readonly blockchainRid: string;
+    readonly nodeUrls: readonly string[];
+}
 
-interface AtbashClient {
+declare class Atbash {
+    readonly auth: AgentAuth;
+    readonly endpoint: string;
+    readonly nodeUrls: readonly string[];
+    readonly blockchainRid: string;
+    /** Default org name used by `auditToolCall` / `judgeAction`. */
+    readonly orgName?: string;
+    /** Default judge response-signing pubkey, if configured (see fromConfig). */
+    readonly verifyPubKey?: string;
+    /** When true (default), `auditToolCall` denies on any error. */
+    readonly failClosed: boolean;
+    private readonly logger;
+    private readonly http;
+    /**
+     * Per-client cache of resolved chains. Keyed by orgName so repeated
+     * calls don't re-hit the dashboard. Cleared by `clearChainCache()`.
+     */
+    private readonly _chainCache;
+    /**
+     * Cached bearer token for risk-engine / insurance read calls. Built
+     * lazily as a signed `log_tool_call` tx and refreshed every 4 min so
+     * server-side replay protection windows never expire it mid-session.
+     */
+    private _authBearer;
+    constructor(privkey: string, options?: AtbashOptions);
+    /**
+     * Construct from resolved config: explicit overrides → env vars → the
+     * `~/.config/atbash/config.json` file (see userConfig.resolve). The private
+     * key comes from `agentKey` (override/env/file) or, failing that, the agent
+     * key file (`~/.config/atbash/guard-client-key`). The judge endpoint is
+     * validated against the trusted allowlist / self-hosted policy; a
+     * self-hosted endpoint's `verifyPubKey` becomes the client default.
+     */
+    static fromConfig(options?: FromConfigOptions): Atbash;
+    get pubkey(): string;
+    get privkey(): string;
+    /** GET /api/ai/exists?pubkey=… — defaults to this client's pubkey. */
+    checkAgentExists(pubkey?: string): Promise<boolean>;
+    /**
+     * Pre-flight `checkAgentExists`, then sign `log_tool_call` locally and
+     * return the signed tx hex. The server broadcasts to chain.
+     */
+    logToolCall(action: string, context?: string, options?: LogToolCallOptions): Promise<LogToolCallResult>;
+    /**
+     * Sign log_tool_call + optionally judge_action, POST /api/v1/judge.
+     *
+     * `verifyPubKey` checks the `X-Atbash-Signature` header against the exact
+     * response bytes via the Rust core's `verifySignature`.
+     */
+    judgeAction(action: string, context?: string, options?: JudgeOptions): Promise<JudgeResult>;
+    private _judgeAction;
+    /**
+     * High-level guard: redact secrets, submit for judgement, and collapse the
+     * result into an allow/deny `Decision`. Fails closed by default — any error
+     * (judge unreachable, unrecognized verdict) denies unless `failClosed` is
+     * explicitly false.
+     */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
+    private fail;
+    getJudgmentStatus(judgmentId: string, agentPubkey?: string): Promise<JudgmentStatus>;
+    getToolCalls(maxCount: number): Promise<ToolCallRecord[]>;
+    getOrgToolCalls(orgName: string, maxCount: number): Promise<ToolCallRecord[]>;
+    getAgentToolCalls(agentPubkey: string, maxCount: number): Promise<ToolCallRecord[]>;
+    getToolCallCount(): Promise<number>;
+    getToolCallFull(toolCallId: string): Promise<ToolCallFull | null>;
+    getOrgTierInfo(orgName: string): Promise<TierInfo | null>;
+    getPendingHeldActions(orgName: string, maxCount: number): Promise<HeldAction[]>;
+    getHeldActionReviews(orgName: string, maxCount: number): Promise<HeldActionReview[]>;
+    getAgentDetail(agentPubkey: string): Promise<Record<string, unknown>>;
+    getAgentPolicy(agentPubkey: string): Promise<AgentPolicy>;
+    getSafetyStats(): Promise<Record<string, unknown>>;
+    /**
+     * Org's subscription on a specific chain. The `network` arg selects
+     * which chain to query; without it, the dashboard picks the default.
+     * Returns null when the org has no record on that chain.
+     */
+    getOrgSubscription(orgName: string, network?: Network): Promise<OrgSubscription | null>;
+    /**
+     * Read the org's active network from the dashboard's off-chain
+     * `org_networks` map. The map is the authoritative source after a
+     * plan switch — subscription rows on the source chain go stale, but
+     * the map is updated on every assign. Returns null when there's no
+     * entry (caller falls back to per-chain subscription resolution).
+     */
+    getActiveNetworkForOrg(orgName: string): Promise<Network | null>;
+    /**
+     * 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.
+     * Defaults to the public chain when nothing else resolves.
+     */
+    resolveChainForOrg(orgName: string): Promise<ChainConfig>;
+    /**
+     * Resolve a chain given an already-fetched `org_networks` map result.
+     * Split out from {@link resolveChainForOrg} so callers that have already
+     * queried the map (the judge path) don't fetch /api/org-network twice.
+     * Caches per orgName like its caller.
+     */
+    private resolveChainFromMap;
+    /** Drop any cached chain resolutions. Useful in tests. */
+    clearChainCache(): void;
+    /**
+     * Wrap an SDK method body in telemetry — records the call at start
+     * and a success/error duration at end. Re-throws on failure so the
+     * caller sees the original exception. Pass `agentPubkey` when the
+     * method is keyed to a specific agent; tracked methods that don't
+     * depend on an agent (read queries) pass `undefined`.
+     */
+    private track;
+    /**
+     * Pick the BRID for a given per-call chain override. `blockchainRid`
+     * takes precedence; otherwise `network` maps to one of the known
+     * chains; otherwise the client's default.
+     */
+    private bridFromChainOpts;
+    /**
+     * Get-or-create a Bearer token for dashboard reads. The token is a
+     * signed `log_tool_call` op (locally signed, never submitted) — the
+     * dashboard verifies the signature against the agent's pubkey. Cached
+     * for 4 minutes; refreshed after that so a long-lived client never
+     * trips the server's replay window.
+     */
+    private getAuthBearer;
+    private authHeaders;
+    private riskEngineGet;
+    private riskEnginePost;
+    private riskEngineRecords;
+    private raiseIfError;
+    /** Wrap a failed HTTP *response* (non-2xx / non-200) as an AtbashAPIError. */
+    private httpError;
+    /** Wrap a *transport* failure (fetch threw, no response) as an AtbashAPIError. */
+    private transportError;
+    private json;
+    static generateKeypair(): KeyPair;
+    static isValidPrivateKey(hex: string): boolean;
+    static derivePublicKey(privkey: string): string;
+    static redactSecrets(text: string): RedactResult;
+    static normalizeForMatching(text: string): string;
+    static containsEvasionCharacters(text: string): boolean;
 }
-declare function createAtbashClient(config?: AtbashClientConfig): AtbashClient;
 
-declare function validateJudgeEndpoint(judge?: JudgeEndpointConfig): ValidatedEndpoint;
+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). */
+    readonly status: number;
+    /** Raw response body text (may be empty). */
+    readonly body: string;
+    constructor(status: number, body: string, statusText?: string, endpoint?: string);
+}
+declare class SignatureVerificationError extends Error {
+    constructor(message: string);
+}
+
+/** Normalize wire shapes (verdict casing, status, pubkey) to canonical forms. */
+
+declare function normalizeVerdict(raw: unknown): Verdict;
+declare function normalizeStatus(raw: unknown): JudgmentState;
+/** Wire pubkey may be a hex string, a Buffer/Uint8Array, or `{ data: [...] }`. */
+declare function pubkeyToHex(val: unknown): string;
+
+interface AtbashUserConfig {
+    agentKey?: string;
+    orgName?: string;
+    judgeEndpoint?: string;
+    blockchainRid?: string;
+    provider?: string;
+    providerModel?: string;
+}
+declare function getConfigDir(): string;
+declare function getConfigPath(): string;
+declare function loadUserConfig(): AtbashUserConfig;
+declare function saveUserConfig(config: AtbashUserConfig): void;
+declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): string;
 
 declare function resolveKeyPath(input?: string): string;
 declare function loadAgentFromFile(keyPath?: string): AgentAuth;
 
+/**
+ * Canonical secret kinds reported by the Rust core in `SecretMatch.kind`.
+ * Wire is permissive (modelled as a free string in {@link SecretMatch})
+ * so unknown kinds don't break callers; use this union when narrowing.
+ */
+type SecretKind = "anthropic" | "openai" | "openai_project" | "github" | "google" | "google_oauth" | "aws_access_key" | "aws_secret_key" | "stripe" | "slack" | "slack_webhook" | "sendgrid" | "twilio_sid" | "mailgun" | "npm_token" | "jwt" | "private_key_pem" | "context_secret" | "bearer" | "base64" | "generic_token";
+/**
+ * Walk a JSON-shaped value and redact secrets inside every string leaf.
+ * Object keys are not touched; only values. Arrays and nested objects
+ * are recursed structurally so the returned value has the same shape.
+ */
+declare function redactJsonStrings<T>(value: T): T;
+
 declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHex: string | null, pubKeyHex: string): {
     ok: boolean;
     reason?: string;
@@ -243,8 +509,9 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
  * and agent identity. ON by default.
  *
  * Opt-out: create ~/.config/atbash/telemetry.json with { "enabled": false }
- * The file must be mode 0600. If missing, corrupted, or unreadable → telemetry stays ON.
- * Environment variables cannot disable telemetry (prevents agent bypass).
+ * The file must be readable by the SDK process. If missing, corrupted, or
+ * unreadable → telemetry stays ON. Environment variables cannot disable
+ * telemetry (prevents agent bypass via env-var injection).
  */
 type ClientSource = "cli" | "sdk" | "plugin:openclaw" | "plugin:langchain" | "plugin:langgraph" | "plugin:hermes" | "plugin:eliza" | "plugin:crewai" | "plugin:mcp" | "plugin:autogen" | "plugin:jeenai" | (string & {});
 interface TelemetryConfig {
@@ -257,83 +524,37 @@ interface TelemetryConfig {
 }
 declare function setupTelemetry(config: TelemetryConfig): void;
 /**
- * Flush pending metrics and shut down. Call before process exits.
+ * Record a function call. Call at the START of each tracked function.
+ * Safe to call even if telemetry is disabled — does nothing.
  */
-declare function shutdownTelemetry(): Promise<void>;
-
-interface AtbashUserConfig {
-    agentKey?: string;
-    orgName?: string;
-    judgeEndpoint?: string;
-    blockchainRid?: string;
-    network?: string;
-    provider?: string;
-    providerModel?: string;
-}
-declare function getConfigDir(): string;
-declare function getConfigPath(): string;
-declare function loadUserConfig(): AtbashUserConfig;
-declare function saveUserConfig(config: AtbashUserConfig): void;
-declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): string;
-
+declare function recordCall(functionName: string, source?: ClientSource, agentPubkey?: string): void;
 /**
- * Scan a single memory entry for poisoning.
- *
- * Defence layers (in order):
- * 1. **Regex pre-filter** — catches obvious attacks instantly, zero latency
- * 2. **LLM-as-Judge** — catches semantic / rephrased attacks the regex misses
- *
- * Both layers run against unicode-normalized text. The entry is fenced
- * in the judge prompt so attackers cannot meta-inject into the scanner.
- * Every scan is logged on-chain via the judge API for forensic audit.
+ * Record function duration. Call at the END of each tracked function.
+ * Safe to call even if telemetry is disabled — does nothing.
  */
-declare function scanMemory(entry: MemoryEntry, auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult>;
-/**
- * Scan multiple memory entries. By default stops on the first red
- * verdict. Set `stopOnRed: false` to scan all entries regardless.
- */
-declare function scanMemoryBatch(entries: MemoryEntry[], auth: AgentAuth, opts?: MemoryScanOptions): Promise<MemoryScanResult[]>;
-
+declare function recordDuration(functionName: string, durationMs: number, status: "success" | "error", source?: ClientSource): void;
 /**
- * Create a timestamped snapshot of the current memory state.
+ * Force-flush pending metrics without shutting down.
+ * Use in short-lived processes (CLI) to ensure data is sent.
  */
-declare function createMemorySnapshot(entries: MemoryEntry[]): MemorySnapshot;
+declare function flushTelemetry(): Promise<void>;
 /**
- * Compute the diff between two memory snapshots and run anomaly
- * detection heuristics on the result.
- *
- * Catches what other defenses miss:
- * - HMAC detects external tampering, not entries the agent wrote itself
- * - Provenance tagging neutralizes untrusted sources, but a trusted
- *   channel can still be exploited
- * - Regex catches fixed phrases, but attackers rephrase
- * - LLM-as-judge catches semantic manipulation on individual entries
- * - This function catches the *cumulative effect* — gradual multi-step
- *   poisoning where entries shift agent behavior across sessions
+ * Flush pending metrics and shut down. Call before process exits.
  */
-declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
+declare function shutdownTelemetry(): Promise<void>;
 
-/**
- * Unicode normalization for memory content before regex matching.
- *
- * Defeats evasion techniques:
- * - Zero-width characters inserted between letters
- * - Homoglyphs (Cyrillic "а" instead of Latin "a")
- * - Mixed-script confusables
- * - Invisible formatting characters
- */
-/**
- * Normalize a string for safe regex matching:
- * 1. NFKC normalization (collapses compatibility decompositions)
- * 2. Strip zero-width / invisible characters
- * 3. Map common confusable characters to their Latin equivalents
- */
-declare function normalizeForMatching(input: string): string;
-/**
- * Check whether a string contains suspicious encoding that may indicate
- * an evasion attempt (presence of confusables, invisible chars, etc.).
- * Returns true if the raw and normalized forms differ.
- */
-declare function containsEvasionCharacters(input: string): boolean;
+declare function isValidPrivateKey(hex: string): boolean;
+declare function derivePublicKey(privkey: string): string;
+declare function generateKeypair(): KeyPair;
+declare function loadAgent(privkey: string): AgentAuth;
+declare function signLogToolCall(toolCallId: string, action: string, context: string, toolName: string, toolArgsJson: string, privkey: string, blockchainRid: string): string;
+declare function signJudgeAction(judgmentId: string, action: string, context: string, extra: string, privkey: string, blockchainRid: string): string;
+declare function verifySignature(body: Buffer, signatureHex: string, pubkeyHex: string): boolean;
+declare function normalizeForMatching(text: string): string;
+declare function containsEvasionCharacters(text: string): boolean;
+declare function redactSecrets(text: string): RedactResult;
+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 AgentPolicy, type AnomalySeverity, type AnomalyType, type AtbashClient, type AtbashClientConfig, type AtbashUserConfig, type ClientOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentStatus, type JudgmentStatusState, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type OrgSubscription, type Provider, type PubkeyValue, type TelemetryConfig, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, checkAgentExists, containsEvasionCharacters, createAtbashClient, createMemorySnapshot, derivePublicKey, diffMemorySnapshots, generateKeyPair, getAgentDetail, getAgentPolicy, getAgentToolCalls, getConfigDir, getConfigPath, getHeldActionReviews, getJudgmentStatus, getOrgSubscription, getOrgToolCalls, getPendingHeldActions, getSafetyStats, getToolCallCount, getToolCallFull, getToolCalls, isValidPrivateKey, judgeAction, loadAgent, loadAgentFromFile, loadUserConfig, normalizeForMatching, resolve, resolveKeyPath, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, toPubkeyHex, validateJudgeEndpoint, verifyJudgeResponseSignature };
+export { type ActionType, type AgentAuth, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, type ChainOpts, type ClientSource, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, type Decision, type DecisionVerdict, type FromConfigOptions, type HeldAction, type HeldActionReview, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, type Provider, type PubkeyValue, type RedactResult, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, containsEvasionCharacters, containsSecret, createMemorySnapshot, derivePublicKey, diffMemorySnapshots, flushTelemetry, generateKeypair, getConfigDir, getConfigPath, isValidPrivateKey, loadAgent, loadAgentFromFile, loadUserConfig, normalizeForMatching, normalizeStatus, normalizeVerdict, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, saveUserConfig, setupTelemetry, shutdownTelemetry, signJudgeAction, signLogToolCall, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };