@serve.zone/interfaces 19.8.0 → 20.1.0

package/dist_ts/data/secret.d.ts

@@ -0,0 +1,205 @@
+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 interface IServiceSecretOwner {
+    kind: 'service';
+    serviceId: string;
+}
+export interface ISecretSetSecretOwner {
+    kind: 'secret-set';
+    secretSetId: string;
+}
+export type TSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner;
+export interface ISecretVersionReference {
+    secretId: string;
+    secretVersionId: string;
+}
+export type TSecretVersionRetentionReferenceKind = 'desired-manifest' | 'applied-manifest' | 'previous-accepted-manifest' | 'rollback-manifest' | 'backup' | 'retention-window';
+export interface ISecretVersionRetentionReference {
+    kind: TSecretVersionRetentionReferenceKind;
+    resourceId: string;
+    expiresAt?: number;
+}
+/** Browser-safe logical secret metadata. It never contains value material. */
+export interface ISecretMetadata {
+    id: string;
+    organizationId: string;
+    owner: TSecretOwner;
+    key: string;
+    environment: TSecretEnvironment;
+    name: string;
+    description?: string;
+    tags: Array<{
+        key: string;
+        value: string;
+    }>;
+    managementSource: TSecretManagementSource;
+    /** Exact reconciliation owner, for example operator or appstore:<appId>. */
+    managementScope: TSecretManagementScope;
+    defaultDelivery: TSecretDelivery;
+    lifecycleState: TSecretLifecycleState;
+    activeVersion?: ISecretVersionReference;
+    versionCount: number;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+    lastRotatedAt?: number;
+}
+/** Browser-safe immutable-version metadata. It never contains an encrypted envelope. */
+export interface ISecretVersionMetadata {
+    id: string;
+    secretId: string;
+    lifecycleState: TSecretVersionLifecycleState;
+    createdAt: number;
+    createdBy: string;
+    source: TSecretManagementSource;
+    retiredAt?: number;
+    revokedAt?: number;
+    purgedAt?: number;
+}
+export interface ISecretSetMetadata {
+    id: string;
+    organizationId: string;
+    name: string;
+    description?: string;
+    lifecycleState: 'active' | 'retired' | 'deleted';
+    revision: number;
+    /** Dedicated CAS revision for secrets owned by this set. */
+    secretsRevision: number;
+    currentConsumerRollout?: ISecretSetConsumerRolloutSummary;
+    createdAt: number;
+    updatedAt: number;
+}
+export type TSecretSetConsumerRolloutStatus = 'pending' | 'published' | 'applied' | 'failed';
+export interface ISecretSetConsumerRolloutSummary {
+    rolloutId: string;
+    secretId: string;
+    secretVersionId: string;
+    totalConsumers: number;
+    pendingConsumers: number;
+    failedConsumers: number;
+    updatedAt: number;
+}
+export interface ISecretSetConsumerRolloutStatus {
+    serviceId: string;
+    status: TSecretSetConsumerRolloutStatus;
+    desiredManifestIds: string[];
+    appliedManifestIds: string[];
+    errorCode?: string;
+    updatedAt: number;
+}
+export interface ISecretEnvironmentDelivery {
+    type: 'environment';
+    variableName: string;
+}
+export interface ISecretFileDelivery {
+    type: 'file';
+    targetPath: string;
+    uid: number;
+    gid: number;
+    mode: number;
+}
+export type TSecretDelivery = ISecretEnvironmentDelivery | ISecretFileDelivery;
+export interface ISecretSetAttachmentMapping {
+    /** Source key in the attached SecretSet. */
+    sourceKey: string;
+    /** Final service key. Defaults to sourceKey. */
+    targetKey?: string;
+    /** Optional service-specific delivery override. */
+    delivery?: TSecretDelivery;
+}
+export interface ISecretSetAttachment {
+    id: string;
+    secretSetId: string;
+    environment: TSecretEnvironment;
+    mappings?: ISecretSetAttachmentMapping[];
+}
+/**
+ * Caller-managed value-free inputs to service secret resolution.
+ * Cloudly verifies organization ownership when resolving the referenced sets.
+ */
+export interface IServiceSecretConfiguration {
+    schemaVersion: 1;
+    /** Dedicated CAS revision for SecretSet attachments. */
+    revision: number;
+    /** Dedicated CAS revision for service-owned secret membership. */
+    secretsRevision: number;
+    secretSetAttachments: ISecretSetAttachment[];
+}
+export interface IResolvedSecretManifestEntry {
+    secretId: string;
+    secretVersionId: string;
+    key: string;
+    environment: TSecretEnvironment;
+    owner: TSecretOwner;
+    delivery: TSecretDelivery;
+}
+/** Immutable, value-free runtime snapshot. */
+export interface IResolvedSecretManifest {
+    schemaVersion: 1;
+    id: string;
+    digest: TSha256Digest;
+    organizationId: string;
+    serviceId: string;
+    clusterId: string;
+    secretRolloutId: string;
+    secretRolloutGeneration: number;
+    entries: IResolvedSecretManifestEntry[];
+    createdAt: number;
+}
+export interface IResolvedSecretManifestReference {
+    manifestId: string;
+    manifestDigest: TSha256Digest;
+    clusterId: string;
+    secretRolloutId: string;
+    secretRolloutGeneration: number;
+}
+export interface IAcceptedPreviousSecretManifest {
+    manifest: IResolvedSecretManifestReference;
+    /** Exclusive material-issuance deadline for tasks draining the previous rollout. */
+    acceptedUntil: number;
+}
+export type TClusterSecretDeploymentStatus = 'pending' | 'applying' | 'applied' | 'drifted' | 'failed';
+export interface IClusterSecretDeploymentState {
+    clusterId: string;
+    desiredManifest: IResolvedSecretManifestReference;
+    appliedManifest?: IResolvedSecretManifestReference;
+    previousAcceptedManifest?: IAcceptedPreviousSecretManifest;
+    status: TClusterSecretDeploymentStatus;
+    updatedAt: number;
+}
+/** Server-managed per-cluster authority switched with an expected revision CAS. */
+export interface IServiceSecretDeploymentPlan {
+    schemaVersion: 1;
+    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 validateSecretManagementScope: (sourceArg: TSecretManagementSource, scopeArg: unknown) => string[];
+export declare const validateSecretDelivery: (deliveryArg: unknown) => string[];
+/**
+ * One shared precedence rule for resolution and runtime verification.
+ * A manifest is authoritative once published; before publication an attachment
+ * override wins over the Secret default.
+ */
+export declare const resolveSecretDelivery: (deliveryArg: {
+    secretDefault: TSecretDelivery;
+    attachmentOverride?: TSecretDelivery;
+    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. */
+export declare const computeResolvedSecretManifestDigest: (manifestArg: IResolvedSecretManifest) => Promise<TSha256Digest>;
+export declare const verifyResolvedSecretManifestDigest: (manifestArg: IResolvedSecretManifest) => Promise<boolean>;
+export declare const validateResolvedSecretManifest: (manifestArg: unknown) => string[];
+export declare const validateServiceSecretDeploymentPlan: (planArg: unknown, expectedTargetClusterIdsArg?: string[]) => string[];