@tinycloud/sdk-core 1.0.0

package/dist/delegations/SharingService.d.ts

@@ -0,0 +1,279 @@
+/**
+ * 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.
+     */
+    sessionExpiry?: Date;
+}
+/**
+ * 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?;
+    /**
+     * 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">>): 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>>;
+    /**
+     * 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

@@ -0,0 +1 @@
+{"version":3,"file":"SharingService.d.ts","sourceRoot":"","sources":["../../src/delegations/SharingService.ts"],"names":[],"mappings":"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"}