Zugriffsregeln

Regeln

lookups:
  member:
    collection: members
    where: doc.email == user.email
access:
  database:
    tickets:
      read: doc.author_id == user.id or member.role == "agent"
      insert: user.signed_in == true
      update: doc.author_id == user.id and doc.status == "open"
      delete: member.role == "admin"
      set:
        author_id: user.id
        status: '"open"'
  files:
    attachments:
      read: member.role == "agent"
  runs:
    read: run.context.end_user.id == user.id
  retrieval:
    help:
      search: true

access:
  database:
    "*":
      read: true
    tickets:
      read: user == null or doc.author_id == user.id
      insert: true
      update: user == null or doc.author_id == user.id
  files:
    uploads:
      read: file.session_id == session.id
      write: true
  retrieval:
    help:
      search: true
    notes:
      search: true
      store: true

Eine fehlende Ressource, Collection, ein fehlender Ordner, Namespace oder eine fehlende Operation ist verboten. Auch YAML-true und false sind Regeln: read: true lässt jeden lesen. Setze eine Regel, die mit einem Anführungszeichen beginnt, in Quotes, etwa read: '"finance" in user.groups', damit YAML sie als Text liest.

Der Eintrag "*" gilt für jede Collection, jeden Ordner und jeden Namespace ohne eigenen Eintrag. Ein benannter Eintrag hat Vorrang, auch ein leerer: secrets: {} neben "*": {read: true} verbietet jede Operation auf secrets. Setze den Key in Quotes, denn ein bloßes * liest YAML als Alias.

Namen

Jede Regel sieht user, die Lookups und den Datensatz ihrer Operation; Regeln von Agenten sehen außerdem context und session. Ein Name, der nicht verfügbar ist, lässt connic lint scheitern.

In Apps ist user der Besucher; was id, groups und claims in jedem Modus enthalten, steht unter Anmeldung. run.input und run.output lassen sich als JSON lesen, etwa run.input.order_id. Runs, die eine App startet, tragen den Besucher in run.context.end_user, Freigaben in approval.context.end_user.

In Agenten ist user der Besucher der App, deren Anfrage den Run gestartet hat, auch in den Agenten, die dieser Run mit trigger_agent startet. connic übernimmt ihn aus der signierten App-Anfrage, Middleware und Tools können ihn also nicht ändern. Runs ohne App-Besucher, etwa per Cron, Webhook oder aus dem Dashboard, haben user null.

Agenten

Regeln in agents/<name>.yaml legen fest, was die eingebauten Tools des Agenten dürfen, egal ob das Modell sie aufruft oder deine eigenen Tools über connic.tools. Ein verbotener Aufruf liefert statt eines Ergebnisses einen Fehler, und Listen und Zählungen sehen nur erlaubte Datensätze.

• Database Tools nutzen die Regeln unter database. db_upsert braucht insert und update und wird abgelehnt, wenn sein Filter nur Dokumente trifft, die die Regeln verbergen.
• File Tools nutzen die Regeln unter files, ebenso Downloads des Browsers in Dateien, Uploads des Browsers aus Dateien, Dateien, die retrieval_store importiert, und Freigabelinks in Ergebnissen von retrieval_query.
• Retrieval Tools nutzen die Regeln unter retrieval: search für retrieval_query, store für retrieval_store und delete für retrieval_delete. Eine Suche ohne Namespace braucht den Eintrag "*".
• Sobald ein Agent access hat, scheitert connic lint, wenn er ein eingebautes Tool nutzt, dessen Ressource keine Einträge hat, denn jeder Aufruf wäre verboten. Jede Ressource nimmt bis zu 100 Einträge.
• Regeln auf user verbieten Runs ohne Besucher. Mit user == null or ... lässt du diese Runs durch. Ein set-Wert, der user liest, verbietet das Schreiben, wenn es keinen Besucher gibt.
• lookups steht in der Agent-Datei neben access. Ihr where kann auch context und session nutzen, und ein Lookup darf nicht context heißen.

Das Deployment prüft die Regeln von Agenten wie die von Apps und scheitert mit der Agent-Datei und dem Pfad der Regel. Für Agenten mit den älteren Einstellungen siehe database, retrieval und files ersetzen.

Syntax

Regeln nutzen die Ausdruckssprache von connic, dieselbe wie Approval-Regeln und bedingte Tools: Vergleiche, and, or, not, in, not in, Pfade mit Punkten oder Subscripts und Literale, ohne Funktionsaufrufe und Arithmetik, bis zu 2.000 Zeichen. Weil connic den Teil einer Regel, der den Datensatz betrifft, in einen Abfragefilter übersetzt, gelten für die Datensatznamen doc, file, run, session und approval diese Grenzen:

