Access Rules

Rules

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

A missing resource, collection, folder, namespace, or operation is denied. YAML true and false are rules too: read: true lets every visitor read. Quote a rule that starts with a quotation mark, as in read: '"finance" in user.groups', so YAML reads it as text.

Names

Each rule sees user, the lookups, and the record of its operation. Using a name that isn't available fails connic lint.

user is the signed-in visitor; see Sign-in for what id, groups, and claims hold in each mode. run.input and run.output can be read as JSON, as in run.input.order_id. Runs started from an app carry the visitor in run.context.end_user, and approvals carry it in approval.context.end_user.

Grammar

Rules use connic's expression language, the same one as approval rules and conditional tools: comparisons, and, or, not, in, not in, paths with dots or subscripts, and literals, without function calls or arithmetic, up to 2,000 characters. Because connic turns the record part of a rule into a query filter, these limits apply to the record names doc, file, run, session, and approval:

• Compare a field with a value, as in doc.done == true. A bare doc.done is rejected.
• A rule can't compare two fields of the record, or a field of the record with new.
• doc.id, run.id, run.status, approval.id, and approval.status take only ==, !=, in, and not in.
• Field names can't start with _ or $ or contain dots. Stored system fields are id, created_at, and updated_at.

Every rule also follows these limits:

• is and is not work only with the literals null, true, and false.
• A comparison can't take another condition as a value, so (doc.done == true) == false is rejected. Combine comparisons with and, or, and not.
• Database and file rules, and the where of lookups, become database filters with these limits: 10 levels of nesting, of which the filter connic wraps around access rules takes one, 100 branches per and or or, 256 terms, and 1,000 values per in list.

connic lint checks syntax and names. Deploys of public apps warn in the deployment log about rules that let every visitor read everything, write without depending on the visitor, or upload without a size limit. The deploy checks that connic can enforce every rule and fails with the rule's path, for example with use is and is not only with null, true or false or 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

How rules apply

For each request, connic evaluates every part of a rule that doesn't involve the stored record: user, the lookups, and new. What's left about the record becomes a filter that connic adds to the browser's own. Lists, counts, totals, updates, and deletes therefore only ever touch allowed records.

• A rule that is false whatever the record denies the request with 403. For a single run, file, session, or approval, a record the rule doesn't allow answers 404, like one that doesn't exist.
• insert and files write check new before the write. Every document of an insert must pass, or nothing is inserted.
• Database update changes only the documents the doc part allows, and the new part checks the update. A rule on new.status fails when the update doesn't set status.
• Files update sees the file before the change as file and after it as new. Moving a file to another folder also needs that folder's write rule.
• A rule can still make a filter that is too large for one visitor, for example doc.team in user.groups for someone in more than 1,000 groups. The request then fails with 500 This app's access rule makes a database filter that is too large: <reason>. Simplify the rule or the values it compares with.

Public visitors

On a public app, user.signed_in is false, user.email and user.name are null, user.groups is empty, and user.id is the browser's visitor ID.

Comparisons with a public visitor's email are unknown, so doc.owner == user.email matches no document, not even one whose owner is null, and a lookup with where: doc.email == user.email finds nothing.

connic derives the visitor ID from a secret in the browser's cookie, separately for each app, so knowing someone's ID doesn't let anyone act as them. The ID changes when the cookies are cleared, and anyone can get a new one. Rules on user.id fit data that belongs to one browser, such as a draft, not data that needs an account.

Protect public forms

Anyone can submit the forms of a public app, bots included. Writes through the data API are checked against your rules but run no middleware, so they can't check a challenge. For forms that bots target, protect the form yourself and let an agent do the write:

1. 1

   Add a challenge service, such as a CAPTCHA, to the form. It adds a token to the submission.

2. 2

   Send the form to a sync webhook connector with apps_only: true at /_connic/c/<key>, instead of inserting it through the data API.

3. 3

   In the agent's middleware, verify the token with the challenge service and stop the run when the check fails. The agent then writes with database tools.

4. 4

   Leave insert out of the collection's rules, so the browser can't write past the check.

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("The form check failed. Reload the page and try again.")
    return content

The verification request depends on the challenge service; the example sends the token and a secret to the service's verification URL, both stored as Variables. StopProcessing ends the run before the agent starts, and the form gets the message as the run's output. A rate_limit on the connector caps how many runs the form can start per minute. connic doesn't check challenges itself.

Examples

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