feat(settings): activate Security authentication policy (Phase 3b)

api/openapi.yaml

@@ -3097,6 +3097,37 @@ paths:
           description: Revoked (idempotent)
         '403': {$ref: '#/components/responses/Forbidden'}
 
+  # Spec: api-auth-policy — workspace authentication policy.
+  /api/v1/auth-policy:
+    get:
+      operationId: getAuthPolicy
+      summary: View the workspace authentication policy
+      x-required-permission: system:auth_policy_read
+      responses:
+        '200':
+          description: Current policy
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/AuthPolicy'}
+        '403': {$ref: '#/components/responses/Forbidden'}
+    put:
+      operationId: putAuthPolicy
+      summary: Replace the workspace authentication policy
+      x-required-permission: system:auth_policy_write
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/AuthPolicyUpdateRequest'}
+      responses:
+        '200':
+          description: Policy updated
+          content:
+            application/json:
+              schema: {$ref: '#/components/schemas/AuthPolicy'}
+        '400': {$ref: '#/components/responses/BadRequest'}
+        '403': {$ref: '#/components/responses/Forbidden'}
+
 components:
   responses:
     BadRequest:
@@ -3142,6 +3173,12 @@ components:
         access_token:  {type: string}
         refresh_token: {type: string}
         user:          {$ref: '#/components/schemas/AuthMeResponse'}
+        mfa_enrollment_required:
+          type: boolean
+          description: >-
+            True when workspace policy requires MFA but the user has not
+            enrolled. The session is still issued (soft enforcement); the
+            client must force MFA enrollment before anything else.
 
     AuthRefreshRequest:
       type: object
@@ -3318,6 +3355,34 @@ components:
         token:     {type: string, description: The raw secret. Shown once.}
         api_token: {$ref: '#/components/schemas/ApiToken'}
 
+    AuthPolicy:
+      type: object
+      required: [require_mfa, session_idle_timeout_seconds, session_absolute_timeout_seconds, updated_at]
+      description: Workspace-wide authentication policy.
+      properties:
+        require_mfa:
+          type: boolean
+          description: When true, every user must have MFA enrolled (soft-enforced at login).
+        session_idle_timeout_seconds:
+          type: integer
+          description: Inactivity window. A session expires this many seconds after its last use.
+        session_absolute_timeout_seconds:
+          type: integer
+          description: Absolute lifetime cap regardless of activity, in seconds.
+        updated_at: {type: string, format: date-time}
+        updated_by: {type: string, format: uuid, nullable: true}
+
+    AuthPolicyUpdateRequest:
+      type: object
+      required: [require_mfa, session_idle_timeout_seconds, session_absolute_timeout_seconds]
+      description: >-
+        Replaces the whole policy. Bounds (enforced server-side): idle
+        300..86400 s, absolute 3600..2592000 s, absolute >= idle.
+      properties:
+        require_mfa: {type: boolean}
+        session_idle_timeout_seconds:     {type: integer, minimum: 300, maximum: 86400}
+        session_absolute_timeout_seconds: {type: integer, minimum: 3600, maximum: 2592000}
+
     UserCreateRequest:
       type: object
       required: [username, email, password]

audit/events.yaml

@@ -153,6 +153,10 @@ events:
     severity: warning
     description: API key invalidated
 
+  - code: auth.policy.updated
+    severity: warning
+    description: Workspace authentication policy changed (require-MFA, session timeouts)
+
   # =========================================================================
   # authz — RBAC and authorization
   # =========================================================================

auth/permissions.yaml

@@ -362,6 +362,15 @@ permissions:
     description: Modify runtime system configuration
     dangerous: true
 
+  - id: system:auth_policy_read
+    category: system
+    description: View the workspace authentication policy (require-MFA, session timeouts)
+
+  - id: system:auth_policy_write
+    category: system
+    description: Modify the workspace authentication policy (require-MFA, session timeouts)
+    dangerous: true
+
   # =========================================================================
   # role - role administration
   # =========================================================================
@@ -532,6 +541,8 @@ roles:
       - integration:*
       - audit:*
       - system:read
+      - system:auth_policy_read
+      - system:auth_policy_write
 
   - id: admin
     description: Full system administration

