@tinycloud/sdk-core 2.2.0-beta.1 → 2.2.0-beta.4

package/dist/index.cjs

@@ -36,10 +36,13 @@ __export(index_exports, {
   CapabilityKeyRegistry: () => CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes: () => CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema: () => ClientSessionSchema,
+  CloudLocationResolutionError: () => CloudLocationResolutionError,
   DEFAULT_DEFAULTS: () => DEFAULT_DEFAULTS,
   DEFAULT_EXPIRY: () => DEFAULT_EXPIRY,
   DEFAULT_MANIFEST_SPACE: () => DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION: () => DEFAULT_MANIFEST_VERSION,
+  DEFAULT_TINYCLOUD_FALLBACK_HOST: () => DEFAULT_TINYCLOUD_FALLBACK_HOST,
+  DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL: () => DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
   DataVaultService: () => import_sdk_services4.DataVaultService,
   DatabaseHandle: () => import_sdk_services4.DatabaseHandle,
   DelegationErrorCodes: () => DelegationErrorCodes,
@@ -51,6 +54,7 @@ __export(index_exports, {
   ErrorCodes: () => import_sdk_services4.ErrorCodes,
   HooksService: () => import_sdk_services4.HooksService,
   KVService: () => import_sdk_services4.KVService,
+  LocationRecordValidationError: () => LocationRecordValidationError,
   ManifestValidationError: () => ManifestValidationError,
   PermissionNotInManifestError: () => PermissionNotInManifestError,
   PrefixedKVService: () => import_sdk_services4.PrefixedKVService,
@@ -76,6 +80,7 @@ __export(index_exports, {
   activateSessionWithHost: () => activateSessionWithHost,
   applyPrefix: () => applyPrefix,
   buildSpaceUri: () => buildSpaceUri,
+  canonicalLocationPayload: () => canonicalLocationPayload,
   checkNodeInfo: () => checkNodeInfo,
   composeManifestRequest: () => composeManifestRequest,
   createCapabilityKeyRegistry: () => createCapabilityKeyRegistry,
@@ -87,24 +92,34 @@ __export(index_exports, {
   defaultSpaceCreationHandler: () => defaultSpaceCreationHandler,
   err: () => import_sdk_services4.err,
   expandActionShortNames: () => expandActionShortNames,
+  fetchLocationRecord: () => fetchLocationRecord,
   fetchPeerId: () => fetchPeerId,
+  httpUrlToMultiaddr: () => httpUrlToMultiaddr,
   isCapabilitySubset: () => isCapabilitySubset,
   loadManifest: () => loadManifest,
+  locationPayloadForRecord: () => locationPayloadForRecord,
   makePublicSpaceId: () => makePublicSpaceId,
   manifestAbilitiesUnion: () => manifestAbilitiesUnion,
+  multiaddrToHttpUrl: () => multiaddrToHttpUrl,
   normalizeDefaults: () => normalizeDefaults,
   ok: () => import_sdk_services4.ok,
   parseExpiry: () => parseExpiry,
   parseRecapCapabilities: () => parseRecapCapabilities,
   parseSpaceUri: () => parseSpaceUri,
+  resolveCloudLocation: () => resolveCloudLocation,
   resolveManifest: () => resolveManifest,
+  resolveTinyCloudHosts: () => resolveTinyCloudHosts,
   resourceCapabilitiesToAbilitiesMap: () => resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap: () => resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError: () => import_sdk_services4.serviceError,
+  signLocationRecord: () => signLocationRecord,
   submitHostDelegation: () => submitHostDelegation,
   validateClientSession: () => validateClientSession,
+  validateLocationRecord: () => validateLocationRecord,
+  validateLocationRecordPayload: () => validateLocationRecordPayload,
   validateManifest: () => validateManifest,
-  validatePersistedSessionData: () => validatePersistedSessionData
+  validatePersistedSessionData: () => validatePersistedSessionData,
+  verifyLocationRecord: () => verifyLocationRecord
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -4330,6 +4345,394 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
   };
 }
 
+// src/location.ts
+var import_multiaddr = require("@multiformats/multiaddr");
+var import_multiaddr_to_uri = require("@multiformats/multiaddr-to-uri");
+var import_uri_to_multiaddr = require("@multiformats/uri-to-multiaddr");
+var import_ed25519 = require("@noble/curves/ed25519");
+var import_basics = require("multiformats/basics");
+var import_viem = require("viem");
+var DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL = "https://registry.tinycloud.xyz";
+var DEFAULT_TINYCLOUD_FALLBACK_HOST = "https://node.tinycloud.xyz";
+var LocationRecordValidationError = class extends Error {
+  constructor(message) {
+    super(`Location record validation failed: ${message}`);
+    this.name = "LocationRecordValidationError";
+  }
+};
+var CloudLocationResolutionError = class extends Error {
+  constructor(subject, attempts) {
+    super(`Unable to resolve TinyCloud location for ${subject}`);
+    this.name = "CloudLocationResolutionError";
+    this.attempts = attempts;
+  }
+};
+function locationPayloadForRecord(record) {
+  return {
+    version: record.version,
+    subject: record.subject,
+    multiaddrs: [...record.multiaddrs],
+    updated_at: record.updated_at,
+    sequence: record.sequence
+  };
+}
+function canonicalLocationPayload(payload) {
+  return JSON.stringify({
+    version: payload.version,
+    subject: payload.subject,
+    multiaddrs: payload.multiaddrs,
+    updated_at: payload.updated_at,
+    sequence: payload.sequence
+  });
+}
+async function signLocationRecord(payload, signer) {
+  validateLocationRecordPayload(payload);
+  const message = canonicalLocationPayload(payload);
+  const signature = signer.type === "did:pkh" ? await signer.signMessage(message) : base64UrlEncode2(
+    await signer.signBytes(new TextEncoder().encode(message))
+  );
+  return { ...payload, signature };
+}
+function validateLocationRecordPayload(input) {
+  if (input === null || typeof input !== "object") {
+    throw new LocationRecordValidationError("payload must be an object");
+  }
+  const payload = input;
+  if (payload.version !== 1) {
+    throw new LocationRecordValidationError("version must be 1");
+  }
+  validateSubject(payload.subject);
+  validateMultiaddrs(payload.multiaddrs);
+  if (typeof payload.updated_at !== "string" || Number.isNaN(Date.parse(payload.updated_at))) {
+    throw new LocationRecordValidationError(
+      "updated_at must be an ISO timestamp"
+    );
+  }
+  if (typeof payload.sequence !== "number" || !Number.isSafeInteger(payload.sequence) || payload.sequence < 0) {
+    throw new LocationRecordValidationError(
+      "sequence must be a non-negative safe integer"
+    );
+  }
+  return {
+    version: 1,
+    subject: payload.subject,
+    multiaddrs: [...payload.multiaddrs],
+    updated_at: payload.updated_at,
+    sequence: payload.sequence
+  };
+}
+function validateLocationRecord(input) {
+  const payload = validateLocationRecordPayload(input);
+  const signature = input.signature;
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw new LocationRecordValidationError(
+      "signature must be a non-empty string"
+    );
+  }
+  return { ...payload, signature };
+}
+async function verifyLocationRecord(input) {
+  const record = validateLocationRecord(input);
+  const payload = canonicalLocationPayload(locationPayloadForRecord(record));
+  if (record.subject.startsWith("did:pkh:")) {
+    return verifyPkhSignature(record.subject, payload, record.signature);
+  }
+  if (record.subject.startsWith("did:key:")) {
+    return verifyDidKeySignature(record.subject, payload, record.signature);
+  }
+  return false;
+}
+async function fetchLocationRecord(registryUrl, subject, fetchFn = globalThis.fetch) {
+  const url = `${registryUrl.replace(/\/$/, "")}/v1/locations/${encodeURIComponent(subject)}`;
+  const response = await fetchFn(url);
+  if (response.status === 404) {
+    return null;
+  }
+  if (!response.ok) {
+    throw new Error(`location registry returned HTTP ${response.status}`);
+  }
+  const body = await response.json();
+  if (body.record === void 0) {
+    throw new LocationRecordValidationError("registry response missing record");
+  }
+  return validateLocationRecord(body.record);
+}
+async function resolveCloudLocation(subject, options = {}) {
+  validateSubject(subject);
+  const verifyRecords = options.verifyRecords ?? true;
+  const attempts = await Promise.all([
+    resolveExplicit(subject, options.explicitMultiaddrs),
+    resolveBlockchain(subject, options.blockchain, verifyRecords),
+    resolveCentralized(subject, options, verifyRecords),
+    resolveFallback(subject, options.fallbackMultiaddrs)
+  ]);
+  const winner = attempts.find((attempt) => attempt.candidate)?.candidate;
+  if (!winner) {
+    throw new CloudLocationResolutionError(subject, attempts);
+  }
+  return {
+    subject,
+    source: winner.source,
+    multiaddrs: [...winner.multiaddrs],
+    ...winner.record ? { record: winner.record } : {},
+    attempts,
+    resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function resolveTinyCloudHosts(subject, options = {}) {
+  const location = await resolveCloudLocation(subject, {
+    explicitMultiaddrs: hostsToMultiaddrs(options.explicitHosts),
+    blockchain: options.blockchain,
+    centralizedRegistryUrl: options.registryUrl === null ? void 0 : options.registryUrl ?? DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
+    fallbackMultiaddrs: hostsToMultiaddrs(
+      options.fallbackHosts === null ? void 0 : options.fallbackHosts ?? [DEFAULT_TINYCLOUD_FALLBACK_HOST]
+    ),
+    fetch: options.fetch,
+    verifyRecords: options.verifyRecords
+  });
+  return {
+    hosts: location.multiaddrs.map((addr) => multiaddrToHttpUrl(addr)),
+    location
+  };
+}
+function multiaddrToHttpUrl(input) {
+  const uri = (0, import_multiaddr_to_uri.multiaddrToUri)((0, import_multiaddr.multiaddr)(input));
+  if (!uri.startsWith("http://") && !uri.startsWith("https://")) {
+    throw new LocationRecordValidationError(
+      `multiaddr does not resolve to http/https: ${input}`
+    );
+  }
+  return uri;
+}
+function httpUrlToMultiaddr(input) {
+  const url = new URL(input);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new LocationRecordValidationError("URL must use http or https");
+  }
+  return (0, import_uri_to_multiaddr.uriToMultiaddr)(url.toString()).toString();
+}
+function hostsToMultiaddrs(hosts) {
+  if (hosts === void 0 || hosts.length === 0) {
+    return void 0;
+  }
+  return hosts.map(
+    (host) => host.startsWith("/") ? host : httpUrlToMultiaddr(host)
+  );
+}
+async function resolveExplicit(subject, multiaddrs) {
+  return resolveAttempt("explicit", async () => {
+    if (multiaddrs === void 0 || multiaddrs.length === 0) {
+      return null;
+    }
+    return toCandidate(subject, "explicit", multiaddrs, false);
+  });
+}
+async function resolveBlockchain(subject, resolver, verifyRecords) {
+  return resolveAttempt("blockchain", async () => {
+    if (!resolver) {
+      return null;
+    }
+    return toCandidate(
+      subject,
+      "blockchain",
+      await resolver(subject),
+      verifyRecords
+    );
+  });
+}
+async function resolveCentralized(subject, options, verifyRecords) {
+  return resolveAttempt("centralized", async () => {
+    if (!options.centralizedRegistryUrl) {
+      return null;
+    }
+    const record = await fetchLocationRecord(
+      options.centralizedRegistryUrl,
+      subject,
+      options.fetch
+    );
+    return toCandidate(subject, "centralized", record, verifyRecords);
+  });
+}
+async function resolveFallback(subject, multiaddrs) {
+  return resolveAttempt("fallback", async () => {
+    if (multiaddrs === void 0 || multiaddrs.length === 0) {
+      return null;
+    }
+    return toCandidate(subject, "fallback", multiaddrs, false);
+  });
+}
+async function resolveAttempt(source, resolve) {
+  try {
+    const candidate = await resolve();
+    return candidate ? { source, candidate } : { source };
+  } catch (error) {
+    return {
+      source,
+      error: error instanceof Error ? error : new Error(String(error))
+    };
+  }
+}
+async function toCandidate(subject, source, input, verifyRecord) {
+  if (input === null || input === void 0) {
+    return null;
+  }
+  if (Array.isArray(input)) {
+    validateMultiaddrs(input);
+    return { source, multiaddrs: [...input] };
+  }
+  const maybeRecord = input;
+  if (maybeRecord.version === 1 && maybeRecord.signature !== void 0) {
+    const record = validateLocationRecord(input);
+    if (record.subject !== subject) {
+      throw new LocationRecordValidationError(
+        "location record subject does not match requested subject"
+      );
+    }
+    if (verifyRecord && !await verifyLocationRecord(record)) {
+      throw new LocationRecordValidationError(
+        "location record signature is invalid"
+      );
+    }
+    return { source, multiaddrs: [...record.multiaddrs], record };
+  }
+  const candidateInput = input;
+  if (!Array.isArray(candidateInput.multiaddrs)) {
+    throw new LocationRecordValidationError(
+      "candidate multiaddrs must be an array"
+    );
+  }
+  validateMultiaddrs(candidateInput.multiaddrs);
+  if (candidateInput.record !== void 0) {
+    const record = validateLocationRecord(candidateInput.record);
+    if (record.subject !== subject) {
+      throw new LocationRecordValidationError(
+        "location record subject does not match requested subject"
+      );
+    }
+    if (verifyRecord && !await verifyLocationRecord(record)) {
+      throw new LocationRecordValidationError(
+        "location record signature is invalid"
+      );
+    }
+    return { source, multiaddrs: [...candidateInput.multiaddrs], record };
+  }
+  return { source, multiaddrs: [...candidateInput.multiaddrs] };
+}
+function validateSubject(subject) {
+  if (typeof subject !== "string" || subject.length === 0) {
+    throw new LocationRecordValidationError(
+      "subject must be a non-empty string"
+    );
+  }
+  if (!subject.startsWith("did:pkh:") && !subject.startsWith("did:key:")) {
+    throw new LocationRecordValidationError(
+      "subject must be did:pkh or did:key"
+    );
+  }
+}
+function validateMultiaddrs(input) {
+  if (!Array.isArray(input)) {
+    throw new LocationRecordValidationError("multiaddrs must be an array");
+  }
+  for (const addr of input) {
+    if (typeof addr !== "string" || addr.length === 0) {
+      throw new LocationRecordValidationError(
+        "multiaddr entries must be non-empty strings"
+      );
+    }
+    try {
+      (0, import_multiaddr.multiaddr)(addr);
+    } catch {
+      throw new LocationRecordValidationError(`invalid multiaddr: ${addr}`);
+    }
+  }
+}
+async function verifyPkhSignature(did, payload, signature) {
+  const address = did.split(":").at(-1);
+  if (!address || !/^0x[a-fA-F0-9]{40}$/.test(address)) {
+    throw new LocationRecordValidationError(
+      "did:pkh subject must end with an EVM address"
+    );
+  }
+  if (!/^0x[0-9a-fA-F]+$/.test(signature)) {
+    throw new LocationRecordValidationError("did:pkh signature must be hex");
+  }
+  return (0, import_viem.verifyMessage)({
+    address,
+    message: payload,
+    signature
+  });
+}
+function verifyDidKeySignature(did, payload, signature) {
+  const publicKey = ed25519PublicKeyFromDidKey(did);
+  const signatureBytes = decodeBase64Url(signature);
+  if (signatureBytes.length !== 64) {
+    throw new LocationRecordValidationError(
+      "did:key signature must be a base64url Ed25519 signature"
+    );
+  }
+  return import_ed25519.ed25519.verify(
+    signatureBytes,
+    new TextEncoder().encode(payload),
+    publicKey
+  );
+}
+function ed25519PublicKeyFromDidKey(did) {
+  const identifier = did.slice("did:key:".length);
+  if (!identifier.startsWith("z")) {
+    throw new LocationRecordValidationError(
+      "did:key must use base58btc multibase"
+    );
+  }
+  const bytes = import_basics.bases.base58btc.decode(identifier);
+  if (bytes.length !== 34 || bytes[0] !== 237 || bytes[1] !== 1) {
+    throw new LocationRecordValidationError(
+      "did:key must be an Ed25519 public key"
+    );
+  }
+  return bytes.slice(2);
+}
+function base64UrlEncode2(bytes) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  let output = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const a = bytes[i];
+    const b = bytes[i + 1];
+    const c = bytes[i + 2];
+    const triplet = a << 16 | (b ?? 0) << 8 | (c ?? 0);
+    output += alphabet[triplet >> 18 & 63];
+    output += alphabet[triplet >> 12 & 63];
+    if (i + 1 < bytes.length) {
+      output += alphabet[triplet >> 6 & 63];
+    }
+    if (i + 2 < bytes.length) {
+      output += alphabet[triplet & 63];
+    }
+  }
+  return output;
+}
+function decodeBase64Url(value) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+  const bytes = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const char of value) {
+    const index = alphabet.indexOf(char);
+    if (index < 0) {
+      throw new LocationRecordValidationError(
+        "did:key signature must be base64url"
+      );
+    }
+    buffer = buffer << 6 | index;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push(buffer >> bits & 255);
+    }
+  }
+  return Uint8Array.from(bytes);
+}
+
 // src/capabilities.ts
 var PermissionNotInManifestError = class extends Error {
   constructor(missing, granted) {
@@ -4451,10 +4854,13 @@ function parseRecapCapabilities(parseWasm, siwe) {
   CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema,
+  CloudLocationResolutionError,
   DEFAULT_DEFAULTS,
   DEFAULT_EXPIRY,
   DEFAULT_MANIFEST_SPACE,
   DEFAULT_MANIFEST_VERSION,
+  DEFAULT_TINYCLOUD_FALLBACK_HOST,
+  DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
   DataVaultService,
   DatabaseHandle,
   DelegationErrorCodes,
@@ -4466,6 +4872,7 @@ function parseRecapCapabilities(parseWasm, siwe) {
   ErrorCodes,
   HooksService,
   KVService,
+  LocationRecordValidationError,
   ManifestValidationError,
   PermissionNotInManifestError,
   PrefixedKVService,
@@ -4491,6 +4898,7 @@ function parseRecapCapabilities(parseWasm, siwe) {
   activateSessionWithHost,
   applyPrefix,
   buildSpaceUri,
+  canonicalLocationPayload,
   checkNodeInfo,
   composeManifestRequest,
   createCapabilityKeyRegistry,
@@ -4502,23 +4910,33 @@ function parseRecapCapabilities(parseWasm, siwe) {
   defaultSpaceCreationHandler,
   err,
   expandActionShortNames,
+  fetchLocationRecord,
   fetchPeerId,
+  httpUrlToMultiaddr,
   isCapabilitySubset,
   loadManifest,
+  locationPayloadForRecord,
   makePublicSpaceId,
   manifestAbilitiesUnion,
+  multiaddrToHttpUrl,
   normalizeDefaults,
   ok,
   parseExpiry,
   parseRecapCapabilities,
   parseSpaceUri,
+  resolveCloudLocation,
   resolveManifest,
+  resolveTinyCloudHosts,
   resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError,
+  signLocationRecord,
   submitHostDelegation,
   validateClientSession,
+  validateLocationRecord,
+  validateLocationRecordPayload,
   validateManifest,
-  validatePersistedSessionData
+  validatePersistedSessionData,
+  verifyLocationRecord
 });
 //# sourceMappingURL=index.cjs.map