@bwalletx/connect 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.5.0 (unreleased)
+
+- **Access protocol v1 ($401 identity / $403 token-gated access)**, spec in `docs/ACCESS-PROTOCOL.md`. Standard BRC-100 calls only, so any BRC-100 wallet works.
+- Client: `requestAccess()` signs the site's challenge and proves the keys that hold the token (`proveHoldings()`). Errors are `AccessError` with a protocol code.
+- Server: `createAccessChallenge`, `verifyAccess`, `checkTokenHolding`, plus `oneSatResolver()` (1Sat indexer) and `bitSignResolver()` (identity level / KYC). Fails closed: an indexer outage is `indexer_unavailable`, never a grant.
+- Next.js: `createBwalletXAccess()` gives challenge, verify, status and logout routes, a signed access cookie, and `getAccess()`, which re-checks holdings every `recheckEvery` seconds so selling the tokens ends access.
+- `<bwalletx-signin require-token="bsv21:…" min="100">` runs the access flow and emits `bwalletx-access-granted` / `bwalletx-access-denied`.
+- Protocol videos and posters in `assets/protocol/` (401 green, 402 blue, 403 red), exported as `PROTOCOL_MEDIA`.
+
+## 0.4.1 (2026-10-12)
+
+- React: `BwalletXProvider` and `BwalletxSignin` declare `ReactElement` return types, so they type-check as JSX under React 18 `@types/react`.
+- First public release of the 0.4 line (0.4.0 was staged on npm but never released).
+
+## 0.4.0 (2026-10-12)
+
+Everything from 0.3 still works the same way. All additions are BRC-100 first: bWalletX is the main target, but any BRC-100 wallet goes through the same interface.
+
+- **React** (`@bwalletx/connect/react`): `<BwalletXProvider>` and `useBwalletX()` give you status, identityKey, handle and paymail, connect/disconnect, the BRC-100 `wallet`, and pay/tip/buyToken. Safe to server-render. `<BwalletxSignin>` is unchanged.
+- **Next.js adapter** (`@bwalletx/connect/next`, new): `createBwalletXAuth()` gives you challenge, verify, logout and session route handlers, an HMAC-signed httpOnly session cookie, and `getSession()` for server components. The secret comes from `BWALLETX_SESSION_SECRET` (or `secret`). There is no default, so it throws if the secret is missing.
+- **Nonce stores**: `redisStore` (Upstash, node-redis, ioredis) and `pgStore` (any `query` function), plus `pgNonceTableSql()`. `memoryStore` now warns when it runs in production.
+- **Sessions**: `signSession`, `verifySession`, `serializeCookie` and `readCookie` (WebCrypto, so they work on Edge).
+- **Payments**: `pay` (to a paymail, address or BRC-29 identity key; in sats or USD; optional OP_RETURN memo), `tip`, and a `buyToken` quote hook. Each makes one `createAction` and is never retried. Errors are `PaymentError` with a `code` and a `maybeSent` flag.
+- **Server**: `verifyPayment` checks a txid, raw tx, BEEF or Atomic BEEF against the expected outputs, with optional WhatsOnChain or ARC status checks and SPV.
+- **Account linking**: `linkIdentity`, `signInOrLink`, and `IdentityLinkConflictError` (the Next adapter turns it into a 409).
+- **Wallet picker**: `discoverWallets` finds every BRC-100 wallet that announces itself, plus the in-app wallet, optional localhost desktop wallets and phone pairing. `pickWallet` shows the picker UI. `handcashAdapter` is a transitional slot that wraps an app's own HandCash login and imports no HandCash SDK.
+- **Pairing QR modal**: `pairingModal()` and `qrSvg()`, using the bundled `qrcode-generator` (MIT).
+- Tooling: ESLint (`pnpm lint`) and a CI workflow on pull requests.
+
+## 0.3.0
+
+- bApp shell: the `bapp.json` manifest, 5-slot bar, top bar, drawer and in-wallet bridge.

package/README.md

@@ -1,6 +1,6 @@
 # @bwalletx/connect
 
