@serve.zone/interfaces 21.1.0 → 23.0.0

package/readme.md

@@ -30,6 +30,43 @@ 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.
 
+## Secrets v23 Pre-Cutover Contract
+
+Version 23 removes the old grouped/bundled secret DTOs and plaintext runtime
+material API. Secret values enter Cloudly only as strict SmartCrypto X25519
+envelopes or an explicit bounded server-generation request. Coreflow receives a
+full digest-verified schema-v2 manifest plus one sealed envelope per pinned
+SecretVersion through the Node-only runtime export.
+
+This is a contract release before consumer cutover. It does **not** claim that
+clean-v2 migration, backup verification, historical secret erasure, or storage
+cleanup has completed. Those operations remain separately gated and must be
+proven by their owning services before destructive cleanup.
+
+Breaking removals include:
+
+- The SecretGroup and SecretBundle data/request modules and request namespaces.
+- `getServiceSecretBundlesAsFlatObject` and every service/preflight field tied
+  to bundled flattening or aggregate runtime files.
+- Plaintext resolved runtime values, generic platform config/credential maps,
+  credential-bearing Cloudly settings, and serialized object-storage
+  credential references.
+- Hosted-app control-token identities and credential-bearing bootstrap actions.
+
+Primary v23 additions include:
+
+- `TSecretValueInput`, `TSecretIngressRecipient`, the
+  `requests.secret.IReq_GetSecretIngressRecipient` contract with method
+  `getSecretIngressRecipient`, and fixed-order create/rotate/App Store context
+  builders.
+- Schema-v2 `IResolvedSecretManifest` contracts, stable Docker resource naming,
+  WorkloadInit map/wrapper helpers, and `ISealedResolvedSecretMaterial` under
+  `@serve.zone/interfaces/runtime`.
+- Two-step Coreflow X25519 recipient enrollment and exact recipient lifecycle
+  validators.
+- Mandatory `IImmutableContainerInvocationV1` evidence on immutable image
+  deployment plans.
+
 ## Portable Storage Contracts
 
 App Store templates can declare logical, template-local `storageClasses` and
@@ -82,18 +119,21 @@ const storageConfig: appstore.IAppStoreVersionConfig = {
       capacity: { request: '100GiB', limit: '1TiB' },
       reclaimPolicy: 'retain',
       delivery: {
-        type: 'secretFile',
+        type: 'file',
         targetPath: '/run/secrets/backup-archive.json',
         format: 'servezone-object-storage-v1',
+        uid: 1000,
+        gid: 1000,
+        mode: 0o400,
       },
       protection: { versioning: 'required', retentionDays: 30 },
     },
   ],
   requiresFeatures: [
-    appstore.appStoreStorageFeatureIds.bindingsV1,
+    appstore.appStoreStorageFeatureIds.bindingsV2,
     appstore.appStoreStorageFeatureIds.filesystemV1,
-    appstore.appStoreStorageFeatureIds.objectStorageV1,
-    appstore.appStoreStorageFeatureIds.objectStorageSecretFileV1,
+    appstore.appStoreStorageFeatureIds.objectStorageV2,
+    appstore.appStoreStorageFeatureIds.objectStorageFileV2,
   ],
 };
 ```
@@ -104,13 +144,15 @@ 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
+its own endpoint, bucket, and value-free credential management scope. Launcher
+environment delivery uses an explicit key map and file delivery uses one
+managed JSON Secret at 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
+metadata plus a service-owned credential management scope and delivery policy,
+never credential references or values. Filesystem
 bindings expose the container mount and access mode, never a host path.
 
 Portable manifests and resolved bindings intentionally have no fields for
@@ -310,14 +352,15 @@ Common data contracts include:
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
 - Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, and `IGatewayClientRoute` client-owned route views. Gateway route intent supports optional match `domains`, `transport`, and `remoteIngress`, plus explicit route `priority` and `managedRouteKind`. Ownership can combine `hostname` with `routeRef` so a normal route and a path-specific managed route for the same hostname reconcile independently.
 - Value-free `ISecretMetadata`, `ISecretVersionMetadata`, and `ISecretSetMetadata`
-  contracts for operator views, plus exact-version `IResolvedSecretManifest`
-  contracts for cluster delivery. Manifest helpers enforce canonical shared
-  digests, globally unique environment/file delivery targets, and per-cluster
-  desired/applied/previous-accepted rollout state. `ISecretBundle` and
-  `ISecretGroup` remain legacy compatibility contracts during the versioned
-  migration.
+  contracts for operator views, plus schema-v2 exact-version
+  `IResolvedSecretManifest` contracts for cluster delivery. Manifest helpers
+  bind immutable image rollout and invocation evidence, enforce canonical
+  digests and globally unique launcher/file targets, and track per-cluster
+  desired/applied/previous-accepted rollout state. Platform-provider and system
+  owners are valid metadata owners but are rejected from workload manifests.
   `listSecrets` exposes the dedicated `targetSecretsRevision` CAS fence;
-  `createSecret` consumes and returns that fence, while
+  every create, rotate, and lifecycle mutation consumes and returns that
+  aggregate owner fence, while
   `setServiceSecretSetAttachments` returns the independent
   `secretConfigurationRevision`. Generic service writes own neither revision.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
@@ -368,7 +411,7 @@ const config: appstore.IAppStoreVersionConfig = {
 };
 ```
 
