Secret-Attribute

Der Attribut-Werttyp Secret speichert Zugangsdaten — Passwörter, Client Secrets, API-Schlüssel, Bot-Tokens, private Schlüssel, Refresh Tokens — verschlüsselt. Die Engine erzwingt das: Ein Secret-Wert wird bei jedem Schreiben verschlüsselt, keine öffentliche API gibt ihn zurück, und Lesende sehen nur, ob ein Wert gesetzt ist.

Verfügbarkeit

Der Werttyp Secret ist ab dem System-CK-Modell 2.5.0 und dem Engine-Release verfügbar, das es ausliefert. Modelle, die ihn verwenden, müssen von System >= 2.5 abhängen (siehe System-Abhängigkeit).

Wann Secret verwendet wird

Verwenden Sie Secret für jedes Attribut, dessen Wert Zugriff auf etwas gewährt: Passwörter, Client Secrets, API-Schlüssel, Tokens, private Schlüssel und Passphrasen, Verbindungszeichenfolgen mit Zugangsdaten. Werte, die ein Konto identifizieren, ohne Zugriff zu gewähren — Benutzernamen, Client-IDs, Tenant-IDs — bleiben String.

Ein Secret-Wert wird nur serverseitig verwendet:

• der Communication Controller entschlüsselt Secrets, wenn er die Adapter-Konfiguration erstellt,
• Pipelines lesen ein Secret bei Bedarf mit dem Node RevealSecret@1,
• GraphQL, MCP und octo-cli melden nur, ob ein Wert gesetzt ist (siehe Secret-Attribute in der API).

Ein Secret-Attribut definieren

$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
attributes:
  - id: Password
    valueType: Secret
    description: Password of the mailbox account

Weisen Sie es einem Typ wie jedes andere Attribut zu:

types:
  - typeId: EMailReceiverConfiguration
    derivedFromCkTypeId: System/Configuration
    attributes:
      - id: ${this}/UserName
        name: UserName
      - id: ${this}/Password
        name: Password
        isOptional: true

Der Werttyp gehört zur Definition des Attributs. Wird eine Definition sowohl von Zugangsdaten- als auch von anderen Attributen verwendet, teilen Sie sie zuerst auf und stellen Sie nur das Zugangsdaten-Attribut um.

Regeln

Der Compiler erzwingt für ein Secret-Attribut die folgenden Regeln. Die Nummern beziehen sich auf die Compiler-Meldungen weiter unten.

Regel	Meldung
Keine defaultValues — Zugangsdaten werden nie mit dem Modell ausgeliefert	70
Keine autoCompleteValues und keine autoIncrementReference	71
Kein Attribut einer Association Role	71
Die effektive Ownership ist immer Secret. Eine nicht gesetzte Ownership wird Secret; jede andere deklarierte Ownership ist ein Fehler	72
Nicht indizierbar — der gespeicherte Wert ist Chiffretext	73
Nicht in Display Rules (displayNameRule, displayDescriptionRule) referenziert	74
Nicht in Owner-Attributpfaden referenziert	69
Das Modell hängt von System >= 2.5 ab	75
Ein Record mit einem Secret-Unterattribut deklariert einen gültigen recordKey	76, 77

Zusätzlich sind Secret-Attribute nie Teil von Query-Spalten, Formeln, Runtime-Queries, Archiv-Spaltenpfaden oder CrateDB-Spalten.

Ownership Secret bedeutet: Ein erneutes Anwenden eines Blueprints behält den gespeicherten Wert, und Runtime-Exporte (ExportRt, Deep-Graph-Export) enthalten ihn nie.

Secrets in Records

Ein Secret-Attribut kann Unterattribut eines Records sein. Da ein Record-Array immer als Ganzes geschrieben wird, muss die Engine pro Element entscheiden, ob ein leeres Secret „unverändert" bedeutet. Sie ordnet eingehende und gespeicherte Elemente über einen Record Key zu, den die Record-Definition mit recordKey benennt:

$schema: https://schemas.meshmakers.cloud/construction-kit-elements.schema.json
records:
  - recordId: ValueOverride
    recordKey: Path             # names a sub-attribute of the record
    attributes:
      - id: ${this}/Path
        name: Path
      - id: ${this}/Value
        name: Value             # String: non-secret overrides stay readable
      - id: ${this}/SecretValue
        name: SecretValue       # attribute definition with valueType: Secret
      - id: ${this}/IsSecret
        name: IsSecret

Das ist die Form des Helm-Records ValueOverride in System.Communication 3.41: Ein Secret-Override setzt IsSecret und trägt seinen Wert in SecretValue; bestehende Einträge mit einem enc:v1-Wert in Value werden weiter ausgerollt, sind aber veraltet.

Regeln für recordKey:

