feat(gov-000): harden feature flag governance

Author: Mr-Dark-debug

CHANGELOG.md

@@ -34,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Added the missing `rbac_hardening_v1` enum value to feature flag migrations to keep Supabase schema in sync with governance defaults.
+- Locked the admin feature flag API (including PURGE) behind RBAC checks, emitting denial telemetry and documenting reversible down migrations.
 
 ### Planned - Library Feature
 - **User Library System**: Complete Medium-style library feature for saving and organizing content

docs/06-data-model-delta.md

@@ -66,7 +66,7 @@
 - **Webhooks:** Store delivery payloads for 30 days for debugging, then purge.
 
 ## 4. Migration Approach
-1. **Feature-flag gated migrations:** Introduce new tables with `enabled` flags default false; ensure down migrations exist.
+1. **Feature-flag gated migrations:** Introduce new tables with `enabled` flags default false; ensure down migrations exist. `0017_create_feature_flags.down.sql` and `0018_expand_role_matrix.down.sql` provide rollback paths for GOV-000 and SEC-001 respectively.
 2. **Backfill Strategy:** Use Supabase functions or background workers to populate new tables (e.g., `reputation_aggregates`) with resume tokens.
 3. **Incremental rollout:** Deploy schema changes in small batches (spaces, then content, then commerce) to minimize lock times.
 4. **Testing:** Integration tests validating RLS and referential integrity must run in CI before enabling flags.

docs/08-observability.md

@@ -17,7 +17,7 @@
 | `event_rsvp_to_attendance_rate` | Attendance / RSVPs | Gauge | `event_type`, `space` |
 | `moderation_queue_oldest_min` | Age of oldest open report | Gauge | `queue_type`, `space` |
 | `crash_free_sessions` | % of sessions without fatal error | Gauge | `platform` |
-| `authz_denied_count` | Authorization failures | Counter | `resource`, `role`, `space` |
+| `authz_denied_count` | Authorization failures | Counter | `context`, `resource`, `role`, `space`, `reason` |
 | `flag_evaluation_latency_ms` | Feature flag evaluation | Histogram | `flag_key` |
 | `webhook_delivery_success_rate` | Webhook successes vs. attempts | Gauge | `event_type` |
 | `automod_trigger_count` | Automod actions per rule | Counter | `rule_type`, `space` |

docs/09-test-strategy.md

@@ -34,7 +34,7 @@
 - Tests must run with flags ON and OFF to ensure fallback behavior.
 - Provide helper to set flag context in tests (`withFeatureFlag('spaces_v1', true)`).
 - CI includes matrix builds for critical flags (Spaces, Commerce, Events).
-- Added Vitest coverage for the feature flag SDK (caching, invalidation, telemetry) as part of GOV-000; extend coverage to admin API routes in upcoming iterations.
+- Added Vitest coverage for the feature flag SDK (caching, invalidation, telemetry) as part of GOV-000; admin route guard tests (`tests/unit/feature-flags-admin-route.test.ts`) now verify unauthorized flows and cache purge protections.
 - SEC-001 adds Vitest coverage for role slug normalization and observability counters, plus a Supabase RBAC harness (`tests/security/rbac-policies.test.ts`) that runs when credentials are provided.
 
 ## 7. Performance & Load

docs/10-release-plan.md

@@ -45,7 +45,7 @@
 
 ## 6. Rollback Procedures
 - **Feature-level:** Toggle flag OFF, clear caches, notify stakeholders.
-- **Database-level:** Execute down migration scripts; for irreversible data changes, restore from Supabase point-in-time recovery.
+- **Database-level:** Execute down migration scripts (`0017_create_feature_flags.down.sql`, `0018_expand_role_matrix.down.sql`); for irreversible data changes, restore from Supabase point-in-time recovery.
 - **Payments:** Pause webhook processing via provider dashboard, ensure escrow funds safe.
 - **Events:** Notify attendees of postponement if event module impacted.
 

docs/assumptions.md

@@ -12,3 +12,4 @@
 | A-008 | 2025-02-14 | Legal/compliance resources available before Phase 3 commerce rollout. | Necessary for payments, KYC, events. | Open |
 | A-009 | 2025-10-10 | Feature flag ownership stored as free-text owner label until RBAC revamp in SEC-001. | Allows governance UI to launch without expanded role matrix; revisit once role hierarchy finalized. | Closed (2025-10-17) |
 | A-010 | 2025-02-18 | Despite cutover directive, execution continues ticket-by-ticket under feature flags to avoid destabilizing one-shot release until all prerequisites validated. | Aligns with risk register and roadmap gating; supports rehearsed cutover later without skipping validation. | Open |
