@x1id/resolve 0.12.0 → 0.14.0

package/README.md

@@ -116,6 +116,44 @@ to the other". `@jack.x1` throws `ambiguous` rather than guessing. Use
 `looksLikeName(input)` to decide whether to attempt resolution at all, so
 pasting base58 does not surface a validation error.
 
+## Scoped names under customer TLDs
+
+Anyone can launch their own X1ID TLD (e.g. `.e2eshib`), and names registered
+under it — `hello.e2eshib` — are first-class X1ID names. These are **not** X1NS
+or SNS: `.x1` / `.xnt` / `.xen` are the separate **X1NS** domain system and
+`.sol` is **SNS** (Solana Name Service), each resolved on its own path. A
+customer TLD is resolved natively by this SDK against the `@handle` registry.
+
+Scoped resolution derives a per-TLD PDA, which needs `@solana/web3.js`. It is
+**opt-in and explicit** — you wire a deriver in; the SDK never auto-imports
+web3 for you:
+
+```ts
+import { createResolver, WasmResolver, makeScopedHandleDeriver } from "@x1id/resolve";
+import * as web3 from "@solana/web3.js";
+
+const wasm = await WasmResolver.fromBytes(/* module bytes */);
+
+// `makeScopedHandleDeriver` is ASYNC — await it. Pass the RESULT (not the
+// Promise) as `scopedHandleDeriver`.
+const scopedHandleDeriver = await makeScopedHandleDeriver(web3);
+
+const x1id = createResolver({
+  rpcUrl: "https://rpc.testnet.x1.xyz",
+  wasm,
+  scopedHandleDeriver,
+});
+
+await x1id.resolve("hello.e2eshib"); // resolves the scoped name under .e2eshib
+```
+
+Without `scopedHandleDeriver`, resolving a launched customer TLD throws
+`ResolveError { code: "not-configured" }` even with `@solana/web3.js` installed —
+the deriver is what the SDK actually calls. And because `makeScopedHandleDeriver`
+returns a Promise, passing it **un-awaited** is a common footgun; the SDK
+detects that and throws a clear `not-configured` error telling you to `await` it,
+rather than a cryptic "scopedHandleKey is not a function".
+
 ## Reads chain state, not an API
 
 X1NS names resolve by deriving accounts and reading them over RPC. This library

package/dist/gateClient.d.ts

