@dexterai/vault 0.4.2 → 0.6.0

package/dist/connect/index.d.cts

@@ -0,0 +1,145 @@
+import { PublicKey, Transaction, Connection } from '@solana/web3.js';
+
+/**
+ * verifyConnectProof — the relying-app VERIFIER for "Connect a Tab" step 1.
+ *
+ * A third-party app uses this to confirm a user controls a named Dexter vault.
+ * It reconstructs the read-only two-instruction proof transaction
+ *   [secp256r1_verify, prove_passkey]
+ * from the proof + the challenge it issued + the vault's passkey pubkey, and
+ * simulates it against the caller-supplied Connection (Helius mainnet) via the
+ * legacy `Transaction` simulate overload — which does NOT verify signatures, so
+ * the placeholder blockhash and formal feePayer are never checked.
+ * `err === null` → the holder controls the vault.
+ *   (`connection.simulateTransaction(tx, undefined, false)`: signature is
+ *    `(transaction, signers?, includeAccounts?)`; the third arg is
+ *    `includeAccounts`, set false. There is no `sigVerify` param on this
+ *    overload — `sigVerify` exists only on the VersionedTransaction config.)
+ *
+ * This is THE canonical method documented in provePasskey.ts: a verifier treats
+ * a passing simulate of [secp256r1_verify, prove_passkey] (err === null) as
+ * proof of control.
+ * It reuses the exact on-chain P-256 semantics rather than re-implementing
+ * verification — a forged/wrong-key/wrong-challenge proof makes the on-chain
+ * precompile (or prove_passkey's op-message check) reject, and simulate
+ * returns a non-null err. The reject path is genuinely simulate-driven; it is
+ * NOT a bypassable string compare.
+ *
+ * The `simulate` step is injectable with a real default (the same
+ * injectable-default-real pattern ./tab and ./factoring use for assembleSignV2
+ * / readPriorSpent) so the assembly + decision logic is unit-testable offline,
+ * while production hits the real chain.
+ */
+
+interface ConnectProof {
+    /** 33-byte compressed P-256 passkey pubkey bound to the vault. */
+    passkeyPubkey: Uint8Array;
+    /** base58 vault PDA the proof claims control of. */
+    vault: string;
+    /** WebAuthn ceremony outputs (from WebAuthnAssertionResult). */
+    clientDataJSON: Uint8Array;
+    authenticatorData: Uint8Array;
+    /** 64-byte compact lowS r||s P-256 signature. */
+    signature: Uint8Array;
+}
+interface ConnectVerifyResult {
+    ok: boolean;
+    vault?: PublicKey;
+    reason?: string;
+}
+/** Injectable simulate fn — defaults to the real connection.simulateTransaction.
+ *  Matches the on-chain verifier method documented in provePasskey.ts.
+ *
+ *  The return shape is intentionally MINIMAL: only `value.err` is consumed by
+ *  the decision path. The real `simulateTransaction` response is richer —
+ *  `{ context, value: { err, logs, accounts, unitsConsumed, ... } }`. A future
+ *  maintainer wanting richer `reason` diagnostics can read `value.logs` (it is
+ *  present on the real response and on the optional `logs?` below). Keeping the
+ *  type narrow also keeps the tests' fake simulate trivial. */
+type SimulateFn = (tx: Transaction) => Promise<{
+    value: {
+        err: unknown;
+        logs?: string[] | null;
+    };
+}>;
+/**
+ * CHALLENGE-ENCODING CONTRACT (C2 — the ceremony — MUST match this):
+ *
+ * The on-chain prove_passkey takes a 32-byte `challenge` (the SIWX nonce/digest);
+ * its op-message is "siwx_login" || challenge, and the WebAuthn
+ * clientDataJSON.challenge field must base64url-decode to
+ * sha256("siwx_login" || challenge).
+ *
+ * The op-message is exactly utf8("siwx_login") concatenated DIRECTLY with the
+ * 32 challenge bytes — no separator, no length prefix, no padding between them
+ * (it is rebuilt on-chain by plain byte concatenation; see provePasskey.ts).
+ *
+ * The relying-app `challenge` STRING that this verifier receives maps to those
+ * 32 bytes by this rule:
+ *   - if it base64url-decodes to EXACTLY 32 bytes, those bytes ARE the challenge;
+ *   - otherwise, sha256(utf8(challenge)) → 32 bytes.
+ * The base64url form is accepted with OR without `=` padding; the canonical
+ * issuer form is unpadded `base64url(random 32 bytes)`.
+ *
+ * So a relying app SHOULD issue `base64url(random 32 bytes)` (the canonical,
+ * zero-ambiguity form). The fallback (sha256 of an arbitrary string) keeps any
+ * other issuer deterministic. C2 produces the matching ceremony challenge:
+ *   clientDataJSON.challenge = base64url(sha256("siwx_login" || challengeBytes)).
+ */
+declare function decodeChallengeTo32Bytes(challenge: string): Uint8Array;
+declare function verifyConnectProof(args: {
+    connection: Connection;
+    /** The challenge the relying app issued (raw string; the SAME one C2 signed). */
+    challenge: string;
+    proof: ConnectProof;
+    /** Default: real connection.simulateTransaction (injectable for tests). */
+    simulate?: SimulateFn;
+}): Promise<ConnectVerifyResult>;
+
+/**
+ * connectTab — the browser-side ceremony for "Connect a Tab" step 1 (auth).
+ *
+ * Runs the WebAuthn passkey assertion and returns a `ConnectProof` that the C1
+ * verifier (`verifyConnectProof`) accepts. connectTab + verifyConnectProof must
+ * agree byte-for-byte on the challenge contract — the round-trip test is the
+ * proof they do.
+ *
+ * THE CHALLENGE CONTRACT (must match verify.ts / provePasskey.ts / the IDL):
+ *   - The relying-app `challenge` STRING maps to 32 bytes via the SAME
+ *     `decodeChallengeTo32Bytes` the verifier uses.
+ *   - The on-chain prove_passkey op-message is utf8("siwx_login") concatenated
+ *     DIRECTLY with those 32 challenge bytes (no separator, no length prefix).
+ *   - The WebAuthn `clientDataJSON.challenge` field must equal
+ *     base64url(sha256("siwx_login" || challengeBytes)).
+ *
+ * Since `WebAuthnAssertion.assertOver(X)` causes the browser to write
+ * base64url(X) into clientDataJSON.challenge, the bytes we pass to assertOver
+ * are sha256("siwx_login" || challengeBytes) — the 32-byte digest, NOT the raw
+ * challenge. Then clientDataJSON.challenge == base64url(sha256(opMessage)),
+ * exactly what prove_passkey reconstructs and the precompile signature is over.
+ *
+ * Framework-agnostic: a plain browser function. The C3 button is documented as
+ * a snippet, not a shipped React component (React is not a dependency).
+ */
+
+interface ConnectTabArgs {
+    /** The challenge the relying app issued (same string the server will pass to verifyConnectProof). */
+    challenge: string;
+    /** base58 vault PDA being connected. */
+    vault: string;
+    /** 33-byte compressed P-256 passkey pubkey bound to the vault. */
+    passkeyPubkey: Uint8Array;
+    /** Raw WebAuthn credential ID bytes for the vault's passkey. */
+    credentialId: Uint8Array;
+    /** Optional WebAuthn RP id (defaults to the page's RP). */
+    rpId?: string;
+}
+/**
+ * Run the passkey assertion and return a verifier-ready ConnectProof.
+ *
+ * Browser-only (requires navigator.credentials). The returned proof feeds
+ * straight into verifyConnectProof with the SAME challenge string.
+ */
+declare function connectTab(args: ConnectTabArgs): Promise<ConnectProof>;
+
+export { type ConnectProof, type ConnectTabArgs, type ConnectVerifyResult, type SimulateFn, connectTab, decodeChallengeTo32Bytes, verifyConnectProof };

