Bosatsu packages

Yichus/Access

Builtin package (resource access.bosatsu). This is the complete package source used by this build. The export list names its public API; definitions below give the types and behavior.

New to the API? Start with Make a data app or Build an API, then use this page to look up a definition.

package Yichus/Access

# Canonical data-access rules for Yichus APIs. Author-facing
# policy modeling lives here; Yichus owns the analysis and the runtime
# that constructs `Principal` at the trust boundary.
#
# Verified statically by the access analyzer (`AccessAnalyzer` on the
# JVM and in the API-safety MCP bundle); a `Withheld` declaration is
# checked by `api verify`'s `stored-field-disclosure` property.
#
# The model is deliberately small so every claim is provable from the
# typed Matchless IR:
#
#   - `Principal` is the authenticated caller. It is constructed by the
#     runtime at the trust boundary, never by handler code.
#   - A resource with `OwnerScoped` policy stores rows keyed by exactly
#     `Principal.user_id`, or multiple rows per user keyed by
#     `owner_key(principal, local_key)`, one form per table: a user id
#     can spell another caller's owner_key ("5:alice" is
#     `owner_key(alice, "")`), so on a table keyed both ways the bare
#     `user_id` operations are refused. The analyzer proves that every
#     `db_read` / `db_write` / `db_delete` key on that table is derived
#     from the authenticated caller by one of those two forms, directly
#     or through helpers of the program (up to eight calls deep) whose
#     bodies return one, and that no unkeyed operation
#     (`db_create`, `db_query`) touches the table.
#   - A resource with `Public` policy is readable and writable by any
#     caller; no key discipline is required or claimed.
#   - `PublicReadRoleWrite(roles)` permits reads and queries on any route,
#     including anonymous routes. Every create, update, delete, or ID allocation
#     must be reachable only through routes requiring every declared role.
#   - A resource with `GuardedOrRoles(guards, roles)` follows the same row
#     guard rules as `Guarded` on ordinary routes. A binding may instead use
#     the resource without a row guard only when it is reachable from at least
#     one declared route and every route that reaches it requires every role
#     in `roles`. Route and call reachability come from typed IR; an unrouted,
#     mixed-authority, or unresolved helper receives no role proof.
#     An empty guards list makes the resource role-only: every operation,
#     including creation, requires this route authority.
#   - A resource with `Guarded(guards)` policy holds rows whose visibility
#     and mutability are decided by declared predicates ("guards"): pure
#     `Bool`-returning bindings in the spec's package, named in `guards`,
#     that take the caller's `user_id` and a row. The analyzer proves,
#     by branch dominance over the typed IR, that
#       * every `db_write` / `db_delete` on the table is either a create
#         (keyed by a `db_next_id` of the same table) or sits inside the
#         true branch of a guard applied to `Principal.user_id` and a
#         row read from a Guarded table;
#       * every value derived from a row read from the table (the row, a
#         field of it, anything computed from it) is used only inside
#         such a branch, as an argument to a guard, as a match
#         scrutinee, or as the rows of `keep_visible` filtered by a
#         guard — until a guard branch has vouched for it, after which
#         it may reach the response.
#     The finding at each site names the guards that dominate it; the
#     reader judges whether they are the right ones. Nothing about the
#     guard's body is checked beyond its type: the guard IS the rule.
#   - A resource with `Under(parent, roles)` policy stores rows that belong
#     to rows of `parent`, a `Guarded` or `GuardedOrRoles` resource: each
#     key is `child_key(parent_key, local_key)`, and `db_query_under(tbl,
#     parent_key)` lists the rows under one parent. Touching them is allowed
#     exactly where touching the parent row is: every `db_read`,
#     `db_read_opt`, `db_write`, `db_delete` (and their `tx_` forms) is keyed
#     `child_key(k, local)`, and every `db_query_under` names `k`, where `k`
#     is the key a parent row was read at and the operation sits in the true
#     branch of one of the parent's guards applied to `Principal.user_id`
#     and that row. Rows read under that branch are vouched for by it. As
#     for `GuardedOrRoles`, a binding reachable only from routes requiring
#     every role in `roles` may touch any row without a guard. `db_create`,
#     `db_next_id` and `db_query` take no parent key, so on an `Under`
#     resource they need that route authority too. Separate rows under one
#     parent let concurrent writers (one row per fan, say) commit without
#     conflicting on the parent row.
#
# Declare the rules as an `AccessSpec` binding. Discovery is structural
# (any binding whose checked type is `AccessSpec` participates), so the
# spec survives renames, moves, and other agent edits to the file.

from Bosatsu/Predef import List, concat_String, int_to_String, length_String

export (
  Principal(),
  Policy(),
  AccessRule(),
  AccessSpec(),
  Release(),
  Withheld(),
  owner_key,
  child_key,
  length_framed,
  keep_visible,
  reveal,
)

