P0: Prevent privileged signup and enforce organization membership

[tomqwu]

Current Priority Decision

Owner direction, 2026-09-13: complete Church/Basketball business workflows and day-to-day operations for every role first; billing and platform readiness later.

Execution lane: phase: business-flow. Current business milestone: #289.
This section overrides older priority, start conditions, broad dependency order and launch estimates below. Keep the detailed technical recommendations where compatible. Execute only the NOW slice; do not expand a mixed issue into its whole production scope. Record completed slice receipts in #289; keep this issue open while retained later work remains.

NOW

Complete safe browser org/admin bootstrap, invitations, qualification management and membership for BO-01/02/11/12. Keep admin/volunteer permission levels distinct from every Church/Basketball scheduling qualification. Normal UI must onboard all roles without API seeding.

LATER

No department-manager RBAC expansion or enterprise identity platform. Agree bootstrap compatibility before schema/API change.

Validation stays local. No CI checks, hosted reviewers or Ollama code review. Preserve tenant isolation, real member responses and atomic roster changes. A deferred feature is not permission to expose an unfixed vulnerability. No deployment, paid-provider activation or production sign-off is authorized by this reprioritization.

Before implementation, read #252 and #289; finish one role/work package with tests, local review and affected docs/assets. The earlier completion receipt below covers whole-issue closure, not a requirement to finish every deferred package before the business milestone.

---

Current Implementation Handoff

Prepared 2026-09-13 for a lower-cost builder at source 21a4a804aa57580451edded04736b1f51aef7e48.
No CI checks. All implementation validation and code review run locally.
Use the shared builder contract and this issue's work packages; no xhigh model or automatic model upgrade is required. This is a detailed recommendation, not a claim that a smaller model cannot make mistakes or that tests have passed.

Risk/review focus: High: identity bootstrap and privilege assignment.
Start condition: Start only the NOW work package defined above. Use its local business prerequisites, not the entire older platform-release dependency list.

Source of Truth and Current State

• api/routers/auth.py
• api/routers/organizations.py
• api/routers/invitations.py
• api/routers/people.py
• api/dependencies.py
• api/models.py
• web/auth.py
• web/routers/partials.py
• tests/api/test_auth_change_password.py
• tests/api/test_invitation_accept_jwt.py
• tests/api/test_bulk_people_import.py

check_admin_permission grants only exact admin; aliases are not currently proven escalation. Public signup still accepts an existing org_id and gives the first user admin based on a count. It must not become a tenant-join or empty-org takeover mechanism.

This handoff supersedes stale implementation statements in the background below. Preserve existing successful behavior and tests. Recheck the current branch before editing; the baseline is a source pointer, not permission to discard newer changes.

Dependencies and Ownership

• NOW-slice prerequisite receipts: P1: Repair local test entry points, coverage and isolation #281; only the needed safe/local package must pass, not every platform acceptance item in those tickets. Full-release dependency designs below remain later work.
• Coordinate, but do not wait for entire tickets to close merely to inspect/write isolated tests: P2: Complete organization lifecycle and PostgreSQL release acceptance #253, P0: Close tenant data exposure in scheduling APIs and exports #254, P1: Protect browser workflows; defer distributed abuse limits #261, P1: Complete pluggable church and basketball acceptance coverage #279, P1: Audit every web journey for usability and failure recovery #285, P2: Regenerate the mobile API client and validate native release #191.
• The final commands below require P1: Repair local test entry points, coverage and isolation #281's safe local environment or an equivalently verified isolated setup. A missing dependency blocks only the slice that needs it; document that state.
• Shared source/ORM/migration changes are serialized per the master roadmap. Do not start concurrent edits to the same ownership area.

Recommended Decisions

1. Recommended contract: create organization + first admin atomically through an explicit bootstrap operation; existing-organization membership requires a valid single-use invitation or an authenticated same-tenant admin action. Keep email uniqueness as currently modeled.
2. Do not accept public authorization-role claims. After bootstrap, invitation roles come from the stored invitation, not the redemption request. Admin/volunteer are permission roles; other approved strings are scheduling qualifications, not permissions.
3. Reject ambiguous reserved permission spellings rather than normalizing a malicious value into admin. Only authenticated admin role-management may grant exact admin.
4. Recommend migrating legacy two-step callers to bootstrap instead of treating a known org_id as a credential. If compatibility must retain two steps, design a hashed, expiring single-use bootstrap capability and race tests before coding that alternative.

