i2y/ritsu/sekisho

When this applies

The job is the authorization of a service, written where it can be checked: which principal (a person signed in, a service, a workflow) may do which action on which resource, under which conditions, and which operation of the service's contract each action guards. sekisho writes it as a .gate, checks every combination of roles, attributes, inputs and the answers of the rules and dates it reads, and generates Cedar and the code that asks Cedar.

It does not apply to authentication (who the caller is: the service's own login, tokens, mTLS), to the balance of an account (that is a bound of chobo's book, kept in the write itself), or to a relation that goes more than one step (resource.project.owner): sekisho writes none of those.

The files bundled with this skill are reference.md (the whole language and the commands) and codes.md (every diagnostic). Read them when you need them, not all up front.

Working with sekisho

Your part is to write the gate, get it past ritsu sekisho check, generate what the service runs, and show the page to the people who decide who may do what. Three things stay with people:

1. Who may do what. The roles, the permits and the forbids are a decision of the business and

of security. Never add a permit, widen a role or drop a forbid to make the check pass.

1. What is expected to hold. An expect and a separate say what a person has decided must

never or always happen; when one does not hold, the policies are wrong or the expectation is, and only a person can say which.

1. That no one is meant to do an action (nobody "<why>").

1. The loop

1. Read what is there: the contract of the service (an OpenAPI or AsyncAPI document, a .proto),

the rules and dates the conditions will read, the workflows that call the service.

1. Write the gate: the heading, the use lines, today if a date is read, the enums, the roles,

the principals and workflows, the resources, the actions with what they guard, then the policies, the expectations and the separations.

1. Run the check and fix what it says, one diagnostic at a time, from the top; `ritsu sekisho

explain <code> says how. Then ritsu check` on the project, which adds the checks across the languages (X15, X16).

1. Generate the Cedar and the code that asks it, into the service's package (`ritsu gen --target

cedar --target <language>…, or ritsu sekisho gen --target …), and have CI run the same gen with --check`.

1. Write the page with ritsu sekisho doc, and show it to the people who decide.
2. When the gate changes, or a rule or a date it reads does, ritsu sekisho diff <old> <new> says

which combinations gained or lost a permission, and which are decided by other policies, with an example of each. Each side is a path, <path>@<git revision>, @<name>/<path> (a dependency at the lock's version) or @<name>@<version>/<path> (a version in the store); it exits 1 when a permission is gained or lost or the interface differs. Show it to the people who decide.

$ ritsu sekisho check examples/refunds/refunds.gate --root examples/refunds
$ ritsu sekisho explain E302
$ ritsu sekisho gen examples/refunds/refunds.gate --target cedar --root examples/refunds
$ ritsu sekisho doc examples/refunds/refunds.gate --root examples/refunds --format html
$ ritsu sekisho diff examples/refunds/refunds.gate@HEAD~1 examples/refunds/refunds.gate

Run every command as ritsu sekisho <command> (through a link to ritsu named sekisho, sekisho <command> is the same): it reads the rules, the dates, the calendars and the flows a gate names in the same process, where sekisho built alone from its crate reads no other language and stops with E209. --root is the directory the paths of what the gate names are written from (else the nearest directory above that holds .git or ritsu.mod). Add --lang ja for Japanese.

2. The language on one page

gate refunds v1
description "Who may look at an order of the shop, refund it, and export the record of refunds. A sketch of a shop's own terms, written as sekisho's example"
namespace Shop
 
use rule refund_limit from "rules/refund_limit.rule"
use dates refund_terms from "dates/refund_terms.cal"
use calendar uk from "calendars/england_and_wales.cal"
use openapi orders from "api/orders.json"
 
today range >=2026-10-01 <=2028-10-31 offset +00:00
 
enum order_status = paid | shipped | returned | refunded
 
role manager
  description "Refunds what a clerk cannot, and after the refund period on a business day"
  includes clerk
  can view_order, refund_order
 
principal User
  description "A member of the shop's staff, signed in"
  roles clerk, manager, auditor
  attributes
    refund_limit : money[GBP, incl_tax]  range >=0GBP <=10_000GBP
    suspended    : bool
 
workflow returns from "flows/returns.flow"
  description "Refunds a returned order once the item is back at the warehouse"
 
resource Order
  description "An order of the shop"
  attributes
    status   : order_status
    paid_on  : date  range >=2026-01-01 <=2028-09-30
    customer : Customer
 
action refund_order
  description "Refund an order, in part or in whole"
  guards orders refundOrder
  principal User, Workflow
  resource Order from orderId
  input
    amount : money[GBP, incl_tax]  range >=1GBP <=10_000GBP
  context
    refund_band  = refund_limit(amount: amount, limit: principal.refund_limit).band
    in_period    = today <= refund_terms.last_day(paid_on: resource.paid_on)
    business_day = today is open in uk
 
permit clerks_refund_within_their_limit
  description "A clerk refunds up to the clerk's own limit, while the refund period lasts"
  principal in clerk
  action refund_order
  when refund_band is within_limit
  when in_period
 
forbid suspended_staff_do_nothing
  description "A suspended member of the staff does nothing"
  principal is User
  action any
  when principal.suspended
 
expect deny clerks_never_refund_over_their_limit
  description "A clerk who is not a manager never refunds more than the clerk's own limit"
  principal in clerk
  action refund_order
  unless principal in manager
  when refund_band is over_limit
 
separate refunding_and_auditing
  description "The people who refund are not the people who audit the refunds"
  actions refund_order, export_refunds

• The parts come in this order (E003), and the lines of a block are indented with spaces.
• Cedar's meaning: what no policy allows is denied, and a forbid that applies wins over every

permit. principal in <role> follows includes.

• A name that is not ASCII carries an alias for Cedar: 返金する(refund_order).
• An enum the gate shares with a workflow or a rule is written once in an enums file and read with

import enum order_state from "rules/order_states.rule" (-> <name> renames it here): the gate then uses it as an enum it writes, and a value renamed in the file stops the gate where it is written.

• Every attribute counts finitely: bool, an enum, a number of a unit type with both ends of its

range, a date with a range, an entity type, T?. There are no free strings.

• guards names an operation of a document a use line reads: an operationId (or `"POST

