Activation 2/3: dry-run operator CLI for trusted claims, organizations and memberships

[mekado11]

Why

V2 authority comes from two things: server-managed organization memberships, and the Firebase Auth is_super_admin claim that has governed legacy administration since #24. Nothing in the repo could create either one, so no account, including the owner's, can use the redesigned workspace. This adds a reviewed operator path that runs only with the project owner's local Admin credentials. There is no browser or public API.

Independent of #28 (server credentials); the two can merge in either order.

What

npm run operator -- <command> --project P ... (scripts/operator.ts, with the logic in server/v2/operator.ts):

Command	Effect
inspect --email/--uid	Read-only report: Auth state, operator claim, legacy profile/company. Flags forged profile is_super_admin without trusting it, and lists V2 memberships.
audit-legacy-admins	Read-only list of accounts whose profile says admin, with their real claim state. After the hardened rules deploy, each needs an explicit decision.
grant-operator / revoke-operator	Set or remove the claim while keeping other claims. Grant requires a verified, enabled account; revoke also revokes sessions.
provision-org	Creates organizations/{id} and a published context_versions/context-v1. Never overwrites; an existing org with a different name is refused.
add-member --roles	Creates or re-activates a membership. The member must be verified and enabled, and the org active. Re-checks optimistically inside the transaction.

Safety:

• Everything is a dry run unless --apply, and prints the exact before/after changes.
• --project must equal FIREBASE_PROJECT_ID.
• The org and membership commands require an actor who holds the Auth claim; forged profile flags are refused.
• Records are validated with the existing V2 zod contracts (Organization, ContextVersion, Membership).
• Org and membership writes create an audit event in organizations/{id}/audit_events in the same transaction, in the same shape as the existing command-service events.

Also:

• The two V2 collection-group field overrides from firestore.v2.indexes.json are merged into firestore.indexes.json as a minimal diff, so firebase deploy --only firestore:indexes (without --force) ships them and keeps unrelated deployed indexes.
• docs/v2/activation-runbook.md lists the ordered, reversible activation steps: backup → audit → credentials → claim → org/membership → indexes → rules → flags → acceptance.

Not changed

No data, rules, claims or flags are changed by merging. Nothing runs automatically.

Verification

• New tests/emulator/operator.test.ts (8 tests) covers:
  • dry run is read-only; claims are preserved; revoke revokes sessions;
  • unverified and unknown accounts are refused; forged profile flags are rejected as the actor;
  • records are schema-valid, audit events are written, and re-runs are no-ops or refused;
  • the optimistic-concurrency abort;
  • a provisioned readiness lead is recognized by the existing getReadinessContext and getExerciseSetup;
  • inspect and audit-legacy-admins report correctly;
  • the CLI refuses a project mismatch and defaults to dry run.
• Ran it locally alongside the existing security.test.ts: 26/26 pass.
• typecheck:v2, test:v2 68/68, test:security 52/52.

🤖 Generated with Claude Code

https://claude.ai/code/session_017SrzLVR7J3b9nCU177esz8

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hubcys	Ready	Preview	Sep 23, 2026 8:24pm UTC

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f1f3349457

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".