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.

When on (default), write routes (POST/PUT/PATCH + bulk) filter the payload to only the columns the caller holds a field WRITE claim for (put.entity.field), on top of the mass-assignment deny-list — so a caller without a full-entity write claim cannot set fields it lacks a claim for. A full-entity-claim holder still writes every non-deny-listed column; godmin bypasses. Set false for pre-H4 entity-claim-only writes.

When true, a bare single-segment claim (e.g. `get`) no longer acts as an all-entity wildcard — at least `method.entity` (2 segments) is required to grant entity access. Godmin roles always bypass.

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 this seeds the godmin for the main schema; each tenant schema gets its own godmin from that tenant's configured godAdminEmail (not this value).

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.

DEPRECATED and NOT ENFORCED — this key was never wired into the request pipeline, so paths listed here are still authenticated and authorized normally. It does NOT make anything public. Kept only for config back-compat; use publicPaths to open a path.

Paths reachable without a claim check. A bare entry (e.g. /products) opens GET + OPTIONS only — use the method-qualified form ("POST /products") to expose a write. EXCEPTION: a bare entry whose path starts with "/auth/" is exposed for ALL HTTP methods (GET/POST/PUT/PATCH/DELETE/OPTIONS), so an unqualified /auth/login or /auth/register POST works — every other bare path stays GET + OPTIONS only. (The declared default is inert: the raw config value is read without merging defaults, so auth/entity routes stay public via their own flags, not this key.)

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 cannot read a column they lack a claim for. A full/table-level read claim reveals every column EXCEPT columns declared sensitive: true (see below), which stay claim-gated.

A column marked sensitive: true in config.entities is claim-gated ON TOP OF the ordinary model, inverting the blanket table-read rule: a caller holding only the full table-level read claim (allowedFields undefined/empty) does NOT see it — stripUnclaimedSensitive scrubs it from every list/detail response AND from /auth/me — and sensitiveFieldQueryable blocks it in filter/search/sort/select/distinct. It is revealed and queryable ONLY for a caller holding that specific per-column read claim (a defined allowedFields containing the column); godmin bypasses. Registered at boot from config.entities (registerSensitiveColumns) and unioned into the logger's redactKeys, so the value is also redacted from log context AND audit diffs. Distinct from the absolute password/auth-secret block (SENSITIVE_OUTPUT_KEYS), which NO claim opens. Declared on the entity/column (see the entities doc) but enforced here on the authorization field-read path.

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. On reads and by-id/bulk writes the resolved values become WHERE filters (applyScopeFilters); on CREATE (POST/form/bulk-POST) there is no row to filter, so they are forced onto the new record — overriding any client-supplied owned value, and failing closed (403) if the scope names a column the entity lacks — so a scoped claim can never create a row owned by someone else. This is true row-level security, the runtime behind the $self seed assignment.

Independent of the claim model, generic-entity writes (POST/PUT/PATCH/DELETE + bulk) to the framework's own sensitive tables require godmin: the RBAC tables (roles/claims/user_roles/role_claims — so a claim can't self-assign godmin) and the money / tenant-routing / auth-secret system tables (payment_*, domain_*, verifications, api_keys, magic_link_tokens, user_sessions, trusted_devices). Their columns are mass-assignable (domain_hostnames.tenant_id is the live routing key; payment_sub_merchants.iban a payout destination), so legitimate owner writes must go through the dedicated routes (/invoices, /sub-merchants, /domains/hostnames, /subscriptions, /cards). Generic reads stay on the claim model.

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 (and x-user-claim-scopes) injected by a trusted gateway and matches them with no database at all. In embed mode the JWT now carries per-action ownership scope (claimScopes, resolved self: → concrete values at mint), so checkAuthorizationFromJWT merges each granting claim's scope into scopeFilters at both the entity-level and field/relation-level paths (mergeGrantingScopes) — enforcing the SAME row-level filtering as the DB path, not just field/relation matching. A legacy token minted without claimScopes simply runs unscoped. (This closes the pre-0.9.734 embed-mode IDOR where scoped claims were silently dropped on the JWT path.) Resolve mode carries no inline claims/scope on the token — use 'consumer — via IDP' or the ClaimsCache when you need scope from a resolve-mode token.

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.

A CATALOG of comparable shared keys. Each entry seeds exactly one claim with method GUARD (action = the name up to the first {, path = the name, policy = { kind:'guard', keyTemplate, valueType }). It carries no condition, endpoint or metric — only a key name and its type. Seeded idempotently and reconciled: removing an entry deactivates its GUARD claim (never deletes → assignments survive), re-adding reactivates it.

The dynamic part — nothing is hardcoded. Assign a GUARD claim to a role and store a JSON condition in that role_claims.scope (via the portal GuardConditionEditor or PATCH /roleClaims/:id). op is one of the operators allowed by the value type; value is the compared number/boolean/string; invalidates lists claim ACTIONS to suppress while the condition holds. The SAME GUARD claim caps different roles differently (role A gt 1000000, role B gt 50000).

Suppressed claims are subtracted prefix-aware (dot-bounded): ["llm"] removes every llm.* claim, ["llm.prediction.…predict_stream…"] removes only that leaf. Discovered claims are LEAF rows, so use the shortest prefix that covers the capability you are capping.

The full EvaluatedGuard[] roster — each { action, key, valueType, op, threshold, current, invalidates, holds } — every guard the caller has with its live key value and whether it currently holds. Powers the profile Usage-limits panel ("token_spent_today = 42 000, gt 1 000 000 → ok"). Self via x-user-id; godmin reads anyone via ?userId=. /quotas is a migration alias.

{ suppressedClaims, firedGuards } — the actions the caller has LOST right now plus the guards that fired (each names its key so a denial can be explained). This is what the proxy's authorize layer GETs to enforce guards. Self via x-user-id; godmin via ?userId=.

Master switch. When true (with a DB and non-consumer mode) the discovery + manifest routes mount and boot discovery can run. Also gates the ClaimGuard endpoints (see the ClaimGuards coupling note).

Fetch + parse + reconcile every configured service's OpenAPI during boot seeding. Discovery is idempotent, so re-running each boot is safe; a per-service fetch/parse failure is logged and skipped (never fails boot).

The external services to discover. Each OpenAPI operation becomes a claim action {id}.{tag|resource}.{operationId | method_path}, hierarchical so a role can be granted {id}.*, {id}.resource.*, or a single op via prefix match. Vanished endpoints are DEACTIVATED (isActive:false), never deleted, so role assignments survive.

DECLARED BUT NEVER READ — inert. No code reads trigger.enabled or trigger.basePath; POST /authorization/discover is a hardcoded path gated solely on endpointDiscovery.enabled. Setting trigger changes nothing.

Shared secret (or env NUCLEUS_DISCOVERY_TOKEN) that lets the proxy — which holds no user session — fetch the route/role-claims manifests. Presented as the x-discovery-token header; the manifest handlers accept godmin OR a valid token.

Re-run discovery + reconcile on demand; returns the per-service diff ({ added, reactivated, deactivated, unchanged, total }). godmin only (session-protected). The route is only mounted when endpointDiscovery.enabled is true (and a DB is configured, non-consumer mode) — a call 404s otherwise; when it IS mounted, a non-godmin caller gets 403.

The templated route → required-action table the proxy consumes. Registered as a PUBLIC route so the sessionless proxy can reach it; the handler enforces godmin OR a valid x-discovery-token. A companion GET /authorization/role-claims-manifest returns the role → claim-actions map the proxy uses in resolve mode.