@@ -77,7 +77,17 @@ export interface GuardResult {
  *
  * 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.
+ * 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

package/dist/gateClient.js

@@ -78,7 +78,17 @@ export async function checkGate(cfg, subject, policy) {
  *
  * 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.
+ * 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

package/dist/index.js

@@ -70,6 +70,7 @@ import { scopedTldCandidate, namespaceIsActive, NAMESPACE_MAX_LEN, } from "./sco
 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";
+import { fetchSubnames, resolveSubnameRecords } from "./subname.js";
 /** Root authority for each X1NS TLD — used to verify a fetched account really
  *  belongs to the TLD it claims. Without this check a caller handed an
  *  arbitrary account would read an owner straight out of it. */
@@ -79,6 +80,72 @@ const TLD_ROOT = Object.freeze({
     xen: "3SUwpSz33AsyJwf6B48cKZuDTswuUEdUhcXszZrFWPqo",
 });
 const SPL_NAME_HEADER_LEN = 96;
+/**
+ * Suffixes that are NEVER a subname parent: the native X1NS namespaces (handled
+ * by `parseName` before we ever reach the subname path) and the external TLDs
+ * the universal resolver owns. `foo.sol`/`foo.eth` must stay `unrecognized` to
+ * the native resolver — never resolved as a subname under `@sol`/`@eth` — so
+ * the whole never-conflate-a-namespace rule holds on the money path too.
+ */
+const SUBNAME_RESERVED_SUFFIXES = new Set([
+    "x1",
+    "xnt",
+    "xen",
+    "sol",
+    "eth",
+]);
+/**
+ * Classify `input` as a `label.parent` SUBNAME candidate by SHAPE ONLY (no
+ * chain read) — the FIRST interpretation tried for a dotted, non-`@`, non-X1NS
+ * 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 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.
+ */
+function subnameCandidate(input) {
+    const t = input.trim().toLowerCase();
+    if (!t || t.startsWith("@"))
+        return null;
+    const dot = t.lastIndexOf(".");
+    if (dot <= 0 || dot === t.length - 1)
+        return null;
+    const label = t.slice(0, dot);
+    const parent = t.slice(dot + 1);
+    if (label.includes("."))
+        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;
@@ -240,6 +307,15 @@ export function createResolver(config) {
         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);
         }
+        // `makeScopedHandleDeriver(web3)` is async; a common footgun is passing the
+        // un-awaited Promise as `scopedHandleDeriver`, which would otherwise surface
+        // a baffling `scopedDeriver.scopedHandleKey is not a function` wrapped as an
+        // rpc-error. Detect the Promise/thenable (or any object missing the method)
+        // and fail with an actionable message instead.
+        if (typeof scopedDeriver.then === "function" ||
+            typeof scopedDeriver.scopedHandleKey !== "function") {
+            throw new ResolveError("not-configured", "scopedHandleDeriver must be the awaited result of makeScopedHandleDeriver(web3), not the Promise it returns — did you forget `await`?", input);
+        }
         let pda;
         try {
             pda = await scopedDeriver.scopedHandleKey(label, name, programBase58);
@@ -290,6 +366,275 @@ export function createResolver(config) {
             cache.set(`scoped:${label}:${name}:${chain}`, { value, expires: Date.now() + ttl });
         return value;
     }
+    /**
+     * Resolve a `label.parent` SUBNAME (#7375) — a label under a parent
+     * `@handle`, e.g. `pay.alice`. Called ONLY for a dotted, non-`@`, non-X1NS
+     * input (the native parser's `unrecognized` fall-through), and BEFORE the
+     * scoped customer-TLD path, per the owner-approved disambiguation order.
+     *
+     * Returns `null` — the signal to try the scoped path next — when `@parent`
+     * is NOT a registered handle (so `x.y` was never a subname). Once `@parent`
+     * IS a registered handle we are COMMITTED to the subname interpretation:
+     * every outcome is a `Resolved` or a throw (`not-found` / `no-record-for-chain`),
+     * never a fall-through to scoped.
+     *
+     * A subname has NO owner; it resolves PURELY through its per-chain `Record`s
+     * (like an ETH/BTC record on a handle), so EVERY chain — X1/SOL included —
+     * comes from a record, never an owner key. Both staleness layers of
+     * docs/record-trust.md are enforced via `subname.ts`:
+     *   1. `subname.createdAt >= parent.registeredAt` — else the subname was left
+     *      behind by a PREVIOUS owner of the parent (any transfer/sale/recovery/
+     *      re-registration bumps `registered_at`): `not-found`, never resolved.
+     *   2. `record.updatedAt >= subname.createdAt` — a record from a previous
+     *      incarnation of the same `["subname", parent, label]` PDA is dropped.
+     * The subname account itself is located by the program-scoped
+     * `getProgramAccounts` scan (`fetchSubnames`) — scoping the scan to the
+     * registry program id IS the ownership check — then matched by canonical
+     * label; nothing is hand-derived here (the WASM module has no subname PDA
+     * derivation and this package never hand-rolls the on-curve check).
+     */
+    async function resolveSubname(labelRaw, parentRaw, chain, input) {
+        // The parent half must canonicalize as a handle; if it cannot, `@parent`
+        // can never be a registered handle → not a subname, try scoped instead.
+        let parentCanonical;
+        try {
+            parentCanonical = normalizeHandle(parentRaw);
+        }
+        catch {
+            return null;
+        }
+        // The subname label must also canonicalize as a handle label (same rules).
+        // If it cannot we cannot build a cache key yet — defer the verdict until
+        // after the parent-registration check decides the branch.
+        let subLabel = null;
+        try {
+            subLabel = normalizeHandle(labelRaw);
+        }
+        catch {
+            subLabel = null;
+        }
+        if (subLabel !== null && ttl > 0) {
+            const hit = cache.get(`subname:${parentCanonical}:${subLabel}:${chain}`);
+            if (hit && hit.expires > Date.now())
+                return hit.value;
+        }
+        // Is `@parent` a REGISTERED handle? That — and only that — decides whether
+        // `x.y` is a subname. `not-found`/`invalid-handle` → not a subname, fall
+        // through to scoped; a real rpc-error/malformed account propagates.
+        let parent;
+        try {
+            parent = await fetchHandle(parentCanonical, input);
+        }
+        catch (e) {
+            if (e instanceof ResolveError && (e.code === "not-found" || e.code === "invalid-handle")) {
+                return null;
+            }
+            throw e;
+        }
+        // COMMITTED to the subname interpretation: `@parent` is a live handle.
+        if (subLabel === null) {
+            throw new ResolveError("not-found", `"${input.trim()}" is not a subname of @${parentCanonical}`, input);
+        }
+        const display = `${subLabel}.${parentCanonical}`;
+        // Locate the subname account via the program scan (ownership check), then
+        // match the canonical label. `fetchSubnames` already flags each with
+        // `live` (staleness layer 1: createdAt >= parent.registeredAt).
+        const subs = await fetchSubnames(rpc, programBase58, parent.pda, parent.handle.registeredAt);
+        const match = subs.find((s) => s.label === subLabel);
+        if (!match) {
+            throw new ResolveError("not-found", `${display} is not a subname of @${parentCanonical}`, input);
+        }
+        // Staleness layer 1 — a subname stranded by a parent transfer/re-registration
+        // belongs to a PREVIOUS owner and must NEVER resolve to a payment address.
+        if (!match.live) {
+            throw new ResolveError("not-found", `${display} was created before the current @${parentCanonical} registration — it belongs to a previous owner`, input);
+        }
+        // Read the subname's LIVE records. `resolveSubnameRecords` re-applies layer
+        // 1 (returns [] when stale) AND layer 2 (record.updatedAt >= createdAt),
+        // dropping any stale record — the only safe entry point.
+        const subname = {
+            parent: match.parent,
+            label: match.label,
+            createdAt: match.createdAt,
+            bump: match.bump,
+        };
+        const records = await resolveSubnameRecords(rpc, programBase58, match.account, subname, parent.handle.registeredAt);
+        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 subname is its own namespace — never "handle" (so a consumer that
+            // branches on `=== "handle"`, e.g. dev-api's attestation enrichment, does
+            // not treat it as a top-level handle) and never the parent's.
+            namespace: "subname",
+            address: record.address,
+            chain,
+            // Like a handle's ETH/BTC record: `unverified` unless the record itself
+            // is co-signed/verified (and `verified` is already forced false for any
+            // stale record by records.ts).
+            verification: record.verified ? "verified" : "unverified",
+        };
+        if (ttl > 0) {
+            cache.set(`subname:${parentCanonical}:${subLabel}:${chain}`, {
+                value,
+                expires: Date.now() + ttl,
+            });
+        }
+        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
@@ -307,12 +652,36 @@ export function createResolver(config) {
         }
         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
+            // 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) {
+                    // `null` ⇒ `@parent` is not a registered handle ⇒ not a subname;
+                    // fall through to the scoped path. A committed subname path either
+                    // returns a `Resolved` or throws (never reaches scoped).
+                    const resolved = await resolveSubname(sub.label, sub.parent, chain, input);
+                    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);
@@ -402,8 +771,15 @@ export function createResolver(config) {
      */
     async function reverse(address) {
         const owner = decodeBase58_32(address);
-        if (!owner)
-            throw new ResolveError("unrecognized", `"${address}" is not an address`, address);
+        // `decodeBase58_32` left-pads a short/tiny base58 input into 32 bytes, so a
+        // malformed address like "abc" would otherwise slip through as a valid tiny
+        // key. Require the canonical round-trip: a malformed address must THROW
+        // (matching the dev-api's 400 INVALID_ADDRESS and the docs/drill checklist),
+        // reserving the `null` return exclusively for a WELL-FORMED address that
+        // genuinely has no primary.
+        if (!owner || encodeBase58(owner) !== address) {
+            throw new ResolveError("unrecognized", `"${address}" is not a valid X1 address`, address);
+        }
         const handleName = await reverseHandle(owner);
         if (handleName !== null)
             return handleName;

package/dist/signin.d.ts

@@ -211,9 +211,21 @@ export type SignInVerification = {
  * wallet signed. Whether that wallet currently owns a handle is a separate,
  * on-chain question answered by {@link resolveIdentity}.
  *
- * Replay protection is nonce + expiry, and both need the relying party: pass
- * `expectedNonce` (and never accept the same nonce twice), and keep the expiry
- * window short. The domain binding needs `expectedDomain` to become a check.
+ * ⚠️ `expectedDomain` and `expectedNonce` are the anti-phishing and anti-replay
+ * checks, and they are OPT-IN. OMITTING THEM DISABLES THAT PROTECTION:
+ *
+ * - no `expectedDomain` → the domain binding is NOT enforced. A signature a
+ *   user produced for a phishing site's challenge will verify here. Always pass
+ *   your own origin's domain in a real login.
+ * - no `expectedNonce` → the nonce binding is NOT enforced, so this call cannot
+ *   tell a fresh proof from a replayed one. Pass the nonce the RP issued, and
+ *   never accept the same nonce twice (burn it server-side). Keep the expiry
+ *   window short regardless — expiry alone only bounds the replay window, it
+ *   does not close it.
+ *
+ * {@link signInWithX1ID} passes both for you. A bare `verifySignIn` without
+ * them emits a one-time dev-mode `console.warn` so the gap is noticed in
+ * development; it is silent in production (and whenever `process` is absent).
  */
 export declare function verifySignIn(params: VerifySignInParams): Promise<SignInVerification>;
 /** One live "verified by [platform]" signal on the signed-in handle. */

package/package.json

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