@tinycloud/sdk-core 2.1.0-beta.0 → 2.1.0-beta.2

package/dist/index.js

@@ -493,6 +493,16 @@ var DelegationApiResponseSchema = z3.object({
   /** CID of the created delegation */
   cid: z3.string().optional()
 });
+var DelegatedResourceSchema = z3.object({
+  /** Short-form service name, e.g. "kv", "sql", "duckdb", "capabilities", "hooks". */
+  service: z3.string(),
+  /** Full space id string, e.g. "tinycloud:pkh:eip155:1:0x....:default". */
+  space: z3.string(),
+  /** Resource path; empty string when the resource URI had no path segment. */
+  path: z3.string(),
+  /** Full-URN ability strings, e.g. ["tinycloud.kv/get", "tinycloud.kv/put"]. */
+  actions: z3.array(z3.string())
+});
 var CreateDelegationWasmParamsSchema = z3.object({
   /** The session containing delegation credentials */
   session: z3.unknown().refine(
@@ -503,10 +513,23 @@ var CreateDelegationWasmParamsSchema = z3.object({
   delegateDID: z3.string(),
   /** Space ID this delegation applies to */
   spaceId: z3.string(),
-  /** Resource path this delegation grants access to */
-  path: z3.string(),
-  /** Actions to authorize */
-  actions: z3.array(z3.string()),
+  /**
+   * Multi-resource abilities map: short-service → path → full-URN actions.
+   * Matches the shape accepted by `prepareSession`.
+   *
+   * Example:
+   * ```
+   * {
+   *   kv: {
+   *     "com.listen.app/": ["tinycloud.kv/get", "tinycloud.kv/put"]
+   *   },
+   *   sql: {
+   *     "com.listen.app/data.sqlite": ["tinycloud.sql/read"]
+   *   }
+   * }
+   * ```
+   */
+  abilities: z3.record(z3.string(), z3.record(z3.string(), z3.array(z3.string()))),
   /** Expiration time in seconds since Unix epoch */
   expirationSecs: z3.number(),
   /** Optional not-before time in seconds since Unix epoch */
@@ -519,12 +542,13 @@ var CreateDelegationWasmResultSchema = z3.object({
   cid: z3.string(),
   /** DID of the delegate */
   delegateDID: z3.string(),
-  /** Resource path the delegation grants access to */
-  path: z3.string(),
-  /** Actions the delegation authorizes */
-  actions: z3.array(z3.string()),
   /** Expiration time */
-  expiry: z3.coerce.date()
+  expiry: z3.coerce.date(),
+  /**
+   * All (service, space, path, actions) entries granted by this delegation.
+   * Always non-empty on success.
+   */
+  resources: z3.array(DelegatedResourceSchema)
 });
 
 // src/spaces/spaces.schema.ts
@@ -2631,7 +2655,352 @@ function validateEncodedShareData(data) {
   return { ok: true, data: result.data };
 }
 
+// src/manifest.ts
+import ms from "ms";
+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 = ms(
+    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 } : {}
+  };
+}
+function resourceCapabilitiesToAbilitiesMap(resources) {
+  const out = {};
+  for (const r of resources) {
+    const shortService = SERVICE_LONG_TO_SHORT[r.service];
+    if (shortService === void 0) {
+      throw new ManifestValidationError(
+        `unknown service '${r.service}' \u2014 no short-form mapping. Known services: ${Object.keys(SERVICE_LONG_TO_SHORT).join(", ")}`
+      );
+    }
+    if (out[shortService] === void 0) {
+      out[shortService] = {};
+    }
+    const pathsMap = out[shortService];
+    const existing = pathsMap[r.path];
+    if (existing === void 0) {
+      pathsMap[r.path] = [...r.actions];
+    } else {
+      const seen = new Set(existing);
+      for (const action of r.actions) {
+        if (!seen.has(action)) {
+          existing.push(action);
+          seen.add(action);
+        }
+      }
+    }
+  }
+  return out;
+}
+function manifestAbilitiesUnion(resolved) {
+  const all = [...resolved.resources];
+  for (const delegate of resolved.additionalDelegates) {
+    for (const perm of delegate.permissions) {
+      all.push(perm);
+    }
+  }
+  return resourceCapabilitiesToAbilitiesMap(all);
+}
+
 // src/delegations/SharingService.ts
+function inferShortServiceFromActionUrns(actions) {
+  let short;
+  for (const action of actions) {
+    const slash = action.indexOf("/");
+    if (slash === -1) return void 0;
+    const longService = action.slice(0, slash);
+    const candidate = SERVICE_LONG_TO_SHORT[longService];
+    if (candidate === void 0) return void 0;
+    if (short === void 0) {
+      short = candidate;
+    } else if (short !== candidate) {
+      return void 0;
+    }
+  }
+  return short;
+}
 var DEFAULT_READ_ACTIONS = ["tinycloud.kv/get", "tinycloud.kv/metadata"];
 var DEFAULT_EXPIRY_MS = 24 * 60 * 60 * 1e3;
 var BASE64_PREFIX = "tc1:";
@@ -2975,12 +3344,34 @@ var SharingService = class {
     }
     if (this.createDelegationWasmFn) {
       try {
+        if (actions.length === 0) {
+          return {
+            ok: false,
+            error: createError2(
+              DelegationErrorCodes.VALIDATION_ERROR,
+              "createDelegation requires at least one action"
+            )
+          };
+        }
+        const shortService = inferShortServiceFromActionUrns(actions);
+        if (shortService === void 0) {
+          return {
+            ok: false,
+            error: createError2(
+              DelegationErrorCodes.VALIDATION_ERROR,
+              `createDelegation: cannot infer service from actions ${JSON.stringify(actions)} \u2014 expected full URNs like "tinycloud.kv/get"`
+            )
+          };
+        }
         const wasmResult = this.createDelegationWasmFn({
           session: this.session,
           delegateDID,
           spaceId: this.session.spaceId,
-          path,
-          actions,
+          abilities: {
+            [shortService]: {
+              [path]: [...actions]
+            }
+          },
           expirationSecs: Math.floor(expiry.getTime() / 1e3)
         });
         const registerRes = await this.fetchFn(`${this.host}/delegate`, {
@@ -2999,12 +3390,22 @@ var SharingService = class {
             )
           };
         }
+        if (wasmResult.resources.length === 0) {
+          return {
+            ok: false,
+            error: createError2(
+              DelegationErrorCodes.CREATION_FAILED,
+              "createDelegation WASM returned empty resources array for a single-entry request"
+            )
+          };
+        }
+        const primary = wasmResult.resources[0];
         return {
           cid: wasmResult.cid,
           delegateDID: wasmResult.delegateDID,
           spaceId: this.session.spaceId,
-          path: wasmResult.path,
-          actions: wasmResult.actions,
+          path: primary.path,
+          actions: primary.actions,
           expiry: wasmResult.expiry,
           isRevoked: false,
           authHeader: wasmResult.delegation,
@@ -3733,11 +4134,112 @@ async function checkNodeInfo(host, sdkProtocol, fetchFn = globalThis.fetch.bind(
     quotaUrl: data.quota_url
   };
 }
+
+// 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;
+}
 export {
   AutoApproveSpaceCreationHandler,
   CapabilityKeyRegistry,
   CapabilityKeyRegistryErrorCodes,
   ClientSessionSchema,
+  DEFAULT_DEFAULTS,
+  DEFAULT_EXPIRY,
   DataVaultService,
   DatabaseHandle,
   DelegationErrorCodes,
@@ -3749,11 +4251,16 @@ export {
   ErrorCodes2 as ErrorCodes,
   HooksService2 as HooksService,
   KVService2 as KVService,
+  ManifestValidationError,
+  PermissionNotInManifestError,
   PrefixedKVService,
   ProtocolMismatchError,
+  SERVICE_LONG_TO_SHORT,
+  SERVICE_SHORT_TO_LONG,
   SQLAction,
   SQLService2 as SQLService,
   ServiceContext2 as ServiceContext,
+  SessionExpiredError,
   SharingService,
   SilentNotificationHandler,
   SiweConfigSchema,
@@ -3767,6 +4274,7 @@ export {
   VaultPublicSpaceKVActions,
   VersionCheckError,
   activateSessionWithHost,
+  applyPrefix,
   buildSpaceUri,
   checkNodeInfo,
   createCapabilityKeyRegistry,
@@ -3777,13 +4285,23 @@ export {
   defaultSignStrategy,
   defaultSpaceCreationHandler,
   err4 as err,
+  expandActionShortNames,
   fetchPeerId,
+  isCapabilitySubset,
+  loadManifest,
   makePublicSpaceId,
+  manifestAbilitiesUnion,
+  normalizeDefaults,
   ok4 as ok,
+  parseExpiry,
+  parseRecapCapabilities,
   parseSpaceUri,
+  resolveManifest,
+  resourceCapabilitiesToAbilitiesMap,
   serviceError4 as serviceError,
   submitHostDelegation,
   validateClientSession,
+  validateManifest,
   validatePersistedSessionData
 };
 //# sourceMappingURL=index.js.map