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

package/dist/index.cjs

@@ -36,30 +36,36 @@ __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,
-  DataVaultService: () => import_sdk_services4.DataVaultService,
-  DatabaseHandle: () => import_sdk_services4.DatabaseHandle,
+  DEFAULT_TINYCLOUD_FALLBACK_HOST: () => DEFAULT_TINYCLOUD_FALLBACK_HOST,
+  DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL: () => DEFAULT_TINYCLOUD_LOCATION_REGISTRY_URL,
+  DataVaultService: () => import_sdk_services5.DataVaultService,
+  DatabaseHandle: () => import_sdk_services5.DatabaseHandle,
   DelegationErrorCodes: () => DelegationErrorCodes,
   DelegationManager: () => DelegationManager,
-  DuckDbAction: () => import_sdk_services4.DuckDbAction,
-  DuckDbDatabaseHandle: () => import_sdk_services4.DuckDbDatabaseHandle,
-  DuckDbService: () => import_sdk_services4.DuckDbService,
+  DuckDbAction: () => import_sdk_services5.DuckDbAction,
+  DuckDbDatabaseHandle: () => import_sdk_services5.DuckDbDatabaseHandle,
+  DuckDbService: () => import_sdk_services5.DuckDbService,
   EnsDataSchema: () => EnsDataSchema,
-  ErrorCodes: () => import_sdk_services4.ErrorCodes,
-  HooksService: () => import_sdk_services4.HooksService,
-  KVService: () => import_sdk_services4.KVService,
+  ErrorCodes: () => import_sdk_services5.ErrorCodes,
+  HooksService: () => import_sdk_services5.HooksService,
+  KVService: () => import_sdk_services5.KVService,
+  LocationRecordValidationError: () => LocationRecordValidationError,
   ManifestValidationError: () => ManifestValidationError,
   PermissionNotInManifestError: () => PermissionNotInManifestError,
-  PrefixedKVService: () => import_sdk_services4.PrefixedKVService,
+  PrefixedKVService: () => import_sdk_services5.PrefixedKVService,
   ProtocolMismatchError: () => ProtocolMismatchError,
+  SECRET_NAME_RE: () => import_sdk_services5.SECRET_NAME_RE,
   SERVICE_LONG_TO_SHORT: () => SERVICE_LONG_TO_SHORT,
   SERVICE_SHORT_TO_LONG: () => SERVICE_SHORT_TO_LONG,
-  SQLAction: () => import_sdk_services4.SQLAction,
-  SQLService: () => import_sdk_services4.SQLService,
-  ServiceContext: () => import_sdk_services4.ServiceContext,
+  SQLAction: () => import_sdk_services5.SQLAction,
+  SQLService: () => import_sdk_services5.SQLService,
+  SecretsService: () => import_sdk_services5.SecretsService,
+  ServiceContext: () => import_sdk_services5.ServiceContext,
   SessionExpiredError: () => SessionExpiredError,
   SharingService: () => SharingService,
   SilentNotificationHandler: () => SilentNotificationHandler,