• Ein Record, dessen eigene oder geerbte Attribute ein Secret-Attribut enthalten, muss einen effektiven recordKey haben (eigenen oder vom nächsten Basis-Record geerbten). Das gilt für den Record-Typ, unabhängig davon, ob er als Record oder RecordArray verwendet wird, weil ein anderes Modell ihn in einem Array wiederverwenden kann (Meldung 76).
• Der Key benennt ein Unterattribut des Records, das erforderlich ist, kein Secret ist und den Werttyp String, Int, Int64 oder Enum hat (Meldung 77).
• Einzelne Record-Attribute werden nach Position übernommen (es gibt genau ein Element); der Key wird für RecordArray-Attribute verwendet.

Wie die Übernahme in der API funktioniert, beschreibt Secrets in Records.

System-Abhängigkeit

Ein Modell mit Secret-Attributen muss von System >= 2.5 abhängen, damit eine Engine, die den Werttyp nicht kennt, mit einem klaren Abhängigkeitsfehler abbricht, statt das Attribut falsch zu lesen:

# ckModel.yaml
dependencies:
  - System-[2.5,3.0)

Versionierung

Änderung	Klassifizierung
valueType von String auf Secret geändert	MINOR
valueType von Secret auf etwas anderes geändert, oder jede andere valueType-Änderung	MAJOR
recordKey eines Records gesetzt, entfernt oder geändert	MINOR

String → Secret ist Minor, weil gespeicherte Werte lesbar bleiben: Lesende akzeptieren Legacy-Klartext in einem Secret-Feld, bis der Verschlüsselungs-Sweep gelaufen ist (siehe Secret Encryption Key Ring). Die effektive Ownership wird Secret. Clients, die den Wert als String selektieren, müssen vor dem Ausrollen der Modelländerung auf den Ist-gesetzt-Zustand umgestellt werden. Siehe auch Versionierungsregeln.

Blueprint-Seeds

Blueprint-Seed-Daten dürfen für Secret-Attribute nur leere Werte enthalten; Secrets werden nach der Installation gesetzt. Siehe Secret-Attribute in Seed-Daten.

Compiler-Meldungen

Die Meldungstexte werden vom Compiler auf Englisch ausgegeben.

Nr.	Key	Level	Meldung
70	SecretAttributeHasDefaultValues	ERROR	Secret attribute '{ckAttributeId}' declares defaultValues. A Secret attribute cannot have default values - a credential must never ship with the model; set it after installation.
71	SecretAttributeAssignmentInvalid	ERROR	Secret attribute '{attributeName}' ('{ckAttributeId}') of '{ckElementId}' is invalid: {reason}
72	SecretAttributeOwnershipNotSecret	ERROR	Secret attribute '{attributeName}' of '{ckElementId}' declares ownership '{ownership}'. The effective ownership of a Secret attribute is always 'Secret'; remove the override or declare 'ownership: Secret'.
73	SecretAttributeIndexed	ERROR	Index of type '{ckTypeId}' references Secret attribute path '{attributePath}'. Secret attributes cannot be indexed - the stored value is ciphertext.
74	SecretAttributeReferencedByDisplayRule	ERROR	Display rule '{ruleProperty}' of type '{ckTypeId}' references Secret attribute path '{attributePath}'. Display rules cannot reveal Secret attributes.
75	SecretAttributeRequiresSystemDependency	ERROR	Construction kit model '{modelId}' uses Secret attributes and must depend on System >= {minimumVersion} (declared: {declaredDependency}). Declare the dependency as 'System-[{minimumVersion},3.0)' so engines that do not know the Secret value type fail with a dependency error.
76	RecordWithSecretRequiresRecordKey	ERROR	Record '{ckRecordId}' contains Secret attribute(s) {secretAttributes} but declares no 'recordKey'. A record with Secret sub-attributes must name the sub-attribute that identifies an element, so a secret left empty on a record array replace can be carried over from the stored element with the same key.
77	RecordKeyInvalid	ERROR	Record key '{recordKey}' of record '{ckRecordId}' is invalid: {reason}

Begründungen (reason) zu Meldung 71:

• Secret attributes cannot be attributes of an association role
• autoCompleteValues are not allowed - they would publish candidate secrets with the model
• autoIncrementReference is not allowed - a generated sequence number is not a secret

Begründungen (reason) zu Meldung 77:

• the record has no attribute with this name
• a Secret attribute cannot be the record key
• the key attribute must be of value type String, Int, Int64 or Enum
• the key attribute must not be optional - an element without a key cannot be matched

Ein Owner-Attributpfad, der auf ein Secret-Attribut zeigt, wird mit der bestehenden Meldung 69 (OwnerAttributeInvalid) gemeldet.

Siehe auch

• Secret-Attribute in der API — GraphQL-Semantik
• RevealSecret@1 — ein Secret in einer Pipeline lesen
• Secret Encryption Key Ring — Schlüssel, Rotation, Migration, Monitoring