@tinycloud/share-sdk 1.1.1 → 1.2.0-beta.1

package/dist/addressed-publish-CsUS7-SI.d.cts

@@ -0,0 +1,535 @@
+import { ShareEnvelopeV2, UnifiedPolicyCapability, ShareAction, UnifiedContentSource, PolicyCredentialRequirementV1 } from '@tinycloud/share-envelope';
+
+/** The only interactive boundary exposed by the headless SDK. */
+type ShareAuthorizationMethod = "openkey-device" | "email-claim" | "email-otp";
+interface ShareAuthorizationRequired {
+    readonly state: "authorization-required";
+    readonly method: ShareAuthorizationMethod;
+    /** A browser-safe continuation location. It must never contain a claim secret. */
+    readonly continueUrl?: string;
+    /** An opaque, short-lived, nonce-bound handle. It is not a bearer credential. */
+    readonly resumeToken?: string;
+}
+interface ShareAuthorizationDenied {
+    readonly state: "denied";
+    readonly reason: "rejected" | "expired" | "revoked" | "unsupported";
+}
+interface ShareAuthorizationReady<T> {
+    readonly state: "ready";
+    readonly value: T;
+}
+type ShareAuthorizationResult<T> = ShareAuthorizationReady<T> | ShareAuthorizationRequired | ShareAuthorizationDenied;
+interface ShareAuthorizationAdapter<T> {
+    begin(input: {
+        readonly envelope: ShareEnvelopeV2;
+        readonly method: ShareAuthorizationMethod;
+    }): Promise<ShareAuthorizationResult<T>>;
+    resume(input: {
+        readonly envelope: ShareEnvelopeV2;
+        readonly method: ShareAuthorizationMethod;
+        readonly resumeToken: string;
+        readonly proof?: unknown;
+    }): Promise<ShareAuthorizationResult<T>>;
+    /** Verify the detached node proof against a pinned authority trust bundle. */
+    readonly verifyResult?: (input: {
+        readonly envelope: ShareEnvelopeV2;
+        readonly value: T;
+        readonly proof: unknown;
+    }) => Promise<boolean>;
+}
+/**
+ * A node-authorized addressed read.  Returning plaintext alone is not an
+ * authorization result: the caller must also return the signed response
+ * binding and digest that the node produced for that exact share.
+ */
+interface ShareAuthorizedContent {
+    readonly bytes: Uint8Array;
+    readonly bodyDigest: string;
+    readonly contentSourceDigest: string;
+    readonly binding: {
+        readonly shareId: string;
+        readonly delegationCid: string;
+        readonly authorityMaterialHandle: string;
+        readonly authorityMaterialDigest: string;
+        readonly resource: {
+            readonly kind: "exact" | "prefix";
+            readonly path: string;
+        };
+        readonly action?: string;
+    };
+    /** A detached node proof; self-reported bytes and digests are not authorization. */
+    readonly proof: unknown;
+}
+/**
+ * Start or continue a target authorization without ever guessing a device,
+ * claim, or delegation secret. Adapters own their protocol and are expected
+ * to bind their resume token to a server challenge and expiry.
+ */
+declare function authorizeShare<T>(input: {
+    readonly envelope: ShareEnvelopeV2;
+    readonly method: ShareAuthorizationMethod;
+    readonly adapter: ShareAuthorizationAdapter<T>;
+    readonly resumeToken?: string;
+    readonly proof?: unknown;
+}): Promise<ShareAuthorizationResult<T>>;
+declare function authorizationMethodForTarget(target: {
+    readonly kind: string;
+}): ShareAuthorizationMethod | undefined;
+
+declare const SHARE_CONTENT_LIMIT: number;
+declare const SHARE_PUBLISH_RESULT_VERSION: 1;
+declare const DEFAULT_SHARE_LIFETIME_MS: number;
+type SharePublishTarget = {
+    readonly kind: "bearer";
+} | {
+    readonly kind: "recipientDid";
+    readonly did: string;
+} | {
+    readonly kind: "email";
+    readonly address: string;
+} | {
+    readonly kind: "emailDomain";
+    readonly domain: string;
+};
+/** Input shared by the native bearer and Policy/v3 addressed publishers. */
+interface SharePublishOptions {
+    readonly source: Uint8Array | AsyncIterable<Uint8Array>;
+    readonly filename: string;
+    readonly mediaType?: string;
+    readonly allowBinary?: boolean;
+    readonly target?: SharePublishTarget;
+    readonly expiresAt?: Date;
+    readonly expiryWasExplicit?: boolean;
+    readonly origin: string;
+    readonly maxBytes?: number;
+    readonly now?: () => number;
+}
+interface PublishedShareMetadata {
+    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 expiryClamped?: boolean;
+    readonly expiresAt: string;
+    readonly display: {
+        readonly filename?: string;
+        readonly senderName?: string;
+    };
+    readonly recipientMatcher?: {
+        readonly kind: "bearer" | "recipientDid" | "exactEmail" | "emailDomain";
+        readonly value?: string;
+    };
+    readonly registrationCid?: string;
+    readonly policyCid?: string;
+    readonly ownerDelegationCid?: string;
+    readonly enforcementDelegationCid?: string;
+    readonly ownerDid?: string;
+    readonly shareKeyDid?: string;
+    readonly enforcerDid?: string;
+    readonly envelopeCid?: string;
+    readonly shareCid?: string;
+    /** Set when the content is a numbered artifact version (TC-1428). Pinned: the share can only ever read this version. */
+    readonly artifact?: {
+        readonly id: string;
+        readonly version: number;
+        readonly mode: "pinned";
+    };
+}
+/** Sender-only Policy/v3 material retained in encrypted history for delivery retries. */
+interface PublishedShareDeliveryMaterial {
+    /**
+     * The signed plaintext policy envelope. It is retained only in encrypted
+     * sender history so a delivery can be retried; it never travels in a URL.
+     */
+    readonly envelope: Readonly<Record<string, unknown>>;
+    /** CIDv1/raw/sha2-256 of `sealedEnvelope`, and the CID in the share URL. */
+    readonly shareCid: string;
+    /**
+     * Canonical `version || nonce || AES-256-GCM ciphertext+tag`, base64url.
+     * Node reopens this exact value before authorizing email delivery.
+     */
+    readonly sealedEnvelope: string;
+    /** 32-byte AES-GCM key for `sealedEnvelope`, base64url and fragment-only in the URL. */
+    readonly envelopeKey: string;
+}
+interface PublishedShare {
+    readonly protocol: "tinycloud-share";
+    readonly version: typeof SHARE_PUBLISH_RESULT_VERSION;
+    /** The complete link is deliberately non-enumerable on production results. */
+    readonly url: string;
+    readonly link: {
+        readonly kind: "native" | "policy";
+        readonly cid: string;
+    };
+    readonly metadata: PublishedShareMetadata;
+    /** Non-enumerable Policy/v3 delivery material; never included in command output. */
+    readonly deliveryMaterial?: PublishedShareDeliveryMaterial;
+}
+/** Machine-readable output omits the complete bearer capability and delivery material. */
+declare function redactPublishedShare(result: PublishedShare): Omit<PublishedShare, "url" | "deliveryMaterial">;
+type SharePublishErrorCode = "invalid-argument" | "authority-required" | "max-bytes-exceeded";
+declare class SharePublishError extends Error {
+    readonly code: SharePublishErrorCode;
+    constructor(code: SharePublishErrorCode, message: string);
+}
+
+type ShareTarget = SharePublishTarget;
+interface TargetPublishInput {
+    readonly source: Uint8Array;
+    readonly filename: string;
+    readonly mediaType?: string;
+    /** Additional files for a prefix resource; source remains the first file for compatibility. */
+    readonly files?: readonly {
+        readonly bytes: Uint8Array;
+        readonly filename: string;
+        readonly mediaType?: string;
+    }[];
+    readonly target: ShareTarget;
+    readonly expiresAt: Date;
+    readonly expiryWasExplicit?: boolean;
+    readonly origin: string;
+    readonly resourceKind?: "exact" | "prefix";
+    readonly actions?: readonly ("read" | "list" | "edit")[];
+    readonly notify?: boolean;
+    /** Publish as the next write-once version of this artifact and pin the share to it (TC-1428). */
+    readonly artifact?: {
+        readonly id: string;
+        readonly note?: string;
+    };
+}
+type TargetPublishOutcome = PublishedShare | ShareAuthorizationRequired;
+interface TargetPublishAdapter {
+    publish(input: TargetPublishInput): Promise<TargetPublishOutcome>;
+}
+declare function normalizeShareTarget(target: ShareTarget): ShareTarget;
+declare function targetAuthorizationMethod(target: ShareTarget): ShareAuthorizationMethod | undefined;
+/** Route every share through the authenticated TinyCloud authority adapter. */
+declare function publishTargetShare(input: SharePublishOptions & {
+    readonly target: ShareTarget;
+    readonly notify?: boolean;
+    readonly targetAdapter?: TargetPublishAdapter;
+    readonly files?: readonly {
+        readonly bytes: Uint8Array;
+        readonly filename: string;
+        readonly mediaType?: string;
+    }[];
+    readonly resourceKind?: "exact" | "prefix";
+    readonly actions?: readonly ("read" | "list" | "edit")[];
+}): Promise<TargetPublishOutcome>;
+
+interface OwnerDelegationReceipt {
+    readonly delegationCid: string;
+    readonly signedDagCbor: Uint8Array;
+    readonly delegation: {
+        readonly delegateDID: string;
+        readonly spaceId: string;
+        readonly path: string;
+        readonly actions: readonly string[];
+        readonly expiry: Date;
+    };
+    /** Exact service-scoped capabilities encoded in the signed owner delegation. */
+    readonly permissions?: readonly OwnerDelegationPermission[];
+}
+interface OwnerDelegationPermission {
+    readonly service: string;
+    readonly path: string;
+    readonly actions: readonly string[];
+}
+interface CreateOwnerDelegationBase {
+    readonly delegateDid: string;
+    readonly spaceId: string;
+    readonly expiresAt: Date;
+}
+type CreateOwnerDelegationParams = CreateOwnerDelegationBase & ({
+    readonly path: string;
+    readonly actions: readonly string[];
+    readonly permissions?: never;
+} | {
+    readonly permissions: readonly OwnerDelegationPermission[];
+    readonly path?: never;
+    readonly actions?: never;
+});
+declare const MAX_CONTENT_BYTES: number;
+declare const OWNER_SHARE_REGISTRATION_DOMAIN = "xyz.tinycloud.share/policy-registration/v2\0";
+type OwnerShareAction = "tinycloud.kv/get" | "tinycloud.kv/list" | "tinycloud.kv/metadata" | "tinycloud.kv/put";
+interface OwnerShareDecryption {
+    readonly networkId: string;
+    readonly action: "tinycloud.encryption/decrypt";
+}
+type OwnerShareMatcher = {
+    readonly kind: "exactEmail";
+    readonly value: string;
+} | {
+    readonly kind: "emailDomain";
+    readonly value: string;
+} | {
+    readonly kind: "recipientDid";
+    readonly value: string;
+} | {
+    readonly kind: "bearer";
+};
+interface OwnerSharePolicyV2 {
+    readonly type: "TinyCloudSharePolicy";
+    readonly version: 2;
+    readonly shareId: string;
+    readonly ownerDid: string;
+    readonly shareKeyDid: string;
+    readonly recipientMatcher: OwnerShareMatcher;
+    readonly target: {
+        readonly origin: string;
+        readonly nodeAudience: string;
+        readonly enforcerDid: string;
+        readonly spaceId: string;
+    };
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+    readonly actions: readonly OwnerShareAction[];
+    readonly decryption?: OwnerShareDecryption;
+    readonly contentSource: {
+        readonly kind: "kv";
+        readonly space: string;
+        readonly path: string;
+        readonly action: "tinycloud.kv/get";
+    };
+    readonly contentSourceDigest: string;
+    readonly ownerDelegationCid: string;
+    readonly expiresAt: string;
+}
+interface DelegatedShareKey {
+    readonly did: string;
+    readonly publicKey: Uint8Array;
+    readonly extractable: boolean;
+    /** The underlying WebCrypto private key handle; private JWK material is never returned. */
+    readonly cryptoKey: CryptoKey;
+    sign(bytes: Uint8Array): Promise<Uint8Array>;
+    clear(): void;
+}
+interface SignedDelegation {
+    readonly cid: string;
+    readonly dagCbor: string;
+    readonly issuerDid: string;
+    readonly audienceDid: string;
+    readonly facts: Record<string, string | readonly string[]>;
+    readonly signature: string;
+}
+interface RegisterOwnerSharePolicyParams {
+    readonly policy: {
+        readonly bytes: Uint8Array;
+        readonly cid: string;
+        readonly proof: string;
+    };
+    readonly ownerDelegation: OwnerDelegationReceipt;
+    readonly enforcementDelegation: SignedDelegation;
+    readonly contentSourceDigest: string;
+    /** The enrolled receipt key from the node trust bundle. */
+    readonly nodeProof?: {
+        readonly kid: string;
+        readonly publicKey: Uint8Array;
+    };
+}
+interface OwnerSharePolicyRegistration {
+    readonly registrationCid: string;
+    readonly policyCid: string;
+    readonly ownerDelegationCid: string;
+    readonly enforcementDelegationCid: string;
+    readonly ownerDid: string;
+    readonly shareKeyDid: string;
+    readonly enforcerDid: string;
+    readonly shareId: string;
+    readonly recipientMatcher: OwnerShareMatcher;
+    readonly target: {
+        readonly origin: string;
+        readonly nodeAudience: string;
+        readonly spaceId: string;
+    };
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+    readonly actions: readonly OwnerShareAction[];
+    readonly contentSource: {
+        readonly kind: "kv";
+        readonly space: string;
+        readonly path: string;
+        readonly action: "tinycloud.kv/get";
+    };
+    readonly contentSourceDigest: string;
+    readonly registeredAt: string;
+    readonly expiresAt: string;
+}
+interface OwnerSharePolicyRegistrationReceipt {
+    readonly registration: OwnerSharePolicyRegistration;
+    readonly proof: {
+        readonly alg: "EdDSA";
+        readonly kid: string;
+        readonly signature: string;
+    };
+}
+declare function createDelegatedShareKey(options: {
+    readonly extractable: boolean;
+}): Promise<DelegatedShareKey>;
+/**
+ * Rehydrate a signer wrapper around a `DelegatedShareKey`'s private
+ * `CryptoKey` handle that was persisted (e.g. via IndexedDB structured
+ * clone) and recovered after a reload. `privateKey` must be the same
+ * non-extractable Ed25519 `CryptoKey` originally produced by
+ * {@link createDelegatedShareKey}.
+ */
+declare function restoreDelegatedShareKey(input: {
+    readonly privateKey: CryptoKey;
+    readonly publicKey: Uint8Array;
+    readonly extractable: boolean;
+}): DelegatedShareKey;
+declare function createPolicyEnforcementDelegation(input: {
+    readonly ownerDelegation: OwnerDelegationReceipt;
+    readonly shareKey: DelegatedShareKey;
+    readonly enforcerDid: string;
+    readonly policyCid: string;
+    readonly shareId: string;
+    readonly spaceId: string;
+    readonly nodeAudience: string;
+    readonly path: string;
+    readonly actions: readonly OwnerShareAction[];
+    readonly contentSourceDigest: string;
+    readonly expiresAt: string;
+}): Promise<SignedDelegation>;
+declare function canonicalOwnerSharePolicy(policy: OwnerSharePolicyV2): Promise<{
+    readonly bytes: Uint8Array;
+    readonly cid: string;
+    readonly digest: string;
+}>;
+declare function computeOwnerShareRegistrationCid(registration: Omit<OwnerSharePolicyRegistration, "registrationCid">): string;
+declare function validateOwnerSharePolicyRegistration(value: unknown, expected: RegisterOwnerSharePolicyParams): OwnerSharePolicyRegistrationReceipt;
+/** Validate the exact UTF-8 response bytes emitted by the registration route. */
+declare function validateOwnerSharePolicyRegistrationBytes(bytesValue: Uint8Array, expected: RegisterOwnerSharePolicyParams): OwnerSharePolicyRegistrationReceipt;
+
+interface AddressedOwnerRootInput {
+    readonly ownerDid: string;
+    readonly role: "policy-authority" | "policy-enforcement";
+    readonly audienceDid: string;
+    readonly policyId: string;
+    readonly policyDigestHex: string;
+    readonly policyCid: string;
+    readonly contentSourceDigestHex: string;
+    readonly capabilityCeilingHashHex: string;
+    readonly nativeProjectionHashHex: string;
+    readonly notBefore: Date;
+    readonly expiresAt: Date;
+    readonly nodeAudience: string;
+    readonly capabilities: readonly UnifiedPolicyCapability[];
+}
+interface AddressedOwnerRootReceipt {
+    readonly cid: string;
+    readonly delegationHeader: {
+        readonly Authorization: string;
+    };
+}
+interface AddressedPolicyRegistrationInput {
+    readonly policyCid: string;
+    readonly policy: Readonly<Record<string, unknown>>;
+    readonly policyRoot: {
+        readonly cid: string;
+        readonly authorization: string;
+    };
+    readonly enforcementRoot: {
+        readonly cid: string;
+        readonly authorization: string;
+    };
+    readonly contentSourceDigestHex: string;
+    readonly nativeProjectionHashHex: string;
+    readonly rootExpiresAt: string;
+    readonly enforcerDid: string;
+    readonly expectedNodeAudience: string;
+}
+interface AddressedPolicyRegistrationReceipt {
+    readonly policyCid: string;
+    readonly policyRootCid: string;
+    readonly enforcementRootCid: string;
+    readonly attestedEnforcerBinding: {
+        readonly schema: "xyz.tinycloud.policy/attested-enforcer/v2";
+        readonly enforcerDid: string;
+        readonly nodeAudience: string;
+        readonly attestationBindingDigestHex: string;
+        readonly issuedAt: string;
+        readonly expiresAt: string;
+        readonly signature: {
+            readonly suite: "Ed25519";
+            readonly signerDid: string;
+            readonly value: string;
+        };
+    };
+}
+/** App-neutral owner authority. Node SDK owns all Policy/v3 transport. */
+interface AddressedPublishAuthority {
+    readonly ownerDid: string;
+    createOwnerRoot(input: AddressedOwnerRootInput): Promise<AddressedOwnerRootReceipt>;
+    sign(bytes: Uint8Array): Promise<Uint8Array>;
+    registerPolicy(input: AddressedPolicyRegistrationInput): Promise<AddressedPolicyRegistrationReceipt>;
+}
+interface AddressedSharePublishOptions {
+    readonly shareId: string;
+    readonly shareOrigin: string;
+    readonly nodeOrigin: string;
+    readonly nodeAudience: string;
+    readonly enforcerDid: string;
+    readonly spaceId: string;
+    readonly target: Exclude<ShareTarget, {
+        readonly kind: "bearer";
+    }>;
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+    readonly actions: readonly ShareAction[];
+    readonly policyActions: readonly OwnerShareAction[];
+    readonly contentSource: UnifiedContentSource;
+    readonly credentialRequirement?: PolicyCredentialRequirementV1;
+    readonly filename: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly artifact?: "html";
+    readonly deliveryEmail?: string;
+    readonly expiresAt: Date;
+    /** Sender-history material required by Node's Policy/v3 delivery authorization. */
+    readonly onDeliveryMaterial?: (input: PublishedShareDeliveryMaterial) => void;
+    readonly authority: AddressedPublishAuthority;
+}
+type MailboxTarget = Extract<ShareTarget, {
+    readonly kind: "email" | "emailDomain";
+}>;
+/** The Policy/v2 credential commitment a share addressed to `target` must carry. */
+declare function addressedCredentialRequirement(target: MailboxTarget): PolicyCredentialRequirementV1;
+/** Facts every addressed-share check needs, available before any side effect. */
+type AddressedShareRequest = Pick<AddressedSharePublishOptions, "target" | "actions" | "policyActions" | "filename" | "deliveryEmail">;
+interface PreparedAddressedShare {
+    /** The canonical target the envelope's recipient matcher will carry. */
+    readonly target: Exclude<ShareTarget, {
+        readonly kind: "bearer";
+    }>;
+    /** Present for mailbox targets: the Policy/v2 commitment to pass to `publishAddressedShare`. */
+    readonly credentialRequirement?: PolicyCredentialRequirementV1;
+}
+/**
+ * Runs every argument and target check of `publishAddressedShare` that does
+ * not depend on stored content, and derives the credential commitment. It has
+ * no side effects, so senders call it before uploading content or publishing
+ * a location record; a refused share then leaves nothing behind.
+ */
+declare function prepareAddressedShare(request: AddressedShareRequest): PreparedAddressedShare;
+/** Canonical application-neutral Policy/v3 addressed publisher shared by browser and CLI. */
+declare function publishAddressedShare(input: AddressedSharePublishOptions): Promise<PublishedShare>;
+
+export { publishTargetShare as $, type AddressedOwnerRootInput as A, type ShareAuthorizationReady as B, type CreateOwnerDelegationParams as C, type DelegatedShareKey as D, type ShareAuthorizationRequired as E, SharePublishError as F, type SharePublishErrorCode as G, type SharePublishOptions as H, type SharePublishTarget as I, type SignedDelegation as J, type TargetPublishAdapter as K, addressedCredentialRequirement as L, MAX_CONTENT_BYTES as M, authorizationMethodForTarget as N, type OwnerShareAction as O, type PublishedShareDeliveryMaterial as P, authorizeShare as Q, type RegisterOwnerSharePolicyParams as R, type ShareAuthorizationMethod as S, type TargetPublishOutcome as T, canonicalOwnerSharePolicy as U, computeOwnerShareRegistrationCid as V, createDelegatedShareKey as W, createPolicyEnforcementDelegation as X, normalizeShareTarget as Y, prepareAddressedShare as Z, publishAddressedShare as _, type OwnerShareMatcher as a, redactPublishedShare as a0, restoreDelegatedShareKey as a1, targetAuthorizationMethod as a2, validateOwnerSharePolicyRegistration as a3, validateOwnerSharePolicyRegistrationBytes as a4, type OwnerSharePolicyRegistrationReceipt as b, type PublishedShare as c, type ShareAuthorizedContent as d, type ShareAuthorizationAdapter as e, type TargetPublishInput as f, type ShareAuthorizationResult as g, type ShareTarget as h, type AddressedOwnerRootReceipt as i, type AddressedPolicyRegistrationInput as j, type AddressedPolicyRegistrationReceipt as k, type AddressedPublishAuthority as l, type AddressedSharePublishOptions as m, type AddressedShareRequest as n, DEFAULT_SHARE_LIFETIME_MS as o, OWNER_SHARE_REGISTRATION_DOMAIN as p, type OwnerDelegationPermission as q, type OwnerDelegationReceipt as r, type OwnerShareDecryption as s, type OwnerSharePolicyRegistration as t, type OwnerSharePolicyV2 as u, type PreparedAddressedShare as v, type PublishedShareMetadata as w, SHARE_CONTENT_LIMIT as x, SHARE_PUBLISH_RESULT_VERSION as y, type ShareAuthorizationDenied as z };