feat(auth): server-side tier gating via requireTier middleware

The JWT already carried a `tier` claim but nothing on the server read it
— AuthGate enforcement was client-only, so a valid JWT could hit paid
LLM/research endpoints regardless of the user's access tier.

- shared-hono authMiddleware now extracts `tier` into `c.userTier`,
  defaulting unknown/missing claims to `public` (never silently grants
  higher access).
- New `requireTier(minTier)` middleware + `hasTier`/`getTierLevel`
  helpers. Tier hierarchy (guest < public < beta < alpha < founder) is
  mirrored locally to avoid pulling the Svelte-facing shared-branding
  package into Bun services.
- Applied `requireTier('beta')` as defense-in-depth on resource-heavy
  apps/api modules (chat, context, food, guides, news-research, picture,
  plants, research, traces, who) and the MCP endpoint. Pure CRUD modules
  stay auth-only — access there is gated by ownership, not tier.
- DEV_BYPASS_AUTH now injects `userTier` (defaults to founder, override
  via DEV_USER_TIER).
- Authentication guideline documents the pattern + test suite covers
  hierarchy, passes-at-minimum, and rejection paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

packages/shared-hono/package.json

@@ -28,6 +28,7 @@
 		"postgres": "^3.4.5"
 	},
 	"devDependencies": {
+		"@types/bun": "latest",
 		"@types/node": "^24.10.1",
 		"typescript": "^5.9.3"
 	}

packages/shared-hono/src/auth.ts

@@ -10,6 +10,21 @@
 import type { Context, Next } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
+import type { AccessTier } from './types';
+
+const VALID_TIERS: ReadonlySet<AccessTier> = new Set([
+	'guest',
+	'public',
+	'beta',
+	'alpha',
+	'founder',
+]);
+
+function readTierClaim(raw: unknown): AccessTier {
+	return typeof raw === 'string' && VALID_TIERS.has(raw as AccessTier)
+		? (raw as AccessTier)
+		: 'public';
+}
 
 const AUTH_URL = () => process.env.MANA_AUTH_URL ?? 'http://localhost:3001';
 const SERVICE_KEY = () => process.env.MANA_SERVICE_KEY ?? '';
@@ -65,6 +80,7 @@ export function authMiddleware() {
 			c.set('userId', process.env.DEV_USER_ID ?? '00000000-0000-0000-0000-000000000000');
 			c.set('userEmail', 'dev@example.com');
 			c.set('userRole', 'user');
+			c.set('userTier', readTierClaim(process.env.DEV_USER_TIER ?? 'founder'));
 			return next();
 		}
 
@@ -88,10 +104,12 @@ export function authMiddleware() {
 				throw new HTTPException(401, { message: 'Token missing subject claim' });
 			}
 
+			const claims = payload as Record<string, unknown>;
 			c.set('userId', payload.sub);
