@tinycloudlabs/node-sdk 1.0.0

package/dist/TinyCloudNode.d.ts

@@ -0,0 +1,441 @@
+/**
+ * TinyCloudNode - High-level API for Node.js users.
+ *
+ * Each user has their own TinyCloudNode instance with their own key.
+ * This class provides a simplified interface for:
+ * - Signing in and managing sessions
+ * - Key-value storage operations on own space
+ * - Creating and using delegations
+ *
+ * @example
+ * ```typescript
+ * const alice = new TinyCloudNode({
+ *   privateKey: process.env.ALICE_PRIVATE_KEY,
+ *   host: "https://node.tinycloud.xyz",
+ *   prefix: "myapp",
+ * });
+ *
+ * await alice.signIn();
+ * await alice.kv.put("greeting", "Hello, world!");
+ *
+ * // Delegate access to Bob
+ * const delegation = await alice.createDelegation({
+ *   path: "shared/",
+ *   actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
+ *   delegateDID: bob.did,
+ * });
+ *
+ * // Bob uses the delegation
+ * const access = await bob.useDelegation(delegation);
+ * const data = await access.kv.get("shared/data");
+ * ```
+ */
+import { TinyCloudSession, IKVService, DelegationManager, ISpaceService, ICapabilityKeyRegistry, ISharingService, Delegation, CreateDelegationParams, DelegationResult } from "@tinycloudlabs/sdk-core";
+import { PortableDelegation } from "./delegation";
+import { DelegatedAccess } from "./DelegatedAccess";
+/**
+ * Configuration for TinyCloudNode.
+ * All fields are optional - TinyCloudNode can work with zero configuration.
+ */
+export interface TinyCloudNodeConfig {
+    /** Hex-encoded private key (with or without 0x prefix). Optional - only needed for wallet mode and signIn() */
+    privateKey?: string;
+    /** TinyCloud server URL (default: "https://node.tinycloud.xyz") */
+    host?: string;
+    /** Space prefix for this user's space. Optional - only needed for signIn() */
+    prefix?: string;
+    /** Domain for SIWE messages (default: derived from host) */
+    domain?: string;
+    /** Session expiration time in milliseconds (default: 1 hour) */
+    sessionExpirationMs?: number;
+    /** Whether to automatically create space if it doesn't exist (default: false) */
+    autoCreateSpace?: boolean;
+}
+/**
+ * High-level TinyCloud API for Node.js environments.
+ *
+ * Each user creates their own TinyCloudNode instance with their private key.
+ * The instance manages the user's session and provides access to their space.
+ */
+export declare class TinyCloudNode {
+    /** Flag to ensure WASM panic hook is only initialized once */
+    private static wasmInitialized;
+    private config;
+    private signer;
+    private auth;
+    private tc;
+    private _address?;
+    private _chainId;
+    private sessionManager;
+    private _serviceContext?;
+    private _kv?;
+    /** Session key ID - always available */
+    private sessionKeyId;
+    /** Session key JWK as object - always available */
+    private sessionKeyJwk;
+    private _capabilityRegistry;
+    private _keyProvider;
+    private _sharingService;
+    private _delegationManager?;
+    private _spaceService?;
+    /**
+     * Create a new TinyCloudNode instance.
+     *
+     * All configuration is optional. Without a privateKey, the instance operates
+     * in "session-only" mode where it can receive delegations but cannot create
+     * its own space via signIn().
+     *
+     * @param config - Configuration options (all optional)
+     *
+     * @example
+     * ```typescript
+     * // Session-only mode - can receive delegations
+     * const bob = new TinyCloudNode();
+     * console.log(bob.did); // did:key:z6Mk... - available immediately
+     *
+     * // Wallet mode - can create own space
+     * const alice = new TinyCloudNode({
+     *   privateKey: process.env.ALICE_PRIVATE_KEY,
+     *   prefix: "myapp",
+     * });
+     * await alice.signIn();
+     * ```
+     */
+    constructor(config?: TinyCloudNodeConfig);
+    /**
+     * Get the primary identity DID for this user.
+     * - If wallet connected and signed in: returns PKH DID (did:pkh:eip155:{chainId}:{address})
+     * - If session-only mode: returns session key DID (did:key:z6Mk...)
+     *
+     * Use this for delegations - it always returns the appropriate identity.
+     */
+    get did(): string;
+    /**
+     * Get the session key DID. Always available.
+     * Format: did:key:z6Mk...#z6Mk...
+     *
+     * Use this when you specifically need the session key, not the user identity.
+     */
+    get sessionDid(): string;
+    /**
+     * Get the Ethereum address for this user.
+     */
+    get address(): string | undefined;
+    /**
+     * Check if this instance is in session-only mode (no wallet).
+     * In session-only mode, the instance can receive delegations but cannot
+     * create its own space via signIn().
+     */
+    get isSessionOnly(): boolean;
+    /**
+     * Get the space ID for this user.
+     * Available after signIn().
+     */
+    get spaceId(): string | undefined;
+    /**
+     * Get the current TinyCloud session.
+     * Available after signIn().
+     */
+    get session(): TinyCloudSession | undefined;
+    /**
+     * Sign in and create a new session.
+     * This creates the user's space if it doesn't exist.
+     * Requires wallet mode (privateKey in config).
+     */
+    signIn(): Promise<void>;
+    /**
+     * Connect a wallet to upgrade from session-only mode to wallet mode.
+     *
+     * This allows a user who started in session-only mode to later connect
+     * a wallet and gain the ability to create their own space.
+     *
+     * Note: This does NOT automatically sign in. Call signIn() after connecting
+     * the wallet to create your space.
+     *
+     * @param privateKey - The Ethereum private key (hex string, no 0x prefix)
+     * @param options - Optional configuration
+     * @param options.prefix - Space name prefix (defaults to "default")
+     *
+     * @example
+     * ```typescript
+     * // Start in session-only mode
+     * const node = new TinyCloudNode({ host: "https://node.tinycloud.xyz" });
+     * console.log(node.did); // did:key:z6Mk... (session key)
+     *
+     * // Later, connect a wallet
+     * node.connectWallet(privateKey);
+     * await node.signIn();
+     * console.log(node.did); // did:pkh:eip155:1:0x... (PKH)
+     * ```
+     */
+    connectWallet(privateKey: string, options?: {
+        prefix?: string;
+    }): void;
+    /**
+     * Initialize the service context and KV service after sign-in.
+     * @internal
+     */
+    private initializeServices;
+    /**
+     * Initialize the v2 delegation system services.
+     * @internal
+     */
+    private initializeV2Services;
+    /**
+     * Get the session expiry time.
+     * @internal
+     */
+    private getSessionExpiry;
+    /**
+     * Wrapper for the WASM createDelegation function.
+     * Adapts the WASM interface to what SharingService expects.
+     * @internal
+     */
+    private createDelegationWrapper;
+    /**
+     * Track a received delegation in the capability registry.
+     * @internal
+     */
+    private trackReceivedDelegation;
+    /**
+     * Key-value storage operations on this user's space.
+     */
+    get kv(): IKVService;
+    /**
+     * Get the CapabilityKeyRegistry for managing keys and their capabilities.
+     *
+     * The registry tracks keys (session, main, ingested) and their associated
+     * delegations, enabling automatic key selection for operations.
+     *
+     * @example
+     * ```typescript
+     * const registry = alice.capabilityRegistry;
+     *
+     * // Get the best key for an operation
+     * const key = registry.getKeyForCapability(
+     *   "tinycloud://my-space/kv/data",
+     *   "tinycloud.kv/get"
+     * );
+     *
+     * // List all capabilities
+     * const capabilities = registry.getAllCapabilities();
+     * ```
+     */
+    get capabilityRegistry(): ICapabilityKeyRegistry;
+    /**
+     * Access received delegations (recipient view).
+     *
+     * Use this to see what delegations have been received via useDelegation().
+     *
+     * @example
+     * ```typescript
+     * // List all received delegations
+     * const received = bob.delegations.list();
+     * console.log("I have access to:", received.length, "spaces");
+     *
+     * // Get a specific delegation by CID
+     * const delegation = bob.delegations.get(cid);
+     * ```
+     */
+    get delegations(): {
+        /** List all received delegations */
+        list: () => Delegation[];
+        /** Get a delegation by CID */
+        get: (cid: string) => Delegation | undefined;
+    };
+    /**
+     * Get the DelegationManager for delegation CRUD operations.
+     *
+     * This is the v2 delegation service providing a cleaner API than
+     * the legacy createDelegation/useDelegation methods.
+     *
+     * @example
+     * ```typescript
+     * const delegations = alice.delegationManager;
+     *
+     * // Create a delegation
+     * const result = await delegations.create({
+     *   delegateDID: bob.did,
+     *   path: "shared/",
+     *   actions: ["tinycloud.kv/get", "tinycloud.kv/put"],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours
+     * });
+     *
+     * // List delegations
+     * const listResult = await delegations.list();
+     *
+     * // Revoke a delegation
+     * await delegations.revoke(delegationCid);
+     * ```
+     */
+    get delegationManager(): DelegationManager;
+    /**
+     * Get the SpaceService for managing spaces.
+     *
+     * The SpaceService provides access to owned and delegated spaces,
+     * including space creation, listing, and scoped operations.
+     *
+     * @example
+     * ```typescript
+     * const spaces = alice.spaces;
+     *
+     * // List all accessible spaces
+     * const result = await spaces.list();
+     *
+     * // Create a new space
+     * const createResult = await spaces.create('photos');
+     *
+     * // Get a space object for operations
+     * const mySpace = spaces.get('default');
+     * await mySpace.kv.put('key', 'value');
+     *
+     * // Check if a space exists
+     * const exists = await spaces.exists('photos');
+     * ```
+     */
+    get spaces(): ISpaceService;
+    /**
+     * Alias for `spaces` - get the SpaceService.
+     * @see spaces
+     */
+    get spaceService(): ISpaceService;
+    /**
+     * Get the SharingService for creating and receiving v2 sharing links.
+     *
+     * The SharingService creates sharing links with embedded private keys,
+     * allowing recipients to exercise delegations without prior session setup.
+     *
+     * @example
+     * ```typescript
+     * const sharing = alice.sharing;
+     *
+     * // Generate a sharing link
+     * const result = await sharing.generate({
+     *   path: "/kv/documents/report.pdf",
+     *   actions: ["tinycloud.kv/get"],
+     *   expiry: new Date(Date.now() + 24 * 60 * 60 * 1000),
+     * });
+     *
+     * if (result.ok) {
+     *   console.log("Share URL:", result.data.url);
+     *   // Send the URL to the recipient
+     * }
+     *
+     * // Receive a sharing link
+     * const receiveResult = await sharing.receive(shareUrl);
+     * if (receiveResult.ok) {
+     *   // Use the pre-configured KV service
+     *   const data = await receiveResult.data.kv.get("report.pdf");
+     * }
+     * ```
+     */
+    get sharing(): ISharingService;
+    /**
+     * Alias for `sharing` - get the SharingService.
+     * @see sharing
+     */
+    get sharingService(): ISharingService;
+    /**
+     * Create a delegation using the v2 DelegationManager.
+     *
+     * This is a convenience method that wraps DelegationManager.create().
+     * For more control, use `this.delegationManager` directly.
+     *
+     * @param params - Delegation parameters
+     * @returns Result containing the created Delegation
+     *
+     * @example
+     * ```typescript
+     * const result = await alice.delegate({
+     *   delegateDID: bob.did,
+     *   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<DelegationResult<Delegation>>;
+    /**
+     * Revoke a delegation using the v2 DelegationManager.
+     *
+     * @param cid - The CID of the delegation to revoke
+     * @returns Result indicating success or failure
+     */
+    revokeDelegation(cid: string): Promise<DelegationResult<void>>;
+    /**
+     * List all delegations for the current session's space.
+     *
+     * @returns Result containing an array of Delegations
+     */
+    listDelegations(): Promise<DelegationResult<Delegation[]>>;
+    /**
+     * 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
+     */
+    checkPermission(path: string, action: string): Promise<DelegationResult<boolean>>;
+    /**
+     * Create a delegation from this user to another user.
+     *
+     * The delegation grants the recipient access to a specific path and actions
+     * within this user's space.
+     *
+     * @param params - Delegation parameters
+     * @returns A portable delegation that can be sent to the recipient
+     */
+    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 TinyCloudNode.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>;
+    /**
+     * Use a delegation received from another user.
+     *
+     * This creates a new session key for this user that chains from the
+     * received delegation, allowing operations on the delegator's space.
+     *
+     * Works in both modes:
+     * - **Wallet mode**: Creates a SIWE sub-delegation from PKH to session key
+     * - **Session-only mode**: Uses the delegation directly (must target session key DID)
+     *
+     * @param delegation - The PortableDelegation to use (from createDelegation or transport)
+     * @returns A DelegatedAccess instance for performing operations
+     */
+    useDelegation(delegation: PortableDelegation): Promise<DelegatedAccess>;
+    /**
+     * Create a sub-delegation from a received delegation.
+     *
+     * 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
+     */
+    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>;
+}
+//# sourceMappingURL=TinyCloudNode.d.ts.map

