@byline/core 6.11.0 → 6.12.0

package/dist/@types/db-types.d.ts

@@ -3,6 +3,7 @@ import type { CollectionDefinition } from '@byline/core';
 import type { DbErrorClassification } from '../lib/errors.js';
 import type { ISchedulerStore } from '../scheduler/types.js';
 import type { DocumentRevisionStore } from './document-revision.js';
+import type { StorageValidator } from './storage-types.js';
 /**
  * Read mode for document queries.
  *
@@ -245,6 +246,11 @@ export interface IDbAdapter {
         audit: IAuditCommands;
         /** Singleton slot → document mapping writes. */
         singletons: ISingletonCommands;
+        /**
+         * Stored-file identity maintenance (backfill). Optional: an adapter
+         * without it cannot run `backfillStoredFileIdentity`.
+         */
+        storedFiles?: IStoredFileCommands;
     };
     queries: {
         collections: ICollectionQueries;
@@ -253,6 +259,8 @@ export interface IDbAdapter {
         audit: IAuditQueries;
         /** Singleton slot → document mapping reads. */
         singletons: ISingletonQueries;
+        /** Stored-file identity maintenance reads (backfill). Optional. */
+        storedFiles?: IStoredFileQueries;
     };
     /**
      * Run `fn` inside a single database transaction so the
@@ -549,6 +557,66 @@ export interface ISingletonQueries {
      */
     getMappedDocumentId(collectionId: string): Promise<string | null>;
 }
