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

package/dist/history-CUWDK0lE.d.cts

@@ -0,0 +1,180 @@
+import { d as OwnerShareAction, f as OwnerShareMatcher, j as PublishedShareDeliveryMaterial, q as SignedDelegation, h as OwnerSharePolicyRegistrationReceipt, a as DelegatedShareKey, P as PublishedShare } from './owner-policy-BqzRlkb6.cjs';
+
+interface EncryptedShareHistoryStorage {
+    put(value: Uint8Array): Promise<void>;
+    list(): Promise<readonly Uint8Array[]>;
+    clear(): Promise<void>;
+}
+declare class MemoryEncryptedShareHistoryStorage implements EncryptedShareHistoryStorage {
+    private readonly values;
+    put(value: Uint8Array): Promise<void>;
+    list(): Promise<readonly Uint8Array[]>;
+    clear(): Promise<void>;
+}
+/**
+ * The durable record a sender needs, after a reload, to display and manage
+ * a share it created. Every identity/CID here comes verbatim from the
+ * Node-verified {@link OwnerSharePolicyRegistrationReceipt}; nothing is
+ * re-derived or guessed.
+ */
+interface SenderShareRecord {
+    readonly shareId: string;
+    readonly registrationCid?: string;
+    readonly policyCid?: string;
+    readonly ownerDelegationCid?: string;
+    readonly enforcementDelegationCid?: string;
+    readonly shareKeyDid?: string;
+    readonly ownerDid?: string;
+    readonly enforcerDid?: string;
+    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 recipientMatcher: OwnerShareMatcher;
+    /** The signed target discriminator, retained separately from the email matcher. */
+    readonly targetKind?: "bearer" | "recipientDid" | "email" | "emailDomain";
+    readonly registeredAt: string;
+    readonly expiresAt: string;
+    readonly revokedAt?: string;
+    readonly envelopeCid?: string;
+    readonly shareCid?: string;
+    /** Complete bearer links are encrypted at rest and only revealed explicitly. */
+    readonly link?: string;
+    readonly filename?: string;
+    /** Policy/v3 delivery material. The containing history record must remain encrypted at rest. */
+    readonly deliveryMaterial?: PublishedShareDeliveryMaterial;
+    /** Canonical mailboxes whose invitation delivery was confirmed; history is encrypted at rest. */
+    readonly deliveredRecipients?: readonly string[];
+    /**
+     * `migrated`: imported once from a CLI's local history by the OWNER's
+     * session (slice 5), at an owner-layout key `records/<shareId>`. Such a
+     * record is exempt from the ±1-day `registeredAt` window and nothing else:
+     * its chain is verified like an agent record's, it never ranks as a web
+     * row, and it cannot override a revocation. A record claiming `migrated`
+     * inside an agent subtree is rejected.
+     */
+    readonly provenance?: "migrated";
+    /**
+     * The signed chain behind every CID this record claims (TC-1432 C1), as
+     * exact bytes. Agent records carry it so the owner's browser can verify
+     * the chain without a node lookup. Policy/v3 records prove through
+     * `deliveryMaterial.envelope` plus `session`.
+     */
+    readonly proofs?: SenderShareRecordProofs;
+}
+interface SenderShareRecordProofs {
+    /** Owner→session SIWE CACAO (base64url DAG-CBOR) of the issuing session; absent when it is gone. */
+    readonly session?: string;
+    /** Native bearer link delegation (compact UCAN); its CID is `enforcementDelegationCid`. */
+    readonly link?: string;
+    /** Policy/v2 owner-policy chain: policy bytes (base64url), owner→share-key SIWE CACAO (base64url), enforcement delegation and node registration receipt. */
+    readonly ownerPolicy?: string;
+    readonly ownerDelegation?: string;
+    readonly enforcementDelegation?: SignedDelegation;
+    readonly registration?: OwnerSharePolicyRegistrationReceipt;
+}
+/** Create the durable encrypted-history shape from canonical publication receipts. */
+declare function historyRecordForPublishedShare(result: PublishedShare, now?: Date): SenderShareRecord;
+/**
+ * "direct" selects the Policy/v3 enforcement root; "ancestor" selects its
+ * policy-authority sibling. Addressed shares revoke that signed root through
+ * the Node Policy/v3 endpoint, which cuts off existing sessions as well as
+ * fresh admission and delivery. Bearer shares retain ordinary delegation
+ * revocation.
+ */
+type SenderShareRevocationScope = "direct" | "ancestor";
+interface SenderShareRecordStorage {
+    put(record: SenderShareRecord): Promise<void>;
+    /** Atomically transform the latest record, if present. Implementations that
+     * provide this must serialize the read and write with every other writer. */
+    update?(shareId: string, change: (record: SenderShareRecord) => SenderShareRecord | Promise<SenderShareRecord>): Promise<SenderShareRecord | undefined>;
+    list(): Promise<readonly SenderShareRecord[]>;
+    get(shareId: string): Promise<SenderShareRecord | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+interface StoredSenderShareKey {
+    readonly cryptoKey: CryptoKey;
+    readonly publicKey: Uint8Array;
+    readonly extractable: boolean;
+}
+interface SenderShareKeyStorage {
+    put(shareId: string, key: StoredSenderShareKey): Promise<void>;
+    get(shareId: string): Promise<StoredSenderShareKey | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+/** In-memory reference implementation. Real deployments back these with IndexedDB so the non-extractable `CryptoKey` survives a reload via structured clone. */
+declare class MemorySenderShareRecordStorage implements SenderShareRecordStorage {
+    private readonly records;
+    private operation;
+    private serialize;
+    put(record: SenderShareRecord): Promise<void>;
+    update(shareId: string, change: (record: SenderShareRecord) => SenderShareRecord | Promise<SenderShareRecord>): Promise<SenderShareRecord | undefined>;
+    list(): Promise<readonly SenderShareRecord[]>;
+    get(shareId: string): Promise<SenderShareRecord | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+declare class MemorySenderShareKeyStorage implements SenderShareKeyStorage {
+    private readonly keys;
+    put(shareId: string, key: StoredSenderShareKey): Promise<void>;
+    get(shareId: string): Promise<StoredSenderShareKey | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+interface SenderShareStoreOptions {
+    readonly records: SenderShareRecordStorage;
+    readonly keys: SenderShareKeyStorage;
+    readonly now?: () => Date;
+}
+/**
+ * Reload-safe sender-side management for shares created through
+ * {@link canonicalOwnerSharePolicy} / `registerOwnerSharePolicy`. Persists
+ * the registration receipt's canonical identity tuple plus the ephemeral
+ * share key's non-extractable `CryptoKey` handle, so a sender can list,
+ * inspect, and revoke shares it created in an earlier session -- without
+ * ever re-exporting private key material.
+ */
+declare class SenderShareStore {
+    private readonly records;
+    private readonly keys;
+    private readonly now;
+    constructor(options: SenderShareStoreOptions);
+    /** Persist a Node-verified registration receipt and its share key handle. */
+    save(receipt: OwnerSharePolicyRegistrationReceipt, key: DelegatedShareKey): Promise<SenderShareRecord>;
+    /** List shares created in any session, most recent first. */
+    list(options?: {
+        readonly includeRevoked?: boolean;
+        readonly includeExpired?: boolean;
+    }): Promise<readonly SenderShareRecord[]>;
+    get(shareId: string): Promise<SenderShareRecord | undefined>;
+    /** Recover a signer for the persisted share key after a reload. */
+    loadKey(shareId: string): Promise<DelegatedShareKey | undefined>;
+    /**
+     * The delegation CID to pass to the node's existing generic
+     * `tinycloud.delegation/revoke` invocation to revoke this share at the
+     * requested scope. Does not itself call the node -- callers invoke
+     * their own `revokeDelegation`/`DelegationManager.revoke` with the
+     * returned CID, then call {@link markRevoked} once that succeeds.
+     */
+    revocationTarget(shareId: string, scope: SenderShareRevocationScope): Promise<string>;
+    /** Mark a share revoked locally after the caller's node-side revoke call succeeds. */
+    markRevoked(shareId: string, revokedAt?: string): Promise<SenderShareRecord>;
+    /** Forget a share and clear its persisted key handle. */
+    remove(shareId: string): Promise<void>;
+}
+/** WebCrypto-backed persistence adapter; links and private material are absent. */
+declare class EncryptedSenderShareHistory {
+    private readonly storage;
+    private readonly key;
+    private readonly now;
+    constructor(storage: EncryptedShareHistoryStorage, key: CryptoKey, now?: () => Date);
+    put(record: SenderShareRecord): Promise<void>;
+    list(): Promise<readonly SenderShareRecord[]>;
+    clear(): Promise<void>;
+}
+
+export { EncryptedSenderShareHistory as E, MemoryEncryptedShareHistoryStorage as M, type SenderShareRecord as S, type SenderShareRecordStorage as a, type EncryptedShareHistoryStorage as b, MemorySenderShareKeyStorage as c, MemorySenderShareRecordStorage as d, type SenderShareKeyStorage as e, type SenderShareRecordProofs as f, type SenderShareRevocationScope as g, SenderShareStore as h, historyRecordForPublishedShare as i };

package/dist/history-CyT6x8h4.d.ts

@@ -0,0 +1,180 @@
+import { d as OwnerShareAction, f as OwnerShareMatcher, j as PublishedShareDeliveryMaterial, q as SignedDelegation, h as OwnerSharePolicyRegistrationReceipt, a as DelegatedShareKey, P as PublishedShare } from './owner-policy-BqzRlkb6.js';
+
+interface EncryptedShareHistoryStorage {
+    put(value: Uint8Array): Promise<void>;
+    list(): Promise<readonly Uint8Array[]>;
+    clear(): Promise<void>;
+}
+declare class MemoryEncryptedShareHistoryStorage implements EncryptedShareHistoryStorage {
+    private readonly values;
+    put(value: Uint8Array): Promise<void>;
+    list(): Promise<readonly Uint8Array[]>;
+    clear(): Promise<void>;
+}
+/**
+ * The durable record a sender needs, after a reload, to display and manage
+ * a share it created. Every identity/CID here comes verbatim from the
+ * Node-verified {@link OwnerSharePolicyRegistrationReceipt}; nothing is
+ * re-derived or guessed.
+ */
+interface SenderShareRecord {
+    readonly shareId: string;
+    readonly registrationCid?: string;
+    readonly policyCid?: string;
+    readonly ownerDelegationCid?: string;
+    readonly enforcementDelegationCid?: string;
+    readonly shareKeyDid?: string;
+    readonly ownerDid?: string;
+    readonly enforcerDid?: string;
+    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 recipientMatcher: OwnerShareMatcher;
+    /** The signed target discriminator, retained separately from the email matcher. */
+    readonly targetKind?: "bearer" | "recipientDid" | "email" | "emailDomain";
+    readonly registeredAt: string;
+    readonly expiresAt: string;
+    readonly revokedAt?: string;
+    readonly envelopeCid?: string;
+    readonly shareCid?: string;
+    /** Complete bearer links are encrypted at rest and only revealed explicitly. */
+    readonly link?: string;
+    readonly filename?: string;
+    /** Policy/v3 delivery material. The containing history record must remain encrypted at rest. */
+    readonly deliveryMaterial?: PublishedShareDeliveryMaterial;
+    /** Canonical mailboxes whose invitation delivery was confirmed; history is encrypted at rest. */
+    readonly deliveredRecipients?: readonly string[];
+    /**
+     * `migrated`: imported once from a CLI's local history by the OWNER's
+     * session (slice 5), at an owner-layout key `records/<shareId>`. Such a
+     * record is exempt from the ±1-day `registeredAt` window and nothing else:
+     * its chain is verified like an agent record's, it never ranks as a web
+     * row, and it cannot override a revocation. A record claiming `migrated`
+     * inside an agent subtree is rejected.
+     */
+    readonly provenance?: "migrated";
+    /**
+     * The signed chain behind every CID this record claims (TC-1432 C1), as
+     * exact bytes. Agent records carry it so the owner's browser can verify
+     * the chain without a node lookup. Policy/v3 records prove through
+     * `deliveryMaterial.envelope` plus `session`.
+     */
+    readonly proofs?: SenderShareRecordProofs;
+}
+interface SenderShareRecordProofs {
+    /** Owner→session SIWE CACAO (base64url DAG-CBOR) of the issuing session; absent when it is gone. */
+    readonly session?: string;
+    /** Native bearer link delegation (compact UCAN); its CID is `enforcementDelegationCid`. */
+    readonly link?: string;
+    /** Policy/v2 owner-policy chain: policy bytes (base64url), owner→share-key SIWE CACAO (base64url), enforcement delegation and node registration receipt. */
+    readonly ownerPolicy?: string;
+    readonly ownerDelegation?: string;
+    readonly enforcementDelegation?: SignedDelegation;
+    readonly registration?: OwnerSharePolicyRegistrationReceipt;
+}
+/** Create the durable encrypted-history shape from canonical publication receipts. */
+declare function historyRecordForPublishedShare(result: PublishedShare, now?: Date): SenderShareRecord;
+/**
+ * "direct" selects the Policy/v3 enforcement root; "ancestor" selects its
+ * policy-authority sibling. Addressed shares revoke that signed root through
+ * the Node Policy/v3 endpoint, which cuts off existing sessions as well as
+ * fresh admission and delivery. Bearer shares retain ordinary delegation
+ * revocation.
+ */
+type SenderShareRevocationScope = "direct" | "ancestor";
+interface SenderShareRecordStorage {
+    put(record: SenderShareRecord): Promise<void>;
+    /** Atomically transform the latest record, if present. Implementations that
+     * provide this must serialize the read and write with every other writer. */
+    update?(shareId: string, change: (record: SenderShareRecord) => SenderShareRecord | Promise<SenderShareRecord>): Promise<SenderShareRecord | undefined>;
+    list(): Promise<readonly SenderShareRecord[]>;
+    get(shareId: string): Promise<SenderShareRecord | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+interface StoredSenderShareKey {
+    readonly cryptoKey: CryptoKey;
+    readonly publicKey: Uint8Array;
+    readonly extractable: boolean;
+}
+interface SenderShareKeyStorage {
+    put(shareId: string, key: StoredSenderShareKey): Promise<void>;
+    get(shareId: string): Promise<StoredSenderShareKey | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+/** In-memory reference implementation. Real deployments back these with IndexedDB so the non-extractable `CryptoKey` survives a reload via structured clone. */
+declare class MemorySenderShareRecordStorage implements SenderShareRecordStorage {
+    private readonly records;
+    private operation;
+    private serialize;
+    put(record: SenderShareRecord): Promise<void>;
+    update(shareId: string, change: (record: SenderShareRecord) => SenderShareRecord | Promise<SenderShareRecord>): Promise<SenderShareRecord | undefined>;
+    list(): Promise<readonly SenderShareRecord[]>;
+    get(shareId: string): Promise<SenderShareRecord | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+declare class MemorySenderShareKeyStorage implements SenderShareKeyStorage {
+    private readonly keys;
+    put(shareId: string, key: StoredSenderShareKey): Promise<void>;
+    get(shareId: string): Promise<StoredSenderShareKey | undefined>;
+    delete(shareId: string): Promise<void>;
+}
+interface SenderShareStoreOptions {
+    readonly records: SenderShareRecordStorage;
+    readonly keys: SenderShareKeyStorage;
+    readonly now?: () => Date;
+}
+/**
+ * Reload-safe sender-side management for shares created through
+ * {@link canonicalOwnerSharePolicy} / `registerOwnerSharePolicy`. Persists
+ * the registration receipt's canonical identity tuple plus the ephemeral
+ * share key's non-extractable `CryptoKey` handle, so a sender can list,
+ * inspect, and revoke shares it created in an earlier session -- without
+ * ever re-exporting private key material.
+ */
+declare class SenderShareStore {
+    private readonly records;
+    private readonly keys;
+    private readonly now;
+    constructor(options: SenderShareStoreOptions);
+    /** Persist a Node-verified registration receipt and its share key handle. */
+    save(receipt: OwnerSharePolicyRegistrationReceipt, key: DelegatedShareKey): Promise<SenderShareRecord>;
+    /** List shares created in any session, most recent first. */
+    list(options?: {
+        readonly includeRevoked?: boolean;
+        readonly includeExpired?: boolean;
+    }): Promise<readonly SenderShareRecord[]>;
+    get(shareId: string): Promise<SenderShareRecord | undefined>;
+    /** Recover a signer for the persisted share key after a reload. */
+    loadKey(shareId: string): Promise<DelegatedShareKey | undefined>;
+    /**
+     * The delegation CID to pass to the node's existing generic
+     * `tinycloud.delegation/revoke` invocation to revoke this share at the
+     * requested scope. Does not itself call the node -- callers invoke
+     * their own `revokeDelegation`/`DelegationManager.revoke` with the
+     * returned CID, then call {@link markRevoked} once that succeeds.
+     */
+    revocationTarget(shareId: string, scope: SenderShareRevocationScope): Promise<string>;
+    /** Mark a share revoked locally after the caller's node-side revoke call succeeds. */
+    markRevoked(shareId: string, revokedAt?: string): Promise<SenderShareRecord>;
+    /** Forget a share and clear its persisted key handle. */
+    remove(shareId: string): Promise<void>;
+}
+/** WebCrypto-backed persistence adapter; links and private material are absent. */
+declare class EncryptedSenderShareHistory {
+    private readonly storage;
+    private readonly key;
+    private readonly now;
+    constructor(storage: EncryptedShareHistoryStorage, key: CryptoKey, now?: () => Date);
+    put(record: SenderShareRecord): Promise<void>;
+    list(): Promise<readonly SenderShareRecord[]>;
+    clear(): Promise<void>;
+}
+
+export { EncryptedSenderShareHistory as E, MemoryEncryptedShareHistoryStorage as M, type SenderShareRecord as S, type SenderShareRecordStorage as a, type EncryptedShareHistoryStorage as b, MemorySenderShareKeyStorage as c, MemorySenderShareRecordStorage as d, type SenderShareKeyStorage as e, type SenderShareRecordProofs as f, type SenderShareRevocationScope as g, SenderShareStore as h, historyRecordForPublishedShare as i };

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  ArtifactPinError: () => ArtifactPinError,
   CredentialInvitationError: () => CredentialInvitationError,
   DEFAULT_MAX_CONTENT_BLOB_BYTES: () => DEFAULT_MAX_CONTENT_BLOB_BYTES,
   DEFAULT_MAX_SEALED_BLOB_BYTES: () => DEFAULT_MAX_SEALED_BLOB_BYTES,
@@ -42,6 +43,8 @@ __export(src_exports, {
   ShareReceiveError: () => ShareReceiveError,
   ShareRecipientClient: () => ShareRecipientClient,
   addressedCredentialRequirement: () => addressedCredentialRequirement,
+  artifactBindingView: () => artifactBindingView,
+  assertArtifactBinding: () => assertArtifactBinding,
   authorizationMethodForTarget: () => authorizationMethodForTarget,
   authorizeShare: () => authorizeShare,
   canonicalOwnerSharePolicy: () => canonicalOwnerSharePolicy,
@@ -84,7 +87,8 @@ __export(src_exports, {
   toBase64Url: () => toBase64Url,
   toShareErrorInfo: () => toShareErrorInfo,
   validateOwnerSharePolicyRegistration: () => validateOwnerSharePolicyRegistration,
-  validateOwnerSharePolicyRegistrationBytes: () => validateOwnerSharePolicyRegistrationBytes
+  validateOwnerSharePolicyRegistrationBytes: () => validateOwnerSharePolicyRegistrationBytes,
+  verifyArtifactShare: () => verifyArtifactShare
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -5425,6 +5429,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),
@@ -5444,7 +5462,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];
@@ -6036,6 +6060,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;
@@ -6072,7 +6174,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) {
@@ -6103,6 +6206,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");
@@ -6821,6 +6930,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);
@@ -6887,7 +7004,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((0, import_sha2562.sha256)(textEncoder.encode(`${ENVELOPE_V3_DOMAIN}${canonicalize(unsigned)}`)));
@@ -8581,6 +8699,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));
@@ -8770,6 +8889,7 @@ async function openNativeShare(sharing, link) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ArtifactPinError,
   CredentialInvitationError,
   DEFAULT_MAX_CONTENT_BLOB_BYTES,
   DEFAULT_MAX_SEALED_BLOB_BYTES,
@@ -8792,6 +8912,8 @@ async function openNativeShare(sharing, link) {
   ShareReceiveError,
   ShareRecipientClient,
   addressedCredentialRequirement,
+  artifactBindingView,
+  assertArtifactBinding,
   authorizationMethodForTarget,
   authorizeShare,
   canonicalOwnerSharePolicy,
@@ -8834,6 +8956,7 @@ async function openNativeShare(sharing, link) {
   toBase64Url,
   toShareErrorInfo,
   validateOwnerSharePolicyRegistration,
-  validateOwnerSharePolicyRegistrationBytes
+  validateOwnerSharePolicyRegistrationBytes,
+  verifyArtifactShare
 });
 //# sourceMappingURL=index.cjs.map