@bwalletx/connect 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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`.

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 };