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

package/dist/index.js

@@ -154,6 +154,7 @@ var Space = class {
     this._id = config.id;
     this._name = config.name;
     this._kv = config.createKV(config.id);
+    this._vault = config.createVault(config.id);
     this._delegations = config.createDelegations(config.id);
     this._sharing = config.createSharing(config.id);
     this._getInfo = config.getInfo;
@@ -176,6 +177,12 @@ var Space = class {
   get kv() {
     return this._kv;
   }
+  /**
+   * Data Vault operations scoped to this space.
+   */
+  get vault() {
+    return this._vault;
+  }
   /**
    * Delegation operations scoped to this space.
    */
@@ -559,6 +566,8 @@ var SpaceConfigSchema = z4.object({
   name: z4.string(),
   /** Factory function to create a space-scoped KV service */
   createKV: z4.function(),
+  /** Factory function to create a space-scoped Data Vault service */
+  createVault: z4.function(),
   /** Factory function to create space-scoped delegations */
   createDelegations: z4.function(),
   /** Factory function to create space-scoped sharing */
@@ -579,6 +588,8 @@ var SpaceServiceConfigSchema = z4.object({
   capabilityRegistry: z4.unknown().optional(),
   /** Factory function to create a space-scoped KV service */
   createKVService: z4.function().optional(),
+  /** Factory function to create a space-scoped Data Vault service */
+  createVaultService: z4.function().optional(),
   /** User's PKH DID (derived from address or provided explicitly) */
   userDid: z4.string().optional(),
   /** Optional SharingService for v2 sharing links (client-side) */
@@ -717,6 +728,20 @@ function validateServerSpaceInfoResponse(data) {
   return { ok: true, data: result.data };
 }
 
+// src/expiry.ts
+var EPHEMERAL_MS = 60 * 60 * 1e3;
+var SESSION_MS = 7 * 24 * 60 * 60 * 1e3;
+var SHARE_MS = 7 * 24 * 60 * 60 * 1e3;
+var APP_MS = 30 * 24 * 60 * 60 * 1e3;
+var MAX_MS = 10 * 365 * 24 * 60 * 60 * 1e3;
+var EXPIRY = {
+  EPHEMERAL_MS,
+  SESSION_MS,
+  SHARE_MS,
+  APP_MS,
+  MAX_MS
+};
+
 // src/spaces/SpaceService.ts
 var SERVICE_NAME = "space";
 var SpaceErrorCodes = {
@@ -793,7 +818,7 @@ function transformServerDelegations(validatedData, defaultSpaceId) {
       spaceId,
       path,
       actions,
-      expiry: info.expiry ? new Date(info.expiry) : new Date(Date.now() + 24 * 60 * 60 * 1e3),
+      expiry: info.expiry ? new Date(info.expiry) : new Date(Date.now() + EXPIRY.SHARE_MS),
       isRevoked: false,
       createdAt: info.issued_at ? new Date(info.issued_at) : void 0,
       parentCid: firstStringParent
@@ -820,6 +845,7 @@ var SpaceService = class {
     this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.capabilityRegistry = config.capabilityRegistry;
     this.createKVServiceFn = config.createKVService;
+    this.createVaultServiceFn = config.createVaultService;
     this._userDid = config.userDid;
     this.sharingService = config.sharingService;
     this.createDelegationFn = config.createDelegation;
@@ -834,6 +860,7 @@ var SpaceService = class {
     if (config.fetch) this.fetchFn = config.fetch;
     if (config.capabilityRegistry) this.capabilityRegistry = config.capabilityRegistry;
     if (config.createKVService) this.createKVServiceFn = config.createKVService;
+    if (config.createVaultService) this.createVaultServiceFn = config.createVaultService;
     if (config.userDid !== void 0) this._userDid = config.userDid;
     if (config.sharingService) this.sharingService = config.sharingService;
     if (config.createDelegation) this.createDelegationFn = config.createDelegation;
@@ -1116,6 +1143,7 @@ var SpaceService = class {
       id: spaceId,
       name,
       createKV: this.createSpaceScopedKV.bind(this),
+      createVault: this.createSpaceScopedVault.bind(this),
       createDelegations: this.createSpaceScopedDelegations.bind(this),
       createSharing: this.createSpaceScopedSharing.bind(this),
       getInfo: this.getSpaceInfo.bind(this)
@@ -1245,6 +1273,21 @@ var SpaceService = class {
       }
     });
   }
+  /**
+   * Create a space-scoped Data Vault service.
+   */
+  createSpaceScopedVault(spaceId) {
+    if (this.createVaultServiceFn) {
+      return this.createVaultServiceFn(spaceId);
+    }
+    return new Proxy({}, {
+      get: () => {
+        throw new Error(
+          "Vault service factory not configured. Provide createVaultService in SpaceServiceConfig."
+        );
+      }
+    });
+  }
   /**
    * Create space-scoped delegation operations.
    */
@@ -1989,7 +2032,11 @@ import {
   DataVaultService,
   VaultHeaders,
   VaultPublicSpaceKVActions,
-  createVaultCrypto
+  createVaultCrypto,
+  SecretsService,
+  SECRET_NAME_RE as SECRET_NAME_RE2,
+  canonicalizeSecretScope,
+  resolveSecretPath as resolveSecretPath2
 } from "@tinycloud/sdk-services";
 
 // src/space.ts
@@ -2179,7 +2226,7 @@ var DelegationManager = class {
         spaceId: this.session.spaceId,
         path: params.path,
         actions: params.actions,
-        expiry: params.expiry ?? new Date(Date.now() + 24 * 60 * 60 * 1e3),
+        expiry: params.expiry ?? new Date(Date.now() + EXPIRY.SHARE_MS),
         isRevoked: false,
         allowSubDelegation: !(params.disableSubDelegation ?? false),
         createdAt: /* @__PURE__ */ new Date()
@@ -2658,6 +2705,7 @@ function validateEncodedShareData(data) {
 
 // src/manifest.ts
 import ms from "ms";
+import { resolveSecretPath, SECRET_NAME_RE } from "@tinycloud/sdk-services";
 var ManifestValidationError = class extends Error {
   constructor(message) {
     super(`Manifest validation failed: ${message}`);
@@ -2670,6 +2718,8 @@ var DEFAULT_MANIFEST_VERSION = 1;
 var DEFAULT_MANIFEST_SPACE = "applications";
 var ACCOUNT_REGISTRY_SPACE = "account";
 var ACCOUNT_REGISTRY_PATH = "applications/";
+var SECRETS_SPACE = "secrets";
+var VAULT_PERMISSION_SERVICE = "tinycloud.vault";
 var SERVICE_SHORT_TO_LONG = Object.freeze({
   kv: "tinycloud.kv",
   sql: "tinycloud.sql",
@@ -2694,12 +2744,6 @@ var DEFAULT_STANDARD_ENTRIES = [
     space: DEFAULT_MANIFEST_SPACE,
     path: "/",
     actions: ["read", "write"]
-  },
-  {
-    service: "tinycloud.capabilities",
-    space: DEFAULT_MANIFEST_SPACE,
-    path: "/",
-    actions: ["read"]
   }
 ];
 var DEFAULT_ADMIN_ENTRIES = [
@@ -2714,12 +2758,6 @@ var DEFAULT_ADMIN_ENTRIES = [
     space: DEFAULT_MANIFEST_SPACE,
     path: "/",
     actions: ["read", "write", "ddl"]
-  },
-  {
-    service: "tinycloud.capabilities",
-    space: DEFAULT_MANIFEST_SPACE,
-    path: "/",
-    actions: ["read", "admin"]
   }
 ];
 var DEFAULT_ALL_ENTRIES = [
@@ -2740,12 +2778,6 @@ var DEFAULT_ALL_ENTRIES = [
     space: DEFAULT_MANIFEST_SPACE,
     path: "/",
     actions: ["read", "write"]
-  },
-  {
-    service: "tinycloud.capabilities",
-    space: DEFAULT_MANIFEST_SPACE,
-    path: "/",
-    actions: ["read", "admin"]
   }
 ];
 function parseExpiry(duration) {
@@ -2770,6 +2802,20 @@ function expandActionShortNames(service, actions) {
     return `${service}/${a}`;
   });
 }
+function expandPermissionEntry(entry) {
+  if (entry.service !== VAULT_PERMISSION_SERVICE) {
+    return [
+      {
+        ...entry,
+        actions: expandActionShortNames(entry.service, entry.actions)
+      }
+    ];
+  }
+  return expandVaultPermissionEntry(entry);
+}
+function expandPermissionEntries(entries) {
+  return entries.flatMap(expandPermissionEntry);
+}
 function applyPrefix(prefix, path, skipPrefix) {
   if (skipPrefix) {
     return path;
@@ -2841,8 +2887,49 @@ function validateManifest(input) {
       (p, i) => validatePermissionEntry(p, `permissions[${i}]`)
     );
   }
+  if (m.secrets !== void 0) {
+    validateManifestSecrets(m.secrets);
+  }
   return m;
 }
+function validateManifestSecrets(secrets) {
+  if (secrets === null || typeof secrets !== "object" || Array.isArray(secrets)) {
+    throw new ManifestValidationError("manifest.secrets must be an object");
+  }
+  for (const [name, spec] of Object.entries(secrets)) {
+    if (!SECRET_NAME_RE.test(name)) {
+      throw new ManifestValidationError(
+        `manifest.secrets.${name} must match ${SECRET_NAME_RE.source}`
+      );
+    }
+    try {
+      resolveSecretPath(
+        secretNameFromSpec(name, spec),
+        { scope: secretScopeFromSpec(spec) }
+      );
+    } catch (error) {
+      throw new ManifestValidationError(
+        `manifest.secrets.${name}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    const actions = secretActionsFromSpec(name, spec);
+    if (actions.length === 0) {
+      throw new ManifestValidationError(
+        `manifest.secrets.${name} actions must be non-empty`
+      );
+    }
+    for (const action of actions) {
+      if (typeof action !== "string" || action.length === 0) {
+        throw new ManifestValidationError(
+          `manifest.secrets.${name} actions must be non-empty strings`
+        );
+      }
+    }
+    if (spec !== null && typeof spec === "object" && !Array.isArray(spec) && spec.expiry !== void 0) {
+      parseExpiry(spec.expiry);
+    }
+  }
+}
 function validatePermissionEntry(p, path) {
   if (p === null || typeof p !== "object") {
     throw new ManifestValidationError(`${path} must be an object`);
@@ -2866,6 +2953,16 @@ function validatePermissionEntry(p, path) {
       `${path}.actions must be a non-empty array`
     );
   }
+  for (const action of entry.actions) {
+    if (typeof action !== "string" || action.length === 0) {
+      throw new ManifestValidationError(
+        `${path}.actions must contain non-empty strings`
+      );
+    }
+    if (entry.service === VAULT_PERMISSION_SERVICE) {
+      vaultActionExpansion(action);
+    }
+  }
   if (entry.expiry !== void 0) {
     parseExpiry(entry.expiry);
   }
@@ -2895,7 +2992,8 @@ function defaultEntriesForTier(tier) {
     service: e.service,
     space: e.space,
     path: e.path,
-    actions: [...e.actions]
+    actions: [...e.actions],
+    ...e.skipPrefix !== void 0 ? { skipPrefix: e.skipPrefix } : {}
   }));
 }
 function resolveManifest(input) {
@@ -2907,9 +3005,14 @@ function resolveManifest(input) {
   const tier = normalizeDefaults(manifest.defaults);
   const defaultEntries = defaultEntriesForTier(tier);
   const explicitEntries = manifest.permissions ?? [];
-  const allEntries = [...defaultEntries, ...explicitEntries];
-  const resources = allEntries.map(
-    (entry) => resolveEntry(entry, prefix, expiryMs, space)
+  const secretEntries = secretEntriesForManifest(manifest.secrets);
+  const allEntries = [
+    ...defaultEntries,
+    ...explicitEntries,
+    ...secretEntries
+  ];
+  const resources = withCapabilitiesReadForSpaces(
+    allEntries.flatMap((entry) => resolveEntry(entry, prefix, expiryMs, space))
   );
   const additionalDelegates = manifest.did === void 0 ? [] : [
     {
@@ -2929,25 +3032,191 @@ function resolveManifest(input) {
     additionalDelegates
   };
 }
+function normalizeSecretActions(actions) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (action) => {
+    if (!seen.has(action)) {
+      out.push(action);
+      seen.add(action);
+    }
+  };
+  for (const action of actions) {
+    if (action === "read") {
+      add("get");
+      continue;
+    }
+    if (action === "write") {
+      add("put");
+      continue;
+    }
+    if (action === "delete") {
+      add("del");
+      continue;
+    }
+    if (action === "get" || action === "put" || action === "del" || action === "list" || action === "metadata") {
+      add(action);
+      continue;
+    }
+    if (action === "tinycloud.kv/get" || action === "tinycloud.kv/put" || action === "tinycloud.kv/del" || action === "tinycloud.kv/list" || action === "tinycloud.kv/metadata") {
+      add(action);
+      continue;
+    }
+    throw new ManifestValidationError(
+      `unknown secret action ${JSON.stringify(action)}; expected read, write, delete, list, or metadata`
+    );
+  }
+  return out;
+}
+function secretNameFromSpec(fallbackName, spec) {
+  if (spec !== null && typeof spec === "object" && !Array.isArray(spec)) {
+    return spec.name ?? fallbackName;
+  }
+  return fallbackName;
+}
+function secretScopeFromSpec(spec) {
+  if (spec !== null && typeof spec === "object" && !Array.isArray(spec)) {
+    return spec.scope;
+  }
+  return void 0;
+}
+function secretActionsFromSpec(name, spec) {
+  if (spec === true) {
+    return ["read"];
+  }
+  if (typeof spec === "string") {
+    return [spec];
+  }
+  if (Array.isArray(spec)) {
+    return spec;
+  }
+  if (spec === null || typeof spec !== "object") {
+    throw new ManifestValidationError(
+      `manifest.secrets.${name} must be true, a string action, an actions array, or an object`
+    );
+  }
+  if (spec.actions === void 0) {
+    return ["read"];
+  }
+  if (typeof spec.actions === "string") {
+    return [spec.actions];
+  }
+  if (Array.isArray(spec.actions)) {
+    return spec.actions;
+  }
+  throw new ManifestValidationError(
+    `manifest.secrets.${name}.actions must be a string or array`
+  );
+}
+function secretEntriesForManifest(secrets) {
+  if (secrets === void 0) {
+    return [];
+  }
+  const entries = [];
+  for (const [name, spec] of Object.entries(secrets)) {
+    const actions = secretActionsFromSpec(name, spec);
+    const secretPath = resolveSecretPath(
+      secretNameFromSpec(name, spec),
+      { scope: secretScopeFromSpec(spec) }
+    );
+    const extra = spec !== true && typeof spec === "object" && !Array.isArray(spec) ? spec : {};
+    entries.push({
+      service: VAULT_PERMISSION_SERVICE,
+      space: SECRETS_SPACE,
+      path: secretPath.vaultKey,
+      actions: normalizeSecretActions(actions),
+      skipPrefix: true,
+      ...extra.expiry !== void 0 ? { expiry: extra.expiry } : {},
+      ...extra.description !== void 0 ? { description: extra.description } : {}
+    });
+  }
+  return entries;
+}
 function resolveEntry(entry, prefix, _inheritedExpiryMs, inheritedSpace) {
   const resolvedPath = applyPrefix(
     prefix,
     entry.path,
     entry.skipPrefix === true
   );
-  const resolvedActions = expandActionShortNames(entry.service, entry.actions);
   const entryExpiryMs = entry.expiry !== void 0 ? parseExpiry(entry.expiry) : void 0;
-  return {
-    service: entry.service,
+  return expandPermissionEntry({
+    ...entry,
     space: entry.space ?? inheritedSpace,
     path: resolvedPath,
-    actions: resolvedActions,
+    skipPrefix: true
+  }).map((expanded) => ({
+    service: expanded.service,
+    space: expanded.space ?? inheritedSpace,
+    path: expanded.path,
+    actions: expanded.actions,
     // 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 } : {},
     ...entry.description !== void 0 ? { description: entry.description } : {}
-  };
+  }));
+}
+function expandVaultPermissionEntry(entry) {
+  const byBase = /* @__PURE__ */ new Map();
+  for (const action of entry.actions) {
+    const expansion = vaultActionExpansion(action);
+    for (const base of expansion.bases) {
+      const actions = byBase.get(base) ?? [];
+      if (!actions.includes(expansion.action)) {
+        actions.push(expansion.action);
+      }
+      byBase.set(base, actions);
+    }
+  }
+  return [...byBase.entries()].map(([base, actions]) => ({
+    ...entry,
+    service: "tinycloud.kv",
+    path: vaultKVPath(base, entry.path),
+    actions,
+    skipPrefix: true
+  }));
+}
+function vaultActionExpansion(action) {
+  const normalized = normalizeVaultAction(action);
+  if (normalized === "read" || normalized === "get") {
+    return { bases: ["keys", "vault"], action: "tinycloud.kv/get" };
+  }
+  if (normalized === "write" || normalized === "put") {
+    return { bases: ["keys", "vault"], action: "tinycloud.kv/put" };
+  }
+  if (normalized === "delete" || normalized === "del") {
+    return { bases: ["keys", "vault"], action: "tinycloud.kv/del" };
+  }
+  if (normalized === "list") {
+    return { bases: ["vault"], action: "tinycloud.kv/list" };
+  }
+  if (normalized === "head") {
+    return { bases: ["vault"], action: "tinycloud.kv/get" };
+  }
+  if (normalized === "metadata") {
+    return { bases: ["vault"], action: "tinycloud.kv/metadata" };
+  }
+  throw new ManifestValidationError(
+    `unknown vault action ${JSON.stringify(action)}; expected read, write, delete, get, put, del, list, head, or metadata`
+  );
+}
+function normalizeVaultAction(action) {
+  if (action.startsWith(`${VAULT_PERMISSION_SERVICE}/`)) {
+    return action.slice(`${VAULT_PERMISSION_SERVICE}/`.length);
+  }
+  if (action.startsWith("tinycloud.kv/")) {
+    return action.slice("tinycloud.kv/".length);
+  }
+  if (action.includes("/")) {
+    throw new ManifestValidationError(
+      `unknown vault action ${JSON.stringify(action)}; expected a tinycloud.vault or tinycloud.kv action`
+    );
+  }
+  return action;
+}
+function vaultKVPath(base, path) {
+  const normalized = path.startsWith("/") ? path.slice(1) : path;
+  return `${base}/${normalized}`;
 }
 function cloneResourceCapability(entry) {
   return {
@@ -2992,6 +3261,24 @@ function dedupeResources(resources) {
   }
   return [...byKey.values()];
 }
+function capabilitiesReadPermission(space) {
+  return {
+    service: "tinycloud.capabilities",
+    space,
+    path: "",
+    actions: ["tinycloud.capabilities/read"]
+  };
+}
+function withCapabilitiesReadForSpaces(resources) {
+  if (resources.length === 0) {
+    return [];
+  }
+  const spaces = new Set(resources.map((resource) => resource.space));
+  return dedupeResources([
+    ...resources,
+    ...[...spaces].map(capabilitiesReadPermission)
+  ]);
+}
 function accountRegistryPermission() {
   return {
     service: "tinycloud.kv",
@@ -3019,6 +3306,7 @@ function composeManifestRequest(inputs, options = {}) {
   if (includeAccountRegistryPermissions) {
     resources.push(accountRegistryPermission());
   }
+  const resourcesWithImplicitCapabilities = withCapabilitiesReadForSpaces(resources);
   const manifestsByAppId = /* @__PURE__ */ new Map();
   for (const manifest of manifests) {
     const current = manifestsByAppId.get(manifest.app_id);
@@ -3038,7 +3326,7 @@ function composeManifestRequest(inputs, options = {}) {
   })) : [];
   return {
     manifests,
-    resources: dedupeResources(resources),
+    resources: resourcesWithImplicitCapabilities,
     delegationTargets,
     registryRecords,
     expiryMs: Math.max(...resolved.map((entry) => entry.expiryMs)),
@@ -3117,7 +3405,7 @@ function inferShortServiceFromActionUrns(actions) {
   return short;
 }
 var DEFAULT_READ_ACTIONS = ["tinycloud.kv/get", "tinycloud.kv/metadata"];
-var DEFAULT_EXPIRY_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_EXPIRY_MS = EXPIRY.SHARE_MS;
 var BASE64_PREFIX = "tc1:";
 function createError2(code, message, cause, meta) {
   return {
@@ -4250,6 +4538,394 @@ 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 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 = 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();
+}
+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 {
+      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) {
@@ -4370,10 +5046,13 @@ export {
   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,
@@ -4381,18 +5060,22 @@ export {
   DuckDbAction,
   DuckDbDatabaseHandle,
   DuckDbService2 as DuckDbService,
+  EXPIRY,
   EnsDataSchema,
   ErrorCodes2 as ErrorCodes,
   HooksService2 as HooksService,
   KVService2 as KVService,
+  LocationRecordValidationError,
   ManifestValidationError,
   PermissionNotInManifestError,
   PrefixedKVService,
   ProtocolMismatchError,
+  SECRET_NAME_RE2 as SECRET_NAME_RE,
   SERVICE_LONG_TO_SHORT,
   SERVICE_SHORT_TO_LONG,
   SQLAction,
   SQLService2 as SQLService,
+  SecretsService,
   ServiceContext2 as ServiceContext,
   SessionExpiredError,
   SharingService,
@@ -4404,12 +5087,15 @@ export {
   SpaceService,
   TinyCloud,
   UnsupportedFeatureError,
+  VAULT_PERMISSION_SERVICE,
   VaultHeaders,
   VaultPublicSpaceKVActions,
   VersionCheckError,
   activateSessionWithHost,
   applyPrefix,
   buildSpaceUri,
+  canonicalLocationPayload,
+  canonicalizeSecretScope,
   checkNodeInfo,
   composeManifestRequest,
   createCapabilityKeyRegistry,
@@ -4421,23 +5107,36 @@ export {
   defaultSpaceCreationHandler,
   err4 as err,
   expandActionShortNames,
+  expandPermissionEntries,
+  expandPermissionEntry,
+  fetchLocationRecord,
   fetchPeerId,
+  httpUrlToMultiaddr,
   isCapabilitySubset,
   loadManifest,
+  locationPayloadForRecord,
   makePublicSpaceId,
   manifestAbilitiesUnion,
+  multiaddrToHttpUrl,
   normalizeDefaults,
   ok4 as ok,
   parseExpiry,
   parseRecapCapabilities,
   parseSpaceUri,
+  resolveCloudLocation,
   resolveManifest,
+  resolveSecretPath2 as resolveSecretPath,
+  resolveTinyCloudHosts,
   resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError4 as serviceError,
+  signLocationRecord,
   submitHostDelegation,
   validateClientSession,
+  validateLocationRecord,
+  validateLocationRecordPayload,
   validateManifest,
-  validatePersistedSessionData
+  validatePersistedSessionData,
+  verifyLocationRecord
 };
 //# sourceMappingURL=index.js.map