Small Work Packages

Each item is one reviewable slice, not permission for one giant PR. Add the failing regression first; finish code, tests and affected docs for that slice together. Leave this issue open until all packages and original acceptance criteria are satisfied or explicitly revised by the owner.

• 255.1: Add tests for joining an existing org without invitation, racing first-admin signup and overriding invitation roles; preserve existing valid onboarding behavior as a compatibility fixture.
• 255.2: Record the approved bootstrap approach and affected web/API/mobile/CLI callers in the issue, then implement the smallest shared transaction boundary.
• 255.3: Apply the same role policy to invitations, people updates and bulk import; never let a UI-only validator be the sole control.
• 255.4: Migrate fixtures/callers intentionally, update OpenAPI and README role explanations, and run complete signup/invitation browser journeys.

Required Regression Cases

These are specifications for tests to add/retain, not claimed execution results. Each new negative case must assert unchanged unauthorized state and zero forbidden side effects.

• T255-01: Existing org + uninvited public signup -> denied, zero Person rows and no role change.
• T255-02: Two simultaneous bootstrap/redemption requests -> one organization/admin or one accepted invitation; loser receives a defined conflict, never a second privileged identity.
• T255-03: Invitation to tenant A redeemed with tenant B/body admin override -> stored tenant/roles win or request is rejected.
• T255-04: Valid first admin -> usable login; invited musician/coach -> volunteer plus qualification with no admin access.

Local Commands and Evidence

Existing targeted commands (paths checked against the audit source; run only after the stated safe preflight):

poetry run pytest tests/api/test_invitation_accept_jwt.py tests/api/test_bulk_people_import.py tests/api/test_multi_tenant.py -q
poetry run pytest tests/web/test_signup.py tests/web/test_invitation.py -q
poetry run pytest tests/e2e/test_auth_flows.py tests/e2e/test_onboarding_wizard.py -q

Also run the shared formatting/lint/touched-type/unit/full-suite and local review protocol from #252 for the final pushed revision. Add new targeted tests to these commands when implemented. Run API and browser tiers in separate processes. Native, PostgreSQL, image, provider and operator drills require their explicit environment; an unavailable tool/target is blocked/not run, never a pass.

Schema and Compatibility

Atomic bootstrap may reuse existing models. A two-step capability requires a new reviewed migration with hashed token, expiry and consumed state; it is a proposed change, not an existing table.

Stop Conditions

Owner approval is required for breaking public signup compatibility and the bootstrap choice. Do not guess organization membership or mint credentials from an org ID.

After two failed focused repair attempts without new diagnostic evidence, stop the affected package and post the exact failure, commands, suspected boundary and needed decision. Do not silently broaden scope, weaken tests or upgrade models. A fresh local reviewer checks: Review every path that writes Person.roles/org_id and every race around first-admin/invitation consumption.

Completion Receipt

• Work-package and regression IDs above map to changed files and actual results.
• Commands, versions, dates, pass/fail/skip/not-run counts, logs/screenshots and tested head/base SHAs are linked.
• A separate local review records findings and resolution; self-review is labeled if used and is not misrepresented as independent review.
• Affected docs/README/playbooks/screenshots and dependency/roadmap status are reconciled, not left as unnamed follow-ups.
• If implementation is authorized through PR/merge, GitHub reports mergeable and the shared local-evidence requirements are met; reviewer agents never merge.
• No hosted CI check, status attestation, Ollama reviewer, live provider action, deployment, real-data purge or store submission was introduced by implication.

Copyable Builder Prompt

First read this issue's Current Priority Decision and #289. Run only its NOW slice.
If this issue is deferred, report that state instead of starting the older package list.
Implement the next ready work package in tomqwu/SignUpFlow issue #255.
Read its Current Implementation Handoff and #252 Builder Handoff Contract first.
Inspect current source and preserve newer/unrelated changes. Start with the
package's failing regression, then complete code, local tests, local review and
affected docs/assets together. Do not skip acceptance or invent passing evidence.
No CI checks or Ollama code review. Do not deploy, activate providers, purge real
data or submit to stores. Stop and report unmet prerequisites or policy decisions.
Record the package/test IDs and exact reviewed/tested source SHAs before claiming done.

---

