@pvium/p2id-verifier 0.1.0

package/README.md

@@ -0,0 +1,200 @@
+# @pvium/p2id-verifier
+
+Pvium's implementation for verifying identity attestations. It imports
+[`@pvium/p2id-core`](https://www.npmjs.com/package/@pvium/p2id-core) for the protocol identity
+types and hashing rules, then checks the attestation's zero-knowledge proof locally using a
+bundled circuit verification key and configured trusted signing keys. `p2id-core` is installed
+automatically as this package's runtime dependency.
+
+## Install
+
+```sh
+yarn add @pvium/p2id-verifier
+```
+
+Requires Node.js 20+.
+
+## Quick start
+
+```ts
+import { IdentityType } from '@pvium/p2id-core';
+import { verifyIdentity, AttestationSigner, shutdown } from '@pvium/p2id-verifier';
+
+const result = await verifyIdentity({
+  attestation,                          // proof, public inputs and wallet
+  signer: AttestationSigner.Production, // trusted Privy signing keys
+  identityType: IdentityType.Email,     // identity type from the original request
+  identityValue: 'you@example.com',      // identity value from the original request
+});
+
+if (result.valid) {
+  console.log(result.wallet);   // wallet linked to the email in the signed token
+  console.log(result.issuedAt); // token issue time, in Unix seconds
+} else {
+  console.log(result.reason);
+}
+
+await shutdown(); // release the backend after verification is complete
+```
+
+Pass the identity type and value from the original request. Verification checks these values
+and the attestation's wallet against the proof.
+
+## Obtain an attestation
+
+JSON representation:
+
+```json
+{
+  "proof": "<base64>",
+  "publicInputs": "<base64>",
+  "wallet": "0xA01b6E60D51eDB3fEB9f86a62b846f4F90070f98",
+  "circuitVersion": 1
+}
+```
+
+**Pvium API or SDK:** recipient resolution can return an attestation summary. Fetch the full
+attestation and pass it to `verifyIdentity` (see
+[With the Pvium SDK](#with-the-pvium-sdk)).
+
+**Self-hosted prover:** request an attestation from the
+[prover service](https://github.com/pvium/zkid/tree/main/http-prover):
+
+```sh
+curl -s https://your-prover/attestations \
+  -H "authorization: Bearer $AUTH_TOKEN" -H 'content-type: application/json' \
+  -d '{ "identityType": "email", "identityValue": "you@example.com",
+        "wallet": "0xA01b6E60D51eDB3fEB9f86a62b846f4F90070f98", "jwt": "<Privy identity token>" }'
+```
+
+Pass the response to `verifyIdentity` with `signer` set to your Privy app's JWKS URL.
+
+## Reading the result
+
+| `result` | Meaning |
+| --- | --- |
+| `{ valid: true, wallet, issuedAt }` | The signed token links the requested identity and wallet. `issuedAt` is the token's issue time. |
+| `reason: 'identity value mismatch'` / `'identity type mismatch'` | The public inputs do not match the requested identity. |
+| `reason: 'wallet mismatch'` | The wallet does not match the public inputs. |
+| `reason: 'attestation carries no wallet'` | The public inputs contain no wallet commitment. |
+| `reason: 'not signed by a trusted key'` | The signing key is not accepted by the configured `signer`. |
+| `reason: 'invalid proof'` | The proof does not verify. |
+| `reason: 'attestation is for circuit version N; …'` or `'… different circuit build …'` | The declared circuit version or verification-key hash differs from this release (see [Versioning](#versioning)). |
+| `reason: 'malformed attestation: …'` | The public inputs could not be decoded. |
+| `reason: 'unknown identity type "…"'` / `'unrecognised signer: …'` | The identity type or signer argument is unsupported. |
+
+These failures return `{ valid: false, reason }`. Malformed input and backend initialization
+errors can also throw; callers should handle rejected promises.
+
+The package does not enforce an attestation age. Apply an application-specific limit to
+`issuedAt`; this example uses 30 days:
+
+```ts
+const MAX_AGE = 30 * 24 * 3600;
+if (!result.valid) throw new Error(result.reason);
+const age = Date.now() / 1000 - result.issuedAt;
+if (age < 0 || age > MAX_AGE) throw new Error('attestation outside the accepted time window');
+```
+
+## In a server
+
+Using Express 5:
+
+```ts
+import express from 'express';
+import { verifyIdentity, AttestationSigner, IdentityType, shutdown } from '@pvium/p2id-verifier';
+
+const app = express().use(express.json({ limit: '64kb' }));
+
+app.post('/verify-identity', async (req, res) => {
+  const { email, attestation } = req.body;
+  const check = await verifyIdentity({ attestation, signer: AttestationSigner.Production, identityType: IdentityType.Email, identityValue: email });
+  res.status(check.valid ? 200 : 422).json(check);
+});
+
+process.on('SIGTERM', () => shutdown());
+```
+
+The Barretenberg backend initializes on first proof verification and is reused. Startup time
+depends on the runtime and backend. Browser builds use WASM and workers.
+
+## Reading a claim without verifying it
+
+`decodeClaim` reads public inputs without checking the proof. Treat the decoded fields as
+unverified until verification succeeds.
+
+```ts
+import { decodeClaim } from '@pvium/p2id-verifier';
+
+const claim = decodeClaim(Buffer.from(attestation.publicInputs, 'base64'));
+claim.identityType; // numeric identity type ID
+claim.identityHash; // commitment to (type, value)
+claim.wallet;       // reported EVM wallet, or null
+claim.iat;          // reported token issue time
+claim.signer;       // { x, y }: reported P-256 signing key
+```
+
+## Trusted signers
+
+`signer` selects the trusted token-signing keys.
+
+| `signer` | Use |
+| --- | --- |
+| `AttestationSigner.Production` (or `'production'`) | Pvium's production Privy keys, pinned in `PVIUM_ENVIRONMENTS.production.keys`. Unknown keys trigger a lookup against the app's JWKS. |
+| `AttestationSigner.Sandbox` (or `'sandbox'`) | Pvium's sandbox Privy keys, with the same pinning and lookup behavior. |
+| A JWKS URL string, or `{ jwksUrl }` | Accept P-256 keys from the specified JWKS. |
+| PEM string or `{ x, y }` | Accept one specified P-256 key. |
+
+`PVIUM_ENVIRONMENTS` exposes app IDs, JWKS URLs and pinned keys. Pinned keys remain trusted
+until removed in a package release. JWKS responses are cached for ten minutes.
+
+## With the Pvium SDK
+
+Use `payout.getAttestation` to fetch a proof from a recipient's attestation summary. Verify it
+against the identity in the original request:
+
+```ts
+import { PviumSdk } from '@pvium/sdk';
+import { verifyIdentity, AttestationSigner } from '@pvium/p2id-verifier';
+
+const pvium = new PviumSdk({ apiKey: process.env.PVIUM_API_KEY!, environment: 'production' });
+const recipient = { identityType: 'email' as const, identityValue: 'you@example.com' };
+const { data } = await pvium.payout.resolveRecipients(batchId, [recipient]);
+const summary = data.resolved[0]?.attestation;
+if (!summary) throw new Error('attestation unavailable');
+
+const attestation = await pvium.payout.getAttestation(summary);
+const result = await verifyIdentity({
+  attestation,
+  signer: AttestationSigner.Production,
+  identityType: recipient.identityType,
+  identityValue: recipient.identityValue,
+});
+if (!result.valid) throw new Error(result.reason);
+// Apply the freshness policy, then use result.wallet as the payment destination.
+```
+
+An absent attestation does not establish an identity-to-wallet binding. Wallet payees do not
+require one; for identity payees, retry resolution when the proof is available.
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `verifyIdentity(input)` | Verify an identity-to-wallet attestation |
+| `AttestationSigner`, `PVIUM_ENVIRONMENTS` | Signer presets, app IDs, JWKS URLs and pinned keys |
+| `decodeClaim(publicInputs)`, `toPublicInputFields`, `PUBLIC_INPUT_COUNT` | Decode and format public inputs without proof verification |
+| `shutdown()` | Release the verification backend |
+| `CIRCUIT_VERSION`, `VK_SHA256` | Supported circuit version and verification-key hash |
+| `IdentityType`, `IdentityTypeName` | Identity types re-exported from `@pvium/p2id-core` |
+
+Proof bytes and public inputs accept `Uint8Array` or base64 strings. Public inputs also accept
+an array of hexadecimal fields.
+
+## Versioning
+
+Each release includes a verification key for one circuit version (`CIRCUIT_VERSION`).
+`@aztec/bb.js` is pinned to the matching Barretenberg version (`5.0.0-nightly.20260522`).
+Preserve `circuitVersion` and `vkHash` when passing attestations so mismatches can be reported
+before proof verification. Circuit changes require a new package release; use the release
+matching the attestation's circuit version and verification key.

package/dist/environments.d.ts

@@ -0,0 +1,25 @@
+import type { P256PublicKey } from './publicInputs.js';
+/**
+ * Pvium environments. Each is a Privy app: attestations are made from tokens that app signed,
+ * so the trust anchor per environment is that app's signing keys.
+ *
+ * `keys` are the P-256 keys pinned at release time (from `jwksUrl`), so verification works with
+ * no network call. `jwksUrl` is the live source: if an attestation's signer is not among the
+ * pinned keys, the JWKS is fetched once (cached) to cover a key Privy rotated in after this
+ * release. Rotation *out* is deliberate: a pinned key stays trusted until an SDK release drops it.
+ */
+export interface PviumEnvironment {
+    name: 'production' | 'sandbox';
+    privyAppId: string;
+    jwksUrl: string;
+    keys: Array<P256PublicKey & {
+        kid: string;
+    }>;
+}
+export declare const PVIUM_ENVIRONMENTS: Record<'production' | 'sandbox', PviumEnvironment>;
+export type PviumEnvironmentName = keyof typeof PVIUM_ENVIRONMENTS;
+/** Typed choice of trusted signer: a Pvium environment (keys pinned in the SDK). */
+export declare enum AttestationSigner {
+    Production = "production",
+    Sandbox = "sandbox"
+}

package/dist/environments.js

@@ -0,0 +1,42 @@
+export const PVIUM_ENVIRONMENTS = {
+    production: {
+        name: 'production',
+        privyAppId: 'cmjzq9okg01kwjm0cq4b0xs74',
+        jwksUrl: 'https://auth.privy.io/api/v1/apps/cmjzq9okg01kwjm0cq4b0xs74/jwks.json',
+        keys: [
+            {
+                kid: 'gtxaE3pGoA51jLX-_Oeo75Zif0R3k-tBo7NsQpAy4RI',
+                x: 0x95b9d9d18fbed9f5c3b8aab466271793539be2cbc86a7090dd92f4df600850den,
+                y: 0x3acff34d3319d44a03afdd818474d3551e2b37ee2ff029ceac1ee74924eeb813n,
+            },
+            {
+                kid: 'w43bEjqKgP4wGge2dXiLR18B83IgjT4rAjjDcXXd7E0',
+                x: 0xf638cd1c8ae040434c3325c1fdfb4d313496b9e4d266017266c803c4e474cadan,
+                y: 0x93d01d1f671d945cd44a46142a5c35e9b06c27bdac8d65d77c6996112509d029n,
+            },
+        ],
+    },
+    sandbox: {
+        name: 'sandbox',
+        privyAppId: 'cmhc6t92u001tju0cxkxg34on',
+        jwksUrl: 'https://auth.privy.io/api/v1/apps/cmhc6t92u001tju0cxkxg34on/jwks.json',
+        keys: [
+            {
+                kid: 'Lp_q4NY6tg5jSdiD790AIm01JR7GIJ_xmDVZZ6MVAfM',
+                x: 0x487140ed4fa91d71559b5e015286c9b76c270883f59a5ae9febac9b291584cd1n,
+                y: 0xd4cf5625205d28cbe6c8108a695929208c08f3bdc7790ab7023abe17dcdefc04n,
+            },
+            {
+                kid: '1NtmKuIrWxOltnhgo5yNIyuFFmi-cQDW1Ucqv2185Og',
+                x: 0x84e87db1d90fb3ef5079e6fbe8a50e8f2aee7f8ad66c13b837cc93e016e2b9aan,
+                y: 0x27a0949bf003bb64d5a622a05737d2547efa8980267daf35cc75276cb30c9de5n,
+            },
+        ],
+    },
+};
+/** Typed choice of trusted signer: a Pvium environment (keys pinned in the SDK). */
+export var AttestationSigner;
+(function (AttestationSigner) {
+    AttestationSigner["Production"] = "production";
+    AttestationSigner["Sandbox"] = "sandbox";
+})(AttestationSigner || (AttestationSigner = {}));

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { verifyIdentity } from './verifyIdentity.js';
+export type { Attestation, Signer, VerifyIdentityInput, VerifyIdentityResult } from './verifyIdentity.js';
+export { decodeClaim, toPublicInputFields, PUBLIC_INPUT_COUNT } from './publicInputs.js';
+export type { IdentityClaim, P256PublicKey, PublicInputs } from './publicInputs.js';
+export { PVIUM_ENVIRONMENTS, AttestationSigner } from './environments.js';
+export type { PviumEnvironment, PviumEnvironmentName } from './environments.js';
+export { shutdown, VerifierUnavailableError } from './verify.js';
+export { VK_SHA256, CIRCUIT_VERSION } from './vk.js';
+export { IdentityType } from '@pvium/p2id-core';
+export type { IdentityTypeName } from '@pvium/p2id-core';

package/dist/index.js

@@ -0,0 +1,8 @@
+// Verify Pvium identity attestations off-chain. Address derivation and identity hashing are in
+// @pvium/p2id-core; the identity types are re-exported here for convenience.
+export { verifyIdentity } from './verifyIdentity.js';
+export { decodeClaim, toPublicInputFields, PUBLIC_INPUT_COUNT } from './publicInputs.js';
+export { PVIUM_ENVIRONMENTS, AttestationSigner } from './environments.js';
+export { shutdown, VerifierUnavailableError } from './verify.js';
+export { VK_SHA256, CIRCUIT_VERSION } from './vk.js';
+export { IdentityType } from '@pvium/p2id-core';

package/dist/publicInputs.d.ts

@@ -0,0 +1,49 @@
+/** Number of public inputs the circuit emits: 2 inputs + 9 outputs. */
+export declare const PUBLIC_INPUT_COUNT = 11;
+/** Positions in the public input array (see circuit/src/main.nr). */
+export declare const PI: {
+    readonly identityType: 0;
+    readonly wallet: 1;
+    readonly signerXHi: 2;
+    readonly signerXLo: 3;
+    readonly signerYHi: 4;
+    readonly signerYLo: 5;
+    readonly iat: 6;
+    readonly identityHashHi: 7;
+    readonly identityHashLo: 8;
+    readonly walletHashHi: 9;
+    readonly walletHashLo: 10;
+};
+export interface P256PublicKey {
+    x: bigint;
+    y: bigint;
+}
+/** What a proof asserts, decoded from its public inputs. */
+export interface IdentityClaim {
+    identityType: number;
+    /**
+     * EVM address of the wallet linked in the same token, lowercase hex, checked in-circuit
+     * against the address read from the token. Null for a non-EVM wallet or no wallet.
+     */
+    wallet: `0x${string}` | null;
+    /** P-256 public key the token was signed with. */
+    signer: P256PublicKey;
+    /**
+     * When Privy issued the token this proof was made from, unix seconds. This is the attestation
+     * time; whether it is fresh enough is the caller's policy.
+     */
+    iat: number;
+    /** sha256(prefix || type || normalize(value)); see identityHash(). */
+    identityHash: `0x${string}`;
+    /**
+     * identityHash(IdentityType.Wallet, address) for a wallet linked in the same token, proving
+     * the identity and the wallet belong to the same Privy user. Null when the proof has no wallet.
+     */
+    walletHash: `0x${string}` | null;
+}
+/** Accepts the raw 320-byte `public_inputs` file or an array of 32-byte hex fields. */
+export type PublicInputs = Uint8Array | readonly string[];
+/** Normalise public inputs to the `string[]` form bb.js expects (0x-prefixed, 32 bytes each). */
+export declare function toPublicInputFields(inputs: PublicInputs): string[];
+/** Decode the claim carried by a proof's public inputs. Does not verify anything. */
+export declare function decodeClaim(inputs: PublicInputs): IdentityClaim;

package/dist/publicInputs.js

@@ -0,0 +1,55 @@
+import { toHex } from '@pvium/p2id-core';
+/** Number of public inputs the circuit emits: 2 inputs + 9 outputs. */
+export const PUBLIC_INPUT_COUNT = 11;
+/** Positions in the public input array (see circuit/src/main.nr). */
+export const PI = {
+    identityType: 0,
+    wallet: 1,
+    signerXHi: 2,
+    signerXLo: 3,
+    signerYHi: 4,
+    signerYLo: 5,
+    iat: 6,
+    identityHashHi: 7,
+    identityHashLo: 8,
+    walletHashHi: 9,
+    walletHashLo: 10,
+};
+/** Normalise public inputs to the `string[]` form bb.js expects (0x-prefixed, 32 bytes each). */
+export function toPublicInputFields(inputs) {
+    if (inputs instanceof Uint8Array) {
+        if (inputs.length !== PUBLIC_INPUT_COUNT * 32) {
+            throw new Error(`expected ${PUBLIC_INPUT_COUNT * 32} bytes of public inputs, got ${inputs.length}`);
+        }
+        const out = [];
+        for (let i = 0; i < inputs.length; i += 32)
+            out.push(toHex(inputs.subarray(i, i + 32)));
+        return out;
+    }
+    if (inputs.length !== PUBLIC_INPUT_COUNT) {
+        throw new Error(`expected ${PUBLIC_INPUT_COUNT} public inputs, got ${inputs.length}`);
+    }
+    return inputs.map((f) => {
+        const h = f.startsWith('0x') ? f.slice(2) : f;
+        if (!/^[0-9a-fA-F]{1,64}$/.test(h))
+            throw new Error(`bad public input field: ${f}`);
+        return `0x${h.toLowerCase().padStart(64, '0')}`;
+    });
+}
+/** Decode the claim carried by a proof's public inputs. Does not verify anything. */
+export function decodeClaim(inputs) {
+    const f = toPublicInputFields(inputs).map((h) => BigInt(h));
+    const join = (hi, lo) => (hi << 128n) | lo;
+    const hex32 = (v) => `0x${v.toString(16).padStart(64, '0')}`;
+    return {
+        identityType: Number(f[PI.identityType]),
+        wallet: f[PI.wallet] === 0n ? null : `0x${f[PI.wallet].toString(16).padStart(40, '0')}`,
+        signer: { x: join(f[PI.signerXHi], f[PI.signerXLo]), y: join(f[PI.signerYHi], f[PI.signerYLo]) },
+        iat: Number(f[PI.iat]),
+        identityHash: hex32(join(f[PI.identityHashHi], f[PI.identityHashLo])),
+        walletHash: (() => {
+            const w = join(f[PI.walletHashHi], f[PI.walletHashLo]);
+            return w === 0n ? null : hex32(w);
+        })(),
+    };
+}

package/dist/signer.d.ts

@@ -0,0 +1,7 @@
+import type { P256PublicKey } from './publicInputs.js';
+/**
+ * Parse a P-256 public key from a SubjectPublicKeyInfo PEM (what Privy's dashboard shows as the
+ * app verification key). The DER ends with the 65-byte uncompressed point 0x04 || x || y, so no
+ * ASN.1 parser is needed.
+ */
+export declare function parseP256PublicKeyPem(pem: string): P256PublicKey;

package/dist/signer.js

@@ -0,0 +1,24 @@
+/**
+ * Parse a P-256 public key from a SubjectPublicKeyInfo PEM (what Privy's dashboard shows as the
+ * app verification key). The DER ends with the 65-byte uncompressed point 0x04 || x || y, so no
+ * ASN.1 parser is needed.
+ */
+export function parseP256PublicKeyPem(pem) {
+    const body = pem
+        .split('\n')
+        .filter((l) => !l.startsWith('-----'))
+        .join('')
+        .trim();
+    const der = Uint8Array.from(atob(body), (c) => c.charCodeAt(0));
+    if (der.length < 65 || der[der.length - 65] !== 0x04) {
+        throw new Error('expected an uncompressed P-256 public key in SPKI PEM');
+    }
+    const point = der.subarray(der.length - 65);
+    return { x: bytesToBigInt(point.subarray(1, 33)), y: bytesToBigInt(point.subarray(33, 65)) };
+}
+function bytesToBigInt(b) {
+    let v = 0n;
+    for (const x of b)
+        v = (v << 8n) | BigInt(x);
+    return v;
+}

package/dist/verify.d.ts

@@ -0,0 +1,19 @@
+import { type PublicInputs } from './publicInputs.js';
+export interface ProofBundle {
+    /** Raw proof bytes as produced by `bb prove -t evm` (or bb.js with verifierTarget 'evm'). */
+    proof: Uint8Array;
+    publicInputs: PublicInputs;
+}
+/** The circuit's UltraHonk verification key (EVM / keccak transcript), bundled with the package. */
+export declare function verificationKey(): Uint8Array;
+/** Release the Barretenberg WASM instance. Call when your process is done verifying. */
+export declare function shutdown(): Promise<void>;
+/**
+ * Cryptographic check only: is this a valid proof for the Pvium identity circuit with these
+ * public inputs? Says nothing about who signed the token or whether it has expired.
+ */
+export declare function verifyProof(bundle: ProofBundle): Promise<boolean>;
+/** The proof could not be checked at all: the Barretenberg WASM backend failed in this environment. */
+export declare class VerifierUnavailableError extends Error {
+    constructor(cause: unknown);
+}

package/dist/verify.js

@@ -0,0 +1,53 @@
+import { Barretenberg, UltraHonkVerifierBackend } from '@aztec/bb.js';
+import { VK_BASE64 } from './vk.js';
+import { toPublicInputFields } from './publicInputs.js';
+let vkCache;
+/** The circuit's UltraHonk verification key (EVM / keccak transcript), bundled with the package. */
+export function verificationKey() {
+    if (!vkCache)
+        vkCache = Uint8Array.from(atob(VK_BASE64), (c) => c.charCodeAt(0));
+    return vkCache;
+}
+let apiPromise;
+async function backend() {
+    apiPromise ??= Barretenberg.new({ threads: 1 });
+    return new UltraHonkVerifierBackend(await apiPromise);
+}
+/** Release the Barretenberg WASM instance. Call when your process is done verifying. */
+export async function shutdown() {
+    if (apiPromise) {
+        const api = await apiPromise;
+        apiPromise = undefined;
+        await api.destroy();
+    }
+}
+/**
+ * Cryptographic check only: is this a valid proof for the Pvium identity circuit with these
+ * public inputs? Says nothing about who signed the token or whether it has expired.
+ */
+export async function verifyProof(bundle) {
+    const publicInputs = toPublicInputFields(bundle.publicInputs);
+    let v;
+    try {
+        v = await backend();
+    }
+    catch (e) {
+        throw new VerifierUnavailableError(e);
+    }
+    try {
+        return await v.verifyProof({ proof: bundle.proof, publicInputs, verificationKey: verificationKey() }, { verifierTarget: 'evm' });
+    }
+    catch {
+        // bb.js throws on a malformed or tampered proof (e.g. a point that is not on the curve)
+        // as well as returning false: either way the proof did not verify. Environment failures
+        // (WASM cannot load, no threads or shared memory) surface when the backend is created above.
+        return false;
+    }
+}
+/** The proof could not be checked at all: the Barretenberg WASM backend failed in this environment. */
+export class VerifierUnavailableError extends Error {
+    constructor(cause) {
+        super(`proof verifier unavailable in this environment: ${cause?.message ?? String(cause)}`);
+        this.name = 'VerifierUnavailableError';
+    }
+}

package/dist/verifyIdentity.d.ts

@@ -0,0 +1,50 @@
+import { IdentityType, type IdentityTypeName } from '@pvium/p2id-core';
+import { type P256PublicKey, type PublicInputs } from './publicInputs.js';
+import { AttestationSigner, type PviumEnvironmentName } from './environments.js';
+/** What Pvium's resolution API returns for an identity: the proof plus the address it binds. */
+export interface Attestation {
+    /** Proof bytes, or base64 of them. */
+    proof: Uint8Array | string;
+    /** Public inputs: raw bytes, base64 of them, or the hex fields. */
+    publicInputs: PublicInputs | string;
+    /** The wallet address the proof binds to the identity, exactly as linked in Privy. */
+    wallet: string;
+    /** Circuit version that produced the proof, as reported by the prover. Checked when present. */
+    circuitVersion?: number;
+    vkHash?: string;
+}
+/**
+ * Who is trusted to have signed the token behind an attestation.
+ *
+ * - `AttestationSigner.Production` / `AttestationSigner.Sandbox` (or the strings `'production'` /
+ *   `'sandbox'`): Pvium's Privy apps, keys pinned in the SDK, JWKS consulted only for a key
+ *   rotated in after this release (see environments.ts).
+ * - a JWKS URL (`https://…/jwks.json`) or `{ jwksUrl }`: any JWKS; every P-256 key it serves
+ *   is accepted. For self-hosted provers under your own Privy app.
+ * - a SPKI PEM string, or raw `{ x, y }`: one specific key.
+ */
+export type Signer = AttestationSigner | PviumEnvironmentName | string | {
+    jwksUrl: string;
+} | P256PublicKey;
+export interface VerifyIdentityInput {
+    attestation: Attestation;
+    signer: Signer;
+    identityType: IdentityType | IdentityTypeName;
+    identityValue: string;
+}
+export type VerifyIdentityResult = {
+    valid: true;
+    /** The wallet address, now proven to be linked to the identity in the same Privy account. */
+    wallet: string;
+    /** When Privy issued the token the proof was made from (unix seconds). Freshness is your policy. */
+    issuedAt: number;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Does this attestation prove that `identityValue` (of `identityType`) and `attestation.wallet`
+ * belong to the same Privy user, signed by `signer`? On success the wallet is returned as a
+ * trusted value together with the attestation time.
+ */
+export declare function verifyIdentity(input: VerifyIdentityInput): Promise<VerifyIdentityResult>;

package/dist/verifyIdentity.js

@@ -0,0 +1,125 @@
+import { IdentityType, identityHash, resolveIdentityType } from '@pvium/p2id-core';
+import { decodeClaim } from './publicInputs.js';
+import { parseP256PublicKeyPem } from './signer.js';
+import { verifyProof } from './verify.js';
+import { PVIUM_ENVIRONMENTS } from './environments.js';
+import { CIRCUIT_VERSION, VK_SHA256 } from './vk.js';
+/**
+ * Does this attestation prove that `identityValue` (of `identityType`) and `attestation.wallet`
+ * belong to the same Privy user, signed by `signer`? On success the wallet is returned as a
+ * trusted value together with the attestation time.
+ */
+export async function verifyIdentity(input) {
+    let type;
+    try {
+        type = resolveIdentityType(input.identityType);
+    }
+    catch (e) {
+        return { valid: false, reason: e.message };
+    }
+    const att = input.attestation;
+    if (att.circuitVersion !== undefined && att.circuitVersion !== CIRCUIT_VERSION) {
+        return { valid: false, reason: `attestation is for circuit version ${att.circuitVersion}; this SDK verifies version ${CIRCUIT_VERSION}` };
+    }
+    if (att.vkHash !== undefined && att.vkHash.toLowerCase() !== VK_SHA256) {
+        return { valid: false, reason: 'attestation was produced by a different circuit build than this SDK verifies' };
+    }
+    const proof = typeof input.attestation.proof === 'string' ? fromBase64(input.attestation.proof) : input.attestation.proof;
+    const publicInputs = typeof input.attestation.publicInputs === 'string' ? fromBase64(input.attestation.publicInputs) : input.attestation.publicInputs;
+    let claim;
+    try {
+        claim = decodeClaim(publicInputs);
+    }
+    catch (e) {
+        return { valid: false, reason: `malformed attestation: ${e.message}` };
+    }
+    let trusted;
+    try {
+        trusted = await trustedKeys(input.signer, claim.signer);
+    }
+    catch (e) {
+        return { valid: false, reason: e.message };
+    }
+    if (!trusted.some((k) => k.x === claim.signer.x && k.y === claim.signer.y)) {
+        return { valid: false, reason: 'not signed by a trusted key' };
+    }
+    if (claim.identityType !== type)
+        return { valid: false, reason: 'identity type mismatch' };
+    if (identityHash(type, input.identityValue) !== claim.identityHash) {
+        return { valid: false, reason: 'identity value mismatch' };
+    }
+    if (claim.walletHash === null)
+        return { valid: false, reason: 'attestation carries no wallet' };
+    if (identityHash(IdentityType.Wallet, input.attestation.wallet) !== claim.walletHash) {
+        return { valid: false, reason: 'wallet mismatch' };
+    }
+    // For an EVM wallet the circuit also exposes the address it read from the token; it must agree.
+    const w = input.attestation.wallet;
+    if (w.toLowerCase().startsWith('0x') && claim.wallet !== w.toLowerCase()) {
+        return { valid: false, reason: 'wallet mismatch' };
+    }
+    let proofOk;
+    try {
+        proofOk = await verifyProof({ proof, publicInputs });
+    }
+    catch (e) {
+        return { valid: false, reason: e.message }; // the backend failed; says so, not "invalid proof"
+    }
+    if (!proofOk)
+        return { valid: false, reason: 'invalid proof' };
+    return { valid: true, wallet: input.attestation.wallet, issuedAt: claim.iat };
+}
+async function trustedKeys(signer, claimSigner) {
+    if (typeof signer === 'string') {
+        if (signer in PVIUM_ENVIRONMENTS) {
+            const env = PVIUM_ENVIRONMENTS[signer];
+            const pinned = env.keys;
+            // Pinned keys answer without a network call; fall back to the live JWKS only when the
+            // attestation names a key we do not know (rotated in after this SDK release).
+            if (!claimSigner || pinned.some((k) => k.x === claimSigner.x && k.y === claimSigner.y))
+                return pinned;
+            try {
+                return [...pinned, ...(await fetchJwks(env.jwksUrl))];
+            }
+            catch {
+                return pinned;
+            }
+        }
+        if (/^https?:\/\//i.test(signer))
+            return fetchJwks(signer);
+        if (signer.includes('-----BEGIN'))
+            return [parseP256PublicKeyPem(signer)];
+        throw new Error(`unrecognised signer: expected AttestationSigner.Production/Sandbox, a JWKS URL, a PEM, or {x, y}`);
+    }
+    if ('jwksUrl' in signer)
+        return fetchJwks(signer.jwksUrl);
+    return [signer];
+}
+const jwksCache = new Map();
+const JWKS_TTL_MS = 10 * 60 * 1000;
+async function fetchJwks(url) {
+    const hit = jwksCache.get(url);
+    if (hit && Date.now() - hit.at < JWKS_TTL_MS)
+        return hit.keys;
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`JWKS fetch failed: ${res.status}`);
+    const body = (await res.json());
+    const keys = (body.keys ?? [])
+        .filter((k) => k.kty === 'EC' && k.crv === 'P-256' && k.x && k.y)
+        .map((k) => ({ x: b64urlToBigInt(k.x), y: b64urlToBigInt(k.y) }));
+    if (keys.length === 0)
+        throw new Error('JWKS has no P-256 keys');
+    jwksCache.set(url, { at: Date.now(), keys });
+    return keys;
+}
+function fromBase64(s) {
+    const std = s.replace(/-/g, '+').replace(/_/g, '/');
+    return Uint8Array.from(atob(std.padEnd(std.length + ((4 - (std.length % 4)) % 4), '=')), (c) => c.charCodeAt(0));
+}
+function b64urlToBigInt(s) {
+    let v = 0n;
+    for (const b of fromBase64(s))
+        v = (v << 8n) | BigInt(b);
+    return v;
+}

package/dist/vk.d.ts

@@ -0,0 +1,6 @@
+/** UltraHonk verification key for circuit/src/main.nr (keccak / EVM transcript). */
+export declare const VK_BASE64 = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFK5zXF15qgIWxKqH++n94C0tZrqo9d617DIAlbbFl3AoZvXeX9VqtfnDcJpUPOYMyAU60SkPXtNOsy3Py+4HnKh1hmPKJIn3Bgyl/i/y0L4xmq/jnhiYNKeCjYhiceUqMF8mf72zAl+fvbtu1NgLYlzwqA3lniVuvxv53HIhXZ7YMD70rFGCgsLzLYtRSf5FSOyFnaQ6Yl2FEIWw0Ld/VSxFUTa8bzczXTVXXy4Qwi2f4GLVWX7WIWWDsXwgujcggKNvuOTl5etGw9JRyYBIKlglbxvii78J9xOfG9bB7ipcvduuZmh8QvFygxaLKlE4tlXWFmmYLBoo1pM12IlisEw24IjqIi0IkD5UJB1XJhn7DhPU+onAYA4pZMazlM/azCkd4NqFkMc03rPB1DjThGUwJMy1IMjkMet4vsSZHMxEgZby5ck+e6VKkGkHjl31hsZIAbt3cAMF3LhEsG8A+SBkBaJB7fVjIzKlb8jXKUQs1XJUa3suPu3MnJnzPUt9CHyHZ9HJZ1VBx8h4KYAzOEb5QtiYem5Ef/axvWfYhXisnRfX24bUURRUoQK3rBJXCQrcRhdZNf7zegX/u7WeZPC+knjRIVFLEd+MZzguYGVdCtL2zoPdaNfH5hxH7ZVLVBi1cFBBRhoTz6Ft+DXXSKDeN8sXMU98QbqcXDeNuKsIL6gz7aNyPgfLCRKY0QxnLJ++49xCaO6HcULo0X2qhXx/qnV0e2hKaQOVjRuA2e8tG6C+uOoR+61lcSniTBRpsAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB2Ehu/aLL+WzukcV5yAnz0fQEuC2LnFF9Nd3Lz66iDxF3Ip1cq8sW9efKmlb82RKzRcmNniuJooPgVWsYVwO98Eo2Fn9+H6A7LTtfhfUt3f7y7W7R6J6rnG1qeAejDBpRHFGBt/Xc6oDUxE/OSgZcaO0mBJ6S9U4zfPWcaS+EpMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAllEQ5xXBttNS/F9DNA/cb4Cr9kfm/Ejk5mx3BpEV8wBoV8wWDWQc0P3PABe1WrE64g9D1LD+9CfqalJjrUQ5iL+0tZrnZfmoQHSjG03k2oBMQO8ZDm23t7qBUdsKnh0MW7Oa6fdX026TAQoUsGGDWXP1C4qulluBW6gtYYuyq3QKYI8wrTeVG1ygWJzjCP+X4VlTy8mISbDjB9EqU9hWfH4+ktXV1EZLn5GNtOoBMVz8INbwNWZWHtGZdfBbt3BMVvTwB6mV+1TMvrH9dJJ7Sq5X/dhKZj6Ltl6GOGRGushvFHC1PwBT0szR9oQv3coz55bu+SgP7+Ott7xir05dDJtZ8Jy3vAScIK+d8MeCZqfmBGjVxK2uxsNhqnai6hoIjk1QABtTfgznBoBiJzUNphplSkXgTguWc5TY8nZHWDBLm/i342fW2SBf6qPET2yfeFOgAodwv83tIOP0YAjd3AYtYdo2v4rKMrlQxazDOKKcPfSV9I7P4XZDDaILp+REmPHUybNif3QD7RDpLF7Mu6ILUJ9ElS9tl3c7iqwWaSR/58AbuLqlcbIsAO29/Fgfgb1I05mbQ5h+3gKrTbtheAzZlD22xukek7qdw1XR2pCb8NrfDNYLpTfz8xq2P3SwQEWwHk5B9rWZITRwHHcRiEzgSxVYqr6NFKhpW7OJ3jgMD8vrp1Ca8rPA6MyTzZauFpWrA3hI5jVKnklrQmnk0IARG1gPuAaSqTdGu6gY6wwLE1vreQhLKBDz/ta2xcJMvqogOIYFvboT5pjxpvS9kHM9Go8BG7fW/2NqURarvAht5rZd40F3tRfliZT3YshQ6/1yWKmD7hlY152/Sa+0oH4kOiBLMNjcrxvLgL3LYJsZzWzi2L08ZR2r7sUi0YSQpEYC6wwepo1DtMm8PjCPcyO+7Lys3wAzebQ8qDIuruBI24CEjlbJs2Fd3E2AIzEyvAGYDfHArMBvssODDXXf0K9JvWztA1Kek2Cd2k/SH1Fi9X3hDB+k7M95t4CbbE2YqVs5B9rC+E7nCZ0diG4Ie7oGyOoh/KZBJsUwR6YRg1hqpjy3j3dpUfY9t5Ocl3tWCfWM4x4ZWwNEsoa6m7yx8FCMjRMJkjlZNuG3XL4TLVDUSDvtLoAldolNDx1/jDdwkIG4f2OZLow6xxvcgdI/QLvjZFalpWW+uvsW5i9BhTA==";
+/** sha256 of the raw vk bytes, for sanity-checking against the deployed verifier's build. */
+export declare const VK_SHA256 = "0x1c799113fea7ad5b9814605a3cda138e441cee6778ff29d62940e61ebcef822b";
+/** The circuit version this SDK release verifies. Attestations from other versions are rejected. */
+export declare const CIRCUIT_VERSION = 1;

package/dist/vk.js

@@ -0,0 +1,7 @@
+// GENERATED by scripts/embed-vk.mjs — do not edit.
+/** UltraHonk verification key for circuit/src/main.nr (keccak / EVM transcript). */
+export const VK_BASE64 = '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';
+/** sha256 of the raw vk bytes, for sanity-checking against the deployed verifier's build. */
+export const VK_SHA256 = '0x1c799113fea7ad5b9814605a3cda138e441cee6778ff29d62940e61ebcef822b';
+/** The circuit version this SDK release verifies. Attestations from other versions are rejected. */
+export const CIRCUIT_VERSION = 1;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pvium/p2id-verifier",
+  "version": "0.1.0",
+  "description": "Pvium's off-chain verifier for P2ID identity attestations (Noir/UltraHonk zero-knowledge proofs)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/embed-vk.mjs && tsc -p tsconfig.json",
+    "test": "yarn build && node --test --import tsx test/*.test.ts",
+    "sync": "sh scripts/sync-circuit.sh",
+    "prepublishOnly": "yarn test"
+  },
+  "dependencies": {
+    "@aztec/bb.js": "5.0.0-nightly.20260522",
+    "@pvium/p2id-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}