@x1id/resolve 0.22.0 → 0.43.0

package/dist/nsGate.js

@@ -0,0 +1,172 @@
+/**
+ * TLD token gate (program upgrade 6, OpenProject #8457; spec
+ * docs/specs/tld-communities.md §2).
+ *
+ * A TLD creator sets `["ns_gate", label]` = { mint, min_amount } with
+ * {@link buildSetNamespaceGateIx}; the namespace's registration mode becomes
+ * `TokenGated` (2). A non-creator, non-minter payer then registers through
+ * `register_under_namespace_v2` with two more remaining accounts after the
+ * pricing PDA: the gate PDA and a token account of the gate mint owned by the
+ * RECIPIENT (the registration's `owner`, the new name's owner) holding
+ * `>= min_amount` ({@link appendNamespaceGateAccounts}). The gate checks who
+ * RECEIVES the name, never who pays: a holder cannot buy a gated name for a
+ * non-holder, and anyone may pay for a holder. A creator or authorised-minter
+ * PAYER bypasses the gate (issuing to anyone).
+ *
+ * {@link decodeRegistrationMode} FAILS CLOSED: any byte other than 0 (Open)
+ * is not open — 1 is invite-only, 2 token-gated, anything else "restricted".
+ */
+import { encodeBase58, decodeBase58_32 } from "./base58.js";
+export const NAMESPACE_GATE_SEED = "ns_gate";
+export const SET_NAMESPACE_GATE_DISCRIMINATOR = Uint8Array.from([1, 89, 110, 52, 27, 181, 228, 203]);
+export const CLEAR_NAMESPACE_GATE_DISCRIMINATOR = Uint8Array.from([168, 198, 44, 238, 202, 217, 63, 7]);
+/** `sha256("account:NamespaceGate")[0..8]`. */
+export const NAMESPACE_GATE_ACCOUNT_DISCRIMINATOR = Uint8Array.from([76, 234, 116, 167, 238, 185, 71, 218]);
+/** `NamespaceRegistrationMode` bytes. */
+export const NAMESPACE_MODE_OPEN = 0;
+export const NAMESPACE_MODE_INVITE_ONLY = 1;
+export const NAMESPACE_MODE_TOKEN_GATED = 2;
+/** Program error codes (NsGateError, offset 6220). */
+export const NAMESPACE_GATE_ERRORS = {
+    6220: "NsGateRequired",
+    6221: "NsGateMismatch",
+    6222: "NsGateTokenAccountMismatch",
+    6223: "NsGateBalanceTooLow",
+    6224: "NsGateInvalid",
+};
+/** Map a raw mode byte. FAIL CLOSED: only 0 is open; an unknown value (a
+ *  future mode this client does not know) is "restricted", never "open". */
+export function decodeRegistrationMode(byte) {
+    if (byte === NAMESPACE_MODE_OPEN)
+        return "open";
+    if (byte === NAMESPACE_MODE_INVITE_ONLY)
+        return "invite-only";
+    if (byte === NAMESPACE_MODE_TOKEN_GATED)
+        return "token-gated";
+    return "restricted";
+}
+const SYSTEM_PROGRAM = "11111111111111111111111111111111";
+const TE = new TextEncoder();
+function bytes(v, what) {
+    if (typeof v === "string") {
+        const b = decodeBase58_32(v);
+        if (!b)
+            throw new Error(`${what} is not a valid base58 address`);
+        return b;
+    }
+    if (v.length !== 32)
+        throw new Error(`${what} must be exactly 32 bytes`);
+    return v;
+}
+function k(v, what, isSigner, isWritable) {
+    return { pubkey: encodeBase58(bytes(v, what)), isSigner, isWritable };
+}
+function borshStr(s) {
+    const b = TE.encode(s);
+    const out = new Uint8Array(4 + b.length);
+    new DataView(out.buffer).setUint32(0, b.length, true);
+    out.set(b, 4);
+    return out;
+}
+/** `["ns_gate", label]`. */
+export async function deriveNamespaceGatePda(find, programId, label) {
+    return find([TE.encode(NAMESPACE_GATE_SEED), TE.encode(label)], encodeBase58(bytes(programId, "programId")));
+}
+/** `set_namespace_gate(label, mint, min_amount)`: creator(s,w), namespace(w), ns_gate(w), mint, system. Sets mode 2. */
+export function buildSetNamespaceGateIx(p) {
+    if (typeof p.minAmount !== "bigint" || p.minAmount <= 0n || p.minAmount > 0xffffffffffffffffn) {
+        throw new Error("minAmount must be a u64 bigint > 0");
+    }
+    const amt = new Uint8Array(8);
+    new DataView(amt.buffer).setBigUint64(0, p.minAmount, true);
+    const label = borshStr(p.label);
+    const data = new Uint8Array(8 + label.length + 32 + 8);
+    data.set(SET_NAMESPACE_GATE_DISCRIMINATOR, 0);
+    data.set(label, 8);
+    data.set(bytes(p.mint, "mint"), 8 + label.length);
+    data.set(amt, 8 + label.length + 32);
+    return {
+        programId: encodeBase58(bytes(p.programId, "programId")),
+        keys: [
+            k(p.creator, "creator", true, true),
+            k(p.namespace, "namespace", false, true),
+            k(p.namespaceGate, "namespaceGate", false, true),
+            k(p.mint, "mint", false, false),
+            k(SYSTEM_PROGRAM, "systemProgram", false, false),
+        ],
+        data,
+    };
+}
+/** `clear_namespace_gate(label)`: creator(s,w), namespace(w), ns_gate(w). Mode 2 returns to Open. */
+export function buildClearNamespaceGateIx(p) {
+    const label = borshStr(p.label);
+    const data = new Uint8Array(8 + label.length);
+    data.set(CLEAR_NAMESPACE_GATE_DISCRIMINATOR, 0);
+    data.set(label, 8);
+    return {
+        programId: encodeBase58(bytes(p.programId, "programId")),
+        keys: [
+            k(p.creator, "creator", true, true),
+            k(p.namespace, "namespace", false, true),
+            k(p.namespaceGate, "namespaceGate", false, true),
+        ],
+        data,
+    };
+}
+/**
+ * Append the gate accounts to a `buildRegisterUnderNamespaceV2Ix` result
+ * (which ends with the pricing PDA at `remaining_accounts[0]`): `[1]` the
+ * `["ns_gate", label]` PDA, `[2]` a gate-mint token account OWNED BY THE
+ * RECIPIENT (the instruction's `owner`, not the payer). Not needed when the
+ * payer is the creator or an authorised minter.
+ */
+export function appendNamespaceGateAccounts(ix, namespaceGate, ownerTokenAccount) {
+    return {
+        ...ix,
+        keys: [...ix.keys, k(namespaceGate, "namespaceGate", false, false), k(ownerTokenAccount, "ownerTokenAccount", false, false)],
+    };
+}
+/**
+ * Client-side mirror of the program's gate test, for UI pre-checks (the
+ * program is the authority). `payer` decides the bypass (creator, or a
+ * minter the caller knows is authorised); otherwise the `recipient` must own
+ * `tokenAccount` (decoded base layout: `owner`, `mint`, `amount`) of the gate
+ * mint with `amount >= gate.minAmount`.
+ */
+export function namespaceGateAllows(p) {
+    const eq = (a, b, w) => encodeBase58(bytes(a, w)) === encodeBase58(bytes(b, w));
+    if (eq(p.payer, p.creator, "payer") || p.payerIsAuthorisedMinter === true)
+        return true;
+    const ta = p.tokenAccount;
+    if (!ta)
+        return false;
+    return eq(ta.mint, p.gate.mint, "mint") && eq(ta.owner, p.recipient, "recipient") && ta.amount >= p.gate.minAmount;
+}
+/** Decode a `NamespaceGate` (disc | version | bump | mint@10 | token_program@42 | min_amount@74 | updated_at@82 | label@90). */
+export function decodeNamespaceGate(data) {
+    if (data.length < 94)
+        return null;
+    for (let i = 0; i < 8; i++)
+        if (data[i] !== NAMESPACE_GATE_ACCOUNT_DISCRIMINATOR[i])
+            return null;
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const len = dv.getUint32(90, true);
+    if (len > 16 || data.length < 94 + len)
+        return null;
+    let label;
+    try {
+        label = new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(94, 94 + len));
+    }
+    catch {
+        return null;
+    }
+    return {
+        version: data[8],
+        bump: data[9],
+        mint: encodeBase58(data.subarray(10, 42)),
+        tokenProgram: encodeBase58(data.subarray(42, 74)),
+        minAmount: dv.getBigUint64(74, true),
+        updatedAt: dv.getBigInt64(82, true),
+        label,
+    };
+}

