fix: restore dead prod verification gates; wire root org, root admin, and Permit ReBAC

[izzywdev]

📋 Description

Two clusters of defect, both of the same shape: machinery that exists, looks configured, and does nothing.

A. Production had no automated post-deploy verification for ~4 weeks

• prod-smoke.yml triggered on push to values-prod.yaml gated if: startsWith(head_commit.message, 'release:'). Those conditions are mutually exclusive: release.yml writes its tag bump as release: fuzefront images <sha> [skip ci] — it must carry that token, or the bump push re-triggers release forever — and GitHub does not start push-triggered workflows for commits carrying it. Last real execution 2026-06-30; all 25 runs since are skipped; no run exists for any automated release commit.
• prod-post-deploy.yml triggered on workflow_run of release.yml. It is registered, state: active, name matcher byte-exact, on master since 2026-07-27, and release.yml has succeeded many times since — yet zero runs, ever. So the post-prod Playwright E2E never ran automatically either.

Dispatching post-prod-e2e.yml by hand against production returned 5 passed, 3 failed — see Questions for Reviewers. Those failures are pre-existing and were invisible precisely because both gates were dead.

B. The platform root org and the Permit ReBAC hierarchy were unwired

• No stable root identity. ensureRootPortal() resolved the root as the oldest organizations row of type='platform', creating one on the fly; its own doc comment conceded the codebase "has no pre-existing single root org concept". Rebuild the DB — as the 2026-07-24 Longhorn incident did — and a different row becomes root, orphaning every Permit tenant, tuple and portal row keyed to the old id.
• Ownership fell to a service principal. Owner was "first user with admin in roles, else first user". In production that resolves to platform-registrar: migration 014 gives it roles ['admin','user'] and creates it before any human signs up. It has no password_hash and can never complete an interactive login — so the root org was owned by a principal no human can act as.
• ReBAC declared, never wired. permit/schema.ts defines Organization.relations.parent and an org-admin role derived parent→child. createOrganizationResourceInstance / setOrganizationParent / assignOrgAdminRebac had zero callers anywhere in the repo. No resource instance, no parent tuple, no root grant were ever created — the derivation had nothing to derive from and failed closed, silently. parent_id was validated, permission-checked and stored, then handed to Permit only as a tenant attribute.
• Permit schema never synced automatically — reachable only via npm run permit:schema and tests.

🔄 Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• 🧪 Test addition or improvement

🧪 Testing

• Unit tests
• Integration tests
• E2E tests
• Manual testing

Test Configuration:

• Node.js version: 20 / 22 / 24 (CI matrix)
• OS: Linux
• Browser (if applicable): n/a

Test Instructions

cd backend
npx tsc --noEmit -p tsconfig.json
npm test -- provisioning.test.ts root-org-admin.test.ts

What I verified locally: tsc --noEmit is clean across all changed files (the only remaining errors are pre-existing @fuzefront/custom-hostname-client module-resolution failures, present on master). All four workflow files parse as valid YAML.

What I could NOT verify locally, and why: the backend suite needs Postgres and there is no Docker daemon in this environment, so provisioning.test.ts and the new root-org-admin.test.ts have not been executed — CI is their first run. The production endpoints are also unreachable from here (the egress proxy denies app.fuzefront.com: connect_rejected, gateway answered 403), which is why the post-prod E2E had to be dispatched into Actions instead.

🔧 Implementation Details

Changes Made

• Backend Changes:
  • migrations/015_seed_root_platform_organization.ts (new) — seeds the root platform org under a fixed id, plus its owner membership. A migration, not a seed, for the reason migration 014 documents in its own header: runSeeds() only runs when NODE_ENV !== 'production'. It adopts a pre-existing platform org rather than creating a second one, so environments that already ran the old ensureRootPortal() don't end up with two platform orgs and "oldest wins" deciding which is real.
  • repositories/portalRepository.ts — resolve the root org by fixed id, falling back to oldest-platform for pre-015 databases; pin the created row to that id.
  • services/organizationProvisioning.ts — new permit_org_instance and permit_org_parent steps. A missing explicit parent fails the step (a real inconsistency the caller asked for); a missing implied root parent is skipped with a warning, so org creation can never wedge in failed on a DB without a root org. Authorization still fails closed either way.
  • services/rootOrgAdmin.ts (new) — grants root org-admin to real administrators on boot, explicitly excluding platform-registrar. Granting that token-only principal tree-wide authority would hand every holder of a sealed registration token administrative control of every tenant — a privilege escalation, not a convenience. One failing grant does not abort the rest.
  • permit/sync-permit-schema.ts — extract syncPermitSchemaFromRegistry() so boot and the CLI share one definition. Syncing the base schema alone would omit product policies, and a role absent from the synced schema just denies, silently.
  • index.ts — sync the Permit schema and ensure root admins at boot. Both non-fatal: Permit being unreachable must not stop the platform booting.
