@serve.zone/interfaces 32.1.0 → 32.2.0

package/changelog.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026-09-18 - 32.2.0
+
+### Features
+
+- Add `platform.createStorageRequestSha256(value)` and `platform.canonicalizeStorageRequest(value)`,
+  the contract's own statement of `IResolvedStorageBindingBase.requestDigest`: the request alone,
+  normalized to its contract shape, written as strict canonical JSON and hashed to bare lowercase
+  hex. A control plane issues that value on a binding and its consumer re-derives it, so both now
+  call one function instead of each deriving a value the other cannot reproduce — a prefix or a
+  wrapper object around the request is a different value for the same binding. Anything that is not
+  a storage request is refused with the new `platform.StorageContractError` rather than hashed.
+  `platform.storageRequestCanonicalDigestGoldenVectors` writes the digest down for a filesystem
+  request and for both object-storage deliveries.
+- The storage request normalizer is now one implementation for both kinds, shared by
+  `platform.storage` and `platform.storagemigration`, so
+  `createObjectStorageMigrationTargetRequestSha256` and `createStorageRequestSha256` cannot drift.
+  Migration contract errors keep their own class and messages.
+
 ## 2026-09-18 - 32.1.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '32.1.0',
+    version: '32.2.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/platform/storage.d.ts

@@ -142,8 +142,12 @@ export interface IResolvedStorageBindingBase {
     /** Stable App Store storageRequests[].id. */
     requestId: string;
     /**
-     * Canonical digest of the normalized request. Adapters use it to distinguish
-     * an idempotent reconciliation from a migration.
+     * Canonical digest of the normalized request, exactly as
+     * `createStorageRequestSha256` states it: bare lowercase hex over the request
+     * alone. Adapters use it to distinguish an idempotent reconciliation from a
+     * migration, and a consumer re-derives it to recognise the request it asked
+     * for, so the control plane and the consumer call that one function rather
+     * than each deriving a value the other cannot reproduce.
      */
     requestDigest: string;
     kind: TStorageResourceKind;
@@ -180,3 +184,26 @@ export interface IResolvedObjectStorageBinding extends IResolvedStorageBindingBa
     retentionDays?: number;
 }
 export type TResolvedStorageBinding = IResolvedFilesystemStorageBinding | IResolvedObjectStorageBinding;
+export declare class StorageContractError extends Error {
+    constructor(reasonArg: string);
+}
+/**
+ * The exact bytes a storage request's digest is taken over: the request normalized to its contract
+ * shape, written as strict canonical JSON — keys in UTF-16 code-unit order, no whitespace, no
+ * absent member carried as `null`.
+ *
+ * Anything that is not a storage request is refused rather than hashed, because a digest of an
+ * unjudged body would name a request no adapter could fulfil.
+ */
+export declare const canonicalizeStorageRequest: (valueArg: unknown) => string;
+/**
+ * The storage request digest: bare lowercase hex SHA-256 over the canonical request, with no
+ * prefix and nothing but the request in the hashed value.
+ *
+ * A control plane issues this value on a binding and a consumer re-derives it from the request it
+ * declared; the two only agree because they call this one function. A second derivation elsewhere
+ * — a prefix, or a wrapper object around the request — is a different value for the same binding,
+ * and the consumer would keep rejecting a binding that is in fact its own.
+ */
+export declare const createStorageRequestSha256: (valueArg: unknown) => Promise<string>;
+export { storageRequestCanonicalDigestGoldenVectors, type IStorageRequestCanonicalDigestGoldenVector, } from './storage.golden.js';

package/dist_ts/platform/storage.golden.d.ts

@@ -0,0 +1,31 @@
+import type { IAppStoreFilesystemStorageRequest, IAppStoreObjectStorageRequest } from '../appstore/types.js';
+export interface IStorageRequestCanonicalDigestGoldenVector<TInput> {
+    input: TInput;
+    canonicalJson: string;
+    sha256: string;
+}
+/**
+ * The storage request digest, written down for both kinds and both deliveries.
+ *
+ * A control plane and its consumer compare this value, so it is stated here as bytes rather than
+ * as whatever the current normalizer happens to produce: a member that starts or stops
+ * participating, an optional member that starts being carried when it is absent, or a delivery
+ * mode written as anything but its number would move these digests and be caught here.
+ */
+export declare const storageRequestCanonicalDigestGoldenVectors: {
+    filesystem: {
+        input: IAppStoreFilesystemStorageRequest;
+        canonicalJson: string;
+        sha256: string;
+    };
+    objectStorageLauncherEnvironment: {
+        input: IAppStoreObjectStorageRequest;
+        canonicalJson: string;
+        sha256: string;
+    };
+    objectStorageFile: {
+        input: IAppStoreObjectStorageRequest;
+        canonicalJson: string;
+        sha256: string;
+    };
+};

