@tinycloud/sdk-core 2.10.0-beta.0 → 2.10.0-beta.1

package/dist/delegations/index.d.cts

@@ -0,0 +1,420 @@
+import { I as ICapabilityKeyRegistry, D as DelegationManager, R as Result, a as DelegationError } from '../recipient-types.schema-B2wH53_t.cjs';
+export { A as AccountDelegationPage, b as AccountDelegationQueryOptions, c as AccountDelegationRecord, d as AccountDelegationResource, C as CapabilityEntry, e as CreateDelegationParams, f as CreateDelegationWasmParams, g as CreateDelegationWasmResult, h as CreateOwnerDelegationParams, i as DelegateReceivedShareParams, j as DelegatedResource, k as DelegatedShareAccess, l as DelegatedShareKey, m as Delegation, n as DelegationApiResponse, o as DelegationChain, p as DelegationChainV2, q as DelegationDirection, r as DelegationErrorCode, s as DelegationErrorCodes, t as DelegationFilters, u as DelegationManagerConfig, v as DelegationRecord, w as DelegationRevocationReceipt, x as DelegationStatus, E as EncodedShareData, G as GenerateShareParams, y as ISharingService, z as IngestOptions, J as JWK, K as KeyInfo, B as KeyProvider, F as KeyType, M as MAX_CONTENT_BYTES, H as MAX_SEALED_SHARE_CONTENT_BYTES, L as MAX_SHARE_ARTIFACT_BYTES, N as MAX_SHARE_CONTENT_BYTES, O as MemorySenderShareKeyStorage, P as MemorySenderShareRecordStorage, Q as MemoryShareCache, S as OwnerDelegationReceipt, T as OwnerShareAction, U as OwnerShareMatcher, V as OwnerSharePolicyRegistration, W as OwnerSharePolicyRegistrationReceipt, X as OwnerSharePolicyV2, Y as ReceiveOptions, Z as RegisterOwnerSharePolicyParams, _ as SHARE_DELIVERY_AUTHORIZATION_DOMAIN, $ as SenderShareKeyStorage, a0 as SenderShareRecord, a1 as SenderShareRecordStorage, a2 as SenderShareRevocationScope, a3 as SenderShareStore, a4 as ShareAccess, a5 as ShareAccessError, a6 as ShareAccessV2, a7 as ShareAction, a8 as ShareActionSchema, a9 as ShareAddressedDelegationEnvelopeV2, aa as ShareAddressedDelegationEnvelopeV2Schema, ab as ShareAddressedDelegationRequestV2, ac as ShareAddressedDelegationRequestV2Schema, ad as ShareAddressedDelegationResponseV2, ae as ShareAddressedDelegationResponseV2Schema, af as ShareAddressedRecipientMatcher, ag as ShareArtifactInput, ah as ShareArtifactResult, ai as ShareArtifactV2, aj as ShareCache, ak as ShareCacheEntry, al as ShareCacheKey, am as ShareCacheMetadata, an as ShareCapabilityLike, ao as ShareConflict, ap as ShareContentMetadata, aq as ShareContentSource, ar as ShareDeliveryAuthorization, as as ShareDeliveryAuthorizationReceipt, at as ShareDeliveryAuthorizationRequest, au as ShareDetachedProof, av as ShareEnvelopeError, aw as ShareEnvelopeV2, ax as ShareExpiryBounds, ay as ShareKvContentSource, az as ShareLink, aA as ShareLinkData, aB as ShareLinkLocation, aC as ShareListEntry, aD as ShareListResult, aE as ShareNativeAction, aF as ShareNativeInvokeEnvelopeV1, aG as ShareNativeInvokeErrorResult, aH as ShareNativeInvokeInput, aI as ShareNativeInvokeResult, aJ as ShareNativeInvokeSuccessResult, aK as ShareNativeResponse, aL as ShareNativeResponseSchema, aM as SharePolicy, aN as SharePolicyBinding, aO as SharePolicySession, aP as SharePolicySessionV1, aQ as SharePolicySessionWireV1, aR as ShareReadInvocationV1, aS as ShareReadResult, aT as ShareRecipientClient, aU as ShareRecipientClientOptions, aV as ShareRecipientClientOptionsSchema, aW as ShareRecipientPolicy, aX as ShareRecipientPolicySchema, aY as ShareRecipientResult, aZ as ShareRecipientTarget, a_ as ShareRecipientTargetSchema, a$ as ShareResource, b0 as ShareResourceSchema, b1 as ShareSaveOptions, b2 as ShareSchema, b3 as ShareSqlContentSource, b4 as ShareWireAction, b5 as SharingService, b6 as SharingServiceConfig, b7 as SignedDelegation, b8 as SpaceInfo, b9 as SpaceOwnership, ba as ValidateShareDeliveryAuthorizationExpected, bb as VerifyShareEnvelopeOptions, bc as canonicalOwnerSharePolicy, bd as computeOwnerShareRegistrationCid, be as computeShareCid, bf as createDelegatedShareKey, bg as createPolicyEnforcementDelegation, bh as createShareArtifact, bi as createShareArtifactAsync, bj as createSharePolicy, bk as createSharingService, bl as decryptShareBytesAsync, bm as encodeInlineShareUrl, bn as encodeShareArtifact, bo as encodeShareUrl, bp as encryptShareBytes, bq as encryptShareBytesAsync, br as intersectShareCapabilities, bs as isV2ShareLink, bt as normalizeShareActions, bu as normalizeShareRecipientTarget, bv as normalizeShareResource, bw as parseShareArtifact, bx as parseShareUrl, by as restoreDelegatedShareKey, bz as shareCapabilityAllows, bA as shareDeliveryTrustedKid, bB as signShareEnvelope, bC as validateOwnerSharePolicyRegistration, bD as validateOwnerSharePolicyRegistrationBytes, bE as validateShareDeliveryAuthorizationBytes, bF as verifyShareCid, bG as verifyShareEnvelope } from '../recipient-types.schema-B2wH53_t.cjs';
+import { z } from 'zod';
+import { ServiceSession, InvokeFunction, FetchFunction, IKVService } from '@tinycloud/sdk-services';
+
+/**
+ * Zod schemas for SharingService types.
+ *
+ * These schemas provide runtime validation for sharing link data,
+ * receive options, and service configuration.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Schema for data encoded in a sharing link.
+ *
+ * This is the primary validation point for external share link data.
+ * The link is base64-decoded and JSON-parsed, then validated against this schema.
+ */
+declare const EncodedShareDataSchema: z.ZodObject<{
+    /** Private key in JWK format (must include d parameter) */
+    key: z.ZodEffects<z.ZodObject<{
+        kty: z.ZodString;
+        crv: z.ZodOptional<z.ZodString>;
+        x: z.ZodOptional<z.ZodString>;
+        y: z.ZodOptional<z.ZodString>;
+        d: z.ZodOptional<z.ZodString>;
+        e: z.ZodOptional<z.ZodString>;
+        n: z.ZodOptional<z.ZodString>;
+        kid: z.ZodOptional<z.ZodString>;
+        alg: z.ZodOptional<z.ZodString>;
+        use: z.ZodOptional<z.ZodString>;
+        key_ops: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        kty: string;
+        crv?: string | undefined;
+        x?: string | undefined;
+        y?: string | undefined;
+        d?: string | undefined;
+        e?: string | undefined;
+        n?: string | undefined;
+        kid?: string | undefined;
+        alg?: string | undefined;
+        use?: string | undefined;
+        key_ops?: string[] | undefined;
+    }, {
+        kty: string;
+        crv?: string | undefined;
+        x?: string | undefined;
+        y?: string | undefined;
+        d?: string | undefined;
+        e?: string | undefined;
+        n?: string | undefined;
+        kid?: string | undefined;
+        alg?: string | undefined;
+        use?: string | undefined;
+        key_ops?: string[] | undefined;
+    }>, {
+        kty: string;
+        crv?: string | undefined;
+        x?: string | undefined;
+        y?: string | undefined;
+        d?: string | undefined;
+        e?: string | undefined;
+        n?: string | undefined;
+        kid?: string | undefined;
+        alg?: string | undefined;
+        use?: string | undefined;
+        key_ops?: string[] | undefined;
+    }, {
+        kty: string;
+        crv?: string | undefined;
+        x?: string | undefined;
+        y?: string | undefined;
+        d?: string | undefined;
+        e?: string | undefined;
+        n?: string | undefined;
+        kid?: string | undefined;
+        alg?: string | undefined;
+        use?: string | undefined;
+        key_ops?: string[] | undefined;
+    }>;
+    /** DID of the key */
+    keyDid: z.ZodString;
+    /** The delegation granting access */
+    delegation: z.ZodObject<{
+        cid: z.ZodString;
+        delegateDID: z.ZodString;
+        spaceId: z.ZodString;
+        path: z.ZodString;
+        actions: z.ZodArray<z.ZodString, "many">;
+        caveats: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+        expiry: z.ZodDate;
+        isRevoked: z.ZodBoolean;
+        delegatorDID: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodDate>;
+        parentCid: z.ZodOptional<z.ZodString>;
+        allowSubDelegation: z.ZodOptional<z.ZodBoolean>;
+        authHeader: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        expiry: Date;
+        actions: string[];
+        spaceId: string;
+        cid: string;
+        delegateDID: string;
+        isRevoked: boolean;
+        caveats?: Record<string, unknown>[] | undefined;
+        createdAt?: Date | undefined;
+        delegatorDID?: string | undefined;
+        parentCid?: string | undefined;
+        allowSubDelegation?: boolean | undefined;
+        authHeader?: string | undefined;
+    }, {
+        path: string;
+        expiry: Date;
+        actions: string[];
+        spaceId: string;
+        cid: string;
+        delegateDID: string;
+        isRevoked: boolean;
+        caveats?: Record<string, unknown>[] | undefined;
+        createdAt?: Date | undefined;
+        delegatorDID?: string | undefined;
+        parentCid?: string | undefined;
+        allowSubDelegation?: boolean | undefined;
+        authHeader?: string | undefined;
+    }>;
+    /** Resource path this link grants access to */
+    path: z.ZodString;
+    /** TinyCloud host URL */
+    host: z.ZodString;
+    /** Space ID */
+    spaceId: z.ZodString;
+    /** Schema version (must be 1) */
+    version: z.ZodLiteral<1>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    delegation: {
+        path: string;
+        expiry: Date;
+        actions: string[];
+        spaceId: string;
+        cid: string;
+        delegateDID: string;
+        isRevoked: boolean;
+        caveats?: Record<string, unknown>[] | undefined;
+        createdAt?: Date | undefined;
+        delegatorDID?: string | undefined;
+        parentCid?: string | undefined;
+        allowSubDelegation?: boolean | undefined;
+        authHeader?: string | undefined;
+    };
+    key: {
+        kty: string;
+        crv?: string | undefined;
+        x?: string | undefined;
+        y?: string | undefined;
+        d?: string | undefined;
+        e?: string | undefined;
+        n?: string | undefined;
+        kid?: string | undefined;
+        alg?: string | undefined;
+        use?: string | undefined;
+        key_ops?: string[] | undefined;
+    };
+    spaceId: string;
+    version: 1;
+    keyDid: string;
+    host: string;
+}, {
+    path: string;
+    delegation: {
+        path: string;
+        expiry: Date;
+        actions: string[];
+        spaceId: string;
+        cid: string;
+        delegateDID: string;
+        isRevoked: boolean;
+        caveats?: Record<string, unknown>[] | undefined;
+        createdAt?: Date | undefined;
+        delegatorDID?: string | undefined;
+        parentCid?: string | undefined;
+        allowSubDelegation?: boolean | undefined;
+        authHeader?: string | undefined;
+    };
+    key: {
+        kty: string;
+        crv?: string | undefined;
+        x?: string | undefined;
+        y?: string | undefined;
+        d?: string | undefined;
+        e?: string | undefined;
+        n?: string | undefined;
+        kid?: string | undefined;
+        alg?: string | undefined;
+        use?: string | undefined;
+        key_ops?: string[] | undefined;
+    };
+    spaceId: string;
+    version: 1;
+    keyDid: string;
+    host: string;
+}>;
+type EncodedShareData = z.infer<typeof EncodedShareDataSchema>;
+/**
+ * Schema for options when receiving a sharing link.
+ */
+declare const ReceiveOptionsSchema: z.ZodObject<{
+    /**
+     * Whether to automatically create a sub-delegation to the current session key.
+     * Default: true
+     */
+    autoSubdelegate: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Whether to use the current session key for operations (requires autoSubdelegate).
+     * Default: true
+     */
+    useSessionKey: z.ZodOptional<z.ZodBoolean>;
+    /**
+     * Ingestion options passed to CapabilityKeyRegistry.
+     */
+    ingestOptions: z.ZodOptional<z.ZodObject<{
+        persist: z.ZodOptional<z.ZodBoolean>;
+        validateChain: z.ZodOptional<z.ZodBoolean>;
+        keyName: z.ZodOptional<z.ZodString>;
+        createSessionKey: z.ZodOptional<z.ZodBoolean>;
+        priority: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        priority?: number | undefined;
+        persist?: boolean | undefined;
+        validateChain?: boolean | undefined;
+        keyName?: string | undefined;
+        createSessionKey?: boolean | undefined;
+    }, {
+        priority?: number | undefined;
+        persist?: boolean | undefined;
+        validateChain?: boolean | undefined;
+        keyName?: string | undefined;
+        createSessionKey?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    autoSubdelegate?: boolean | undefined;
+    useSessionKey?: boolean | undefined;
+    ingestOptions?: {
+        priority?: number | undefined;
+        persist?: boolean | undefined;
+        validateChain?: boolean | undefined;
+        keyName?: string | undefined;
+        createSessionKey?: boolean | undefined;
+    } | undefined;
+}, {
+    autoSubdelegate?: boolean | undefined;
+    useSessionKey?: boolean | undefined;
+    ingestOptions?: {
+        priority?: number | undefined;
+        persist?: boolean | undefined;
+        validateChain?: boolean | undefined;
+        keyName?: string | undefined;
+        createSessionKey?: boolean | undefined;
+    } | undefined;
+}>;
+type ReceiveOptions = z.infer<typeof ReceiveOptionsSchema>;
+/**
+ * Schema for SharingService configuration.
+ *
+ * Note: Function fields use z.function() for shape validation only.
+ * External types (ServiceSession, DelegationManager, ICapabilityKeyRegistry)
+ * use z.unknown() with runtime type refinement.
+ */
+declare const SharingServiceConfigSchema: z.ZodObject<{
+    /** TinyCloud host URLs */
+    hosts: z.ZodArray<z.ZodString, "many">;
+    /**
+     * Active session for authentication.
+     * Required for generate(), optional for receive().
+     */
+    session: z.ZodOptional<z.ZodEffects<z.ZodUnknown, ServiceSession, unknown>>;
+    /** Platform-specific invoke function */
+    invoke: z.ZodEffects<z.ZodUnknown, InvokeFunction, unknown>;
+    /** Optional custom fetch implementation */
+    fetch: z.ZodOptional<z.ZodEffects<z.ZodUnknown, FetchFunction, unknown>>;
+    /** Key provider for cryptographic operations */
+    keyProvider: z.ZodObject<{
+        createSessionKey: z.ZodEffects<z.ZodUnknown, (name: string) => Promise<string>, unknown>;
+        getJWK: z.ZodEffects<z.ZodUnknown, (keyId: string) => object, unknown>;
+        getDID: z.ZodEffects<z.ZodUnknown, (keyId: string) => Promise<string>, unknown>;
+    }, "strip", z.ZodTypeAny, {
+        createSessionKey: (name: string) => Promise<string>;
+        getJWK: (keyId: string) => object;
+        getDID: (keyId: string) => Promise<string>;
+    }, {
+        createSessionKey?: unknown;
+        getJWK?: unknown;
+        getDID?: unknown;
+    }>;
+    /** Capability key registry for key/delegation management */
+    registry: z.ZodEffects<z.ZodUnknown, ICapabilityKeyRegistry, unknown>;
+    /**
+     * Delegation manager for creating delegations.
+     * Required for generate(), optional for receive().
+     */
+    delegationManager: z.ZodOptional<z.ZodEffects<z.ZodUnknown, DelegationManager, unknown>>;
+    /** Factory for creating KV service instances */
+    createKVService: z.ZodEffects<z.ZodUnknown, (config: {
+        hosts: string[];
+        session: ServiceSession;
+        invoke: InvokeFunction;
+        fetch?: FetchFunction;
+        pathPrefix?: string;
+    }) => IKVService, unknown>;
+    /** Base URL for sharing links (e.g., "https://share.myapp.com") */
+    baseUrl: z.ZodOptional<z.ZodString>;
+    /**
+     * Custom delegation creation function.
+     */
+    createDelegation: z.ZodOptional<z.ZodEffects<z.ZodUnknown, Function | undefined, unknown>>;
+    /**
+     * WASM function for client-side delegation creation.
+     */
+    createDelegationWasm: z.ZodOptional<z.ZodEffects<z.ZodUnknown, Function | undefined, unknown>>;
+    /** CID computation used to verify transportable child delegations. */
+    computeCid: z.ZodOptional<z.ZodEffects<z.ZodUnknown, (data: Uint8Array, codec: bigint) => string, unknown>>;
+    /**
+     * Path prefix for KV operations.
+     */
+    pathPrefix: z.ZodOptional<z.ZodString>;
+    /**
+     * Session expiry time.
+     */
+    sessionExpiry: z.ZodOptional<z.ZodDate>;
+    /**
+     * Callback to create a DIRECT delegation from wallet to share key.
+     * This is the preferred method for long-lived share links because it
+     * bypasses the session delegation chain entirely.
+     */
+    onRootDelegationNeeded: z.ZodOptional<z.ZodEffects<z.ZodUnknown, Function | undefined, unknown>>;
+}, "strip", z.ZodTypeAny, {
+    hosts: string[];
+    invoke: InvokeFunction;
+    keyProvider: {
+        createSessionKey: (name: string) => Promise<string>;
+        getJWK: (keyId: string) => object;
+        getDID: (keyId: string) => Promise<string>;
+    };
+    registry: ICapabilityKeyRegistry;
+    createKVService: (config: {
+        hosts: string[];
+        session: ServiceSession;
+        invoke: InvokeFunction;
+        fetch?: FetchFunction;
+        pathPrefix?: string;
+    }) => IKVService;
+    session?: ServiceSession | undefined;
+    baseUrl?: string | undefined;
+    fetch?: FetchFunction | undefined;
+    delegationManager?: DelegationManager | undefined;
+    createDelegation?: Function | undefined;
+    createDelegationWasm?: Function | undefined;
+    computeCid?: ((data: Uint8Array, codec: bigint) => string) | undefined;
+    pathPrefix?: string | undefined;
+    sessionExpiry?: Date | undefined;
+    onRootDelegationNeeded?: Function | undefined;
+}, {
+    hosts: string[];
+    keyProvider: {
+        createSessionKey?: unknown;
+        getJWK?: unknown;
+        getDID?: unknown;
+    };
+    session?: unknown;
+    baseUrl?: string | undefined;
+    invoke?: unknown;
+    fetch?: unknown;
+    registry?: unknown;
+    delegationManager?: unknown;
+    createKVService?: unknown;
+    createDelegation?: unknown;
+    createDelegationWasm?: unknown;
+    computeCid?: unknown;
+    pathPrefix?: string | undefined;
+    sessionExpiry?: Date | undefined;
+    onRootDelegationNeeded?: unknown;
+}>;
+type SharingServiceConfig = z.infer<typeof SharingServiceConfigSchema>;
+/**
+ * Validates encoded share data from a decoded link.
+ *
+ * @param data - Unknown data to validate (from JSON.parse)
+ * @returns Result with validated data or validation error
+ *
+ * @example
+ * ```typescript
+ * const parsed = JSON.parse(base64UrlDecode(linkData));
+ * const result = validateEncodedShareData(parsed);
+ * if (!result.ok) {
+ *   return result; // Forward the error
+ * }
+ * const shareData = result.data;
+ * ```
+ */
+declare function validateEncodedShareData(data: unknown): Result<EncodedShareData, DelegationError>;
+/**
+ * Validates receive options.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateReceiveOptions(data: unknown): Result<ReceiveOptions, DelegationError>;
+/**
+ * Validates SharingService configuration.
+ *
+ * @param data - Unknown data to validate
+ * @returns Result with validated data or validation error
+ */
+declare function validateSharingServiceConfig(data: unknown): Result<SharingServiceConfig, DelegationError>;
+
+export { DelegationError, DelegationManager, EncodedShareDataSchema, ReceiveOptionsSchema, Result, SharingServiceConfigSchema, validateEncodedShareData, validateReceiveOptions, validateSharingServiceConfig };