@tinycloud/sdk-core 3.3.0-beta.17 → 3.3.0-beta.20

package/dist/index.js

@@ -18382,11 +18382,16 @@ async function resolveTinyCloudHosts(subject, options2 = {}) {
     fetch: fetchFn,
     verifyRecords: options2.verifyRecords
   });
-  return {
-    hosts: location.multiaddrs.map((addr) => multiaddrToHttpUrl(addr)),
-    location
-  };
+  const hosts = location.multiaddrs.map((addr) => multiaddrToHttpUrl(addr));
+  if (location.source === "fallback" && !fallbackDeprecationWarned) {
+    fallbackDeprecationWarned = true;
+    console.warn(
+      `[tinycloud:location] Deprecated: no registry host for this account, using fallback ${hosts[0]}. The silent fallback will be removed in a future major; opt in to registryPolicy "fail-closed" now.`
+    );
+  }
+  return { hosts, location };
 }
+var fallbackDeprecationWarned = false;
 function memoizeFetch(fetchFn) {
   const cache2 = /* @__PURE__ */ new Map();
   return (async (input, init) => {
@@ -18599,11 +18604,18 @@ function publishedHttpOrigins(record2) {
   return origins;
 }
 async function boundedResponseText(response, label, maxBytes) {
+  const bytes2 = await boundedResponseBytes(response, maxBytes);
+  if (bytes2 === null) {
+    throw new LocationRecordValidationError(`${label} response is too large`);
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes2);
+}
+async function boundedResponseBytes(response, maxBytes) {
   const declaredLength = response.headers.get("content-length");
   if (declaredLength !== null && (!/^\d+$/.test(declaredLength) || Number(declaredLength) > maxBytes)) {
-    throw new LocationRecordValidationError(`${label} response is too large`);
+    return null;
   }
-  if (response.body === null) return "";
+  if (response.body === null) return new Uint8Array();
   const reader = response.body.getReader();
   const chunks = [];
   let total = 0;
@@ -18615,7 +18627,7 @@ async function boundedResponseText(response, label, maxBytes) {
       total += value.byteLength;
       if (total > maxBytes) {
         await reader.cancel().catch(() => void 0);
-        throw new LocationRecordValidationError(`${label} response is too large`);
+        return null;
       }
       chunks.push(value);
     }
@@ -18628,7 +18640,7 @@ async function boundedResponseText(response, label, maxBytes) {
     bytes2.set(chunk, offset);
     offset += chunk.byteLength;
   }
-  return new TextDecoder("utf-8", { fatal: true }).decode(bytes2);
+  return bytes2;
 }
 function boundedSignal(parent, timeoutMs) {
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -18926,6 +18938,699 @@ function decodeBase64Url4(value) {
   }
   return Uint8Array.from(bytes2);
 }
+
+// src/registry-verdict.ts
+import { ed25519 as ed2551912 } from "@noble/curves/ed25519";
+import { verifyMessage as verifyMessage3 } from "viem";
+var RegistryLookupInputError = class extends TypeError {
+  constructor(code3, message) {
+    super(message);
+    this.code = code3;
+    this.name = "RegistryLookupInputError";
+  }
+};
+var REGISTRY_LOOKUP_MAX_BODY_BYTES = 64 * 1024;
+var REGISTRY_NOT_FOUND_BODY = '{"error":"location record not found"}';
+var MAX_JSON_DEPTH = 32;
+var JSON_SIMPLE_ESCAPES = {
+  '"': '"',
+  "\\": "\\",
+  "/": "/",
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "	"
+};
+var SECP256K1_N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+var BASE64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var IPV4_OCTET = "(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])";
+var IPV4 = new RegExp(`^${IPV4_OCTET}(\\.${IPV4_OCTET}){3}$`);
+var DNS_LABEL = "[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?";
+var DNS_NAME = new RegExp(`^${DNS_LABEL}(\\.${DNS_LABEL})*$`);
+var HOST_MULTIADDR = /^\/(ip4|ip6|dns|dns4|dns6)\/([^/]+)\/tcp\/([1-9][0-9]{0,4})\/(https|http|tls\/http)$/;
+var RFC3339_DATE_TIME = /^([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?(Z|[+-]([0-9]{2}):([0-9]{2}))$/;
+async function classifyRegistryLookup(subject, response, options2 = {}) {
+  if (!isCanonicalSubject(subject)) {
+    throw new RegistryLookupInputError(
+      "invalid-subject",
+      "subject must be did:pkh:eip155:<chainId>:<EIP-55 address> or an Ed25519 did:key"
+    );
+  }
+  const remembered = options2.rememberedSequence ?? null;
+  if (remembered !== null && (!Number.isSafeInteger(remembered) || remembered < 0)) {
+    throw new RegistryLookupInputError(
+      "invalid-remembered-sequence",
+      "rememberedSequence must be a non-negative safe integer"
+    );
+  }
+  const unavailable = (reason, message) => ({
+    status: "unavailable",
+    subject,
+    source: "offchain",
+    reason,
+    message,
+    hosts: []
+  });
+  if (response.kind === "network-error") {
+    return unavailable("network-error", "location registry could not be reached");
+  }
+  if (response.kind === "timeout") {
+    return unavailable("timeout", "location registry lookup timed out");
+  }
+  if (response.status !== 200 && response.status !== 404) {
+    return unavailable("http-status", `location registry returned HTTP ${response.status}`);
+  }
+  if (response.body.length > REGISTRY_LOOKUP_MAX_BODY_BYTES || new TextEncoder().encode(response.body).byteLength > REGISTRY_LOOKUP_MAX_BODY_BYTES) {
+    return unavailable("oversize-response", "location registry response is too large");
+  }
+  if (response.status === 404) {
+    const body = response.body;
+    let start = 0;
+    let end = body.length;
+    while (start < end && " 	\n\r".includes(body[start])) start++;
+    while (end > start && " 	\n\r".includes(body[end - 1])) end--;
+    if (body.slice(start, end) !== REGISTRY_NOT_FOUND_BODY) {
+      return unavailable(
+        "malformed-response",
+        "location registry 404 is not the registry's not-found response"
+      );
+    }
+    if (remembered !== null) {
+      return unavailable(
+        "not-found-after-registered",
+        `location registry has no record, but sequence ${remembered} was seen before`
+      );
+    }
+    return { status: "unregistered", subject, source: "offchain", hosts: [] };
+  }
+  let record2;
+  try {
+    record2 = parseRecordResponse(response.body);
+  } catch (error) {
+    return unavailable(
+      "malformed-response",
+      error instanceof Error ? error.message : "location registry response is invalid"
+    );
+  }
+  if (record2.subject !== subject) {
+    return unavailable(
+      "subject-mismatch",
+      "location record subject does not match requested subject"
+    );
+  }
+  if (!await verifyRecordSignature(record2)) {
+    return unavailable("invalid-signature", "location record signature is invalid");
+  }
+  if (remembered !== null && record2.sequence < remembered) {
+    return unavailable(
+      "rollback",
+      `location record sequence ${record2.sequence} is below remembered sequence ${remembered}`
+    );
+  }
+  const hosts = [];
+  for (const address of record2.multiaddrs) {
+    const origin2 = multiaddrOrigin(address);
+    if (origin2 !== null) hosts.push({ urls: [origin2], source: "offchain" });
+  }
+  return {
+    status: "registered",
+    subject,
+    source: "offchain",
+    sequence: record2.sequence,
+    hosts
+  };
+}
+function isCanonicalSubject(subject) {
+  if (typeof subject !== "string") return false;
+  const pkh = /^did:pkh:eip155:([1-9][0-9]*):(0x[0-9a-fA-F]{40})$/.exec(subject);
+  if (pkh !== null) {
+    try {
+      return pkhDid(pkh[2], Number(pkh[1])) === subject;
+    } catch {
+      return false;
+    }
+  }
+  return ed25519KeyFromDidKey(subject) !== null;
+}
+function ed25519KeyFromDidKey(did) {
+  if (!did.startsWith("did:key:z")) return null;
+  const identifier = did.slice("did:key:".length);
+  let bytes2;
+  try {
+    bytes2 = bases.base58btc.decode(identifier);
+  } catch {
+    return null;
+  }
+  if (bytes2.length !== 34 || bytes2[0] !== 237 || bytes2[1] !== 1) {
+    return null;
+  }
+  return bytes2.slice(2);
+}
+var JsonInteger = class {
+  constructor(lexeme) {
+    this.lexeme = lexeme;
+  }
+};
+function parseStrictJson(text3) {
+  let i = 0;
+  const fail2 = (what) => {
+    throw new SyntaxError(`location registry response is not strict JSON: ${what} at ${i}`);
+  };
+  const skipWhitespace2 = () => {
+    while (i < text3.length && " 	\n\r".includes(text3[i])) i++;
+  };
+  const readHex4 = () => {
+    const hex3 = text3.slice(i, i + 4);
+    if (!/^[0-9a-fA-F]{4}$/.test(hex3)) fail2("bad \\u escape");
+    i += 4;
+    return parseInt(hex3, 16);
+  };
+  const parseString = () => {
+    i++;
+    let out = "";
+    for (; ; ) {
+      if (i >= text3.length) fail2("unterminated string");
+      const code3 = text3.charCodeAt(i);
+      if (code3 === 34) {
+        i++;
+        return out;
+      }
+      if (code3 < 32) fail2("control character in string");
+      if (code3 === 92) {
+        const escape2 = text3[i + 1];
+        i += 2;
+        if (escape2 !== void 0 && Object.prototype.hasOwnProperty.call(JSON_SIMPLE_ESCAPES, escape2)) {
+          out += JSON_SIMPLE_ESCAPES[escape2];
+          continue;
+        }
+        if (escape2 !== "u") fail2("bad escape");
+        const unit = readHex4();
+        if (unit >= 55296 && unit <= 56319) {
+          if (text3[i] !== "\\" || text3[i + 1] !== "u") fail2("unpaired surrogate");
+          i += 2;
+          const low = readHex4();
+          if (low < 56320 || low > 57343) fail2("unpaired surrogate");
+          out += String.fromCharCode(unit, low);
+        } else if (unit >= 56320 && unit <= 57343) {
+          fail2("unpaired surrogate");
+        } else {
+          out += String.fromCharCode(unit);
+        }
+        continue;
+      }
+      out += text3[i];
+      i++;
+    }
+  };
+  const parseValue = (depth) => {
+    skipWhitespace2();
+    const c = text3[i];
+    if (c === "{" || c === "[") {
+      if (depth >= MAX_JSON_DEPTH) fail2("nesting too deep");
+      i++;
+      skipWhitespace2();
+      const close = c === "{" ? "}" : "]";
+      const object4 = /* @__PURE__ */ new Map();
+      const array = [];
+      if (text3[i] === close) {
+        i++;
+        return c === "{" ? object4 : array;
+      }
+      for (; ; ) {
+        if (c === "{") {
+          skipWhitespace2();
+          if (text3[i] !== '"') fail2("expected key");
+          const key = parseString();
+          if (object4.has(key)) fail2("duplicate key");
+          skipWhitespace2();
+          if (text3[i] !== ":") fail2("expected ':'");
+          i++;
+          object4.set(key, parseValue(depth + 1));
+        } else {
+          array.push(parseValue(depth + 1));
+        }
+        skipWhitespace2();
+        if (text3[i] === ",") {
+          i++;
+          continue;
+        }
+        if (text3[i] !== close) fail2(`expected ',' or '${close}'`);
+        i++;
+        return c === "{" ? object4 : array;
+      }
+    }
+    if (c === '"') return parseString();
+    for (const [literal, value2] of [["true", true], ["false", false], ["null", null]]) {
+      if (text3.startsWith(literal, i)) {
+        i += literal.length;
+        return value2;
+      }
+    }
+    const number = /-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/y;
+    number.lastIndex = i;
+    const match = number.exec(text3);
+    if (match === null) return fail2("unexpected token");
+    if (match[2] !== void 0 || match[3] !== void 0) fail2("non-integer number");
+    i += match[0].length;
+    return new JsonInteger(match[0]);
+  };
+  const value = parseValue(0);
+  skipWhitespace2();
+  if (i !== text3.length) fail2("trailing data");
+  return value;
+}
+function parseRecordResponse(body) {
+  const root = parseStrictJson(body);
+  const record2 = root instanceof Map ? root.get("record") : void 0;
+  if (!(record2 instanceof Map)) {
+    throw new SyntaxError("location registry response has no record object");
+  }
+  const version = record2.get("version");
+  const subject = record2.get("subject");
+  const multiaddrs = record2.get("multiaddrs");
+  const updatedAt = record2.get("updated_at");
+  const sequence = record2.get("sequence");
+  const signature = record2.get("signature");
+  if (!(version instanceof JsonInteger) || version.lexeme !== "1") {
+    throw new SyntaxError("record.version must be the integer 1");
+  }
+  if (typeof subject !== "string") {
+    throw new SyntaxError("record.subject must be a string");
+  }
+  if (!Array.isArray(multiaddrs) || !multiaddrs.every((entry) => typeof entry === "string" && entry.length > 0)) {
+    throw new SyntaxError("record.multiaddrs must be an array of non-empty strings");
+  }
+  if (typeof updatedAt !== "string" || !isRfc3339DateTime(updatedAt)) {
+    throw new SyntaxError("record.updated_at must be an RFC 3339 date-time");
+  }
+  if (!(sequence instanceof JsonInteger) || !/^(0|[1-9][0-9]*)$/.test(sequence.lexeme) || !Number.isSafeInteger(Number(sequence.lexeme))) {
+    throw new SyntaxError("record.sequence must be a non-negative safe integer");
+  }
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw new SyntaxError("record.signature must be a non-empty string");
+  }
+  return {
+    subject,
+    multiaddrs,
+    updated_at: updatedAt,
+    sequence: Number(sequence.lexeme),
+    signature
+  };
+}
+function isRfc3339DateTime(value) {
+  const match = RFC3339_DATE_TIME.exec(value);
+  if (match === null) return false;
+  const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
+  const leap = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+  const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+  return daysInMonth !== void 0 && day >= 1 && day <= daysInMonth && hour <= 23 && minute <= 59 && second <= 59 && (match[8] === "Z" || Number(match[9]) <= 23 && Number(match[10]) <= 59);
+}
+async function verifyRecordSignature(record2) {
+  const payload = canonicalLocationPayload({
+    version: 1,
+    subject: record2.subject,
+    multiaddrs: record2.multiaddrs,
+    updated_at: record2.updated_at,
+    sequence: record2.sequence
+  });
+  const { signature } = record2;
+  if (record2.subject.startsWith("did:pkh:")) {
+    if (!/^0x[0-9a-fA-F]{130}$/.test(signature)) return false;
+    const r = BigInt(`0x${signature.slice(2, 66)}`);
+    const s = BigInt(`0x${signature.slice(66, 130)}`);
+    const v = parseInt(signature.slice(130), 16);
+    if (r === 0n || r >= SECP256K1_N || s === 0n || s > SECP256K1_N / 2n) return false;
+    if (v !== 0 && v !== 1 && v !== 27 && v !== 28) return false;
+    const address = record2.subject.slice(record2.subject.lastIndexOf(":") + 1);
+    try {
+      return await verifyMessage3({
+        address,
+        message: payload,
+        signature
+      });
+    } catch {
+      return false;
+    }
+  }
+  const publicKey = ed25519KeyFromDidKey(record2.subject);
+  if (publicKey === null || !/^[A-Za-z0-9_-]{86}$/.test(signature)) return false;
+  const bytes2 = new Uint8Array(64);
+  let buffer = 0;
+  let bits = 0;
+  let length2 = 0;
+  for (const char of signature) {
+    buffer = (buffer << 6 | BASE64URL.indexOf(char)) & 65535;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes2[length2++] = buffer >> bits & 255;
+    }
+  }
+  try {
+    return ed2551912.verify(bytes2, new TextEncoder().encode(payload), publicKey, { zip215: false });
+  } catch {
+    return false;
+  }
+}
+function multiaddrOrigin(address) {
+  const match = HOST_MULTIADDR.exec(address);
+  if (match === null) return null;
+  const [, protocol, host, portText, transport] = match;
+  const port = Number(portText);
+  if (port > 65535) return null;
+  let authority;
+  if (protocol === "ip4") {
+    if (!IPV4.test(host)) return null;
+    authority = host;
+  } else if (protocol === "ip6") {
+    if (!/^[0-9A-Fa-f:.]+$/.test(host) || !host.includes(":")) return null;
+    authority = `[${host}]`;
+  } else {
+    if (host.length > 253 || !DNS_NAME.test(host) || /^(0[xX][0-9a-fA-F]*|[0-9]+)$/.test(host.slice(host.lastIndexOf(".") + 1))) {
+      return null;
+    }
+    authority = host;
+  }
+  const scheme = transport === "http" ? "http" : "https";
+  try {
+    return new URL(`${scheme}://${authority}:${port}`).origin;
+  } catch {
+    return null;
+  }
+}
+
+// src/registry-policy.ts
+var DEFAULT_REGISTRY_OWNER_CHAIN_ID = 1;
+var DEFAULT_NEW_USER_HOST = DEFAULT_TINYCLOUD_FALLBACK_HOST;
+var DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS = 3e3;
+var DEFAULT_REGISTRY_SEQUENCE_STORAGE_KEY = "tinycloud.registrySequences.v1";
+var MAX_SUBJECT_LENGTH = 74;
+function registryOwnerSubjectV1(address, registryChainId = DEFAULT_REGISTRY_OWNER_CHAIN_ID) {
+  return pkhDid(address, registryChainId);
+}
+function createInMemoryRegistrySequenceStore() {
+  const sequences = /* @__PURE__ */ new Map();
+  return {
+    get: (subject) => sequences.get(subject),
+    set: (subject, sequence) => {
+      if ((sequences.get(subject) ?? -1) < sequence) sequences.set(subject, sequence);
+    }
+  };
+}
+function createLocalStorageRegistrySequenceStore(storage, storageKey = DEFAULT_REGISTRY_SEQUENCE_STORAGE_KEY) {
+  const backing = storage ?? defaultWebStorage();
+  const memory = createInMemoryRegistrySequenceStore();
+  if (!backing) {
+    return memory;
+  }
+  const read2 = () => {
+    const sequences = /* @__PURE__ */ new Map();
+    const raw = backing.getItem(storageKey);
+    if (raw === null) return sequences;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = void 0;
+    }
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      for (const [subject, sequence] of Object.entries(parsed)) {
+        if (!isSequence(sequence)) break;
+        sequences.set(subject, sequence);
+      }
+      if (sequences.size === Object.keys(parsed).length) return sequences;
+    }
+    throw new Error(`Corrupt registry sequence store "${storageKey}"`);
+  };
+  return {
+    get: async (subject) => {
+      const sequence = Math.max(read2().get(subject) ?? -1, await memory.get(subject) ?? -1);
+      return sequence < 0 ? void 0 : sequence;
+    },
+    set: async (subject, sequence) => {
+      await memory.set(subject, sequence);
+      const sequences = read2();
+      if ((sequences.get(subject) ?? -1) >= sequence) return;
+      sequences.set(subject, sequence);
+      backing.setItem(storageKey, JSON.stringify(Object.fromEntries(sequences)));
+    }
+  };
+}
+function isSequence(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+async function resolveOwnerHosts(subject, options2 = {}) {
+  if (typeof subject !== "string" || // Bounds the work below; covers any did:pkh with a safe-integer chain ID.
+  subject.length > MAX_SUBJECT_LENGTH || !isCanonicalSubject(subject)) {
+    throw new RegistryLookupInputError(
+      "invalid-subject",
+      "subject must be did:pkh:eip155:<chainId>:<EIP-55 address> or an Ed25519 did:key"
+    );
+  }
+  const store = options2.sequenceStore;
+  const remembered = store === void 0 ? void 0 : await store.get(subject);
+  const registryUrl = options2.registryUrl ?? DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL;
+  const url = `${registryUrl.replace(/\/$/, "")}/v1/locations/${encodeURIComponent(subject)}`;
+  const observed = await observeRegistry(
+    url,
+    options2.fetch ?? globalThis.fetch,
+    options2.timeoutMs ?? DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS
+  );
+  if (observed.kind === "oversize" || observed.kind === "invalid-utf8") {
+    const oversize = observed.kind === "oversize";
+    return {
+      status: "unavailable",
+      subject,
+      source: "offchain",
+      reason: oversize ? "oversize-response" : "malformed-response",
+      message: oversize ? "location registry response is too large" : "location registry response is not UTF-8",
+      hosts: []
+    };
+  }
+  const verdict = await classifyRegistryLookup(subject, observed, {
+    rememberedSequence: remembered ?? null
+  });
+  if (store !== void 0 && verdict.status === "registered" && (remembered === void 0 || verdict.sequence > remembered)) {
+    try {
+      await store.set(subject, verdict.sequence);
+    } catch (error) {
+      if (!sequenceWriteWarned) {
+        sequenceWriteWarned = true;
+        console.warn("[tinycloud:registry] could not remember the registry sequence:", error);
+      }
+    }
+  }
+  return verdict;
+}
+var sequenceWriteWarned = false;
+async function observeRegistry(url, fetchFn, timeoutMs) {
+  const controller = new AbortController();
+  let cancelTimer = () => void 0;
+  const timedOut = new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      controller.abort();
+      resolve({ kind: "timeout" });
+    }, timeoutMs);
+    cancelTimer = () => clearTimeout(timer);
+  });
+  try {
+    return await Promise.race([readRegistry(url, fetchFn, controller.signal), timedOut]);
+  } finally {
+    cancelTimer();
+  }
+}
+async function readRegistry(url, fetchFn, signal) {
+  let response;
+  try {
+    response = await fetchFn(url, {
+      redirect: "error",
+      headers: { accept: "application/json" },
+      signal
+    });
+  } catch {
+    return { kind: "network-error" };
+  }
+  if (response.status !== 200 && response.status !== 404) {
+    await response.body?.cancel().catch(() => void 0);
+    return { kind: "http", status: response.status, body: "" };
+  }
+  let bytes2;
+  try {
+    bytes2 = await boundedResponseBytes(response, REGISTRY_LOOKUP_MAX_BODY_BYTES);
+  } catch {
+    return { kind: "network-error" };
+  }
+  if (bytes2 === null) return { kind: "oversize" };
+  try {
+    return {
+      kind: "http",
+      status: response.status,
+      body: new TextDecoder("utf-8", { fatal: true }).decode(bytes2)
+    };
+  } catch {
+    return { kind: "invalid-utf8" };
+  }
+}
+var NodeNotFoundError = class extends Error {
+  constructor(subject, verdict) {
+    super(
+      verdict.status === "registered" ? `No usable TinyCloud host is registered for ${subject}` : `${subject} is not registered and newUserHost is null`
+    );
+    this.subject = subject;
+    this.verdict = verdict;
+    this.code = "node_not_found";
+    this.name = "NodeNotFoundError";
+  }
+};
+var RegistryUnavailableError = class extends Error {
+  constructor(subject, verdict, detail = {}) {
+    super(`Location registry unavailable for ${subject}: ${detail.message ?? verdict?.message}`);
+    this.subject = subject;
+    this.verdict = verdict;
+    this.code = "registry_unavailable";
+    this.name = "RegistryUnavailableError";
+    if (detail.cause !== void 0) this.cause = detail.cause;
+  }
+};
+var NodeRegistryEntryExistsError = class extends Error {
+  constructor(subject, host, verdict) {
+    super(`The registry entry for ${subject} does not list ${host}`);
+    this.subject = subject;
+    this.host = host;
+    this.verdict = verdict;
+    this.code = "node_registry_entry_exists";
+    this.name = "NodeRegistryEntryExistsError";
+    this.registeredHosts = secureRecordHosts(verdict);
+  }
+};
+async function lookupOwnerRegistryVerdict(subject, options2 = {}) {
+  if (options2.registryUrl === null) {
+    throw new RegistryUnavailableError(subject, void 0, {
+      message: "no location registry is configured"
+    });
+  }
+  try {
+    return await resolveOwnerHosts(subject, {
+      registryUrl: options2.registryUrl,
+      sequenceStore: options2.sequenceStore,
+      fetch: options2.fetch,
+      timeoutMs: options2.timeoutMs
+    });
+  } catch (error) {
+    throw new RegistryUnavailableError(subject, void 0, {
+      message: error instanceof Error ? error.message : String(error),
+      cause: error
+    });
+  }
+}
+async function resolveFailClosedTinyCloudHosts(address, options2 = {}) {
+  const newUserHost = options2.newUserHost === null ? null : exactHttpOrigin(options2.newUserHost ?? DEFAULT_NEW_USER_HOST, "newUserHost");
+  const subject = registryOwnerSubjectV1(address, options2.registryChainId);
+  const resolve = async () => {
+    let verdict;
+    let unavailable;
+    try {
+      verdict = await lookupOwnerRegistryVerdict(subject, options2);
+    } catch (error) {
+      if (!(error instanceof RegistryUnavailableError)) throw error;
+      unavailable = error;
+    }
+    if (options2.autoDiscoverLocalNode ?? true) {
+      const linkNames = verdict?.status === "registered" ? secureRecordHosts(verdict).flatMap((host) => LOCAL_LINK_ORIGIN.exec(host)?.[1] ?? []) : [];
+      for (const candidate of [
+        { localNodeUrl: options2.localNodeUrl, localLinkName: options2.localLinkName },
+        ...linkNames.map((localLinkName) => ({ localLinkName }))
+      ]) {
+        const local = await discoverLocalTinyCloudNode({
+          ...candidate,
+          expectedNodeDid: options2.expectedNodeDid,
+          identityStore: options2.localNodeIdentityStore,
+          fetch: options2.fetch
+        });
+        if (local) return { hosts: [local.url], ...verdict === void 0 ? {} : { verdict } };
+      }
+    }
+    if (verdict === void 0) throw unavailable;
+    return { hosts: hostsForVerdict(verdict, newUserHost), verdict };
+  };
+  for (let attempt = 1; ; attempt++) {
+    let failure;
+    try {
+      return await resolve();
+    } catch (error) {
+      if (!(error instanceof NodeNotFoundError) && !(error instanceof RegistryUnavailableError)) {
+        throw error;
+      }
+      failure = error;
+    }
+    if (!options2.onNodeNotFound) throw failure;
+    const decision = await options2.onNodeNotFound({ error: failure, attempt });
+    switch (decision?.action) {
+      case "retry":
+        continue;
+      case "use-host":
+        return {
+          hosts: [exactHttpOrigin(decision.host, "onNodeNotFound host")],
+          ...failure.verdict === void 0 ? {} : { verdict: failure.verdict }
+        };
+      case "abort":
+        throw failure;
+      default:
+        throw new TypeError("onNodeNotFound returned an unknown action");
+    }
+  }
+}
+var LOCAL_LINK_ORIGIN = /^https:\/\/([a-z0-9-]+)\.local\.tinycloud\.link$/;
+function secureRecordHosts(verdict) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const host of verdict.hosts) {
+    for (const url of host.urls) {
+      try {
+        hosts.add(exactHttpOrigin(url, "registry host"));
+      } catch {
+      }
+    }
+  }
+  return [...hosts];
+}
+function hostsForVerdict(verdict, newUserHost) {
+  switch (verdict.status) {
+    case "registered": {
+      const hosts = secureRecordHosts(verdict);
+      if (hosts.length === 0) throw new NodeNotFoundError(verdict.subject, verdict);
+      return hosts;
+    }
+    case "unregistered":
+      if (newUserHost === null) throw new NodeNotFoundError(verdict.subject, verdict);
+      return [newUserHost];
+    case "unavailable":
+      throw new RegistryUnavailableError(verdict.subject, verdict);
+  }
+}
+function assertSpaceCreationAllowed(verdict, host) {
+  switch (verdict.status) {
+    case "unregistered":
+      return;
+    case "unavailable":
+      throw new RegistryUnavailableError(verdict.subject, verdict);
+    case "registered": {
+      const origin2 = httpOrigin(host);
+      if (origin2 !== void 0 && secureRecordHosts(verdict).includes(origin2)) {
+        return;
+      }
+      throw new NodeRegistryEntryExistsError(verdict.subject, host, verdict);
+    }
+  }
+}
+function httpOrigin(host) {
+  try {
+    const url = new URL(host);
+    return url.protocol === "https:" || url.protocol === "http:" ? url.origin : void 0;
+  } catch {
+    return void 0;
+  }
+}
 export {
   ACCOUNT_INDEX_SCHEMA2 as ACCOUNT_INDEX_SCHEMA,
   ACCOUNT_MANIFEST_PERMISSIONS2 as ACCOUNT_MANIFEST_PERMISSIONS,
@@ -18974,6 +19679,10 @@ export {
   DEFAULT_LOCAL_NODE_URL,
   DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION,
+  DEFAULT_NEW_USER_HOST,
+  DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS,
+  DEFAULT_REGISTRY_OWNER_CHAIN_ID,
+  DEFAULT_REGISTRY_SEQUENCE_STORAGE_KEY,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DEFAULT_TINYCLOUD_FALLBACK_HOST,
   DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
@@ -19030,6 +19739,8 @@ export {
   NATIVE_PROJECTION_V1_DOMAIN,
   NETWORK_NAME_PATTERN,
   NetworkIdError,
+  NodeNotFoundError,
+  NodeRegistryEntryExistsError,
   OPENKEY_ACTION_ID_SEPARATOR,
   OWNER_NODE_BINDING_TIMEOUT_MS,
   OpenKeyManageKeyError,
@@ -19058,6 +19769,8 @@ export {
   PermissionNotInManifestError,
   PrefixedKVService,
   ProtocolMismatchError,
+  REGISTRY_LOOKUP_MAX_BODY_BYTES,
+  REGISTRY_NOT_FOUND_BODY,
   REQUESTER_ENGINE_RETRY_ATTEMPTS,
   REQUESTER_ENGINE_RETRY_MAX_DELAY_MS,
   REQUESTER_NEAR_EXPIRY_SECONDS,
@@ -19066,6 +19779,8 @@ export {
   ROOT_STATUS_CHECKPOINT_V1_SCHEMA,
   ROOT_STATUS_RENEWAL_V1_DOMAIN,
   ROOT_STATUS_V1_DOMAIN,
+  RegistryLookupInputError,
+  RegistryUnavailableError,
   SECRETS_SPACE,
   SECRET_NAME_RE2 as SECRET_NAME_RE,
   SECRET_RECORDS_SCHEMA,
@@ -19135,6 +19850,7 @@ export {
   admitPolicyCredentialV4,
   appSecretScope,
   applyPrefix,
+  assertSpaceCreationAllowed,
   authorizationVerdictOf2 as authorizationVerdictOf,
   bootstrapEncryptionNetworkId,
   bootstrapSpaceId,
@@ -19165,6 +19881,7 @@ export {
   canonicalizeUnifiedPolicyCapability,
   checkDecryptInvocationInput,
   checkNodeInfo,
+  classifyRegistryLookup,
   clearTinyCloudDebugLogs,
   compactAttenuationContains,
   composeBootstrapSpaceManifest,
@@ -19182,7 +19899,9 @@ export {
   createEmailDomainCredentialRequirement,
   createHolderBinding,
   createInMemoryLocalNodeIdentityStore,
+  createInMemoryRegistrySequenceStore,
   createLocalStorageLocalNodeIdentityStore,
+  createLocalStorageRegistrySequenceStore,
   createOpenKeyCallbackSigningStrategy,
   createOpenKeyManageKeySigningStrategy,
   createPolicyEnforcementDelegation,
@@ -19266,6 +19985,7 @@ export {
   jcsCanonicalize,
   loadManifest,
   locationPayloadForRecord,
+  lookupOwnerRegistryVerdict,
   mailboxBelongsToDomain,
   makePkhSpaceId,
   makePublicSpaceId,
@@ -19314,11 +20034,14 @@ export {
   publishLocationRecord,
   recapCaveatsEqual,
   registerPolicyV3,
+  registryOwnerSubjectV1,
   renewPolicyRootStatusV3,
   requestTinyCloudManageKeyScope,
   resolveCloudLocation,
+  resolveFailClosedTinyCloudHosts,
   resolveManifest,
   resolveManifestKnowledgeRoot,
+  resolveOwnerHosts,
   resolveSecretListPrefix,
   resolveSecretPath2 as resolveSecretPath,
   resolveTinyCloudHosts,