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

package/dist/index.js

@@ -2754,9 +2754,7 @@ function parseExpiry(duration) {
       `expiry must be a non-empty duration string (got ${JSON.stringify(duration)})`
     );
   }
-  const parsed = ms(
-    duration
-  );
+  const parsed = ms(duration);
   if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed <= 0) {
     throw new ManifestValidationError(
       `invalid expiry duration: ${JSON.stringify(duration)}`
@@ -2811,23 +2809,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}]`)
@@ -2844,7 +2852,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(
@@ -2935,7 +2945,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) {
@@ -2944,7 +2955,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) {
@@ -2954,7 +2966,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) {
@@ -2973,6 +2986,9 @@ function dedupeResources(resources) {
         seen.add(action);
       }
     }
+    if (existing.description === void 0 && resource.description !== void 0) {
+      existing.description = resource.description;
+    }
   }
   return [...byKey.values()];
 }
@@ -2981,11 +2997,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 = {}) {
@@ -4238,6 +4250,339 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
   };
 }
 
+// src/location.ts
+import { multiaddr } from "@multiformats/multiaddr";
+import { multiaddrToUri } from "@multiformats/multiaddr-to-uri";
+import { uriToMultiaddr } from "@multiformats/uri-to-multiaddr";
+import { ed25519 } from "@noble/curves/ed25519";
+import { bases } from "multiformats/basics";
+import { verifyMessage } from "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 = multiaddrToUri(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 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 {
+      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 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 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 = 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) {
@@ -4358,6 +4703,7 @@ export {
   CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema,
+  CloudLocationResolutionError,
   DEFAULT_DEFAULTS,
   DEFAULT_EXPIRY,
   DEFAULT_MANIFEST_SPACE,
@@ -4373,6 +4719,7 @@ export {
   ErrorCodes2 as ErrorCodes,
   HooksService2 as HooksService,
   KVService2 as KVService,
+  LocationRecordValidationError,
   ManifestValidationError,
   PermissionNotInManifestError,
   PrefixedKVService,
@@ -4398,6 +4745,7 @@ export {
   activateSessionWithHost,
   applyPrefix,
   buildSpaceUri,
+  canonicalLocationPayload,
   checkNodeInfo,
   composeManifestRequest,
   createCapabilityKeyRegistry,
@@ -4409,23 +4757,32 @@ export {
   defaultSpaceCreationHandler,
   err4 as err,
   expandActionShortNames,
+  fetchLocationRecord,
   fetchPeerId,
+  httpUrlToMultiaddr,
   isCapabilitySubset,
   loadManifest,
+  locationPayloadForRecord,
   makePublicSpaceId,
   manifestAbilitiesUnion,
+  multiaddrToHttpUrl,
   normalizeDefaults,
   ok4 as ok,
   parseExpiry,
   parseRecapCapabilities,
   parseSpaceUri,
+  resolveCloudLocation,
   resolveManifest,
   resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError4 as serviceError,
+  signLocationRecord,
   submitHostDelegation,
   validateClientSession,
+  validateLocationRecord,
+  validateLocationRecordPayload,
   validateManifest,
-  validatePersistedSessionData
+  validatePersistedSessionData,
+  verifyLocationRecord
 };
 //# sourceMappingURL=index.js.map