Auth & Security Specification

Status: v3.60 (revised — see Change Log) Owner: datapipelines.co core Depends on: Type System Last updated: 2026-10-25

1. Purpose

This spec defines how users authenticate (OIDC via any provider — Google, Microsoft, Okta, Auth0, Keycloak, etc.), how sessions work (internal JWT after OIDC login), how agents authenticate (API keys), what authenticated principals can do (roles — a member's, or a key's own, §7.5), and the Spring Security wiring that ties it all together.

The product is self-hosted, internal-users-only. Identity is delegated to any OIDC-compliant provider via OpenID Connect by default; deployments without an IdP may additionally enable optional local password accounts (§5A), stored as Argon2id hashes. After any login, the server issues its own JWT for stateless session management.

2. Design Principles

1. Identity is delegated by default; local accounts are the narrow exception. The server never sees or stores OIDC user passwords — identity belongs to the external provider. The one exception (§5A): a deployment with no IdP at all would otherwise be unusable — evaluating the product required registering an OAuth client before seeing a single screen, the biggest adoption barrier the product had. For that deployment shape, optional local accounts exist: admin-created only (no self-registration), stored as Argon2id hashes (never plaintext, never in config beyond the one-time first-admin seed), forced to rotate seeded/reset credentials at first login, and off unless explicitly enabled. An OIDC-only deployment behaves exactly as before.
2. Generic OIDC, not provider-specific. Any OIDC-compliant provider works — Google, Microsoft, Okta, Auth0, Keycloak, Ping, AWS Cognito, etc. The deployment configures which provider(s) to enable; the code is provider-agnostic.
3. OIDC for humans, API keys for agents. Users log in via browser (OIDC redirect flow). Agents (Claude, GLM, Copilot) authenticate via API keys issued from the UI.
4. Internal JWT after OIDC. Once OIDC validates the user, the server issues its own JWT (8h TTL). The JWT is the session — any instance can validate it statelessly. OIDC tokens are NOT used for ongoing session management.
5. API keys per agent, not global. A user generates one key per agent. Compromised keys are individually revocable. Per-agent usage visible in audit logs.
6. Keys hashed at rest. Same protection as passwords would be. A database leak does not expose working credentials.
7. Roles decide, and every credential has exactly one. A session holds its membership's role; every key its OWN role (§7.5) — an mcp key the member role chosen at creation under the subset rule, an API or server key its transport role. There are no scopes (#215 slice (b)).
8. Stateless server, near-live revocation. JWT + API key validation are stateless across instances; both paths re-check the principal's liveness (user is_active, key revocation) through a short-TTL cache backed by Postgres (§6.3, §7.3). Deactivating a user or revoking a key takes effect within ~1 minute — never the full JWT lifetime.

