@serve.zone/interfaces 17.3.0 → 17.5.0

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/dist_ts/platformservice/pushnotification.d.ts

@@ -1,4 +1,5 @@
 import * as plugins from '../plugins.js';
+/** @deprecated Use the credential-scoped requests.webpush contracts. */
 export interface IRequest_SendPushNotification extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_SendPushNotification> {
     method: 'sendPushNotification';
     request: {

package/dist_ts/requests/index.d.ts

@@ -31,7 +31,9 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, migrationRequests as migration, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+import * as webPushRequests from './webpush.js';
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, migrationRequests as migration, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, webPushRequests as webpush, };
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';
+export * from './webpush.js';

package/dist_ts/requests/index.js

@@ -32,8 +32,10 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, migrationRequests as migration, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+import * as webPushRequests from './webpush.js';
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, corestoreRequests as corestore, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, migrationRequests as migration, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, webPushRequests as webpush, };
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxrQkFBa0IsTUFBTSxpQkFBaUIsQ0FBQztBQUN0RCxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssd0JBQXdCLE1BQU0sdUJBQXVCLENBQUM7QUFDbEUsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGFBQWEsTUFBTSxZQUFZLENBQUM7QUFDNUMsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLFdBQVcsTUFBTSxVQUFVLENBQUM7QUFDeEMsT0FBTyxLQUFLLFlBQVksTUFBTSxXQUFXLENBQUM7QUFDMUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLG9CQUFvQixNQUFNLG1CQUFtQixDQUFDO0FBQzFELE9BQU8sS0FBSyxtQkFBbUIsTUFBTSxrQkFBa0IsQ0FBQztBQUN4RCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBRWhELE9BQU8sRUFDTCxhQUFhLElBQUksS0FBSyxFQUN0QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsbUJBQW1CLElBQUksV0FBVyxFQUNsQyxlQUFlLElBQUksT0FBTyxFQUMxQixjQUFjLElBQUksTUFBTSxFQUN4QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGtCQUFrQixJQUFJLFVBQVUsRUFDaEMsV0FBVyxJQUFJLEdBQUcsRUFDbEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsd0JBQXdCLElBQUksZ0JBQWdCLEVBQzVDLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixhQUFhLElBQUksS0FBSyxFQUN0QixjQUFjLElBQUksTUFBTSxFQUN4QixXQUFXLElBQUksR0FBRyxFQUNsQixZQUFZLElBQUksSUFBSSxFQUNwQixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUMifQ==
+export * from './webpush.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxrQkFBa0IsTUFBTSxpQkFBaUIsQ0FBQztBQUN0RCxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssd0JBQXdCLE1BQU0sdUJBQXVCLENBQUM7QUFDbEUsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGFBQWEsTUFBTSxZQUFZLENBQUM7QUFDNUMsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLFdBQVcsTUFBTSxVQUFVLENBQUM7QUFDeEMsT0FBTyxLQUFLLFlBQVksTUFBTSxXQUFXLENBQUM7QUFDMUMsT0FBTyxLQUFLLGlCQUFpQixNQUFNLGdCQUFnQixDQUFDO0FBQ3BELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxnQkFBZ0IsTUFBTSxlQUFlLENBQUM7QUFDbEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLG9CQUFvQixNQUFNLG1CQUFtQixDQUFDO0FBQzFELE9BQU8sS0FBSyxtQkFBbUIsTUFBTSxrQkFBa0IsQ0FBQztBQUN4RCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyxZQUFZLE1BQU0sV0FBVyxDQUFDO0FBQzFDLE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBRWhELE9BQU8sRUFDTCxhQUFhLElBQUksS0FBSyxFQUN0QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsbUJBQW1CLElBQUksV0FBVyxFQUNsQyxlQUFlLElBQUksT0FBTyxFQUMxQixjQUFjLElBQUksTUFBTSxFQUN4QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGtCQUFrQixJQUFJLFVBQVUsRUFDaEMsV0FBVyxJQUFJLEdBQUcsRUFDbEIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsd0JBQXdCLElBQUksZ0JBQWdCLEVBQzVDLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGlCQUFpQixJQUFJLFNBQVMsRUFDOUIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixhQUFhLElBQUksS0FBSyxFQUN0QixjQUFjLElBQUksTUFBTSxFQUN4QixXQUFXLElBQUksR0FBRyxFQUNsQixZQUFZLElBQUksSUFBSSxFQUNwQixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUMifQ==

package/dist_ts/requests/webpush.d.ts