• Vergleiche ein Feld mit einem Wert, etwa doc.done == true. Ein bloßes doc.done wird abgelehnt.
• Eine Regel kann weder zwei Felder des Datensatzes noch ein Feld des Datensatzes mit new vergleichen.
• In update-Regeln der Datenbank nutzt du new über seine Felder, etwa new.status, und vergleichst jedes mit einem Wert: Zwei Felder von new lassen sich nicht vergleichen.
• doc.id, file.session_id, run.id, run.status, approval.id und approval.status erlauben nur ==, !=, in und not in.
• Feldnamen dürfen nicht mit _ oder $ beginnen und keine Punkte enthalten. Die gespeicherten Systemfelder heißen id, created_at und updated_at. Dasselbe gilt für die Namen unter set und fields und für jeden Teil des values-Pfads eines Lookups, der aus mehreren Teilen bestehen kann, etwa team.id. Andere Namen lehnen connic lint und das Deployment ab.

Außerdem gelten für jede Regel diese Grenzen:

• is und is not funktionieren nur mit den Literalen null, true und false.
• Ein Vergleich kann keine andere Bedingung als Wert nehmen, deshalb wird (doc.done == true) == false abgelehnt. Verknüpfe Vergleiche mit and, or und not.
• Regeln für Datenbank und Dateien sowie das where von Lookups werden zu Datenbankfiltern mit diesen Grenzen: 10 Verschachtelungsebenen, von denen der Filter, den connic um Zugriffsregeln legt, eine belegt, 100 Zweige pro and oder or, 256 Terme und 1.000 Werte pro in-Liste.

connic lint prüft Syntax und Namen. Bei öffentlichen Apps warnt das Deployment im Log vor Regeln, die jeden Besucher alles lesen lassen, Schreibzugriffe nicht vom Besucher abhängig machen oder Uploads ohne Größengrenze erlauben. Das Deployment prüft, ob connic jede Regel durchsetzen kann, und scheitert mit dem Pfad der Regel, etwa mit use is and is not only with null, true or false oder it compiles to a database filter that is too large: <reason>:

App validation failed:
  - apps/portal.yaml: access.database.tickets.read: can't compare two fields of doc

So wirken die Regeln

Bei jeder Anfrage und jedem Tool-Aufruf wertet connic alle Teile einer Regel aus, die den gespeicherten Datensatz nicht betreffen: user, die Lookups, new und in Agenten context und session. Was über den Datensatz übrig bleibt, wird zu einem Filter, den connic dem Filter des Aufrufers hinzufügt. Listen, Zählungen, Summen, Updates und Löschungen erreichen deshalb nur erlaubte Datensätze.

• Eine Regel, die unabhängig vom Datensatz falsch ist, lehnt die Anfrage ab, in Apps mit 403. Bei einem einzelnen Run, einer Datei, Session oder Freigabe antwortet ein Datensatz, den die Regel nicht erlaubt, mit 404, als gäbe es ihn nicht.
• insert und write bei Dateien prüfen new vor dem Schreiben, also das Dokument oder den Upload mit den Feldern aus set. Jedes Dokument eines Inserts muss die Regel erfüllen, sonst wird nichts eingefügt.
• update in der Datenbank ändert nur die Dokumente, die der doc-Teil erlaubt. new ist jedes Dokument nach der Änderung: die Felder, die das Update schickt, und für alle anderen die gespeicherten Werte. Ein Feld, das das Update auf null setzt, fehlt in new. update: new.status == "open" lässt also ein Update des Titels bei offenen Tickets durch.
• update bei Dateien sieht die Datei vor der Änderung als file und danach als new. Wer eine Datei in einen anderen Ordner verschiebt, braucht zusätzlich dessen write-Regel.
• Ein Upsert braucht insert und update. Er ändert das erste Dokument, das die Regeln ändern lassen, oder fügt eines ein, das die Insert-Regel erlaubt. Trifft sein Filter nur Dokumente, die die Regeln nicht ändern lassen, wird er abgelehnt.
• Eine Regel kann für eine einzelne Anfrage trotzdem einen zu großen Filter ergeben, etwa doc.team in user.groups für jemanden in mehr als 1.000 Gruppen. Die Anfrage scheitert dann, in Apps mit 500 An access rule makes a database filter that is too large: <reason>. Simplify the rule or the values it compares with.

access:
  database:
    tickets:
      set:
        author_id: user.id            # beim Insert
        updated_by:
          value: user.id
          writes: [insert, update]
  files:
    uploads:
      set:
        uploaded_by: user.id          # Metadaten jedes Uploads

access:
  database:
    tickets:
      read: doc.author_id == user.id or member.role == "agent"
      update: doc.author_id == user.id or member.role == "agent"
      fields:
        internal_notes: member.role == "agent"

lookups:
  teams:
    collection: memberships
    where: doc.user_id == user.id
    values: team_id
access:
  database:
    projects:
      read: doc.team_id in teams

Öffentliche Besucher

In einer öffentlichen App ist user.signed_in false, user.email und user.name sind null, user.groups ist leer, und user.id ist die Besucher-ID des Browsers.