-`redirectPath` is a canonical callback path on the app's HTTPS origin. Registration validation also requires that canonical app origin explicitly and rejects cross-origin, normalized, query-bearing, fragment-bearing, or duplicate callback URLs. The five environment values are environment-key names, not credentials embedded in the manifest. A host injects the generated client secret through its secret environment path and injects the other registration values only while OIDC is enabled.
+`redirectPath` is a canonical callback path on the app's HTTPS origin. Registration validation also requires that canonical app origin explicitly and rejects cross-origin, normalized, query-bearing, fragment-bearing, or duplicate callback URLs. The five environment values are environment-key names, not credentials embedded in the manifest. A host injects the generated client secret through launcher environment delivery and injects the other registration values only while OIDC is enabled.
 
 `data.IHostedAppRoleAssignment` binds a stable user subject to an immutable `appInstanceId`. That same app instance is the OIDC `client_id`, the ID-token `aud`, and the `servezone_app_instance_id` claim. Tokens include only the assigned roles for that audience; `preferred_username` is display metadata and must not be treated as identity authority.
 
@@ -380,6 +423,16 @@ Validate untrusted manifests, registrations, and claims with:
 - `appstore.validateAppStorePlatformOidcCapability`
 - `appstore.validateAppStoreVersionPlatformOidc`
 
+Hosted lifecycle RPCs accept only `IIdentityCredential`. After JWT
+verification, handlers validate `IHostedAppMachineClaims` and derive the exact
+app instance and service from `servezone_app_instance_id` and
+`servezone_service_id`; callers cannot submit those selectors. Bootstrap
+actions are either a canonical same-origin `setupRoute` path or a nonsecret
+`message`. Control tokens, usernames, passwords, and token URLs are not part of
+the lifecycle contract. Each server action carries a CAS revision; completion
+requires its exact ID, current revision, and `ready` status so a delayed request
+cannot complete a replacement action.
+
 ## TypedRequest Contracts
 
 Use `requests` when registering handlers with `@api.global/typedrequest` or when creating typed requests through a TypedSocket client.
@@ -487,8 +540,12 @@ sessions, Coreflow reconciliation, and the CoreMail-to-dcrouter gateway
 session. Only the three authentication handshakes carry reusable peer
 credentials. Subsequent transfer operations may carry a scoped, short-lived,
 one-time bearer capability, while every subsequent workload request derives
-tenant, service, binding, capabilities, allowed senders, and credential version
-from the server-owned TypedSocket peer.
+tenant, service, binding, capabilities, allowed senders, and the composite
+credential ID/version identity from the server-owned TypedSocket peer.
+Successful workload authentication also returns the effective binding state and
+the exact `allowedOperations` derived from
+`data.coreMailWorkloadOperationPolicy`. Disabled bindings never authenticate;
+draining bindings permit outbound status plus inbound list/fetch/ack only.
 
 Large content never travels inside TypedRequest JSON. Outbound body parts and
 attachments use prepare/upload/complete operations with short-lived one-time
@@ -496,8 +553,8 @@ HTTP transfer grants. Inbound delivery uses bounded delivery listing followed
 by prepare/fetch/complete and an explicit acknowledgement after the workload
 has processed the exact byte count and SHA-256 digest. `data.coreMailLimits`
 defines the 64 KiB control-frame boundary, bounded structured content, the
