@x1id/resolve 0.11.0 → 0.13.0

package/dist/attestation.d.ts

@@ -91,6 +91,14 @@ export declare const ATTESTATION_KIND_TELEGRAM = 5;
  *  `>=` this on-chain; the SDK's builder enforces the same bound. Mirrors
  *  `Attestation::KIND_COUNT` (programs/x1-handles/src/state.rs). */
 export declare const ATTESTATION_KIND_COUNT = 6;
+/** `Attestation.kind` — validator control proven TRUSTLESSLY on-chain (#8486):
+ *  the vote account's `authorized_withdrawer` co-signed `attest_validator`, or
+ *  signed the challenge that `attest_validator_signed` verifies via the Ed25519
+ *  precompile. Value 6 — equal to {@link ATTESTATION_KIND_COUNT}, i.e. OUTSIDE
+ *  the attestor-mintable range (`create_attestation` refuses `>= KIND_COUNT`),
+ *  so only the cryptographic validator path can mint it. `evidenceHash` holds
+ *  the vote account pubkey; surfaced as a gold shield, not the blue tick. */
+export declare const ATTESTATION_KIND_VALIDATOR = 6;
 /** Anchor account discriminator: `sha256("account:Attestation")[0..8]`.
  *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
  *  everywhere it runs); asserted against a re-derivation in the test suite
@@ -104,6 +112,18 @@ export declare const SET_ATTESTOR_DISCRIMINATOR: Uint8Array;
 export declare const CREATE_ATTESTATION_DISCRIMINATOR: Uint8Array;
 /** Anchor instruction discriminator: `sha256("global:close_attestation")[0..8]`. */
 export declare const CLOSE_ATTESTATION_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:attest_validator")[0..8]` — the co-sign path. */
+export declare const ATTEST_VALIDATOR_DISCRIMINATOR: Uint8Array;
+/** Anchor instruction discriminator: `sha256("global:attest_validator_signed")[0..8]` — the detached path. */
+export declare const ATTEST_VALIDATOR_SIGNED_DISCRIMINATOR: Uint8Array;
+/** The SVM Ed25519 signature-verification precompile — carries the withdraw
+ *  authority's detached signature for `attest_validator_signed`. */
+export declare const ED25519_PROGRAM_ID = "Ed25519SigVerify111111111111111111111111111";
+/** The Instructions sysvar — `attest_validator_signed` introspects it. */
+export declare const SYSVAR_INSTRUCTIONS_ID = "Sysvar1nstructions1111111111111111111111111";
+/** Domain-separator prefix of the validator-attestation challenge. MUST byte-
+ *  match `VALIDATOR_ATTEST_CHALLENGE_PREFIX` in programs/x1-handles/src/lib.rs. */
+export declare const VALIDATOR_ATTEST_CHALLENGE_PREFIX: Uint8Array;
 /** `Attestation` account size — every field is fixed-width, so unlike a
  *  `Handle` the account is exactly this long:
  *  disc(8) + handle(32) + kind(1) + evidence_hash(32) + attested_at(8)
@@ -112,7 +132,7 @@ export declare const ATTESTATION_LEN = 114;
 /** `AttestorConfig` account size: disc(8) + attestor(32) + bump(1). */
 export declare const ATTESTOR_CONFIG_LEN = 41;
 /** Human name an attestation `kind` byte carries. */
-export type AttestationKindName = "dns" | "social" | "x" | "discord" | "github" | "telegram";
+export type AttestationKindName = "dns" | "social" | "x" | "discord" | "github" | "telegram" | "validator";
 /** Which verification signal an attestation `kind` byte names, or null for a
  *  kind this SDK does not know (future program versions may add kinds). For the
  *  per-platform kinds this returns the platform slug; the two legacy kinds keep
@@ -272,6 +292,88 @@ export interface CloseAttestationParams {
  * a rotated-away key's output).
  */
 export declare function buildCloseAttestationIx(p: CloseAttestationParams): BuiltInstruction;
