@tinycloud/sdk-core 2.0.4 → 2.1.0-beta.1

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -24,6 +34,8 @@ __export(index_exports, {
   CapabilityKeyRegistry: () => CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes: () => CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema: () => ClientSessionSchema,
+  DEFAULT_DEFAULTS: () => DEFAULT_DEFAULTS,
+  DEFAULT_EXPIRY: () => DEFAULT_EXPIRY,
   DataVaultService: () => import_sdk_services4.DataVaultService,
   DatabaseHandle: () => import_sdk_services4.DatabaseHandle,
   DelegationErrorCodes: () => DelegationErrorCodes,
@@ -33,12 +45,18 @@ __export(index_exports, {
   DuckDbService: () => import_sdk_services4.DuckDbService,
   EnsDataSchema: () => EnsDataSchema,
   ErrorCodes: () => import_sdk_services4.ErrorCodes,
+  HooksService: () => import_sdk_services4.HooksService,
   KVService: () => import_sdk_services4.KVService,
+  ManifestValidationError: () => ManifestValidationError,
+  PermissionNotInManifestError: () => PermissionNotInManifestError,
   PrefixedKVService: () => import_sdk_services4.PrefixedKVService,
   ProtocolMismatchError: () => ProtocolMismatchError,
+  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,
+  SessionExpiredError: () => SessionExpiredError,
   SharingService: () => SharingService,
   SilentNotificationHandler: () => SilentNotificationHandler,
   SiweConfigSchema: () => SiweConfigSchema,
@@ -52,6 +70,7 @@ __export(index_exports, {
   VaultPublicSpaceKVActions: () => import_sdk_services4.VaultPublicSpaceKVActions,
   VersionCheckError: () => VersionCheckError,
   activateSessionWithHost: () => activateSessionWithHost,
+  applyPrefix: () => applyPrefix,
   buildSpaceUri: () => buildSpaceUri,
   checkNodeInfo: () => checkNodeInfo,
   createCapabilityKeyRegistry: () => createCapabilityKeyRegistry,
@@ -62,13 +81,21 @@ __export(index_exports, {
   defaultSignStrategy: () => defaultSignStrategy,
   defaultSpaceCreationHandler: () => defaultSpaceCreationHandler,
   err: () => import_sdk_services4.err,
+  expandActionShortNames: () => expandActionShortNames,
   fetchPeerId: () => fetchPeerId,
+  isCapabilitySubset: () => isCapabilitySubset,
+  loadManifest: () => loadManifest,
   makePublicSpaceId: () => makePublicSpaceId,
+  normalizeDefaults: () => normalizeDefaults,
   ok: () => import_sdk_services4.ok,
+  parseExpiry: () => parseExpiry,
+  parseRecapCapabilities: () => parseRecapCapabilities,
   parseSpaceUri: () => parseSpaceUri,
+  resolveManifest: () => resolveManifest,
   serviceError: () => import_sdk_services4.serviceError,
   submitHostDelegation: () => submitHostDelegation,
   validateClientSession: () => validateClientSession,
+  validateManifest: () => validateManifest,
   validatePersistedSessionData: () => validatePersistedSessionData
 });
 module.exports = __toCommonJS(index_exports);
@@ -1554,6 +1581,7 @@ var TinyCloud = class _TinyCloud {
     }
     this._serviceContext = new import_sdk_services2.ServiceContext({
       invoke: effectiveInvoke,
+      invokeAny: this.config.invokeAny,
       fetch: fetchFn ?? this.config.fetch ?? globalThis.fetch.bind(globalThis),
       hosts: effectiveHosts,
       retryPolicy: this.config.retryPolicy
@@ -1562,6 +1590,7 @@ var TinyCloud = class _TinyCloud {
       kv: import_sdk_services2.KVService,
       sql: import_sdk_services2.SQLService,
       duckdb: import_sdk_services2.DuckDbService,
+      hooks: import_sdk_services2.HooksService,
       ...this.config.services
     };
     for (const [name, ServiceClass] of Object.entries(serviceConstructors)) {
@@ -1642,6 +1671,22 @@ var TinyCloud = class _TinyCloud {
     }
     return service;
   }
+  /**
+   * Get the Hooks service.
+   * @throws Error if services are not initialized
+   */
+  get hooks() {
+    if (!this._servicesInitialized) {
+      throw new Error(
+        "Services not initialized. Call initializeServices() first, or use TinyCloudWeb/TinyCloudNode which handles this automatically."
+      );
+    }
+    const service = this._services.get("hooks");
+    if (!service) {
+      throw new Error("Hooks service is not registered.");
+    }
+    return service;
+  }
   /**
    * Get the Data Vault service.
    * @throws Error if services are not initialized or vault service is not registered
@@ -3760,12 +3805,405 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
     quotaUrl: data.quota_url
   };
 }
+
+// src/manifest.ts
+var import_ms = __toESM(require("ms"), 1);
+var ManifestValidationError = class extends Error {
+  constructor(message) {
+    super(`Manifest validation failed: ${message}`);
+    this.name = "ManifestValidationError";
+  }
+};
+var DEFAULT_EXPIRY = "30d";
+var DEFAULT_DEFAULTS = true;
+var SERVICE_SHORT_TO_LONG = Object.freeze({
+  kv: "tinycloud.kv",
+  sql: "tinycloud.sql",
+  duckdb: "tinycloud.duckdb",
+  capabilities: "tinycloud.capabilities",
+  hooks: "tinycloud.hooks"
+});
+var SERVICE_LONG_TO_SHORT = Object.freeze(
+  Object.fromEntries(
+    Object.entries(SERVICE_SHORT_TO_LONG).map(([s, l]) => [l, s])
+  )
+);
+var DEFAULT_STANDARD_ENTRIES = [
+  {
+    service: "tinycloud.kv",
+    space: "default",
+    path: "/",
+    actions: ["get", "put", "del", "list", "metadata"]
+  },
+  {
+    service: "tinycloud.sql",
+    space: "default",
+    path: "/",
+    actions: ["read", "write"]
+  },
+  {
+    service: "tinycloud.capabilities",
+    space: "default",
+    path: "/",
+    actions: ["read"]
+  }
+];
+var DEFAULT_ADMIN_ENTRIES = [
+  {
+    service: "tinycloud.kv",
+    space: "default",
+    path: "/",
+    actions: ["get", "put", "del", "list", "metadata"]
+  },
+  {
+    service: "tinycloud.sql",
+    space: "default",
+    path: "/",
+    actions: ["read", "write", "ddl"]
+  },
+  {
+    service: "tinycloud.capabilities",
+    space: "default",
+    path: "/",
+    actions: ["read", "admin"]
+  }
+];
+var DEFAULT_ALL_ENTRIES = [
+  {
+    service: "tinycloud.kv",
+    space: "default",
+    path: "/",
+    actions: ["get", "put", "del", "list", "metadata"]
+  },
+  {
+    service: "tinycloud.sql",
+    space: "default",
+    path: "/",
+    actions: ["read", "write", "ddl"]
+  },
+  {
+    service: "tinycloud.duckdb",
+    space: "default",
+    path: "/",
+    actions: ["read", "write"]
+  },
+  {
+    service: "tinycloud.capabilities",
+    space: "default",
+    path: "/",
+    actions: ["read", "admin"]
+  }
+];
+function parseExpiry(duration) {
+  if (typeof duration !== "string" || duration.length === 0) {
+    throw new ManifestValidationError(
+      `expiry must be a non-empty duration string (got ${JSON.stringify(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)}`
+    );
+  }
+  return parsed;
+}
+function expandActionShortNames(service, actions) {
+  return actions.map((a) => {
+    if (a.includes("/")) {
+      return a;
+    }
+    return `${service}/${a}`;
+  });
+}
+function applyPrefix(prefix, path, skipPrefix) {
+  if (skipPrefix) {
+    return path;
+  }
+  if (prefix === "") {
+    return path;
+  }
+  if (path.startsWith("/")) {
+    return `${prefix}${path}`;
+  }
+  return `${prefix}/${path}`;
+}
+async function loadManifest(url) {
+  const fetchFn = globalThis.fetch;
+  if (typeof fetchFn !== "function") {
+    throw new ManifestValidationError(
+      "loadManifest requires a global fetch; pass the manifest object directly on runtimes without fetch"
+    );
+  }
+  const res = await fetchFn(url);
+  if (!res.ok) {
+    throw new ManifestValidationError(
+      `failed to fetch manifest from ${url}: HTTP ${res.status}`
+    );
+  }
+  const json = await res.json();
+  return validateManifest(json);
+}
+function validateManifest(input) {
+  if (input === null || typeof input !== "object") {
+    throw new ManifestValidationError("manifest must be an object");
+  }
+  const m = input;
+  if (typeof m.id !== "string" || m.id.length === 0) {
+    throw new ManifestValidationError("manifest.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");
+  }
+  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");
+    }
+    m.permissions.forEach(
+      (p, i) => validatePermissionEntry(p, `permissions[${i}]`)
+    );
+  }
+  if (m.delegations !== void 0) {
+    if (!Array.isArray(m.delegations)) {
+      throw new ManifestValidationError("manifest.delegations must be an array");
+    }
+    m.delegations.forEach((d, i) => {
+      if (typeof d?.to !== "string" || d.to.length === 0) {
+        throw new ManifestValidationError(
+          `delegations[${i}].to is required and must be a non-empty DID string`
+        );
+      }
+      if (d.expiry !== void 0) {
+        parseExpiry(d.expiry);
+      }
+      if (!Array.isArray(d.permissions)) {
+        throw new ManifestValidationError(
+          `delegations[${i}].permissions must be an array`
+        );
+      }
+      d.permissions.forEach(
+        (p, j) => validatePermissionEntry(p, `delegations[${i}].permissions[${j}]`)
+      );
+    });
+  }
+  return m;
+}
+function validatePermissionEntry(p, path) {
+  if (p === null || typeof p !== "object") {
+    throw new ManifestValidationError(`${path} must be an object`);
+  }
+  const entry = p;
+  if (typeof entry.service !== "string" || entry.service.length === 0) {
+    throw new ManifestValidationError(`${path}.service is required`);
+  }
+  if (typeof entry.space !== "string" || entry.space.length === 0) {
+    throw new ManifestValidationError(`${path}.space is required`);
+  }
+  if (typeof entry.path !== "string") {
+    throw new ManifestValidationError(
+      `${path}.path is required (use "" or "/" for root)`
+    );
+  }
+  if (!Array.isArray(entry.actions) || entry.actions.length === 0) {
+    throw new ManifestValidationError(
+      `${path}.actions must be a non-empty array`
+    );
+  }
+  if (entry.expiry !== void 0) {
+    parseExpiry(entry.expiry);
+  }
+}
+function normalizeDefaults(value) {
+  if (value === void 0) {
+    return DEFAULT_DEFAULTS;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value !== "string") {
+    return true;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "admin" || normalized === "all") {
+    return normalized;
+  }
+  return true;
+}
+function defaultEntriesForTier(tier) {
+  if (tier === false) {
+    return [];
+  }
+  const source = tier === "admin" ? DEFAULT_ADMIN_ENTRIES : tier === "all" ? DEFAULT_ALL_ENTRIES : DEFAULT_STANDARD_ENTRIES;
+  return source.map((e) => ({
+    service: e.service,
+    space: e.space,
+    path: e.path,
+    actions: [...e.actions]
+  }));
+}
+function resolveManifest(input) {
+  const manifest = validateManifest(input);
+  const prefix = manifest.prefix !== void 0 ? manifest.prefix : manifest.id;
+  const expiryMs = parseExpiry(manifest.expiry ?? DEFAULT_EXPIRY);
+  const includePublicSpace = manifest.includePublicSpace ?? true;
+  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)
+  );
+  const additionalDelegates = (manifest.delegations ?? []).map((d) => ({
+    did: d.to,
+    name: d.name,
+    expiryMs: parseExpiry(d.expiry ?? manifest.expiry ?? DEFAULT_EXPIRY),
+    permissions: d.permissions.map(
+      (entry) => resolveEntry(
+        entry,
+        prefix,
+        parseExpiry(d.expiry ?? manifest.expiry ?? DEFAULT_EXPIRY)
+      )
+    )
+  }));
+  return {
+    id: manifest.id,
+    resources,
+    expiryMs,
+    includePublicSpace,
+    additionalDelegates
+  };
+}
+function resolveEntry(entry, prefix, _inheritedExpiryMs) {
+  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,
+    space: entry.space,
+    path: resolvedPath,
+    actions: resolvedActions,
+    // 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 } : {}
+  };
+}
+
+// src/capabilities.ts
+var PermissionNotInManifestError = class extends Error {
+  constructor(missing, granted) {
+    super(
+      `Requested capabilities exceed current session. Missing ${missing.length} entries.`
+    );
+    this.name = "PermissionNotInManifestError";
+    this.missing = missing;
+    this.granted = granted;
+  }
+};
+var SessionExpiredError = class extends Error {
+  constructor(expiredAt) {
+    super(`Session expired at ${expiredAt.toISOString()}`);
+    this.name = "SessionExpiredError";
+    this.expiredAt = expiredAt;
+  }
+};
+function isCapabilitySubset(requested, granted) {
+  const missing = [];
+  for (const req of requested) {
+    const match = granted.find((g) => canonicalizeEntryMatches(req, g));
+    if (match === void 0) {
+      missing.push(cloneEntry(req));
+      continue;
+    }
+  }
+  return { subset: missing.length === 0, missing };
+}
+function canonicalizeEntryMatches(requested, granted) {
+  if (requested.service !== granted.service) {
+    return false;
+  }
+  if (requested.space !== granted.space) {
+    return false;
+  }
+  if (!pathContains(granted.path, requested.path)) {
+    return false;
+  }
+  const reqActions = new Set(
+    expandActionShortNames(requested.service, requested.actions)
+  );
+  const grantedActions = new Set(
+    expandActionShortNames(granted.service, granted.actions)
+  );
+  for (const a of reqActions) {
+    if (!grantedActions.has(a)) {
+      return false;
+    }
+  }
+  return true;
+}
+function pathContains(grantedPath, requestedPath) {
+  if (grantedPath === "" || grantedPath === "/") {
+    return true;
+  }
+  if (grantedPath.endsWith("/")) {
+    return requestedPath.startsWith(grantedPath);
+  }
+  return requestedPath === grantedPath;
+}
+function cloneEntry(entry) {
+  return {
+    service: entry.service,
+    space: entry.space,
+    path: entry.path,
+    actions: [...entry.actions],
+    ...entry.skipPrefix !== void 0 ? { skipPrefix: entry.skipPrefix } : {},
+    ...entry.expiry !== void 0 ? { expiry: entry.expiry } : {}
+  };
+}
+function parseRecapCapabilities(parseWasm, siwe) {
+  const raw = parseWasm(siwe);
+  if (!Array.isArray(raw)) {
+    throw new Error(
+      "parseRecapFromSiwe returned a non-array value; wasm binding may be out of sync"
+    );
+  }
+  const normalized = raw.map((entry) => {
+    const longService = SERVICE_SHORT_TO_LONG[entry.service] ?? // Unknown short names pass through. If the recap already contained a
+    // long-form service (e.g. a future tinycloud-node version emits long
+    // form directly), don't double-prefix.
+    (entry.service.startsWith("tinycloud.") ? entry.service : `tinycloud.${entry.service}`);
+    return {
+      service: longService,
+      space: entry.space,
+      path: entry.path,
+      actions: [...entry.actions]
+    };
+  });
+  normalized.sort((a, b) => {
+    if (a.space !== b.space) return a.space < b.space ? -1 : 1;
+    if (a.service !== b.service) return a.service < b.service ? -1 : 1;
+    if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+    return 0;
+  });
+  return normalized;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AutoApproveSpaceCreationHandler,
   CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema,
+  DEFAULT_DEFAULTS,
+  DEFAULT_EXPIRY,
   DataVaultService,
   DatabaseHandle,
   DelegationErrorCodes,
@@ -3775,12 +4213,18 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
   DuckDbService,
   EnsDataSchema,
   ErrorCodes,
+  HooksService,
   KVService,
+  ManifestValidationError,
+  PermissionNotInManifestError,
   PrefixedKVService,
   ProtocolMismatchError,
+  SERVICE_LONG_TO_SHORT,
+  SERVICE_SHORT_TO_LONG,
   SQLAction,
   SQLService,
   ServiceContext,
+  SessionExpiredError,
   SharingService,
   SilentNotificationHandler,
   SiweConfigSchema,
@@ -3794,6 +4238,7 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
   VaultPublicSpaceKVActions,
   VersionCheckError,
   activateSessionWithHost,
+  applyPrefix,
   buildSpaceUri,
   checkNodeInfo,
   createCapabilityKeyRegistry,
@@ -3804,13 +4249,21 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
   defaultSignStrategy,
   defaultSpaceCreationHandler,
   err,
+  expandActionShortNames,
   fetchPeerId,
+  isCapabilitySubset,
+  loadManifest,
   makePublicSpaceId,
+  normalizeDefaults,
   ok,
+  parseExpiry,
+  parseRecapCapabilities,
   parseSpaceUri,
+  resolveManifest,
   serviceError,
   submitHostDelegation,
   validateClientSession,
+  validateManifest,
   validatePersistedSessionData
 });
 //# sourceMappingURL=index.cjs.map