@tinycloud/share-sdk 1.2.1 → 1.3.0-beta.0

package/dist/web-recipient-entry-D9IJEyRA.d.cts

@@ -0,0 +1,206 @@
+import { ShareEnvelopeV3, ShareEnvelopeV2 } from '@tinycloud/share-envelope';
+import { a as ShareAuthorizationMethod, f as ShareAuthorizedContent, c as ShareAuthorizationAdapter } from './authorization-CmP1skO8.cjs';
+
+type ShareErrorCode = "invalid-link" | "fetch-failed" | "max-bytes-exceeded" | "cid-mismatch" | "decrypt-failed" | "envelope-invalid" | "origin-mismatch" | "signature-invalid" | "capability-invalid" | "expired" | "unsupported-target" | "authorization-denied" | "content-integrity-failed";
+declare const SHARE_RESULT_VERSION: 1;
+declare const DEFAULT_MAX_SEALED_BLOB_BYTES: number;
+declare const DEFAULT_MAX_CONTENT_BLOB_BYTES: number;
+declare class ShareReceiveError extends Error {
+    readonly code: ShareErrorCode;
+    readonly details: {
+        readonly expiresAt?: string;
+        readonly stage?: "envelope" | "content";
+        readonly reason?: "policy-target" | "recipient-did-target" | "prefix-resource";
+    } | undefined;
+    constructor(code: ShareErrorCode, message: string, details?: {
+        readonly expiresAt?: string;
+        readonly stage?: "envelope" | "content";
+        readonly reason?: "policy-target" | "recipient-did-target" | "prefix-resource";
+    });
+    toJSON(): ShareErrorInfo;
+}
+interface ShareErrorInfo {
+    readonly protocol: "tinycloud-share";
+    readonly version: typeof SHARE_RESULT_VERSION;
+    readonly error: {
+        readonly code: ShareErrorCode;
+    };
+}
+declare function toShareErrorInfo(error: unknown): ShareErrorInfo;
+/** Policy/v3 links seal their authorization metadata in a fragment; no blob fetch adapter exists. */
+interface ShareFetchOptions {
+    readonly expectedOrigin?: string;
+    readonly signal?: AbortSignal;
+    readonly now?: () => number;
+    readonly maxSealedBlobBytes?: number;
+    readonly maxContentBlobBytes?: number;
+    readonly onResolvedAddressedEnvelope?: (envelope: ShareEnvelopeV3, cid: string) => void;
+}
+interface ShareMetadata {
+    readonly protocol: "tinycloud-share";
+    readonly version: 1;
+    readonly shareId: string;
+    readonly origin: string;
+    readonly target: {
+        readonly kind: "bearer" | "recipientDid" | "email" | "emailDomain";
+        readonly origin: string;
+        readonly nodeAudience: string;
+        readonly spaceId: string;
+    };
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+    readonly actions: readonly string[];
+    readonly expiresAt: string;
+    readonly display: {
+        readonly senderName?: string;
+        readonly filename?: string;
+        readonly mode?: string;
+    };
+    /** Set when the share is pinned to one artifact version; the owner's signature covers it (TC-1428). */
+    readonly artifact?: {
+        readonly id: string;
+        readonly version: number;
+    };
+}
+interface ShareInspection {
+    readonly metadata: ShareMetadata;
+    readonly link: {
+        readonly origin: string;
+        readonly cid: string;
+        readonly kind: "policy";
+    };
+}
+interface ShareReceiveAuthorizationRequired {
+    readonly state: "authorization-required";
+    readonly method: ShareAuthorizationMethod;
+    readonly continueUrl?: string;
+    readonly resumeToken?: string;
+}
+/** Retained as the result consumed after the node authorization ceremony. */
+interface ShareReceiveResult extends ShareInspection {
+    readonly bytes: Uint8Array;
+    readonly text?: string;
+}
+type ShareReceiveOutcome = ShareReceiveResult | ShareReceiveAuthorizationRequired;
+declare function inspectShare(link: string, options?: ShareFetchOptions): Promise<ShareInspection>;
+/**
+ * Resolve and verify invitation metadata only. Actual content access is an
+ * invocation against the owner node and is performed by the receiver SDK.
+ */
+declare function receiveShare(link: string, options?: ShareFetchOptions): Promise<ShareReceiveOutcome>;
+
+interface ShareNodeTrust {
+    readonly invitationKid: string;
+    readonly invitationPublicKey: Uint8Array;
+}
+interface SharePresentationMaterial {
+    readonly holderDid: string;
+    readonly credential: string;
+    readonly credentialDigest?: string;
+    readonly holderBinding: Record<string, unknown>;
+    readonly proof: Record<string, unknown>;
+    readonly sign?: (bytes: Uint8Array) => Promise<Uint8Array>;
+    readonly email?: string;
+    /** Exact v3 credential claim returned by the verified holder ceremony. */
+    readonly claim?: Record<string, unknown>;
+    /** Exact v3 presentation returned by the verified holder ceremony. */
+    readonly presentation?: Record<string, unknown>;
+    /** Exact verified issuer envelope used by accountless v4 admission. */
+    readonly credentialEnvelope?: Record<string, unknown>;
+    /** Exact credential requirement committed by the signed policy. */
+    readonly requirement?: Record<string, unknown>;
+}
+interface SharePolicyChallenge {
+    readonly challengeId: string;
+    readonly nonce: string;
+    readonly expiresAt: string;
+    readonly enforcerDid?: string;
+    readonly action: string;
+    readonly requestBodyDigest: string;
+    readonly [key: string]: unknown;
+}
+interface ShareRecipientClientOptions {
+    readonly nodeOrigin: string;
+    /** Required only by the retired v2 response-proof adapter. Policy/v3 trusts its signed attested binding. */
+    readonly trustedNode?: ShareNodeTrust;
+    readonly holderDid: string;
+    readonly envelope: ShareEnvelopeV2 | ShareEnvelopeV3;
+    readonly fetchFn?: typeof fetch;
+    readonly buildPresentation?: (input: {
+        readonly challenge: SharePolicyChallenge;
+        readonly envelope: ShareEnvelopeV2 | ShareEnvelopeV3;
+        readonly policy: Record<string, unknown>;
+    }) => Promise<SharePresentationMaterial>;
+    readonly sign?: (bytes: Uint8Array) => Promise<Uint8Array>;
+    readonly signal?: AbortSignal;
+    readonly onStage?: (stage: "policy-admission" | "delegation-import" | "invocation" | "decryption") => void;
+    /**
+     * A previously admitted and imported policy session (S0), optionally with
+     * the descendants that re-delegate it, in order, down to this holder.
+     */
+    readonly policyAuthorization?: {
+        readonly authorization: string;
+        readonly cid: string;
+        readonly descendants?: readonly SharePolicyDelegationLink[];
+    };
+}
+/** One signed link of a policy delegation chain, as imported into the Node. */
+interface SharePolicyDelegationLink {
+    readonly authorization: string;
+    readonly cid: string;
+}
+interface SharePolicySession {
+    readonly sessionId: string;
+    readonly expiresAt: string;
+    readonly actions: readonly ("read" | "list" | "edit")[];
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+}
+declare class ShareRecipientClient {
+    private readonly options;
+    private readonly fetchFn;
+    private session;
+    private signer;
+    private nativeSigner;
+    private holderProof;
+    private v3Authorization;
+    private v3NodeAudience;
+    private v3ContentKey;
+    private v3ContentEnvelope;
+    constructor(options: ShareRecipientClientOptions);
+    beginChallenge(envelope: ShareEnvelopeV2): Promise<SharePolicyChallenge>;
+    private establish;
+    authorize(envelope: ShareEnvelopeV2): Promise<ShareAuthorizedContent>;
+    establishPolicySession(): Promise<SharePolicySession>;
+    private establishV3;
+    /** Decrypt a v3 KV value through a fresh recipient-signed decrypt invocation. */
+    decryptV3Content(bytes: Uint8Array): Promise<{
+        readonly bytes: Uint8Array;
+        readonly mediaType: string;
+    }>;
+    /** Re-encrypt edited v3 content with the admitted content key. */
+    encryptV3Content(bytes: Uint8Array, mediaType: string): Promise<Uint8Array>;
+    resumeWithProof(envelope: ShareEnvelopeV2, resumeToken: string, proof: unknown): Promise<ShareAuthorizedContent>;
+    nativeInvoke(request: {
+        readonly action: string;
+        readonly resource?: Record<string, unknown>;
+        readonly body?: number[];
+        readonly bodyDigest?: number[];
+        readonly ifMatch?: string;
+        readonly contentType?: string;
+    }): Promise<Response>;
+    private nativeInvokeV3;
+}
+declare function createAddressedAuthorization(input: Omit<ShareRecipientClientOptions, "envelope" | "buildPresentation"> & {
+    readonly buildPresentation?: (input: {
+        readonly challenge: SharePolicyChallenge;
+        readonly envelope: ShareEnvelopeV2;
+        readonly policy: Record<string, unknown>;
+    }) => Promise<SharePresentationMaterial>;
+}): ShareAuthorizationAdapter<ShareAuthorizedContent>;
+
+export { DEFAULT_MAX_CONTENT_BLOB_BYTES as D, SHARE_RESULT_VERSION as S, DEFAULT_MAX_SEALED_BLOB_BYTES as a, type ShareErrorCode as b, type ShareErrorInfo as c, type ShareFetchOptions as d, type ShareInspection as e, type ShareMetadata as f, type ShareNodeTrust as g, type SharePolicyChallenge as h, type SharePolicyDelegationLink as i, type SharePolicySession as j, type SharePresentationMaterial as k, type ShareReceiveAuthorizationRequired as l, ShareReceiveError as m, type ShareReceiveOutcome as n, type ShareReceiveResult as o, ShareRecipientClient as p, type ShareRecipientClientOptions as q, createAddressedAuthorization as r, inspectShare as s, receiveShare as t, toShareErrorInfo as u };