@tinycloud/sdk-core 2.0.0 → 2.0.2-beta.0

package/dist/delegations/SharingService.d.ts

@@ -1,341 +0,0 @@
-/**
- * SharingService - v2 sharing link service with embedded private keys.
- *
- * This service implements the v2 sharing specification, which embeds private keys
- * directly in sharing links. This allows recipients to exercise delegations
- * without requiring prior session setup.
- *
- * Key differences from v1 SharingLinks:
- * - Private keys are embedded in the link (not just tokens)
- * - Recipients can optionally sub-delegate to their own session key
- * - Pre-configured KV service returned for immediate use
- *
- * @packageDocumentation
- */
-import type { IKVService, ServiceSession, InvokeFunction, FetchFunction } from "@tinycloud/sdk-services";
-import type { Result, DelegationError, Delegation, KeyInfo, KeyProvider, GenerateShareParams, ShareLink, ShareSchema, JWK, IngestOptions, CreateDelegationParams, CreateDelegationWasmParams, CreateDelegationWasmResult } from "./types";
-import type { DelegationManager } from "./DelegationManager";
-import type { ICapabilityKeyRegistry } from "../authorization/CapabilityKeyRegistry";
-/**
- * Data encoded in a sharing link.
- */
-export interface EncodedShareData {
-    /** Private key in JWK format (includes d parameter) */
-    key: JWK;
-    /** DID of the key */
-    keyDid: string;
-    /** The delegation granting access */
-    delegation: Delegation;
-    /** Resource path this link grants access to */
-    path: string;
-    /** TinyCloud host URL */
-    host: string;
-    /** Space ID */
-    spaceId: string;
-    /** Schema version */
-    version: 1;
-}
-/**
- * Options for receiving a sharing link.
- */
-export interface ReceiveOptions {
-    /**
-     * Whether to automatically create a sub-delegation to the current session key.
-     * Default: true
-     */
-    autoSubdelegate?: boolean;
-    /**
-     * Whether to use the current session key for operations (requires autoSubdelegate).
-     * Default: true
-     */
-    useSessionKey?: boolean;
-    /**
-     * Ingestion options passed to CapabilityKeyRegistry.
-     */
-    ingestOptions?: IngestOptions;
-}
-/**
- * Result of receiving a sharing link.
- */
-export interface ShareAccess {
-    /** The delegation that was received/created */
-    delegation: Delegation;
-    /** Key info for the received key */
-    key: KeyInfo;
-    /** Pre-configured KV service for the shared path */
-    kv: IKVService;
-    /** The space ID */
-    spaceId: string;
-    /** The path prefix for this share */
-    path: string;
-}
-/**
- * Configuration for SharingService.
- */
-export interface SharingServiceConfig {
-    /** TinyCloud host URLs */
-    hosts: string[];
-    /**
-     * Active session for authentication.
-     * Required for generate(), optional for receive().
-     */
-    session?: ServiceSession;
-    /** Platform-specific invoke function */
-    invoke: InvokeFunction;
-    /** Optional custom fetch implementation */
-    fetch?: FetchFunction;
-    /** Key provider for cryptographic operations */
-    keyProvider: KeyProvider;
-    /** Capability key registry for key/delegation management */
-    registry: ICapabilityKeyRegistry;
-    /**
-     * Delegation manager for creating delegations (used if createDelegation not provided).
-     * Required for generate(), optional for receive().
-     */
-    delegationManager?: DelegationManager;
-    /** Factory for creating KV service instances */
-    createKVService: (config: {
-        hosts: string[];
-        session: ServiceSession;
-        invoke: InvokeFunction;
-        fetch?: FetchFunction;
-        pathPrefix?: string;
-    }) => IKVService;
-    /** Base URL for sharing links (e.g., "https://share.myapp.com") */
-    baseUrl?: string;
-    /**
-     * Custom delegation creation function. When provided, this is used instead
-     * of delegationManager.create(). This allows platforms to use their own
-     * delegation creation logic (e.g., SIWE-based /delegate endpoint).
-     */
-    createDelegation?: (params: CreateDelegationParams) => Promise<Result<Delegation, DelegationError>>;
-    /**
-     * WASM function for client-side delegation creation.
-     * When provided, this is preferred over server-side creation (createDelegation/delegationManager).
-     * Creates UCAN delegations directly without requiring server roundtrip.
-     */
-    createDelegationWasm?: (params: CreateDelegationWasmParams) => CreateDelegationWasmResult;
-    /**
-     * Path prefix for KV operations.
-     * When set, paths passed to generate() are prefixed with this value.
-     * This ensures the share path matches the session's authorized paths.
-     */
-    pathPrefix?: string;
-    /**
-     * Session expiry time.
-     * When set, sharing link expiry is clamped to not exceed this value
-     * unless onRootDelegationNeeded is provided and returns a new delegation.
-     */
-    sessionExpiry?: Date;
-    /**
-     * Callback to create a DIRECT delegation from the root (wallet) to a share key.
-     * This bypasses the session delegation chain, allowing share links with
-     * expiry longer than the current session.
-     *
-     * When provided and share expiry > session expiry:
-     * 1. SharingService creates the ephemeral share key
-     * 2. This callback is invoked with the share key DID
-     * 3. The callback signs a direct PKH -> share key delegation with the wallet
-     * 4. The returned delegation is used for the share link
-     *
-     * This is the CORRECT solution for long-lived share links because:
-     * - It creates a fresh delegation chain: PKH -> share key
-     * - Not constrained by session expiry (no sub-delegation from session key)
-     *
-     * @param params - Parameters for creating the root delegation
-     * @returns The delegation from wallet to share key, or undefined to fall back to session extension
-     */
-    onRootDelegationNeeded?: (params: {
-        /** DID of the share key to delegate to */
-        shareKeyDID: string;
-        /** Space ID */
-        spaceId: string;
-        /** Path to grant access to */
-        path: string;
-        /** Actions to grant */
-        actions: string[];
-        /** Requested expiry time */
-        requestedExpiry: Date;
-    }) => Promise<Delegation | undefined>;
-}
-/**
- * Interface for the SharingService.
- */
-export interface ISharingService {
-    /**
-     * Generate a sharing link with an embedded private key.
-     *
-     * This creates a new session key, delegates to it, and encodes
-     * the key and delegation into a shareable link.
-     */
-    generate(params: GenerateShareParams): Promise<Result<ShareLink, DelegationError>>;
-    /**
-     * Receive and activate a sharing link.
-     *
-     * Decodes the link, ingests the key into the registry, and optionally
-     * creates a sub-delegation to the current session key.
-     */
-    receive(link: string, options?: ReceiveOptions): Promise<Result<ShareAccess, DelegationError>>;
-    /**
-     * Encode sharing data into a link string.
-     */
-    encodeLink(data: EncodedShareData, schema?: ShareSchema): string;
-    /**
-     * Decode a link string into sharing data.
-     */
-    decodeLink(link: string): EncodedShareData;
-}
-/**
- * SharingService - v2 sharing link service with embedded private keys.
- *
- * @example
- * ```typescript
- * import { SharingService } from "@tinycloud/sdk-core/delegations";
- *
- * const sharing = new SharingService({
- *   hosts: ["https://node.tinycloud.xyz"],
- *   session,
- *   invoke,
- *   keyProvider,
- *   registry,
- *   delegationManager,
- *   createKVService,
- *   baseUrl: "https://share.myapp.com"
- * });
- *
- * // Generate a sharing link
- * const result = await sharing.generate({
- *   path: "/kv/documents/report.pdf",
- *   actions: ["tinycloud.kv/get"],
- *   expiry: new Date("2024-12-31")
- * });
- *
- * if (result.ok) {
- *   console.log("Share this URL:", result.data.url);
- * }
- *
- * // 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");
- * }
- * ```
- */
-export declare class SharingService implements ISharingService {
-    private hosts;
-    private session?;
-    private invoke;
-    private fetchFn;
-    private keyProvider;
-    private registry;
-    private delegationManager?;
-    private createKVService;
-    private baseUrl;
-    private createDelegationFn?;
-    private createDelegationWasmFn?;
-    private pathPrefix;
-    private sessionExpiry?;
-    private onRootDelegationNeeded?;
-    /**
-     * Creates a new SharingService instance.
-     */
-    constructor(config: SharingServiceConfig);
-    /**
-     * Gets the primary host URL.
-     */
-    private get host();
-    /**
-     * Updates the session (e.g., after re-authentication).
-     */
-    updateSession(session: ServiceSession): void;
-    /**
-     * Updates the service configuration.
-     * Used to add full capabilities (session, delegationManager, createDelegation, createDelegationWasm) after signIn.
-     */
-    updateConfig(config: Partial<Pick<SharingServiceConfig, "session" | "delegationManager" | "createDelegation" | "createDelegationWasm" | "sessionExpiry" | "onRootDelegationNeeded">>): void;
-    /**
-     * Generate a sharing link with an embedded private key.
-     *
-     * Flow:
-     * 1. Spawn new session key (unique per share)
-     * 2. Create delegation from current session to spawned key
-     * 3. Package: { key (with private!), delegation, path, host }
-     * 4. Encode based on schema (base64 for now)
-     * 5. Return link string
-     */
-    generate(params: GenerateShareParams): Promise<Result<ShareLink, DelegationError>>;
-    /**
-     * Check if any key in the registry can satisfy the delegation request.
-     * A key can satisfy if it has a delegation that:
-     * 1. Covers the required path (exact match or parent path)
-     * 2. Has all required actions
-     * 3. Has sufficient expiry (delegation.expiry >= requestedExpiry)
-     * 4. Allows sub-delegation
-     * @internal
-     */
-    private findSuitableKeyForDelegation;
-    /**
-     * Check if a delegation path matches/covers the requested path.
-     * A delegation path covers the request if:
-     * - It's an exact match
-     * - It's a parent path (e.g., delegation for "" covers "foo/bar")
-     * - It uses wildcards that match
-     * @internal
-     */
-    private pathMatches;
-    /**
-     * Handle fallback to session extension when root delegation is not available.
-     * @internal
-     */
-    private handleSessionExtensionFallback;
-    /**
-     * Create a delegation from the current session to a share key.
-     * This is the fallback path when root delegation is not available.
-     * @internal
-     */
-    private createSessionDelegation;
-    /**
-     * Receive and activate a sharing link.
-     *
-     * Flow:
-     * 1. Decode link -> extract { key, delegation, path, host }
-     * 2. Ingest key into CapabilityKeyRegistry
-     * 3. If autoSubdelegate (default true) + useSessionKey:
-     *    - Create sub-delegation from ingested key -> current session
-     *    - Register sub-delegation capabilities
-     * 4. Return ShareAccess with pre-configured KV service
-     */
-    receive(link: string, options?: ReceiveOptions): Promise<Result<ShareAccess, DelegationError>>;
-    /**
-     * Encode sharing data into a link string.
-     *
-     * @param data - The share data to encode
-     * @param schema - The encoding schema (default: "base64")
-     * @returns Encoded link string
-     */
-    encodeLink(data: EncodedShareData, schema?: ShareSchema): string;
-    /**
-     * Decode a link string into sharing data.
-     *
-     * @param link - The encoded link string (may include URL prefix)
-     * @returns Decoded share data
-     * @throws Error if link format is invalid or data fails validation
-     */
-    decodeLink(link: string): EncodedShareData;
-    /**
-     * Decode and validate a link string into sharing data.
-     *
-     * Internal method that returns a Result instead of throwing.
-     * Used by receive() for proper error handling.
-     *
-     * @param link - The encoded link string (may include URL prefix)
-     * @returns Result with decoded share data or validation error
-     */
-    private decodeLinkWithValidation;
-}
-/**
- * Create a new SharingService instance.
- */
-export declare function createSharingService(config: SharingServiceConfig): ISharingService;
-//# sourceMappingURL=SharingService.d.ts.map