• CI Changes:
  • release.yml ends with an explicit gh workflow run prod-post-deploy.yml. workflow_dispatch is exempt from the GITHUB_TOKEN recursion guard (the property auto-merge.yml already relies on) and immune to the suppression token. Non-blocking, but a failed dispatch emits a warning naming the release UNVERIFIED.
  • prod-post-deploy.yml — dispatch-triggered; chains health → E2E; no longer cancel-in-progress (a cancelled verification leaves a deploy unverified, the exact failure it exists to prevent).
  • prod-smoke.yml — reusable workflow_call + workflow_dispatch instead of a push trigger that could never fire.
  • Each file records why the previous trigger was dead, so this is not quietly reintroduced.
• Frontend Changes: none.
• SDK Changes: none.

Code Quality

• Code follows the project's coding standards
• Self-review of code completed
• Code is commented, particularly in hard-to-understand areas
• No console.log or debugging statements left in code

Documentation

• Documentation has been updated (if applicable)
• API documentation updated (if applicable)
• README updated (if applicable)
• Migration guide provided (for breaking changes)

🚨 Breaking Changes

None to any API or package surface. Migration 015 is additive and idempotent, and adopts rather than replaces an existing platform org. Its down() is deliberately irreversible — deleting the root org would orphan the root portal and every child's parent tuple.

📋 Checklist

Pre-submission

• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings or errors
• I have added tests that prove my fix is effective
• New and existing unit tests pass locally with my changes — not run locally, see Testing

Code Quality

• Code follows conventional commit format
• TypeScript strict mode passes (no new errors vs. baseline)
• ESLint passes without errors — not run on backend locally
• No security vulnerabilities introduced
• Performance impact considered and documented

Security Checklist (if applicable)

• No sensitive data exposed
• Input validation implemented — unchanged; server-side validation remains authoritative
• Authentication/authorization properly handled — this PR narrows effective authority: platform-registrar is explicitly excluded from the root org-admin grant. Wiring the hierarchy grants no permission that the schema did not already intend.
• No SQL injection vulnerabilities — parameterized knex.raw throughout
• XSS prevention measures in place — n/a

🔗 Related Issues and PRs

Follows #446 (create-organization UI fix), which is what surfaced the root-org and Permit questions.

🎯 Reviewers

• Subject matter expert (if applicable)

📝 Additional Notes

Deployment Notes

• Requires database migration — 015, additive and idempotent, runs automatically on backend start
• Requires environment variable changes
• Requires dependency updates
• Requires configuration changes

Boot-order note: the Permit schema sync and root-admin grant run on every start and are non-fatal. On a Permit outage the platform still boots; authorization continues to fail closed.

Future Work

• The post-prod E2E does not cover organization creation, so it would not have caught fix(frontend): make "create organization" actually reach the API #446. Worth adding.
• ensureRootPortal() still leaves root ownership on platform-registrar until a human admin exists; promoting ownership to a real administrator when one appears is a natural follow-up.
• The root-admin grant keys off roles LIKE '%admin%', a substring match on a JSON column. It works, but a proper role predicate would be sturdier.

Questions for Reviewers

• The dispatched post-prod E2E failed against live production — 5 passed, 3 failed (run 30449148959). These are pre-existing and unrelated to this diff, but you should see them:

  • "Sign in with Google" hands off to Authentik (OIDC flow starts)
  • authenticated dashboard + Module-Federation apps load
  • Authentik login surface is configured — fails with enroll_url missing — enrollment flow not linked on the identification stage (sign-up dead)

  The two prior manual dispatches (2026-07-21, 2026-07-23) also failed, so this has been red for a while with nothing reporting it. Note the authenticated-dashboard case may partly be an artifact: the spec falls back to seeded admin credentials when POST_PROD_EMAIL/POST_PROD_PASSWORD are unset, and the seeded admin does not exist in production (seeds never run there) — so that test may have no valid login available rather than a broken dashboard. Worth setting those secrets before reading too much into it.

• Root-org ownership: I seeded it owned by platform-registrar so the migration has no dependency on a human existing. If you'd rather it be owned by a named human from the start, that needs a decision on who — say the word and I'll change it.

• I did not file the Jira tickets we discussed; still waiting on which project/scope you want.

---

📊 Performance Impact

Bundle Size Impact:

• No significant impact

Runtime Performance:

• No significant impact — two extra Permit calls per org provisioning (idempotent, skipped on re-runs), and two boot-time calls.

🌐 Browser Compatibility

Not applicable — backend and CI only.

🔄 Backwards Compatibility

• Fully backwards compatible

---

Generated by Claude Code

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.