@x1id/resolve 0.13.0 → 0.15.0

package/dist/connect.d.ts

@@ -0,0 +1,174 @@
+/**
+ * X1ID Connect — the TRANSACTION-signature sign-in client (#8452, verify-tx).
+ *
+ * # Why a transaction, not a message
+ *
+ * The message path ({@link import("./signin.js").signInWithX1ID}) asks the
+ * wallet to `signMessage` the challenge bytes. Two real wallets break that on
+ * X1:
+ *   - a Ledger (via Phantom/Backpack) REFUSES off-chain message signing; and
+ *   - Backpack on X1 returns `signMessage` signatures that DO NOT verify under
+ *     the wallet's own pubkey, even though its TRANSACTION signatures are valid
+ *     on-chain.
+ *
+ * So this flow proves wallet control a different, robust way: the wallet signs a
+ * throwaway MEMO TRANSACTION — one SPL-Memo instruction carrying
+ * `x1id-verify:<nonce>`, fee-paid by the wallet, never broadcast. The hosted
+ * `POST /v1/auth/verify-tx` endpoint deserializes the signed artifact, asserts
+ * it is EXACTLY that memo (no disguised transfer/approval), that the fee payer
+ * is the wallet, that the memo binds our single-use nonce, and verifies the
+ * ed25519 transaction signature. A valid proof mints the same Bearer session the
+ * message path does.
+ *
+ * This is the WALLET-control (no primary `@handle`) path — the app.x1id.io model
+ * where the connected wallet IS the identity, with the `@handle` as optional
+ * metadata. A handle-gated sign-in keeps the full on-chain control proof.
+ *
+ * # web3.js is injected, not depended on
+ *
+ * `@solana/web3.js` is an OPTIONAL peer dependency of this package (see
+ * scoped.ts / universalSns.ts). {@link buildVerifyTxChallenge} therefore takes
+ * the `{ Transaction, TransactionInstruction, PublicKey }` constructors as an
+ * injected {@link VerifyTxWeb3} rather than importing them — the SDK core stays
+ * free of a hard web3 dependency and tests can supply a fake.
+ */
+/** Memo prefix the verify-tx proof binds to. The signed memo instruction's
+ *  UTF-8 data MUST be EXACTLY `x1id-verify:<nonce>` — the server rejects any
+ *  other data, which is what kills replay of an unrelated signed transaction. */
+export declare const VERIFY_TX_MEMO_PREFIX: "x1id-verify:";
+/** Canonical SPL Memo program id — the program the challenge memo rides on. */
+export declare const MEMO_PROGRAM_ID: "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+/** The exact memo string for a given challenge nonce. */
+export declare function verifyTxMemo(nonce: string): string;
+/** The slice of a web3.js `PublicKey` used here. */
+export interface PublicKeyInstance {
+    toBytes(): Uint8Array;
+    toBase58(): string;
+}
+export interface PublicKeyCtor {
+    new (value: string | Uint8Array): PublicKeyInstance;
+}
+/** The slice of a web3.js `TransactionInstruction` constructor used here. */
+export interface TransactionInstructionCtor {
+    new (args: {
+        keys: ReadonlyArray<{
+            pubkey: PublicKeyInstance;
+            isSigner: boolean;
+            isWritable: boolean;
+        }>;
+        programId: PublicKeyInstance;
+        data: Uint8Array;
+    }): unknown;
+}
+/** The slice of a web3.js legacy `Transaction` instance used here. */
+export interface TransactionInstance {
+    add(instruction: unknown): TransactionInstance;
+    feePayer: PublicKeyInstance | null | undefined;
+    recentBlockhash: string | undefined;
+    /** Serialize the fully-signed transaction to raw bytes. */
+    serialize(options?: unknown): Uint8Array;
+}
+export interface TransactionCtor {
+    new (): TransactionInstance;
+}
+/** The three web3.js constructors {@link buildVerifyTxChallenge} needs. Pass the
+ *  module (`import * as web3 from "@solana/web3.js"`) or a `{ Transaction,
+ *  TransactionInstruction, PublicKey }` subset — exactly as the scoped deriver
+ *  takes `web3`. */
+export interface VerifyTxWeb3 {
+    readonly Transaction: TransactionCtor;
+    readonly TransactionInstruction: TransactionInstructionCtor;
+    readonly PublicKey: PublicKeyCtor;
+}
+/** 32 zero-bytes in base58 — a structurally valid blockhash. The transaction is
+ *  NEVER broadcast, so a placeholder blockhash is fine; a wallet that insists on
+ *  a fresh one can pass its own in {@link BuildVerifyTxChallengeParams.blockhash}. */
+export declare const PLACEHOLDER_BLOCKHASH: "11111111111111111111111111111111";
+export interface BuildVerifyTxChallengeParams {
+    /** The single-use nonce from the tx-mode challenge. */
+    readonly nonce: string;
+    /** The memo the server returned (`x1id-verify:<nonce>`). Optional — derived
+     *  from `nonce` when omitted; when supplied it MUST equal that, or the build
+     *  throws (catches a client that paired the wrong nonce/memo). */
+    readonly memo?: string;
+    /** The signing wallet, base58 — becomes the fee payer AND the memo signer. */
+    readonly feePayer: string;
+    /** A recent blockhash. Defaults to {@link PLACEHOLDER_BLOCKHASH} (the tx is
+     *  never submitted). */
+    readonly blockhash?: string;
+}
+/**
+ * Build the memo-only challenge transaction the wallet signs for verify-tx.
+ *
+ * The result is a legacy `Transaction` with EXACTLY one instruction: an SPL-Memo
+ * instruction whose data is the UTF-8 bytes of `x1id-verify:<nonce>`, with the
+ * fee payer listed as a required signer on that instruction. Nothing else — no
+ * transfer, no compute-budget, no durable nonce — so the signed artifact can
+ * only ever be a sign-in proof, never a disguised value-moving transaction. The
+ * server enforces the same shape on receipt.
+ */
+export declare function buildVerifyTxChallenge(web3: VerifyTxWeb3, params: BuildVerifyTxChallengeParams): TransactionInstance;
+/** Default hosted X1ID /v1 base URL. */
+export declare const DEFAULT_CONNECT_BASE_URL = "https://api.x1id.io";
+export interface ConnectClientConfig {
+    /** Your X1ID API key (`x1id_…` / `x1idlive_…`) — identifies the dapp. */
+    readonly apiKey: string;
+    /** Base URL of the /v1 API. Defaults to {@link DEFAULT_CONNECT_BASE_URL}. */
+    readonly baseUrl?: string;
+    /** Inject a `fetch` (tests, non-global-fetch runtimes). */
+    readonly fetchImpl?: typeof fetch;
+    /** Per-request timeout in ms (default 15_000). */
+    readonly timeoutMs?: number;
+}
+/** The Bearer session verify-tx mints — identical shape to the message path. */
+export interface ConnectSession {
+    readonly token: string;
+    readonly token_type: string;
+    readonly expires_at: number;
+    readonly handle: string | null;
+    readonly address: string;
+    readonly verified: readonly string[];
+    readonly source: string;
+    readonly proves: string;
+    readonly disclaimer: string;
+}
+/** The tx-mode challenge response (the fields this flow uses). */
+export interface TxChallenge {
+    readonly nonce: string;
+    readonly memo: string;
+    readonly handle: string | null;
+    readonly expires_at: number;
+}
+/** Thrown when sign-in could not complete (network, auth, a typed service
+ *  error, a wallet failure, or tx-mode being unavailable for this wallet). */
+export declare class ConnectError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}
+export interface SigninWithTxParams {
+    /** Injected web3.js constructors (see {@link VerifyTxWeb3}). */
+    readonly web3: VerifyTxWeb3;
+    /** The connected wallet's address, base58 — the fee payer / identity. */
+    readonly wallet: string;
+    /**
+     * The wallet's transaction signer. Takes the memo transaction built here and
+     * returns it fully signed (the wallet's `signTransaction`). The returned
+     * object must `serialize()` to the signed transaction bytes.
+     */
+    readonly signTransaction: (tx: TransactionInstance) => Promise<TransactionInstance>;
+    /** Optional recent blockhash; defaults to {@link PLACEHOLDER_BLOCKHASH}. */
+    readonly blockhash?: string;
+}
+/**
+ * Sign in with a transaction-signature proof of wallet control.
+ *
+ * Requests a tx-mode challenge, builds the memo transaction, has the caller's
+ * wallet sign it, and posts the signed artifact to `POST /v1/auth/verify-tx`,
+ * returning the minted session. Throws {@link ConnectError} on any failure.
+ *
+ * The wallet must have NO primary `@handle` for the tx path (it proves wallet
+ * control only); if it has one, the challenge comes back without a memo and this
+ * throws `TX_MODE_UNAVAILABLE` (use the handle-gated message path instead).
+ */
+export declare function signinWithTx(cfg: ConnectClientConfig, params: SigninWithTxParams): Promise<ConnectSession>;

