--- id: CAP-PFM-SEC-016 title: Administer Rhythm staff memberships feature: FEAT-PFM-SEC-05 product_area: platform module: security revision: 1 status: draft product_intent: confirmed implementation_evidence: observed supersedes: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - 'services-platform:docs/hq/rhythm-hq-plan.md#H1' - 'services-platform:docs/hq/rhythm-hq-plan.md#H2' - 'services-platform:docs/hq/rhythm-hq-plan.md#H3' - >- services-platform:docs/hq/rhythm-hq-plan.md#Acceptance checkpoints (2026-10-12 Final acceptance: phase 1) - 'services-platform:docs/security/invitation-lifecycle.md#Founding staff (Andrew, 2026-10-12)' purpose: >- HQ provides administration of Rhythm’s own staff memberships and roles. Staff administration keeps its customer boundary and protects the remaining Rhythm Administrator. outcomes: - HQ provides a separate administration surface for Rhythm memberships. - Founding-staff reconciliation supports initial environment administration. - Administrator safety checks preserve a remaining active Rhythm Administrator. concepts: - CON-PFM-SEC-003 actors: - ACT-PFM-004 - ACT-PFM-005 - ACT-PFM-006 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: hq.staff.read where_checked: api scope: global - key: hq.staff.invite where_checked: api scope: global - key: hq.staff.disable where_checked: api scope: global - key: hq.staff.update where_checked: api scope: global - key: hq.roles.read where_checked: api scope: global - key: hq.roles.manage where_checked: api scope: global rules: - id: BR-CAP-PFM-SEC-016-01 proved_by: [ATS-PFM-SEC-016-01, ATS-PFM-SEC-018-09, TST-PFM-SEC-056, TST-PFM-SEC-058] statement: >- HQ staff operations require staff status and the permission declared by that operation. Customer Administrator authority is insufficient; staff status alone does not supply a missing key. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-platform:modules/security/tests/e2e/hq-staff-and-roles.e2e.spec.js#refuses an administrator of a customer, holding every key at that customer, as 403 origin: 'services-platform:docs/hq/rhythm-hq-plan.md#H1' - id: BR-CAP-PFM-SEC-016-02 proved_by: [] statement: >- The staff list returns only members of Rhythm’s customer, with case-insensitive name and email search, HQ-role filtering and last-authentication information. kind: policy enforced_at: - api - service must_prove: false provenance: test source: >- services-platform:modules/security/tests/e2e/hq-staff-and-roles.e2e.spec.js#never answers a console user of another customer, whose people are that customer's own origin: 'services-platform:docs/hq/rhythm-hq-plan.md#D7' - id: BR-CAP-PFM-SEC-016-03 proved_by: [ATS-PFM-SEC-016-02] statement: >- A staff invitation targets Rhythm’s customer and assigns one of the three built-in staff roles at platform scope. Other role choices are rejected by name; assigning Rhythm Administrator also requires role-management authority. kind: permission enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/security/services/invitations/invite-staff.ts:inviteStaff' origin: 'services-platform:docs/hq/rhythm-hq-plan.md#H3' - id: BR-CAP-PFM-SEC-016-04 proved_by: [ATS-PFM-SEC-016-03, TST-PFM-SEC-058, TST-PFM-SEC-119] statement: >- HQ can replace the outstanding invitation for a still-invited staff member. Accepted memberships cannot be reinvited, and a person outside Rhythm’s staff returns not found without a message being sent. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/services/invitations/resend-staff-invitation.integration.spec.js#is not found, so the route reports nothing about who exists origin: >- services-platform:docs/security/security-administration.md#15 (resending a staff invitation, 2026-10-12) - id: BR-CAP-PFM-SEC-016-05 proved_by: [ATS-PFM-SEC-016-04, ATS-PFM-SEC-016-09, ATS-PFM-SEC-017-20, TST-PFM-SEC-023] statement: >- Staff suspension withdraws outstanding invitations and attempts to disable pool sign-in after the membership change. Revocation ends the membership and its grants and invitations; pool failures must not be described as rollback of committed membership changes. kind: lifecycle enforced_at: - service must_prove: true provenance: observed source: 'services-platform:modules/security/aws/api/hq-staff.routes.ts:hqStaffRoutes' origin: 'services-platform:docs/hq/rhythm-hq-plan.md#H2' - id: BR-CAP-PFM-SEC-016-06 proved_by: [ATS-PFM-SEC-009-20, ATS-PFM-SEC-016-05, ATS-PFM-SEC-016-08, TST-PFM-SEC-117] statement: >- An operation that would remove the last active Rhythm Administrator must reject and roll back its change, whether it changes the role, suspends, revokes or deletes the membership. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/services/invitations/delete-user.integration.spec.js#refuses the delete as the staff guard does, naming its machine code origin: 'services-platform:docs/hq/rhythm-hq-plan.md#H3' - id: BR-CAP-PFM-SEC-016-07 proved_by: [ATS-PFM-SEC-016-06, TST-PFM-SEC-056, TST-PFM-SEC-094] statement: >- The shared catalog supplies Rhythm Administrator with HQ administration, Support Representative with HQ reading and deletion hold authority, and Software Engineer with HQ reading and custom-query-table authoring. The HQ and lifecycle plans differ on Support’s deletion authority. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/unit/services/catalog/reconcile-catalog.spec.ts#gives Support Representative the HQ reader and the deletion hold, at platform scope, and no customer app; services-platform:modules/security/tests/unit/services/catalog/reconcile-catalog.spec.ts#gives Software Engineer the same HQ reader, the deletion request to read, and the custom query tables to author origin: 'services-platform:docs/hq/rhythm-hq-plan.md#H2' - id: BR-CAP-PFM-SEC-016-08 proved_by: [ATS-PFM-SEC-016-07, ATS-PFM-SEC-016-10, TST-PFM-SEC-176] statement: >- Deployment reconciles a configured founding-staff list into active memberships and roles without invitation acceptance. Existing suspended or revoked founders remain unchanged, and removing a configured name does not remove its membership. Eligible founders can begin with Google sign-in. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/security/tests/integration/services/provisioning/ensure-founding-staff.integration.spec.js#leaves exactly one assignment: Rhythm Administrator at platform scope, active origin: 'services-platform:docs/security/invitation-lifecycle.md#Founding staff (Andrew, 2026-10-12)' - id: BR-CAP-PFM-SEC-016-09 proved_by: [] statement: >- HQ staff detail returns profile information, last authentication and customer-workspace access grants. A console membership belonging to another customer is answered as not found. kind: policy enforced_at: - api - service must_prove: false provenance: test source: >- services-platform:modules/security/tests/e2e/hq-staff-detail.e2e.spec.js#answers a console user of another customer 404, as an unknown id origin: 'services-platform:docs/hq/rhythm-hq-plan.md#K8' - id: BR-CAP-PFM-SEC-016-10 proved_by: [] statement: The accepted phase-one scope defers a requirement for staff multi-factor authentication. kind: policy enforced_at: - service must_prove: false provenance: documented source: 'services-platform:docs/hq/rhythm-hq-plan.md#D9' origin: 'services-platform:docs/hq/rhythm-hq-plan.md#K7' - id: BR-CAP-PFM-SEC-016-11 proved_by: [] statement: >- The staff-update and role-reading permission keys need an explicit product decision: attach them to operations or remove unused declarations. kind: policy enforced_at: - api must_prove: false provenance: unknown source: FND-PFM-SEC-005 origin: none scenarios: - id: SC-CAP-PFM-SEC-016-01 given: A support recruit needs access to HQ. when: An authorized administrator invites the person with the Support role. then: >- Their staff role supplies HQ reading rather than staff administration. Customer workspace entry requires separate staff-access authority. provenance: test source: >- react-console:e2e/mock/hq-ops.mock.spec.ts#the invite dialog takes a Rhythm address, a role, and offers to resend an invitation already sent edge_cases: [] constraints: [] depends_on: [] related: - CAP-PFM-SEC-009 - CAP-PFM-SEC-017 - CAP-PFM-SEC-013 journeys: [] open_questions: [] evidence: - >- Pinned services-platform references for the structured rows: docs/hq/rhythm-hq-plan.md; docs/security/invitation-lifecycle.md; docs/security/security-administration.md; modules/security/aws/api/hq-staff.routes.ts; modules/security/services/invitations/invite-staff.ts; modules/security/tests/e2e/hq-staff-and-roles.e2e.spec.js; modules/security/tests/e2e/hq-staff-detail.e2e.spec.js; modules/security/tests/integration/services/invitations/delete-user.integration.spec.js; modules/security/tests/integration/services/invitations/resend-staff-invitation.integration.spec.js; modules/security/tests/integration/services/provisioning/ensure-founding-staff.integration.spec.js; modules/security/tests/unit/services/catalog/reconcile-catalog.spec.ts. - 'Pinned react-console references for the structured rows: e2e/mock/hq-ops.mock.spec.ts.' controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-005, TC-MON-001, TC-MON-003, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-PFM-SEC-05-01, FAS-PFM-SEC-05-02, FAS-PFM-SEC-05-03, FAS-PFM-SEC-05-04, FAS-PFM-SEC-05-05] suites: [TST-PFM-SEC-023, TST-PFM-SEC-056, TST-PFM-SEC-058, TST-PFM-SEC-094, TST-PFM-SEC-117, TST-PFM-SEC-119, TST-PFM-SEC-176] --- # Administer Rhythm staff memberships ## Purpose HQ provides administration of Rhythm’s own staff memberships and roles. Staff administration keeps its customer boundary and protects the remaining Rhythm Administrator. ## How It Works An authorized administrator uses HQ Staff to find a colleague, inspect the profile and customer-access records, and manage membership. New colleagues receive an invitation with a staff role; accepted colleagues use ordinary sign-in and recovery. The administrator can suspend, reinstate or revoke access, with the shared membership service reporting any pool failure after its database work. Role choices are read from the stored catalog, which can be incomplete before reconciliation. The founding-staff list supports initial administration. The product should decide what to do with the unused staff-update and role-reading permissions. ## Relationships - Console membership administration supplies the shared lifecycle mechanics. - Staff workspace access governs entry into customer work. - Release reconciliation supplies built-in staff definitions.