Secrets

TL;DR

Ein workspace secret ist ein benanntes, workspace-eigenes Drittanbieter-Credential — der LLM-Token eines Teams, der Stripe-Schlüssel eines Kunden, ein Token für einen gated Model-Hub —, das ein backend per ID referenziert statt per Wert. Der Wert erscheint nie in einem backend-Graphen, der Historie des backend, einer CLI-Antwort, einer REST-Antwort oder irgendeinem agent-Modus-JSON.
Ein component-Autor deklariert einen Parameter als secret, indem er secret: true zu seinem config_schema-Eintrag hinzufügt. Der Parametertyp bleibt String; der Wert, den ein backend-Autor später bindet, ist die ID des secret, und die Plattform löst diese ID zur Deploy-Zeit zum Wert auf.
Ein backend-Autor bindet den deklarierten Parameter an ein workspace secret mit ppl backend change-parameter und übergibt die ID des secret. Die Anfrage trägt die ID, nie das Credential selbst.
Secrets werden mit ppl secret list per Metadaten aufgelistet (oder in der workspace-UI, Workspace → Secrets); ihr Erstellen, Aktualisieren, Rotieren und Löschen ist eine workspace-Mutation, die nur aus einer interaktiven ppl login-Session läuft, weil dort der Wert eingegeben wird.
Das Rotieren eines secret durch Wiederverwendung seines Namens hält die ID stabil, sodass jedes an diese ID gebundene backend bei seinem nächsten Deploy den neuen Wert ohne Graph-Bearbeitung aufnimmt.

Was workspace secrets tatsächlich sind

Ein workspace secret ist ein benanntes, workspace-skopiertes Drittanbieter-Credential — der LLM-API-Token des Teams, der Stripe-Schlüssel eines Kunden, ein Token für einen gated Model-Hub. Das sind die eigenen Credentials des Mandanten für die externen Dienste, mit denen ein backend spricht, nicht Plattform-Infrastruktur-Credentials. Sie leben an der workspace-Grenze, getrennt von jedem backend.

Der Ablauf hat drei Rollen. Ein component-Autor deklariert mit secret: true, welche Parameter secrets tragen. Ein backend-Autor bindet diese Parameter per ID an bestimmte workspace secrets. Die Plattform löst jede ID zur Deploy-Zeit zu ihrem Wert auf. Der backend-Graph, die Historie des backend, jede CLI-Antwort (einschließlich ppl secret list, das nur Metadaten zurückgibt) und jede API-Oberfläche tragen nur die ID; der Wert erreicht ein component allein zur Deploy-Zeit.

Workspaces besitzen secrets

Ein workspace ist die mandantenfähige Grenze: jedes component, backend, runtime, file, secret und Teammitglied gehört genau einem workspace, und die Mandantenisolation folgt aus diesem einzigen Besitz. Die CLI bindet sich an einen aktiven workspace zur Zeit — ppl workspace switch <workspace_id> bindet ihn neu, ppl workspace list zeigt die workspaces, denen du angehörst, und ppl workspace update --add-user / --remove-user passt die Mitgliedschaft an. Weil der secret-Store auf den workspace beschränkt ist, ändert ein Wechsel, welche secrets du siehst, und ein Teamkollege in einem anderen workspace sieht nie die secrets dieses einen.

Die Sicherheitsgarantie

Die Garantie ist konkret: der Wert eines workspace secret ist nie sichtbar in:

der backend-Graph-Definition, einschließlich jeder exportierten, geforkten oder inspizierten Form;
der Ausgabe irgendeines ppl-Befehls, einschließlich agent-Modus-JSON;
REST-API-Antworten;
jeder Ansicht, die die Historie des backend zeigt;
jedem Activity-Feed.

Der Wert erreicht das laufende component zur Deploy-Zeit, wenn die Plattform die gebundene ID auflöst. Ab diesem Punkt liegt das, was mit ihm geschieht, in der Verantwortung des component — die Plattform kann nicht verhindern, dass ein component-Autor ihn loggt oder über einen Ausgabe-Stream offenlegt. Components, die secrets verarbeiten, sollten sie nicht loggen.

