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

package/dist/index.d.cts

@@ -179,6 +179,416 @@ interface IENSResolver {
     resolveAvatar?(ensName: string): Promise<string | null>;
 }
 
+/**
+ * TinyCloud App Manifest
+ *
+ * A declarative description of an app's identity and the capabilities it
+ * needs. The manifest drives the SIWE recap at sign-in time, enabling a
+ * single wallet prompt that covers the app's own permissions plus any
+ * pre-declared delegations.
+ *
+ * The SDK does NOT fetch external manifests. Apps compose their own manifest
+ * (optionally including backend or agent addenda) before handing it to the
+ * SDK.
+ *
+ * Canonical spec: `.claude/specs/manifest.md`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single permission entry inside a manifest. This is the shape apps write
+ * in their `manifest.json` and the shape we compare against when performing
+ * the capability-subset derivability check in the delegation flow.
+ *
+ * `service` uses the long form (e.g. `"tinycloud.kv"`, `"tinycloud.sql"`)
+ * which matches the ability-namespace half of the full action URN.
+ */
+interface PermissionEntry {
+    /** Service namespace, e.g. "tinycloud.kv", "tinycloud.sql", "tinycloud.duckdb", "tinycloud.capabilities". */
+    service: string;
+    /** "default" for the user's personal space, or a specific space id. */
+    space: string;
+    /**
+     * Service-specific path.
+     * - tinycloud.kv: hierarchical prefix. "/" = all, "foo/" = prefix match, "foo" = exact key
+     * - tinycloud.sql: database name/file (e.g. "data.sqlite") or "/" for all
+     * - tinycloud.duckdb: database name/file
+     * - tinycloud.capabilities: capability key URI or "/" for all
+     */
+    path: string;
+    /**
+     * Short action names (e.g. "get", "put", "read", "ddl"). The SDK expands
+     * these to full URNs (e.g. `tinycloud.kv/get`) during resolution.
+     * Already-expanded URNs are passed through unchanged.
+     */
+    actions: string[];
+    /** When true, the manifest prefix is NOT prepended to `path`. Default false. */
+    skipPrefix?: boolean;
+    /** Per-entry expiry override, ms-format. */
+    expiry?: string;
+}
+/**
+ * A pre-declared delegation that will be included in the main SIWE recap as
+ * an additional audience.
+ */
+interface ManifestDelegation {
+    /** DID of the delegate (e.g. a backend's wallet DID). */
+    to: string;
+    /** Informational display name. Optional. */
+    name?: string;
+    /** Expiry override for this delegation, ms-format. Optional. */
+    expiry?: string;
+    /**
+     * Permissions to delegate. Same shape as the top-level `permissions`, and
+     * the manifest prefix is inherited identically (unless `skipPrefix: true`).
+     */
+    permissions: PermissionEntry[];
+}
+/**
+ * The valid values for `Manifest.defaults`.
+ *
+ * - `false` → no auto-included permissions
+ * - `true` → standard tier (KV + SQL read/write + capabilities:read)
+ * - `"admin"` → standard + SQL ddl + capabilities:admin
+ * - `"all"` → everything the SDK supports (including DuckDB)
+ *
+ * Unknown string values silently fall back to `true`. Values are normalized
+ * (lowercase + trim) before matching.
+ */
+type ManifestDefaults = boolean | "admin" | "all";
+/**
+ * The raw manifest shape an app declares. See `.claude/specs/manifest.md`.
+ */
+interface Manifest {
+    /** Schema version. Optional, defaults to 1. */
+    version?: number;
+    /** Bundle identifier — reverse DNS. Required. */
+    id: string;
+    /** Display name. Required. */
+    name: string;
+    /** One-line description. Optional. */
+    description?: string;
+    /** URL to app icon. Optional. */
+    icon?: string;
+    /** App version string. Optional. */
+    appVersion?: string;
+    /** Default expiry for permissions. ms-format ("30d", "2h", "1y"). Default "30d". */
+    expiry?: string;
+    /**
+     * Path prefix auto-prepended to permission paths. Optional, defaults to
+     * `id`. Set to `""` to disable entirely. Individual permissions can opt
+     * out with `skipPrefix: true`.
+     */
+    prefix?: string;
+    /**
+     * Default permission set to auto-include. Optional, defaults to `true`.
+     * See {@link ManifestDefaults}.
+     */
+    defaults?: ManifestDefaults | string;
+    /** Whether to include the public-space companion delegation. Default `true`. */
+    includePublicSpace?: boolean;
+    /**
+     * Additional permissions beyond the defaults. Use for cross-space access,
+     * DuckDB (opt-in), or `skipPrefix: true` entries.
+     */
+    permissions?: PermissionEntry[];
+    /** Pre-delegations to other DIDs at sign-in. */
+    delegations?: ManifestDelegation[];
+}
+/**
+ * A resolved permission entry with fully-expanded paths and action URNs.
+ * This is the shape the delegation flow compares against parsed recap
+ * capabilities, and the shape the session-key delegation path actually uses.
+ */
+interface ResourceCapability {
+    /** Long-form service, e.g. "tinycloud.kv". */
+    service: string;
+    /** Space id — "default" stays as-is here; the caller resolves it to a full SpaceId at sign-in time. */
+    space: string;
+    /** Path with the manifest prefix applied (or skipped per `skipPrefix`). */
+    path: string;
+    /** Full-URN actions, e.g. ["tinycloud.kv/get", "tinycloud.kv/put"]. */
+    actions: string[];
+    /** Per-entry expiry override in milliseconds. */
+    expiryMs?: number;
+}
+/**
+ * A resolved delegation entry with fully-expanded permissions.
+ */
+interface ResolvedDelegate {
+    /** DID of the delegate. */
+    did: string;
+    /** Informational display name. Optional. */
+    name?: string;
+    /** Expiry in milliseconds (per-delegation > manifest default > 30 days). */
+    expiryMs: number;
+    /** Fully resolved permissions. */
+    permissions: ResourceCapability[];
+}
+/**
+ * The output of {@link resolveManifest}: a fully-expanded capability set
+ * ready to drive the SIWE recap.
+ */
+interface ResolvedCapabilities {
+    /** Bundle identifier copied from manifest.id. */
+    id: string;
+    /** All session-key resources with paths fully resolved (prefix applied). */
+    resources: ResourceCapability[];
+    /** Default expiry for the session, in milliseconds. */
+    expiryMs: number;
+    /** Whether to include the public-space companion. */
+    includePublicSpace: boolean;
+    /** Additional delegate targets with resolved paths. */
+    additionalDelegates: ResolvedDelegate[];
+}
+/**
+ * Thrown when the manifest fails validation (missing id/name, bad expiry,
+ * empty actions on a permission, etc).
+ */
+declare class ManifestValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Default expiry when neither the manifest, delegation, nor permission
+ * specifies one. Spec: 30 days.
+ */
+declare const DEFAULT_EXPIRY = "30d";
+/**
+ * Default `defaults` value when the manifest omits it. Spec: standard tier.
+ */
+declare const DEFAULT_DEFAULTS: ManifestDefaults;
+/**
+ * Known services and their short-form (recap URI) names. The TinyCloud
+ * node encodes the recap resource URI with the short service name, while
+ * action URNs and manifest entries use the long `tinycloud.<short>` form.
+ * This table is the canonical bridge between the two.
+ */
+declare const SERVICE_SHORT_TO_LONG: Readonly<Record<string, string>>;
+/**
+ * Inverse of {@link SERVICE_SHORT_TO_LONG}.
+ */
+declare const SERVICE_LONG_TO_SHORT: Readonly<Record<string, string>>;
+/**
+ * Parse an ms-format duration string (e.g. "30d", "2h", "1y") into
+ * milliseconds.
+ *
+ * @throws {ManifestValidationError} on empty string, non-string input, or
+ * any input `ms()` cannot parse.
+ */
+declare function parseExpiry(duration: string): number;
+/**
+ * Expand a list of action short names (or already-expanded URNs) into full
+ * ability URNs of the form `<service>/<action>`.
+ *
+ * Examples:
+ *   `expandActionShortNames("tinycloud.kv", ["get", "put"])`
+ *     → `["tinycloud.kv/get", "tinycloud.kv/put"]`
+ *   `expandActionShortNames("tinycloud.kv", ["tinycloud.kv/get"])`
+ *     → `["tinycloud.kv/get"]` (passed through unchanged)
+ */
+declare function expandActionShortNames(service: string, actions: readonly string[]): string[];
+/**
+ * Apply the manifest prefix to a permission path per the spec rules.
+ *
+ * - `skipPrefix: true` → path is returned as-is
+ * - `prefix === ""` → path is returned as-is
+ * - path starts with "/" → `prefix + path`  (e.g. "com.listen.app" + "/" → "com.listen.app/")
+ * - otherwise → `prefix + "/" + path`  (e.g. "com.listen.app" + "data.sqlite" → "com.listen.app/data.sqlite")
+ */
+declare function applyPrefix(prefix: string, path: string, skipPrefix: boolean): string;
+/**
+ * Fetch and parse a manifest from a URL (browser) or file path (node).
+ * The runtime decides the fetch strategy via `globalThis.fetch`; this is
+ * platform-agnostic. Callers that want custom loading should JSON.parse a
+ * Manifest themselves and skip this helper.
+ *
+ * @throws if the fetch fails, the JSON is invalid, or the manifest fails
+ * validation.
+ */
+declare function loadManifest(url: string): Promise<Manifest>;
+/**
+ * Validate a manifest-shaped object and return it strongly-typed.
+ * Throws {@link ManifestValidationError} on any hard failure.
+ */
+declare function validateManifest(input: unknown): Manifest;
+/**
+ * Normalize a `defaults` value: lowercase + trim, then match against known
+ * tiers. Unknown string values silently fall back to `true` (standard).
+ * Boolean values pass through.
+ */
+declare function normalizeDefaults(value: Manifest["defaults"] | undefined): ManifestDefaults;
+/**
+ * Resolve a raw manifest into a {@link ResolvedCapabilities} object: expand
+ * shortform actions, apply the prefix, merge defaults, and compute effective
+ * expiries. Pure function — does no I/O.
+ *
+ * Resolution semantics (spec):
+ * - `prefix` defaults to `id`; set to `""` to disable prefix application entirely.
+ * - `defaults` defaults to `true` (standard tier); unknown string values fall back to `true`.
+ * - Per-entry expiry overrides per-delegation overrides manifest > `DEFAULT_EXPIRY`.
+ * - Default entries use `skipPrefix: false` so they inherit the manifest prefix.
+ * - Prefix inheritance applies identically to `permissions` and `delegations[*].permissions`.
+ */
+declare function resolveManifest(input: Manifest): ResolvedCapabilities;
+/**
+ * The shape `prepareSession` and the multi-resource `createDelegation` WASM
+ * export both accept:
+ *
+ * ```
+ * { [shortService]: { [path]: [fullUrnAction, ...] } }
+ * ```
+ *
+ * - `shortService` is the recap-level service segment (`"kv"`, `"sql"`,
+ *   `"duckdb"`, `"capabilities"`, `"hooks"`) — not the manifest long form.
+ * - `path` is the fully-resolved path (prefix already applied). An empty
+ *   string means "no path segment" on the resource URI.
+ * - Action strings are full URNs like `"tinycloud.kv/get"`.
+ *
+ * This is a single source of truth for both the session's own recap (at
+ * sign-in) and the delegations it can derive (post sign-in). We re-use it
+ * for both so one manifest drives both sides.
+ */
+type AbilitiesMap = Record<string, Record<string, string[]>>;
+/**
+ * Convert a list of {@link ResourceCapability} entries (manifest
+ * long-form service, full-URN actions) into the {@link AbilitiesMap}
+ * shape the WASM layer expects.
+ *
+ * When multiple entries target the same `(service, path)` pair, their
+ * action lists are merged and deduped. Entries whose service has no
+ * short-form mapping in {@link SERVICE_LONG_TO_SHORT} are rejected with
+ * a {@link ManifestValidationError} — the SDK does not silently drop
+ * unknown services because the recap encoding would lose them.
+ *
+ * Paths are kept verbatim: this function does NOT collapse
+ * `"com.listen.app/"` and `"com.listen.app"` or reinterpret empty /
+ * slash strings. Callers that care about path canonicalization should
+ * normalize before calling.
+ */
+declare function resourceCapabilitiesToAbilitiesMap(resources: readonly ResourceCapability[]): AbilitiesMap;
+/**
+ * Build the {@link AbilitiesMap} that a session should be signed with,
+ * given a {@link ResolvedCapabilities} (i.e. the output of
+ * {@link resolveManifest}).
+ *
+ * The resulting map is the **union** of:
+ * 1. the app's own resources (`resolved.resources`), and
+ * 2. every permission declared in every `additionalDelegates[*]` entry.
+ *
+ * The union is what makes the manifest's delegations ergonomic: at
+ * sign-in, the session key acquires recap coverage for both the app's
+ * runtime needs and every downstream delegation target. Post sign-in,
+ * `delegateTo(backendDID, backendPermissions)` can then issue the
+ * sub-delegation via the session key (no wallet prompt) because the
+ * caps are already part of the granted set.
+ *
+ * Duplicate `(service, path, action)` triples across resources and
+ * delegations are merged and deduped — the session SIWE doesn't need
+ * them repeated.
+ */
+declare function manifestAbilitiesUnion(resolved: ResolvedCapabilities): AbilitiesMap;
+
+/**
+ * Capability subset checking and recap parsing.
+ *
+ * This module powers the capability-chain delegation flow. The key decision
+ * a `delegateTo` call has to make is: "are the requested capabilities a
+ * subset of what the current session already grants?"
+ *
+ * - If yes → issue the delegation via the session-key UCAN path (no wallet prompt).
+ * - If no → raise {@link PermissionNotInManifestError} so the caller can
+ *   trigger an escalation flow via `requestPermissions`.
+ *
+ * Canonical spec: `.claude/specs/capability-chain.md`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Thrown when a `delegateTo` call requests capabilities that the current
+ * session does not already grant. The caller can catch this and trigger
+ * `requestPermissions(missing)` to show an escalation modal.
+ */
+declare class PermissionNotInManifestError extends Error {
+    readonly missing: PermissionEntry[];
+    readonly granted: PermissionEntry[];
+    constructor(missing: PermissionEntry[], granted: PermissionEntry[]);
+}
+/**
+ * Thrown when the current session has expired (or will expire within the
+ * safety margin). The caller should trigger a fresh sign-in.
+ */
+declare class SessionExpiredError extends Error {
+    readonly expiredAt: Date;
+    constructor(expiredAt: Date);
+}
+interface SubsetCheckResult {
+    /** True when every requested entry is covered by a granted entry. */
+    subset: boolean;
+    /** Entries the granted set does not cover (empty when `subset` is true). */
+    missing: PermissionEntry[];
+}
+/**
+ * Check whether `requested` is a strict subset of `granted`.
+ *
+ * Matching rules for each `requested[i]`:
+ * - `service` matches exactly.
+ * - `space` matches exactly.
+ * - Path containment:
+ *     - If `granted.path` ends with `/`, it covers any `requested.path` that
+ *       starts with `granted.path`.
+ *     - Otherwise, the paths must match exactly.
+ * - Action containment: every URN in `requested.actions` must appear in
+ *   `granted.actions` (set subset).
+ *
+ * Any `requested` entry that does not find a matching `granted` entry is
+ * added to `missing` and the overall result is non-subset.
+ *
+ * Both sides are expected to be in the canonical long-form shape (service
+ * starts with `tinycloud.`, actions are full URNs). Use {@link parseRecapCapabilities}
+ * or `expandActionShortNames` to normalize inputs first.
+ */
+declare function isCapabilitySubset(requested: readonly PermissionEntry[], granted: readonly PermissionEntry[]): SubsetCheckResult;
+/**
+ * The raw shape returned from the WASM `parseRecapFromSiwe` export. The
+ * Rust layer encodes the service in the short form (e.g. `"kv"`) because
+ * that is what the SIWE recap resource URI actually contains. We normalize
+ * to the manifest long form (`"tinycloud.kv"`) in {@link parseRecapCapabilities}.
+ *
+ * @internal
+ */
+interface WasmRecapEntry {
+    service: string;
+    space: string;
+    path: string;
+    actions: string[];
+}
+/**
+ * Signature of the WASM `parseRecapFromSiwe` export. Accepts the signed
+ * SIWE message string and returns an array of raw recap entries. Throws if
+ * the SIWE is malformed or the recap statement has been tampered.
+ *
+ * Exposed as an interface so the SDK can inject the web or node binding
+ * without `capabilities.ts` needing to know which.
+ */
+type ParseRecapFromSiwe = (siweString: string) => WasmRecapEntry[];
+/**
+ * Parse a signed SIWE message into an array of {@link PermissionEntry}
+ * objects in the canonical long-form manifest shape.
+ *
+ * This is a thin wrapper around the WASM `parseRecapFromSiwe` export that:
+ * 1. Normalizes short-form services (`"kv"`) to long-form (`"tinycloud.kv"`).
+ * 2. Returns entries in a deterministic order (sorted by space, then service,
+ *    then path) so downstream equality checks are stable.
+ *
+ * Returns an empty array when the SIWE has no recap resource (plain auth
+ * SIWE); this matches the WASM function's behavior and the spec.
+ *
+ * @param parseWasm The WASM `parseRecapFromSiwe` binding.
+ * @param siwe The signed SIWE message string (exactly what `session.siwe` stores).
+ */
+declare function parseRecapCapabilities(parseWasm: ParseRecapFromSiwe, siwe: string): PermissionEntry[];
+
 /**
  * WASM binding abstraction for TinyCloud SDK.
  *
@@ -210,6 +620,15 @@ interface IWasmBindings {
     makeSpaceId: (address: string, chainId: number, prefix: string) => string;
     /** Create a delegation */
     createDelegation: (...args: any[]) => any;
