gora8-signer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Guillen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# gora8-signer
+
+Local, self-custodied key signing for a gora8 agent — the private key is
+generated and used wherever *your* agent runs, never inside gora8's own
+infrastructure. gora8 never holds it, never has an authorization
+credential over it, and has no path to reconstruct it. See
+[`SELF_CUSTODY_ARCHITECTURE.md`](https://github.com/gora8/internal-repo/blob/main/SELF_CUSTODY_ARCHITECTURE.md)
+in the gora8 monorepo for the full design and threat model this package
+implements.
+
+This is not `gora8-agent` (search/hire/dispute — the agent's economic
+actions) or `gora8-cli` (deploying and configuring an agent). This
+package does exactly one thing: hold a key safely, check a request
+against the agent's own Mandate before signing anything, and produce a
+signature — nothing else.
+
+## Why a separate process
+
+The signer is meant to run isolated from your agent's own application
+code — especially relevant for an LLM-driven agent, where a prompt
+injection could otherwise trick your own business logic into doing
+something harmful. Your agent's code talks to the signer only over a
+local Unix domain socket, requesting one of four named operations —
+never a generic "sign this" call, and never given direct access to the
+key.
+
+## Install
+
+```bash
+npm install gora8-signer
+```
+
+## Quick start — standalone signer process
+
+```bash
+# Generate a key (encrypted-file store 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
+
+# Run the signer as its own process
+npx gora8-signer start my-agent-id
+```
+
+Your agent's own code then talks to it over the socket:
+
+```typescript
+import { SignerIpcClient } from "gora8-signer";
+
+const signer = new SignerIpcClient("~/.gora8/signer/my-agent-id/signer.sock");
+const address = await signer.address();
+```
+
+## Storage
+
+Defaults to the OS-native keychain (macOS Keychain, Windows Credential
+Manager, Linux Secret Service) — the key never touches disk in
+plaintext. Falls back to an encrypted file (AES-256-GCM, envelope
+encryption) only when no OS keychain is available, e.g. a headless
+container. The encryption key for that fallback (`GORA8_SIGNER_KEK`) is
+expected to come from **your own** infrastructure — your own cloud KMS,
+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.
+
+## Policy enforcement
+
+Before signing anything, the signer fetches your agent's current signed
+Mandate (`GET /v1/agents/:id/mandate` — public, no auth required) and
+checks the request against it: per-transaction limit, daily/monthly
+caps (tracked locally from this signer's own audit log, not gora8's
+count), allowed counterparties. This runs independently of, and in
+addition to, gora8's on-chain `MandateEnforcer` — real defense-in-depth,
+not a duplicate of the same trust.
+
+## Audit log
+
+Every signing decision — allowed or refused — is appended to a local,
+append-only log. Periodically (`gora8-signer commit <agent-id>`), a
+Merkle root over that log can be computed and published anywhere you
+choose — gora8 never sees the log's contents, only whatever root you
+decide to share, using the identical commitment scheme gora8's own
+reputation system uses (`buildMerkleTree`/`verifyMerkleProof`, exported
+from this package too).
+
+## Deployment topologies
+
+- **Persistent server**: run `gora8-signer start` as a sidecar next to
+  your agent's own process.
+- **CLI/local development**: everything on one machine, OS keychain
+  storage, no extra setup.
+- **Serverless/ephemeral**: harder — no persistent local storage exists
+  between invocations. Either run `gora8-signer` as your own small,
+  persistent service your functions call into over your own network, or
+  have your function call your own cloud KMS directly for each
+  signature. See `SELF_CUSTODY_ARCHITECTURE.md` for the full discussion —
+  this is a known, disclosed gap in the current version, not silently
+  glossed over.
+
+## What this package does not do
+
+- Encode ERC-8004 or `MandateEnforcer` calldata — that's the caller's
+  job (it already exists in gora8's own client libraries); this package
+  only ever signs an already-built payload.
+- Broadcast transactions — gora8's relay wallet still submits and pays
+  gas, exactly as it does today. Only the authorization to spend moves,
+  not gas sponsorship.
+- Recover a lost key automatically — recovery (an opt-in Shamir split)
+  is a deliberate, separate feature, not built into this first version.

package/dist/audit-log.d.ts

@@ -0,0 +1,33 @@
+import { type Hex } from "viem";
+import { type MerkleTree } from "./merkle-tree.js";
+export interface AuditEntry {
+    timestamp: string;
+    operation: string;
+    allowed: boolean;
+    reason?: string;
+    amount: number | null;
+    counterparty: string | null;
+    txHash?: string;
+}
+export declare class AuditLog {
+    private readonly filePath;
+    constructor(filePath: string);
+    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
+     *  gora8's own server-side count). */
+    spentSince(since: Date): Promise<number>;
+    /** Builds a Merkle tree over every entry logged so far and returns the
+     *  root — the caller (the signer's own periodic job, or an explicit
+     *  CLI command) decides what to do with it: push to gora8's API as a
+     *  commitment, print it for the owner to record independently, etc.
+     *  This module deliberately doesn't push anywhere itself — committing
+     *  is a policy decision (how often, to whom), not this module's job. */
+    computeCommitment(): Promise<{
+        root: Hex;
+        tree: MerkleTree;
+        entryCount: number;
+    }>;
+}

package/dist/audit-log.js

@@ -0,0 +1,67 @@
+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 {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async append(entry) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        await appendFile(this.filePath, JSON.stringify(entry) + "\n", { mode: 0o600 });
+    }
+    async readAll() {
+        try {
+            const raw = await readFile(this.filePath, "utf8");
+            return raw
+                .split("\n")
+                .filter((line) => line.length > 0)
+                .map((line) => JSON.parse(line));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+    }
+    /** 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
+     *  gora8's own server-side count). */
+    async spentSince(since) {
+        const entries = await this.readAll();
+        return entries
+            .filter((e) => e.allowed && e.amount !== null && new Date(e.timestamp) >= since)
+            .reduce((sum, e) => sum + (e.amount ?? 0), 0);
+    }
+    /** Builds a Merkle tree over every entry logged so far and returns the
+     *  root — the caller (the signer's own periodic job, or an explicit
+     *  CLI command) decides what to do with it: push to gora8's API as a
+     *  commitment, print it for the owner to record independently, etc.
+     *  This module deliberately doesn't push anywhere itself — committing
+     *  is a policy decision (how often, to whom), not this module's job. */
+    async computeCommitment() {
+        const entries = await this.readAll();
+        if (entries.length === 0) {
+            throw new Error("computeCommitment: no audit entries to commit yet.");
+        }
+        const leaves = entries.map(leafFor);
+        const tree = buildMerkleTree(leaves);
+        return { root: tree.root, tree, entryCount: entries.length };
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { defaultKeyStore, EnvKekProvider } from "./keystore.js";
+import { PolicyEngine } from "./policy.js";
+import { AuditLog } from "./audit-log.js";
+import { Signer, SlidingWindowRateLimiter } 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
+// generation/storage — matches the design's "the CLI generates the key
+// locally" flow (SELF_CUSTODY_ARCHITECTURE.md). Kept intentionally small:
+// this is the reference implementation an owner can also run standalone
+// (e.g. as the persistent signer service described for serverless/
+// ephemeral deployment topologies), not a full product CLI.
+function dataDir(agentId) {
+    return join(homedir(), ".gora8", "signer", agentId);
+}
+async function fetchMandate(agentId, apiBase) {
+    const res = await fetch(`${apiBase}/v1/agents/${agentId}/mandate`);
+    if (!res.ok)
+        throw new Error(`Failed to fetch Mandate for ${agentId}: HTTP ${res.status}`);
+    return (await res.json());
+}
+async function main() {
+    const [, , command, agentId] = process.argv;
+    const apiBase = process.env.GORA8_API_BASE_URL ?? "https://api.gora8.com";
+    if (!command || !agentId) {
+        console.error("Usage: gora8-signer <init|start|commit> <agent-id>");
+        process.exit(1);
+    }
+    const dir = dataDir(agentId);
+    const keyStore = await defaultKeyStore(agentId, join(dir, "key.enc.json"), new EnvKekProvider());
+    const auditLog = new AuditLog(join(dir, "audit.jsonl"));
+    switch (command) {
+        case "init": {
+            if (await keyStore.hasKey()) {
+                console.error(`A key already exists for agent "${agentId}". Not generating a new one.`);
+                const address = await keyStore.address();
+                console.log(address);
+                process.exit(1);
+            }
+            const address = await keyStore.generateAndStore();
+            console.log(address);
+            break;
+        }
+        case "start": {
+            const policyEngine = new PolicyEngine({ fetchMandate: () => fetchMandate(agentId, apiBase) }, auditLog);
+            const signer = new Signer({
+                keyStore,
+                policyEngine,
+                auditLog,
+                rateLimiter: new SlidingWindowRateLimiter(30, 60_000), // 30 signatures/min sanity backstop
+            });
+            const socketPath = process.env.GORA8_SIGNER_SOCKET ?? join(dir, "signer.sock");
+            const server = new SignerIpcServer(signer, socketPath);
+            await server.start();
+            console.log(`gora8-signer listening on ${socketPath}`);
+            process.on("SIGINT", async () => {
+                await server.stop();
+                process.exit(0);
+            });
+            process.on("SIGTERM", async () => {
+                await server.stop();
+                process.exit(0);
+            });
+            break;
+        }
+        case "commit": {
+            const { root, entryCount } = await auditLog.computeCommitment();
+            console.log(JSON.stringify({ root, entryCount }));
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { OsKeychainStore, EncryptedFileStore, EnvKekProvider, defaultKeyStore } from "./keystore.js";
+export type { KeyStore, KekProvider } from "./keystore.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 type { SignerOptions } from "./signer.js";
+export { SignerIpcServer } from "./ipc-server.js";
+export { SignerIpcClient } from "./ipc-client.js";
+export { buildMerkleTree, getMerkleProof, verifyMerkleProof } from "./merkle-tree.js";
+export type { MerkleTree } from "./merkle-tree.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { OsKeychainStore, EncryptedFileStore, EnvKekProvider, defaultKeyStore } from "./keystore.js";
+export { PolicyEngine } from "./policy.js";
+export { AuditLog } from "./audit-log.js";
+export { Signer, SlidingWindowRateLimiter } 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

@@ -0,0 +1,50 @@
+export declare class SignerIpcClient {
+    private readonly socketPath;
+    constructor(socketPath: string);
+    private call;
+    address(): Promise<`0x${string}`>;
+    signRegisterIdentity(params: {
+        agentURI: string;
+        unsignedTx: {
+            to: `0x${string}`;
+            nonce: number;
+            data: `0x${string}`;
+            gas?: bigint;
+        };
+        chainId: number;
+    }): Promise<{
+        signedTransaction: `0x${string}`;
+    }>;
+    signEIP7702Authorization(contractAddress: `0x${string}`, chainId: number, nonce: number): Promise<{
+        r: `0x${string}`;
+        s: `0x${string}`;
+        yParity: number;
+    }>;
+    signMandateExecute(params: {
+        to: `0x${string}`;
+        value: bigint;
+        data: `0x${string}`;
+        digest: `0x${string}`;
+        amount: number;
+    }): Promise<{
+        signature: `0x${string}`;
+    }>;
+    signAgreementTerms(params: {
+        termsHash: `0x${string}`;
+        counterparty: `0x${string}`;
+    }): Promise<{
+        signature: `0x${string}`;
+    }>;
+    signWithdrawal(params: {
+        to: `0x${string}`;
+        amount: number;
+        unsignedTx: {
+            to: `0x${string}`;
+            value: bigint;
+            data: `0x${string}`;
+        };
+        chainId: number;
+    }): Promise<{
+        signedTransaction: `0x${string}`;
+    }>;
+}

package/dist/ipc-client.js

@@ -0,0 +1,53 @@
+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.
+export class SignerIpcClient {
+    socketPath;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    call(method, params) {
+        return new Promise((resolve, reject) => {
+            const conn = createConnection(this.socketPath);
+            const id = randomUUID();
+            let buffer = "";
+            conn.on("connect", () => {
+                conn.write(JSON.stringify({ id, method, params }) + "\n");
+            });
+            conn.on("data", (chunk) => {
+                buffer += chunk.toString("utf8");
+                const newlineIndex = buffer.indexOf("\n");
+                if (newlineIndex === -1)
+                    return;
+                const response = JSON.parse(buffer.slice(0, newlineIndex));
+                conn.end();
+                if (response.error)
+                    reject(new Error(response.error));
+                else
+                    resolve(response.result);
+            });
+            conn.on("error", reject);
+        });
+    }
+    address() {
+        return this.call("address");
+    }
+    signRegisterIdentity(params) {
+        return this.call("signRegisterIdentity", params);
+    }
+    signEIP7702Authorization(contractAddress, chainId, nonce) {
+        return this.call("signEIP7702Authorization", { contractAddress, chainId, nonce });
+    }
+    signMandateExecute(params) {
+        return this.call("signMandateExecute", params);
+    }
+    signAgreementTerms(params) {
+        return this.call("signAgreementTerms", params);
+    }
+    signWithdrawal(params) {
+        return this.call("signWithdrawal", params);
+    }
+}

package/dist/ipc-server.d.ts

@@ -0,0 +1,11 @@
+import type { Signer } from "./signer.js";
+export declare class SignerIpcServer {
+    private readonly signer;
+    private readonly socketPath;
+    private server;
+    constructor(signer: Signer, socketPath: string);
+    start(): Promise<void>;
+    private handle;
+    private dispatch;
+    stop(): Promise<void>;
+}

package/dist/ipc-server.js

@@ -0,0 +1,81 @@
+import { createServer } from "node:net";
+import { unlink } from "node:fs/promises";
+export class SignerIpcServer {
+    signer;
+    socketPath;
+    server = null;
+    constructor(signer, socketPath) {
+        this.signer = signer;
+        this.socketPath = socketPath;
+    }
+    async start() {
+        // Remove a stale socket file from an unclean previous shutdown —
+        // net.createServer refuses to bind over an existing path otherwise.
+        await unlink(this.socketPath).catch(() => { });
+        this.server = createServer((conn) => {
+            let buffer = "";
+            conn.on("data", (chunk) => {
+                buffer += chunk.toString("utf8");
+                let newlineIndex;
+                while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+                    const line = buffer.slice(0, newlineIndex);
+                    buffer = buffer.slice(newlineIndex + 1);
+                    if (line.length === 0)
+                        continue;
+                    this.handle(line, conn);
+                }
+            });
+        });
+        await new Promise((resolve, reject) => {
+            this.server.once("error", reject);
+            this.server.listen(this.socketPath, resolve);
+        });
+        // Owner-only permissions — matches the encrypted-file store's 0o600.
+        // Anything reachable by other local users defeats the isolation
+        // this socket exists for.
+        const { chmod } = await import("node:fs/promises");
+        await chmod(this.socketPath, 0o600).catch(() => { });
+    }
+    async handle(line, conn) {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            return; // malformed line — drop it, don't crash the connection over it
+        }
+        let response;
+        try {
+            const result = await this.dispatch(request.method, request.params);
+            response = { id: request.id, result };
+        }
+        catch (err) {
+            response = { id: request.id, error: err instanceof Error ? err.message : String(err) };
+        }
+        conn.write(JSON.stringify(response) + "\n");
+    }
+    async dispatch(method, params) {
+        switch (method) {
+            case "address":
+                return this.signer.address();
+            case "signRegisterIdentity":
+                return this.signer.signRegisterIdentity(params);
+            case "signEIP7702Authorization": {
+                const p = params;
+                return this.signer.signEIP7702Authorization(p.contractAddress, p.chainId, p.nonce);
+            }
+            case "signMandateExecute":
+                return this.signer.signMandateExecute(params);
+            case "signAgreementTerms":
+                return this.signer.signAgreementTerms(params);
+            case "signWithdrawal":
+                return this.signer.signWithdrawal(params);
+            default:
+                throw new Error(`Unknown method: ${method}`);
+        }
+    }
+    async stop() {
+        await new Promise((resolve) => this.server?.close(() => resolve()));
+        await unlink(this.socketPath).catch(() => { });
+    }
+}

package/dist/keystore.d.ts

@@ -0,0 +1,60 @@
+import type { Address, Hex } from "viem";
+export interface KeyStore {
+    /** True once a key has been generated and stored — callers check this
+     *  before generateAndStore() to avoid silently overwriting an existing
+     *  key (which would orphan whatever address was already registered
+     *  on-chain). */
+    hasKey(): Promise<boolean>;
+    /** Generates a fresh key, persists it, and returns only the derived
+     *  address — never the key itself. Throws if a key already exists;
+     *  callers must not call this to "reset" a store. */
+    generateAndStore(): Promise<Address>;
+    /** The only way to use the key. `fn`'s return value escapes this
+     *  scope; the raw private key string itself never does. */
+    withPrivateKey<T>(fn: (privateKey: Hex) => Promise<T> | T): Promise<T>;
+    address(): Promise<Address>;
+}
+export declare class OsKeychainStore implements KeyStore {
+    private readonly service;
+    private readonly account;
+    constructor(agentId: string);
+    private entry;
+    hasKey(): Promise<boolean>;
+    generateAndStore(): Promise<Address>;
+    withPrivateKey<T>(fn: (privateKey: Hex) => Promise<T> | T): Promise<T>;
+    address(): Promise<Address>;
+}
+export interface KekProvider {
+    /** Returns a 32-byte key-encryption key. Called once per
+     *  generateAndStore()/withPrivateKey() — implementations are expected
+     *  to cache/memoize their own upstream fetch if it's expensive. */
+    getKek(): Promise<Buffer>;
+}
+/** Development/local-only KEK provider — reads a hex-encoded 32-byte key
+ *  from an env var. NOT a substitute for a real KMS in production: this
+ *  exists so the encrypted-file store is usable and testable without a
+ *  cloud account, and so self-hosted deployments have something to point
+ *  at before wiring up their own KMS-backed provider (see this file's
+ *  doc comment on KekProvider — implement one against AWS KMS/GCP KMS/
+ *  age and pass it to EncryptedFileStore instead, for anything real). */
+export declare class EnvKekProvider implements KekProvider {
+    private readonly envVar;
+    constructor(envVar?: string);
+    getKek(): Promise<Buffer>;
+}
+export declare class EncryptedFileStore implements KeyStore {
+    private readonly filePath;
+    private readonly kek;
+    constructor(filePath: string, kek: KekProvider);
+    hasKey(): Promise<boolean>;
+    generateAndStore(): Promise<Address>;
+    withPrivateKey<T>(fn: (privateKey: Hex) => Promise<T> | T): Promise<T>;
+    address(): Promise<Address>;
+    private writeEncrypted;
+    private readEncrypted;
+}
+/** 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. */
+export declare function defaultKeyStore(agentId: string, fallbackFilePath: string, kek: KekProvider): Promise<KeyStore>;

package/dist/keystore.js

@@ -0,0 +1,164 @@
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from "node:crypto";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+function deriveAddress(privateKey) {
+    return privateKeyToAccount(privateKey).address;
+}
+// ── OS-native keychain store (default) ─────────────────────────────────
+//
+// Backed by @napi-rs/keyring (NAPI-RS bindings over the well-established
+// Rust `keyring-rs` crate) — macOS Keychain, Windows Credential Manager,
+// Linux Secret Service (org.freedesktop.secrets). This is the default
+// because it's the closest local equivalent to what a TEE-based vendor
+// gives you: the OS, not this process's own memory or a plain file, is
+// what actually guards the secret at rest.
+export class OsKeychainStore {
+    service;
+    account;
+    constructor(agentId) {
+        this.service = "gora8-signer";
+        this.account = agentId;
+    }
+    async entry() {
+        const { Entry } = await import("@napi-rs/keyring");
+        return new Entry(this.service, this.account);
+    }
+    async hasKey() {
+        try {
+            const entry = await this.entry();
+            entry.getPassword();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async generateAndStore() {
+        if (await this.hasKey()) {
+            throw new Error(`A key already exists for agent "${this.account}" in the OS keychain. ` +
+                "Refusing to overwrite — generating a new key would orphan the address already registered on-chain.");
+        }
+        const privateKey = generatePrivateKey();
+        const entry = await this.entry();
+        entry.setPassword(privateKey);
+        return deriveAddress(privateKey);
+    }
+    async withPrivateKey(fn) {
+        const entry = await this.entry();
+        const privateKey = entry.getPassword();
+        return fn(privateKey);
+    }
+    async address() {
+        return this.withPrivateKey((pk) => deriveAddress(pk));
+    }
+}
+/** Development/local-only KEK provider — reads a hex-encoded 32-byte key
+ *  from an env var. NOT a substitute for a real KMS in production: this
+ *  exists so the encrypted-file store is usable and testable without a
+ *  cloud account, and so self-hosted deployments have something to point
+ *  at before wiring up their own KMS-backed provider (see this file's
+ *  doc comment on KekProvider — implement one against AWS KMS/GCP KMS/
+ *  age and pass it to EncryptedFileStore instead, for anything real). */
+export class EnvKekProvider {
+    envVar;
+    constructor(envVar = "GORA8_SIGNER_KEK") {
+        this.envVar = envVar;
+    }
+    async getKek() {
+        const hex = process.env[this.envVar];
+        if (!hex) {
+            throw new Error(`${this.envVar} is not set. EncryptedFileStore needs a 32-byte hex-encoded key-encryption ` +
+                "key — generate one with `openssl rand -hex 32` for local/dev use, or implement a real " +
+                "KekProvider against your own KMS for production (see keystore.ts's doc comment).");
+        }
+        const buf = Buffer.from(hex, "hex");
+        if (buf.length !== 32) {
+            throw new Error(`${this.envVar} must decode to exactly 32 bytes (got ${buf.length}).`);
+        }
+        return buf;
+    }
+}
+export class EncryptedFileStore {
+    filePath;
+    kek;
+    constructor(filePath, kek) {
+        this.filePath = filePath;
+        this.kek = kek;
+    }
+    async hasKey() {
+        try {
+            await readFile(this.filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async generateAndStore() {
+        if (await this.hasKey()) {
+            throw new Error(`A key already exists at ${this.filePath}. Refusing to overwrite — generating a new key ` +
+                "would orphan the address already registered on-chain.");
+        }
+        const privateKey = generatePrivateKey();
+        await this.writeEncrypted(privateKey);
+        return deriveAddress(privateKey);
+    }
+    async withPrivateKey(fn) {
+        const privateKey = await this.readEncrypted();
+        return fn(privateKey);
+    }
+    async address() {
+        return this.withPrivateKey((pk) => deriveAddress(pk));
+    }
+    async writeEncrypted(privateKey) {
+        const salt = randomBytes(16);
+        const kekMaterial = await this.kek.getKek();
+        // scrypt-derive a per-store encryption key from the raw KEK + a
+        // random salt, rather than using the KEK bytes directly as the AES
+        // key — so a KEK reused across multiple stores never reuses the
+        // exact same AES key material.
+        const derivedKey = scryptSync(kekMaterial, salt, 32);
+        const iv = randomBytes(12);
+        const cipher = createCipheriv("aes-256-gcm", derivedKey, iv);
+        const ciphertext = Buffer.concat([cipher.update(privateKey, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        const payload = {
+            version: 1,
+            iv: iv.toString("hex"),
+            authTag: authTag.toString("hex"),
+            ciphertext: ciphertext.toString("hex"),
+            salt: salt.toString("hex"),
+        };
+        await mkdir(dirname(this.filePath), { recursive: true });
+        await writeFile(this.filePath, JSON.stringify(payload), { mode: 0o600 });
+    }
+    async readEncrypted() {
+        const raw = await readFile(this.filePath, "utf8");
+        const payload = JSON.parse(raw);
+        const kekMaterial = await this.kek.getKek();
+        const derivedKey = scryptSync(kekMaterial, Buffer.from(payload.salt, "hex"), 32);
+        const decipher = createDecipheriv("aes-256-gcm", derivedKey, Buffer.from(payload.iv, "hex"));
+        decipher.setAuthTag(Buffer.from(payload.authTag, "hex"));
+        const plaintext = Buffer.concat([decipher.update(Buffer.from(payload.ciphertext, "hex")), decipher.final()]);
+        return plaintext.toString("utf8");
+    }
+}
+/** 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. */
+export async function defaultKeyStore(agentId, fallbackFilePath, kek) {
+    try {
+        await import("@napi-rs/keyring");
+        const store = new OsKeychainStore(agentId);
+        // Probe for a usable keychain backend (this throws on headless Linux
+        // hosts with no Secret Service daemon running) without touching any
+        // real credential.
+        await store.hasKey();
+        return store;
+    }
+    catch {
+        return new EncryptedFileStore(fallbackFilePath, kek);
+    }
+}

package/dist/merkle-tree.d.ts

@@ -0,0 +1,11 @@
+import { type Hex } from "viem";
+export interface MerkleTree {
+    root: Hex;
+    layers: Hex[][];
+}
+/** A single, odd leaf at any level is carried up unchanged (not
+ *  duplicated/hashed with itself) — avoids the well-known second-preimage
+ *  issue some naive "duplicate the last leaf" implementations have. */
+export declare function buildMerkleTree(leaves: Hex[]): MerkleTree;
+export declare function getMerkleProof(tree: MerkleTree, leafIndex: number): Hex[];
+export declare function verifyMerkleProof(leaf: Hex, proof: Hex[], root: Hex): boolean;

package/dist/merkle-tree.js

@@ -0,0 +1,55 @@
+import { keccak256, encodePacked } from "viem";
+// Identical convention to api/src/lib/merkle-tree.ts (gora8's own
+// reputation-ledger CommitmentRoot) — a standard sorted-pair keccak256
+// merkle tree, the same one OpenZeppelin's MerkleProof.sol uses.
+// Deliberately the same code, not a bespoke reimplementation: this
+// signer's audit log commitment and gora8's reputation commitment should
+// be verifiable the same way, by the same tooling, not two subtly
+// different "merkle-ish" schemes an auditor has to learn separately.
+function hashPair(a, b) {
+    const [lo, hi] = a.toLowerCase() < b.toLowerCase() ? [a, b] : [b, a];
+    return keccak256(encodePacked(["bytes32", "bytes32"], [lo, hi]));
+}
+/** A single, odd leaf at any level is carried up unchanged (not
+ *  duplicated/hashed with itself) — avoids the well-known second-preimage
+ *  issue some naive "duplicate the last leaf" implementations have. */
+export function buildMerkleTree(leaves) {
+    if (leaves.length === 0)
+        throw new Error("buildMerkleTree: at least one leaf is required.");
+    const layers = [leaves];
+    let current = leaves;
+    while (current.length > 1) {
+        const next = [];
+        for (let i = 0; i < current.length; i += 2) {
+            if (i + 1 < current.length) {
+                next.push(hashPair(current[i], current[i + 1]));
+            }
+            else {
+                next.push(current[i]);
+            }
+        }
+        layers.push(next);
+        current = next;
+    }
+    return { root: current[0], layers };
+}
+export function getMerkleProof(tree, leafIndex) {
+    const proof = [];
+    let index = leafIndex;
+    for (let level = 0; level < tree.layers.length - 1; level++) {
+        const layer = tree.layers[level];
+        const isRightNode = index % 2 === 1;
+        const siblingIndex = isRightNode ? index - 1 : index + 1;
+        if (siblingIndex < layer.length)
+            proof.push(layer[siblingIndex]);
+        index = Math.floor(index / 2);
+    }
+    return proof;
+}
+export function verifyMerkleProof(leaf, proof, root) {
+    let computed = leaf;
+    for (const sibling of proof) {
+        computed = hashPair(computed, sibling);
+    }
+    return computed.toLowerCase() === root.toLowerCase();
+}

package/dist/policy.d.ts

@@ -0,0 +1,79 @@
+import type { Address } from "viem";
+export interface Mandate {
+    protocol: string;
+    mandateId: string;
+    status: "active" | "revoked";
+    spending: {
+        perTransactionLimit: number | null;
+        dailyCap: number | null;
+        monthlyCap: number | null;
+        currency: string;
+    };
+    counterpartyRequirements: {
+        allowedCounterparties: string[];
+    };
+    validUntil: string;
+}
+export interface SigningRequest {
+    /** Decimal amount in the Mandate's currency (USDC) — null for
+     *  operations that don't move value (identity registration, the
+     *  EIP-7702 delegation itself). */
+    amount: number | null;
+    counterparty: Address | null;
+    /** Contract + 4-byte selector, for a MandateEnforcer.execute()-shaped
+     *  call — checked against an allowlist if one is configured (see
+     *  PolicyEngine's constructor). Mandate.spending/counterpartyRequirements
+     *  don't carry this today; it's an additional, signer-local
+     *  restriction, opt-in per deployment. */
+    contract: Address | null;
+    selector: `0x${string}` | null;
+}
+export interface PolicyDecision {
+    allowed: boolean;
+    reason?: string;
+}
+export interface PolicyEngineOptions {
+    /** How the engine fetches the current Mandate — default implementation
+     *  hits gora8's public, unauthenticated endpoint; tests/self-hosted
+     *  setups can substitute anything. */
+    fetchMandate: () => Promise<Mandate>;
+    /** How often the cached Mandate is allowed to go stale before a fresh
+     *  fetch is forced (ms). Defaults to 60s — short enough that a
+     *  just-revoked or just-tightened policy takes effect quickly, long
+     *  enough that a burst of signing requests doesn't hit gora8's API
+     *  once per signature. */
+    cacheTtlMs?: number;
+    /** Optional allowlist of (contract, selector) pairs — if set, any
+     *  signing request naming a contract/selector outside this list is
+     *  refused regardless of what the Mandate itself says (the Mandate
+     *  doesn't model this dimension; this is a signer-local addition for
+     *  deployments that want it). Unset means "no restriction beyond the
+     *  Mandate's own fields." */
+    allowedTargets?: Array<{
+        contract: Address;
+        selector: `0x${string}`;
+    }>;
+}
+/** The local, independent counterpart to daily/monthly caps —
+ *  gora8's own server tracks cumulative spend against its database
+ *  (see policy-enforcement.ts's sumHiredSince()); this signer keeps its
+ *  OWN running tally from what it has actually signed, so daily/monthly
+ *  enforcement doesn't depend on trusting gora8's count either. Backed
+ *  by the same audit log this signer already writes (see audit-log.ts) —
+ *  not a second, separately-maintained ledger. */
+export interface SpendTracker {
+    spentSince(date: Date): Promise<number>;
+}
+export declare class PolicyEngine {
+    private readonly options;
+    private readonly spendTracker;
+    private cachedMandate;
+    private cachedAt;
+    constructor(options: PolicyEngineOptions, spendTracker: SpendTracker);
+    private mandate;
+    /** Forces the next check to re-fetch — call this when gora8 pushes a
+     *  policy-edit notification, so a tightened (or revoked) Mandate takes
+     *  effect immediately rather than waiting out the TTL. */
+    invalidateCache(): void;
+    evaluate(request: SigningRequest): Promise<PolicyDecision>;
+}

package/dist/policy.js

@@ -0,0 +1,71 @@
+export class PolicyEngine {
+    options;
+    spendTracker;
+    cachedMandate = null;
+    cachedAt = 0;
+    constructor(options, spendTracker) {
+        this.options = options;
+        this.spendTracker = spendTracker;
+    }
+    async mandate() {
+        const ttl = this.options.cacheTtlMs ?? 60_000;
+        if (this.cachedMandate && Date.now() - this.cachedAt < ttl)
+            return this.cachedMandate;
+        const fresh = await this.options.fetchMandate();
+        this.cachedMandate = fresh;
+        this.cachedAt = Date.now();
+        return fresh;
+    }
+    /** Forces the next check to re-fetch — call this when gora8 pushes a
+     *  policy-edit notification, so a tightened (or revoked) Mandate takes
+     *  effect immediately rather than waiting out the TTL. */
+    invalidateCache() {
+        this.cachedMandate = null;
+    }
+    async evaluate(request) {
+        const mandate = await this.mandate();
+        if (mandate.status !== "active") {
+            return { allowed: false, reason: `Mandate ${mandate.mandateId} is not active (status: ${mandate.status}).` };
+        }
+        if (new Date(mandate.validUntil).getTime() < Date.now()) {
+            return { allowed: false, reason: `Mandate ${mandate.mandateId} expired at ${mandate.validUntil}.` };
+        }
+        if (request.amount !== null) {
+            const { perTransactionLimit, dailyCap, monthlyCap } = mandate.spending;
+            if (perTransactionLimit !== null && request.amount > perTransactionLimit) {
+                return { allowed: false, reason: `Amount ${request.amount} exceeds per-transaction limit ${perTransactionLimit}.` };
+            }
+            if (dailyCap !== null) {
+                const since = new Date();
+                since.setHours(0, 0, 0, 0);
+                const spentToday = await this.spendTracker.spentSince(since);
+                if (spentToday + request.amount > dailyCap) {
+                    return { allowed: false, reason: `Would exceed daily cap ${dailyCap} (already spent ${spentToday} today).` };
+                }
+            }
+            if (monthlyCap !== null) {
+                const since = new Date();
+                since.setDate(1);
+                since.setHours(0, 0, 0, 0);
+                const spentThisMonth = await this.spendTracker.spentSince(since);
+                if (spentThisMonth + request.amount > monthlyCap) {
+                    return { allowed: false, reason: `Would exceed monthly cap ${monthlyCap} (already spent ${spentThisMonth} this month).` };
+                }
+            }
+        }
+        const allowedCounterparties = mandate.counterpartyRequirements.allowedCounterparties;
+        if (request.counterparty && allowedCounterparties.length > 0) {
+            const match = allowedCounterparties.some((c) => c.toLowerCase() === request.counterparty.toLowerCase());
+            if (!match) {
+                return { allowed: false, reason: `Counterparty ${request.counterparty} is not on the Mandate's allowed-counterparty list.` };
+            }
+        }
+        if (this.options.allowedTargets && request.contract && request.selector) {
+            const match = this.options.allowedTargets.some((t) => t.contract.toLowerCase() === request.contract.toLowerCase() && t.selector.toLowerCase() === request.selector.toLowerCase());
+            if (!match) {
+                return { allowed: false, reason: `${request.contract}.${request.selector} is not on the configured allowed-targets list.` };
+            }
+        }
+        return { allowed: true };
+    }
+}

package/dist/signer.d.ts

@@ -0,0 +1,120 @@
+import { type Address, type Hex } from "viem";
+import type { KeyStore } from "./keystore.js";
+import type { PolicyEngine } from "./policy.js";
+import { AuditLog } from "./audit-log.js";
+interface RateLimiter {
+    /** Throws if calling now would exceed the configured rate — a sanity
+     *  backstop independent of Mandate spend limits (catches "signing too
+     *  often," e.g. a runaway loop, not "spending too much"). */
+    checkAndRecord(): void;
+}
+/** Simple sliding-window limiter — no external dependency needed for
+ *  something this small. */
+export declare class SlidingWindowRateLimiter implements RateLimiter {
+    private readonly maxCalls;
+    private readonly windowMs;
+    private timestamps;
+    constructor(maxCalls: number, windowMs: number);
+    checkAndRecord(): void;
+}
+export interface SignerOptions {
+    keyStore: KeyStore;
+    policyEngine: PolicyEngine;
+    auditLog: AuditLog;
+    rateLimiter?: RateLimiter;
+}
+export declare class Signer {
+    private readonly options;
+    constructor(options: SignerOptions);
+    address(): Promise<Address>;
+    private logAndEnforce;
+    /** One-time: signs the register() call that mints this agent's
+     *  ERC-8004 identity, owned by this signer's own address. Takes an
+     *  already-encoded, already-nonced unsigned transaction — this package
+     *  deliberately doesn't know ERC-8004's ABI or fetch chain state (nonce,
+     *  gas price) itself, both to avoid duplicating that knowledge (it
+     *  already exists in erc8004-client.ts's server-side counterpart) and
+     *  to keep this signer's own network surface at zero: it never makes
+     *  an RPC call, only signs exactly what it's handed. `agentURI` is
+     *  accepted for the audit log entry, not used to build the call. */
+    signRegisterIdentity(params: {
+        agentURI: string;
+        unsignedTx: {
+            to: Address;
+            nonce: number;
+            data: Hex;
+            gas?: bigint;
+        };
+        chainId: number;
+    }): Promise<{
+        signedTransaction: Hex;
+    }>;
+    /** Signs an EIP-7702 authorization delegating this wallet's code to
+     *  `contractAddress` (gora8's own MandateEnforcer, or any other
+     *  contract the owner explicitly configures) — the exact mechanism
+     *  mandate-enforcer-client.ts's delegateAndSetMandate() already uses
+     *  server-side today; this is the same operation, signed locally. */
+    signEIP7702Authorization(contractAddress: Address, chainId: number, nonce: number): Promise<{
+        r: Hex;
+        s: Hex;
+        yParity: number;
+    }>;
+    /** The actual spend-constrained call — MandateEnforcer.execute()'s
+     *  signature, or any (to, value, data) tuple the caller has already
+     *  determined needs signing. `amount` is the decimal USDC value being
+     *  moved (for Mandate evaluation) even though `value`/`data` carry the
+     *  real on-chain encoding — the two are related but not always
+     *  identical (a USDC transferWithAuthorization's "value" isn't the
+     *  transaction's native-token value field), so both are passed
+     *  explicitly rather than this method trying to infer one from the
+     *  other. */
+    signMandateExecute(params: {
+        to: Address;
+        value: bigint;
+        data: Hex;
+        /** MandateEnforcer.hashExecute(to, value, data, executeNonce)'s
+         *  result — computed by the caller (it needs MandateEnforcer's own
+         *  ABI, which this package doesn't duplicate; see this method's own
+         *  doc comment and signRegisterIdentity's for why). */
+        digest: Hex;
+        amount: number;
+    }): Promise<{
+        signature: Hex;
+    }>;
+    /** Co-signs an Agreement's terms hash (api/src/lib/agreement.ts) — the
+     *  buyer-side commitment before a hire is forwarded, or the
+     *  provider-side counter-signature once delivery succeeds. Neither
+     *  moves funds itself (the actual spend is a separate
+     *  signMandateExecute call, evaluated and rate-limited on its own) —
+     *  `amount` is deliberately omitted from the policy request so this
+     *  doesn't double-count against the Mandate's daily/monthly caps
+     *  alongside the real payment for the same hire; the counterparty
+     *  check still applies, so gora8 can't get this signer to attest to
+     *  terms with a counterparty outside the Mandate's allowlist. Like
+     *  signMandateExecute, signs the exact digest the caller already
+     *  computed (agreement.ts's hashTerms()) — this package doesn't
+     *  duplicate Agreement's own hashing logic, only signs what it's
+     *  handed. */
+    signAgreementTerms(params: {
+        termsHash: Hex;
+        counterparty: Address;
+    }): Promise<{
+        signature: Hex;
+    }>;
+    /** Owner-initiated funds-out — same policy checks apply (a withdrawal
+     *  is still constrained by the Mandate's spend limits and, if
+     *  configured, allowed-counterparty list). */
+    signWithdrawal(params: {
+        to: Address;
+        amount: number;
+        unsignedTx: {
+            to: Address;
+            value: bigint;
+            data: Hex;
+        };
+        chainId: number;
+    }): Promise<{
+        signedTransaction: Hex;
+    }>;
+}
+export {};

package/dist/signer.js

@@ -0,0 +1,172 @@
+import { createWalletClient, http, defineChain } from "viem";
+/** Simple sliding-window limiter — no external dependency needed for
+ *  something this small. */
+export class SlidingWindowRateLimiter {
+    maxCalls;
+    windowMs;
+    timestamps = [];
+    constructor(maxCalls, windowMs) {
+        this.maxCalls = maxCalls;
+        this.windowMs = windowMs;
+    }
+    checkAndRecord() {
+        const now = Date.now();
+        this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
+        if (this.timestamps.length >= this.maxCalls) {
+            throw new Error(`Rate limit exceeded: more than ${this.maxCalls} signing requests in ${this.windowMs}ms.`);
+        }
+        this.timestamps.push(now);
+    }
+}
+// A syntactically-valid but never-actually-called placeholder — viem's
+// http() transport validates its URL eagerly at client-construction
+// time even though every operation this signer performs (signAuthorization,
+// signTransaction, raw digest signing) is pure offline computation
+// against the account and never issues a real RPC call. No real network
+// access is needed or granted here; broadcasting is gora8's relay
+// wallet's job, not this signer's — see this file's own doc comment.
+const OFFLINE_PLACEHOLDER_RPC_URL = "http://127.0.0.1:0";
+function genericChain(chainId) {
+    return defineChain({
+        id: chainId,
+        name: `chain-${chainId}`,
+        nativeCurrency: { name: "ETH", symbol: "ETH", decimals: 18 },
+        rpcUrls: { default: { http: [OFFLINE_PLACEHOLDER_RPC_URL] } },
+    });
+}
+export class Signer {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async address() {
+        return this.options.keyStore.address();
+    }
+    async logAndEnforce(operation, request) {
+        this.options.rateLimiter?.checkAndRecord();
+        const decision = await this.options.policyEngine.evaluate(request);
+        const entry = {
+            timestamp: new Date().toISOString(),
+            operation,
+            allowed: decision.allowed,
+            reason: decision.reason,
+            amount: request.amount,
+            counterparty: request.counterparty,
+        };
+        await this.options.auditLog.append(entry);
+        if (!decision.allowed) {
+            throw new Error(`Refused: ${operation} — ${decision.reason}`);
+        }
+    }
+    /** One-time: signs the register() call that mints this agent's
+     *  ERC-8004 identity, owned by this signer's own address. Takes an
+     *  already-encoded, already-nonced unsigned transaction — this package
+     *  deliberately doesn't know ERC-8004's ABI or fetch chain state (nonce,
+     *  gas price) itself, both to avoid duplicating that knowledge (it
+     *  already exists in erc8004-client.ts's server-side counterpart) and
+     *  to keep this signer's own network surface at zero: it never makes
+     *  an RPC call, only signs exactly what it's handed. `agentURI` is
+     *  accepted for the audit log entry, not used to build the call. */
+    async signRegisterIdentity(params) {
+        await this.logAndEnforce("signRegisterIdentity", { amount: null, counterparty: null, contract: null, selector: null });
+        return this.options.keyStore.withPrivateKey(async (privateKey) => {
+            const { privateKeyToAccount } = await import("viem/accounts");
+            const account = privateKeyToAccount(privateKey);
+            const walletClient = createWalletClient({ account, chain: genericChain(params.chainId), transport: http(OFFLINE_PLACEHOLDER_RPC_URL) });
+            const signedTransaction = await walletClient.signTransaction({
+                account,
+                chain: genericChain(params.chainId),
+                to: params.unsignedTx.to,
+                nonce: params.unsignedTx.nonce,
+                data: params.unsignedTx.data,
+                gas: params.unsignedTx.gas,
+            });
+            return { signedTransaction };
+        });
+    }
+    /** Signs an EIP-7702 authorization delegating this wallet's code to
+     *  `contractAddress` (gora8's own MandateEnforcer, or any other
+     *  contract the owner explicitly configures) — the exact mechanism
+     *  mandate-enforcer-client.ts's delegateAndSetMandate() already uses
+     *  server-side today; this is the same operation, signed locally. */
+    async signEIP7702Authorization(contractAddress, chainId, nonce) {
+        await this.logAndEnforce("signEIP7702Authorization", { amount: null, counterparty: null, contract: contractAddress, selector: null });
+        return this.options.keyStore.withPrivateKey(async (privateKey) => {
+            const { privateKeyToAccount } = await import("viem/accounts");
+            const account = privateKeyToAccount(privateKey);
+            const walletClient = createWalletClient({ account, chain: genericChain(chainId), transport: http(OFFLINE_PLACEHOLDER_RPC_URL) });
+            const authorization = await walletClient.signAuthorization({ contractAddress, chainId, nonce });
+            return { r: authorization.r, s: authorization.s, yParity: authorization.yParity ?? 0 };
+        });
+    }
+    /** The actual spend-constrained call — MandateEnforcer.execute()'s
+     *  signature, or any (to, value, data) tuple the caller has already
+     *  determined needs signing. `amount` is the decimal USDC value being
+     *  moved (for Mandate evaluation) even though `value`/`data` carry the
+     *  real on-chain encoding — the two are related but not always
+     *  identical (a USDC transferWithAuthorization's "value" isn't the
+     *  transaction's native-token value field), so both are passed
+     *  explicitly rather than this method trying to infer one from the
+     *  other. */
+    async signMandateExecute(params) {
+        const selector = params.data.slice(0, 10);
+        await this.logAndEnforce("signMandateExecute", {
+            amount: params.amount,
+            counterparty: params.to,
+            contract: params.to,
+            selector,
+        });
+        return this.options.keyStore.withPrivateKey(async (privateKey) => {
+            const { privateKeyToAccount } = await import("viem/accounts");
+            const account = privateKeyToAccount(privateKey);
+            // Raw signature over the already-fully-encoded digest — not
+            // signMessage/signTypedData, matching mandate-enforcer-client.ts's
+            // existing executeViaMandate() convention exactly (this is the
+            // same operation, just signed locally instead of server-side).
+            const signature = await account.sign({ hash: params.digest });
+            return { signature };
+        });
+    }
+    /** Co-signs an Agreement's terms hash (api/src/lib/agreement.ts) — the
+     *  buyer-side commitment before a hire is forwarded, or the
+     *  provider-side counter-signature once delivery succeeds. Neither
+     *  moves funds itself (the actual spend is a separate
+     *  signMandateExecute call, evaluated and rate-limited on its own) —
+     *  `amount` is deliberately omitted from the policy request so this
+     *  doesn't double-count against the Mandate's daily/monthly caps
+     *  alongside the real payment for the same hire; the counterparty
+     *  check still applies, so gora8 can't get this signer to attest to
+     *  terms with a counterparty outside the Mandate's allowlist. Like
+     *  signMandateExecute, signs the exact digest the caller already
+     *  computed (agreement.ts's hashTerms()) — this package doesn't
+     *  duplicate Agreement's own hashing logic, only signs what it's
+     *  handed. */
+    async signAgreementTerms(params) {
+        await this.logAndEnforce("signAgreementTerms", { amount: null, counterparty: params.counterparty, contract: null, selector: null });
+        return this.options.keyStore.withPrivateKey(async (privateKey) => {
+            const { privateKeyToAccount } = await import("viem/accounts");
+            const account = privateKeyToAccount(privateKey);
+            const signature = await account.sign({ hash: params.termsHash });
+            return { signature };
+        });
+    }
+    /** Owner-initiated funds-out — same policy checks apply (a withdrawal
+     *  is still constrained by the Mandate's spend limits and, if
+     *  configured, allowed-counterparty list). */
+    async signWithdrawal(params) {
+        await this.logAndEnforce("signWithdrawal", { amount: params.amount, counterparty: params.to, contract: null, selector: null });
+        return this.options.keyStore.withPrivateKey(async (privateKey) => {
+            const { privateKeyToAccount } = await import("viem/accounts");
+            const account = privateKeyToAccount(privateKey);
+            const walletClient = createWalletClient({ account, chain: genericChain(params.chainId), transport: http(OFFLINE_PLACEHOLDER_RPC_URL) });
+            const signedTransaction = await walletClient.signTransaction({
+                account,
+                to: params.unsignedTx.to,
+                value: params.unsignedTx.value,
+                data: params.unsignedTx.data,
+                chain: genericChain(params.chainId),
+            });
+            return { signedTransaction };
+        });
+    }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "gora8-signer",
+  "version": "0.1.0",
+  "description": "Local, self-custodied key signing for gora8 agents — the key is generated and used wherever your agent runs, never inside gora8's own infrastructure. See SELF_CUSTODY_ARCHITECTURE.md in the gora8 monorepo for the full design.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "gora8-signer": "./dist/cli.js"
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^20.0.0"
+  },
+  "dependencies": {
+    "viem": "^2.21.0",
+    "@napi-rs/keyring": "^1.3.0"
+  }
+}