Authorization

Master switch. When true, the authorization middleware guards entity and auth routes, checking the caller's claims against the claim required by the matched route.

Generate claims from your entities on startup. For each table Nucleus emits method claims (get.product, post.product, …), optional field-level claims (get.product.price), relation claims, and bulk-operation claims for entities that expose bulk routes. Idempotent — existing claims are skipped.

embed writes the full claim list directly into the JWT — dead simple, but the token grows with claim count. resolve puts only role names + a claimsVersion in the JWT and caches role→claims in shared Redis; consumer services resolve claims by role, keeping tokens tiny even with hundreds of claims.

• embed— Claims live in the JWT payload. Simple; token grows with claims.
• resolve— Roles + version in the JWT; claims resolved from Redis. Best at scale.

Redis key prefix for the role→claims cache used in resolve mode. A version key is bumped on every change so stale caches are detected and refreshed.

Email of the super-admin to create/ensure on boot. In multi-tenant mode a godmin is seeded into every tenant schema.

Initial password for the godmin. Provide via an env var and rotate after first login — treat it as a break-glass credential.

Entities excluded from claim generation entirely.

Columns excluded from field-level claim generation — system columns and secrets you never expose as toggles.

Paths the authorization middleware ignores completely.

Paths reachable without any claim check.

For an IDP (full mode): seed claims for entities that physically live in other consumer services. Only table_name is required; columns are optional for field-level claims. This lets one IDP own the permission model for an entire fleet.

Example: [{ "table_name": "blog_posts" }]

Declarative starter data for your access model.

The required permission is built from the request: get.product for the entity, get.product.price for a field, get.product.with.author for a relation. The HTTP method is lower-cased and joined with dots.

A held claim authorises anything more specific: get.product matches get.product.price and get.product.with.author (a prefix match), but a field-only claim never widens to the whole entity. A godmin role short-circuits the whole check.

Without a full-entity claim, the request is still allowed if the caller holds claims for the specific fields/relations asked for — and the response is then trimmed by filterResponseFields (id is always kept) and filterResponseRelations, so a user literally cannot read a column they lack a claim for.

A role-claim may carry a scope (a URLSearchParams string like userId=self:id). self:<field> is resolved from the caller's own user row — lazily, only when a matched claim actually needs it, so unscoped requests do no extra query. The resolved values become WHERE filters (applyScopeFilters), giving true row-level security; this is the runtime behind the $self seed assignment.

The IDP / monolith path: roles and claims (with scope and self:) are read from the database for the complete, authoritative check described above.

A stateless resource server reads x-user-roles / x-user-claims (injected by a trusted gateway) and matches them with no database at all. Fast, but JWT claims carry no scope, so row-level filtering isn't available on this path — field/relation matching still is.

When a consumer needs full scope/self semantics it POSTs to {IDP_URL}/auth/check with the access token and trusts the IDP's verdict. The response envelope is unwrapped defensively (legacy flat shapes still accepted; anything unrecognised fails closed).

When jwtClaimsMode is resolve, buildCache() writes {prefix}:role:{name} → claim arrays plus a {prefix}:version integer that bumps on every role-claim change. Tokens carry only roles + the version; services resolveClaimsForRoles() from Redis and rebuild when the version moves — keeping tokens tiny at any claim count.