+    /**
+     * Parse the recap resource of a signed SIWE message into structured
+     * permission entries. Used by the capability-chain delegation flow to
+     * decide whether a requested delegation is derivable from the current
+     * session without a fresh wallet prompt.
+     *
+     * Returns an empty array when the SIWE has no recap resource.
+     */
+    parseRecapFromSiwe: (siweString: string) => WasmRecapEntry[];
     /** Generate a host SIWE message for space activation */
     generateHostSIWEMessage: (params: any) => string;
     /** Convert a signed SIWE message to delegation headers */
@@ -837,11 +1256,11 @@ declare const DelegationSchema: z.ZodObject<{
     authHeader: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     path: string;
+    actions: string[];
+    expiry: Date;
     spaceId: string;
     cid: string;
     delegateDID: string;
-    actions: string[];
-    expiry: Date;
     isRevoked: boolean;
     createdAt?: Date | undefined;
     delegatorDID?: string | undefined;
@@ -850,11 +1269,11 @@ declare const DelegationSchema: z.ZodObject<{
     authHeader?: string | undefined;
 }, {
     path: string;
+    actions: string[];
+    expiry: Date;
     spaceId: string;
     cid: string;
     delegateDID: string;
-    actions: string[];
-    expiry: Date;
     isRevoked: boolean;
     createdAt?: Date | undefined;
     delegatorDID?: string | undefined;
@@ -995,11 +1414,11 @@ declare const CapabilityEntrySchema: z.ZodObject<{
         authHeader: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1008,11 +1427,11 @@ declare const CapabilityEntrySchema: z.ZodObject<{
         authHeader?: string | undefined;
     }, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1044,11 +1463,11 @@ declare const CapabilityEntrySchema: z.ZodObject<{
     }[];
     delegation: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1081,11 +1500,11 @@ declare const CapabilityEntrySchema: z.ZodObject<{
     }[];
     delegation: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1128,10 +1547,10 @@ declare const DelegationRecordSchema: z.ZodObject<{
     parentCid: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     path: string;
+    actions: string[];
     spaceId: string;
     createdAt: Date;
     cid: string;
-    actions: string[];
     isRevoked: boolean;
     delegator: string;
     delegatee: string;
@@ -1141,10 +1560,10 @@ declare const DelegationRecordSchema: z.ZodObject<{
     keyId?: string | undefined;
 }, {
     path: string;
+    actions: string[];
     spaceId: string;
     createdAt: Date;
     cid: string;
-    actions: string[];
     isRevoked: boolean;
     delegator: string;
     delegatee: string;
@@ -1172,15 +1591,15 @@ declare const CreateDelegationParamsSchema: z.ZodObject<{
     statement: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     path: string;
-    delegateDID: string;
     actions: string[];
+    delegateDID: string;
     statement?: string | undefined;
     expiry?: Date | undefined;
     disableSubDelegation?: boolean | undefined;
 }, {
     path: string;
-    delegateDID: string;
     actions: string[];
+    delegateDID: string;
     statement?: string | undefined;
     expiry?: Date | undefined;
     disableSubDelegation?: boolean | undefined;
@@ -1216,11 +1635,11 @@ declare const DelegationChainSchema: z.ZodArray<z.ZodObject<{
     authHeader: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     path: string;
+    actions: string[];
+    expiry: Date;
     spaceId: string;
     cid: string;
     delegateDID: string;
-    actions: string[];
-    expiry: Date;
     isRevoked: boolean;
     createdAt?: Date | undefined;
     delegatorDID?: string | undefined;
@@ -1229,11 +1648,11 @@ declare const DelegationChainSchema: z.ZodArray<z.ZodObject<{
     authHeader?: string | undefined;
 }, {
     path: string;
+    actions: string[];
+    expiry: Date;
     spaceId: string;
     cid: string;
     delegateDID: string;
-    actions: string[];
-    expiry: Date;
     isRevoked: boolean;
     createdAt?: Date | undefined;
     delegatorDID?: string | undefined;
@@ -1274,11 +1693,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
         authHeader: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1287,11 +1706,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
         authHeader?: string | undefined;
     }, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1327,11 +1746,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
         authHeader: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1340,11 +1759,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
         authHeader?: string | undefined;
     }, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1380,11 +1799,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
         authHeader: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1393,11 +1812,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
         authHeader?: string | undefined;
     }, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1408,11 +1827,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     root: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1422,11 +1841,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
     };
     chain: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1436,11 +1855,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
     }[];
     leaf: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1451,11 +1870,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
 }, {
     root: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1465,11 +1884,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
     };
     chain: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1479,11 +1898,11 @@ declare const DelegationChainV2Schema: z.ZodObject<{
     }[];
     leaf: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1525,7 +1944,7 @@ declare const DelegationFiltersSchema: z.ZodObject<{
     actions?: string[] | undefined;
     delegator?: string | undefined;
     delegatee?: string | undefined;
-    direction?: "received" | "granted" | "all" | undefined;
+    direction?: "received" | "all" | "granted" | undefined;
     includeRevoked?: boolean | undefined;
     validAt?: Date | undefined;
     limit?: number | undefined;
@@ -1535,7 +1954,7 @@ declare const DelegationFiltersSchema: z.ZodObject<{
     actions?: string[] | undefined;
     delegator?: string | undefined;
     delegatee?: string | undefined;
-    direction?: "received" | "granted" | "all" | undefined;
+    direction?: "received" | "all" | "granted" | undefined;
     includeRevoked?: boolean | undefined;
     validAt?: Date | undefined;
     limit?: number | undefined;
@@ -1620,11 +2039,11 @@ declare const ShareLinkSchema: z.ZodObject<{
         authHeader: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1633,11 +2052,11 @@ declare const ShareLinkSchema: z.ZodObject<{
         authHeader?: string | undefined;
     }, {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1655,11 +2074,11 @@ declare const ShareLinkSchema: z.ZodObject<{
     url: string;
     delegation: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1675,11 +2094,11 @@ declare const ShareLinkSchema: z.ZodObject<{
     url: string;
     delegation: {
         path: string;
+        actions: string[];
+        expiry: Date;
         spaceId: string;
         cid: string;
         delegateDID: string;
-        actions: string[];
-        expiry: Date;
         isRevoked: boolean;
         createdAt?: Date | undefined;
         delegatorDID?: string | undefined;
@@ -1828,8 +2247,51 @@ declare const DelegationApiResponseSchema: z.ZodObject<{
     cid?: string | undefined;
 }>;
 type DelegationApiResponse = z.infer<typeof DelegationApiResponseSchema>;
+/**
+ * A single (service, space, path, actions) entry inside a
+ * createDelegation WASM result.
+ *
+ * Mirrors the Rust `DelegatedResource` struct in
+ * `tinycloud-sdk-wasm/src/session.rs`. Field names match the manifest
+ * {@link PermissionEntry} shape so callers can reconstruct what they sent
+ * without having to re-parse the UCAN.
+ *
+ * `service` is the short form (e.g. `"kv"`, `"sql"`) as returned by the
+ * Rust layer. The SDK layer translates to the long form
+ * (`"tinycloud.kv"`) when comparing against manifests.
+ */
+declare const DelegatedResourceSchema: z.ZodObject<{
+    /** Short-form service name, e.g. "kv", "sql", "duckdb", "capabilities", "hooks". */
+    service: z.ZodString;
+    /** Full space id string, e.g. "tinycloud:pkh:eip155:1:0x....:default". */
+    space: z.ZodString;
+    /** Resource path; empty string when the resource URI had no path segment. */
+    path: z.ZodString;
+    /** Full-URN ability strings, e.g. ["tinycloud.kv/get", "tinycloud.kv/put"]. */
+    actions: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    service: string;
+    space: string;
+    actions: string[];
+}, {
+    path: string;
+    service: string;
+    space: string;
+    actions: string[];
+}>;
+type DelegatedResource = z.infer<typeof DelegatedResourceSchema>;
 /**
  * Input parameters for the createDelegation WASM function.
+ *
+ * A single call may encode multiple `(service, path, actions)` entries
+ * via the `abilities` map — the underlying UCAN will contain one
+ * attenuation entry per `(service, path)` pair, all signed by the same
+ * session key in one blob.
+ *
+ * The `abilities` shape is identical to what `prepareSession` accepts
+ * (`Record<shortService, Record<path, actionURNs[]>>`), so manifest
+ * resolution can feed both sides from one data structure.
  */
 declare const CreateDelegationWasmParamsSchema: z.ZodObject<{
     /** The session containing delegation credentials */
@@ -1838,27 +2300,38 @@ declare const CreateDelegationWasmParamsSchema: z.ZodObject<{
     delegateDID: z.ZodString;
     /** Space ID this delegation applies to */
     spaceId: z.ZodString;
-    /** Resource path this delegation grants access to */
-    path: z.ZodString;
-    /** Actions to authorize */
-    actions: z.ZodArray<z.ZodString, "many">;
+    /**
+     * 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: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
     /** Expiration time in seconds since Unix epoch */
     expirationSecs: z.ZodNumber;
     /** Optional not-before time in seconds since Unix epoch */
     notBeforeSecs: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    path: string;
     spaceId: string;
     session: ServiceSession;
     delegateDID: string;
-    actions: string[];
+    abilities: Record<string, Record<string, string[]>>;
     expirationSecs: number;
     notBeforeSecs?: number | undefined;
 }, {
-    path: string;
     spaceId: string;
     delegateDID: string;
-    actions: string[];
+    abilities: Record<string, Record<string, string[]>>;
     expirationSecs: number;
     session?: unknown;
     notBeforeSecs?: number | undefined;
@@ -1866,6 +2339,11 @@ declare const CreateDelegationWasmParamsSchema: z.ZodObject<{
 type CreateDelegationWasmParams = z.infer<typeof CreateDelegationWasmParamsSchema>;
 /**
  * Result from the createDelegation WASM function.
+ *
+ * A single UCAN may cover multiple resources. The `resources` array
+ * describes every `(service, space, path, actions)` entry granted, in
+ * deterministic (service, path) lexicographic order (the Rust side sorts
+ * the HashMap entries before signing).
  */
 declare const CreateDelegationWasmResultSchema: z.ZodObject<{
     /** Base64url-encoded UCAN delegation */
@@ -1874,26 +2352,54 @@ declare const CreateDelegationWasmResultSchema: z.ZodObject<{
     cid: z.ZodString;
     /** DID of the delegate */
     delegateDID: z.ZodString;
-    /** Resource path the delegation grants access to */
-    path: z.ZodString;
-    /** Actions the delegation authorizes */
-    actions: z.ZodArray<z.ZodString, "many">;
     /** Expiration time */
     expiry: z.ZodDate;
+    /**
+     * All (service, space, path, actions) entries granted by this delegation.
+     * Always non-empty on success.
+     */
+    resources: z.ZodArray<z.ZodObject<{
+        /** Short-form service name, e.g. "kv", "sql", "duckdb", "capabilities", "hooks". */
+        service: z.ZodString;
+        /** Full space id string, e.g. "tinycloud:pkh:eip155:1:0x....:default". */
+        space: z.ZodString;
+        /** Resource path; empty string when the resource URI had no path segment. */
+        path: z.ZodString;
+        /** Full-URN ability strings, e.g. ["tinycloud.kv/get", "tinycloud.kv/put"]. */
+        actions: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        service: string;
+        space: string;
+        actions: string[];
+    }, {
+        path: string;
+        service: string;
+        space: string;
+        actions: string[];
+    }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    path: string;
+    resources: {
+        path: string;
+        service: string;
+        space: string;
+        actions: string[];
+    }[];
+    expiry: Date;
     delegation: string;
     cid: string;
     delegateDID: string;
-    actions: string[];
-    expiry: Date;
 }, {
-    path: string;
+    resources: {
+        path: string;
+        service: string;
+        space: string;
+        actions: string[];
+    }[];
+    expiry: Date;
     delegation: string;
     cid: string;
     delegateDID: string;
-    actions: string[];
-    expiry: Date;
 }>;
 type CreateDelegationWasmResult = z.infer<typeof CreateDelegationWasmResultSchema>;
 
@@ -3875,4 +4381,4 @@ interface NodeInfo {
 }
 declare function checkNodeInfo(host: string, sdkProtocol: number, fetchFn?: typeof globalThis.fetch): Promise<NodeInfo>;
 
-export { AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, type ClientSession, ClientSessionSchema, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, type Delegation, type DelegationApiResponse, type DelegationChain, type DelegationChainV2, type DelegationDirection, type DelegationError, type DelegationErrorCode, DelegationErrorCodes, type DelegationFilters, DelegationManager, type DelegationManagerConfig, type DelegationRecord, type Result as DelegationResult, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type Extension, type GenerateShareParams, type ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, type ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, type NodeInfo, type PartialSiweMessage, type PersistedSessionData, type PersistedTinyCloudSession, ProtocolMismatchError, type ReceiveOptions, type ServerHost, type ShareAccess, type ShareLink, type ShareLinkData, type ShareSchema, SharingService, type SharingServiceConfig, type SignCallback, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, type SpaceInfo, type SpaceOwnership, SpaceService, type SpaceServiceConfig, type StoredDelegationChain, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, type ValidationError, VersionCheckError, activateSessionWithHost, buildSpaceUri, checkNodeInfo, createCapabilityKeyRegistry, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, fetchPeerId, makePublicSpaceId, parseSpaceUri, submitHostDelegation, validateClientSession, validatePersistedSessionData };
+export { type AbilitiesMap, AutoApproveSpaceCreationHandler, type AutoRejectStrategy, type AutoSignStrategy, type Bytes, type CallbackStrategy, type CapabilityEntry, CapabilityKeyRegistry, type CapabilityKeyRegistryErrorCode, CapabilityKeyRegistryErrorCodes, type ClientSession, ClientSessionSchema, type CreateDelegationFunction, type CreateDelegationParams, type CreateDelegationWasmParams, type CreateDelegationWasmResult, DEFAULT_DEFAULTS, DEFAULT_EXPIRY, type DelegatedResource, type Delegation, type DelegationApiResponse, type DelegationChain, type DelegationChainV2, type DelegationDirection, type DelegationError, type DelegationErrorCode, DelegationErrorCodes, type DelegationFilters, DelegationManager, type DelegationManagerConfig, type DelegationRecord, type Result as DelegationResult, type EncodedShareData, type EnsData, EnsDataSchema, type EventEmitterStrategy, type Extension, type GenerateShareParams, type ICapabilityKeyRegistry, type IENSResolver, type INotificationHandler, type ISessionManager, type ISessionStorage, type ISharingService, type ISigner, type ISpace, type ISpaceCreationHandler, type ISpaceScopedDelegations, type ISpaceScopedSharing, type ISpaceService, type IUserAuthorization, type IWasmBindings, type IngestOptions, type JWK, type KeyInfo, type KeyProvider, type KeyType, type Manifest, type ManifestDefaults, type ManifestDelegation, ManifestValidationError, type NodeInfo, type ParseRecapFromSiwe, type PartialSiweMessage, type PermissionEntry, PermissionNotInManifestError, type PersistedSessionData, type PersistedTinyCloudSession, ProtocolMismatchError, type ReceiveOptions, type ResolvedCapabilities, type ResolvedDelegate, type ResourceCapability, SERVICE_LONG_TO_SHORT, SERVICE_SHORT_TO_LONG, type ServerHost, SessionExpiredError, type ShareAccess, type ShareLink, type ShareLinkData, type ShareSchema, SharingService, type SharingServiceConfig, type SignCallback, type SignRequest, type SignResponse, type SignStrategy, SilentNotificationHandler, type SiweConfig, SiweConfigSchema, Space, type SpaceConfig, type SpaceCreationContext, type SpaceDelegationParams, type SpaceErrorCode, SpaceErrorCodes, type SpaceHostResult, type SpaceInfo, type SpaceOwnership, SpaceService, type SpaceServiceConfig, type StoredDelegationChain, type SubsetCheckResult, TinyCloud, type TinyCloudConfig, type TinyCloudSession, UnsupportedFeatureError, type UserAuthorizationConfig, type ValidationError, VersionCheckError, type WasmRecapEntry, activateSessionWithHost, applyPrefix, buildSpaceUri, checkNodeInfo, createCapabilityKeyRegistry, createSharingService, createSpaceService, defaultSignStrategy, defaultSpaceCreationHandler, expandActionShortNames, fetchPeerId, isCapabilitySubset, loadManifest, makePublicSpaceId, manifestAbilitiesUnion, normalizeDefaults, parseExpiry, parseRecapCapabilities, parseSpaceUri, resolveManifest, resourceCapabilitiesToAbilitiesMap, submitHostDelegation, validateClientSession, validateManifest, validatePersistedSessionData };