elsa-core/specs/007-secrets-module/data-model.md

Data Model: Secrets Module

Secret

Logical named secret referenced by workflows and modules.

• TechnicalName: immutable unique name used by references and exports.
• DisplayName: optional user-facing label.
• Description: optional safe metadata.
• Type: secret type identifier.
• Scope: optional classification used by pickers and consumers.
• Tags: optional safe labels.
• StoreName: selected store identifier.
• Status: active, retired, expired, revoked, or deleted.
• TenantId, Owner, CreatedAt, UpdatedAt: operational metadata.
• LatestVersionNumber: current active version number.

Validation:

• TechnicalName is required, trimmed, case-normalized for uniqueness, and immutable after creation.
• Metadata must not contain raw secret values.
• Only one latest active version may exist for a technical name.

SecretVersion

Versioned value or external-reference payload for a secret.

• SecretTechnicalName: parent technical name.
• Version: monotonically increasing version number.
• Status: active, retired, expired, or revoked.
• ProtectedPayload: provider-private encrypted value or lookup metadata.
• PayloadContentType: store/type-specific payload descriptor.
• ExpiresAt: optional expiration time.
• CreatedAt, UpdatedAt, RetiredAt, RevokedAt: lifecycle timestamps.

State transitions:

• Create: no version -> version 1 active latest.
• Rotate/update: current active latest -> retired, new version -> active latest.
• Expire: active -> expired.
• Revoke: active or retired -> revoked.
• Delete: logical secret becomes unavailable; provider decides whether versions are hard-deleted or tombstoned.

SecretReference

Serializable value stored in workflow definitions and module settings.

• TechnicalName: immutable secret technical name.
• RequiredType: optional expected secret type.
• RequiredScope: optional expected scope.

Resolution:

• Resolve by TechnicalName.
• Return the latest active version only.
• Fail for missing, expired, revoked, deleted, incompatible type, incompatible scope, or unavailable store.

SecretTypeDescriptor

Registered metadata for a secret type.

• Type: stable type name.
• DisplayName: safe user-facing label.
• Description: safe help text.
• SupportedStoreCapabilities: required read/write/list/export/test capabilities.
• EditorContract: Studio editor descriptor and validation metadata.
• CanGenerate: whether the type can generate payloads server-side.
• CanExportEncrypted: whether encrypted export is supported.

Built-in v1 types:

• Text: standard string value.
• RsaKey: generated or provided RSA key material.
• X509CertificateReference: certificate reference metadata, not private certificate material.

SecretStoreDescriptor

Registered metadata for a store implementation.

• Name: stable store identifier.
• DisplayName: safe user-facing label.
• Description: safe help text.
• Capabilities: read, write, list, delete, rotate, test, encrypted export.
• SupportedTypes: secret types the store can handle.
• IsDefault: whether new secrets use this store when no explicit store is selected.

V1 stores:

• ElsaEncrypted: writable Elsa-managed encrypted store.
• Configuration: read-only deployment configuration store.

SecretPayload

Store-owned payload attached to a version.

• StoreName: store that owns the payload.
• Type: secret type.
• ProtectedData: encrypted value or provider-private lookup metadata.
• Metadata: safe store/type metadata for diagnostics and pickers.

Rules:

• General metadata APIs never return ProtectedData.
• Provider-private metadata is not exposed outside store-specific boundaries.
• Cleartext is not persisted in workflow definitions, module settings, logs, audit events, or general API responses.

SecretImportItem

Safe import/export package representation.

• TechnicalName: target secret name.
• Type, Scope, Description: safe metadata.
• StoreName: requested target store.
• ReferenceOnly: whether no value is included.
• EncryptedPayload: optional payload encrypted for the import target.
• ConflictBehavior: create-new, update/rotate, skip, or unspecified.

Rules:

• Same-name conflicts fail when ConflictBehavior is unspecified.
• Encrypted payload import requires matching decryption material.
• Reference-only import creates or validates metadata without importing a value.

SecretAuditEvent

Security event emitted for privileged operations.

• Action: create, update, rotate, revoke, delete, test, runtime-use, encrypted-export, import, failed-privileged-operation.
• TechnicalName: affected secret.
• Actor: user or system identity.
• Timestamp: event time.
• Reason: optional user-provided reason.
• Result: success or failure.

Rules:

• Audit events never include raw secret values, encrypted payloads, or provider-private metadata.