@serve.zone/interfaces 19.8.0 → 20.0.0

package/ts/data/secretbundle.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Compatibility-only persisted shape. Service-owned Secrets and
+ * explicit same-organization SecretSets replace this model.
+ */
 export interface ISecretBundle {
   id: string;
   data: {

package/ts/data/secretgroup.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Compatibility-only persisted shape. Migrate to ISecretMetadata
+ * and immutable SecretVersion records; do not create new SecretGroups.
+ */
 export interface ISecretGroup {
   /**
    * the insatnce id. This should be a random id, except for default

package/ts/data/service.ts

@@ -13,6 +13,10 @@ import type {
   IServicePublicPortMapping,
   IServiceTargetPort,
 } from './serviceports.js';
+import type {
+  IServiceSecretConfiguration,
+  IServiceSecretDeploymentPlan,
+} from './secret.js';
 
 export interface IServiceVolume {
   /** Stable Docker volume name. If omitted, Coreflow derives one from service id and mount path. */
@@ -258,14 +262,22 @@ export interface IService {
     reconciliationStatus?: IServiceReconciliationStatus;
     environment: { [key: string]: string };
     /**
-     * the main secret bundle id, exclusive to the service
+     * Legacy main SecretBundle ID. New services use secretConfiguration and
+     * the server-managed secretDeployment manifest pointer.
+     *
+     * @deprecated Compatibility-only until the versioned SecretBundle migration completes.
      */
-    secretBundleId: string;
+    secretBundleId?: string;
     /**
-     * those secret bundle ids do not belong to the service itself
-     * and thus live past the service lifecycle
+     * Legacy additional SecretBundle IDs.
+     *
+     * @deprecated Use explicit same-organization SecretSet attachments.
      */
     additionalSecretBundleIds?: string[];
+    /** Value-free, caller-managed SecretSet attachment configuration. */
+    secretConfiguration?: IServiceSecretConfiguration;
+    /** Server-managed immutable manifest authority pointer. */
+    secretDeployment?: IServiceSecretDeploymentPlan;
     /** Exact OCI/Docker argument vector appended after the image entrypoint. */
     containerArgs?: string[];
     /** Secret keys mounted as files and excluded from Env and secret.json. */
@@ -338,10 +350,18 @@ export interface IService {
   };
 }
 
-/** Caller-writable service data. Immutable policy and rollout fields are server-managed. */
+/**
+ * Caller-writable service data. Immutable rollout state and SecretSet
+ * attachments are changed only through their dedicated fenced APIs.
+ */
 export type TServiceWritableData = Omit<
   IService['data'],
-  'organizationId' | 'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'
+  | 'organizationId'
+  | 'immutableImageRequired'
+  | 'imageDeployment'
+  | 'imageRolloutStatus'
+  | 'secretConfiguration'
+  | 'secretDeployment'
 >;
 
 /** Caller-writable update data. Null explicitly removes an existing argument vector. */

package/ts/requests/index.ts

@@ -25,6 +25,7 @@ import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
 import * as routingRequests from './routing.js';
+import * as secretRequests from './secret.js';
 import * as secretBundleRequests from './secretbundle.js';
 import * as secretGroupRequests from './secretgroup.js'; 
 import * as serverRequests from './server.js';
@@ -61,6 +62,7 @@ export {
   nodeRequests as node,
   platformRequests as platform,
   routingRequests as routing,
+  secretRequests as secret,
   secretBundleRequests as secretbundle,
   secretGroupRequests as secretgroup,
   serverRequests as server,

package/ts/requests/secret.ts

@@ -0,0 +1,256 @@
+import type * as plugins from '../plugins.js';
+import type {
+  IResolvedSecretManifestEntry,
+  ISecretMetadata,
+  ISecretSetAttachment,
+  ISecretSetConsumerRolloutStatus,
+  ISecretSetMetadata,
+  ISecretVersionMetadata,
+  ISecretVersionRetentionReference,
+  TSecretDelivery,
+  TSecretEnvironment,
+} from '../data/secret.js';
+import type { IIdentityCredential } from '../data/user.js';
+
+export type TSecretMutationTarget =
+  | { kind: 'service'; serviceId: string }
+  | { kind: 'secret-set'; secretSetId: string };
+
+export type TSecretValueInput =
+  | { mode: 'provided'; value: string }
+  /** Server-generated runtime-only value; plaintext is never returned. */
+  | { mode: 'generated'; bytes: 32 | 48 | 64 };
+
+export interface IReq_ListSecrets extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListSecrets
+> {
+  method: 'listSecrets';
+  request: {
+    identity: IIdentityCredential;
+    target: TSecretMutationTarget;
+    environment?: TSecretEnvironment;
+  };
+  response: {
+    secrets: ISecretMetadata[];
+    /** Observable CAS fence for the selected service or SecretSet. */
+    targetSecretsRevision: number;
+  };
+}
+
+export interface IReq_GetSecretMetadata extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretMetadata
+> {
+  method: 'getSecretMetadata';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+  };
+  response: {
+    secret: ISecretMetadata;
+    versions: ISecretVersionMetadata[];
+  };
+}
+
+export interface IReq_CreateSecret extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateSecret
+> {
+  method: 'createSecret';
+  request: {
+    identity: IIdentityCredential;
+    target: TSecretMutationTarget;
+    key: string;
+    environment: TSecretEnvironment;
+    name: string;
+    description?: string;
+    tags?: Array<{ key: string; value: string }>;
+    delivery: TSecretDelivery;
+    valueInput: TSecretValueInput;
+    expectedTargetSecretsRevision: number;
+  };
+  response: {
+    secret: ISecretMetadata;
+    version: ISecretVersionMetadata;
+    /** Post-create CAS revision for the selected target. */
+    targetSecretsRevision: number;
+  };
+}
+
+export interface IReq_RotateSecret extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RotateSecret
+> {
+  method: 'rotateSecret';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+    valueInput: TSecretValueInput;
+    expectedSecretRevision: number;
+    expectedActiveVersionId?: string;
+  };
+  response: {
+    secret: ISecretMetadata;
+    version: ISecretVersionMetadata;
+  };
+}
+
+export interface IReq_ChangeSecretLifecycle extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ChangeSecretLifecycle
+> {
+  method: 'changeSecretLifecycle';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+    action: 'retire' | 'revoke' | 'delete' | 'request-purge';
+    expectedSecretRevision: number;
+  };
+  response: {
+    secret: ISecretMetadata;
+  };
+}
+
+export interface IReq_GetSecretVersionPurgePreflight
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretVersionPurgePreflight
+> {
+  method: 'getSecretVersionPurgePreflight';
+  request: {
+    identity: IIdentityCredential;
+    secretId: string;
+    secretVersionId: string;
+  };
+  response: {
+    purgeAllowed: boolean;
+    references: ISecretVersionRetentionReference[];
+  };
+}
+
+export interface IReq_ListSecretSets extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListSecretSets
+> {
+  method: 'listSecretSets';
+  request: {
+    identity: IIdentityCredential;
+    organizationId: string;
+  };
+  response: {
+    secretSets: ISecretSetMetadata[];
+  };
+}
+
+export interface IReq_CreateSecretSet extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_CreateSecretSet
+> {
+  method: 'createSecretSet';
+  request: {
+    identity: IIdentityCredential;
+    organizationId: string;
+    name: string;
+    description?: string;
+  };
+  response: {
+    secretSet: ISecretSetMetadata;
+  };
+}
+
+export interface IReq_UpdateSecretSet extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_UpdateSecretSet
+> {
+  method: 'updateSecretSet';
+  request: {
+    identity: IIdentityCredential;
+    secretSetId: string;
+    name: string;
+    description?: string;
+    expectedRevision: number;
+  };
+  response: {
+    secretSet: ISecretSetMetadata;
+  };
+}
+
+export interface IReq_ChangeSecretSetLifecycle
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ChangeSecretSetLifecycle
+> {
+  method: 'changeSecretSetLifecycle';
+  request: {
+    identity: IIdentityCredential;
+    secretSetId: string;
+    action: 'retire' | 'delete';
+    expectedRevision: number;
+  };
+  response: {
+    secretSet: ISecretSetMetadata;
+  };
+}
+
+export interface IReq_GetSecretSetConsumerRollout
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretSetConsumerRollout
+> {
+  method: 'getSecretSetConsumerRollout';
+  request: {
+    identity: IIdentityCredential;
+    secretSetId: string;
+    rolloutId: string;
+    cursor?: string;
+    limit?: number;
+  };
+  response: {
+    consumers: ISecretSetConsumerRolloutStatus[];
+    nextCursor?: string;
+  };
+}
+
+export interface IReq_SetServiceSecretSetAttachments
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SetServiceSecretSetAttachments
+> {
+  method: 'setServiceSecretSetAttachments';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    attachments: ISecretSetAttachment[];
+    expectedSecretConfigurationRevision: number;
+  };
+  response: {
+    attachments: ISecretSetAttachment[];
+    /** Post-update attachment CAS revision. */
+    secretConfigurationRevision: number;
+  };
+}
+
+export interface ISecretResolutionPreviewCollision {
+  environment: TSecretEnvironment;
+  key: string;
+  sourceSecretIds: string[];
+  reason: 'duplicate-secret-set-key' | 'duplicate-service-key' | 'invalid-alias';
+}
+
+export interface IReq_PreviewServiceSecretResolution
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_PreviewServiceSecretResolution
+> {
+  method: 'previewServiceSecretResolution';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    attachments?: ISecretSetAttachment[];
+  };
+  response: {
+    entries: IResolvedSecretManifestEntry[];
+    collisions: ISecretResolutionPreviewCollision[];
+  };
+}

