@tinycloud/sdk-core 2.8.0-beta.0 → 2.9.0-beta.0

package/dist/index.cjs

@@ -69,6 +69,8 @@ __export(index_exports, {
   DEFAULT_EXPIRY: () => DEFAULT_EXPIRY,
   DEFAULT_KEY_VERSION: () => import_sdk_services7.DEFAULT_KEY_VERSION,
   DEFAULT_KNOWLEDGE_ROOT: () => DEFAULT_KNOWLEDGE_ROOT,
+  DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY: () => DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY,
+  DEFAULT_LOCAL_NODE_URL: () => DEFAULT_LOCAL_NODE_URL,
   DEFAULT_MANIFEST_SPACE: () => DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION: () => DEFAULT_MANIFEST_VERSION,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS: () => DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
@@ -103,6 +105,9 @@ __export(index_exports, {
   KV: () => import_bootstrap3.KV,
   KVService: () => import_sdk_services7.KVService,
   LISTEN_SQL_STATEMENT_CATALOG: () => LISTEN_SQL_STATEMENT_CATALOG,
+  LOCAL_LINK_HOST_SUFFIX: () => LOCAL_LINK_HOST_SUFFIX,
+  LOCAL_LINK_PROBE_TIMEOUT_MS: () => LOCAL_LINK_PROBE_TIMEOUT_MS,
+  LOCAL_LOOPBACK_PROBE_TIMEOUT_MS: () => LOCAL_LOOPBACK_PROBE_TIMEOUT_MS,
   LocationRecordValidationError: () => LocationRecordValidationError,
   ManifestValidationError: () => ManifestValidationError,
   NETWORK_NAME_PATTERN: () => import_sdk_services7.NETWORK_NAME_PATTERN,
@@ -198,6 +203,8 @@ __export(index_exports, {
   createAndSignPolicyStatus: () => createAndSignPolicyStatus,
   createAndSignSignedObject: () => createAndSignSignedObject,
   createCapabilityKeyRegistry: () => createCapabilityKeyRegistry,
+  createInMemoryLocalNodeIdentityStore: () => createInMemoryLocalNodeIdentityStore,
+  createLocalStorageLocalNodeIdentityStore: () => createLocalStorageLocalNodeIdentityStore,
   createOpenKeyCallbackSigningStrategy: () => createOpenKeyCallbackSigningStrategy,
   createSharingService: () => createSharingService,
   createSpaceService: () => createSpaceService,
@@ -213,6 +220,7 @@ __export(index_exports, {
   didCacheKey: () => didCacheKey,
   didEquals: () => didEquals,
   disableTinyCloudDebug: () => import_sdk_services7.disableTinyCloudDebug,
+  discoverLocalTinyCloudNode: () => discoverLocalTinyCloudNode,
   discoverNetwork: () => import_sdk_services7.discoverNetwork,
   enableTinyCloudDebug: () => import_sdk_services7.enableTinyCloudDebug,
   encryptToNetwork: () => import_sdk_services7.encryptToNetwork,
@@ -12449,6 +12457,54 @@ var import_ed255193 = require("@noble/curves/ed25519");
 var import_viem5 = require("viem");
 var DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
 var DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+var DEFAULT_LOCAL_NODE_URL = "http://127.0.0.1:8000";
+var LOCAL_LOOPBACK_PROBE_TIMEOUT_MS = 250;
+var LOCAL_LINK_PROBE_TIMEOUT_MS = 750;
+var LOCAL_LINK_HOST_SUFFIX = ".local.tinycloud.link";
+function createInMemoryLocalNodeIdentityStore() {
+  const pins = /* @__PURE__ */ new Map();
+  return {
+    get: (url) => pins.get(url),
+    set: (url, nodeDid) => {
+      pins.set(url, nodeDid);
+    }
+  };
+}
+var DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY = "tinycloud.localNodePins.v1";
+function defaultWebStorage() {
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function createLocalStorageLocalNodeIdentityStore(storage, storageKey = DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY) {
+  const backing = storage ?? defaultWebStorage();
+  if (!backing) {
+    return createInMemoryLocalNodeIdentityStore();
+  }
+  const readPins = () => {
+    const raw = backing.getItem(storageKey);
+    if (!raw) return {};
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+    }
+    backing.removeItem(storageKey);
+    return {};
+  };
+  return {
+    get: (url) => readPins()[url],
+    set: (url, nodeDid) => {
+      const pins = readPins();
+      pins[url] = nodeDid;
+      backing.setItem(storageKey, JSON.stringify(pins));
+    }
+  };
+}
 var LocationRecordValidationError = class extends Error {
   constructor(message) {
     super(`Location record validation failed: ${message}`);
@@ -12575,6 +12631,33 @@ async function resolveCloudLocation(subject, options2 = {}) {
   };
 }
 async function resolveTinyCloudHosts(subject, options2 = {}) {
+  const hasExplicitHosts = options2.explicitHosts !== void 0 && options2.explicitHosts.length > 0;
+  const fetchFn = memoizeFetch(options2.fetch ?? globalThis.fetch);
+  if (!hasExplicitHosts && (options2.autoDiscoverLocalNode ?? true)) {
+    const local = await discoverLocalTinyCloudNode({
+      subject,
+      autoDiscoverLocalNode: true,
+      localNodeUrl: options2.localNodeUrl,
+      localLinkName: options2.localLinkName,
+      registryUrl: options2.registryUrl,
+      expectedNodeDid: options2.expectedNodeDid,
+      identityStore: options2.localNodeIdentityStore,
+      verifyRecords: options2.verifyRecords,
+      fetch: fetchFn
+    });
+    if (local) {
+      const multiaddrs = [httpUrlToMultiaddr(local.url)];
+      const candidate = { source: local.source, multiaddrs };
+      const location2 = {
+        subject,
+        source: local.source,
+        multiaddrs,
+        attempts: [{ source: local.source, candidate }],
+        resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return { hosts: [local.url], location: location2 };
+    }
+  }
   const location = await resolveCloudLocation(subject, {
     explicitMultiaddrs: hostsToMultiaddrs(options2.explicitHosts),
     blockchain: options2.blockchain,
@@ -12582,7 +12665,7 @@ async function resolveTinyCloudHosts(subject, options2 = {}) {
     fallbackMultiaddrs: hostsToMultiaddrs(
       options2.fallbackHosts === null ? void 0 : options2.fallbackHosts ?? [DEFAULT_TINYCLOUD_FALLBACK_HOST]
     ),
-    fetch: options2.fetch,
+    fetch: fetchFn,
     verifyRecords: options2.verifyRecords
   });
   return {
@@ -12590,6 +12673,181 @@ async function resolveTinyCloudHosts(subject, options2 = {}) {
     location
   };
 }
+function memoizeFetch(fetchFn) {
+  const cache2 = /* @__PURE__ */ new Map();
+  return (async (input, init) => {
+    const key = String(input);
+    let cached = cache2.get(key);
+    if (!cached) {
+      cached = fetchFn(input, init);
+      cache2.set(key, cached);
+    }
+    const response = await cached;
+    return response.clone();
+  });
+}
+async function discoverLocalTinyCloudNode(options2 = {}) {
+  if ((options2.autoDiscoverLocalNode ?? true) === false) {
+    return null;
+  }
+  const fetchFn = options2.fetch ?? globalThis.fetch;
+  const identityStore = options2.identityStore ?? defaultLocalNodeIdentityStore;
+  const staticCandidates = [
+    {
+      source: "local-loopback",
+      url: options2.localNodeUrl ?? DEFAULT_LOCAL_NODE_URL,
+      timeoutMs: LOCAL_LOOPBACK_PROBE_TIMEOUT_MS
+    }
+  ];
+  if (options2.localLinkName) {
+    if (isValidDnsLabel(options2.localLinkName)) {
+      staticCandidates.push({
+        source: "local-link",
+        url: `https://${options2.localLinkName}${LOCAL_LINK_HOST_SUFFIX}`,
+        timeoutMs: LOCAL_LINK_PROBE_TIMEOUT_MS
+      });
+    } else {
+      debugLog(
+        `localLinkName "${options2.localLinkName}" is not a valid DNS label; skipping`
+      );
+    }
+  }
+  for (const candidate of staticCandidates) {
+    const adopted = await probeAndVerifyLocalCandidate(
+      candidate,
+      fetchFn,
+      identityStore,
+      options2.expectedNodeDid
+    );
+    if (adopted) {
+      return adopted;
+    }
+  }
+  const registryCandidates = await fetchRegistryLocalLinkCandidates(
+    options2,
+    fetchFn,
+    staticCandidates
+  );
+  for (const candidate of registryCandidates) {
+    const adopted = await probeAndVerifyLocalCandidate(
+      candidate,
+      fetchFn,
+      identityStore,
+      options2.expectedNodeDid
+    );
+    if (adopted) {
+      return adopted;
+    }
+  }
+  return null;
+}
+var defaultLocalNodeIdentityStore = createInMemoryLocalNodeIdentityStore();
+function debugLog(message) {
+  console.debug(`[tinycloud:location] ${message}`);
+}
+async function probeAndVerifyLocalCandidate(candidate, fetchFn, identityStore, expectedNodeDid) {
+  const healthy = await probeHealthz(candidate.url, candidate.timeoutMs, fetchFn);
+  if (!healthy) {
+    return null;
+  }
+  const info = await fetchLocalNodeInfo(candidate.url, candidate.timeoutMs, fetchFn);
+  if (!info?.nodeDid) {
+    debugLog(`local node at ${candidate.url} did not report a nodeId DID; skipping`);
+    return null;
+  }
+  const pinnedNodeDid = await identityStore.get(candidate.url);
+  const expected = expectedNodeDid ?? pinnedNodeDid;
+  if (expected !== void 0 && expected !== info.nodeDid) {
+    debugLog(
+      `local node DID mismatch at ${candidate.url}: expected ${expected}, got ${info.nodeDid}`
+    );
+    return null;
+  }
+  if (pinnedNodeDid === void 0 || expectedNodeDid !== void 0) {
+    await identityStore.set(candidate.url, info.nodeDid);
+  }
+  return { source: candidate.source, url: candidate.url, nodeDid: info.nodeDid };
+}
+async function fetchRegistryLocalLinkCandidates(options2, fetchFn, existingCandidates) {
+  if (!options2.subject || options2.registryUrl === null) {
+    return [];
+  }
+  const registryUrl = options2.registryUrl ?? DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL;
+  try {
+    const record = await fetchLocationRecord(registryUrl, options2.subject, fetchFn);
+    if (!record) {
+      return [];
+    }
+    const shouldVerify = options2.verifyRecords ?? true;
+    if (shouldVerify && !await verifyLocationRecord(record)) {
+      debugLog(
+        `registry record signature invalid for ${options2.subject}; skipping local-link lookup`
+      );
+      return [];
+    }
+    return extractLocalLinkUrls(record).filter((url) => !existingCandidates.some((c) => c.url === url)).map((url) => ({
+      source: "local-link",
+      url,
+      timeoutMs: LOCAL_LINK_PROBE_TIMEOUT_MS
+    }));
+  } catch {
+    return [];
+  }
+}
+function extractLocalLinkUrls(record) {
+  if (!record) {
+    return [];
+  }
+  const urls = [];
+  for (const addr of record.multiaddrs) {
+    let url;
+    try {
+      url = multiaddrToHttpUrl(addr);
+    } catch {
+      continue;
+    }
+    if (isLocalLinkUrl(url)) {
+      urls.push(url);
+    }
+  }
+  return urls;
+}
+var DNS_LABEL_REGEX = /^[a-z0-9]([a-z0-9-]{1,30}[a-z0-9])?$/;
+function isValidDnsLabel(value) {
+  return DNS_LABEL_REGEX.test(value);
+}
+function isLocalLinkUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" && parsed.hostname.endsWith(LOCAL_LINK_HOST_SUFFIX);
+  } catch {
+    return false;
+  }
+}
+async function probeHealthz(url, timeoutMs, fetchFn) {
+  try {
+    const response = await fetchFn(`${url.replace(/\/$/, "")}/healthz`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+async function fetchLocalNodeInfo(url, timeoutMs, fetchFn) {
+  try {
+    const response = await fetchFn(`${url.replace(/\/$/, "")}/info`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const body = await response.json();
+    return { nodeDid: body.nodeId };
+  } catch {
+    return null;
+  }
+}
 function multiaddrToHttpUrl(input) {
   const uri = multiaddrToUri(multiaddr(input));
   if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
@@ -12866,6 +13124,8 @@ function decodeBase64Url(value) {
   DEFAULT_EXPIRY,
   DEFAULT_KEY_VERSION,
   DEFAULT_KNOWLEDGE_ROOT,
+  DEFAULT_LOCAL_NODE_PIN_STORAGE_KEY,
+  DEFAULT_LOCAL_NODE_URL,
   DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION,
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
@@ -12900,6 +13160,9 @@ function decodeBase64Url(value) {
   KV,
   KVService,
   LISTEN_SQL_STATEMENT_CATALOG,
+  LOCAL_LINK_HOST_SUFFIX,
+  LOCAL_LINK_PROBE_TIMEOUT_MS,
+  LOCAL_LOOPBACK_PROBE_TIMEOUT_MS,
   LocationRecordValidationError,
   ManifestValidationError,
   NETWORK_NAME_PATTERN,
@@ -12995,6 +13258,8 @@ function decodeBase64Url(value) {
   createAndSignPolicyStatus,
   createAndSignSignedObject,
   createCapabilityKeyRegistry,
+  createInMemoryLocalNodeIdentityStore,
+  createLocalStorageLocalNodeIdentityStore,
   createOpenKeyCallbackSigningStrategy,
   createSharingService,
   createSpaceService,
@@ -13010,6 +13275,7 @@ function decodeBase64Url(value) {
   didCacheKey,
   didEquals,
   disableTinyCloudDebug,
+  discoverLocalTinyCloudNode,
   discoverNetwork,
   enableTinyCloudDebug,
   encryptToNetwork,