-Add "Sign in with bWalletX" to a website.
+Add "Sign in with bWalletX" to a website. Built on the open BRC-100 wallet interface, so every BRC-100 wallet works the same way, with bWalletX first.
 
 The user's wallet signs a one-time challenge from your server with a key derived from its identity key. Your server checks the signature and signs the user in as that identity key. You don't need an API key or an account with us, and nothing passes through bwalletx.com. The only service of ours involved is the encrypted pairing relay (`relay.bwallet.space`), and only when the user signs in from a phone or the web wallet.
 
@@ -14,6 +14,144 @@ pnpm add @bwalletx/connect @bsv/sdk
 
 `@bsv/sdk` (2.2 or later, 2.x or 3.x) is a peer dependency.
 
+## Next.js quick start (App Router)
+
+Works with bWalletX and any other BRC-100 wallet. Set a session secret (32+ characters) in your environment. There is no default: the routes throw without it.
+
+```sh
+# .env.local (never commit it)
+BWALLETX_SESSION_SECRET=   # e.g. the output of: openssl rand -base64 48
+APP_ORIGIN=https://example.com
+```
+
+```ts
+// lib/bwalletx.ts
+import { createBwalletXAuth, pgStore, signInOrLink } from '@bwalletx/connect/next';
+import { query } from './db'; // (sql, params) => Promise<{ rows }>
+
+export const auth = createBwalletXAuth({
+  origin: process.env.APP_ORIGIN!,
+  store: pgStore({ query }),            // or redisStore({ client: upstash })
+  // Optional: link the identity key to your user table.
+  onVerified: async (identityKey) => {
+    const r = await signInOrLink(identityKey, {
+      findUserByIdentityKey: async (k) => (await query('select user_id from wallet_links where identity_key = $1', [k])).rows[0]?.user_id ?? null,
+      attach: async (uid, k) => void (await query('insert into wallet_links (user_id, identity_key) values ($1, $2)', [uid, k])),
+      createUser: async () => (await query('insert into users default values returning id', [])).rows[0].id,
+    });
+    return { uid: r.userId ?? undefined };
+  },
+});
+```
+
+```ts
+// app/api/bwalletx/challenge/route.ts
+import { auth } from '@/lib/bwalletx';
+export const POST = auth.challenge;
+// app/api/bwalletx/verify/route.ts  → export const POST = auth.verify;
+// app/api/bwalletx/logout/route.ts  → export const POST = auth.logout;
+// app/api/bwalletx/session/route.ts → export const GET = auth.session;
+```
+
+```tsx
+// any server component or route handler
+const session = await auth.getSession(); // { sub: identityKey, uid?, handle?, paymail?, exp } | null
+```
+
+The cookie (`bwx_session`) is `HttpOnly; SameSite=Lax; Secure` (Secure when the origin is https), HMAC-SHA256 signed, 7 days by default (`maxAge`). Both POST routes check the `Origin` header against `origin`. `signSession` / `verifySession` are also exported from `@bwalletx/connect/server` if you want the token without the adapter.
+
+Create the nonce table once (a migration): `pgNonceTableSql()` returns the SQL.
+
+## React quick start
+
+```tsx
+'use client';
+import { BwalletXProvider, useBwalletX } from '@bwalletx/connect/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <BwalletXProvider
+      challengeUrl="/api/bwalletx/challenge"
+      verifyUrl="/api/bwalletx/verify"
+      logoutUrl="/api/bwalletx/logout"
+      sessionUrl="/api/bwalletx/session">
+      {children}
+    </BwalletXProvider>
+  );
+}
+
+function Account() {
+  const { status, identityKey, handle, connect, disconnect, tip } = useBwalletX();
+  if (status !== 'connected') return <button onClick={() => connect()}>Connect wallet</button>;
+  return (
+    <>
+      <span>{handle ?? identityKey?.slice(0, 10)}</span>
+      <button onClick={() => tip({ to: 'author@example.com', usd: 0.05 })}>Tip 5¢</button>
+      <button onClick={disconnect}>Sign out</button>
+    </>
+  );
+}
+```
+
+`useBwalletX()` gives `status` (`idle | restoring | connecting | connected | error`), `identityKey`, `handle`, `paymail`, `wallet` (the BRC-100 `WalletInterface`), `walletId`, `signedIn`, `error`, `wallets`, `connect({ walletId? })`, `disconnect()`, `listWallets()`, `pay`, `tip` and `buyToken`.
+
+`connect()` finds wallets, shows the built-in picker when there is more than one (bWalletX first), shows the pairing QR modal for phones, and signs in through your routes when `challengeUrl` and `verifyUrl` are set. Nothing touches `window` during render, so the provider is safe in server-rendered pages. After a reload the session comes back from `sessionUrl`, but `wallet` stays `null` until the user calls `connect()` again.
+
+## Payments
+
+```ts
+import { pay, tip, buyToken } from '@bwalletx/connect';
+
+await pay(wallet, { to: 'alice@example.com', sats: 5000, memo: 'Album' }); // paymail
+await pay(wallet, { to: '1Abc...', usd: 1 });                              // address; WhatsOnChain rate, or pass usdPerBsv
+const r = await pay(wallet, { to: identityKeyHex, sats: 100 });            // BRC-29; r.remittance goes to the recipient
+await buyToken(wallet, { token: '$BOASE', amount: 100, quote: (q) => fetch('/api/quote', { method: 'POST', body: JSON.stringify(q) }).then((x) => x.json()) });
+```
+
+Each call makes one `createAction`, and nothing is ever retried. Failures throw a `PaymentError` with a `code` (`BAD_REQUEST`, `RESOLVE_FAILED`, `RATE_FAILED`, `WALLET_REJECTED`, `WALLET_ERROR`, `NOT_SUPPORTED`). When `maybeSent` is true, the wallet may already have broadcast the payment, so check before you ask the user again. Browsers often can't resolve paymails themselves because of CORS, so pass `resolvePaymail` to do it on your server.
+
+On the server, check the payment before you deliver anything:
+
+```ts
+import { verifyPayment } from '@bwalletx/connect/server';
+
+const r = await verifyPayment({
+  tx: body.tx ?? body.txid,                       // Atomic BEEF / BEEF / raw hex, or a txid (fetched from WhatsOnChain)
+  expected: [{ address: SELLER_ADDRESS, satoshis: price }], // or { script: hex, satoshis }
+  requireSeen: true,                              // status from WhatsOnChain; or status: 'arc', arcUrl, arcApiKey
+});
+```
+
+Every expected output has to be matched by a different output that carries at least the expected amount. Otherwise `verifyPayment` throws a `PaymentVerificationError` with a `code` (`OUTPUT_MISSING`, `TX_NOT_FOUND`, `NOT_SEEN`, `REJECTED`, `SPV_FAILED`, `BAD_TX`, `NETWORK`). Pass `spv: chainTracker` to check the merkle proofs in a BEEF as well.
+
+## Wallets and the picker
+
+`discoverWallets()` lists everything it can find, with bWalletX first:
+
+- every wallet that announces itself through BRC-100 discovery (bWalletX, Yours, Metanet and others)
+- the in-app browser's `window.CWI`
+- desktop wallets on localhost ports 3321 and 3301 (only with `probeLocal: true`)
+- phone pairing (`pairing: pairingModal()`)
+- any adapters you add in `extra`
+
+`pickWallet(list)` shows the picker. `pairingModal()` returns `PairingOptions` that draw the QR code and match code, so you no longer need your own QR library.
+
+## Migrating from HandCash Connect
+
+1. Keep your HandCash login for now and put it behind the same picker:
+   ```ts
+   import { handcashAdapter } from '@bwalletx/connect';
+   const handcash = handcashAdapter({
+     login: () => myExistingHandCashLogin(), // resolves { handle, paymail? } once signed in
+     pay: (req) => fetch('/api/handcash/pay', { method: 'POST', body: JSON.stringify(req) }).then((r) => r.json()),
+   });
+   <BwalletXProvider extraWallets={[handcash]} ... />
+   ```
+   **This adapter is transitional.** It wraps your own HandCash code; this package does not import any HandCash SDK. HandCash announced BRC-100 support in October 2026. Once that ships, HandCash shows up as an ordinary BRC-100 wallet and you can delete the adapter.
+2. Let existing users link their wallet. When someone already signed in with HandCash connects bWalletX, call `signInOrLink(identityKey, { currentUserId, ... })` (or `linkIdentity`) in `onVerified`. This links the identity to their existing account instead of creating a new one. If the identity is already linked to someone else, `IdentityLinkConflictError` turns into a 409 response.
+3. Replace HandCash payment calls with `pay` / `tip` / `buyToken`, and check them on the server with `verifyPayment` instead of HandCash payment webhooks.
+4. Remove the adapter when your users have moved over.
+
 ## The button
 
 `<bwalletx-signin>` is the standard "Sign in with bWalletX" button: a web component with no dependencies (Shadow DOM), plus a React wrapper. It is the gold button from bit-sign's sign-in card.