+/**
+ * Selection for `IStoredFileQueries.listStoredFilePaths`. `limit` counts
+ * distinct storage paths, never rows or hash groups, so one path's groups are
+ * never split across pages.
+ */
+export interface ListStoredFilePathsParams {
+    /** Only rows written by this provider (`byline_store_file.storage_provider`). */
+    storageProvider: string;
+    /** Only rows of this collection, when set. */
+    collectionId?: string;
+    /** `'missing'`: rows with no content hash. `'present'`: rows with one. */
+    identity: 'missing' | 'present';
+    /** Keyset cursor: only paths ordered strictly after this one. */
+    afterPath?: string;
+    /** Maximum number of distinct paths to return. */
+    limit: number;
+}
+/** One storage path and, for `identity: 'present'`, every recorded hash on it. */
+export interface StoredFilePathGroup {
+    storagePath: string;
+    /**
+     * Distinct recorded hashes on this path with the number of rows carrying
+     * each. Empty for `identity: 'missing'`. More than one entry means older
+     * versions recorded bytes that were later replaced at the same path.
+     */
+    hashes: Array<{
+        fileHash: string;
+        rowCount: number;
+    }>;
+}
+/**
+ * Maintenance reads over `byline_store_file` for stored-file identity
+ * backfill and verification. Direct storage primitives: they bypass
+ * collection auth and hooks, like every `db.queries.*` call.
+ */
+export interface IStoredFileQueries {
+    /**
+     * Distinct storage paths in ascending byte order. Paths, provider names and
+     * digests compare exactly — bytes, not collation: paths that differ only in
+     * case, accents or trailing spaces are distinct, and `'LOCAL'` is not
+     * `'local'`. Adapters must not apply case folding or space padding.
+     */
+    listStoredFilePaths(params: ListStoredFilePathsParams): Promise<StoredFilePathGroup[]>;
+}
+/** Maintenance writes over `byline_store_file` for stored-file identity backfill. */
+export interface IStoredFileCommands {
+    /**
+     * Record `fileHash` and `storageValidator` on every row for this provider
+     * and path (and collection, when set) whose `file_hash` is still NULL.
+     * Never overwrites a recorded hash, so repeating it is harmless. Returns the
+     * number of rows updated.
+     */
+    setIdentityForPath(params: {
+        storageProvider: string;
+        storagePath: string;
+        collectionId?: string;
+        fileHash: string;
+        storageValidator: StorageValidator;
+    }): Promise<number>;
+}
 /** Locked structural state returned by tree mutation commands. */
 export interface TreePlacementState {
     placed: boolean;

package/dist/@types/field-data-types.d.ts

@@ -7,6 +7,7 @@
  */
 import type { ArrayField, BlocksField, Field, FieldSet, GroupField, LocalizedField, OptionalField, RelationField, SelectField } from './field-types.js';
 import type { RelatedDocumentValue } from './relation-types.js';
+import type { StorageValidator } from './storage-types.js';
 import type { Prettify, ValueUnion } from './type-utils.js';
 /**
  * Structural type for any JSON-serializable value. Used as the type for
@@ -116,7 +117,23 @@ export interface StoredFileValue {
     storageProvider: string;
     storagePath: string;
     storageUrl?: string;
+    /**
+     * Content hash of the original object: SHA-256 of the bytes Byline passed
+     * to `IStorageProvider.upload()`, which providers store verbatim, as 64
+     * lower-case hexadecimal characters. Image variants are not covered.
+     *
+     * Recorded once, at upload or backfill time, and describes the bytes
+     * observed then; `storageValidator` is how a consumer detects that the
+     * object has since changed. Absent (never an empty string) when unknown — a
+     * consumer that requires identity must treat absence as an error.
+     */
     fileHash?: string;
+    /**
+     * Validator of the stored version that `fileHash` was computed from, when
+     * the provider issued one. Never compared with `fileHash`; see
+     * `StorageValidator`.
+     */
+    storageValidator?: StorageValidator;
     imageWidth?: number;
     imageHeight?: number;
     imageFormat?: string;

package/dist/@types/storage-types.d.ts

@@ -21,7 +21,75 @@ export interface StoredFileLocation {
      * signed S3 URLs generated at read-time).
      */
     storageUrl: string | null;
+    /**
+     * Validator of the stored version of the object, when the provider issues
+     * one. Absent when the provider has no usable validator for this write.
+     * See {@link StorageValidator}.
+     */
+    storageValidator?: StorageValidator;
+}
+/**
+ * An opaque token a storage provider issues for one stored version of an
+ * object — an S3 version id or ETag, or a local file's device, inode,
+ * modification time and size.
+ *
+ * A validator identifies a *stored version*, not content. Its only use is
+ * equality: "is the object at this path still the version I recorded?"
+ * Two validators match only when both `kind` and `value` are equal; a
+ * validator of a different `kind` is unknown, never "changed".
+ *
+ * A validator is never compared with `StoredFileValue.fileHash`. An ETag is
+ * not a content digest: multipart uploads and server-side encryption give
+ * ETags that are not the MD5 of the object.
+ *
+ * `kind` is 1–32 characters; `value` is 1–1024 characters.
+ */
+export interface StorageValidator {
+    kind: string;
+    value: string;
+}
+/** Result of a bound read — see `IStorageProvider.download`. */
+export interface StoredObjectRead {
+    /** The object's bytes, streamed. */
+    body: NodeJS.ReadableStream;
+    /**
+     * Validator of exactly the bytes in `body`, taken from the same request or
+     * the same open file handle. This is the provider's canonical validator and
+     * may be of a different kind from a `download` `expect`.
+     */
+    validator: StorageValidator;
+    /** Object size in bytes, when the provider reports it. */
+    size?: number;
+}
+/** Options for `IStorageProvider.download`. */
+export interface StorageDownloadOptions {
+    /**
+     * Fail-closed precondition. The provider exposes the body only when it has
+     * established that the current object carries a token of `expect.kind`
+     * equal to `expect.value`; otherwise it rejects with
+     * `ERR_STORAGE_PRECONDITION` and exposes nothing.
+     */
+    expect?: StorageValidator;
+    /** Abort the read. The provider disposes of any open body or handle. */
+    signal?: AbortSignal;
+}
+/** Result of `IStorageProvider.head`. */
+export interface StoredObjectHead {
+    validator: StorageValidator;
+    size?: number;
 }
+/**
+ * Reasons carried in `details.reason` of an `ERR_STORAGE_PRECONDITION` error.
+ *
+ * - `changed` — the provider established that the current object's token of
+ *   the expected kind differs.
+ * - `unsupported-kind` — the provider does not issue validators of the
+ *   expected kind. Checked before any request.
+ * - `unestablishable` — the kind is supported, but the response lacks a usable
+ *   token of that kind.
+ * - `missing` — no object exists at the path.
+ */
+export type StoragePreconditionReason = 'changed' | 'unsupported-kind' | 'unestablishable' | 'missing';
 /**
  * Options passed to `IStorageProvider.upload()` describing the file being
  * stored.
@@ -93,7 +161,13 @@ export interface IStorageProvider {
     readonly providerName: string;
     /**
      * Store a file. The `stream` may be a Node.js `Readable` or a raw `Buffer`.
-     * Returns the location metadata to be recorded alongside the file entry.
+     * Returns the location metadata to be recorded alongside the file entry,
+     * including the stored version's validator when the provider issues one.
+     *
+     * Providers must store the bytes verbatim: no compression, transcoding or
+     * other transform. Byline's content hash (`StoredFileValue.fileHash`) is
+     * computed over the bytes passed here and relies on them being the bytes
+     * stored. A stream must be consumed to its end before the promise resolves.
      */
     upload(stream: NodeJS.ReadableStream | Buffer, options: UploadFileOptions): Promise<StoredFileLocation>;
     /**
@@ -131,4 +205,38 @@ export interface IStorageProvider {
      * **Optional capability** — see `move`.
      */
     exists?(storagePath: string): Promise<boolean>;