Earlier Audit and Acceptance Context

Current policy (2026-09-13)

No CI checks. Everything is validated locally. This includes code review,
formatting, lint, type checks, migrations, all test tiers, security scans,
artifact checks and mobile validation. Do not add hosted jobs, required CI
statuses, synthetic success checks or an Ollama reviewer. GitHub is for source,
PRs, issues and publication, not validation.

Record commands, environment, results, limitations and reviewed head/base SHAs.
Builders merge only with completed local evidence and GitHub mergeability;
reviewer agents never merge. Real staging/provider/device acceptance remains
required where applicable, driven by authorized local operator tools.
Historical evidence and older comments do not override this policy.

Parent roadmap: #252

Priority: P0, blocks core production pilot. Phase: A. Suggested owner: Backend/security. Original estimate (superseded; re-estimate remaining work): 3-5 engineering days.

Historical audit evidence (recheck against current source)

api/routers/auth.py:98 accepts any existing org_id and strips only the literal admin role for later signups. api/dependencies.py:15 treats super_admin as administrative. A disposable signup returned 201 with that role and passed the actual admin permission function. First-admin assignment uses a count followed by an insert. The repository policy permits only volunteer/admin authorization roles.

Baseline: GitHub main 214e3f3f17a582d5f9b2063be6872ea2b1d25714, audited 2026-09-09. Findings concern synthetic reproduction or source inspection, not a claim of live exploitation.

Implementation plan

1. Remove client-selected authorization privileges from public signup. Establish a server-controlled allowlist for admin/volunteer and distinguish scheduling skills/role names from authorization roles.
2. Make new organization plus first admin creation atomic. Require a valid invitation or explicit owner-approved join policy for existing organizations; validate org ownership in the invitation flow.
3. Remove the super_admin authorization bypass and handle existing out-of-policy data with a reviewed migration/remediation procedure, without silently deleting scheduling skills.
4. Apply the same role contract to invitations, person update, CSV import and web onboarding. Audit disabled-person/cancelled-org behavior in login, refresh, API and cookie sessions.

Acceptance criteria

• Anonymous signup cannot obtain any elevated role, including alternate spelling/case/unrecognized values.
• Joining an existing tenant requires its intended invitation/approval policy; creating an empty org cannot let a concurrent stranger claim its admin.
• PostgreSQL concurrent onboarding produces one intended owner and no orphan organization.
• Session/API authorization rejects inactive membership and respects the agreed cancellation behavior.
• Existing legitimate invitation, login, refresh and onboarding tests pass.

Dependencies

#253

Validation

Write failing tests/api escalation and two-tenant onboarding tests first. Add concurrent PostgreSQL signup tests and role round-trip tests for imports/invitations; run affected web flows and make test-all.

Whole-repository audit scope (2026-09-13)

Baseline: 21a4a804aa57580451edded04736b1f51aef7e48. This addendum assigns full-scope follow-through; it is not a new test pass or production sign-off. No CI checks; all review and validation runs locally.

Separate permission roles from scheduling qualifications throughout signup, invitations, people updates, bulk import, membership changes, web forms and generated clients. Cover case/alias/normalization, first-admin bootstrap races and joining an existing organization, not only the exact string admin. Coordinate usable custom roles with #285 and both domain rosters with #279; ensure no caller-supplied role/identity can grant tenant admin access. Public onboarding behavior must be explicit in #278/#284.

Keep evidence and disposition synchronized with master roadmap #252 and documentation ledger #277. Close only after the remaining acceptance criteria have linked local results; a planning/audit note is not completion.

[tomqwu]

Partial security fix in draft PR #272: the undocumented super_admin role no longer grants administrative privileges, including on billing routes. Negative real-JWT tests cover this bypass. Existing signup/membership and atomic owner-registration behavior is not otherwise changed; keep this issue open for the remaining acceptance criteria.

[tomqwu]