package/dist/connect/index.d.ts

@@ -0,0 +1,145 @@
+import { PublicKey, Transaction, Connection } from '@solana/web3.js';
+
+/**
+ * verifyConnectProof — the relying-app VERIFIER for "Connect a Tab" step 1.
+ *
+ * A third-party app uses this to confirm a user controls a named Dexter vault.
+ * It reconstructs the read-only two-instruction proof transaction
+ *   [secp256r1_verify, prove_passkey]
+ * from the proof + the challenge it issued + the vault's passkey pubkey, and
+ * simulates it against the caller-supplied Connection (Helius mainnet) via the
+ * legacy `Transaction` simulate overload — which does NOT verify signatures, so
+ * the placeholder blockhash and formal feePayer are never checked.
+ * `err === null` → the holder controls the vault.
+ *   (`connection.simulateTransaction(tx, undefined, false)`: signature is
+ *    `(transaction, signers?, includeAccounts?)`; the third arg is
+ *    `includeAccounts`, set false. There is no `sigVerify` param on this
+ *    overload — `sigVerify` exists only on the VersionedTransaction config.)
+ *
+ * This is THE canonical method documented in provePasskey.ts: a verifier treats
+ * a passing simulate of [secp256r1_verify, prove_passkey] (err === null) as
+ * proof of control.
+ * It reuses the exact on-chain P-256 semantics rather than re-implementing
+ * verification — a forged/wrong-key/wrong-challenge proof makes the on-chain
+ * precompile (or prove_passkey's op-message check) reject, and simulate
+ * returns a non-null err. The reject path is genuinely simulate-driven; it is
+ * NOT a bypassable string compare.
+ *
+ * The `simulate` step is injectable with a real default (the same
+ * injectable-default-real pattern ./tab and ./factoring use for assembleSignV2
+ * / readPriorSpent) so the assembly + decision logic is unit-testable offline,
+ * while production hits the real chain.
+ */
+
+interface ConnectProof {
+    /** 33-byte compressed P-256 passkey pubkey bound to the vault. */
+    passkeyPubkey: Uint8Array;
+    /** base58 vault PDA the proof claims control of. */
+    vault: string;
+    /** WebAuthn ceremony outputs (from WebAuthnAssertionResult). */
+    clientDataJSON: Uint8Array;
+    authenticatorData: Uint8Array;
+    /** 64-byte compact lowS r||s P-256 signature. */
+    signature: Uint8Array;
+}
+interface ConnectVerifyResult {
+    ok: boolean;
+    vault?: PublicKey;
+    reason?: string;
+}
+/** Injectable simulate fn — defaults to the real connection.simulateTransaction.
+ *  Matches the on-chain verifier method documented in provePasskey.ts.
+ *
+ *  The return shape is intentionally MINIMAL: only `value.err` is consumed by
+ *  the decision path. The real `simulateTransaction` response is richer —
+ *  `{ context, value: { err, logs, accounts, unitsConsumed, ... } }`. A future
+ *  maintainer wanting richer `reason` diagnostics can read `value.logs` (it is
+ *  present on the real response and on the optional `logs?` below). Keeping the
+ *  type narrow also keeps the tests' fake simulate trivial. */
+type SimulateFn = (tx: Transaction) => Promise<{
+    value: {
+        err: unknown;
+        logs?: string[] | null;
+    };
+}>;
+/**
+ * CHALLENGE-ENCODING CONTRACT (C2 — the ceremony — MUST match this):
+ *
+ * The on-chain prove_passkey takes a 32-byte `challenge` (the SIWX nonce/digest);
+ * its op-message is "siwx_login" || challenge, and the WebAuthn
+ * clientDataJSON.challenge field must base64url-decode to
+ * sha256("siwx_login" || challenge).
+ *
+ * The op-message is exactly utf8("siwx_login") concatenated DIRECTLY with the
+ * 32 challenge bytes — no separator, no length prefix, no padding between them
+ * (it is rebuilt on-chain by plain byte concatenation; see provePasskey.ts).
+ *
+ * The relying-app `challenge` STRING that this verifier receives maps to those
+ * 32 bytes by this rule:
+ *   - if it base64url-decodes to EXACTLY 32 bytes, those bytes ARE the challenge;
+ *   - otherwise, sha256(utf8(challenge)) → 32 bytes.
+ * The base64url form is accepted with OR without `=` padding; the canonical
+ * issuer form is unpadded `base64url(random 32 bytes)`.
+ *
+ * So a relying app SHOULD issue `base64url(random 32 bytes)` (the canonical,
+ * zero-ambiguity form). The fallback (sha256 of an arbitrary string) keeps any
+ * other issuer deterministic. C2 produces the matching ceremony challenge:
+ *   clientDataJSON.challenge = base64url(sha256("siwx_login" || challengeBytes)).
+ */
+declare function decodeChallengeTo32Bytes(challenge: string): Uint8Array;
+declare function verifyConnectProof(args: {
+    connection: Connection;
+    /** The challenge the relying app issued (raw string; the SAME one C2 signed). */
+    challenge: string;
+    proof: ConnectProof;
+    /** Default: real connection.simulateTransaction (injectable for tests). */
+    simulate?: SimulateFn;
+}): Promise<ConnectVerifyResult>;
+
+/**
+ * connectTab — the browser-side ceremony for "Connect a Tab" step 1 (auth).
+ *
+ * Runs the WebAuthn passkey assertion and returns a `ConnectProof` that the C1
+ * verifier (`verifyConnectProof`) accepts. connectTab + verifyConnectProof must
+ * agree byte-for-byte on the challenge contract — the round-trip test is the
+ * proof they do.
+ *
+ * THE CHALLENGE CONTRACT (must match verify.ts / provePasskey.ts / the IDL):
+ *   - The relying-app `challenge` STRING maps to 32 bytes via the SAME
+ *     `decodeChallengeTo32Bytes` the verifier uses.
+ *   - The on-chain prove_passkey op-message is utf8("siwx_login") concatenated
+ *     DIRECTLY with those 32 challenge bytes (no separator, no length prefix).
+ *   - The WebAuthn `clientDataJSON.challenge` field must equal
+ *     base64url(sha256("siwx_login" || challengeBytes)).
+ *
+ * Since `WebAuthnAssertion.assertOver(X)` causes the browser to write
+ * base64url(X) into clientDataJSON.challenge, the bytes we pass to assertOver
+ * are sha256("siwx_login" || challengeBytes) — the 32-byte digest, NOT the raw
+ * challenge. Then clientDataJSON.challenge == base64url(sha256(opMessage)),
+ * exactly what prove_passkey reconstructs and the precompile signature is over.
+ *
+ * Framework-agnostic: a plain browser function. The C3 button is documented as
+ * a snippet, not a shipped React component (React is not a dependency).
+ */
+
+interface ConnectTabArgs {
+    /** The challenge the relying app issued (same string the server will pass to verifyConnectProof). */
+    challenge: string;
+    /** base58 vault PDA being connected. */
+    vault: string;
+    /** 33-byte compressed P-256 passkey pubkey bound to the vault. */
+    passkeyPubkey: Uint8Array;
+    /** Raw WebAuthn credential ID bytes for the vault's passkey. */
+    credentialId: Uint8Array;
+    /** Optional WebAuthn RP id (defaults to the page's RP). */
+    rpId?: string;
+}
+/**
+ * Run the passkey assertion and return a verifier-ready ConnectProof.
+ *
+ * Browser-only (requires navigator.credentials). The returned proof feeds
+ * straight into verifyConnectProof with the SAME challenge string.
+ */
+declare function connectTab(args: ConnectTabArgs): Promise<ConnectProof>;
+
+export { type ConnectProof, type ConnectTabArgs, type ConnectVerifyResult, type SimulateFn, connectTab, decodeChallengeTo32Bytes, verifyConnectProof };