Skip to content

Listing Ops, Roles And Principal Requirements ​

(since 0.20.3, cratestack#1388)

cratestack contract ops is a read-only report of every op a schema exposes, with the rules written on it, the roles those rules name, and whether the op can be called with no principal. It exists for consumers that gate their own artefacts on a schema's policies: a relay that keeps one allowlist per client app, an API gateway's route table. Those used to port the policy grammar by hand, which drifts with every release. This command answers from the parser the macros lower @allow from, so there is one source of truth.

bash
cratestack contract ops --schema path/to/schema.cstack          # a table
cratestack contract ops --schema path/to/schema.cstack --json   # one JSON document
Exit codeMeaning
0The report printed.
2The schema could not be read. With --json, stdout is { "ok": false, "error": "…" }, as contract check prints; the message carries no terminal colour codes.

The JSON document ​

json
{
  "ok": true,
  "schema": "admin-actions",
  "transport": "rpc",
  "ops": [
    {
      "key": "procedure.listActionsAwaitingSignature",
      "kind": "procedure",
      "allow": ["hasRole(\"admin\")"],
      "deny": [],
      "roles": ["admin"],
      "requires_principal": true,
      "unanalysed": [],
      "contract_digest": "…"
    }
  ]
}

The field set is stable: later releases only add fields. Keys come out in exactly the order shown.

FieldMeaning
schemaThe schema file's name without its extension.
transportrest or rpc.
keyThe op's key, the same one contract digest prints: an RPC op_id (procedure.ping, model.Widget.list), or "<METHOD> <route template>" on REST.
kindprocedure, subscription (a subscription procedure), or model.<verb> (list, get, create, update, delete, subscribe).
allow, denyThe rule texts as written, in order. For a model op, the @@allow / @@deny rules of that verb (a rule for all applies to every verb).
rolesEvery hasRole("…") literal named anywhere in an allow rule, sorted and deduplicated. A deny rule adds none. This is a superset of the roles that grant access, not the roles that grant it: a role under a branch that cannot hold, or in an && that something else blocks, is still listed.
requires_principaltrue when no allow rule can hold for a caller with no principal. See below.
unanalysedRule texts the analysis did not fully understand, and any attribute the macros' own audit would refuse (a mis-spaced @allow (x), an invisible character).
contract_digestThe same per-op digest contract digest prints.

Which rules decide which model verb is one table, cratestack_policy::model_verb_policy_slot, which the macros generate from and this command reads, so the report cannot describe a different slot than the generated code consults:

VerbRules that decide itDescriptor slot
list"list", "read", "all"read_allow_policies / read_deny_policies
get"detail", "read", "all"detail_allow_policies / detail_deny_policies
subscribe"detail", "read", "all"detail_allow_policies / detail_deny_policies
create"create", "all"create_allow_policies / create_deny_policies
update"update", "all"update_allow_policies / update_deny_policies
delete"delete", "all"delete_allow_policies / delete_deny_policies

subscribe reads the detail slot, like get, not the list one: a feed decides each event the way get decides one row, at open and for every event. A model with @@allow("list", hasRole("a")) and @@allow("detail", auth() == null) therefore reports list as needing a principal and get and subscribe as not.

What requires_principal means ​

Every policy node evaluates, for a caller with no principal, to one of two things: always false (no row and no input can make it hold) or maybe true. requires_principal is true exactly when every @allow rule is always false, or when there is no @allow at all. It is never true for an op an anonymous caller can pass.

TermFor a caller with no principal
true, auth() == nullmaybe true
auth() != null, hasRole("…"), inTenant("…"), auth().isSystem(), falsealways false
A comparison with an auth() side (auth().<claim> == …, column == auth().<claim>, auth() == <relation>)always false, unless a none or every quantifier wraps it (below)
A comparison of inputs or fields, an in [...] list, a bare boolean fieldmaybe true
Anything the analysis does not understandmaybe true, and listed in unanalysed

contract ops reads every policy exactly as the generated server does: the analysis and the macros read a term with the same code, in the same order, quirks included. In particular set membership is read before comparison, so label in ["== auth().id", "public"] is a set-membership test (maybe true), not a comparison with auth(). How a string literal holding quotes, backslashes, &&, ||, ==, != or parentheses is read is whatever the generated server does, unchanged. The edge cases are tracked in cratestack#1392; avoid writing policies that depend on them.

For a schema that compiles, the verdict is the server's behaviour. For a schema the macros refuse (a policy that names an unknown field, for instance) no server exists, so the verdict is not meaningful: contract ops parses and semantically checks the schema but does not run the macros, and a term the macros would refuse may still get a verdict (auth() ==null and items.userId == auth().id do). Run cratestack check first, and treat the output as meaningful only for a schema that builds.

Rules combine like this: && is always false if any branch is, || only if every branch is, and several @allow lines are alternatives. @deny is not consulted: it can only refuse, so it cannot make an op callable.

Relation quantifiers ​

For an anonymous caller a comparison with auth() renders FALSE, and what a relation quantifier makes of that decides the whole term (memberships.<quantifier>.userId == auth().id):

QuantifierRenderedAnonymous
some, or a to-one hop (owner.id == auth().id)EXISTS (… AND FALSE)always false
noneNOT EXISTS (… AND FALSE), true for every rowmaybe true
everyNOT EXISTS (… AND NOT (FALSE)), vacuously true for a row with no related rowsmaybe true

A none or every anywhere in the path (a.some.b.none.c == auth().id) makes the term maybe true. So @@allow("read", memberships.none.userId == auth().id) reports requires_principal: false, and so does the every form.

An op with no @allow is denied to every caller (deny by default). It reports requires_principal: true with an empty allow, so a consumer that wants "ops callable anonymously" does not list it, and one that wants "ops naming role X" does not either. Check for an empty allow to tell it apart from a real principal requirement.

A rule the analysis does not understand (a malformed expression, an unknown function, an unrecognised term shape, an attribute the macros' audit would refuse) is listed in unanalysed, and the op reports requires_principal: false, treated as anonymous. A consumer that gates on this must refuse any op with a non-empty unanalysed rather than trust the verdict.

Deriving an allowlist and checking it is complete ​

roles lists the roles an op names, so it over-approximates who may call it. An allowlist recipe must treat it as a superset, must also read requires_principal, and must refuse any op with a non-empty unanalysed:

bash
cratestack contract ops --schema s.cstack --json > ops.json
# Refuse the whole derivation if any op has a rule the analysis could not read.
jq -e '[.ops[] | select(.unanalysed | length > 0)] | length == 0' ops.json >/dev/null \
  || { echo "ops with unanalysed rules; refusing to derive" >&2; exit 1; }
# Candidates: ops that name the role AND are not callable anonymously. Review the
# list: naming a role does not mean the role is what grants access.
jq -r '.ops[] | select((.roles | index("operator")) and .requires_principal) | .key' ops.json \
  | sort > derived.txt
diff <(sort operator-allowlist.txt) derived.txt

An op that names the role but reports requires_principal: false is callable with no principal at all; it must not sit on an allowlist that assumes authentication, so list those separately rather than dropping them:

bash
jq -r '.ops[] | select((.roles | index("operator")) and (.requires_principal | not)) | .key' ops.json

Released under the MIT License.