package/dist/connect.js

@@ -0,0 +1,193 @@
+/**
+ * X1ID Connect — the TRANSACTION-signature sign-in client (#8452, verify-tx).
+ *
+ * # Why a transaction, not a message
+ *
+ * The message path ({@link import("./signin.js").signInWithX1ID}) asks the
+ * wallet to `signMessage` the challenge bytes. Two real wallets break that on
+ * X1:
+ *   - a Ledger (via Phantom/Backpack) REFUSES off-chain message signing; and
+ *   - Backpack on X1 returns `signMessage` signatures that DO NOT verify under
+ *     the wallet's own pubkey, even though its TRANSACTION signatures are valid
+ *     on-chain.
+ *
+ * So this flow proves wallet control a different, robust way: the wallet signs a
+ * throwaway MEMO TRANSACTION — one SPL-Memo instruction carrying
+ * `x1id-verify:<nonce>`, fee-paid by the wallet, never broadcast. The hosted
+ * `POST /v1/auth/verify-tx` endpoint deserializes the signed artifact, asserts
+ * it is EXACTLY that memo (no disguised transfer/approval), that the fee payer
+ * is the wallet, that the memo binds our single-use nonce, and verifies the
+ * ed25519 transaction signature. A valid proof mints the same Bearer session the
+ * message path does.
+ *
+ * This is the WALLET-control (no primary `@handle`) path — the app.x1id.io model
+ * where the connected wallet IS the identity, with the `@handle` as optional
+ * metadata. A handle-gated sign-in keeps the full on-chain control proof.
+ *
+ * # web3.js is injected, not depended on
+ *
+ * `@solana/web3.js` is an OPTIONAL peer dependency of this package (see
+ * scoped.ts / universalSns.ts). {@link buildVerifyTxChallenge} therefore takes
+ * the `{ Transaction, TransactionInstruction, PublicKey }` constructors as an
+ * injected {@link VerifyTxWeb3} rather than importing them — the SDK core stays
+ * free of a hard web3 dependency and tests can supply a fake.
+ */
+/** Memo prefix the verify-tx proof binds to. The signed memo instruction's
+ *  UTF-8 data MUST be EXACTLY `x1id-verify:<nonce>` — the server rejects any
+ *  other data, which is what kills replay of an unrelated signed transaction. */
+export const VERIFY_TX_MEMO_PREFIX = "x1id-verify:";
+/** Canonical SPL Memo program id — the program the challenge memo rides on. */
+export const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+/** The exact memo string for a given challenge nonce. */
+export function verifyTxMemo(nonce) {
+    return VERIFY_TX_MEMO_PREFIX + nonce;
+}
+/** 32 zero-bytes in base58 — a structurally valid blockhash. The transaction is
+ *  NEVER broadcast, so a placeholder blockhash is fine; a wallet that insists on
+ *  a fresh one can pass its own in {@link BuildVerifyTxChallengeParams.blockhash}. */
+export const PLACEHOLDER_BLOCKHASH = "11111111111111111111111111111111";
+/**
+ * Build the memo-only challenge transaction the wallet signs for verify-tx.
+ *
+ * The result is a legacy `Transaction` with EXACTLY one instruction: an SPL-Memo
+ * instruction whose data is the UTF-8 bytes of `x1id-verify:<nonce>`, with the
+ * fee payer listed as a required signer on that instruction. Nothing else — no
+ * transfer, no compute-budget, no durable nonce — so the signed artifact can
+ * only ever be a sign-in proof, never a disguised value-moving transaction. The
+ * server enforces the same shape on receipt.
+ */
+export function buildVerifyTxChallenge(web3, params) {
+    const { nonce, feePayer, blockhash } = params;
+    if (typeof nonce !== "string" || nonce.length === 0)
+        throw new Error("nonce is required");
+    if (typeof feePayer !== "string" || feePayer.length === 0)
+        throw new Error("feePayer is required");
+    const memo = params.memo ?? verifyTxMemo(nonce);
+    if (memo !== verifyTxMemo(nonce)) {
+        throw new Error(`memo must be exactly "${verifyTxMemo(nonce)}" for this nonce`);
+    }
+    const payer = new web3.PublicKey(feePayer);
+    const memoProgram = new web3.PublicKey(MEMO_PROGRAM_ID);
+    const ix = new web3.TransactionInstruction({
+        // The signer must appear in the instruction keys for the memo to be a
+        // "signed memo" and for the wallet to require THIS key's signature.
+        keys: [{ pubkey: payer, isSigner: true, isWritable: false }],
+        programId: memoProgram,
+        data: new TextEncoder().encode(memo),
+    });
+    const tx = new web3.Transaction();
+    tx.add(ix);
+    tx.feePayer = payer;
+    tx.recentBlockhash = blockhash ?? PLACEHOLDER_BLOCKHASH;
+    return tx;
+}
+// -----------------------------------------------------------------------------
+// signinWithTx — one call: tx-mode challenge -> sign -> verify-tx -> session
+// -----------------------------------------------------------------------------
+/** Default hosted X1ID /v1 base URL. */
+export const DEFAULT_CONNECT_BASE_URL = "https://api.x1id.io";
+/** Thrown when sign-in could not complete (network, auth, a typed service
+ *  error, a wallet failure, or tx-mode being unavailable for this wallet). */
+export class ConnectError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "ConnectError";
+    }
+}
+function baseUrlOf(cfg) {
+    return (cfg.baseUrl ?? DEFAULT_CONNECT_BASE_URL).replace(/\/+$/, "");
+}
+function bytesToBase64(bytes) {
+    let bin = "";
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    // `btoa` is available in browsers and Node 18+ (the SDK's floor). register.ts
+    // already relies on the sibling `atob`.
+    return btoa(bin);
+}
+async function postJson(cfg, path, body) {
+    const doFetch = cfg.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function")
+        throw new ConnectError("NO_FETCH", "no fetch available; pass fetchImpl in the config");
+    if (!cfg.apiKey)
+        throw new ConnectError("NO_API_KEY", "an X1ID apiKey is required");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), cfg.timeoutMs ?? 15_000);
+    let res;
+    try {
+        res = await doFetch(`${baseUrlOf(cfg)}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-api-key": cfg.apiKey },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        throw new ConnectError("REQUEST_FAILED", `request to ${path} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch {
+        throw new ConnectError("BAD_RESPONSE", `${path} returned non-JSON (HTTP ${res.status})`, res.status);
+    }
+    if (!res.ok) {
+        const b = (parsed ?? {});
+        throw new ConnectError(b.code ?? "HTTP_ERROR", b.message ?? `${path} returned HTTP ${res.status}`, res.status);
+    }
+    return parsed;
+}
+/**
+ * Sign in with a transaction-signature proof of wallet control.
+ *
+ * Requests a tx-mode challenge, builds the memo transaction, has the caller's
+ * wallet sign it, and posts the signed artifact to `POST /v1/auth/verify-tx`,
+ * returning the minted session. Throws {@link ConnectError} on any failure.
+ *
+ * The wallet must have NO primary `@handle` for the tx path (it proves wallet
+ * control only); if it has one, the challenge comes back without a memo and this
+ * throws `TX_MODE_UNAVAILABLE` (use the handle-gated message path instead).
+ */
+export async function signinWithTx(cfg, params) {
+    const challenge = await postJson(cfg, "/v1/auth/challenge", {
+        wallet: params.wallet,
+        mode: "tx",
+    });
+    if (!challenge.memo || !challenge.nonce) {
+        throw new ConnectError("TX_MODE_UNAVAILABLE", "the transaction sign-in path is for a wallet with no primary @handle; this wallet returned no tx memo");
+    }
+    const tx = buildVerifyTxChallenge(params.web3, {
+        nonce: challenge.nonce,
+        memo: challenge.memo,
+        feePayer: params.wallet,
+        ...(params.blockhash !== undefined ? { blockhash: params.blockhash } : {}),
+    });
+    let signed;
+    try {
+        signed = await params.signTransaction(tx);
+    }
+    catch (e) {
+        throw new ConnectError("WALLET_ERROR", `wallet failed to sign the challenge transaction: ${String(e)}`, undefined);
+    }
+    let signedTransaction;
+    try {
+        signedTransaction = bytesToBase64(signed.serialize());
+    }
+    catch (e) {
+        throw new ConnectError("WALLET_ERROR", `could not serialize the signed transaction: ${String(e)}`);
+    }
+    return postJson(cfg, "/v1/auth/verify-tx", {
+        nonce: challenge.nonce,
+        signedTransaction,
+    });
+}

package/dist/index.d.ts

@@ -51,6 +51,7 @@ export * from "./clearRecords.js";
 export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
+export * from "./connect.js";
 export * from "./domainProof.js";
 export { scopedTldCandidate, namespaceIsActive, makeScopedHandleDeriver, type ScopedCandidate, type ScopedHandleDeriver, } from "./scoped.js";
 import { type Chain, type Resolved } from "./types.js";

package/dist/index.js

@@ -58,6 +58,7 @@ export * from "./clearRecords.js";
 export * from "./commitReveal.js";
 export * from "./pnftTransfer.js";
 export * from "./signin.js";
+export * from "./connect.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
@@ -100,8 +101,8 @@ const SUBNAME_RESERVED_SUFFIXES = new Set([
  * name (owner-approved disambiguation order: subname before scoped-TLD). The
  * shape is a single interior dot with non-empty halves, a `parent` that is not
  * a reserved suffix, and a `label` with no further dot (a deeper `a.b.c` is
- * sub-subname territory the one-level program does not support → stays
- * `unrecognized`). Whether `@parent` is actually a registered handle is a chain
+ * sub-subname territory handled by {@link subSubnameCandidate}, NOT a one-level
+ * subname). Whether `@parent` is actually a registered handle is a chain
  * fact the resolver establishes separately. Both halves are normalized for real
  * at resolve; a parent that cannot be a handle (e.g. > 32 bytes) simply fails
  * the registration check and falls through to the scoped path.
@@ -116,11 +117,36 @@ function subnameCandidate(input) {
     const label = t.slice(0, dot);
     const parent = t.slice(dot + 1);
     if (label.includes("."))
-        return null; // a.b.c — a true sub-subname, unsupported
+        return null; // a.b.c — a sub-subname (see subSubnameCandidate)
     if (SUBNAME_RESERVED_SUFFIXES.has(parent))
         return null; // never conflate with X1NS / external
     return { label, parent };
 }
+/**
+ * Classify `input` as a `leaf.mid.root` SUB-SUBNAME candidate by SHAPE ONLY (no
+ * chain read) — a THIRD naming level (#7375 two-level), `deep.pay.jack`: a
+ * sub-subname `leaf` under a subname `mid.root` under the handle `@root`. Shape:
+ * EXACTLY three dot-separated non-empty segments, no leading `@`, and a `root`
+ * (last) segment that is not a reserved suffix (so `a.b.sol`/`a.b.x1` stay with
+ * the X1NS / universal path, never a native sub-subname). FOUR or more segments
+ * → `null` (the program is two levels deep only). Whether `@root` is a
+ * registered handle and `mid.root` a live subname are chain facts the resolver
+ * establishes separately ({@link Resolver.resolve}'s `resolveSubSubname`).
+ */
+function subSubnameCandidate(input) {
+    const t = input.trim().toLowerCase();
+    if (!t || t.startsWith("@"))
+        return null;
+    const parts = t.split(".");
+    if (parts.length !== 3)
+        return null; // exactly three segments; 4+ → not a sub-subname
+    const [leaf, mid, root] = parts;
+    if (!leaf || !mid || !root)
+        return null; // no empty segment (e.g. `a..c`, `.a.b`)
+    if (SUBNAME_RESERVED_SUFFIXES.has(root))
+        return null; // never conflate with X1NS / external
+    return { leaf, mid, root };
+}
 // `Primary` pointer account (`["primary", owner]` under the registry):
 //   disc(8) | owner(32) | handle(32) | set_at(i64 LE, 8) | bump(1) = 81 bytes
 const PRIMARY_LEN = 81;
@@ -460,6 +486,156 @@ export function createResolver(config) {
         }
         return value;
     }
+    /**
+     * Resolve a `leaf.mid.root` SUB-SUBNAME (#7375 two-level, owner decision
+     * 2026-09-24) — a sub-subname `leaf` under a subname `mid.root` under the
+     * handle `@root`, e.g. `deep.pay.jack`. Called ONLY for an exactly-3-segment,
+     * non-`@`, non-X1NS input (the native parser's `unrecognized` fall-through).
+     *
+     * Returns `null` — the signal to fall through to `unrecognized` — when the
+     * input was never a sub-subname at all: `@root` is NOT a registered handle,
+     * or there is no `mid` subname account under it. Those cases are "this 3-dot
+     * name is not one of ours", not an error. Once the `mid` subname ACCOUNT
+     * exists we are COMMITTED: every outcome is a `Resolved` or a throw
+     * (`not-found` / `no-record-for-chain`), never a fall-through and never a
+     * wrong address.
+     *
+     * A sub-subname has NO owner (like every subname); it resolves PURELY through
+     * its per-chain `Record`s, EVERY chain included. ALL THREE staleness layers of
+     * docs/record-trust.md (generalized to three levels — see app's subSubname.ts)
+     * are enforced:
+     *   1. `mid.createdAt >= root.registeredAt` — the level-2 subname belongs to
+     *      the handle's CURRENT owner (the subname scan's `.live` flag). A `mid`
+     *      stranded by a parent transfer/re-registration → `not-found`.
+     *   2. `leaf.createdAt >= mid.createdAt` — the sub-subname belongs to the
+     *      CURRENT incarnation of its immediate parent subname (that PDA is reused
+     *      across revoke + re-create). The second scan's `.live` flag, re-checked
+     *      inside `resolveSubnameRecords`.
+     *   3. `record.updatedAt >= leaf.createdAt` — the record belongs to the
+     *      CURRENT incarnation of the sub-subname itself (ordinary record staleness
+     *      with the leaf's `createdAt` as the epoch).
+     * Nothing is hand-derived: both levels are located by the program-scoped
+     * `getProgramAccounts` scan (`fetchSubnames`, which IS the ownership check),
+     * the mid subname's pubkey standing in for the parent at the lower level — the
+     * same account type and formula, one level deeper.
+     */
+    async function resolveSubSubname(leafRaw, midRaw, rootRaw, chain, input) {
+        // The root half must canonicalize as a handle; if it cannot, `@root` can
+        // never be a registered handle → not a sub-subname, fall through.
+        let rootCanonical;
+        try {
+            rootCanonical = normalizeHandle(rootRaw);
+        }
+        catch {
+            return null;
+        }
+        // The mid + leaf halves must also canonicalize as handle labels. Defer a
+        // non-canonical verdict until the branch (mid-account existence) is decided,
+        // exactly as `resolveSubname` defers its `subLabel`.
+        let midLabel = null;
+        let leafLabel = null;
+        try {
+            midLabel = normalizeHandle(midRaw);
+        }
+        catch {
+            midLabel = null;
+        }
+        try {
+            leafLabel = normalizeHandle(leafRaw);
+        }
+        catch {
+            leafLabel = null;
+        }
+        if (midLabel !== null && leafLabel !== null && ttl > 0) {
+            const hit = cache.get(`subsubname:${rootCanonical}:${midLabel}:${leafLabel}:${chain}`);
+            if (hit && hit.expires > Date.now())
+                return hit.value;
+        }
+        // Is `@root` a REGISTERED handle? If not, `a.b.c` was never a sub-subname.
+        // `not-found`/`invalid-handle` → fall through; a real error propagates.
+        let root;
+        try {
+            root = await fetchHandle(rootCanonical, input);
+        }
+        catch (e) {
+            if (e instanceof ResolveError && (e.code === "not-found" || e.code === "invalid-handle")) {
+                return null;
+            }
+            throw e;
+        }
+        // A non-canonical mid can never match a stored subname label → not a
+        // sub-subname (fall through), same as a missing mid account below.
+        if (midLabel === null)
+            return null;
+        // Locate the level-2 (mid) subname under the handle. Its EXISTENCE (a label
+        // match) is the COMMIT POINT: a missing mid subname means `a.b.c` names
+        // nothing of ours → fall through to `unrecognized`; a mid subname that
+        // EXISTS is the point of no return. `fetchSubnames` flags each `.live`
+        // against `root.registeredAt` — staleness LAYER 1.
+        const subs = await fetchSubnames(rpc, programBase58, root.pda, root.handle.registeredAt);
+        const mid = subs.find((s) => s.label === midLabel);
+        if (!mid)
+            return null; // no such mid subname → unrecognized
+        // COMMITTED to the sub-subname interpretation from here.
+        const leafDisplay = leafLabel ?? leafRaw.trim().toLowerCase();
+        const display = `${leafDisplay}.${midLabel}.${rootCanonical}`;
+        const midDisplay = `${midLabel}.${rootCanonical}`;
+        // Staleness LAYER 1 — a mid subname stranded by a parent transfer/
+        // re-registration belongs to a PREVIOUS owner; nothing under it may resolve.
+        if (!mid.live) {
+            throw new ResolveError("not-found", `${midDisplay} was created before the current @${rootCanonical} registration — ${display} belongs to a previous owner`, input);
+        }
+        if (leafLabel === null) {
+            throw new ResolveError("not-found", `"${input.trim()}" is not a sub-subname of ${midDisplay}`, input);
+        }
+        // Locate the level-3 (leaf) sub-subname under the mid subname — the SAME
+        // program scan + `Subname` account type, the mid subname's pubkey standing
+        // in for the parent and its `createdAt` for `parentRegisteredAt`. The
+        // resulting `.live` flag is staleness LAYER 2 (leaf.createdAt >= mid.createdAt).
+        const subsubs = await fetchSubnames(rpc, programBase58, mid.account, mid.createdAt);
+        const leaf = subsubs.find((s) => s.label === leafLabel);
+        if (!leaf) {
+            throw new ResolveError("not-found", `${display} is not a sub-subname of ${midDisplay}`, input);
+        }
+        // Staleness LAYER 2 — a leaf stranded by its parent subname being revoked +
+        // re-created belongs to a previous incarnation and must never resolve.
+        if (!leaf.live) {
+            throw new ResolveError("not-found", `${display} was created before the current ${midDisplay} subname — it belongs to a previous incarnation`, input);
+        }
+        // Read the leaf's LIVE records. `resolveSubnameRecords` re-applies LAYER 2
+        // (leaf.createdAt >= mid.createdAt) AND LAYER 3 (record.updatedAt >=
+        // leaf.createdAt), dropping any stale record — the only safe entry point.
+        const leafSubname = {
+            parent: leaf.parent,
+            label: leaf.label,
+            createdAt: leaf.createdAt,
+            bump: leaf.bump,
+        };
+        const records = await resolveSubnameRecords(rpc, programBase58, leaf.account, leafSubname, mid.createdAt);
+        const record = records.find((r) => !r.stale && r.coinType === CHAIN_COIN_TYPE[chain]);
+        if (!record) {
+            throw new ResolveError("no-record-for-chain", `${display} has no ${chain} record`, input);
+        }
+        const value = {
+            input,
+            name: display,
+            // A sub-subname is its own namespace — never "handle", "subname", or the
+            // root's — so a consumer branching on the namespace treats it distinctly.
+            namespace: "sub-subname",
+            address: record.address,
+            chain,
+            // Like a subname record: `unverified` unless the record itself is
+            // co-signed (sub-subname records are always unverified on chain in v1).
+            verification: record.verified ? "verified" : "unverified",
+        };
+        if (ttl > 0) {
+            cache.set(`subsubname:${rootCanonical}:${midLabel}:${leafLabel}:${chain}`, {
+                value,
+                expires: Date.now() + ttl,
+            });
+        }
+        return value;
+    }
     /** See `Resolver.records`. */
     async function records(input) {
         const parsed = parseName(input); // throws with a specific code
@@ -477,12 +653,17 @@ export function createResolver(config) {
         }
         catch (e) {
             // A dotted, non-`@`, non-X1NS name is `unrecognized` to the strict native
-            // parser — but it MAY be a SUBNAME `label.parent` (#7375) or a scoped
-            // customer-TLD name `name.tld` (#8484/#8485). Owner-approved
-            // disambiguation order: try the subname interpretation FIRST (when
-            // `@parent` is a registered handle), then the scoped path. Each re-throws
-            // / falls through so `.sol`/`.eth`/unknown TLDs behave exactly as before.
-            // Any other code (ambiguous / invalid-*) is preserved verbatim.
+            // parser — but it MAY be a one-level SUBNAME `label.parent` (#7375), a
+            // two-level SUB-SUBNAME `leaf.mid.root` (#7375 two-level, 3 segments), or
+            // a scoped customer-TLD name `name.tld` (#8484/#8485). Owner-approved
+            // disambiguation order: the subname interpretation FIRST (when `@parent`
+            // is a registered handle), then the sub-subname interpretation (when
+            // `@root` is a registered handle AND `mid.root` an existing subname), then
+            // the scoped path. `subnameCandidate`/`scopedTldCandidate` are both
+            // 2-segment-only and `subSubnameCandidate` is 3-segment-only, so each
+            // input matches at most one; each re-throws / falls through 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 sub = subnameCandidate(input);
                 if (sub) {
@@ -493,6 +674,15 @@ export function createResolver(config) {
                     if (resolved !== null)
                         return resolved;
                 }
+                const subsub = subSubnameCandidate(input);
+                if (subsub) {
+                    // `null` ⇒ `@root` is not a handle, or `mid.root` is not a subname ⇒
+                    // not a sub-subname; fall through to `unrecognized`. A committed
+                    // sub-subname path either returns a `Resolved` or throws.
+                    const resolved = await resolveSubSubname(subsub.leaf, subsub.mid, subsub.root, chain, input);
+                    if (resolved !== null)
+                        return resolved;
+                }
                 const cand = scopedTldCandidate(input);
                 if (cand)
                     return resolveScoped(cand.sub, cand.tld, chain, input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x1id/resolve",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Resolve @handles and X1NS names on X1. Never silently picks between namespaces.",
   "type": "module",
   "main": "./dist/index.js",