+export interface AttestValidatorParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's authority (owner, or NFT holder if tokenized); signs + pays rent. */
+    readonly owner: AddressLike;
+    /** The vote account's withdraw authority; co-signs (MAY equal `owner`). */
+    readonly withdrawAuthority: AddressLike;
+    /** The `["handle", name]` PDA. */
+    readonly handle: AddressLike;
+    /** The validator's vote account (owned by the Vote program on-chain). */
+    readonly voteAccount: AddressLike;
+    /** The `["attestation", handle, [KIND_VALIDATOR]]` PDA. */
+    readonly attestation: AddressLike;
+    /** ONLY for a tokenized handle: the caller's associated token account for the
+     *  handle's NFT mint (the holder-proof `require_current_authority` reads). */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build `attest_validator` (co-sign path). Two signers — `owner` (authorizes
+ * the link) and `withdrawAuthority` (the proof) — which MAY be the same key. No
+ * instruction args: the co-signature IS the proof.
+ */
+export declare function buildAttestValidatorIx(p: AttestValidatorParams): BuiltInstruction;
+/**
+ * The exact 96-byte challenge the withdraw authority signs for the DETACHED
+ * path: `PREFIX(24) ‖ handle(32) ‖ voteAccount(32) ‖ registeredAt i64 LE(8)`.
+ * MUST byte-match the program. `registeredAt` is the handle's on-chain
+ * `registered_at` (seconds) — pass the exact value from the Handle account.
+ */
+export declare function validatorAttestChallenge(handle: AddressLike, voteAccount: AddressLike, registeredAt: bigint | number): Uint8Array;
+export interface Ed25519VerifyParams {
+    /** The 32-byte ed25519 public key (the withdraw authority). */
+    readonly publicKey: AddressLike;
+    /** The signed message (the validator challenge). */
+    readonly message: Uint8Array;
+    /** The 64-byte ed25519 signature over `message` by `publicKey`. */
+    readonly signature: Uint8Array;
+}
+/**
+ * Build the Ed25519 precompile instruction (no accounts) proving `signature` is
+ * `publicKey`'s over `message`. SELF-CONTAINED single signature — all three
+ * instruction-index fields are `0xFFFF` — matching the exact layout
+ * `attest_validator_signed` requires. Place it IMMEDIATELY BEFORE the attest ix
+ * (use {@link buildAttestValidatorSignedIxs}).
+ */
+export declare function buildEd25519VerifyIx(p: Ed25519VerifyParams): BuiltInstruction;
+export interface AttestValidatorSignedParams {
+    /** The registry program id. */
+    readonly programId: AddressLike;
+    /** The handle's authority (owner / NFT holder); the SOLE tx signer, pays rent. */
+    readonly owner: AddressLike;
+    readonly handle: AddressLike;
+    readonly voteAccount: AddressLike;
+    /** The `["attestation", handle, [KIND_VALIDATOR]]` PDA. */
+    readonly attestation: AddressLike;
+    /** ONLY for a tokenized handle: the caller's ATA for the handle's NFT mint. */
+    readonly holderTokenAccount?: AddressLike;
+}
+/**
+ * Build the `attest_validator_signed` ix ALONE. The withdraw authority's proof
+ * is NOT here — it rides in the Ed25519 precompile ix that MUST immediately
+ * precede this one. Prefer {@link buildAttestValidatorSignedIxs}, which returns
+ * both, in order. No instruction args.
+ */
+export declare function buildAttestValidatorSignedIx(p: AttestValidatorSignedParams): BuiltInstruction;
+export interface AttestValidatorSignedTxParams extends AttestValidatorSignedParams {
+    /** The vote account's `authorized_withdrawer` (32-byte ed25519 pubkey) whose
+     *  offline signature over the challenge this carries. */
+    readonly withdrawAuthority: AddressLike;
+    /** The 64-byte ed25519 signature over {@link validatorAttestChallenge},
+     *  produced offline by the withdraw authority. */
+    readonly signature: Uint8Array;
+    /** The handle's on-chain `registered_at` (seconds). */
+    readonly registeredAt: bigint | number;
+}
+/**
+ * Build BOTH instructions for the detached path, IN ORDER:
+ * `[ed25519VerifyIx, attestValidatorSignedIx]`. Submit them as ONE transaction
+ * in this order — the program loads the ed25519 ix at `current_index - 1`.
+ * `owner` is the only signer.
+ */
+export declare function buildAttestValidatorSignedIxs(p: AttestValidatorSignedTxParams): BuiltInstruction[];
 /** The minimal shape the verification helpers read — any {@link Resolved}
  *  satisfies it, as does a bare `{ verifications }` an integrator assembles
  *  from a raw REST payload. */

