@atbash/sdk 0.3.25 → 0.4.0-dev.1

package/dist/index.d.mts

@@ -0,0 +1,560 @@
+type JudgeEndpointConfig = {
+    policy?: "default";
+    endpoint?: string;
+} | {
+    policy: "self-hosted";
+    endpoint: string;
+    verifyPubKey: string;
+};
+interface ValidatedEndpoint {
+    url: string;
+    policy: "default" | "self-hosted";
+    verifyPubKey: string | null;
+}
+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 {
+    privkey: string;
+    pubkey: string;
+}
+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 {
+    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;
+    actionType: string;
+    reason: string;
+    confidence: number;
+    provider: string;
+    latencyMs: number;
+    toolCallId: string;
+    onChain: boolean;
+}
+interface JudgmentStatus {
+    status: JudgmentState;
+    verdict: Verdict;
+    reason: string;
+    judgmentId: string;
+    onChain?: boolean;
+    cached?: boolean;
+    responseTimeMs?: number;
+}
+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 {
+    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 {
+    judgmentId: string;
+    agentPubkey: string;
+    actionText: string;
+    actionContext: string;
+    verdict: Verdict;
+    reason: string;
+    createdAt: number;
+}
+interface HeldActionReview {
+    judgmentId: string;
+    actionText: string;
+    status: string;
+    reviewNote: string;
+    reviewedAt: number;
+    createdAt: number;
+    reviewedBy?: string;
+}
+interface AgentPolicy {
+    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;
+    verdict: DecisionVerdict;
+    reason?: string;
+    toolCallId?: string;
+}
+/** Input to `auditToolCall`. */
+interface ToolCallInput {
+    toolName: string;
+    args?: unknown;
+    context?: string;
+}
+/** 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;
+    blockchainRid?: string;
+    timeoutMs?: number;
+    nodeUrls?: readonly string[];
+    /** Default org name — see {@link AtbashOptions.orgName}. */
+    orgName?: string;
+    failClosed?: boolean;
+    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;
+}
+
+interface ChainConfig {
+    readonly network: Network;
+    readonly blockchainRid: string;
+    readonly nodeUrls: readonly string[];
+}
+
+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 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;
+};
+
+/**
+ * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
+ *
+ * Tracks: function call counts, latency, source (CLI/plugin/SDK),
+ * and agent identity. ON by default.
+ *
+ * Opt-out: create ~/.config/atbash/telemetry.json with { "enabled": false }
+ * 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 {
+    /** Must be true to send any telemetry. Default: false */
+    enabled: boolean;
+    /** Where calls originate */
+    source?: ClientSource;
+    /** Flush interval in ms. Default: 60000 */
+    exportIntervalMs?: number;
+}
+declare function setupTelemetry(config: TelemetryConfig): void;
+/**
+ * Record a function call. Call at the START of each tracked function.
+ * Safe to call even if telemetry is disabled — does nothing.
+ */
+declare function recordCall(functionName: string, source?: ClientSource, agentPubkey?: string): void;
+/**
+ * Record function duration. Call at the END of each tracked function.
+ * Safe to call even if telemetry is disabled — does nothing.
+ */
+declare function recordDuration(functionName: string, durationMs: number, status: "success" | "error", source?: ClientSource): void;
+/**
+ * Force-flush pending metrics without shutting down.
+ * Use in short-lived processes (CLI) to ensure data is sent.
+ */
+declare function flushTelemetry(): Promise<void>;
+/**
+ * Flush pending metrics and shut down. Call before process exits.
+ */
+declare function shutdownTelemetry(): Promise<void>;
+
+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, 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 };