@tinycloud/share-sdk 1.2.0-beta.4 → 1.2.0-beta.5

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { ShareEnvelopeV3, ShareEnvelopeV2 } from '@tinycloud/share-envelope';
+import { ShareEnvelopeV3, ShareEnvelopeV2, ArtifactPin, UnsignedShareEnvelopeV3 } from '@tinycloud/share-envelope';
 export { CheckBearerDelegationOptions, DelegationCheckResult, canonicalize, checkBearerDelegation, fromBase64Url, requiredResourceUri, resourceUriCovers, toBase64Url } from '@tinycloud/share-envelope';
-import { S as ShareAuthorizationMethod, a as ShareAuthorizedContent, b as ShareAuthorizationAdapter, T as TargetPublishOutcome, c as TargetPublishInput, d as ShareAuthorizationResult, e as ShareTarget } from './addressed-publish-DVvTlGog.cjs';
-export { A as AddressedOwnerRootInput, f as AddressedOwnerRootReceipt, g as AddressedPolicyRegistrationInput, h as AddressedPolicyRegistrationReceipt, i as AddressedPublishAuthority, j as AddressedSharePublishOptions, k as AddressedShareRequest, P as PreparedAddressedShare, l as ShareAuthorizationDenied, m as ShareAuthorizationReady, n as ShareAuthorizationRequired, o as TargetPublishAdapter, p as addressedCredentialRequirement, q as authorizationMethodForTarget, r as authorizeShare, s as normalizeShareTarget, t as prepareAddressedShare, u as publishAddressedShare, v as publishTargetShare, w as targetAuthorizationMethod } from './addressed-publish-DVvTlGog.cjs';
+import { S as ShareAuthorizationMethod, a as ShareAuthorizedContent, b as ShareAuthorizationAdapter, T as TargetPublishOutcome, c as TargetPublishInput, d as ShareAuthorizationResult, e as ShareTarget } from './addressed-publish-DtcLNG2m.cjs';
+export { A as AddressedOwnerRootInput, f as AddressedOwnerRootReceipt, g as AddressedPolicyRegistrationInput, h as AddressedPolicyRegistrationReceipt, i as AddressedPublishAuthority, j as AddressedSharePublishOptions, k as AddressedShareRequest, P as PreparedAddressedShare, l as ShareAuthorizationDenied, m as ShareAuthorizationReady, n as ShareAuthorizationRequired, o as TargetPublishAdapter, p as addressedCredentialRequirement, q as authorizationMethodForTarget, r as authorizeShare, s as normalizeShareTarget, t as prepareAddressedShare, u as publishAddressedShare, v as publishTargetShare, w as targetAuthorizationMethod } from './addressed-publish-DtcLNG2m.cjs';
 export { C as CreateOwnerDelegationParams, D as DEFAULT_SHARE_LIFETIME_MS, a as DelegatedShareKey, M as MAX_CONTENT_BYTES, O as OWNER_SHARE_REGISTRATION_DOMAIN, b as OwnerDelegationPermission, c as OwnerDelegationReceipt, d as OwnerShareAction, e as OwnerShareDecryption, f as OwnerShareMatcher, g as OwnerSharePolicyRegistration, h as OwnerSharePolicyRegistrationReceipt, i as OwnerSharePolicyV2, P as PublishedShare, j as PublishedShareDeliveryMaterial, k as PublishedShareMetadata, R as RegisterOwnerSharePolicyParams, S as SHARE_CONTENT_LIMIT, l as SHARE_PUBLISH_RESULT_VERSION, m as SharePublishError, n as SharePublishErrorCode, o as SharePublishOptions, p as SharePublishTarget, q as SignedDelegation, r as canonicalOwnerSharePolicy, s as computeOwnerShareRegistrationCid, t as createDelegatedShareKey, u as createPolicyEnforcementDelegation, v as redactPublishedShare, w as restoreDelegatedShareKey, x as validateOwnerSharePolicyRegistration, y as validateOwnerSharePolicyRegistrationBytes } from './owner-policy-BqzRlkb6.cjs';
 import { S as SenderShareRecord, a as SenderShareRecordStorage } from './history-CUWDK0lE.cjs';
 export { E as EncryptedSenderShareHistory, b as EncryptedShareHistoryStorage, M as MemoryEncryptedShareHistoryStorage, c as MemorySenderShareKeyStorage, d as MemorySenderShareRecordStorage, e as SenderShareKeyStorage, f as SenderShareRecordProofs, g as SenderShareRevocationScope, h as SenderShareStore, i as historyRecordForPublishedShare } from './history-CUWDK0lE.cjs';
