@agenticprimitives/key-custody 0.1.0-alpha.2 → 1.0.0-alpha.10

package/dist/relayer-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayer-account.d.ts","sourceRoot":"","sources":["../src/relayer-account.ts"],"names":[],"mappings":"AA2CA,OAAO,EAML,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AACd,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AA6CD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,YAAY,CAAC,CAgDvB"}

package/dist/relayer-account.js

@@ -0,0 +1,146 @@
+// createRelayerAccount — KMS-backed viem LocalAccount with built-in audit
+// emission for funded relayer/operator chain calls.
+//
+// R5.12a / PKG-KEY-CUSTODY-005 (relayer-pattern package gap).
+//
+// Why a separate factory from `createKmsViemAccount`:
+//
+//   `createKmsViemAccount(backend)` returns a general-purpose viem
+//   LocalAccount. App-level relayers that pay gas for sponsored deploys,
+//   name registrations, custody-policy applies, paymaster top-ups, etc.
+//   need ONE more thing: a forensic trail. Every relayed sign op must
+//   emit an audit row tagged with the operator ROLE so the on-chain
+//   action stitches back to the off-chain `(role, target, value)` tuple
+//   in audit logs.
+//
+//   The `createRelayerAccount(backend, { role, auditSink })` factory
+//   composes the existing `createKmsViemAccount` + audit emission so
+//   app code reaches for THIS when migrating off raw private keys.
+//
+//   Why this matters: pre-R5.12a, app authors reached for
+//   `privateKeyToAccount(DEPLOYER_PRIVATE_KEY)` because there was no
+//   obvious "use me for funded relayer ops" entry point. The packages
+//   had all the primitives (`buildSignerBackend` + `createKmsViemAccount`),
+//   but no convention. This factory IS the convention.
+//
+// Audit event emitted on every sign op:
+//   action:   `key-custody.relay.sign`
+//   actor:    { type: 'system', id: <role> }
+//   subject:  { type: <opType>, id: <digestFingerprint> }
+//   context:
+//     role:           caller-supplied role tag
+//     signerAddress:  the relayer EOA
+//     opType:         'message' | 'transaction' | 'typed-data'
+//     to:             tx target address (transaction only)
+//     value:          tx value in wei (transaction only)
+//     digestFingerprint: keccak256(digest).slice(0, 18) — 9 bytes of
+//                        the digest, never the digest itself
+//
+// Fail-soft: audit emission errors are caught and silently dropped so
+// a logging outage cannot break the relay flow. Consumers who need
+// fail-hard semantics should wrap the supplied sink with
+// `composeFailHardSinks` from @agenticprimitives/audit.
+import { hashMessage, hashTypedData, keccak256, serializeTransaction, } from 'viem';
+import { buildEvent } from '@agenticprimitives/audit';
+import { createKmsViemAccount } from './kms-viem-account';
+function digestFingerprint(digest) {
+    // 18 chars = 9 bytes of the keccak hash. Enough to disambiguate in
+    // logs; far too short to be a preimage. Same redaction shape used by
+    // LocalSecp256k1Signer / GcpKmsSigner for digests in audit rows.
+    return keccak256(digest).slice(0, 18);
+}
+async function emitRelaySign(auditSink, role, signerAddress, opType, digest, txContext) {
+    if (!auditSink)
+        return;
+    try {
+        await auditSink.write(buildEvent({
+            action: 'key-custody.relay.sign',
+            outcome: 'success',
+            actor: { type: 'system', id: role },
+            subject: { type: opType, id: digestFingerprint(digest) },
+            context: {
+                role,
+                signerAddress,
+                opType,
+                to: txContext?.to ?? null,
+                // Audit context values must be JSON-serialisable; emit value as
+                // a decimal string (bigint loses precision on JSON.stringify).
+                value: txContext?.value !== undefined ? txContext.value.toString() : null,
+                digestFingerprint: digestFingerprint(digest),
+            },
+        }));
+    }
+    catch {
+        // Fail-soft: an audit sink outage cannot break the relay flow.
+        // Consumers who want fail-hard semantics wrap with
+        // composeFailHardSinks from @agenticprimitives/audit.
+    }
+}
+/**
+ * Wrap a {@link KmsAccountBackend} as a viem {@link LocalAccount} suitable
+ * for funded relayer / operator chain calls.
+ *
+ * The returned account delegates signing to `createKmsViemAccount(backend)`
+ * (same HSM-backed digest signing, no key material leaves KMS) and
+ * additionally emits a `key-custody.relay.sign` audit row on every
+ * sign op tagged with the supplied `role`.
+ *
+ * Migration target for app code that previously used
+ * `privateKeyToAccount(env.X_PRIVATE_KEY)` for funded ops.
+ *
+ * @example
+ * ```ts
+ * const backend = buildSignerBackend({ backend: 'gcp-kms' });
+ * const relayer = await createRelayerAccount(backend, {
+ *   role: 'direct-deploy',
+ *   auditSink,
+ * });
+ * await walletClient.writeContract({ account: relayer, ... });
+ * // emits: key-custody.relay.sign { role: 'direct-deploy', opType: 'transaction', to, value, ... }
+ * ```
+ */
+export async function createRelayerAccount(backend, opts) {
+    const inner = await createKmsViemAccount(backend);
+    const { role, auditSink } = opts;
+    return {
+        address: inner.address,
+        type: 'local',
+        source: 'kms-relayer',
+        publicKey: inner.publicKey,
+        async signMessage({ message }) {
+            const digest = hashMessage(message);
+            const signed = await inner.signMessage({ message });
+            await emitRelaySign(auditSink, role, inner.address, 'message', digest);
+            return signed;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async signTransaction(transaction, options) {
+            // Compute the digest for audit emission BEFORE handing off to
+            // the inner account (which recomputes it internally; viem doesn't
+            // expose the precomputed digest from privateKeyToAccount-style
+            // accounts, so we re-do it here for the audit subject).
+            const serializer = options?.serializer ?? serializeTransaction;
+            const unsigned = serializer(transaction);
+            const digest = keccak256(unsigned);
+            const signed = await inner.signTransaction(transaction, options);
+            await emitRelaySign(auditSink, role, inner.address, 'transaction', digest, {
+                to: transaction.to ?? null,
+                // viem transactions use bigint for value; default to 0n when omitted.
+                value: typeof transaction.value === 'bigint'
+                    ? transaction.value
+                    : transaction.value !== undefined
+                        ? BigInt(transaction.value)
+                        : 0n,
+            });
+            return signed;
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async signTypedData(args) {
+            const digest = hashTypedData(args);
+            const signed = await inner.signTypedData(args);
+            await emitRelaySign(auditSink, role, inner.address, 'typed-data', digest);
+            return signed;
+        },
+    };
+}
+//# sourceMappingURL=relayer-account.js.map

package/dist/relayer-account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relayer-account.js","sourceRoot":"","sources":["../src/relayer-account.ts"],"names":[],"mappings":"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"}

package/dist/spend-capped-account.d.ts

@@ -0,0 +1,71 @@
+import { type Hex, type LocalAccount } from 'viem';
+import { type AuditSink } from '@agenticprimitives/audit';
+export interface CreateSpendCappedAccountOpts {
+    /**
+     * Maximum ETH value (in wei) this account is allowed to send PER
+     * TRANSACTION. A `signTransaction` request with `value > capWei`
+     * is rejected with {@link SpendCapExceededError} before any signing
+     * round-trip.
+     *
+     * `0n` is permitted and meaningful — it blocks ALL value-transferring
+     * txs while still allowing contract writes that don't send ETH.
+     * Useful for a signer that can call `register(...)` but cannot
+     * `transfer(...)` natively.
+     */
+    capWei: bigint;
+    /**
+     * Where to write `key-custody.relay.spend-cap.reject` events. Omit
+     * only for tests; production deploys SHOULD wire a durable sink so
+     * cap rejections leave a forensic trail (operators will want to
+     * detect the request pattern that triggered the reject).
+     */
+    auditSink?: AuditSink;
+}
+/**
+ * Thrown by a spend-capped account's `signTransaction` when the
+ * requested `value` exceeds the configured `capWei`. The HSM is
+ * never asked to sign — this is a pre-signing fail-closed gate.
+ */
+export declare class SpendCapExceededError extends Error {
+    readonly capWei: bigint;
+    readonly requestedValue: bigint;
+    readonly to: Hex | null;
+    readonly signerAddress: Hex;
+    constructor(opts: {
+        capWei: bigint;
+        requestedValue: bigint;
+        to: Hex | null;
+        signerAddress: Hex;
+    });
+}
+/**
+ * Wrap any viem {@link LocalAccount} with a per-transaction ETH-value
+ * cap. The cap is enforced BEFORE signing: a `signTransaction` call
+ * with `value > capWei` throws {@link SpendCapExceededError} and the
+ * HSM / KMS never sees the digest.
+ *
+ * `signMessage` and `signTypedData` are forwarded verbatim — they
+ * don't carry an on-chain ETH value, so the cap doesn't apply.
+ *
+ * Composes with `createRelayerAccount`: wrap the relayer with the
+ * cap to get role-tagged audit emission AND a per-tx spend limit.
+ *
+ * Synchronous factory — the wrapper holds no async state. The inner
+ * account must already be resolved (it carries the address).
+ *
+ * @example
+ * ```ts
+ * const inner = await createRelayerAccount(backend, {
+ *   role: 'paymaster-topup',
+ *   auditSink,
+ * });
+ * const capped = createSpendCappedAccount(inner, {
+ *   capWei: 10n ** 17n, // 0.1 ETH
+ *   auditSink,
+ * });
+ * await walletClient.sendTransaction({ account: capped, to, value: 5n * 10n ** 16n }); // 0.05 ETH — OK
+ * await walletClient.sendTransaction({ account: capped, to, value: 10n ** 18n });      // throws SpendCapExceededError
+ * ```
+ */
+export declare function createSpendCappedAccount(inner: LocalAccount, opts: CreateSpendCappedAccountOpts): LocalAccount;
+//# sourceMappingURL=spend-capped-account.d.ts.map

package/dist/spend-capped-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-capped-account.d.ts","sourceRoot":"","sources":["../src/spend-capped-account.ts"],"names":[],"mappings":"AAkDA,OAAO,EACL,KAAK,GAAG,EACR,KAAK,YAAY,EAElB,MAAM,MAAM,CAAC;AACd,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEtE,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,IAAI,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC;gBAEhB,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,EAAE,EAAE,GAAG,GAAG,IAAI,CAAC;QACf,aAAa,EAAE,GAAG,CAAC;KACpB;CAYF;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,4BAA4B,GACjC,YAAY,CAgDd"}

package/dist/spend-capped-account.js

@@ -0,0 +1,181 @@
+// createSpendCappedAccount — wrap any viem LocalAccount with a per-tx
+// ETH-value cap that fails CLOSED before any signing round-trip.
+//
+// R5.12b / PKG-KEY-CUSTODY-010 (relayer-pattern gap, follow-on to R5.12a).
+//
+// Use case:
+//   You're running a funded operator key — say the paymaster top-up key
+//   — that legitimately needs to send ETH on chain. The key is meant
+//   to send AT MOST `capWei` per transaction. A compromised app
+//   process holding this account should not be able to drain funds in
+//   one shot.
+//
+//   Pre-R5.12b, the only way to enforce this was operationally:
+//   monitor the on-chain balance, hope the operator catches a drain
+//   in time, rotate keys after the fact. The cap was unenforceable
+//   at signing time.
+//
+//   Post-R5.12b, `createSpendCappedAccount(inner, { capWei })`
+//   wraps any viem LocalAccount and inspects `transaction.value` in
+//   `signTransaction`. If `value > capWei`, throws a
+//   `SpendCapExceededError` BEFORE the KMS round-trip — the HSM
+//   never even sees the digest.
+//
+// What it does NOT do:
+//   - Track cumulative spend across calls (the cap is per-tx, not a
+//     rolling budget). A cumulative tracker is operational state
+//     (sticky across processes / restarts), which belongs at the
+//     app or substrate layer, not in a stateless signer wrapper.
+//   - Inspect calldata (no introspection of internal ETH transfers
+//     a contract call might perform). The cap is on the value the
+//     account itself sends; downstream contract behavior is the
+//     contract's contract.
+//
+// Composition:
+//   Designed to compose with `createRelayerAccount` (R5.12a):
+//
+//     const inner = await createRelayerAccount(backend, {
+//       role: 'paymaster-topup',
+//       auditSink,
+//     });
+//     const capped = createSpendCappedAccount(inner, {
+//       capWei: 10n ** 17n, // 0.1 ETH per tx
+//       auditSink,
+//     });
+//
+//   When a tx is rejected, the cap wrapper emits its own
+//   `key-custody.relay.spend-cap.reject` event so the relayer's
+//   `key-custody.relay.sign.success` and the cap's reject are both
+//   in the audit trail with matching `signerAddress`.
+import { buildEvent } from '@agenticprimitives/audit';
+/**
+ * Thrown by a spend-capped account's `signTransaction` when the
+ * requested `value` exceeds the configured `capWei`. The HSM is
+ * never asked to sign — this is a pre-signing fail-closed gate.
+ */
+export class SpendCapExceededError extends Error {
+    capWei;
+    requestedValue;
+    to;
+    signerAddress;
+    constructor(opts) {
+        super(`[key-custody] spend cap exceeded: requested ${opts.requestedValue.toString()} wei to ${opts.to ?? '<no target>'}, cap is ${opts.capWei.toString()} wei (signer ${opts.signerAddress})`);
+        this.name = 'SpendCapExceededError';
+        this.capWei = opts.capWei;
+        this.requestedValue = opts.requestedValue;
+        this.to = opts.to;
+        this.signerAddress = opts.signerAddress;
+    }
+}
+function readTxValue(tx) {
+    // viem accepts bigint (canonical), number, string. Normalise to bigint;
+    // undefined / null → 0n.
+    const v = tx.value;
+    if (v === undefined || v === null)
+        return 0n;
+    if (typeof v === 'bigint')
+        return v;
+    if (typeof v === 'number')
+        return BigInt(v);
+    if (typeof v === 'string')
+        return BigInt(v);
+    // Defensive: any other shape is treated as "we don't know, fail closed
+    // by reporting as MAX_UINT256". A signer that can't reason about value
+    // shouldn't be allowed to send arbitrary amounts.
+    return (1n << 256n) - 1n;
+}
+async function emitCapReject(auditSink, opts) {
+    if (!auditSink)
+        return;
+    try {
+        await auditSink.write(buildEvent({
+            action: 'key-custody.relay.spend-cap.reject',
+            outcome: 'denied',
+            actor: { type: 'system', id: opts.signerAddress },
+            subject: { type: 'transaction', id: opts.to ?? '<no-target>' },
+            context: {
+                signerAddress: opts.signerAddress,
+                to: opts.to,
+                capWei: opts.capWei.toString(),
+                requestedValue: opts.requestedValue.toString(),
+            },
+        }));
+    }
+    catch {
+        // Fail-soft: a sink outage does not affect the rejection itself
+        // (the throw still happens; the audit row is just missing).
+    }
+}
+/**
+ * Wrap any viem {@link LocalAccount} with a per-transaction ETH-value
+ * cap. The cap is enforced BEFORE signing: a `signTransaction` call
+ * with `value > capWei` throws {@link SpendCapExceededError} and the
+ * HSM / KMS never sees the digest.
+ *
+ * `signMessage` and `signTypedData` are forwarded verbatim — they
+ * don't carry an on-chain ETH value, so the cap doesn't apply.
+ *
+ * Composes with `createRelayerAccount`: wrap the relayer with the
+ * cap to get role-tagged audit emission AND a per-tx spend limit.
+ *
+ * Synchronous factory — the wrapper holds no async state. The inner
+ * account must already be resolved (it carries the address).
+ *
+ * @example
+ * ```ts
+ * const inner = await createRelayerAccount(backend, {
+ *   role: 'paymaster-topup',
+ *   auditSink,
+ * });
+ * const capped = createSpendCappedAccount(inner, {
+ *   capWei: 10n ** 17n, // 0.1 ETH
+ *   auditSink,
+ * });
+ * await walletClient.sendTransaction({ account: capped, to, value: 5n * 10n ** 16n }); // 0.05 ETH — OK
+ * await walletClient.sendTransaction({ account: capped, to, value: 10n ** 18n });      // throws SpendCapExceededError
+ * ```
+ */
+export function createSpendCappedAccount(inner, opts) {
+    if (opts.capWei < 0n) {
+        throw new Error(`[key-custody] createSpendCappedAccount: capWei must be >= 0; got ${opts.capWei.toString()}`);
+    }
+    const { capWei, auditSink } = opts;
+    return {
+        address: inner.address,
+        type: 'local',
+        source: 'kms-spend-capped',
+        publicKey: inner.publicKey,
+        async signMessage({ message }) {
+            // Messages carry no on-chain value; forward verbatim.
+            return inner.signMessage({ message });
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async signTransaction(transaction, options) {
+            const requestedValue = readTxValue(transaction);
+            if (requestedValue > capWei) {
+                const to = transaction.to ?? null;
+                await emitCapReject(auditSink, {
+                    capWei,
+                    requestedValue,
+                    to,
+                    signerAddress: inner.address,
+                });
+                throw new SpendCapExceededError({
+                    capWei,
+                    requestedValue,
+                    to,
+                    signerAddress: inner.address,
+                });
+            }
+            // Under or at cap → delegate. (At-cap is intentionally permitted;
+            // `cap == requested` is the boundary, not a violation.)
+            return inner.signTransaction(transaction, options);
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async signTypedData(args) {
+            // Typed data carries no on-chain value; forward verbatim.
+            return inner.signTypedData(args);
+        },
+    };
+}
+//# sourceMappingURL=spend-capped-account.js.map

package/dist/spend-capped-account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-capped-account.js","sourceRoot":"","sources":["../src/spend-capped-account.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/key-custody",
-  "version": "0.1.0-alpha.2",
+  "version": "1.0.0-alpha.10",
   "description": "Pluggable envelope encryption + signers + HMAC providers (local-AES / AWS KMS / GCP KMS). Pure crypto primitives; no session lifecycle (that's in delegation).",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "ap-provision-gcp": "./bin/ap-provision-gcp.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -32,6 +35,14 @@
       "types": "./dist/providers/gcp.d.ts",
       "import": "./dist/providers/gcp.js"
     },
+    "./kms-core": {
+      "types": "./dist/kms/kms-core.d.ts",
+      "import": "./dist/kms/kms-core.js"
+    },
+    "./provision-gcp": {
+      "types": "./dist/kms/provision-gcp.d.ts",
+      "import": "./dist/kms/provision-gcp.js"
+    },
     "./mac": {
       "types": "./dist/mac.d.ts",
       "import": "./dist/mac.js"
@@ -39,38 +50,49 @@
     "./kms-viem": {
       "types": "./dist/kms-viem-account.d.ts",
       "import": "./dist/kms-viem-account.js"
+    },
+    "./relayer": {
+      "types": "./dist/relayer-account.d.ts",
+      "import": "./dist/relayer-account.js"
+    },
+    "./spend-cap": {
+      "types": "./dist/spend-capped-account.d.ts",
+      "import": "./dist/spend-capped-account.js"
     }
   },
   "files": [
     "LICENSE",
+    "bin",
     "dist",
     "spec.md",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:unit": "vitest run test/unit",
-    "test:integration": "vitest run test/integration --passWithNoTests",
-    "test:watch": "vitest",
-    "clean": "rm -rf dist"
-  },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@noble/curves": "^1.6.0",
-    "@noble/hashes": "^1.5.0"
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0"
   },
   "peerDependencies": {
-    "@agenticprimitives/audit": "workspace:*",
-    "@agenticprimitives/connect-auth": "workspace:*",
-    "@agenticprimitives/types": "workspace:*",
-    "viem": "^2.50.0"
+    "viem": "^2.52.2",
+    "@agenticprimitives/audit": "1.0.0-alpha.10",
+    "@agenticprimitives/types": "1.0.0-alpha.10",
+    "@agenticprimitives/connect-auth": "1.0.0-alpha.10"
+  },
+  "peerDependenciesMeta": {
+    "@agenticprimitives/audit": {
+      "optional": true
+    },
+    "@agenticprimitives/connect-auth": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "vitest": "^2.1.0"
+    "vitest": "^4.1.8"
   },
   "keywords": [
     "kms",
@@ -80,5 +102,14 @@
     "secp256k1",
     "hmac",
     "agentic"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit --passWithNoTests",
+    "test:integration": "vitest run test/integration --passWithNoTests",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}