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

package/dist/addressed-publish-BnSBJ-MX.d.ts

@@ -0,0 +1,242 @@
+import { ShareEnvelopeV2, UnifiedPolicyCapability, ShareAction, UnifiedContentSource, PolicyCredentialRequirementV1, ArtifactPin } from '@tinycloud/share-envelope';
+import { p as SharePublishTarget, P as PublishedShare, o as SharePublishOptions, d as OwnerShareAction, j as PublishedShareDeliveryMaterial } from './owner-policy-BqzRlkb6.js';
+
+/** 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;
+
+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 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";
+    /** 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>;
+
+export { type AddressedOwnerRootInput as A, type PreparedAddressedShare as P, type ShareAuthorizationMethod as S, type TargetPublishOutcome as T, type ShareAuthorizedContent as a, type ShareAuthorizationAdapter as b, type TargetPublishInput as c, type ShareAuthorizationResult as d, type ShareTarget as e, type AddressedOwnerRootReceipt as f, type AddressedPolicyRegistrationInput as g, type AddressedPolicyRegistrationReceipt as h, type AddressedPublishAuthority as i, type AddressedSharePublishOptions as j, type AddressedShareRequest as k, type ShareAuthorizationDenied as l, type ShareAuthorizationReady as m, type ShareAuthorizationRequired as n, type TargetPublishAdapter as o, addressedCredentialRequirement as p, authorizationMethodForTarget as q, authorizeShare as r, normalizeShareTarget as s, prepareAddressedShare as t, publishAddressedShare as u, publishTargetShare as v, targetAuthorizationMethod as w };

package/dist/addressed-publish-DtcLNG2m.d.cts

@@ -0,0 +1,242 @@
+import { ShareEnvelopeV2, UnifiedPolicyCapability, ShareAction, UnifiedContentSource, PolicyCredentialRequirementV1, ArtifactPin } from '@tinycloud/share-envelope';
+import { p as SharePublishTarget, P as PublishedShare, o as SharePublishOptions, d as OwnerShareAction, j as PublishedShareDeliveryMaterial } from './owner-policy-BqzRlkb6.cjs';
+
+/** 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;
+
+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 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";
+    /** 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>;
+
+export { type AddressedOwnerRootInput as A, type PreparedAddressedShare as P, type ShareAuthorizationMethod as S, type TargetPublishOutcome as T, type ShareAuthorizedContent as a, type ShareAuthorizationAdapter as b, type TargetPublishInput as c, type ShareAuthorizationResult as d, type ShareTarget as e, type AddressedOwnerRootReceipt as f, type AddressedPolicyRegistrationInput as g, type AddressedPolicyRegistrationReceipt as h, type AddressedPublishAuthority as i, type AddressedSharePublishOptions as j, type AddressedShareRequest as k, type ShareAuthorizationDenied as l, type ShareAuthorizationReady as m, type ShareAuthorizationRequired as n, type TargetPublishAdapter as o, addressedCredentialRequirement as p, authorizationMethodForTarget as q, authorizeShare as r, normalizeShareTarget as s, prepareAddressedShare as t, publishAddressedShare as u, publishTargetShare as v, targetAuthorizationMethod as w };

package/dist/artifact.cjs

@@ -29,16 +29,18 @@ __export(artifact_exports, {
   artifactVersionResource: () => artifactVersionResource,
   artifactVersionsPrefix: () => artifactVersionsPrefix,
   assertArtifactId: () => assertArtifactId,
+  buildArtifactPin: () => buildArtifactPin,
   listArtifactVersions: () => listArtifactVersions,
   manifestBytes: () => manifestBytes,
   newArtifactId: () => newArtifactId,
   parseArtifactManifest: () => parseArtifactManifest,
   parseArtifactVersionPath: () => parseArtifactVersionPath,
   publishArtifactVersion: () => publishArtifactVersion,
-  sha256Hex: () => sha256Hex
+  sha256Hex: () => sha256Hex,
+  verifyArtifactFileBytes: () => verifyArtifactFileBytes,
+  verifyArtifactManifestBytes: () => verifyArtifactManifestBytes
 });
 module.exports = __toCommonJS(artifact_exports);
-var import_sha2562 = require("@noble/hashes/sha256");
 
 // ../share-envelope/dist/index.js
 var import_sha2 = require("@noble/hashes/sha2");
@@ -5322,6 +5324,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),
@@ -5341,7 +5357,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];
@@ -5440,6 +5462,17 @@ function canonicalize(value) {
 }
 var MAX_INLINE_BYTES = 256 * 1024;
 
+// src/artifact.ts
+var import_sha2562 = require("@noble/hashes/sha256");
+
+// 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/filename-policy.ts
 var UNSAFE_FILENAME_CODE_POINT = /[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u;
 function hasUnsafeFilenameCodePoint(value) {
@@ -5453,8 +5486,21 @@ function canonicalShareFilename(value) {
   return canonical;
 }
 
+// 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(code2) {
+    super(code2);
+    this.name = "ArtifactPinError";
+    this.code = code2;
+  }
+};
+
 // src/artifact.ts
-var ARTIFACT_ROOT = "artifacts";
+function sha256Hex(bytes) {
+  return Array.from((0, import_sha2562.sha256)(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
 var ARTIFACT_MANIFEST_NAME = "manifest.json";
 var ARTIFACT_MANIFEST_VERSION = 1;
 var ARTIFACT_MAX_PUBLISH_ATTEMPTS = 16;
@@ -5468,9 +5514,6 @@ var ArtifactError = class extends Error {
     this.code = code2;
   }
 };
-function sha256Hex(bytes) {
-  return Array.from((0, import_sha2562.sha256)(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
 function newArtifactId(random = (length2) => crypto.getRandomValues(new Uint8Array(length2))) {
   return `art_${Array.from(random(8), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
 }
@@ -5493,11 +5536,6 @@ function artifactVersionResource(artifactId, version) {
 function artifactVersionFilePath(artifactId, version, filename) {
   return `${artifactVersionResource(artifactId, version)}/${filename}`;
 }
-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] };
-}
 function manifestBytes(manifest) {
   return new TextEncoder().encode(canonicalize(manifest));
 }
@@ -5643,6 +5681,40 @@ async function publishArtifactVersion(store, input) {
   }
   throw new ArtifactError("conflict", "could not claim an artifact version number after repeated races; retry");
 }
+function buildArtifactPin(version, filename) {
+  const entry = version.manifest.files.find((candidate) => candidate.path === filename);
+  if (entry === void 0) throw new ArtifactError("invalid-argument", "artifact manifest does not list that file");
+  return {
+    v: 1,
+    artifactId: version.artifactId,
+    version: version.version,
+    manifestSha256: version.manifestSha256,
+    files: [{ path: entry.path, sha256: entry.sha256, bytes: entry.bytes }]
+  };
+}
+function verifyArtifactManifestBytes(pin, manifestBytes2) {
+  if (sha256Hex(manifestBytes2) !== pin.manifestSha256) {
+    throw new ArtifactPinError("manifest-mismatch");
+  }
+  let manifest;
+  try {
+    manifest = parseArtifactManifest(manifestBytes2);
+  } catch {
+    throw new ArtifactPinError("manifest-mismatch");
+  }
+  const file = pin.files[0];
+  const listed = manifest.files.find((candidate) => candidate.path === file.path);
+  if (listed === void 0 || listed.sha256 !== file.sha256 || listed.bytes !== file.bytes) {
+    throw new ArtifactPinError("manifest-mismatch");
+  }
+  return manifest;
+}
+function verifyArtifactFileBytes(pin, storedBytes) {
+  const file = pin.files[0];
+  if (storedBytes.byteLength !== file.bytes || sha256Hex(storedBytes) !== file.sha256) {
+    throw new ArtifactPinError("file-digest-mismatch");
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ARTIFACT_MANIFEST_NAME,
@@ -5654,12 +5726,15 @@ async function publishArtifactVersion(store, input) {
   artifactVersionResource,
   artifactVersionsPrefix,
   assertArtifactId,
+  buildArtifactPin,
   listArtifactVersions,
   manifestBytes,
   newArtifactId,
   parseArtifactManifest,
   parseArtifactVersionPath,
   publishArtifactVersion,
-  sha256Hex
+  sha256Hex,
+  verifyArtifactFileBytes,
+  verifyArtifactManifestBytes
 });
 //# sourceMappingURL=artifact.cjs.map