gora8-signer 0.1.3 → 0.1.4

package/README.md

@@ -37,11 +37,11 @@ npm install gora8-signer
 # shown here; OS keychain is used automatically instead when available —
 # see Storage below)
 export GORA8_SIGNER_KEK=$(openssl rand -hex 32)   # dev only — see Storage
-npx gora8-signer init my-agent-id
+npx --package=gora8-signer gora8-signer init my-agent-id
 # {"evmAddress":"0x...","solanaAddress":"..."}
 
 # Run the signer as its own process
-npx gora8-signer start my-agent-id
+npx --package=gora8-signer gora8-signer start my-agent-id
 ```
 
 Your agent's own code then talks to it over the socket:
@@ -72,6 +72,15 @@ a mounted secret, whatever your deployment already uses — never gora8's.
 The env-var-based provider shown above is for local development only;
 implement `KekProvider` against your real KMS for production.
 
+Auto-detection isn't airtight: some minimal container images (e.g.
+Alpine) ship the OS-keychain library's native binding without a working
+Secret Service underneath it, so it *loads* successfully but can't
+actually store or retrieve anything — confirmed live, not hypothesized.
+If you know your deployment target has no real OS keychain, set
+`GORA8_SIGNER_SECRET_BACKEND=file` (or `keychain` to force the other
+way, erroring loudly instead of silently falling back if it isn't
+actually usable) rather than relying on auto-detection to figure it out.
+
 ## Policy enforcement
 
 Before signing anything, the signer fetches your agent's current signed

package/dist/audit-log.d.ts

@@ -1,5 +1,6 @@
 import { type Hex } from "viem";
 import { type MerkleTree } from "./merkle-tree.js";
+import { type DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
 export interface AuditEntry {
     timestamp: string;
     operation: string;
@@ -9,11 +10,63 @@ export interface AuditEntry {
     counterparty: string | null;
     txHash?: string;
 }
-export declare class AuditLog {
+export interface AuditLogBackend {
+    /** Appends one entry. Must preserve append order for the same reason
+     *  Merkle-leaf ordering has to be stable — a backend whose writes can
+     *  reorder or interleave under concurrency (multiple serverless
+     *  instances appending at once, say) needs its own ordering
+     *  guarantee (a monotonic sort key, a single-writer queue in front of
+     *  it, etc.) or computeCommitment()'s root stops meaning "the log as
+     *  it actually happened." Local, single-process storage gets this for
+     *  free; a distributed backend has to earn it explicitly. */
+    append(entry: AuditEntry): Promise<void>;
+    readAll(): Promise<AuditEntry[]>;
+}
+/** File-backed, append-only JSONL — the original (and still the
+ *  default local/persistent-process) storage, extracted here as one
+ *  implementation of AuditLogBackend rather than baked into AuditLog
+ *  itself. */
+export declare class LocalFileAuditLogBackend implements AuditLogBackend {
     private readonly filePath;
     constructor(filePath: string);
     append(entry: AuditEntry): Promise<void>;
     readAll(): Promise<AuditEntry[]>;
+}
+/** DynamoDB-backed — the distributed case LocalFileAuditLogBackend's
+ *  doc comment flagged as not yet built: multiple concurrent
+ *  processes appending without a shared filesystem to serialize
+ *  writes through. Ordering (this file's whole reason for calling it
+ *  out as a backend-specific concern, not something the AuditLog
+ *  orchestration layer can paper over) comes from a DynamoDB atomic
+ *  counter, not wall-clock timestamps — two concurrent appends always
+ *  get two different, strictly increasing sequence numbers via a
+ *  single conditionless `ADD` (DynamoDB serializes this itself; no
+ *  compare-and-swap needed here, unlike the rate-limit backend, since
+ *  an atomic increment is exactly what's needed and DynamoDB provides
+ *  it natively). Entries are stored under a different partition
+ *  (`<key>#entries`, sort key = that sequence number) than the counter
+ *  itself (`<key>#seq`), so `readAll()`'s Query never has to filter
+ *  the counter item out. Requires a table with a String partition key
+ *  named `pk` and a Number sort key named `sortKey`. */
+export declare class DynamoDbAuditLogBackend implements AuditLogBackend {
+    private readonly client;
+    private readonly tableName;
+    private readonly key;
+    constructor(client: DynamoDBDocumentClient, tableName: string, key: string);
+    private nextSeq;
+    append(entry: AuditEntry): Promise<void>;
+    readAll(): Promise<AuditEntry[]>;
+}
+/** The orchestration layer — hash-chain leaf computation, Merkle
+ *  commitment, and spend-tracking, all built on top of whatever
+ *  AuditLogBackend is injected. Public API unchanged from before this
+ *  file was split (append/readAll/spentSince/computeCommitment) — only
+ *  the constructor changed, from a file path to a backend. */
+export declare class AuditLog {
+    private readonly backend;
+    constructor(backend: AuditLogBackend);
+    append(entry: AuditEntry): Promise<void>;
+    readAll(): Promise<AuditEntry[]>;
     /** Sum of `amount` across allowed entries since `since` — the local,
      *  independent spend tracker policy.ts's SpendTracker interface
      *  expects (see that file's doc comment on why this doesn't rely on

package/dist/audit-log.js

@@ -2,21 +2,12 @@ import { appendFile, readFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { keccak256, toHex } from "viem";
 import { buildMerkleTree } from "./merkle-tree.js";
-function leafFor(entry) {
-    // Canonical JSON key order so the same logical entry always hashes to
-    // the same leaf regardless of object construction order.
-    const canonical = JSON.stringify({
-        timestamp: entry.timestamp,
-        operation: entry.operation,
-        allowed: entry.allowed,
-        reason: entry.reason ?? null,
-        amount: entry.amount,
-        counterparty: entry.counterparty,
-        txHash: entry.txHash ?? null,
-    });
-    return keccak256(toHex(canonical));
-}
-export class AuditLog {
+import { QueryCommand, PutCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
+/** File-backed, append-only JSONL — the original (and still the
+ *  default local/persistent-process) storage, extracted here as one
+ *  implementation of AuditLogBackend rather than baked into AuditLog
+ *  itself. */
+export class LocalFileAuditLogBackend {
     filePath;
     constructor(filePath) {
         this.filePath = filePath;
@@ -39,6 +30,112 @@ export class AuditLog {
             throw err;
         }
     }
+}
+/** DynamoDB-backed — the distributed case LocalFileAuditLogBackend's
+ *  doc comment flagged as not yet built: multiple concurrent
+ *  processes appending without a shared filesystem to serialize
+ *  writes through. Ordering (this file's whole reason for calling it
+ *  out as a backend-specific concern, not something the AuditLog
+ *  orchestration layer can paper over) comes from a DynamoDB atomic
+ *  counter, not wall-clock timestamps — two concurrent appends always
+ *  get two different, strictly increasing sequence numbers via a
+ *  single conditionless `ADD` (DynamoDB serializes this itself; no
+ *  compare-and-swap needed here, unlike the rate-limit backend, since
+ *  an atomic increment is exactly what's needed and DynamoDB provides
+ *  it natively). Entries are stored under a different partition
+ *  (`<key>#entries`, sort key = that sequence number) than the counter
+ *  itself (`<key>#seq`), so `readAll()`'s Query never has to filter
+ *  the counter item out. Requires a table with a String partition key
+ *  named `pk` and a Number sort key named `sortKey`. */
+export class DynamoDbAuditLogBackend {
+    client;
+    tableName;
+    key;
+    constructor(client, tableName, key) {
+        this.client = client;
+        this.tableName = tableName;
+        this.key = key;
+    }
+    async nextSeq() {
+        const res = await this.client.send(new UpdateCommand({
+            TableName: this.tableName,
+            Key: { pk: `${this.key}#seq`, sortKey: 0 },
+            UpdateExpression: "ADD seq :one",
+            ExpressionAttributeValues: { ":one": 1 },
+            ReturnValues: "UPDATED_NEW",
+        }));
+        const seq = res.Attributes?.seq;
+        if (typeof seq !== "number")
+            throw new Error(`DynamoDbAuditLogBackend: counter update for "${this.key}" returned no numeric seq.`);
+        return seq;
+    }
+    async append(entry) {
+        const seq = await this.nextSeq();
+        // AuditEntry's optional fields (reason, txHash) arrive as
+        // `undefined`, not omitted, whenever they're unset — fine for
+        // LocalFileAuditLogBackend (JSON.stringify silently drops undefined
+        // keys), but DynamoDB's default marshaller rejects `undefined`
+        // outright rather than dropping it (found live-verifying this: the
+        // very first signRegisterIdentity through a real CLI run threw here,
+        // since a successful signature's `reason` is always undefined). The
+        // JSON round-trip restores exactly the same "absent, not null"
+        // behavior the file backend already has, rather than requiring every
+        // caller to remember to construct their DynamoDBDocumentClient with
+        // `marshallOptions: { removeUndefinedValues: true }`.
+        const cleanEntry = JSON.parse(JSON.stringify(entry));
+        await this.client.send(new PutCommand({
+            TableName: this.tableName,
+            Item: { pk: `${this.key}#entries`, sortKey: seq, entry: cleanEntry },
+        }));
+    }
+    async readAll() {
+        const entries = [];
+        let exclusiveStartKey;
+        do {
+            const res = await this.client.send(new QueryCommand({
+                TableName: this.tableName,
+                KeyConditionExpression: "pk = :pk",
+                ExpressionAttributeValues: { ":pk": `${this.key}#entries` },
+                ScanIndexForward: true, // ascending sortKey — append order, same as the file backend's line order
+                ExclusiveStartKey: exclusiveStartKey,
+            }));
+            for (const item of res.Items ?? [])
+                entries.push(item.entry);
+            exclusiveStartKey = res.LastEvaluatedKey;
+        } while (exclusiveStartKey);
+        return entries;
+    }
+}
+function leafFor(entry) {
+    // Canonical JSON key order so the same logical entry always hashes to
+    // the same leaf regardless of object construction order.
+    const canonical = JSON.stringify({
+        timestamp: entry.timestamp,
+        operation: entry.operation,
+        allowed: entry.allowed,
+        reason: entry.reason ?? null,
+        amount: entry.amount,
+        counterparty: entry.counterparty,
+        txHash: entry.txHash ?? null,
+    });
+    return keccak256(toHex(canonical));
+}
+/** The orchestration layer — hash-chain leaf computation, Merkle
+ *  commitment, and spend-tracking, all built on top of whatever
+ *  AuditLogBackend is injected. Public API unchanged from before this
+ *  file was split (append/readAll/spentSince/computeCommitment) — only
+ *  the constructor changed, from a file path to a backend. */
+export class AuditLog {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    append(entry) {
+        return this.backend.append(entry);
+    }
+    readAll() {
+        return this.backend.readAll();
+    }
     /** Sum of `amount` across allowed entries since `since` — the local,
      *  independent spend tracker policy.ts's SpendTracker interface
      *  expects (see that file's doc comment on why this doesn't rely on

package/dist/cli.js

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { defaultKeyStore, defaultSolanaKeyStore, EnvKekProvider } from "./keystore.js";
+import { KMSClient } from "@aws-sdk/client-kms";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { defaultEvmSigningBackend, defaultSolanaSigningBackend } from "./signing-backend.js";
+import { KmsSigningBackend, SolanaKmsSigningBackend } from "./kms-signing-backend.js";
+import { EnvKekProvider } from "./keystore.js";
 import { PolicyEngine } from "./policy.js";
-import { AuditLog } from "./audit-log.js";
-import { Signer, SlidingWindowRateLimiter } from "./signer.js";
+import { AuditLog, LocalFileAuditLogBackend, DynamoDbAuditLogBackend } from "./audit-log.js";
+import { LocalFileRateLimitBackend, DynamoDbRateLimitBackend } from "./rate-limit-backend.js";
+import { Signer } from "./signer.js";
 import { SignerIpcServer } from "./ipc-server.js";
 // Minimal CLI so `gora8 deploy` (the Go CLI) can shell out to this
 // package directly rather than needing its own reimplementation of key
@@ -16,6 +22,90 @@ import { SignerIpcServer } from "./ipc-server.js";
 function dataDir(agentId) {
     return join(homedir(), ".gora8", "signer", agentId);
 }
+// Per-chain backend selection, independent of each other (same
+// reasoning as everywhere else in this codebase: EVM and Solana are two
+// entirely separate secrets, so one chain can be KMS-backed while the
+// other stays local without conflict). Presence of the KMS key id env
+// var *is* the selection — no separate "backend kind" var to drift out
+// of sync with it. `provisioning` is null for a KMS-backed chain: the
+// key already exists in KMS, provisioned out of band through the KMS
+// console/API (see LocalKeyProvisioning's doc comment in
+// signing-backend.ts), so `init` has nothing to generate for it.
+let sharedKmsClient;
+function kmsClient() {
+    // process.env.AWS_REGION, if set, is picked up by the SDK's own
+    // default provider chain automatically — no gora8-specific region
+    // handling needed here.
+    if (!sharedKmsClient)
+        sharedKmsClient = new KMSClient({});
+    return sharedKmsClient;
+}
+let sharedDynamoDbClient;
+function dynamoDbClient() {
+    if (!sharedDynamoDbClient)
+        sharedDynamoDbClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+    return sharedDynamoDbClient;
+}
+// Same independent-per-concern selection as the signing backends above:
+// presence of the table-name env var is the selection, no separate
+// "backend kind" var. This is what actually closes the "persistent
+// process assumed" gap a KMS-backed signing key alone doesn't close —
+// KMS made the *key* stateless-deployment-safe; these make the rate
+// limiter and audit log safe for the same topology (a Lambda/Cloud-Run
+// invocation with no durable local disk, possibly multiple concurrent
+// instances of the same agent).
+function selectAuditLogBackend(agentId, dir) {
+    const tableName = process.env.GORA8_AUDIT_LOG_DYNAMODB_TABLE;
+    if (tableName) {
+        console.error(`Audit log backend: DynamoDB (table "${tableName}")`);
+        return new DynamoDbAuditLogBackend(dynamoDbClient(), tableName, agentId);
+    }
+    console.error("Audit log backend: local file");
+    return new LocalFileAuditLogBackend(join(dir, "audit.jsonl"));
+}
+function selectRateLimitBackend(agentId, dir) {
+    const tableName = process.env.GORA8_RATE_LIMIT_DYNAMODB_TABLE;
+    if (tableName) {
+        console.error(`Rate limit backend: DynamoDB (table "${tableName}")`);
+        return new DynamoDbRateLimitBackend(dynamoDbClient(), tableName, agentId);
+    }
+    console.error("Rate limit backend: local file");
+    return new LocalFileRateLimitBackend(join(dir, "rate-limit.json"));
+}
+async function selectEvmBackend(agentId, dir, kek) {
+    const keyId = process.env.GORA8_EVM_KMS_KEY_ID;
+    if (keyId) {
+        console.error(`EVM signing backend: AWS KMS (key "${keyId}")`);
+        return { backend: new KmsSigningBackend(kmsClient(), keyId), provisioning: null };
+    }
+    console.error("EVM signing backend: local (OS keychain / encrypted file)");
+    const local = await defaultEvmSigningBackend(agentId, join(dir, "key.enc.json"), kek);
+    return { backend: local, provisioning: local };
+}
+async function selectSolanaBackend(agentId, dir, kek) {
+    const keyId = process.env.GORA8_SOLANA_KMS_KEY_ID;
+    if (keyId) {
+        console.error(`Solana signing backend: AWS KMS (key "${keyId}")`);
+        return { backend: new SolanaKmsSigningBackend(kmsClient(), keyId), provisioning: null };
+    }
+    console.error("Solana signing backend: local (OS keychain / encrypted file)");
+    const local = await defaultSolanaSigningBackend(agentId, join(dir, "solana-key.enc.json"), kek);
+    return { backend: local, provisioning: local };
+}
+/** Shared by both chains' `init` handling: generate-and-store for a
+ *  local backend (skipping if a key already exists), or just report the
+ *  address for a KMS-backed one (`provisioning === null`) — there's
+ *  nothing for `init` to generate against KMS. */
+async function resolveOrGenerateAddress(label, agentId, backend, provisioning) {
+    if (!provisioning)
+        return backend.address();
+    const hasKey = await provisioning.hasKey();
+    if (hasKey) {
+        console.error(`A ${label} key already exists for agent "${agentId}". Not generating a new one.`);
+        return backend.address();
+    }
+    return provisioning.generateAndStore();
+}
 async function fetchMandate(agentId, apiBase) {
     const res = await fetch(`${apiBase}/v1/agents/${agentId}/mandate`);
     if (!res.ok)
@@ -31,26 +121,18 @@ async function main() {
     }
     const dir = dataDir(agentId);
     const kek = new EnvKekProvider();
-    const keyStore = await defaultKeyStore(agentId, join(dir, "key.enc.json"), kek);
-    const solanaKeyStore = await defaultSolanaKeyStore(agentId, join(dir, "solana-key.enc.json"), kek);
-    const auditLog = new AuditLog(join(dir, "audit.jsonl"));
+    const { backend: evmSigningBackend, provisioning: evmProvisioning } = await selectEvmBackend(agentId, dir, kek);
+    const { backend: solanaSigningBackend, provisioning: solanaProvisioning } = await selectSolanaBackend(agentId, dir, kek);
+    const auditLog = new AuditLog(selectAuditLogBackend(agentId, dir));
     switch (command) {
         case "init": {
-            // Both keys generated together, same as `gora8 deploy` provisions
+            // Both chains handled together, same as `gora8 deploy` provisions
             // both an EVM and a Solana wallet for every agent today — two
-            // entirely independent secrets (different curves, different
-            // storage entries), not one key used two ways. Each is checked and
-            // reported separately so a partial prior init (e.g. EVM exists,
-            // Solana doesn't yet — the state every pre-Solana-self-custody
-            // agent is in) doesn't block generating just the missing one.
-            const hasEvm = await keyStore.hasKey();
-            const evmAddress = hasEvm ? await keyStore.address() : await keyStore.generateAndStore();
-            if (hasEvm)
-                console.error(`An EVM key already exists for agent "${agentId}". Not generating a new one.`);
-            const hasSolana = await solanaKeyStore.hasKey();
-            const solanaAddress = hasSolana ? await solanaKeyStore.address() : await solanaKeyStore.generateAndStore();
-            if (hasSolana)
-                console.error(`A Solana key already exists for agent "${agentId}". Not generating a new one.`);
+            // entirely independent secrets (different curves, independently
+            // local-or-KMS per resolveOrGenerateAddress above), not one key
+            // used two ways.
+            const evmAddress = await resolveOrGenerateAddress("EVM", agentId, evmSigningBackend, evmProvisioning);
+            const solanaAddress = await resolveOrGenerateAddress("Solana", agentId, solanaSigningBackend, solanaProvisioning);
             console.log(JSON.stringify({ evmAddress, solanaAddress }));
             break;
         }
@@ -72,11 +154,15 @@ async function main() {
             const mandateAgentId = process.env.GORA8_AGENT_ID || agentId;
             const policyEngine = new PolicyEngine({ fetchMandate: () => fetchMandate(mandateAgentId, apiBase) }, auditLog);
             const signer = new Signer({
-                keyStore,
-                solanaKeyStore,
+                evmSigningBackend,
+                solanaSigningBackend,
                 policyEngine,
                 auditLog,
-                rateLimiter: new SlidingWindowRateLimiter(30, 60_000), // 30 signatures/min sanity backstop
+                rateLimit: {
+                    backend: selectRateLimitBackend(agentId, dir),
+                    windowMs: 60_000,
+                    maxCalls: 30, // sanity backstop
+                },
             });
             const socketPath = process.env.GORA8_SIGNER_SOCKET ?? join(dir, "signer.sock");
             const server = new SignerIpcServer(signer, socketPath);

package/dist/index.d.ts

@@ -1,10 +1,15 @@
-export { OsKeychainSecretStore, EncryptedFileSecretStore, EnvKekProvider, defaultKeyStore, defaultSolanaKeyStore } from "./keystore.js";
-export type { KeyStore, SolanaKeyStore, SecretStore, KekProvider } from "./keystore.js";
+export { OsKeychainSecretStore, EncryptedFileSecretStore, EnvKekProvider, defaultSecretStore } from "./keystore.js";
+export type { SecretStore, KekProvider } from "./keystore.js";
+export { defaultEvmSigningBackend, defaultSolanaSigningBackend } from "./signing-backend.js";
+export type { EvmSigningBackend, SolanaSigningBackend, LocalKeyProvisioning } from "./signing-backend.js";
+export { KmsSigningBackend, defaultKmsSigningBackend, SolanaKmsSigningBackend, defaultSolanaKmsSigningBackend } from "./kms-signing-backend.js";
 export { PolicyEngine } from "./policy.js";
 export type { Mandate, SigningRequest, PolicyDecision, PolicyEngineOptions, SpendTracker } from "./policy.js";
-export { AuditLog } from "./audit-log.js";
-export type { AuditEntry } from "./audit-log.js";
-export { Signer, SlidingWindowRateLimiter } from "./signer.js";
+export { AuditLog, LocalFileAuditLogBackend, DynamoDbAuditLogBackend } from "./audit-log.js";
+export type { AuditEntry, AuditLogBackend } from "./audit-log.js";
+export { InMemoryRateLimitBackend, LocalFileRateLimitBackend, DynamoDbRateLimitBackend } from "./rate-limit-backend.js";
+export type { RateLimitStateBackend } from "./rate-limit-backend.js";
+export { Signer } from "./signer.js";
 export type { SignerOptions } from "./signer.js";
 export { SignerIpcServer } from "./ipc-server.js";
 export { SignerIpcClient } from "./ipc-client.js";

package/dist/index.js

@@ -1,7 +1,10 @@
-export { OsKeychainSecretStore, EncryptedFileSecretStore, EnvKekProvider, defaultKeyStore, defaultSolanaKeyStore } from "./keystore.js";
+export { OsKeychainSecretStore, EncryptedFileSecretStore, EnvKekProvider, defaultSecretStore } from "./keystore.js";
+export { defaultEvmSigningBackend, defaultSolanaSigningBackend } from "./signing-backend.js";
+export { KmsSigningBackend, defaultKmsSigningBackend, SolanaKmsSigningBackend, defaultSolanaKmsSigningBackend } from "./kms-signing-backend.js";
 export { PolicyEngine } from "./policy.js";
-export { AuditLog } from "./audit-log.js";
-export { Signer, SlidingWindowRateLimiter } from "./signer.js";
+export { AuditLog, LocalFileAuditLogBackend, DynamoDbAuditLogBackend } from "./audit-log.js";
+export { InMemoryRateLimitBackend, LocalFileRateLimitBackend, DynamoDbRateLimitBackend } from "./rate-limit-backend.js";
+export { Signer } from "./signer.js";
 export { SignerIpcServer } from "./ipc-server.js";
 export { SignerIpcClient } from "./ipc-client.js";
 export { buildMerkleTree, getMerkleProof, verifyMerkleProof } from "./merkle-tree.js";

package/dist/ipc-client.d.ts

@@ -24,8 +24,8 @@ export declare class SignerIpcClient {
         to: `0x${string}`;
         value: bigint;
         data: `0x${string}`;
-        digest: `0x${string}`;
-        amount: number;
+        executeNonce: bigint;
+        chainId: number;
     }): Promise<{
         signature: `0x${string}`;
     }>;
@@ -35,9 +35,13 @@ export declare class SignerIpcClient {
     }): Promise<{
         signature: `0x${string}`;
     }>;
+    signAgreementCommit(params: {
+        termsHash: `0x${string}`;
+        counterparty: `0x${string}`;
+    }): Promise<{
+        signature: `0x${string}`;
+    }>;
     signWithdrawal(params: {
-        to: `0x${string}`;
-        amount: number;
         unsignedTx: {
             to: `0x${string}`;
             value: bigint;

package/dist/ipc-client.js

@@ -1,9 +1,10 @@
 import { createConnection } from "node:net";
 import { randomUUID } from "node:crypto";
 // Thin client for the agent's own application code — the only thing it
-// imports to request a signature. It never has access to KeyStore,
-// PolicyEngine, or the raw key at all; it can only send one of the four
-// named requests over the socket and get back a signature or a refusal.
+// imports to request a signature. It never has access to the signing
+// backend, PolicyEngine, or any key material at all; it can only send
+// one of the named requests over the socket and get back a signature or
+// a refusal.
 export class SignerIpcClient {
     socketPath;
     constructor(socketPath) {
@@ -47,6 +48,9 @@ export class SignerIpcClient {
     signAgreementTerms(params) {
         return this.call("signAgreementTerms", params);
     }
+    signAgreementCommit(params) {
+        return this.call("signAgreementCommit", params);
+    }
     signWithdrawal(params) {
         return this.call("signWithdrawal", params);
     }

package/dist/ipc-server.js

@@ -68,6 +68,8 @@ export class SignerIpcServer {
                 return this.signer.signMandateExecute(params);
             case "signAgreementTerms":
                 return this.signer.signAgreementTerms(params);
+            case "signAgreementCommit":
+                return this.signer.signAgreementCommit(params);
             case "signWithdrawal":
                 return this.signer.signWithdrawal(params);
             case "solanaAddress":

package/dist/keystore.d.ts

@@ -1,4 +1,3 @@
-import type { Address, Hex } from "viem";
 export interface SecretStore {
     hasSecret(): Promise<boolean>;
     /** Persists `secret` — throws if one is already stored; callers must
@@ -8,21 +7,6 @@ export interface SecretStore {
      *  scope; the raw secret string itself never does. */
     withSecret<T>(fn: (secret: string) => Promise<T> | T): Promise<T>;
 }
-export interface KeyStore {
-    hasKey(): Promise<boolean>;
-    generateAndStore(): Promise<Address>;
-    withPrivateKey<T>(fn: (privateKey: Hex) => Promise<T> | T): Promise<T>;
-    address(): Promise<Address>;
-}
-export interface SolanaKeyStore {
-    hasKey(): Promise<boolean>;
-    generateAndStore(): Promise<string>;
-    /** `fn` receives the raw 64-byte Solana secret key, matching
-     *  `@solana/web3.js`'s `Keypair.fromSecretKey()` input — same scoped-
-     *  access discipline as EVM's `withPrivateKey`. */
-    withSecretKey<T>(fn: (secretKey: Uint8Array) => Promise<T> | T): Promise<T>;
-    address(): Promise<string>;
-}
 export declare class OsKeychainSecretStore implements SecretStore {
     private readonly service;
     private readonly account;
@@ -32,6 +16,25 @@ export declare class OsKeychainSecretStore implements SecretStore {
     constructor(account: string, service?: string);
     private entry;
     hasSecret(): Promise<boolean>;
+    /**
+     * Same read `hasSecret()` does, but lets a real access failure
+     * propagate instead of collapsing it to `false` — `defaultSecretStore`
+     * below needs exactly this distinction and `hasSecret()` structurally
+     * can't provide it (its own contract is "is there a secret," which is
+     * correctly `false`-not-throw for "backend works, nothing stored yet").
+     *
+     * Found live, not hypothesized: a container with @napi-rs/keyring's
+     * native binding present (so `import()` succeeds) but no working OS
+     * Secret Service/session keyring underneath it — `getPassword()`
+     * itself throws "Couldn't access platform storage: PermissionDenied,"
+     * not "no such entry." `defaultSecretStore`'s probe used to call
+     * `hasSecret()`, which swallowed that exact error and returned `false`
+     * indistinguishably from "keychain works, key doesn't exist yet" —
+     * so it kept the keychain backend instead of falling back to
+     * `EncryptedFileSecretStore`, and every real sign operation failed
+     * downstream, well after the fallback decision was already locked in.
+     */
+    probe(): Promise<boolean>;
     store(secret: string): Promise<void>;
     withSecret<T>(fn: (secret: string) => Promise<T> | T): Promise<T>;
 }
@@ -63,10 +66,13 @@ export declare class EncryptedFileSecretStore implements SecretStore {
     private writeEncrypted;
     private readEncrypted;
 }
-export declare function defaultKeyStore(agentId: string, fallbackFilePath: string, kek: KekProvider): Promise<KeyStore>;
-/** Same defaulting behavior as `defaultKeyStore`, for the Solana key —
- *  `fallbackFilePath` must be a different path than the EVM store's
- *  (e.g. `solana-key.enc.json` next to `key.enc.json`), and the OS
- *  keychain account is automatically suffixed so the two never collide
- *  under the same service/account pair. */
-export declare function defaultSolanaKeyStore(agentId: string, fallbackFilePath: string, kek: KekProvider): Promise<SolanaKeyStore>;
+/** Picks OS keychain by default, falling back to the encrypted file
+ *  store only when the OS keychain genuinely isn't available (headless
+ *  container with no Secret Service, etc.) — never silently prefers the
+ *  weaker option. Shared by both EVM's and Solana's local signing
+ *  backends (signing-backend.ts) — `account`/`fallbackFilePath` must
+ *  already be kind-specific (see OsKeychainSecretStore's doc comment).
+ *  Exported (not module-private) specifically so signing-backend.ts can
+ *  build a SecretStore without this file needing to know anything about
+ *  curves or signing — the dependency runs one direction only. */
+export declare function defaultSecretStore(account: string, fallbackFilePath: string, kek: KekProvider): Promise<SecretStore>;