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

package/dist/artifact.d.cts

@@ -1,4 +1,18 @@
+import { ArtifactPin } from '@tinycloud/share-envelope';
+
+/**
+ * The few artifact helpers the browser bundles need (the pin verifier reads a version path). Kept
+ * apart from `artifact.ts`, which is CLI and agent tooling and must stay out of those bundles.
+ */
 declare const ARTIFACT_ROOT = "artifacts";
+/** The artifact and version a stored KV path belongs to, if it is under a version directory. */
+declare function parseArtifactVersionPath(path: string): {
+    readonly artifactId: string;
+    readonly version: number;
+    readonly file: string;
+} | undefined;
+
+declare function sha256Hex(bytes: Uint8Array): string;
 declare const ARTIFACT_MANIFEST_NAME = "manifest.json";
 declare const ARTIFACT_MANIFEST_VERSION: 1;
 /** A lost create race bumps `n`; this bounds how many times one publish retries. */
@@ -66,19 +80,12 @@ interface ArtifactVersionSummary {
     readonly manifest?: ArtifactManifest;
     readonly manifestSha256?: string;
 }
-declare function sha256Hex(bytes: Uint8Array): string;
 declare function newArtifactId(random?: (length: number) => Uint8Array): string;
 declare function assertArtifactId(value: string): string;
 declare function artifactVersionsPrefix(artifactId: string): string;
 /** Delegation resource for one version: a prefix, NO trailing slash. */
 declare function artifactVersionResource(artifactId: string, version: number): string;
 declare function artifactVersionFilePath(artifactId: string, version: number, filename: string): string;
-/** The artifact and version a stored KV path belongs to, if it is under a version directory. */
-declare function parseArtifactVersionPath(path: string): {
-    readonly artifactId: string;
-    readonly version: number;
-    readonly file: string;
-} | undefined;
 declare function manifestBytes(manifest: ArtifactManifest): Uint8Array;
 /**
  * Strict manifest parser. Unknown fields, duplicate paths and malformed
@@ -100,5 +107,18 @@ declare function listArtifactVersions(store: ArtifactStore, artifactId: string):
  *   is never reused, and a manifest lists the only files it vouches for.
  */
 declare function publishArtifactVersion(store: ArtifactStore, input: ArtifactVersionInput): Promise<ArtifactVersionResult>;
+/** The pin an owner signs for one stored file of a freshly published version. */
+declare function buildArtifactPin(version: ArtifactVersionResult, filename: string): ArtifactPin;
+/**
+ * For a holder of `manifest.json` (the owner, or a tool auditing a version): the bytes must hash to the pinned
+ * digest, parse strictly, and list the pinned file with the same digest and size.
+ */
+declare function verifyArtifactManifestBytes(pin: ArtifactPin, manifestBytes: Uint8Array): ArtifactManifest;
+/**
+ * The bytes fetched from the owner's KV (ciphertext, for an addressed share) must be the bytes the owner pinned.
+ * Audit and tooling check. The recipient does not call it: `assertArtifactBinding` ties the pin's digest to
+ * `contentSource.initialCiphertextDigestHex`, and `decryptV3Content` already refuses bytes that do not hash to that.
+ */
+declare function verifyArtifactFileBytes(pin: ArtifactPin, storedBytes: Uint8Array): void;
 
-export { ARTIFACT_MANIFEST_NAME, ARTIFACT_MANIFEST_VERSION, ARTIFACT_MAX_PUBLISH_ATTEMPTS, ARTIFACT_ROOT, ArtifactError, type ArtifactErrorCode, type ArtifactManifest, type ArtifactManifestFile, type ArtifactStore, type ArtifactVersionInput, type ArtifactVersionResult, type ArtifactVersionSummary, artifactVersionFilePath, artifactVersionResource, artifactVersionsPrefix, assertArtifactId, listArtifactVersions, manifestBytes, newArtifactId, parseArtifactManifest, parseArtifactVersionPath, publishArtifactVersion, sha256Hex };
+export { ARTIFACT_MANIFEST_NAME, ARTIFACT_MANIFEST_VERSION, ARTIFACT_MAX_PUBLISH_ATTEMPTS, ARTIFACT_ROOT, ArtifactError, type ArtifactErrorCode, type ArtifactManifest, type ArtifactManifestFile, type ArtifactStore, type ArtifactVersionInput, type ArtifactVersionResult, type ArtifactVersionSummary, artifactVersionFilePath, artifactVersionResource, artifactVersionsPrefix, assertArtifactId, buildArtifactPin, listArtifactVersions, manifestBytes, newArtifactId, parseArtifactManifest, parseArtifactVersionPath, publishArtifactVersion, sha256Hex, verifyArtifactFileBytes, verifyArtifactManifestBytes };

package/dist/artifact.d.ts

@@ -1,4 +1,18 @@
+import { ArtifactPin } from '@tinycloud/share-envelope';
+
+/**
+ * The few artifact helpers the browser bundles need (the pin verifier reads a version path). Kept
+ * apart from `artifact.ts`, which is CLI and agent tooling and must stay out of those bundles.
+ */
 declare const ARTIFACT_ROOT = "artifacts";
+/** The artifact and version a stored KV path belongs to, if it is under a version directory. */
+declare function parseArtifactVersionPath(path: string): {
+    readonly artifactId: string;
+    readonly version: number;
+    readonly file: string;
+} | undefined;
+
+declare function sha256Hex(bytes: Uint8Array): string;
 declare const ARTIFACT_MANIFEST_NAME = "manifest.json";
 declare const ARTIFACT_MANIFEST_VERSION: 1;
 /** A lost create race bumps `n`; this bounds how many times one publish retries. */
