@serve.zone/interfaces 23.2.0 → 24.1.0

package/readme.md

@@ -30,13 +30,14 @@ 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
+## Secrets v24 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.
+Version 24 retains the value-free v23 architecture while replacing the remaining
+pre-cutover lifecycle and runtime authority gaps. 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
@@ -53,12 +54,24 @@ Breaking removals include:
   credential references.
 - Hosted-app control-token identities and credential-bearing bootstrap actions.
 
-Primary v23 additions include:
+The current secret contract includes:
 
-- `TSecretValueInput`, `TSecretIngressRecipient`, the
+- `TSecretValueInput`, active-only `IActiveSecretRecipientMetadata`, the
   `requests.secret.IReq_GetSecretIngressRecipient` contract with method
   `getSecretIngressRecipient`, and fixed-order create/rotate/App Store context
   builders.
+- `ISecretEnvelopeAdmissionBindingV1` under the Node-only runtime export binds
+  an exact envelope and request context to one recipient generation. The
+  binding is reproducible and does not itself prove admission. Retiring-key
+  retries require a trusted Cloudly mutation receipt created atomically while
+  that recipient was active; caller-supplied admission or issuance timestamps
+  are not part of the contract.
+- `getSecretVersionPurgePreflight` returns bounded advisory reference pages and
+  complete blocker counts. `purgeSecretVersion` identifies one exact version
+  and fences the mutation by secret, version, and target revisions. The
+  non-issuable `purge-pending` lifecycle and revisioned
+  `pending`/`erasing`/`failed`/`succeeded` operation keep external erasure
+  durable across retries without treating preflight as authorization.
 - Schema-v2 `IResolvedSecretManifest` contracts, stable Docker resource naming,
   WorkloadInit map/wrapper helpers, and `ISealedResolvedSecretMaterial` under
   `@serve.zone/interfaces/runtime`.
@@ -67,7 +80,7 @@ Primary v23 additions include:
 - Mandatory `IImmutableContainerInvocationV1` evidence on immutable image
   deployment plans.
 
-### Secrets v23.1 Runtime Registration And Reporting
+### Secrets v24 Runtime Registration And Reporting
 
 The Node-only `@serve.zone/interfaces/runtime` export adds the live contract
 that Cloudly must validate before publishing secret-bearing desired state to a
@@ -76,17 +89,38 @@ Coreflow connection:
 - `getSecretRecipientEnrollmentState` returns either an exact generation-zero
   empty state or the complete valid recipient set for the cluster derived from
   the verified JWT.
-- `getCoreflowSecretRuntimeRegistrationExpectation` returns the authoritative
-  live reporter session, target-node set, active recipient, and approved
-  WorkloadInit artifacts for the cluster derived from the verified JWT.
+- `getCoreflowSecretRuntimeRegistrationExpectation` returns either an
+  `available` v2 expectation or an explicit unavailable reason. The available
+  expectation binds the live reporter session, active recipient, fresh
+  generation-fenced target authority, and active WorkloadInit approval through
+  `expectationDigest`.
+- Spark sends authenticated, sequenced local Swarm membership observations and,
+  on managers, complete manager snapshots. Cloudly derives scope from the Spark
+  credential, reconciles manager consensus privately, and publishes one fresh
+  single-Swarm target authority or a targetless unavailable state. Structural
+  contract validation does not itself establish manager consensus.
+- `TSparkSwarmObservationV2` lets workers report only their local Swarm node ID,
+  because Docker does not expose the Swarm cluster ID to workers. Cloudly may
+  associate that node with a cluster only through authenticated node scope and
+  accepted manager consensus. V2 is a producer contract only until a later
+  consumer release defines transport, replay handling, and activation.
+  `validateSparkSwarmObservationV2` validates the exact structure and any
+  attached manager snapshot; it does not establish consensus or runtime
+  authority.
+- WorkloadInit approval binds a clean stable release identity, version-tagged
+  OCI index, exact amd64 and arm64 platform/executable digests, policy
+  generation, and a Cloudly summary of detached Cosign DSSE/SLSA verification.
+  Public shape and digest validators do not verify the signature, public-key
+  trust root, or private Cloudly policy.
 - `coreflowSecretRuntimeRegistrationTagId` is the sole dedicated TypedSocket
   tag identifier. Its payload is exactly
-  `ICoreflowSecretRuntimeRegistrationV1`; cluster scope comes from the verified
+  `ICoreflowSecretRuntimeRegistrationV2`; cluster scope comes from the verified
   connection identity rather than the tag.
-- `ICoreflowSecretRuntimeRegistrationV1` binds a reporter session to the exact
-  authoritative schedulable target-node set, required secret capabilities,
-  active recipient, approved WorkloadInit OCI index, and exact per-platform
-  manifest and installed-executable digests.
+- `ICoreflowSecretRuntimeRegistrationV2` references the exact expectation,
+  target generation/digest, and WorkloadInit authority. It must cover every
+  Cloudly-node/Swarm-cluster/Swarm-node identity and approved per-platform
+  manifest and installed-executable digest without self-asserting placement or
+  approval.
 - `validateCoreflowSecretRuntimeRegistration` compares the registration with a
   trusted expectation built by Cloudly, including the live reporter session.
   Missing, extra, duplicate, reordered, or mismatched node evidence fails
@@ -410,6 +444,8 @@ Common data contracts include:
   aggregate owner fence, while
   `setServiceSecretSetAttachments` returns the independent
   `secretConfigurationRevision`. Generic service writes own neither revision.
+  Purge is a separate exact-version mutation with its own version revision and
+  durable operation; it is not a logical-secret lifecycle action.
 - 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.

package/ts/00_commitinfo_data.ts

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

package/ts/appstore/types.ts

@@ -5,7 +5,7 @@ import {
   validateSecretValueInputForRecipient,
   type TSecretDelivery,
   type TSecretGeneratedEncoding,
-  type TSecretIngressRecipient,
+  type IActiveSecretRecipientMetadata,
   type TSecretValueInput,
 } from '../data/secret.js';
 import {
@@ -511,7 +511,7 @@ export const validateAppStoreEnvironmentDeclarations = (
 export const validateAppStoreInstallRequest = async (
   requestArg: unknown,
   configArg: IAppStoreVersionConfig,
-  activeIngressRecipientArg: TSecretIngressRecipient,
+  activeIngressRecipientArg: IActiveSecretRecipientMetadata,
 ): Promise<string[]> => {
   if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
     return ['install request must be an object'];