vibecarbon 0.8.0 → 0.10.0

package/carbon/src/client/pages/Dashboard.tsx

@@ -11,6 +11,7 @@ import {
   UserPlus,
   Users,
 } from 'lucide-react';
+import { useId } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Area, AreaChart } from 'recharts';
 import { useAuth } from '../components/auth/AuthProvider';
@@ -21,7 +22,7 @@ import { ChartContainer } from '../components/ui/chart';
 import { Skeleton } from '../components/ui/skeleton';
 import { adminServices, getServiceUrl } from '../lib/admin-services';
 import { getAuthHeaders } from '../lib/api';
-import { getUserInitials } from '../lib/utils';
+import { cn, getUserInitials } from '../lib/utils';
 
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL || 'http://localhost:8000';
 
@@ -49,24 +50,25 @@ function getGreetingKey() {
 }
 
 function MiniSparkline({ data }: { data: Array<{ week: string; count: number }> }) {
+  const gradientId = useId();
   return (
     <ChartContainer
-      config={{ count: { label: 'Signups', color: 'rgba(255,255,255,0.5)' } }}
-      className="h-16 w-full aspect-auto"
+      config={{ count: { label: 'Signups', color: 'var(--chart-1)' } }}
+      className="h-16 w-full aspect-auto [&_.recharts-area-curve]:[filter:drop-shadow(0_0_5px_var(--glow-primary))]"
     >
       <AreaChart data={data} margin={{ top: 4, right: 0, bottom: 0, left: 0 }}>
         <defs>
-          <linearGradient id="sparkFill" x1="0" y1="0" x2="0" y2="1">
-            <stop offset="0%" stopColor="rgba(255,255,255,0.3)" />
-            <stop offset="100%" stopColor="rgba(255,255,255,0.05)" />
+          <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+            <stop offset="0%" stopColor="var(--color-count)" stopOpacity={0.25} />
+            <stop offset="100%" stopColor="var(--color-count)" stopOpacity={0.03} />
           </linearGradient>
         </defs>
         <Area
           dataKey="count"
           type="monotone"
-          stroke="rgba(255,255,255,0.6)"
+          stroke="var(--color-count)"
           strokeWidth={2}
-          fill="url(#sparkFill)"
+          fill={`url(#${gradientId})`}
         />
       </AreaChart>
     </ChartContainer>
@@ -79,8 +81,6 @@ interface KpiCardProps {
   change: string;
   positive: boolean;
   icon: React.ComponentType<{ className?: string }>;
-  accentColor: string;
-  accentVar: string;
   sparklineData?: Array<{ week: string; count: number }>;
   loading: boolean;
 }
@@ -91,26 +91,18 @@ function KpiCard({
   change,
   positive,
   icon: Icon,
-  accentColor: _accentColor,
-  accentVar,
   sparklineData,
   loading,
 }: KpiCardProps) {
   return (
-    <Card
-      className="relative overflow-hidden ring-0 text-white backdrop-blur-md"
-      style={{
-        border: '2px solid transparent',
-        background: `linear-gradient(315deg, color-mix(in oklab, ${accentVar} 70%, transparent), color-mix(in oklab, ${accentVar} 40%, transparent)) padding-box, linear-gradient(oklch(0.18 0.02 260),oklch(0.18 0.02 260)) padding-box, linear-gradient(315deg, white, ${accentVar}) border-box`,
-      }}
-    >
+    <Card className="glass relative overflow-hidden ring-0">
       <CardHeader className="relative z-10 pb-1">
         <div className="flex items-center justify-between">
-          <CardDescription className="text-sm font-semibold uppercase tracking-wide text-white drop-shadow-sm">
+          <CardDescription className="text-sm font-medium uppercase tracking-wide">
             {label}
           </CardDescription>
-          <div className="flex size-8 items-center justify-center rounded-md bg-white/20 backdrop-blur-sm">
-            <Icon className="size-4 drop-shadow-sm" />
+          <div className="flex size-8 items-center justify-center rounded-md bg-muted text-muted-foreground">
+            <Icon className="size-4" />
           </div>
         </div>
       </CardHeader>
@@ -118,13 +110,20 @@ function KpiCard({
         {loading ? (
           <Skeleton className="h-9 w-24 rounded-md" />
         ) : (
-          <p className="text-4xl font-extrabold tabular-nums drop-shadow-sm">{value}</p>
+          <p className="font-mono text-5xl font-bold tabular-nums tracking-tight text-card-foreground">
+            {value}
+          </p>
         )}
         <div className="mt-1.5">
           {loading ? (
             <Skeleton className="h-5 w-32 rounded-md" />
           ) : (
-            <span className="inline-flex items-center gap-1 text-xs font-medium text-white/90 drop-shadow-sm">
+            <span
+              className={cn(
+                'inline-flex items-center gap-1 text-xs font-medium',
+                positive ? 'text-success' : 'text-destructive'
+              )}
+            >
               {positive ? <TrendingUp className="size-3" /> : <TrendingDown className="size-3" />}
               {change}
             </span>
@@ -214,25 +213,27 @@ export default function Dashboard() {
     <>
       <PageHeader title={t('dashboard.title')} />
 
-      <ContentPanel variant="full">
-        {/* Welcome banner */}
-        <Card className="relative overflow-hidden">
-          <div className="pointer-events-none absolute inset-0 bg-gradient-to-r from-primary/5 to-transparent" />
+      <ContentPanel variant="full" className="space-y-12">
+        {/* Welcome banner — the view's hero panel */}
+        <Card className="glass relative overflow-hidden ring-0">
+          <div className="pointer-events-none absolute inset-0 [background:radial-gradient(90%_140%_at_0%_0%,var(--glow-primary),transparent_55%)]" />
           <CardHeader className="relative">
             <div className="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
               <div className="flex items-center gap-4">
-                <div className="flex size-14 shrink-0 items-center justify-center rounded-full bg-primary/10 text-xl font-semibold text-primary">
+                <div className="glow-teal-subtle flex size-14 shrink-0 items-center justify-center rounded-full bg-primary/10 text-xl font-semibold text-primary ring-1 ring-primary/30">
                   {initials}
                 </div>
                 <div>
-                  <CardTitle className="text-xl">
+                  <CardTitle className="font-display text-3xl tracking-tight">
                     {greeting}, {firstName}!
                   </CardTitle>
-                  <CardDescription className="mt-0.5">{user?.email}</CardDescription>
+                  <CardDescription className="mt-1">{user?.email}</CardDescription>
                 </div>
               </div>
               <div className="flex items-center gap-3 sm:flex-col sm:items-end">
-                <p className="text-xs text-muted-foreground">{formattedDate}</p>
+                <p className="rounded-full border border-border px-3 py-1.5 text-xs text-muted-foreground">
+                  {formattedDate}
+                </p>
               </div>
             </div>
           </CardHeader>
@@ -250,8 +251,6 @@ export default function Dashboard() {
             }
             positive={stats ? stats.users.newThisMonth >= stats.users.newLastMonth : true}
             icon={Users}
-            accentColor="bg-primary/10 text-primary"
-            accentVar="var(--primary)"
             sparklineData={stats?.users.weeklySignups}
             loading={!stats}
           />
@@ -267,8 +266,6 @@ export default function Dashboard() {
             }
             positive={stats ? stats.users.newThisMonth >= stats.users.newLastMonth : true}
             icon={UserPlus}
-            accentColor="bg-blue-500/10 text-blue-600 dark:text-blue-400"
-            accentVar="#3b82f6"
             sparklineData={stats?.users.weeklySignups}
             loading={!stats}
           />
@@ -284,8 +281,6 @@ export default function Dashboard() {
             }
             positive={stats ? stats.users.activeThisMonth >= stats.users.activeLastMonth : true}
             icon={Activity}
-            accentColor="bg-amber-500/10 text-amber-600 dark:text-amber-400"
-            accentVar="var(--warning)"
             loading={!stats}
           />
           <KpiCard
@@ -296,8 +291,6 @@ export default function Dashboard() {
             }
             positive={true}
             icon={Globe}
-            accentColor="bg-destructive/10 text-destructive"
-            accentVar="var(--destructive)"
             loading={!stats}
           />
         </div>

package/carbon/src/client/pages/Docs.tsx

@@ -287,7 +287,7 @@ export function DocsPage() {
               )}
             </header>
 
-            <article className="prose prose-invert max-w-none">
+            <article className="prose dark:prose-invert max-w-none">
               <page.Component components={mdxComponents} />
             </article>
 

package/carbon/src/client/pages/Home.tsx

@@ -63,7 +63,7 @@ function VibecarbonCTAFooter() {
       }
       footerLinks={
         <>
-          <div className="flex items-center gap-6">
+          <div className="flex flex-wrap items-center justify-center gap-x-6 gap-y-2">
             <a
               href="https://github.com/hyperformant/vibecarbon/"
               target="_blank"

package/carbon/src/client/pages/Legal.tsx

@@ -65,7 +65,7 @@ export default function LegalRoute() {
           <p className="text-lg text-muted-foreground">{page.description}</p>
         </header>
 
-        <article className="prose prose-invert max-w-none">
+        <article className="prose dark:prose-invert max-w-none">
           <page.Component />
         </article>
       </div>

package/carbon/src/server/billing/providers/paddle.ts

@@ -7,7 +7,7 @@
  * Paddle API docs: https://developer.paddle.com/api-reference/overview
  */
 
-import { createHmac } from 'node:crypto';
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import { env } from '../../lib/env';
 import { logger } from '../../lib/logger';
 import type { BillingProvider, CheckoutResult, PortalResult, SubscriptionInfo } from '../provider';
@@ -224,9 +224,28 @@ export class PaddleProvider implements BillingProvider {
       .update(payload)
       .digest('hex');
 
-    if (expectedHash !== providedHash) {
+    // SECURITY: constant-time comparison to avoid leaking the expected HMAC via
+    // response-timing. `!==` short-circuits on the first differing byte, which
+    // is a classic signature-forgery oracle. Encode as bytes and compare with
+    // timingSafeEqual (guarding the length first, since it throws on mismatch).
+    const expectedBuf = Buffer.from(expectedHash, 'hex');
+    const providedBuf = Buffer.from(providedHash, 'hex');
+    if (expectedBuf.length !== providedBuf.length || !timingSafeEqual(expectedBuf, providedBuf)) {
       throw new Error('Invalid Paddle webhook signature');
     }
+
+    // SECURITY: reject stale events to blunt replay attacks. A captured, validly
+    // signed payload can otherwise be resent forever. Mirror Stripe/Polar's
+    // 5-minute tolerance. Paddle's `ts` is a Unix timestamp in seconds.
+    const timestampSec = Number.parseInt(timestamp, 10);
+    if (!Number.isFinite(timestampSec)) {
+      throw new Error('Invalid Paddle webhook timestamp');
+    }
+    const ageSec = Math.abs(Date.now() / 1000 - timestampSec);
+    const TOLERANCE_SEC = 5 * 60;
+    if (ageSec > TOLERANCE_SEC) {
+      throw new Error('Paddle webhook timestamp outside tolerance');
+    }
   }
 
   /** Map Paddle event types to normalized billing event names. */

package/carbon/src/server/billing/providers/polar.ts

@@ -244,6 +244,20 @@ export class PolarProvider implements BillingProvider {
     if (!matched) {
       throw new Error('Invalid Polar webhook signature');
     }
+
+    // SECURITY: reject stale events to blunt replay attacks. A captured, validly
+    // signed payload can otherwise be resent forever to re-assert subscription
+    // state. Standard Webhooks timestamps are Unix seconds; use the same
+    // 5-minute tolerance as the Paddle/Stripe verifiers.
+    const timestampSec = Number.parseInt(timestamp, 10);
+    if (!Number.isFinite(timestampSec)) {
+      throw new Error('Invalid Polar webhook timestamp');
+    }
+    const ageSec = Math.abs(Date.now() / 1000 - timestampSec);
+    const TOLERANCE_SEC = 5 * 60;
+    if (ageSec > TOLERANCE_SEC) {
+      throw new Error('Polar webhook timestamp outside tolerance');
+    }
   }
 
   /** Map Polar event types to normalized billing event names. */

package/carbon/src/server/index.ts

@@ -1,6 +1,7 @@
 import { serve } from '@hono/node-server';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
 import { cors } from 'hono/cors';
 import { logger as honoLogger } from 'hono/logger';
 import { secureHeaders } from 'hono/secure-headers';
@@ -124,15 +125,17 @@ app.use(
   })
 );
 
-// Request body size limit middleware
-app.use('/api/*', async (c, next) => {
-  const contentLength = Number.parseInt(c.req.header('content-length') || '0', 10);
-  const maxSize = 10 * 1024 * 1024; // 10MB
-  if (contentLength > maxSize) {
-    return c.json({ error: 'Request body too large' }, 413);
-  }
-  await next();
-});
+// Request body size limit. bodyLimit enforces the cap while READING the stream,
+// not just by trusting the Content-Length header (which a client can under-state
+// or omit with chunked transfer-encoding to smuggle an oversized body past a
+// header-only check).
+app.use(
+  '/api/*',
+  bodyLimit({
+    maxSize: 10 * 1024 * 1024, // 10MB
+    onError: (c) => c.json({ error: 'Request body too large' }, 413),
+  })
+);
 
 // Supabase session middleware - inject user and client into context
 // Skip for health endpoint (no auth needed, avoids unnecessary getUser() call)

package/carbon/src/server/lib/client-ip.ts

@@ -0,0 +1,68 @@
+import { env } from './env';
+import { logger } from './logger';
+
+// Minimal shape so both Hono's full `Context` and lightweight test doubles work.
+type HasHeader = { req: { header: (name: string) => string | undefined } };
+
+const ipv4Regex = /^(?:\d{1,3}\.){3}\d{1,3}$/;
+const ipv6Regex = /^[a-fA-F0-9:]+$/;
+
+export function isValidIp(ip: string): boolean {
+  return ipv4Regex.test(ip) || ipv6Regex.test(ip);
+}
+
+// Log the "no trusted IP" warning at most once per process to avoid log spam.
+let warnedAboutMissingIP = false;
+
+/**
+ * Resolve the client IP from a trusted reverse proxy.
+ *
+ * SECURITY: `X-Forwarded-For` is an ordered list where each proxy APPENDS the
+ * address of the host it received the connection from. With N trusted proxy
+ * hops in front of this server (`TRUSTED_PROXY_HOPS`, default 1 = Traefik), the
+ * real client IP is the Nth entry counted from the RIGHT. Every entry to the
+ * left of that is attacker-supplied and MUST be ignored — trusting the leftmost
+ * value (as the previous implementations did) lets a client spoof an arbitrary
+ * IP and mint fresh rate-limit / login-lockout buckets at will.
+ *
+ * We deliberately do NOT fall back to `x-real-ip` / `cf-connecting-ip`: Traefik
+ * does not set those, so an attacker could forge them. When a trusted IP can't
+ * be derived we return a shared sentinel ('unknown') so those requests share a
+ * single, more-restrictive bucket (fail closed).
+ */
+export function getClientIp(c: HasHeader, hops: number = env.TRUSTED_PROXY_HOPS): string {
+  const xff = c.req.header('x-forwarded-for');
+
+  if (xff && hops > 0) {
+    const ips = xff
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    // Need at least `hops` entries for the depth-from-right index to land on a
+    // proxy-written value rather than an attacker-supplied one.
+    if (ips.length >= hops) {
+      const candidate = ips[ips.length - hops];
+      if (isValidIp(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  // In development there is typically no reverse proxy in front of the server.
+  if (env.NODE_ENV === 'development') {
+    return 'localhost';
+  }
+
+  if (!warnedAboutMissingIP) {
+    warnedAboutMissingIP = true;
+    logger.warn(
+      'Could not determine a trusted client IP from X-Forwarded-For. Ensure the reverse ' +
+        'proxy (Traefik) sets X-Forwarded-For and that TRUSTED_PROXY_HOPS matches the number ' +
+        'of trusted proxies in front of this server. Requests without a trusted IP share a ' +
+        'single rate-limit bucket.'
+    );
+  }
+
+  return 'unknown';
+}

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

@@ -1,5 +1,14 @@
 import { z } from 'zod';
 
+/**
+ * Parse a boolean env var strictly: only the literal string "true" is true.
+ * `z.coerce.boolean()` is NOT usable here — it treats any non-empty string
+ * (including "false") as `true`. Empty strings are stripped to `undefined`
+ * before validation (see cleanedEnv below), so they fall back to `def`.
+ */
+const envBool = (def: boolean) =>
+  z.preprocess((v) => (v === undefined ? def : v === 'true'), z.boolean());
+
 const envSchema = z.object({
   // Supabase (required)
   SUPABASE_URL: z.string().url(),
@@ -27,12 +36,12 @@ const envSchema = z.object({
   DEV_LOKI_PORT: z.coerce.number().optional(),
 
   // OAuth (optional - configure in Supabase dashboard)
-  GOOGLE_ENABLED: z.coerce.boolean().default(false),
-  MICROSOFT_ENABLED: z.coerce.boolean().default(false),
-  GITHUB_ENABLED: z.coerce.boolean().default(false),
-  APPLE_ENABLED: z.coerce.boolean().default(false),
-  DISCORD_ENABLED: z.coerce.boolean().default(false),
-  MAGIC_LINK_ENABLED: z.coerce.boolean().default(true),
+  GOOGLE_ENABLED: envBool(false),
+  MICROSOFT_ENABLED: envBool(false),
+  GITHUB_ENABLED: envBool(false),
+  APPLE_ENABLED: envBool(false),
+  DISCORD_ENABLED: envBool(false),
+  MAGIC_LINK_ENABLED: envBool(true),
 
   // SMTP (shared with Supabase Auth)
   SMTP_HOST: z.string().optional(),
@@ -72,6 +81,11 @@ const envSchema = z.object({
   // Redis (optional - for distributed rate limiting)
   // Format: redis://[:password@]host:port or redis://[:password@]host:port/db
   REDIS_URL: z.string().url().optional(),
+
+  // Number of trusted reverse-proxy hops in front of this server. Used to pick
+  // the real client IP out of X-Forwarded-For (see lib/client-ip.ts). The
+  // default single hop matches the standard Traefik deployment.
+  TRUSTED_PROXY_HOPS: z.coerce.number().int().min(0).default(1),
 });
 
 // Apply port offset to localhost URLs in development

package/carbon/src/server/lib/rate-limiter.ts

@@ -1,5 +1,6 @@
 import type { Context, Next } from 'hono';
 import Redis from 'ioredis';
+import { getClientIp } from './client-ip';
 import { env } from './env';
 import { logger } from './logger';
 
@@ -194,76 +195,21 @@ function getStore(): HybridStore {
   return store;
 }
 
-// =============================================================================
-// IP EXTRACTION
-// =============================================================================
-
-// Track if we've warned about missing IP headers (log once per process)
-let warnedAboutMissingIP = false;
-
-/**
- * Extract client IP from request headers
- *
- * Security note: Only trust x-forwarded-for when behind a trusted reverse proxy (Traefik).
- * The leftmost IP in x-forwarded-for is the original client IP.
- *
- * Fallback behavior:
- * - In development: Falls back to 'localhost' (expected when not behind proxy)
- * - In production: Falls back to 'unknown' but logs a warning (indicates misconfiguration)
- *
- * When IP is 'unknown', all such requests share a rate limit bucket - this is intentional
- * as it provides more restrictive rate limiting for requests that bypass proper headers.
- */
-function getClientIP(c: Context): string {
-  // x-forwarded-for format: "client, proxy1, proxy2"
-  const xff = c.req.header('x-forwarded-for');
-  if (xff) {
-    // Take leftmost (original client) IP, trim whitespace
-    const clientIP = xff.split(',')[0].trim();
-    // Basic validation - must look like an IP (IPv4 or IPv6)
-    if (/^[\d.:a-fA-F]+$/.test(clientIP)) {
-      return clientIP;
-    }
-  }
-
-  // Fallback to x-real-ip (set by some proxies like nginx)
-  const realIP = c.req.header('x-real-ip');
-  if (realIP && /^[\d.:a-fA-F]+$/.test(realIP)) {
-    return realIP;
-  }
-
-  // Fallback to cf-connecting-ip (Cloudflare)
-  const cfIP = c.req.header('cf-connecting-ip');
-  if (cfIP && /^[\d.:a-fA-F]+$/.test(cfIP)) {
-    return cfIP;
-  }
-
-  // In development, localhost is expected
-  if (env.NODE_ENV === 'development') {
-    return 'localhost';
-  }
-
-  // In production, warn about missing IP headers (indicates proxy misconfiguration)
-  if (!warnedAboutMissingIP) {
-    warnedAboutMissingIP = true;
-    logger.warn(
-      'Could not determine client IP from request headers. ' +
-        'Ensure reverse proxy (Traefik) is configured to set X-Forwarded-For or X-Real-IP headers. ' +
-        'Requests without identifiable IPs will share a rate limit bucket.'
-    );
-  }
-
-  return 'unknown';
-}
-
 // =============================================================================
 // RATE LIMITER MIDDLEWARE
 // =============================================================================
 
 export function createRateLimiter(options: { windowMs: number; max: number }) {
   return async (c: Context, next: Next) => {
-    const ip = getClientIP(c);
-    const key = `${ip}:${c.req.path}`;
+    // SECURITY: prefer a per-user bucket for authenticated requests so a single
+    // account behind a shared/NAT'd IP can't exhaust everyone else's budget (and
+    // can't dodge its own limit by rotating IPs). Falls back to the trusted
+    // client IP — resolved via getClientIp, which ignores attacker-supplied
+    // X-Forwarded-For entries. Note: the app-wide limiters in index.ts run
+    // before the auth middleware sets `user`, so those key by IP.
+    const user = c.get('user');
+    const identifier = user?.id ? `user:${user.id}` : `ip:${getClientIp(c)}`;
+    const key = `${identifier}:${c.req.path}`;
     const now = Date.now();
 
     const result = await getStore().increment(key, options.windowMs, options.max);
@@ -276,7 +222,7 @@ export function createRateLimiter(options: { windowMs: number; max: number }) {
 
     if (!result.allowed) {
       // Log rate limit violations for security monitoring
-      logger.warn({ ip, path: c.req.path, count: result.count }, 'Rate limit exceeded');
+      logger.warn({ identifier, path: c.req.path, count: result.count }, 'Rate limit exceeded');
       return c.json(
         { error: 'Too many requests', retryAfter: Math.ceil((result.resetTime - now) / 1000) },
         429

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

@@ -15,11 +15,17 @@ export const supabaseAdmin: SupabaseClient<Database> = createClient<Database>(
   }
 );
 
-// Create a client for a specific user's context (respects RLS)
-// Uses SERVICE_ROLE_KEY to pass Kong's ACL gate for PostgREST, but RLS is still
-// enforced because PostgREST reads the user's role from the Authorization JWT.
+// Create a client for a specific user's context (respects RLS).
+//
+// SECURITY: uses the ANON key (not the service-role key) as the apikey, with the
+// user's JWT layered on via the Authorization header. PostgREST derives the
+// Postgres role from the JWT, so RLS is enforced for the authenticated user.
+// The critical property is fail-safe degradation: if the Authorization header is
+// ever dropped (bug, proxy stripping, refactor), the client falls back to the
+// anon role under RLS rather than to service_role BYPASSRLS. The dedicated
+// service-role clients (supabaseAdmin / createAuthClient) remain for admin ops.
 export function createSupabaseClient(accessToken: string): SupabaseClient<Database> {
-  return createClient<Database>(env.SUPABASE_URL, env.SUPABASE_SERVICE_ROLE_KEY, {
+  return createClient<Database>(env.SUPABASE_URL, env.SUPABASE_ANON_KEY, {
     global: {
       headers: {
         Authorization: `Bearer ${accessToken}`,

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

@@ -0,0 +1,76 @@
+import type { Context, Next } from 'hono';
+import type { HonoVariables } from '../types';
+
+/**
+ * Hono middleware factory: gate an organization-scoped billing route behind
+ * org membership.
+ *
+ * The route indicates its target via `type` ('user' | 'organization') and,
+ * when organization-scoped, `organizationId`. Reads are GET requests that carry
+ * these in the query string; writes are POSTs that carry them in the JSON body
+ * (Hono caches the parsed body, so the handler can re-parse it safely).
+ *
+ * SECURITY: the membership lookup uses the RLS-enforced per-user Supabase client
+ * (`c.get('supabase')`), never the service-role `adminDb`. A caller can only see
+ * memberships they belong to, so this can neither be bypassed nor used to probe
+ * arbitrary organizations. When `type !== 'organization'` the guard is inert.
+ *
+ * Applying this as route middleware (rather than an inline check per handler)
+ * ensures no org-scoped billing route can silently skip the membership check.
+ */
+export function requireOrgRole(roles: string[]) {
+  return async (
+    c: Context<{ Variables: HonoVariables }>,
+    next: Next
+  ): Promise<Response | undefined> => {
+    const user = c.get('user');
+    if (!user) {
+      return c.json({ error: 'Unauthorized' }, 401);
+    }
+
+    let type: string | undefined;
+    let organizationId: string | undefined;
+
+    if (c.req.method === 'GET') {
+      type = c.req.query('type') ?? 'user';
+      organizationId = c.req.query('organizationId');
+    } else {
+      try {
+        const body = (await c.req.json()) as {
+          type?: string;
+          organizationId?: string;
+        };
+        type = body?.type;
+        organizationId = body?.organizationId;
+      } catch {
+        // Malformed JSON — let the handler's own validation return the 400 so
+        // error handling stays in one place. No data is accessed here.
+        await next();
+        return;
+      }
+    }
+
+    if (type !== 'organization') {
+      await next();
+      return;
+    }
+
+    if (!organizationId) {
+      return c.json({ error: 'Organization ID is required for organization billing' }, 400);
+    }
+
+    const supabase = c.get('supabase');
+    const { data: membership } = await supabase
+      .from('memberships')
+      .select('role')
+      .eq('user_id', user.id)
+      .eq('organization_id', organizationId)
+      .single();
+
+    if (!membership || !roles.includes(membership.role)) {
+      return c.json({ error: 'You must be an admin to manage organization billing' }, 403);
+    }
+
+    await next();
+  };
+}