package/ts/runtime.ts

@@ -0,0 +1,80 @@
+import type * as plugins from './plugins.js';
+import type {
+  IIdentityCredential,
+  IResolvedSecretManifest,
+  TSha256Digest,
+} from './data/index.js';
+import {
+  validateResolvedSecretManifest,
+  verifyResolvedSecretManifestDigest,
+} from './data/secret.js';
+
+/**
+ * Runtime-only material. This module is exported only under the Node condition
+ * and is intentionally unreachable from the universal/browser-facing barrel.
+ */
+export interface IResolvedSecretMaterialValue {
+  secretVersionId: string;
+  value: string;
+}
+
+export interface IResolvedSecretMaterial {
+  schemaVersion: 1;
+  /** Full value-free manifest so the runtime can verify its canonical digest. */
+  manifest: IResolvedSecretManifest;
+  /** Plaintext values keyed only by the exact version IDs pinned by the manifest. */
+  values: IResolvedSecretMaterialValue[];
+}
+
+/**
+ * Verifies the immutable manifest and requires exactly one material value for
+ * every pinned version. Callers separately compare the verified manifest
+ * reference to the request and their authenticated cluster scope.
+ */
+export const verifyResolvedSecretMaterial = async (
+  materialArg: unknown,
+): Promise<boolean> => {
+  if (!materialArg || typeof materialArg !== 'object' || Array.isArray(materialArg)) return false;
+  const material = materialArg as Partial<IResolvedSecretMaterial>;
+  if (!material.manifest || !Array.isArray(material.values)) return false;
+  if (material.schemaVersion !== 1) return false;
+  if (validateResolvedSecretManifest(material.manifest).length > 0) return false;
+  if (!await verifyResolvedSecretManifestDigest(material.manifest)) return false;
+  if (!material.values.every((valueArg) => (
+    Boolean(valueArg)
+    && typeof valueArg === 'object'
+    && typeof valueArg.secretVersionId === 'string'
+    && typeof valueArg.value === 'string'
+  ))) return false;
+  const expectedVersionIds = material.manifest.entries
+    .map((entryArg) => entryArg.secretVersionId)
+    .sort();
+  const actualVersionIds = material.values
+    .map((valueArg) => valueArg.secretVersionId)
+    .sort();
+  return new Set(actualVersionIds).size === actualVersionIds.length
+    && JSON.stringify(actualVersionIds) === JSON.stringify(expectedVersionIds);
+};
+
+/**
+ * Cluster and organization are derived from the verified JWT. A caller cannot
+ * select either scope through request fields.
+ */
+export interface IReq_GetResolvedSecretMaterial
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetResolvedSecretMaterial
+> {
+  method: 'getResolvedSecretMaterial';
+  request: {
+    identity: IIdentityCredential;
+    serviceId: string;
+    secretRolloutId: string;
+    secretRolloutGeneration: number;
+    manifestId: string;
+    manifestDigest: TSha256Digest;
+  };
+  response: {
+    material: IResolvedSecretMaterial;
+  };
+}