+    /**
+     * Bound read: stream the object and return the validator of exactly the
+     * bytes streamed, taken from the same request or the same open file
+     * handle. The returned validator is the provider's canonical one and may be
+     * of a different kind from `expect`.
+     *
+     * Without `expect`: resolves `null` when no object exists at the path, and
+     * fails with `ERR_STORAGE` (`details.reason: 'validator-unavailable'`) when
+     * the object has no usable validator. A bound read never returns bytes
+     * without a validator.
+     *
+     * With `expect`: exposes the body only when a token of `expect.kind` equal
+     * to `expect.value` is established; otherwise fails with
+     * `ERR_STORAGE_PRECONDITION` (see {@link StoragePreconditionReason}) and
+     * exposes nothing.
+     *
+     * On every rejection after a response or handle exists, the provider
+     * disposes of it before throwing.
+     *
+     * **Optional capability** — see `move`.
+     */
+    download?(storagePath: string, options?: StorageDownloadOptions): Promise<StoredObjectRead | null>;
+    /**
+     * Cheap change probe: the current object's validator and size. Resolves
+     * `null` when no object exists; fails with `ERR_STORAGE`
+     * (`validator-unavailable`) for a present object without a usable
+     * validator.
+     *
+     * Not a provenance source — the object can change after `head` returns.
+     * Use `download` when bytes must be paired with their validator.
+     *
+     * **Optional capability** — see `move`.
+     */
+    head?(storagePath: string): Promise<StoredObjectHead | null>;
 }

package/dist/@types/store-types.d.ts

