@dexterai/connect 0.17.0 → 0.18.0

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">@dexterai/connect</h1>
 
 <p align="center">
-  <strong>Sign in with Dexter — passkey sign-in for any app. Tap your face, you're in: a non-custodial Dexter Wallet and its live USD balance, in one component.</strong>
+  <strong>Sign in with Dexter. One passkey tap gives any website a non-custodial Dexter Wallet, and gives any server an offline-verifiable session.</strong>
 </p>
 
 <p align="center">
@@ -18,23 +18,31 @@
 
 ## What this is
 
-A React connector that adds **"Sign in with Dexter"** to any app. One
-`<SignInWithDexter/>` button runs a discoverable passkey ceremony — the user
-taps their face and you get back a session plus their non-custodial **Dexter
-Wallet** (address + live USD balance). No password, no seed phrase, no
-extension.
+A `<SignInWithDexter/>` button runs a discoverable passkey ceremony. The user
+taps their face, and your app gets back a session plus their **Dexter
+Wallet**: address, live USD balance, and the rails for an agent to spend from
+it under on-chain limits. The user holds their own keys; only their passkey
+moves funds, enforced on-chain. Composes
+[`@dexterai/vault`](https://www.npmjs.com/package/@dexterai/vault).
 
-The user holds their own keys. Nothing here is custodial — only the user's
-passkey moves funds, enforced on-chain. Composes
-[`@dexterai/vault`](https://www.npmjs.com/package/@dexterai/vault); the only
-peer is React.
+Four entry points cover the whole flow:
+
+| Entry point | Runs in | What it gives you |
+|---|---|---|
+| `@dexterai/connect` | browser | framework-free core: `passkeyLogin`, `createWallet`, `continueWithDexter`, the wallet store, agent-spend controls |
+| `@dexterai/connect/react` | browser | `<SignInWithDexter/>`, the branded wallet kit, hooks |
+| `@dexterai/connect/server` | Node 18+, Workers, Vercel edge | `verifyDexterSession`: offline session verification |
+| `@dexterai/connect/worldid` | browser | `<VerifyPersonhood/>` World ID proof-of-personhood button |
 
 ## Install
 
 ```bash
-npm install @dexterai/connect react
+npm install @dexterai/connect @dexterai/vault react
 ```
 
+`@solana/web3.js` and `@worldcoin/idkit` are optional peers: the first for
+agent-spend signing, the second only if you use the World ID button.
+
 ## Quick start
 
 ```tsx
@@ -52,39 +60,128 @@ function Header() {
 }
 ```
 
-Signed out, it renders a **Sign in with Dexter** button. On success it becomes
-a compact chip — the Dexter Wallet address + **"$X.XX available."**
+Signed out, it renders a **Sign in with Dexter** button. Connected, it becomes
+the wallet chip: address plus **"$X.XX available."**
 
-## Hook (full control)
+## Works on any website
+
+The ceremony is not limited to dexter.cash. On a foreign origin, `passkeyLogin`
+opens a hosted popup on `dexter.cash/connect`, runs the ceremony there, and
+posts the result back to your page (origin-checked and nonce-bound on both
+sides). The default `transport: 'auto'` picks the right mode; `'popup'` and
+`'inline'` force it.
+
+```ts
+import { passkeyLogin } from '@dexterai/connect';
+
+const { session, vault } = await passkeyLogin({ transport: 'auto' });
+```
 
-For your own UI, use the hook directly:
+## Verify the session on your server
+
+```ts
+import { createDexterClient } from '@dexterai/connect/server';
+
+const dexter = createDexterClient(); // parameterized on (iss, jwksUrl); defaults to Dexter's issuer
+
+export async function handler(req: Request) {
+  const auth = await dexter.authenticateRequest(req);
+  if (!auth.isSignedIn) return new Response('unauthorized', { status: 401 });
+  auth.sub;          // stable user id
+  auth.vaultAddress; // the Dexter Wallet address, from the signed dexter claim
+  auth.claims;       // full verified JWT payload
+}
+```
+
+Verification is a local ES256 signature check against a cached JWKS. The first
+call fetches the key set; every later call is pure local crypto with zero
+network (measured at ~0.6ms). The algorithm list is pinned to ES256, and
+issuer plus audience are always checked. `verifyDexterSession(token, options)`
+does the same for a bare token string, and `jwtKey` accepts a public JWK for
+fully networkless deployments.
+
+## Hook (full control)
 
 ```tsx
 import { useSignInWithDexter } from '@dexterai/connect/react';
 
 const c = useSignInWithDexter();
 await c.signIn();        // run the passkey ceremony
-c.status;                // idle → pending → done → error
+c.status;                // idle -> pending -> done -> error
 c.vaultAddress;          // the Dexter Wallet address (base58)
 c.usdcBalance;           // USD available (via Dexter's RPC), or null
 c.disconnect();
 ```
 
-## What `useSignInWithDexter()` gives you
-
 | Field | What it is |
 |---|---|
 | `signIn()` / `disconnect()` | run the passkey ceremony / clear state |
-| `status` / `isVaultConnected` | `idle→pending→done→error` / connected flag |
+| `status` / `isVaultConnected` | `idle->pending->done->error` / connected flag |
 | `session` | auth session tokens (camelCase) |
 | `vaultAddress` / `vaultPda` | the Dexter Wallet address / PDA |
 | `usdcBalance` / `refreshBalance()` | USD available, best-effort via Dexter's RPC |
 | `vault` / `credentialId` / `error` | raw vault payload / credential id / typed error |
 
-## Exports
+## The wallet kit
+
+Branded, presentational pieces that share one implementation across every
+Dexter surface, themed with `--dx-*` CSS variables: `DexterButton` (and
+`DexterMark`) for any action that should look like Dexter, `DexterWalletChip`
+as the header trigger, `DexterWalletMenu` for manage / save / start-fresh, and
+the `useDexterWallet` + `useIdentity` hooks to drive them.
+
+## Agent spend
+
+The control surface for letting an agent spend from the connected wallet:
+
+```ts
+import {
+  assembleAgentSpendStatus, // honest two-mode status read
+  enableAgentSpend,         // the on switch
+  revokeAgentSpend,         // the off switch
+  createPasskeySigner,      // @dexterai/vault guest signer for x402 / tab flows
+} from '@dexterai/connect';
+```
+
+The verbs are framework-free and take `apiOrigin` as a parameter; the SDK
+reads no environment variables.
+
+## World ID
+
+```tsx
+import { VerifyPersonhood } from '@dexterai/connect/worldid';
+
+<VerifyPersonhood onSuccess={(proof) => sendToYourVerifier(proof)} />
+```
 
-- `@dexterai/connect` — framework-free: `passkeyLogin()`, `ConnectError`, types.
-- `@dexterai/connect/react` — `<SignInWithDexter/>`, `useSignInWithDexter()`.
+`useVerifyPersonhood` is the headless version. Requires the optional
+`@worldcoin/idkit` peer.
+
+## Wallet lifecycle
+
+- `createWallet` mints a brand-new named passkey + vault; `passkeyLogin` signs
+  an existing one in; `continueWithDexter` resumes a known wallet.
+- The **wallet store** (`getActiveHandle`, `listWallets`, `switchWallet`,
+  `ejectActiveWallet`, `forgetWallet`, `subscribeWallet`) is the canonical
+  owner of the active-wallet handle. Read and write through it rather than
+  touching localStorage.
+- The **WebAuthn Signal API** helpers (`renamePasskey`, `prunePasskey`,
+  `syncAcceptedPasskeys`, `passkeySignalSupport`) keep the OS keychain in sync
+  where the browser supports it.
+- `resolveIdentity` combines the wallet handle with whatever account token you
+  pass in; `ceremonyPhaseLabel` gives shared copy for connecting-step UI;
+  `createAnonServerPolicy` builds the anonymous server policy for the signer.
+
+## Peer dependencies
+
+| Peer | Required | Why |
+|---|---|---|
+| `react` >=18 | yes | the `/react` and `/worldid` surfaces |
+| `@dexterai/vault` >=0.30 | yes | signer + agent-spend message builders (0.30 matches the deployed program's account layout) |
+| `@solana/web3.js` | optional | agent-spend signing paths |
+| `@worldcoin/idkit` | optional | only for `/worldid` |
+
+The `/server` entry has none of these peers; it depends only on `jose`.
 
 ## License
 

package/dist/server.d.ts

@@ -0,0 +1,72 @@
+import { JWTPayload, JWK, JSONWebKeySet } from 'jose';
+
+/**
+ * @dexterai/connect/server — offline Dexter session verification.
+ *
+ * The server half of Sign in with Dexter (CONTRACT-dexter-session-token.md):
+ * a local ES256 signature check against the published JWKS — no call to
+ * Supabase or dexter-api on the hot path, so it runs on Node and edge
+ * runtimes alike. Pre-hook tokens (no `dexter` claim) verify as signed-in
+ * with `vaultAddress: null`; once the access-token hook is enabled the
+ * claim appears with no code change here.
+ *
+ * Phase 1 issuer is Supabase (CONTRACT §3); everything is parameterized on
+ * (iss, jwksUrl) so the Phase-2 sovereign cutover is a config flip.
+ */
+
+declare const DEFAULT_ISS = "https://qdgumpoqnthrjfmqziwm.supabase.co/auth/v1";
+declare const DEFAULT_AUDIENCE = "authenticated";
+/** The namespaced claim sealed into the token by the access-token hook. */
+interface DexterClaim {
+    ver: number;
+    /** Swig state address (base58) — the canonical Dexter Wallet identity. */
+    vault: string;
+    /** 16-byte passkey handle, base64url; absent on rows without one. */
+    userHandle?: string;
+    agentGrant?: unknown;
+}
+type VerifyFailureReason = 'no_token' | 'invalid' | 'expired' | 'issuer_mismatch' | 'audience_mismatch';
+type DexterSession = {
+    isSignedIn: true;
+    sub: string;
+    vaultAddress: string | null;
+    userHandle: string | null;
+    agentGrant: unknown;
+    sessionId: string | null;
+    aal: string | null;
+    claims: JWTPayload & {
+        dexter?: DexterClaim;
+    };
+} | {
+    isSignedIn: false;
+    reason: VerifyFailureReason;
+};
+interface VerifyOptions {
+    /** Expected issuer. Phase 1 default: the Dexter Supabase project. */
+    iss?: string;
+    /** JWKS location; defaults to `${iss}/.well-known/jwks.json`. */
+    jwksUrl?: string;
+    /**
+     * Public key(s) for fully networkless verification (a JWK or a JWKS).
+     * When omitted, the JWKS is fetched once and cached in-instance.
+     */
+    jwtKey?: JWK | JSONWebKeySet;
+    /** Expected audience. Default: Supabase's `authenticated`. */
+    audience?: string;
+}
+/** A fetch-API Request or anything with a node-style headers bag. */
+type RequestLike = Request | {
+    headers: Record<string, string | string[] | undefined>;
+};
+interface DexterClient {
+    verifyDexterSession(token: string): Promise<DexterSession>;
+    authenticateRequest(req: RequestLike): Promise<DexterSession>;
+}
+declare function createDexterClient(options?: VerifyOptions): DexterClient;
+/**
+ * One-off verification. For servers verifying many requests against a
+ * remote JWKS, create a client once instead so the key set caches.
+ */
+declare function verifyDexterSession(token: string, options?: VerifyOptions): Promise<DexterSession>;
+
+export { DEFAULT_AUDIENCE, DEFAULT_ISS, type DexterClaim, type DexterClient, type DexterSession, type RequestLike, type VerifyFailureReason, type VerifyOptions, createDexterClient, verifyDexterSession };

package/dist/server.js

@@ -0,0 +1,90 @@
+// src/server.ts
+import {
+  createLocalJWKSet,
+  createRemoteJWKSet,
+  jwtVerify,
+  errors as joseErrors
+} from "jose";
+var DEFAULT_ISS = "https://qdgumpoqnthrjfmqziwm.supabase.co/auth/v1";
+var DEFAULT_AUDIENCE = "authenticated";
+function buildGetKey(opts) {
+  if (opts.jwtKey) {
+    const set = "keys" in opts.jwtKey ? opts.jwtKey : { keys: [opts.jwtKey] };
+    return createLocalJWKSet(set);
+  }
+  const iss = opts.iss ?? DEFAULT_ISS;
+  const url = new URL(opts.jwksUrl ?? `${iss}/.well-known/jwks.json`);
+  return createRemoteJWKSet(url, {
+    cacheMaxAge: 6e5,
+    cooldownDuration: 3e4,
+    timeoutDuration: 5e3
+  });
+}
+function failureReason(err) {
+  if (err instanceof joseErrors.JWTExpired) return "expired";
+  if (err instanceof joseErrors.JWTClaimValidationFailed) {
+    if (err.claim === "iss") return "issuer_mismatch";
+    if (err.claim === "aud") return "audience_mismatch";
+    if (err.claim === "exp") return "expired";
+  }
+  return "invalid";
+}
+function bearerFrom(req) {
+  let raw;
+  const headers = req.headers;
+  if (headers && typeof headers.get === "function") {
+    raw = headers.get("authorization");
+  } else {
+    const bag = headers;
+    raw = bag.authorization ?? bag.Authorization;
+  }
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  if (!value) return null;
+  const match = /^Bearer\s+(.+)$/i.exec(value);
+  return match ? match[1] : null;
+}
+function createDexterClient(options = {}) {
+  const iss = options.iss ?? DEFAULT_ISS;
+  const audience = options.audience ?? DEFAULT_AUDIENCE;
+  const getKey = buildGetKey(options);
+  async function verify(token) {
+    try {
+      const { payload } = await jwtVerify(token, getKey, {
+        issuer: iss,
+        audience,
+        algorithms: ["ES256"]
+        // pinned — defeats alg-confusion / alg:none
+      });
+      const dexter = payload.dexter;
+      return {
+        isSignedIn: true,
+        sub: payload.sub ?? "",
+        vaultAddress: dexter?.vault ?? null,
+        userHandle: dexter?.userHandle ?? null,
+        agentGrant: dexter?.agentGrant ?? null,
+        sessionId: payload.session_id ?? null,
+        aal: payload.aal ?? null,
+        claims: payload
+      };
+    } catch (err) {
+      return { isSignedIn: false, reason: failureReason(err) };
+    }
+  }
+  return {
+    verifyDexterSession: verify,
+    async authenticateRequest(req) {
+      const token = bearerFrom(req);
+      if (!token) return { isSignedIn: false, reason: "no_token" };
+      return verify(token);
+    }
+  };
+}
+function verifyDexterSession(token, options = {}) {
+  return createDexterClient(options).verifyDexterSession(token);
+}
+export {
+  DEFAULT_AUDIENCE,
+  DEFAULT_ISS,
+  createDexterClient,
+  verifyDexterSession
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/connect",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Sign in with Dexter — passkey connector. Composes @dexterai/vault.",
   "type": "module",
   "exports": {
@@ -15,6 +15,10 @@
     "./worldid": {
       "types": "./dist/worldid.d.ts",
       "import": "./dist/worldid.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
     }
   },
   "files": [
@@ -26,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@dexterai/vault": ">=0.22",
+    "@dexterai/vault": ">=0.30.0",
     "@solana/web3.js": "^1.98.0",
     "@worldcoin/idkit": "^4.1.8",
     "react": ">=18"
@@ -40,7 +44,7 @@
     }
   },
   "devDependencies": {
-    "@dexterai/vault": "^0.24.0",
+    "@dexterai/vault": "^0.30.0",
     "@solana/web3.js": "^1.98.4",
     "@types/react": "^19.1.12",
     "@worldcoin/idkit": "^4.1.8",
@@ -50,6 +54,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@simplewebauthn/browser": "^13.3.0"
+    "@simplewebauthn/browser": "^13.3.0",
+    "jose": "^6.2.3"
   }
 }