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

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