DevRunbook-Public/docs/26-authentication-authorization.md

26 — Authentication and authorization

Security model

The MVP is a self-hosted multi-user-capable application with personal workspaces. Public registration is disabled by default. Identity, instance administration and workspace authorization are separate concepts.

Roles

Instance roles

• instance_owner — created during first run; may manage instance settings, users, retention, encryption-key status and destructive maintenance.
• instance_admin — may manage users, jobs, integrations and operational settings but may not transfer ownership.
• user — ordinary authenticated user.

Workspace roles

• owner — controls workspace data and membership.
• editor — creates and edits profiles, drafts, private playbooks and integrations.
• viewer — reads workspace resources and downloads artifacts but cannot mutate them.

The MVP may create one personal workspace per user and expose only its owner membership in the normal UI. Authorization checks must still use workspace IDs and roles so team support does not require replacing ownership assumptions.

Registration and invitations

Default registration mode is closed.

• The first-run owner may create users or issue single-use invitations.
• Invitation tokens are random, hashed at rest, expire and are invalidated after use.
• Email delivery is optional and not required for the MVP; the administrator may copy an invite link.
• An invitation grants a specific instance role and optional workspace membership.
• No API may accept an arbitrary workspace ID from an invitation without verifying the invitation binding.

First-run ownership

The first-run flow is defined in docs/31-first-run-and-instance-lifecycle.md.

• Only one transaction may complete initial ownership.
• A setup token is required when configured and strongly recommended whenever the instance is reachable beyond loopback.
• No default username or password is generated.
• Setup endpoints become unavailable after completion.

Password and credential behavior

• Minimum password length: 12 characters by default.
• Do not impose composition rules that encourage predictable substitutions.
• Permit password managers and paste.
• Compare new passwords against a local denylist of common passwords when practical; no password is sent to an external service.
• Hash with the authentication library's current recommended memory-hard algorithm and parameters.
• Rehash on successful login when stored parameters are outdated.
• Never log passwords or password-derived values.

Sessions

• Database-backed revocable sessions.
• Session token stored only in a secure, HTTP-only, same-site cookie.
• Rotate session identity after authentication, password change and privilege change.
• Idle timeout default: 12 hours.
• Absolute timeout default: 30 days.
• Users can revoke all other sessions.
• Instance administrators can revoke a user's sessions and must generate an audit event.
• CSRF protection is mandatory for all cookie-authenticated state changes.

Login protection

• Rate-limit by account identifier and source network without permanently locking a user out.
• Use progressive delay and generic failure messages.
• Record successful login, failed-login threshold events, password reset and session revocation without storing credential material.
• Support reverse-proxy-aware source-address handling only from explicitly trusted proxies.

Password recovery

Self-hosted instances cannot assume email delivery. Provide both:

1. administrator-issued single-use reset link; and
2. an operator command runnable inside the application container that creates a short-lived reset token for a named user.

The operator command must not accept or print a new password. It prints only the reset URL/token once, records an audit event and revokes prior unused reset tokens.

Authorization rules

Every application use case receives an authenticated actor and workspace context. Route handlers must not perform authorization solely through UI visibility.

Mandatory checks include:

• actor has access to the target workspace;
• actor role permits the action;
• referenced playbook, profile, run, artifact and integration belong to the same workspace or are built-in public content;
• immutable published versions and generated runs cannot be edited;
• artifact download authorization is checked at request time;
• jobs cannot be retried across workspace boundaries;
• instance-admin endpoints require instance role, not workspace ownership.

Built-in and private content

• Built-in published playbooks are readable by every authenticated user.
• Private playbooks belong to one workspace.
• A private playbook cannot reference another workspace's profile, evaluation or resource.
• Publishing inside the private workspace does not make content globally public.

Sensitive actions

Require recent authentication or password confirmation for:

• changing password;
• rotating integration secrets;
• deleting a workspace, repository, run history or integration;
• exporting all user-owned data;
• changing instance ownership;
• changing encryption-key configuration.

Audit events

At minimum record:

• account creation, invitation, disablement and role change;
• login threshold event and session revocation;
• first-run completion and ownership transfer;
• integration creation, token rotation and deletion;
• private playbook publication/deprecation;
• generated-run creation and artifact deletion;
• retention, backup and destructive-data actions.

Audit payloads contain opaque resource IDs and safe metadata only.

Authorization test matrix

For every workspace resource, test:

• unauthenticated request;
• authenticated actor without workspace membership;
• viewer attempting mutation;
• editor performing allowed mutation;
• owner performing destructive action;
• instance admin without workspace membership;
• cross-workspace ID substitution;
• deleted/disabled user session;
• immutable resource mutation attempt.

Reference implementation mapping

Better Auth is the preferred library adapter. The application must keep authorization, workspace policy and audit behavior in application-owned use cases rather than treating library plugins as the complete authorization model.

Milestone 0 must verify:

• Next.js route and server integration;
• PostgreSQL/Drizzle schema ownership and migration behavior;
• database-backed session revocation;
• secure cookie flags behind the configured public URL and trusted proxy;
• email/password hashing and rehash behavior;
• password-reset token creation without mandatory external email delivery;
• rate-limit hooks and generic login errors;
• session invalidation after password or privilege changes;
• compatibility with the first-run transaction and operator reset command.