vibecarbon 0.2.1 → 0.3.0

package/carbon/.env.example

@@ -218,3 +218,31 @@ VITE_ENVIRONMENT="development"
 
 # App version shown in Super Admin (set automatically during deployment)
 VITE_APP_VERSION="0.1.0"
+
+# =============================================================================
+# CONNECTION POOLING (Supavisor — production)
+# =============================================================================
+# The internal Supabase stack (auth, rest, realtime, storage, meta) connects to
+# Postgres DIRECTLY and must stay that way — a transaction pooler breaks
+# realtime's replication slot, PostgREST's NOTIFY-based schema reload, and
+# migration advisory locks.
+#
+# Supavisor (started by docker-compose.prod.yml) is the pooler for EXTERNAL
+# direct-DB clients — e.g. a BI tool, a one-off script, or a serverless function
+# you connect to your database yourself. Nothing internal routes through it.
+#
+# Supavisor needs VAULT_ENC_KEY (vault encryption) and REALTIME_SECRET
+# (SECRET_KEY_BASE, also used by Realtime). `vibecarbon create` AUTO-GENERATES
+# both into .env.local alongside JWT_SECRET / POSTGRES_PASSWORD — you do not set
+# them by hand. The `:-default` fallbacks in docker-compose.prod.yml are dev-only
+# safety nets that a created project never uses.
+#
+# External connection strings (POOLER_TENANT_ID defaults to PROJECT_NAME; the
+# username carries the tenant id):
+#   Transaction mode (short, stateless queries / serverless):
+#     postgres://postgres.<PROJECT_NAME>:<POSTGRES_PASSWORD>@<host>:5432/postgres
+#   Session mode (needs prepared statements / LISTEN-NOTIFY / advisory locks):
+#     postgres://postgres.<PROJECT_NAME>:<POSTGRES_PASSWORD>@<host>:6543/postgres
+#
+# NOTE: the pooler ships configured but is not yet exercised by an automated
+# end-to-end test — validate connectivity on a real deploy before relying on it.

package/carbon/docker-compose.yml

@@ -171,6 +171,14 @@ services:
       # failover — pg_promote retried 5 times against an unreachable
       # standby psql before aborting.
       - hot_standby=on
+      - -c
+      # Explicit connection ceiling (image default is 100). Real consumers —
+      # PostgREST pool + auth + storage + realtime + meta + Supavisor's server
+      # pool + replication + superuser_reserved — sum to ~65; 200 leaves
+      # headroom for the HA standby and scale-ups so the ceiling can't be hit.
+      # Connection pooling for EXTERNAL direct-DB clients is Supavisor (prod
+      # overlay); the internal stack connects directly. See docs/security.md.
+      - max_connections=200
     environment:
       POSTGRES_HOST: /var/run/postgresql
       PGPORT: 5432
@@ -330,6 +338,11 @@ services:
       PGRST_DB_USE_LEGACY_GUCS: "false"
       PGRST_APP_SETTINGS_JWT_SECRET: ${JWT_SECRET}
       PGRST_APP_SETTINGS_JWT_EXP: 3600
+      # Explicit DB connection pool (= PostgREST's default, made intentional)
+      # plus a fail-fast acquisition timeout so a saturated pool returns a clear
+      # error instead of hanging. Part of the max_connections budget on `db`.
+      PGRST_DB_POOL: "10"
+      PGRST_DB_POOL_ACQUISITION_TIMEOUT: "10"
     command: postgrest
     depends_on:
       db:

package/carbon/src/server/index.ts

@@ -6,6 +6,7 @@ import { logger as honoLogger } from 'hono/logger';
 import { secureHeaders } from 'hono/secure-headers';
 import { timeout } from 'hono/timeout';
 import { env } from './lib/env';
+import { decodeAalFromJwt } from './lib/jwt';
 import { logger } from './lib/logger';
 import { createRateLimiter } from './lib/rate-limiter';
 import { getSupabaseClient } from './lib/supabase';