package/dist/delegations/SharingService.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"SharingService.d.ts","sourceRoot":"","sources":["../../src/delegations/SharingService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EACV,MAAM,EACN,eAAe,EACf,UAAU,EACV,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,SAAS,EAET,WAAW,EACX,GAAG,EACH,aAAa,EACb,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAqFrF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,GAAG,EAAE,GAAG,CAAC;IACT,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,UAAU,EAAE,UAAU,CAAC;IACvB,oCAAoC;IACpC,GAAG,EAAE,OAAO,CAAC;IACb,oDAAoD;IACpD,EAAE,EAAE,UAAU,CAAC;IACf,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,0BAA0B;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,wCAAwC;IACxC,MAAM,EAAE,cAAc,CAAC;IACvB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,gDAAgD;IAChD,WAAW,EAAE,WAAW,CAAC;IACzB,4DAA4D;IAC5D,QAAQ,EAAE,sBAAsB,CAAC;IACjC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,gDAAgD;IAChD,eAAe,EAAE,CAAC,MAAM,EAAE;QACxB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,cAAc,CAAC;QACxB,MAAM,EAAE,cAAc,CAAC;QACvB,KAAK,CAAC,EAAE,aAAa,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KAAK,UAAU,CAAC;IACjB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;IACpG;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,MAAM,EAAE,0BAA0B,KAAK,0BAA0B,CAAC;IAC1F;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE;QAChC,0CAA0C;QAC1C,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,8BAA8B;QAC9B,IAAI,EAAE,MAAM,CAAC;QACb,uBAAuB;QACvB,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,4BAA4B;QAC5B,eAAe,EAAE,IAAI,CAAC;KACvB,KAAK,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC,CAAC;IAEnF;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC;IAE/F;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAEjE;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;CAC5C;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAC9C,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,kBAAkB,CAAC,CAA2C;IACtE,OAAO,CAAC,sBAAsB,CAAC,CAA+C;IAC9E,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAO;IAC7B,OAAO,CAAC,sBAAsB,CAAC,CAAiD;IAEhF;;OAEG;gBACS,MAAM,EAAE,oBAAoB;IAiBxC;;OAEG;IACH,OAAO,KAAK,IAAI,GAEf;IAED;;OAEG;IACI,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAInD;;;OAGG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,eAAe,GAAG,wBAAwB,CAAC,CAAC,GAAG,IAAI;IAqBlM;;;;;;;;;OASG;IACG,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IA4MxF;;;;;;;;OAQG;IACH,OAAO,CAAC,4BAA4B;IAqDpC;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAsBnB;;;OAGG;YACW,8BAA8B;IAK5C;;;;OAIG;YACW,uBAAuB;IAmGrC;;;;;;;;;;OAUG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IA0GhD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,GAAE,WAAsB,GAAG,MAAM;IAU1E;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB;IAQ1C;;;;;;;;OAQG;IACH,OAAO,CAAC,wBAAwB;CAiGjC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,eAAe,CAElF"}