@tinycloud/sdk-core 2.2.0-beta.0 → 2.2.0-beta.3

package/dist/index.cjs

@@ -36,6 +36,7 @@ __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,
@@ -51,6 +52,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 +78,7 @@ __export(index_exports, {
   activateSessionWithHost: () => activateSessionWithHost,
   applyPrefix: () => applyPrefix,
   buildSpaceUri: () => buildSpaceUri,
+  canonicalLocationPayload: () => canonicalLocationPayload,
   checkNodeInfo: () => checkNodeInfo,
   composeManifestRequest: () => composeManifestRequest,
   createCapabilityKeyRegistry: () => createCapabilityKeyRegistry,
@@ -87,24 +90,33 @@ __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,
   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);
 
@@ -2834,9 +2846,7 @@ function parseExpiry(duration) {
       `expiry must be a non-empty duration string (got ${JSON.stringify(duration)})`
     );
   }
-  const parsed = (0, import_ms.default)(
-    duration
-  );
+  const parsed = (0, import_ms.default)(duration);
   if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed <= 0) {
     throw new ManifestValidationError(
       `invalid expiry duration: ${JSON.stringify(duration)}`
@@ -2891,23 +2901,33 @@ function validateManifest(input) {
     );
   }
   if (typeof m.app_id !== "string" || m.app_id.length === 0) {
-    throw new ManifestValidationError("manifest.app_id is required and must be a non-empty string");
+    throw new ManifestValidationError(
+      "manifest.app_id is required and must be a non-empty string"
+    );
   }
   if (typeof m.name !== "string" || m.name.length === 0) {
-    throw new ManifestValidationError("manifest.name is required and must be a non-empty string");
+    throw new ManifestValidationError(
+      "manifest.name is required and must be a non-empty string"
+    );
   }
   if (m.did !== void 0 && (typeof m.did !== "string" || m.did.length === 0)) {
-    throw new ManifestValidationError("manifest.did must be a non-empty DID string");
+    throw new ManifestValidationError(
+      "manifest.did must be a non-empty DID string"
+    );
   }
   if (m.space !== void 0 && (typeof m.space !== "string" || m.space.length === 0)) {
-    throw new ManifestValidationError("manifest.space must be a non-empty string");
+    throw new ManifestValidationError(
+      "manifest.space must be a non-empty string"
+    );
   }
   if (m.expiry !== void 0) {
     parseExpiry(m.expiry);
   }
   if (m.permissions !== void 0) {
     if (!Array.isArray(m.permissions)) {
-      throw new ManifestValidationError("manifest.permissions must be an array");
+      throw new ManifestValidationError(
+        "manifest.permissions must be an array"
+      );
     }
     m.permissions.forEach(
       (p, i) => validatePermissionEntry(p, `permissions[${i}]`)
@@ -2924,7 +2944,9 @@ function validatePermissionEntry(p, path) {
     throw new ManifestValidationError(`${path}.service is required`);
   }
   if (entry.space !== void 0 && (typeof entry.space !== "string" || entry.space.length === 0)) {
-    throw new ManifestValidationError(`${path}.space must be a non-empty string`);
+    throw new ManifestValidationError(
+      `${path}.space must be a non-empty string`
+    );
   }
   if (typeof entry.path !== "string") {
     throw new ManifestValidationError(
@@ -3015,7 +3037,8 @@ function resolveEntry(entry, prefix, _inheritedExpiryMs, inheritedSpace) {
     // Only populate `expiryMs` when the entry had its own expiry override.
     // When absent, callers use the parent (delegation or manifest) expiry
     // which is carried on ResolvedDelegate.expiryMs / ResolvedCapabilities.expiryMs.
-    ...entryExpiryMs !== void 0 ? { expiryMs: entryExpiryMs } : {}
+    ...entryExpiryMs !== void 0 ? { expiryMs: entryExpiryMs } : {},
+    ...entry.description !== void 0 ? { description: entry.description } : {}
   };
 }
 function cloneResourceCapability(entry) {
@@ -3024,7 +3047,8 @@ function cloneResourceCapability(entry) {
     space: entry.space,
     path: entry.path,
     actions: [...entry.actions],
-    ...entry.expiryMs !== void 0 ? { expiryMs: entry.expiryMs } : {}
+    ...entry.expiryMs !== void 0 ? { expiryMs: entry.expiryMs } : {},
+    ...entry.description !== void 0 ? { description: entry.description } : {}
   };
 }
 function clonePermissionEntry(entry) {
@@ -3034,7 +3058,8 @@ function clonePermissionEntry(entry) {
     path: entry.path,
     actions: [...entry.actions],
     ...entry.skipPrefix !== void 0 ? { skipPrefix: entry.skipPrefix } : {},
-    ...entry.expiry !== void 0 ? { expiry: entry.expiry } : {}
+    ...entry.expiry !== void 0 ? { expiry: entry.expiry } : {},
+    ...entry.description !== void 0 ? { description: entry.description } : {}
   };
 }
 function dedupeResources(resources) {
@@ -3053,6 +3078,9 @@ function dedupeResources(resources) {
         seen.add(action);
       }
     }
+    if (existing.description === void 0 && resource.description !== void 0) {
+      existing.description = resource.description;
+    }
   }
   return [...byKey.values()];
 }
@@ -3061,11 +3089,7 @@ function accountRegistryPermission() {
     service: "tinycloud.kv",
     space: ACCOUNT_REGISTRY_SPACE,
     path: ACCOUNT_REGISTRY_PATH,
-    actions: [
-      "tinycloud.kv/get",
-      "tinycloud.kv/put",
-      "tinycloud.kv/list"
-    ]
+    actions: ["tinycloud.kv/get", "tinycloud.kv/put", "tinycloud.kv/list"]
   };
 }
 function composeManifestRequest(inputs, options = {}) {
@@ -4318,6 +4342,339 @@ 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 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()
+  };
+}
+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();
+}
+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) {
@@ -4439,6 +4796,7 @@ function parseRecapCapabilities(parseWasm, siwe) {
   CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema,
+  CloudLocationResolutionError,
   DEFAULT_DEFAULTS,
   DEFAULT_EXPIRY,
   DEFAULT_MANIFEST_SPACE,
@@ -4454,6 +4812,7 @@ function parseRecapCapabilities(parseWasm, siwe) {
   ErrorCodes,
   HooksService,
   KVService,
+  LocationRecordValidationError,
   ManifestValidationError,
   PermissionNotInManifestError,
   PrefixedKVService,
@@ -4479,6 +4838,7 @@ function parseRecapCapabilities(parseWasm, siwe) {
   activateSessionWithHost,
   applyPrefix,
   buildSpaceUri,
+  canonicalLocationPayload,
   checkNodeInfo,
   composeManifestRequest,
   createCapabilityKeyRegistry,
@@ -4490,23 +4850,32 @@ function parseRecapCapabilities(parseWasm, siwe) {
   defaultSpaceCreationHandler,
   err,
   expandActionShortNames,
+  fetchLocationRecord,
   fetchPeerId,
+  httpUrlToMultiaddr,
   isCapabilitySubset,
   loadManifest,
+  locationPayloadForRecord,
   makePublicSpaceId,
   manifestAbilitiesUnion,
+  multiaddrToHttpUrl,
   normalizeDefaults,
   ok,
   parseExpiry,
   parseRecapCapabilities,
   parseSpaceUri,
+  resolveCloudLocation,
   resolveManifest,
   resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError,
+  signLocationRecord,
   submitHostDelegation,
   validateClientSession,
+  validateLocationRecord,
+  validateLocationRecordPayload,
   validateManifest,
-  validatePersistedSessionData
+  validatePersistedSessionData,
+  verifyLocationRecord
 });
 //# sourceMappingURL=index.cjs.map