/orders/{orderId}/refunds"), "Service/Method" of a .proto, an AsyncAPI operation's key, a chobo transfer's <transfer>.<operation>`.

• A computed value is the output of a rule (<rule>(…).<output>, an enum or a bool), today

against a date of koyomi, or today is open in <calendar>. It is given only attributes, inputs, constants and today; the generated code computes it, and a caller cannot hand it in.

• Conditions: principal in, principal is, principal is workflow, x is v, x is not v, a

bool, a number against a constant, resource.a is principal, resource.a is principal.b, principal in resource.a, allowed <action>, joined with and, or, not and parentheses.

• allowed <action> is another action's answer, asked with the same principal and resource: an

escalation (unless allowed approve on request_approval), the weaker operation first (forbid … when allowed archive_document on delete_document). The action asked is given this action's inputs of the same names, or what is written: allowed approve(amount: total). The check walks both actions together, so each combination has one answer; the generated code asks the other action first, and a refusal of it refuses this one.

• A policy's alias is its @id, <file's alias>/<policy's alias>: renaming a policy changes the

@id that the records of decisions and Verified Permissions hold.

3. What to ask a person

• Who may do each action, and on which conditions, before writing a permit.
• What the operations of the contract mean, when an action's name or what it guards is not plain

from the document.

• What an expectation should say, when E304 shows a combination where it does not hold: whether

the policies or the expectation are wrong.

• Whether a role's reach (can) is wrong or the policies are, at E306 and W302.
• Whether two duties must be kept apart (separate), and what to do at E305.
• Whether an operation of a context that no action guards is open to anyone on purpose (then its

contract says security: []), at ritsu's E907 and W907.

• What a workflow should do when it is denied, at ritsu's W909: the task declares the error

(errors denied = 403), and the flow handles it.

• Whether an action should hang on another action's answer (allowed), when the business says

"only when they could not …" or "rather than …", and what the other action's inputs are given when this action has none of their names (E110).

4. From a diagnostic to a fix

ritsu sekisho explain <code> (and codes.md) gives each code's cause, its fix and its smallest reproduction. The usual ones: