@serve.zone/interfaces 22.0.0 → 23.0.0

package/dist_ts/data/secret.d.ts

@@ -1,11 +1,12 @@
+import * as plugins from '../plugins.js';
 import type { TSha256Digest } from './immutableimage.js';
 export type TSecretEnvironment = string;
 export type TSecretLifecycleState = 'active' | 'retired' | 'revoked' | 'deleted';
 export type TSecretVersionLifecycleState = 'active' | 'retired' | 'revoked' | 'purged';
 /** Retired versions remain usable only through an already-accepted manifest. */
-export declare const isSecretVersionMaterialIssuable: (lifecycleStateArg: TSecretVersionLifecycleState) => boolean;
-export type TSecretManagementSource = 'operator' | 'legacy' | 'appstore' | 'mail' | 'oidc' | 'webpush' | 'platform' | 'system';
-export type TSecretManagementScope = 'operator' | 'legacy' | `appstore:${string}` | `mail:${string}` | `oidc:${string}` | `webpush:${string}` | `platform:${string}` | `system:${string}`;
+export declare const isSecretVersionMaterialIssuable: (lifecycleStateArg: TSecretVersionLifecycleState, referencedByAcceptedManifestArg: boolean) => boolean;
+export type TSecretManagementSource = 'operator' | 'appstore' | 'mail' | 'oidc' | 'webpush' | 'platform' | 'system';
+export type TSecretManagementScope = 'operator' | `appstore:${string}` | `mail:${string}` | `oidc:${string}` | `webpush:${string}` | `platform:${string}` | `system:${string}`;
 export interface IServiceSecretOwner {
     kind: 'service';
     serviceId: string;
@@ -14,7 +15,17 @@ export interface ISecretSetSecretOwner {
     kind: 'secret-set';
     secretSetId: string;
 }
-export type TSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner;
+export interface IPlatformProviderSecretOwner {
+    kind: 'platform-provider';
+    providerConfigId: string;
+}
+export interface ISystemSecretOwner {
+    kind: 'system';
+    systemId: string;
+}
+export type TSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner | IPlatformProviderSecretOwner | ISystemSecretOwner;
+export type TSecretMutationTarget = TSecretOwner;
+export type TWorkloadSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner;
 export interface ISecretVersionReference {
     secretId: string;
     secretVersionId: string;
@@ -93,18 +104,35 @@ export interface ISecretSetConsumerRolloutStatus {
     errorCode?: string;
     updatedAt: number;
 }
-export interface ISecretEnvironmentDelivery {
-    type: 'environment';
+export interface ISecretLauncherEnvironmentDelivery {
+    type: 'launcher-environment';
     variableName: string;
+    uid: number;
+    gid: number;
+    mode: 0o400 | 0o440;
 }
 export interface ISecretFileDelivery {
     type: 'file';
     targetPath: string;
     uid: number;
     gid: number;
-    mode: number;
+    mode: 0o400 | 0o440;
 }
-export type TSecretDelivery = ISecretEnvironmentDelivery | ISecretFileDelivery;
+export type TSecretDelivery = ISecretLauncherEnvironmentDelivery | ISecretFileDelivery;
+export declare const secretValueLimits: Readonly<{
+    maximumBytes: number;
+    minimumGeneratedBytes: 16;
+    maximumGeneratedBytes: 64;
+}>;
+export type TSecretGeneratedEncoding = 'hex' | 'base64url';
+export type TSecretValueInput = {
+    mode: 'sealed';
+    envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+} | {
+    mode: 'generated';
+    encoding: TSecretGeneratedEncoding;
+    bytes: number;
+};
 export interface ISecretSetAttachmentMapping {
     /** Source key in the attached SecretSet. */
     sourceKey: string;
@@ -124,7 +152,7 @@ export interface ISecretSetAttachment {
  * Cloudly verifies organization ownership when resolving the referenced sets.
  */
 export interface IServiceSecretConfiguration {
-    schemaVersion: 1;
+    schemaVersion: 2;
     /** Dedicated CAS revision for SecretSet attachments. */
     revision: number;
     /** Dedicated CAS revision for service-owned secret membership. */
@@ -136,17 +164,21 @@ export interface IResolvedSecretManifestEntry {
     secretVersionId: string;
     key: string;
     environment: TSecretEnvironment;
-    owner: TSecretOwner;
+    owner: TWorkloadSecretOwner;
     delivery: TSecretDelivery;
 }
 /** Immutable, value-free runtime snapshot. */
 export interface IResolvedSecretManifest {
-    schemaVersion: 1;
+    schemaVersion: 2;
     id: string;
     digest: TSha256Digest;
     organizationId: string;
     serviceId: string;
     clusterId: string;
+    imageRolloutId: string;
+    imageRolloutGeneration: number;
+    requestedImageDigest: TSha256Digest;
+    invocationDigest: TSha256Digest;
     secretRolloutId: string;
     secretRolloutGeneration: number;
     entries: IResolvedSecretManifestEntry[];
@@ -156,6 +188,10 @@ export interface IResolvedSecretManifestReference {
     manifestId: string;
     manifestDigest: TSha256Digest;
     clusterId: string;
+    imageRolloutId: string;
+    imageRolloutGeneration: number;
+    requestedImageDigest: TSha256Digest;
+    invocationDigest: TSha256Digest;
     secretRolloutId: string;
     secretRolloutGeneration: number;
 }
@@ -175,15 +211,22 @@ export interface IClusterSecretDeploymentState {
 }
 /** Server-managed per-cluster authority switched with an expected revision CAS. */
 export interface IServiceSecretDeploymentPlan {
-    schemaVersion: 1;
+    schemaVersion: 2;
     revision: number;
     clusterStates: IClusterSecretDeploymentState[];
     updatedAt: number;
 }
 export declare const resolvedSecretManifestReferencesEqual: (leftArg: IResolvedSecretManifestReference | undefined, rightArg: IResolvedSecretManifestReference | undefined) => boolean;
 export declare const isResolvedSecretManifestReferenceAccepted: (stateArg: IClusterSecretDeploymentState, referenceArg: IResolvedSecretManifestReference, nowArg: number) => boolean;
+export declare const validateSecretMutationId: (mutationIdArg: unknown) => string[];
+export declare const validateSecretOwner: (ownerArg: unknown) => string[];
 export declare const validateSecretManagementScope: (sourceArg: TSecretManagementSource, scopeArg: unknown) => string[];
 export declare const validateSecretDelivery: (deliveryArg: unknown) => string[];
+export declare const validateSecretValueInput: (valueInputArg: unknown) => string[];
+/** Checks the SmartCrypto context digest without opening or decrypting the envelope. */
+export declare const verifySecretEnvelopeContext: (envelopeArg: unknown, contextArg: unknown) => Promise<boolean>;
+/** Files accept arbitrary bytes; launcher values must be valid UTF-8 without NUL. */
+export declare const validateSecretValueBytes: (valueBytesArg: unknown, deliveryArg: TSecretDelivery) => string[];
 /**
  * One shared precedence rule for resolution and runtime verification.
  * A manifest is authoritative once published; before publication an attachment
@@ -195,7 +238,6 @@ export declare const resolveSecretDelivery: (deliveryArg: {
     manifestDelivery?: TSecretDelivery;
 }) => TSecretDelivery;
 export declare const validateServiceSecretConfiguration: (configurationArg: unknown) => string[];
-export declare const validateServiceSecretMode: (serviceDataArg: unknown) => string[];
 export declare const validateSecretSetAttachmentOwnership: (configurationArg: IServiceSecretConfiguration, serviceOrganizationIdArg: string, secretSetsArg: ISecretSetMetadata[]) => string[];
 export declare const createResolvedSecretManifestDigestInput: (manifestArg: IResolvedSecretManifest) => string;
 /** Shared canonical digest; the digest field itself is excluded from the input. */
@@ -203,3 +245,134 @@ export declare const computeResolvedSecretManifestDigest: (manifestArg: IResolve
 export declare const verifyResolvedSecretManifestDigest: (manifestArg: IResolvedSecretManifest) => Promise<boolean>;
 export declare const validateResolvedSecretManifest: (manifestArg: unknown) => string[];
 export declare const validateServiceSecretDeploymentPlan: (planArg: unknown, expectedTargetClusterIdsArg?: string[]) => string[];
+export declare const dockerSecretResourceNameDomain: "serve.zone/docker-secret-resource/v1";
+export declare const workloadInitEnvironmentMapPath: "/run/serve.zone/workloadinit-map-v1.json";
+export declare const workloadRuntimeAssetRoot: "/opt/serve.zone/runtime-assets";
+export declare const workloadInitExecutablePath: "/opt/serve.zone/runtime-assets/workloadinit/v1/workloadinit";
+export declare const workloadInitEnvironmentMapMode: 292;
+export declare const workloadRuntimeAssetsReadOnly: true;
+/** Stable resource name; no logical key or value material appears in Docker. */
+export declare const createDockerSecretResourceName: (secretVersionIdArg: string) => Promise<`szsv-${string}`>;
+export declare const createLauncherSecretSourcePath: (resourceArg: string) => `/run/serve.zone/secrets/${string}`;
+export interface IWorkloadInitEnvironmentMapEntryV1 {
+    variableName: string;
+    resource: string;
+    source: string;
+}
+export interface IWorkloadInitEnvironmentMapV1 {
+    schemaVersion: 1;
+    manifestId: string;
+    manifestDigest: TSha256Digest;
+    entries: IWorkloadInitEnvironmentMapEntryV1[];
+}
+/**
+ * The nonsecret map is generated only from launcher deliveries. Direct file
+ * deliveries mount their version resource at the declared target without the
+ * launcher. Runtime assets are mounted read-only; no shell, symlink, or
+ * aggregate material file participates in delivery.
+ */
+export declare const createWorkloadInitEnvironmentMap: (manifestArg: IResolvedSecretManifest) => Promise<IWorkloadInitEnvironmentMapV1>;
+export declare const verifyWorkloadInitEnvironmentMap: (mapArg: unknown, manifestArg: IResolvedSecretManifest) => Promise<boolean>;
+export interface IWorkloadInitWrappedInvocation {
+    command: [typeof workloadInitExecutablePath];
+    args: string[];
+}
+export declare const createWorkloadInitWrappedInvocation: (originalArgvArg: string[]) => IWorkloadInitWrappedInvocation;
+/**
+ * A Docker secret resource and its nonsecret map remain while any desired,
+ * applied, or previous-accepted retained manifest references them. Deletion is
+ * allowed only after no retained reference exists and Docker confirms the
+ * corresponding rollout or service removal.
+ */
+export interface ISecretRuntimeResourceRetention {
+    resource: string;
+    retainedManifestIds: string[];
+    dockerRemovalConfirmed: boolean;
+}
+export type TSecretRecipientLifecycleState = 'active' | 'retiring' | 'revoked';
+interface ISecretRecipientMetadataBase {
+    schemaVersion: 1;
+    recipientKeyId: string;
+    /** Canonical unpadded base64url raw 32-byte X25519 public key. */
+    publicKey: string;
+    generation: number;
+    activatedAt: number;
+}
+export interface IActiveSecretRecipientMetadata extends ISecretRecipientMetadataBase {
+    lifecycleState: 'active';
+    acceptUntil?: never;
+    revokedAt?: never;
+}
+export interface IRetiringSecretRecipientMetadata extends ISecretRecipientMetadataBase {
+    lifecycleState: 'retiring';
+    acceptUntil: number;
+    revokedAt?: never;
+}
+export interface IRevokedSecretRecipientMetadata extends ISecretRecipientMetadataBase {
+    lifecycleState: 'revoked';
+    acceptUntil?: never;
+    revokedAt: number;
+}
+export type TSecretRecipientMetadata = IActiveSecretRecipientMetadata | IRetiringSecretRecipientMetadata | IRevokedSecretRecipientMetadata;
+export type TSecretIngressRecipient = TSecretRecipientMetadata;
+export declare const secretRecipientLimits: Readonly<{
+    maximumRecipients: 64;
+}>;
+export declare const validateSecretRecipientMetadata: (recipientArg: unknown) => string[];
+export declare const validateSecretRecipientSet: (recipientsArg: unknown) => string[];
+/** New envelopes target only active recipients. */
+export declare const canIssueNewSecretEnvelope: (recipientArg: TSecretRecipientMetadata) => boolean;
+export declare const validateSecretValueInputForRecipient: (valueInputArg: unknown, recipientArg: TSecretRecipientMetadata, expectedContextArg: Uint8Array) => Promise<string[]>;
+/** Retiring recipients open only already-issued envelopes before their deadline. */
+export declare const canOpenIssuedSecretEnvelope: (recipientArg: TSecretRecipientMetadata, issuedAtArg: number, nowArg: number) => boolean;
+export declare const createSecretCreateEnvelopeContext: (contextArg: {
+    mutationId: string;
+    target: TSecretMutationTarget;
+    key: string;
+    environment: TSecretEnvironment;
+    delivery: TSecretDelivery;
+    expectedTargetSecretsRevision: number;
+}) => Uint8Array;
+export declare const createSecretRotateEnvelopeContext: (contextArg: {
+    mutationId: string;
+    secretId: string;
+    expectedSecretRevision: number;
+    expectedActiveVersionId: string;
+    expectedTargetSecretsRevision: number;
+}) => Uint8Array;
+export declare const createAppStoreInstallSecretEnvelopeContext: (contextArg: {
+    mutationId: string;
+    appId: string;
+    appVersion: string;
+    serviceId: string;
+    key: string;
+    delivery: TSecretDelivery;
+    generation?: {
+        encoding: TSecretGeneratedEncoding;
+        bytes: number;
+    };
+}) => Uint8Array;
+export declare const createResolvedSecretMaterialEnvelopeContext: (contextArg: {
+    recipientKeyId: string;
+    organizationId: string;
+    clusterId: string;
+    serviceId: string;
+    imageRolloutId: string;
+    imageRolloutGeneration: number;
+    requestedImageDigest: TSha256Digest;
+    secretRolloutId: string;
+    secretRolloutGeneration: number;
+    manifestId: string;
+    manifestDigest: TSha256Digest;
+    secretId: string;
+    secretVersionId: string;
+}) => Uint8Array;
+export declare const createSecretRecipientEnrollmentChallengeContext: (contextArg: {
+    enrollmentId: string;
+    clusterId: string;
+    recipientKeyId: string;
+    publicKey: string;
+    generation: number;
+    expiresAt: number;
+}) => Uint8Array;
+export {};