-			c.set('userEmail', (payload as Record<string, unknown>).email ?? '');
-			c.set('userRole', (payload as Record<string, unknown>).role ?? 'user');
-			c.set('sessionId', (payload as Record<string, unknown>).sid ?? '');
+			c.set('userEmail', claims.email ?? '');
+			c.set('userRole', claims.role ?? 'user');
+			c.set('userTier', readTierClaim(claims.tier));
+			c.set('sessionId', claims.sid ?? '');
 			return next();
 		} catch (err) {
 			if (err instanceof HTTPException) throw err;

packages/shared-hono/src/index.ts

@@ -33,6 +33,7 @@
  */
 
 export { authMiddleware, serviceAuthMiddleware } from './auth';
+export { requireTier, hasTier, getTierLevel } from './tier';
 export { createDb } from './db';
 export type { DbOptions } from './db';
 export { healthRoute } from './health';
@@ -43,4 +44,4 @@ export type { CreditBalance, CreditValidationResult } from './credits';
 export { rateLimitMiddleware } from './rate-limit';
 export { requestLogger, initLogger } from './logger';
 export { logger } from '@mana/shared-logger';
-export type { CurrentUserData, AuthVariables } from './types';
+export type { CurrentUserData, AuthVariables, AccessTier } from './types';

packages/shared-hono/src/tier.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'bun:test';
+import { Hono } from 'hono';
+import type { AccessTier, AuthVariables } from './types';
+import { getTierLevel, hasTier, requireTier } from './tier';
+
+describe('tier helpers', () => {
+	it('orders tiers guest < public < beta < alpha < founder', () => {
+		expect(getTierLevel('guest')).toBeLessThan(getTierLevel('public'));
+		expect(getTierLevel('public')).toBeLessThan(getTierLevel('beta'));
+		expect(getTierLevel('beta')).toBeLessThan(getTierLevel('alpha'));
+		expect(getTierLevel('alpha')).toBeLessThan(getTierLevel('founder'));
+	});
+
+	it('treats unknown and missing tiers as 0', () => {
+		expect(getTierLevel(undefined)).toBe(0);
+		expect(getTierLevel('nobody')).toBe(0);
+	});
+
+	it('hasTier returns true when user tier meets or exceeds min', () => {
+		expect(hasTier('founder', 'alpha')).toBe(true);
+		expect(hasTier('alpha', 'alpha')).toBe(true);
+		expect(hasTier('beta', 'alpha')).toBe(false);
+		expect(hasTier(undefined, 'public')).toBe(false);
+	});
+});
+
+function buildApp(presetTier: AccessTier | undefined) {
+	const app = new Hono<{ Variables: AuthVariables }>();
+	app.use('*', async (c, next) => {
+		if (presetTier !== undefined) c.set('userTier', presetTier);
+		return next();
+	});
+	app.get('/protected', requireTier('beta'), (c) => c.text('ok'));
+	return app;
+}
+
+describe('requireTier middleware', () => {
+	it('passes when the user tier exceeds the minimum', async () => {
+		const res = await buildApp('alpha').request('/protected');
+		expect(res.status).toBe(200);
+		expect(await res.text()).toBe('ok');
+	});
+
+	it('passes when the user tier matches the minimum exactly', async () => {
+		const res = await buildApp('beta').request('/protected');
+		expect(res.status).toBe(200);
+	});
+
+	it('rejects with 403 when the user tier is below the minimum', async () => {
+		const res = await buildApp('public').request('/protected');
+		expect(res.status).toBe(403);
+	});
+
+	it('rejects with 403 when no tier is set on the context (defensive default)', async () => {
+		const res = await buildApp(undefined).request('/protected');
+		expect(res.status).toBe(403);
+	});
+
+	it('rejects a guest caller', async () => {
+		const res = await buildApp('guest').request('/protected');
+		expect(res.status).toBe(403);
+	});
+});

packages/shared-hono/src/tier.ts

@@ -0,0 +1,59 @@
+/**
+ * Access tier helpers for server-side gating.
+ *
+ * Mirrors the hierarchy in @mana/shared-branding/mana-apps.ts. Kept here so
+ * Bun/Hono services don't need to pull in a Svelte-facing package.
+ *
+ * If you change the hierarchy, update BOTH files.
+ */
+
+import type { Context, Next } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { AccessTier } from './types';
+
+const TIER_LEVELS: Record<AccessTier, number> = {
+	guest: 0,
+	public: 1,
+	beta: 2,
+	alpha: 3,
+	founder: 4,
+};
+
+function normalizeTier(value: unknown): AccessTier {
+	if (typeof value === 'string' && value in TIER_LEVELS) {
+		return value as AccessTier;
+	}
+	return 'public';
+}
+
+export function getTierLevel(tier: string | undefined): number {
+	if (!tier) return 0;
+	return TIER_LEVELS[tier as AccessTier] ?? 0;
+}
+
+export function hasTier(userTier: string | undefined, minTier: AccessTier): boolean {
+	return getTierLevel(userTier) >= TIER_LEVELS[minTier];
+}
+
+/**
+ * Require a minimum access tier on a Hono route.
+ *
+ * Must run AFTER `authMiddleware()` so `userTier` is set on the context.
+ *
+ * Usage:
+ * ```ts
+ * app.use('/api/*', authMiddleware());
+ * app.post('/api/v1/ai/generate', requireTier('alpha'), handler);
+ * ```
+ */
+export function requireTier(minTier: AccessTier) {
+	return async (c: Context, next: Next) => {
+		const userTier = normalizeTier(c.get('userTier'));
+		if (!hasTier(userTier, minTier)) {
+			throw new HTTPException(403, {
+				message: `Requires access tier '${minTier}' — current tier '${userTier}' is insufficient.`,
+			});
+		}
+		return next();
+	};
+}

packages/shared-hono/src/types.ts

@@ -1,3 +1,10 @@
+/**
+ * Access tier hierarchy — mirrored from @mana/shared-branding.
+ * Kept local here to avoid pulling a Svelte-facing package into Bun servers.
+ * If you add a tier, update BOTH this file and shared-branding/mana-apps.ts.
+ */
+export type AccessTier = 'guest' | 'public' | 'beta' | 'alpha' | 'founder';
+
 /**
  * User data extracted from a verified JWT token.
  * Compatible with @mana/shared-nestjs-auth CurrentUserData.
@@ -6,6 +13,7 @@ export interface CurrentUserData {
 	userId: string;
 	email: string;
 	role: string;
+	tier: AccessTier;
 	sessionId?: string;
 }
 
@@ -16,5 +24,6 @@ export interface AuthVariables {
 	userId: string;
 	userEmail: string;
 	userRole: string;
+	userTier: AccessTier;
 	sessionId?: string;
 }

packages/shared-hono/tsconfig.json

@@ -8,7 +8,7 @@
 		"skipLibCheck": true,
 		"outDir": "dist",
 		"declaration": true,
-		"types": ["node"]
+		"types": ["node", "bun"]
 	},
 	"include": ["src/**/*.ts"]
 }