@agenticprimitives/connect-auth 0.1.0-alpha.2

package/dist/verify-signature.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Universal signature verification for app servers.
+ *
+ * Consumers (e.g. demo-a2a's `/auth/siwe-verify`) call `verifyUserSignature`
+ * with `{ signer, hash, signature, universalValidator, publicClient }` and
+ * get back a single boolean — they do NOT branch on signer method (EOA,
+ * passkey, etc.). The on-chain `UniversalSignatureValidator` contract
+ * dispatches: ECDSA for code-less signers, ERC-1271 for deployed smart
+ * accounts, ERC-6492 for counterfactual smart accounts (deploys via
+ * factoryCalldata embedded in the signature, then ERC-1271).
+ *
+ * Doctrine — see [[feedback-demo-a2a-is-signer-agnostic]] memory and
+ * spec 130 §7: connect-auth ships the verifier helper; demo-a2a calls
+ * it; passkey internals stay out of demo-a2a entirely.
+ *
+ * Two modes:
+ *   - `verifyUserSignature` (state-changing): calls `isValidSig` on the
+ *     validator. The 6492 path may DEPLOY the user's smart account
+ *     before verifying. Suitable for relayer pre-flight where the
+ *     submitter is OK paying for deploy gas if verification succeeds.
+ *   - `verifyUserSignatureView` (read-only): calls `isValidSigView`. 6492
+ *     wrappers without already-deployed accounts will return false.
+ *     Suitable for cheap pre-checks.
+ *
+ * The function signature intentionally takes the validator address as a
+ * parameter — connect-auth is transport- and deployment-agnostic; the
+ * caller wires in the deployed contract address from its config.
+ */
+import type { Address, Hex } from './types';
+/** ERC-1271 magic value. */
+export declare const ERC1271_MAGIC: Hex;
+/** ERC-6492 32-byte magic suffix (`0x6492…6492` repeated). */
+export declare const ERC6492_MAGIC: Hex;
+/**
+ * Minimal viem-like public-client shape — accepts any client with
+ * `readContract` (view-only) and `simulateContract` (state-changing
+ * dry-run) supporting the universal-validator ABI. Kept loose so this
+ * works with viem, ethers-via-shim, or test mocks.
+ */
+export interface UniversalValidatorClient {
+    readContract(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: 'isValidSigView';
+        args: readonly [Address, Hex, Hex];
+    }): Promise<boolean>;
+    simulateContract?(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: 'isValidSig';
+        args: readonly [Address, Hex, Hex];
+    }): Promise<{
+        result: boolean;
+    }>;
+}
+export declare const universalSignatureValidatorAbi: readonly [{
+    readonly type: "function";
+    readonly name: "isValidSig";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "hash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "sig";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isValidSigView";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "hash";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "sig";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}];
+export interface VerifyUserSignatureArgs {
+    /** The on-chain UniversalSignatureValidator contract address. */
+    universalValidator: Address;
+    /** The claimed signer — for passkey-owned accounts, this is the
+     *  smart-account address derived from the passkey's pubkey. */
+    signer: Address;
+    /** The 32-byte digest the user signed. */
+    hash: Hex;
+    /** The signature blob — EOA 65-byte sig, ERC-1271 1271-compliant blob,
+     *  or ERC-6492-wrapped counterfactual blob. */
+    signature: Hex;
+    client: UniversalValidatorClient;
+}
+/**
+ * Result of a signature verify call. H7-B.3 (PKG-CONNECT-AUTH-001 closure):
+ * the legacy boolean return conflated three very different outcomes that
+ * callers MUST distinguish:
+ *
+ *   - `{ ok: true }` — signature verified.
+ *   - `{ ok: false, reason: 'invalid' }` — chain answered, signature is bad.
+ *   - `{ ok: false, reason: 'rpc' }` — chain unreachable / call reverted /
+ *     RPC error. Caller may retry, fall back to a different RPC, or surface
+ *     a soft error. **Treating this as 'invalid' is a fail-open hazard**
+ *     (chain down → every verify returns false → caller gates on truthiness).
+ *   - `{ ok: false, reason: 'config' }` — the client doesn't expose the
+ *     verb required (e.g. `simulateContract` for state-tolerant verify).
+ *
+ * `details` carries the underlying error (when applicable) for telemetry.
+ */
+export type SignatureVerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'invalid';
+} | {
+    ok: false;
+    reason: 'rpc';
+    details?: unknown;
+} | {
+    ok: false;
+    reason: 'config';
+    details?: string;
+};
+/**
+ * Read-only verification. Counterfactual signatures (6492-wrapped) for
+ * not-yet-deployed accounts will return `{ ok: false, reason: 'invalid' }`
+ * here — use `verifyUserSignature` (which performs the 6492 deploy via
+ * `simulateContract`) for the state-tolerant path.
+ *
+ * H7-B.3: typed result; chain errors propagate as `reason: 'rpc'` so the
+ * caller can distinguish a forged signature from a network/RPC fault.
+ */
+export declare function verifyUserSignatureView(args: VerifyUserSignatureArgs): Promise<SignatureVerifyResult>;
+/**
+ * State-tolerant verification. Uses `simulateContract` (eth_call) against
+ * the `isValidSig` entry, which will counterfactually deploy the account
+ * in the simulated state if the signature is a 6492 wrapper for a
+ * not-yet-deployed signer. The on-chain state is NOT mutated (it's a
+ * simulation), so this is safe to call from read-only HTTP handlers.
+ *
+ * Falls back to the view path if the client doesn't expose
+ * `simulateContract`. H7-B.3: typed result.
+ */
+export declare function verifyUserSignature(args: VerifyUserSignatureArgs): Promise<SignatureVerifyResult>;
+/**
+ * Check whether a signature blob is ERC-6492-wrapped (last 32 bytes are
+ * the magic suffix). Useful for callers that want to log "user signed
+ * counterfactually" without inspecting deeper.
+ */
+export declare function isErc6492Wrapped(signature: Hex): boolean;
+//# sourceMappingURL=verify-signature.d.ts.map