package/dist/oidc.d.ts

@@ -0,0 +1,272 @@
+/**
+ * "Sign in with X1ID" — a relying-party (RP) client for the X1ID OpenID Connect
+ * provider at `https://auth.x1id.io` (services/auth, OpenProject #8842).
+ *
+ * Authorization code flow with PKCE S256, `state` and `nonce`; the ID token is
+ * verified against the provider's JWKS (signature for the algorithms discovery
+ * advertises, `iss`, `aud`, `azp`, `exp`/`iat` with a small clock skew,
+ * `nonce`), then `/me` (UserInfo) is fetched and its `sub` checked against the
+ * ID token's.
+ *
+ * Runs in browsers and in Node 20+: Web Crypto + `fetch` only, no runtime
+ * dependency, no DOM access at import time. Browser SPAs use
+ * {@link beginX1idLogin} / {@link completeX1idLogin} (pending state kept in
+ * `sessionStorage`); servers call {@link X1idOidcClient.createAuthorization}
+ * and {@link X1idOidcClient.handleCallback} and keep the pending state in their
+ * own session.
+ *
+ * What a sign-in proves: the user controlled the wallet (`sub`) at sign-in. It
+ * is NOT proof of legal identity, personhood or KYC. Key accounts on `sub`
+ * (the wallet), never on the handle — handles move.
+ */
+export declare const X1ID_ISSUER = "https://auth.x1id.io";
+export declare const X1ID_DEFAULT_SCOPE = "openid profile wallet";
+/** ID-token algorithms this client can verify (the provider's ES256 default,
+ *  EdDSA/Ed25519, and the opt-in RS256 chain). Never `none`, never HS*. */
+export declare const X1ID_SUPPORTED_ID_TOKEN_ALGS: readonly ["ES256", "EdDSA", "RS256"];
+export type X1idIdTokenAlg = (typeof X1ID_SUPPORTED_ID_TOKEN_ALGS)[number];
+/** Default tolerance for `exp` / `iat` against the local clock, in seconds. */
+export declare const X1ID_DEFAULT_CLOCK_SKEW_SECS = 60;
+/** How long a pending login (state/nonce/verifier) stays usable. Matches the
+ *  provider's interaction lifetime. */
+export declare const X1ID_PENDING_TTL_MS: number;
+/**
+ * Every failure is an `X1idAuthError`. `code` is either one of this client's
+ * own codes below, or the provider's OAuth `error` value verbatim
+ * (`access_denied`, `invalid_grant`, `login_required`, …).
+ */
+export type X1idAuthErrorCode = "invalid_config" | "discovery_failed" | "state_mismatch" | "iss_mismatch" | "missing_code" | "pending_expired" | "token_request_failed" | "invalid_token_response" | "invalid_id_token" | "userinfo_failed" | "no_crypto" | (string & {});
+export declare class X1idAuthError extends Error {
+    readonly code: X1idAuthErrorCode;
+    /** The provider's `error_description`, when it sent one. */
+    readonly description: string | undefined;
+    constructor(code: X1idAuthErrorCode, message: string, description?: string);
+}
+export interface X1idOidcConfig {
+    /** Your client id from the X1ID client registry (`x1c_…`). */
+    readonly clientId: string;
+    /** Registered redirect URI (exact match). */
+    readonly redirectUri: string;
+    /** Default `https://auth.x1id.io`. https only (loopback http for local dev). */
+    readonly issuer?: string;
+    /** Default `openid profile wallet`. `openid` is always added. */
+    readonly scope?: string | readonly string[];
+    /** Confidential (server-side) clients only. NEVER put a secret in a browser
+     *  bundle. Omit for public clients (SPA / native: PKCE, no secret). */
+    readonly clientSecret?: string;
+    /** How a confidential client authenticates at `/token`. Default
+     *  `client_secret_basic` (the registry default). */
+    readonly tokenEndpointAuthMethod?: "client_secret_basic" | "client_secret_post";
+    /** Pin the ID-token algorithm (e.g. "RS256" if your client is registered
+     *  for it). Default: any algorithm the provider advertises that this client
+     *  supports. */
+    readonly idTokenSigningAlg?: X1idIdTokenAlg;
+    /** `exp`/`iat` tolerance in seconds. Default 60. */
+    readonly clockSkewSecs?: number;
+    /** Injected `fetch` (tests, proxies). Default `globalThis.fetch`. */
+    readonly fetch?: typeof fetch;
+    /** Injected Web Crypto (tests, old runtimes). Default `globalThis.crypto`. */
+    readonly crypto?: Crypto;
+    /** Injected clock in ms (tests). Default `Date.now`. */
+    readonly now?: () => number;
+}
+/** The subset of the provider's discovery document this client uses. */
+export interface X1idDiscovery {
+    readonly issuer: string;
+    readonly authorization_endpoint: string;
+    readonly token_endpoint: string;
+    readonly jwks_uri: string;
+    readonly userinfo_endpoint?: string;
+    readonly end_session_endpoint?: string;
+    readonly revocation_endpoint?: string;
+    readonly id_token_signing_alg_values_supported?: readonly string[];
+    readonly code_challenge_methods_supported?: readonly string[];
+    readonly authorization_response_iss_parameter_supported?: boolean;
+    readonly [k: string]: unknown;
+}
+/**
+ * What must survive the redirect: keep it server-side (session) or in
+ * `sessionStorage` (SPA, see {@link beginX1idLogin}). Never put it in the URL.
+ */
+export interface X1idPendingLogin {
+    readonly state: string;
+    readonly nonce: string;
+    readonly codeVerifier: string;
+    readonly redirectUri: string;
+    readonly issuer: string;
+    /** ms since epoch. */
+    readonly createdAt: number;
+}
+export interface X1idAuthorizationOptions {
+    /** e.g. "login" to force a fresh sign-in, "consent" (required by a PUBLIC
+     *  client that asks for `offline_access`). */
+    readonly prompt?: string;
+    /** Override the configured scope for this request. */
+    readonly scope?: string | readonly string[];
+    /** `max_age` in seconds. */
+    readonly maxAge?: number;
+    /** `ui_locales`. */
+    readonly uiLocales?: string;
+    /** Any further authorization parameters. The protocol parameters this client
+     *  owns (state, nonce, PKCE, client_id, redirect_uri, response_type) cannot
+     *  be overridden. */
+    readonly extraParams?: Readonly<Record<string, string>>;
+}
+export interface X1idIdTokenClaims {
+    readonly iss: string;
+    /** The wallet address (base58). Your account key. */
+    readonly sub: string;
+    readonly aud: string | readonly string[];
+    readonly exp: number;
+    readonly iat: number;
+    readonly nonce?: string;
+    readonly azp?: string;
+    readonly auth_time?: number;
+    /** `["pop"]`: proof of possession of the wallet key at sign-in. */
+    readonly amr?: readonly string[];
+    readonly [k: string]: unknown;
+}
+/** `/me` claims, by scope (see services/auth/README.md "Scopes and claims"). */
+export interface X1idUserInfo {
+    readonly sub: string;
+    /** `profile`: the wallet's primary @handle (no `@`), read live from chain. */
+    readonly x1id_handle?: string;
+    readonly preferred_username?: string;
+    /** `profile`: the handle's https avatar. */
+    readonly picture?: string;
+    /** `wallet` */
+    readonly wallet_address?: string;
+    readonly wallet_chain?: string;
+    readonly [k: string]: unknown;
+}
+export interface X1idTokens {
+    readonly accessToken: string;
+    readonly tokenType: string;
+    /** ms since epoch, from `expires_in`. */
+    readonly expiresAt: number | undefined;
+    readonly refreshToken: string | undefined;
+    readonly scope: string | undefined;
+    readonly idToken: string | undefined;
+    readonly idTokenClaims: X1idIdTokenClaims | undefined;
+}
+export interface X1idLoginResult extends X1idTokens {
+    /** The wallet address that signed in (the verified ID token's `sub`). */
+    readonly sub: string;
+    readonly idToken: string;
+    readonly idTokenClaims: X1idIdTokenClaims;
+    /** Present unless `{ userInfo: false }` was passed. */
+    readonly userInfo: X1idUserInfo | undefined;
+}
+export interface X1idVerifyIdTokenOptions {
+    readonly issuer: string;
+    readonly clientId: string;
+    /** The nonce sent in the authorization request. Required for a login; omit
+     *  only for an ID token from a refresh. */
+    readonly nonce?: string;
+    /** Allowed `alg` values. */
+    readonly algorithms: readonly string[];
+    /** Resolve the verification key for a header. */
+    readonly getKey: (header: JwtHeader) => Promise<JsonWebKey | null>;
+    readonly clockSkewSecs?: number;
+    readonly now?: () => number;
+    readonly crypto?: Crypto;
+}
+export interface JwtHeader {
+    readonly alg: string;
+    readonly kid?: string;
+    readonly typ?: string;
+    readonly [k: string]: unknown;
+}
+/** `bytes` random bytes, base64url (32 bytes → 43 chars, 256 bits). */
+export declare function randomUrlSafe(bytes?: number, crypto?: Crypto): string;
+/** A fresh RFC 7636 code verifier: 32 random bytes → 43 base64url chars. */
+export declare function generateCodeVerifier(crypto?: Crypto): string;
+/** RFC 7636 S256: BASE64URL(SHA-256(ASCII(verifier))). */
+export declare function codeChallengeS256(verifier: string, crypto?: Crypto): Promise<string>;
+/** Decode a JWT without verifying it (for logging / inspection only). */
+export declare function decodeJwtUnverified(jwt: string): {
+    header: JwtHeader;
+    payload: Record<string, unknown>;
+};
+/**
+ * Verify an X1ID ID token: signature (only `algorithms`, never `none`/HS*),
+ * `iss` exact match, `aud` contains the client, `azp` (if present, or if
+ * several audiences) equals the client, `exp` in the future and `iat` not in
+ * the future (± `clockSkewSecs`), `nonce` equal to the one sent, `sub` a
+ * non-empty string. Returns the claims; throws `X1idAuthError("invalid_id_token")`.
+ */
+export declare function verifyX1idIdToken(jwt: string, o: X1idVerifyIdTokenOptions): Promise<X1idIdTokenClaims>;
+export interface X1idOidcClient {
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    /** Fetch (once, then cached) and validate the discovery document. */
+    discover(): Promise<X1idDiscovery>;
+    /** Build the authorization URL + the pending state to keep until the callback. */
+    createAuthorization(opts?: X1idAuthorizationOptions): Promise<{
+        url: string;
+        pending: X1idPendingLogin;
+    }>;
+    /**
+     * Handle the redirect back: check `state`, the RFC 9207 `iss` parameter and
+     * any `error`, exchange the code (PKCE), verify the ID token, fetch `/me`.
+     * Call it once per pending login (codes are single-use).
+     */
+    handleCallback(callbackUrl: string | URL, pending: X1idPendingLogin, opts?: {
+        userInfo?: boolean;
+    }): Promise<X1idLoginResult>;
+    /** Exchange a code directly (when you parsed the callback yourself). */
+    exchangeCode(code: string, pending: X1idPendingLogin): Promise<X1idTokens & {
+        idToken: string;
+        idTokenClaims: X1idIdTokenClaims;
+    }>;
+    /** Verify an ID token from this provider for this client. */
+    verifyIdToken(idToken: string, opts?: {
+        nonce?: string;
+    }): Promise<X1idIdTokenClaims>;
+    /** GET `/me` with an access token. Pass `expectedSub` (the ID token's sub) —
+     *  OIDC Core §5.3.2 requires the two to match. */
+    fetchUserInfo(accessToken: string, expectedSub?: string): Promise<X1idUserInfo>;
+    /** Refresh (rotating). An ID token in the response is verified; pass the
+     *  account's `sub` so a different subject is rejected. */
+    refresh(refreshToken: string, opts?: {
+        expectedSub?: string;
+    }): Promise<X1idTokens>;
+    /** RFC 7009 revocation of an access or refresh token. */
+    revoke(token: string, hint?: "access_token" | "refresh_token"): Promise<void>;
+    /** RP-initiated logout URL at auth.x1id.io. */
+    logoutUrl(opts?: {
+        idTokenHint?: string;
+        postLogoutRedirectUri?: string;
+        state?: string;
+    }): Promise<string>;
+}
+/** Create an RP client. Nothing is fetched until first use. */
+export declare function createX1idOidcClient(config: X1idOidcConfig): X1idOidcClient;
+/** Minimal Storage (sessionStorage, or a test double). */
+export interface X1idStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Start "Sign in with X1ID" in a browser: stores the pending login in
+ * `sessionStorage` (keyed by state, so two tabs don't collide) and navigates
+ * to auth.x1id.io. Pass `navigate` to handle the redirect yourself.
+ */
+export declare function beginX1idLogin(client: X1idOidcClient, opts?: X1idAuthorizationOptions & {
+    storage?: X1idStorage;
+    navigate?: (url: string) => void;
+}): Promise<string>;
+/**
+ * Finish the login on your redirect page: looks up (and removes — single use)
+ * the pending login for the callback's `state`, then runs
+ * {@link X1idOidcClient.handleCallback}. By default strips `code`/`state` from
+ * the address bar afterwards (`history.replaceState`).
+ */
+export declare function completeX1idLogin(client: X1idOidcClient, opts?: {
+    url?: string | URL;
+    storage?: X1idStorage;
+    userInfo?: boolean;
+    cleanUrl?: boolean;
+}): Promise<X1idLoginResult>;