> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

> Decide what people and agents may read and do in an ontology with Cedar policies: per action, per view instance, per field, with approvals for sensitive actions.

An ontology decides every call with [Cedar](https://www.cedarpolicy.com) policies that you write in the project. The same policies govern agents, people, and spaces. Tilde validates every policy at build time, against a schema generated from your objects, views, and handlers.

Access is deny by default. A call runs only if a policy permits it and no policy forbids it.

## Write a policy

`policy(id, cedar`...`)` holds exactly one `permit` or `forbid`. Interpolate handlers, views, objects, and properties, and Tilde writes the Cedar names for you.

```ts ontology/policies.ts theme={"system"}
import { cedar, group, lake, policy, query, readField } from "@tilde/ontology";
import { CustomerView, customerOverview, addCustomerNote, creditCustomer, topCustomers } from "./customer.ts";
import { Customer } from "./sales.ts";

const person = cedar`principal.type == "user"`;
const agent = cedar`principal.type == "agent"`;

export const policies = [
  // The sales team runs everything on customers.
  policy("sales", cedar`permit(principal in ${group("sales")}, action, resource is ${CustomerView});`),

  // People and agents see every field, except where a forbid below says otherwise.
  policy("fields", cedar`permit(principal, action == ${readField}, resource) when { ${person} || ${agent} };`),

  // Agents read customers and write notes.
  policy("agents", cedar`permit(principal, action in [${customerOverview}, ${addCustomerNote}], resource is ${CustomerView}) when { ${agent} };`),

  // Agents credit small amounts only, and never for gold customers.
  policy("agent-credits", cedar`permit(principal, action == ${creditCustomer}, resource) when { ${agent} && context.input.amount < 100 };`),
  policy("no-gold-credits", cedar`forbid(principal, action == ${creditCustomer}, resource is ${CustomerView}) when { ${agent} && resource.tier == "gold" };`),

  // Internal notes are for people only, in every handler.
  policy("notes-for-people", cedar`forbid(principal, action, resource == ${Customer.internalNotes}) unless { ${person} };`),

  // Everyone may list customers.
  policy("list", cedar`permit(principal, action == ${topCustomers}, resource == ${lake}) when { ${person} || ${agent} };`),
  policy("query", cedar`permit(principal, action == ${query}, resource) when { ${person} || ${agent} };`),
];
```

List them in `ontology({ policies })`.

## Principals

Each call carries a subject, and the actors acting for it. The subject and every actor must each be allowed. An agent never exceeds the person it acts for, and the person never exceeds the agent.

| Who calls | Subject | Actor |
| - | - | - |
| A person in **Live** or a space | `user:<id>` | None |
| An agent serving a signed-in Tilde user | `user:<id>` | `agent:<id>` |
| An agent on a routine, or talking to a channel address such as a phone number | `agent:<id>` | None |

Use these in conditions:

| Expression | Matches |
| - | - |
| `principal.type == "user"` | A person, or `"agent"` for an agent. |
| `principal in ${group("sales")}` | Members of a Tilde group. A team's group is `<team-slug>/<name>`. |
| `principal == Principal::"agent:<id>"` | One agent. |
| `principal.hasTag("routine")`, `principal.getTag("thread")` | The routine, thread, or signal that triggered the call. |

## Resources and actions

| Resource | Actions on it |
| - | - |
| A view instance, `resource is ${CustomerView}` | The view's reads and actions. `resource` has the root object's properties, such as `resource.tier`. |
| All data, `resource == ${lake}` | View-less reads, and realtime views with `watch`. |
| An object type or model | `query`, which view-less reads need for each object they read. |
| A property, `resource == ${Customer.internalNotes}` | `readField`, and each edit an action makes. |
| A space, `resource == ${space("pipeline")}` | `openSpace`. See [Spaces](https://trytilde.ai/docs/ontology/spaces.md#who-can-open-a-space). |

`context.input` is the handler's input, typed from its zod schema.

## Field masking

A caller sees a property only with `readField` on it. Otherwise the value is null wherever a handler loads it, in output fields tagged with `prop()`, and inside handler SQL. Grant `readField` broadly, and `forbid` the sensitive properties.

## Edits

Each edit an action makes is checked on its own. Edits are permitted by default, so only a `forbid` refuses one. The `notes-for-people` policy above stops agents changing internal notes through any action.

## Approvals

An action can require a person's approval. Permit it only when `context.approved` is true. A caller who is otherwise allowed then gets **pending approval**, and the input waits for a decision.

```ts theme={"system"}
import { approve, approveOf } from "@tilde/ontology";

export const approvals = [
  // Agents change tiers only once approved.
  policy("agent-tiers", cedar`permit(principal, action == ${updateCustomerTier}, resource) when { principal.type == "agent" && context.approved };`),
  // Managers approve anything that needs approval.
  policy("managers-approve", cedar`permit(principal in ${group("managers")}, action in ${approve}, resource is ${CustomerView});`),
  // Downgrades to bronze need a staff approver.
  policy("bronze-needs-staff", cedar`forbid(principal, action == ${approveOf(updateCustomerTier)}, resource) when { context.input.tier == "bronze" } unless { principal in ${group("staff")} };`),
];
```

Nobody in the requester's own chain can approve their request. Approvals expire after seven days. Tilde checks the requester's policies again when the request is approved.

## Audit

Tilde audits every decision, with the policies that decided it, and every finished action with its input and result. Values that carry one of the environment's secrets are never recorded.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.