@x1id/resolve 0.11.0 → 0.12.0

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,98 @@
+/**
+ * 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. Pass `onError: "allow"` to fail-open.
+ *
+ * @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,118 @@
+/**
+ * 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. Pass `onError: "allow"` to fail-open.
+ *
+ * @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";

package/dist/index.js

@@ -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";
 // Was previously imported here for internal use only, never re-exported —
 // promoted to public API 2026-09-22 because a second real package (mcp/)
@@ -57,8 +59,14 @@ export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
 export * from "./domainProof.js";
+// Named (not `export *`): `NAMESPACE_MAX_LEN` is already exported by
+// adminMarket.js, and two `export *` sharing a name would make it ambiguous
+// (dropped from the package's public surface). Re-export the scoped API, minus
+// that one equal-valued constant.
+export { scopedTldCandidate, namespaceIsActive, makeScopedHandleDeriver, } from "./scoped.js";
 import { ResolveError, CHAIN_COIN_TYPE } from "./types.js";
-import { parseName } from "./parse.js";
+import { parseName, normalizeHandle } from "./parse.js";
+import { scopedTldCandidate, namespaceIsActive, NAMESPACE_MAX_LEN, } from "./scoped.js";
 import { encodeBase58, decodeBase58_32 } from "./base58.js";
 import { DEFAULT_HANDLE_PROGRAM, TOKEN_ACCOUNT_MIN_LEN, bytesEqual, makeAccountReader, nftHolder, parseHandleAccount, readI64, readU64, } from "./accounts.js";
 import { fetchRecords, liveRecords } from "./records.js";
@@ -91,6 +99,7 @@ export function createResolver(config) {
     // Re-encoded (not the caller's string) so a non-canonical base58 spelling of
     // the same key still compares equal to the RPC's `owner` field.
     const programBase58 = encodeBase58(handleProgram);
+    const scopedDeriver = config.scopedHandleDeriver ?? null;
     async function resolveX1ns(canonical, label, tld, chain, input) {
         const account = config.wasm.deriveX1nsAccount(label, tld);
         if (!account) {
@@ -178,6 +187,109 @@ export function createResolver(config) {
             : await nftHolder(reader, config.wasm, canonical, handle.nftMint, input);
         return { input, name: canonical, namespace: "handle", address, chain, verification };
     }
+    /**
+     * Resolve a SCOPED customer-TLD name `name.tld` (#8484/#8485), or throw
+     * `unrecognized` when `.tld` is not one of OUR launched namespaces — so an
+     * unlaunched `.tld` behaves exactly as before (never a scoped hit). The
+     * contract mirrors `tools/api`'s `resolve_scoped`: canonicalize both halves
+     * as the program does, confirm `["namespace", tld]` is a program-owned Active
+     * `Namespace`, then derive `["handle", tld, name]` and read its CURRENT
+     * authority through the SAME owner/tokenization/record path a bare `@handle`
+     * uses — only the `name`/`namespace` fields differ (the TLD label).
+     */
+    async function resolveScoped(subRaw, tldRaw, chain, input) {
+        // The exact fall-through the native parser would have produced: a
+        // non-canonical half, or a `.tld` that is not a launched namespace, is
+        // simply "not a handle or a known domain" — never a misleading
+        // invalid-handle, and never a scoped hit on a name we do not own.
+        const notScoped = () => new ResolveError("unrecognized", `"${input.trim()}" is not a handle or a known domain`, input);
+        // Canonicalize both halves exactly as the program's `handle_normalize`
+        // does. A half that does not normalize can never name one of our scoped
+        // names — fall through rather than erroring (matches resolve_scoped).
+        let name;
+        let label;
+        try {
+            name = normalizeHandle(subRaw);
+            label = normalizeHandle(tldRaw);
+        }
+        catch {
+            throw notScoped();
+        }
+        if (label.length > NAMESPACE_MAX_LEN)
+            throw notScoped();
+        if (ttl > 0) {
+            const hit = cache.get(`scoped:${label}:${name}:${chain}`);
+            if (hit && hit.expires > Date.now())
+                return hit.value;
+        }
+        // Is `.label` a launched, Active X1ID namespace? Derive `["namespace",
+        // label]` via the WASM (canonical, always available) and read it. It must
+        // exist, be owned by the registry program, and carry `status == Active`.
+        const nsAccountKey = config.wasm.deriveNamespaceAccount(label, handleProgram);
+        if (!nsAccountKey)
+            throw notScoped();
+        const ns = await accountInfo(encodeBase58(nsAccountKey));
+        if (!ns || ns.owner !== programBase58 || !namespaceIsActive(ns.data)) {
+            // Not one of our launched namespaces — preserve today's behavior so an
+            // unlaunched `.tld` (and `.sol`/`.eth`, handled elsewhere) stays
+            // "unrecognized", never resolved through the wrong path.
+            throw notScoped();
+        }
+        // Confirmed a scoped X1ID name. From here any failure is a REAL error,
+        // never a silent fall-through (mirrors resolve_scoped's comment).
+        if (!scopedDeriver) {
+            throw new ResolveError("not-configured", `.${label} is a launched X1ID TLD, but scoped resolution needs a PDA deriver — install @solana/web3.js and pass scopedHandleDeriver (see makeScopedHandleDeriver)`, input);
+        }
+        let pda;
+        try {
+            pda = await scopedDeriver.scopedHandleKey(label, name, programBase58);
+        }
+        catch (e) {
+            throw new ResolveError("rpc-error", `scoped handle derivation failed: ${String(e)}`, input);
+        }
+        const h = await accountInfo(pda);
+        // An account at the PDA the registry does not own is not a handle — the
+        // scoped name is unregistered under this (live) TLD.
+        if (!h || h.owner !== programBase58) {
+            throw new ResolveError("not-found", `${name}.${label} is not registered`, input);
+        }
+        const handle = parseHandleAccount(h.data);
+        if (!handle) {
+            throw new ResolveError("rpc-error", `${name}.${label} returned a malformed account`, input);
+        }
+        const display = `${name}.${label}`;
+        let value;
+        if (chain !== "X1" && chain !== "SOL") {
+            // ETH/BTC addresses live in per-chain `Record` accounts — same staleness
+            // rule as a bare handle (fetchRecords → liveRecords).
+            const live = liveRecords(await fetchRecords(rpc, programBase58, pda, handle.registeredAt, handle.recordsClearedAt));
+            const record = live.find((r) => r.coinType === CHAIN_COIN_TYPE[chain]);
+            if (!record) {
+                throw new ResolveError("no-record-for-chain", `${display} has no ${chain} record`, input);
+            }
+            value = {
+                input,
+                name: display,
+                namespace: label,
+                address: record.address,
+                chain,
+                verification: record.verified ? "verified" : "unverified",
+            };
+        }
+        else {
+            // Same authority rule as a bare handle: untokenized → `Handle.owner`
+            // (verified); tokenized → whoever holds the NFT now (verified only in its
+            // ATA). A scoped name is always tokenized in practice, but both branches
+            // are kept so the shape is byte-identical to resolveHandle.
+            const { address, verification } = handle.nftMint === null
+                ? { address: encodeBase58(handle.owner), verification: "verified" }
+                : await nftHolder(reader, config.wasm, display, handle.nftMint, input);
+            value = { input, name: display, namespace: label, address, chain, verification };
+        }
+        if (ttl > 0)
+            cache.set(`scoped:${label}:${name}:${chain}`, { value, expires: Date.now() + ttl });
+        return value;
+    }
     /** See `Resolver.records`. */
     async function records(input) {
         const parsed = parseName(input); // throws with a specific code
@@ -189,7 +301,24 @@ export function createResolver(config) {
     }
     async function resolve(input, opts) {
         const chain = opts?.chain ?? "X1";
-        const parsed = parseName(input); // throws with a specific code
+        let parsed;
+        try {
+            parsed = parseName(input); // throws with a specific code
+        }
+        catch (e) {
+            // A dotted, non-`@`, non-X1NS name is `unrecognized` to the strict native
+            // parser — but it MAY be a scoped customer-TLD name `name.tld` (#8484/
+            // #8485). Try that before giving up; `resolveScoped` itself re-throws the
+            // same `unrecognized` when `.tld` is not a launched namespace, so
+            // `.sol`/`.eth`/unknown TLDs behave exactly as before. Any other code
+            // (ambiguous / invalid-*) is preserved verbatim.
+            if (e instanceof ResolveError && e.code === "unrecognized") {
+                const cand = scopedTldCandidate(input);
+                if (cand)
+                    return resolveScoped(cand.sub, cand.tld, chain, input);
+            }
+            throw e;
+        }
         const key = `${parsed.namespace}:${parsed.canonical}:${chain}`;
         if (ttl > 0) {
             const hit = cache.get(key);
@@ -304,3 +433,9 @@ export function createResolver(config) {
         clearCache: () => cache.clear(),
     };
 }
+export * from "./adminMarket.js";
+export * from "./namespaceOverride.js";
+// The X1ID Universal Resolver (#8475): cross-namespace resolution (.sol via SNS,
+// .eth via ENS) alongside the native path. Additive — the native resolver above
+// is untouched; `createUniversalResolver` composes it with external adapters.
+export * from "./universal.js";