-30 MiB serialized MIME ceiling, transfer deadlines, and five-minute grant
-lifetime.
+30 MiB serialized MIME ceiling, a 56 KiB inbound page budget, bounded opaque
+cursors, transfer deadlines, and five-minute grant lifetime.
 
 Coreflow applies `data.ICoreMailDesiredState` with a config-epoch
 compare-and-set fence. It stages the digest-fenced JSON snapshot through a
@@ -526,22 +583,65 @@ canonical environment keys for the verifier-only bootstrap payload and the
 separate control and gateway secret values; no consumer may derive or embed
 plaintext material in desired state.
 
+CoreMail schema v2 keeps durable authority at the stable tenant, service, and
+binding identity while revisions, config epochs, and composite
+`credentialId`/`version` values fence sessions and new actions. Credential
+versions are authority-wide monotonic and unique even when rotation changes the
+credential ID. `active`
+bindings accept new mail, `draining` bindings permit existing status and
+inbound fetch/ack work without accepting new mail, and `disabled` bindings
+reject authentication. Cloudly retains a draining binding until pending
+inbound delivery reaches zero as reported by
+`ICoreMailBindingReconciliationStatus.pendingInboundCount`.
+
 `data.ICoreMailGatewayPeerDesiredState` gives dcrouter the authoritative HTTPS
 CoreMail transfer origin associated with an authenticated CoreMail service.
-The origin is control-plane state and must never be inferred from a socket,
-Host header, TypedSocket tag, or unrestricted peer input. The gateway
-authentication response repeats dcrouter's bound origin so CoreMail can reject
-configuration drift before handing over a path-only transfer grant.
+The same origin is carried in CoreMail desired state and returned by workload
+and gateway authentication. It must never be inferred from a socket, Host
+header, TypedSocket tag, or unrestricted peer input. CoreMail compares both
+authoritative views before handing over a path-only transfer grant.
+
+Inbound delivery pagination uses an opaque CoreMail-owned `cursor`, is bounded
+by `data.coreMailLimits.inboundPageSize`, and returns `nextCursor` only when
+another page may exist. Consumers must not construct or parse cursor contents.
+Cursor signing keys are value-free runtime references with one current and bounded
+retiring versions; plaintext remains in resolved runtime secrets.
+
+Quota windows are fixed UTC minute/day buckets. A new outbound quota unit is
+consumed only by the first durable insertion of an idempotency identity, while
+replays consume none. Pending inbound includes every state except
+`acknowledged`. These semantics are exported as `data.coreMailQuotaPolicy`.
+Every binding carries finite `messagesPerMinute`, `messagesPerDay`, and
+`maxPendingInbound` values; omitted or unlimited quotas are not valid schema-v2
+desired state.
+`data.coreMailRetentionPolicy` retains terminal outbound,
+acknowledged inbound, and idempotency receipts for 30 days and expired
+capabilities for 24 hours. Pending inbound is never age-purged.
+
+HTTP transfers use canonical `/transfers/<uuid>` paths and one-time Bearer
+tokens. `data.coreMailTransferTokenPolicy` requires canonical 256-bit
+base64url token material, while `issuedAt` and `expiresAt` prove the exact
+five-minute lifetime. PUT succeeds with 204 and GET with 200. Content length
+and type must match the grant; digest integrity is bound by grant metadata and repeated in
+the completion RPC rather than an optional HTTP digest header. Apply the
+exported strict normalizers for outbound message descriptors, envelopes,
+method-specific upload/download grants, submissions, gateway outbound
+statuses, inbound deliveries,
+desired state, bootstrap state, and gateway-peer state at their corresponding
+untrusted request and response boundaries.
 
 Control and gateway credential rotation is ordered: provision the candidate
 plaintext through resolved runtime secrets, publish and activate the matching
 `argon2id-v1` verifier, roll or reconnect every affected replica, observe
 per-task authentication and readiness, then mark the previous verifier
 `retiring` with `acceptUntil`. Remove the previous verifier and secret only
-after its acceptance window has elapsed and no session uses that version.
+after its acceptance window has elapsed and no session uses that composite
+credential identity.
 Reconciliation status carries the exact CoreMail task, rollout generation, and
 image digest so Coreflow can correlate every response with its authoritative
-current task roster.
+current task roster. Apply `data.normalizeCoreMailReconciliationStatus` before
+using pending-inbound or composite active-session counts for drain and rotation
+decisions.
 
 Request groups are exported by product area:
 
