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

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 Besucher lesen. Setze eine Regel, die mit einem Anführungszeichen beginnt, in Quotes, etwa read: '"finance" in user.groups', damit YAML sie als Text liest.

Namen

Jede Regel sieht user, die Lookups und den Datensatz ihrer Operation. Ein Name, der nicht verfügbar ist, lässt connic lint scheitern.

user ist der angemeldete 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.

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.
• doc.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.

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 wertet connic alle Teile einer Regel aus, die den gespeicherten Datensatz nicht betreffen: user, die Lookups und new. Was über den Datensatz übrig bleibt, wird zu einem Filter, den connic dem Filter des Browsers 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 mit 403 ab. 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. 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, und der new-Teil prüft das Update. Eine Regel auf new.status scheitert, wenn das Update status nicht setzt.
• 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.
• Eine Regel kann für einen einzelnen Besucher 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 mit 500 This app's access rule makes a database filter that is too large: <reason>. Simplify the rule or the values it compares with.

Ö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 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.

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"

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