@@ -0,0 +1,132 @@
+import * as plugins from '../plugins.js';
+import type { IIdentity } from '../data/user.js';
+import type { IWebPushBinding, IWebPushCredentialOneTimeSecret, IWebPushDeliveryStatus, IWebPushNotificationPayload, IWebPushResourceOwner, IWebPushServiceStatus, IWebPushSubscription, TWebPushCancellationTarget, TWebPushUrgency } from '../data/webpush.js';
+/** Control-plane authentication. Never accepted by application delivery RPCs. */
+export interface IWebPushControlRequestAuth {
+    identity?: IIdentity;
+    apiToken?: string;
+}
+/** Required service credential. Owner scope is resolved exclusively from it. */
+export interface IWebPushAppCredentialAuth {
+    credentialId: string;
+    credentialSecret: string;
+    identity?: never;
+    apiToken?: never;
+}
+export type TWebPushBindingSync = Omit<IWebPushBinding, 'id' | 'status' | 'credential' | 'vapidKeys' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
+    id?: string;
+};
+export interface IReq_ListWebPushBindings extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListWebPushBindings> {
+    method: 'listWebPushBindings';
+    request: {
+        auth: IWebPushControlRequestAuth;
+        owner?: Partial<IWebPushResourceOwner>;
+    };
+    response: {
+        bindings: IWebPushBinding[];
+    };
+}
+export interface IReq_SyncWebPushBinding extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncWebPushBinding> {
+    method: 'syncWebPushBinding';
+    request: {
+        auth: IWebPushControlRequestAuth;
+        binding: TWebPushBindingSync;
+    };
+    response: {
+        success: boolean;
+        binding?: IWebPushBinding;
+        credential?: IWebPushCredentialOneTimeSecret;
+        message?: string;
+    };
+}
+export interface IReq_DeleteWebPushBinding extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteWebPushBinding> {
+    method: 'deleteWebPushBinding';
+    request: {
+        auth: IWebPushControlRequestAuth;
+        id: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
+export interface IReq_RotateWebPushCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RotateWebPushCredential> {
+    method: 'rotateWebPushCredential';
+    request: {
+        auth: IWebPushControlRequestAuth;
+        credentialId: string;
+    };
+    response: {
+        success: boolean;
+        credential?: IWebPushCredentialOneTimeSecret;
+        message?: string;
+    };
+}
+export interface IReq_RotateWebPushVapidKey extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RotateWebPushVapidKey> {
+    method: 'rotateWebPushVapidKey';
+    request: {
+        auth: IWebPushControlRequestAuth;
+        bindingId: string;
+    };
+    response: {
+        success: boolean;
+        binding?: IWebPushBinding;
+        message?: string;
+    };
+}
+export interface IReq_GetWebPushServiceStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetWebPushServiceStatus> {
+    method: 'getWebPushServiceStatus';
+    request: {
+        auth: IWebPushAppCredentialAuth;
+        owner?: never;
+    };
+    response: IWebPushServiceStatus;
+}
+export interface IReq_EnqueueWebPush extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_EnqueueWebPush> {
+    method: 'enqueueWebPush';
+    request: {
+        auth: IWebPushAppCredentialAuth;
+        /** Required credential-scoped replay key. */
+        idempotencyKey: string;
+        /** Opaque application identity; never a raw endpoint. */
+        subscriptionId: string;
+        subscription: IWebPushSubscription;
+        vapidKeyId: string;
+        payload: IWebPushNotificationPayload;
+        ttlSeconds?: number;
+        urgency?: TWebPushUrgency;
+        /** Provider derives an opaque RFC Topic HMAC; this value is never sent raw. */
+        collapseKey?: string;
+        owner?: never;
+    };
+    response: {
+        accepted: boolean;
+        spoolItemId?: string;
+        message?: string;
+    };
+}
+export interface IReq_CancelWebPush extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CancelWebPush> {
+    method: 'cancelWebPush';
+    request: {
+        auth: IWebPushAppCredentialAuth;
+        target: TWebPushCancellationTarget;
+        owner?: never;
+    };
+    response: {
+        success: boolean;
+        cancelledCount: number;
+        alreadyTerminalCount: number;
+        message?: string;
+    };
+}
+export interface IReq_GetWebPushDeliveryStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetWebPushDeliveryStatus> {
+    method: 'getWebPushDeliveryStatus';
+    request: {
+        auth: IWebPushAppCredentialAuth;
+        spoolItemId: string;
+        owner?: never;
+    };
+    response: {
+        delivery?: IWebPushDeliveryStatus;
+    };
+}

package/dist_ts/requests/webpush.js

@@ -0,0 +1,2 @@
+import * as plugins from '../plugins.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoid2VicHVzaC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL3dlYnB1c2gudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "17.3.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.
@@ -99,6 +189,8 @@ Common data contracts include:
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
+- Web Push contracts for environment-specific service bindings, public credential state, public VAPID key rotation metadata, privacy-minimal notification signals, and redacted delivery state. Subscription endpoints, browser key material, provider ciphertext, VAPID private keys, and credential secrets are intentionally absent from public binding and status DTOs.
+- Service-level Web Push declaration through `IService.data.webPush`. Immutable deployment declarations can require the `pushnotification` platform capability alongside database and object-storage capabilities; this does not turn Web Push into a Corestore resource or volume capability.
 - `IUser`, JWT-only `IIdentityCredential`, full `IIdentity`, and token-related contracts for authentication context. `IIdentity` extends `IIdentityCredential` with server-issued user metadata.
 - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
 
@@ -156,6 +248,24 @@ The immutable deployment workflow is:
 
 Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned, routeRef-owned, and combined hostname-plus-routeRef routes. A client can label canonical intent with `managedRouteKind: 'letsencrypt-http01-forward'` and set a higher `priority` for a path-specific HTTP-01 route while retaining a separate normal route for the same hostname. Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, `rotateMailCredential`, and `getMailDeliveryStatus`. `IReq_GetMailDeliveryStatus` looks up a delivery spool item by `spoolItemId`, returns `data.IMailDeliveryStatus`, and accepts `IMailSubmissionRequestAuth` so service-mail credentials can query their own accepted, queued, deferred, delivered, or failed status. `TMailAddressBindingSync.outboundEnabled` explicitly controls whether a gateway should maintain a managed outbound SMTP credential for an address binding. Binding credential metadata is public; `rotateMailCredential` returns the new secret only in its one-time `IMailCredentialOneTimeSecret` response.
 
+### Web Push Contracts
+
+New Web Push integrations use `requests.webpush`. Control-plane methods and application delivery methods deliberately use different, non-overlapping authentication types:
+
+- `listWebPushBindings`, `syncWebPushBinding`, `deleteWebPushBinding`, `rotateWebPushCredential`, and `rotateWebPushVapidKey` use control-plane identity or gateway API-token authentication.
+- `getWebPushServiceStatus`, `enqueueWebPush`, `cancelWebPush`, and `getWebPushDeliveryStatus` require a Web Push application credential. The gateway derives the owner exclusively from that credential; application requests cannot submit owner identity.
+
+`syncWebPushBinding` may return the initial application credential secret once, and `rotateWebPushCredential` may return its replacement once. Binding and status DTOs contain only public credential and VAPID metadata. `enqueueWebPush` requires a credential-scoped idempotency key, an opaque application subscription ID, the browser Push API subscription, the VAPID key ID used for that browser subscription, and a privacy-minimal `notificationAvailable` signal.
+
+```typescript
+import { requests } from '@serve.zone/interfaces';
+
+type EnqueueWebPush = requests.webpush.IReq_EnqueueWebPush;
+type WebPushStatus = requests.webpush.IReq_GetWebPushDeliveryStatus;
+```
+
+A delivery state of `pushServiceAccepted` means only that the remote push service accepted the encrypted request. It does not prove browser receipt, notification display, or user interaction.
+
 ### Gateway Client Lifecycle and DNS
 
 `syncGatewayClientRoute` accepts an optional `dnsMode`. Omission means `skip` for older clients. `observe` reports DNS without changing it. `reconcile` makes the gateway authoritative for the exact route hostname: it claims or replaces manual A, AAAA, and CNAME records, including already-correct manual values. Its optional `dns` result contains a closed status, retryability, the desired A/AAAA target, overwritten-record evidence, `checkedAt`, and `authoritativeVerifiedAt` once the provider or authoritative server confirms the state. Consumers can carry that evidence while retrying public propagation instead of treating an immediate recursive lookup miss as permanent.
@@ -231,6 +341,7 @@ Request groups are exported by product area:
 - `requests.status`
 - `requests.task`
 - `requests.version`
+- `requests.webpush`
 
 ## Platform Contracts
 
@@ -249,7 +360,7 @@ Available platform modules:
 
 - `platform.email` for transactional email, recipient registration, email status, and email stats.
 - `platform.sms` for SMS delivery and verification-code delivery.
-- `platform.pushnotification` for push-notification delivery.
+- `platform.pushnotification` is the deprecated legacy device-token push contract. New browser Web Push integrations use `requests.webpush`.
 - `platform.letter` for physical letter workflows.
 - `platform.ai`, `platform.database`, `platform.objectstorage`, `platform.logging`, `platform.backup`, and `platform.sip` for infrastructure and application capabilities.
 - `platform.types` plus root re-exports for shared capability, provider, binding, credential, and endpoint metadata.

package/ts/00_commitinfo_data.ts

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