@serve.zone/interfaces 17.4.0 → 17.5.0

package/changelog.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2026-07-23 - 17.5.0
+
+### Features
+
+- add portable named filesystem and object-storage App Store request contracts
+- add backend-neutral storage capability advertisements and resolved binding lifecycle contracts
+- keep physical backend configuration and credential values outside portable and resolved public storage DTOs
+
 ## 2026-07-23 - 17.4.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/appstore/types.d.ts

@@ -1,9 +1,72 @@
 import type { IServiceSecretFile } from '../data/service.js';
 import type { IServiceDomainRoute, IServicePublicPortMapping, IServiceTargetPort } from '../data/serviceports.js';
+import type { IStorageCapacityRequest, IStorageClassRequirement, TFilesystemStorageAccessMode, TObjectStorageAccessMode, TObjectStorageDelivery, TStorageReclaimPolicy, TStorageResourceKind, TStorageSnapshotMode } from '../platform/storage.js';
 export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
+export interface IAppStorePlatformRequirements {
+    mongodb?: boolean;
+    /**
+     * @deprecated `s3: true` is normalized to one legacy object-storage binding.
+     * New templates use a named objectStorage request.
+     */
+    s3?: boolean;
+    clickhouse?: boolean;
+    valkey?: boolean;
+    mariadb?: boolean;
+}
 export type TAppStoreSourceType = 'inline' | 'repoManifest' | 'dockerImage';
 export type TAppStoreTrackingMode = 'tag' | 'digest';
 export type TAppStoreUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';
+export declare const appStoreStorageFeatureIds: {
+    readonly bindingsV1: "storage.bindings.v1";
+    readonly filesystemV1: "storage.filesystem.v1";
+    readonly objectStorageV1: "storage.object-storage.v1";
+    readonly objectStorageSecretFileV1: "storage.object-storage.secret-file.v1";
+};
+export type TAppStoreStorageFeatureId = typeof appStoreStorageFeatureIds[keyof typeof appStoreStorageFeatureIds];
+export type TAppStoreStoragePurpose = 'runtime' | 'database' | 'registry' | 'backup';
+/**
+ * A template-local logical class. It states portable policy requirements and
+ * preferences; fulfillment adapters select their own compatible policy class.
+ */
+export interface IAppStoreStorageClass {
+    kind: TStorageResourceKind;
+    purpose: TAppStoreStoragePurpose;
+    required?: IStorageClassRequirement;
+    preferred?: IStorageClassRequirement;
+}
+export interface IAppStoreStorageRequestBase {
+    /** Stable identity used across upgrades, migrations, and restores. */
+    id: string;
+    kind: TStorageResourceKind;
+    /** Key in the containing version config's storageClasses record. */
+    storageClass: string;
+    capacity?: IStorageCapacityRequest;
+    reclaimPolicy: TStorageReclaimPolicy;
+}
+export interface IAppStoreFilesystemProtection {
+    backup?: 'required';
+    snapshots?: Exclude<TStorageSnapshotMode, 'none'>;
+    consistency?: 'crashConsistent' | 'applicationConsistent';
+}
+export interface IAppStoreFilesystemStorageRequest extends IAppStoreStorageRequestBase {
+    kind: 'filesystem';
+    mountPath: string;
+    accessMode: TFilesystemStorageAccessMode;
+    protection?: IAppStoreFilesystemProtection;
+}
+export interface IAppStoreObjectStorageProtection {
+    backup?: 'required';
+    versioning?: 'required';
+    /** Minimum provider-enforced retention duration. */
+    retentionDays?: number;
+}
+export interface IAppStoreObjectStorageRequest extends IAppStoreStorageRequestBase {
+    kind: 'objectStorage';
+    accessMode: TObjectStorageAccessMode;
+    delivery: TObjectStorageDelivery;
+    protection?: IAppStoreObjectStorageProtection;
+}
+export type TAppStoreStorageRequest = IAppStoreFilesystemStorageRequest | IAppStoreObjectStorageRequest;
 export interface IAppStoreInlineSource {
     type: 'inline';
 }