@@ -67,6 +67,11 @@ interface ShareMetadata {
         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;
@@ -485,4 +490,85 @@ declare function parseNativeShareUrl(value: string): string;
 /** Receive through the public SDK without creating another transport protocol. */
 declare function openNativeShare(sharing: NativeSharingService, link: string): Promise<unknown>;
 
-export { CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationMethod, ShareAuthorizationResult, ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyDelegationLink, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, ShareTarget, TargetPublishInput, TargetPublishOutcome, canonicalShareFilename, claimShare, createAddressedAuthorization, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, inspectShare, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, receiveShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, toShareErrorInfo };
+/**
+ * Artifact pin verification (TC-1428). Small on purpose: this is the one place that decides whether an addressed
+ * share that reads an artifact version may be trusted.
+ *
+ * What is signed. The owner signs the whole Policy/v3 envelope (Ed25519, `verifyEnvelopeV3SignatureOnly`). `artifactPin` is a
+ * field of that envelope, so the signature covers it: artifact id, version, the sha256 of the version's
+ * `manifest.json`, and the sha256 and size of the one stored file the share reads. The manifest stays an owner-side
+ * record; a recipient never needs to fetch it. Policy/v3 already binds the file's ciphertext digest
+ * (`contentSource.initialCiphertextDigestHex`); the pin binds that digest to an artifact identity and a version, so a
+ * share cannot be re-pointed at another version or another artifact's path without breaking the signature.
+ *
+ * Trust model (accepted, TC-1428 finding 3): the owner is the trusted signer. The node has no write-once ACL, so the
+ * owner (or whoever holds the owner's session) can overwrite `versions/<n>/<file>` afterwards. A recipient then
+ * detects the substitution through the pin digest and fails closed; it cannot tell a malicious owner from a node
+ * serving stale or altered bytes, and does not try to.
+ *
+ * Fails closed: any addressed share whose content source lies under `artifacts/` must carry a valid pin that matches
+ * that source. A pin on any other path is refused. `artifacts/<id>/current/...` has no pin form in v1 and is refused.
+ */
+
+type ArtifactPinErrorCode = "missing-pin" | "unsupported-artifact-path" | "wrong-signer" | "bad-signature" | "pin-source-mismatch" | "pinned-share-writable" | "expectation-mismatch" | "file-digest-mismatch" | "manifest-mismatch";
+declare class ArtifactPinError extends Error {
+    readonly code: ArtifactPinErrorCode;
+    /** The code is the message: stable, short, and what callers and tests match on. */
+    constructor(code: ArtifactPinErrorCode);
+}
+/**
+ * What the caller already knows about the share it is opening, from outside the envelope. Optional: a v1 pinned share
+ * names its version in its own signed pin and nothing outside the link says which one to expect, so no production
+ * caller passes it. A caller that does learn a version out of band (a listing, a "newer version" link) uses it to
+ * refuse an older or different pin.
+ */
+interface ExpectedArtifact {
+    readonly artifactId?: string;
+    readonly version?: number;
+}
+interface VerifyArtifactShareOptions {
+    /** The did:key the caller trusts as the sender. `signature.signerDid` is self-asserted and proves nothing alone. */
+    readonly expectedOwnerDid: string;
+    readonly expected?: ExpectedArtifact;
+}
+/**
+ * The fields of an envelope (or of a share about to be built) that the pin binds. Taking a view lets the publisher run
+ * the identical check before it registers anything, and the recipient run it again where it reads.
+ */
+interface ArtifactBindingView {
+    readonly artifactPin?: ArtifactPin;
+    readonly target: {
+        readonly spaceId: string;
+    };
+    readonly contentSource: {
+        readonly kvResource: string;
+        readonly selector: "exact" | "prefix";
+        readonly mode: "mutable" | "immutable";
+        readonly initialCiphertextDigestHex?: string | undefined;
+    };
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+    /** Share actions (`read` | `list` | `edit`). */
+    readonly actions: readonly string[];
+    /** KV abilities the signed policy grants on the content source. */
+    readonly policyKvActions: readonly string[];
+}
+declare function artifactBindingView(envelope: UnsignedShareEnvelopeV3 | ShareEnvelopeV3): ArtifactBindingView;
+/**
+ * The pin and the content source must say the same thing, and a pinned share must be read-only. Synchronous and
+ * signature-free, so the publisher can run it before registering anything and the recipient can re-run it at the
+ * point of reading. Returns the pin for an artifact share and `undefined` for any other share.
+ */
+declare function assertArtifactBinding(view: ArtifactBindingView, expected?: ExpectedArtifact): ArtifactPin | undefined;
+/**
+ * Check that the trusted owner signed this envelope (and so its pin), then the pin binding. Throws `ArtifactPinError`;
+ * never returns a partial answer. Only the owner's Ed25519 signature over the envelope is checked here, because that
+ * is what authenticates the pin. The rest of the envelope (policy signature, owner roots, enforcer binding) is
+ * `verifyEnvelopeV3`'s job, and `resolvePolicyShare` runs both before it trusts a link. (Folding the two into one
+ * call was measured: +911 gzip bytes in the canonical ESM bundle, for a saved ed25519 verify.)
+ */
+declare function verifyArtifactShare(envelope: ShareEnvelopeV3, options: VerifyArtifactShareOptions): ArtifactPin | undefined;
+
+export { type ArtifactBindingView, ArtifactPinError, type ArtifactPinErrorCode, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, type ExpectedArtifact, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationMethod, ShareAuthorizationResult, ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyDelegationLink, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, ShareTarget, TargetPublishInput, TargetPublishOutcome, type VerifyArtifactShareOptions, artifactBindingView, assertArtifactBinding, canonicalShareFilename, claimShare, createAddressedAuthorization, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, inspectShare, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, receiveShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, toShareErrorInfo, verifyArtifactShare };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { ShareEnvelopeV3, ShareEnvelopeV2 } from '@tinycloud/share-envelope';
+import { ShareEnvelopeV3, ShareEnvelopeV2, ArtifactPin, UnsignedShareEnvelopeV3 } from '@tinycloud/share-envelope';
 export { CheckBearerDelegationOptions, DelegationCheckResult, canonicalize, checkBearerDelegation, fromBase64Url, requiredResourceUri, resourceUriCovers, toBase64Url } from '@tinycloud/share-envelope';
-import { S as ShareAuthorizationMethod, a as ShareAuthorizedContent, b as ShareAuthorizationAdapter, T as TargetPublishOutcome, c as TargetPublishInput, d as ShareAuthorizationResult, e as ShareTarget } from './addressed-publish-BDaGyQA9.js';
-export { A as AddressedOwnerRootInput, f as AddressedOwnerRootReceipt, g as AddressedPolicyRegistrationInput, h as AddressedPolicyRegistrationReceipt, i as AddressedPublishAuthority, j as AddressedSharePublishOptions, k as AddressedShareRequest, P as PreparedAddressedShare, l as ShareAuthorizationDenied, m as ShareAuthorizationReady, n as ShareAuthorizationRequired, o as TargetPublishAdapter, p as addressedCredentialRequirement, q as authorizationMethodForTarget, r as authorizeShare, s as normalizeShareTarget, t as prepareAddressedShare, u as publishAddressedShare, v as publishTargetShare, w as targetAuthorizationMethod } from './addressed-publish-BDaGyQA9.js';
+import { S as ShareAuthorizationMethod, a as ShareAuthorizedContent, b as ShareAuthorizationAdapter, T as TargetPublishOutcome, c as TargetPublishInput, d as ShareAuthorizationResult, e as ShareTarget } from './addressed-publish-BnSBJ-MX.js';
+export { A as AddressedOwnerRootInput, f as AddressedOwnerRootReceipt, g as AddressedPolicyRegistrationInput, h as AddressedPolicyRegistrationReceipt, i as AddressedPublishAuthority, j as AddressedSharePublishOptions, k as AddressedShareRequest, P as PreparedAddressedShare, l as ShareAuthorizationDenied, m as ShareAuthorizationReady, n as ShareAuthorizationRequired, o as TargetPublishAdapter, p as addressedCredentialRequirement, q as authorizationMethodForTarget, r as authorizeShare, s as normalizeShareTarget, t as prepareAddressedShare, u as publishAddressedShare, v as publishTargetShare, w as targetAuthorizationMethod } from './addressed-publish-BnSBJ-MX.js';
 export { C as CreateOwnerDelegationParams, D as DEFAULT_SHARE_LIFETIME_MS, a as DelegatedShareKey, M as MAX_CONTENT_BYTES, O as OWNER_SHARE_REGISTRATION_DOMAIN, b as OwnerDelegationPermission, c as OwnerDelegationReceipt, d as OwnerShareAction, e as OwnerShareDecryption, f as OwnerShareMatcher, g as OwnerSharePolicyRegistration, h as OwnerSharePolicyRegistrationReceipt, i as OwnerSharePolicyV2, P as PublishedShare, j as PublishedShareDeliveryMaterial, k as PublishedShareMetadata, R as RegisterOwnerSharePolicyParams, S as SHARE_CONTENT_LIMIT, l as SHARE_PUBLISH_RESULT_VERSION, m as SharePublishError, n as SharePublishErrorCode, o as SharePublishOptions, p as SharePublishTarget, q as SignedDelegation, r as canonicalOwnerSharePolicy, s as computeOwnerShareRegistrationCid, t as createDelegatedShareKey, u as createPolicyEnforcementDelegation, v as redactPublishedShare, w as restoreDelegatedShareKey, x as validateOwnerSharePolicyRegistration, y as validateOwnerSharePolicyRegistrationBytes } from './owner-policy-BqzRlkb6.js';
 import { S as SenderShareRecord, a as SenderShareRecordStorage } from './history-CyT6x8h4.js';
 export { E as EncryptedSenderShareHistory, b as EncryptedShareHistoryStorage, M as MemoryEncryptedShareHistoryStorage, c as MemorySenderShareKeyStorage, d as MemorySenderShareRecordStorage, e as SenderShareKeyStorage, f as SenderShareRecordProofs, g as SenderShareRevocationScope, h as SenderShareStore, i as historyRecordForPublishedShare } from './history-CyT6x8h4.js';
@@ -67,6 +67,11 @@ interface ShareMetadata {
         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;
@@ -485,4 +490,85 @@ declare function parseNativeShareUrl(value: string): string;
 /** Receive through the public SDK without creating another transport protocol. */
 declare function openNativeShare(sharing: NativeSharingService, link: string): Promise<unknown>;
 
-export { CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationMethod, ShareAuthorizationResult, ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyDelegationLink, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, ShareTarget, TargetPublishInput, TargetPublishOutcome, canonicalShareFilename, claimShare, createAddressedAuthorization, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, inspectShare, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, receiveShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, toShareErrorInfo };
+/**
+ * Artifact pin verification (TC-1428). Small on purpose: this is the one place that decides whether an addressed
+ * share that reads an artifact version may be trusted.
+ *
+ * What is signed. The owner signs the whole Policy/v3 envelope (Ed25519, `verifyEnvelopeV3SignatureOnly`). `artifactPin` is a
+ * field of that envelope, so the signature covers it: artifact id, version, the sha256 of the version's
+ * `manifest.json`, and the sha256 and size of the one stored file the share reads. The manifest stays an owner-side
+ * record; a recipient never needs to fetch it. Policy/v3 already binds the file's ciphertext digest
+ * (`contentSource.initialCiphertextDigestHex`); the pin binds that digest to an artifact identity and a version, so a
+ * share cannot be re-pointed at another version or another artifact's path without breaking the signature.
+ *
+ * Trust model (accepted, TC-1428 finding 3): the owner is the trusted signer. The node has no write-once ACL, so the
+ * owner (or whoever holds the owner's session) can overwrite `versions/<n>/<file>` afterwards. A recipient then
+ * detects the substitution through the pin digest and fails closed; it cannot tell a malicious owner from a node
+ * serving stale or altered bytes, and does not try to.
+ *
+ * Fails closed: any addressed share whose content source lies under `artifacts/` must carry a valid pin that matches
+ * that source. A pin on any other path is refused. `artifacts/<id>/current/...` has no pin form in v1 and is refused.
+ */
+
+type ArtifactPinErrorCode = "missing-pin" | "unsupported-artifact-path" | "wrong-signer" | "bad-signature" | "pin-source-mismatch" | "pinned-share-writable" | "expectation-mismatch" | "file-digest-mismatch" | "manifest-mismatch";
+declare class ArtifactPinError extends Error {
+    readonly code: ArtifactPinErrorCode;
+    /** The code is the message: stable, short, and what callers and tests match on. */
+    constructor(code: ArtifactPinErrorCode);
+}
+/**
+ * What the caller already knows about the share it is opening, from outside the envelope. Optional: a v1 pinned share
+ * names its version in its own signed pin and nothing outside the link says which one to expect, so no production
+ * caller passes it. A caller that does learn a version out of band (a listing, a "newer version" link) uses it to
+ * refuse an older or different pin.
+ */
+interface ExpectedArtifact {
+    readonly artifactId?: string;
+    readonly version?: number;
+}
+interface VerifyArtifactShareOptions {
+    /** The did:key the caller trusts as the sender. `signature.signerDid` is self-asserted and proves nothing alone. */
+    readonly expectedOwnerDid: string;
+    readonly expected?: ExpectedArtifact;
+}
+/**
+ * The fields of an envelope (or of a share about to be built) that the pin binds. Taking a view lets the publisher run
+ * the identical check before it registers anything, and the recipient run it again where it reads.
+ */
+interface ArtifactBindingView {
+    readonly artifactPin?: ArtifactPin;
+    readonly target: {
+        readonly spaceId: string;
+    };
+    readonly contentSource: {
+        readonly kvResource: string;
+        readonly selector: "exact" | "prefix";
+        readonly mode: "mutable" | "immutable";
+        readonly initialCiphertextDigestHex?: string | undefined;
+    };
+    readonly resource: {
+        readonly kind: "exact" | "prefix";
+        readonly path: string;
+    };
+    /** Share actions (`read` | `list` | `edit`). */
+    readonly actions: readonly string[];
+    /** KV abilities the signed policy grants on the content source. */
+    readonly policyKvActions: readonly string[];
+}
+declare function artifactBindingView(envelope: UnsignedShareEnvelopeV3 | ShareEnvelopeV3): ArtifactBindingView;
+/**
+ * The pin and the content source must say the same thing, and a pinned share must be read-only. Synchronous and
+ * signature-free, so the publisher can run it before registering anything and the recipient can re-run it at the
+ * point of reading. Returns the pin for an artifact share and `undefined` for any other share.
+ */
+declare function assertArtifactBinding(view: ArtifactBindingView, expected?: ExpectedArtifact): ArtifactPin | undefined;
+/**
+ * Check that the trusted owner signed this envelope (and so its pin), then the pin binding. Throws `ArtifactPinError`;
+ * never returns a partial answer. Only the owner's Ed25519 signature over the envelope is checked here, because that
+ * is what authenticates the pin. The rest of the envelope (policy signature, owner roots, enforcer binding) is
+ * `verifyEnvelopeV3`'s job, and `resolvePolicyShare` runs both before it trusts a link. (Folding the two into one
+ * call was measured: +911 gzip bytes in the canonical ESM bundle, for a saved ed25519 verify.)
+ */
+declare function verifyArtifactShare(envelope: ShareEnvelopeV3, options: VerifyArtifactShareOptions): ArtifactPin | undefined;
+
+export { type ArtifactBindingView, ArtifactPinError, type ArtifactPinErrorCode, CredentialInvitationError, type CredentialInvitationErrorCode, type CredentialInvitationReceipt, type CredentialInvitationResult, DEFAULT_MAX_CONTENT_BLOB_BYTES, DEFAULT_MAX_SEALED_BLOB_BYTES, type ExpectedArtifact, MemoryShareCache, NATIVE_SHARE_FRAGMENT_PARAMETER, type NativeShareResult, type NativeSharingService, type ParsedAddressedEnvelope, SHARE_RESULT_VERSION, SHARE_V2_PROTOCOL, SenderShareRecord, SenderShareRecordStorage, ShareAuthorizationAdapter, ShareAuthorizationMethod, ShareAuthorizationResult, ShareAuthorizedContent, type ShareCache, type ShareCacheEntry, type ShareCacheKey, type ShareCacheMetadata, type ShareDeliveryAdapter, type ShareErrorCode, type ShareErrorInfo, type ShareFetchOptions, type ShareHistoryView, type ShareInspection, type ShareMetadata, type ShareNodeTrust, ShareNotifyError, type ShareNotifyInput, type ShareNotifyResult, type ShareNotifyState, type SharePolicyChallenge, type SharePolicyDelegationLink, type SharePolicyPublishAdapter, type SharePolicyRootRevocation, type SharePolicySession, type SharePresentationMaterial, type ShareReceiveAuthorizationRequired, ShareReceiveError, type ShareReceiveOutcome, type ShareReceiveResult, ShareRecipientClient, type ShareRecipientClientOptions, type ShareRevocationAdapter, type ShareRevocationResult, ShareTarget, TargetPublishInput, TargetPublishOutcome, type VerifyArtifactShareOptions, artifactBindingView, assertArtifactBinding, canonicalShareFilename, claimShare, createAddressedAuthorization, createNativeShare, createShareV2HolderBindingArtifact, deliverCredentialInvitation, hasUnsafeFilenameCodePoint, inspectShare, listShares, notifyShare, openNativeShare, parseAddressedEnvelope, parseNativeShareUrl, publishPolicyShare, receiveShare, recipientMatchesShareRecord, resumeShareAuthorization, revokeShare, shareDeliveryWindowExpiresAt, showShare, toShareErrorInfo, verifyArtifactShare };

package/dist/index.js

@@ -5341,6 +5341,20 @@ var v3TargetSchema = external_exports.object({
   nodeAudience: external_exports.string().min(1),
   spaceId: external_exports.string().refine(isCanonicalPathSegment, { message: "expected a canonical space id" })
 }).strict();
+var ARTIFACT_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{2,62}$/;
+var artifactPinSchema = external_exports.object({
+  v: external_exports.literal(1),
+  artifactId: external_exports.string().regex(ARTIFACT_ID_PATTERN),
+  version: external_exports.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+  /** SHA-256 (lowercase hex) of the exact `manifest.json` bytes. The manifest itself stays an owner-side record. */
+  manifestSha256: external_exports.string().regex(/^[0-9a-f]{64}$/),
+  /** An addressed share reads one exact file, so exactly one entry: the stored bytes (ciphertext) it will fetch. */
+  files: external_exports.array(external_exports.object({
+    path: external_exports.string().min(1).max(255),
+    sha256: external_exports.string().regex(/^[0-9a-f]{64}$/),
+    bytes: external_exports.number().int().nonnegative()
+  }).strict()).length(1)
+}).strict();
 var unsignedShareEnvelopeV3BaseSchema = external_exports.object({
   version: external_exports.literal(3),
   shareId: external_exports.string().min(1),
@@ -5360,7 +5374,13 @@ var unsignedShareEnvelopeV3BaseSchema = external_exports.object({
   expiry: external_exports.string().datetime({ offset: true }),
   display: displaySchema,
   encrypted: external_exports.literal(true),
-  metadata: contentMetadataSchema
+  metadata: contentMetadataSchema,
+  /**
+   * TC-1428: an owner-signed statement that this share reads one write-once artifact version. Additive: absent on
+   * every other share, and covered by the envelope signature because the signature spans the whole unsigned object.
+   * The shape is checked here; its binding to the content source is `verifyArtifactShare` in share-sdk.
+   */
+  artifactPin: artifactPinSchema.optional()
 }).strict();
 function validateV3Invariants(value, ctx) {
   const actions = [...value.actions];
@@ -5952,6 +5972,84 @@ async function parseSealedInlineShareUrl(url, options = {}) {
   return { kind: "inline", ciphertextCid: record.cid, ciphertext, key32 };
 }
 
+// src/artifact-core.ts
+var ARTIFACT_ROOT = "artifacts";
+function parseArtifactVersionPath(path) {
+  const match = /^artifacts\/([a-z0-9][a-z0-9_-]{2,62})\/versions\/([1-9][0-9]{0,14})\/([^/]+)$/.exec(path);
+  if (match === null) return void 0;
+  return { artifactId: match[1], version: Number(match[2]), file: match[3] };
+}
+
+// src/artifact-pin.ts
+var ArtifactPinError = class extends Error {
+  code;
+  /** The code is the message: stable, short, and what callers and tests match on. */
+  constructor(code3) {
+    super(code3);
+    this.name = "ArtifactPinError";
+    this.code = code3;
+  }
+};
+function artifactBindingView(envelope) {
+  return {
+    ...envelope.artifactPin === void 0 ? {} : { artifactPin: envelope.artifactPin },
+    target: envelope.target,
+    contentSource: envelope.contentSource,
+    resource: envelope.resource,
+    actions: envelope.actions,
+    policyKvActions: envelope.policy.capabilityCeiling.flatMap((capability) => capability.kind === "kv" ? capability.actions : [])
+  };
+}
+function sourcePath(view) {
+  const resource = view.contentSource.kvResource;
+  const marker = "/kv/";
+  const at = resource.indexOf(marker);
+  if (at <= 0 || resource.slice(0, at) !== view.target.spaceId) {
+    throw new ArtifactPinError("pin-source-mismatch");
+  }
+  return resource.slice(at + marker.length);
+}
+function assertArtifactBinding(view, expected = {}) {
+  const pin = view.artifactPin;
+  const path = sourcePath(view);
+  const inArtifacts = path === ARTIFACT_ROOT || path.startsWith(`${ARTIFACT_ROOT}/`);
+  if (!inArtifacts) {
+    if (pin !== void 0) throw new ArtifactPinError("pin-source-mismatch");
+    return void 0;
+  }
+  if (pin === void 0) throw new ArtifactPinError("missing-pin");
+  const parsed = parseArtifactVersionPath(path);
+  if (parsed === void 0) throw new ArtifactPinError("unsupported-artifact-path");
+  const file = pin.files[0];
+  const source = view.contentSource;
+  if (
+    // The stored ciphertext of one file: bounded like content (100 MiB) plus the envelope's own framing.
+    file.bytes > 128 * 1024 * 1024 || pin.artifactId !== parsed.artifactId || pin.version !== parsed.version || file.path !== parsed.file || view.resource.kind !== "exact" || view.resource.path !== path || source.selector !== "exact" || source.mode !== "immutable" || source.initialCiphertextDigestHex !== file.sha256
+  ) {
+    throw new ArtifactPinError("pin-source-mismatch");
+  }
+  if (view.actions.includes("edit") || view.policyKvActions.includes("tinycloud.kv/put")) {
+    throw new ArtifactPinError("pinned-share-writable");
+  }
+  if (expected.artifactId !== void 0 && expected.artifactId !== pin.artifactId || expected.version !== void 0 && expected.version !== pin.version) {
+    throw new ArtifactPinError("expectation-mismatch");
+  }
+  return pin;
+}
+function verifyArtifactShare(envelope, options) {
+  if (envelope.signature.signerDid !== options.expectedOwnerDid) {
+    throw new ArtifactPinError("wrong-signer");
+  }
+  let valid;
+  try {
+    valid = verifyEnvelopeV3SignatureOnly(envelope) && envelope.policy.ownerDid === options.expectedOwnerDid;
+  } catch {
+    valid = false;
+  }
+  if (!valid) throw new ArtifactPinError("bad-signature");
+  return assertArtifactBinding(artifactBindingView(envelope), options.expected);
+}
+
 // src/receive.ts
 var SHARE_RESULT_VERSION = 1;
 var DEFAULT_MAX_SEALED_BLOB_BYTES = 100 * 1024 * 1024 + 29;
@@ -5988,7 +6086,8 @@ function metadataFor(envelope, origin) {
       ...envelope.display.senderName === void 0 ? {} : { senderName: envelope.display.senderName },
       ...envelope.display.filename === void 0 ? {} : { filename: envelope.display.filename },
       ...envelope.display.mode === void 0 ? {} : { mode: envelope.display.mode }
-    }
+    },
+    ...envelope.artifactPin === void 0 ? {} : { artifact: { id: envelope.artifactPin.artifactId, version: envelope.artifactPin.version } }
   };
 }
 async function resolvePolicyShare(link, options) {
@@ -6019,6 +6118,12 @@ async function resolvePolicyShare(link, options) {
   } catch {
     throw new ShareReceiveError("signature-invalid", "share signature is invalid");
   }
+  try {
+    verifyArtifactShare(envelope, { expectedOwnerDid: envelope.policy.ownerDid });
+  } catch (error) {
+    if (!(error instanceof ArtifactPinError)) throw error;
+    throw new ShareReceiveError("envelope-invalid", `share artifact pin is invalid (${error.code})`);
+  }
   options.signal?.throwIfAborted();
   const expiry = Date.parse(envelope.expiry);
   if (!Number.isFinite(expiry)) throw new ShareReceiveError("envelope-invalid", "share expiry is invalid");
@@ -6737,6 +6842,14 @@ function assertMailboxCommitment(commitment, target) {
 async function publishAddressedShare(input) {
   assertSafeInput(input);
   const { target } = prepareAddressedShare(input);
+  assertArtifactBinding({
+    ...input.artifactPin === void 0 ? {} : { artifactPin: input.artifactPin },
+    target: { spaceId: input.spaceId },
+    contentSource: input.contentSource,
+    resource: input.resource,
+    actions: input.actions,
+    policyKvActions: input.policyActions
+  });
   const options = { ...input, filename: canonicalShareFilename(input.filename) };
   if (target.kind !== "recipientDid") assertMailboxCommitment(options.credentialRequirement, target);
   const expiry = rfc3339Seconds(options.expiresAt);
@@ -6803,7 +6916,8 @@ async function publishAddressedShare(input) {
       filename: options.filename,
       ...options.mediaType.startsWith("text/") ? { encoding: "utf-8" } : {},
       ...options.artifact === void 0 ? {} : { artifact: options.artifact }
-    }
+    },
+    ...options.artifactPin === void 0 ? {} : { artifactPin: options.artifactPin }
   };
   unsignedShareEnvelopeV3Schema.parse(unsigned);
   const envelopeSignature = await options.authority.sign(sha2563(textEncoder.encode(`${ENVELOPE_V3_DOMAIN}${canonicalize(unsigned)}`)));
@@ -8497,6 +8611,7 @@ var ShareRecipientClient = class {
     const envelope = this.options.envelope;
     const signer = this.nativeSigner ?? this.signer;
     if (envelope.version !== 3 || this.session === void 0 || this.v3Authorization === void 0 || this.v3NodeAudience === void 0 || signer === void 0) throw new Error("v3 policy session signer is required");
+    assertArtifactBinding(artifactBindingView(envelope));
     if (!matchesInitialCiphertextDigest(bytes3, envelope.contentSource.initialCiphertextDigestHex)) throw new Error("v3 owner KV ciphertext digest mismatch");
     const encrypted = parseV3InlineEncryptedEnvelope(bytes3, envelope);
     const receiverPrivateKey = crypto.getRandomValues(new Uint8Array(32));
@@ -8685,6 +8800,7 @@ async function openNativeShare(sharing, link) {
   return sharing.receive(parseNativeShareUrl(link), { autoSubdelegate: false, useSessionKey: false });
 }
 export {
+  ArtifactPinError,
   CredentialInvitationError,
   DEFAULT_MAX_CONTENT_BLOB_BYTES,
   DEFAULT_MAX_SEALED_BLOB_BYTES,
@@ -8707,6 +8823,8 @@ export {
   ShareReceiveError,
   ShareRecipientClient,
   addressedCredentialRequirement,
+  artifactBindingView,
+  assertArtifactBinding,
   authorizationMethodForTarget,
   authorizeShare,
   canonicalOwnerSharePolicy,
@@ -8749,6 +8867,7 @@ export {
   toBase64Url,
   toShareErrorInfo,
   validateOwnerSharePolicyRegistration,
-  validateOwnerSharePolicyRegistrationBytes
+  validateOwnerSharePolicyRegistrationBytes,
+  verifyArtifactShare
 };
 //# sourceMappingURL=index.js.map