@@ -66,19 +80,12 @@ interface ArtifactVersionSummary {
     readonly manifest?: ArtifactManifest;
     readonly manifestSha256?: string;
 }
-declare function sha256Hex(bytes: Uint8Array): string;
 declare function newArtifactId(random?: (length: number) => Uint8Array): string;
 declare function assertArtifactId(value: string): string;
 declare function artifactVersionsPrefix(artifactId: string): string;
 /** Delegation resource for one version: a prefix, NO trailing slash. */
 declare function artifactVersionResource(artifactId: string, version: number): string;
 declare function artifactVersionFilePath(artifactId: string, version: number, filename: string): string;
-/** The artifact and version a stored KV path belongs to, if it is under a version directory. */
-declare function parseArtifactVersionPath(path: string): {
-    readonly artifactId: string;
-    readonly version: number;
-    readonly file: string;
-} | undefined;
 declare function manifestBytes(manifest: ArtifactManifest): Uint8Array;
 /**
  * Strict manifest parser. Unknown fields, duplicate paths and malformed
@@ -100,5 +107,18 @@ declare function listArtifactVersions(store: ArtifactStore, artifactId: string):
  *   is never reused, and a manifest lists the only files it vouches for.
  */
 declare function publishArtifactVersion(store: ArtifactStore, input: ArtifactVersionInput): Promise<ArtifactVersionResult>;
+/** The pin an owner signs for one stored file of a freshly published version. */
+declare function buildArtifactPin(version: ArtifactVersionResult, filename: string): ArtifactPin;
+/**
+ * For a holder of `manifest.json` (the owner, or a tool auditing a version): the bytes must hash to the pinned
+ * digest, parse strictly, and list the pinned file with the same digest and size.
+ */
+declare function verifyArtifactManifestBytes(pin: ArtifactPin, manifestBytes: Uint8Array): ArtifactManifest;
+/**
+ * The bytes fetched from the owner's KV (ciphertext, for an addressed share) must be the bytes the owner pinned.
+ * Audit and tooling check. The recipient does not call it: `assertArtifactBinding` ties the pin's digest to
+ * `contentSource.initialCiphertextDigestHex`, and `decryptV3Content` already refuses bytes that do not hash to that.
+ */
+declare function verifyArtifactFileBytes(pin: ArtifactPin, storedBytes: Uint8Array): void;
 
-export { ARTIFACT_MANIFEST_NAME, ARTIFACT_MANIFEST_VERSION, ARTIFACT_MAX_PUBLISH_ATTEMPTS, ARTIFACT_ROOT, ArtifactError, type ArtifactErrorCode, type ArtifactManifest, type ArtifactManifestFile, type ArtifactStore, type ArtifactVersionInput, type ArtifactVersionResult, type ArtifactVersionSummary, artifactVersionFilePath, artifactVersionResource, artifactVersionsPrefix, assertArtifactId, listArtifactVersions, manifestBytes, newArtifactId, parseArtifactManifest, parseArtifactVersionPath, publishArtifactVersion, sha256Hex };
+export { ARTIFACT_MANIFEST_NAME, ARTIFACT_MANIFEST_VERSION, ARTIFACT_MAX_PUBLISH_ATTEMPTS, ARTIFACT_ROOT, ArtifactError, type ArtifactErrorCode, type ArtifactManifest, type ArtifactManifestFile, type ArtifactStore, type ArtifactVersionInput, type ArtifactVersionResult, type ArtifactVersionSummary, artifactVersionFilePath, artifactVersionResource, artifactVersionsPrefix, assertArtifactId, buildArtifactPin, listArtifactVersions, manifestBytes, newArtifactId, parseArtifactManifest, parseArtifactVersionPath, publishArtifactVersion, sha256Hex, verifyArtifactFileBytes, verifyArtifactManifestBytes };

package/dist/artifact.js

@@ -4,9 +4,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/artifact.ts
-import { sha256 as sha2563 } from "@noble/hashes/sha256";
-
 // ../share-envelope/dist/index.js
 import { sha256 } from "@noble/hashes/sha2";
 import { ed25519 } from "@noble/curves/ed25519";
@@ -5289,6 +5286,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),
@@ -5308,7 +5319,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];
@@ -5407,6 +5424,17 @@ function canonicalize(value) {
 }
 var MAX_INLINE_BYTES = 256 * 1024;
 
+// src/artifact.ts
+import { sha256 as sha2563 } from "@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) {
@@ -5420,8 +5448,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(sha2563(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;
@@ -5435,9 +5476,6 @@ var ArtifactError = class extends Error {
     this.code = code2;
   }
 };
-function sha256Hex(bytes) {
-  return Array.from(sha2563(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("")}`;
 }
@@ -5460,11 +5498,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));
 }
@@ -5610,6 +5643,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");
+  }
+}
 export {
   ARTIFACT_MANIFEST_NAME,
   ARTIFACT_MANIFEST_VERSION,
@@ -5620,12 +5687,15 @@ export {
   artifactVersionResource,
   artifactVersionsPrefix,
   assertArtifactId,
+  buildArtifactPin,
   listArtifactVersions,
   manifestBytes,
   newArtifactId,
   parseArtifactManifest,
   parseArtifactVersionPath,
   publishArtifactVersion,
-  sha256Hex
+  sha256Hex,
+  verifyArtifactFileBytes,
+  verifyArtifactManifestBytes
 };
 //# sourceMappingURL=artifact.js.map