Partial implementation receipt (PR #292, merged as 34996c1c9222c9b70868c3a545f826d10d263e49):

• Normal browser invitations now keep account access (admin/volunteer) separate from scheduling qualifications.
• Reserved permission aliases cannot be supplied as qualifications.
• The admin qualification editor preserves access and scopes every member lookup by both org_id and person ID.
• Cross-tenant mutation and accidental privilege-escalation cases have executable tests.

Local evidence for pushed head cacff48095e86930bd40727bd9a32d99f735f2da: make test-all completed with 1,467 passed and 21 skipped, including Church/Basketball Playwright runs at 360px and 1440px. GitHub reported MERGEABLE/CLEAN before merge.

This issue remains open. Atomic organization bootstrap, invitation-only API membership, and applying the shared role policy to all API role mutation paths are still required.

[tomqwu]

Implementation receipt: PR #293 merged as 73b5a99.

Completed in this package:

• atomic organization + first-admin signup
• invitation-only membership after bootstrap
• one exact admin/volunteer access-role policy across invitations and people writes
• globally unique member email migration with conflict/race handling
• web, API, playbook, performance, and Flutter caller migration
• OpenAPI/generated-client/docs reconciliation

Local evidence on pushed head a0339ed:

• make test-all: 1,490 passed, 21 skipped
• make test-mobile: 65 passed
• Playwright: 33 passed, including Church/Basketball at 360px and 1440px
• Black, Ruff, OpenAPI contract, diff check, and secret scan passed

This issue remains open for its still-unmet acceptance evidence: real PostgreSQL concurrency and inactive/cancelled-member authentication behavior, coordinated with #253 and #260. No hosted tests, Ollama review, provider activation, deployment, or production database operation was performed.

[tomqwu]

Current BO-11 account/session slice merged in #306 (dbafb60008c69d4ba39580dff23bac4e203e957d). Normal browser flows now prove admin/member logout/login, password change, refreshed-session continuity, and copied stale-session rejection in both domains and widths. Broader BO-01/02/12 membership and bootstrap scope remains open and is next.

[tomqwu]

BO-12 source receipt: PR #307 merged as 35c4bc4124cdb3f014ad9304b117c3d0550b6ffb.

Implemented and verified:

• all production API access tokens and browser sessions carry org_id and reload only an active matching membership
• signup, login, password change, refresh, and invitation acceptance use tenant-bound access credentials
• Church and Basketball coexist in one live local server; each administrator sees only its own directory
• every declared Church and Basketball scheduling qualification runs as a volunteer at 360px and 1440px and cannot enter the admin surface, invite, publish, read a foreign person, or mutate a peer's availability
• tests/security/ is restored to the supported make test-all API tier
• README, roadmap, authorization/testing docs, coverage manifest, both domain guides, and instruction files are reconciled

Local evidence on tested head d6848fd8bb09acb3778ff2f456aacd78d09026b4 against base dbafb60008c69d4ba39580dff23bac4e203e957d:

• initial TDD: 7 failed / 8 passed before implementation
• Black and Ruff passed
• focused dependency mypy passed; broader router mypy still has 85 recorded legacy errors and was not called green
• focused auth/authorization: 169 passed
• make test-all: 1,600 passed, 21 skipped (includes 54 Playwright)
• make test-mobile: 65 passed
• phone/desktop tenant-directory and member-boundary screenshots inspected without overlap/clipping
• self-review recorded in PR; no CI or Ollama review used
• GitHub reported MERGEABLE/CLEAN before builder merge

This completes the BO-12 slice only. Keep the parent issue open where its retained domain, usability, release, provider, PostgreSQL, or whole-application acceptance remains.

[tomqwu]

Completion receipt for PR #318 (merged as 34991bd5660c6422a884f40d5b3f9c71a4a5608e; reviewed head 8ef3d7e79ce92b6d96ac4a782f31364e3d30b960, base 024e45cfdd1da68dcc13888b7f58d991a605b264).

• make test-all: 1,731 passed, 21 skipped, 0 failed/errors; exact-head report test-artifacts/local-validation/20260914T220552.562377Z-84297-1aec53ae/report.json.
• make test-postgres: 8/8 on PostgreSQL 16.14; exact-head report test-artifacts/postgres-validation/2026-09-14T220546.824527-0000-83945-721f1f41/report.json.
• Two parallel PostgreSQL harness invocations each passed 8/8 with distinct owned containers/databases; no labeled containers remained.
• Black, Ruff, and mypy for changed modules passed. Whole-repo mypy remains a known legacy backlog: 830 errors in 39 files.
• Local self-review found no blocking findings after the stale documentation-test assertion was corrected. This was self-review, not independent review.
• GitHub reported MERGEABLE / CLEAN before merge. No hosted CI test, Ollama review, provider action, deployment, or mobile change was involved.