Feld-Rechte

Manche Felder dürfen nicht alle sehen oder schreiben — z. B. interne Notizen oder Preise. Dafür sperrst du einzelne Felder pro Rolle, statt ganze Sammlungen zu schließen. Grundlage sind readonlyFields, hiddenFields und validProjections.

Wofür welcher Schalter

Schalter	Wo	Wirkung
`readonlyFields`	Collection, PermissionSet, Feld-Definition	Schreiben verboten: `POST`/`PUT` mit dem Feld → Fehler; Lesen bleibt erlaubt
`hiddenFields`	Collection, PermissionSet, Feld-Definition	Schreiben verboten und Lesen unsichtbar: Feld wird aus jeder `GET`-Antwort und aus `fields[]` der Config-Auslieferung entfernt
`validProjections`	nur PermissionSet	Erlaubte `?projection=`-Namen für diese Rolle; fremde Namen → `permission denied for given projection`
`readonly` / `hidden`	Feld-Definition (`fields[]`, auch `eval`)	Feldweit für alle Nicht-Admins (`true` = immer, `false` = niemals, `eval` = pro Dokument)

Die Kaskade lautet: Collection → PermissionSet → Feld-Definition. Die Feld-Definition hat das letzte Wort: readonly: false entfernt das Feld aus jedem effektiven Set, readonly: true fügt es immer hinzu. Ein --Prefix im PermissionSet zieht ab: readonlyFields: [-createdBy] entfernt ein Collection-Eintrag nur für diese Rolle. Elternpfade expandieren auf alle Unterfelder (payment schließt payment.cardNumber ein); einzelne Felder adressierst du per Dot-Notation (payment.cardNumber). Quelle der Wahrheit: tibi-types/schemas/config/permissions.schema.json und collection.schema.json (Feld-Definitionen); die Statuscode-Logik steht im Server (internal/controller/http_status.go).

So konfigurierst du es

readonlyFields: [createdBy]   # Ebene 1: gilt für alle Rollen
hiddenFields: [costPrice]

permissions:
  public:
    methods:
      get: true
    readonlyFields: [status, customerName]
    hiddenFields: [internalMargin, costPrice, payment.cardNumber]
    validProjections: [teaser]   # nur GET mit ?projection=teaser
  user:
    methods:
      get: true
      post: true
      put: true
    readonlyFields: [customerName]
    hiddenFields: [internalMargin]

fields:
  - name: createdBy
    type: string
  - name: costPrice
    type: number
  - name: lockedNote
    type: string
    readonly:
      eval: "$.status === 'confirmed'"   # nur gesperrt, wenn das Dokument bestätigt ist

Schema-Belege: permissions.schema.json (permissions.*.validProjections, *.readonlyFields, *.hiddenFields), collection.schema.json (Top-Level readonlyFields, hiddenFields).
eval kennt $ (Dokument), $this (Feldwert), $auth, $method, $project, $namespace.
Feld-Rechte gelten auch für "token:…"-PermissionSets — Tokens unterliegen denselben Listen wie Nutzer.

Verhalten und Fehler

Vorgang	readonly-Feld	hidden-Feld
`POST` / Bulk-`POST` (je Zeile)	Fehler	Fehler
`PUT` / Bulk-Update, inkl. Operatoren (`$set`, `$inc`, …)	Fehler	Fehler
`GET` Liste und Einzel	sichtbar	gestripped
Config-Auslieferung (`yourPermissions`)	Liste steht in `readonlyFields`	Liste wird nicht ausgeliefert; Feld-Definitionen fehlen in `fields[]`

Fehlerantwort (Status hängt von der Projekt-Config ab — modern 403, Legacy 400):

{"error": "readonly fields must not be sent", "fields": ["customerName"]}
// oder: {"error": "hidden fields must not be sent", "fields": ["costPrice"]}
// falsche Projektion: 400 {"error": "permission denied for given projection"}

Verwandt: Rechte und Tokens (Permission-Blöcke, Token-Köpfe), Lesen und suchen (select, projection, lookup).

Verifiziert am 68b4278 2026-10-17 (tibi-server)