@serve.zone/interfaces 32.1.0 → 32.3.0

package/dist_ts/platform/storage.d.ts

@@ -1,3 +1,4 @@
+import type { TAppStoreStorageRequest } from '../appstore/types.js';
 import type { TSecretManagementScope } from '../data/secret.js';
 /**
  * Backend-neutral storage vocabulary shared by App Store manifests, control
@@ -142,8 +143,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 +185,44 @@ export interface IResolvedObjectStorageBinding extends IResolvedStorageBindingBa
     retentionDays?: number;
 }
 export type TResolvedStorageBinding = IResolvedFilesystemStorageBinding | IResolvedObjectStorageBinding;
+export declare class StorageContractError extends Error {
+    constructor(reasonArg: string);
+}
+/**
+ * The one judgement of what a storage request is: the request read against its exact schema and
+ * returned in its contract shape — required members present, optional members carried only when
+ * the request declares them, and every value within the bounds an adapter can fulfil.
+ *
+ * A control plane that admits requests, a fulfillment adapter that provisions them, and an App
+ * Store front end that assembles them all have to agree on the same acceptance rules; a second
+ * copy of them anywhere is a second answer to which requests exist, and the digest one side issues
+ * would name a request the other never accepted. `canonicalizeStorageRequest` and
+ * `createStorageRequestSha256` are derived from this function rather than the other way round, so
+ * a consumer that needs the judged request itself does not have to re-parse its own canonical
+ * bytes.
+ *
+ * The returned request is a fresh value; the input is never read again after normalization and
+ * never mutated. Anything that is not a storage request is refused with `StorageContractError`,
+ * whose message names the failing field so a consumer can map it to its own status vocabulary.
+ */
+export declare const normalizeStorageRequest: (valueArg: unknown) => TAppStoreStorageRequest;
+/**
+ * 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,58 @@
 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: readStorageRequest } = createStorageContractReaders(fail);
+/**
+ * The one judgement of what a storage request is: the request read against its exact schema and
+ * returned in its contract shape — required members present, optional members carried only when
+ * the request declares them, and every value within the bounds an adapter can fulfil.
+ *
+ * A control plane that admits requests, a fulfillment adapter that provisions them, and an App
+ * Store front end that assembles them all have to agree on the same acceptance rules; a second
+ * copy of them anywhere is a second answer to which requests exist, and the digest one side issues
+ * would name a request the other never accepted. `canonicalizeStorageRequest` and
+ * `createStorageRequestSha256` are derived from this function rather than the other way round, so
+ * a consumer that needs the judged request itself does not have to re-parse its own canonical
+ * bytes.
+ *
+ * The returned request is a fresh value; the input is never read again after normalization and
+ * never mutated. Anything that is not a storage request is refused with `StorageContractError`,
+ * whose message names the failing field so a consumer can map it to its own status vocabulary.
+ */
+export const normalizeStorageRequest = (valueArg) => {
+    return readStorageRequest(valueArg, 'storage request');
+};
+/**
+ * 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), 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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3BsYXRmb3JtL3N0b3JhZ2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBRUEsT0FBTyxFQUNMLHNCQUFzQixFQUN0Qiw0QkFBNEIsR0FDN0IsTUFBTSw2QkFBNkIsQ0FBQztBQUNyQyxPQUFPLEVBQUUsNEJBQTRCLEVBQUUsTUFBTSwrQkFBK0IsQ0FBQztBQVE3RTs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSxnQ0FBZ0MsR0FBRztJQUM5QyxhQUFhLEVBQUUsZUFBZTtDQUN0QixDQUFDO0FBaU9YLE1BQU0sT0FBTyxvQkFBcUIsU0FBUSxLQUFLO0lBQzdDLFlBQW1CLFNBQWlCO1FBQ2xDLEtBQUssQ0FBQywyQkFBMkIsU0FBUyxFQUFFLENBQUMsQ0FBQztRQUM5QyxJQUFJLENBQUMsSUFBSSxHQUFHLHNCQUFzQixDQUFDO0lBQ3JDLENBQUM7Q0FDRjtBQUVELE1BQU0sSUFBSSxHQUFHLENBQUMsU0FBaUIsRUFBUyxFQUFFO0lBQ3hDLE1BQU0sSUFBSSxvQkFBb0IsQ0FBQyxTQUFTLENBQUMsQ0FBQztBQUM1QyxDQUFDLENBQUM7QUFFRixNQUFNLEVBQUUsdUJBQXVCLEVBQUUsa0JBQWtCLEVBQUUsR0FDbkQsNEJBQTRCLENBQUMsSUFBSSxDQUFDLENBQUM7QUFFckM7Ozs7Ozs7Ozs7Ozs7Ozs7R0FnQkc7QUFDSCxNQUFNLENBQUMsTUFBTSx1QkFBdUIsR0FBRyxDQUNyQyxRQUFpQixFQUNRLEVBQUU7SUFDM0IsT0FBTyxrQkFBa0IsQ0FBQyxRQUFRLEVBQUUsaUJBQWlCLENBQUMsQ0FBQztBQUN6RCxDQUFDLENBQUM7QUFFRjs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQUcsQ0FBQyxRQUFpQixFQUFVLEVBQUU7SUFDdEUsT0FBTyxzQkFBc0IsQ0FBQyx1QkFBdUIsQ0FBQyxRQUFRLENBQUMsRUFBRSxJQUFJLENBQUMsQ0FBQztBQUN6RSxDQUFDLENBQUM7QUFFRjs7Ozs7Ozs7R0FRRztBQUNILE1BQU0sQ0FBQyxNQUFNLDBCQUEwQixHQUFHLEtBQUssRUFDN0MsUUFBaUIsRUFDQSxFQUFFO0lBQ25CLE9BQU8sNEJBQTRCLENBQUMsMEJBQTBCLENBQUMsUUFBUSxDQUFDLEVBQUUsSUFBSSxDQUFDLENBQUM7QUFDbEYsQ0FBQyxDQUFDO0FBRUYsT0FBTyxFQUNMLDBDQUEwQyxHQUUzQyxNQUFNLHFCQUFxQixDQUFDIn0=