Vergleiche mit der E-Mail-Adresse eines öffentlichen Besuchers sind unbestimmt. doc.owner == user.email trifft deshalb kein Dokument, auch keines, dessen owner null ist, und ein Lookup mit where: doc.email == user.email findet nichts.

connic leitet die Besucher-ID für jede App getrennt aus einem Secret im Cookie des Browsers ab. Wer die ID eines anderen kennt, kann also nicht in dessen Namen handeln. Die ID ändert sich, wenn jemand die Cookies löscht, und jeder kann sich eine neue holen. Regeln auf user.id passen zu Daten, die zu einem Browser gehören, etwa einem Entwurf, nicht zu Daten, die ein Konto brauchen.

Öffentliche Formulare schützen

Die Formulare einer öffentlichen App kann jeder absenden, auch Bots. Schreibzugriffe über die Data API prüft connic gegen deine Regeln, aber ohne Middleware, eine Challenge lässt sich dort also nicht prüfen. Für Formulare, die Bots anziehen, schützt du das Formular selbst und lässt einen Agenten schreiben:

1. 1

   Binde einen Challenge-Dienst wie ein CAPTCHA in das Formular ein. Er fügt dem Absenden ein Token hinzu.

2. 2

   Schicke das Formular an einen Sync-Webhook-Connector mit apps_only: true unter /_connic/c/<key>, statt es über die Data API einzufügen.

3. 3

   Prüfe das Token in der Middleware des Agenten beim Challenge-Dienst und stoppe den Run, wenn die Prüfung scheitert. Danach schreibt der Agent mit Database Tools.

4. 4

   Lass insert in den Regeln der Collection in der App weg, damit der Browser nicht an der Prüfung vorbei schreiben kann.

import os

import httpx
from connic import StopProcessing


async def before(content, context):
    token = context["payload"].get("challenge_token")
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.post(
            os.environ["CHALLENGE_VERIFY_URL"],
            data={"secret": os.environ["CHALLENGE_SECRET"], "response": token},
        )
    if not response.json().get("success"):
        raise StopProcessing("Die Formularprüfung ist fehlgeschlagen. Lade die Seite neu und versuche es noch einmal.")
    return content

Wie die Prüfung aussieht, hängt vom Challenge-Dienst ab; das Beispiel schickt das Token und ein Secret an die Prüf-URL des Dienstes, beide als Variablen gespeichert. StopProcessing beendet den Run, bevor der Agent startet, und das Formular bekommt die Meldung als Ausgabe des Runs. Ein rate_limit am Connector begrenzt, wie viele Runs das Formular pro Minute starten kann. connic prüft Challenges nicht selbst.

database, retrieval und files ersetzen

Agenten können ihre Tools noch mit den älteren Einstellungen database, retrieval und files beschränken. Diese Einstellungen sind veraltet, und connic setzt sie als die Zugriffsregeln unten durch. connic lint warnt davor und gibt den passenden access-Block aus, den du an ihrer Stelle einfügst, und das Deployment warnt im Log. Ein Agent kann nicht gleichzeitig access und die älteren Einstellungen haben.

Eine Einstellung an einem Eintrag hat Vorrang vor der obersten Ebene, und verschachtelte Namespaces folgen dem genauesten Eintrag.

Beispiele

access:
  database:
    notes:
      read: doc.owner_id == user.id
      insert: user.signed_in == true
      update: doc.owner_id == user.id
      delete: doc.owner_id == user.id
      set:
        owner_id: user.id

lookups:
  member:
    collection: members
    where: doc.email == user.email
access:
  database:
    orders:
      read: doc.customer_id == member.customer_id or member.role == "admin"
      update: member.role == "admin"

tools:
  - db_find
  - db_update
lookups:
  member:
    collection: members
    where: doc.email == user.email
access:
  database:
    orders:
      read: user == null or doc.customer_id == member.customer_id
      update: user == null or doc.customer_id == member.customer_id

session:
  key: context.customer_id
tools:
  - file_list
  - file_read
  - file_write
access:
  files:
    uploads:
      read: file.session_id == session.id
      write: true
      update: file.session_id == session.id
    templates:
      read: true

auth:
  mode: public
access:
  database:
    articles:
      read: doc.status == "published"

access:
  files:
    invoices:
      read: '"billing" in user.groups'
    uploads:
      read: file.metadata.uploaded_by == user.id
      write: >-
        new.metadata.uploaded_by == user.id
        and new.mime_type == "application/pdf"
        and new.size <= 10000000

access:
  runs:
    read: run.context.end_user.id == user.id
    cancel: run.context.end_user.id == user.id and run.status in ["queued", "started"]

access:
  approvals:
    read: '"finance" in user.groups'
    decide: '"finance" in user.groups and approval.tool == "issue_refund" and approval.params.amount < 5000'

auth:
  mode: public
access:
  retrieval:
    help:
      search: true
  files:
    retrieval/help:
      read: true