@tinycloud/node-sdk 3.1.0-beta.1 → 3.1.0-beta.11

package/dist/{core-Bm76PnOz.d.cts → core-CJiLya1s.d.cts}

@@ -758,6 +758,17 @@ interface PortableDelegation extends Omit<Delegation, "isRevoked"> {
      * fields are authoritative (legacy single-resource shape).
      */
     resources?: DelegatedResource[];
+    /**
+     * The wallet-signed SIWE message and EIP-191 signature behind a
+     * `delegationHeader` that is a CACAO session grant (OpenKey `/delegate`,
+     * {@link TinyCloudNode.grantRuntimePermissions}) rather than a compact UCAN.
+     * Not authority: activation rebuilds the CACAO from them and accepts only
+     * byte-identical authorization bytes.
+     */
+    siweProof?: {
+        siwe: string;
+        signature: string;
+    };
 }
 /**
  * The transport shape `tc auth request --emit` produces and that an owner
@@ -819,6 +830,11 @@ interface RuntimeDelegationActivator {
     useRuntimeDelegation(delegation: PortableDelegation): Promise<void>;
     useDelegation?(delegation: PortableDelegation): Promise<unknown>;
     getRuntimePermissionDelegations(): PortableDelegation[];
+    /**
+     * Verify a wallet-signed session grant issued to this runtime's live session
+     * key. Required to activate a CACAO grant; compact UCANs do not use it.
+     */
+    verifySessionGrant?(grant: SessionGrantProof): VerifiedSessionGrant;
 }
 /** The installed authority returned by {@link activateValidatedRuntimeDelegation}. */
 interface ValidatedRuntimeDelegation {
@@ -842,16 +858,59 @@ interface CompactRuntimeDelegationInput {
     readonly ownerAddress: string;
     readonly chainId: number;
 }
+/** A CACAO session grant and the signed SIWE proof it was built from. */
+interface SessionGrantProof {
+    readonly delegationHeader: {
+        Authorization: string;
+    };
+    readonly delegationCid: string;
+    readonly spaceId: string;
+    readonly address: string;
+    readonly chainId: number;
+    readonly siwe: string;
+    readonly signature: string;
+}
+/** Authority read from a verified session grant's signed ReCap. */
+interface VerifiedSessionGrant {
+    readonly recap: readonly {
+        service: string;
+        space: string;
+        path: string;
+        actions: string[];
+        caveats?: Record<string, unknown>[];
+    }[];
+    readonly expiresAt: Date;
+}
+/**
+ * Stable reasons {@link activateValidatedRuntimeDelegation} refuses a
+ * delegation for. The error message is for the caller and may quote
+ * transport fields or a node's response; the reason is safe to publish.
+ */
+declare const RUNTIME_DELEGATION_REJECTIONS: readonly ["host_mismatch", "expired", "cid_mismatch", "authority_invalid", "proof_missing", "proof_invalid", "owner_mismatch", "audience_mismatch", "resources_mismatch", "unsupported", "activation_rejected"];
+type RuntimeDelegationRejection = typeof RUNTIME_DELEGATION_REJECTIONS[number];
+declare class RuntimeDelegationRejectedError extends Error {
+    readonly reason: RuntimeDelegationRejection;
+    constructor(reason: RuntimeDelegationRejection, message: string);
+}
 /**
- * CID-bind and activate one compact runtime delegation.
+ * CID-bind and activate one runtime delegation.
+ *
+ * A compact UCAN's audience, expiry and permissions come from its signed
+ * payload, and its transport fields must agree with them. A CACAO session
+ * grant (OpenKey `/delegate`, `grantRuntimePermissions`) is verified from its
+ * `siweProof` against this runtime's live session key; its installed
+ * authority is exactly the verified ReCap, and its transport `resources` are
+ * display data that is never consulted. Either way the helper then invokes
+ * {@link TinyCloudNode.useRuntimeDelegation}; the node activation call remains
+ * the authority and delegation-chain validation boundary.
  *
- * The helper derives audience, expiry, and effective permissions from the
- * compact UCAN's signed payload, verifies the transport fields agree, then
- * invokes {@link TinyCloudNode.useRuntimeDelegation}. The node activation call
- * remains the authority and delegation-chain validation boundary.
+ * `options.authorize`, when given, sees the signed capabilities before
+ * anything is activated or installed; returning `false` refuses the
+ * delegation.
  */
 declare function activateValidatedRuntimeDelegation(node: RuntimeDelegationActivator, delegation: PortableDelegation, options: {
     host: string;
+    authorize?: (effectivePermissions: readonly PermissionEntry[]) => boolean;
 }): Promise<ValidatedRuntimeDelegation>;
 /**
  * Import compact UCAN bytes returned by an authority ceremony through the
@@ -1445,6 +1504,9 @@ declare class TinyCloudNode {
     private resolveBootstrapDecision;
     private readBootstrapCompletionMarker;
     private writeBootstrapCompletionMarker;
+    /**
+     * A marker written before a canonical space was added triggers one bounded repair.
+     */
     private isAcceptedBootstrapCompletionMarker;
     private markerReadIsUnhostedSpace;
     private runAccountBootstrap;
@@ -1966,6 +2028,18 @@ declare class TinyCloudNode {
      * live authority must combine this with {@link getVerifiedSessionCapabilities}.
      */
     getEffectiveRuntimePermissionEntries(): PermissionEntry[];
+    /**
+     * Verify a wallet-signed session grant (a CACAO built from a SIWE and its
+     * EIP-191 signature) issued to this instance's live session key. The
+     * verifier rebuilds the CACAO from `siwe` and `signature`, so the grant is
+     * accepted only when its authorization bytes and CID are exactly that CACAO,
+     * its signer is `address`, its audience is this session key, it is valid
+     * now, and its ReCap covers `spaceId` or names only raw encryption networks
+     * (a decrypt-only grant has no space). Returns the signed ReCap and expiry.
+     * Bindings without `validateSessionGrant` fall back to the session verifier,
+     * which also refuses decrypt-only grants.
+     */
+    verifySessionGrant(grant: SessionGrantProof): VerifiedSessionGrant;
     /**
      * Install a portable runtime permission delegation into this SDK instance so
      * matching service calls and downstream `delegateTo()` calls can use it.
@@ -2474,4 +2548,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 declare function createWasmKeyProvider(sessionManager: SessionManagerWithListing): WasmKeyProvider;
 
-export { ACCEPTED_MARKER_VERSIONS as A, BOOTSTRAP_COMPLETION_MARKER_KEY as B, type CompactRuntimeDelegationInput as C, type DelegateToOptions as D, type EnsureEncryptionNetworkOptions as E, FileSessionStorage as F, serializeDelegation as G, InvalidRestoredSessionError as I, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type OwnerDelegationReceipt as O, type PortableDelegation as P, type RestorableSession as R, type SecretPermissionHint as S, TinyCloudNode as T, type UnifiedOwnerRootInput as U, type ValidatedRuntimeDelegation as V, WasmKeyProvider as W, type AuthDelegationArtifact as a, type AuthRequestArtifact as b, BOOTSTRAP_COMPLETION_MARKER_VERSION as c, type BootstrapCompletionMarker as d, type BootstrapWarning as e, type CreateOwnerDelegationParams as f, type DelegateToResult as g, DelegatedAccess as h, type DelegationAuthority as i, NodeUserAuthorization as j, type NodeUserAuthorizationConfig as k, type RuntimeDelegationActivator as l, type RuntimePermissionGrantOptions as m, type SecretReadInput as n, type SecretReadResult as o, type SignStrategy as p, type TinyCloudNodeConfig as q, type UnifiedOwnerRootReceipt as r, UnsupportedSessionRestoreError as s, type WasmKeyProviderConfig as t, activateCompactRuntimeDelegation as u, activateValidatedRuntimeDelegation as v, createWasmKeyProvider as w, defaultSignStrategy as x, deserializeDelegation as y, grantAuthRequest as z };
+export { ACCEPTED_MARKER_VERSIONS as A, BOOTSTRAP_COMPLETION_MARKER_KEY as B, type CompactRuntimeDelegationInput as C, type DelegateToOptions as D, type EnsureEncryptionNetworkOptions as E, FileSessionStorage as F, activateValidatedRuntimeDelegation as G, createWasmKeyProvider as H, InvalidRestoredSessionError as I, defaultSignStrategy as J, deserializeDelegation as K, grantAuthRequest as L, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type OwnerDelegationReceipt as O, type PortableDelegation as P, serializeDelegation as Q, RUNTIME_DELEGATION_REJECTIONS as R, type SecretPermissionHint as S, TinyCloudNode as T, type UnifiedOwnerRootInput as U, type ValidatedRuntimeDelegation as V, WasmKeyProvider as W, type AuthDelegationArtifact as a, type AuthRequestArtifact as b, BOOTSTRAP_COMPLETION_MARKER_VERSION as c, type BootstrapCompletionMarker as d, type BootstrapWarning as e, type CreateOwnerDelegationParams as f, type DelegateToResult as g, DelegatedAccess as h, type DelegationAuthority as i, NodeUserAuthorization as j, type NodeUserAuthorizationConfig as k, type RestorableSession as l, type RuntimeDelegationActivator as m, RuntimeDelegationRejectedError as n, type RuntimeDelegationRejection as o, type RuntimePermissionGrantOptions as p, type SecretReadInput as q, type SecretReadResult as r, type SessionGrantProof as s, type SignStrategy as t, type TinyCloudNodeConfig as u, type UnifiedOwnerRootReceipt as v, UnsupportedSessionRestoreError as w, type VerifiedSessionGrant as x, type WasmKeyProviderConfig as y, activateCompactRuntimeDelegation as z };

package/dist/{core-Bm76PnOz.d.ts → core-CJiLya1s.d.ts}

@@ -758,6 +758,17 @@ interface PortableDelegation extends Omit<Delegation, "isRevoked"> {
      * fields are authoritative (legacy single-resource shape).
      */
     resources?: DelegatedResource[];
+    /**
+     * The wallet-signed SIWE message and EIP-191 signature behind a
+     * `delegationHeader` that is a CACAO session grant (OpenKey `/delegate`,
+     * {@link TinyCloudNode.grantRuntimePermissions}) rather than a compact UCAN.
+     * Not authority: activation rebuilds the CACAO from them and accepts only
+     * byte-identical authorization bytes.
+     */
+    siweProof?: {
+        siwe: string;
+        signature: string;
+    };
 }
 /**
  * The transport shape `tc auth request --emit` produces and that an owner
@@ -819,6 +830,11 @@ interface RuntimeDelegationActivator {
     useRuntimeDelegation(delegation: PortableDelegation): Promise<void>;
     useDelegation?(delegation: PortableDelegation): Promise<unknown>;
     getRuntimePermissionDelegations(): PortableDelegation[];
+    /**
+     * Verify a wallet-signed session grant issued to this runtime's live session
+     * key. Required to activate a CACAO grant; compact UCANs do not use it.
+     */
+    verifySessionGrant?(grant: SessionGrantProof): VerifiedSessionGrant;
 }
 /** The installed authority returned by {@link activateValidatedRuntimeDelegation}. */
 interface ValidatedRuntimeDelegation {
@@ -842,16 +858,59 @@ interface CompactRuntimeDelegationInput {
     readonly ownerAddress: string;
     readonly chainId: number;
 }
+/** A CACAO session grant and the signed SIWE proof it was built from. */
+interface SessionGrantProof {
+    readonly delegationHeader: {
+        Authorization: string;
+    };
+    readonly delegationCid: string;
+    readonly spaceId: string;
+    readonly address: string;
+    readonly chainId: number;
+    readonly siwe: string;
+    readonly signature: string;
+}
+/** Authority read from a verified session grant's signed ReCap. */
+interface VerifiedSessionGrant {
+    readonly recap: readonly {
+        service: string;
+        space: string;
+        path: string;
+        actions: string[];
+        caveats?: Record<string, unknown>[];
+    }[];
+    readonly expiresAt: Date;
+}
+/**
+ * Stable reasons {@link activateValidatedRuntimeDelegation} refuses a
+ * delegation for. The error message is for the caller and may quote
+ * transport fields or a node's response; the reason is safe to publish.
+ */
+declare const RUNTIME_DELEGATION_REJECTIONS: readonly ["host_mismatch", "expired", "cid_mismatch", "authority_invalid", "proof_missing", "proof_invalid", "owner_mismatch", "audience_mismatch", "resources_mismatch", "unsupported", "activation_rejected"];
+type RuntimeDelegationRejection = typeof RUNTIME_DELEGATION_REJECTIONS[number];
+declare class RuntimeDelegationRejectedError extends Error {
+    readonly reason: RuntimeDelegationRejection;
+    constructor(reason: RuntimeDelegationRejection, message: string);
+}
 /**
- * CID-bind and activate one compact runtime delegation.
+ * CID-bind and activate one runtime delegation.
+ *
+ * A compact UCAN's audience, expiry and permissions come from its signed
+ * payload, and its transport fields must agree with them. A CACAO session
+ * grant (OpenKey `/delegate`, `grantRuntimePermissions`) is verified from its
+ * `siweProof` against this runtime's live session key; its installed
+ * authority is exactly the verified ReCap, and its transport `resources` are
+ * display data that is never consulted. Either way the helper then invokes
+ * {@link TinyCloudNode.useRuntimeDelegation}; the node activation call remains
+ * the authority and delegation-chain validation boundary.
  *
- * The helper derives audience, expiry, and effective permissions from the
- * compact UCAN's signed payload, verifies the transport fields agree, then
- * invokes {@link TinyCloudNode.useRuntimeDelegation}. The node activation call
- * remains the authority and delegation-chain validation boundary.
+ * `options.authorize`, when given, sees the signed capabilities before
+ * anything is activated or installed; returning `false` refuses the
+ * delegation.
  */
 declare function activateValidatedRuntimeDelegation(node: RuntimeDelegationActivator, delegation: PortableDelegation, options: {
     host: string;
+    authorize?: (effectivePermissions: readonly PermissionEntry[]) => boolean;
 }): Promise<ValidatedRuntimeDelegation>;
 /**
  * Import compact UCAN bytes returned by an authority ceremony through the
@@ -1445,6 +1504,9 @@ declare class TinyCloudNode {
     private resolveBootstrapDecision;
     private readBootstrapCompletionMarker;
     private writeBootstrapCompletionMarker;
+    /**
+     * A marker written before a canonical space was added triggers one bounded repair.
+     */
     private isAcceptedBootstrapCompletionMarker;
     private markerReadIsUnhostedSpace;
     private runAccountBootstrap;
@@ -1966,6 +2028,18 @@ declare class TinyCloudNode {
      * live authority must combine this with {@link getVerifiedSessionCapabilities}.
      */
     getEffectiveRuntimePermissionEntries(): PermissionEntry[];
+    /**
+     * Verify a wallet-signed session grant (a CACAO built from a SIWE and its
+     * EIP-191 signature) issued to this instance's live session key. The
+     * verifier rebuilds the CACAO from `siwe` and `signature`, so the grant is
+     * accepted only when its authorization bytes and CID are exactly that CACAO,
+     * its signer is `address`, its audience is this session key, it is valid
+     * now, and its ReCap covers `spaceId` or names only raw encryption networks
+     * (a decrypt-only grant has no space). Returns the signed ReCap and expiry.
+     * Bindings without `validateSessionGrant` fall back to the session verifier,
+     * which also refuses decrypt-only grants.
+     */
+    verifySessionGrant(grant: SessionGrantProof): VerifiedSessionGrant;
     /**
      * Install a portable runtime permission delegation into this SDK instance so
      * matching service calls and downstream `delegateTo()` calls can use it.
@@ -2474,4 +2548,4 @@ declare class WasmKeyProvider implements KeyProvider {
  */
 declare function createWasmKeyProvider(sessionManager: SessionManagerWithListing): WasmKeyProvider;
 
-export { ACCEPTED_MARKER_VERSIONS as A, BOOTSTRAP_COMPLETION_MARKER_KEY as B, type CompactRuntimeDelegationInput as C, type DelegateToOptions as D, type EnsureEncryptionNetworkOptions as E, FileSessionStorage as F, serializeDelegation as G, InvalidRestoredSessionError as I, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type OwnerDelegationReceipt as O, type PortableDelegation as P, type RestorableSession as R, type SecretPermissionHint as S, TinyCloudNode as T, type UnifiedOwnerRootInput as U, type ValidatedRuntimeDelegation as V, WasmKeyProvider as W, type AuthDelegationArtifact as a, type AuthRequestArtifact as b, BOOTSTRAP_COMPLETION_MARKER_VERSION as c, type BootstrapCompletionMarker as d, type BootstrapWarning as e, type CreateOwnerDelegationParams as f, type DelegateToResult as g, DelegatedAccess as h, type DelegationAuthority as i, NodeUserAuthorization as j, type NodeUserAuthorizationConfig as k, type RuntimeDelegationActivator as l, type RuntimePermissionGrantOptions as m, type SecretReadInput as n, type SecretReadResult as o, type SignStrategy as p, type TinyCloudNodeConfig as q, type UnifiedOwnerRootReceipt as r, UnsupportedSessionRestoreError as s, type WasmKeyProviderConfig as t, activateCompactRuntimeDelegation as u, activateValidatedRuntimeDelegation as v, createWasmKeyProvider as w, defaultSignStrategy as x, deserializeDelegation as y, grantAuthRequest as z };
+export { ACCEPTED_MARKER_VERSIONS as A, BOOTSTRAP_COMPLETION_MARKER_KEY as B, type CompactRuntimeDelegationInput as C, type DelegateToOptions as D, type EnsureEncryptionNetworkOptions as E, FileSessionStorage as F, activateValidatedRuntimeDelegation as G, createWasmKeyProvider as H, InvalidRestoredSessionError as I, defaultSignStrategy as J, deserializeDelegation as K, grantAuthRequest as L, MemorySessionStorage as M, type NodeEventEmitterStrategy as N, type OwnerDelegationReceipt as O, type PortableDelegation as P, serializeDelegation as Q, RUNTIME_DELEGATION_REJECTIONS as R, type SecretPermissionHint as S, TinyCloudNode as T, type UnifiedOwnerRootInput as U, type ValidatedRuntimeDelegation as V, WasmKeyProvider as W, type AuthDelegationArtifact as a, type AuthRequestArtifact as b, BOOTSTRAP_COMPLETION_MARKER_VERSION as c, type BootstrapCompletionMarker as d, type BootstrapWarning as e, type CreateOwnerDelegationParams as f, type DelegateToResult as g, DelegatedAccess as h, type DelegationAuthority as i, NodeUserAuthorization as j, type NodeUserAuthorizationConfig as k, type RestorableSession as l, type RuntimeDelegationActivator as m, RuntimeDelegationRejectedError as n, type RuntimeDelegationRejection as o, type RuntimePermissionGrantOptions as p, type SecretReadInput as q, type SecretReadResult as r, type SessionGrantProof as s, type SignStrategy as t, type TinyCloudNodeConfig as u, type UnifiedOwnerRootReceipt as v, UnsupportedSessionRestoreError as w, type VerifiedSessionGrant as x, type WasmKeyProviderConfig as y, activateCompactRuntimeDelegation as z };