@tinycloudlabs/web-sdk 0.2.0 → 1.0.0

package/dist/modules/tcw.d.ts

@@ -1,27 +1,149 @@
-import { TCWRPCProviders, TCWEnsData } from '@tinycloudlabs/web-core';
-import { IUserAuthorization, TinyCloudStorage } from '.';
-import { TCWClientConfig, TCWClientSession, TCWExtension } from '@tinycloudlabs/web-core/client';
-import type { providers, Signer } from 'ethers';
+import { RPCProviders } from '@tinycloudlabs/web-core';
+import { IUserAuthorization } from '.';
+import { WebUserAuthorization, WebSignStrategy } from '../authorization';
+import { ClientConfig, ClientSession, Extension } from '@tinycloudlabs/web-core/client';
+import type { providers } from 'ethers';
 import type { NotificationConfig } from '../notifications/types';
-import { SiweMessage } from 'siwe';
+import { IKVService, ICapabilityKeyRegistry, DelegationManager, ISpaceService, ISpace, Delegation, Result, DelegationError, ISharingService, CreateDelegationParams, ISpaceCreationHandler } from '@tinycloudlabs/sdk-core';
+import { PortableDelegation, DelegatedAccess } from '../delegation';
 declare global {
     interface Window {
         ethereum?: any;
     }
 }
 /**
- * Configuration for managing TCW Modules
+ * Configuration for TinyCloudWeb.
+ *
+ * Extends ClientConfig with notification options and the new unified auth module.
+ *
+ * ## New Auth Module (1.0.0)
+ *
+ * Set `useNewAuth: true` to enable the new unified auth architecture with:
+ * - **SignStrategy pattern**: Control how sign requests are handled
+ * - **Session-only mode**: Receive delegations without a wallet
+ * - **`did` vs `sessionDid` model**: Clear identity distinction
+ * - **`connectWallet()` upgrade pattern**: Upgrade from session-only to full auth
+ *
+ * @example
+ * ```typescript
+ * // Legacy mode (default)
+ * const tcw = new TinyCloudWeb({
+ *   providers: { web3: { driver: window.ethereum } }
+ * });
+ *
+ * // New auth mode (recommended for new projects)
+ * const tcw = new TinyCloudWeb({
+ *   useNewAuth: true,
+ *   signStrategy: { type: 'wallet-popup' },
+ *   spaceCreationHandler: new ModalSpaceCreationHandler()
+ * });
+ *
+ * // Session-only mode (no wallet required)
+ * const tcw = new TinyCloudWeb({ useNewAuth: true });
+ * console.log(tcw.sessionDid); // did:key:z6Mk...
+ * ```
  */
