@zerodev/solana-sponsorship-sdk 0.0.1 → 0.1.0-beta.0

package/README.md

@@ -83,6 +83,238 @@ async function main() {
 }
 ```
 
+## Usage with Privy
+
+With Privy, the wallet is managed for you. Instead of `partiallySignTransactionMessageWithSigners`, compile the transaction to bytes and use Privy's `signTransaction`:
+
+```typescript
+import { compileTransaction, getTransactionEncoder, getTransactionDecoder } from "@solana/kit";
+import { useSignTransaction } from "@privy-io/react-auth/solana";
+
+// Inside your React component:
+const { signTransaction } = useSignTransaction();
+
+// Build the transaction message with pipe() as in Quick Start, then:
+const unsignedTx = compileTransaction(message);
+const encoded = new Uint8Array(getTransactionEncoder().encode(unsignedTx));
+
+// Sign with Privy, then decode and sponsor
+const { signedTransaction } = await signTransaction({ transaction: encoded, wallet });
+const decoded = getTransactionDecoder().decode(signedTransaction);
+const result = await sponsorTransaction(sponsorshipRpc, decoded);
+```
+
+See [`examples/sponsorship-with-privy.ts`](./examples/sponsorship-with-privy.ts) for a complete example.
+
+## Usage with Dynamic
+
+Dynamic's signer uses `@solana/web3.js` `VersionedTransaction` internally (already a transitive dependency of `@dynamic-labs/solana` — no extra install needed). Compile the transaction to bytes, deserialize for Dynamic's signer via dynamic import, then decode back for sponsorship:
+
+```typescript
+import { compileTransaction, getTransactionEncoder, getTransactionDecoder } from "@solana/kit";
+import { isSolanaWallet } from "@dynamic-labs/solana";
+import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
+
+const { primaryWallet } = useDynamicContext();
+if (!primaryWallet || !isSolanaWallet(primaryWallet)) throw new Error("No Solana wallet");
+
+// Build the transaction message with pipe() as in Quick Start, then:
+const unsignedTx = compileTransaction(message);
+const encoded = new Uint8Array(getTransactionEncoder().encode(unsignedTx));
+
+// Sign with Dynamic, then decode and sponsor.
+// The `as any` casts are needed because Dynamic's signer types may differ
+// from the @solana/web3.js VersionedTransaction import.
+const { VersionedTransaction } = await import("@solana/web3.js");
+const signer = await primaryWallet.getSigner();
+const versionedTx = VersionedTransaction.deserialize(encoded);
+const signedTx = await signer.signTransaction(versionedTx as any);
+const decoded = getTransactionDecoder().decode((signedTx as any).serialize());
+const result = await sponsorTransaction(sponsorshipRpc, decoded);
+```
+
+See [`examples/sponsorship-with-dynamic.ts`](./examples/sponsorship-with-dynamic.ts) for a complete example.
+
+## Passkeys & Session Keys
+
+The SDK ships a complete browser-passkey flow on top of a sponsored [swig wallet](https://swig.zerodev.app/). You get:
+
+- **Passkey-controlled wallets** — a swig wallet whose root authority is a Secp256r1 (P-256) WebAuthn credential. The user holds the only private key; you never see it.
+- **Session keys** — a short-lived plain Ed25519 keypair that the passkey delegates to, so most transactions go through without a WebAuthn prompt. Useful for high-frequency UX (gameplay, in-app trades, batched ops).
+- **Sponsored every step** — wallet creation, session creation, session-signed sends, and direct passkey-signed sends are all paid by the sponsor server.
+
+All snippets below run in a browser. For Node / CI use, see [Testing without a browser](#testing-without-a-browser).
+
+### Concepts
+
+| Term | What it is |
+| --- | --- |
+| **`PasskeySigner`** | Wraps a registered WebAuthn credential (`credentialId`, 33-byte compressed P-256 pubkey, `rpId`) and exposes `sign(challenge)`. Built with `createBrowserPasskeySigner`. |
+| **Passkey wallet** | A swig PDA whose root authority is the passkey. Created via `createPasskeyWallet` (session-backed) or `createDirectPasskeyWallet` (plain). |
+| **Session key** | Plain `KeyPairSigner` minted by the SDK and registered on the wallet as a delegate authority that expires at a fixed slot. Created via `createSessionKey`. |
+| **`MAX_SESSION_SLOTS`** | Swig's hard cap on session duration (`216_000` ≈ 24h at 400 ms/slot). `createSessionKey` rejects anything larger. |
+
+### Step 1 — Register a passkey
+
+The SDK doesn't dictate which passkey server you use; it just needs the `credentialId`, the 33-byte compressed P-256 pubkey, and the `rpId` you registered against. To pull the compressed pubkey out of a WebAuthn registration response:
+
+```typescript
+import { extractCompressedP256 } from "@zerodev/solana-sponsorship-sdk";
+
+const cred = (await navigator.credentials.create({ publicKey: createOptions })) as PublicKeyCredential;
+const publicKeyBytes = extractCompressedP256(cred); // 33-byte compressed P-256
+
+const credential = {
+  credentialId: new Uint8Array(cred.rawId),
+  publicKeyBytes,
+  rpId: createOptions.rp.id ?? "localhost",
+};
+```
+
+`extractCompressedP256` enforces ES256 (`alg = -7`) — the only curve the on-chain swig verifier accepts.
+
+### Step 2 — Build a `PasskeySigner`
+
+```typescript
+import { passkey } from "@zerodev/solana-sponsorship-sdk";
+
+const signer = passkey.createBrowserPasskeySigner({
+  credentialId: credential.credentialId,
+  publicKeyBytes: credential.publicKeyBytes,
+  rpId: credential.rpId,
+});
+```
+
+The signer holds no state — cache it per credential rather than rebuilding per-tx.
+
+### Step 3 — Create a wallet + session in one shot
+
+The most common shape: one sponsored swig create, one sponsored session-create, one signer the rest of the session can use without WebAuthn prompts.
+
+```typescript
+import { createSolanaRpc } from "@solana/kit";
+import { createSponsorshipRpc, passkey } from "@zerodev/solana-sponsorship-sdk";
+
+const sponsorshipRpc = createSponsorshipRpc({ endpoint: SPONSOR_RPC_URL });
+const solanaRpc = createSolanaRpc(SOLANA_RPC_URL);
+
+const result = await passkey.createPasskeyWalletWithSession({
+  sponsorshipRpc,
+  solanaRpc,
+  credentialId: credential.credentialId,
+  publicKeyBytes: credential.publicKeyBytes,
+  passkeySigner: signer,
+  sessionDurationSlots: 5_000n, // ~33 min on mainnet (400 ms/slot)
+});
+
+if ("sessionError" in result) {
+  // Wallet was created successfully but session bootstrap failed.
+  // `result.wallet` is usable; retry session creation later via createSessionKey.
+  throw result.sessionError;
+}
+
+const { wallet, walletSignature, session, sessionSignature } = result;
+```
+
+Or do the two steps separately if you want more control over confirmation between them:
+
+```typescript
+const { wallet, signature: createSig } = await passkey.createPasskeyWallet({
+  sponsorshipRpc,
+  solanaRpc,
+  credentialId: credential.credentialId,
+  publicKeyBytes: credential.publicKeyBytes,
+});
+// await your own confirmation here...
+
+const { session, signature: sessionSig } = await passkey.createSessionKey({
+  wallet: wallet.address,
+  passkeySigner: signer,
+  durationSlots: 5_000n,
+  sponsorshipRpc,
+  solanaRpc,
+});
+```
+
+### Step 4 — Send session-signed transactions
+
+The session signer pays no SOL and prompts no WebAuthn UI. The sponsor server still pays fees and broadcasts.
+
+```typescript
+import { sponsorTransaction, passkey } from "@zerodev/solana-sponsorship-sdk";
+
+const tx = await passkey.buildSessionSignedTransaction({
+  wallet: wallet.address,
+  session,                         // from createSessionKey
+  innerInstructions: [transferIx], // your app's instructions
+  sponsorshipRpc,
+  solanaRpc,
+});
+
+const { signature } = await sponsorTransaction(sponsorshipRpc, tx);
+```
+
+`buildSessionSignedTransaction` throws `SessionExpiredError` if the current slot is past `session.expiresAtSlot` — catch it and prompt the user to re-authorise via `createSessionKey`.
+
+### Direct passkey signing (no session)
+
+For high-value or admin operations you may want every tx to go through a WebAuthn prompt. That requires a **direct** passkey wallet — its root authority is `createSecp256r1AuthorityInfo` (plain), not `createSecp256r1SessionAuthorityInfo`. Only the direct flavour supports swig's `signV1` path.
+
+```typescript
+const { wallet: directWallet } = await passkey.createDirectPasskeyWallet({
+  sponsorshipRpc,
+  solanaRpc,
+  credentialId: credential.credentialId,
+  publicKeyBytes: credential.publicKeyBytes,
+});
+
+const tx = await passkey.buildPasskeySignedTransaction({
+  wallet: directWallet.address,
+  signer,                          // PasskeySigner — triggers a WebAuthn prompt
+  innerInstructions: [transferIx],
+  sponsorshipRpc,
+  solanaRpc,
+});
+
+const { signature } = await sponsorTransaction(sponsorshipRpc, tx);
+```
+
+### One passkey, two wallets
+
+If your app needs **both** session-signed UX and direct passkey signing for the same user, mint both wallet types from the same credential at registration time:
+
+```typescript
+const sessionBacked = await passkey.createPasskeyWallet({ ...common });
+const direct       = await passkey.createDirectPasskeyWallet({ ...common });
+```
+
+This is the pattern the [`solana-passkey-e2e`](https://github.com/zerodevapp/solana-passkey-e2e) demo uses. Two wallets is the simplest way to support both signing paths — each wallet has exactly one passkey role, which keeps the SDK's "exactly one passkey role" invariant satisfied.
+
+### Testing without a browser
+
+`@zerodev/solana-sponsorship-sdk/testing` exports a software passkey signer that signs with a held-in-memory P-256 keypair, no WebAuthn ceremony required. Use it from Node, Vitest, Playwright fixtures, or anywhere `navigator.credentials` is not available:
+
+```typescript
+import { createSoftwarePasskeySigner } from "@zerodev/solana-sponsorship-sdk/testing";
+
+const signer = await createSoftwarePasskeySigner({ rpId: "localhost" });
+
+// `signer` is a `PasskeySigner` — drop into createPasskeyWallet, createSessionKey,
+// buildPasskeySignedTransaction, buildSessionSignedTransaction unchanged.
+```
+
+### Errors
+
+| Error | Meaning |
+| --- | --- |
+| `SessionExpiredError` | `currentSlot >= session.expiresAtSlot` at build time. Re-create the session. |
+| `SessionBootstrapError` | Returned by `createPasskeyWalletWithSession` when the wallet was created but session creation failed or timed out. `result.wallet` is still valid; retry `createSessionKey`. |
+| `passkey-signed transaction requires unsupported non-sponsor signature(s)` | You called `buildPasskeySignedTransaction` against a session-backed wallet. Either use `buildSessionSignedTransaction` with a session key, or mint a direct wallet with `createDirectPasskeyWallet`. |
+
+### End-to-end reference
+
+The full canonical flow — register → both wallets → session key → session-signed transfer → direct passkey-signed transfer — lives in [`solana-passkey-e2e`](https://github.com/zerodevapp/solana-passkey-e2e). The Playwright `real mode` spec drives the same code path against a local validator and a live passkey server, so it's the closest thing to a runnable production example.
+
 ## Documentation
 
 ### Core Concepts
@@ -104,6 +336,34 @@ Sponsors a transaction and returns a `SponsorshipResponse`.
 #### `getFeePayer()`
 Gets the sponsor's fee payer address from the sponsorship server.
 
+### Passkey API (`passkey.*`)
+
+All re-exported under both `import { passkey } from "..."` and as named top-level imports (`coseToCompressedP256`, `spkiToCompressedP256`, `extractCompressedP256`).
+
+| Symbol | Purpose |
+| --- | --- |
+| `createBrowserPasskeySigner({ credentialId, publicKeyBytes, rpId })` | Build a `PasskeySigner` from a registered credential. |
+| `createPasskeyWallet(params)` | Mint a session-backed swig wallet (use with `createSessionKey`). |
+| `createDirectPasskeyWallet(params)` | Mint a direct-Secp256r1 swig wallet (use with `buildPasskeySignedTransaction`). |
+| `createPasskeyWalletWithSession(params)` | Convenience: create the session-backed wallet **and** its first session key in one call. |
+| `createSessionKey(params)` | Delegate a fresh `KeyPairSigner` as a time-bound authority on an existing wallet. |
+| `buildSessionSignedTransaction(params)` | Compile a sponsor-payable tx signed by a session key. |
+| `buildPasskeySignedTransaction(params)` | Compile a sponsor-payable tx signed via WebAuthn (direct wallets only). |
+| `buildCreatePasskeyWalletTx(params)` / `buildCreateDirectPasskeyWalletTx(params)` | Lower-level: return the unsigned `TransactionMessage` instead of sponsoring + broadcasting. |
+| `computePasskeyChallenge(message)` | SHA-256 of the wire-message preimage used as the WebAuthn challenge. |
+| `passkeySignerToSigningFn(signer)` | Adapter from `PasskeySigner` to `@swig-wallet/lib`'s `UpstreamSigningFn`. |
+| `extractCompressedP256(cred)` | Pull a 33-byte compressed P-256 pubkey out of a WebAuthn `PublicKeyCredential`. |
+| `coseToCompressedP256(cose)` / `spkiToCompressedP256(spki)` | Lower-level conversions for COSE and SPKI inputs. |
+| `MAX_SESSION_SLOTS` | `216_000n` — swig's hard cap on session duration. |
+| `SessionExpiredError`, `SessionBootstrapError` | Typed errors — see [Errors](#errors). |
+
+### Testing helpers (`@zerodev/solana-sponsorship-sdk/testing`)
+
+| Symbol | Purpose |
+| --- | --- |
+| `createSoftwarePasskeySigner({ rpId })` | In-memory P-256 `PasskeySigner` for Node tests; no WebAuthn ceremony. |
+| `buildClientDataJSON`, `buildAuthenticatorData` | Low-level helpers for constructing canonical WebAuthn assertion components in fixtures. |
+
 ## License
 
 MIT License

package/dist/index.d.ts

@@ -1 +1,3 @@
-export { type SponsorshipApi, type SponsorshipRpc, type SponsorshipRpcRequest, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipConfig, type GetFeePayerResponse, type RpcError, type RpcResponse, SponsorshipError, createSponsorshipRpc, sponsorTransaction, setTransactionMessageSponsorFeePayer, setTransactionMessageSponsorFeePayerNoopSigner } from './sponsorship';
+export { type SponsorshipApi, type SponsorshipRpc, type SponsorshipRpcRequest, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipConfig, type GetFeePayerResponse, type RpcError, type RpcResponse, SponsorshipError, createSponsorshipRpc, sponsorTransaction, setTransactionMessageSponsorFeePayer, setTransactionMessageSponsorFeePayerNoopSigner } from './sponsorship.js';
+export * as passkey from './passkey/index.js';
+export { coseToCompressedP256, spkiToCompressedP256, extractCompressedP256, type PublicKeyCredentialLike } from './passkey/index.js';

package/dist/index.js

@@ -1 +1,3 @@
-export { SponsorshipError, createSponsorshipRpc, sponsorTransaction, setTransactionMessageSponsorFeePayer, setTransactionMessageSponsorFeePayerNoopSigner } from './sponsorship';
+export { SponsorshipError, createSponsorshipRpc, sponsorTransaction, setTransactionMessageSponsorFeePayer, setTransactionMessageSponsorFeePayerNoopSigner } from './sponsorship.js';
+export * as passkey from './passkey/index.js';
+export { coseToCompressedP256, spkiToCompressedP256, extractCompressedP256 } from './passkey/index.js';

package/dist/passkey/challenge.d.ts

@@ -0,0 +1,6 @@
+export declare function computePasskeyChallenge(params: {
+    dataPayload: Uint8Array;
+    accountsPayload: Uint8Array;
+    slot: bigint;
+    odometer: number;
+}): Uint8Array;

package/dist/passkey/challenge.js

@@ -0,0 +1,40 @@
+/**
+ * Challenge derivation for swig-wallet Secp256r1 (passkey) authorities.
+ *
+ * @swig-wallet/kit@1.9.1 does NOT export a standalone challenge hash helper.
+ * The digest logic lives inside `prepareSecp256r1Payload` in @swig-wallet/lib@1.9.1
+ * (node_modules/@swig-wallet/lib/dist/index.js, line 3925).
+ *
+ * Canonical preimage (mirrors upstream exactly):
+ *   message = dataPayload || accountsPayload || slot_le64 || odometer_le32
+ *   challenge = keccak256(message)
+ *
+ * `accountsPayload` is the already-encoded account-metas bytes returned by
+ * `getSignV2Instruction.preview(...)` — callers must NOT re-encode it.
+ *
+ * If @swig-wallet/kit is upgraded and the preimage layout changes, the
+ * pinned fixture in challenge.test.ts will fail, forcing an explicit bump.
+ */
+import { keccak_256 } from "@noble/hashes/sha3";
+export function computePasskeyChallenge(params) {
+    const { dataPayload, accountsPayload, slot, odometer } = params;
+    // 8-byte little-endian slot
+    const slotBytes = new Uint8Array(8);
+    new DataView(slotBytes.buffer).setBigUint64(0, slot, /* littleEndian= */ true);
+    // 4-byte little-endian odometer
+    const odometerBytes = new Uint8Array(4);
+    new DataView(odometerBytes.buffer).setUint32(0, odometer, /* littleEndian= */ true);
+    const message = new Uint8Array(dataPayload.length +
+        accountsPayload.length +
+        slotBytes.length +
+        odometerBytes.length);
+    let offset = 0;
+    message.set(dataPayload, offset);
+    offset += dataPayload.length;
+    message.set(accountsPayload, offset);
+    offset += accountsPayload.length;
+    message.set(slotBytes, offset);
+    offset += slotBytes.length;
+    message.set(odometerBytes, offset);
+    return keccak_256(message);
+}

package/dist/passkey/compile.d.ts

@@ -0,0 +1,3 @@
+import { type Transaction } from "@solana/kit";
+import type { CompileWithSponsorParams } from "./types.js";
+export declare function compileWithSponsor(params: CompileWithSponsorParams): Promise<Transaction>;

package/dist/passkey/compile.js

@@ -0,0 +1,12 @@
+import { appendTransactionMessageInstructions, blockhash, compileTransaction, createNoopSigner, createTransactionMessage, partiallySignTransaction, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, } from "@solana/kit";
+export async function compileWithSponsor(params) {
+    const sponsorSigner = createNoopSigner(params.feePayer);
+    const message = pipe(createTransactionMessage({ version: 0 }), (m) => setTransactionMessageFeePayerSigner(sponsorSigner, m), (m) => appendTransactionMessageInstructions(params.instructions, m), (m) => setTransactionMessageLifetimeUsingBlockhash({
+        blockhash: blockhash(params.latestBlockhash.blockhash),
+        lastValidBlockHeight: params.latestBlockhash.lastValidBlockHeight,
+    }, m));
+    const compiled = compileTransaction(message);
+    if (!params.extraSigner)
+        return compiled;
+    return partiallySignTransaction([params.extraSigner.keyPair], compiled);
+}

package/dist/passkey/confirmation.d.ts

@@ -0,0 +1,4 @@
+import { type Rpc, type SolanaRpcApi } from "@solana/kit";
+import type { SignatureConfirmationOptions, SignatureConfirmationResult, SignatureConfirmationSettings } from "./types.js";
+export declare function resolveSignatureConfirmationOptions(options?: SignatureConfirmationOptions): SignatureConfirmationSettings;
+export declare function waitForSignatureConfirmation(rpc: Rpc<SolanaRpcApi>, rawSignature: string, options: SignatureConfirmationSettings): Promise<SignatureConfirmationResult>;

package/dist/passkey/confirmation.js

@@ -0,0 +1,48 @@
+import { commitmentComparator, } from "@solana/kit";
+export function resolveSignatureConfirmationOptions(options = {}) {
+    const settings = {
+        commitment: options.commitment ?? "confirmed",
+        maxAttempts: options.maxAttempts ?? 30,
+        intervalMs: options.intervalMs ?? 1000,
+        searchTransactionHistory: options.searchTransactionHistory ?? true,
+    };
+    if (settings.maxAttempts < 1) {
+        throw new RangeError("walletConfirmation.maxAttempts must be at least 1");
+    }
+    if (settings.intervalMs < 0) {
+        throw new RangeError("walletConfirmation.intervalMs must be non-negative");
+    }
+    return settings;
+}
+export async function waitForSignatureConfirmation(rpc, rawSignature, options) {
+    const { commitment, maxAttempts, intervalMs, searchTransactionHistory } = options;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const { value } = await rpc
+            .getSignatureStatuses([rawSignature], { searchTransactionHistory })
+            .send();
+        const status = value[0];
+        if (status?.err) {
+            return {
+                kind: "failed",
+                message: `wallet creation transaction failed: ${formatRpcValue(status.err)}`,
+            };
+        }
+        if (status?.confirmationStatus &&
+            commitmentComparator(status.confirmationStatus, commitment) >= 0) {
+            return { kind: "confirmed" };
+        }
+        if (attempt < maxAttempts - 1) {
+            await sleep(intervalMs);
+        }
+    }
+    return {
+        kind: "timeout",
+        message: `wallet creation transaction ${rawSignature} was not ${commitment} after ${maxAttempts} status checks`,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatRpcValue(value) {
+    return (JSON.stringify(value, (_key, v) => typeof v === "bigint" ? v.toString() : v) ?? String(value));
+}

package/dist/passkey/constants.d.ts

@@ -0,0 +1 @@
+export declare const MAX_SESSION_SLOTS = 216000n;

package/dist/passkey/constants.js

@@ -0,0 +1,5 @@
+// Solana ~400ms slots: 24h ≈ 216,000 slots. Cap the root authority's
+// session window at 24h so sessions can never outlive the wallet's
+// security model. Per-session durations passed to createSessionKey may
+// be shorter but never longer.
+export const MAX_SESSION_SLOTS = 216000n;

package/dist/passkey/cose.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a COSE_Key blob (ES256 / P-256) into a 33-byte compressed P-256 pubkey.
+ *
+ * Accepts the minimal subset of CBOR needed for an ES256 EC2 key:
+ *   {1: 2 (kty=EC2), 3: -7 (alg=ES256), -1: 1 (crv=P-256), -2: bstr(32) x, -3: bstr(32) y}
+ *
+ * Throws:
+ *   - 'algorithm_not_supported' if alg !== -7
+ *   - 'unsupported_curve' if crv !== 1
+ *   - 'malformed_cose' on any structural problem (wrong kty, missing coord, truncation, etc.)
+ */
+export declare function coseToCompressedP256(cose: Uint8Array): Uint8Array;

package/dist/passkey/cose.js

@@ -0,0 +1,108 @@
+/**
+ * Converts a COSE_Key blob (ES256 / P-256) into a 33-byte compressed P-256 pubkey.
+ *
+ * Accepts the minimal subset of CBOR needed for an ES256 EC2 key:
+ *   {1: 2 (kty=EC2), 3: -7 (alg=ES256), -1: 1 (crv=P-256), -2: bstr(32) x, -3: bstr(32) y}
+ *
+ * Throws:
+ *   - 'algorithm_not_supported' if alg !== -7
+ *   - 'unsupported_curve' if crv !== 1
+ *   - 'malformed_cose' on any structural problem (wrong kty, missing coord, truncation, etc.)
+ */
+export function coseToCompressedP256(cose) {
+    const map = readItem(cose, 0);
+    if (map.kind !== "map")
+        throw new Error("malformed_cose: expected map");
+    const fields = new Map();
+    let off = map.next;
+    for (let i = 0; i < map.value; i++) {
+        if (off >= cose.length)
+            throw new Error("malformed_cose: truncated map");
+        const key = readItem(cose, off);
+        if (key.kind !== "int")
+            throw new Error("malformed_cose: non-int key");
+        off = key.next;
+        if (off >= cose.length)
+            throw new Error("malformed_cose: truncated value");
+        const value = readItem(cose, off);
+        off = value.next;
+        fields.set(key.value, value);
+    }
+    const kty = fields.get(1);
+    if (!kty || kty.kind !== "int" || kty.value !== 2) {
+        throw new Error("malformed_cose: kty must be 2 (EC2)");
+    }
+    const alg = fields.get(3);
+    if (!alg || alg.kind !== "int" || alg.value !== -7) {
+        throw new Error("algorithm_not_supported: only ES256 (-7) is supported");
+    }
+    const crv = fields.get(-1);
+    if (!crv || crv.kind !== "int" || crv.value !== 1) {
+        throw new Error("unsupported_curve: only P-256 (crv=1) is supported");
+    }
+    const x = fields.get(-2);
+    const y = fields.get(-3);
+    if (!x || x.kind !== "bstr" || x.bytes.length !== 32) {
+        throw new Error("malformed_cose: x coord missing or not 32 bytes");
+    }
+    if (!y || y.kind !== "bstr" || y.bytes.length !== 32) {
+        throw new Error("malformed_cose: y coord missing or not 32 bytes");
+    }
+    const yOdd = (y.bytes[31] & 1) === 1;
+    const out = new Uint8Array(33);
+    out[0] = yOdd ? 0x03 : 0x02;
+    out.set(x.bytes, 1);
+    return out;
+}
+function readItem(bytes, offset) {
+    if (offset >= bytes.length)
+        throw new Error("malformed_cose: unexpected end of input");
+    const initial = bytes[offset];
+    const majorType = initial >> 5;
+    const additionalInfo = initial & 0x1f;
+    let next = offset + 1;
+    let value;
+    if (additionalInfo < 24) {
+        value = additionalInfo;
+    }
+    else if (additionalInfo === 24) {
+        if (next + 1 > bytes.length)
+            throw new Error("malformed_cose: truncated 1-byte length");
+        value = bytes[next];
+        next += 1;
+    }
+    else if (additionalInfo === 25) {
+        if (next + 2 > bytes.length)
+            throw new Error("malformed_cose: truncated 2-byte length");
+        value = (bytes[next] << 8) | bytes[next + 1];
+        next += 2;
+    }
+    else if (additionalInfo === 26) {
+        if (next + 4 > bytes.length)
+            throw new Error("malformed_cose: truncated 4-byte length");
+        value =
+            bytes[next] * 0x1000000 +
+                (bytes[next + 1] << 16) +
+                (bytes[next + 2] << 8) +
+                bytes[next + 3];
+        next += 4;
+    }
+    else {
+        throw new Error("malformed_cose: unsupported additional info");
+    }
+    switch (majorType) {
+        case 0:
+            return { kind: "int", value, next };
+        case 1:
+            return { kind: "int", value: -(value + 1), next };
+        case 2: {
+            if (next + value > bytes.length)
+                throw new Error("malformed_cose: truncated byte string");
+            return { kind: "bstr", bytes: bytes.subarray(next, next + value), next: next + value };
+        }
+        case 5:
+            return { kind: "map", value, next };
+        default:
+            throw new Error("malformed_cose: unsupported major type " + majorType);
+    }
+}

package/dist/passkey/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class SessionExpiredError extends Error {
+    readonly currentSlot: bigint;
+    readonly expiresAtSlot: bigint;
+    readonly name = "SessionExpiredError";
+    constructor(currentSlot: bigint, expiresAtSlot: bigint);
+}
+export declare class SessionBootstrapError extends Error {
+    readonly name = "SessionBootstrapError";
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}

package/dist/passkey/errors.js

@@ -0,0 +1,15 @@
+export class SessionExpiredError extends Error {
+    constructor(currentSlot, expiresAtSlot) {
+        super(`session expired: currentSlot=${currentSlot} >= expiresAtSlot=${expiresAtSlot}`);
+        this.currentSlot = currentSlot;
+        this.expiresAtSlot = expiresAtSlot;
+        this.name = "SessionExpiredError";
+    }
+}
+export class SessionBootstrapError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = "SessionBootstrapError";
+        this.cause = cause;
+    }
+}

package/dist/passkey/extract.d.ts

@@ -0,0 +1,23 @@
+export type PublicKeyCredentialLike = {
+    response: PublicKeyCredentialResponseLike;
+};
+type PublicKeyCredentialResponseLike = {
+    getPublicKey(): ArrayBuffer | Uint8Array | null;
+    getPublicKeyAlgorithm(): number;
+};
+/**
+ * Extracts a 33-byte compressed P-256 pubkey from a browser `PublicKeyCredential`
+ * registration response.
+ *
+ * Also accepts a structural shape (just `response.getPublicKey()` +
+ * `response.getPublicKeyAlgorithm()`) so the helper can be unit-tested in Node
+ * without DOM lib types.
+ *
+ * Throws:
+ *   - 'algorithm_not_supported' if the credential's algorithm is not ES256 (-7)
+ *   - 'malformed_spki' if `getPublicKey()` returns null or a non-conforming SPKI
+ *   - 'unsupported_curve' if the SPKI's curve OID is not prime256v1
+ */
+export declare function extractCompressedP256(cred: PublicKeyCredential): Uint8Array;
+export declare function extractCompressedP256(cred: PublicKeyCredentialLike): Uint8Array;
+export {};

package/dist/passkey/extract.js

@@ -0,0 +1,21 @@
+import { spkiToCompressedP256 } from "./spki.js";
+export function extractCompressedP256(cred) {
+    const response = cred.response;
+    if (!hasPublicKeyMethods(response)) {
+        throw new Error("malformed_spki: credential response does not expose public key methods");
+    }
+    const alg = response.getPublicKeyAlgorithm();
+    if (alg !== -7) {
+        throw new Error("algorithm_not_supported: expected ES256 (-7), got " + alg);
+    }
+    const raw = response.getPublicKey();
+    if (raw === null || raw === undefined) {
+        throw new Error("malformed_spki: getPublicKey() returned null");
+    }
+    const spki = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    return spkiToCompressedP256(spki);
+}
+function hasPublicKeyMethods(response) {
+    const candidate = response;
+    return typeof candidate.getPublicKey === "function" && typeof candidate.getPublicKeyAlgorithm === "function";
+}

package/dist/passkey/index.d.ts

@@ -0,0 +1,12 @@
+export type { BuildCreatePasskeyWalletTxParams, BuildCreatePasskeyWalletTxResult, BuildPasskeySignedTransactionParams, BuildSessionSignedTransactionParams, CreatePasskeyWalletParams, CreatePasskeyWalletWithSessionParams, CreatePasskeyWalletWithSessionResult, CreateSessionKeyParams, PasskeySigner, PasskeyWallet, SessionKey, UpstreamSigningFn, SignatureConfirmationOptions, WebAuthnAssertion, } from "./types.js";
+export { createBrowserPasskeySigner } from "./signer.js";
+export { computePasskeyChallenge } from "./challenge.js";
+export { MAX_SESSION_SLOTS } from "./constants.js";
+export { buildCreateDirectPasskeyWalletTx, buildCreatePasskeyWalletTx, createDirectPasskeyWallet, createPasskeyWallet, } from "./wallet.js";
+export { passkeySignerToSigningFn, } from "./signing-fn.js";
+export { buildPasskeySignedTransaction, } from "./sign.js";
+export { buildSessionSignedTransaction, createPasskeyWalletWithSession, createSessionKey, } from "./session.js";
+export { SessionBootstrapError, SessionExpiredError } from "./errors.js";
+export { coseToCompressedP256 } from "./cose.js";
+export { spkiToCompressedP256 } from "./spki.js";
+export { extractCompressedP256, type PublicKeyCredentialLike } from "./extract.js";

package/dist/passkey/index.js

@@ -0,0 +1,11 @@
+export { createBrowserPasskeySigner } from "./signer.js";
+export { computePasskeyChallenge } from "./challenge.js";
+export { MAX_SESSION_SLOTS } from "./constants.js";
+export { buildCreateDirectPasskeyWalletTx, buildCreatePasskeyWalletTx, createDirectPasskeyWallet, createPasskeyWallet, } from "./wallet.js";
+export { passkeySignerToSigningFn, } from "./signing-fn.js";
+export { buildPasskeySignedTransaction, } from "./sign.js";
+export { buildSessionSignedTransaction, createPasskeyWalletWithSession, createSessionKey, } from "./session.js";
+export { SessionBootstrapError, SessionExpiredError } from "./errors.js";
+export { coseToCompressedP256 } from "./cose.js";
+export { spkiToCompressedP256 } from "./spki.js";
+export { extractCompressedP256 } from "./extract.js";

package/dist/passkey/role.d.ts

@@ -0,0 +1,4 @@
+import type { Address } from "@solana/kit";
+import type { Swig } from "@swig-wallet/lib";
+import type { PasskeySigner } from "./types.js";
+export declare function requirePasskeyRoleId(swig: Swig, signer: PasskeySigner, wallet: Address): number;

package/dist/passkey/role.js

@@ -0,0 +1,10 @@
+export function requirePasskeyRoleId(swig, signer, wallet) {
+    const roles = swig.findRolesByAuthorityAddress(signer.publicKeyBytes);
+    if (roles.length === 0) {
+        throw new Error(`no role found for passkey on swig ${wallet}`);
+    }
+    if (roles.length > 1) {
+        throw new Error(`expected exactly one passkey role on swig ${wallet}, got ${roles.length}`);
+    }
+    return roles[0].id;
+}