package/dist_ts/platform/storage.golden.js

@@ -0,0 +1,84 @@
+import { deepFreezeValue } from '../private/canonicaljson.js';
+const filesystemRequest = {
+    id: 'app-state',
+    kind: 'filesystem',
+    storageClass: 'databaseFast',
+    accessMode: 'ReadWriteOnce',
+    reclaimPolicy: 'delete',
+    mountPath: '/var/lib/app',
+    capacity: {
+        request: '20GiB',
+        limit: '40GiB',
+    },
+    protection: {
+        backup: 'required',
+        snapshots: 'portable',
+        consistency: 'applicationConsistent',
+    },
+};
+const objectStorageLauncherEnvironmentRequest = {
+    id: 'object-data',
+    kind: 'objectStorage',
+    storageClass: 'backupCapacity',
+    accessMode: 'readWrite',
+    reclaimPolicy: 'retain',
+    delivery: {
+        type: 'launcher-environment',
+        keys: {
+            endpoint: 'APP_S3_ENDPOINT',
+            bucket: 'APP_S3_BUCKET',
+            region: 'APP_S3_REGION',
+            accessKeyId: 'APP_S3_ACCESS_KEY',
+            secretAccessKey: 'APP_S3_SECRET_KEY',
+        },
+    },
+    capacity: {
+        request: '500GiB',
+    },
+    protection: {
+        backup: 'required',
+        versioning: 'required',
+        retentionDays: 30,
+    },
+};
+const objectStorageFileRequest = {
+    id: 'object-archive',
+    kind: 'objectStorage',
+    storageClass: 'archiveCapacity',
+    accessMode: 'readOnly',
+    reclaimPolicy: 'delete',
+    delivery: {
+        type: 'file',
+        targetPath: '/run/secrets/object-archive.json',
+        format: 'servezone-object-storage',
+        uid: 10_000,
+        gid: 10_000,
+        mode: 0o400,
+    },
+};
+/**
+ * The storage request digest, written down for both kinds and both deliveries.
+ *
+ * A control plane and its consumer compare this value, so it is stated here as bytes rather than
+ * as whatever the current normalizer happens to produce: a member that starts or stops
+ * participating, an optional member that starts being carried when it is absent, or a delivery
+ * mode written as anything but its number would move these digests and be caught here.
+ */
+export const storageRequestCanonicalDigestGoldenVectors = deepFreezeValue({
+    filesystem: {
+        input: filesystemRequest,
+        canonicalJson: '{"accessMode":"ReadWriteOnce","capacity":{"limit":"40GiB","request":"20GiB"},"id":"app-state","kind":"filesystem","mountPath":"/var/lib/app","protection":{"backup":"required","consistency":"applicationConsistent","snapshots":"portable"},"reclaimPolicy":"delete","storageClass":"databaseFast"}',
+        sha256: '0f8dc2e480ade7110be1f1d95f666cc56d5b90110d1c4a1b8b8383e2eeda6fae',
+    },
+    objectStorageLauncherEnvironment: {
+        input: objectStorageLauncherEnvironmentRequest,
+        canonicalJson: '{"accessMode":"readWrite","capacity":{"request":"500GiB"},"delivery":{"keys":{"accessKeyId":"APP_S3_ACCESS_KEY","bucket":"APP_S3_BUCKET","endpoint":"APP_S3_ENDPOINT","region":"APP_S3_REGION","secretAccessKey":"APP_S3_SECRET_KEY"},"type":"launcher-environment"},"id":"object-data","kind":"objectStorage","protection":{"backup":"required","retentionDays":30,"versioning":"required"},"reclaimPolicy":"retain","storageClass":"backupCapacity"}',
+        sha256: '88bd943800bea75b576612b966484e66ddbf7ec9529a7f29dd1eadc9a36e2b79',
+    },
+    objectStorageFile: {
+        input: objectStorageFileRequest,
+        canonicalJson: '{"accessMode":"readOnly","delivery":{"format":"servezone-object-storage","gid":10000,"mode":256,"targetPath":"/run/secrets/object-archive.json","type":"file","uid":10000},"id":"object-archive","kind":"objectStorage","reclaimPolicy":"delete","storageClass":"archiveCapacity"}',
+        sha256: '13186abbfe733b3917363e0694d367f2d6aa87a4064445532d7c857ee274f795',
+    },
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZS5nb2xkZW4uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9wbGF0Zm9ybS9zdG9yYWdlLmdvbGRlbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFJQSxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sNkJBQTZCLENBQUM7QUFROUQsTUFBTSxpQkFBaUIsR0FBc0M7SUFDM0QsRUFBRSxFQUFFLFdBQVc7SUFDZixJQUFJLEVBQUUsWUFBWTtJQUNsQixZQUFZLEVBQUUsY0FBYztJQUM1QixVQUFVLEVBQUUsZUFBZTtJQUMzQixhQUFhLEVBQUUsUUFBUTtJQUN2QixTQUFTLEVBQUUsY0FBYztJQUN6QixRQUFRLEVBQUU7UUFDUixPQUFPLEVBQUUsT0FBTztRQUNoQixLQUFLLEVBQUUsT0FBTztLQUNmO0lBQ0QsVUFBVSxFQUFFO1FBQ1YsTUFBTSxFQUFFLFVBQVU7UUFDbEIsU0FBUyxFQUFFLFVBQVU7UUFDckIsV0FBVyxFQUFFLHVCQUF1QjtLQUNyQztDQUNGLENBQUM7QUFFRixNQUFNLHVDQUF1QyxHQUFrQztJQUM3RSxFQUFFLEVBQUUsYUFBYTtJQUNqQixJQUFJLEVBQUUsZUFBZTtJQUNyQixZQUFZLEVBQUUsZ0JBQWdCO0lBQzlCLFVBQVUsRUFBRSxXQUFXO0lBQ3ZCLGFBQWEsRUFBRSxRQUFRO0lBQ3ZCLFFBQVEsRUFBRTtRQUNSLElBQUksRUFBRSxzQkFBc0I7UUFDNUIsSUFBSSxFQUFFO1lBQ0osUUFBUSxFQUFFLGlCQUFpQjtZQUMzQixNQUFNLEVBQUUsZUFBZTtZQUN2QixNQUFNLEVBQUUsZUFBZTtZQUN2QixXQUFXLEVBQUUsbUJBQW1CO1lBQ2hDLGVBQWUsRUFBRSxtQkFBbUI7U0FDckM7S0FDRjtJQUNELFFBQVEsRUFBRTtRQUNSLE9BQU8sRUFBRSxRQUFRO0tBQ2xCO0lBQ0QsVUFBVSxFQUFFO1FBQ1YsTUFBTSxFQUFFLFVBQVU7UUFDbEIsVUFBVSxFQUFFLFVBQVU7UUFDdEIsYUFBYSxFQUFFLEVBQUU7S0FDbEI7Q0FDRixDQUFDO0FBRUYsTUFBTSx3QkFBd0IsR0FBa0M7SUFDOUQsRUFBRSxFQUFFLGdCQUFnQjtJQUNwQixJQUFJLEVBQUUsZUFBZTtJQUNyQixZQUFZLEVBQUUsaUJBQWlCO0lBQy9CLFVBQVUsRUFBRSxVQUFVO0lBQ3RCLGFBQWEsRUFBRSxRQUFRO0lBQ3ZCLFFBQVEsRUFBRTtRQUNSLElBQUksRUFBRSxNQUFNO1FBQ1osVUFBVSxFQUFFLGtDQUFrQztRQUM5QyxNQUFNLEVBQUUsMEJBQTBCO1FBQ2xDLEdBQUcsRUFBRSxNQUFNO1FBQ1gsR0FBRyxFQUFFLE1BQU07UUFDWCxJQUFJLEVBQUUsS0FBSztLQUNaO0NBQ0YsQ0FBQztBQUVGOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLENBQUMsTUFBTSwwQ0FBMEMsR0FBRyxlQUFlLENBQUM7SUFDeEUsVUFBVSxFQUFFO1FBQ1YsS0FBSyxFQUFFLGlCQUFpQjtRQUN4QixhQUFhLEVBQUUsc1NBQXNTO1FBQ3JULE1BQU0sRUFBRSxrRUFBa0U7S0FDM0U7SUFDRCxnQ0FBZ0MsRUFBRTtRQUNoQyxLQUFLLEVBQUUsdUNBQXVDO1FBQzlDLGFBQWEsRUFBRSx3YkFBd2I7UUFDdmMsTUFBTSxFQUFFLGtFQUFrRTtLQUMzRTtJQUNELGlCQUFpQixFQUFFO1FBQ2pCLEtBQUssRUFBRSx3QkFBd0I7UUFDL0IsYUFBYSxFQUFFLG9SQUFvUjtRQUNuUyxNQUFNLEVBQUUsa0VBQWtFO0tBQzNFO0NBQ0YsQ0FBQyxDQUFDIn0=

package/dist_ts/platform/storage.js

@@ -1,3 +1,5 @@
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex, } from '../private/canonicaljson.js';
+import { createStorageContractReaders } from '../private/storagecontract.js';
 /**
  * Compatibility bridge for the existing generic platform capability. New
  * filesystem requests intentionally have no generic IPlatformBinding mapping.
@@ -5,4 +7,38 @@
 export const storageKindPlatformCapabilityIds = {
     objectStorage: 'objectstorage',
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3BsYXRmb3JtL3N0b3JhZ2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBUUE7OztHQUdHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sZ0NBQWdDLEdBQUc7SUFDOUMsYUFBYSxFQUFFLGVBQWU7Q0FDdEIsQ0FBQyJ9
+export class StorageContractError extends Error {
+    constructor(reasonArg) {
+        super(`storage contract error: ${reasonArg}`);
+        this.name = 'StorageContractError';
+    }
+}
+const fail = (reasonArg) => {
+    throw new StorageContractError(reasonArg);
+};
+const { normalizeStorageRequest } = createStorageContractReaders(fail);
+/**
+ * The exact bytes a storage request's digest is taken over: the request normalized to its contract
+ * shape, written as strict canonical JSON — keys in UTF-16 code-unit order, no whitespace, no
+ * absent member carried as `null`.
+ *
+ * Anything that is not a storage request is refused rather than hashed, because a digest of an
+ * unjudged body would name a request no adapter could fulfil.
+ */
+export const canonicalizeStorageRequest = (valueArg) => {
+    return canonicalizeStrictJson(normalizeStorageRequest(valueArg, 'storage request'), fail);
+};
+/**
+ * The storage request digest: bare lowercase hex SHA-256 over the canonical request, with no
+ * prefix and nothing but the request in the hashed value.
+ *
+ * A control plane issues this value on a binding and a consumer re-derives it from the request it
+ * declared; the two only agree because they call this one function. A second derivation elsewhere
+ * — a prefix, or a wrapper object around the request — is a different value for the same binding,
+ * and the consumer would keep rejecting a binding that is in fact its own.
+ */
+export const createStorageRequestSha256 = async (valueArg) => {
+    return createCanonicalJsonSha256Hex(canonicalizeStorageRequest(valueArg), fail);
+};
+export { storageRequestCanonicalDigestGoldenVectors, } from './storage.golden.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3BsYXRmb3JtL3N0b3JhZ2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUNMLHNCQUFzQixFQUN0Qiw0QkFBNEIsR0FDN0IsTUFBTSw2QkFBNkIsQ0FBQztBQUNyQyxPQUFPLEVBQUUsNEJBQTRCLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQVE3RTs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSxnQ0FBZ0MsR0FBRztJQUM5QyxhQUFhLEVBQUUsZUFBZTtDQUN0QixDQUFDO0FBaU9YLE1BQU0sT0FBTyxvQkFBcUIsU0FBUSxLQUFLO0lBQzdDLFlBQW1CLFNBQWlCO1FBQ2xDLEtBQUssQ0FBQywyQkFBMkIsU0FBUyxFQUFFLENBQUMsQ0FBQztRQUM5QyxJQUFJLENBQUMsSUFBSSxHQUFHLHNCQUFzQixDQUFDO0lBQ3JDLENBQUM7Q0FDRjtBQUVELE1BQU0sSUFBSSxHQUFHLENBQUMsU0FBaUIsRUFBUyxFQUFFO0lBQ3hDLE1BQU0sSUFBSSxvQkFBb0IsQ0FBQyxTQUFTLENBQUMsQ0FBQztBQUM1QyxDQUFDLENBQUM7QUFFRixNQUFNLEVBQUUsdUJBQXVCLEVBQUUsR0FBRyw0QkFBNEIsQ0FBQyxJQUFJLENBQUMsQ0FBQztBQUV2RTs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQUcsQ0FBQyxRQUFpQixFQUFVLEVBQUU7SUFDdEUsT0FBTyxzQkFBc0IsQ0FDM0IsdUJBQXVCLENBQUMsUUFBUSxFQUFFLGlCQUFpQixDQUFDLEVBQ3BELElBQUksQ0FDTCxDQUFDO0FBQ0osQ0FBQyxDQUFDO0FBRUY7Ozs7Ozs7O0dBUUc7QUFDSCxNQUFNLENBQUMsTUFBTSwwQkFBMEIsR0FBRyxLQUFLLEVBQzdDLFFBQWlCLEVBQ0EsRUFBRTtJQUNuQixPQUFPLDRCQUE0QixDQUFDLDBCQUEwQixDQUFDLFFBQVEsQ0FBQyxFQUFFLElBQUksQ0FBQyxDQUFDO0FBQ2xGLENBQUMsQ0FBQztBQUVGLE9BQU8sRUFDTCwwQ0FBMEMsR0FFM0MsTUFBTSxxQkFBcUIsQ0FBQyJ9