@@ -572,8 +672,6 @@ Request groups are exported by product area:
 - `requests.platform`
 - `requests.routing`
 - `requests.secret`
-- `requests.secretbundle`
-- `requests.secretgroup`
 - `requests.server`
 - `requests.service`
 - `requests.settings`
@@ -583,28 +681,53 @@ Request groups are exported by product area:
 - `requests.webpush`
 
 Secret material response contracts are not exported from the universal
-browser-facing entrypoint. Node runtimes import the isolated subpath:
+browser-facing entrypoint.
+
+The root entrypoint does use `@push.rocks/smartcrypto` to parse and validate
+strict ingress envelopes. Browser consumers that import the root contract can
+therefore include SmartCrypto and its browser-compatible crypto dependencies in
+their bundle. This package never opens private keys; sealed runtime material
+contracts remain isolated to the Node-only `/runtime` subpath.
+
+Node runtimes import the isolated subpath:
 
 ```typescript
 import {
-  verifyResolvedSecretMaterial,
+  verifySealedResolvedSecretMaterial,
 } from '@serve.zone/interfaces/runtime';
 import type {
   IReq_GetResolvedSecretMaterial,
-  IResolvedSecretMaterial,
+  ISecretMaterialExpectation,
+  ISealedResolvedSecretMaterial,
 } from '@serve.zone/interfaces/runtime';
 
-async function acceptMaterial(material: IResolvedSecretMaterial) {
-  if (!await verifyResolvedSecretMaterial(material)) {
+async function acceptMaterial(
+  material: ISealedResolvedSecretMaterial,
+  expectation: ISecretMaterialExpectation,
+) {
+  if (!await verifySealedResolvedSecretMaterial(material, expectation)) {
     throw new Error('secret material does not match its immutable manifest');
   }
 }
 ```
 
-Runtime material is shaped as `{ manifest, values }`. The helper verifies the
-canonical manifest digest and exact one-to-one version-ID coverage before
-plaintext use. The runtime must separately compare the verified manifest
-reference and cluster to its request and authenticated deployment scope.
+Runtime material is shaped as `{ schemaVersion: 1, manifest, entries }`, where
+each entry contains only `secretVersionId` and a strict X25519 envelope. The
+helper verifies the canonical schema-v2 manifest digest, envelope context
+digests, active recipient key, sorted exact one-to-one version coverage, every
+request fence, and the trusted local organization/cluster expectation. It never
+decrypts. Organization and cluster are derived from the verified cluster JWT
+and cannot be selected by request fields.
+
+Launcher environment delivery uses stable `szsv-<base32-sha256>` Docker
+resource names and `/run/serve.zone/secrets/<resource>` source paths. The
+nonsecret map is written to `/run/serve.zone/workloadinit-map-v1.json` with mode
+0444. Runtime assets under `/opt/serve.zone/runtime-assets` are read-only, and
+the wrapper executes
+`workloadinit run --map /run/serve.zone/workloadinit-map-v1.json -- <argv...>`
+without a shell, symlink, or aggregate value file. Resources and maps remain
+retained while any desired, applied, or previous-accepted manifest references
+them and are deleted only after Docker confirms rollout or service removal.
 
 ## Platform Contracts
 
@@ -628,7 +751,9 @@ Available platform modules:
 - `platform.ai`, `platform.database`, `platform.objectstorage`, `platform.logging`, `platform.backup`, and `platform.sip` for infrastructure and application capabilities.
 - `platform.storage` for provider-neutral storage classes, requests, capabilities, and resolved bindings.
 - `platform.storagemigration` for fenced object-storage migration intent, status, consumer acknowledgements, canonical digests, and strict normalizers.
-- `platform.types` plus root re-exports for shared capability, provider, binding, credential, and endpoint metadata.
+- `platform.types` provider and binding metadata is value-free. Provider-specific
+  operational config stays adapter-internal, while public DTOs expose typed
+  endpoints and optional credential management scopes only.
 
 ## Legacy Platformservice Contracts
 
@@ -667,7 +792,7 @@ pnpm test
 pnpm run buildDocs
 ```
 
-The package is authored as ESM TypeScript and built with `tsbuild tsfolders --allowimplicitany`.
+The package is authored as ESM TypeScript and built with `tsbuild tsfolders`.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

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