--- id: CAP-PFM-SEC-011 title: Review security changes and refused attempts feature: FEAT-PFM-SEC-03 product_area: platform module: security revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - 'services-platform:docs/security/security-administration.md#5. Audit' purpose: Authorized reviewers inspect security decisions and recorded refusals to understand how access changed. outcomes: - Reviewers trace recorded access changes to their actor and request. - Handled refusals remain visible after the attempted mutation rolls back. - Customer history is searchable without exposing other customers’ events. concepts: - CON-PFM-SEC-003 actors: - ACT-PFM-001 - ACT-PFM-006 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: platform.security-access.explain where_checked: api scope: tenant rules: - id: BR-CAP-PFM-SEC-011-01 proved_by: [ATS-PFM-SEC-011-01, TST-PFM-SEC-051, TST-PFM-SEC-141] statement: >- The product should record security administration changes with actor and sign-in context, customer and applicable workspace, entity and version, action, widening classification, affected keys and count, before/after values, request and outcome; successful audited mutations write their event with the change. kind: invariant enforced_at: - service - database must_prove: true provenance: documented source: 'services-platform:docs/security/security-administration.md#5. Audit' origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - id: BR-CAP-PFM-SEC-011-02 proved_by: [ATS-PFM-SEC-011-02, ATS-PFM-SEC-011-10, ATS-PFM-SEC-012-17, TST-PFM-SEC-051, TST-PFM-SEC-121, TST-PFM-SEC-141] statement: >- An audited administration refusal records its machine code after the failed transaction unwinds so the event survives rollback; this does not cover requests rejected before those administration paths. kind: invariant enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/security/services/audit/refused-attempts.ts:auditedAttempt' origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - id: BR-CAP-PFM-SEC-011-03 proved_by: [ATS-PFM-SEC-011-03, ATS-PFM-SEC-011-07, TST-PFM-SEC-083] statement: 'Invitation tokens, their hashes and passwords are excluded from security audit records.' kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/lifecycle/invitation/invitation-arc.integration.spec.js#carries neither the raw token nor its hash anywhere in what it recorded origin: 'services-platform:docs/security/security-administration.md#5. Audit' - id: BR-CAP-PFM-SEC-011-04 proved_by: [ATS-PFM-SEC-011-04, ATS-PFM-SEC-011-09, TST-PFM-SEC-142] statement: >- Customer history orders events newest first, supports entity-kind and identity filters and cursor continuation without repeating rows, and excludes events from other customers. kind: policy enforced_at: - api - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/services/persistence/audit-events.queries.integration.spec.js#leaves out another customer's events, whoever wrote them origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - id: BR-CAP-PFM-SEC-011-05 proved_by: [ATS-PFM-SEC-011-05, TST-PFM-SEC-051] statement: >- Security-history reads require access-explanation permission; user or role read permission alone is insufficient. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-platform:modules/security/tests/e2e/console-users.e2e.spec.js#refuses the reader, who may not read the history either origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - id: BR-CAP-PFM-SEC-011-06 proved_by: [] statement: >- Role and policy update responses distinguish affected-person and assignment counts, while their audit event stores the affected-assignment count. kind: calculation enforced_at: - service must_prove: false provenance: observed source: >- services-platform:modules/security/services/definitions/manage-roles.ts:updateCustomRole; services-platform:modules/security/services/definitions/manage-policies.ts:updateCustomPolicy origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - id: BR-CAP-PFM-SEC-011-07 proved_by: [ATS-PFM-SEC-009-19, ATS-PFM-SEC-011-06, ATS-PFM-SEC-011-08, TST-PFM-SEC-069, TST-PFM-SEC-117] statement: User deletion records success or refusal even when successful deletion removes the membership row. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/e2e/users.e2e.spec.js#writes the deletion to the security trail, naming who deleted whom origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-11 Final acceptance) - id: BR-CAP-PFM-SEC-011-08 proved_by: [] statement: >- Database constraints limit audit entity kinds, outcomes and actor access kinds to the supported values. kind: validation enforced_at: - database must_prove: false provenance: test source: >- services-platform:modules/security/tests/integration/services/persistence/audit-events.integration.spec.js#refuses an entity type, an outcome and an actor access type the lists do not hold origin: none - id: BR-CAP-PFM-SEC-011-09 proved_by: [] statement: >- Workspace purge removes workspace-scoped security events, while the deletion request retains staff lifecycle actions; this remains a recorded default awaiting individual product review. kind: lifecycle enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/tenants/tenant-lifecycle-plan.md#13 (D6)' origin: none - id: BR-CAP-PFM-SEC-011-10 proved_by: [] statement: 'User, role and policy view pages expose their applicable audit trail through History.' kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:e2e/mock/security-view-edit.mock.spec.ts#the view reads the role: no fields, no bar, and History origin: >- services-platform:docs/security/security-administration.md#14 Acceptance checkpoints (2026-10-13/14 Final acceptance) scenarios: - id: SC-CAP-PFM-SEC-011-01 given: An administrator attempted delegation beyond their authority. when: An authorized reviewer opens the customer’s history. then: The handled grant refusal and its reason appear alongside successful administration events. provenance: test source: >- services-platform:modules/security/tests/e2e/console-users.e2e.spec.js#records the refused attempt too, so an access review sees what was tried edge_cases: [] constraints: [] depends_on: [] related: - CAP-PFM-SEC-008 - CAP-PFM-SEC-009 - CAP-PFM-SEC-010 - CAP-PFM-SEC-012 journeys: - JNY-PFM-SEC-003 - JNY-PFM-SEC-004 open_questions: [] evidence: - >- Pinned services-platform references for the structured rows: docs/security/security-administration.md; docs/tenants/tenant-lifecycle-plan.md; modules/security/services/audit/refused-attempts.ts; modules/security/services/definitions/manage-policies.ts; modules/security/services/definitions/manage-roles.ts; modules/security/tests/e2e/console-users.e2e.spec.js; modules/security/tests/e2e/users.e2e.spec.js; modules/security/tests/integration/lifecycle/invitation/invitation-arc.integration.spec.js; modules/security/tests/integration/services/persistence/audit-events.integration.spec.js; modules/security/tests/integration/services/persistence/audit-events.queries.integration.spec.js. - 'Pinned react-console references for the structured rows: e2e/mock/security-view-edit.mock.spec.ts.' controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-003, TC-PI-001, TC-PI-003, TC-PI-005, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-SEC-03-01, FAS-PFM-SEC-03-04, FAS-PFM-SEC-03-05] suites: [TST-PFM-SEC-051, TST-PFM-SEC-069, TST-PFM-SEC-083, TST-PFM-SEC-117, TST-PFM-SEC-121, TST-PFM-SEC-141, TST-PFM-SEC-142] --- # Review security changes and refused attempts ## Purpose Access reviewers need a clear account of who made a security decision and what happened. The customer trail connects recorded changes and refused attempts to the affected membership or definition. ## How It Works A reviewer opens customer history or the History view for a particular record. The event ordering makes recent decisions easy to locate. Entity filters narrow an investigation to the membership, role or policy under review. Cursor continuation supports longer reviews without repeating events. A recorded refusal explains an attempted change even when rollback preserved the original record. Machine reasons support consistent interpretation without copying arbitrary refusal messages into history. Definition impact counts help staff understand the reach of an edit. The reader must distinguish a tested audit path from a promise that every operation is fully audited; deletion recovery remains a known exception. Removal of workspace-scoped events also limits the trail after a workspace purge and still needs its product review. ## Relationships - Membership, assignment and definition administration supply the recorded decisions. - Staff-access management records customer-access decisions. - Workspace retirement retains its own lifecycle request history after purge.