@@ -58,6 +58,9 @@ export interface FileStore extends BaseStore {
     storage_path: string;
     storage_url?: string;
     file_hash?: string;
+    /** Storage validator, persisted as a pair; both null when unknown. */
+    storage_validator_kind?: string;
+    storage_validator_value?: string;
     image_width?: number;
     image_height?: number;
     image_format?: string;

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { resolvePasskeyConfig } from './config/validate-passkey-config.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_STORAGE_PRECONDITION, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { type BylineLogger, getLogger } from './lib/logger.js';
 export { AsyncRegistry, type RegisteredServices, Registry } from './lib/registry.js';

package/dist/index.js

@@ -21,7 +21,7 @@ export { resolvePasskeyConfig } from './config/validate-passkey-config.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_DOCUMENT_HOOK_COMMITTED, ERR_DOCUMENT_STALE, ERR_LOCK_CONFLICT, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_STORAGE_PRECONDITION, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, getLockConflictDetails, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';

package/dist/lib/errors.d.ts

@@ -86,6 +86,7 @@ export declare const ErrorCodes: {
     readonly DATABASE: 'ERR_DATABASE';
     readonly LOCK_CONFLICT: 'ERR_LOCK_CONFLICT';
     readonly STORAGE: 'ERR_STORAGE';
+    readonly STORAGE_PRECONDITION: 'ERR_STORAGE_PRECONDITION';
     readonly READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED';
     readonly READ_RECURSION: 'ERR_READ_RECURSION';
     readonly PATH_CONFLICT: 'ERR_PATH_CONFLICT';
@@ -119,6 +120,13 @@ export declare function getLockConflictDetails(error: unknown): {
     retryable: true;
 } | null;
 export declare const ERR_STORAGE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * A storage read precondition (`IStorageProvider.download` `expect`) was not
+ * established. `details.reason` is a `StoragePreconditionReason`: a proven
+ * change (`changed`) is distinct from an expectation that could not be checked
+ * (`unsupported-kind`, `unestablishable`) and from a missing object.
+ */
+export declare const ERR_STORAGE_PRECONDITION: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_READ_BUDGET_EXCEEDED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_READ_RECURSION: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 /**

package/dist/lib/errors.js

@@ -119,6 +119,7 @@ export const ErrorCodes = {
     DATABASE: 'ERR_DATABASE',
     LOCK_CONFLICT: 'ERR_LOCK_CONFLICT',
     STORAGE: 'ERR_STORAGE',
+    STORAGE_PRECONDITION: 'ERR_STORAGE_PRECONDITION',
     READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED',
     READ_RECURSION: 'ERR_READ_RECURSION',
     PATH_CONFLICT: 'ERR_PATH_CONFLICT',
@@ -173,6 +174,13 @@ export function getLockConflictDetails(error) {
     }
 }
 export const ERR_STORAGE = createErrorType(ErrorCodes.STORAGE);
+/**
+ * A storage read precondition (`IStorageProvider.download` `expect`) was not
+ * established. `details.reason` is a `StoragePreconditionReason`: a proven
+ * change (`changed`) is distinct from an expectation that could not be checked
+ * (`unsupported-kind`, `unestablishable`) and from a missing object.
+ */
+export const ERR_STORAGE_PRECONDITION = createErrorType(ErrorCodes.STORAGE_PRECONDITION, 'warn');
 export const ERR_READ_BUDGET_EXCEEDED = createErrorType(ErrorCodes.READ_BUDGET_EXCEEDED);
 export const ERR_READ_RECURSION = createErrorType(ErrorCodes.READ_RECURSION);
 /**

package/dist/schemas/zod/builder.js

@@ -1,6 +1,7 @@
 import * as z from 'zod';
 import { REQUIRED_WORKFLOW_STATUSES } from '../../@types/index.js';
 import { getCollectionDefinition } from '../../config/config.js';
+import { CONTENT_HASH_PATTERN, STORAGE_VALIDATOR_LIMITS } from '../../storage/content-hash.js';
 // Helper function to apply custom validation rules
 const applyValidationRules = (schema, rules) => {
     return rules.reduce((acc, rule) => {
@@ -170,7 +171,15 @@ export const fieldToZodSchema = (field, strict = true) => {
                 storageProvider: z.string(),
                 storagePath: z.string(),
                 storageUrl: z.string().nullable().optional(),
-                fileHash: z.string().nullable().optional(),
+                // Content identity: absent when unknown, never an empty string.
+                fileHash: z.string().regex(CONTENT_HASH_PATTERN).nullable().optional(),
+                storageValidator: z
+                    .object({
+                    kind: z.string().min(1).max(STORAGE_VALIDATOR_LIMITS.kind),
+                    value: z.string().min(1).max(STORAGE_VALIDATOR_LIMITS.value),
+                })
+                    .nullable()
+                    .optional(),
                 imageWidth: z.number().nullable().optional(),
                 imageHeight: z.number().nullable().optional(),
                 imageFormat: z.string().nullable().optional(),

package/dist/services/field-upload.js

@@ -9,6 +9,7 @@ import { isSingleton, resolveUploadHooks } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_DATABASE, ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
+import { sha256Hex } from '../storage/content-hash.js';
 import { resolveUploadFilename } from '../utils/slugify-filename.js';
 import { createDocument, getDocumentHookCommittedDetails, } from './document-lifecycle/index.js';
 function isMimeTypeAllowed(mimeType, allowedTypes) {
@@ -220,6 +221,22 @@ export async function uploadField(ctx, params) {
         //    `targetStoragePath`, which providers write verbatim (no UUID
         //    prefix / key derivation) — variants still derive sibling paths
         //    from the resulting `storedFile.storagePath`.
+        // -- Content identity. The upload arrives as an in-memory buffer, so
+        //    hashing it reads no bytes from storage. Providers store bytes
+        //    verbatim, so this is also the hash of the stored original.
+        if (buffer.length !== fileSize) {
+            throw ERR_VALIDATION({
+                message: `Upload is ${buffer.length} bytes but declared ${fileSize} bytes.`,
+                details: {
+                    collectionPath,
+                    fieldName,
+                    reason: 'size-mismatch',
+                    actualSize: buffer.length,
+                    declaredSize: fileSize,
+                },
+            }, uploadField).log(logger);
+        }
+        const fileHash = await sha256Hex(buffer);
         let storedFile;
         try {
             storedFile = await storage.upload(buffer, {
@@ -284,7 +301,8 @@ export async function uploadField(ctx, params) {
             storageProvider: storedFile.storageProvider,
             storagePath: storedFile.storagePath,
             storageUrl: storedFile.storageUrl ?? undefined,
-            fileHash: undefined,
+            fileHash,
+            ...(storedFile.storageValidator && { storageValidator: storedFile.storageValidator }),
             imageWidth: imageMeta.width ?? undefined,
             imageHeight: imageMeta.height ?? undefined,
             imageFormat: imageMeta.format ?? undefined,

package/dist/services/field-upload.test.node.js

@@ -656,3 +656,53 @@ describe('uploadField service', () => {
         expect(del).toHaveBeenNthCalledWith(3, 'media/card.webp');
     });
 });
+describe('uploadField content identity', () => {
+    it('records the SHA-256 of the uploaded bytes and the provider validator', async () => {
+        const { ctx, upload } = buildCtx();
+        upload.mockResolvedValueOnce({
+            storageProvider: 'local',
+            storagePath: 'media/original.png',
+            storageUrl: '/uploads/media/original.png',
+            storageValidator: { kind: 'local-stat', value: '1:2:3:3' },
+        });
+        const { createHash } = await import('node:crypto');
+        const expected = createHash('sha256').update(Buffer.from('png')).digest('hex');
+        const result = await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        expect(result.storedFile.fileHash).toBe(expected);
+        expect(result.storedFile.fileHash).toMatch(/^[0-9a-f]{64}$/);
+        expect(result.storedFile.storageValidator).toEqual({ kind: 'local-stat', value: '1:2:3:3' });
+    });
+    it('omits storageValidator when the provider issues none, but still records the hash', async () => {
+        const { ctx } = buildCtx();
+        const result = await uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        });
+        expect(result.storedFile.fileHash).toMatch(/^[0-9a-f]{64}$/);
+        expect('storageValidator' in result.storedFile).toBe(false);
+    });
+    it('rejects a buffer whose length differs from the declared size before writing bytes', async () => {
+        const { ctx, upload, storedPaths } = buildCtx();
+        await expect(uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 4,
+            shouldCreateDocument: false,
+        })).rejects.toMatchObject({
+            code: ErrorCodes.VALIDATION,
+            details: expect.objectContaining({ reason: 'size-mismatch', actualSize: 3, declaredSize: 4 }),
+        });
+        expect(upload).not.toHaveBeenCalled();
+        expect(storedPaths.size).toBe(0);
+    });
+});

package/dist/storage/content-hash.d.ts

@@ -0,0 +1,23 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { StorageValidator } from '../@types/storage-types.js';
+/** A `StoredFileValue.fileHash`: SHA-256 as 64 lower-case hexadecimal characters. */
+export declare const CONTENT_HASH_PATTERN: RegExp;
+/** Upper bounds for `StorageValidator` members. */
+export declare const STORAGE_VALIDATOR_LIMITS: {
+    readonly kind: 32;
+    readonly value: 1024;
+};
+/** SHA-256 of an in-memory byte sequence, as lower-case hex. */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * Exact validator equality: both `kind` and `value` must match. Validators of
+ * different kinds are not comparable, so this returns `false` for them — the
+ * caller must treat that as "unknown", not "changed".
+ */
+export declare function isSameStorageValidator(a: StorageValidator, b: StorageValidator): boolean;

package/dist/storage/content-hash.js

@@ -0,0 +1,26 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/** A `StoredFileValue.fileHash`: SHA-256 as 64 lower-case hexadecimal characters. */
+export const CONTENT_HASH_PATTERN = /^[0-9a-f]{64}$/;
+/** Upper bounds for `StorageValidator` members. */
+export const STORAGE_VALIDATOR_LIMITS = { kind: 32, value: 1024 };
+/** SHA-256 of an in-memory byte sequence, as lower-case hex. */
+export async function sha256Hex(bytes) {
+    // Copy into a plain ArrayBuffer view: `digest` rejects SharedArrayBuffer-backed
+    // views, and a Node Buffer may be a slice of a larger pooled allocation.
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new Uint8Array(bytes));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Exact validator equality: both `kind` and `value` must match. Validators of
+ * different kinds are not comparable, so this returns `false` for them — the
+ * caller must treat that as "unknown", not "changed".
+ */
+export function isSameStorageValidator(a, b) {
+    return a.kind === b.kind && a.value === b.value;
+}

package/dist/storage/content-hash.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/storage/content-hash.test.node.js

@@ -0,0 +1,67 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { fieldToZodSchema } from '../schemas/zod/builder.js';
+import { CONTENT_HASH_PATTERN, isSameStorageValidator, sha256Hex } from './content-hash.js';
+// FIPS 180-2 test vectors.
+const ABC_SHA256 = 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad';
+const EMPTY_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
+describe('content hash helpers', () => {
+    it('computes SHA-256 as lower-case hex', async () => {
+        expect(await sha256Hex(new TextEncoder().encode('abc'))).toBe(ABC_SHA256);
+        expect(await sha256Hex(new Uint8Array())).toBe(EMPTY_SHA256);
+    });
+    it('hashes only the viewed bytes of a sliced Buffer', async () => {
+        const pooled = Buffer.from('xxabcxx');
+        expect(await sha256Hex(pooled.subarray(2, 5))).toBe(ABC_SHA256);
+    });
+    it('compares validators by exact kind and value', () => {
+        const a = { kind: 's3-etag', value: 'abc' };
+        expect(isSameStorageValidator(a, { kind: 's3-etag', value: 'abc' })).toBe(true);
+        expect(isSameStorageValidator(a, { kind: 's3-etag', value: 'abd' })).toBe(false);
+        expect(isSameStorageValidator(a, { kind: 's3-version', value: 'abc' })).toBe(false);
+    });
+    it('matches only 64 lower-case hex characters', () => {
+        expect(CONTENT_HASH_PATTERN.test(ABC_SHA256)).toBe(true);
+        expect(CONTENT_HASH_PATTERN.test(ABC_SHA256.toUpperCase())).toBe(false);
+        expect(CONTENT_HASH_PATTERN.test(ABC_SHA256.slice(1))).toBe(false);
+        expect(CONTENT_HASH_PATTERN.test('')).toBe(false);
+    });
+});
+describe('stored-file Zod rules', () => {
+    const schema = fieldToZodSchema({ name: 'file', label: 'File', type: 'file' });
+    const base = {
+        fileId: 'f1',
+        filename: 'a.pdf',
+        originalFilename: 'a.pdf',
+        mimeType: 'application/pdf',
+        fileSize: 3,
+        storageProvider: 'local',
+        storagePath: 'media/a.pdf',
+        processingStatus: 'complete',
+    };
+    it('accepts an absent, null or well-formed hash and validator', () => {
+        expect(schema.safeParse(base).success).toBe(true);
+        expect(schema.safeParse({ ...base, fileHash: null, storageValidator: null }).success).toBe(true);
+        expect(schema.safeParse({
+            ...base,
+            fileHash: ABC_SHA256,
+            storageValidator: { kind: 's3-etag', value: 'abc' },
+        }).success).toBe(true);
+    });
+    it('rejects an empty or malformed hash', () => {
+        expect(schema.safeParse({ ...base, fileHash: '' }).success).toBe(false);
+        expect(schema.safeParse({ ...base, fileHash: ABC_SHA256.toUpperCase() }).success).toBe(false);
+        expect(schema.safeParse({ ...base, fileHash: ABC_SHA256.slice(2) }).success).toBe(false);
+    });
+    it('rejects an empty or oversized validator', () => {
+        expect(schema.safeParse({ ...base, storageValidator: { kind: '', value: 'x' } }).success).toBe(false);
+        expect(schema.safeParse({ ...base, storageValidator: { kind: 'k', value: '' } }).success).toBe(false);
+        expect(schema.safeParse({ ...base, storageValidator: { kind: 'k'.repeat(33), value: 'x' } }).success).toBe(false);
+    });
+});

package/dist/storage/index.d.ts

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { fingerprintCollection } from './collection-fingerprint.js';
+export { CONTENT_HASH_PATTERN, isSameStorageValidator } from './content-hash.js';
 export { assertDocumentVersionParent, type DocumentVersionParentAssertion, type DocumentVersionParentConflictReason, } from './document-version-parent.js';
 export { ALL_STORE_TYPES, type FieldStoreKind, type FieldStoreMapping, fieldTypeToStore, fieldTypeToStoreType, type StoreType, } from './field-store-map.js';
 export { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, type VersionLocaleLedger, } from './locale-resolution.js';

package/dist/storage/index.js

@@ -6,6 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { fingerprintCollection } from './collection-fingerprint.js';
+export { CONTENT_HASH_PATTERN, isSameStorageValidator } from './content-hash.js';
 export { assertDocumentVersionParent, } from './document-version-parent.js';
 export { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, } from './field-store-map.js';
 export { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, } from './locale-resolution.js';