-interface TCWModuleConfig {
-    storage?: boolean | {
-        [key: string]: any;
-    };
-}
-interface TCWConfig extends TCWClientConfig {
-    modules?: TCWModuleConfig;
+export interface Config extends ClientConfig {
+    /** Notification configuration for error popups and toasts */
     notifications?: NotificationConfig;
+    /** Optional prefix for KV service keys */
+    kvPrefix?: string;
+    /**
+     * Prefix for space names when creating spaces.
+     * @example 'myapp' results in spaces like 'myapp-default'
+     */
+    spacePrefix?: string;
+    /**
+     * TinyCloud server hosts.
+     * @default ['https://node.tinycloud.xyz']
+     */
+    tinycloudHosts?: string[];
+    /**
+     * Whether to auto-create space on sign-in if it doesn't exist.
+     * @default true
+     */
+    autoCreateSpace?: boolean;
+    /**
+     * Whether to use the new WebUserAuthorization class.
+     *
+     * When `true`, uses the new unified auth module architecture featuring:
+     * - SignStrategy pattern for controlling sign requests
+     * - Session-only mode (receive delegations without wallet)
+     * - Clear `did` vs `sessionDid` model
+     * - `connectWallet()` upgrade pattern
+     *
+     * When `false` (default), uses the legacy UserAuthorization for backward compatibility.
+     *
+     * **Recommended**: Set to `true` for new projects or when migrating to 1.0.0.
+     *
+     * @default false
+     */
+    useNewAuth?: boolean;
+    /**
+     * Sign strategy for handling sign requests.
+     *
+     * Only used when `useNewAuth: true`. Determines how SIWE signing is handled:
+     * - `'wallet-popup'` (default): Show browser wallet popup
+     * - `{ type: 'auto-sign' }`: Automatically sign (requires external signer setup)
+     * - `{ type: 'callback', handler: fn }`: Custom callback for sign requests
+     * - `{ type: 'event-emitter', emitter: ee }`: Emit events for external handling
+     *
+     * @example
+     * ```typescript
+     * // Default: wallet popup
+     * signStrategy: 'wallet-popup'
+     *
+     * // Custom callback for approval UI
+     * signStrategy: {
+     *   type: 'callback',
+     *   handler: async (req) => {
+     *     const approved = await showCustomApprovalDialog(req.message);
+     *     return { approved };
+     *   }
+     * }
+     * ```
+     */
+    signStrategy?: WebSignStrategy;
+    /**
+     * Handler for space creation confirmation.
+     *
+     * Only used when `useNewAuth: true`. Controls how space creation is confirmed:
+     * - `ModalSpaceCreationHandler` (default): Shows a modal dialog
+     * - `{ confirmSpaceCreation: async () => true }`: Auto-approve
+     * - Custom implementation of `ISpaceCreationHandler`
+     *
+     * @example
+     * ```typescript
+     * // Default: modal confirmation
+     * spaceCreationHandler: new ModalSpaceCreationHandler()
+     *
+     * // Auto-approve (no UI)
+     * spaceCreationHandler: { confirmSpaceCreation: async () => true }
+     *
+     * // Custom handler
+     * spaceCreationHandler: {
+     *   confirmSpaceCreation: async (context) => {
+     *     return await showCustomDialog(`Create space: ${context.spaceId}?`);
+     *   }
+     * }
+     * ```
+     */
+    spaceCreationHandler?: ISpaceCreationHandler;
+}
+/**
+ * Result of receiving a share link.
+ */
+export interface ShareReceiveResult<T = unknown> {
+    /** The retrieved data */
+    data: T;
+    /** The delegation that authorized access */
+    delegation: Delegation;
+    /** The path the share grants access to */
+    path: string;
+    /** The space ID */
+    spaceId: string;
 }
-/** TCW: TinyCloud Web SDK
+/** TinyCloud Web SDK
  *
  * An SDK for building user-controlled web apps.
  */
@@ -30,7 +152,36 @@ export declare class TinyCloudWeb {
     /** The Ethereum provider */
     provider: providers.Web3Provider;
     /** Supported RPC Providers */
-    static RPCProviders: typeof TCWRPCProviders;
+    static RPCProviders: typeof RPCProviders;
+    /**
+     * Receive and retrieve data from a v2 share link.
+     *
+     * This static method allows receiving shared data without being signed in.
+     * The share link contains an embedded private key and delegation that
+     * grants access to the shared resource.
+     *
+     * @param link - The share link (tc1:... format or full URL)
+     * @param key - Optional specific key to retrieve within the shared path
+     * @returns Result containing the data or an error
+     *
+     * @example
+     * ```typescript
+     * // Receive shared data using just the link
+     * const result = await TinyCloudWeb.receiveShare('tc1:...');
+     * if (result.ok) {
+     *   console.log('Data:', result.data.data);
+     *   console.log('Path:', result.data.path);
+     * } else {
+     *   console.error('Error:', result.error.message);
+     * }
+     *
+     * // Or from a full URL
+     * const result = await TinyCloudWeb.receiveShare(
+     *   'https://share.example.com/share/tc1:...'
+     * );
+     * ```
+     */
+    static receiveShare<T = unknown>(link: string, key?: string): Promise<Result<ShareReceiveResult<T>, DelegationError>>;
     /** UserAuthorization Module
      *
      * Handles the capabilities that a user can provide a app, specifically
@@ -40,22 +191,244 @@ export declare class TinyCloudWeb {
      * - session key management
      * - creates, manages, and handles session data
      * - manages/provides capabilities
+     *
+     * NOTE: When useNewAuth is true, this is a WebUserAuthorization instance.
+     * The type is `any` to allow both legacy and new auth modules.
+     * Use `webAuth` getter for typed access to WebUserAuthorization.
      */
-    userAuthorization: IUserAuthorization;
-    /** Storage Module */
-    storage: TinyCloudStorage;
+    userAuthorization: IUserAuthorization | WebUserAuthorization;
     /** Error Handler for Notifications */
     private errorHandler;
-    constructor(config?: TCWConfig);
+    /** Service Context for sdk-services */
+    private _serviceContext?;
+    /** KV Service instance */
+    private _kvService?;
+    /** Capability Key Registry for automatic key selection */
+    private _capabilityRegistry?;
+    /** Delegation Manager for CRUD operations on delegations */
+    private _delegationManager?;
+    /** Space Service for managing spaces */
+    private _spaceService?;
+    /** KeyProvider for SharingService */
+    private _keyProvider?;
+    /** SharingService for generating/receiving share links */
+    private _sharingService?;
+    constructor(config?: Config);
+    /**
+     * Create a WebUserAuthorization instance from the config.
+     * Maps legacy config options to new WebUserAuthorizationConfig.
+     * @private
+     */
+    private createWebUserAuthorization;
+    /**
+     * Get the KV service.
+     *
+     * Returns the new sdk-services KVService with Result pattern.
+     * Must be signed in for the service to be available.
+     *
+     * @throws Error if not signed in
+     *
+     * @example
+     * ```typescript
+     * const result = await tcw.kv.get('key');
+     * if (result.ok) {
+     *   console.log(result.data.data);
+     * } else {
+     *   console.error(result.error.code, result.error.message);
+     * }
+     * ```
+     */
+    get kv(): IKVService;
+    /**
+     * Get the KV prefix configured for this instance.
+     */
+    get kvPrefix(): string;
+    /**
+     * Get the capability key registry for automatic key selection.
+     * This registry tracks keys and their associated delegations,
+     * enabling automatic selection of the best key for operations.
+     *
+     * Must be signed in for the registry to be available.
+     *
+     * @throws Error if not signed in
+     *
+     * @example
+     * ```typescript
+     * // Get the best key for an operation
+     * const key = tcw.capabilityRegistry.getKeyForCapability(
+     *   'tinycloud://my-space/kv/data',
+     *   'tinycloud.kv/get'
+     * );
+     *
+     * // List all capabilities
+     * const capabilities = tcw.capabilityRegistry.getAllCapabilities();
+     * ```
+     */
+    get capabilityRegistry(): ICapabilityKeyRegistry;
+    /**
+     * Get the delegation manager for CRUD operations on delegations.
+     * Handles creating, revoking, listing, and querying delegations.
+     *
+     * Must be signed in for the manager to be available.
+     *
+     * @throws Error if not signed in
+     *
+     * @example
+     * ```typescript
+     * // Create a delegation
+     * const result = await tcw.delegations.create({
+     *   delegateDID: 'did:pkh:eip155:1:0x...',
+     *   path: 'shared/',
+     *   actions: ['tinycloud.kv/get', 'tinycloud.kv/list'],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000),
+     * });
+     *
+     * // List all delegations
+     * const listResult = await tcw.delegations.list();
+     *
+     * // Revoke a delegation
+     * await tcw.delegations.revoke('bafy...');
+     * ```
+     */
+    get delegations(): DelegationManager;
     /**
-     * Extends TCW with a functions that are called after connecting and signing in.
+     * Get the space service for managing spaces (owned and delegated).
+     * Provides listing, creation, and access to space-scoped operations.
+     *
+     * Must be signed in for the service to be available.
+     *
+     * @throws Error if not signed in
+     *
+     * @example
+     * ```typescript
+     * // List all accessible spaces
+     * const result = await tcw.spaces.list();
+     * if (result.ok) {
+     *   for (const space of result.data) {
+     *     console.log(`${space.name} (${space.type})`);
+     *   }
+     * }
+     *
+     * // Create a new space
+     * const createResult = await tcw.spaces.create('photos');
+     *
+     * // Get a space object for operations
+     * const space = tcw.spaces.get('photos');
+     * await space.kv.put('album/vacation', { photos: [...] });
+     * ```
+     */
+    get spaces(): ISpaceService;
+    /**
+     * Get a specific space by name or URI.
+     * Shorthand for `tcw.spaces.get(nameOrUri)`.
+     *
+     * Must be signed in for the service to be available.
+     *
+     * @param nameOrUri - Short name or full space URI
+     * @returns Space object with scoped operations
+     * @throws Error if not signed in
+     *
+     * @example
+     * ```typescript
+     * // Get an owned space by short name
+     * const photos = tcw.space('photos');
+     * await photos.kv.put('vacation/photo1.jpg', imageData);
+     *
+     * // Get a delegated space by full URI
+     * const shared = tcw.space('tinycloud:pkh:eip155:1:0x...:shared');
+     * const data = await shared.kv.get('document.json');
+     * ```
+     */
+    space(nameOrUri: string): ISpace;
+    /**
+     * Get the sharing service for generating and managing share links.
+     * Provides v2 sharing links with embedded private keys.
+     *
+     * Must be signed in for the service to be available.
+     *
+     * @throws Error if not signed in
+     *
+     * @example
+     * ```typescript
+     * // Generate a sharing link for a key
+     * const result = await tcw.sharing.generate({
+     *   path: 'shared/document.json',
+     *   actions: ['tinycloud.kv/get'],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000),
+     * });
+     * if (result.ok) {
+     *   console.log('Share link:', result.data.link);
+     * }
+     *
+     * // Receive a share (static method, no auth needed)
+     * const shareResult = await TinyCloudWeb.receiveShare('tc1:...');
+     * ```
+     */
+    get sharing(): ISharingService;
+    /**
+     * Initialize the sdk-services KVService and other services.
+     * Called internally after sign-in when the session is established.
+     *
+     * @internal
      */
-    extend(extension: TCWExtension): void;
+    private initializeKVService;
+    /**
+     * Initialize the delegation system services.
+     * Called internally after sign-in when the session is established.
+     *
+     * @param hosts - TinyCloud host URLs
+     * @param serviceSession - The service session
+     * @internal
+     */
+    private initializeDelegationServices;
+    /**
+     * Create a delegation for sharing using the WASM /delegate endpoint.
+     * @internal
+     */
+    private createDelegationForSharing;
+    /**
+     * Wrapper for the WASM createDelegation function.
+     * Adapts the WASM interface to what SharingService expects.
+     * @internal
+     */
+    private createDelegationWrapper;
+    /**
+     * Get the session expiry time.
+     * @internal
+     */
+    private getSessionExpiry;
+    /**
+     * Create a delegation using SIWE-based flow.
+     * This method implements the correct delegation creation pattern:
+     * 1. Use prepareSession() to build the delegation
+     * 2. Sign the SIWE message with the user's wallet
+     * 3. Use completeSessionSetup() to get the delegation header
+     * 4. Activate the delegation with the server
+     *
+     * @param params - Delegation parameters including spaceId
+     * @param session - The TinyCloud session
+     * @param address - User's address
+     * @param chainId - Chain ID
+     * @param hosts - TinyCloud host URLs
+     * @returns Result containing the created Delegation or an error
+     * @internal
+     */
+    private createDelegationWithSIWE;
+    /**
+     * Convert TinyCloud session to ServiceSession.
+     * Gets session from UserAuthorization.
+     * @internal
+     */
+    private toServiceSession;
+    /**
+     * Extends TinyCloudWeb with functions that are called after connecting and signing in.
+     */
+    extend(extension: Extension): void;
     /**
      * Request the user to sign in, and start the session.
      * @returns Object containing information about the session
      */
-    signIn: () => Promise<TCWClientSession>;
+    signIn: () => Promise<ClientSession>;
     /**
      * Invalidates user's session.
      */
@@ -65,20 +438,11 @@ export declare class TinyCloudWeb {
      * Should be called when the SDK is no longer needed.
      */
     cleanup(): void;
-    /**
-     * ENS data supported by TCW.
-     * @param address - User address.
-     * @param resolveEnsOpts - Options to resolve ENS.
-     * @returns Object containing ENS data.
-     */
-    resolveEns(
-    /** User address */
-    address: string): Promise<TCWEnsData>;
     /**
      * Gets the session representation (once signed in).
-     * @returns Address.
+     * @returns Session object.
      */
-    session: () => TCWClientSession | undefined;
+    session: () => ClientSession | undefined;
     /**
      * Gets the address that is connected and signed in.
      * @returns Address.
@@ -90,33 +454,265 @@ export declare class TinyCloudWeb {
      */
     chainId: () => number | undefined;
     /**
-     * Gets the provider that is connected and signed in.
-     * @returns Provider.
+     * Check if the new auth module is being used.
+     * @returns true if using WebUserAuthorization, false if using legacy UserAuthorization
      */
-    getProvider(): providers.Web3Provider | undefined;
+    get isNewAuthEnabled(): boolean;
     /**
-     * Returns the signer of the connected address.
-     * @returns ethers.Signer
-     * @see https://docs.ethers.io/v5/api/signer/#Signer
+     * Get the WebUserAuthorization instance (new auth module only).
+     * Throws if not using new auth module.
+     *
+     * @throws Error if useNewAuth is false
      */
-    getSigner(): Signer;
+    get webAuth(): WebUserAuthorization;
     /**
-     * Generates a SIWE message for authentication with session key capabilities.
-     * This method delegates to the UserAuthorization module.
+     * Get the primary DID for this user (new auth module only).
+     *
+     * - If wallet connected and signed in: returns PKH DID (persistent identity)
+     * - If session-only mode: returns session key DID (ephemeral)
      *
-     * @param address - Ethereum address performing the signing
-     * @param partialSiweMessage - Optional partial SIWE message to override defaults
-     * @returns SiweMessage object ready for signing
+     * @throws Error if useNewAuth is false
      */
-    generateSiweMessage(address: string, partialSiweMessage?: Partial<SiweMessage>): Promise<SiweMessage>;
+    get did(): string;
     /**
-     * Sign in using a pre-signed SIWE message.
-     * This method delegates to the UserAuthorization module.
-     * @param siweMessage - The SIWE message that was generated
-     * @param signature - The signature of the SIWE message
-     * @returns Object containing information about the session
+     * Get the session key DID (new auth module only).
+     * Always available, even before sign-in.
+     *
+     * Format: `did:key:z6Mk...#z6Mk...`
+     *
+     * @throws Error if useNewAuth is false
+     */
+    get sessionDid(): string;
+    /**
+     * Check if in session-only mode (new auth module only).
+     * Session-only mode means no wallet is connected, but delegations can be received.
+     *
+     * @throws Error if useNewAuth is false
+     */
+    get isSessionOnly(): boolean;
+    /**
+     * Check if a wallet is connected (new auth module only).
+     * Wallet may be connected but not signed in.
+     *
+     * @throws Error if useNewAuth is false
+     */
+    get isWalletConnected(): boolean;
+    /**
+     * Connect a wallet to upgrade from session-only mode (new auth module only).
+     *
+     * This allows users who started in session-only mode (e.g., received
+     * delegations) to later connect a wallet and create their own space.
+     *
+     * @param provider - Web3 provider (e.g., window.ethereum)
+     * @param options - Optional configuration
+     *
+     * @throws Error if useNewAuth is false
+     *
+     * @example
+     * ```typescript
+     * // Create in session-only mode
+     * const tcw = new TinyCloudWeb({ useNewAuth: true });
+     * console.log(tcw.isSessionOnly); // true
+     *
+     * // User clicks "Connect Wallet"
+     * tcw.connectWallet(window.ethereum);
+     * console.log(tcw.isSessionOnly); // false
+     *
+     * // Now can sign in
+     * await tcw.signIn();
+     * ```
+     */
+    connectWallet(provider: providers.ExternalProvider | providers.Web3Provider, options?: {
+        spacePrefix?: string;
+    }): void;
+    /**
+     * Use a delegation received from another user.
+     *
+     * This creates a session that chains from the received delegation,
+     * allowing operations on the delegator's space.
+     *
+     * Works in both modes:
+     * - **Session-only mode**: Uses the delegation directly (must target session key DID)
+     * - **Wallet mode**: Creates a SIWE sub-delegation from PKH to session key
+     *
+     * @param delegation - The PortableDelegation to use (from createDelegation or transport)
+     * @returns A DelegatedAccess instance for performing operations
+     *
+     * @throws Error if useNewAuth is false (legacy auth not supported)
+     * @throws Error if in session-only mode and delegation doesn't target this user's DID
+     * @throws Error if in wallet mode and not signed in
+     *
+     * @example
+     * ```typescript
+     * // Session-only mode (most common for receiving delegations)
+     * const tcw = new TinyCloudWeb({ useNewAuth: true });
+     * const delegation = deserializeDelegation(receivedData);
+     *
+     * // The delegation must target tcw.did (session key DID in session-only mode)
+     * const access = await tcw.useDelegation(delegation);
+     *
+     * // Perform KV operations on the delegated space
+     * const data = await access.kv.get("shared/document.json");
+     * await access.kv.put("shared/notes.txt", "Hello!");
+     *
+     * // Wallet mode (signed in user receiving delegation)
+     * const tcw = new TinyCloudWeb({ useNewAuth: true, providers: { web3: { driver: window.ethereum } } });
+     * await tcw.signIn();
+     *
+     * // The delegation should target tcw.did (PKH DID when signed in)
+     * const access = await tcw.useDelegation(delegation);
+     * ```
+     */
+    useDelegation(delegation: PortableDelegation): Promise<DelegatedAccess>;
+    /**
+     * Convenience method to create a delegation via the delegation manager.
+     * For creating PortableDelegations, use createDelegation() instead.
+     *
+     * @param params - Delegation parameters
+     * @returns Result containing the created Delegation or an error
+     *
+     * @example
+     * ```typescript
+     * const result = await tcw.delegate({
+     *   delegateDID: 'did:pkh:eip155:1:0x...',
+     *   path: 'shared/',
+     *   actions: ['tinycloud.kv/get', 'tinycloud.kv/put'],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000),
+     * });
+     *
+     * if (result.ok) {
+     *   console.log('Delegation created:', result.data.cid);
+     * }
+     * ```
+     */
+    delegate(params: CreateDelegationParams): Promise<Result<Delegation, DelegationError>>;
+    /**
+     * Revoke a delegation by CID.
+     *
+     * @param cid - The CID of the delegation to revoke
+     * @returns Result indicating success or failure
+     *
+     * @example
+     * ```typescript
+     * const result = await tcw.revokeDelegation('bafy...');
+     * if (result.ok) {
+     *   console.log('Delegation revoked');
+     * }
+     * ```
+     */
+    revokeDelegation(cid: string): Promise<Result<void, DelegationError>>;
+    /**
+     * List all delegations for the current space.
+     *
+     * @returns Result containing an array of Delegations
+     *
+     * @example
+     * ```typescript
+     * const result = await tcw.listDelegations();
+     * if (result.ok) {
+     *   console.log('Delegations:', result.data.length);
+     * }
+     * ```
+     */
+    listDelegations(): Promise<Result<Delegation[], DelegationError>>;
+    /**
+     * Check if the current session has permission for a path and action.
+     *
+     * @param path - The resource path to check
+     * @param action - The action to check (e.g., 'tinycloud.kv/get')
+     * @returns Result containing boolean permission status
+     *
+     * @example
+     * ```typescript
+     * const result = await tcw.checkPermission('shared/docs', 'tinycloud.kv/get');
+     * if (result.ok && result.data) {
+     *   console.log('Permission granted');
+     * }
+     * ```
+     */
+    checkPermission(path: string, action: string): Promise<Result<boolean, DelegationError>>;
+    /**
+     * Create a delegation to grant access to another user.
+     * Returns a PortableDelegation that can be serialized and sent to the recipient.
+     *
+     * @param params - Delegation parameters
+     * @returns A portable delegation that can be sent to the recipient
+     *
+     * @throws Error if not signed in
+     * @throws Error if using legacy auth mode (requires useNewAuth: true)
+     *
+     * @example
+     * ```typescript
+     * const delegation = await tcw.createDelegation({
+     *   path: "shared/",
+     *   actions: ["tinycloud.kv/get", "tinycloud.kv/list"],
+     *   delegateDID: recipientDid,
+     *   expiryMs: 7 * 24 * 60 * 60 * 1000, // 7 days
+     * });
+     *
+     * // Send to recipient
+     * const token = serializeDelegation(delegation);
+     * ```
+     */
+    createDelegation(params: {
+        /** Path within the space to delegate access to */
+        path: string;
+        /** Actions to allow (e.g., ["tinycloud.kv/get", "tinycloud.kv/put"]) */
+        actions: string[];
+        /** DID of the recipient (from their TinyCloudWeb.did) */
+        delegateDID: string;
+        /** Whether to prevent the recipient from creating sub-delegations (default: false) */
+        disableSubDelegation?: boolean;
+        /** Expiration time in milliseconds from now (default: 1 hour) */
+        expiryMs?: number;
+    }): Promise<PortableDelegation>;
+    /**
+     * Track a received delegation in the capability registry.
+     * @private
+     */
+    private trackReceivedDelegation;
+    /**
+     * Create a sub-delegation from a received delegation.
+     * Allows chaining delegations (Alice -> Bob -> Carol).
+     *
+     * This allows further delegating access that was received from another user,
+     * if the original delegation allows sub-delegation.
+     *
+     * @param parentDelegation - The delegation received from another user
+     * @param params - Sub-delegation parameters (must be within parent's scope)
+     * @returns A portable delegation for the sub-delegate
+     *
+     * @throws Error if useNewAuth is false (legacy auth not supported)
+     * @throws Error if in session-only mode (requires wallet)
+     * @throws Error if not signed in
+     * @throws Error if parent delegation does not allow sub-delegation
+     * @throws Error if sub-delegation path is outside parent's path
+     * @throws Error if sub-delegation actions are not a subset of parent's actions
+     *
+     * @example
+     * ```typescript
+     * // Bob received a delegation from Alice
+     * const access = await tcw.useDelegation(aliceDelegation);
+     *
+     * // Bob creates sub-delegation for Carol
+     * const subDelegation = await tcw.createSubDelegation(aliceDelegation, {
+     *   path: "shared/subset/",
+     *   actions: ["tinycloud.kv/get"],
+     *   delegateDID: carolDid,
+     * });
+     * ```
      */
-    signInWithSignature(siweMessage: SiweMessage, signature: string): Promise<TCWClientSession>;
+    createSubDelegation(parentDelegation: PortableDelegation, params: {
+        /** Path within the delegated path to sub-delegate */
+        path: string;
+        /** Actions to allow (must be subset of parent's actions) */
+        actions: string[];
+        /** DID of the recipient */
+        delegateDID: string;
+        /** Whether to prevent the recipient from creating further sub-delegations */
+        disableSubDelegation?: boolean;
+        /** Expiration time in milliseconds from now (must be before parent's expiry) */
+        expiryMs?: number;
+    }): Promise<PortableDelegation>;
 }
-export {};
 //# sourceMappingURL=tcw.d.ts.map