# The authenticated caller: a stable user id plus role names.
# `roles` is RESERVED: access decisions must not branch on it. Role-protected
# server entry points declare `RequiresRoles` in `Yichus/Service`; the runtime
# checks those roles before handler invocation and does not expose the verified
# claim through this field. It remains here for Principal shape compatibility.
# Handlers that touch owner-scoped data must take a Principal and
# derive their DB keys from `user_id`.
struct Principal(user_id: String, roles: List[String])

# A key part prefixed by its length: joining framed parts (or framed parts
# and one last unframed part) is injective even when the parts contain
# separators.
def length_framed(value: String) -> String:
  concat_String([int_to_String(length_String(value)), ":", value])

# A collision-free key for one of several rows owned by the authenticated
# caller. The decimal length prefix makes (user_id, local_key) injective even
# when either string contains separators. The access analyzer recognizes this
# exact typed call and requires `principal` to derive from the handler's
# runtime-injected Principal; hand-built or request-supplied values prove
# nothing.
def owner_key(principal: Principal, local_key: String) -> String:
  Principal(user_id, _) = principal
  concat_String([length_framed(user_id), local_key])

# The key of one row stored under a parent row: `parent_key` is the key
# the parent row is stored at, `local_key` names the row among its
# siblings. The length prefix makes (parent_key, local_key) injective, so
# no child of one parent can be named through another. The access analyzer
# recognizes this exact typed call; `Yichus/Data::db_query_under(tbl,
# parent_key)` lists every row keyed this way under `parent_key`.
def child_key(parent_key: String, local_key: String) -> String:
  concat_String([length_framed(parent_key), local_key])

# Per-resource access policy.
enum Policy:
  Public
  OwnerScoped
  Guarded(guards: List[String])
  GuardedOrRoles(guards: List[String], roles: List[String])
  PublicReadRoleWrite(roles: List[String])
  Under(parent: String, roles: List[String])

# Filters rows read from a Guarded table by a guard. The analyzer
# accepts a `db_query` result of a Guarded table only here, and only
# when `visible` is a lambda whose body applies a declared guard to the
# caller's `user_id` and the row; the result is then clean and may
# reach the response.
def keep_visible[a](rows: List[a], visible: a -> Bool) -> List[a]:
  [row for row in rows if visible(row)]

# One rule: the table name (as passed to `Yichus/Data::table`) and the
# policy the analyzer must prove for it.
struct AccessRule(resource: String, policy: Policy)

# The complete declared access surface of an API module. Every table a
# handler touches must be covered by exactly one rule; an operation on
# an undeclared table is a finding, never silently allowed.
struct AccessSpec(rules: List[AccessRule])

# A function a withheld field may reach an exposed route's response
# through: what a call of it returns may be disclosed, and nothing else of
# what it was given. Held like `Yichus/Service::Handler` holds its
# function, so one declaration can list functions of different types; the
# analyzer reads which function from the typed Global reference in the
# Matchless IR, never from a name. Nothing about the function's body is
# checked: the release IS the rule. A function that returns its argument,
# or an invertible function of it, discloses the field. A function released
# is released at every call of it in the program, a `Bosatsu/Predef` one
# too, so release a named function of your own.
# The check follows flow, not values: a stored value returned under a
# released guard is still reported as copied, even when it must equal the
# caller's input (the answer returned only when matches(answer, guess)
# holds), so return the caller's own input there instead.
# Releasing an equality test makes it an oracle: a caller can try values
# until one is accepted. The check judges one response and does not count
# calls, so bound the guesses with `limited` or `limited_by` on the route.
struct Release(run: exists a. a)

def reveal[a](run: a) -> Release:
  Release(run)

# Fields of `table`'s rows that no exposed route (a `public_route`, or a
# `publishable_route` answering someone an account gave its key to) may
# answer with, except through a call of one of `releases`. Each path names
# a field of the table's checked row type, as the reach report renders
# it: `questions[].answer` is the `answer` of every element of the row's
# `questions` list, an enum's field is preceded by its constructor
# (`Locked.note`), and a leading `[]` steps into a `Table[List[a]]` row.
# Write each declaration as its own top-level binding, literally:
#   name = Withheld("table", ["path", ...], [reveal(f), ...])
# with `f` a top-level function definition (`Release(f)` also works).
# Only the named paths are judged: another stored field computed from a
# withheld value (a label or key built from the answer) carries the same
# secret, so name it too.
# Anything else fails the check loudly: a Withheld inside another value
# or behind a `def`; a table, path or list that is not a literal; a table
# the program opens with no one checked row type; a path that names no
# field; no path; a release that is a value or a lambda, or is written
# through a helper; a table declared by two bindings. Discovery is
# structural, as for `AccessSpec`: any binding whose checked type is
# `Withheld` participates.
struct Withheld(table: String, paths: List[String], releases: List[Release])