@@ -108,7 +246,10 @@ interface NonceStore {
 
 `take` must read and delete in one step. `verifySignIn` calls it before checking anything else, so each nonce gets exactly one attempt.
 
-`memoryStore()` keeps challenges in the process. It is lost on restart and isn't shared between processes or serverless instances, so it prints a warning the first time it is used. If you leave out `store`, a shared in-memory store is used and you get the same warning. In production, use Redis (`GETDEL`) or a database row you delete with `DELETE ... RETURNING`.
+`memoryStore()` keeps challenges in the process. It is lost on restart and isn't shared between processes or serverless instances, so it prints a warning the first time it is used. If you leave out `store`, a shared in-memory store is used and you get the same warning. In production it warns louder. Use one of the built-in shared stores, which need no driver dependency because you pass your own client:
+
+- `redisStore({ client })`: Upstash, Vercel KV or node-redis as they are, or ioredis with `flavor: 'ioredis'`. It uses `GETDEL`, so you need Redis 6.2 or later.
+- `pgStore({ query })`: any `(sql, params)` function (node-postgres, postgres.js, Neon). It deletes each nonce with `DELETE ... RETURNING`, and `pgNonceTableSql()` gives you the table.
 
 Also rate-limit the challenge route per IP. It is unauthenticated.
 
@@ -238,10 +379,10 @@ API: `validateManifest(json)` → `{ok, manifest, errors}`, `parseManifest`, `lo
 
 ## Limits
 
-- You get the identity key and nothing else: no handle, paymail or name.
+- Sign-in proves the identity key and nothing else: no handle, paymail or name. Use `onVerified` to look them up and add them yourself.
 - The identity key is the same on every site that uses this method, so two sites can tell it is the same wallet.
 - `relay.bwallet.space` is run by The Bitcoin Corporation. It has no published uptime guarantee and allows about 60 frames a minute per channel.
-- There is no hosted sign-in page or OAuth-style redirect. You run the two routes yourself.
+- There is no hosted sign-in page or OAuth-style redirect (auth.bwalletx.com is planned). You run the routes yourself; `@bwalletx/connect/next` gives you ready-made ones.
 
 ## Testing
 

package/dist/access-Z6xQwKVF.d.cts

@@ -0,0 +1,118 @@
+import { WalletProtocol } from '@bsv/sdk';
+
+/**
+ * $401 / $402 / $403 access protocol, version 1. Shared by sites (client + server) and wallets.
+ * The full spec is docs/ACCESS-PROTOCOL.md. Pure: no I/O, @bsv/sdk types only.
+ *
+ *   401 identity  "prove who you are (at identity level N, or KYC'd)"
+ *   402 payment   "pay for this" (the challenge format is reserved; payment itself uses pay())
+ *   403 access    "prove you hold N of token X (or N basis points of its supply)"
+ */
+
+declare const ACCESS_VERSION: 1;
+/** Security level 2, a protocol name used for nothing else. Wallets recognise it and show the kind's video. */
+declare const ACCESS_PROTOCOL: WalletProtocol;
+/** How long a challenge is valid. */
+declare const ACCESS_CHALLENGE_LIFETIME_S = 120;
+/** At most this many holding proofs are read from one response. */
+declare const MAX_HOLDING_PROOFS = 50;
+type AccessKind = '401' | '402' | '403';
+interface TokenRequirement {
+    /** 'bsv21:<txid>_<vout>' */
+    id: string;
+    /** Minimum raw (unscaled, integer string) amount. */
+    min?: string;
+    /** Minimum in basis points of total supply (1 = 0.01%, 10000 = 100%). */
+    minBps?: number;
+}
+interface AccessRequirement {
+    token?: TokenRequirement;
+    /** $401 identity level (bit-sign strands): 1 Basic, 2 Verified, 3 Strong, 4 Sovereign (Veriff). */
+    identityLevel?: number;
+    /** A live KYC credential is required. */
+    kyc?: boolean;
+}
+/** What the wallet signs, as canonical JSON. Times are seconds since the epoch. */
+interface AccessChallenge {
+    v: 1;
+    kind: AccessKind;
+    origin: string;
+    nonce: string;
+    iat: number;
+    exp: number;
+    /** The identity key the site expects. A different wallet account is `wrong_account`. */
+    sub?: string;
+    require: AccessRequirement;
+}
+/** A key that locks some of the required token, proving control by signing the same challenge bytes. */
+interface HoldingProof {
+    /** Compressed public key hex of the key locking the outputs. */
+    pubkey: string;
+    /** DER signature by that key over SHA-256(challenge bytes), as BRC-100 createSignature returns. */
+    signature: number[];
+    /** Optional hint: outpoints ('txid_vout') this key holds. Servers must not trust it. */
+    outpoints?: string[];
+}
+/** What the wallet (via requestAccess) posts back to the site. */
+interface AccessResponse {
+    v: 1;
+    /** The challenge string exactly as issued. */
+    challenge: string;
+    identityKey: string;
+    /** DER signature: createSignature({ protocolID: ACCESS_PROTOCOL, keyID: nonce, counterparty: 'anyone', data: challenge bytes }). */
+    signature: number[];
+    holdings?: HoldingProof[];
+}
+type AccessErrorCode = 'not_installed' | 'user_rejected' | 'wrong_account' | 'insufficient_tokens' | 'identity_level_too_low' | 'kyc_required' | 'indexer_unavailable' | 'expired' | 'replay' | 'invalid_signature' | 'bad_request';
+/** The HTTP status a site should answer each code with. */
+declare const ACCESS_ERROR_STATUS: Record<AccessErrorCode, number>;
+interface AccessErrorBody {
+    error: AccessErrorCode;
+    message: string;
+    /** insufficient_tokens: raw amounts; identity_level_too_low: levels. */
+    have?: string | number;
+    need?: string | number;
+}
+declare class AccessError extends Error {
+    readonly code: AccessErrorCode;
+    readonly have?: string | number;
+    readonly need?: string | number;
+    constructor(code: AccessErrorCode, message?: string, extra?: {
+        have?: string | number;
+        need?: string | number;
+    });
+    toJSON(): AccessErrorBody;
+}
+/** One video + poster + colour per kind, so wallets and sites show the same thing. Paths are inside the package. */
+declare const PROTOCOL_MEDIA: Record<AccessKind, {
+    name: string;
+    color: string;
+    video: string;
+    poster: string;
+}>;
+/** Media URLs on a CDN (unpkg) for a given package version. */
+declare function protocolMediaUrl(kind: AccessKind, which: 'video' | 'poster', version?: string): string;
+/**
+ * Canonical JSON: object keys sorted by code unit, no whitespace, undefined members dropped.
+ * Only strings, finite numbers, booleans, null, arrays and plain objects are allowed.
+ */
+declare function canonicalJson(v: unknown): string;
+/** The bytes every signature in the protocol covers: UTF-8 of the challenge string. */
+declare function challengeBytes(challenge: string): number[];
+/** Throws AccessError('bad_request') if the requirement is malformed. Returns a normalised copy. */
+declare function normaliseRequirement(r: unknown): AccessRequirement;
+/** The kind a requirement implies: any token → 403; otherwise 401. */
+declare function kindFor(r: AccessRequirement): AccessKind;
+/** Parse and validate a challenge string. Throws AccessError('bad_request'). Does not check expiry. */
+declare function parseAccessChallenge(s: unknown): AccessChallenge;
+/** Raw amount needed for a token requirement, given total supply (needed only for minBps). Rounds up. */
+declare function tokenNeedRaw(t: TokenRequirement, supplyRaw?: string): string;
+/** Compare unscaled integer strings. Fails closed on malformed input. */
+declare function atLeastRaw(have: string, need: string): boolean;
+/** A user-readable line for an error code. */
+declare function accessErrorMessage(code: AccessErrorCode, e?: {
+    have?: string | number;
+    need?: string | number;
+}): string;
+
+export { AccessError as A, type HoldingProof as H, MAX_HOLDING_PROOFS as M, PROTOCOL_MEDIA as P, type TokenRequirement as T, type AccessRequirement as a, type AccessResponse as b, ACCESS_ERROR_STATUS as c, ACCESS_PROTOCOL as d, ACCESS_VERSION as e, type AccessChallenge as f, type AccessErrorBody as g, type AccessErrorCode as h, type AccessKind as i, accessErrorMessage as j, canonicalJson as k, ACCESS_CHALLENGE_LIFETIME_S as l, atLeastRaw as m, challengeBytes as n, kindFor as o, protocolMediaUrl as p, normaliseRequirement as q, parseAccessChallenge as r, tokenNeedRaw as t };

package/dist/access-Z6xQwKVF.d.ts

@@ -0,0 +1,118 @@
+import { WalletProtocol } from '@bsv/sdk';
+
+/**
+ * $401 / $402 / $403 access protocol, version 1. Shared by sites (client + server) and wallets.
+ * The full spec is docs/ACCESS-PROTOCOL.md. Pure: no I/O, @bsv/sdk types only.
+ *
+ *   401 identity  "prove who you are (at identity level N, or KYC'd)"
+ *   402 payment   "pay for this" (the challenge format is reserved; payment itself uses pay())
+ *   403 access    "prove you hold N of token X (or N basis points of its supply)"
+ */
+
+declare const ACCESS_VERSION: 1;
+/** Security level 2, a protocol name used for nothing else. Wallets recognise it and show the kind's video. */
+declare const ACCESS_PROTOCOL: WalletProtocol;
+/** How long a challenge is valid. */
+declare const ACCESS_CHALLENGE_LIFETIME_S = 120;
+/** At most this many holding proofs are read from one response. */
+declare const MAX_HOLDING_PROOFS = 50;
+type AccessKind = '401' | '402' | '403';
+interface TokenRequirement {
+    /** 'bsv21:<txid>_<vout>' */
+    id: string;
+    /** Minimum raw (unscaled, integer string) amount. */
+    min?: string;
+    /** Minimum in basis points of total supply (1 = 0.01%, 10000 = 100%). */
+    minBps?: number;
+}
+interface AccessRequirement {
+    token?: TokenRequirement;
+    /** $401 identity level (bit-sign strands): 1 Basic, 2 Verified, 3 Strong, 4 Sovereign (Veriff). */
+    identityLevel?: number;
+    /** A live KYC credential is required. */
+    kyc?: boolean;
+}
+/** What the wallet signs, as canonical JSON. Times are seconds since the epoch. */
+interface AccessChallenge {
+    v: 1;
+    kind: AccessKind;
+    origin: string;
+    nonce: string;
+    iat: number;
+    exp: number;
+    /** The identity key the site expects. A different wallet account is `wrong_account`. */
+    sub?: string;
+    require: AccessRequirement;
+}
+/** A key that locks some of the required token, proving control by signing the same challenge bytes. */
+interface HoldingProof {
+    /** Compressed public key hex of the key locking the outputs. */
+    pubkey: string;
+    /** DER signature by that key over SHA-256(challenge bytes), as BRC-100 createSignature returns. */
+    signature: number[];
+    /** Optional hint: outpoints ('txid_vout') this key holds. Servers must not trust it. */
+    outpoints?: string[];
+}
+/** What the wallet (via requestAccess) posts back to the site. */
+interface AccessResponse {
+    v: 1;
+    /** The challenge string exactly as issued. */
+    challenge: string;
+    identityKey: string;
+    /** DER signature: createSignature({ protocolID: ACCESS_PROTOCOL, keyID: nonce, counterparty: 'anyone', data: challenge bytes }). */
+    signature: number[];
+    holdings?: HoldingProof[];
+}
+type AccessErrorCode = 'not_installed' | 'user_rejected' | 'wrong_account' | 'insufficient_tokens' | 'identity_level_too_low' | 'kyc_required' | 'indexer_unavailable' | 'expired' | 'replay' | 'invalid_signature' | 'bad_request';
+/** The HTTP status a site should answer each code with. */
+declare const ACCESS_ERROR_STATUS: Record<AccessErrorCode, number>;
+interface AccessErrorBody {
+    error: AccessErrorCode;
+    message: string;
+    /** insufficient_tokens: raw amounts; identity_level_too_low: levels. */
+    have?: string | number;
+    need?: string | number;
+}
+declare class AccessError extends Error {
+    readonly code: AccessErrorCode;
+    readonly have?: string | number;
+    readonly need?: string | number;
+    constructor(code: AccessErrorCode, message?: string, extra?: {
+        have?: string | number;
+        need?: string | number;
+    });
+    toJSON(): AccessErrorBody;
+}
+/** One video + poster + colour per kind, so wallets and sites show the same thing. Paths are inside the package. */
+declare const PROTOCOL_MEDIA: Record<AccessKind, {
+    name: string;
+    color: string;
+    video: string;
+    poster: string;
+}>;
+/** Media URLs on a CDN (unpkg) for a given package version. */
+declare function protocolMediaUrl(kind: AccessKind, which: 'video' | 'poster', version?: string): string;
+/**
+ * Canonical JSON: object keys sorted by code unit, no whitespace, undefined members dropped.
+ * Only strings, finite numbers, booleans, null, arrays and plain objects are allowed.
+ */
+declare function canonicalJson(v: unknown): string;
+/** The bytes every signature in the protocol covers: UTF-8 of the challenge string. */
+declare function challengeBytes(challenge: string): number[];
+/** Throws AccessError('bad_request') if the requirement is malformed. Returns a normalised copy. */
+declare function normaliseRequirement(r: unknown): AccessRequirement;
+/** The kind a requirement implies: any token → 403; otherwise 401. */
+declare function kindFor(r: AccessRequirement): AccessKind;
+/** Parse and validate a challenge string. Throws AccessError('bad_request'). Does not check expiry. */
+declare function parseAccessChallenge(s: unknown): AccessChallenge;
+/** Raw amount needed for a token requirement, given total supply (needed only for minBps). Rounds up. */
+declare function tokenNeedRaw(t: TokenRequirement, supplyRaw?: string): string;
+/** Compare unscaled integer strings. Fails closed on malformed input. */
+declare function atLeastRaw(have: string, need: string): boolean;
+/** A user-readable line for an error code. */
+declare function accessErrorMessage(code: AccessErrorCode, e?: {
+    have?: string | number;
+    need?: string | number;
+}): string;
+
+export { AccessError as A, type HoldingProof as H, MAX_HOLDING_PROOFS as M, PROTOCOL_MEDIA as P, type TokenRequirement as T, type AccessRequirement as a, type AccessResponse as b, ACCESS_ERROR_STATUS as c, ACCESS_PROTOCOL as d, ACCESS_VERSION as e, type AccessChallenge as f, type AccessErrorBody as g, type AccessErrorCode as h, type AccessKind as i, accessErrorMessage as j, canonicalJson as k, ACCESS_CHALLENGE_LIFETIME_S as l, atLeastRaw as m, challengeBytes as n, kindFor as o, protocolMediaUrl as p, normaliseRequirement as q, parseAccessChallenge as r, tokenNeedRaw as t };