3. Authentication Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Browser (Human User)                      │
│                                                                │
│  1. User visits /login                                         │
│  2. Sees buttons for each configured OIDC provider             │
│  3. Clicks one (e.g., "Sign in with Google", "Sign in with     │
│     Okta", "Sign in with Company SSO")                         │
│  4. Redirected to OIDC provider                                │
│  5. Authenticates at provider                                  │
│  6. Provider redirects back with authorization code           │
│  7. Server exchanges code for OIDC tokens                     │
│  8. Server validates ID token, extracts user identity         │
│  9. Server creates/updates user record in Postgres            │
│ 10. Server issues internal JWT (8h TTL)                       │
│ 11. Server sets HttpOnly cookie: dp_session=<JWT>             │
│ 12. Redirect to /                                               │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                    Agent (Claude / GLM / Copilot)              │
│                                                                │
│ 1. User has previously logged in and generated an API key     │
│ 2. Agent sends: DP-API-Key: dpk_<id>.<secret>                 │
│    (or, on /mcp: Authorization: Bearer dpk_<id>.<secret>)     │
│ 3. Server validates key hash (Argon2id) against Postgres      │
│ 4. Server resolves the user the key acts as + its role        │
│ 5. Request authenticated                                       │
└──────────────────────────────────────────────────────────────┘

Both paths resolve to the same internal principal:

data class AuthenticatedPrincipal(
    val userId: UUID,
    val email: String,
    val displayName: String,
    val authMethod: AuthMethod,       // OIDC, API_KEY or PROMOTION
    val keyId: String?,               // present when a key authenticated
    val workspace: WorkspaceContext?, // the resolved role in the active / pinned workspace
    val keyRole: KeyRole?,            // every key's own role (keys v2 A13; §7.5)
)

4. User Identity

4.1 User entity

{
  "id": "uuid",
  "email": "alice@company.com",
  "display_name": "Alice Wang",
  "profile_picture_url": "https://lh3.googleusercontent.com/...",
  "provider": "google",
  "provider_subject": "108214793245678901234",
  "is_active": true,
  "is_admin": false,
  "created_at": "2026-08-01T10:00:00Z",
  "last_login_at": "2026-08-05T14:30:00Z"
}

The provider field stores the OIDC registration name as configured by the deployment (e.g., google, microsoft, okta, company-sso). It's free text — any provider name the deployment configures. Not constrained to a fixed enum.

4.2 User provisioning

First login: When a user logs in via OIDC for the first time:

1. Server extracts email, name, sub, picture from the OIDC ID token — for a protocol: oauth2 provider, from its user-info and emails endpoints instead (§5.5, #655). The email is normalized to lowercase before every lookup and store — provider case differences must not fork one human into two rows (or mint a second bootstrap admin, §4.4). If the ID token carries email_verified: false, the login is rejected (auth.login.oidc_error, audited) — an unverified self-registered account at a provider must never reach the email-keyed linking step below, or it takes over the existing account with that email. A provider omitting the claim is now also treated as NOT vouching for the address (2026-09-21, #187 — fail closed): the login is rejected the same way. An IdP that never emits the claim must be trusted explicitly, per provider, with datapipelines.auth.oidc.providers[].trust-email-without-verified-claim: true (§5.1); each acceptance under the knob is audited (auth.login.email_verified_assumed). A claim that is present and false is refused whatever the knob says.

2. Checks if a user with that email already exists.

   • Yes: the stored identity is compared with the incoming one (2026-09-21, #187 — an identity is linked ONCE, never silently re-linked):
     • the row is the provider = 'bootstrap' placeholder — this login completes it (the §4.4 pre-provisioned admin's first sign-in); provider, provider_subject, last_login_at, profile_picture_url and display_name update (the display_name refresh is owner-ratified 2026-08-28: there is no profile-edit feature, so a stored name has no user-chosen referent to protect, and freezing it would leave an IdP rename unrepresentable; revisit if a profile surface ever ships);
     • the stored (provider, provider_subject) equals the incoming pair — the same person signing in again; the same refresh runs;
     • anything else — a different provider, a different subject under the same provider, or a local/system row — the login is refused: nothing is updated, the event is auth.login.identity_mismatch (naming the two providers, never the subjects), and the redirect is /login?error=identity_mismatch ("This email is already linked to a different sign-in identity. Ask an administrator to reset it."). Re-linking an account is the super admin's explicit identity reset on the admin users screen (user.identity_reset, §7.6, audited auth.user.identity_reset), which returns the row to the bootstrap placeholder so the NEXT sign-in with that email claims it. Grant-wise this step changes nothing: is_admin is decided at row creation and nowhere else (§4.4).
   • No: Creates a new user record. Default is_active: true, is_admin: false. 2a. Materialises every pending invitation for that email (§4.6) into real memberships, with their roles, in the same act — and DELETES the invitations. The materialise runs in WorkspaceService.workspaceForLogin (step 4), the one resolution both credential paths reach, so it happens before any workspace is stamped: the first login lands an invited user in the invited workspace with the invited role, and the demo join below never fires for them (D-R11 — the invited workspace REPLACES the default, it is not added beside it). Each materialisation is audited (workspace.invitation_materialised) with the inviter.

3. Checks the email domain allowlist (if configured — see §4.3).

   • Domain not allowlisted: reject login with auth.login.domain_not_allowed.

4. Workspace resolution (§5.1, §12): determines the active workspace the JWT stamps — the user's last-used workspace when it still resolves to a live, ACTIVE membership, else their first active membership, else — this is the D-R11 rule — a fresh viewer membership of demo, the one workspace the product ships (created by DemoWorkspaceSeeder at first boot, with the example content, and never recreated once deactivated — O-3). The demo join fires only for a user with NO membership at all, so somebody removed from demo on purpose is not re-added by their next login. It lives in WorkspaceService.workspaceForLogin, shared by both credential paths: the owner's rule is about logging in, not about which provider did it. All three stamps — last-used, first membership, the demo join — are built by the one super-admin-aware helper resolveForSession uses (#262, #271): a super admin's login response keeps the instance authority whichever fallback stamped it.

   A user still with nothing selectable — demo deactivated, or never seeded — stamps nothing. They authenticate fine and every workspace-scoped operation is refused; round 2 draws the "no workspace" page.

   The provisioning modes are gone (D-R11). auto-per-user (a personal workspace per first login), self-serve (anyone creates) and closed (admin only) were removed with open-join in RBAC round 1, and both config keys are refused BY NAME at startup (Configuration §3.17). Workspaces are created by super admins. Existing personal workspaces stay as ordinary workspaces, with their sole member as the workspace admin (D-R14).

5. Issues internal JWT (stamping active_workspace when step 4 resolved one), sets cookie, redirects to /.

Subsequent logins: Same flow — user record updated, JWT reissued.

Account deactivation: Admin marks user is_active: false via UI. Subsequent OIDC logins are rejected with auth.login.user_inactive. Existing sessions and API keys stop working within the liveness-cache TTL (~60s): every authenticated request re-checks is_active through the cache (PrincipalLiveness, §11A.3), so a deactivated user's JWT and keys are dead within a minute, not at the 8h JWT expiry — refused with auth.principal_deactivated (401; a page navigation lands on /login?error=inactive). Nothing is revoked: reactivation restores them. API keys additionally remain individually revocable.

4.3 Email domain allowlist

Configurable per deployment:

• DATAPIPELINES_AUTH_ALLOWLIST_DOMAINS=company.com,subsidiary.com
• If set, only users with emails from these domains can log in.
• If empty (default), any Google/Microsoft user can log in (open provisioning).

For internal-only deployments, always set the allowlist to prevent random Google accounts from accessing the instance.

4.4 Bootstrap admin

A fresh deployment has zero admins (users.is_admin DEFAULT FALSE, no seed rows) — so without a bootstrap path, nobody can ever grant admin. The mechanism (added 2026-08-07, security review LOW-11; extended 2026-08-29 to seed the first admin's local credential, §5A.2):

• The operator sets datapipelines.auth.bootstrap-admin-email (Configuration §3.4) before first start.
• When a user row is created (first provisioning, §4.2) and its lowercase-normalized email matches the configured value (compared case-insensitively), is_admin is set true. The grant fires only at row creation: a later login changes nothing, the flag is never revoked by this path, and after an admin deliberately revokes admin (auth.user.admin_revoked, §10.1) this path never re-grants it — re-instating admin is an explicit §16.3 operation.
• Audit-logged as auth.user.admin_granted with actor bootstrap (§10.1).
• If the key is unset, no bootstrap occurs — the deployment simply has no admin until the key is set and that user logs in.

Pre-provisioning (design 2026-08-16-sample-data §6.1). When datapipelines.bootstrap.datasources-file is set, startup needs this user to exist before anyone has logged in: datasources.created_by is NOT NULL REFERENCES users(id), and bootstrap datasource registration runs before the server accepts traffic. So, when no row exists for the configured address (lowercase-normalized, §4.2), one is created with placeholder identity fields — provider = 'bootstrap', provider_subject = the email (together satisfying the NOT NULL columns and the (provider, provider_subject) uniqueness), display_name from the email local-part, is_active = TRUE.

This is not a second grant path. It is the rule above firing earlier in time: the row is created, so the grant fires, once, with the auth.user.admin_granted / actor bootstrap audit event. Everything the rule already promised still holds, and each clause is load-bearing here:

• A restart finds the row and touches nothing on it — no re-grant, no identity rewrite, not even updated_at. An admin who deliberately revoked admin stays revoked.
• The admin's first real OIDC login completes the placeholder through §4.2's linking step: provider, provider_subject, profile_picture_url and — this case only — display_name from the name claim. It grants nothing.
• If that admin logs in before registration ever runs, §4.2 creates the row and grants there instead; the later pre-provisioning finds it and adds nothing. Either order, exactly one grant and exactly one audit event.

Startup refuses when datasources-file is set and this key is not (Configuration §3.18) — a missing actor would otherwise surface as a foreign-key error mid-startup naming neither key.

Explicitly rejected: "first user to log in becomes admin." Combined with the open-provisioning default (§4.3), that rule is a land-grab race on any reachable instance — whoever hits /login first owns every datasource credential. Do not reintroduce it as a convenience.

4.5 The system service account (R7)

pipeline_versions.created_by and pipeline_executions.triggered_by are NOT NULL REFERENCES users(id). Some writes the system makes belong to no human: a version promoted from another deployment (authenticated by a shared server key, not a principal — Versioning §10.6), a retention sweep, a stale-execution reap. Those writes still need an actor row.

One row serves all of them, provisioned at first boot through the same createUser path §4.2 and §4.4 use, and read back through the one well-known lookup UserService.systemActor() — so promotion, scheduled jobs and any future automated write stamp the SAME actor and nobody mints a second.

Login is disabled by construction, not by a flag. Three independent facts each make it impossible: no OIDC provider may be named system, so no external identity can link to the row; the address cannot resolve; and the local-password paths refuse it — createLocalUser at the reserved address answers EmailTaken (the row already holds it), and resetPassword on a non-human row answers "no such user". Since #215 its row also carries users.kind = 'system', and every login, linking and user-administration path refuses a non-human row by that ONE predicate (§4.7). There is nothing to disable because there is no credential to hold.

Idempotent. A restart returns the existing row untouched — no re-grant, no identity rewrite, no updated_at bump, the same contract §4.4's pre-provisioning states. Two replicas racing a fresh database settle it by catch-and-reread, exactly as the bootstrap actor does (ARCH-AUDIT M5).

It is deliberately not a credential. It holds no API key and no password, and nothing authenticates as it; it is the name history writes down when the writer was the system itself. The one exception is the promotion receiver's DEPRECATED config-value credential (Versioning §10.6): a shared secret with no row to attach an identity to, so a push it opens acts as this account (#215 B6). A STORED server key acts as its own identity instead (§4.7, §7.7).

It is the identity schedules fire under (#9, R2). A scheduled launch is built IN-PROCESS as an AuthenticatedPrincipal for this row — AuthMethod.SYSTEM, a workspace context for the schedule's workspace marked as the system actor's (SystemActorPrincipals.forWorkspace) — never by a filter, and no request can carry it (WorkspaceResolutionFilter refuses one that did). Its permission questions go to PermissionResolver's system arm (holdsAsSystemActor), which answers a FIXED set in any workspace — pipeline.execute, pipeline.read, execution.read (the launch, the pinned version's read, the reconciler's execution read) — and nothing else: no instance permission, no role, no key. The set is code (RolePermissions.SYSTEM_ACTOR), not a §7.6 column, so the role walk never sees it; SystemActorPrincipalTest pins it against a literal and proves a widened resolver is caught. A scheduled execution records executed_by = this row and triggered_via = SCHEDULE; the schedule and a Run now's person are on the scheduler's own schedule_runs row (scheduler design revision §4).

4.6 Invitations

The owner's scenario (2026-09-10): "Admin created a workspace and wants to add employees to that… They will have two options: 1. create user/password, 2. company SSO." Today a member is added through POST /workspaces/{name}/members (§17.7), which requires the users row to exist — and an SSO user's row is created only at their FIRST login (§4.2). So a workspace admin could not add bob@company.com before Bob had ever signed in. The bridge is an invitation keyed by email (metadata-db §4.17) that the login path materialises.

The rules, each load-bearing:

1. An invitation exists only while no users row holds that email. Inviting an email that has a row makes the person a member AT ONCE (the ordinary member-added path). There is no invitation "pending for an existing user", and nothing pretends a person exists before they do: the invitation references an EMAIL; workspace_members.user_id stays NOT NULL REFERENCES users(id).
2. Invite-time refusals. The email is normalized lowercase before every lookup and store (the §4.2 rule — Bob@Company.com and bob@company.com are one invitee). An email the §4.3 domain allowlist would refuse AT LOGIN is refused at INVITE time with the SAME code the login would use (auth.login.domain_not_allowed, at a 400 here — the caller's request is the defect): an invitation that could never be honoured is a trap. Inviting into a DEACTIVATED workspace is refused (workspace.inactive, 404) — a super admin can see the greyed workspace, and this is the verb telling them the same thing every other member verb would.
3. The latest admin decision wins. Re-inviting the same email UPSERTS the row: the role (and inviter, and date) is replaced, and the upsert is audited (workspace.member_invited) every time it fires — the row keeps no history; the audit trail does. The role is one of the four WorkspaceRole values, enforced by the same kind of database CHECK the members table states (D20).
4. Materialisation at login. When a user row comes into existence (§4.2's first login, or the admin's local-account creation — the two creation paths), every pending invitation for that email becomes a membership with its invited role, and the invitations are deleted, in one atomic statement. The demo-viewer default (§4.2 step 4) is applied ONLY when no invitation materialised — the invited workspace replaces the demo default, it is not added beside it (D-R11) — and active_workspace stamps the FIRST-INVITED workspace: the materialised memberships enter the membership ordering at their invitation dates (joined_at = invited_at), so "first membership" is the admin's first decision, not an alphabetical accident of same-transaction timestamps.
5. Deactivated workspaces wait. An invitation into a deactivated workspace does not materialise at login — the materialise predicate requires the workspace to be active — and is not lost either: reactivation makes it live at the next login. The row can be revoked meanwhile by a super admin, which is exactly the tidying a super admin inside a greyed workspace is for.
6. Revocation and visibility. DELETE /workspaces/{name}/invitations/{email} revokes (workspace admin or super admin, workspace.members.manage); a missing invitation is workspace.invitation.not_found (404). The members listing (§17.6) returns pending invitations in a SEPARATE invitations[] array, never mixed into members[] — a client that counts members must not count ghosts.

No expiry in v1, and no email is ever sent — the product has no SMTP (§5A); an invitation is a row, not a message, and it is revocable like any other membership. There is no self-service join: invitations are created by a workspace admin or a super admin, through the same permission gate as every other member verb (workspace.members.manage).

Local accounts need no invitation (§5A.1): the Admin → Users form's optional "also add to workspace, with a role" writes the user row and the membership in one act, because the row exists by the time the membership is written — rule 1 doing the work directly.

4.7 Key identities

Since #215 (the permissions and keys record §3.3, PK5, ratified 2026-09-23) an endpoint key and a server key each act as their own non-login identity — a users row with kind = 'service' — never as the person who created them. The MCP (user) key is the one exception: it acts as its member (§7.5).

users.kind is human | service | system (V34; UserKind). V34 set system on the System row (§4.5) and human on every other; one identity per existing endpoint/server key was created in the same migration (PK9).

The identity is built exactly like the System account, so login is impossible by construction:

• Created with its key, in one transaction (B4): ApiKeyService.issue provisions the identity and inserts the key under @Transactional("metadataTransactionManager") — a half-created pair cannot exist. The key row's user_id is the identity; api_keys.created_by records the person who created it (the Keys page's "Created by").
• Revoking the key deactivates the identity (is_active = false, in the same transaction). History keeps the row, so runs and received versions still name it: history renders "<key name> (API key)".
• Lifecycle is derived, never cascaded (record A2). Deactivating or deleting a workspace revokes no key and deactivates no identity; the ONE liveness predicate (§11A.3) reads the identity, the key and the pinned workspace on every request, so reactivating the workspace restores exactly what was live before.
• Managed only through its key (record A3). The user-administration routes — REST (/api/v1/auth/users/**) and the admin screen's list, row actions, identity reset, password reset and mail status — look the row up BEFORE any mutation and answer an unknown-user 404 for a non-human row; the admin users page, members lists and invitations show human rows only; adding a non-human row to a workspace is refused as "no such person".
• Attribution (record C5, C4): pipeline_executions.executed_by, audit_log.user_id and every created_by written on the key's behalf name the identity. The per-user concurrency limit (ExecutionSlots, keyed on executed_by) is therefore a per-KEY limit. Runs a key served before V34 keep their original attribution (the key's creator); the serve audit still pairs those with the key (§7.7).

One predicate: a person is kind = 'human'. It guards OIDC linking (a service or system row is never claimable, whatever its provider says — the kind is judged before the provider), the identity reset (which refuses a non-human row, so the bootstrap flip can never make one claimable — this closed a pre-existing hole for the System row), the local-credential read, the password reset, membership and invitation materialisation, the session filter (a token naming a non-human row is auth.session.invalid) and every user-administration route.

5. OIDC Login Flow

5.1 Provider configuration (generic)

OIDC providers are configured as a list in the deployment config. Each provider requires only three values — client-id, client-secret, and issuer-uri. The issuer URI triggers OIDC discovery (/.well-known/openid-configuration), which auto-configures all authorization, token, userinfo, and JWKS endpoints.

Two protocols (#655). An entry's protocol is oidc (the default — everything above) or oauth2, for a provider that speaks OAuth 2.0 without OpenID Connect: no discovery document, no ID token, no openid scope. GitHub is the shipped one. Discovery cannot build such an entry — the entry GitHub shipped as until #655 (issuer-uri: https://github.com/login/oauth) failed at startup the moment a client-id was set — so an oauth2 entry names its endpoints instead, and needs no HTTP at startup:

issuer-uri is refused on an oauth2 entry, and the oauth2-only keys are refused on an oidc entry (discovery would silently ignore them). Every endpoint is https://; plain http:// is accepted only for localhost / 127.0.0.1 (a test stub). Configuration §7 enforces all of it at startup, naming the provider and the key.

Each provider takes one optional trust knob — trust-email-without-verified-claim (default false, #187): set it true ONLY for an IdP that never emits the email_verified claim, so a missing claim is accepted as verified (audited auth.login.email_verified_assumed). A claim that is present and false is refused regardless.

datapipelines:
  auth:
    oidc:
      providers:
        - name: google               # registration ID (used in URLs, stored in users.provider)
          client-id: ${GOOGLE_CLIENT_ID}
          client-secret: ${GOOGLE_CLIENT_SECRET}
          issuer-uri: https://accounts.google.com
          display-name: "Sign in with Google"   # shown on login button
          # trust-email-without-verified-claim: true   # ONLY for an IdP that never emits the claim (§4.2, #187)

        - name: github               # OAuth 2.0, not OIDC (#655)
          protocol: oauth2
          client-id: ${GITHUB_CLIENT_ID}
          client-secret: ${GITHUB_CLIENT_SECRET}
          authorization-uri: https://github.com/login/oauth/authorize
          token-uri: https://github.com/login/oauth/access_token
          user-info-uri: https://api.github.com/user
          user-name-attribute: id
          scopes: [read:user, user:email]
          emails-uri: https://api.github.com/user/emails
          display-name: "Sign in with GitHub"

        - name: microsoft
          client-id: ${MS_CLIENT_ID}
          client-secret: ${MS_CLIENT_SECRET}
          issuer-uri: https://login.microsoftonline.com/common/v2.0
          display-name: "Sign in with Microsoft"

        # Any other OIDC provider:
        # - name: okta
        #   client-id: ${OKTA_CLIENT_ID}
        #   client-secret: ${OKTA_CLIENT_SECRET}
        #   issuer-uri: https://company.okta.com
        #   display-name: "Sign in with Okta"
        #
        # - name: keycloak
        #   client-id: ${KEYCLOAK_CLIENT_ID}
        #   client-secret: ${KEYCLOAK_CLIENT_SECRET}
        #   issuer-uri: https://sso.company.com/realms/main
        #   display-name: "Company SSO"

Scopes requested for every oidc provider: openid, profile, email. These are the standard OIDC scopes that give us the user's identity. An oauth2 provider requests exactly its configured scopes (GitHub: read:user for the profile, user:email for the emails endpoint).

5.2 ClientRegistration bean (built at startup)

The provider list is converted into Spring Security ClientRegistration objects at startup. OIDC discovery fetches each provider's .well-known/openid-configuration to auto-detect all endpoints.

@Configuration
class OidcConfig {

    @Bean
    fun clientRegistrationRepository(
        authConfig: AuthConfig
    ): ClientRegistrationRepository {
        val registrations = authConfig.oidc.providers.map { p ->
            ClientRegistration.withRegistrationId(p.name)
                .clientId(p.clientId)
                .clientSecret(p.clientSecret)
                .scope("openid", "profile", "email")
                .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
                // ABSOLUTE, from datapipelines.auth.base-url — NEVER the request-derived
                // {baseUrl} template: an attacker-controlled Host / X-Forwarded-Host would
                // otherwise choose the redirect_uri sent to the IdP, and the only backstop
                // is the IdP's own allowlist, a control this deployment does not own.
                .redirectUri("${authConfig.baseUrl}/login/oauth2/code/${p.name}")
                .issuerUri(p.issuerUri)        // triggers OIDC discovery
                .clientName(p.displayName)
                .build()
        }

        if (registrations.isEmpty()) {
            error("No OIDC providers configured. Set datapipelines.auth.oidc.providers in config.")
        }

        return InMemoryClientRegistrationRepository(registrations)
    }
}

The branch (#655). The sample above is the oidc arm. OidcConfig dispatches on protocol: oidc builds through discovery (ClientRegistrations.fromIssuerLocation) with the three OIDC scopes; oauth2 builds from the configured endpoints with the authorization-code grant, client_secret_basic, the configured scopes and user-name-attribute, and makes no HTTP call. Both arms share the registration id, client credentials, display name and the absolute redirect URI below. An unknown protocol, a missing oauth2 key or an openid scope on an oauth2 entry throws at construction naming the provider — the second line behind Configuration §7.

The redirect URI is built from datapipelines.auth.base-url (Configuration §3.4) — the deployment's exact external origin (e.g. https://dp.example.com, no trailing slash). Startup fails when it is unset while any OIDC provider is configured. This is what §13's "OIDC redirect URI locked to the deployment's exact domain" means mechanically; the earlier {baseUrl} placeholder resolved from the incoming request and let a hostile Host/X-Forwarded-Host header pick the redirect target (v2.4).

5.3 Login page (dynamic — renders buttons for each configured provider)

@Controller
class LoginController(
    private val clientRegistrationRepository: ClientRegistrationRepository
) {
    @GetMapping("/login")
    fun login(model: Model): String {
        val providers = clientRegistrationRepository.toList().map { reg ->
            mapOf(
                "name" to reg.registrationId,
                "displayName" to reg.clientName
            )
        }
        model.addAttribute("providers", providers)
        return "login"
    }

    private fun ClientRegistrationRepository.toList(): List<ClientRegistration> {
        // Spring's Iterable → Kotlin List
        return this.asIterable().toList()
    }
}

<!-- login.html (Thymeleaf) — renders one button per configured provider -->
<div class="ds-card login-card">
    <h1 class="ds-h2">Sign in to datapipelines.co</h1>
    <div th:each="p : ${providers}" class="login-buttons">
        <a th:href="@{'/oauth2/authorization/' + ${p.name}}"
           class="ds-button ds-button--secondary"
           th:text="${p.displayName}">
            Sign in
        </a>
    </div>
</div>

The login page shows only the providers the deployment configured — one button, two buttons, or five buttons. No hardcoded provider names.

When local accounts are enabled (§5A), the page gains a username/password form before the provider buttons, separated by a simple divider — one form, then the divider, then the buttons, never tabs (tabs hide half the methods behind a click and add state to a page that should have none). Only the methods actually enabled render: an OIDC-only deployment shows exactly the page above (no form, no divider), a local-only deployment shows the form with no divider and no buttons. Failure states arrive as ?error= banners (credentials, locked, inactive — same idiom as the OIDC banners).

5.4 OIDC redirect flow (Spring Security handles automatically)

1. User clicks a provider button (e.g., "Sign in with Okta")
   → GET /oauth2/authorization/okta
   → Spring Security redirects to Okta's authorization endpoint

2. User authenticates at Okta
   → Okta redirects to: GET /login/oauth2/code/okta?code={auth_code}&state={state}

3. Spring Security exchanges code for OIDC tokens (server-side)
   → Calls Okta's token endpoint with client_id + client_secret + code
   → Receives: id_token, access_token, refresh_token

4. Spring Security validates ID token (signature, audience, issuer, expiry)
   → Extracts claims: sub, email, name, picture

5. OidcSuccessHandler (our custom code):
   → user = userService.findOrCreateByEmail(claims, registrationId)
   → jwt = jwtService.issue(user)
   → response.setCookie("dp_session", jwt, httpOnly=true, secure=base-url-scheme, sameSite="Lax")
     (T33: `secure` is keyed off datapipelines.auth.base-url's scheme — https (or unset) keeps
     the flag; an explicit http:// base-url drops it so local login works. Production MUST run
     https — see §8.4. The same rule applies to the dp_csrf and dp_oauth2_authz cookies.)
   → response.sendRedirect("/")

5.5 OIDC success handler

@Component
class OidcSuccessHandler(
    private val userService: UserService,
    private val jwtService: JwtService,
    private val auditLogger: AuditLogger,
    private val authConfig: AuthConfig
) : SimpleUrlAuthenticationSuccessHandler() {

    override fun onAuthenticationSuccess(
        request: HttpServletRequest,
        response: HttpServletResponse,
        authentication: Authentication
    ) {
        val oidcUser = authentication.principal as OidcUser
        val claims = oidcUser.idToken.claims
        val clientRegistration = (authentication as OAuth2AuthenticationToken)
            .authorizedClientRegistrationId     // "google", "okta", "company-sso", etc.

        val email = claims["email"] as String
        val displayName = claims["name"] as String? ?: email
        val pictureUrl = claims["picture"] as String?
        val providerSubject = claims["sub"] as String

        // Check allowlist
        if (!authConfig.isDomainAllowed(email)) {
            auditLogger.log("auth.login.domain_not_allowed", email = email)
            redirectStrategy.sendRedirect(request, response, "/login?error=domain_not_allowed")
            return
        }

        // Find or create user
        val user = userService.findOrCreateByEmail(
            email = email,
            displayName = displayName,
            pictureUrl = pictureUrl,
            provider = clientRegistration,        // whatever registration name was configured
            providerSubject = providerSubject
        )

        if (!user.isActive) {
            auditLogger.log("auth.login.user_inactive", userId = user.id)
            redirectStrategy.sendRedirect(request, response, "/login?error=inactive")
            return
        }

        // Issue internal JWT
        val jwt = jwtService.issue(user)
        val cookie = Cookie("dp_session", jwt).apply {
            isHttpOnly = true
            secure = true
            // Lax, not Strict: Strict withholds the cookie on the cross-site redirect
            // chain back from the IdP (and on reloads of that landing), so every login
            // would end on a 401. CSRF protection covers state-changing requests.
            setAttribute("SameSite", "Lax")
            maxAge = authConfig.jwt.ttlHours * 3600
            path = "/"
        }
        response.addCookie(cookie)

        userService.updateLastLogin(user.id)
        auditLogger.log("auth.login.success", userId = user.id,
            details = mapOf("provider" to clientRegistration))

        redirectStrategy.sendRedirect(request, response, "/")
    }
}

SameSite=Lax, and it stays Lax (T33, 096 §F). Strict is the instinctive choice here and it does not work: the post-login landing arrives over the cross-site redirect chain from the identity provider, where a Strict cookie is withheld — and a browser RELOAD of that landing re-uses the cross-site initiator, so the user never becomes logged in and the failure looks like "login is broken", not like a cookie attribute. Observed live 2026-08-28. Lax still withholds the cookie on cross-site POSTs; the control for state change is the dp_csrf double-submit token (§8.4), which does not depend on SameSite at all. This paragraph exists because the KDoc on OidcSuccessHandler and §8.4 both said Strict for three rounds while the code said Lax, and a text that leans on a defence the code does not provide invites someone to "fix" the code to match it.

The create branch tells sys-ops (137, §5A.8). UserService.findOrCreateByEmail answers Provisioned(user, created), and when created is true — this callback's insert won the row — the handler hands a "New user" notice to MailNotices after the workspace resolution (so the notice can name where the account landed): created by: self-service via <registration id>, never a password. A returning user's login sends nothing; the loser of a two-replica first-login race reports created = false and sends nothing either — the winner's callback already did. With mail unconfigured the notice is one INFO line.

The success handler is fully provider-agnostic. It reads authorizedClientRegistrationId from the authentication token — that's whatever provider name the deployment configured. It doesn't know or care whether it's Google, Okta, or Keycloak.

Identity per protocol (#655). An oidc login's identity is the ID token's claims (above). An oauth2 login has no ID token: Spring routes a registration without the openid scope to the plain OAuth 2.0 user service, and ours (OAuth2IdentityUserService) reads the user-info endpoint and returns a principal carrying the same keys — so the handler reads claims from either principal and everything after it (lowercasing, the §4.2 gates, the link-once rule, the allowlist, the session) is ONE code path:

The verified-primary rule. With emails-uri set, the user-info email is discarded — GitHub's is the public profile address, neither verified nor necessarily the account's, and provisioning is keyed on email (§4.2), so trusting it would let anyone who types a victim's address into a public profile take the victim's row. No primary row → no address → refused (missing_email); a primary row whose verified is not the JSON true → refused (email_not_verified). The trust knob does not apply to an entry with emails-uri: the endpoint states verification itself, so trust-email-without-verified-claim cannot stand in for it; an oauth2 entry without emails-uri is judged by the user-info attributes exactly as an OIDC token's claims, knob included. A failed, non-2xx or malformed emails read (not a list, a non-object row, two primaries, a primary without an address) refuses as invalid_emails_response; a user-info answer without the subject attribute as invalid_user_info_response.

Provider read timeouts (#682). datapipelines.auth.oidc.provider-read-timeout-seconds (default 10, integer in 1–2147483; Configuration §3.4) sets both connect and read timeouts for the code-for-token exchange (both protocols), OAuth2 user-info, the emails read and OIDC user-info. A stalled token exchange fails as invalid_token_response; either user-info path fails as invalid_user_info_response; the emails path fails as invalid_emails_response with emails endpoint read failed (ResourceAccessException). These reach the failure path below. This is a per-connect/read bound, not a total login deadline. The ID-token decoder's JWKS fetch is bounded by the same key through a JwtDecoderFactory bean (#686): the bean re-creates Spring's ID-token decoder with the bounded HTTP client and keeps everything else Spring's — the same algorithm resolution, the same validators (timestamp + OIDC issuer/audience), the same claim-type conversion, one decoder per registration — so a stalled JWKS read fails the ID-token decode as invalid_id_token and reaches the failure path below. Startup discovery keeps Spring's separate 30 s bound.

The failure path. Every provider-side login failure — a refused consent, a lost authorization request, a failed token exchange, the refusals above — redirects to /login?error=oidc_error (the existing banner; no new page) and is audited auth.login.oidc_error with details.reason = the OAuth 2.0 error code (authentication_failed when there is none) and details.provider = the callback's registration id when it names a CONFIGURED provider (null otherwise — an unknown path segment is never written). The login limiter (§11.5; /login and /oauth2/ prefixes, per client IP) meters the callback path, which bounds these rows.

The access token is not retained. It lives only inside the user-info request: the bearer of the user-info and emails reads, never stored, logged or put in a cookie. Spring Boot's default authorized-client repository would have kept every login's token in an in-memory map keyed by principal; OidcConfig replaces it with a repository that stores nothing, so a login leaves no provider token in the process — for either protocol.

5.6 Workspace resolution & the DP-Workspace header

Every authenticated request resolves exactly one active workspace (design §5); all authored-content operations (pipelines, templates, executions) are scoped to it.

• Session (JWT) principals: the active workspace comes from the JWT's active_workspace claim (stamped at login, §4.2 step 4), membership re-checked per request through the same 60s liveness cache as users.is_active (§6.3) — workspace revocation takes effect within the identical ~1-minute window. A claim whose membership is gone falls back to the first live membership.
• DP-Workspace: <workspace name> switches the active workspace for that request. A name the principal is not a member of is refused 403 workspace.membership_required — indistinguishable from an unknown name, so the header cannot probe workspace existence. A successful switch is remembered as the user's last-used workspace (drives the next login's stamp). Global is_admin bypasses the membership check (design D4).
• API-key / MCP principals: the key's pinned workspace_id (chosen at issuance, §7.4) IS the context — no override exists. DP-Workspace on an API-key request is rejected (400 workspace.header_forbidden), never silently ignored: a header- switchable agent key would make every leaked key a skeleton key across the user's workspaces (design D3), and a quietly dropped header would train agents on a lie.
• The pin also governs workspace management. The workspace-management endpoints (§7.6 "Update a workspace / manage its members") address their target by path NAME, so for a key principal the service refuses any target other than the key's pinned workspace — the same no-oracle 403 workspace.membership_required a non-member gets, so "pinned elsewhere" and "not a member" stay indistinguishable. Without this, a key pinned to workspace A could rename, delete, or edit the membership of workspace B whenever its owner belongs to both — the D3 skeleton key by another door. Sessions are untouched (their active workspace is switchable by design). Two exemptions, both because no EXISTING workspace is overreached: create (there is no target workspace yet, creation grants the caller ownership of a NEW workspace only, and the author floor plus the per-mode provisioning refusal are its gates) and the open-join self-join (adding the caller's OWN email to a workspace the deployment declared open touches only the caller's own membership — the joiner enters as member, and the key's active workspace stays pinned).
• Zero memberships (possible under closed provisioning): the request proceeds with no workspace; every workspace-scoped operation then answers 403 workspace.membership_required.

5A. Local password accounts (optional)

Local username/password authentication is the optional second sign-in method for deployments without an IdP (§2 Principle 1). It is disabled by default (datapipelines.auth.local.enabled, Configuration §3.4); a deployment with only OIDC configured behaves exactly as before this section existed. With no OIDC providers and local accounts enabled, the deployment starts and serves the whole product with zero external setup — the zero-setup path.

5A.1 Accounts

A local account is an ordinary users row whose password_hash holds an Argon2id encoded hash (metadata-db §4.1) produced by the same SecretHasher API keys use (§7.2) — no second hashing library, no hand-rolled parameters. password_hash IS NULL means OIDC-only: that account can never authenticate locally. There is no self-registration — a local account exists because an admin created it on the user-administration screen, or because it is the config-seeded bootstrap admin (§5A.2). The email domain allowlist (§4.3) governs OIDC exactly as today; admin creation is itself the gate for local accounts, so the allowlist does not re-apply there.

A local account's provider is the placeholder 'local' (like 'bootstrap', §4.4 — a value with meaning, not an OIDC registration name): it marks "no OIDC identity is linked". If the person later signs in via OIDC with the same email, §4.2's linking step replaces the placeholder exactly as it replaces 'bootstrap'; the local password stays valid alongside the OIDC identity unless an admin disables local access.

Admin operations on the user-administration screen (§7.6 user.manage): create a local user (a random one-time password, must_change_password = TRUE, audited auth.user.created — emailed to the user when mail is configured, shown to the admin exactly once when it is not (§5A.8); there is no self-service "forgot password" flow, so an admin-driven reset is the whole account-recovery story), reset a password (new one-time credential, forces the change, clears the lockout — the unlock path for a sprayed-out account; mailed the same way), disable local access (the hash is cleared and the account is OIDC-only again), and unlock (clears the lockout without touching the credential).

5A.2 Seeding the first admin

A fresh local-accounts deployment has the chicken-and-egg §4.4 solves for OIDC: no admin exists to create the first account. Config seeds the first admin only, never ordinary users — passwords are not a config medium (config is plaintext in docker compose config, docker inspect, image layers and pasted issue reports, and offers no rotation, no revocation and no self-service). Every other account's credential lives hashed in the database, created by an admin from the user-administration screen.

• datapipelines.auth.local.bootstrap-password-hash — the preferred form: a pre-computed Argon2id hash, produced by ./gradlew :modules:auth:hashPassword (prompts, or reads DATAPIPELINES_SEED_PASSWORD; never take the password as a shell argument — it would leak into shell history and the process table). The plaintext never has to sit in a config file.
• datapipelines.auth.local.bootstrap-password — the plaintext alternative, accepted because a zero-setup demo should be one command. It is never logged and never audited.

Both forms land on the bootstrap-admin-email account (created through the single §4.4 creation path, so the admin grant and its audit event fire exactly as for OIDC) and always seed with must_change_password = TRUE: the app refuses to proceed to any other screen until the seeded credential is replaced (§5A.4). Seeding is create-if-absent and idempotent — a restart never resets a changed password, and an account that already exists is left untouched. And the seeded credential cannot survive silently: every startup where the bootstrap-admin account still has must_change_password = TRUE logs a WARN (event=auth.local.one_time_credential_pending). Startup refuses the ambiguous shapes (Configuration §7): both forms set, a seed without local.enabled, or a seed without bootstrap-admin-email — each naming both keys.

The seed fires ONCE, at row creation, so bootstrap-admin-email is a before-first-boot decision. Changing it afterwards creates no second administrator and moves no credential — the account that exists is the account that works. Every subsequent startup says so, as a WARN, and changes nothing:

event=auth.local.bootstrap_mismatch configured=you@example.com seeded=admin@local.test

Sign in as the seeded address and add or reset the other from Admin → Users, or start again from an empty database. ./app.sh --scaffold exists for exactly this: it writes deploy/secrets.env and stops, so the address can be set before the first --start. Both ./app.sh --start and ./app.sh --status read the seeded row out of the database and print the login that exists rather than the one the file names.

5A.3 Lockout

Distinct from the per-IP login rate limit (§9, rate_limit.exceeded): that damper is IP/route-scoped and cannot stop a slow spray against one account from many addresses. After datapipelines.auth.local.lockout.max-failures (default 5) consecutive failed local logins, the account locks for datapipelines.auth.local.lockout.duration-minutes (default 15):

• While locked, an attempt does no Argon2 work and does not touch the failure count — a spray cannot keep the lock warm or spend the server's native hashing memory. Even the correct password is refused until the lock expires.
• An expired lock starts a fresh failure budget (the count resets on the next failure rather than re-locking instantly forever).
• A successful login clears the counters. The lock engagement is audited as auth.login.locked (§10.1), and an admin can clear it early (unlock or password reset on the user-administration screen).

5A.4 Forced password change

Every seeded (§5A.2) and admin-reset credential is one-time: users.must_change_password is TRUE, and the app refuses to proceed to any other screen until it is changed. The mechanism is an MVC interceptor (ForcedPasswordChangeInterceptor) registered once for all paths — a filter/interceptor concern precisely so a future controller cannot forget it (a test adds a brand-new route and proves it is still gated). While the flag is set:

• Browsers are redirected 302 to /settings/password; htmx requests get HX-Redirect (a 302 would swap a full page into a fragment target); API and MCP paths get the 403 auth.password.change_required envelope (§9) — a redirect is meaningless to a JSON client.
• The allowlist is exactly: the change-password page and its endpoint, /logout, /health, /ready, and the public/static paths the change page needs to render.
• API-key principals are not gated — an API key is a separate credential the user created deliberately; the forced change is about the human proving control of the interactive account.
• The flag is read through the same ~60s liveness cache (D13); every password mutation evicts it immediately.

Only a password-opened session is gated. The session JWT carries an amr claim (pwd | oidc, RFC 8176) saying which credential opened it, and ForcedPasswordChangeInterceptor applies the gate to pwd sessions only: a user whose row was seeded with a local one-time password but who signs in through an identity provider presented no password and is not asked to change one. A session token minted before the claim existed is treated as pwd until it expires. (2026-09-06: the owner's Google sign-in was bounced to the change screen by the seeded local credential.)

On a successful change through the gate (the user's must_change_password was TRUE), the response carries HX-Redirect: /dashboard so the browser leaves the change screen; a voluntary change from Settings stays on the page with a toast (fixed 2026-09-05 — the forced flow used to leave the form on screen with a toast saying "you can continue"). The change itself (self-service, POST /partials/account/password) verifies the current password first — a hijacked session must not be able to rotate the credential — enforces the §5A.5 floor, clears must_change_password, and audits auth.password.changed.

5A.5 Enumeration resistance and the password policy

Unknown email, an OIDC-only account, and a wrong password are the same outcome: the same Invalid email or password. banner, the same redirect, the same HTTP status, and — just as important — the same cost. The no-row path still runs one Argon2 verification against a dummy hash, so response timing cannot tell "no such account" from "wrong password". Failure audit events carry no credential material.

Passwords are compared only through SecretHasher.verify (constant-time-ish at the hash layer). The policy floor for user-chosen passwords (self-service change) is 12 characters minimum and 128 maximum: length is the factor that resists offline cracking (NIST 800-63B), composition rules push users to predictable patterns, and the maximum bounds Argon2 input cost. Seeded/admin-generated one-time passwords are random and always force a change at first login, so the floor does not apply to them.

5A.6 The login flow

POST /login (form fields email, password, plus the _csrf double-submit token — Spring's field name; the COOKIE is dp_csrf and the header DP-CSRF-Token, §8.4) is public (§8.3) and metered by the same per-IP LoginRateLimitFilter as the OIDC paths (/login prefix). It is deliberately not under a scope-governed path: it is the authentication ceremony itself, so no principal exists for the ScopeInterceptor to check yet — exactly like the OIDC callback it mirrors.

On success the flow converges with OIDC: the same JwtService.issue mints the same dp_session cookie, the same §4.2-step-4 workspace resolution runs (workspaceForLogin: last-used, else first active membership, else the D-R11 demo join — the pre-113 auto-per-user clause no longer exists), the same auth.login.success audit event is written (with provider: "local" in the details), and is_active is re-checked exactly as on the OIDC path (a deactivated account with the correct password gets the inactive banner — safe to reveal because the caller just proved the password). The must_change_password flag does not block the login; it engages the §5A.4 gate after it.

5A.7 Credential minting is session-only

Any operation that mints or rotates a usable interactive credential refuses an API-key principal with auth.session.required (§13.7), regardless of role. The set is exactly:

Why the role matrix cannot express this. A permission test sees a role, not a credential, so it sees a dpk_ key and a browser session with the same role as one principal. (Since #215 B2 no key reaches these partials at all — the MCP key is confined to /mcp — so this rule is now the second line.) ApiKeyFilter applies no path test and ApiKeyCredentialMatcher makes key requests CSRF-exempt, so an admin-scoped key reaches these partials with a single header. It could then create a local admin, read the one-time password out of the response body, and sign in — trading a revocable, workspace-pinned, non-interactive credential for a dp_session that is not pinned and that outlives revocation of the key that created it. That defeats the ~60s revocation contract in §8, which is the entire answer to a leaked agent key (§2, principle 5).

The self-service change is the same shape one floor down: profile.password is every role's, so without this rule a leaked key could guess its owner's password and, on a hit, rotate it into a full takeover.

Deliberately excluded: activate, deactivate, promote, demote. These administer users without ever emitting a credential, and are already ratified for keys through the documented /api/v1/auth/users REST surface (§7.6 user.manage). The line this draws is credential-minting, not privilege.

Second layer. Because a hijacked session is still a threat, LocalPasswordService.changeOwn also consults the §5A.3 lockout before any Argon2 work, counts failures on the same counter as POST /login, and audits them (auth.password.change_failed, auth.password.change_locked). Before this it had none of the three, making it an unmetered, unaudited guessing oracle beside a fully-defended login path.

5A.8 Mail: the welcome mail and the new-user notice

Two notices, owned here because they are outbound adapters of this module's own flows (137, the owner's 2026-09-14 rulings; keys in Configuration §3.27):

Mail is enabled exactly when it is configured — host and from both set; there is no flag (Configuration §3.27). Any SMTP server (Postmark's SMTP endpoint is one); STARTTLS is required-not-opportunistic and the hardened posture refuses it off; the Postmark stream header is optional and rides every message when set. With mail off, every notice is one INFO line (event=mail.skipped, kind and recipient domain only — Observability §3.4B) and nothing is claimed or audited.

The mechanics (MailNotifier, MailSender, MailSendRepository — mail_sends, Metadata DB §4.19):

1. Rendered once, Thymeleaf text + html parts from mail-templates/; the password is a template variable and nothing else in the product ever sees it again. It exists in exactly one place: the message body handed to the transport. Not in the audit row, not in a log line, not in the claim row — pinned by MailNotifierIntegrationTest (a positive control proves the password DID reach the transport, then audit, log capture and row_to_json(mail_sends) are grepped for it: zero hits).
2. Claimed before it is sent, on the request thread: one mail_sends row per message identity (user, kind, act) — act is the user's own id for welcome and new_user (once per user, ever) and a fresh id per password_reset (two resets are two credentials and two mails). ON CONFLICT DO NOTHING: a retry, a double-submit or a second instance finds the row and does not send. The welcome mail carrying a password never goes twice. The claim rides the caller's transaction when there is one, so a rolled-back creation claims nothing; it exists — PENDING — by the time the admin screen renders. The row proves an ATTEMPT, not a delivery, and is never cleaned up.
3. Sent after commit, off the request thread: registered as an afterCommit synchronization when a metadata transaction is open (today neither hook point runs in one — the create paths catch-and-reread a duplicate insert, which an aborted Postgres transaction would forbid), else handed to a bounded pool at once (two threads, a queue of 100, caller-runs on overflow — not discard, because a discarded welcome mail is a password nobody has). A failed send NEVER fails the request. The transport's timeouts are bounded (connect 10 s, read/write 30 s). A connect failure — the one class that proves nothing was delivered — is retried in place, bounded (3 attempts, 250 ms / 1 s backoff, each retry logged mail.send_retry; 158, #121); anything past connect (a read timeout after DATA, a 5xx, an authentication refusal) is terminal at once, because the server may hold the message and a password mail never risks a second copy.
4. Recorded: sent_at + the Message-ID on the claim row and mail.sent in the audit log; or error (the exception's class and message) on the row and mail.failed — kind, to, act_id and the id or the error in details, never the body (Enums §15). A row still PENDING long after its claim is a send the process never got to (it died between commit and send): the admin screen shows it, and the admin's answer is a reset — never a silent retry of a password mail.

What the admin screen shows follows from the derivation (UI §4.12): with mail on, create and reset show "Emailed to <address>" with the claim's outcome — sending (polled until terminal), sent, or failed with the error — and never the password; an admin should not have to message anyone, and two copies of a credential are one too many. With mail off they show the password as before.

6. Session Tokens (Internal JWT)

6.1 JWT format

After OIDC login, the server issues its own JWT:

• Algorithm: HS256 (HMAC-SHA256, symmetric).
• TTL: 8 hours (configurable via DATAPIPELINES_AUTH_JWT_TTL_HOURS).
• Claims:

  {
    "sub": "user-uuid",
    "email": "alice@company.com",
    "name": "Alice Wang",
    "active_workspace": "acme",
    "iat": 1691234567,
    "exp": 1691263367,
    "iss": "datapipelines"
  }
  

  active_workspace is present only when login resolved one (§4.2 step 4); it is the workspace name, the same value DP-Workspace carries (§5.6).
• Signing secret: DATAPIPELINES_JWT_SECRET env var (≥ 32 bytes random, base64). Required at startup.

No authority rides the token. What a session may do is its membership's role in the active workspace, resolved per request (§11A), plus the user row's is_admin re-read through the §11.4 cache — never a claim, so a demotion or a revoked super admin takes effect within one TTL rather than at token expiry. A scopes claim a pre-round-1 token may still carry is ignored (scopes were removed entirely in #215).

A browser session is therefore the broadest credential in the product — switchable across every workspace the user belongs to (§5.6), where a key's workspace is pinned at issue and immutable. There is no read-only session: the §7.6 matrix cannot express "this principal is a browser" or "this principal is a key", so the four gates that need that distinction are written outside it, by hand — requireSessionAdmin on the credential-minting admin actions (§5A.7), changeOwnPassword refusing keys (§5A.4), POST /workspace/switch (§5.6), and the published-endpoint surface refusing sessions (§7.7). Anything that must distinguish the two is a fifth one, written outside the matrix too. (Since #215 B2 the MCP key reaches none of the four surfaces, so each is also a second line behind the kind confinement, §7.7.)

6.2 Why not use OIDC tokens directly?

• Decoupled TTL. Our JWT has its own TTL (8h). OIDC access tokens have provider-specific TTLs (Google = 1h). Using OIDC tokens would require refreshing mid-session.
• Our own authorization model. What a session may do is our roles (§11A), resolved per request. OIDC tokens carry provider scopes which don't map to it.
• Stateless validation. Our JWT is validated with a local HMAC secret. OIDC token validation requires fetching the provider's JWKS (network call).
• No vendor lock-in. Whichever provider authenticated the user — an OIDC one, or GitHub over OAuth 2.0 (shipped, #655) — the internal JWT is identical.

6.3 JWT validation (on every request)

class JwtAuthenticationFilter(
    private val jwtService: JwtService
) : OncePerRequestFilter() {

    override fun doFilterInternal(
        request: HttpServletRequest,
        response: HttpServletResponse,
        filterChain: FilterChain
    ) {
        // Extract JWT from cookie
        val cookie = request.cookies?.firstOrNull { it.name == "dp_session" }
        val jwt = cookie?.value

        if (jwt != null) {
            try {
                val claims = jwtService.validate(jwt)
                val userId = UUID.fromString(claims.subject)

                // Liveness re-check through the ONE predicate (§11A.3): cached (60s TTL,
                // same cache infra as §7.3) lookup of users.is_active. Deactivation kills
                // the session within ~1 min — `auth.principal_deactivated`.
                principalLiveness.require(userId, pin = null)

                val principal = AuthenticatedPrincipal(
                    userId = userId,
                    email = claims["email"] as String,
                    displayName = claims["name"] as String,
                    authMethod = AuthMethod.OIDC,
                    keyId = null
                )
                SecurityContextHolder.getContext().authentication =
                    UsernamePasswordAuthenticationToken(principal, null, emptyList())
            } catch (e: Exception) {
                // Invalid/expired JWT or deactivated user — clear cookie, proceed unauthenticated
                response.addCookie(Cookie("dp_session", "").apply { maxAge = 0 })
            }
        }

        filterChain.doFilter(request, response)
    }
}

6.4 Session expiration

JWT expires after 8h (configurable). On expiry:

• API calls return 401 auth.session.expired.
• UI redirects to /login.
• No refresh token flow. User re-authenticates via OIDC.

6.5 Logout

POST /logout
Cookie: dp_session=<jwt>

Server clears dp_session cookie. The JWT itself is stateless and not revoked server-side — but with the cookie cleared and the JWT gone from the client, the session is effectively dead. The OIDC provider's session is NOT terminated (user may need to sign out separately at Google/Microsoft if they want full logout).

7. API Keys

Unchanged from the previous auth spec — API keys are independent of the OIDC login mechanism. A user logs in via OIDC, generates API keys from the UI, and those keys are used by agents.

7.1 Anatomy

dpk_<key_id>.<random_secret>

• dpk_ — literal prefix (secret-scanner detectable).
• key_id — 12-char base32, unique per key.
• random_secret — 48-char base32.
• Total length: ~64 chars.

7.2 Storage

Argon2id hash (same as before). Schema in Metadata DB spec.

7.3 Validation flow

1. Client sends DP-API-Key: dpk_<id>.<secret>
   (on /mcp, Authorization: Bearer dpk_<id>.<secret> is equivalent)
2. Parse id and secret.
3. Look up api_keys WHERE id = 'dpk_<id>' AND is_revoked = false.
4. Not found → 401 auth.api_key.invalid.
5. expires_at < now → 401 auth.api_key.expired.
6. Argon2id.verify(key_hash, full_key).
7. Verify fails → 401 auth.api_key.invalid.
8. PrincipalLiveness (§11A.3), cached, 60s TTL: the users.is_active of the
    user the key ACTS AS — its own identity (§4.7) for every kind — and,
    for an MCP key only, of its CREATOR besides (A20: a deactivated
    person's MCP keys are refused until reactivation; endpoint and server
    keys stay creator-independent, PK2)
    → inactive is 401 auth.principal_deactivated; the pinned workspace's
    liveness → deactivated is 404 auth.key_workspace_inactive. A server key
    on the promotion route folds both into 401 auth.promotion.key_invalid.
9. Update last_used_at, last_used_ip (async).
10. Build the principal: userId = the user the key acts as — its own
    identity (§4.7) for every kind. Every key carries its KEY ROLE (§7.5):
    the MCP key the role CHOSEN at creation (A13), an endpoint or server
    key its transport role (`api_caller` / `promotion_receiver`). Nothing is
    read from any membership. No key principal is ever a super admin (B1).

In-memory cache (datapipelines.auth.api-keys.cache-ttl-seconds, default 60s) for recently-validated keys, user liveness and memberships, invalidated on revocation/deactivation/role change on the local instance and by TTL elsewhere — so a role change, a member removal, a key revocation or a deactivation takes effect within the auth cache TTL, 60 s by default (#215 B5, record amendment A9).

7.4 Issuance

Keys v2 (#233, A13–A15) — every key is a robot member of one workspace, and the Keys page is the ONE creation path for every kind. No key is minted at sign-in any more: the login mint (D16), the top-bar chip and minted_at_login are retired (V37). What each kind is and who may create it:

• An mcp key is created by anyone holding mcp_key.create (author, promoter, workspace admin; a super admin) — on the Keys page (POST /partials/api-keys) or over REST (POST /api/v1/auth/api-keys), naming the ROLE it should carry. The subset rule (§7.5, A14) decides which roles the creator may offer; a request for a role outside that set is refused with auth.role_required, details.required = the role, details.held = the creator's. viewer is never a key role (A15) and super_admin is not a value api_keys.role accepts (B1). A first login creates NO key (A15).
• An endpoint key (shown in the UI as an "API key", D17) is created by a workspace admin or super admin (api_key.create), with its endpoint associations in the same request or added later from the page. It acts as its own identity (§4.7) with the api_caller role.
• A server key is minted — and revoked — by a super admin (server_key.create, D18; server_key.revoke for the revocation). It acts as its own identity with the promotion_receiver role.

Revocation (A14/A17): a creator may revoke a key THEY created (mcp_key.revoke_own, author and above) — DELETE /api/v1/auth/api-keys/{keyId} or the page's Delete; a caller holding api_key.revoke revokes any key of the workspace through the same routes, a server key additionally needing server_key.revoke. Removing a member revokes EVERY live key they created in that workspace, of every kind, each audited with reason member_removed (A17/B6 — the created-by generalisation of #200); the members-row lever (reason admin_revoked) does the same without removing them. One edge, stated: a key whose creator no longer holds ANY membership of the key's workspace — an ex-super-admin's key, say — has no creator revoke-own to answer to (their permission is judged where they are a member); in that workspace it is revocable by the workspace admin's api_key.revoke alone. Revocation is the end state — keys and identities are never hard-deleted by the application; the retention sweep's purge (§11C) deletes a revoked key and its identity only once nothing references them (A17/B5).

Names are unique per workspace among live keys (A18): (workspace_id, name) is a partial unique index, so a replacement key needs a fresh name until the old one is revoked.

The show-once copy survives only as the V37-migrated login keys' sealed plaintext (§4.7): a key created on the page returns its plaintext in the create response exactly once (§7.4's original rule) and stores nothing copyable; a migrated key's unread copy is opened ONCE by its creator from the Keys page (GET /partials/mcp-key/secret — the open and the clear are ONE creator-scoped statement, ApiKeyRepository.openAndClearSealedSecret), and the fetch-metadata guard still refuses anything a browser marks cross-site or as a navigation (the §7.4 Sec-Fetch rule of #213). No NEW key is ever minted with a sealed copy (A15).

For every key created on demand, the guards run in the service, before anything is written: the creator must hold the KIND's create permission in the pinned workspace (mcp_key.create for mcp — the route's floor, since it is the LOWEST of the three; api_key.create for endpoint; server_key.create for server; gate 7); and the subset rule (A14, record O3 ruled) — a key's role must not hold a permission its creator lacks in that workspace. The identity and the key are then created in ONE transaction (§4.7). A request that still sends scopes is refused by name (scopes were removed, PK8); one that names NO kind is refused with auth.key_kind_not_mintable (keys v2: there is no default kind to fall back to). The workspace pin is unchanged: a key is pinned to a workspace (design §5.2) and the pin is the key's request context for its entire lifetime (§5.6). The HTTP surface for key management is defined in REST API §16.

7.5 Key roles

Scopes are gone (#215 slice (b), record PK8), and since keys v2 (#233, A13) every key carries a role of its own — chosen at creation, held by its identity, judged by one column of §7.6. Nothing is derived from a membership at request time: no cap (PK4 retired), no freshness rule (C2 retired) — the member's later role changes do not flow to the key, and the key's authority changes only when someone creates a new key. What freshness remains is revocation's (§7.4): a creator's revoke-own (mcp_key.revoke_own), the workspace admin's api_key.revoke, member removal, and the members-row lever.

The subset rule (A14, record O3 ruled): a creator may give a key any role whose permission set — the one RolePermissions table, read off the §7.6 columns — is a subset of the creator's own permissions in that workspace. No ordinal ladder exists: promoter and author are not comparable and neither may mint the other; a workspace admin's column contains both, so an admin may mint any of the three; a super admin holds every permission, so any role. RolePermissions.offerable is the one predicate, consulted by the Keys page dialog, the REST route and the service.

Key roles are snake_case everywhere — storage, wire, the CHECK — and the UI shows a human label ("api caller"). A key's role is stored on its row (api_keys.role), and a database CHECK (V37, widened V45) makes the kind/role families a fact: mcp ⇒ one of the three member roles (role IS NULL tolerated only on a revoked pre-v2 row), endpoint ⇒ api_caller, server ⇒ promotion_receiver, dashboard ⇒ dashboard_viewer — the transport arms spelled with role IS NOT NULL, because under SQL's three-valued logic the bare comparison would admit a NULL role.

No key is ever a super admin (B1). superAdmin is false on every key principal, and super_admin is not a value api_keys.role accepts, so no key resolves an instance permission, whoever minted it.

7.6 Operation Matrix — the permission catalog (authoritative)

This matrix is the ONLY place authorization requirements are defined. REST API, MCP Server, and UI Screens reference it; they never assert anything locally. Since #215 slice (a) it is the permission catalog of the permissions and keys record §2 (ratified 2026-09-23, amended 2026-09-24): one row per <functionality>.<permission> — 100 on this base — and every REST handler, UI route and MCP tool declares exactly ONE of them (@RequiredScope(Permission.X) on a handler; the tool's catalog entry, McpToolCatalog.Entry.permission, since slice (b)). The thirty coarse operations of v2 (READ_RESOURCES … MANAGE_DATASOURCE_GRANTS) are retired; each maps onto the permissions its surfaces were spread over.

Since slice (b) there is one axis, the ROLE (§7.5, §11A):

• The member roles — the five columns viewer … super_admin; in code the ONE role table RolePermissions. For a session that is its own membership's role. For the MCP key it is the key's OWN role — chosen at creation, held by its identity (A13): no member's CURRENT role flows to it, so no demotion reaches it — nothing is re-read (PK4 and C2 are retired). A key whose role must change is revoked and replaced, and the freshness levers are all revocation's (§7.4): revoke-own, api_key.revoke, member removal, the members-row lever. Super admin is a property of the USER, held in every workspace (D7): ✓ on every row except the two fenced ones — and never on a key (B1).
• The key roles — the three columns api_caller, promotion_receiver and dashboard_viewer (record §3.2; dashboard_viewer since L5): an endpoint, server or dashboard key is judged by its key role's column and nothing else.

Cell alphabet. ✓ = the role holds the permission; ✗ = refused with auth.role_required (the MCP key is judged as its OWN key role — details.held names it; auth.key_issuer_role_lost remains only on the context-judged path, §9); own = held, and the read or cancel path additionally limits the caller to their OWN runs (D11: executed_by = self) unless they also hold execution.read_all / execution.cancel_all; all = held, every row of the workspace; lens = held, and the promoter LENS (178, §11A.1) narrows WHAT is returned to released objects newer than the promotion target's — a hidden object answers exactly as an absent one, and an unreadable target answers NOTHING (fail closed); fenced = no MEMBER role holds it, super admin included — only the promotion_receiver key role does, through the promotion server-key route family (§7.7). In the key-role columns, own = the executions the key started (its identity's runs, §4.7), bound = what the key's bindings admit — for api_caller the published paths bound to the key (§7.7), for dashboard_viewer the dashboard folders bound to it (§7.7; an unbound key serves NOTHING), and lens the promoter lens (the mcp:promoter column mirrors the promoter member cell, and an mcp promoter key IS lensed — A13); fenced refuses (the promotion receiving rows, §7.7). Every ✓ / own / all / lens / bound cell is allowed to the role walk; ✗ and fenced are refused.

ScopeMatrix.allowed(principal, permission, workspace) answers it and is the only function ScopeInterceptor and the MCP dispatcher call; a handler or tool that declares no permission is refused with auth.permission.undeclared. A refusal's details name the catalog permission (required) and the ROLE it was judged as (held: viewer … workspace_admin, super_admin, a key role — informative only). Each row's Surfaces cell names every route in code font as the handler maps it (VERB /path, a path variable's regex dropped) and, after MCP:, every tool by wire name — the drift test, the reachability gate and the role walk read the placement from here, so a route or tool the table does not place, or places on a row other than the one it declares, fails the build. Four rows have no surface of their own — execution.read_all, execution.cancel_all, server_key.create, server_key.revoke — because a service asks for them inside another row's route (the own-only execution filters, the cancel paths, the key issuance and revocation services); the reachability gate counts that service check as the row's claim.

The catalog — permissions and roles: (record §2, #215; keys v2 #233 — 67 permissions; the scheduler #9 — 73; the parameter engine #194 — 82; the dashboards #10 L1b — 96; the dashboard runtime #10 L2 — 97; the transfer #10 L1c — 99; the dashboard key kind #10 L5 — 100)

(There is no datasource WRITE on the MCP surface at all (094): registering one means handing over a live database credential, and no credential travels through an agent — creating, editing and deleting a datasource are UI/REST-only. Nor is there a workspace, membership, release or promote tool: those are human verbs (D-R2, O-2), which is the same reason no key is ever a super admin (B1). 38 of the 42 tools operate inside the API key's pinned workspace; the four exceptions are calculators_list / calculators_get (072) and docs_list / docs_get (120), and only because they touch no workspace data at all — the calculator catalog and the shipped skill docs are properties of the BUILD, identical for every caller.)

UI screens reference the same permissions as the routes they call; per-screen minimums are listed in UI Screens and MUST match this matrix. Since round 2 (114) they also RENDER by it: a verb this matrix would refuse is not drawn at all, and the screen-by-screen inventory — every verb, the role boolean that renders it, and the permission it answers to — is UI Screens §4.3e. There is deliberately no "UI" column here: the rendering rule is derived from the role columns, and a second copy of it in this table would be a second thing to keep true. The htmx partials (/partials/**) and the workspace screen actions declare their REST twin's permission with the same @RequiredScope mechanism, and the ScopeInterceptor governs every non-public route with the same default-deny: an unannotated handler is refused (auth.permission.undeclared), and a mutating partial enforces its twin's permission. Three rail items follow a row since 2026-09-20 and are drawn only for the roles that hold it: Executions (execution.read), Promotion (promotion.read), Workspaces (workspace.read; a principal with no workspace keeps the link because the no-workspace page is the one screen that explains their state).

No PAGE route floors above read. The last one did until #348: the pipeline editor (GET /pipelines/{id}/editor) declared pipeline.execute (122) — the permission the screen it USED to serve existed to exercise for its lowest role (D3: viewers execute what they can read). The read workspace made version selection explicit and the editor page a READ page (GET /pipelines/{id}, the canonical route), so the old route is a compatibility REDIRECT at pipeline.read: the promoter walks through it to the released content exactly as the canonical route admits, a viewer reaches the same page, and the lens — not the route — decides what either sees. Execute remains its own POST on its own row, CSRF-checked and role-gated; no page's GET carries a write's floor. The template editor (GET /templates/editor) floors at template.read since 143 (T315, owner ruling): the explorer's Open links render for every reader, the page renders read state (a draft body is read, never written, by a GET), and every write it can make — Edit, Preview, the lifecycle dialogs — is its own route on its own permission, hidden by role in the markup (UI Screens §4.7). 096 §C's authoring floor stays on those writes. Every GET declares the LOWEST permission whose row admits it (ReadFloorTest): a read of executions is execution.read, not pipeline.read, because their role sets differ; a read of the workspaces page is workspace.read; a dialog fetched for a verb floors at that verb's permission; every other read a signed-in person may make is one of the every-role reads (pipeline.read, template.read, datasource.read, endpoint.read, semantic.read, the self rows).

7.7 Key kinds and published-endpoint bindings

Round 074 gives every API key a kind (ApiKeyKind, api_keys.kind, default user); round 091 adds the third. A kind answers WHERE a credential may be presented; its role (§7.5) answers what it may do there.

Each kind carries exactly one role (the database CHECK, §7.5), so a request that names a role its kind cannot hold is refused rather than quietly corrected (endpoint.key_kind_refused) — a caller who writes {"kind": "endpoint", "role": "promotion_receiver"} holds a mental model this surface has to correct out loud. A request that still sends scopes is refused by name.

The confinement is central, not per-handler. Every key kind is refused on every route outside its own family, so a new route cannot become reachable to one by someone forgetting a check — the same default-deny reasoning as the unannotated-handler rule in §7.6. The MCP key's family is /mcp; ApiKeyFilter refuses it everywhere else FIRST (the chain stops there — a session cookie on the same request does not rescue it), and ScopeInterceptor states the same reach table for every MVC handler (ScopeInterceptor.reachableBy). Two properties of the interceptor's check are load-bearing:

• It is decided before the handler's @RequiredScope is read. A UI page carries no annotation and lives outside the governed prefixes, so an annotation-first order would let every screen in the product answer a credential that authorises none of them (091: a scopeless key could render /settings/api-keys and read its owner's key list).
• On the routes a confined kind may reach, what it may DO is its key role (§7.5). Keys v2 A16 narrows the endpoint family to the published tree alone — the paging routes ride it, and the framework's execution routes are simply off the surface, so the old "reached by path, refused by role" case on DELETE /api/v1/executions/{id} is gone.

/mcp is a servlet, not an MVC handler, so the interceptor never sees it; McpAuthFilter refuses EVERY kind except mcp there (the endpoint, server and dashboard keys alike — stated as the allowlist "kind = mcp" rather than a denylist of the confined kinds, so the next kind cannot pass to /mcp untouched). Without that refusal such a key could not CALL a tool (its key role holds no tool's permission) but could still read the whole catalogue through tools/list.

The dashboard kind's bindings (L5)

dashboard_key_bindings is endpoint_key_bindings' twin: name_prefix (a folder of the dashboard NAME space — the folder grammar's 1–9 segments, or the root /), api_key_id, workspace_id, created_by, created_at; PK (name_prefix, api_key_id). The two binding routes are dashboard.key.bind's (§7.6), and binding/unbinding is audited dashboard.key_bound / dashboard.key_unbound (Enums §15).

A binding names a folder of the dashboard name space, not a pattern: finance/dashboards binds every dashboard whose name begins finance/dashboards/, and the root / binds the workspace's whole dashboard tree. Per request the dashboard's name ancestors are walked from the most specific (finance/dashboards/private/x → finance/dashboards/private → finance/dashboards → finance → /), and the first node carrying any binding decides — R-EP2 verbatim: a deeper binding therefore replaces an inherited one rather than adding to it, so a key bound at finance/dashboards stops serving finance/dashboards/private/** the moment someone binds another key at finance/dashboards/private. Bind both keys at the deeper node when both should keep working.

The unbound case is where the security lives (the endpoint rule, #215 B3): a dashboard with no binding on any ancestor of its name is served to NO key. An unbound dashboard key, a key bound elsewhere, and a key of another workspace all get the dashboard family's ordinary 404 (dashboard.not_found) on a runtime route — a hidden dashboard is indistinguishable from an absent one (§11A.1). At bind time the prefix must be the root or a folder at or above a dashboard the CALLER'S workspace actually has — the same non-disclosure rule the endpoint bindings' requireInsideWorkspace follows (#191).

The runtime's reads for a dashboard_viewer principal go through the key's lens — the admitted names are what the R-EP2 walk admits, computed per request from the key's workspace bindings. The refresh records of a key principal carry principal_key_id (V43's column; principal_user_id stays NULL — the CHECK wants exactly one), and the executions it delegates carry executed_by = the key's identity with executed_by_key_kind = 'dashboard' (D50).

One key = one budget, deliberately: the SSE stream cap (datapipelines.sse.max-streams-per-user) and the §11A rate limit are keyed on the principal's identity, so every end user behind one key shares that key's budget. Size max-streams-per-user for the host application's concurrency (Configuration §3.6); the reference proxy's README says the same.

Hierarchical bindings (ruling R-EP2)

A binding names a node of the endpoint tree, not a pattern: /lending authorises every endpoint beneath it. Per request, the ancestors of the request path are walked from the most specific (/lending/{borough}/home → /lending/{borough} → /lending → /), and the first node carrying any binding decides. The presenting key must be among that node's bound keys, or the request is 403 endpoint.key_not_bound.

A binding stays inside its workspace (2026-09-21, #191). At bind time, a prefix is refused unless it is the root / or a node at or above a path the CALLER'S workspace publishes — endpoint.path_invalid, with a message that names only the caller's own tree, because whether another workspace publishes at the prefix is exactly what the refusal must not reveal (§11A.1). At serve time, a binding decides only for an endpoint of ITS OWN workspace: the ancestor query filters on the endpoint's workspace_id, the authorizer re-checks the surviving rows in memory (fail closed, either layer alone suffices), and a foreign binding at a nearer node neither authorises nor shadows — the walk continues past it as if the node carried nothing. A root binding is therefore still safe: it exercises only bindings of the serving key's own workspace.

A deeper binding therefore replaces an inherited one rather than adding to it: a binding at /lending/private hides the one at /lending for that subtree, and the key bound at /lending stops working there. Bind both keys at the deeper node when both should work.

The demo workspace's public key (#224) is an ordinary endpoint key — an api_caller minted at bootstrap from datapipelines.bootstrap.demo-api-key, named demo-public-key, bound to the demo family's published paths and shown on the site's demo-data page; nothing about it is a fourth kind, and its budget is the serve path's per-key budget (rest-api §19.8).

That is the more conservative of the two readings, and it is chosen deliberately. An operator who binds a narrow key deep in the tree is drawing a boundary; an additive model would silently keep the broad key working across it. The cost of "replace" is a binding an operator can see is missing and add; the cost of "add" is a boundary that was never real.

A bound node decides for every credential that reaches it — since B2 that is only ever an endpoint key.

The unbound case

An endpoint with no binding on any ancestor is not public and not open to any key: it is unservable until a key is bound to it (#215 B3). Serving takes a key (a session is refused with auth.session.required), and since B2 the MCP key never reaches a published path — so the only credential that can arrive is an endpoint key, refused with 403 endpoint.key_kind_refused. Until slice (b) a user key of the endpoint's own workspace holding execute was admitted here; that branch went with the scopes.

That is the security property: an unbound path authorises nothing. If an unbound path fell through to "any endpoint key may call it", publishing a new endpoint would silently widen every existing endpoint key's reach at the moment of publication.

Reading results

An endpoint key may read the metadata and the cursor of executions it started (api_caller holds execution.read and execution.result.read, both own). Since #215 its runs carry its own identity in executed_by (§4.7), so ownership is the ordinary own-runs rule — executed_by = the principal — and the key's creator does NOT see the key's run as their own (only execution.read_all does). Runs served BEFORE V34 carry the creator instead; for those, ownership is still proved by the endpoint.served audit row that pairs the key id with the execution id. A different endpoint key asking for the same execution is refused either way.

Issuance

POST /api/v1/auth/api-keys takes kind and bindings in the same request, and the bindings are validated before the key is minted. They are part of issuance rather than a second call because the plaintext key is returned exactly once: a failure between mint and bind would leave an operator holding a secret they can neither use nor re-read. Since 179 the route is api_key.create (workspace admins and super admins), kind is endpoint, server or dashboard (L5) — user is refused with auth.key_kind_not_mintable, and an absent kind means user, so a pre-179 client meets the refusal rather than silently minting a different credential — and the bindings may name the key by api_key_id (the /api-keys page's shape) or, kept for REST compatibility, by the caller's own key's api_key_name (endpoint bindings only: since L5 the by-name path filters the kind, exactly as the by-id path always did). The request may name the key's role (only the kind's own); the response carries role, the identity it acts as ({id, display_name}) and created_by. Everything else about a transport key is an ordinary key — dpk_ prefix, Argon2id, expiring, revocable, rate-limited on its identity's budget (§11A). A dashboard key is minted WITHOUT bindings (they are dashboard.key.bind's verb, on the key's card after mint); the endpoint bindings field on a dashboard-key request is refused, exactly as on every non-endpoint kind.

Binding and unbinding are audited (endpoint.key_bound / endpoint.key_unbound, Enums §15), as is every serve (endpoint.served).

The server kind (091)

Promotion is one deployment writing RELEASED content into another (Versioning §10.6). Its credential is a server key, and since #215 a stored one acts as its own service identity (§4.7) with the promotion_receiver role — no human it can be traced to, and no longer the System account's authority (record C4). 091 changed where the key LIVES.

Until 091 it was a pre-shared configuration value — datapipelines.deployment.promotion.server-key — which nobody can mint, list, expire or revoke without editing a file and restarting the deployment. A server key is the same credential stored like every other key: Argon2id hash, dpk_ prefix, an owner, an expiry, a revocation flag and a last-used stamp. The configured value is accepted for one release and WARNs at boot (Configuration §3.19).

• Minting is server_key.create — a super admin's (D18): whoever holds this credential can write pipelines, templates and datasource references into the receiving deployment.
• Role: promotion_receiver — promotion.inventory.read and promotion.push, and nothing else. The confinement is the route family, asserted the same way an endpoint key's is. Intake is instance-wide (#215 B6, owner ruling 2026-09-24; record amendment A11): a batch names its target workspace and the receiver resolves it by name, for ANY workspace — the key's workspace_id is where it is listed and administered (the Keys page), not a confinement.
• Presented as DP-Promotion-Key, by a deployment. PromotionServerKeyFilter compares the configured value first (constant time — a deployment that has not migrated pays no database read), then validates the header against the key store. Fail-closed is unchanged: no configured value AND no live server key ⇒ every push refused. Missing header, malformed header, wrong key, wrong kind, revoked, expired, a deactivated identity or pinned workspace and "nothing configured here" all answer the same auth.promotion.key_invalid, so a caller cannot classify a credential by asking. The creator's liveness is not consulted (PK2).
• The actor is the key's own identity (record C4), never the admin who minted it: received versions and the auth.promotion.accepted row name it. The deprecated config value — a bootstrap credential with no row to attach an identity to — stays the System account (§4.5, B6), with the same promotion_receiver role. The key's id rides on the principal so the audit trail can name WHICH key across a rotation, and last_used_at is stamped like any other key's.
• Presented as an ordinary DP-API-Key it authenticates a principal that is refused everywhere — /api/**, /partials/**, /mcp and every UI page — with 403 endpoint.key_kind_refused and details.reason = "server_key_off_surface".

Rotation, which the config value never had: mint a second server key, set it on the sender, revoke the first. No restart, on either side.

8. Spring Security Configuration

8.1 Filter chain

Security headers are written before the downstream filter chain starts. An SSE worker may write the response while the original servlet thread unwinds; deferred security-header inspection at that point would race the container's mutable headers. HeaderWriterFilter therefore uses eager writing. The default security and private-cache headers remain enabled; an explicit application Cache-Control value (including public page/asset TTLs) overrides that header afterward. This changes header timing, not authentication, authorization or CSRF rules.

The sketch below is the shape of SecurityConfig.securityFilterChain as it is actually assembled, not a simplification: the three addFilterBefore calls read in the REVERSE of the order they produce, which is why the resulting order is spelled out under §8.2 rather than inferred from the source. The permitAll list is not written inline — it is PublicPaths.ENTRIES (§8.3), so every pattern carries a reason and is reachable to the tests that guard it.

@Configuration
@EnableWebSecurity
class SecurityConfig(
    private val filters: AuthFilters,                 // apiKey, jwt, loginRateLimit, promotionServerKey, workspaceResolution, oidcSignedInBounce
    private val oidcSuccessHandler: OidcSuccessHandler,
    private val scopeInterceptor: ScopeInterceptor,
    private val forcedPasswordChangeInterceptor: ForcedPasswordChangeInterceptor,
    // …entry point, access-denied handler, logout handler, OAuth2 authorization-request
    // repository + resolver, AuthProperties
) {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http
            .csrf { csrf ->
                // Cookie: dp_csrf (readable by JS), header: DP-CSRF-Token; the plain
                // (non-XOR) request handler keeps cookie value == header value.
                csrf.csrfTokenRepository(cookieCsrfRepository())
                // Exemption follows the CREDENTIAL, not the path (§8.4): DP-API-Key (or
                // Bearer dpk_ on /mcp); promotion requires a server-key header (§10.6);
                // screenshot upload requires a single-use DP-Upload-Token (#353). No cookie authenticates there.
                csrf.ignoringRequestMatchers(ApiKeyCredentialMatcher(), PromotionRouteMatcher(), UploadCapabilityRouteMatcher())
                // Double-submit needs a STABLE cookie; this chain has no server session to
                // protect, so Spring's rotate-or-delete strategy is neutered (027).
                csrf.sessionAuthenticationStrategy(NullAuthenticatedSessionStrategy())
            }
            .authorizeHttpRequests { auth ->
                auth
                    // A re-dispatch of an already-authorized request, not a path rule (§8.3).
                    .dispatcherTypeMatchers(DispatcherType.ASYNC, DispatcherType.ERROR).permitAll()
                    // THE allowlist — one row per pattern, each with its reason (§8.3).
                    .requestMatchers(*PublicPaths.PATTERNS.toTypedArray()).permitAll()
                    .anyRequest().authenticated()
            }

        // OIDC login is wired ONLY when providers are configured (§5A): a local-accounts-only
        // deployment has no ClientRegistrations and no /oauth2 endpoints.
        if (oidcConfigured) configureOidcLogin(http)   // + OidcSignedInBounceFilter (090)

        http
            .addFilterBefore(filters.jwt, UsernamePasswordAuthenticationFilter::class.java)
            .addFilterBefore(filters.apiKey, JwtAuthenticationFilter::class.java)
            .addFilterBefore(filters.loginRateLimit, ApiKeyFilter::class.java)
            .addFilterBefore(filters.promotionServerKey, LoginRateLimitFilter::class.java)
            .addFilterAfter(filters.workspaceResolution, JwtAuthenticationFilter::class.java)
            .sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
            .exceptionHandling {
                it.authenticationEntryPoint(authEntryPoint)      // §8.2 — splits by Accept
                it.accessDeniedHandler(authAccessDeniedHandler)
            }
            .logout { logout ->
                logout.logoutUrl("/logout")
                       .addLogoutHandler(auditLogoutHandler)
                       .deleteCookies("dp_session")
                       .logoutSuccessUrl("/login")
            }

        val chain = http.build()
        chain.filters.filterIsInstance<HeaderWriterFilter>().single().setShouldWriteHeadersEagerly(true)
        return chain
    }

    // Two MVC interceptors, registered as WebMvcConfigurer beans: the scope interceptor on
    // every handler (§7.6), and the forced-password-change gate on every handler except
    // ForcedPasswordChangeInterceptor.EXCLUDE_PATTERNS (§5A.4).
}

8.2 Filter order (per request)

 1. CORS filter                     — a container filter ahead of the security chain (one origin = auth.base-url; unset ⇒ no CORS)
 2. CSRF filter                     — validates dp_csrf on state-changing requests; exemption follows the CREDENTIAL (§8.4), never the path
 3. PromotionServerKeyFilter        — /api/v1/promotion/** only: the DP-Promotion-Key gate (§10.6). Inert everywhere else
 4. LoginRateLimitFilter            — /login and /oauth2/ only: per-client-IP damper, 429 rate_limit.exceeded (§11.5)
 5. ApiKeyFilter                    — checks DP-API-Key header (or Bearer dpk_ on /mcp); if present, validates and sets SecurityContext
 6. JwtAuthenticationFilter         — checks dp_session cookie; DECLINES when ApiKeyFilter stashed a rejection (§8.4); skips /mcp entirely
 7. WorkspaceResolutionFilter       — resolves the active workspace onto the principal (§5.6): DP-Workspace switch or claim/pin, membership-checked
 8. OAuth2LoginAuthenticationFilter — handles /oauth2/** and /login/oauth2/code/** redirects (wired only when a provider is configured)
 9. AuthorizationFilter             — checks the §8.3 allowlist, then authenticated() for everything else
10. ForcedPasswordChangeInterceptor — §5A.4, every handler except EXCLUDE_PATTERNS
11. ScopeInterceptor (MVC)          — kind confinement (§7.7), then @RequiredScope; default-deny for unannotated handlers outside the §8.3 allowlist;
                                      an ASYNC re-dispatch passes untouched — the REQUEST dispatch judged it (§8.3, #404)
12. Controller                      — handles the request

If neither API key nor JWT is present (and the path requires auth), the AuthorizationFilter routes to the entry point, which splits by client shape (T31): a request whose Accept includes text/html — a browser navigating a UI route — gets a 302 to /login (the Location is a relative header, never sendRedirect's Host-derived absolute URL); /api/** and /mcp NEVER redirect (their 401 JSON envelope is contract, byte-pinned), and non-HTML clients (curl's Accept: */*, JSON API callers) keep the exact current envelope whatever path they hit. If authenticated but scope insufficient, the ScopeInterceptor returns 403.

A streaming response's completion (an SSE emitter, a CSV body) re-enters the servlet as an ASYNC dispatch. Steps 5–7 are OncePerRequestFilters that skip it, so its SecurityContext is empty; step 9 permits it by dispatcher type, step 10 finds no principal and passes, and step 11 returns at once. The handler is not invoked again on that dispatch — only the result or exception the REQUEST dispatch's handler produced is rendered, by the @ControllerAdvice — so nothing new is authorized and the D-R8 audit row stays one per request.

8.3 Public endpoints (no auth required)

The table below is generated from PublicPaths.ENTRIES (modules/auth), which is the single source of the permitAll list the chain in §8.1 is built from. PublicPathsTest parses this section and demands equality pattern-for-pattern, reason-for-reason and round-for-round, so neither side can move without the other; PublicRouteWalkerTest (modules/web) then walks every request mapping the application registers against these patterns and freezes the resulting public handler set by name, so a new controller mapped under one of the globs fails the build instead of shipping public. Everything not matched here falls to anyRequest().authenticated().

Two things are deliberately not rows in this table:

• The DispatcherType.ASYNC / ERROR permit (§8.1). It is not a path rule: it says that a re-dispatch of a request the REQUEST dispatch already authenticated and authorized is not re-authorized from an empty SecurityContext. Without it every completed SSE stream dies as Access Denied on its completion dispatch. ScopeInterceptor holds the same premise for the ASYNC dispatch (§8.2 step 11): until v3.40 it judged the re-dispatch against the empty context, so a stream completed with an error BEFORE its first frame answered 401 auth.api_key.missing in place of the error's envelope — the execute route's 429 pipeline.execution.concurrency_limit and the idempotent retry's never-started 410 result.expired (rest-api §6.1) — while every later completion hid the refusal behind the committed response (#404). The ERROR dispatch needs no exemption there: its handler is /error, a row of the table below, which the interceptor already passes.
• Anything reached only with a credential. Being on this list means anonymous access, not "unscoped": an annotated handler on a public path is still enforced by ScopeInterceptor.

8.4 API endpoints (auth via API key OR JWT)

All /api/v1/** endpoints accept either:

• DP-API-Key: dpk_... header (agents, programmatic clients).
• Cookie: dp_session=<jwt> (browser UI calling REST directly).

The filter chain tries API key first, then JWT. If both are present the API key decides the request — including when it decides to refuse it (096 §E, review finding F9). A presented DP-API-Key that fails validation ends the request with its own code (auth.api_key.invalid / auth.api_key.expired); JwtAuthenticationFilter declines to authenticate the cookie behind it, and AuthEntryPoint answers with the key's stashed error.

Until 096 the rejection was stashed and the chain continued, so a revoked or expired key presented alongside a live dp_session was served at SESSION privilege — at least author (§6.1) — by a credential the server had just refused, and revoking a key produced no visible signal to a client holding both. Not browser-exploitable (a custom header forces a preflight this deployment does not grant), but it meant revocation did not end the session beside it.

CSRF exemption is scoped by credential type, never by path: a request is exempt only when it carries an API key (DP-API-Key header, or Authorization: Bearer dpk_ on /mcp) — a credential a hostile browser context cannot forge, with no cookie involved. A state-changing request authenticated by the dp_session cookie requires the dp_csrf double-submit token (DP-CSRF-Token header) wherever it occurs: /partials/** (UI Screens §3), POST /logout, and cookie-authenticated calls to /api/v1/** alike. /mcp accepts no cookies at all (§8.5), so CSRF never arises there. Two routes are exempt because their ONE credential is a header and no cookie authenticates anything on them — the reasoning above applied to a route, not a path glob over cookie traffic: the promotion receiver (PromotionRouteMatcher, §10.6, refused outright without a valid server key) and, since #353, POST /api/v1/visualizations/{id}/tests/sessions/{sessionId}/screenshot (UploadCapabilityRouteMatcher): its handler reads no principal, its PublicPaths entry makes it ungoverned, and the single-use DP-Upload-Token capability is verified against the run it names — an agent's Playwright request carries no dp_csrf pair, and there is no cookie session there to protect. dp_session's SameSite=Lax (§5.5 — Strict withholds the cookie on the IdP's cross-site redirect chain and strands every login) is defense-in-depth, not the control: it defends against neither a same-site subdomain attacker nor a cross-site top-level GET. In the §8.1 chain this is a RequestMatcher over the credential carrier, not a path glob. A CSRF failure returns 403 auth.csrf.invalid with details.reason: missing | mismatch (§9). All three cookies this module mints (dp_session, dp_csrf, dp_oauth2_authz) carry the Secure flag keyed off datapipelines.auth.base-url's scheme (T33): https:// — or no base-url at all — keeps Secure; an explicit http:// base-url drops it so local development login works over plain HTTP. Production MUST be https — the wrong default would silently drop sessions there, so absent configuration fails secure. The dp_csrf cookie is stable for the life of the browsing session: it is minted by the first response that renders a CSRF token (the login page) and is never rotated or deleted afterwards — the chain's CSRF config pins NullAuthenticatedSessionStrategy, because Spring's default CsrfAuthenticationStrategy rotates-or-deletes the cookie on every security-context change, which (with per-request JWT authentication, §4.2) is every authenticated request and would strand each rendered page's hx-headers token against a rotated cookie (found 027). (History: v2.2's prose and sketch contradicted each other; v2.3 briefly resolved toward path-based exemption + SameSite=Strict; v2.4 supersedes both after two Gate C seats independently flagged the subdomain gap — exemption follows the credential, not the path.)

8.5 MCP endpoint (/mcp)

POST /mcp and GET /mcp (MCP Server §3) are API-key-only — session cookies are not accepted there. Two equivalent credential carriers:

• DP-API-Key: dpk_<id>.<secret> — same as REST.
• Authorization: Bearer dpk_<id>.<secret> — for MCP clients that can only set the standard Authorization header. The ApiKeyFilter recognizes the dpk_ prefix in a Bearer token and routes it through the identical validation path (§7.3).

/mcp is CSRF-exempt (no cookie auth) and enforces the same permission catalog (§7.6) per tool.

The filter chain authenticates on the servlet thread and the MCP layer carries the principal forward in the transport context (McpToolContext), because the MCP SDK runs each tool handler on its own scheduler thread — SecurityContextHolder is empty there. Code reachable from a tool therefore takes the principal and the workspace as arguments and never reads the thread-local; a @Bean adapter that did (the save-time datasource lookup, until 134) silently validated every MCP save as "no principal" (MCP Server §4.1). Filters, interceptors and MVC controllers run on the request thread and may keep reading it.

8.6 Entry inventory and public contract

Every way into the running application, as a reviewed table the build compares with what the application actually registers — in both directions, by name (#217, security-assurance record §4, ratified B3/B5). A registration with no row fails: somebody added a filter, a servlet, a scheduled job or a listener that nobody reviewed. A row with no registration also fails: the doc promises an entry, or a guard, that is not there. Adding one of these is a two-line change — the code and its row — in the same commit, the rule AGENTS.md already applies to handlers and §7.6.

Handler methods are not listed here: §7.6 is their reviewed table (B3 — one table, never two). EntryInventoryE2eTest places every handler the application registers, from every module, on the §7.6 row of the permission it declares or in the public contract below, and every route §7.6 names must be registered.

The entry inventory: one row per registration, read at runtime by EntryInventoryE2eTest. Servlets and container filters come from the servlet container, with each filter's order from Spring Boot's sorted initializers (container when the container registered it itself). The security chain comes from FilterChainProxy, in the order it runs. Handler mappings are every HandlerMapping bean, and a mapping of a kind the test cannot read fails until it has an adapter. Scheduled jobs are every @Scheduled task. Ports and actuator endpoints come from the PACKAGED jar booted as its own process: its LISTEN sockets are read from /proc/<pid>/fd and /proc/<pid>/net/tcp{,6}, and its management port's actuator index is read with a session, each endpoint with the status an anonymous caller gets. "Reachable from a request" is no for every scheduled job (B5 — a job is inventoried, unreachable from any transport and bounded, never an entry point), and the test also fails if a job's bean is a request handler. Since #9 the scheduler's db-scheduler tasks are a family of their own (scheduler-task), read off every Task bean — a new task is a new row, and the same B5 rules hold for it.

The public contract: one row per §8.3 glob, its reason exactly as PublicPaths states it. PublicContractE2eTest holds the running application to it. Every handler under a public glob is named in the row of the FIRST glob, in declaration order, that covers it. A row names only handlers that are registered: resources for the static-resource handler, filter:<Class> for a security-chain endpoint. The rows and PublicPaths are the same set of globs, reason for reason. An anonymous GET of the probe answers the row's status, never with a stack trace and never with a session cookie. An anonymous POST, PUT and DELETE on the probe (with a matching CSRF pair, so the refusal measured is the route's) are refused (403, 404 or 405). The exceptions: the row names the suites that own those verbs (own E2E: — the login and OIDC flows are tested where they live, and the test checks that those suites exist), or states that every verb gets the GET's answer (same answer:). The "principal · write · content" cell is the reviewed claim; no test measures datastore writes here (the record's slice B effect witnesses will).

9. Auth Errors

Codes follow the {domain}.{entity}.{failure} convention; the registry of record is Pipeline Contract §13.7.

Rate limiting uses the single system-wide rate_limit.exceeded code (Pipeline Contract §13.11) — there is no separate auth-layer rate-limit code. The two limiters answer with DIFFERENT user messages (#232): the login damper says "Too many sign-in attempts. Wait a minute and try again." (what it counts — sign-in attempts), while the per-user API limiter and every API surface answer with the error catalog's request-volume sentence, "You're sending requests faster than we allow. Wait a moment and try again." (§13.11 carries both). The login damper is in-process (per instance, no Redis), so it never raises the companion rate_limit.unavailable: that code belongs to the shared per-user limiter, whose counters live in Redis and which fails closed when they cannot be read (REST API §12.3). The login rate limit is datapipelines.auth.rate-limit.login-per-minute (Configuration §3.4), and the address it buckets by — like every audit source_ip — is resolved through datapipelines.auth.trusted-proxies (Deployment §6.2): behind a load balancer, without that list every request shares the LB's address and the per-IP limiter becomes a global one. Empty (the default) means X-Forwarded-For is ignored entirely and the direct peer is the client, so a bare deployment is unaffected.

Workspace resolution failures (§5.6) use the workspace.* codes — catalogued in Pipeline Contract §13.12. The 404 rule governs them: an addressed workspace the caller cannot reach — unknown, non-member, or deactivated — is one answer, workspace.not_found (404), never a 403. workspace.membership_required (403) survives only where NO workspace was addressed (a principal with zero memberships), because there is no name there whose existence a 403 could leak. workspace.creation_forbidden was retired with the provisioning modes (§4.2).

10. Audit Log

10.1 Events

The same audit_log table also carries the promotion events — auth.promotion.rejected when the peer-credential gate refuses a request, auth.promotion.accepted when a batch is applied (Versioning §10) — the datasource decryption events (Datasources §7.4), the MCP tool events — mcp.tool.called for every tool call, mcp.tool.write for every mutating one — emitted by the MCP dispatcher through the same sink (MCP §14), and the mail events — mail.sent / mail.failed for every notice §5A.8 sends, kind and recipients in details and never a body (all registered in Enums §15).

Scheduler notification mail is not audited per send — a deliberate split (#442b). A schedule's notices are sent by the system, not by a person, on transitions a run made; their record of truth is the run's own trail (notification_enqueued / _sent / _failed / _uncertain rows — ids, attempt counts and sanitized codes, never an address; Scheduler §2.3) and the delivery rows a schedule.update holder reads on the run (REST §20.11). They go through the shared transport's MailSender directly, below MailNotifier, so they write no mail.sent / mail.failed row: that row's details carry recipients, and copying every scheduled send's address into audit_log would spread personal data into a store kept for a person's acts. What IS a person's act is audited: the resend (schedule.notification_resent, REST §20.13 — schedule, run and delivery ids and the prior state, never the address), beside the settings changes themselves (schedule.created / schedule.updated, counts and events only).

10.1A Delivery: durable before log returns (#266)

Audit rows are authorization inputs, not only a trail: an MCP key's read of its own execution is decided by its mcp.execution.launched / mcp.tool.called rows (McpCallAudit.calledByKey), an endpoint key's by its serve row (EndpointServeAudit.servedByKey), and McpToolLearnings decides the MCP entry-point checks from a key's own mcp.tool.called rows. So AuditEventSink.log returns only once the row is committed — never from memory — and a caller that proceeds can always read what it just did.

The default path is the direct INSERT (#266b). The audit writer ships switched off — datapipelines.persistence.audit.enabled: false (Configuration §3.32) — because, measured, audit rows never formed batches (mean batch size 1.0 at 500 rows/s, 1.0–1.1 at 5,000) and the writer only added to their tail (p99 +4 ms at 100 concurrent executions). By default every row is the pre-#266 INSERT: on the caller's own connection inside its transaction when it holds one, on a pool connection otherwise. The batched path exists behind the switch for a deployment whose metadata database is slow enough for audit rows to queue. How a row is committed is decided per call, by AuditLogger:

The paragraphs below on order, bounds, timestamp and the natural key describe the batched path; on the default path each row is its caller's own INSERT, as it always was.

Order. The writer is partitioned by key id (then user id): one credential's events commit in the order they were logged, and because each caller waits for its commit, an event that happens because of an earlier one (a revoked after its created) is always committed after it. That causal order is the one the product relies on. The order of ids is weaker across the transactional boundary (#266b, the security pass's observation 2): a transactional row takes its id inside its caller's transaction, a batched row when its batch commits, so a transactional row of one key can carry a lower id than a batched row of the same key that was admitted to the writer earlier — "revoked, then called" by id for a call that was admitted first. No reader compares two audit rows' relative order: the four FROM audit_log reads in main sources are McpCallAudit.calledByKey and EndpointServeAudit.servedByKey (EXISTS) and McpToolLearnings (max(timestamp) and a DISTINCT set), so no authorization decision moves; it matters to a forensic reader of the table, who should order one key's rows by causality, not by id, around a transactional event.

Bounded. A row waits at most record-max-wait-ms (Configuration §3.32) for its batch; then the caller takes it back from the queue and runs the INSERT itself, on its own thread. A row already inside a commit is waited on — exactly as long as the caller's own INSERT would have waited on the same database. The sink never returns before the row is durable or definitively not.

Failures — which reach the caller (by direction: #266b outside a transaction, #704 inside one). Outside a transaction a store failure is the row's, never the request's: a row the database refuses (a user id with no user row, a malformed address — on the batched path it fails alone, the rest of its batch commits), or a database that cannot be reached, is WARNed (audit_log write failed …), counted (datapipelines.persistence.failures{store=audit,kind=…} on the batched path) and swallowed; the request proceeds without the row. On the direct path a store failure is a DataAccessException; on the batched path it is that or a TransactionException, because the batch runs in its own transaction and an unreachable database surfaces there as CannotCreateTransactionException (a failed COMMIT as TransactionSystemException) — neither is a DataAccessException, and the direct INSERT swallowed the same outage. Anything else propagates out of log and fails the request, exactly as the pre-#266 INSERT's catch (DataAccessException) let it: a runtime exception from the driver or the template, a details map that cannot be serialized, an Error. The batched path rethrows it on the caller's thread (AuditRowSink.propagates, BatchingWriter's one claimed exit). Every WARN names the row's ids and the failure's class and SQLState — never the database's message, which quotes the refused row (Postgres puts the row in DETAIL and a fragment of details_json in CONTEXT). A malformed credential still costs no audit write at all (ApiKeyFilter, pinned by ApiKeyRejectionAuditTest). Inside a caller's transaction the same failure propagates (#704): AuditLogger runs the joined INSERT uncaught, the caller's transaction rolls back and the request is refused — the boundary's catch-all (the generic 500 envelope, reason: internal_error; REST API catalogues no code for it, and none is added), the boundary logging the failure once. A swallowed failure there kept nothing alive: on Postgres the refused INSERT aborts the caller's transaction, so its COMMIT became a silent rollback behind a success response — #517's falsification saw a release answer 200 with nothing committed. Audit rows are authorization inputs; a key issued with no auth.api_key.created row is not an outcome this product produces.

The release rows are strict (#517, release-dependencies record §11). A release — the pipeline's, and every dependency it flips — writes its *.version.released rows through StrictReleaseAuditSink, not AuditLogger: the same audit_log INSERT (AuditRowSink.INSERT), on the release transaction's own connection, and never caught. A store failure throws, the transaction rolls every flip and pointer back with it, and the release is refused — unavailable audit storage refuses the release — the same rule, for rows the release coordinator writes through its own sink. The sink refuses to write outside a transaction, never batches, never defers, and its rows carry ids, names, versions and words only, never a body. One row per actual flip, dependencies first and the root last; every row of one release shares release_id, carries scope: "version", a cascaded row cascade_root: {family, id, version}, and the root's dependencies_released (Enums §15). via keeps its existing words (session / api_key).

timestamp. Still the column default NOW() — the database's clock, which McpToolLearnings compares with pipeline_versions.updated_at and must keep free of cross-clock skew. For a batched row it is the batch transaction's start: later than the call by the queue wait (at most record-max-wait-ms, 2 s by default, before the caller writes the row itself; measured ≤ 43 ms under load), and equal across the rows of one batch (callers that were concurrent — id orders them). The consequence, stated (#266b, the security pass's observation 1): McpToolLearnings's check "rendered after the last edit" compares a key's latest render row's timestamp with the pipeline's updated_at, so a render whose row commits in a batch that began δ after the call reads as later than an edit that landed inside that δ — the check passes a render that did not see the edit. It is permissive, and it needs a SECOND actor editing the pipeline inside δ: the key's own next call starts only after log returned, i.e. after the commit, so the single-key sequential flow the check was built for is unaffected. The race existed before #266 at the granularity of the tool's own run time (the row was inserted after the render finished); the switch-on batched path widens it by δ, and the default direct path does not.

No natural key (batched path). audit_log has none to deduplicate by, so the batch is all-or-nothing (a failed batch leaves nothing behind before its rows are retried one at a time). A batch whose COMMIT succeeded but whose acknowledgment was lost to a dropped connection is retried as singles and its rows land twice — the at-least-once edge of any retried write; the writer counts every retried batch (datapipelines.persistence.batches.retried{store=audit}).

Retention (datapipelines.audit.retention-days) is documented but still not implemented — nothing binds the key or deletes rows (#266 finding, tracked separately).

10.2 Log shape

{
  "timestamp": "2026-08-05T14:30:00.123Z",
  "event": "auth.login.success",
  "user_id": "uuid",
  "provider": "google",
  "source_ip": "10.0.0.42",
  "user_agent": "Mozilla/5.0...",
  "details": {
    "email": "alice@company.com"
  }
}

10.3 Retention

datapipelines.audit.retention-days (Configuration §3.12: default 365, bounds 30–3650, refused at startup outside them) is enforced by AuditLogRetention, the retention sweep's last step — hourly, under no principal, reachable from no route or tool (ArchitectureGuardTest's B5 list names it; §8.6's inventory row is the sweep). #310.

What is deleted. Every row whose timestamp is older than the database's NOW() minus the retention, the cutoff read ONCE per tick from the database's clock — the clock timestamp was written with; a replica whose JVM clock runs fast deletes nothing early. One cutoff for every event. §10.1 draws no line between security events (auth.*, workspace.*, the promotion and datasource events) and the per-call rows (mcp.tool.called, endpoint.served), so the job draws none either and carries no event list: a deployment that must keep its security trail longer raises the retention for the whole log, and the 30-day floor — not an exemption list — is what protects the trail from a misconfiguration. Rows go in bounded batches (at most 5,000 a statement, each its own short transaction; at most 50 statements or 2 seconds a tick), oldest first through idx_audit_timestamp; a tick that stops with rows left WARNs and the next continues (Metadata DB §8.2, Observability §7).

What is never deleted. A row younger than the cutoff, and nothing outside audit_log: keys and identities are §11C's, executions and their events their own retention's. The job writes no audit row of its own — its record is its log line and its meter (an audit row per tick would be a row a later tick deletes).

The read-backs — what a cutoff can and cannot change. Four readers decide something from audit rows, and every one asks whether a row EXISTS (EXISTS, max(timestamp), DISTINCT), so a deleted row can only turn a yes into a no: retention can refuse what was allowed, never allow what was refused.

• McpCallAudit.calledByKey — executions_cancel's same-credential rule. It gates only a RUNNING execution, and an execution runs at most datapipelines.executor.execution-timeout-seconds (default ten minutes) before it ends or the crash sweep aborts it: nothing it reads is near a 30-day cutoff.
• EndpointServeAudit.servedByKey — §7.7's endpoint-key visibility arm. It can answer yes only for a run served before V34 (#215), whose executed_by is the key's creator; a run served since carries the key's own identity and is visible without it. An endpoint key loses sight of a pre-V34 run once that run's serve row ages out.
• McpToolLearnings.columnsRead — check A (pipeline.validation.table_not_learned). A key's learning of a table lasts as long as its datasources_get_columns row: past the retention the key reads the columns again (the refusal names the one call that clears it).
• McpToolLearnings.lastRenderAt — check B (pipeline.execution.template_unrendered). A render older than the cutoff no longer counts, so a draft whose last edit and last render both predate it is rendered again before it runs.

And the keys purge. An audit row naming a revoked key's identity (audit_log.user_id, a foreign key) is one of the references that keeps the key and its identity (§11C); once the last such row ages out, the next tick's purge may delete the pair. audit_log.key_id is deliberately not a foreign key (Metadata DB §4.3), so a surviving row may name a key the purge has removed — the trail outliving its key is the design.

11. Configuration

OIDC providers are configured as a generic list. The deployment chooses which provider(s) to enable — any OIDC-compliant provider works.

11.1 OIDC provider configuration

Providers are defined in application.yml (structural config) with secrets referenced from env vars:

datapipelines:
  auth:
    oidc:
      providers:
        - name: google               # registration ID
          client-id: ${GOOGLE_CLIENT_ID}
          client-secret: ${GOOGLE_CLIENT_SECRET}
          issuer-uri: https://accounts.google.com
          display-name: "Sign in with Google"
          # picture-hosts: lh3.googleusercontent.com   # #197 — see below; empty = no avatar fetch
          # trust-email-without-verified-claim: true   # default false (§4.2/#187) — only for
          #                                            # an IdP that never emits the claim

        # GitHub — OAuth 2.0 WITHOUT OpenID Connect (§5.1, #655): the endpoints are named,
        # nothing is discovered; the address is the verified PRIMARY row of emails-uri.
        - name: github
          protocol: oauth2
          client-id: ${GITHUB_CLIENT_ID:}
          client-secret: ${GITHUB_CLIENT_SECRET:}
          authorization-uri: https://github.com/login/oauth/authorize
          token-uri: https://github.com/login/oauth/access_token
          user-info-uri: https://api.github.com/user
          user-name-attribute: id
          scopes: [read:user, user:email]
          emails-uri: https://api.github.com/user/emails
          display-name: "Sign in with GitHub"
          picture-hosts: avatars.githubusercontent.com

        # Microsoft (Entra ID) — SINGLE-TENANT only in v1: the issuer-uri MUST name
        # your tenant. Multi-tenant `/common` is NOT supported: its discovery metadata
        # carries the `{tenantid}` issuer template, which the OIDC discovery client
        # (Nimbus, via Spring's ClientRegistrations.fromIssuerLocation) refuses, so a
        # `/common` issuer fails startup — no request flow can ever succeed behind it.
        # - name: microsoft
        #   client-id: ${MICROSOFT_CLIENT_ID}
        #   client-secret: ${MICROSOFT_CLIENT_SECRET}
        #   issuer-uri: https://login.microsoftonline.com/{tenant-id}/v2.0
        #   display-name: "Sign in with Microsoft"

        # Add any OIDC provider the company uses:
        # - name: okta
        #   client-id: ${OKTA_CLIENT_ID}
        #   client-secret: ${OKTA_CLIENT_SECRET}
        #   issuer-uri: https://company.okta.com
        #   display-name: "Sign in with Okta"
        #
        # - name: keycloak
        #   client-id: ${KEYCLOAK_CLIENT_ID}
        #   client-secret: ${KEYCLOAK_CLIENT_SECRET}
        #   issuer-uri: https://sso.company.com/realms/main
        #   display-name: "Company SSO"

    jwt:
      secret: ${DATAPIPELINES_JWT_SECRET}
      ttl-hours: 8
      algorithm: HS256

    allowlist:
      domains: ${DATAPIPELINES_AUTH_ALLOWLIST_DOMAINS:}    # comma-separated, empty = open

    api-keys:
      cache-ttl-seconds: 60

• datapipelines.auth.oidc.provider-read-timeout-seconds — shared by all providers, default 10; 1–2147483 seconds for connect and read timeouts on token, OAuth2 user-info, emails, OIDC user-info calls and the ID-token decoder's JWKS fetch (§5.5, #686). Startup discovery keeps Spring's separate 30 s bound.

Per provider, three values are required:

• client-id — from the OIDC provider's app registration.
• client-secret — from the provider's app registration.
• issuer-uri — the provider's OIDC issuer URL. Triggers auto-discovery of all endpoints. (oidc entries only; refused on an oauth2 entry.)

The protocol and the oauth2 keys (#655, §5.1):

• protocol — optional, oidc (default) or oauth2; anything else refuses startup.
• authorization-uri, token-uri, user-info-uri — required for oauth2, empty by default; https:// (plain http:// only for localhost / 127.0.0.1).
• user-name-attribute — required for oauth2, empty by default: the user-info attribute that is the stable subject.
• scopes — required for oauth2, empty list by default; never openid.
• emails-uri — optional, unset by default; when set, the verified primary row is the only source of the address and the trust knob is not consulted (§5.5).

Two further values:

• name — required. Registration ID used in URLs (/oauth2/authorization/{name}) and stored in users.provider. Lowercase [a-z0-9-]+. (The §5.2 bean uses it directly; there is no derivation fallback.)
• display-name — optional. Text shown on the login button; defaults to name.

One further value (#197):

• picture-hosts — optional, comma-separated bare hostnames, default empty. The allowlist the avatar proxy (GET /avatar, §7.6 profile.read) may fetch the stored users.profile_picture_url from, so the CSP's img-src can stay 'self' data: and the browser never loads an image from an identity provider's host. The host is NOT derivable from issuer-uri (Google issues from accounts.google.com, serves pictures from lh3.googleusercontent.com; Entra's pictures live on Microsoft Graph; a self-hosted Keycloak's sit wherever its operator mapped them), so the operator names the hosts the deployment trusts. Empty (the default) = the proxy fetches nothing and every avatar falls back to initials — exactly the rendering a login without a picture claim already gets. A non-hostname entry (scheme, port, path, userinfo or wildcard) refuses startup. Only providers with a non-blank client-id contribute; a dormant entry's hosts are validated for shape but never allowlisted (#651). The fetch itself is fenced: the caller's OWN row only, http/https, no userinfo component, redirects never followed, a 1 MiB cap on the body, and a small private TTL cache. Three rules narrow it further (#246). A stored picture URL that names a port — any explicit port, the scheme's default included — is refused before any connection is made: the allowlist names hosts, never ports, so a port would steer the fetch to any service on a trusted host. Only raster images are served — image/png, image/jpeg, image/gif and image/webp, the type passed through as the provider sent it — and anything else, SVG included (a document format that can carry script), is refused. The whole fetch — connect, headers and body — completes within 5 s or is abandoned and its connection closed, so a provider that dribbles or stalls its body holds a request thread no longer than that and the avatar falls back to initials. A refused or failed fetch is itself remembered (#254): it enters the same bounded TTL cache as a negative entry, so a broken picture host costs ONE provider fetch per user per TTL instead of one per page view, the 404 answers with Cache-Control: private, max-age=<ttl seconds> so the browser stops asking while the refusal stands, and a later successful fetch replaces the negative entry.

11.2 Common provider issuer URIs (reference)

11.3 Required environment variables

The env vars depend on which providers the deployment configures. The structural config (which providers, issuer URIs) is in application.yml; secrets are in env vars:

For example, a deployment using Google + Okta would set:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
OKTA_CLIENT_ID=...
OKTA_CLIENT_SECRET=...
DATAPIPELINES_JWT_SECRET=...

11.4 API key validation cache

Validated API keys, user liveness and memberships are cached in-memory per instance for datapipelines.auth.api-keys.cache-ttl-seconds (default 60). Revocation, deactivation and a role change invalidate the local cache immediately and take effect elsewhere within the TTL — 60 s by default (#215 B5, record amendment A9: this is the freshness contract; no eviction bus, no Redis stamp).

Running executions and open streams (security-assurance record P4, owner ruling 2026-09-24, #230). The bound above governs every NEW request. An execution that is already running when its caller's authority is revoked keeps that authority to completion, under the executor's own drain and cancel rules; revocation never cancels it. An open SSE stream — the live execute stream, the idempotent-retry follow and the replay — re-judges its subscriber before EVERY write (event or heartbeat), with the same predicate a new request would run: liveness through the cache above, the live is_admin snapshot, the workspace resolution then execution.read and the execution's own visibility. The workspace re-judged is the one the stream OPENED in (#263): the filter stamps only the RESOLVED context — a DP-Workspace header switch included — so the re-judgement re-resolves that name, not the JWT claim, and a stream opened under a header switch keeps reading while that workspace's membership holds; its revocation still cuts, because the resolution re-checks the membership through the same cache. The token's expiry is judged too (#263): the subscriber carries the validated token's exp (read at the principal's construction from the claims the credential filter already validated), and a write at or past it ends the stream at that write — the same cut a fresh request meets at the credential filter. The re-check costs nothing within the TTL and sees a mutation on the instance that performed it at once (the cache evictions), so every cut lands at the stream's next write: the stream ends there, carrying a final revoked SSE comment — the same static string for a revocation and an expiry — and never the event, while the execution itself runs to completion — a revoked or expired READER never cancels the run it was watching. The duration timer records the credential fact (close_reason, Observability §4.1): revoked for a standing revocation, expired for a token past its exp (#263).

11.5 Other auth configuration keys

All auth config keys (allowlist domains, JWT TTL, cache TTL, login rate limit) are defined in Configuration §3.4 — the single config authority. This spec does not restate names or defaults.

The login limiter's window is per INSTANCE (096 §F, review finding F8). It is an in-memory fixed one-minute window per client address, held in each replica's own heap — so N replicas behind a load balancer give a client that lands on all of them an effective budget of N × login-per-minute. Deliberate: this is a brute-force damper, not a distributed quota, and a shared store on the login path costs more than it buys.

It also fails OPEN at its ceiling: the table is bounded at 10,000 tracked clients, and once it is full (after sweeping rolled-over windows) a new client is admitted UNMETERED rather than the map being grown, so a spoofed-source-IP flood can never exhaust the heap. That is the owner's posture and it is unchanged; what 096 added is that each such admission increments datapipelines.auth.login_rate_limit.saturated (Observability §4.1), so saturation is a rate to alert on rather than a WARN line lost inside the flood that caused it. The per-user API/MCP limiter (Configuration §3.7) is a different budget with a different key and fails CLOSED — the two are not interchangeable.

11A. Roles

Permission lives in the workspace membership, not on the user (RBAC design D-R1, ratified 2026-09-10; roles design D1, ratified 2026-09-20). A person is a viewer in one workspace and an author in another; there is no global "author" any more. The one global authority left is users.is_admin, which means super admin — the instance.

A membership row (workspace_members, metadata-db §4.12) carries exactly one role — role, one of viewer, author, promoter, workspace_admin (V29; WorkspaceRole). V23 had split the role into three additive booleans so that "an author who also releases" could be one row; the 2026-09-20 rulings took release away from the promoter and made it an ops role that authors nothing, so the combination the booleans existed for no longer exists and the row is one value again. The migration's precedence for old rows: admin → workspace_admin, else promoter → promoter, else author → author, else viewer. An invitation (§4.6) carries the same one role (D20).

Vocabulary (D21). A role is what a member holds. A permission is an action a role may perform — a ROW of the §7.6 matrix (Permission in code: the 65 <functionality>.<permission> catalog rows, pipeline.read …, each held by the roles its §7.6 row admits). "The author role has the permission to release" is a sentence about a row; a permission is never a free string, and nothing in the product grants or stores one.

The five roles, as the record's §2 ratifies them (the row-by-row table is §7.6; this is the shape):

Reads are cumulative — viewer ⊂ author ⊂ workspace admin ⊂ super admin — and the promoter is NOT on that chain: it reads datasources as a viewer does, reads pipelines, templates and endpoints through the lens (§11A.1), reads no executions, and adds the promote verb.

Two rows changed hands on 2026-09-20 and are worth naming: release is the author's (it was the promoter's — "the author releases, the promoter promotes", D8), and the workspaces page is the workspace admin's (D13) while the switcher in the chrome stays every member's. Executions became own-or-admin on every surface (D11): a member's list is their own runs, a workspace admin's is the workspace's, a promoter's does not exist; an endpoint-key run is nobody's own and lists for admins only (executed_by_key_kind, metadata-db §4.6).

11A.1 The 404 rule

A workspace you cannot reach does not exist. Non-member, unknown name, and deactivated are ONE answer — 404 workspace.not_found, the same body a genuinely missing row produces — on every surface: REST, MCP, UI pages and htmx partials. Never 403 for a foreign id. The same rule covers every entity inside a workspace: an id or name from another workspace is not-found, not forbidden, because a 403 would turn a flat namespace into an enumeration oracle one request at a time.

The rule is mechanical, not a convention: every repository read that a caller-supplied id or name can reach carries the workspace predicate IN ITS SQL, and WorkspaceIsolationSweepTest walks every REST route and every MCP tool with a foreign workspace's identifiers and asserts the not-found answer on every one.

The lens clause (178, roles design §3.1). For a principal whose role in the active workspace is promoter (and not a super admin), the same rule covers every pipeline and template the promotion rule does not list: an object is VISIBLE iff it has a current RELEASED version and that version is newer than the promotion target's inventory entry for the same name — Versioning §10.2's rule, the target's absence counting as version 0, the same content hash counting as "nothing to push" — and an endpoint is visible iff its pipeline is. Everything else — a draft, an already-promoted object, one the target serves at a higher version — is ABSENT for that principal: lists, levels, counts, search, the rail badges, the resource catalogue and used_by leave it out, and a get by id or name answers exactly the not-found an id from another workspace gets. A visible object's pending DRAFT is invisible too ("it should hide draft"): the working version a promoter reads is the current RELEASE, the draft pointer and the list badge are absent, DRAFT rows leave the version list, and an explicit DRAFT version number is not-found. The rule covers VERSION CONTENT, not only names (178b): the node-SQL partial renders the release's node with the pinned template read through the lens (a hidden or DRAFT template version is "template not found"), the checks reads refuse a DRAFT version exactly as an absent one (PipelineService.findExecutable under the lens), and used_by / the used-by pane list RELEASED pins of RELEASED template versions only — a draft's number or status never travels. The edge of the rule: a bundle is the artifact's pins (owner ruling 2026-10-02, #344). What an artifact PINS is part of the artifact the caller may already see: an export bundle (the pipeline, parameter-set, visualization and dashboard export routes) and a promotion batch carry the templates the artifact pins — and a dashboard's pinned visualizations with their templates — at the exact pinned versions, read WITHOUT the lens. A pinned template the lens hides rides with the artifact: it is never dropped and never a reason to refuse, and only Versioning §10.4's skip rule (already on the target at the same version and hash) leaves one out of a batch. The lens governs the ROOT — a hidden or draft root exports as an absent one, a hidden promotion root refuses — and every direct template read. PromoterLensSweepTest exports a visible pipeline that pins a hidden template and reads that template directly in one case (the bundle carries it; the direct read is the absent 404), and each family's transfer test is red if its bundle applies the lens. The rule is applied ONCE per request (PromotableView, the same computation the promotion page lists from) and passed as a value into every read (PipelineService, TemplateService, EndpointPublishService) — never a thread-local, because an MCP tool runs where no security context exists. The higher environment is read through a per-workspace cache (inventory-cache-ttl-seconds, Configuration §3.19); when it cannot be read the lens FAILS CLOSED — the promoter sees nothing, the list screens say why in the promotion page's words, a read is never a 502 — and pipeline.promotion.lens_unavailable is logged once per window. Both credential kinds are lensed alike: a promoter's API key is a promoter. PromoterLensSweepTest walks every promoter-reachable GET route and read tool with a hidden and an absent identifier and demands identical answers, exact lists, a leak-free body, a viewer control that never touches the target, and the fail-closed walk.

workspace.membership_required (403) survives in exactly one place: a principal with ZERO memberships, which addressed no workspace at all and so has no name to protect. Two permissions are judged WITHOUT a workspace context for a session: workspace.read (the page) and workspace.switch (the REST list-own, §17.1) — "which workspaces do I belong to" is meaningful when the answer is none, and it is how a zero-membership person reaches the no-workspace page (UI §4.13) instead of a JSON 404. A key never gets that exception: a key with no context is a key whose workspace is gone, and it stays the 404.

Dashboard delegated runtime reads (#343). dashboard.execute authorizes the delegated evaluation of a dashboard's pinned parameter set under D50, even when the caller does not hold parameter_set.evaluate. The runtime returns the evaluator's existing bounded response unchanged, including its selector diagnostics; this is not a direct parameter-set read grant. Refresh source frames include execution links only when the caller's current principal also holds execution.read.

A second null-context exception stands beside it (#113): a super admin session keeps the INSTANCE verbs — the operations whose permission is super_admin (create / deactivate / reactivate / delete a workspace, user administration, instance datasources and their grants) — when NO workspace is reachable at all. Those operations are instance-level by construction: none of them reads or writes a workspace's content, and refusing them stranded the one principal who could repair an empty deployment (deactivate the last active workspace, and even the reactivate verb answered workspace.not_found). The evidence is the user row's is_admin, re-read per request through the auth cache — not a context the request does not have. Every workspace-scoped operation stays the 404 for that principal, and a key never gets this exception either: no key is ever a super admin (B1, §7.5).

11A.2 Super admins

A super admin is an implicit member of every workspace (D-R8) and resolves any workspace through the SAME path everyone else does — no bypass branch, so there is no second code path to keep correct. Every action they take in a workspace where they hold no explicit membership is audited as auth.super_admin_acting with acting_via=super_admin, reads included (§10.1 says why).

A deactivated workspace is not selectable by a super admin either: §11A.3's first effect has no exception, and a super admin who needs to act inside one reactivates it first — an audited, reversible step.

11A.3 Deactivation

Deactivate, never delete (D-R10, D15). Deactivation — of a USER (users.is_active, §4.2) or of a WORKSPACE (workspaces.deactivated_at) — purges nothing and revokes nothing; it is reversible, and reactivation restores every credential. What it does is make the principal or the workspace served nothing, through ONE predicate.

The predicate. PrincipalLiveness answers "user active ∧ (pinned workspace active, when the credential pins one)", both reads through the §11.4 liveness cache (so a valid request costs zero extra queries, and a deactivation takes effect on the instance that performed it at once and everywhere else within one TTL, ~60 s by default). It is judged where each credential BECOMES a principal — the earliest point a refusal can happen, and the one every surface passes through because the security chain is global, so no boundary downstream restates it and no new surface can forget it:

The USER case has one code on every surface but the promotion peer. The WORKSPACE case keeps the older 404 rule (§11A.1): a deactivated workspace is indistinguishable from one that does not exist — auth.key_workspace_inactive stays distinct only because a key's holder is a member by construction and already knows the pin.

A deactivated workspace's five effects, all consequences of readers consulting Workspace.isActive (or its cached form, the predicate):

1. it cannot be selected — the switcher hides it, and DP-Workspace naming it answers 404 like a non-membership;
2. its published endpoints are unknown paths — to every caller, not only to keys pinned there;
3. API keys pinned to it are refused with auth.key_workspace_inactive (404), server keys with the promotion peer's one answer;
4. WorkspaceLiveness answers false for it — the question a scheduler will ask (no consumer exists yet; the interface is the hook);
5. a super admin's listing shows it greyed with the date.

To a MEMBER a deactivated workspace is indistinguishable from one that never existed, so deactivation is not a signal anybody can read. Reactivation is a super-admin verb and is audited. DeactivationSweepTest proves the whole table on the live server: every route and every tool, for a deactivated session and for keys with a deactivated identity, pin or — mcp keys only (A20) — deactivated creator, plus the differential (deactivated vs unknown workspace: same body on every route) and the promotion peer's one body.

There is deliberately NO last-active-workspace guard: decommissioning the final workspace is a legitimate operator act, and it is recoverable — with zero active workspaces the super admin's session resolves no workspace at all, and §11A.1's second null-context exception (#113) keeps the instance verbs, reactivation included, available to exactly that principal.

11A.4 Keys

Keys v2 (#233, A13–A19; the record §3 as amended): a key is a robot member of one workspace — kind, workspace, identity, role, created by. The mcp key carries the member role CHOSEN AT CREATION under the subset rule and acts as its own identity (§4.7, §7.5) — nothing is derived from a membership any more, so a member's role change does not affect their existing keys at all (C2 retired with the derivation). endpoint (api_caller) and server (promotion_receiver) keys are unchanged in shape (PK2). No key is ever a super admin (B1). On every request, inside the validation-cache TTL (60 s by default): the key is live, its identity is active, and its pinned workspace is active.

Lifecycle (A15/A17): nothing is minted at sign-in; creation is the Keys page (or the REST twin) alone; revocation is the end state — the application never hard-deletes a key or an identity. The retention sweep's purge (§11C) deletes a revoked, unbound key and its deactivated identity only once no FK column references them (B5); removing a member revokes every key they created in that workspace (B6).

11C. The keys purge (keys v2 A17/B5)

Revocation is the end state; the purge is the only delete. The application never hard-deletes a key or an identity. As a step of the retention sweep (the hourly job that also retains execution events and — its last step since #310 — the audit log, RetentionSchedulingConfiguration), KeyRetentionPurge deletes:

• a REVOKED key that no endpoint_key_bindings row names, and whose identity nothing references — the two are one unit: an execution's executed_by, an audit row's user_id, a membership, an invitation, or a surviving key row keeps the pair alive (B5's falsification: a revoked key with one live execution STAYS; one with none goes);
• then the deactivated service identities that nothing references at all.

An audit row keeps its identity only while it lives: the audit-log retention (§10.3) deletes rows past datapipelines.audit.retention-days, after which the next tick's purge may take a revoked key whose only references were those rows.

The "nothing references" predicate is DERIVED from the live schema (information_schema, every FK referencing users(id)), so a migration that adds a new FK automatically blocks the purge — the purge never disables a constraint and never guesses. A test enumerates the FKs independently and asserts the purge respects exactly that list; KeysV2MigrationTest and the retention tests prove both directions.

12. Implementation Notes

12.1 Where this lives

auth Gradle module:

• co.datapipelines.auth.User data class
• co.datapipelines.auth.ApiKey data class
• co.datapipelines.auth.Permission, RolePermissions, KeyRole, UserKind — the catalog, the one role table, the key roles, what a users row is
• co.datapipelines.auth.AuthenticatedPrincipal data class
• co.datapipelines.auth.JwtService — issue + validate internal JWTs
• co.datapipelines.auth.ApiKeyService — issue + validate + revoke API keys
• co.datapipelines.auth.UserService — find-or-create by OIDC identity
• co.datapipelines.auth.OidcSuccessHandler — OIDC login callback
• co.datapipelines.auth.JwtAuthenticationFilter — cookie → JWT → principal
• co.datapipelines.auth.ApiKeyFilter — header → key → principal
• co.datapipelines.auth.ScopeInterceptor — @RequiredScope enforcement
• co.datapipelines.auth.AuditLogger
• co.datapipelines.auth.SecurityConfig — Spring Security wiring

12.2 Dependencies

• Spring Security (OAuth2 client, CSRF, filter chain).
• Spring Security OAuth2Jose (JWT validation for OIDC ID tokens).
• de.mkammerer:argon2-jvm — API key hashing.
• io.jsonwebtoken:jjwt — internal JWT issue/validate.

12.3 Persistence (JDBC)

All auth tables accessed via JdbcTemplate + RowMapper. No JPA. See Metadata DB spec for table definitions.

13. Security Checklist

• [ ] OIDC client secrets stored in env vars or secret manager, not in source.
• [ ] DATAPIPELINES_JWT_SECRET is high-entropy (≥ 32 bytes random).
• [ ] Email domain allowlist configured for internal-only deployments.
• [ ] API keys hashed with Argon2id, never stored plaintext.
• [ ] Session cookies HttpOnly, Secure, SameSite=Lax (§5.5 — Strict is unusable with an IdP redirect chain; CSRF, not SameSite, is the control).
• [ ] CSRF protection on all state-changing UI endpoints.
• [ ] No /actuator/* path reachable without auth on the application port; /actuator/prometheus served only on the separate management port (Observability §4.2). Root /health, /ready, /info are the only public probes.
• [ ] All auth events audited.
• [ ] All traffic over TLS.
• [ ] OIDC redirect URI locked to the deployment's exact domain (not localhost in production).

14. What Changed from v1.0

Postscript (v2.10): optional local accounts returned in §5A — narrower than v1.0's: admin-created only (no self-registration), Argon2id via the API-key SecretHasher, per-account lockout, forced rotation of seeded/reset credentials, off by default.

15. Open Questions / Future

• Additional OIDC providers (Okta, Auth0) — easy to add; just another registration with an issuer-uri. GitHub is OAuth 2.0, not OIDC — shipped as a protocol: oauth2 entry (#655, §5.1).
• SAML — for enterprises that require SAML instead of OIDC. Spring Security SAML extension.
• Group/role sync from provider — map OIDC groups to internal roles automatically.
• Per-datasource ACLs — fine-grained access beyond roles.
• Service accounts — non-human principals for CI/CD.
• MFA — if provider enforces it (Google/Microsoft MFA is provider-side, transparent to us).

Appendix A: Change Log