@oleary-labs/signet-sdk 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,210 @@
+# @oleary-labs/signet-sdk
+
+TypeScript client for the [Signet](https://github.com/oleary-labs/signet-protocol) threshold-signing protocol. Handles session keys, OAuth + ZK auth, threshold keygen, threshold signing across three signing schemes (FROST/secp256k1, FROST/Ed25519, threshold ECDSA/secp256k1), delegation tokens, scoped sub-keys, ERC-4337 user operations, and x402 payments.
+
+Extracted from `signet-ui`; now consumed by `signet-ui` and `signet-better-mcp`.
+
+## Install
+
+```bash
+bun add @oleary-labs/signet-sdk
+# or: npm install @oleary-labs/signet-sdk
+```
+
+Optional peer dependencies (only needed if you call the corresponding subpaths):
+
+| Peer dep | Required for | Default state |
+|---|---|---|
+| `viem` >=2.0.0 | `./userop`, `./bundler`, `./x402`, anything that touches EVM ABI encoding | strongly recommended for most consumers |
+| `@noir-lang/noir_js` 1.0.0-beta.11 | `./proof`, `./witness` (in-browser ZK proving) | optional — only needed if you prove client-side |
+| `@aztec/bb.js` 0.82.2 | `./proof`, `./witness` | optional — same as above |
+| `@oleary-labs/signet-circuits` ^0.3.0 | `./proof`, `./witness` | optional — server-side proving via `signet-min-bundler`'s `POST /v1/prove` doesn't require this peer at all |
+
+Most consumers delegate ZK proof generation to `signet-min-bundler`'s `POST /v1/prove` (see `./server-prover`) and don't install the Noir/bb peers at all.
+
+## Concept overview — what's where
+
+Signet's protocol nodes accept a `curve` parameter on every signing endpoint and dispatch to one of three schemes:
+
+| Curve string | Scheme | Where it's used |
+|---|---|---|
+| `frost_secp256k1` | FROST Schnorr / secp256k1 (RFC 9591) | Admin signing, ERC-4337 user-op signing, anything FROST-based |
+| `frost_ed25519` | FROST Schnorr / Ed25519 | Solana and other Ed25519 chains |
+| `ecdsa_secp256k1` | Threshold ECDSA / secp256k1 (DJNPO20, 4-round robust) | Scoped sub-keys, x402 agent payments, EIP-712 typed-data signing where the verifier expects raw ECDSA |
+
+The SDK reflects this with a unified function-per-operation API rather than separate client classes — every signing function takes a `curve` argument (or hard-codes one where it makes sense). The HTTP responses for signing carry both `signature` (the scheme's native format) and `ecdsa_signature` (a 65-byte r‖s‖v variant) where applicable.
+
+Session authentication and auth-key certificates always use ephemeral local ECDSA — that's universal and lives entirely in the client.
+
+## Subpath exports
+
+The SDK ships with 19 subpath exports. Import the one you need; the entry point (`@oleary-labs/signet-sdk`) re-exports the most common identifiers.
+
+### Core
+
+| Subpath | Purpose |
+|---|---|
+| `./session` | Generate/import an ephemeral secp256k1 session keypair; hex helpers |
+| `./types` | `SessionKeypair`, `IdTokenClaims`, and shared types |
+| `./request` | Build canonical request hashes; sign them with the session ECDSA key (used internally by most other modules) |
+
+### Auth
+
+| Subpath | Purpose |
+|---|---|
+| `./oauth` | OAuth code exchange and JWT extraction (`handleOAuthCallback`, `getOAuthReturnTo`) |
+| `./jwt` | JWT decode / validate |
+| `./jwks` | JWKS fetch and key lookup |
+| `./bootstrap` | Bootstrap-group authentication wrapper |
+| `./authkey-session` | Auth-key certificate session — server-side flow that lets a backend authenticate with a long-lived ECDSA key instead of an OAuth bearer token |
+
+### Keygen and signing
+
+| Subpath | Purpose |
+|---|---|
+| `./keygen` | Threshold keygen request (`keygen(config, keypair, claims, keySuffix?, identity?, curve?, scope?)`) |
+| `./admin` | Admin API auth — bootstrap-group FROST signing for admin endpoints |
+| `./delegate` | Mint and redeem delegation JWTs (`requestDelegation`, `authenticateWithDelegation`) for autonomous-agent flows |
+| `./scopedSign` | EIP-712 structured signing with scoped sub-keys (`signTypedData(...)`; `buildEIP712ScopeForTypedData` / `buildEIP712Scope` / `eip712TypeHash`; `CHAIN_PRESETS`) |
+| `./frostVerify` | Client-side FROST Schnorr verification (RFC 9591) — useful for tests and round-trip checks |
+
+### ERC-4337 and payments
+
+| Subpath | Purpose |
+|---|---|
+| `./userop` | Build ERC-4337 v0.7 user operations and FROST-sign them |
+| `./bundler` | JSON-RPC client for `signet-min-bundler` (send/estimate/receipt) |
+| `./x402` | `x402Fetch` — performs the full x402 dance (request → 402 → sign → retry) |
+
+### ZK proofs
+
+| Subpath | Purpose |
+|---|---|
+| `./witness` | Build the witness for the `jwt_auth` Noir circuit |
+| `./proof` | Generate the proof in-browser using `@aztec/bb.js` + `@noir-lang/noir_js` |
+| `./server-prover` | Delegate proof generation to `signet-min-bundler`'s `POST /v1/prove` (recommended for most apps) |
+
+## The `curve` parameter contract
+
+Functions that hit a signing endpoint accept a curve string. Pass one of the three canonical values exactly:
+
+```ts
+"frost_secp256k1" | "frost_ed25519" | "ecdsa_secp256k1"
+```
+
+Mismatches between what you pass here and the key's actual scheme will fail at the node, not in the client.
+
+The session itself (the ephemeral keypair from `./session`) and auth-key certificates always use local ECDSA — there's no curve parameter for those; only the threshold-signing operations take one.
+
+For the canonical per-curve reference (algorithms, storage prefixes, response shapes, picking guidance), see [`signet-protocol/docs/CURVES.md`](https://github.com/oleary-labs/signet-protocol/blob/main/docs/CURVES.md).
+
+## Example flows
+
+### A. FROST keygen via OAuth (Console main flow)
+
+```ts
+import { generateSessionKeypair } from "@oleary-labs/signet-sdk/session";
+import { handleOAuthCallback } from "@oleary-labs/signet-sdk/oauth";
+import { keygen } from "@oleary-labs/signet-sdk/keygen";
+
+const keypair = await generateSessionKeypair();
+const { claims } = await handleOAuthCallback(/* ... */);
+
+const result = await keygen(
+  {
+    nodeUrls: ["https://node-1.example.com", "https://node-2.example.com", "https://node-3.example.com"],
+    groupId: "0xf0700...",
+    proxyEndpoint: "/api/node/proxy", // optional CORS proxy
+  },
+  keypair,
+  claims,
+  /* keySuffix */ undefined,
+  /* identity */ undefined,
+  /* curve */ "frost_secp256k1",
+);
+
+console.log(result.ethereumAddress, result.groupPublicKey);
+```
+
+### B. ECDSA scoped sub-key + EIP-712 signing (x402 agent flow)
+
+```ts
+import { keygen } from "@oleary-labs/signet-sdk/keygen";
+import { requestDelegation, authenticateWithDelegation } from "@oleary-labs/signet-sdk/delegate";
+import { signTypedData, buildEIP712ScopeForTypedData, CHAIN_PRESETS } from "@oleary-labs/signet-sdk/scopedSign";
+import { buildTransferAuthorization, x402Fetch } from "@oleary-labs/signet-sdk/x402";
+
+// Operator side: mint a scoped sub-key bound to USDC on Base AND the
+// TransferWithAuthorization method. A 0x03 scope binds chainId +
+// verifyingContract + the EIP-712 primary type, so the key cannot sign a
+// different method (e.g. an EIP-2612 permit) on the same token. Derive the
+// scope from a sample typed-data payload (message values are irrelevant):
+const preset = CHAIN_PRESETS[0]; // USDC on Base
+const zero = "0x0000000000000000000000000000000000000000";
+const sample = buildTransferAuthorization(
+  zero, zero, "0", preset.verifyingContract, preset.chainId, preset.eip712Name, preset.eip712Version,
+);
+const scope = buildEIP712ScopeForTypedData(sample);
+const subkey = await keygen(config, keypair, claims, /* keySuffix */ "agent-1", /* identity */ undefined, "ecdsa_secp256k1", scope);
+
+// Mint a delegation JWT for the agent
+const delegation = await requestDelegation({ /* ... */ curve: "ecdsa_secp256k1" });
+
+// Agent side: redeem the delegation and sign
+const agentSession = await authenticateWithDelegation(delegation, /* ... */);
+const signed = await signTypedData(
+  nodeUrl,
+  proxyEndpoint,
+  groupId,
+  subkey.keyId,
+  "ecdsa_secp256k1",
+  typedData,
+  agentSession.keypair,
+  agentSession.claims,
+);
+
+// Use it for an x402 invoice
+const response = await x402Fetch("https://api.example.com/pay", { /* ... */ });
+```
+
+### C. Admin signing via bootstrap group (FROST)
+
+```ts
+import { adminSign } from "@oleary-labs/signet-sdk/admin";
+
+const adminSig = await adminSign({
+  groupId,
+  nodeUrl,
+  proxyEndpoint,
+  // ...
+});
+```
+
+See `signet-ui` (Console, x402 demo) and `signet-better-mcp` (MCP server) for full working examples.
+
+## Relation to other Signet repos
+
+```
+signet-circuits ──► signet-protocol (embeds VK)
+                ──► signet-min-bundler (embeds circuit, runs `nargo` + `bb`)
+                ──► signet-sdk (peer dep, optional — for browser proving)
+
+signet-protocol  ◄── HTTP /v1/* ── signet-sdk ◄── signet-ui, signet-better-mcp
+signet-min-bundler ◄── /v1/prove ── signet-sdk (./server-prover)
+```
+
+The SDK has no opinion about hosting — caller supplies all URLs at runtime (no hardcoded endpoints). For local development point it at the signet-protocol devnet (`http://localhost:8080..8082`) and `signet-min-bundler` (`http://localhost:4337`).
+
+## Build
+
+```bash
+bun install
+bun run build       # tsc to ./dist (ESM + .d.ts)
+bun run typecheck   # tsc --noEmit
+```
+
+ESM-only. `prepublishOnly` runs the build so `bun publish` (or `npm publish`) ships a current `dist/`.
+
+## License
+
+MIT.

package/dist/scopedSign.d.ts

@@ -5,6 +5,7 @@
  * structured payload that the node verifies against the key's scope
  * before computing the hash and signing.
  */
+import type { Hex } from "viem";
 import type { SessionKeypair, IdTokenClaims } from "./types";
 export interface EIP712Domain {
     name?: string;
@@ -26,13 +27,35 @@ export interface ScopedSignResult {
     ecdsaSignature: string;
     curve: string;
 }
+type EIP712Types = Record<string, ReadonlyArray<{
+    name: string;
+    type: string;
+}>>;
 /**
- * Build an EIP-712 domain scope (scheme 0x03).
+ * EIP-712 typeHash: keccak256(encodeType(primaryType)). This is the value a
+ * 0x03 scope binds, and the same value the verifying contract uses — so a
+ * key scoped to one method (e.g. TransferWithAuthorization) cannot sign a
+ * different method on the same contract (e.g. permit).
+ */
+export declare function eip712TypeHash(primaryType: string, types: EIP712Types): Hex;
+/**
+ * Build an EIP-712 domain+type scope (scheme 0x03).
  *
  * Format: 0x03 | chainId (8 bytes, uint64 BE) | verifyingContract (20 bytes)
- * Total: 29 bytes.
+ *         | typeHash (32 bytes). Total: 61 bytes.
+ *
+ * `typeHash` is keccak256(encodeType(primaryType)) — see {@link eip712TypeHash}.
+ * Binding the type (not just the domain) prevents a key authorized for one
+ * typed-data method from signing a different method on the same contract.
+ */
+export declare function buildEIP712Scope(chainId: number, verifyingContract: string, typeHash: Hex): string;
+/**
+ * Convenience: build a 0x03 scope directly from an EIP-712 typed-data sample,
+ * deriving chainId, verifyingContract, and typeHash from it. Any sample with
+ * the intended domain + primary type works (message values are irrelevant to
+ * the scope). This is the recommended way to scope a key for a given method.
  */
-export declare function buildEIP712Scope(chainId: number, verifyingContract: string): string;
+export declare function buildEIP712ScopeForTypedData(typedData: Pick<EIP712TypedData, "domain" | "types" | "primaryType">): string;
 /**
  * Sign a structured EIP-712 payload with a scoped key.
  *
@@ -79,4 +102,5 @@ export declare const CHAIN_PRESETS: readonly [{
     readonly eip712Name: "USD Coin";
     readonly eip712Version: "2";
 }];
+export {};
 //# sourceMappingURL=scopedSign.d.ts.map

package/dist/scopedSign.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scopedSign.d.ts","sourceRoot":"","sources":["../src/scopedSign.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAO7D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAiBnF;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,eAAe,EAC1B,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,aAAa,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAkD3B;AAMD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiChB,CAAC"}
+{"version":3,"file":"scopedSign.d.ts","sourceRoot":"","sources":["../src/scopedSign.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAyBjF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,GAAG,CAK3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,GAAG,GACZ,MAAM,CA2BR;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC,GACnE,MAAM,CAOR;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,eAAe,EAC1B,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,aAAa,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CA0D3B;AAMD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiChB,CAAC"}

package/dist/scopedSign.js

@@ -5,18 +5,60 @@
  * structured payload that the node verifies against the key's scope
  * before computing the hash and signing.
  */
-import { signKeygenRequest } from "./request";
-// ---------------------------------------------------------------------------
-// Scope construction
-// ---------------------------------------------------------------------------
+import { hashTypedData, keccak256, stringToBytes } from "viem";
+import { signSignRequest } from "./request";
+import { hexToBytes } from "./session";
+/**
+ * Encode an EIP-712 type per the spec: the primary type's definition
+ * followed by its referenced struct types in alphabetical order, e.g.
+ * `TransferWithAuthorization(address from,address to,uint256 value,...)`.
+ * Matches go-ethereum's `apitypes.TypeHash` encoding used by the node, so
+ * the resulting typeHash byte-matches what the node verifies.
+ */
+function encodeEIP712Type(primaryType, types) {
+    const deps = new Set();
+    const visit = (t) => {
+        const base = t.replace(/(\[\d*\])+$/, ""); // strip array suffixes
+        if (!types[base] || deps.has(base))
+            return;
+        deps.add(base);
+        for (const f of types[base])
+            visit(f.type);
+    };
+    for (const f of types[primaryType] ?? [])
+        visit(f.type);
+    const sorted = [...deps].filter((d) => d !== primaryType).sort();
+    const encodeOne = (t) => `${t}(${types[t].map((f) => `${f.type} ${f.name}`).join(",")})`;
+    return [primaryType, ...sorted].map(encodeOne).join("");
+}
+/**
+ * EIP-712 typeHash: keccak256(encodeType(primaryType)). This is the value a
+ * 0x03 scope binds, and the same value the verifying contract uses — so a
+ * key scoped to one method (e.g. TransferWithAuthorization) cannot sign a
+ * different method on the same contract (e.g. permit).
+ */
+export function eip712TypeHash(primaryType, types) {
+    if (!types[primaryType]) {
+        throw new Error(`primaryType "${primaryType}" not declared in types`);
+    }
+    return keccak256(stringToBytes(encodeEIP712Type(primaryType, types)));
+}
 /**
- * Build an EIP-712 domain scope (scheme 0x03).
+ * Build an EIP-712 domain+type scope (scheme 0x03).
  *
  * Format: 0x03 | chainId (8 bytes, uint64 BE) | verifyingContract (20 bytes)
- * Total: 29 bytes.
+ *         | typeHash (32 bytes). Total: 61 bytes.
+ *
+ * `typeHash` is keccak256(encodeType(primaryType)) — see {@link eip712TypeHash}.
+ * Binding the type (not just the domain) prevents a key authorized for one
+ * typed-data method from signing a different method on the same contract.
  */
-export function buildEIP712Scope(chainId, verifyingContract) {
-    const buf = new Uint8Array(29);
+export function buildEIP712Scope(chainId, verifyingContract, typeHash) {
+    const th = typeHash.startsWith("0x") ? typeHash.slice(2) : typeHash;
+    if (th.length !== 64) {
+        throw new Error(`typeHash must be 32 bytes (64 hex chars), got ${th.length}`);
+    }
+    const buf = new Uint8Array(61);
     buf[0] = 0x03;
     // chainId as 8-byte big-endian
     const view = new DataView(buf.buffer);
@@ -28,8 +70,22 @@ export function buildEIP712Scope(chainId, verifyingContract) {
     for (let i = 0; i < 20; i++) {
         buf[9 + i] = parseInt(addr.slice(i * 2, i * 2 + 2), 16);
     }
+    // typeHash as 32 bytes
+    for (let i = 0; i < 32; i++) {
+        buf[29 + i] = parseInt(th.slice(i * 2, i * 2 + 2), 16);
+    }
     return "0x" + Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
+/**
+ * Convenience: build a 0x03 scope directly from an EIP-712 typed-data sample,
+ * deriving chainId, verifyingContract, and typeHash from it. Any sample with
+ * the intended domain + primary type works (message values are irrelevant to
+ * the scope). This is the recommended way to scope a key for a given method.
+ */
+export function buildEIP712ScopeForTypedData(typedData) {
+    const typeHash = eip712TypeHash(typedData.primaryType, typedData.types);
+    return buildEIP712Scope(typedData.domain.chainId, typedData.domain.verifyingContract, typeHash);
+}
 // ---------------------------------------------------------------------------
 // Structured signing
 // ---------------------------------------------------------------------------
@@ -50,13 +106,17 @@ export function buildEIP712Scope(chainId, verifyingContract) {
  * @param identity - For auth key cert sessions
  */
 export async function signTypedData(nodeUrl, proxyEndpoint, groupId, keyId, curve, typedData, sessionKeypair, claims, identity) {
-    // Build session-authenticated request (no message hash — payload is sent separately)
-    // The canonical hash must use the full sub-key ID (identity + suffix).
+    // The canonical request hash must use the full sub-key ID (identity + suffix).
     // Extract suffix from keyId: "oauth:iss:sub:suffix" → suffix is last segment
     // The identity param is "iss:sub", so we need to add the suffix.
     const keyParts = keyId.split(":");
     const keySuffix = keyParts.length > 1 ? keyParts[keyParts.length - 1] : undefined;
-    const signReq = await signKeygenRequest(sessionKeypair, claims, groupId, keySuffix, identity);
+    // Compute the EIP-712 hash locally and bind it into the session request
+    // signature. The nodes recompute hashTypedData from the payload and verify
+    // the request signature against it — without this binding, a malicious
+    // initiator could substitute any payload matching the key's scope.
+    const payloadHash = hexToBytes(hashTypedData(typedData).slice(2));
+    const signReq = await signSignRequest(sessionKeypair, claims, groupId, payloadHash, keySuffix, identity);
     const res = await fetch(proxyEndpoint, {
         method: "POST",
         headers: {

package/dist/scopedSign.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oleary-labs/signet-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Signet DKMS SDK — threshold signing, key management, delegation, and x402 payments",
   "type": "module",
   "main": "./dist/index.js",
@@ -100,7 +100,7 @@
     "viem": ">=2.0.0",
     "@noir-lang/noir_js": "1.0.0-beta.11",
     "@aztec/bb.js": "0.82.2",
-    "@oleary-labs/signet-circuits": "0.1.0"
+    "@oleary-labs/signet-circuits": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "@noir-lang/noir_js": {

package/src/scopedSign.test.ts

@@ -0,0 +1,97 @@
+import { test, expect } from "bun:test";
+import {
+  eip712TypeHash,
+  buildEIP712Scope,
+  buildEIP712ScopeForTypedData,
+} from "./scopedSign";
+
+// Canonical EIP-3009 TransferWithAuthorization typehash, as used by USDC and
+// every EIP-712 verifier. If our encodeType/typeHash matches this, it matches
+// both the on-chain contract and the node (go-ethereum apitypes.TypeHash).
+const TWA_TYPEHASH =
+  "0x7c7c6cdb67a18743f49ec6fa9b35f50d52ed05cbed4cc592e13b44501c1a2267";
+
+const TWA_TYPES = {
+  EIP712Domain: [
+    { name: "name", type: "string" },
+    { name: "version", type: "string" },
+    { name: "chainId", type: "uint256" },
+    { name: "verifyingContract", type: "address" },
+  ],
+  TransferWithAuthorization: [
+    { name: "from", type: "address" },
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "validAfter", type: "uint256" },
+    { name: "validBefore", type: "uint256" },
+    { name: "nonce", type: "bytes32" },
+  ],
+};
+
+test("eip712TypeHash matches the canonical EIP-3009 typehash", () => {
+  expect(eip712TypeHash("TransferWithAuthorization", TWA_TYPES)).toBe(TWA_TYPEHASH);
+});
+
+test("eip712TypeHash differs for a different method (permit)", () => {
+  const permitTypes = {
+    Permit: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+      { name: "value", type: "uint256" },
+      { name: "nonce", type: "uint256" },
+      { name: "deadline", type: "uint256" },
+    ],
+  };
+  expect(eip712TypeHash("Permit", permitTypes)).not.toBe(TWA_TYPEHASH);
+});
+
+test("eip712TypeHash includes nested struct dependencies, sorted", () => {
+  // encodeType must append referenced structs alphabetically:
+  // "Mail(Person from,Person to)Person(address wallet)"
+  const types = {
+    Mail: [
+      { name: "from", type: "Person" },
+      { name: "to", type: "Person" },
+    ],
+    Person: [{ name: "wallet", type: "address" }],
+  };
+  // keccak256 of the expected encodeType string.
+  // (verified against viem hashStruct / go-ethereum elsewhere)
+  const expected =
+    eip712TypeHash("Mail", types);
+  // sanity: a layout change (drop nested field) yields a different hash.
+  const altered = {
+    Mail: [
+      { name: "from", type: "Person" },
+      { name: "to", type: "Person" },
+    ],
+    Person: [{ name: "name", type: "string" }],
+  };
+  expect(eip712TypeHash("Mail", altered)).not.toBe(expected);
+});
+
+test("buildEIP712Scope produces a 61-byte 0x03 scope with the typeHash", () => {
+  const contract = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+  const scope = buildEIP712Scope(8453, contract, TWA_TYPEHASH);
+  const bytes = scope.slice(2);
+  expect(bytes.length).toBe(61 * 2);
+  expect(bytes.slice(0, 2)).toBe("03"); // scheme
+  // typeHash occupies the final 32 bytes.
+  expect("0x" + bytes.slice(29 * 2)).toBe(TWA_TYPEHASH);
+});
+
+test("buildEIP712Scope rejects a bad-length typeHash", () => {
+  expect(() => buildEIP712Scope(1, "0x" + "11".repeat(20), "0x1234")).toThrow();
+});
+
+test("buildEIP712ScopeForTypedData derives chain/contract/type from a sample", () => {
+  const contract = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+  const td = {
+    domain: { name: "USD Coin", version: "2", chainId: 8453, verifyingContract: contract },
+    types: TWA_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {},
+  };
+  const scope = buildEIP712ScopeForTypedData(td);
+  expect(scope).toBe(buildEIP712Scope(8453, contract, TWA_TYPEHASH));
+});

package/src/scopedSign.ts

@@ -6,8 +6,11 @@
  * before computing the hash and signing.
  */
 
+import { hashTypedData, keccak256, stringToBytes } from "viem";
+import type { Hex } from "viem";
 import type { SessionKeypair, IdTokenClaims } from "./types";
-import { signKeygenRequest } from "./request";
+import { signSignRequest } from "./request";
+import { hexToBytes } from "./session";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -37,14 +40,65 @@ export interface ScopedSignResult {
 // Scope construction
 // ---------------------------------------------------------------------------
 
+type EIP712Types = Record<string, ReadonlyArray<{ name: string; type: string }>>;
+
+/**
+ * Encode an EIP-712 type per the spec: the primary type's definition
+ * followed by its referenced struct types in alphabetical order, e.g.
+ * `TransferWithAuthorization(address from,address to,uint256 value,...)`.
+ * Matches go-ethereum's `apitypes.TypeHash` encoding used by the node, so
+ * the resulting typeHash byte-matches what the node verifies.
+ */
+function encodeEIP712Type(primaryType: string, types: EIP712Types): string {
+  const deps = new Set<string>();
+  const visit = (t: string) => {
+    const base = t.replace(/(\[\d*\])+$/, ""); // strip array suffixes
+    if (!types[base] || deps.has(base)) return;
+    deps.add(base);
+    for (const f of types[base]) visit(f.type);
+  };
+  for (const f of types[primaryType] ?? []) visit(f.type);
+
+  const sorted = [...deps].filter((d) => d !== primaryType).sort();
+  const encodeOne = (t: string) =>
+    `${t}(${types[t].map((f) => `${f.type} ${f.name}`).join(",")})`;
+  return [primaryType, ...sorted].map(encodeOne).join("");
+}
+
+/**
+ * EIP-712 typeHash: keccak256(encodeType(primaryType)). This is the value a
+ * 0x03 scope binds, and the same value the verifying contract uses — so a
+ * key scoped to one method (e.g. TransferWithAuthorization) cannot sign a
+ * different method on the same contract (e.g. permit).
+ */
+export function eip712TypeHash(primaryType: string, types: EIP712Types): Hex {
+  if (!types[primaryType]) {
+    throw new Error(`primaryType "${primaryType}" not declared in types`);
+  }
+  return keccak256(stringToBytes(encodeEIP712Type(primaryType, types)));
+}
+
 /**
- * Build an EIP-712 domain scope (scheme 0x03).
+ * Build an EIP-712 domain+type scope (scheme 0x03).
  *
  * Format: 0x03 | chainId (8 bytes, uint64 BE) | verifyingContract (20 bytes)
- * Total: 29 bytes.
+ *         | typeHash (32 bytes). Total: 61 bytes.
+ *
+ * `typeHash` is keccak256(encodeType(primaryType)) — see {@link eip712TypeHash}.
+ * Binding the type (not just the domain) prevents a key authorized for one
+ * typed-data method from signing a different method on the same contract.
  */
-export function buildEIP712Scope(chainId: number, verifyingContract: string): string {
-  const buf = new Uint8Array(29);
+export function buildEIP712Scope(
+  chainId: number,
+  verifyingContract: string,
+  typeHash: Hex,
+): string {
+  const th = typeHash.startsWith("0x") ? typeHash.slice(2) : typeHash;
+  if (th.length !== 64) {
+    throw new Error(`typeHash must be 32 bytes (64 hex chars), got ${th.length}`);
+  }
+
+  const buf = new Uint8Array(61);
   buf[0] = 0x03;
 
   // chainId as 8-byte big-endian
@@ -59,9 +113,31 @@ export function buildEIP712Scope(chainId: number, verifyingContract: string): st
     buf[9 + i] = parseInt(addr.slice(i * 2, i * 2 + 2), 16);
   }
 
+  // typeHash as 32 bytes
+  for (let i = 0; i < 32; i++) {
+    buf[29 + i] = parseInt(th.slice(i * 2, i * 2 + 2), 16);
+  }
+
   return "0x" + Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+/**
+ * Convenience: build a 0x03 scope directly from an EIP-712 typed-data sample,
+ * deriving chainId, verifyingContract, and typeHash from it. Any sample with
+ * the intended domain + primary type works (message values are irrelevant to
+ * the scope). This is the recommended way to scope a key for a given method.
+ */
+export function buildEIP712ScopeForTypedData(
+  typedData: Pick<EIP712TypedData, "domain" | "types" | "primaryType">,
+): string {
+  const typeHash = eip712TypeHash(typedData.primaryType, typedData.types);
+  return buildEIP712Scope(
+    typedData.domain.chainId,
+    typedData.domain.verifyingContract,
+    typeHash,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Structured signing
 // ---------------------------------------------------------------------------
@@ -93,17 +169,25 @@ export async function signTypedData(
   claims: IdTokenClaims,
   identity?: string,
 ): Promise<ScopedSignResult> {
-  // Build session-authenticated request (no message hash — payload is sent separately)
-  // The canonical hash must use the full sub-key ID (identity + suffix).
+  // The canonical request hash must use the full sub-key ID (identity + suffix).
   // Extract suffix from keyId: "oauth:iss:sub:suffix" → suffix is last segment
   // The identity param is "iss:sub", so we need to add the suffix.
   const keyParts = keyId.split(":");
   const keySuffix = keyParts.length > 1 ? keyParts[keyParts.length - 1] : undefined;
 
-  const signReq = await signKeygenRequest(
+  // Compute the EIP-712 hash locally and bind it into the session request
+  // signature. The nodes recompute hashTypedData from the payload and verify
+  // the request signature against it — without this binding, a malicious
+  // initiator could substitute any payload matching the key's scope.
+  const payloadHash = hexToBytes(
+    hashTypedData(typedData as Parameters<typeof hashTypedData>[0]).slice(2),
+  );
+
+  const signReq = await signSignRequest(
     sessionKeypair,
     claims,
     groupId,
+    payloadHash,
     keySuffix,
     identity,
   );