frontend/src/api/auth-bootstrap.ts

@@ -34,6 +34,8 @@ function permissionsForRole(role: string): string[] {
       'token:read',
       'token:write',
       'token:delete',
+      'system:auth_policy_read',
+      'system:auth_policy_write',
       'admin',
     ];
   }
@@ -78,6 +80,8 @@ export async function bootstrapAuth(): Promise<void> {
         'token:read',
         'token:write',
         'token:delete',
+        'system:auth_policy_read',
+        'system:auth_policy_write',
         'admin',
       ],
       mfaEnabled: false,

frontend/src/api/schema.d.ts

@@ -2022,6 +2022,24 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/auth-policy": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** View the workspace authentication policy */
+        get: operations["getAuthPolicy"];
+        /** Replace the workspace authentication policy */
+        put: operations["putAuthPolicy"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -2035,6 +2053,8 @@ export interface components {
             access_token: string;
             refresh_token: string;
             user: components["schemas"]["AuthMeResponse"];
+            /** @description True when workspace policy requires MFA but the user has not enrolled. The session is still issued (soft enforcement); the client must force MFA enrollment before anything else. */
+            mfa_enrollment_required?: boolean;
         };
         AuthRefreshRequest: {
             refresh_token: string;
@@ -2172,6 +2192,25 @@ export interface components {
             token: string;
             api_token: components["schemas"]["ApiToken"];
         };
+        /** @description Workspace-wide authentication policy. */
+        AuthPolicy: {
+            /** @description When true, every user must have MFA enrolled (soft-enforced at login). */
+            require_mfa: boolean;
+            /** @description Inactivity window. A session expires this many seconds after its last use. */
+            session_idle_timeout_seconds: number;
+            /** @description Absolute lifetime cap regardless of activity, in seconds. */
+            session_absolute_timeout_seconds: number;
+            /** Format: date-time */
+            updated_at: string;
+            /** Format: uuid */
+            updated_by?: string | null;
+        };
+        /** @description Replaces the whole policy. Bounds (enforced server-side): idle 300..86400 s, absolute 3600..2592000 s, absolute >= idle. */
+        AuthPolicyUpdateRequest: {
+            require_mfa: boolean;
+            session_idle_timeout_seconds: number;
+            session_absolute_timeout_seconds: number;
+        };
         UserCreateRequest: {
             username: string;
             email: string;
@@ -7638,4 +7677,51 @@ export interface operations {
             403: components["responses"]["Forbidden"];
         };
     };
+    getAuthPolicy: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Current policy */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AuthPolicy"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    putAuthPolicy: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AuthPolicyUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Policy updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AuthPolicy"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
 }

frontend/src/pages/LoginPage.tsx

@@ -100,11 +100,21 @@ export function LoginPage() {
       };
       if (mfaRequired && values.otp) body.otp = values.otp;
 
-      const { response, error } = await api.POST('/api/v1/auth/login', {
+      const {
+        data: loginData,
+        response,
+        error,
+      } = await api.POST('/api/v1/auth/login', {
         body,
       });
 
       if (response.ok) {
+        // Soft require-MFA enforcement: the session is issued, but workspace
+        // policy requires this user to enroll in MFA before doing anything
+        // else. Land them on the profile page where enrollment lives.
+        const enrollmentRequired = !!(
+          loginData as { mfa_enrollment_required?: boolean } | undefined
+        )?.mfa_enrollment_required;
         // IMPORTANT (C-02): we do NOT read access_token / refresh_token
         // from the response body. Session cookie is the credential.
         const { data: me } = await api.GET('/api/v1/auth/me');
@@ -138,13 +148,19 @@ export function LoginPage() {
                     'token:read',
                     'token:write',
                     'token:delete',
+                    'system:auth_policy_read',
+                    'system:auth_policy_write',
                     'admin',
                   ]
                 : ['host:read', 'scan:read'],
             mfaEnabled: !!meTyped.mfa_enabled,
           };
           setIdentity(nextIdentity);
         }
+        if (enrollmentRequired) {
+          navigate({ to: '/settings/profile' });
+          return;
+        }
         const dest = safeReturnTo(search.return_to);
         navigate({ to: dest });
         return;