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

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

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

The entry "*" covers every collection, folder, or namespace without an entry of its own. A named entry wins over it, even an empty one: secrets: {} next to "*": {read: true} denies every operation on secrets. Quote the key, because YAML reads a bare * as an alias.

Names

Each rule sees user, the lookups, and the record of its operation; agent rules also see context and session. Using a name that isn't available fails connic lint.

In apps, user is the 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.

In agents, user is the visitor of the app whose request started the run, also in the agents that run starts with trigger_agent. connic takes it from the signed app request, so middleware and tools can't change it. Runs no app visitor started, such as from cron, a webhook, or the dashboard, have user null.

Agents

Rules in agents/<name>.yaml decide what the agent's built-in tools may do, whether the model calls them or your own tools call them through connic.tools. A denied call returns an error instead of a result, and lists and counts only see allowed records.

• Database tools use database rules. db_upsert needs insert and update, and is denied when its filter matches only documents the rules hide.
• File tools use files rules, and so do browser downloads into files, browser uploads from files, files that retrieval_store imports, and share links in retrieval_query results.
• Retrieval tools use retrieval rules: search for retrieval_query, store for retrieval_store, and delete for retrieval_delete. A search without a namespace needs the entry "*".
• Once an agent has access, connic lint fails when it lists a built-in tool whose resource has no entries, because every call would be denied. Each resource takes up to 100 entries.
• Rules on user deny runs without a visitor. Write user == null or ... to let those runs through, and keep in mind that a set value that reads user denies the write when there is no visitor.
• lookups sit next to access in the agent file. Their where can also use context and session, and a lookup can't be called context.

Deploys check agent rules like app rules and fail with the agent file and the rule's path. See Replace database, retrieval, and files for agents that still use the older settings.

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.
• In database update rules, use new through its fields, as in new.status, and compare each with a value: two fields of new can't be compared.
• doc.id, file.session_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. The same goes for the names under set and fields, and for each part of a lookup's values path, which may have several parts, as in team.id. connic lint and the deploy reject other names.

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 or tool call, connic evaluates every part of a rule that doesn't involve the stored record: user, the lookups, new, and in agents context and session. What's left about the record becomes a filter that connic adds to the caller'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 in apps. 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, the document or upload with the fields set writes, before the write. Every document of an insert must pass, or nothing is inserted.
• Database update changes only the documents the doc part allows. new is each document after the change: the fields the update sends, and the stored values for the rest. A field the update sets to null is gone from new. So update: new.status == "open" lets an update of the title through on open tickets.
• 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.
• An upsert needs insert and update. It updates the first document the rules let change, or inserts one the insert rule allows, and is denied when its filter matches only documents the rules don't let change.
• A rule can still make a filter that is too large for one request, for example doc.team in user.groups for someone in more than 1,000 groups. The request then fails, in apps with 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            # on insert
        updated_by:
          value: user.id
          writes: [insert, update]
  files:
    uploads:
      set:
        uploaded_by: user.id          # metadata of each upload

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

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 in the app, 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.

Replace database, retrieval, and files

Agents can still limit their tools with the older database, retrieval, and files settings, which are deprecated. connic enforces them as the access rules below. connic lint warns about them and prints the matching access block to paste in their place, and deploys warn in the log. An agent can't have both access and the older settings.

A setting on an entry wins over the top-level one, and nested namespaces follow the most specific entry.

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"

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