package/dist/verify-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-signature.d.ts","sourceRoot":"","sources":["../src/verify-signature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE5C,4BAA4B;AAC5B,eAAO,MAAM,aAAa,EAAE,GAAkB,CAAC;AAE/C,8DAA8D;AAC9D,eAAO,MAAM,aAAa,EAAE,GAC0C,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,YAAY,CAAC,IAAI,EAAE;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;QACxB,YAAY,EAAE,gBAAgB,CAAC;QAC/B,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,gBAAgB,CAAC,CAAC,IAAI,EAAE;QACtB,OAAO,EAAE,OAAO,CAAC;QACjB,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;QACxB,YAAY,EAAE,YAAY,CAAC;QAC3B,IAAI,EAAE,SAAS,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAClC;AAED,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBjC,CAAC;AAEX,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,kBAAkB,EAAE,OAAO,CAAC;IAC5B;mEAC+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,0CAA0C;IAC1C,IAAI,EAAE,GAAG,CAAC;IACV;mDAC+C;IAC/C,SAAS,EAAE,GAAG,CAAC;IACf,MAAM,EAAE,wBAAwB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAYhC;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAehC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAMxD"}

package/dist/verify-signature.js

@@ -0,0 +1,118 @@
+/**
+ * Universal signature verification for app servers.
+ *
+ * Consumers (e.g. demo-a2a's `/auth/siwe-verify`) call `verifyUserSignature`
+ * with `{ signer, hash, signature, universalValidator, publicClient }` and
+ * get back a single boolean — they do NOT branch on signer method (EOA,
+ * passkey, etc.). The on-chain `UniversalSignatureValidator` contract
+ * dispatches: ECDSA for code-less signers, ERC-1271 for deployed smart
+ * accounts, ERC-6492 for counterfactual smart accounts (deploys via
+ * factoryCalldata embedded in the signature, then ERC-1271).
+ *
+ * Doctrine — see [[feedback-demo-a2a-is-signer-agnostic]] memory and
+ * spec 130 §7: connect-auth ships the verifier helper; demo-a2a calls
+ * it; passkey internals stay out of demo-a2a entirely.
+ *
+ * Two modes:
+ *   - `verifyUserSignature` (state-changing): calls `isValidSig` on the
+ *     validator. The 6492 path may DEPLOY the user's smart account
+ *     before verifying. Suitable for relayer pre-flight where the
+ *     submitter is OK paying for deploy gas if verification succeeds.
+ *   - `verifyUserSignatureView` (read-only): calls `isValidSigView`. 6492
+ *     wrappers without already-deployed accounts will return false.
+ *     Suitable for cheap pre-checks.
+ *
+ * The function signature intentionally takes the validator address as a
+ * parameter — connect-auth is transport- and deployment-agnostic; the
+ * caller wires in the deployed contract address from its config.
+ */
+/** ERC-1271 magic value. */
+export const ERC1271_MAGIC = '0x1626ba7e';
+/** ERC-6492 32-byte magic suffix (`0x6492…6492` repeated). */
+export const ERC6492_MAGIC = '0x6492649264926492649264926492649264926492649264926492649264926492';
+export const universalSignatureValidatorAbi = [
+    {
+        type: 'function',
+        name: 'isValidSig',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'signer', type: 'address' },
+            { name: 'hash', type: 'bytes32' },
+            { name: 'sig', type: 'bytes' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+    {
+        type: 'function',
+        name: 'isValidSigView',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'signer', type: 'address' },
+            { name: 'hash', type: 'bytes32' },
+            { name: 'sig', type: 'bytes' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
+/**
+ * Read-only verification. Counterfactual signatures (6492-wrapped) for
+ * not-yet-deployed accounts will return `{ ok: false, reason: 'invalid' }`
+ * here — use `verifyUserSignature` (which performs the 6492 deploy via
+ * `simulateContract`) for the state-tolerant path.
+ *
+ * H7-B.3: typed result; chain errors propagate as `reason: 'rpc'` so the
+ * caller can distinguish a forged signature from a network/RPC fault.
+ */
+export async function verifyUserSignatureView(args) {
+    try {
+        const ok = await args.client.readContract({
+            address: args.universalValidator,
+            abi: universalSignatureValidatorAbi,
+            functionName: 'isValidSigView',
+            args: [args.signer, args.hash, args.signature],
+        });
+        return ok ? { ok: true } : { ok: false, reason: 'invalid' };
+    }
+    catch (e) {
+        return { ok: false, reason: 'rpc', details: e };
+    }
+}
+/**
+ * State-tolerant verification. Uses `simulateContract` (eth_call) against
+ * the `isValidSig` entry, which will counterfactually deploy the account
+ * in the simulated state if the signature is a 6492 wrapper for a
+ * not-yet-deployed signer. The on-chain state is NOT mutated (it's a
+ * simulation), so this is safe to call from read-only HTTP handlers.
+ *
+ * Falls back to the view path if the client doesn't expose
+ * `simulateContract`. H7-B.3: typed result.
+ */
+export async function verifyUserSignature(args) {
+    if (!args.client.simulateContract) {
+        return verifyUserSignatureView(args);
+    }
+    try {
+        const { result } = await args.client.simulateContract({
+            address: args.universalValidator,
+            abi: universalSignatureValidatorAbi,
+            functionName: 'isValidSig',
+            args: [args.signer, args.hash, args.signature],
+        });
+        return result ? { ok: true } : { ok: false, reason: 'invalid' };
+    }
+    catch (e) {
+        return { ok: false, reason: 'rpc', details: e };
+    }
+}
+/**
+ * Check whether a signature blob is ERC-6492-wrapped (last 32 bytes are
+ * the magic suffix). Useful for callers that want to log "user signed
+ * counterfactually" without inspecting deeper.
+ */
+export function isErc6492Wrapped(signature) {
+    if (signature.length < 2 + 64)
+        return false; // '0x' + 32 bytes hex
+    return (signature.slice(-64).toLowerCase() ===
+        ERC6492_MAGIC.slice(2).toLowerCase());
+}
+//# sourceMappingURL=verify-signature.js.map

package/dist/verify-signature.js.map

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@agenticprimitives/connect-auth",
+  "version": "0.1.0-alpha.2",
+  "description": "User authentication (passkey + SIWE + Google OAuth), JWT sessions, and pluggable signer interfaces.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/connect-auth"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/connect-auth",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./passkey": {
+      "types": "./dist/methods/passkey.d.ts",
+      "import": "./dist/methods/passkey.js"
+    },
+    "./siwe": {
+      "types": "./dist/methods/siwe.d.ts",
+      "import": "./dist/methods/siwe.js"
+    },
+    "./google": {
+      "types": "./dist/methods/google.d.ts",
+      "import": "./dist/methods/google.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "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"
+  },
+  "peerDependencies": {
+    "@agenticprimitives/types": "workspace:*",
+    "viem": "^2.50.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "auth",
+    "passkey",
+    "siwe",
+    "oauth",
+    "session",
+    "agentic"
+  ]
+}

package/spec.md

@@ -0,0 +1,6 @@
+# @agenticprimitives/connect-auth — spec
+
+The authoritative specification for this package lives at the repo root:
+**[`../../specs/200-connect-auth.md`](../../specs/200-connect-auth.md)**
+
+When this package is published, the spec is included verbatim from that file. Do not edit a divergent copy here — edit the canonical one.