Extract Grammaratur, Dregarnuhr, Geduldh, Mestionora, Ordoschnellic, Schutzaria, Kunstzeal and Seheweit behind compatible application contracts. Include accumulated editor resilience, navigation and theme UX, remote CLI, storage/schema and DR groundwork, tests and design/operations documentation. Verified: uncached full Go suite; go vet ./...; race tests for all eight components; 11 targeted Chromium tests; Node suites; 19 Python CLI tests; reproducible editor build. No push, release tag or deployment in this checkpoint.
8.6 KiB
Authentication and Authorization Backend
Boundary
Authentication proves an identity. Every authenticator produces the same
internal principal_uuid; authenticators never grant document access directly.
Authorization is Domain-scoped and evaluates positive grants only:
request -> session -> principal -> Domain membership -> role -> capability
Campus owns trusted identity-provider configuration. A Domain owns membership, roles, grants, session policy, and the default authorization mode. Managed Campus provider metadata is inherited from its controller; secrets remain on the instance that performs authentication and are never federated.
Authentication methods
| Method | Stable external key | Secret location |
|---|---|---|
| password | normalized username | Argon2id verifier in credential table |
| OIDC | exact (issuer, subject) |
encrypted client secret/config |
| LDAP | (provider UUID, immutable directory attribute) |
encrypted bind secret |
| TOTP | principal + factor UUID | encrypted seed; recovery codes hashed |
| magic link | normalized verified email | one-use hashed challenge |
| device approval | requesting-device challenge UUID | one-use hashed challenge |
OIDC groups and LDAP groups are attributes. Explicit mapping rules may create
or remove Membership/Role bindings, but group names are not capabilities.
The route policy, internal group schema, /g/ namespace, and endpoint matrix
are specified in Endpoint Authorization and Groups.
Core records
principals: canonical person/service identity and lifecycle state.principal_identities: unique provider subjects attached to a Principal.auth_credentials: password/TOTP/recovery material and version metadata.domain_memberships: Principal membership in one Domain.auth_roles,auth_role_bindings: Domain roles and membership assignment.groups,group_members,auth_group_role_bindings: Domain-scoped Principal collections and their Role assignment.auth_capability_grants: positive operation grants with typed targets.auth_sessions: opaque, hashed, rotating browser sessions.auth_challenges: short-lived one-use login/MFA/device challenges.auth_audit_log: append-only authentication and policy decisions.
Capabilities use verbs read, create, upload, write, rename, delete,
link, manage, and delegate. Targets are domain, quartier, street, spot, path, or
object. Locality inheritance is resolved by the address model; an exceptional
Page/Object grant does not rewrite the path hierarchy.
Evaluation
- Resolve Domain before reading the session.
- Hash the opaque cookie and load an unexpired, unrevoked session for that Domain. Reject suspended/quarantined Principals.
- Resolve Membership and its Role bindings.
- Match the requested verb and target against positive grants.
manageincludes administrative operations but does not implydelegate. - Record denied sensitive operations and every policy/configuration mutation.
No matching grant means deny. During migration, authorization_mode=legacy
leaves existing anonymous behavior intact. Administrators bootstrap an owner,
verify access, then switch a Domain to enforcing. New Domains should default
to enforcing once the bootstrap flow is complete.
HTTP flows
Implementation clarification (2026-11-01): clients requesting JSON from
POST /_/auth/login (or /totp) receive an opaque Bearer session rather than
extracting a browser cookie. The remote CLI follows this existing flow and the
same Domain membership/capability checks; see remote CLI.
It does not implement an OIDC device handoff yet. The cookie descriptions below
apply to browser sessions, not a requirement for all HTTP clients.
/_/auth/login,/_/auth/logout,/_/auth/callback/oidc/{provider}/u/{username}is the Domain-scoped profile and user-Wiki root./u/{username}/_/editis its owner-only profile editor and/_/auth/profileredirects there. Other descendants are ordinary semantic Wiki paths. Usernames exclude dots so the public handle can be derived as{username}.{domain FQDN}without ambiguity./_/auth/challenge/password,/totp,/magic-link,/device/_/api/v1/auth/session,/principals,/roles,/grants,/audit
Cookies are Secure, HttpOnly, SameSite=Lax, host-only, and contain only a
random secret whose SHA-256 hash is stored. Login rotates the session; password
or factor changes revoke all Principal sessions. State/nonce/PKCE are mandatory
for OIDC. Magic links and device approvals store only a token hash, are
single-use, expire quickly, and are bound to Domain and intended action.
TOTP seeds are encrypted with AES-GCM using a 256-bit instance key stored as
auth.key beside the Document Store (0600), or derived from
PAGESWIKI_AUTH_KEY. Enrollment remains disabled until a valid six-digit code
is confirmed. Login challenges expire after five minutes, allow five attempts,
and reject reuse of an accepted 30-second counter.
OIDC providers are configured per Domain from the authentication panel. The
flow uses discovery, Authorization Code, PKCE S256, state, and nonce, then
resolves the subject through UserInfo. A first login may bind (issuer, sub)
only to an existing Principal with the same verified email; it never creates a
role or capability from provider claims. Client secrets are encrypted with the
instance authentication key.
LDAP providers are also Domain-scoped. The implemented login sequence follows the same separation used by Wiki.js' LDAP authenticator:
- connect to an
ldap://orldaps://endpoint with an 8-second socket deadline; optionally upgrade anldap://connection with StartTLS; - bind the configured search service account, or use an anonymous search when both bind fields are empty;
- insert the RFC 4515-escaped login into a configured filter containing
{{username}}, search below the configured Base DN, and require exactly one result (server size limit 2, time limit 6 seconds); - read an explicitly configured immutable ID, local username, email, and display-name attribute;
- bind as the returned user DN with the submitted password. A search result by itself is never accepted as proof of authentication;
- resolve the first login by an exact unique local username or email, then
persist
(provider UUID, immutable ID). Following logins use only that immutable binding. Optional automatic provisioning creates an ordinarymemberwith no local password credential.
The immutable attribute should be entryUUID for common LDAP servers or the
binary objectGUID for Active Directory. DN, email, display name, and account
name are mutable attributes and therefore are not stable subjects. Bind
passwords use the instance authentication-key encryption; leaving the password
blank in the settings form preserves the existing encrypted value. TLS
certificate validation is on by default, a private CA can be appended as PEM,
and disabling validation is an explicit per-Domain administrator action.
The settings panel exposes a saved-configuration login test. User passwords are used only for the user-DN bind and are neither persisted nor logged. Connection admission is bounded to four process-wide LDAP operations. The browser receives the same generic invalid-credentials response for lookup and password failures; the server log retains the provider-side error without the submitted username or password.
SMTP magic links target existing active/read-only Principals by normalized email. The public request response never reveals whether an address exists. Links contain a random token whose hash alone is stored, expire after fifteen minutes, and are consumed atomically once. SMTP credentials use the same encrypted provider-secret storage. Delivery is admitted through a bounded background slot so an SMTP server cannot hold the login request open.
LDAP and SMTP run through bounded worker queues with timeouts; request handlers do not wait indefinitely on an external directory or mail server. A durable authentication-attempt quota keyed by Domain, normalized account identifier, source prefix, and challenge kind remains required before an Internet-facing multi-tenant deployment; bounded provider admission is not a rate limiter.
Delivery order
- Common schema, Principal normalization, sessions, RBAC evaluation, audit.
- Bootstrap owner plus password/Argon2id and optional TOTP.
- OIDC Authorization Code + PKCE.
- SMTP magic link and device approval challenges.
- LDAP bind/search with immutable identity mapping.
- Delegated macaroon capabilities after canonical RBAC is enforced.