+| A-011 | 2025-02-19 | Supabase migration runner respects paired `.down.sql` files for rollback in staging/production. | Verified locally; staging rehearsal scheduled before enabling GOV-000 for pilot use. | Open |

docs/progress/weekly-2025-10-17.md

@@ -1,6 +1,7 @@
 # Weekly Progress — 2025-10-17
 
 ## Highlights
+- Hardened GOV-000 governance tooling with admin guard telemetry, cache purge protection, and reversible migrations for feature flags/RBAC.
 - Delivered SEC-001 RBAC hardening: refreshed Supabase `roles`/`profile_roles`, migrated legacy slugs, and rewrote taxonomy/community policies for the new member → admin ladder.
 - Gated admin role management behind the new `rbac_hardening_v1` flag, surfaced highest-role badges in the console sidebar, and mapped legacy editor/author selections.
 - Instrumented `authz_denied_count` counter plus console telemetry for admin/community APIs; added Vitest coverage for role slug normalization and metrics emission.
@@ -21,6 +22,7 @@
 
 ## Metrics Snapshot
 - `authz_denied_count`: 0 during admin API smoke tests post-migration (baseline logging now available).
+- Added `context`/`reason` tags to `authz_denied_count` to differentiate governance vs. RBAC denials in dashboards.
 - `flag_evaluation_latency_ms` remains stable at ~4ms p95 (no regression after RBAC changes share the metrics adapter).
 
 ## Risks / Follow-ups

src/app/api/admin/feature-flags/route.ts

@@ -11,6 +11,7 @@ import {
   invalidateFeatureFlagCache,
   upsertFeatureFlagCache,
 } from '@/lib/feature-flags/server'
+import { recordAuthzDeny } from '@/lib/observability/metrics'
 import { createServerClient, createServiceRoleClient } from '@/lib/supabase/server-client'
 import type { Database } from '@/lib/supabase/types'
 import type { AdminFeatureFlagAuditEntry, AdminFeatureFlagRecord } from '@/utils/types'
@@ -72,7 +73,7 @@ const mapAuditRow = (row: Database['public']['Tables']['feature_flag_audit']['Ro
   createdAt: row.created_at,
 })
 
-const requireAdminProfile = async (): Promise<{ profile: ProfileRecord } | { response: NextResponse }> => {
+export const requireAdminProfile = async (): Promise<{ profile: ProfileRecord } | { response: NextResponse }> => {
   const supabase = createServerClient()
   const {
     data: { user },
@@ -86,6 +87,7 @@ const requireAdminProfile = async (): Promise<{ profile: ProfileRecord } | { res
   }
 
   if (!user) {
+    recordAuthzDeny('feature_flag_admin', { reason: 'no_session' })
     return { response: NextResponse.json({ error: 'Unauthorized' }, { status: 401 }) }
   }
 
@@ -104,7 +106,16 @@ const requireAdminProfile = async (): Promise<{ profile: ProfileRecord } | { res
     }
   }
 
-  if (!profile?.is_admin) {
+  if (!profile) {
+    recordAuthzDeny('feature_flag_admin', { reason: 'missing_profile', user_id: user.id })
+    return { response: NextResponse.json({ error: 'Forbidden: admin access required.' }, { status: 403 }) }
+  }
+
+  if (!profile.is_admin) {
+    recordAuthzDeny('feature_flag_admin', {
+      reason: 'forbidden',
+      profile_id: profile.id,
+    })
     return { response: NextResponse.json({ error: 'Forbidden: admin access required.' }, { status: 403 }) }
   }
 
@@ -385,6 +396,12 @@ export async function PATCH(request: Request) {
 }
 
 export async function PURGE() {
+  const result = await requireAdminProfile()
+
+  if ('response' in result) {
+    return result.response
+  }
+
   invalidateFeatureFlagCache()
   return NextResponse.json({ message: 'Feature flag cache cleared.' })
 }

supabase/migrations/0017_create_feature_flags.down.sql

@@ -0,0 +1,21 @@
+-- =================================================================
+-- DOWN MIGRATION: FEATURE FLAG GOVERNANCE
+-- =================================================================
+-- Drops feature flag tables, policies, and enum to revert GOV-000.
+-- Safe to run after ensuring no other tables depend on feature_flag_key.
+
+DROP TABLE IF EXISTS public.feature_flag_audit CASCADE;
+DROP TABLE IF EXISTS public.feature_flags CASCADE;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1
+    FROM pg_type t
+    WHERE t.typname = 'feature_flag_key'
+      AND t.typnamespace = 'public'::regnamespace
+  ) THEN
+    DROP TYPE public.feature_flag_key;
+  END IF;
+END;
+$$;