Capabilities¶

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

Lookup reference for the capability ACL: the capability id grammar, the capability list, full/own/none grading, the seeded role bundles, and a summary of which routes demand which capability. The identity model behind it — tokens, Margonem-ID binding, identity linking, governance data — is owned by Roles & permissions. Each API reference area page carries the route table for its own slice, naming every route's exact capability and Write flag.

The list is derived rather than declared here. Nerthus.Core builds it from the closed route table plus the role bundles, tops it with admin.all, and publishes the result as the capabilities field of GET /schema. The contributor store's read side runs the same derivation over the seeded bundle defaults, so a ## Role block cannot widen the set its own @dostęp is checked against. With either input missing — a test parsing a store on its own — that validator falls back to a list in code carrying the same ids. One id below stays outside the derivation: log.fetch.request, which the fetch service checks against the caller's set itself. Everything else becomes authorable in the contributor store as soon as its route or its bundle exists, so the table below records that set rather than defining it.

Id grammar¶

A capability is <resource>.<action> with an optional .own ownership suffix:

<resource>.<action>[.own]     e.g. entity.read, pu.award, player.write.own

• <resource>.all grants every action on the resource.
• admin.all grants everything — it is the machine token's implicit set and the Namiestnik/Koordynator bundle.
• X.own never silently satisfies X (see Grading).

Capability list¶

entity.read is wider than the entity index. Its file half reaches an allowlist of eight lore roots and seven root-level files — Świat gry, Postaci, Organizacje, Wątki, Bestiariusz, Archiwum, Źródła and the generated Lokacje (daemon/services/Files.ps1). A ninth root, Dzieła, appears only for a caller holding external.read, and is not entity.read's. One of those files is nerthus.contributors.md, the store carrying every person's @dostęp grants and the SHA-256 behind each @klucz_api line, so every seeded bundle holding entity.read can page it: Gracz, Narrator, Radny, IT and Bot. A stored hash is not a usable bearer. The allowlist and the refusals are Lore files; the reasoning is the lore-file read surface.

A log.fetch fetch reaches only the hosts integrations.logs.hosts names, and the daemon re-checks that list against every redirect hop before it follows one. log.fetch.request adds the kind: request form, where the caller supplies the method, URL, headers and body and the daemon issues that request past the allow-list. POST /logs/fetch and POST /logs/parse both reach that form, so the fetch service checks the capability at its one outbound call rather than at the route. A fetch persists the answer into the committed nerthus.logs/ archive; parse returns it and writes nothing.

No seeded role bundle carries workflow.settle, workflow.map_checkup, session.distribute, session-registry.regenerate, economy.read, log.fetch.request, or sync.run — the read-only IT bundle is the only one that carries sync.read. Settlement spans distribution, currency, and PU at once; distribution, registry regeneration and sync act on the whole repository; and log.fetch.request reaches whatever the daemon's network reaches. Those seven resolve only through admin.all or a per-Person grant. .own grading is meaningless for repo-level sync: the handlers treat an own-only sync grant as no grant and refuse with 403. The daemon's own scheduled sync tick runs in-process and needs no token — design in Sync.

The machine token implicitly satisfies every capability (admin.all); it exists to authenticate local processes, never to sandbox the operator's shell. Capabilities scope end users reaching the daemon through the Discord/Margonem bot — token mechanics in Roles & permissions.

Grading (full / own / none)¶

When the dispatcher checks a route's required capability, the caller's grant is graded:

X.own never silently satisfies X. The caller's own subjects are their Gracz entity (by name or Margonem ID) and every Postać whose @należy_do is that Gracz.

Handler scoping for an OwnOnly caller, route by route:

So a Gracz holding pu.read.own reads their PU timeline but not another player's, and player.write.own lets them edit their own Postać but not create a second Gracz.

Role bundles¶

Roles are named bundles of capabilities — data, not hardcoded tiers. They load from committed .nerthus/data-tables/roles.json; the daemon seeds that file only when it is absent, so a Rada edit survives every boot and re-init (file location and seed rule: Data tables, Configuration). The seeded defaults are also the fallback when the file is missing:

A player cannot read another player's Tematy zastrzeżone. Until 2026-08-26 they could: the field rides on the Gracz projection, /entities/{name} costs entity.read, and every player's token holds it — measured through the API, not inferred. Moving the field behind player.read was proposed and would have changed nothing, because the Gracz bundle holds player.read too. player.restricted.read is the capability that actually discriminates, and the removal happens in the dispatcher for every route rather than in the handlers that happen to know about it.

The Gracz bundle does not read sessions, including the evenings that player was at. The capability governs three doors and each one is gated on it, because the same bytes reach a reader through all three: the /sessions routes, the session search tier, and the session blocks inside a lore file served by /files/content. session.report stays in the bundle — filing an account of an evening is not reading the account somebody else filed.

The MC and SMC bundles do not read the lore. Chat moderation is a job over people and records: those surfaces read /moderation/*, /keyrings/* and the regulation corpus, which needs no bearer at all. Somebody who moderates chat and narrates holds the lore through the narrator role, since a person's effective set is the union of the roles they hold. Neither bundle can read a moderation record's body: it is ciphertext addressed to the moderacja keyring, which the daemon is not a member of.

Namiestnik and Koordynator are two distinct roles with identical seeded bundles — roles.json keys them separately, so the Rada can diverge them later. The bundles are independent lists, not strict supersets: the narrator bundle carries full pu.read/currency.read instead of the .own variants and omits identity.read; the radny bundle omits log.fetch.

A person may hold several roles at once — somebody who plays and narrates holds both — and their effective set is the union of those bundles, with their personal @dostęp applied once, last, over that union. The resolution order is owned by Permissions; the examples below assume a single role only for brevity.

A Person's effective set is built in layers: their role bundles (usually just gracz), then their contributor-store elevation — the @rola role's caps plus their personal @dostęp, from nerthus.contributors.md — then per-Person grants, minus per-Person revokes (a revoke wins last). Session tokens store only the role; capabilities are recomputed on every request, so a change takes effect on live tokens immediately. Every externally-minted session token carries the gracz role, so a Narrator's or Radny's extra powers come from the contributor store (their @rola), not the token; a per-Person grant on their Margonem ID or a named token minted with -Roles narrator are the secondary paths. Because session.report sits in the gracz bundle, every logged-in player can file a session report (POST /sessions/report) without any per-Person grant — the draft is quarantined and Rada-reviewed, so the capability is safe to seed broadly (Submit a session report).

Routes → capabilities (summary)¶

Route by route, the exact capability and Write flag are on the API reference area page owning that slice. The shape of the mapping:

Eight routes are public (no bearer, no capability): GET /health, GET /schema, GET /routes, GET /schema/version, GET /fleet/status, POST /auth/margonem, POST /auth/discord, and the one-time GET /api-keys/claim/{sha} — there the 64-hex sha in the path is the secret, and the entry destroys itself on first read. GET /fleet/status answers a fixed self-description card and nothing else; the field list is contract, owned by Fleet. GET /routes publishes the whole map, so the live count is always one anonymous call away.

Election eligibility (GET /elections/eligibility) requires pu.read because eligibility is PU-derived data; a Gracz self-checks via pu.read.own. The formula and window live in PU model.