@@ -70,41 +76,57 @@ __export(index_exports, {
   SpaceService: () => SpaceService,
   TinyCloud: () => TinyCloud,
   UnsupportedFeatureError: () => UnsupportedFeatureError,
-  VaultHeaders: () => import_sdk_services4.VaultHeaders,
-  VaultPublicSpaceKVActions: () => import_sdk_services4.VaultPublicSpaceKVActions,
+  VAULT_PERMISSION_SERVICE: () => VAULT_PERMISSION_SERVICE,
+  VaultHeaders: () => import_sdk_services5.VaultHeaders,
+  VaultPublicSpaceKVActions: () => import_sdk_services5.VaultPublicSpaceKVActions,
   VersionCheckError: () => VersionCheckError,
   activateSessionWithHost: () => activateSessionWithHost,
   applyPrefix: () => applyPrefix,
   buildSpaceUri: () => buildSpaceUri,
+  canonicalLocationPayload: () => canonicalLocationPayload,
+  canonicalizeSecretScope: () => import_sdk_services5.canonicalizeSecretScope,
   checkNodeInfo: () => checkNodeInfo,
   composeManifestRequest: () => composeManifestRequest,
   createCapabilityKeyRegistry: () => createCapabilityKeyRegistry,
   createSharingService: () => createSharingService,
   createSpaceService: () => createSpaceService,
-  createVaultCrypto: () => import_sdk_services4.createVaultCrypto,
-  defaultRetryPolicy: () => import_sdk_services4.defaultRetryPolicy,
+  createVaultCrypto: () => import_sdk_services5.createVaultCrypto,
+  defaultRetryPolicy: () => import_sdk_services5.defaultRetryPolicy,
   defaultSignStrategy: () => defaultSignStrategy,
   defaultSpaceCreationHandler: () => defaultSpaceCreationHandler,
-  err: () => import_sdk_services4.err,
+  err: () => import_sdk_services5.err,
   expandActionShortNames: () => expandActionShortNames,
+  expandPermissionEntries: () => expandPermissionEntries,
+  expandPermissionEntry: () => expandPermissionEntry,
+  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,
+  ok: () => import_sdk_services5.ok,
   parseExpiry: () => parseExpiry,
   parseRecapCapabilities: () => parseRecapCapabilities,
   parseSpaceUri: () => parseSpaceUri,
+  resolveCloudLocation: () => resolveCloudLocation,
   resolveManifest: () => resolveManifest,
+  resolveSecretPath: () => import_sdk_services5.resolveSecretPath,
+  resolveTinyCloudHosts: () => resolveTinyCloudHosts,
   resourceCapabilitiesToAbilitiesMap: () => resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap: () => resourceCapabilitiesToSpaceAbilitiesMap,
-  serviceError: () => import_sdk_services4.serviceError,
+  serviceError: () => import_sdk_services5.serviceError,
+  signLocationRecord: () => signLocationRecord,
   submitHostDelegation: () => submitHostDelegation,
   validateClientSession: () => validateClientSession,
+  validateLocationRecord: () => validateLocationRecord,
+  validateLocationRecordPayload: () => validateLocationRecordPayload,
   validateManifest: () => validateManifest,
-  validatePersistedSessionData: () => validatePersistedSessionData
+  validatePersistedSessionData: () => validatePersistedSessionData,
+  verifyLocationRecord: () => verifyLocationRecord
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -254,6 +276,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;
@@ -276,6 +299,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.
    */
@@ -659,6 +688,8 @@ var SpaceConfigSchema = import_zod4.z.object({
   name: import_zod4.z.string(),
   /** Factory function to create a space-scoped KV service */
   createKV: import_zod4.z.function(),
+  /** Factory function to create a space-scoped Data Vault service */
+  createVault: import_zod4.z.function(),
   /** Factory function to create space-scoped delegations */
   createDelegations: import_zod4.z.function(),
   /** Factory function to create space-scoped sharing */
@@ -679,6 +710,8 @@ var SpaceServiceConfigSchema = import_zod4.z.object({
   capabilityRegistry: import_zod4.z.unknown().optional(),
   /** Factory function to create a space-scoped KV service */
   createKVService: import_zod4.z.function().optional(),
+  /** Factory function to create a space-scoped Data Vault service */
+  createVaultService: import_zod4.z.function().optional(),
   /** User's PKH DID (derived from address or provided explicitly) */
   userDid: import_zod4.z.string().optional(),
   /** Optional SharingService for v2 sharing links (client-side) */
@@ -920,6 +953,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;
@@ -934,6 +968,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;
@@ -1216,6 +1251,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)
@@ -1345,6 +1381,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.
    */
@@ -2070,7 +2121,7 @@ var TinyCloud = class _TinyCloud {
 };
 
 // src/index.ts
-var import_sdk_services4 = require("@tinycloud/sdk-services");
+var import_sdk_services5 = require("@tinycloud/sdk-services");
 
 // src/space.ts
 async function fetchPeerId(host, spaceId) {
@@ -2738,6 +2789,7 @@ function validateEncodedShareData(data) {
 
 // src/manifest.ts
 var import_ms = __toESM(require("ms"), 1);
+var import_sdk_services3 = require("@tinycloud/sdk-services");
 var ManifestValidationError = class extends Error {
   constructor(message) {
     super(`Manifest validation failed: ${message}`);
@@ -2750,6 +2802,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",
@@ -2774,12 +2828,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 = [
@@ -2794,12 +2842,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 = [
@@ -2820,12 +2862,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) {
@@ -2834,9 +2870,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)}`
@@ -2852,6 +2886,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;
@@ -2891,30 +2939,81 @@ 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}]`)
     );
   }
+  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 (!import_sdk_services3.SECRET_NAME_RE.test(name)) {
+      throw new ManifestValidationError(
+        `manifest.secrets.${name} must match ${import_sdk_services3.SECRET_NAME_RE.source}`
+      );
+    }
+    try {
+      (0, import_sdk_services3.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`);
@@ -2924,7 +3023,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(
@@ -2936,6 +3037,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);
   }
@@ -2965,7 +3076,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) {
@@ -2977,9 +3089,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 ? [] : [
     {
@@ -2999,24 +3116,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 = (0, import_sdk_services3.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 } : {}
-  };
+    ...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 {
@@ -3024,7 +3308,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 +3319,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,19 +3339,36 @@ function dedupeResources(resources) {
         seen.add(action);
       }
     }
+    if (existing.description === void 0 && resource.description !== void 0) {
+      existing.description = resource.description;
+    }
   }
   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",
     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 = {}) {
@@ -3087,6 +3390,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);
@@ -3106,7 +3410,7 @@ function composeManifestRequest(inputs, options = {}) {
   })) : [];
   return {
     manifests,
-    resources: dedupeResources(resources),
+    resources: resourcesWithImplicitCapabilities,
     delegationTargets,
     registryRecords,
     expiryMs: Math.max(...resolved.map((entry) => entry.expiryMs)),
@@ -3827,7 +4131,7 @@ function createSharingService(config) {
 }
 
 // src/authorization/CapabilityKeyRegistry.ts
-var import_sdk_services3 = require("@tinycloud/sdk-services");
+var import_sdk_services4 = require("@tinycloud/sdk-services");
 var SERVICE_NAME2 = "capability-key-registry";
 var CapabilityKeyRegistryErrorCodes = {
   /** Key not found in registry */
@@ -4045,8 +4349,8 @@ var CapabilityKeyRegistry = class {
   revokeDelegation(cid) {
     const stored = this.store.byCid.get(cid);
     if (!stored) {
-      return (0, import_sdk_services3.err)(
-        (0, import_sdk_services3.serviceError)(
+      return (0, import_sdk_services4.err)(
+        (0, import_sdk_services4.serviceError)(
           CapabilityKeyRegistryErrorCodes.KEY_NOT_FOUND,
           `Delegation not found: ${cid}`,
           SERVICE_NAME2
@@ -4068,7 +4372,7 @@ var CapabilityKeyRegistry = class {
         }
       }
     }
-    return (0, import_sdk_services3.ok)(void 0);
+    return (0, import_sdk_services4.ok)(void 0);
   }
   // ===========================================================================
   // Search
@@ -4318,6 +4622,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) {
@@ -4439,10 +5131,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,
@@ -4454,14 +5149,17 @@ function parseRecapCapabilities(parseWasm, siwe) {
   ErrorCodes,
   HooksService,
   KVService,
+  LocationRecordValidationError,
   ManifestValidationError,
   PermissionNotInManifestError,
   PrefixedKVService,
   ProtocolMismatchError,
+  SECRET_NAME_RE,
   SERVICE_LONG_TO_SHORT,
   SERVICE_SHORT_TO_LONG,
   SQLAction,
   SQLService,
+  SecretsService,
   ServiceContext,
   SessionExpiredError,
   SharingService,
@@ -4473,12 +5171,15 @@ function parseRecapCapabilities(parseWasm, siwe) {
   SpaceService,
   TinyCloud,
   UnsupportedFeatureError,
+  VAULT_PERMISSION_SERVICE,
   VaultHeaders,
   VaultPublicSpaceKVActions,
   VersionCheckError,
   activateSessionWithHost,
   applyPrefix,
   buildSpaceUri,
+  canonicalLocationPayload,
+  canonicalizeSecretScope,
   checkNodeInfo,
   composeManifestRequest,
   createCapabilityKeyRegistry,
@@ -4490,23 +5191,36 @@ function parseRecapCapabilities(parseWasm, siwe) {
   defaultSpaceCreationHandler,
   err,
   expandActionShortNames,
+  expandPermissionEntries,
+  expandPermissionEntry,
+  fetchLocationRecord,
   fetchPeerId,
+  httpUrlToMultiaddr,
   isCapabilitySubset,
   loadManifest,
+  locationPayloadForRecord,
   makePublicSpaceId,
   manifestAbilitiesUnion,
+  multiaddrToHttpUrl,
   normalizeDefaults,
   ok,
   parseExpiry,
   parseRecapCapabilities,
   parseSpaceUri,
+  resolveCloudLocation,
   resolveManifest,
+  resolveSecretPath,
+  resolveTinyCloudHosts,
   resourceCapabilitiesToAbilitiesMap,
   resourceCapabilitiesToSpaceAbilitiesMap,
   serviceError,
+  signLocationRecord,
   submitHostDelegation,
   validateClientSession,
+  validateLocationRecord,
+  validateLocationRecordPayload,
   validateManifest,
-  validatePersistedSessionData
+  validatePersistedSessionData,
+  verifyLocationRecord
 });
 //# sourceMappingURL=index.cjs.map