package/dist/TinyCloudNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyCloudNode.d.ts","sourceRoot":"","sources":["../src/TinyCloudNode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAEL,gBAAgB,EAGhB,UAAU,EAIV,iBAAiB,EAEjB,aAAa,EAEb,sBAAsB,EAEtB,eAAe,EAEf,UAAU,EACV,sBAAsB,EAGtB,gBAAgB,EAGjB,MAAM,yBAAyB,CAAC;AAejC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMpD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,+GAA+G;IAC/G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,eAAe,CAAS;IAEvC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,IAAI,CAAsC;IAClD,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,eAAe,CAAC,CAAiB;IACzC,OAAO,CAAC,GAAG,CAAC,CAAY;IAExB,wCAAwC;IACxC,OAAO,CAAC,YAAY,CAAS;IAC7B,mDAAmD;IACnD,OAAO,CAAC,aAAa,CAAS;IAG9B,OAAO,CAAC,mBAAmB,CAAwB;IACnD,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,eAAe,CAAiB;IAExC,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAC/C,OAAO,CAAC,aAAa,CAAC,CAAe;IAErC;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,MAAM,GAAE,mBAAwB;IA4F5C;;;;;;OAMG;IACH,IAAI,GAAG,IAAI,MAAM,CAOhB;IAED;;;;;OAKG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED;;;;OAIG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED;;;OAGG;IACH,IAAI,OAAO,IAAI,gBAAgB,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA+BtE;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAgC1B;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAwH5B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IA8B/B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA4B/B;;OAEG;IACH,IAAI,EAAE,IAAI,UAAU,CAKnB;IAMD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,kBAAkB,IAAI,sBAAsB,CAK/C;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAI,WAAW,IAAI;QACjB,oCAAoC;QACpC,IAAI,EAAE,MAAM,UAAU,EAAE,CAAC;QACzB,8BAA8B;QAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;KAC9C,CAiBA;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAI,iBAAiB,IAAI,iBAAiB,CAKzC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,MAAM,IAAI,aAAa,CAK1B;IAED;;;OAGG;IACH,IAAI,YAAY,IAAI,aAAa,CAEhC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,IAAI,OAAO,IAAI,eAAe,CAI7B;IAED;;;OAGG;IACH,IAAI,cAAc,IAAI,eAAe,CAEpC;IAMD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAIrF;;;;;OAKG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAIpE;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC,UAAU,EAAE,CAAC,CAAC;IAIhE;;;;;;OAMG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAIvF;;;;;;;;OAQG;IACG,gBAAgB,CAAC,MAAM,EAAE;QAC7B,kDAAkD;QAClD,IAAI,EAAE,MAAM,CAAC;QACb,wEAAwE;QACxE,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,0DAA0D;QAC1D,WAAW,EAAE,MAAM,CAAC;QACpB,sFAAsF;QACtF,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,iEAAiE;QACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAsE/B;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqH7E;;;;;;;;;OASG;IACG,mBAAmB,CACvB,gBAAgB,EAAE,kBAAkB,EACpC,MAAM,EAAE;QACN,qDAAqD;QACrD,IAAI,EAAE,MAAM,CAAC;QACb,4DAA4D;QAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,2BAA2B;QAC3B,WAAW,EAAE,MAAM,CAAC;QACpB,6EAA6E;QAC7E,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,gFAAgF;QAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACA,OAAO,CAAC,kBAAkB,CAAC;CAkG/B"}