package/dist/attestation.js

@@ -90,6 +90,14 @@ export const ATTESTATION_KIND_TELEGRAM = 5;
  *  `>=` this on-chain; the SDK's builder enforces the same bound. Mirrors
  *  `Attestation::KIND_COUNT` (programs/x1-handles/src/state.rs). */
 export const ATTESTATION_KIND_COUNT = 6;
+/** `Attestation.kind` — validator control proven TRUSTLESSLY on-chain (#8486):
+ *  the vote account's `authorized_withdrawer` co-signed `attest_validator`, or
+ *  signed the challenge that `attest_validator_signed` verifies via the Ed25519
+ *  precompile. Value 6 — equal to {@link ATTESTATION_KIND_COUNT}, i.e. OUTSIDE
+ *  the attestor-mintable range (`create_attestation` refuses `>= KIND_COUNT`),
+ *  so only the cryptographic validator path can mint it. `evidenceHash` holds
+ *  the vote account pubkey; surfaced as a gold shield, not the blue tick. */
+export const ATTESTATION_KIND_VALIDATOR = 6;
 /** Anchor account discriminator: `sha256("account:Attestation")[0..8]`.
  *  Pinned (this SDK is zero-dependency and cannot assume WebCrypto SHA-256
  *  everywhere it runs); asserted against a re-derivation in the test suite
@@ -113,6 +121,22 @@ export const CREATE_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
 export const CLOSE_ATTESTATION_DISCRIMINATOR = Uint8Array.from([
     249, 84, 133, 23, 48, 175, 252, 221,
 ]);
+/** Anchor instruction discriminator: `sha256("global:attest_validator")[0..8]` — the co-sign path. */
+export const ATTEST_VALIDATOR_DISCRIMINATOR = Uint8Array.from([
+    170, 159, 195, 248, 59, 130, 28, 168,
+]);
+/** Anchor instruction discriminator: `sha256("global:attest_validator_signed")[0..8]` — the detached path. */
+export const ATTEST_VALIDATOR_SIGNED_DISCRIMINATOR = Uint8Array.from([
+    160, 18, 26, 117, 233, 252, 230, 221,
+]);
+/** The SVM Ed25519 signature-verification precompile — carries the withdraw
+ *  authority's detached signature for `attest_validator_signed`. */
+export const ED25519_PROGRAM_ID = "Ed25519SigVerify111111111111111111111111111";
+/** The Instructions sysvar — `attest_validator_signed` introspects it. */
+export const SYSVAR_INSTRUCTIONS_ID = "Sysvar1nstructions1111111111111111111111111";
+/** Domain-separator prefix of the validator-attestation challenge. MUST byte-
+ *  match `VALIDATOR_ATTEST_CHALLENGE_PREFIX` in programs/x1-handles/src/lib.rs. */
+export const VALIDATOR_ATTEST_CHALLENGE_PREFIX = new TextEncoder().encode("x1id:validator-attest:v1");
 /** `Attestation` account size — every field is fixed-width, so unlike a
  *  `Handle` the account is exactly this long:
  *  disc(8) + handle(32) + kind(1) + evidence_hash(32) + attested_at(8)
@@ -157,6 +181,8 @@ export function attestationKindName(kind) {
             return "github";
         case ATTESTATION_KIND_TELEGRAM:
             return "telegram";
+        case ATTESTATION_KIND_VALIDATOR:
+            return "validator";
         default:
             return null;
     }
@@ -177,6 +203,8 @@ export function platformSlug(kind) {
             return "github";
         case ATTESTATION_KIND_TELEGRAM:
             return "telegram";
+        case ATTESTATION_KIND_VALIDATOR:
+            return "validator";
         default:
             return null;
     }
@@ -365,6 +393,102 @@ export function buildCloseAttestationIx(p) {
         data: CLOSE_ATTESTATION_DISCRIMINATOR.slice(),
     };
 }
+/**
+ * Build `attest_validator` (co-sign path). Two signers — `owner` (authorizes
+ * the link) and `withdrawAuthority` (the proof) — which MAY be the same key. No
+ * instruction args: the co-signature IS the proof.
+ */
+export function buildAttestValidatorIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.withdrawAuthority, "withdrawAuthority"), isSigner: true, isWritable: false },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.voteAccount, "voteAccount"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestation, "attestation"), isSigner: false, isWritable: true },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data: ATTEST_VALIDATOR_DISCRIMINATOR.slice() };
+}
+/**
+ * The exact 96-byte challenge the withdraw authority signs for the DETACHED
+ * path: `PREFIX(24) ‖ handle(32) ‖ voteAccount(32) ‖ registeredAt i64 LE(8)`.
+ * MUST byte-match the program. `registeredAt` is the handle's on-chain
+ * `registered_at` (seconds) — pass the exact value from the Handle account.
+ */
+export function validatorAttestChallenge(handle, voteAccount, registeredAt) {
+    const out = new Uint8Array(24 + 32 + 32 + 8);
+    out.set(VALIDATOR_ATTEST_CHALLENGE_PREFIX, 0);
+    out.set(toBytes32(handle, "handle"), 24);
+    out.set(toBytes32(voteAccount, "voteAccount"), 56);
+    new DataView(out.buffer, out.byteOffset, out.byteLength).setBigInt64(88, BigInt(registeredAt), true);
+    return out;
+}
+/**
+ * Build the Ed25519 precompile instruction (no accounts) proving `signature` is
+ * `publicKey`'s over `message`. SELF-CONTAINED single signature — all three
+ * instruction-index fields are `0xFFFF` — matching the exact layout
+ * `attest_validator_signed` requires. Place it IMMEDIATELY BEFORE the attest ix
+ * (use {@link buildAttestValidatorSignedIxs}).
+ */
+export function buildEd25519VerifyIx(p) {
+    const pk = toBytes32(p.publicKey, "publicKey");
+    if (p.signature.length !== 64)
+        throw new Error("signature must be exactly 64 bytes");
+    const SELF = 0xffff;
+    const PK_OFF = 16;
+    const SIG_OFF = 48;
+    const MSG_OFF = 112;
+    const data = new Uint8Array(MSG_OFF + p.message.length);
+    data[0] = 1; // num_signatures
+    data[1] = 0; // padding
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    dv.setUint16(2, SIG_OFF, true);
+    dv.setUint16(4, SELF, true); // signature_instruction_index
+    dv.setUint16(6, PK_OFF, true);
+    dv.setUint16(8, SELF, true); // public_key_instruction_index
+    dv.setUint16(10, MSG_OFF, true);
+    dv.setUint16(12, p.message.length, true); // message_data_size
+    dv.setUint16(14, SELF, true); // message_instruction_index
+    data.set(pk, PK_OFF);
+    data.set(p.signature, SIG_OFF);
+    data.set(p.message, MSG_OFF);
+    return { programId: ED25519_PROGRAM_ID, keys: [], data };
+}
+/**
+ * Build the `attest_validator_signed` ix ALONE. The withdraw authority's proof
+ * is NOT here — it rides in the Ed25519 precompile ix that MUST immediately
+ * precede this one. Prefer {@link buildAttestValidatorSignedIxs}, which returns
+ * both, in order. No instruction args.
+ */
+export function buildAttestValidatorSignedIx(p) {
+    const keys = [
+        { pubkey: toBase58(p.owner, "owner"), isSigner: true, isWritable: true },
+        { pubkey: toBase58(p.handle, "handle"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.voteAccount, "voteAccount"), isSigner: false, isWritable: false },
+        { pubkey: toBase58(p.attestation, "attestation"), isSigner: false, isWritable: true },
+        { pubkey: SYSVAR_INSTRUCTIONS_ID, isSigner: false, isWritable: false },
+        { pubkey: SYSTEM_PROGRAM, isSigner: false, isWritable: false },
+    ];
+    if (p.holderTokenAccount !== undefined) {
+        keys.push({ pubkey: toBase58(p.holderTokenAccount, "holderTokenAccount"), isSigner: false, isWritable: false });
+    }
+    return { programId: toBase58(p.programId, "programId"), keys, data: ATTEST_VALIDATOR_SIGNED_DISCRIMINATOR.slice() };
+}
+/**
+ * Build BOTH instructions for the detached path, IN ORDER:
+ * `[ed25519VerifyIx, attestValidatorSignedIx]`. Submit them as ONE transaction
+ * in this order — the program loads the ed25519 ix at `current_index - 1`.
+ * `owner` is the only signer.
+ */
+export function buildAttestValidatorSignedIxs(p) {
+    const message = validatorAttestChallenge(p.handle, p.voteAccount, p.registeredAt);
+    const ed = buildEd25519VerifyIx({ publicKey: p.withdrawAuthority, message, signature: p.signature });
+    const attest = buildAttestValidatorSignedIx(p);
+    return [ed, attest];
+}
 /**
  * The platform slugs a handle is LIVE-verified on — e.g. `["x", "github"]` —
  * de-duplicated, in first-seen order. Only entries with `verified === true`

package/dist/gateClient.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Gate middleware — the drop-in "gate this route" client for X1ID Gate
+ * (gating-as-a-service, #8453). A tiny, framework-agnostic helper that calls the
+ * hosted `POST /v1/gate/check` decision endpoint (api.x1id.io) so a dapp does not
+ * run its own attestation reads. Pairs with the off-chain {@link Gate} /
+ * {@link GateKind} this package already exports.
+ *
+ * Zero-dependency (uses `fetch`); runs anywhere a server runtime has `fetch`
+ * (Node 18+, Next route handlers, edge, Workers). It is a SERVER helper — your
+ * X1ID API key must never ship to a browser.
+ *
+ * Trust: a `passed: true` means the handle carries a live, x1id-attestor-signed
+ * attestation matching the policy — "verified by x1id", NOT trustless proof and
+ * NOT legal personhood. Gate on it accordingly.
+ */
+import type { Gate } from "./gate.js";
+/** Default hosted Gate base URL. Override for staging / self-host. */
+export declare const DEFAULT_GATE_BASE_URL = "https://api.x1id.io";
+export interface GateClientConfig {
+    /** Your X1ID API key (`x1id_…` / `x1idlive_…`). SERVER-ONLY — never expose it. */
+    readonly apiKey: string;
+    /** Base URL of the /v1 API. Defaults to {@link DEFAULT_GATE_BASE_URL}. */
+    readonly baseUrl?: string;
+    /** Inject a `fetch` (tests, non-global-fetch runtimes). */
+    readonly fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms (default 10_000). */
+    readonly timeoutMs?: number;
+}
+/** Exactly one of `handle` / `wallet`. */
+export type GateSubject = {
+    readonly handle: string;
+    readonly wallet?: never;
+} | {
+    readonly wallet: string;
+    readonly handle?: never;
+};
+/** A policy to evaluate: an inline {@link Gate}, or a stored policy id (`gp_…`). */
+export type GatePolicy = Gate | string;
+export interface GateAttestationView {
+    readonly platform: string;
+    readonly kind: number;
+    readonly attested_at: number;
+}
+/** The decision the service returned. */
+export interface GateCheckResult {
+    readonly passed: boolean;
+    readonly subject: {
+        readonly handle: string | null;
+        readonly wallet: string | null;
+    };
+    readonly policy: Gate;
+    readonly attestations: readonly GateAttestationView[];
+    readonly reason?: "no-primary-handle" | "handle-not-registered";
+}
+/** Thrown when the decision could not be obtained (network, auth, 5xx, bad
+ *  input). NOT thrown for a clean `passed: false` — that is a valid decision. */
+export declare class GateError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+/**
+ * Low-level: ask the hosted service whether `subject` passes `policy`. Resolves
+ * to the decision (including a clean `passed: false`); throws {@link GateError}
+ * only when no decision could be obtained.
+ */
+export declare function checkGate(cfg: GateClientConfig, subject: GateSubject, policy: GatePolicy): Promise<GateCheckResult>;
+export interface GuardResult {
+    /** Whether the subject passes the policy. */
+    readonly allowed: boolean;
+    /** The full decision (attestations, reason, …). */
+    readonly decision: GateCheckResult;
+}
+/**
+ * Build a reusable guard for one policy. The returned function takes a subject
+ * and resolves to `{ allowed, decision }`.
+ *
+ * Fail-closed by default: if the decision cannot be obtained (network/5xx), the
+ * guard RE-THROWS {@link GateError} so your route returns an error rather than
+ * silently admitting an unverified caller. `onError: "deny"` instead resolves to
+ * a clean `allowed: false` (fail-closed without a throw).
+ *
+ * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN. On ANY error (network blip,
+ * timeout, 5xx, auth failure, a malformed response) it fabricates a
+ * `passed: true` decision and admits the caller UNVERIFIED. NEVER use it for a
+ * real access gate — anyone who can make your gate call fail (trivial: induce a
+ * timeout) then bypasses it completely. It exists ONLY for soft, non-security
+ * personalization where a missing verification must not degrade UX (e.g.
+ * optionally showing a "verified" flourish). If the gate protects anything —
+ * a route, a mint, an airdrop, a write — use the default `"throw"` or `"deny"`.
+ *
+ * @example
+ * ```ts
+ * import { requireGate, GateKind } from "@x1id/resolve";
+ * const gate = requireGate({ apiKey: process.env.X1ID_API_KEY! }, { kind: GateKind.github });
+ *
+ * // Next.js Route Handler
+ * export async function POST(req: Request) {
+ *   const { handle } = await req.json();
+ *   const { allowed } = await gate({ handle });
+ *   if (!allowed) return Response.json({ error: "verified GitHub required" }, { status: 403 });
+ *   // …proceed
+ * }
+ * ```
+ */
+export declare function requireGate(cfg: GateClientConfig, policy: GatePolicy, opts?: {
+    readonly onError?: "throw" | "allow" | "deny";
+}): (subject: GateSubject) => Promise<GuardResult>;

