@tinycloud/share-sdk 1.4.2 → 1.4.3-beta.0

package/dist/addressed-publish-DorqWQJ8.d.ts

@@ -0,0 +1,380 @@
+import { UnifiedContentSource, UnifiedPolicyCapability, ShareAction, PolicyCredentialRequirementV1, ArtifactPin } from '@tinycloud/share-envelope';
+import { d as SharePublishTarget, c as PublishedShare, e as SharePublishOptions, O as OwnerShareAction, P as PublishedShareDeliveryMaterial, f as SharePublishError } from './owner-policy-aPmXIR3e.js';
+import { S as ShareAuthorizationRequired, a as ShareAuthorizationMethod } from './authorization-CmP1skO8.js';
+
+/**
+ * Path-bound addressed content (TC-2242). An addressed share encrypts its content under ONE named key,
+ * `share/<shareId>` on the owner's default encryption network, and registers that key's wrapped-key digest. The node
+ * refuses a new registration without both (`content-source-key-path-required`, `content-source-key-digest-required`) and
+ * opens only that one key, never the network. This module is the single place that derives the path, validates the
+ * network, serializes the stored envelope and computes the digests, so no consumer hand-writes any of them.
+ *
+ * Call sequence: `planPathBoundShare` (before anything is written) -> the caller holds the plan's `requiredPermissions`
+ * -> `encryptAddressedShareContent` (or the caller's own `keys.createKey` + `keys.encrypt`) -> upload `storedBytes` ->
+ * `bindPathBoundContentSource` -> `publishAddressedShare`.
+ */
+type AddressedContentSourceErrorCode = "share-id-invalid" | "network-invalid" | "network-not-checksummed" | "key-path-required" | "key-path-mismatch" | "digest-invalid" | "key-not-authorized" | "key-receipt-mismatch" | "envelope-invalid" | "stored-bytes-mismatch";
+/** A path-bound source could not be planned, built or accepted. Match on `code`, not the message or `instanceof`. */
+declare class AddressedContentSourceError extends TypeError {
+    readonly code: AddressedContentSourceErrorCode;
+    constructor(code: AddressedContentSourceErrorCode, message: string);
+}
+/**
+ * The content source of an addressed share: a `UnifiedContentSource` that is bound to its one key. **Build it ONLY with
+ * `bindPathBoundContentSource`.** The publisher can check the path, the digest's FORMAT and the network, but it cannot verify that the digest is the
+ * raw-byte digest of the wrapped key (a hand-written literal that registers `encryptedSymmetricKeyHash`, the canonical hash of the base64 text, type-checks
+ * and publishes, and no recipient or node will ever open it). No runtime brand is used, because two copies of this package must interoperate.
+ */
+type PathBoundContentSource = UnifiedContentSource & {
+    readonly encryptionKeyPath: string;
+    readonly encryptedSymmetricKeyDigestHex: string;
+};
+/** The shape of a `PermissionEntry` (`@tinycloud/sdk-core`): hand it to `requestPermissions` or a manifest as is. */
+interface PathBoundPermissionEntry {
+    service: "tinycloud.encryption";
+    path: string;
+    actions: string[];
+}
+/** The key path every addressed share is encrypted under: `share/<shareId>`. */
+declare function pathBoundKeyPath(shareId: string): string;
+/**
+ * The owner's default encryption network URN with the EIP-55 checksummed address, which is the only spelling the node
+ * accepts for key and prefix resources. Pure. Accepts the owner DID (`did:pkh:eip155:<chain>:<address>`, any case), or just the
+ * owner's address (a string `0x...`, or `{ address, chainId? }`; chain id defaults to 1), so a caller never writes the spelling.
+ */
+declare function defaultEncryptionNetworkForOwner(owner: string | {
+    readonly address: string;
+    readonly chainId?: number;
+}): string;
+/** The digest a path-bound source registers: SHA-256 of the DECODED wrapped-key bytes (the node and the recipient compare exactly this). */
+declare function wrappedKeyDigestHex(encryptedSymmetricKey: string): string;
+/** What a consumer needs to encrypt, upload and bind one addressed share's content. */
+interface PathBoundSharePlan {
+    readonly shareId: string;
+    readonly encryptionNetwork: string;
+    /** `share/<shareId>`: the named key the content is encrypted under. */
+    readonly keyPath: string;
+    /** `<network>/share/<shareId>`: the one decrypt resource the share grants. */
+    readonly keyResource: string;
+    /**
+     * ROUTE A, per share at runtime: `key.create` on exactly this share's key, requested with `requestPermissions` before the key is created
+     * (one extra consent per share). For apps that cannot use the sign-in route (for example apps whose sign-in goes through the OpenKey widget
+     * `authorizeTinyCloud` route, which refuses decrypt and key.create outside `apps/`).
+     */
+    readonly requiredPermissions: PathBoundPermissionEntry[];
+    /**
+     * ROUTE B, once at sign-in (manifest entries): `key.create` and `decrypt` on the default network's `<network>/share/` prefix, so every share's
+     * key can be created without a further prompt. Put these in the `permissions` of the manifest the owner signs in with.
+     */
+    readonly sessionPermissions: PathBoundPermissionEntry[];
+    /** The owner session must hold these for the node to register the policy: decrypt under `<network>/share/` (also part of `sessionPermissions`). */
+    readonly registrationPermissions: PathBoundPermissionEntry[];
+    /** Options for `keys.encrypt(plan.keyPath, plaintext, plan.encryptOptions({ metadata }))`. */
+    encryptOptions(extra?: {
+        readonly metadata?: Readonly<Record<string, string>>;
+    }): {
+        networkId: string;
+        metadata?: Record<string, string>;
+    };
+}
+/**
+ * The manifest entries (route B, sign-in) that let one session create every share's key: `decrypt` and `key.create` on the default network's
+ * `<network>/share/` prefix. Needs no share id, so an app builds its manifest before any share exists. Put the result in `manifest.permissions`.
+ */
+declare function pathBoundSessionPermissions(input: {
+    readonly encryptionNetwork: string;
+}): PathBoundPermissionEntry[];
+/** Validate the share id and network and derive the key path and the permissions the share needs. Writes and signs nothing. */
+declare function planPathBoundShare(input: {
+    readonly shareId: string;
+    readonly encryptionNetwork: string;
+}): PathBoundSharePlan;
+/** The v2 envelope a named key's `encrypt` returns: the fields this module reads. Every other field it returns (ciphertext, alg, aad, metadata) is kept in the stored bytes. */
+interface PathBoundEnvelope {
+    readonly v: number;
+    readonly networkId: string;
+    readonly keyPath: string;
+    readonly keyVersion: number;
+    readonly encryptedSymmetricKey: string;
+    readonly encryptedSymmetricKeyHash: string;
+}
+/** The exact bytes to upload: the canonical JSON of the v2 envelope. Nothing else is stored. */
+declare function pathBoundStoredBytes(envelope: PathBoundEnvelope): Uint8Array;
+/**
+ * The content source for an encrypted and uploaded share. `envelope` is what `keys.encrypt` returned, `storedBytes` the
+ * exact bytes uploaded (`pathBoundStoredBytes(envelope)`), `kvResource` where they now live (`<space>/kv/<path>`).
+ * Derives the path, the raw-byte wrapped-key digest, the ciphertext digest and the key version; nothing is taken on trust.
+ */
+declare function bindPathBoundContentSource(input: {
+    readonly plan: PathBoundSharePlan;
+    readonly envelope: PathBoundEnvelope;
+    readonly storedBytes: Uint8Array;
+    readonly kvResource: string;
+    readonly selector: "exact" | "prefix";
+}): PathBoundContentSource;
+/** The part of a named-key client (`NamedKeyClient`, web `tcw.keys`, node `node.keys`) this module calls. */
+interface AddressedShareKeyClient {
+    createKey(path: string, options: {
+        networkId: string;
+    }): Promise<{
+        readonly networkId: string;
+        readonly keyPath: string;
+        readonly state?: string;
+        readonly keyVersion?: number;
+    }>;
+    encrypt(path: string, plaintext: Uint8Array, options: {
+        networkId: string;
+        metadata?: Record<string, string>;
+    }): Promise<PathBoundEnvelope>;
+}
+/** What `encryptAddressedShareContent` returns: the envelope and the exact bytes to upload. */
+interface EncryptedAddressedContent {
+    readonly envelope: PathBoundEnvelope;
+    readonly storedBytes: Uint8Array;
+    readonly byteLength: number;
+}
+/**
+ * Create the share's named key and encrypt the content under it. Built from the same steps a consumer may run itself
+ * (`keys.createKey`, `keys.encrypt`, then `bindPathBoundContentSource`). The key-create capability in
+ * `plan.requiredPermissions` must already be held; an unauthorized answer is reported as `key-not-authorized` naming it.
+ */
+declare function encryptAddressedShareContent(input: {
+    readonly plan: PathBoundSharePlan;
+    readonly keys: AddressedShareKeyClient;
+    readonly plaintext: Uint8Array;
+    readonly metadata?: Readonly<Record<string, string>>;
+}): Promise<EncryptedAddressedContent>;
+/**
+ * The publisher's gate: a content source must be bound to its own share's key, with a registered wrapped-key digest,
+ * before anything is signed, registered or written. There is no network-scope fallback.
+ */
+declare function assertPathBoundContentSource(source: Partial<UnifiedContentSource> | undefined, shareId: string): asserts source is PathBoundContentSource;
+
+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;
+    readonly credentialDescriptor?: unknown;
+    readonly issuerDid?: string;
+    readonly issuerKid?: string;
+    /** 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")[];
+    readonly credentialDescriptor?: unknown;
+    readonly issuerDid?: string;
+    readonly issuerKid?: string;
+}): Promise<TargetPublishOutcome>;
+
+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;
+    /** The links API origin written into the signed header as its audience. Defaults to `https://api.tinycloud.xyz`. */
+    readonly apiOrigin?: 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[];
+    /** Path-bound to this share's own key (`share/<shareId>`) with the wrapped-key digest; build it with `bindPathBoundContentSource`. Anything else is refused before any signing or write. */
+    readonly contentSource: PathBoundContentSource;
+    readonly credentialRequirement?: PolicyCredentialRequirementV1;
+    readonly filename: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly artifact?: "html";
+    /** TC-1428: pins the share to one write-once artifact version; signed with the envelope. Required when the content source is under `artifacts/`. */
+    readonly artifactPin?: ArtifactPin;
+    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>;
+/** The text a share gets when its sealed envelope cannot fit in a link. */
+declare const ADDRESSED_SHARE_TOO_LARGE_MESSAGE = "This share is too large to send as a link, so nothing was shared. Use a shorter path or fewer folders.";
+/** What a publish has written by the time its sealed envelope is measured. */
+interface AddressedShareWrites {
+    readonly policyCid: string;
+    readonly policyRootCid: string;
+    readonly enforcementRootCid: string;
+}
+/**
+ * Thrown by `publishAddressedShare` when the sealed envelope, measured after
+ * the policy registration, is over `MAX_LINK_BODY_BYTES`. The size bound makes
+ * this unreachable for a correct caller; if it happens, `written` names what
+ * the publish registered so the caller can remove it. No link was built.
+ */
+declare class AddressedShareOverLimitError extends SharePublishError {
+    readonly written: AddressedShareWrites;
+    constructor(written: AddressedShareWrites);
+}
+/** What a sender knows before any write; see {@link addressedShareBodyUpperBound}. */
+interface AddressedShareBoundInput extends AddressedShareRequest {
+    readonly shareId: string;
+    readonly ownerDid: string;
+    readonly nodeOrigin: string;
+    readonly nodeAudience: string;
+    readonly enforcerDid: string;
+    readonly spaceId: string;
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+    };
+    /** Where the content will be stored: a path, or the id and stored file name of an artifact (whose version number the publish assigns). */
+    readonly storage: {
+        readonly path: string;
+    } | {
+        readonly artifactId: string;
+        readonly storageName: string;
+    };
+    /** The owner's encryption network for the space. */
+    readonly encryptionNetwork: string;
+    /** Optional and redundant: the path is always `share/<shareId>`. A different value is refused. */
+    readonly encryptionKeyPath?: string;
+    readonly mediaType: string;
+    readonly byteLength: number;
+    readonly artifact?: "html";
+    readonly expiresAt: Date;
+}
+/**
+ * The largest sealed envelope a share can have, in bytes, computed before any
+ * write (upload, registration, registry or KV write): the same envelope the
+ * publish builds, with every value a write returns at its maximum encoded
+ * length (see `sealedBodyUpperBound`). Compare it with `MAX_LINK_BODY_BYTES`.
+ * For an artifact share the version, the manifest digest and the stored size
+ * are taken at their largest.
+ */
+declare function addressedShareBodyUpperBound(input: AddressedShareBoundInput): Promise<number>;
+/** Refuses (`SharePublishError`, code `max-bytes-exceeded`, {@link ADDRESSED_SHARE_TOO_LARGE_MESSAGE}) a share whose largest sealed envelope is over `MAX_LINK_BODY_BYTES`. Call it before any write. */
+declare function assertAddressedShareFits(input: AddressedShareBoundInput): Promise<void>;
+
+export { type AddressedOwnerRootInput as A, normalizeShareTarget as B, pathBoundKeyPath as C, pathBoundSessionPermissions as D, type EncryptedAddressedContent as E, pathBoundStoredBytes as F, planPathBoundShare as G, prepareAddressedShare as H, publishAddressedShare as I, publishTargetShare as J, targetAuthorizationMethod as K, wrappedKeyDigestHex as L, type PathBoundContentSource as P, type ShareTarget as S, type TargetPublishOutcome as T, type AddressedOwnerRootReceipt as a, type AddressedPublishAuthority as b, type TargetPublishInput as c, ADDRESSED_SHARE_TOO_LARGE_MESSAGE as d, AddressedContentSourceError as e, type AddressedContentSourceErrorCode as f, type AddressedPolicyRegistrationInput as g, type AddressedPolicyRegistrationReceipt as h, type AddressedShareBoundInput as i, type AddressedShareKeyClient as j, AddressedShareOverLimitError as k, type AddressedSharePublishOptions as l, type AddressedShareRequest as m, type AddressedShareWrites as n, type PathBoundEnvelope as o, type PathBoundPermissionEntry as p, type PathBoundSharePlan as q, type PreparedAddressedShare as r, type TargetPublishAdapter as s, addressedCredentialRequirement as t, addressedShareBodyUpperBound as u, assertAddressedShareFits as v, assertPathBoundContentSource as w, bindPathBoundContentSource as x, defaultEncryptionNetworkForOwner as y, encryptAddressedShareContent as z };