@@ -138,6 +139,7 @@ app.use('/api/*', async (c, next) => {
 app.use('/api/*', async (c, next) => {
   if (c.req.path === '/api/health' || c.req.path === '/api/health/ready') {
     c.set('user', null);
+    c.set('aal', null);
     await next();
     return;
   }
@@ -154,11 +156,15 @@ app.use('/api/*', async (c, next) => {
     } = await supabase.auth.getUser();
     if (!error && user) {
       c.set('user', user);
+      // Token signature already verified by getUser() above — safe to read claims.
+      c.set('aal', decodeAalFromJwt(authHeader));
     } else {
       c.set('user', null);
+      c.set('aal', null);
     }
   } else {
     c.set('user', null);
+    c.set('aal', null);
   }
 
   await next();

package/carbon/src/server/lib/jwt.ts

@@ -0,0 +1,27 @@
+/** Supabase Authenticator Assurance Level. */
+export type Aal = 'aal1' | 'aal2';
+
+/**
+ * Read the `aal` (Authenticator Assurance Level) claim from a Supabase JWT.
+ *
+ * This does NOT verify the signature — callers must only pass a token that has
+ * already been verified upstream (the session middleware validates it via
+ * `supabase.auth.getUser()` before decoding here). It is a pure payload read.
+ *
+ * Returns 'aal1' | 'aal2', or null when the token is absent, malformed, or
+ * carries no recognizable aal claim.
+ */
+export function decodeAalFromJwt(token: string | undefined): Aal | null {
+  if (!token) return null;
+  const jwt = token.startsWith('Bearer ') ? token.slice('Bearer '.length) : token;
+  const parts = jwt.split('.');
+  if (parts.length !== 3) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')) as {
+      aal?: unknown;
+    };
+    return payload.aal === 'aal1' || payload.aal === 'aal2' ? payload.aal : null;
+  } catch {
+    return null;
+  }
+}

package/carbon/src/server/lib/mfa-settings.ts

@@ -0,0 +1,40 @@
+import { logger } from './logger';
+import { supabaseAdmin } from './supabase';
+
+const TTL_MS = 60_000;
+let cache: { value: boolean; expiresAt: number } | null = null;
+
+/** Test-only: clear the cached global-MFA flag. */
+export function __resetMfaSettingsCache(): void {
+  cache = null;
+}
+
+/**
+ * Whether MFA is enabled application-wide (app_settings.mfa_enabled.enabled).
+ *
+ * Cached for 60s to keep the aal2 gate off the per-request DB hot path. On a
+ * read failure this FAILS OPEN — returns the last-known value, or false (gate
+ * inert) if none — because this control is opt-in and defaults off, so failing
+ * open only restores pre-feature behavior. A held aal2 session is always
+ * honored by the gate regardless of this value.
+ */
+export async function isMfaGloballyEnabled(): Promise<boolean> {
+  if (cache && cache.expiresAt > Date.now()) {
+    return cache.value;
+  }
+  try {
+    const { data, error } = await supabaseAdmin
+      .from('app_settings')
+      .select('value')
+      .eq('key', 'mfa_enabled')
+      .maybeSingle();
+    if (error) throw error;
+    const value = (data?.value ?? null) as { enabled?: boolean } | null;
+    const enabled = value?.enabled === true;
+    cache = { value: enabled, expiresAt: Date.now() + TTL_MS };
+    return enabled;
+  } catch (err) {
+    logger.warn({ err }, 'mfa-settings: failed to read app_settings.mfa_enabled; failing open');
+    return cache?.value ?? false;
+  }
+}

package/carbon/src/server/middleware/requireAal2.ts

@@ -0,0 +1,49 @@
+import type { Context, Next } from 'hono';
+import { isMfaGloballyEnabled } from '../lib/mfa-settings';
+import type { HonoVariables } from '../types';
+
+type Ctx = Context<{ Variables: HonoVariables }>;
+
+/**
+ * Shared decision for aal2 gating. Returns a Response to short-circuit with, or
+ * null when the request may proceed.
+ *
+ * Order: no user -> 401; already aal2 -> allow; MFA globally disabled -> allow
+ * (gate inert, respects the operator toggle); otherwise -> 403 mfa_required.
+ */
+export async function checkAal2(c: Ctx): Promise<Response | null> {
+  const user = c.get('user');
+  if (!user) {
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+
+  const aal = c.get('aal');
+  if (aal === 'aal2') {
+    return null;
+  }
+
+  if (!(await isMfaGloballyEnabled())) {
+    return null;
+  }
+
+  return c.json({ error: 'mfa_required', current_aal: aal ?? 'aal1', aal_required: 'aal2' }, 403);
+}
+
+/**
+ * Hono middleware: gate a route behind aal2.
+ *   v1Routes.delete('/me', requireAal2, handler)
+ */
+export async function requireAal2(c: Ctx, next: Next): Promise<Response | undefined> {
+  const blocked = await checkAal2(c);
+  if (blocked) return blocked;
+  await next();
+}
+
+/**
+ * Inline guard for conditional gating inside a handler (returns a Response to
+ * return early with, or null to proceed):
+ *   if (body.role === 'OWNER') { const b = await assertAal2(c); if (b) return b; }
+ */
+export function assertAal2(c: Ctx): Promise<Response | null> {
+  return checkAal2(c);
+}

package/carbon/src/server/routes/v1/billing.ts

@@ -6,6 +6,7 @@ import { getBillingProvider, getProviderPriceIds, isBillingConfigured } from '..
 import { env } from '../../lib/env';
 import { sanitizeError } from '../../lib/errors';
 import { supabaseAdmin } from '../../lib/supabase';
+import { requireAal2 } from '../../middleware/requireAal2';
 import type { HonoVariables } from '../../types';
 
 // Helper to access tables not yet in generated types
@@ -119,7 +120,16 @@ async function getOrCreateCustomer(
   // Create database record
   // NOTE: stripe_customer_id column stores the provider's customer ID regardless
   // of which provider is active. The column name is kept for backward compatibility.
-  const insertData =
+  // Single explicit shape (not a discriminated union of two object literals):
+  // PostgREST's insert overload rejects the union because the org branch's
+  // `user_id?: undefined` is incompatible with the user branch's `user_id: string`.
+  // `organizationId` is guaranteed defined in the org path by the guard above.
+  const insertData: {
+    user_id?: string;
+    organization_id?: string;
+    stripe_customer_id: string;
+    email: string;
+  } =
     type === 'user'
       ? { user_id: userId, stripe_customer_id: providerCustomerId, email }
       : { organization_id: organizationId, stripe_customer_id: providerCustomerId, email };
@@ -355,7 +365,7 @@ billingRoutes.get('/subscription', async (c) => {
 /**
  * Create a checkout session via the active billing provider
  */
-billingRoutes.post('/checkout', async (c) => {
+billingRoutes.post('/checkout', requireAal2, async (c) => {
   const user = c.get('user');
 
   if (!user) {
@@ -462,7 +472,7 @@ const setupSchema = z.object({
  * method collection differently (during checkout or via their portal).
  * For non-Stripe providers, this endpoint returns 501.
  */
-billingRoutes.post('/setup', async (c) => {
+billingRoutes.post('/setup', requireAal2, async (c) => {
   const user = c.get('user');
 
   if (!user) {
@@ -559,7 +569,7 @@ billingRoutes.post('/setup', async (c) => {
 /**
  * Create a customer portal session via the active billing provider
  */
-billingRoutes.post('/portal', async (c) => {
+billingRoutes.post('/portal', requireAal2, async (c) => {
   const user = c.get('user');
 
   if (!user) {

package/carbon/src/server/routes/v1/index.ts

@@ -7,6 +7,7 @@ import { sendEmail } from '../../lib/email';
 import { sanitizeError } from '../../lib/errors';
 import { logger } from '../../lib/logger';
 import { type getSupabaseClient, supabaseAdmin } from '../../lib/supabase';
+import { assertAal2, requireAal2 } from '../../middleware/requireAal2';
 import type { HonoVariables } from '../../types';
 
 // Helper to access tables not yet in generated types (notifications, etc.)
@@ -145,7 +146,7 @@ v1Routes.get('/me', async (c) => {
 });
 
 // Delete current user's account
-v1Routes.delete('/me', async (c) => {
+v1Routes.delete('/me', requireAal2, async (c) => {
   const user = c.get('user');
 
   if (!user) {
@@ -534,6 +535,15 @@ v1Routes.patch('/organizations/:orgId/members/:userId', async (c) => {
     return c.json({ error: 'Invalid JSON body' }, 400);
   }
 
+  // Promoting/transferring a member to OWNER is a high-privilege action —
+  // require an aal2 (MFA-validated) session. Checked here, before the authz
+  // lookups: an unauthorized caller is still rejected by the role checks below,
+  // and gating early keeps the check cheap and trivially testable.
+  if (body.role === 'OWNER') {
+    const blocked = await assertAal2(c);
+    if (blocked) return blocked;
+  }
+
   // Get current user's role
   const currentUserRole = await getUserOrgRole(supabase, user.id, orgId);
 
@@ -675,14 +685,15 @@ v1Routes.delete('/organizations/:orgId/members/:userId', async (c) => {
 });
 
 // Delete an organization (OWNER only)
-v1Routes.delete('/organizations/:orgId', async (c) => {
+v1Routes.delete('/organizations/:orgId', requireAal2, async (c) => {
   const user = c.get('user');
 
   if (!user) {
     return c.json({ error: 'Unauthorized' }, 401);
   }
 
-  const orgId = c.req.param('orgId');
+  // biome-ignore lint/style/noNonNullAssertion: orgId is always defined when this route matches
+  const orgId = c.req.param('orgId')!;
   const supabase = c.get('supabase');
 
   // Only the owner can delete

package/carbon/src/server/types.ts

@@ -8,4 +8,6 @@ import type { getSupabaseClient } from './lib/supabase';
 export type HonoVariables = {
   user: User | null;
   supabase: ReturnType<typeof getSupabaseClient>;
+  /** Authenticator Assurance Level of the current session, or null if unknown. */
+  aal: 'aal1' | 'aal2' | null;
 };

package/carbon/tests/integration/server/middleware/require-aal2.test.ts

@@ -0,0 +1,123 @@
+import { Hono } from 'hono';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { HonoVariables } from '@server/types';
+
+const { maybeSingleMock, warnMock } = vi.hoisted(() => ({
+  maybeSingleMock: vi.fn(),
+  warnMock: vi.fn(),
+}));
+
+vi.mock('@server/lib/supabase', () => ({
+  supabaseAdmin: {
+    from: () => ({ select: () => ({ eq: () => ({ maybeSingle: maybeSingleMock }) }) }),
+  },
+}));
+vi.mock('@server/lib/logger', () => ({
+  logger: { error: vi.fn(), info: vi.fn(), warn: warnMock, debug: vi.fn() },
+}));
+
+const { requireAal2, assertAal2 } = await import('@server/middleware/requireAal2');
+const { __resetMfaSettingsCache } = await import('@server/lib/mfa-settings');
+
+type Aal = 'aal1' | 'aal2' | null;
+
+// Build a fresh app whose injector middleware seeds user + aal BEFORE the
+// gated route (mountRoute can't be used here — it adds no pre-route middleware).
+function gatedApp(opts: { user: unknown; aal: Aal }) {
+  const app = new Hono<{ Variables: HonoVariables }>();
+  app.use('*', async (c, next) => {
+    // biome-ignore lint/suspicious/noExplicitAny: test injects a minimal user
+    c.set('user', opts.user as any);
+    c.set('aal', opts.aal);
+    await next();
+  });
+  app.delete('/gated', requireAal2, (c) => c.json({ ok: true }));
+  return app;
+}
+
+const aUser = { id: 'user-1', email: 'u@test.com' };
+
+function enableMfa() {
+  maybeSingleMock.mockResolvedValue({ data: { value: { enabled: true } }, error: null });
+}
+function disableMfa() {
+  maybeSingleMock.mockResolvedValue({ data: { value: { enabled: false } }, error: null });
+}
+
+beforeEach(() => {
+  __resetMfaSettingsCache();
+  maybeSingleMock.mockReset();
+  warnMock.mockReset();
+});
+
+describe('requireAal2', () => {
+  it('passes an aal2 session through (no settings read needed)', async () => {
+    const res = await gatedApp({ user: aUser, aal: 'aal2' }).request('/gated', { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(maybeSingleMock).not.toHaveBeenCalled();
+  });
+
+  it('blocks an aal1 session with 403 mfa_required when MFA is globally enabled', async () => {
+    enableMfa();
+    const res = await gatedApp({ user: aUser, aal: 'aal1' }).request('/gated', { method: 'DELETE' });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual({
+      error: 'mfa_required',
+      current_aal: 'aal1',
+      aal_required: 'aal2',
+    });
+  });
+
+  it('reports current_aal as aal1 when the session carries no aal claim', async () => {
+    enableMfa();
+    const res = await gatedApp({ user: aUser, aal: null }).request('/gated', { method: 'DELETE' });
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual({
+      error: 'mfa_required',
+      current_aal: 'aal1',
+      aal_required: 'aal2',
+    });
+  });
+
+  it('passes an aal1 session through when MFA is globally disabled (gate inert)', async () => {
+    disableMfa();
+    const res = await gatedApp({ user: aUser, aal: 'aal1' }).request('/gated', { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  it('returns 401 when there is no authenticated user', async () => {
+    const res = await gatedApp({ user: null, aal: null }).request('/gated', { method: 'DELETE' });
+    expect(res.status).toBe(401);
+    expect(await res.json()).toEqual({ error: 'Unauthorized' });
+  });
+
+  it('fails open (allows) and warns when the settings read throws', async () => {
+    maybeSingleMock.mockRejectedValueOnce(new Error('db down'));
+    const res = await gatedApp({ user: aUser, aal: 'aal1' }).request('/gated', { method: 'DELETE' });
+    expect(res.status).toBe(200);
+    expect(warnMock).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      expect.stringContaining('mfa-settings'),
+    );
+  });
+
+  it('assertAal2 returns a 403 inline for aal1 when MFA is enabled', async () => {
+    enableMfa();
+    const app = new Hono<{ Variables: HonoVariables }>();
+    app.use('*', async (c, next) => {
+      // biome-ignore lint/suspicious/noExplicitAny: minimal injected user
+      c.set('user', aUser as any);
+      c.set('aal', 'aal1');
+      await next();
+    });
+    app.post('/inline', async (c) => {
+      const blocked = await assertAal2(c);
+      if (blocked) return blocked;
+      return c.json({ ok: true });
+    });
+    const res = await app.request('/inline', { method: 'POST' });
+    expect(res.status).toBe(403);
+    expect((await res.json()).error).toBe('mfa_required');
+  });
+});

package/carbon/tests/integration/server/routes/billing-aal2.test.ts

@@ -0,0 +1,63 @@
+import { Hono } from 'hono';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { jsonPost } from '../../../_helpers/app';
+import type { HonoVariables } from '@server/types';
+
+const { maybeSingleMock } = vi.hoisted(() => ({ maybeSingleMock: vi.fn() }));
+
+vi.mock('@server/lib/supabase', () => ({
+  supabaseAdmin: {
+    from: () => ({ select: () => ({ eq: () => ({ maybeSingle: maybeSingleMock }) }) }),
+  },
+}));
+vi.mock('@server/lib/logger', () => ({
+  logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn(), debug: vi.fn() },
+}));
+// Billing is "configured" so the gate (which runs first) is what we observe,
+// not a 503. getBillingProvider is never reached because the gate short-circuits.
+vi.mock('@server/billing', () => ({
+  isBillingConfigured: () => true,
+  getBillingProvider: () => ({}),
+  getProviderPriceIds: () => ({}),
+}));
+
+const { billingRoutes } = await import('@server/routes/v1/billing');
+const { __resetMfaSettingsCache } = await import('@server/lib/mfa-settings');
+
+function appWith(aal: 'aal1' | 'aal2') {
+  const app = new Hono<{ Variables: HonoVariables }>();
+  app.use('*', async (c, next) => {
+    // biome-ignore lint/suspicious/noExplicitAny: minimal injected user
+    c.set('user', { id: 'u1', email: 'u@test.com' } as any);
+    c.set('aal', aal);
+    await next();
+  });
+  app.route('/api/v1/billing', billingRoutes);
+  return app;
+}
+
+beforeEach(() => {
+  __resetMfaSettingsCache();
+  maybeSingleMock.mockReset();
+  maybeSingleMock.mockResolvedValue({ data: { value: { enabled: true } }, error: null });
+});
+
+describe('billing endpoints are aal2-gated when MFA is globally enabled', () => {
+  for (const path of ['/checkout', '/portal', '/setup']) {
+    it(`POST ${path} returns 403 mfa_required for an aal1 session`, async () => {
+      const res = await appWith('aal1').request(
+        `/api/v1/billing${path}`,
+        jsonPost({ type: 'user' }),
+      );
+      expect(res.status).toBe(403);
+      expect((await res.json()).error).toBe('mfa_required');
+    });
+  }
+
+  it('POST /checkout is NOT gated for an aal2 session (gate passes through)', async () => {
+    const res = await appWith('aal2').request('/api/v1/billing/checkout', jsonPost({ type: 'user' }));
+    // Gate satisfied → handler runs. Whatever it returns, it is NOT the mfa_required 403.
+    const body = await res.json();
+    expect(body.error).not.toBe('mfa_required');
+  });
+});

package/carbon/tests/integration/server/routes/v1-aal2.test.ts

@@ -0,0 +1,102 @@
+import { Hono } from 'hono';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { HonoVariables } from '@server/types';
+
+const { maybeSingleMock } = vi.hoisted(() => ({ maybeSingleMock: vi.fn() }));
+
+// supabaseAdmin is used both for the app_settings read (gate) and by handlers.
+// The gate short-circuits gated paths before handlers run, so an app_settings-
+// shaped chain is enough. The PATCH "skip" case proceeds into the handler,
+// which calls getUserOrgRole on the USER client (c.get('supabase')) — injected
+// separately below.
+vi.mock('@server/lib/supabase', () => ({
+  supabaseAdmin: {
+    from: () => ({ select: () => ({ eq: () => ({ maybeSingle: maybeSingleMock }) }) }),
+  },
+}));
+vi.mock('@server/lib/logger', () => ({
+  logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn(), debug: vi.fn() },
+}));
+vi.mock('@server/lib/email', () => ({ sendEmail: vi.fn() }));
+
+const { v1Routes } = await import('@server/routes/v1/index');
+const { __resetMfaSettingsCache } = await import('@server/lib/mfa-settings');
+
+// User-scoped supabase stub whose membership lookups resolve to "no role", so a
+// request that passes the gate cleanly 404s instead of crashing.
+const noRoleSupabase = {
+  from: () => ({
+    select: () => ({ eq: () => ({ eq: () => ({ single: async () => ({ data: null }) }) }) }),
+  }),
+};
+
+function appWith(aal: 'aal1' | 'aal2', user: unknown = { id: 'u1', email: 'u@test.com' }) {
+  const app = new Hono<{ Variables: HonoVariables }>();
+  app.use('*', async (c, next) => {
+    // biome-ignore lint/suspicious/noExplicitAny: minimal injected context
+    c.set('user', user as any);
+    c.set('aal', aal);
+    // biome-ignore lint/suspicious/noExplicitAny: minimal user-client stub
+    c.set('supabase', noRoleSupabase as any);
+    await next();
+  });
+  app.route('/api/v1', v1Routes);
+  return app;
+}
+
+function jsonPatch(body: unknown): RequestInit {
+  return { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) };
+}
+
+beforeEach(() => {
+  __resetMfaSettingsCache();
+  maybeSingleMock.mockReset();
+  maybeSingleMock.mockResolvedValue({ data: { value: { enabled: true } }, error: null });
+});
+
+describe('account + org endpoints are aal2-gated when MFA is globally enabled', () => {
+  it('DELETE /me returns 403 mfa_required for aal1', async () => {
+    const res = await appWith('aal1').request('/api/v1/me', { method: 'DELETE' });
+    expect(res.status).toBe(403);
+    expect((await res.json()).error).toBe('mfa_required');
+  });
+
+  it('DELETE /organizations/:id returns 403 mfa_required for aal1', async () => {
+    const res = await appWith('aal1').request('/api/v1/organizations/org-1', { method: 'DELETE' });
+    expect(res.status).toBe(403);
+    expect((await res.json()).error).toBe('mfa_required');
+  });
+
+  it('PATCH member role -> OWNER returns 403 mfa_required for aal1 (transfer gated)', async () => {
+    const res = await appWith('aal1').request(
+      '/api/v1/organizations/org-1/members/u2',
+      jsonPatch({ role: 'OWNER' }),
+    );
+    expect(res.status).toBe(403);
+    expect((await res.json()).error).toBe('mfa_required');
+  });
+
+  it('PATCH member role -> ADMIN is NOT blocked by the MFA gate for aal1', async () => {
+    const res = await appWith('aal1').request(
+      '/api/v1/organizations/org-1/members/u2',
+      jsonPatch({ role: 'ADMIN' }),
+    );
+    // Proceeds past the gate into the handler, which 404s on the null-role
+    // membership lookup. The point: it is NOT the mfa_required 403.
+    const body = await res.json();
+    expect(body.error).not.toBe('mfa_required');
+  });
+
+  it('aal2 session passes the gate and reaches the handler on DELETE /organizations/:id', async () => {
+    // Same route as the aal1 -> 403 test above. With aal2 the gate is satisfied
+    // and the handler runs; getUserOrgRole (on the null-role stub) then returns
+    // 404 "not found / access denied". Asserting the concrete 404 — not merely
+    // "not 403" — proves the handler actually executed past the gate. The aal1
+    // companion test (403 mfa_required on this same route) is what guards
+    // against the middleware being accidentally removed: if it were, aal1 would
+    // also reach the handler and return 404 instead of 403.
+    const del = await appWith('aal2').request('/api/v1/organizations/org-1', { method: 'DELETE' });
+    expect(del.status).toBe(404);
+    expect((await del.json()).error).not.toBe('mfa_required');
+  });
+});

package/carbon/tests/unit/server/jwt.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { decodeAalFromJwt } from '@server/lib/jwt';
+
+// Build a JWT with the given payload. Signature is irrelevant — decodeAalFromJwt
+// never verifies it (the real session middleware already did via getUser()).
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64 = (o: unknown) => Buffer.from(JSON.stringify(o)).toString('base64url');
+  return `${b64({ alg: 'HS256', typ: 'JWT' })}.${b64(payload)}.fakesig`;
+}
+
+describe('decodeAalFromJwt', () => {
+  it('returns aal2 for an aal2 token', () => {
+    expect(decodeAalFromJwt(makeJwt({ aal: 'aal2', sub: 'u1' }))).toBe('aal2');
+  });
+
+  it('returns aal1 for an aal1 token', () => {
+    expect(decodeAalFromJwt(makeJwt({ aal: 'aal1', sub: 'u1' }))).toBe('aal1');
+  });
+
+  it('returns null when the aal claim is absent', () => {
+    expect(decodeAalFromJwt(makeJwt({ sub: 'u1' }))).toBeNull();
+  });
+
+  it('returns null for an unexpected aal value', () => {
+    expect(decodeAalFromJwt(makeJwt({ aal: 'aal3' }))).toBeNull();
+  });
+
+  it('returns null for a non-JWT string (wrong segment count)', () => {
+    expect(decodeAalFromJwt('not-a-jwt')).toBeNull();
+  });
+
+  it('returns null for malformed base64/JSON without throwing', () => {
+    expect(decodeAalFromJwt('aaa.@@@notbase64@@@.bbb')).toBeNull();
+  });
+
+  it('returns null for undefined/empty input', () => {
+    expect(decodeAalFromJwt(undefined)).toBeNull();
+    expect(decodeAalFromJwt('')).toBeNull();
+  });
+
+  it('tolerates a leading "Bearer " prefix', () => {
+    expect(decodeAalFromJwt(`Bearer ${makeJwt({ aal: 'aal2' })}`)).toBe('aal2');
+  });
+});

package/carbon/tests/unit/server/mfa-settings.test.ts

@@ -0,0 +1,64 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { maybeSingleMock, warnMock } = vi.hoisted(() => ({
+  maybeSingleMock: vi.fn(),
+  warnMock: vi.fn(),
+}));
+
+// supabaseAdmin.from('app_settings').select('value').eq('key','mfa_enabled').maybeSingle()
+vi.mock('@server/lib/supabase', () => ({
+  supabaseAdmin: {
+    from: () => ({ select: () => ({ eq: () => ({ maybeSingle: maybeSingleMock }) }) }),
+  },
+}));
+
+vi.mock('@server/lib/logger', () => ({
+  logger: { error: vi.fn(), info: vi.fn(), warn: warnMock, debug: vi.fn() },
+}));
+
+const { isMfaGloballyEnabled, __resetMfaSettingsCache } = await import('@server/lib/mfa-settings');
+
+beforeEach(() => {
+  __resetMfaSettingsCache();
+  maybeSingleMock.mockReset();
+  warnMock.mockReset();
+});
+
+describe('isMfaGloballyEnabled', () => {
+  it('returns true when the setting is { enabled: true }', async () => {
+    maybeSingleMock.mockResolvedValueOnce({ data: { value: { enabled: true } }, error: null });
+    expect(await isMfaGloballyEnabled()).toBe(true);
+  });
+
+  it('returns false when the setting is { enabled: false }', async () => {
+    maybeSingleMock.mockResolvedValueOnce({ data: { value: { enabled: false } }, error: null });
+    expect(await isMfaGloballyEnabled()).toBe(false);
+  });
+
+  it('returns false when the row is missing', async () => {
+    maybeSingleMock.mockResolvedValueOnce({ data: null, error: null });
+    expect(await isMfaGloballyEnabled()).toBe(false);
+  });
+
+  it('caches within the TTL — a second call issues no query', async () => {
+    maybeSingleMock.mockResolvedValueOnce({ data: { value: { enabled: true } }, error: null });
+    expect(await isMfaGloballyEnabled()).toBe(true);
+    expect(await isMfaGloballyEnabled()).toBe(true);
+    expect(maybeSingleMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('__resetMfaSettingsCache forces a re-query', async () => {
+    maybeSingleMock.mockResolvedValueOnce({ data: { value: { enabled: true } }, error: null });
+    expect(await isMfaGloballyEnabled()).toBe(true);
+    __resetMfaSettingsCache();
+    maybeSingleMock.mockResolvedValueOnce({ data: { value: { enabled: false } }, error: null });
+    expect(await isMfaGloballyEnabled()).toBe(false);
+    expect(maybeSingleMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('fails open to false (gate inert) and warns when the read throws', async () => {
+    maybeSingleMock.mockRejectedValueOnce(new Error('db down'));
+    expect(await isMfaGloballyEnabled()).toBe(false);
+    expect(warnMock).toHaveBeenCalledTimes(1);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibecarbon",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Create and manage production-ready Vibecarbon applications",
   "type": "module",
   "bin": "./src/cli.js",