package/dist/gateClient.js

@@ -0,0 +1,128 @@
+/**
+ * Gate middleware — the drop-in "gate this route" client for X1ID Gate
+ * (gating-as-a-service, #8453). A tiny, framework-agnostic helper that calls the
+ * hosted `POST /v1/gate/check` decision endpoint (api.x1id.io) so a dapp does not
+ * run its own attestation reads. Pairs with the off-chain {@link Gate} /
+ * {@link GateKind} this package already exports.
+ *
+ * Zero-dependency (uses `fetch`); runs anywhere a server runtime has `fetch`
+ * (Node 18+, Next route handlers, edge, Workers). It is a SERVER helper — your
+ * X1ID API key must never ship to a browser.
+ *
+ * Trust: a `passed: true` means the handle carries a live, x1id-attestor-signed
+ * attestation matching the policy — "verified by x1id", NOT trustless proof and
+ * NOT legal personhood. Gate on it accordingly.
+ */
+/** Default hosted Gate base URL. Override for staging / self-host. */
+export const DEFAULT_GATE_BASE_URL = "https://api.x1id.io";
+/** Thrown when the decision could not be obtained (network, auth, 5xx, bad
+ *  input). NOT thrown for a clean `passed: false` — that is a valid decision. */
+export class GateError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "GateError";
+    }
+}
+function baseUrlOf(cfg) {
+    return (cfg.baseUrl ?? DEFAULT_GATE_BASE_URL).replace(/\/+$/, "");
+}
+/**
+ * Low-level: ask the hosted service whether `subject` passes `policy`. Resolves
+ * to the decision (including a clean `passed: false`); throws {@link GateError}
+ * only when no decision could be obtained.
+ */
+export async function checkGate(cfg, subject, policy) {
+    const doFetch = cfg.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function")
+        throw new GateError("NO_FETCH", "no fetch available; pass fetchImpl in the config");
+    if (!cfg.apiKey)
+        throw new GateError("NO_API_KEY", "an X1ID apiKey is required");
+    const url = `${baseUrlOf(cfg)}/v1/gate/check`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), cfg.timeoutMs ?? 10_000);
+    let res;
+    try {
+        res = await doFetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-api-key": cfg.apiKey },
+            body: JSON.stringify({ ...subject, policy }),
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        throw new GateError("REQUEST_FAILED", `gate request failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        throw new GateError("BAD_RESPONSE", `gate returned non-JSON (HTTP ${res.status})`, res.status);
+    }
+    if (!res.ok) {
+        const b = (body ?? {});
+        throw new GateError(b.code ?? "GATE_HTTP_ERROR", b.message ?? `gate returned HTTP ${res.status}`, res.status);
+    }
+    return body;
+}
+/**
+ * Build a reusable guard for one policy. The returned function takes a subject
+ * and resolves to `{ allowed, decision }`.
+ *
+ * Fail-closed by default: if the decision cannot be obtained (network/5xx), the
+ * guard RE-THROWS {@link GateError} so your route returns an error rather than
+ * silently admitting an unverified caller. `onError: "deny"` instead resolves to
+ * a clean `allowed: false` (fail-closed without a throw).
+ *
+ * ⚠️ SECURITY — `onError: "allow"` FAILS OPEN. On ANY error (network blip,
+ * timeout, 5xx, auth failure, a malformed response) it fabricates a
+ * `passed: true` decision and admits the caller UNVERIFIED. NEVER use it for a
+ * real access gate — anyone who can make your gate call fail (trivial: induce a
+ * timeout) then bypasses it completely. It exists ONLY for soft, non-security
+ * personalization where a missing verification must not degrade UX (e.g.
+ * optionally showing a "verified" flourish). If the gate protects anything —
+ * a route, a mint, an airdrop, a write — use the default `"throw"` or `"deny"`.
+ *
+ * @example
+ * ```ts
+ * import { requireGate, GateKind } from "@x1id/resolve";
+ * const gate = requireGate({ apiKey: process.env.X1ID_API_KEY! }, { kind: GateKind.github });
+ *
+ * // Next.js Route Handler
+ * export async function POST(req: Request) {
+ *   const { handle } = await req.json();
+ *   const { allowed } = await gate({ handle });
+ *   if (!allowed) return Response.json({ error: "verified GitHub required" }, { status: 403 });
+ *   // …proceed
+ * }
+ * ```
+ */
+export function requireGate(cfg, policy, opts = {}) {
+    const onError = opts.onError ?? "throw";
+    return async (subject) => {
+        try {
+            const decision = await checkGate(cfg, subject, policy);
+            return { allowed: decision.passed, decision };
+        }
+        catch (e) {
+            if (onError === "throw")
+                throw e;
+            const handle = "handle" in subject && subject.handle ? subject.handle : null;
+            const wallet = "wallet" in subject && subject.wallet ? subject.wallet : null;
+            const decision = {
+                passed: onError === "allow",
+                subject: { handle, wallet },
+                policy: policy,
+                attestations: [],
+            };
+            return { allowed: onError === "allow", decision };
+        }
+    };
+}

package/dist/index.d.ts

@@ -35,12 +35,14 @@ export * from "./subname.js";
 export * from "./recordCount.js";
 export * from "./attestation.js";
 export * from "./gate.js";
+export * from "./gateClient.js";
 export * from "./textRecords.js";
 export * from "./lock.js";
 export * from "./integrator.js";
 export * from "./voucher.js";
 export * from "./agent.js";
 export * from "./register.js";
+export * from "./adminConfig.js";
 export * from "./lease.js";
 export * from "./accounts.js";
 export * from "./x402.js";
@@ -50,7 +52,9 @@ export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
 export * from "./domainProof.js";
+export { scopedTldCandidate, namespaceIsActive, makeScopedHandleDeriver, type ScopedCandidate, type ScopedHandleDeriver, } from "./scoped.js";
 import { type Chain, type Resolved } from "./types.js";
+import { type ScopedHandleDeriver } from "./scoped.js";
 import { WasmResolver } from "./wasm.js";
 import { type HandleRecord } from "./records.js";
 export interface ResolverConfig {
@@ -69,6 +73,18 @@ export interface ResolverConfig {
     readonly cacheTtlMs?: number;
     /** @handle registry program id. Defaults to the canonical X1 deployment. */
     readonly handleProgramId?: string;
+    /**
+     * Deriver for a SCOPED customer-TLD name's `["handle", tld, name]` PDA
+     * (`alices.testtld`, #8484/#8485). Optional and only used for scoped names:
+     * `@handle` and X1NS resolution never touch it. The WASM module has no
+     * two-seed scoped-handle derivation and this package never hand-rolls the
+     * on-curve check (see scoped.ts), so a scoped name is resolvable only when a
+     * deriver is injected — build the default with
+     * {@link makeScopedHandleDeriver} (needs `@solana/web3.js`), or pass a mock.
+     * Absent → a scoped name whose `.tld` IS a launched namespace throws
+     * `not-configured`; unlaunched `.tld`s stay `unrecognized`, unchanged.
+     */
+    readonly scopedHandleDeriver?: ScopedHandleDeriver;
 }
 export interface ResolveOptions {
     /** Which chain's address to return. Default "X1". */
@@ -103,3 +119,6 @@ export interface Resolver {
     clearCache(): void;
 }
 export declare function createResolver(config: ResolverConfig): Resolver;
+export * from "./adminMarket.js";
+export * from "./namespaceOverride.js";
+export * from "./universal.js";