id: cedar-engine title: Cedar is the second engine, and it never permits by accident status: open crates: [didbot-policy, didbot-pds, didbot-lexicon] dependsOn: [policy] exitCriterion: > A bot.did.policy with engine cedar refuses a write, the refusal carries the statement's @id and @reason, a document with a typo in a field name refuses every write in its scope rather than permitting one, and a policy over a collection with a public lexicon is rejected at load when it reads a field that lexicon does not have. #

cedar-engine #

The envelope names its engine. The first is the regex engine; the second is Cedar, through the cedar-policy crate. Cedar brings a typed schema, a validator, time arithmetic and a hierarchy operator that matches the admission tree. It also has three behaviours that are wrong for a deny-only server unless the engine is built around them, and this epic exists to write those down before the crate is added. Everything below was checked against Cedar 4.12 (language 4.5) with the four documents and ten requests in the policy lexicon workshop.

The request model #

One Cedar namespace, Didbot. The principal is always the account. The account tree is Cedar's entity hierarchy: entity Account in [Account], with each account's parents being the accounts that admitted it. Reach still lives in the binding, which decides which documents load at all; a document may narrow further with principal in, and that is allowed and unremarkable.

Each action is one Cedar action with a fixed resource type and context record. This table is the schema, and the schema is generated from it, not written twice.

A write's client is the Client its OAuth token was issued to, the same entity the two OAuth actions take as their resource. So context.client.id like "https://app.example/*" at the write reads like resource.id like "https://app.example/*" at sign-in. A write made with the account's own credential has no client, and a statement tests context has client before reading it.

The principal of every action is an Account carrying kind, handle and depth (edges between it and the operator) when the gate knows them; a statement guards each with has.

now and every timestamp are Cedar datetime values, so a document can say context.now.durationSince(context.existing.createdAt) > duration("1d"). A create over a tombstone arrives with existing populated and operation set to create, per account-data.

Three rules the engine enforces #

Every statement loads under its @id. Handed a document as one text, Cedar numbers the statements policy0, policy1, and a refusal names nothing. The loader splits the document into statements, requires @id on each, requires them to be unique within the document, and loads the set keyed by them. A forbid also requires @reason; the refusal on the wire is the envelope's name, the statement's @id and its @reason, the same three things the regex engine returns.

An evaluation error is a refusal. Cedar treats a policy that errors as not satisfied. For a permit that is safe. For a forbid it means a misspelled field name, or a missing has guard on an optional field, permits the write and tucks the error into the diagnostics. The engine reads the diagnostics after every decision and refuses when they hold any error, naming the statement and saying the check could not complete. A document with a typo therefore refuses everything in its scope, which is loud, rather than permitting silently.

A document may only forbid. Until policy-exemptions ships closed subtrees, the server's baseline is one permit(principal, action, resource) and every loaded document is checked at build time to contain forbids only. A permit in a document is a load error on the dashboard, because a permit that does nothing today would start doing something the day closure exists.

Validation, and what happens without it #

Cedar validates a document against a schema at load, in strict mode. The schema's record types are generated per collection from the lexicon the server knows for it, either shipped in didbot-lexicon or resolved through the published com.atproto.lexicon.schema record for the NSID's authority. Validation happens in the candidate build that policy already describes: the current set keeps serving, the candidate is built and validated in memory, every failure is reported to the dashboard, and the swap happens only when the candidate is clean. Seeing a new collection for the first time triggers a resolve and a rebuild.

A collection with no resolvable lexicon is evaluated unvalidated: Cedar runs without a schema and reads whatever attributes the record has. This works, and it was tested: nested fields, like on a nested URI, and set membership all evaluate. What it loses is catching mistakes at load. A typo surfaces at the first write that reaches the path, as a refusal under the rule above, and the dashboard shows evaluation errors as a second-class signal beside load errors. The open-record schema feature that would let a schema cover the typed part and leave the record open is experimental in Cedar and is not used.

What Cedar cannot say #

• Regex, or case folding. Strings have like with *. A content rule over free text is a regex document.
• Order. JSON arrays become Cedar sets. A rule about the first image or the order of facets is not a Cedar rule.
• Counts or history. Cedar sees one request. Counters and historical facts are the stateful evaluator's, in the resolver and state seams the policy epic keeps open.

Not this epic #

Templates and template links, partial evaluation, and the datetime extension beyond now, durationSince and duration literals. Each is a seam Cedar leaves open and none has a scenario yet.

Work #

• Schema generation from lexicons, the resolve-on-first-sight rebuild, and the unvalidated path for a collection with no lexicon, each flagged to the dashboard.
• Each gate hands the engine the account's admission chain. Request::build makes the chain into the principal's parents when a gate passes one, and no gate does: crates/didbot-policy-cedar/src/shared.rs builds every principal with admitted_by: None, so a statement scoped with principal in refuses every request it is asked about.
• Each gate hands the engine the whole table. Today record.write gives no rkey. A create over a tombstone arrives as an update. oauth.authorize gives no account, and oauth.token no grant. blob.write gives the account, the declared and sniffed types and the size, and no space. A statement reading what its gate leaves out refuses, so no-late-edits reads createdAt as the string it is stored as rather than a datetime, while no shape describes posts.

Done #

• The cedar engine behind the evaluator contract, in its own crate beside the regex engine, with the four workshop documents and ten requests as its tests. crates/didbot-policy-cedar is the engine; didbot_pds::policy_tree::CedarLanguage registers it for bot.did.policy#cedar, and policy_bindings registers each statement under {key}/{@id}/{action}, so a refusal reports the statement the way a regex statement is reported by its index.
• The loader: statements split and keyed by @id; @id unique and required; @reason required on forbids; forbid-only enforced; every failure a build result, not a log line. Document::load splits a document with Cedar's own parser and reports every failure at once by statement. Shapes holds one schema per described collection; a statement is validated against each described collection it names, or every described one when it names none, and a statement that reads the record of a collection with no shape loads with an unvalidated for warning that reaches LoadReport::warnings. The server describes no collection yet, so every record read is evaluated unvalidated.
• Error-is-refusal, with a test that a misspelled field refuses and names the statement. Document::decide reads the diagnostics after every decision and refuses on any error, naming the statement.
• record.write carries the client, as context.client, so a Cedar policy refusing an app at token issue can refuse the tokens it already holds at the write. spares_held_tokens reports a Cedar policy refusing at sign-in or token issue only when none of its record.write statements reads context.client.
• Entities per request: the resource and context for the action. Request::build makes every entity and context in the table. A statement whose scope needs what the request does not carry refuses rather than never matching.
• value and existing are the records themselves. The write path holds both sides already and hands them to the gate whole, on Subject::Write, beside the diff the applicability index walks. A record cannot be recovered from a diff: a path string is not a parse of the key that produced it, so two fields of one record can spell one path, and an update's diff names only what it touched. Both were ways for a statement to be asked about something the repository does not hold.
• A write's request is built once. Every statement asked about a subject judges one request built for it, whichever evaluator holds the statement. Each thread keeps the last request it built, and a subject reuses it only when equal in every field (crates/didbot-policy-cedar/src/shared.rs).
• What a thread keeps between writes is bounded. The kept request holds the record the write carried, so it is kept only while the reuse it exists for can happen: the next miss on any thread drops every entry idle for five seconds, and a subject over 64 KiB is judged from a request built the same way and then not kept at all. Both numbers are constants in shared.rs rather than configuration — they bound the engine's own working set, not anything an operator sizes.