@@ -119,9 +182,21 @@ export interface IAppStoreVersionConfig {
     /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker publishedPorts. */
     publicPortMappings?: IServicePublicPortMapping[];
     envVars?: IAppStoreEnvVar[];
+    /**
+     * @deprecated Legacy volume syntax. New templates use storageClasses and
+     * storageRequests. Resolver normalization must reject legacy physical driver
+     * options that cannot be represented portably.
+     */
     volumes?: TAppStoreVolumeSpec[];
+    /**
+     * Template-local logical policy classes. Keys are stable within the
+     * template; they are not Onebox or Cloudly operator class names.
+     */
+    storageClasses?: Record<string, IAppStoreStorageClass>;
+    /** Stable named filesystem and managed object-storage requests. */
+    storageRequests?: TAppStoreStorageRequest[];
     publishedPorts?: IAppStorePublishedPort[];
-    platformRequirements?: Partial<Record<TAppStorePlatformRequirement, boolean>>;
+    platformRequirements?: IAppStorePlatformRequirements;
     minOneboxVersion?: string;
     minCloudlyVersion?: string;
     appStoreVersion?: string;

package/dist_ts/appstore/types.js

@@ -1,2 +1,7 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9hcHBzdG9yZS90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=
+export const appStoreStorageFeatureIds = {
+    bindingsV1: 'storage.bindings.v1',
+    filesystemV1: 'storage.filesystem.v1',
+    objectStorageV1: 'storage.object-storage.v1',
+    objectStorageSecretFileV1: 'storage.object-storage.secret-file.v1',
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9hcHBzdG9yZS90eXBlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFpQ0EsTUFBTSxDQUFDLE1BQU0seUJBQXlCLEdBQUc7SUFDdkMsVUFBVSxFQUFFLHFCQUFxQjtJQUNqQyxZQUFZLEVBQUUsdUJBQXVCO0lBQ3JDLGVBQWUsRUFBRSwyQkFBMkI7SUFDNUMseUJBQXlCLEVBQUUsdUNBQXVDO0NBQzFELENBQUMifQ==

package/dist_ts/platform/index.d.ts

@@ -8,6 +8,8 @@ import * as objectstorage from './objectstorage.js';
 import * as pushnotification from './pushnotification.js';
 import * as sip from './sip.js';
 import * as sms from './sms.js';
+import * as storage from './storage.js';
 import * as types from './types.js';
-export { ai, backup, database, email, letter, logging, objectstorage, pushnotification, sip, sms, types, };
+export { ai, backup, database, email, letter, logging, objectstorage, pushnotification, sip, sms, storage, types, };
+export * from './storage.js';
 export * from './types.js';

package/dist_ts/platform/index.js

@@ -8,7 +8,9 @@ import * as objectstorage from './objectstorage.js';
 import * as pushnotification from './pushnotification.js';
 import * as sip from './sip.js';
 import * as sms from './sms.js';
+import * as storage from './storage.js';
 import * as types from './types.js';
-export { ai, backup, database, email, letter, logging, objectstorage, pushnotification, sip, sms, types, };
+export { ai, backup, database, email, letter, logging, objectstorage, pushnotification, sip, sms, storage, types, };
+export * from './storage.js';
 export * from './types.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9wbGF0Zm9ybS9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxNQUFNLFNBQVMsQ0FBQztBQUM5QixPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssUUFBUSxNQUFNLGVBQWUsQ0FBQztBQUMxQyxPQUFPLEtBQUssS0FBSyxNQUFNLFlBQVksQ0FBQztBQUNwQyxPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEtBQUssYUFBYSxNQUFNLG9CQUFvQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssS0FBSyxNQUFNLFlBQVksQ0FBQztBQUVwQyxPQUFPLEVBQ0wsRUFBRSxFQUNGLE1BQU0sRUFDTixRQUFRLEVBQ1IsS0FBSyxFQUNMLE1BQU0sRUFDTixPQUFPLEVBQ1AsYUFBYSxFQUNiLGdCQUFnQixFQUNoQixHQUFHLEVBQ0gsR0FBRyxFQUNILEtBQUssR0FDTixDQUFDO0FBRUYsY0FBYyxZQUFZLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9wbGF0Zm9ybS9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssRUFBRSxNQUFNLFNBQVMsQ0FBQztBQUM5QixPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssUUFBUSxNQUFNLGVBQWUsQ0FBQztBQUMxQyxPQUFPLEtBQUssS0FBSyxNQUFNLFlBQVksQ0FBQztBQUNwQyxPQUFPLEtBQUssTUFBTSxNQUFNLGFBQWEsQ0FBQztBQUN0QyxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEtBQUssYUFBYSxNQUFNLG9CQUFvQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSx1QkFBdUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssR0FBRyxNQUFNLFVBQVUsQ0FBQztBQUNoQyxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEtBQUssS0FBSyxNQUFNLFlBQVksQ0FBQztBQUVwQyxPQUFPLEVBQ0wsRUFBRSxFQUNGLE1BQU0sRUFDTixRQUFRLEVBQ1IsS0FBSyxFQUNMLE1BQU0sRUFDTixPQUFPLEVBQ1AsYUFBYSxFQUNiLGdCQUFnQixFQUNoQixHQUFHLEVBQ0gsR0FBRyxFQUNILE9BQU8sRUFDUCxLQUFLLEdBQ04sQ0FBQztBQUVGLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsWUFBWSxDQUFDIn0=

package/dist_ts/platform/storage.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Backend-neutral storage vocabulary shared by App Store manifests, control
+ * planes, and fulfillment adapters. Physical providers and runtime attachment
+ * details intentionally do not belong in these contracts.
+ */
+export type TStorageResourceKind = 'filesystem' | 'objectStorage';
+/**
+ * Compatibility bridge for the existing generic platform capability. New
+ * filesystem requests intentionally have no generic IPlatformBinding mapping.
+ */
+export declare const storageKindPlatformCapabilityIds: {
+    readonly objectStorage: "objectstorage";
+};
+export type TFilesystemStorageAccessMode = 'ReadWriteOnce' | 'ReadOnlyMany' | 'ReadWriteMany';
+export type TObjectStorageAccessMode = 'readOnly' | 'readWrite';
+export type TStoragePerformanceTier = 'standard' | 'highIops' | 'capacity';
+export type TStorageDurability = 'ephemeral' | 'persistent';
+export type TStorageTopology = 'singleNode' | 'multiNode';
+export type TStorageSnapshotMode = 'none' | 'portable' | 'native';
+export type TStorageReclaimPolicy = 'retain' | 'delete';
+/**
+ * A positive base-2 quantity written as an integer followed by KiB, MiB, GiB,
+ * or TiB, for example `20GiB`. Parsers must reject every other representation.
+ */
+export type TStorageCapacityQuantity = string;
+export interface IStorageCapacityRequest {
+    request: TStorageCapacityQuantity;
+    /**
+     * A hard upper bound. A request with a limit can only be fulfilled by a
+     * class whose granted capabilities include hardQuota.
+     */
+    limit?: TStorageCapacityQuantity;
+}
+/**
+ * App-facing requirements describe policy, never a concrete provider class.
+ * Values in a `required` block are hard constraints; values in `preferred`
+ * influence selection but may not weaken required constraints.
+ */
+export interface IStorageClassRequirement {
+    performanceTier?: TStoragePerformanceTier;
+    durability?: TStorageDurability;
+    topology?: TStorageTopology;
+    hardQuota?: true;
+    snapshots?: Exclude<TStorageSnapshotMode, 'none'>;
+    backup?: true;
+    encryptedInTransit?: true;
+}
+export interface IStorageGrantedCapabilities {
+    performanceTier: TStoragePerformanceTier;
+    durability: TStorageDurability;
+    topology: TStorageTopology;
+    hardQuota: boolean;
+    snapshots: TStorageSnapshotMode;
+    backup: boolean;
+    encryptedInTransit: boolean;
+}
+export interface IStorageClassCapabilitiesBase {
+    /** Opaque operator-defined policy class ID, not a physical backend name. */
+    classId: string;
+    /** Changes whenever matching behavior or guarantees change. */
+    revision: string;
+    kind: TStorageResourceKind;
+    performanceTiers: TStoragePerformanceTier[];
+    durabilities: TStorageDurability[];
+    topologies: TStorageTopology[];
+    hardQuota: boolean;
+    snapshotModes: TStorageSnapshotMode[];
+    backup: boolean;
+    encryptedInTransit: boolean;
+}
+export interface IFilesystemStorageClassCapabilities extends IStorageClassCapabilitiesBase {
+    kind: 'filesystem';
+    accessModes: TFilesystemStorageAccessMode[];
+}
+export interface IObjectStorageClassCapabilities extends IStorageClassCapabilitiesBase {
+    kind: 'objectStorage';
+    accessModes: TObjectStorageAccessMode[];
+    versioning: boolean;
+    retention: boolean;
+}
+export type TStorageClassCapabilities = IFilesystemStorageClassCapabilities | IObjectStorageClassCapabilities;
+/**
+ * Fulfillment adapters advertise only portable guarantees. Provider names,
+ * addresses, mount options, principals, and credential values are private.
+ */
+export interface IStorageCapabilityAdvertisement {
+    schemaVersion: 1;
+    featureIds: string[];
+    classes: TStorageClassCapabilities[];
+}
+export interface IObjectStorageEnvironmentDelivery {
+    type: 'environment';
+    /**
+     * Explicit target keys prevent two named bindings from silently overwriting
+     * each other. Every required field must have a distinct environment key.
+     */
+    keys: {
+        endpoint: string;
+        bucket: string;
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+}
+export interface IObjectStorageSecretFileDelivery {
+    type: 'secretFile';
+    /** Canonical absolute path below /run/secrets/. */
+    targetPath: string;
+    /**
+     * JSON object with endpoint, bucket, region, accessKeyId,
+     * secretAccessKey, and optional sessionToken fields.
+     */
+    format: 'servezone-object-storage-v1';
+}
+export type TObjectStorageDelivery = IObjectStorageEnvironmentDelivery | IObjectStorageSecretFileDelivery;
+export type TResolvedStorageBindingStatus = 'requested' | 'provisioning' | 'ready' | 'degraded' | 'failed' | 'releasing' | 'retained' | 'released';
+export type TStorageBindingFailureCode = 'unsupportedCapability' | 'policyUnavailable' | 'provisionFailed' | 'attachmentFailed' | 'quotaExceeded' | 'credentialsUnavailable' | 'backendUnavailable' | 'migrationRequired';
+export interface IStorageBindingFailure {
+    code: TStorageBindingFailureCode;
+    message: string;
+    retryable: boolean;
+    observedAt: number;
+}
+export interface IResolvedStoragePolicyRef {
+    /** Opaque operator-defined policy class ID selected for this request. */
+    classId: string;
+    revision: string;
+}
+export interface IResolvedStorageCapacity {
+    requested?: TStorageCapacityQuantity;
+    granted?: TStorageCapacityQuantity;
+    limit?: TStorageCapacityQuantity;
+}
+export interface IResolvedStorageBindingBase {
+    schemaVersion: 1;
+    /** Stable binding/allocation identity. */
+    id: string;
+    serviceId: string;
+    /** Stable App Store storageRequests[].id. */
+    requestId: string;
+    /**
+     * Canonical digest of the normalized request. Adapters use it to distinguish
+     * an idempotent reconciliation from a migration.
+     */
+    requestDigest: string;
+    kind: TStorageResourceKind;
+    generation: number;
+    observedGeneration: number;
+    status: TResolvedStorageBindingStatus;
+    policy: IResolvedStoragePolicyRef;
+    capabilities: IStorageGrantedCapabilities;
+    /** Opaque resource identity; never a host path, export, or provider URL. */
+    resourceRef: string;
+    capacity?: IResolvedStorageCapacity;
+    failure?: IStorageBindingFailure;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export interface IResolvedFilesystemStorageBinding extends IResolvedStorageBindingBase {
+    kind: 'filesystem';
+    mountPath: string;
+    accessMode: TFilesystemStorageAccessMode;
+}
+export interface IStorageObjectCredentialsRef {
+    secretBundleId: string;
+    accessKeyIdKey: string;
+    secretAccessKeyKey: string;
+    sessionTokenKey?: string;
+}
+export interface IResolvedObjectStorageConnection {
+    endpoint: string;
+    bucket: string;
+    region: string;
+}
+export interface IResolvedObjectStorageBinding extends IResolvedStorageBindingBase {
+    kind: 'objectStorage';
+    accessMode: TObjectStorageAccessMode;
+    connection: IResolvedObjectStorageConnection;
+    credentials: IStorageObjectCredentialsRef;
+    delivery: TObjectStorageDelivery;
+    versioning: boolean;
+    retentionDays?: number;
+}
+export type TResolvedStorageBinding = IResolvedFilesystemStorageBinding | IResolvedObjectStorageBinding;

package/dist_ts/platform/storage.js

@@ -0,0 +1,8 @@
+/**
+ * Compatibility bridge for the existing generic platform capability. New
+ * filesystem requests intentionally have no generic IPlatformBinding mapping.
+ */
+export const storageKindPlatformCapabilityIds = {
+    objectStorage: 'objectstorage',
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3RvcmFnZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3BsYXRmb3JtL3N0b3JhZ2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBTUE7OztHQUdHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sZ0NBQWdDLEdBQUc7SUFDOUMsYUFBYSxFQUFFLGVBQWU7Q0FDdEIsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "17.4.0",
+  "version": "17.5.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -30,6 +30,96 @@ import { appstore, data, platform, platformservice, requests } from '@serve.zone
 
 This package intentionally has no service implementation logic. It is a stable vocabulary for services that need to agree on payload shape, method names, and response types.
 
+## Portable Storage Contracts
+
+App Store templates can declare logical, template-local `storageClasses` and
+stable named `storageRequests`. The same manifest is fulfilled by Onebox or
+Cloudly without exposing a physical provider:
+
+```typescript
+const storageConfig: appstore.IAppStoreVersionConfig = {
+  image: 'example/database:1.0.0',
+  port: 5432,
+  storageClasses: {
+    databaseFast: {
+      kind: 'filesystem',
+      purpose: 'database',
+      required: {
+        performanceTier: 'highIops',
+        durability: 'persistent',
+        hardQuota: true,
+        snapshots: 'native',
+        encryptedInTransit: true,
+      },
+    },
+    backupCapacity: {
+      kind: 'objectStorage',
+      purpose: 'backup',
+      required: {
+        performanceTier: 'capacity',
+        durability: 'persistent',
+        hardQuota: true,
+        encryptedInTransit: true,
+      },
+    },
+  },
+  storageRequests: [
+    {
+      id: 'database-data',
+      kind: 'filesystem',
+      storageClass: 'databaseFast',
+      mountPath: '/var/lib/example',
+      accessMode: 'ReadWriteOnce',
+      capacity: { request: '20GiB', limit: '40GiB' },
+      reclaimPolicy: 'retain',
+      protection: { backup: 'required', snapshots: 'native' },
+    },
+    {
+      id: 'backup-archive',
+      kind: 'objectStorage',
+      storageClass: 'backupCapacity',
+      accessMode: 'readWrite',
+      capacity: { request: '100GiB', limit: '1TiB' },
+      reclaimPolicy: 'retain',
+      delivery: {
+        type: 'secretFile',
+        targetPath: '/run/secrets/backup-archive.json',
+        format: 'servezone-object-storage-v1',
+      },
+      protection: { versioning: 'required', retentionDays: 30 },
+    },
+  ],
+  requiresFeatures: [
+    appstore.appStoreStorageFeatureIds.bindingsV1,
+    appstore.appStoreStorageFeatureIds.filesystemV1,
+    appstore.appStoreStorageFeatureIds.objectStorageV1,
+    appstore.appStoreStorageFeatureIds.objectStorageSecretFileV1,
+  ],
+};
+```
+
+Capacity quantities are positive integers followed by `KiB`, `MiB`, `GiB`, or
+`TiB`. Storage request IDs survive upgrades and restores. Logical class keys
+express requirements and preferences only; Onebox and Cloudly map them to
+operator policy independently.
+
+An app may declare multiple `objectStorage` requests. Each request resolves to
+its own endpoint, bucket, and credential reference. Environment delivery uses
+an explicit key map and secret-file delivery uses a unique target path, so two
+bindings cannot share credential destinations accidentally.
+
+`platform.storage` contains separate capability advertisements and resolved
+binding/status contracts. Resolved object-storage bindings expose connection
+metadata plus credential references, never credential values. Filesystem
+bindings expose the container mount and access mode, never a host path.
+
+Portable manifests and resolved bindings intentionally have no fields for
+Synology, NFS, Kerberos, Corestore, Kubernetes, Docker drivers, servers,
+exports, mount options, provider credential values, or local fallback paths. Runtimes
+must reject unknown manifest fields and unsupported required feature IDs before
+provisioning. Legacy `volumes` and `platformRequirements.s3` remain deprecated
+inputs for strict resolver normalization only.
+
 ## Data Contracts
 
 Use `data` when you need object shapes that are persisted, exchanged between services, or exposed through the Cloudly API.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '17.4.0',
+  version: '17.5.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/appstore/types.ts

@@ -4,12 +4,103 @@ import type {
   IServicePublicPortMapping,
   IServiceTargetPort,
 } from '../data/serviceports.js';
+import type {
+  IStorageCapacityRequest,
+  IStorageClassRequirement,
+  TFilesystemStorageAccessMode,
+  TObjectStorageAccessMode,
+  TObjectStorageDelivery,
+  TStorageReclaimPolicy,
+  TStorageResourceKind,
+  TStorageSnapshotMode,
+} from '../platform/storage.js';
 
 export type TAppStorePlatformRequirement = 'mongodb' | 's3' | 'clickhouse' | 'valkey' | 'mariadb';
+export interface IAppStorePlatformRequirements {
+  mongodb?: boolean;
+  /**
+   * @deprecated `s3: true` is normalized to one legacy object-storage binding.
+   * New templates use a named objectStorage request.
+   */
+  s3?: boolean;
+  clickhouse?: boolean;
+  valkey?: boolean;
+  mariadb?: boolean;
+}
 export type TAppStoreSourceType = 'inline' | 'repoManifest' | 'dockerImage';
 export type TAppStoreTrackingMode = 'tag' | 'digest';
 export type TAppStoreUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';
 
+export const appStoreStorageFeatureIds = {
+  bindingsV1: 'storage.bindings.v1',
+  filesystemV1: 'storage.filesystem.v1',
+  objectStorageV1: 'storage.object-storage.v1',
+  objectStorageSecretFileV1: 'storage.object-storage.secret-file.v1',
+} as const;
+
+export type TAppStoreStorageFeatureId =
+  typeof appStoreStorageFeatureIds[keyof typeof appStoreStorageFeatureIds];
+
+export type TAppStoreStoragePurpose =
+  | 'runtime'
+  | 'database'
+  | 'registry'
+  | 'backup';
+
+/**
+ * A template-local logical class. It states portable policy requirements and
+ * preferences; fulfillment adapters select their own compatible policy class.
+ */
+export interface IAppStoreStorageClass {
+  kind: TStorageResourceKind;
+  purpose: TAppStoreStoragePurpose;
+  required?: IStorageClassRequirement;
+  preferred?: IStorageClassRequirement;
+}
+
+export interface IAppStoreStorageRequestBase {
+  /** Stable identity used across upgrades, migrations, and restores. */
+  id: string;
+  kind: TStorageResourceKind;
+  /** Key in the containing version config's storageClasses record. */
+  storageClass: string;
+  capacity?: IStorageCapacityRequest;
+  reclaimPolicy: TStorageReclaimPolicy;
+}
+
+export interface IAppStoreFilesystemProtection {
+  backup?: 'required';
+  snapshots?: Exclude<TStorageSnapshotMode, 'none'>;
+  consistency?: 'crashConsistent' | 'applicationConsistent';
+}
+
+export interface IAppStoreFilesystemStorageRequest
+extends IAppStoreStorageRequestBase {
+  kind: 'filesystem';
+  mountPath: string;
+  accessMode: TFilesystemStorageAccessMode;
+  protection?: IAppStoreFilesystemProtection;
+}
+
+export interface IAppStoreObjectStorageProtection {
+  backup?: 'required';
+  versioning?: 'required';
+  /** Minimum provider-enforced retention duration. */
+  retentionDays?: number;
+}
+
+export interface IAppStoreObjectStorageRequest
+extends IAppStoreStorageRequestBase {
+  kind: 'objectStorage';
+  accessMode: TObjectStorageAccessMode;
+  delivery: TObjectStorageDelivery;
+  protection?: IAppStoreObjectStorageProtection;
+}
+
+export type TAppStoreStorageRequest =
+  | IAppStoreFilesystemStorageRequest
+  | IAppStoreObjectStorageRequest;
+
 export interface IAppStoreInlineSource {
   type: 'inline';
 }
@@ -140,9 +231,21 @@ export interface IAppStoreVersionConfig {
   /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker publishedPorts. */
   publicPortMappings?: IServicePublicPortMapping[];
   envVars?: IAppStoreEnvVar[];
+  /**
+   * @deprecated Legacy volume syntax. New templates use storageClasses and
+   * storageRequests. Resolver normalization must reject legacy physical driver
+   * options that cannot be represented portably.
+   */
   volumes?: TAppStoreVolumeSpec[];
+  /**
+   * Template-local logical policy classes. Keys are stable within the
+   * template; they are not Onebox or Cloudly operator class names.
+   */
+  storageClasses?: Record<string, IAppStoreStorageClass>;
+  /** Stable named filesystem and managed object-storage requests. */
+  storageRequests?: TAppStoreStorageRequest[];
   publishedPorts?: IAppStorePublishedPort[];
-  platformRequirements?: Partial<Record<TAppStorePlatformRequirement, boolean>>;
+  platformRequirements?: IAppStorePlatformRequirements;
   minOneboxVersion?: string;
   minCloudlyVersion?: string;
   appStoreVersion?: string;

package/ts/platform/index.ts

@@ -8,6 +8,7 @@ import * as objectstorage from './objectstorage.js';
 import * as pushnotification from './pushnotification.js';
 import * as sip from './sip.js';
 import * as sms from './sms.js';
+import * as storage from './storage.js';
 import * as types from './types.js';
 
 export {
@@ -21,7 +22,9 @@ export {
   pushnotification,
   sip,
   sms,
+  storage,
   types,
 };
 
+export * from './storage.js';
 export * from './types.js';

package/ts/platform/storage.ts

@@ -0,0 +1,237 @@
+/**
+ * Backend-neutral storage vocabulary shared by App Store manifests, control
+ * planes, and fulfillment adapters. Physical providers and runtime attachment
+ * details intentionally do not belong in these contracts.
+ */
+export type TStorageResourceKind = 'filesystem' | 'objectStorage';
+/**
+ * Compatibility bridge for the existing generic platform capability. New
+ * filesystem requests intentionally have no generic IPlatformBinding mapping.
+ */
+export const storageKindPlatformCapabilityIds = {
+  objectStorage: 'objectstorage',
+} as const;
+export type TFilesystemStorageAccessMode =
+  | 'ReadWriteOnce'
+  | 'ReadOnlyMany'
+  | 'ReadWriteMany';
+export type TObjectStorageAccessMode = 'readOnly' | 'readWrite';
+export type TStoragePerformanceTier = 'standard' | 'highIops' | 'capacity';
+export type TStorageDurability = 'ephemeral' | 'persistent';
+export type TStorageTopology = 'singleNode' | 'multiNode';
+export type TStorageSnapshotMode = 'none' | 'portable' | 'native';
+export type TStorageReclaimPolicy = 'retain' | 'delete';
+
+/**
+ * A positive base-2 quantity written as an integer followed by KiB, MiB, GiB,
+ * or TiB, for example `20GiB`. Parsers must reject every other representation.
+ */
+export type TStorageCapacityQuantity = string;
+
+export interface IStorageCapacityRequest {
+  request: TStorageCapacityQuantity;
+  /**
+   * A hard upper bound. A request with a limit can only be fulfilled by a
+   * class whose granted capabilities include hardQuota.
+   */
+  limit?: TStorageCapacityQuantity;
+}
+
+/**
+ * App-facing requirements describe policy, never a concrete provider class.
+ * Values in a `required` block are hard constraints; values in `preferred`
+ * influence selection but may not weaken required constraints.
+ */
+export interface IStorageClassRequirement {
+  performanceTier?: TStoragePerformanceTier;
+  durability?: TStorageDurability;
+  topology?: TStorageTopology;
+  hardQuota?: true;
+  snapshots?: Exclude<TStorageSnapshotMode, 'none'>;
+  backup?: true;
+  encryptedInTransit?: true;
+}
+
+export interface IStorageGrantedCapabilities {
+  performanceTier: TStoragePerformanceTier;
+  durability: TStorageDurability;
+  topology: TStorageTopology;
+  hardQuota: boolean;
+  snapshots: TStorageSnapshotMode;
+  backup: boolean;
+  encryptedInTransit: boolean;
+}
+
+export interface IStorageClassCapabilitiesBase {
+  /** Opaque operator-defined policy class ID, not a physical backend name. */
+  classId: string;
+  /** Changes whenever matching behavior or guarantees change. */
+  revision: string;
+  kind: TStorageResourceKind;
+  performanceTiers: TStoragePerformanceTier[];
+  durabilities: TStorageDurability[];
+  topologies: TStorageTopology[];
+  hardQuota: boolean;
+  snapshotModes: TStorageSnapshotMode[];
+  backup: boolean;
+  encryptedInTransit: boolean;
+}
+
+export interface IFilesystemStorageClassCapabilities
+extends IStorageClassCapabilitiesBase {
+  kind: 'filesystem';
+  accessModes: TFilesystemStorageAccessMode[];
+}
+
+export interface IObjectStorageClassCapabilities
+extends IStorageClassCapabilitiesBase {
+  kind: 'objectStorage';
+  accessModes: TObjectStorageAccessMode[];
+  versioning: boolean;
+  retention: boolean;
+}
+
+export type TStorageClassCapabilities =
+  | IFilesystemStorageClassCapabilities
+  | IObjectStorageClassCapabilities;
+
+/**
+ * Fulfillment adapters advertise only portable guarantees. Provider names,
+ * addresses, mount options, principals, and credential values are private.
+ */
+export interface IStorageCapabilityAdvertisement {
+  schemaVersion: 1;
+  featureIds: string[];
+  classes: TStorageClassCapabilities[];
+}
+
+export interface IObjectStorageEnvironmentDelivery {
+  type: 'environment';
+  /**
+   * Explicit target keys prevent two named bindings from silently overwriting
+   * each other. Every required field must have a distinct environment key.
+   */
+  keys: {
+    endpoint: string;
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+}
+
+export interface IObjectStorageSecretFileDelivery {
+  type: 'secretFile';
+  /** Canonical absolute path below /run/secrets/. */
+  targetPath: string;
+  /**
+   * JSON object with endpoint, bucket, region, accessKeyId,
+   * secretAccessKey, and optional sessionToken fields.
+   */
+  format: 'servezone-object-storage-v1';
+}
+
+export type TObjectStorageDelivery =
+  | IObjectStorageEnvironmentDelivery
+  | IObjectStorageSecretFileDelivery;
+
+export type TResolvedStorageBindingStatus =
+  | 'requested'
+  | 'provisioning'
+  | 'ready'
+  | 'degraded'
+  | 'failed'
+  | 'releasing'
+  | 'retained'
+  | 'released';
+
+export type TStorageBindingFailureCode =
+  | 'unsupportedCapability'
+  | 'policyUnavailable'
+  | 'provisionFailed'
+  | 'attachmentFailed'
+  | 'quotaExceeded'
+  | 'credentialsUnavailable'
+  | 'backendUnavailable'
+  | 'migrationRequired';
+
+export interface IStorageBindingFailure {
+  code: TStorageBindingFailureCode;
+  message: string;
+  retryable: boolean;
+  observedAt: number;
+}
+
+export interface IResolvedStoragePolicyRef {
+  /** Opaque operator-defined policy class ID selected for this request. */
+  classId: string;
+  revision: string;
+}
+
+export interface IResolvedStorageCapacity {
+  requested?: TStorageCapacityQuantity;
+  granted?: TStorageCapacityQuantity;
+  limit?: TStorageCapacityQuantity;
+}
+
+export interface IResolvedStorageBindingBase {
+  schemaVersion: 1;
+  /** Stable binding/allocation identity. */
+  id: string;
+  serviceId: string;
+  /** Stable App Store storageRequests[].id. */
+  requestId: string;
+  /**
+   * Canonical digest of the normalized request. Adapters use it to distinguish
+   * an idempotent reconciliation from a migration.
+   */
+  requestDigest: string;
+  kind: TStorageResourceKind;
+  generation: number;
+  observedGeneration: number;
+  status: TResolvedStorageBindingStatus;
+  policy: IResolvedStoragePolicyRef;
+  capabilities: IStorageGrantedCapabilities;
+  /** Opaque resource identity; never a host path, export, or provider URL. */
+  resourceRef: string;
+  capacity?: IResolvedStorageCapacity;
+  failure?: IStorageBindingFailure;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+export interface IResolvedFilesystemStorageBinding
+extends IResolvedStorageBindingBase {
+  kind: 'filesystem';
+  mountPath: string;
+  accessMode: TFilesystemStorageAccessMode;
+}
+
+export interface IStorageObjectCredentialsRef {
+  secretBundleId: string;
+  accessKeyIdKey: string;
+  secretAccessKeyKey: string;
+  sessionTokenKey?: string;
+}
+
+export interface IResolvedObjectStorageConnection {
+  endpoint: string;
+  bucket: string;
+  region: string;
+}
+
+export interface IResolvedObjectStorageBinding
+extends IResolvedStorageBindingBase {
+  kind: 'objectStorage';
+  accessMode: TObjectStorageAccessMode;
+  connection: IResolvedObjectStorageConnection;
+  credentials: IStorageObjectCredentialsRef;
+  delivery: TObjectStorageDelivery;
+  versioning: boolean;
+  retentionDays?: number;
+}
+
+export type TResolvedStorageBinding =
+  | IResolvedFilesystemStorageBinding
+  | IResolvedObjectStorageBinding;