Das Ziel, an das ein serverseitig gehaltenes secret weitergeleitet wird, ist von der Plattform fixiert, nicht von einer Anfrage gewählt: eine client-gelieferte URL kann nicht umlenken, wohin der Wert gesendet wird.

Das Rotieren eines secret — das erneute Setzen seines Werts unter demselben Namen — hält die ID stabil, sodass die Bindung des backend überlebt; was sich ändert, ist der Wert, zu dem die ID auflöst. Der nächste Deploy jedes an diese ID gebundenen backend nimmt den neuen Wert auf; bestehende live deployments behalten ihren ursprünglichen Wert, bis sie neu deployt werden.

Mentales Modell — per ID binden

   Workspace UI                       Component
   ┌──────────────────────┐           ┌──────────────────────────┐
   │ secret  hf_prod      │           │ reads config.hf_token    │
   │   id:  <secret_id>   │           │ as plain String          │
   └──────────┬───────────┘           │ (resolved at deploy time)│
              │ bind by ID            └─────────────▲────────────┘
                                                    │ value at
   ┌──────────────────────────────┐                 │ deploy time
   │ Backend  ·  vertex 3         │                 │
   │   parameter  hf_token        │                 │
   │     type:   String           │                 │
   │     value:  <secret_id>      ├─────────────────┘
   └──────────────────────────────┘

Drei Rollen, drei Grenzen. Der workspace besitzt das secret und die UI zu seiner Verwaltung. Der backend-Autor bindet einen Parameter an eine secret-ID. Das component liest den aufgelösten Wert zur Deploy-Zeit, wie jeden anderen Konfigurationswert. Die Grenzen sind das, was den Wert von jeder Oberfläche fernhält außer der einen Stelle, die er erreichen muss.

Der component-Autor deklariert den Parameter

Verwende diesen Rahmen beim Entwurf eines component, das ein Credential braucht.

Ein component-Autor deklariert, welche Parameter secrets tragen, indem er secret: true zum config_schema-Eintrag hinzufügt. Der Parametertyp bleibt String. Das secret: true-Flag teilt der Plattform zwei Dinge mit: dass der Parameter eine secret-ID statt eines literalen Werts akzeptiert, wenn ein backend ihn bindet, und dass die Plattform diese ID zur Deploy-Zeit zu ihrem Wert auflöst.

config_schema:  hf_token:    type: String    secret: true    description: Hugging Face token for gated model repos.

Das component liest config.hf_token zur Deploy-Zeit als einfachen String, in der Form identisch zu jedem anderen String-Parameter. Das component sieht die ID nie. Aus der Sicht des component-Autors ist ein secret nur ein konfigurierter String mit dem secret: true-Flag im Manifest. Der Autor deklariert, welche Parameter secrets sind; der Autor gibt keinen secret-Wert ein — Werte werden später erstellt, aus einer interaktiven Session oder der workspace-UI.

Ein secret-Parameter kann auch als Maybe<String> (ein optionales secret, das auf Nothing () defaultet) oder List<String> (eine Menge von secrets, etwa die während eines Rotationsfensters akzeptierten Schlüssel) deklariert werden. Ein ungebunden gelassenes optionales secret wird gar nicht an das component übergeben; ein List<String>-secret erreicht das component als List<String> aufgelöster Werte in Bindungsreihenfolge. Jeder andere deklarierte Typ wird für secret: true abgelehnt.

Die Klassifizierung ist die Entscheidung des component-Autors: ein Parameter, dessen Wert auf keiner Oberfläche erscheinen soll, bekommt secret: true; alles andere bleibt ein normaler Parameter. Die Plattform erzwingt das Flag zur Bindungszeit — ein als secret: true deklarierter Parameter lehnt literale Werte ab, und ein nicht als secret: true deklarierter Parameter lehnt secret-IDs ab.

Der backend-Autor bindet per ID

Verwende diesen Rahmen, wann immer ein backend einen secret-Parameter setzen muss.

Die Bindung ist eine normale Parameter-Mutation — dasselbe ppl backend change-parameter-Verb, das jeden anderen Parameter setzt, wobei der Wert die ID des secret ist statt eines Literals:

