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

package/dist/index.cjs

@@ -86,6 +86,10 @@ __export(index_exports, {
   DEFAULT_LOCAL_NODE_URL: () => DEFAULT_LOCAL_NODE_URL,
   DEFAULT_MANIFEST_SPACE: () => DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION: () => DEFAULT_MANIFEST_VERSION,
+  DEFAULT_NEW_USER_HOST: () => DEFAULT_NEW_USER_HOST,
+  DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS: () => DEFAULT_REGISTRY_LOOKUP_TIMEOUT_MS,
+  DEFAULT_REGISTRY_OWNER_CHAIN_ID: () => DEFAULT_REGISTRY_OWNER_CHAIN_ID,
+  DEFAULT_REGISTRY_SEQUENCE_STORAGE_KEY: () => DEFAULT_REGISTRY_SEQUENCE_STORAGE_KEY,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS: () => DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DEFAULT_TINYCLOUD_FALLBACK_HOST: () => DEFAULT_TINYCLOUD_FALLBACK_HOST,
   DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL: () => DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
@@ -142,6 +146,8 @@ __export(index_exports, {
   NATIVE_PROJECTION_V1_DOMAIN: () => NATIVE_PROJECTION_V1_DOMAIN,
   NETWORK_NAME_PATTERN: () => import_sdk_services9.NETWORK_NAME_PATTERN,
   NetworkIdError: () => import_sdk_services9.NetworkIdError,
+  NodeNotFoundError: () => NodeNotFoundError,
+  NodeRegistryEntryExistsError: () => NodeRegistryEntryExistsError,
   OPENKEY_ACTION_ID_SEPARATOR: () => OPENKEY_ACTION_ID_SEPARATOR,
   OWNER_NODE_BINDING_TIMEOUT_MS: () => OWNER_NODE_BINDING_TIMEOUT_MS,
   OpenKeyManageKeyError: () => OpenKeyManageKeyError,
@@ -181,6 +187,7 @@ __export(index_exports, {
   ROOT_STATUS_RENEWAL_V1_DOMAIN: () => ROOT_STATUS_RENEWAL_V1_DOMAIN,
   ROOT_STATUS_V1_DOMAIN: () => ROOT_STATUS_V1_DOMAIN,
   RegistryLookupInputError: () => RegistryLookupInputError,
+  RegistryUnavailableError: () => RegistryUnavailableError,
   SECRETS_SPACE: () => SECRETS_SPACE,
   SECRET_NAME_RE: () => import_sdk_services9.SECRET_NAME_RE,
   SECRET_RECORDS_SCHEMA: () => import_bootstrap4.SECRET_RECORDS_SCHEMA,
@@ -250,6 +257,7 @@ __export(index_exports, {
   admitPolicyCredentialV4: () => admitPolicyCredentialV4,
   appSecretScope: () => import_sdk_services9.appSecretScope,
   applyPrefix: () => applyPrefix,
+  assertSpaceCreationAllowed: () => assertSpaceCreationAllowed,
   authorizationVerdictOf: () => import_sdk_services9.authorizationVerdictOf,
   bootstrapEncryptionNetworkId: () => import_bootstrap4.bootstrapEncryptionNetworkId,
   bootstrapSpaceId: () => import_bootstrap4.bootstrapSpaceId,
@@ -298,7 +306,9 @@ __export(index_exports, {
   createEmailDomainCredentialRequirement: () => createEmailDomainCredentialRequirement,
   createHolderBinding: () => createHolderBinding,
   createInMemoryLocalNodeIdentityStore: () => createInMemoryLocalNodeIdentityStore,
+  createInMemoryRegistrySequenceStore: () => createInMemoryRegistrySequenceStore,
   createLocalStorageLocalNodeIdentityStore: () => createLocalStorageLocalNodeIdentityStore,
+  createLocalStorageRegistrySequenceStore: () => createLocalStorageRegistrySequenceStore,
   createOpenKeyCallbackSigningStrategy: () => createOpenKeyCallbackSigningStrategy,
   createOpenKeyManageKeySigningStrategy: () => createOpenKeyManageKeySigningStrategy,
   createPolicyEnforcementDelegation: () => createPolicyEnforcementDelegation,
@@ -382,6 +392,7 @@ __export(index_exports, {
   jcsCanonicalize: () => jcsCanonicalize,
   loadManifest: () => loadManifest,
   locationPayloadForRecord: () => locationPayloadForRecord,
+  lookupOwnerRegistryVerdict: () => lookupOwnerRegistryVerdict,
   mailboxBelongsToDomain: () => import_share_envelope.mailboxBelongsToDomain,
   makePkhSpaceId: () => makePkhSpaceId,
   makePublicSpaceId: () => makePublicSpaceId,
@@ -430,11 +441,14 @@ __export(index_exports, {
   publishLocationRecord: () => publishLocationRecord,
   recapCaveatsEqual: () => recapCaveatsEqual,
   registerPolicyV3: () => registerPolicyV3,
+  registryOwnerSubjectV1: () => registryOwnerSubjectV1,
   renewPolicyRootStatusV3: () => renewPolicyRootStatusV3,
   requestTinyCloudManageKeyScope: () => requestTinyCloudManageKeyScope,
   resolveCloudLocation: () => resolveCloudLocation,
+  resolveFailClosedTinyCloudHosts: () => resolveFailClosedTinyCloudHosts,
   resolveManifest: () => resolveManifest,
   resolveManifestKnowledgeRoot: () => resolveManifestKnowledgeRoot,
+  resolveOwnerHosts: () => resolveOwnerHosts,
   resolveSecretListPrefix: () => import_sdk_services9.resolveSecretListPrefix,
   resolveSecretPath: () => import_sdk_services9.resolveSecretPath,
   resolveTinyCloudHosts: () => resolveTinyCloudHosts,
@@ -18710,11 +18724,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) => {
@@ -18927,11 +18946,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;
@@ -18943,7 +18969,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);
     }
@@ -18956,7 +18982,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) {
@@ -19635,4 +19661,316 @@ function multiaddrOrigin(address) {
     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;
+  }
+}
 //# sourceMappingURL=index.cjs.map