ppl backend change-parameter <bid> --vertex <v> \    --name hf_token --type String --value "<secret_id>"

Das Typsystem validiert die Bindung beim change-parameter-Aufruf. Ein secret: true-Slot lehnt literal aussehende Werte ab; ein Nicht-secret-Slot lehnt Werte ab, die zu secret-IDs auflösen. Eine Diskrepanz schlägt zur Bearbeitungszeit fehl, vor jedem Deploy.

Die ID stammt aus ppl secret list (oder der workspace-UI). Das Auflisten liefert nur Metadaten — ID, Name, Beschreibung, zuletzt aktualisiert — nie einen Wert. Das Erstellen eines secret liefert seine ID zurück, und diese ID ist das, was der backend-Autor bindet. Erstellen, Aktualisieren, Rotieren und Löschen von secrets sind workspace-Mutationen, die nur aus einer interaktiven ppl login-Session laufen — das ist die eine Menge an Operationen, bei der der Wert tatsächlich eingegeben wird, und diese Eingabe gehört auf eine Oberfläche, die ihn nicht in die Befehlshistorie oder Automatisierungslogs spiegelt.

Wie Rotation ohne Graph-Bearbeitungen funktioniert

Verwende diesen Rahmen, wann immer sich ein Credential ändern muss.

Das Rotieren eines secret-Werts erfordert keine backend-Bearbeitung. Das erneute Setzen eines secret unter seinem bestehenden Namen hält die ID über Rotationen hinweg stabil, die Bindung des backend an diese ID bleibt gültig, und der nächste Deploy jedes an die ID gebundenen backend nimmt den neuen Wert auf. Bestehende live deployments behalten ihren alten Wert, bis sie neu deployt werden.

Das zählt im Team-Maßstab. Wenn viele backends an denselben Hub-Token gebunden sind, ist das Rotieren des Tokens eine einzige Operation, und jedes backend nimmt den neuen Wert bei seinem nächsten Deploy auf. Die Bindung erfolgt an eine ID, sodass eine Wertänderung für jeden Graphen, der sie referenziert, unsichtbar ist.

Die Form des Designs

Die Trennung zwischen "workspace besitzt den Wert" und "backend referenziert den Wert" ist das, was den Rest des Designs funktionieren lässt. Zwei backends im selben workspace können dieselbe secret-ID binden und beim Deploy denselben Wert empfangen. Ein in einen anderen workspace geklontes backend wird an eine andere secret-ID neu gebunden, ohne dass ein Wert mit dem Graphen mitreist. Ein Team, das Credentials migriert, bewegt sie an der workspace-Grenze, und die daran gebundenen backends arbeiten weiter. Die ID ist der Vertrag; der Wert ist Sache des workspace.

Der Preis ist ein zusätzliches Konzept (das workspace secret) und ein zusätzlicher Schritt im Bindungsablauf (das Lesen der ID aus ppl secret list oder der UI). Im Gegenzug betritt der Wert nie eine Oberfläche, die er nicht sollte, die Rotation ist eine Operation pro Credential, und die secret/nicht-secret-Klassifizierung wird vom Typsystem der Plattform zur Bindungszeit erzwungen.

Wo das hinpasst

Workspace secrets sind der erstklassige Mechanismus der Plattform für mandanteneigene Drittanbieter-Credentials. Das bind-per-ID-Design hält den Wert von jeder benutzersichtbaren Oberfläche fern und lässt die häufigen Operationen einfach. Der component-Autor deklariert, welche Parameter secrets sind, der backend-Autor bindet IDs, der workspace-Besitzer verwaltet Werte, und die Plattform löst IDs zur Deploy-Zeit auf. Jede Rolle hat eine Aufgabe, und die Grenze zwischen ihnen ist das, was den Wert eingeschlossen hält.

Verwandt

Backends — wo die secret-ID an einen vertex-Parameter gebunden wird.
Components — wo secret: true deklariert wird.
Types — das Parametertyp-System, gegen das die Bindung validiert.
Solutions — backends, die Drittanbieter-Credentials innerhalb eines ausgelieferten Produkts brauchen.