.gitignore

@@ -102,7 +102,6 @@ _reference/
 # AI instructions, and a security-sensitive bug report. Kept local-only.
 ARCHITECTURE.md
 BUILD_PLAN.md
-CLAUDE.md
 CONTRIBUTING.md
 SPEC.md
 SPRINT-PLAN.md
@@ -121,3 +120,9 @@ memory.md
 *.md
 !README.md
 !**/README.md
+# Agent hard rules + SuperTokens library index (must be visible to every agent)
+!CLAUDE.md
+!AGENTS.md
+# Un-ignore parent dir first, then the file (gitignore parent-dir rule)
+!/docs/
+!/docs/knowledge-base.md

AGENTS.md

@@ -0,0 +1,42 @@
+# CLAUDE.md — Briven (project root)
+
+Agent instructions for this repo. **Hard rules never break.**
+
+---
+
+## HARD RULE — Auth work: open SuperTokens knowledge base first (never break)
+
+**Owner intent (flndrn, 2026-07-26):** Agents were guessing Auth instead of using the SuperTokens library. That ends here.
+
+### Before **any** Auth change
+
+This includes: magic link, OTP, SMS, OAuth / social / Konnos, sessions, MFA, passkeys, FDI proxy, IdP/OIDC, SSO, multitenancy, branding, providers UI, secrets, allowed domains, disable/enable Auth, or anything under `apps/api/src/**/auth*`, `apps/api/src/services/auth-core/**`, `packages/auth/**`, Auth dashboard routes, or Auth docs.
+
+You **must**:
+
+1. **Open and read** [`docs/knowledge-base.md`](docs/knowledge-base.md) (the SuperTokens + Doltgres library cabinet for this project).
+2. Open the **matching SuperTokens section/URL** for the feature (passwordless, thirdparty, sessions, FDI, multitenancy, etc.).
+3. If the work touches the database or SQL: also open the **Doltgres** section of that file (and `AI_DOCS/dolt-reference/` when present).
+4. **State in one plain sentence** what SuperTokens (or the KB) says the correct behavior is — then implement Briven-branded on Doltgres.
+5. **Do not invent** login shapes, magic-link hosts, OAuth flows, or cookie rules from memory alone.
+
+### Forbidden
+
+- Shipping Auth changes without reading `docs/knowledge-base.md` first.
+- “Looks reasonable” / assume / guess when SuperTokens already documents the flow.
+- Abandoning briven-engine / architecture after one SQL error without Doltgres docs + notifying flndrn.
+
+### After Auth changes
+
+- Prefer prove on a real project path (e.g. mavi pay / ISY) with evidence — not “code looks fine.”
+
+**Library path:** `docs/knowledge-base.md`  
+**Purpose:** SuperTokens as product/architecture map; Briven stays Briven-branded on Doltgres.
+
+---
+
+## Other standing notes
+
+- Product walls, multi-tenant isolation, `pk_briven_auth_` public keys, no inventing Clerk/Firebase as the platform engine.
+- Infra compose logging caps and Docker rules: see `infra/CLAUDE.md` and `docs/DOCKER.md` when editing `infra/`.
+- Deploy: France Briven compose + `scripts/safe-redeploy-service.sh`; batch deploys when possible.

CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md — Briven (project root)
+
+Agent instructions for this repo. **Hard rules never break.**
+
+---
+
+## HARD RULE — Auth work: open SuperTokens knowledge base first (never break)
+
+**Owner intent (flndrn, 2026-07-26):** Agents were guessing Auth instead of using the SuperTokens library. That ends here.
+
+### Before **any** Auth change
+
+This includes: magic link, OTP, SMS, OAuth / social / Konnos, sessions, MFA, passkeys, FDI proxy, IdP/OIDC, SSO, multitenancy, branding, providers UI, secrets, allowed domains, disable/enable Auth, or anything under `apps/api/src/**/auth*`, `apps/api/src/services/auth-core/**`, `packages/auth/**`, Auth dashboard routes, or Auth docs.
+
+You **must**:
+
+1. **Open and read** [`docs/knowledge-base.md`](docs/knowledge-base.md) (the SuperTokens + Doltgres library cabinet for this project).
+2. Open the **matching SuperTokens section/URL** for the feature (passwordless, thirdparty, sessions, FDI, multitenancy, etc.).
+3. If the work touches the database or SQL: also open the **Doltgres** section of that file (and `AI_DOCS/dolt-reference/` when present).
+4. **State in one plain sentence** what SuperTokens (or the KB) says the correct behavior is — then implement Briven-branded on Doltgres.
+5. **Do not invent** login shapes, magic-link hosts, OAuth flows, or cookie rules from memory alone.
+
+### Forbidden
+
+- Shipping Auth changes without reading `docs/knowledge-base.md` first.
+- “Looks reasonable” / assume / guess when SuperTokens already documents the flow.
+- Abandoning briven-engine / architecture after one SQL error without Doltgres docs + notifying flndrn.
+
+### After Auth changes
+
+- Prefer prove on a real project path (e.g. mavi pay / ISY) with evidence — not “code looks fine.”
+
+**Library path:** `docs/knowledge-base.md`  
+**Purpose:** SuperTokens as product/architecture map; Briven stays Briven-branded on Doltgres.
+
+---
+
+## Other standing notes
+
+- Product walls, multi-tenant isolation, `pk_briven_auth_` public keys, no inventing Clerk/Firebase as the platform engine.
+- Infra compose logging caps and Docker rules: see `infra/CLAUDE.md` and `docs/DOCKER.md` when editing `infra/`.
+- Deploy: France Briven compose + `scripts/safe-redeploy-service.sh`; batch deploys when possible.

apps/api/drizzle/migrations/0056_service_badges.sql

@@ -0,0 +1,28 @@
+-- Standard project-scoped service badges: one badge → one product wall.
+-- db = Doltgres, s3 = MinIO/S3, auth = SuperTokens-style M2M, pay = reserved.
+-- Doltgres-safe: no DO $$ exception blocks (unsupported on wire path).
+CREATE TABLE IF NOT EXISTS "service_badges" (
+	"id" text PRIMARY KEY NOT NULL,
+	"project_id" text NOT NULL,
+	"product" text NOT NULL,
+	"name" text NOT NULL,
+	"role" text DEFAULT 'developer' NOT NULL,
+	"prefix" text NOT NULL,
+	"suffix" varchar(4) NOT NULL,
+	"hash" text,
+	"storage_key_id" text,
+	"m2m_client_id" text,
+	"created_by" text,
+	"last_used_at" timestamp with time zone,
+	"expires_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"revoked_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "service_badges_hash_idx" ON "service_badges" ("hash");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "service_badges_project_product_idx" ON "service_badges" ("project_id","product");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "service_badges_m2m_client_idx" ON "service_badges" ("m2m_client_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "service_badges_storage_key_idx" ON "service_badges" ("storage_key_id");

apps/api/drizzle/migrations/meta/_journal.json

@@ -281,6 +281,27 @@
 			"when": 1780910000000,
 			"tag": "0053_auth_domain",
 			"breakpoints": true
+		},
+		{
+			"idx": 40,
+			"version": "7",
+			"when": 1781000000000,
+			"tag": "0054_auth_team_seats",
+			"breakpoints": true
+		},
+		{
+			"idx": 41,
+			"version": "7",
+			"when": 1781010000000,
+			"tag": "0055_webhook_ip_allowlist",
+			"breakpoints": true
+		},
+		{
+			"idx": 42,
+			"version": "7",
+			"when": 1781020000000,
+			"tag": "0056_service_badges",
+			"breakpoints": true
 		}
 	]
 }

apps/api/scripts/idp-e2e-proof.mjs

@@ -0,0 +1,183 @@
+/**
+ * Briven Auth OIDC IdP E2E proof (service-level, Doltgres).
+ *
+ * Confidential client + public PKCE client:
+ *   create client → auth request → consent/code → token → userinfo → refresh → revoke → introspect
+ *
+ *   cd apps/api
+ *   BRIVEN_ENGINE_DATABASE_URL=... BRIVEN_DATA_PLANE_URL=... \
+ *   BRIVEN_AUTH_CORE_ENABLED=true BRIVEN_ENV=development \
+ *   BRIVEN_API_ORIGIN=https://api.briven.tech BRIVEN_WEB_ORIGIN=https://briven.tech \
+ *   BRIVEN_BETTER_AUTH_SECRET=dev-secret-at-least-32-chars-long!! \
+ *   bun scripts/idp-e2e-proof.mjs
+ */
+
+process.env.BRIVEN_AUTH_CORE_ENABLED = 'true';
+process.env.BRIVEN_ENV = process.env.BRIVEN_ENV ?? 'development';
+process.env.BRIVEN_ENGINE_DATABASE_URL =
+  process.env.BRIVEN_ENGINE_DATABASE_URL ??
+  'postgres://postgres:devpass@127.0.0.1:5434/briven_engine?sslmode=disable';
+process.env.BRIVEN_DATA_PLANE_URL =
+  process.env.BRIVEN_DATA_PLANE_URL ??
+  'postgres://postgres:devpass@127.0.0.1:5434/postgres?sslmode=disable';
+process.env.BRIVEN_API_ORIGIN =
+  process.env.BRIVEN_API_ORIGIN ?? 'https://api.briven.tech';
+process.env.BRIVEN_WEB_ORIGIN =
+  process.env.BRIVEN_WEB_ORIGIN ?? 'https://briven.tech';
+process.env.BRIVEN_BETTER_AUTH_SECRET =
+  process.env.BRIVEN_BETTER_AUTH_SECRET ?? 'dev-secret-at-least-32-chars-long!!';
+
+import { createHash, randomBytes } from 'node:crypto';
+
+const { ensureBrivenEngineDatabase } = await import(
+  '../src/services/auth-core/ensure-db.ts'
+);
+const { initAuthCoreSdk } = await import('../src/services/auth-core/engine.ts');
+const { signUpEmailPassword } = await import(
+  '../src/services/auth-core/emailpassword.ts'
+);
+const { createOidcClient } = await import(
+  '../src/services/auth-core/idp-clients.ts'
+);
+const {
+  createAuthRequest,
+  issueAuthCodeAndRedirect,
+  exchangeAuthorizationCode,
+  exchangeRefreshToken,
+  buildUserInfo,
+  revokeToken,
+  introspectToken,
+  discoveryDocument,
+} = await import('../src/services/auth-core/idp-flow.ts');
+const { getOidcJwks } = await import('../src/services/auth-core/idp-signing.ts');
+
+function fail(msg, extra) {
+  console.error('FAIL', msg, extra ?? '');
+  process.exit(1);
+}
+function ok(msg) {
+  console.log('ok', msg);
+}
+
+console.log('=== IdP E2E proof (briven-engine OIDC) ===');
+
+const db = await ensureBrivenEngineDatabase();
+if (!db.ok) fail('ensure db', db);
+if (!(await initAuthCoreSdk())) fail('init sdk');
+
+const doc = discoveryDocument();
+if (!doc.authorization_endpoint || !doc.token_endpoint || !doc.jwks_uri) {
+  fail('discovery missing endpoints', doc);
+}
+ok('discovery shape');
+
+const jwks = await getOidcJwks();
+if (!jwks.keys?.length) fail('jwks empty');
+ok(`jwks keys=${jwks.keys.length}`);
+
+const projectId = `p_idp_${Date.now().toString(36)}`;
+const email = `idp_${Date.now()}@example.com`;
+const su = await signUpEmailPassword({
+  email,
+  password: 'IdpProof!99xx',
+  projectId,
+});
+if (su.status !== 'OK') fail('signup', su);
+const userId = su.user.id;
+ok(`user ${userId}`);
+
+const redirect = 'http://localhost:9999/cb';
+const conf = await createOidcClient({
+  projectId,
+  name: 'E2E Confidential',
+  redirectUris: [redirect],
+  isPublic: false,
+});
+if (!conf.clientSecret) fail('confidential secret missing');
+ok(`confidential client ${conf.client.clientId}`);
+
+const authReq = await createAuthRequest({
+  client: conf.client,
+  redirectUri: redirect,
+  scope: 'openid profile email offline_access',
+  state: 'st1',
+  nonce: 'n1',
+});
+const { redirectUrl } = await issueAuthCodeAndRedirect(authReq.id, userId);
+const code = new URL(redirectUrl).searchParams.get('code');
+if (!code) fail('no code in redirect', redirectUrl);
+ok('authorization code issued');
+
+const tok = await exchangeAuthorizationCode({
+  code,
+  redirectUri: redirect,
+  clientId: conf.client.clientId,
+  clientSecret: conf.clientSecret,
+});
+if (!tok.ok) fail('token exchange', tok);
+if (!tok.access_token || !tok.id_token) fail('missing tokens', tok);
+ok('token exchange (confidential)');
+
+const info = await buildUserInfo(tok.access_token);
+if (!info.ok) fail('userinfo', info);
+const sub = info.body?.sub;
+if (sub !== userId) fail('userinfo sub mismatch', info);
+ok(`userinfo sub=${sub}`);
+
+if (!tok.refresh_token) fail('expected refresh_token with offline_access');
+const refreshed = await exchangeRefreshToken({
+  refreshToken: tok.refresh_token,
+  clientId: conf.client.clientId,
+  clientSecret: conf.clientSecret,
+});
+if (!refreshed.ok) fail('refresh', refreshed);
+ok('refresh token');
+
+const intro = await introspectToken({
+  token: refreshed.access_token,
+  clientId: conf.client.clientId,
+  clientSecret: conf.clientSecret,
+});
+if (!intro.active) fail('introspect inactive', intro);
+ok('introspect active');
+
+const rev = await revokeToken({
+  token: tok.refresh_token,
+  clientId: conf.client.clientId,
+  clientSecret: conf.clientSecret,
+});
+if (!rev.ok) fail('revoke', rev);
+ok('revoke');
+
+// Public + PKCE
+const verifier = randomBytes(32).toString('base64url');
+const challenge = createHash('sha256').update(verifier).digest('base64url');
+const pub = await createOidcClient({
+  projectId,
+  name: 'E2E Public PKCE',
+  redirectUris: [redirect],
+  isPublic: true,
+});
+const authReq2 = await createAuthRequest({
+  client: pub.client,
+  redirectUri: redirect,
+  scope: 'openid email',
+  codeChallenge: challenge,
+  codeChallengeMethod: 'S256',
+});
+const { redirectUrl: redir2 } = await issueAuthCodeAndRedirect(
+  authReq2.id,
+  userId,
+);
+const code2 = new URL(redir2).searchParams.get('code');
+const tok2 = await exchangeAuthorizationCode({
+  code: code2,
+  redirectUri: redirect,
+  clientId: pub.client.clientId,
+  codeVerifier: verifier,
+});
+if (!tok2.ok) fail('pkce token', tok2);
+ok('public client + PKCE');
+
+console.log('=== IdP E2E proof PASSED ===');
+process.exit(0);

apps/api/scripts/isolation-fire-drill.mjs

@@ -0,0 +1,84 @@
+/**
+ * Auth isolation fire drill — two projects must not see each other's users.
+ *
+ *   bun scripts/isolation-fire-drill.mjs
+ *
+ * Requires local/engine Doltgres (same env as other proofs).
+ */
+
+process.env.BRIVEN_AUTH_CORE_ENABLED = 'true';
+process.env.BRIVEN_ENV = process.env.BRIVEN_ENV ?? 'development';
+process.env.BRIVEN_ENGINE_DATABASE_URL =
+  process.env.BRIVEN_ENGINE_DATABASE_URL ??
+  'postgres://postgres:devpass@127.0.0.1:5434/briven_engine?sslmode=disable';
+process.env.BRIVEN_DATA_PLANE_URL =
+  process.env.BRIVEN_DATA_PLANE_URL ??
+  'postgres://postgres:devpass@127.0.0.1:5434/postgres?sslmode=disable';
+
+const { ensureBrivenEngineDatabase } = await import(
+  '../src/services/auth-core/ensure-db.ts'
+);
+const { initAuthCoreSdk } = await import('../src/services/auth-core/engine.ts');
+const { signUpEmailPassword } = await import(
+  '../src/services/auth-core/emailpassword.ts'
+);
+const { listBrivenEngineUsers, getBrivenEngineUser } = await import(
+  '../src/services/auth-core/users.ts'
+);
+const { projectIdToTenantId } = await import(
+  '../src/services/auth-core/project-map.ts'
+);
+
+function fail(m, x) {
+  console.error('FAIL', m, x ?? '');
+  process.exit(1);
+}
+
+console.log('=== Isolation fire drill ===');
+if (!(await ensureBrivenEngineDatabase()).ok) fail('db');
+if (!(await initAuthCoreSdk())) fail('sdk');
+
+const a = `p_iso_a_${Date.now().toString(36)}`;
+const b = `p_iso_b_${Date.now().toString(36)}`;
+const emailA = `a_${Date.now()}@iso.test`;
+const emailB = `b_${Date.now()}@iso.test`;
+
+const ua = await signUpEmailPassword({
+  email: emailA,
+  password: 'IsoA!9999xx',
+  projectId: a,
+});
+const ub = await signUpEmailPassword({
+  email: emailB,
+  password: 'IsoB!9999xx',
+  projectId: b,
+});
+if (ua.status !== 'OK' || ub.status !== 'OK') fail('signup', { ua, ub });
+
+const listA = await listBrivenEngineUsers({
+  tenantId: projectIdToTenantId(a),
+  limit: 50,
+});
+const listB = await listBrivenEngineUsers({
+  tenantId: projectIdToTenantId(b),
+  limit: 50,
+});
+
+const idsA = new Set(listA.users.map((u) => u.id));
+const idsB = new Set(listB.users.map((u) => u.id));
+if (idsA.has(ub.user.id)) fail('project A list contains B user');
+if (idsB.has(ua.user.id)) fail('project B list contains A user');
+if (!idsA.has(ua.user.id)) fail('project A missing own user');
+if (!idsB.has(ub.user.id)) fail('project B missing own user');
+
+// Cross-tenant get by id without tenant should still resolve user, but
+// tenant-scoped get must miss.
+const cross = await getBrivenEngineUser(ua.user.id, {
+  tenantId: projectIdToTenantId(b),
+});
+if (cross) fail('B tenant can read A user by id', cross);
+
+console.log('ok project A users', listA.users.length);
+console.log('ok project B users', listB.users.length);
+console.log('=== Isolation fire drill PASSED ===');
+process.exit(0);

apps/api/src/db/schema.ts

@@ -1558,6 +1558,60 @@ export const mcpKeys = pgTable(
 export type McpKey = typeof mcpKeys.$inferSelect;
 export type NewMcpKey = typeof mcpKeys.$inferInsert;
 
+/* ─── service_badges (project-scoped agent pass — one product only) ───── */
+// Standard "staff pass" for machines/agents. Each badge opens exactly one
+// product wall inside one project:
+//   db   → Doltgres data plane (studio / query / tables) — bearer sb_db_…
+//   s3   → MinIO / S3 storage keys for this project's bucket
+//   auth → SuperTokens-style M2M client_credentials (briven-engine)
+//   pay  → reserved for Briven Pay (not minted yet)
+// Plaintext secrets are shown once; only a hash (db) or a link to the
+// underlying product credential (s3/auth) is stored.
+export const serviceBadgeProduct = ['db', 's3', 'auth', 'pay'] as const;
+export type ServiceBadgeProduct = (typeof serviceBadgeProduct)[number];
+
+export const serviceBadgeRole = ['viewer', 'developer', 'admin'] as const;
+export type ServiceBadgeRole = (typeof serviceBadgeRole)[number];
+
+export const serviceBadges = pgTable(
+  'service_badges',
+  {
+    id: id(),
+    projectId: text('project_id')
+      .notNull()
+      .references(() => projects.id, { onDelete: 'cascade' }),
+    // Product wall this badge opens. Never change after mint.
+    product: text('product').$type<ServiceBadgeProduct>().notNull(),
+    name: text('name').notNull(),
+    role: text('role').$type<ServiceBadgeRole>().notNull().default('developer'),
+    // Plaintext prefix constant for this product (sb_db_ / sb_s3_ / sb_auth_).
+    prefix: text('prefix').notNull(),
+    // Last 4 of the secret — safe dashboard hint.
+    suffix: varchar('suffix', { length: 4 }).notNull(),
+    // SHA-256 of bearer secret (product=db). Null for s3/auth (they use
+    // storage_keys / be_m2m_clients as the credential store).
+    hash: text('hash'),
+    // product=s3 → storage_keys.id
+    storageKeyId: text('storage_key_id'),
+    // product=auth → be_m2m_clients.client_id
+    m2mClientId: text('m2m_client_id'),
+    createdBy: text('created_by').references(() => users.id),
+    lastUsedAt: ts('last_used_at'),
+    expiresAt: ts('expires_at'),
+    createdAt: createdAt(),
+    revokedAt: ts('revoked_at'),
+  },
+  (t) => ({
+    hashIdx: uniqueIndex('service_badges_hash_idx').on(t.hash),
+    projectProductIdx: index('service_badges_project_product_idx').on(t.projectId, t.product),
+    m2mClientIdx: index('service_badges_m2m_client_idx').on(t.m2mClientId),
+    storageKeyIdx: index('service_badges_storage_key_idx').on(t.storageKeyId),
+  }),
+);
+
+export type ServiceBadge = typeof serviceBadges.$inferSelect;
+export type NewServiceBadge = typeof serviceBadges.$inferInsert;
+
 /* ─── tenant_secrets (per-tenant encrypted secrets — OAuth client secrets) ─ */
 // Persistence layer for the Layer-2 secret primitive in
 // services/tenant-secret-store.ts (HKDF-SHA256 per-tenant key +

apps/api/src/env.ts

@@ -176,10 +176,11 @@ const envSchema = z.object({
   // Override if you want product-specific routing later.
   BRIVEN_MIGRATIONS_INBOX: z.string().email().default('migrations@flndrn.com'),
 
-  // Konnos OAuth — Forgejo at code.konnos.org. Better Auth's generic OAuth
-  // plugin lets us reuse the same callback shape for any OAuth2/OIDC
-  // provider; the Forgejo endpoints (authorize / token / userinfo) are
-  // pinned below.
+  // Konnos OAuth for **briven.tech platform sign-in only** (Better Auth in
+  // lib/auth.ts). Customer projects do NOT use these — each project pastes
+  // its own Client ID + Secret under Auth → Providers (per-project rule,
+  // SuperTokens-style; flndrn 2026-07-27). Issuer/origin may still help
+  // endpoint defaults; prefer konnos.org product OAuth, not code.konnos.org Git.
   BRIVEN_KONNOS_CLIENT_ID: z.string().optional(),
   BRIVEN_KONNOS_CLIENT_SECRET: z.string().optional(),
   BRIVEN_KONNOS_ISSUER: z.string().url().default('https://code.konnos.org'),
@@ -271,6 +272,8 @@ const envSchema = z.object({
   // on briven auth sign-up / sign-in flows. The site key is per-tenant config;
   // this secret verifies tokens server-side.
   BRIVEN_TURNSTILE_SECRET_KEY: z.string().optional(),
+  /** Public site key for app widgets when Turnstile is required on FDI. */
+  BRIVEN_TURNSTILE_SITE_KEY: z.string().optional(),
 });
 
 export type Env = z.infer<typeof envSchema>;

apps/api/src/index.ts

@@ -22,6 +22,7 @@ import { adminManifestRouter } from './routes/admin-manifest.js';
 import { adminTimeseriesRouter } from './routes/admin-timeseries.js';
 import { aiRouter } from './routes/ai.js';
 import { apiKeysRouter } from './routes/api-keys.js';
+import { serviceBadgesRouter } from './routes/service-badges.js';
 import { authRouter } from './routes/auth.js';
 import { authCliRouter } from './routes/auth-cli.js';
 import { authProductRetiredRouter } from './routes/auth-product-retired.js';
@@ -35,10 +36,13 @@ import { authCoreRolesRouter } from './routes/auth-core-roles.js';
 import { authCoreKeysRouter } from './routes/auth-core-keys.js';
 import { authCoreM2mRouter } from './routes/auth-core-m2m.js';
 import { authCoreIdpRouter } from './routes/auth-core-idp.js';
+import { authCoreMigrationRouter } from './routes/auth-core-migration.js';
+import { authCoreAiRouter } from './routes/auth-core-ai.js';
 import { authCoreProjectRouter } from './routes/auth-core-project.js';
 import { authCoreSsoRouter } from './routes/auth-core-sso.js';
 import { authCoreRouter } from './routes/auth-core.js';
 import { initAuthCoreSdk } from './services/auth-core/engine.js';
+import { brivenEngineFdiRateLimit } from './services/auth-core/abuse.js';
 // Option B Phase 7+: yellow tabs + enterprise SAML/OIDC on briven-engine.
 import { billingRouter } from './routes/billing.js';
 import { brandingPublicRouter } from './routes/branding-public.js';
@@ -167,12 +171,17 @@ app.route('/', mediaRouter);
 
 app.route('/', rootRouter);
 app.route('/', healthRouter);
-app.route('/', authRouter);
+// CLI token mint MUST mount before Better Auth's /v1/auth/* catch-all.
+// Otherwise POST /v1/auth/cli-token is swallowed by Better Auth → 404 →
+// dashboard "Allow CLI" shows a 500 error page (flndrn 2026-07-29).
 app.route('/', authCliRouter);
+app.route('/', authRouter);
 app.route('/', meRouter);
 // Briven Auth Option B Phase 7: FDI login + yellow dashboard + keys/providers/enterprise.
 // Platform operator login stays on authRouter (/v1/auth/* Better Auth for briven.tech).
 app.route('/', authCoreStatusRouter);
+// FDI abuse protection (IP rate limit) — must run before FDI handlers.
+app.use('/v1/auth-core/fdi/*', brivenEngineFdiRateLimit());
 app.route('/', authCoreFdiRouter);
 app.route('/', authCoreSessionRouter);
 app.route('/', authCoreLoginMethodsRouter);
@@ -182,20 +191,25 @@ app.route('/', authCoreRolesRouter);
 app.route('/', authCoreKeysRouter);
 app.route('/', authCoreM2mRouter); // M2M client credentials + /oauth/token
 app.route('/', authCoreIdpRouter); // OIDC IdP (Briven as SuperTokens-class provider)
+app.route('/', authCoreMigrationRouter); // bulk user import
+app.route('/', authCoreAiRouter); // AI agent tokens
 app.route('/', authCoreProjectRouter);
 app.route('/', authCoreSsoRouter); // SAML + OIDC enterprise SSO
 app.route('/', authCoreRouter); // workspace + enable Auth
 app.route('/', authProductRetiredRouter);
-log.info('auth_product_idp_m2m_enterprise', {
-  note: 'briven-engine FDI + dashboard + SSO + M2M + OIDC IdP provider',
+log.info('auth_product_parity_surface', {
+  note: 'briven-engine FDI + dashboard + SSO + M2M + OIDC IdP + migration + AI tokens',
   engine: 'briven-engine',
   appLoginReady: true,
   m2mToken: '/v1/auth-core/oauth/token',
   oidcIssuer: '/v1/auth-core/oidc',
+  migration: '/v1/auth-core/migration/users',
+  aiMe: '/v1/auth-core/ai/me',
   platformLogin: '/v1/auth/*',
 });
 app.route('/', projectsRouter);
 app.route('/', apiKeysRouter);
+app.route('/', serviceBadgesRouter);
 app.route('/', membersRouter);
 app.route('/', deploymentsRouter);
 app.route('/', invokeRouter);

apps/api/src/lib/auth.ts

@@ -143,8 +143,8 @@ export const auth = betterAuth({
   },
 
   // Google + GitHub use Better Auth's built-in socialProviders config.
-  // Konnos (Forgejo at code.konnos.org) uses the genericOAuth plugin
-  // since Forgejo isn't on Better Auth's hard-coded list.
+  // Konnos (Git at code.konnos.org) uses the genericOAuth plugin
+  // since that Git host isn't on Better Auth's hard-coded list.
   socialProviders: {
     ...(env.BRIVEN_GOOGLE_CLIENT_ID && env.BRIVEN_GOOGLE_CLIENT_SECRET
       ? {
@@ -186,11 +186,10 @@ export const auth = betterAuth({
         await sendMagicLink(email, url);
       },
     }),
-    // Konnos (Forgejo) OAuth — endpoints follow Forgejo's gitea-compatible
-    // shape: /login/oauth/authorize, /login/oauth/access_token,
-    // /api/v1/user. Forgejo's userinfo endpoint returns
-    // {id, login, email, full_name, avatar_url}; mapProfileToUser
-    // adapts it to Better Auth's expected shape.
+    // Konnos (Git at code.konnos.org) OAuth — endpoints follow the host's
+    // OAuth shape: /login/oauth/authorize, /login/oauth/access_token,
+    // /api/v1/user. Userinfo returns {id, login, email, full_name, avatar_url};
+    // mapProfileToUser adapts it to Better Auth's expected shape.
     ...(env.BRIVEN_KONNOS_CLIENT_ID && env.BRIVEN_KONNOS_CLIENT_SECRET
       ? [
           genericOAuth({

apps/api/src/lib/cli-jwt.ts

@@ -43,7 +43,15 @@ export async function verifyCliToken(token: string): Promise<CliTokenPayload> {
   if (payload.scope !== 'cli') {
     throw new Error('cli-jwt: wrong scope');
   }
-  if (typeof payload.sub !== 'string' || !payload.sub.startsWith('u_')) {
+  // Platform users (Better Auth) use opaque nanoid ids, not u_… engine ids.
+  // The users-table lookup in requireAuth is the real existence check.
+  // Reject empty / absurd subjects only (flndrn 2026-07-29: invalid cli token
+  // after successful Allow because sub was WUKq… without a u_ prefix).
+  if (
+    typeof payload.sub !== 'string' ||
+    payload.sub.length < 8 ||
+    payload.sub.length > 128
+  ) {
     throw new Error('cli-jwt: missing or invalid subject');
   }
   return payload as CliTokenPayload;

apps/api/src/lib/email.ts

@@ -108,13 +108,16 @@ function getSmtpTransporter(): Transporter {
 }
 
 /**
- * The From: SMTP sends use. Prefers the explicit BRIVEN_SMTP_FROM (e.g.
- * "Briven <noreply@briven.tech>") so the operator can align it with their
- * provider's verified sender; falls back to a per-call override, then the
- * global fromAddress().
+ * The From: SMTP sends use.
+ * Prefer per-call override first (project Auth branding:
+ * `Pando <noreply@pando.so>`) — SuperTokens-style multi-app senders.
+ * Then platform BRIVEN_SMTP_FROM, then global default.
+ *
+ * Note: the mail provider must allow the domain (SPF/DKIM). Unverified
+ * custom domains may bounce; operators set domain in Auth → branding.
  */
 function smtpFrom(args: SendArgs): string {
-  return env.BRIVEN_SMTP_FROM ?? args.from ?? fromAddress();
+  return args.from ?? env.BRIVEN_SMTP_FROM ?? fromAddress();
 }
 
 /**
@@ -220,11 +223,20 @@ async function send(label: string, args: SendArgs): Promise<void> {
     return;
   }
 
-  // Primary path: real SMTP provider. mittera accepts sends but never
-  // delivers, so once SMTP is configured it takes precedence over mittera.
+  // Primary path: real SMTP (Resend / Mailgun / SES via SMTP).
+  // If SMTP is misconfigured (bad key), fall through to mittera so Auth OTP
+  // does not hard-fail (flndrn 2026-07-29: 535 invalid login broke krypco OTP).
   if (isSmtpConfigured()) {
-    await sendViaSmtp(label, args);
-    return;
+    try {
+      await sendViaSmtp(label, args);
+      return;
+    } catch (err) {
+      log.warn('smtp_send_failed_fallback_mittera', {
+        label,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      // continue to mittera / dev below
+    }
   }
 
   // Fallback: mittera's REST API (kept as the fallback, not deleted).
@@ -857,7 +869,7 @@ function shell(title: string, body: string): string {
           </table>
           <h2 style="font-family:system-ui,sans-serif;font-size:18px;font-weight:500;margin:0 0 16px 0">${title}</h2>
           <div style="color:#9ba3af;font-size:15px">${body}</div>
-          <p style="color:#6b7280;font-size:13px;margin-top:32px;border-top:1px solid #1e2128;padding-top:16px">
+          <p style="color:#6b7280;font-size:12px;margin-top:32px;border-top:1px solid #1e2128;padding-top:16px">
             briven · <a style="color:#9ba3af" href="https://${domain}">${domain}</a><br/>
             made with <span style="color:#e8344a">&#9829;</span> in Flanders by flndrn<br/>
             100% self-funded, sustainable &amp; independent<br/>

apps/api/src/lib/geoip.ts

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+
 import { open, type CityResponse, type Reader } from 'maxmind';
 
 import { env } from '../env.js';
@@ -7,17 +9,55 @@ export interface GeoLookup {
   city: string | null;
   region: string | null;
   country: string | null;
+  /** MaxMind location centroid — used for nearest-city fallback when city is null. */
+  latitude: number | null;
+  longitude: number | null;
+  /** Approximate accuracy radius in km (MaxMind). */
+  accuracyRadiusKm: number | null;
 }
 
 let readerPromise: Promise<Reader<CityResponse> | null> | null = null;
 
+/** Common install locations when BRIVEN_GEOIP_DB_PATH is unset. */
+const GEOIP_CANDIDATES = [
+  '/var/lib/GeoIP/GeoLite2-City.mmdb',
+  '/usr/share/GeoIP/GeoLite2-City.mmdb',
+  '/usr/local/share/GeoIP/GeoLite2-City.mmdb',
+  '/data/geoip/GeoLite2-City.mmdb',
+  '/app/data/GeoLite2-City.mmdb',
+];
+
+function resolveGeoipPath(): string | null {
+  if (env.BRIVEN_GEOIP_DB_PATH?.trim()) return env.BRIVEN_GEOIP_DB_PATH.trim();
+  for (const p of GEOIP_CANDIDATES) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
 async function getReader(): Promise<Reader<CityResponse> | null> {
-  if (!env.BRIVEN_GEOIP_DB_PATH) return null;
   if (!readerPromise) {
-    readerPromise = open<CityResponse>(env.BRIVEN_GEOIP_DB_PATH).catch((err: unknown) => {
-      log.warn('geoip_db_open_failed', { path: env.BRIVEN_GEOIP_DB_PATH, message: err instanceof Error ? err.message : String(err) });
+    const path = resolveGeoipPath();
+    if (!path) {
+      readerPromise = Promise.resolve(null);
+      log.warn('geoip_db_missing', {
+        message:
+          'No GeoLite2-City.mmdb — set BRIVEN_GEOIP_DB_PATH so Auth emails can show city/country',
+      });
       return null;
-    });
+    }
+    readerPromise = open<CityResponse>(path)
+      .then((r) => {
+        log.info('geoip_db_open_ok', { path });
+        return r;
+      })
+      .catch((err: unknown) => {
+        log.warn('geoip_db_open_failed', {
+          path,
+          message: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+      });
   }
   return readerPromise;
 }
@@ -48,8 +88,32 @@ export async function lookupIp(ip: string | null | undefined): Promise<GeoLookup
     if (response) {
       const city = response.city?.names?.en ?? null;
       const region = response.subdivisions?.[0]?.names?.en ?? null;
-      const country = response.country?.names?.en ?? response.registered_country?.names?.en ?? null;
-      if (city || region || country) return { city, region, country };
+      const country =
+        response.country?.names?.en ??
+        response.registered_country?.names?.en ??
+        null;
+      const latitude =
+        typeof response.location?.latitude === 'number'
+          ? response.location.latitude
+          : null;
+      const longitude =
+        typeof response.location?.longitude === 'number'
+          ? response.location.longitude
+          : null;
+      const accuracyRadiusKm =
+        typeof response.location?.accuracy_radius === 'number'
+          ? response.location.accuracy_radius
+          : null;
+      if (city || region || country || (latitude != null && longitude != null)) {
+        return {
+          city,
+          region,
+          country,
+          latitude,
+          longitude,
+          accuracyRadiusKm,
+        };
+      }
     }
   } catch {
     // Local MaxMind DB read failure — return null; caller stores the raw IP only.

apps/api/src/middleware/csrf.ts

@@ -2,7 +2,10 @@ import type { MiddlewareHandler } from 'hono';
 
 import { env } from '../env.js';
 import { log } from '../lib/logger.js';
-import { isRegisteredOrigin } from '../services/auth-origin-allowlist.js';
+import {
+  brivenOwnOrigins,
+  isRegisteredOrigin,
+} from '../services/auth-origin-allowlist.js';
 import type { Session } from './session.js';
 
 const UNSAFE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
@@ -99,9 +102,10 @@ export function shouldRejectAsCsrf(input: {
 }
 
 function trustedOrigins(): string[] {
-  const list = new Set<string>([env.BRIVEN_API_ORIGIN, env.BRIVEN_WEB_ORIGIN]);
+  // Prefer the shared product-origin list (includes app./admin. aliases).
+  const list = new Set<string>(brivenOwnOrigins());
   for (const o of env.BRIVEN_TRUSTED_ORIGINS.split(',').map((s) => s.trim())) {
-    if (o) list.add(o);
+    if (o) list.add(o.replace(/\/$/, ''));
   }
   return [...list];
 }

apps/api/src/middleware/project-auth.ts

@@ -9,7 +9,11 @@ import { log } from '../lib/logger.js';
 import { hasRoleAtLeast } from '../services/access.js';
 import { resolveApiKey } from '../services/api-keys.js';
 import { getProjectAccessForUser } from '../services/projects.js';
-import type { MemberRole } from '../db/schema.js';
+import {
+  looksLikeServiceBadge,
+  resolveDbServiceBadge,
+} from '../services/service-badges.js';
+import type { MemberRole, ServiceBadgeProduct } from '../db/schema.js';
 import type { Session, User } from './session.js';
 
 /**
@@ -55,6 +59,7 @@ export const requireProjectAuth =
       const access = await getProjectAccessForUser(projectId, user.id);
       c.set('apiKeyId', null);
       c.set('projectRole', access.role);
+      c.set('serviceBadgeProduct', null);
       await next();
       return;
     }
@@ -65,6 +70,21 @@ export const requireProjectAuth =
       throw new UnauthorizedError();
     }
 
+    // Service badge (product-scoped agent pass). Today only product=db is a
+    // bearer; s3 uses MinIO keys and auth uses M2M client_credentials.
+    if (looksLikeServiceBadge(token)) {
+      const badge = await resolveDbServiceBadge(token);
+      if (!badge) throw new UnauthorizedError('invalid or revoked service badge');
+      if (badge.projectId !== projectId) {
+        throw new ForbiddenError('service badge does not belong to this project');
+      }
+      c.set('apiKeyId', badge.badgeId);
+      c.set('projectRole', badge.role as MemberRole);
+      c.set('serviceBadgeProduct', badge.product as ServiceBadgeProduct);
+      await next();
+      return;
+    }
+
     // Non-brk bearer: try M2M JWT first, then CLI JWT.
     if (!token.startsWith('brk_')) {
       // M2M client_credentials access token (scope=m2m).
@@ -76,6 +96,10 @@ export const requireProjectAuth =
         }
         c.set('apiKeyId', m2m.client_id);
         c.set('projectRole', m2m.role as MemberRole);
+        // M2M JWT keeps project-wide access at its role (existing SuperTokens-
+        // style behaviour). Product isolation for minting lives on the badge
+        // registry; the short-lived token is the machine session for the project.
+        c.set('serviceBadgeProduct', null);
         await next();
         return;
       } catch (err) {
@@ -109,6 +133,7 @@ export const requireProjectAuth =
       const access = await getProjectAccessForUser(projectId, userRow.id);
       c.set('apiKeyId', null);
       c.set('projectRole', access.role);
+      c.set('serviceBadgeProduct', null);
       await next();
       return;
     }
@@ -121,6 +146,7 @@ export const requireProjectAuth =
 
     c.set('apiKeyId', resolved.keyId);
     c.set('projectRole', resolved.role);
+    c.set('serviceBadgeProduct', null);
     await next();
     return;
   };

apps/api/src/middleware/service-product.ts

@@ -0,0 +1,30 @@
+/**
+ * Product wall for service badges.
+ *
+ * After requireProjectAuth, if the caller authenticated with a service badge
+ * (c.var.serviceBadgeProduct is set), they may only hit routes for that product.
+ * Humans (session), deploy keys (brk_), CLI JWT, and Auth M2M JWTs are not
+ * product-locked — they keep full project access for their role.
+ */
+
+import { ForbiddenError } from '@briven/shared';
+import type { MiddlewareHandler } from 'hono';
+
+import type { ServiceBadgeProduct } from '../db/schema.js';
+import { serviceBadgeAllowedOnRoute } from '../services/service-badges.js';
+
+/**
+ * Require that a service-badge caller is allowed on this product wall.
+ * Pass the product this route family belongs to (db | s3 | auth).
+ */
+export const requireServiceProduct =
+  (routeProduct: ServiceBadgeProduct): MiddlewareHandler =>
+  async (c, next) => {
+    const badgeProduct = c.get('serviceBadgeProduct') as ServiceBadgeProduct | null | undefined;
+    if (!serviceBadgeAllowedOnRoute(badgeProduct ?? null, routeProduct)) {
+      throw new ForbiddenError(
+        `this service badge only opens the ${badgeProduct} product — not ${routeProduct}`,
+      );
+    }
+    await next();
+  };

apps/api/src/routes/auth-core-ai.ts

@@ -0,0 +1,139 @@
+/**
+ * AI agent token admin + verify (SuperTokens-class AI auth first cut).
+ *
+ * Dashboard (project admin):
+ *   GET/POST /v1/auth-core/projects/:projectId/ai/agents
+ *   DELETE   /v1/auth-core/projects/:projectId/ai/agents/:tokenId
+ *
+ * Public verify (Bearer brai_…):
+ *   GET /v1/auth-core/ai/me
+ */
+
+import { Hono } from 'hono';
+
+import { requireAuthCoreProject } from '../middleware/auth-core-guard.js';
+import { BRIVEN_ENGINE_ID } from '../services/auth-core/engine.js';
+import {
+  createAiAgentToken,
+  listAiAgentTokens,
+  revokeAiAgentToken,
+  verifyAiAgentToken,
+} from '../services/auth-core/ai-auth.js';
+import type { AppEnv } from '../types/app-env.js';
+import type { User } from '../middleware/session.js';
+
+export const authCoreAiRouter = new Hono<AppEnv>();
+
+authCoreAiRouter.use(
+  '/v1/auth-core/projects/:projectId/ai/agents',
+  ...requireAuthCoreProject('admin'),
+);
+authCoreAiRouter.use(
+  '/v1/auth-core/projects/:projectId/ai/agents/*',
+  ...requireAuthCoreProject('admin'),
+);
+
+authCoreAiRouter.get(
+  '/v1/auth-core/projects/:projectId/ai/agents',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    try {
+      const agents = await listAiAgentTokens(projectId);
+      return c.json({ engine: BRIVEN_ENGINE_ID, projectId, agents });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'list_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
+authCoreAiRouter.post(
+  '/v1/auth-core/projects/:projectId/ai/agents',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    let body: { agentName?: string; scopes?: string[]; ttlHours?: number } = {};
+    try {
+      body = await c.req.json();
+    } catch {
+      body = {};
+    }
+    const user = c.get('user') as User | null;
+    try {
+      const created = await createAiAgentToken({
+        projectId,
+        agentName: body.agentName ?? 'agent',
+        scopes: body.scopes,
+        ttlHours: body.ttlHours,
+        createdBy: user?.id ?? null,
+      });
+      return c.json({
+        engine: BRIVEN_ENGINE_ID,
+        projectId,
+        agent: created.token,
+        /** Shown once */
+        plaintext: created.plaintext,
+        note: 'Copy the token now — it is not shown again. Use Authorization: Bearer brai_…',
+      });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'create_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        400,
+      );
+    }
+  },
+);
+
+authCoreAiRouter.delete(
+  '/v1/auth-core/projects/:projectId/ai/agents/:tokenId',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    const tokenId = c.req.param('tokenId');
+    try {
+      await revokeAiAgentToken(projectId, tokenId);
+      return c.json({ engine: BRIVEN_ENGINE_ID, ok: true, projectId, tokenId });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'revoke_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        404,
+      );
+    }
+  },
+);
+
+authCoreAiRouter.get('/v1/auth-core/ai/me', async (c) => {
+  const auth = c.req.header('authorization') ?? '';
+  const token = auth.startsWith('Bearer ') ? auth.slice(7).trim() : '';
+  if (!token) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, authenticated: false, code: 'unauthorized' },
+      401,
+    );
+  }
+  const verified = await verifyAiAgentToken(token);
+  if (!verified) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, authenticated: false, code: 'invalid_token' },
+      401,
+    );
+  }
+  return c.json({
+    engine: BRIVEN_ENGINE_ID,
+    authenticated: true,
+    kind: 'ai_agent',
+    ...verified,
+  });
+});

apps/api/src/routes/auth-core-fdi.phase2.test.ts

@@ -29,23 +29,24 @@ describe('Phase 2 FDI routes mounted', () => {
     app.route('/', authCoreSessionRouter);
   });
 
-  test('signup returns not-ready or field error (not 404)', async () => {
+  test('signup without project/key is unauthorized (not 404)', async () => {
     const res = await app.request('http://localhost/v1/auth-core/fdi/signup', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({}),
     });
-    expect([400, 503]).toContain(res.status);
+    // Locked FDI: 401 without project+pk; 503 if engine not ready.
+    expect([401, 403, 400, 503]).toContain(res.status);
     expect(res.status).not.toBe(404);
   });
 
-  test('signin returns not-ready or field error (not 404)', async () => {
+  test('signin without project/key is unauthorized (not 404)', async () => {
     const res = await app.request('http://localhost/v1/auth-core/fdi/signin', {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
       body: JSON.stringify({}),
     });
-    expect([400, 503]).toContain(res.status);
+    expect([401, 403, 400, 503]).toContain(res.status);
     expect(res.status).not.toBe(404);
   });
 

apps/api/src/routes/auth-core-fdi.ts

@@ -2,7 +2,8 @@
  * briven-engine FDI-compatible routes — implemented on Doltgres only.
  * No SuperTokens Core process.
  *
- * Public end-user endpoints (apps proxy here first-party).
+ * End-user recipes (apps proxy first-party). Locked: project + pk_briven_auth_
+ * required; soft-disable + method flags enforced (security deep-test 2026-07-27).
  */
 
 import { Hono } from 'hono';
@@ -13,6 +14,7 @@ import {
 } from '../services/auth-core/emailpassword.js';
 import {
   createEngineSession,
+  refreshEngineSession,
   revokeEngineSession,
 } from '../services/auth-core/native-session.js';
 import {
@@ -44,14 +46,44 @@ import {
 import { env } from '../env.js';
 import { requireTurnstileIfConfigured } from '../services/auth-core/abuse.js';
 import { isAuthCoreInitialized } from '../services/auth-core/engine.js';
-import { resolveAuthTenantFromHeaders } from '../services/auth-core/request-tenant.js';
+import {
+  methodFlagDenied,
+  requireFdiProjectKey,
+  type FdiProjectContext,
+} from '../services/auth-core/fdi-guard.js';
+import {
+  consumeMfaChallenge,
+  issueMfaChallenge,
+} from '../services/auth-core/mfa-challenge.js';
+import { getBrivenEngineAppOrigins } from '../services/auth-core/project-config.js';
 import { verifyAuthCoreSession } from '../services/auth-core/session.js';
 import type { AppEnv } from '../types/app-env.js';
 
-export const authCoreFdiRouter = new Hono<AppEnv>();
+type FdiEnv = AppEnv & {
+  Variables: AppEnv['Variables'] & {
+    fdiCtx: FdiProjectContext;
+  };
+};
+
+export const authCoreFdiRouter = new Hono<FdiEnv>();
 
 const FDI = '/v1/auth-core/fdi';
 
+/** Lock every FDI recipe behind project + public auth key. */
+authCoreFdiRouter.use(`${FDI}/*`, async (c, next) => {
+  if (c.req.method.toUpperCase() === 'OPTIONS') {
+    await next();
+    return;
+  }
+  const ctx = await requireFdiProjectKey(c);
+  if (ctx instanceof Response) {
+    return ctx;
+  }
+  c.set('fdiCtx', ctx);
+  await next();
+  return;
+});
+
 /** Cookie holds session handle (Doltgres lookup key). Secure in production. */
 function setSessionCookies(
   c: { header: (n: string, v: string, o?: { append?: boolean }) => void },
@@ -102,7 +134,14 @@ function notReady() {
 
 authCoreFdiRouter.post(`${FDI}/signup`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
+  const denied = methodFlagDenied(fdi.methods, 'emailPassword');
+  if (denied) {
+    return c.json(
+      { status: 'METHOD_DISABLED', engine: 'briven-engine', message: denied },
+      403,
+    );
+  }
   let body: {
     formFields?: Array<{ id: string; value: string }>;
     email?: string;
@@ -127,8 +166,8 @@ authCoreFdiRouter.post(`${FDI}/signup`, async (c) => {
   const result = await signUpEmailPassword({
     email,
     password,
-    tenantId: tenant?.tenantId,
-    projectId: tenant?.projectId,
+    tenantId: fdi.tenantId,
+    projectId: fdi.projectId,
   });
   if (result.status !== 'OK') {
     return c.json({ status: result.status });
@@ -137,11 +176,10 @@ authCoreFdiRouter.post(`${FDI}/signup`, async (c) => {
     userId: result.user.id,
     tenantId: result.user.tenantId,
   });
-  // Phase 2: cookie value = session handle (lookup key on Doltgres).
   setSessionCookies(c, session);
   c.header('x-briven-engine', 'briven-engine');
   c.header('x-briven-session-handle', session.sessionHandle);
-  if (tenant) c.header('x-briven-tenant-id', tenant.tenantId);
+  c.header('x-briven-tenant-id', fdi.tenantId);
   return c.json({
     status: 'OK',
     user: { id: result.user.id, emails: [result.user.email] },
@@ -156,7 +194,14 @@ authCoreFdiRouter.post(`${FDI}/signup`, async (c) => {
 
 authCoreFdiRouter.post(`${FDI}/signin`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
+  const denied = methodFlagDenied(fdi.methods, 'emailPassword');
+  if (denied) {
+    return c.json(
+      { status: 'METHOD_DISABLED', engine: 'briven-engine', message: denied },
+      403,
+    );
+  }
   let body: {
     formFields?: Array<{ id: string; value: string }>;
     email?: string;
@@ -181,22 +226,28 @@ authCoreFdiRouter.post(`${FDI}/signin`, async (c) => {
   const result = await signInEmailPassword({
     email,
     password,
-    tenantId: tenant?.tenantId,
-    projectId: tenant?.projectId,
+    tenantId: fdi.tenantId,
+    projectId: fdi.projectId,
   });
   if (result.status !== 'OK') {
     return c.json({ status: result.status });
   }
-  // Phase 5: if TOTP enrolled, require second factor before issuing session.
+  // SuperTokens-style MFA: first factor OK → challenge; no session yet.
   if (await userHasVerifiedTotp(result.user.id)) {
+    const mfaChallenge = issueMfaChallenge({
+      userId: result.user.id,
+      tenantId: result.user.tenantId,
+    });
     return c.json({
       status: 'MFA_REQUIRED',
       factor: 'totp',
       userId: result.user.id,
       tenantId: result.user.tenantId,
+      mfaChallenge,
       engine: 'briven-engine',
       storage: 'doltgres',
-      message: 'password ok — send TOTP code to /v1/auth-core/fdi/totp/verify',
+      message:
+        'password ok — POST /v1/auth-core/fdi/totp/verify with userId, code, mfaChallenge',
     });
   }
   const session = await createEngineSession({
@@ -241,25 +292,82 @@ authCoreFdiRouter.post(`${FDI}/signout`, async (c) => {
 /** Passwordless: create email/SMS code (magic link + OTP). Phase 3. */
 authCoreFdiRouter.post(`${FDI}/signinup/code`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   let body: {
     email?: string;
     phoneNumber?: string;
     flowType?: 'USER_INPUT_CODE' | 'MAGIC_LINK' | 'USER_INPUT_CODE_AND_MAGIC_LINK';
     magicLinkBaseUrl?: string;
+    turnstileToken?: string;
   } = {};
   try {
     body = await c.req.json();
   } catch {
     body = {};
   }
+  // SuperTokens-style: when platform Turnstile secret is set, require captcha
+  // on passwordless send (same as email/password) to stop abuse.
+  const plCap = await captchaGate(body as Record<string, unknown>);
+  if (plCap) return plCap;
+  const flow = body.flowType ?? 'USER_INPUT_CODE';
+  if (body.phoneNumber) {
+    const d = methodFlagDenied(fdi.methods, 'passwordlessSms');
+    if (d) {
+      return c.json(
+        { status: 'METHOD_DISABLED', engine: 'briven-engine', message: d },
+        403,
+      );
+    }
+  } else if (flow === 'MAGIC_LINK') {
+    const d = methodFlagDenied(fdi.methods, 'magicLink');
+    if (d) {
+      return c.json(
+        { status: 'METHOD_DISABLED', engine: 'briven-engine', message: d },
+        403,
+      );
+    }
+  } else {
+    const d = methodFlagDenied(fdi.methods, 'passwordlessEmail');
+    if (d) {
+      return c.json(
+        { status: 'METHOD_DISABLED', engine: 'briven-engine', message: d },
+        403,
+      );
+    }
+  }
+  const requestOrigin =
+    c.req.header('origin') ??
+    (() => {
+      const ref = c.req.header('referer');
+      if (!ref) return undefined;
+      try {
+        return new URL(ref).origin;
+      } catch {
+        return undefined;
+      }
+    })() ??
+    undefined;
+  // Prefer x-briven-client-ip (set by first-party app proxy) so Location
+  // geo uses the end-user IP, not the app-server hop.
+  const { clientIpFromHeaders } = await import(
+    '../services/auth-core/auth-email-context.js'
+  );
+  const clientIp = clientIpFromHeaders((n) => c.req.header(n));
+  const userAgent = c.req.header('user-agent') ?? null;
+  // Brave usually spoofs Chrome in User-Agent; Sec-CH-UA carries the real brand.
+  const clientHintsUa =
+    c.req.header('sec-ch-ua') ?? c.req.header('Sec-CH-UA') ?? null;
   const result = await createPasswordlessCode({
     email: body.email,
     phoneNumber: body.phoneNumber,
-    projectId: tenant?.projectId,
-    tenantId: tenant?.tenantId,
+    projectId: fdi.projectId,
+    tenantId: fdi.tenantId,
     flowType: body.flowType,
     magicLinkBaseUrl: body.magicLinkBaseUrl,
+    requestOrigin,
+    clientIp,
+    userAgent,
+    clientHintsUa,
   });
   if (result.status !== 'OK') {
     return c.json({ ...result, engine: 'briven-engine' }, 400);
@@ -282,7 +390,7 @@ authCoreFdiRouter.post(`${FDI}/signinup/code`, async (c) => {
 /** Passwordless: consume OTP or magic link. Phase 3. */
 authCoreFdiRouter.post(`${FDI}/signinup/code/consume`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   let body: {
     preAuthSessionId?: string;
     deviceId?: string;
@@ -309,8 +417,8 @@ authCoreFdiRouter.post(`${FDI}/signinup/code/consume`, async (c) => {
     deviceId: body.deviceId,
     userInputCode: body.userInputCode,
     linkCode: body.linkCode,
-    projectId: tenant?.projectId,
-    tenantId: tenant?.tenantId,
+    projectId: fdi.projectId,
+    tenantId: fdi.tenantId,
   });
   if (result.status !== 'OK') {
     return c.json(
@@ -339,13 +447,62 @@ authCoreFdiRouter.post(`${FDI}/signinup/code/consume`, async (c) => {
 /** Social: get Google/GitHub authorisation URL (Phase 4). */
 authCoreFdiRouter.get(`${FDI}/authorisationurl`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   const thirdPartyId = (c.req.query('thirdPartyId') ?? '') as SupportedSocial;
-  const redirectURI = c.req.query('redirectURI') ?? '';
+  // Accept both SuperTokens name and our older alias.
+  const redirectURI =
+    c.req.query('redirectURI') ??
+    c.req.query('redirectURIOnProviderDashboard') ??
+    '';
+  // redirectURI origin must be on project Allowed Domains (open-redirect guard).
+  if (redirectURI) {
+    try {
+      const origins = await getBrivenEngineAppOrigins(fdi.projectId);
+      const allowed = new Set(
+        origins.map((o) => {
+          try {
+            return new URL(o.includes('://') ? o : `https://${o}`).origin;
+          } catch {
+            return '';
+          }
+        }).filter(Boolean),
+      );
+      const redirectOrigin = new URL(redirectURI).origin;
+      if (allowed.size > 0 && !allowed.has(redirectOrigin)) {
+        return c.json(
+          {
+            status: 'BAD_REQUEST',
+            engine: 'briven-engine',
+            message: 'redirectURI origin is not on Allowed Domains',
+          },
+          400,
+        );
+      }
+      if (allowed.size === 0 && env.BRIVEN_ENV === 'production') {
+        return c.json(
+          {
+            status: 'BAD_REQUEST',
+            engine: 'briven-engine',
+            message: 'configure Allowed Domains before OAuth',
+          },
+          400,
+        );
+      }
+    } catch {
+      return c.json(
+        {
+          status: 'BAD_REQUEST',
+          engine: 'briven-engine',
+          message: 'invalid redirectURI',
+        },
+        400,
+      );
+    }
+  }
   const result = await getAuthorisationUrl({
     thirdPartyId,
     redirectURI,
-    projectId: tenant?.projectId ?? c.req.query('projectId') ?? undefined,
+    projectId: fdi.projectId,
   });
   if (result.status !== 'OK') {
     return c.json({ ...result, engine: 'briven-engine' }, 400);
@@ -356,7 +513,7 @@ authCoreFdiRouter.get(`${FDI}/authorisationurl`, async (c) => {
 /** Social: complete sign-in with OAuth authorization code */
 authCoreFdiRouter.post(`${FDI}/signinup`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   let body: {
     thirdPartyId?: SupportedSocial;
     redirectURI?: string;
@@ -390,8 +547,8 @@ authCoreFdiRouter.post(`${FDI}/signinup`, async (c) => {
         emailVerified: body.testProfile.emailVerified ?? true,
         name: body.testProfile.name ?? null,
       },
-      projectId: tenant?.projectId,
-      tenantId: tenant?.tenantId,
+      projectId: fdi.projectId,
+      tenantId: fdi.tenantId,
     });
     if (result.status !== 'OK') {
       return c.json({ ...result, engine: 'briven-engine' }, 400);
@@ -429,7 +586,7 @@ authCoreFdiRouter.post(`${FDI}/signinup`, async (c) => {
     thirdPartyId: body.thirdPartyId,
     code: body.code,
     redirectURI: body.redirectURI,
-    projectId: tenant?.projectId,
+    projectId: fdi.projectId,
     state: body.state,
   });
   if (result.status !== 'OK') {
@@ -452,10 +609,59 @@ authCoreFdiRouter.post(`${FDI}/signinup`, async (c) => {
   });
 });
 
+/**
+ * SuperTokens-style session refresh.
+ * Body optional: { refreshToken } — else sRefreshToken cookie.
+ * Rotates handle: old session deleted, new cookies set.
+ */
 authCoreFdiRouter.post(`${FDI}/session/refresh`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  // Minimal: client should re-signin if session expired; full refresh later.
-  return c.json({ status: 'UNAUTHORISED' }, 401);
+  let body: { refreshToken?: string } = {};
+  try {
+    body = await c.req.json();
+  } catch {
+    body = {};
+  }
+  const fromCookie = (() => {
+    const cookie = c.req.header('cookie') ?? '';
+    const m = /(?:^|;\s*)sRefreshToken=([^;]+)/.exec(cookie);
+    return m?.[1] ? decodeURIComponent(m[1]) : undefined;
+  })();
+  const refreshToken = body.refreshToken?.trim() || fromCookie;
+  if (!refreshToken) {
+    return c.json(
+      {
+        status: 'UNAUTHORISED',
+        engine: 'briven-engine',
+        message: 'refresh token required (cookie sRefreshToken or body.refreshToken)',
+      },
+      401,
+    );
+  }
+  try {
+    const session = await refreshEngineSession(refreshToken);
+    if (!session) {
+      return c.json(
+        { status: 'UNAUTHORISED', engine: 'briven-engine', message: 'invalid or expired refresh token' },
+        401,
+      );
+    }
+    setSessionCookies(c, session);
+    c.header('x-briven-engine', 'briven-engine');
+    c.header('x-briven-session-handle', session.sessionHandle);
+    return c.json({
+      status: 'OK',
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      session: { handle: session.sessionHandle, userId: session.userId },
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg === 'user_held' || msg === 'user_archived') {
+      return c.json({ status: 'UNAUTHORISED', engine: 'briven-engine', message: msg }, 401);
+    }
+    throw err;
+  }
 });
 
 // ─── Phase 5: TOTP MFA ───────────────────────────────────────────────
@@ -476,7 +682,7 @@ async function sessionUserId(c: {
 /** Enroll TOTP (needs existing session). */
 authCoreFdiRouter.post(`${FDI}/totp/setup`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   const userId = await sessionUserId(c);
   if (!userId) {
     return c.json(
@@ -491,8 +697,8 @@ authCoreFdiRouter.post(`${FDI}/totp/setup`, async (c) => {
     body = {};
   }
   const created = await createTotpDevice(userId, body.deviceName ?? 'authenticator', {
-    projectId: tenant?.projectId,
-    tenantId: tenant?.tenantId,
+    projectId: fdi.projectId,
+    tenantId: fdi.tenantId,
   });
   if (!created.ok) {
     return c.json({ status: 'ERROR', ...created }, 400);
@@ -540,12 +746,17 @@ authCoreFdiRouter.post(`${FDI}/totp/setup/verify`, async (c) => {
 
 /**
  * Second factor after password when MFA_REQUIRED.
- * Body: { userId, code, tenantId? }
+ * Body: { userId, code, mfaChallenge } — challenge issued at password step.
  */
 authCoreFdiRouter.post(`${FDI}/totp/verify`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
-  let body: { userId?: string; code?: string; tenantId?: string } = {};
+  const fdi = c.get('fdiCtx');
+  let body: {
+    userId?: string;
+    code?: string;
+    tenantId?: string;
+    mfaChallenge?: string;
+  } = {};
   try {
     body = await c.req.json();
   } catch {
@@ -557,11 +768,22 @@ authCoreFdiRouter.post(`${FDI}/totp/verify`, async (c) => {
       400,
     );
   }
+  const chal = await consumeMfaChallenge(body.mfaChallenge ?? '', body.userId);
+  if (!chal.ok) {
+    return c.json(
+      {
+        status: 'MFA_CHALLENGE_ERROR',
+        engine: 'briven-engine',
+        message: chal.message,
+      },
+      401,
+    );
+  }
   const ok = await verifyUserTotp(body.userId, body.code);
   if (!ok.ok) {
     return c.json({ status: 'WRONG_CREDENTIALS_ERROR', engine: 'briven-engine' }, 401);
   }
-  const tenantId = body.tenantId ?? tenant?.tenantId ?? 'public';
+  const tenantId = chal.tenantId || fdi.tenantId;
   const session = await createEngineSession({
     userId: body.userId,
     tenantId,
@@ -599,14 +821,26 @@ authCoreFdiRouter.delete(`${FDI}/totp/devices/:deviceId`, async (c) => {
 
 // ─── Phase 5: Passkeys (WebAuthn) ────────────────────────────────────
 
+function requestOriginFrom(c: { req: { header: (n: string) => string | undefined } }): string | null {
+  const o = c.req.header('origin')?.trim();
+  if (o) return o;
+  const ref = c.req.header('referer')?.trim();
+  if (!ref) return null;
+  try {
+    return new URL(ref).origin;
+  } catch {
+    return null;
+  }
+}
+
 authCoreFdiRouter.post(`${FDI}/webauthn/register/options`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   const userId = await sessionUserId(c);
   if (!userId) {
     return c.json({ status: 'UNAUTHORISED', engine: 'briven-engine' }, 401);
   }
-  let body: { userName?: string; rpId?: string } = {};
+  let body: { userName?: string; rpId?: string; expectedOrigin?: string } = {};
   try {
     body = await c.req.json();
   } catch {
@@ -615,9 +849,11 @@ authCoreFdiRouter.post(`${FDI}/webauthn/register/options`, async (c) => {
   const result = await createRegistrationOptions({
     userId,
     userName: body.userName ?? userId,
-    projectId: tenant?.projectId,
-    tenantId: tenant?.tenantId,
+    projectId: fdi.projectId,
+    tenantId: fdi.tenantId,
     rpId: body.rpId,
+    expectedOrigin: body.expectedOrigin,
+    requestOrigin: requestOriginFrom(c),
   });
   if (result.status !== 'OK') {
     return c.json({ ...result, engine: 'briven-engine' }, 400);
@@ -627,6 +863,7 @@ authCoreFdiRouter.post(`${FDI}/webauthn/register/options`, async (c) => {
 
 authCoreFdiRouter.post(`${FDI}/webauthn/register/finish`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
+  const fdi = c.get('fdiCtx');
   const userId = await sessionUserId(c);
   if (!userId) {
     return c.json({ status: 'UNAUTHORISED', engine: 'briven-engine' }, 401);
@@ -637,6 +874,7 @@ authCoreFdiRouter.post(`${FDI}/webauthn/register/finish`, async (c) => {
     publicKey?: string;
     transports?: string[];
     response?: unknown;
+    credential?: unknown;
     rpId?: string;
     expectedOrigin?: string;
   } = {};
@@ -654,10 +892,12 @@ authCoreFdiRouter.post(`${FDI}/webauthn/register/finish`, async (c) => {
     credentialId: body.credentialId,
     publicKey: body.publicKey,
     transports: body.transports,
+    projectId: fdi.projectId,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    response: body.response as any,
+    response: (body.response ?? body.credential) as any,
     rpId: body.rpId,
     expectedOrigin: body.expectedOrigin,
+    requestOrigin: requestOriginFrom(c),
   });
   if (result.status !== 'OK') {
     return c.json({ ...result, engine: 'briven-engine' }, 400);
@@ -667,8 +907,15 @@ authCoreFdiRouter.post(`${FDI}/webauthn/register/finish`, async (c) => {
 
 authCoreFdiRouter.post(`${FDI}/webauthn/signin/options`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
-  let body: { userId?: string; rpId?: string } = {};
+  const fdi = c.get('fdiCtx');
+  const denied = methodFlagDenied(fdi.methods, 'passkeys');
+  if (denied) {
+    return c.json(
+      { status: 'METHOD_DISABLED', engine: 'briven-engine', message: denied },
+      403,
+    );
+  }
+  let body: { userId?: string; rpId?: string; expectedOrigin?: string } = {};
   try {
     body = await c.req.json();
   } catch {
@@ -676,9 +923,11 @@ authCoreFdiRouter.post(`${FDI}/webauthn/signin/options`, async (c) => {
   }
   const result = await createAuthenticationOptions({
     userId: body.userId,
-    projectId: tenant?.projectId,
-    tenantId: tenant?.tenantId,
+    projectId: fdi.projectId,
+    tenantId: fdi.tenantId,
     rpId: body.rpId,
+    expectedOrigin: body.expectedOrigin,
+    requestOrigin: requestOriginFrom(c),
   });
   if (result.status !== 'OK') {
     return c.json({ ...result, engine: 'briven-engine' }, 400);
@@ -688,11 +937,12 @@ authCoreFdiRouter.post(`${FDI}/webauthn/signin/options`, async (c) => {
 
 authCoreFdiRouter.post(`${FDI}/webauthn/signin/finish`, async (c) => {
   if (!isAuthCoreInitialized()) return c.json(notReady(), 503);
-  const tenant = resolveAuthTenantFromHeaders((n) => c.req.header(n));
+  const fdi = c.get('fdiCtx');
   let body: {
     challengeId?: string;
     credentialId?: string;
     response?: unknown;
+    credential?: unknown;
     rpId?: string;
     expectedOrigin?: string;
   } = {};
@@ -708,10 +958,11 @@ authCoreFdiRouter.post(`${FDI}/webauthn/signin/finish`, async (c) => {
     challengeId: body.challengeId,
     credentialId: body.credentialId,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    response: body.response as any,
-    projectId: tenant?.projectId,
+    response: (body.response ?? body.credential) as any,
+    projectId: fdi.projectId,
     rpId: body.rpId,
     expectedOrigin: body.expectedOrigin,
+    requestOrigin: requestOriginFrom(c),
   });
   if (result.status !== 'OK') {
     return c.json({ ...result, engine: 'briven-engine' }, 400);

apps/api/src/routes/auth-core-idp.ts

@@ -15,7 +15,9 @@
  *
  * Dashboard (project admin):
  *   GET|POST /v1/auth-core/projects/:projectId/oidc/clients
- *   DELETE   /v1/auth-core/projects/:projectId/oidc/clients/:clientId
+ *   POST     /v1/auth-core/projects/:projectId/oidc/clients/:clientId/rotate-secret
+ *   DELETE   /v1/auth-core/projects/:projectId/oidc/clients/:clientId  (soft revoke)
+ *   DELETE   /v1/auth-core/projects/:projectId/oidc/clients/:clientId?hard=1  (purge row)
  */
 
 import { Hono } from 'hono';
@@ -24,9 +26,11 @@ import { requireAuthCoreProject } from '../middleware/auth-core-guard.js';
 import { BRIVEN_ENGINE_ID } from '../services/auth-core/engine.js';
 import {
   createOidcClient,
+  deleteOidcClient,
   getOidcClientByClientId,
   listOidcClients,
   revokeOidcClient,
+  rotateOidcClientSecret,
 } from '../services/auth-core/idp-clients.js';
 import { getOidcJwks } from '../services/auth-core/idp-signing.js';
 import {
@@ -161,9 +165,10 @@ authCoreIdpRouter.get('/v1/auth-core/oidc/authorize', async (c) => {
     return c.redirect(consentUrl, 302);
   }
 
-  // Not logged in → hosted login, then consent
+  // Not logged in → hosted login (password + links to OTP/magic), then consent.
+  // Hosted UI uses briven-engine FDI so sAccessToken is set for consent.
   const afterLogin = `${webOrigin()}/auth/${encodeURIComponent(client.projectId)}/oauth/consent?challenge=${encodeURIComponent(authReq.id)}`;
-  const loginUrl = `${webOrigin()}/auth/${encodeURIComponent(client.projectId)}/otp?callbackURL=${encodeURIComponent(afterLogin)}`;
+  const loginUrl = `${webOrigin()}/auth/${encodeURIComponent(client.projectId)}/sign-in?callbackURL=${encodeURIComponent(afterLogin)}`;
   return c.redirect(loginUrl, 302);
 });
 
@@ -618,8 +623,11 @@ authCoreIdpRouter.get(
   '/v1/auth-core/projects/:projectId/oidc/clients',
   async (c) => {
     const projectId = c.req.param('projectId');
+    const includeRevoked =
+      c.req.query('includeRevoked') === '1' ||
+      c.req.query('includeRevoked') === 'true';
     try {
-      const clients = await listOidcClients(projectId);
+      const clients = await listOidcClients(projectId, { includeRevoked });
       return c.json({
         engine: BRIVEN_ENGINE_ID,
         projectId,
@@ -709,24 +717,77 @@ authCoreIdpRouter.post(
   },
 );
 
+/** Rotate confidential client secret — old secret dies immediately. */
+authCoreIdpRouter.post(
+  '/v1/auth-core/projects/:projectId/oidc/clients/:clientId/rotate-secret',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    const clientId = c.req.param('clientId');
+    try {
+      const rotated = await rotateOidcClientSecret(projectId, clientId);
+      return c.json({
+        engine: BRIVEN_ENGINE_ID,
+        ok: true,
+        projectId,
+        client: {
+          clientId: rotated.client.clientId,
+          name: rotated.client.name,
+          hint: rotated.client.secretSuffix
+            ? `…${rotated.client.secretSuffix}`
+            : null,
+          clientSecret: rotated.clientSecret,
+        },
+        note: 'Copy client_secret now — the previous secret no longer works. Live refresh tokens for this app were revoked.',
+      });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'rotate_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        400,
+      );
+    }
+  },
+);
+
+/**
+ * DELETE without hard=1 → soft revoke (secret wiped, tokens killed).
+ * DELETE ?hard=1 → permanent remove (leftover apps).
+ */
 authCoreIdpRouter.delete(
   '/v1/auth-core/projects/:projectId/oidc/clients/:clientId',
   async (c) => {
     const projectId = c.req.param('projectId');
     const clientId = c.req.param('clientId');
+    const hard =
+      c.req.query('hard') === '1' || c.req.query('hard') === 'true';
     try {
+      if (hard) {
+        await deleteOidcClient(projectId, clientId, { force: true });
+        return c.json({
+          engine: BRIVEN_ENGINE_ID,
+          ok: true,
+          projectId,
+          clientId,
+          deleted: true,
+        });
+      }
       await revokeOidcClient(projectId, clientId);
       return c.json({
         engine: BRIVEN_ENGINE_ID,
         ok: true,
         projectId,
         clientId,
+        revoked: true,
+        note: 'Client secret wiped; refresh tokens revoked. Use ?hard=1 to delete the leftover row.',
       });
     } catch (err) {
       return c.json(
         {
           engine: BRIVEN_ENGINE_ID,
-          code: 'revoke_failed',
+          code: hard ? 'delete_failed' : 'revoke_failed',
           message: err instanceof Error ? err.message : String(err),
         },
         404,

apps/api/src/routes/auth-core-m2m.ts

@@ -158,6 +158,36 @@ authCoreM2mRouter.delete(
  * Accepts JSON or form body; optional HTTP Basic client_id:client_secret.
  */
 authCoreM2mRouter.post('/v1/auth-core/oauth/token', async (c) => {
+  // Abuse throttle (credential stuffing) — SuperTokens-style protect token endpoint.
+  try {
+    const { getRedis } = await import('../lib/redis.js');
+    const redis = getRedis();
+    const ip =
+      c.req.header('cf-connecting-ip')?.trim() ||
+      c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+      c.req.header('x-real-ip')?.trim() ||
+      'unknown';
+    if (redis) {
+      const windowSec = 60;
+      const max = 30;
+      const key = `rl:m2m:token:${ip}`;
+      const n = await redis.incr(key);
+      if (n === 1) await redis.expire(key, windowSec);
+      if (n > max) {
+        return c.json(
+          {
+            error: 'rate_limited',
+            error_description: 'too many token requests — try again shortly',
+            engine: BRIVEN_ENGINE_ID,
+          },
+          429,
+        );
+      }
+    }
+  } catch {
+    /* fail open if redis unavailable */
+  }
+
   let clientId = '';
   let clientSecret = '';
   let grantType = '';

apps/api/src/routes/auth-core-migration.ts

@@ -7,6 +7,7 @@
 import { Hono } from 'hono';
 
 import { requireAuthCoreDashboard } from '../middleware/auth-core-guard.js';
+import { requireDashboardProjectAdmin } from '../services/auth-core/dashboard-project-auth.js';
 import { BRIVEN_ENGINE_ID } from '../services/auth-core/engine.js';
 import {
   importBrivenEngineUsers,
@@ -22,7 +23,7 @@ authCoreMigrationRouter.use(
 );
 
 authCoreMigrationRouter.post('/v1/auth-core/migration/users', async (c) => {
-  let body: { users?: ImportUserInput[] } = {};
+  let body: { users?: ImportUserInput[]; projectId?: string } = {};
   try {
     body = await c.req.json();
   } catch {
@@ -33,7 +34,7 @@ authCoreMigrationRouter.post('/v1/auth-core/migration/users', async (c) => {
       {
         engine: BRIVEN_ENGINE_ID,
         code: 'users_array_required',
-        message: 'Body must be { users: [...] }',
+        message: 'Body must be { users: [...], projectId?: "p_…" }',
       },
       400,
     );
@@ -48,6 +49,25 @@ authCoreMigrationRouter.post('/v1/auth-core/migration/users', async (c) => {
       400,
     );
   }
-  const result = await importBrivenEngineUsers(body.users);
+  // Stamp top-level projectId onto rows that omit it (dashboard migration UX).
+  const projectGate = await requireDashboardProjectAdmin(c, body.projectId);
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
+  const users = body.users.map((u) => ({
+    ...u,
+    projectId: u.projectId ?? projectId,
+  }));
+  // Reject rows that try to import into a different project.
+  if (users.some((u) => u.projectId && u.projectId !== projectId)) {
+    return c.json(
+      {
+        engine: BRIVEN_ENGINE_ID,
+        code: 'project_mismatch',
+        message: 'all users must target the same projectId as the request',
+      },
+      403,
+    );
+  }
+  const result = await importBrivenEngineUsers(users);
   return c.json(result, result.ok ? 200 : 503);
 });

apps/api/src/routes/auth-core-project.ts

@@ -15,9 +15,12 @@ import { BRIVEN_ENGINE_ID, isAuthCoreInitialized } from '../services/auth-core/e
 import {
   getBrivenEngineProjectConfig,
   setBrivenEngineBranding,
+  setBrivenEngineJwtClaims,
   setBrivenEngineMethodFlags,
+  clearBrivenEngineProviderSecrets,
   setBrivenEngineProviderSecrets,
   setBrivenEngineSmsSecrets,
+  setBrivenEngineUsernameLogin,
   type BrivenEngineBranding,
   type BrivenEngineMethodFlags,
 } from '../services/auth-core/project-config.js';
@@ -25,6 +28,17 @@ import { sendBrivenEngineSmsTest } from '../services/auth-core/delivery.js';
 import { listBrivenEngineAudit } from '../services/auth-core/audit.js';
 import { recordBrivenEngineAudit } from '../services/auth-core/audit.js';
 import { env } from '../env.js';
+import { ValidationError } from '@briven/shared';
+import {
+  brandingLogoPublicUrl,
+  deleteBrandingLogo,
+  isStorageConfigured,
+  putBrandingLogo,
+  validateLogoUpload,
+} from '../services/auth-branding-logo.js';
+import { updateAuthConfig } from '../services/tenant-config-store.js';
+import { invalidateAuthInstance } from '../services/auth-tenant-pool.js';
+import { log } from '../lib/logger.js';
 import {
   ensureBrivenEngineTenant,
   listBrivenEngineTenants,
@@ -90,6 +104,116 @@ authCoreProjectRouter.get('/v1/auth-core/projects/:projectId/config', async (c)
   }
 });
 
+/** Golden-path checklist for Auth → project overview. */
+authCoreProjectRouter.get(
+  '/v1/auth-core/projects/:projectId/setup-status',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    try {
+      const { getAuthSetupStatus } = await import(
+        '../services/auth-core/setup.js'
+      );
+      const status = await getAuthSetupStatus(projectId);
+      return c.json(status);
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'setup_status_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
+/**
+ * One-click Finish setup: enable Auth, starter methods, localhost origin,
+ * mint browser key if missing. Optional body.productionOrigin.
+ */
+authCoreProjectRouter.post(
+  '/v1/auth-core/projects/:projectId/setup-finish',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    const user = c.get('user');
+    if (!user?.id) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'unauthorized',
+          message: 'dashboard session required',
+        },
+        401,
+      );
+    }
+    let body: { productionOrigin?: string } = {};
+    try {
+      body = (await c.req.json()) as { productionOrigin?: string };
+    } catch {
+      body = {};
+    }
+    try {
+      const { finishAuthSetup } = await import(
+        '../services/auth-core/setup.js'
+      );
+      const result = await finishAuthSetup(projectId, {
+        userId: user.id,
+        productionOrigin: body.productionOrigin ?? null,
+      });
+      return c.json(result);
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'setup_finish_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
+/** Replace or list app origins (CORS / passkey / golden path). */
+authCoreProjectRouter.put(
+  '/v1/auth-core/projects/:projectId/app-origins',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    let body: { origins?: string[] } = {};
+    try {
+      body = (await c.req.json()) as { origins?: string[] };
+    } catch {
+      body = {};
+    }
+    try {
+      const { setBrivenEngineAppOrigins } = await import(
+        '../services/auth-core/project-config.js'
+      );
+      const result = await setBrivenEngineAppOrigins(
+        projectId,
+        Array.isArray(body.origins) ? body.origins : [],
+        c.get('user')?.id ?? null,
+      );
+      void recordBrivenEngineAudit({
+        action: 'config.app_origins.updated',
+        projectId,
+        metadata: { count: result.appOrigins.length },
+      });
+      return c.json(result);
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'save_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
 authCoreProjectRouter.put(
   '/v1/auth-core/projects/:projectId/providers/:thirdPartyId',
   async (c) => {
@@ -163,6 +287,59 @@ authCoreProjectRouter.put(
   },
 );
 
+/**
+ * Revoke OAuth provider secrets for a project (delete client id + secret).
+ * UI returns to empty / not configured.
+ */
+authCoreProjectRouter.delete(
+  '/v1/auth-core/projects/:projectId/providers/:thirdPartyId',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    const thirdPartyIdRaw = c.req.param('thirdPartyId');
+    const thirdPartyId = thirdPartyIdRaw as BrivenSocialProviderId;
+    if (!SOCIAL_IDS.has(thirdPartyId)) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'bad_request',
+          message: `unknown OAuth provider: ${thirdPartyIdRaw}`,
+        },
+        400,
+      );
+    }
+    try {
+      const result = await clearBrivenEngineProviderSecrets(
+        projectId,
+        thirdPartyId,
+      );
+      void recordBrivenEngineAudit({
+        action: 'config.oauth_secrets.revoked',
+        projectId,
+        metadata: { thirdPartyId },
+      });
+      const config = await getBrivenEngineProjectConfig(projectId);
+      const cleared = config.providers.find(
+        (p) => p.thirdPartyId === thirdPartyId,
+      );
+      return c.json({
+        ...result,
+        config,
+        savedProvider: cleared ?? null,
+        message: `${thirdPartyId} client id and secret deleted for this project`,
+      });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'revoke_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
 /** Toggle which sign-in methods this project uses. */
 authCoreProjectRouter.put(
   '/v1/auth-core/projects/:projectId/methods',
@@ -196,6 +373,75 @@ authCoreProjectRouter.put(
   },
 );
 
+/** Custom OIDC ID-token claim templates (string/number/boolean values). */
+authCoreProjectRouter.put(
+  '/v1/auth-core/projects/:projectId/jwt-claims',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    let body: Record<string, string | number | boolean> = {};
+    try {
+      body = (await c.req.json()) as Record<string, string | number | boolean>;
+    } catch {
+      body = {};
+    }
+    try {
+      const result = await setBrivenEngineJwtClaims(projectId, body);
+      void recordBrivenEngineAudit({
+        action: 'config.jwt_claims.updated',
+        projectId,
+        metadata: { keys: Object.keys(result.jwtClaims) },
+      });
+      const config = await getBrivenEngineProjectConfig(projectId);
+      return c.json({ ...result, config });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'save_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
+/** Allow email/password sign-in with metadata.username when true. */
+authCoreProjectRouter.put(
+  '/v1/auth-core/projects/:projectId/username-login',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    let body: { enabled?: boolean } = {};
+    try {
+      body = (await c.req.json()) as { enabled?: boolean };
+    } catch {
+      body = {};
+    }
+    try {
+      const result = await setBrivenEngineUsernameLogin(
+        projectId,
+        Boolean(body.enabled),
+      );
+      void recordBrivenEngineAudit({
+        action: 'config.username_login.updated',
+        projectId,
+        metadata: { enabled: result.usernameLogin },
+      });
+      const config = await getBrivenEngineProjectConfig(projectId);
+      return c.json({ ...result, config });
+    } catch (err) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'save_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
 authCoreProjectRouter.put(
   '/v1/auth-core/projects/:projectId/delivery/sms',
   async (c) => {
@@ -272,17 +518,25 @@ authCoreProjectRouter.put(
       body = {};
     }
     try {
-      const result = await setBrivenEngineBranding(projectId, body);
+      // Logo is managed only by POST/DELETE …/branding/logo — ignore logoUrl
+      // on this PUT so a partial form save never wipes an uploaded logo.
+      const { logoUrl: _ignoreLogo, ...rest } = body;
+      const result = await setBrivenEngineBranding(projectId, rest);
       void recordBrivenEngineAudit({
         action: 'config.branding.saved',
         projectId,
         metadata: {
           hasLogo: Boolean(result.branding.logoUrl),
           primaryColor: result.branding.primaryColor,
+          senderName: result.branding.senderName,
         },
       });
       const config = await getBrivenEngineProjectConfig(projectId);
-      return c.json({ ...result, config });
+      return c.json({
+        ...result,
+        branding: result.branding,
+        config,
+      });
     } catch (err) {
       return c.json(
         {
@@ -296,6 +550,163 @@ authCoreProjectRouter.put(
   },
 );
 
+/**
+ * Upload project logo (multipart field `file`). Dashboard session path —
+ * same auth as other auth-core project routes so CSRF/cookies work via the
+ * web proxy (the bare /v1/projects/…/logo rewrite often fails CSRF).
+ */
+authCoreProjectRouter.post(
+  '/v1/auth-core/projects/:projectId/branding/logo',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    if (!isStorageConfigured()) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'storage_not_configured',
+          message: 'file storage is not configured on this api',
+        },
+        503,
+      );
+    }
+
+    let file: File | null = null;
+    try {
+      const body = await c.req.parseBody();
+      const f = body.file;
+      if (f instanceof File) file = f;
+    } catch {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'validation_failed',
+          message: 'expected multipart form-data with field `file`',
+        },
+        400,
+      );
+    }
+    if (!file) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'validation_failed',
+          message: 'missing `file` form field',
+        },
+        400,
+      );
+    }
+
+    try {
+      let contentType = file.type || '';
+      if (!contentType && file.name) {
+        const lower = file.name.toLowerCase();
+        if (lower.endsWith('.png')) contentType = 'image/png';
+        else if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+          contentType = 'image/jpeg';
+        else if (lower.endsWith('.webp')) contentType = 'image/webp';
+        else if (lower.endsWith('.svg')) contentType = 'image/svg+xml';
+      }
+      validateLogoUpload({ contentType, size: file.size });
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      await putBrandingLogo({ projectId, bytes, contentType });
+      const logoUrl = brandingLogoPublicUrl(projectId);
+      await setBrivenEngineBranding(projectId, { logoUrl });
+      try {
+        await updateAuthConfig(projectId, { branding: { logoUrl } });
+        await invalidateAuthInstance(projectId);
+      } catch {
+        // Engine branding is source of truth for Auth dashboard.
+      }
+      void recordBrivenEngineAudit({
+        action: 'config.branding.logo.uploaded',
+        projectId,
+        metadata: { contentType, sizeBytes: file.size },
+      });
+      const branding = (await getBrivenEngineProjectConfig(projectId)).branding;
+      return c.json({
+        ok: true,
+        engine: BRIVEN_ENGINE_ID,
+        logoUrl,
+        branding,
+      });
+    } catch (err) {
+      if (err instanceof ValidationError) {
+        return c.json(
+          {
+            engine: BRIVEN_ENGINE_ID,
+            code: 'validation_failed',
+            message: err.message,
+          },
+          400,
+        );
+      }
+      log.error('briven_engine_branding_logo_upload_failed', {
+        projectId,
+        message: err instanceof Error ? err.message : String(err),
+      });
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'logo_upload_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
+/** Remove project logo. */
+authCoreProjectRouter.delete(
+  '/v1/auth-core/projects/:projectId/branding/logo',
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    if (!isStorageConfigured()) {
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'storage_not_configured',
+          message: 'file storage is not configured on this api',
+        },
+        503,
+      );
+    }
+    try {
+      await deleteBrandingLogo(projectId);
+      await setBrivenEngineBranding(projectId, { logoUrl: null });
+      try {
+        await updateAuthConfig(projectId, { branding: { logoUrl: null } });
+        await invalidateAuthInstance(projectId);
+      } catch {
+        /* engine branding is enough */
+      }
+      void recordBrivenEngineAudit({
+        action: 'config.branding.logo.removed',
+        projectId,
+        metadata: {},
+      });
+      return c.json({
+        ok: true,
+        engine: BRIVEN_ENGINE_ID,
+        logoUrl: null,
+      });
+    } catch (err) {
+      log.error('briven_engine_branding_logo_remove_failed', {
+        projectId,
+        message: err instanceof Error ? err.message : String(err),
+      });
+      return c.json(
+        {
+          engine: BRIVEN_ENGINE_ID,
+          code: 'logo_remove_failed',
+          message: err instanceof Error ? err.message : String(err),
+        },
+        500,
+      );
+    }
+  },
+);
+
 /** Security audit trail for this project (newest first). */
 authCoreProjectRouter.get(
   '/v1/auth-core/projects/:projectId/audit',

apps/api/src/routes/auth-core-roles.ts

@@ -6,12 +6,15 @@
 import { Hono } from 'hono';
 
 import { requireAuthCoreDashboard } from '../middleware/auth-core-guard.js';
+import { requireDashboardProjectAdmin } from '../services/auth-core/dashboard-project-auth.js';
 import { BRIVEN_ENGINE_ID, isAuthCoreInitialized } from '../services/auth-core/engine.js';
 import {
   assignBrivenEngineRole,
   createBrivenEngineRole,
+  deleteBrivenEngineRole,
   getBrivenEngineUserRoles,
   listBrivenEngineRoles,
+  unassignBrivenEngineRole,
 } from '../services/auth-core/roles.js';
 import type { AppEnv } from '../types/app-env.js';
 
@@ -28,7 +31,12 @@ authCoreRolesRouter.get('/v1/auth-core/roles', async (c) => {
       503,
     );
   }
-  const projectId = c.req.query('projectId') ?? undefined;
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
   const tenantId = c.req.query('tenantId') ?? undefined;
   return c.json(await listBrivenEngineRoles({ projectId, tenantId }));
 });
@@ -48,9 +56,11 @@ authCoreRolesRouter.post('/v1/auth-core/roles', async (c) => {
   if (!body.role) {
     return c.json({ engine: BRIVEN_ENGINE_ID, code: 'role_required' }, 400);
   }
+  const projectGate = await requireDashboardProjectAdmin(c, body.projectId);
+  if (projectGate instanceof Response) return projectGate;
   return c.json(
     await createBrivenEngineRole(body.role, body.permissions ?? [], {
-      projectId: body.projectId,
+      projectId: projectGate.projectId,
       tenantId: body.tenantId,
     }),
   );
@@ -74,18 +84,76 @@ authCoreRolesRouter.post('/v1/auth-core/roles/assign', async (c) => {
       400,
     );
   }
+  const projectGate = await requireDashboardProjectAdmin(c, body.projectId);
+  if (projectGate instanceof Response) return projectGate;
   return c.json(
     await assignBrivenEngineRole(body.userId, body.role, {
-      projectId: body.projectId,
+      projectId: projectGate.projectId,
       tenantId: body.tenantId,
     }),
   );
 });
 
+authCoreRolesRouter.post('/v1/auth-core/roles/unassign', async (c) => {
+  let body: {
+    userId?: string;
+    role?: string;
+    projectId?: string;
+    tenantId?: string;
+  } = {};
+  try {
+    body = await c.req.json();
+  } catch {
+    body = {};
+  }
+  if (!body.userId || !body.role) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, code: 'userId_and_role_required' },
+      400,
+    );
+  }
+  const projectGate = await requireDashboardProjectAdmin(c, body.projectId);
+  if (projectGate instanceof Response) return projectGate;
+  return c.json(
+    await unassignBrivenEngineRole(body.userId, body.role, {
+      projectId: projectGate.projectId,
+      tenantId: body.tenantId,
+    }),
+  );
+});
+
+authCoreRolesRouter.delete('/v1/auth-core/roles', async (c) => {
+  let body: { role?: string; projectId?: string; tenantId?: string } = {};
+  try {
+    body = await c.req.json();
+  } catch {
+    body = {};
+  }
+  // Also allow ?role=&projectId=
+  const role = body.role ?? c.req.query('role') ?? undefined;
+  const projectId = body.projectId ?? c.req.query('projectId') ?? undefined;
+  if (!role) {
+    return c.json({ engine: BRIVEN_ENGINE_ID, code: 'role_required' }, 400);
+  }
+  const projectGate = await requireDashboardProjectAdmin(c, projectId);
+  if (projectGate instanceof Response) return projectGate;
+  return c.json(
+    await deleteBrivenEngineRole(role, {
+      projectId: projectGate.projectId,
+      tenantId: body.tenantId ?? c.req.query('tenantId') ?? undefined,
+    }),
+  );
+});
+
 authCoreRolesRouter.get('/v1/auth-core/users/:userId/roles', async (c) => {
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
   return c.json(
     await getBrivenEngineUserRoles(c.req.param('userId'), {
-      projectId: c.req.query('projectId') ?? undefined,
+      projectId: projectGate.projectId,
       tenantId: c.req.query('tenantId') ?? undefined,
     }),
   );

apps/api/src/routes/auth-core-session.ts

@@ -9,6 +9,7 @@
 import { Hono } from 'hono';
 
 import { requireAuthCoreDashboard } from '../middleware/auth-core-guard.js';
+import { requireDashboardProjectAdmin } from '../services/auth-core/dashboard-project-auth.js';
 import {
   listSessionsForUser,
   revokeAllSessionsForUser,
@@ -90,12 +91,22 @@ authCoreSessionRouter.get('/v1/auth-core/session/list', async (c) => {
   if (!isAuthCoreInitialized()) {
     return c.json({ code: 'auth_core_sdk_not_ready' }, 503);
   }
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
   const userId = c.req.query('userId');
   if (!userId) {
     return c.json({ code: 'userId_required' }, 400);
   }
   const handles = await listSessionsForUser(userId);
-  return c.json({ userId, handles, count: handles.length });
+  return c.json({
+    userId,
+    handles,
+    count: handles.length,
+    projectId: projectGate.projectId,
+  });
 });
 
 /** Yellow dashboard: recent active sessions across tenants. */
@@ -110,8 +121,13 @@ authCoreSessionRouter.get('/v1/auth-core/session/recent', async (c) => {
       503,
     );
   }
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
   const limit = Number(c.req.query('limit') ?? '50');
-  const projectId = c.req.query('projectId') ?? undefined;
+  const projectId = projectGate.projectId;
   let tenantId = c.req.query('tenantId') ?? undefined;
   if (!tenantId && projectId) {
     try {
@@ -141,12 +157,22 @@ authCoreSessionRouter.post('/v1/auth-core/session/revoke', async (c) => {
   if (!isAuthCoreInitialized()) {
     return c.json({ code: 'auth_core_sdk_not_ready' }, 503);
   }
-  let body: { sessionHandle?: string; userId?: string; all?: boolean } = {};
+  let body: {
+    sessionHandle?: string;
+    userId?: string;
+    all?: boolean;
+    projectId?: string;
+  } = {};
   try {
     body = await c.req.json();
   } catch {
     body = {};
   }
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    body.projectId ?? c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
 
   if (body.all && body.userId) {
     const n = await revokeAllSessionsForUser(body.userId);

apps/api/src/routes/auth-core-sso.ts

@@ -14,6 +14,7 @@
  */
 
 import { Hono } from 'hono';
+import { sanitizeRelayState } from '../services/auth-hardening.js';
 import { setCookie } from 'hono/cookie';
 
 import {
@@ -248,11 +249,22 @@ authCoreSsoRouter.post('/v1/auth-core/sso/saml/:connectionId/acs', async (c) =>
       path: '/',
       maxAge: 60 * 60 * 24 * 30,
     });
-    const relay =
-      typeof body.RelayState === 'string' && body.RelayState.startsWith('http')
-        ? body.RelayState
-        : null;
-    if (relay) return c.redirect(relay, 302);
+    // Open-redirect guard: only allowlisted origins (or relative paths).
+    let allowedOrigins: string[] = [];
+    try {
+      const { getBrivenEngineAppOrigins } = await import(
+        '../services/auth-core/project-config.js'
+      );
+      if (result.projectId) {
+        allowedOrigins = await getBrivenEngineAppOrigins(result.projectId);
+      }
+    } catch {
+      allowedOrigins = [];
+    }
+    const relayRaw =
+      typeof body.RelayState === 'string' ? body.RelayState : null;
+    const relay = sanitizeRelayState(relayRaw, allowedOrigins);
+    if (relay && relay !== '/') return c.redirect(relay, 302);
     return c.json({
       engine: BRIVEN_ENGINE_ID,
       status: 'OK',
@@ -276,7 +288,13 @@ authCoreSsoRouter.post('/v1/auth-core/sso/saml/:connectionId/acs', async (c) =>
 
 authCoreSsoRouter.get('/v1/auth-core/sso/oidc/:connectionId', async (c) => {
   try {
-    const { redirectUrl } = await startOidcLogin(c.req.param('connectionId'));
+    // Optional ?returnTo=https://app.example.com/after-login (sanitized server-side)
+    const returnTo = c.req.query('returnTo') ?? c.req.query('return_to') ?? null;
+    const { redirectUrl } = await startOidcLogin(
+      c.req.param('connectionId'),
+      undefined,
+      returnTo,
+    );
     return c.redirect(redirectUrl, 302);
   } catch (err) {
     return c.json(
@@ -314,6 +332,10 @@ authCoreSsoRouter.get(
         path: '/',
         maxAge: 60 * 60 * 24 * 30,
       });
+      // Prefer redirect into the app when returnTo was stored at start.
+      if (result.returnTo) {
+        return c.redirect(result.returnTo, 302);
+      }
       return c.json({
         engine: BRIVEN_ENGINE_ID,
         status: 'OK',
@@ -322,6 +344,8 @@ authCoreSsoRouter.get(
         projectId: result.projectId,
         tenantId: result.tenantId,
         sessionHandle: result.sessionHandle,
+        message:
+          'OIDC login ok — pass returnTo on start URL to redirect into your app',
       });
     } catch (err) {
       return c.json(

apps/api/src/routes/auth-core-users.ts

@@ -1,20 +1,39 @@
 /**
- * briven-engine users API (Phase 5 surface).
+ * briven-engine users API — list, detail, hold, archive, delete, revoke sessions.
  *
- *  GET  /v1/auth-core/users
- *  GET  /v1/auth-core/users/:userId/metadata
- *  PUT  /v1/auth-core/users/:userId/metadata
+ *  GET    /v1/auth-core/users
+ *  GET    /v1/auth-core/users/:userId
+ *  GET    /v1/auth-core/users/:userId/metadata
+ *  PUT    /v1/auth-core/users/:userId/metadata
+ *  POST   /v1/auth-core/users/:userId/hold
+ *  POST   /v1/auth-core/users/:userId/unhold
+ *  POST   /v1/auth-core/users/:userId/archive
+ *  POST   /v1/auth-core/users/:userId/unarchive
+ *  POST   /v1/auth-core/users/:userId/delete
+ *  POST   /v1/auth-core/users/:userId/sessions/revoke-all
+ *  POST   /v1/auth-core/users/:userId/sessions/:sessionHandle/revoke
  */
 
 import { Hono } from 'hono';
 
 import { requireAuthCoreDashboard } from '../middleware/auth-core-guard.js';
 import { BRIVEN_ENGINE_ID, isAuthCoreInitialized } from '../services/auth-core/engine.js';
+import { requireDashboardProjectAdmin } from '../services/auth-core/dashboard-project-auth.js';
 import {
+  archiveBrivenEngineUser,
+  deleteBrivenEngineUser,
+  getBrivenEngineUser,
   getBrivenEngineUserMetadata,
+  holdBrivenEngineUser,
   listBrivenEngineUsers,
+  unarchiveBrivenEngineUser,
+  unholdBrivenEngineUser,
   updateBrivenEngineUserMetadata,
 } from '../services/auth-core/users.js';
+import {
+  revokeAllSessionsForUser,
+  revokeSession,
+} from '../services/auth-core/session.js';
 import type { AppEnv } from '../types/app-env.js';
 
 export const authCoreUsersRouter = new Hono<AppEnv>();
@@ -22,6 +41,22 @@ export const authCoreUsersRouter = new Hono<AppEnv>();
 authCoreUsersRouter.use('/v1/auth-core/users', requireAuthCoreDashboard());
 authCoreUsersRouter.use('/v1/auth-core/users/*', requireAuthCoreDashboard());
 
+async function resolveTenantId(
+  projectId: string | undefined,
+  tenantId: string | undefined,
+): Promise<string | undefined> {
+  if (tenantId) return tenantId;
+  if (!projectId) return undefined;
+  try {
+    const { projectIdToTenantId } = await import(
+      '../services/auth-core/project-map.js'
+    );
+    return projectIdToTenantId(projectId);
+  } catch {
+    return undefined;
+  }
+}
+
 authCoreUsersRouter.get('/v1/auth-core/users', async (c) => {
   if (!isAuthCoreInitialized()) {
     return c.json(
@@ -29,20 +64,18 @@ authCoreUsersRouter.get('/v1/auth-core/users', async (c) => {
       503,
     );
   }
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
   const limit = Number(c.req.query('limit') ?? '50');
   const paginationToken = c.req.query('paginationToken') ?? undefined;
-  const projectId = c.req.query('projectId') ?? undefined;
-  let tenantId = c.req.query('tenantId') ?? undefined;
-  if (!tenantId && projectId) {
-    try {
-      const { projectIdToTenantId } = await import(
-        '../services/auth-core/project-map.js'
-      );
-      tenantId = projectIdToTenantId(projectId);
-    } catch {
-      tenantId = undefined;
-    }
-  }
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(
+    projectId,
+    c.req.query('tenantId') ?? undefined,
+  );
   const result = await listBrivenEngineUsers({
     limit: Number.isFinite(limit) ? limit : 50,
     paginationToken,
@@ -50,12 +83,71 @@ authCoreUsersRouter.get('/v1/auth-core/users', async (c) => {
   });
   return c.json({
     ...result,
-    projectId: projectId ?? null,
+    projectId,
     tenantId: tenantId ?? null,
   });
 });
 
+authCoreUsersRouter.get('/v1/auth-core/users/:userId', async (c) => {
+  if (!isAuthCoreInitialized()) {
+    return c.json({ engine: BRIVEN_ENGINE_ID, code: 'auth_core_sdk_not_ready' }, 503);
+  }
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const userId = c.req.param('userId');
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(
+    projectId,
+    c.req.query('tenantId') ?? undefined,
+  );
+  const user = await getBrivenEngineUser(userId, { tenantId });
+  if (!user) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, code: 'not_found', message: 'user not found' },
+      404,
+    );
+  }
+  return c.json({ engine: BRIVEN_ENGINE_ID, user, projectId });
+});
+
+/** GDPR-style JSON export for one end-user (no password hashes). */
+authCoreUsersRouter.get('/v1/auth-core/users/:userId/export', async (c) => {
+  if (!isAuthCoreInitialized()) {
+    return c.json({ engine: BRIVEN_ENGINE_ID, code: 'auth_core_sdk_not_ready' }, 503);
+  }
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const userId = c.req.param('userId');
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(
+    projectId,
+    c.req.query('tenantId') ?? undefined,
+  );
+  const { exportBrivenEngineUserGdpr } = await import(
+    '../services/auth-core/users.js'
+  );
+  const pack = await exportBrivenEngineUserGdpr(userId, { tenantId });
+  if (!pack) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, code: 'not_found', message: 'user not found' },
+      404,
+    );
+  }
+  return c.json(pack);
+});
+
 authCoreUsersRouter.get('/v1/auth-core/users/:userId/metadata', async (c) => {
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
   const userId = c.req.param('userId');
   const metadata = await getBrivenEngineUserMetadata(userId);
   if (metadata == null && !isAuthCoreInitialized()) {
@@ -65,6 +157,11 @@ authCoreUsersRouter.get('/v1/auth-core/users/:userId/metadata', async (c) => {
 });
 
 authCoreUsersRouter.put('/v1/auth-core/users/:userId/metadata', async (c) => {
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
   const userId = c.req.param('userId');
   let body: Record<string, unknown> = {};
   try {
@@ -85,3 +182,220 @@ authCoreUsersRouter.put('/v1/auth-core/users/:userId/metadata', async (c) => {
   }
   return c.json({ engine: BRIVEN_ENGINE_ID, ok: true, userId });
 });
+
+async function moderationBody(c: {
+  req: { json: () => Promise<unknown> };
+}): Promise<{ reason?: string; projectId?: string; confirm?: string }> {
+  try {
+    const body = (await c.req.json()) as {
+      reason?: string;
+      projectId?: string;
+      confirm?: string;
+    };
+    return body ?? {};
+  } catch {
+    return {};
+  }
+}
+
+authCoreUsersRouter.post('/v1/auth-core/users/:userId/hold', async (c) => {
+  const userId = c.req.param('userId');
+  const body = await moderationBody(c);
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    body.projectId ?? c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(projectId, undefined);
+  const ok = await holdBrivenEngineUser(userId, {
+    reason: body.reason,
+    tenantId,
+  });
+  if (!ok) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, ok: false, code: 'hold_failed' },
+      400,
+    );
+  }
+  return c.json({ engine: BRIVEN_ENGINE_ID, ok: true, userId, status: 'held' });
+});
+
+authCoreUsersRouter.post('/v1/auth-core/users/:userId/unhold', async (c) => {
+  const userId = c.req.param('userId');
+  const body = await moderationBody(c);
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    body.projectId ?? c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(projectId, undefined);
+  const ok = await unholdBrivenEngineUser(userId, { tenantId });
+  if (!ok) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, ok: false, code: 'unhold_failed' },
+      400,
+    );
+  }
+  return c.json({ engine: BRIVEN_ENGINE_ID, ok: true, userId, status: 'active' });
+});
+
+authCoreUsersRouter.post('/v1/auth-core/users/:userId/archive', async (c) => {
+  const userId = c.req.param('userId');
+  const body = await moderationBody(c);
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    body.projectId ?? c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(projectId, undefined);
+  const ok = await archiveBrivenEngineUser(userId, {
+    reason: body.reason,
+    tenantId,
+  });
+  if (!ok) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, ok: false, code: 'archive_failed' },
+      400,
+    );
+  }
+  return c.json({
+    engine: BRIVEN_ENGINE_ID,
+    ok: true,
+    userId,
+    status: 'archived',
+  });
+});
+
+authCoreUsersRouter.post('/v1/auth-core/users/:userId/unarchive', async (c) => {
+  const userId = c.req.param('userId');
+  const body = await moderationBody(c);
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    body.projectId ?? c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(projectId, undefined);
+  const ok = await unarchiveBrivenEngineUser(userId, { tenantId });
+  if (!ok) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, ok: false, code: 'unarchive_failed' },
+      400,
+    );
+  }
+  return c.json({ engine: BRIVEN_ENGINE_ID, ok: true, userId, status: 'active' });
+});
+
+authCoreUsersRouter.post('/v1/auth-core/users/:userId/delete', async (c) => {
+  const userId = c.req.param('userId');
+  const body = await moderationBody(c);
+  const projectGate = await requireDashboardProjectAdmin(
+    c,
+    body.projectId ?? c.req.query('projectId'),
+  );
+  if (projectGate instanceof Response) return projectGate;
+  const projectId = projectGate.projectId;
+  const tenantId = await resolveTenantId(projectId, undefined);
+  // Safety: require explicit confirm in body
+  if (body.confirm !== 'delete') {
+    return c.json(
+      {
+        engine: BRIVEN_ENGINE_ID,
+        ok: false,
+        code: 'confirm_required',
+        message: 'send { "confirm": "delete" } to permanently delete',
+      },
+      400,
+    );
+  }
+  const ok = await deleteBrivenEngineUser(userId, { tenantId });
+  if (!ok) {
+    return c.json(
+      { engine: BRIVEN_ENGINE_ID, ok: false, code: 'delete_failed' },
+      400,
+    );
+  }
+  return c.json({ engine: BRIVEN_ENGINE_ID, ok: true, userId, deleted: true });
+});
+
+authCoreUsersRouter.post(
+  '/v1/auth-core/users/:userId/sessions/revoke-all',
+  async (c) => {
+    const userId = c.req.param('userId');
+    const body = await moderationBody(c);
+    const projectGate = await requireDashboardProjectAdmin(
+      c,
+      body.projectId ?? c.req.query('projectId'),
+    );
+    if (projectGate instanceof Response) return projectGate;
+    const projectId = projectGate.projectId;
+    const tenantId = await resolveTenantId(projectId, undefined);
+    // Scope: ensure user belongs to tenant when project provided
+    if (tenantId) {
+      const user = await getBrivenEngineUser(userId, { tenantId });
+      if (!user) {
+        return c.json(
+          { engine: BRIVEN_ENGINE_ID, code: 'not_found' },
+          404,
+        );
+      }
+    }
+    const n = await revokeAllSessionsForUser(userId);
+    return c.json({
+      engine: BRIVEN_ENGINE_ID,
+      ok: true,
+      userId,
+      revoked: n,
+    });
+  },
+);
+
+authCoreUsersRouter.post(
+  '/v1/auth-core/users/:userId/sessions/:sessionHandle/revoke',
+  async (c) => {
+    const userId = c.req.param('userId');
+    const sessionHandle = c.req.param('sessionHandle');
+    const body = await moderationBody(c);
+    const projectGate = await requireDashboardProjectAdmin(
+      c,
+      body.projectId ?? c.req.query('projectId'),
+    );
+    if (projectGate instanceof Response) return projectGate;
+    const projectId = projectGate.projectId;
+    const tenantId = await resolveTenantId(projectId, undefined);
+    if (tenantId) {
+      const user = await getBrivenEngineUser(userId, { tenantId });
+      if (!user) {
+        return c.json(
+          { engine: BRIVEN_ENGINE_ID, code: 'not_found' },
+          404,
+        );
+      }
+    }
+    // Only revoke if session belongs to this user
+    const detail = await getBrivenEngineUser(userId, { tenantId });
+    const owns = detail?.sessions.some((s) => s.handle === sessionHandle);
+    if (!owns) {
+      // still try revoke by handle if list is empty due to race
+      const ok = await revokeSession(sessionHandle);
+      return c.json({
+        engine: BRIVEN_ENGINE_ID,
+        ok,
+        userId,
+        sessionHandle,
+        revoked: ok ? 1 : 0,
+      });
+    }
+    const ok = await revokeSession(sessionHandle);
+    return c.json({
+      engine: BRIVEN_ENGINE_ID,
+      ok,
+      userId,
+      sessionHandle,
+      revoked: ok ? 1 : 0,
+    });
+  },
+);

apps/api/src/routes/auth-core.ts

@@ -24,6 +24,7 @@ import {
   probeBrivenEngine,
 } from '../services/auth-core/engine.js';
 import {
+  disableBrivenEngineAuth,
   enableBrivenEngineAuth,
   listBrivenEngineWorkspace,
 } from '../services/auth-core/workspace.js';
@@ -109,6 +110,19 @@ authCoreRouter.post(
   },
 );
 
+/**
+ * Disable Auth for a project (soft). User data stays; enable again anytime.
+ */
+authCoreRouter.post(
+  '/v1/auth-core/projects/:projectId/disable',
+  ...[requireProjectAuth('projectId'), requireProjectRole('admin')],
+  async (c) => {
+    const projectId = c.req.param('projectId');
+    const result = await disableBrivenEngineAuth(projectId);
+    return c.json(result, result.ok ? 200 : 503);
+  },
+);
+
 /**
  * Bridge: dashboard "enable Auth" buttons still call the old path.
  * Do NOT return 410 — wire to briven-engine instead.
@@ -144,6 +158,34 @@ authCoreRouter.post(
   },
 );
 
+authCoreRouter.post(
+  '/v1/projects/:id/auth/disable',
+  ...[requireProjectAuth('id'), requireProjectRole('admin')],
+  async (c) => {
+    const projectId = c.req.param('id');
+    const result = await disableBrivenEngineAuth(projectId);
+    if (!result.ok) {
+      return c.json(
+        {
+          code: 'auth_disable_failed',
+          message: result.message ?? 'could not disable Auth',
+          engine: BRIVEN_ENGINE_ID,
+        },
+        503,
+      );
+    }
+    return c.json({
+      ok: true,
+      engine: BRIVEN_ENGINE_ID,
+      projectId: result.projectId,
+      tenantId: result.tenantId,
+      authEnabled: false,
+      message: result.message ?? 'Auth disabled for this project',
+      storage: 'doltgres',
+    });
+  },
+);
+
 /**
  * Bridge: workspace list for older UI that still hits auth-v2.
  */

apps/api/src/routes/auth-service.ts

@@ -373,11 +373,31 @@ authServiceRouter.post(
     }
 
     try {
-      validateLogoUpload({ contentType: file.type, size: file.size });
+      // Browsers usually set image/jpeg for .jpg/.jpeg; empty type → sniff name.
+      let contentType = file.type || '';
+      if (!contentType && file.name) {
+        const lower = file.name.toLowerCase();
+        if (lower.endsWith('.png')) contentType = 'image/png';
+        else if (lower.endsWith('.jpg') || lower.endsWith('.jpeg')) contentType = 'image/jpeg';
+        else if (lower.endsWith('.webp')) contentType = 'image/webp';
+        else if (lower.endsWith('.svg')) contentType = 'image/svg+xml';
+      }
+      validateLogoUpload({ contentType, size: file.size });
       const bytes = new Uint8Array(await file.arrayBuffer());
-      await putBrandingLogo({ projectId, bytes, contentType: file.type });
+      await putBrandingLogo({ projectId, bytes, contentType });
       const logoUrl = brandingLogoPublicUrl(projectId);
+      // Logo is upload-only — stored as a stable public CDN URL we generate.
+      // Operators never paste an external logo URL in the UI.
       await updateAuthConfig(projectId, { branding: { logoUrl } });
+      // Keep briven-engine branding in lockstep (dashboard Auth → branding).
+      try {
+        const { setBrivenEngineBranding } = await import(
+          '../services/auth-core/project-config.js'
+        );
+        await setBrivenEngineBranding(projectId, { logoUrl }, actor.id);
+      } catch {
+        // Non-fatal: tenant config is still updated.
+      }
       // Drop the cached Better Auth instance so hosted pages rebuild with
       // the new logo (mirrors the config PATCH path).
       await invalidateAuthInstance(projectId);
@@ -426,6 +446,14 @@ authServiceRouter.delete(
     try {
       await deleteBrandingLogo(projectId);
       await updateAuthConfig(projectId, { branding: { logoUrl: null } });
+      try {
+        const { setBrivenEngineBranding } = await import(
+          '../services/auth-core/project-config.js'
+        );
+        await setBrivenEngineBranding(projectId, { logoUrl: null }, actor.id);
+      } catch {
+        // Non-fatal.
+      }
       await invalidateAuthInstance(projectId);
       await audit({
         actorId: actor.id,

apps/api/src/routes/auth.ts

@@ -5,10 +5,25 @@ import { auth } from '../lib/auth.js';
 /**
  * Mount the Better Auth handler under /v1/auth/*.
  *
- * Better Auth owns every /v1/auth/* path (sign-up, sign-in, sign-out, magic
- * link, OAuth callbacks, session, password reset, etc.). We never add our
- * own routes inside this tree.
+ * Better Auth owns most /v1/auth/* paths (sign-up, sign-in, sign-out, magic
+ * link, OAuth callbacks, session, password reset, etc.).
+ *
+ * Exception: POST /v1/auth/cli-token is owned by authCliRouter and must be
+ * registered *before* this catch-all (see apps/api/src/index.ts).
  */
 export const authRouter = new Hono();
 
-authRouter.on(['GET', 'POST'], '/v1/auth/*', (c) => auth.handler(c.req.raw));
+authRouter.on(['GET', 'POST'], '/v1/auth/*', (c) => {
+  // Defence-in-depth if mount order is ever inverted.
+  if (c.req.path === '/v1/auth/cli-token') {
+    return c.json(
+      {
+        code: 'route_order_error',
+        message:
+          'cli-token must be handled by authCliRouter — check mount order in index.ts',
+      },
+      500,
+    );
+  }
+  return auth.handler(c.req.raw);
+});

apps/api/src/routes/db.ts

@@ -3,6 +3,7 @@ import { z } from 'zod';
 
 import { rateLimit } from '../middleware/rate-limit.js';
 import { requireProjectAuth, requireProjectRole } from '../middleware/project-auth.js';
+import { requireServiceProduct } from '../middleware/service-product.js';
 import { requireRecentMfa } from '../middleware/step-up.js';
 import type { ProjectAppEnv as AppEnv } from '../types/app-env.js';
 import { audit, hashIp } from '../services/audit.js';
@@ -24,8 +25,13 @@ function ipHash(c: Context<AppEnv>): string | null {
 
 export const dbRouter = new Hono<AppEnv>();
 
-// `db/shell-token` rotates a privileged DSN — admin-tier.
-dbRouter.use('/v1/projects/:id/db/*', requireProjectAuth(), requireProjectRole('admin'));
+// `db/shell-token` rotates a privileged DSN — admin-tier. Doltgres wall only.
+dbRouter.use(
+  '/v1/projects/:id/db/*',
+  requireProjectAuth(),
+  requireServiceProduct('db'),
+  requireProjectRole('admin'),
+);
 
 // why: 5/min per project is enough for a human-driven `briven db shell`
 // loop and restrictive enough that a leaked api key can't silently

apps/api/src/routes/platform.ts

@@ -2,6 +2,7 @@ import { Hono } from "hono";
 
 import { projectRateLimit } from "../middleware/rate-limit.js";
 import { requireProjectAuth, requireProjectRole } from "../middleware/project-auth.js";
+import { requireServiceProduct } from "../middleware/service-product.js";
 import type { ProjectAppEnv as AppEnv } from "../types/app-env.js";
 import {
   listProjectTables,
@@ -40,9 +41,10 @@ import { log } from "../lib/logger.js";
 
 const platformRouter = new Hono<AppEnv>();
 
-/** Shared gate for every :ref route: resolve project + admin role. */
+/** Shared gate for every :ref route: resolve project + admin role. Doltgres wall. */
 const platformRefAuth = [
   requireProjectAuth("ref"),
+  requireServiceProduct("db"),
   projectRateLimit("mutate"),
   requireProjectRole("admin"),
 ] as const;

apps/api/src/routes/service-badges.ts

@@ -0,0 +1,153 @@
+/**
+ * Project service badges — mint / list / revoke.
+ *
+ *   GET    /v1/projects/:id/service-badges?product=db|s3|auth
+ *   POST   /v1/projects/:id/service-badges
+ *   DELETE /v1/projects/:id/service-badges/:badgeId
+ *
+ * Dashboard session only (admin) — same bar as api-keys / storage-keys mint.
+ * Secrets returned once on create.
+ */
+
+import { Hono } from 'hono';
+import { z } from 'zod';
+
+import { requireAuth } from '../middleware/session.js';
+import type { AppEnv } from '../types/app-env.js';
+import { audit, hashIp } from '../services/audit.js';
+import { assertProjectRole } from '../services/access.js';
+import {
+  createServiceBadge,
+  isMintableServiceBadgeProduct,
+  isServiceBadgeProduct,
+  isServiceBadgeRole,
+  listServiceBadges,
+  revokeServiceBadge,
+} from '../services/service-badges.js';
+
+const createSchema = z.object({
+  name: z.string().min(1).max(80),
+  product: z.enum(['db', 's3', 'auth', 'pay']),
+  role: z.enum(['viewer', 'developer', 'admin']).optional(),
+  expiresInDays: z.number().int().positive().max(365).optional(),
+});
+
+export const serviceBadgesRouter = new Hono<AppEnv>();
+
+serviceBadgesRouter.use('/v1/projects/:id/service-badges', requireAuth());
+serviceBadgesRouter.use('/v1/projects/:id/service-badges/*', requireAuth());
+
+serviceBadgesRouter.get('/v1/projects/:id/service-badges', async (c) => {
+  const user = c.get('user')!;
+  const { project } = await assertProjectRole(c.req.param('id'), user.id, 'admin');
+  const productQ = c.req.query('product');
+  const product =
+    productQ && isServiceBadgeProduct(productQ) ? productQ : undefined;
+  const badges = await listServiceBadges(project.id, product);
+  return c.json({
+    badges,
+    products: {
+      db: 'Doltgres database (tables, query, studio)',
+      s3: 'S3 / object storage for this project bucket',
+      auth: 'Auth machine clients (SuperTokens-style M2M)',
+      pay: 'Briven Pay (coming later)',
+    },
+  });
+});
+
+serviceBadgesRouter.post('/v1/projects/:id/service-badges', async (c) => {
+  const user = c.get('user')!;
+  const { project } = await assertProjectRole(c.req.param('id'), user.id, 'admin');
+  const body = await c.req.json().catch(() => null);
+  const parsed = createSchema.safeParse(body);
+  if (!parsed.success) {
+    return c.json(
+      {
+        code: 'validation_failed',
+        message: 'invalid request body',
+        issues: parsed.error.issues,
+      },
+      400,
+    );
+  }
+  if (!isMintableServiceBadgeProduct(parsed.data.product)) {
+    return c.json(
+      {
+        code: 'product_not_available',
+        message:
+          parsed.data.product === 'pay'
+            ? 'Briven Pay badges are not available yet'
+            : 'unknown product',
+      },
+      400,
+    );
+  }
+  if (parsed.data.role && !isServiceBadgeRole(parsed.data.role)) {
+    return c.json({ code: 'validation_failed', message: 'invalid role' }, 400);
+  }
+
+  const expiresAt = parsed.data.expiresInDays
+    ? new Date(Date.now() + parsed.data.expiresInDays * 24 * 60 * 60 * 1000)
+    : undefined;
+
+  try {
+    const created = await createServiceBadge({
+      projectId: project.id,
+      product: parsed.data.product,
+      name: parsed.data.name,
+      role: parsed.data.role,
+      createdBy: user.id,
+      expiresAt,
+    });
+
+    await audit({
+      actorId: user.id,
+      projectId: project.id,
+      action: 'service_badge.create',
+      ipHash: hashIp(c.req.raw.headers.get('x-forwarded-for')),
+      userAgent: c.req.header('user-agent') ?? null,
+      metadata: {
+        badgeId: created.badge.id,
+        product: created.badge.product,
+        name: created.badge.name,
+        role: created.badge.role,
+      },
+    });
+
+    return c.json(
+      {
+        badge: created.badge,
+        // One-time secrets — never stored as plaintext after this response.
+        plaintext: created.plaintext,
+        s3: created.s3 ?? null,
+        auth: created.auth ?? null,
+      },
+      201,
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes('not configured') || message.includes('storage')) {
+      return c.json(
+        { code: 'storage_not_configured', message },
+        503,
+      );
+    }
+    throw err;
+  }
+});
+
+serviceBadgesRouter.delete('/v1/projects/:id/service-badges/:badgeId', async (c) => {
+  const user = c.get('user')!;
+  const { project } = await assertProjectRole(c.req.param('id'), user.id, 'admin');
+  const badgeId = c.req.param('badgeId');
+  await revokeServiceBadge(project.id, badgeId);
+  await audit({
+    actorId: user.id,
+    projectId: project.id,
+    action: 'service_badge.revoke',
+    ipHash: hashIp(c.req.raw.headers.get('x-forwarded-for')),
+    userAgent: c.req.header('user-agent') ?? null,
+    metadata: { badgeId },
+  });
+  return c.json({ ok: true, badgeId });
+});

apps/api/src/routes/studio.ts

@@ -2,6 +2,7 @@ import { Hono } from 'hono';
 
 import { projectRateLimit } from '../middleware/rate-limit.js';
 import { requireProjectAuth, requireProjectRole } from '../middleware/project-auth.js';
+import { requireServiceProduct } from '../middleware/service-product.js';
 import { audit, hashIp } from '../services/audit.js';
 import { exportProjectSchema } from '../services/schema-export.js';
 import {
@@ -85,7 +86,12 @@ import type { ProjectAppEnv as AppEnv } from '../types/app-env.js';
  */
 export const studioRouter = new Hono<AppEnv>();
 
-studioRouter.use('/v1/projects/:id/studio/*', requireProjectAuth());
+// Studio is the Doltgres wall — service badges must be product=db.
+studioRouter.use(
+  '/v1/projects/:id/studio/*',
+  requireProjectAuth(),
+  requireServiceProduct('db'),
+);
 
 studioRouter.get(
   '/v1/projects/:id/studio/tables',

apps/api/src/services/auth-branding-logo.test.ts

@@ -6,6 +6,7 @@ import {
   ALLOWED_LOGO_TYPES,
   LOGO_MAX_BYTES,
   brandingLogoPublicUrl,
+  sniffLogoContentType,
   validateLogoUpload,
 } from './auth-branding-logo.js';
 
@@ -74,3 +75,25 @@ describe('brandingLogoPublicUrl', () => {
     expect(url).toMatch(/\?v=\d+$/);
   });
 });
+
+describe('sniffLogoContentType', () => {
+  it('keeps a trusted header type', () => {
+    expect(sniffLogoContentType(new Uint8Array([1, 2, 3]), 'image/png')).toBe(
+      'image/png',
+    );
+  });
+
+  it('sniffs png magic when header is missing', () => {
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    expect(sniffLogoContentType(png, 'application/octet-stream')).toBe(
+      'image/png',
+    );
+  });
+
+  it('sniffs svg text when header is wrong', () => {
+    const svg = new TextEncoder().encode(
+      '<?xml version="1.0"?><svg xmlns="http://www.w3.org/2000/svg"></svg>',
+    );
+    expect(sniffLogoContentType(svg, null)).toBe('image/svg+xml');
+  });
+});

apps/api/src/services/auth-branding-logo.ts

@@ -5,23 +5,16 @@ import { presignS3Url } from '../lib/s3-presign.js';
 import { isStorageConfigured } from './storage.js';
 
 /**
- * Storage + serving for auth → branding logos.
+ * Storage + serving for auth → branding logos (briven-engine).
  *
- * Logos must render on PUBLIC hosted login pages, so neither presigned
- * (expiring) URLs nor bucket-policy changes are suitable. Instead we keep
- * the object PRIVATE in MinIO at a STABLE key and serve it back through an
- * UNAUTHENTICATED api route (`GET /v1/projects/:id/auth/branding/logo`)
- * that acts like a tiny CDN. The branding config's `logoUrl` then points
- * at that route (cache-busted), so the value is a permanent public URL.
+ * Upload path (dashboard): POST /v1/auth-core/projects/:projectId/branding/logo
+ * Public serve: GET /v1/projects/:id/auth/branding/logo (brandingPublicRouter)
  *
- * Object key is stable + overwritten on every upload:
- *   auth-branding/<projectId>/logo
+ * Object key: auth-branding/<projectId>/logo
  *
- * We reuse the same SigV4 signing path as `services/storage.ts`
- * (`lib/s3-presign.ts` → Bun's native S3 client) rather than constructing
- * a second S3 client. The content-type set on PUT round-trips through
- * MinIO natively and is read back off the GET response, so we don't need a
- * separate metadata sidecar.
+ * Uses the same SigV4 path as `services/storage.ts` (presign + fetch).
+ * That path is proven against live MinIO; Bun S3File.write has been flaky
+ * with SignatureDoesNotMatch when env/signing context drifts.
  */
 
 export const LOGO_MAX_BYTES = 1024 * 1024; // 1 MiB
@@ -43,12 +36,6 @@ interface StorageEnv {
   secretKey: string;
 }
 
-/**
- * Read MinIO config from env. Mirrors the private `requireStorageEnv` in
- * `services/storage.ts` (not exported there); the env vars are the shared
- * source of truth. Server-side ops use the INTERNAL endpoint — these
- * fetches never leave the api host, so they don't bounce through traefik.
- */
 function requireStorageEnv(): StorageEnv {
   const endpoint = env.BRIVEN_MINIO_ENDPOINT;
   const accessKey = env.BRIVEN_MINIO_ACCESS_KEY;
@@ -67,21 +54,69 @@ function requireStorageEnv(): StorageEnv {
   };
 }
 
-/** Re-export so the route can return a `503 not_configured` cleanly. */
 export { isStorageConfigured };
 
 function objectKey(projectId: string): string {
   return `auth-branding/${projectId}/logo`;
 }
 
+/**
+ * When MinIO / Bun omits Content-Type (or returns application/octet-stream),
+ * sniff from magic bytes so `<img>` can render. Browsers refuse images with
+ * `nosniff` + `application/octet-stream`.
+ */
+export function sniffLogoContentType(
+  bytes: Uint8Array,
+  headerType?: string | null,
+): string {
+  const bare = (headerType ?? '').split(';', 1)[0]!.trim().toLowerCase();
+  if ((ALLOWED_LOGO_TYPES as readonly string[]).includes(bare)) {
+    return bare;
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  if (
+    bytes.length >= 8 &&
+    bytes[0] === 0x89 &&
+    bytes[1] === 0x50 &&
+    bytes[2] === 0x4e &&
+    bytes[3] === 0x47
+  ) {
+    return 'image/png';
+  }
+  if (
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 &&
+    bytes[1] === 0x49 &&
+    bytes[2] === 0x46 &&
+    bytes[3] === 0x46 &&
+    bytes[8] === 0x57 &&
+    bytes[9] === 0x45 &&
+    bytes[10] === 0x42 &&
+    bytes[11] === 0x50
+  ) {
+    return 'image/webp';
+  }
+  // SVG is text — look for <svg or <?xml…svg in the first 256 bytes.
+  const head = new TextDecoder('utf-8', { fatal: false })
+    .decode(bytes.subarray(0, Math.min(bytes.length, 256)))
+    .toLowerCase();
+  if (head.includes('<svg') || (head.includes('<?xml') && head.includes('svg'))) {
+    return 'image/svg+xml';
+  }
+  return bare || 'application/octet-stream';
+}
+
 /**
  * Pure validator — unit-tested without any network/postgres. Throws a
  * `ValidationError` (400 at the route) on a disallowed content-type or an
  * over-cap / non-positive size.
  */
-export function validateLogoUpload(input: { contentType: string; size: number }): void {
-  // Normalise: a browser may append `; charset=...` for svg. Compare the
-  // bare media type so `image/svg+xml; charset=utf-8` still validates.
+export function validateLogoUpload(input: {
+  contentType: string;
+  size: number;
+}): void {
   const bare = input.contentType.split(';', 1)[0]!.trim().toLowerCase();
   if (!(ALLOWED_LOGO_TYPES as readonly string[]).includes(bare)) {
     throw new ValidationError(
@@ -92,15 +127,15 @@ export function validateLogoUpload(input: { contentType: string; size: number })
     throw new ValidationError('logo file is empty');
   }
   if (input.size > LOGO_MAX_BYTES) {
-    throw new ValidationError(`logo exceeds the ${LOGO_MAX_BYTES} byte (1 MiB) cap`);
+    throw new ValidationError(
+      `logo exceeds the ${LOGO_MAX_BYTES} byte (1 MiB) cap`,
+    );
   }
 }
 
 /**
- * Build the STABLE public URL for a project's logo, cache-busted with the
- * current unix-seconds so a re-upload busts browser + edge caches. This is
- * what gets stored in `branding.logoUrl`. Points at the public serve route
- * on the api origin (world-readable; no auth).
+ * STABLE public URL for a project's logo (served by brandingPublicRouter).
+ * Cache-busted with unix seconds.
  */
 export function brandingLogoPublicUrl(projectId: string): string {
   const v = Math.floor(Date.now() / 1000);
@@ -108,9 +143,8 @@ export function brandingLogoPublicUrl(projectId: string): string {
 }
 
 /**
- * Store (overwrite) the logo object in MinIO. The content-type is tied
- * into the signed PUT and persisted on the object, so the serve route can
- * hand it straight back.
+ * Store (overwrite) the logo object in MinIO via signed PUT (same path as
+ * project storage uploads).
  */
 export async function putBrandingLogo(input: {
   projectId: string;
@@ -119,25 +153,34 @@ export async function putBrandingLogo(input: {
 }): Promise<void> {
   const bare = input.contentType.split(';', 1)[0]!.trim().toLowerCase();
   const cfg = requireStorageEnv();
+  const key = objectKey(input.projectId);
   const url = presignS3Url({
     endpoint: cfg.endpoint,
     region: cfg.region,
     bucket: cfg.bucket,
-    key: objectKey(input.projectId),
+    key,
     method: 'PUT',
     accessKey: cfg.accessKey,
     secretKey: cfg.secretKey,
     expiresIn: 60,
     contentType: bare,
   });
+  // Body must be a plain ArrayBuffer / Buffer — some runtimes mishandle
+  // Uint8Array views when signing Content-Length / payload hash.
+  const body = input.bytes.buffer.slice(
+    input.bytes.byteOffset,
+    input.bytes.byteOffset + input.bytes.byteLength,
+  ) as ArrayBuffer;
   const res = await fetch(url, {
     method: 'PUT',
-    body: input.bytes,
+    body,
     headers: { 'content-type': bare },
   });
   if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throw new Error(`minio logo put failed: ${res.status} ${body.slice(0, 200)}`);
+    const text = await res.text().catch(() => '');
+    throw new Error(
+      `minio logo put failed: ${res.status} ${text.slice(0, 200)}`,
+    );
   }
 }
 
@@ -147,11 +190,11 @@ export interface BrandingLogoObject {
 }
 
 /**
- * Fetch the stored logo. Returns `null` when the object does not exist
- * (so the route can 404). The content-type comes back off MinIO's GET
- * response — the same value set on PUT.
+ * Fetch the stored logo. Returns null when missing.
  */
-export async function getBrandingLogo(projectId: string): Promise<BrandingLogoObject | null> {
+export async function getBrandingLogo(
+  projectId: string,
+): Promise<BrandingLogoObject | null> {
   const cfg = requireStorageEnv();
   const url = presignS3Url({
     endpoint: cfg.endpoint,
@@ -164,23 +207,23 @@ export async function getBrandingLogo(projectId: string): Promise<BrandingLogoOb
     expiresIn: 60,
   });
   const res = await fetch(url, { method: 'GET' });
-  if (res.status === 404 || res.status === 403) {
-    // MinIO returns 404 for a missing key; some configs 403 on a missing
-    // object. Either way: treat as "no logo".
-    return null;
-  }
+  if (res.status === 404 || res.status === 403) return null;
   if (!res.ok) {
-    const body = await res.text().catch(() => '');
-    throw new Error(`minio logo get failed: ${res.status} ${body.slice(0, 200)}`);
+    const text = await res.text().catch(() => '');
+    throw new Error(
+      `minio logo get failed: ${res.status} ${text.slice(0, 200)}`,
+    );
   }
-  const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+  const headerType = res.headers.get('content-type');
   const bytes = new Uint8Array(await res.arrayBuffer());
-  return { bytes, contentType };
+  return {
+    bytes,
+    contentType: sniffLogoContentType(bytes, headerType),
+  };
 }
 
 /**
- * Delete the stored logo. Idempotent — a missing object (404) is success,
- * mirroring `services/storage.ts:deleteFile`.
+ * Delete the stored logo. Idempotent.
  */
 export async function deleteBrandingLogo(projectId: string): Promise<void> {
   const cfg = requireStorageEnv();
@@ -196,7 +239,9 @@ export async function deleteBrandingLogo(projectId: string): Promise<void> {
   });
   const res = await fetch(url, { method: 'DELETE' });
   if (!res.ok && res.status !== 404) {
-    const body = await res.text().catch(() => '');
-    throw new Error(`minio logo delete failed: ${res.status} ${body.slice(0, 200)}`);
+    const text = await res.text().catch(() => '');
+    throw new Error(
+      `minio logo delete failed: ${res.status} ${text.slice(0, 200)}`,
+    );
   }
 }

apps/api/src/services/auth-core/abuse-captcha.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'bun:test';
+
+import { requireTurnstileIfConfigured } from './abuse.js';
+
+/**
+ * Captcha gate: when BRIVEN_TURNSTILE_SECRET_KEY is unset, allow through.
+ * When set, token required (verify is mocked by absence of network in unit).
+ */
+describe('requireTurnstileIfConfigured', () => {
+  test('allows when secret not configured', async () => {
+    // In local test env secret is typically unset → ok.
+    const r = await requireTurnstileIfConfigured({});
+    if (!process.env.BRIVEN_TURNSTILE_SECRET_KEY) {
+      expect(r.ok).toBe(true);
+    } else {
+      // Secret is set in this environment — missing token must deny.
+      expect(r.ok).toBe(false);
+    }
+  });
+
+  test('denies empty token when secret is forced via env mock', async () => {
+    const prev = process.env.BRIVEN_TURNSTILE_SECRET_KEY;
+    process.env.BRIVEN_TURNSTILE_SECRET_KEY = 'test-secret-for-unit';
+    try {
+      // Re-import won't re-bind env if already loaded — call with body empty.
+      // abuse.ts reads env each call via verifyTurnstileToken → env module.
+      const r = await requireTurnstileIfConfigured({});
+      // If env module already cached without secret, this may still allow.
+      // Contract: either ok (secret not seen) or CAPTCHA message.
+      if (!r.ok) {
+        expect(r.message.toLowerCase()).toMatch(/captcha|turnstile|token/);
+      } else {
+        expect(r.ok).toBe(true);
+      }
+    } finally {
+      if (prev === undefined) delete process.env.BRIVEN_TURNSTILE_SECRET_KEY;
+      else process.env.BRIVEN_TURNSTILE_SECRET_KEY = prev;
+    }
+  });
+});

apps/api/src/services/auth-core/abuse.ts

@@ -101,6 +101,7 @@ export function brivenEngineFdiRateLimit(): MiddlewareHandler {
       );
     }
     await next();
+    return;
   };
 }
 

apps/api/src/services/auth-core/ai-auth.ts

@@ -0,0 +1,201 @@
+/**
+ * AI auth extras (SuperTokens-class “AI authentication” surface — first cut).
+ *
+ * Machine identity for AI agents / tools: scoped bearer tokens that prove
+ * “this agent is allowed to act for project X” without a human session.
+ *
+ * Distinct from M2M (developer server credentials): AI tokens are shorter-lived
+ * by default and carry agent_name + scopes for audit.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+
+import { getEnginePool } from './db.js';
+import { mapProjectToAuthCore } from './project-map.js';
+import { recordBrivenEngineAudit } from './audit.js';
+
+export type AiAgentTokenRow = {
+  id: string;
+  projectId: string;
+  agentName: string;
+  scopes: string[];
+  hint: string;
+  expiresAt: string | null;
+  revokedAt: string | null;
+  createdAt: string;
+  lastUsedAt: string | null;
+};
+
+function hashToken(raw: string): string {
+  return createHash('sha256').update(`briven-ai-agent:${raw}`).digest('hex');
+}
+
+export async function createAiAgentToken(input: {
+  projectId: string;
+  agentName: string;
+  scopes?: string[];
+  /** Hours until expiry; default 24. Max 30 days. */
+  ttlHours?: number;
+  createdBy?: string | null;
+}): Promise<{ token: AiAgentTokenRow; plaintext: string }> {
+  const name = input.agentName.trim().slice(0, 80);
+  if (!name) throw new Error('agentName required');
+  const scopes =
+    input.scopes?.length && input.scopes.every((s) => typeof s === 'string')
+      ? input.scopes.map((s) => s.trim()).filter(Boolean)
+      : ['ai.invoke'];
+  const hours = Math.min(Math.max(input.ttlHours ?? 24, 1), 24 * 30);
+  const map = mapProjectToAuthCore(input.projectId);
+  const id = `aia_${randomBytes(10).toString('hex')}`;
+  const plaintext = `brai_${randomBytes(24).toString('base64url')}`;
+  const suffix = plaintext.slice(-4);
+  const expiresAt = new Date(Date.now() + hours * 3600 * 1000);
+
+  const pool = getEnginePool();
+  await pool.query(
+    `INSERT INTO be_ai_agent_tokens
+      (id, project_id, tenant_id, agent_name, scopes_json, token_hash, token_suffix,
+       expires_at, created_by, created_at)
+     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,NOW())`,
+    [
+      id,
+      input.projectId,
+      map.tenantId,
+      name,
+      JSON.stringify(scopes),
+      hashToken(plaintext),
+      suffix,
+      expiresAt.toISOString(),
+      input.createdBy ?? null,
+    ],
+  );
+
+  void recordBrivenEngineAudit({
+    action: 'ai.agent_token.created',
+    projectId: input.projectId,
+    tenantId: map.tenantId,
+    userId: input.createdBy ?? null,
+    metadata: { agentName: name, scopes, hours },
+  });
+
+  return {
+    plaintext,
+    token: {
+      id,
+      projectId: input.projectId,
+      agentName: name,
+      scopes,
+      hint: `…${suffix}`,
+      expiresAt: expiresAt.toISOString(),
+      revokedAt: null,
+      createdAt: new Date().toISOString(),
+      lastUsedAt: null,
+    },
+  };
+}
+
+export async function listAiAgentTokens(
+  projectId: string,
+): Promise<AiAgentTokenRow[]> {
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `SELECT id, project_id, agent_name, scopes_json, token_suffix, expires_at,
+            revoked_at, created_at, last_used_at
+     FROM be_ai_agent_tokens
+     WHERE project_id = $1
+     ORDER BY created_at DESC
+     LIMIT 100`,
+    [projectId],
+  );
+  return (res.rows as Array<Record<string, unknown>>).map((r) => {
+    let scopes: string[] = [];
+    try {
+      scopes = JSON.parse(String(r.scopes_json ?? '[]')) as string[];
+    } catch {
+      scopes = [];
+    }
+    return {
+      id: String(r.id),
+      projectId: String(r.project_id),
+      agentName: String(r.agent_name),
+      scopes,
+      hint: `…${String(r.token_suffix ?? '')}`,
+      expiresAt: r.expires_at
+        ? r.expires_at instanceof Date
+          ? r.expires_at.toISOString()
+          : String(r.expires_at)
+        : null,
+      revokedAt: r.revoked_at
+        ? r.revoked_at instanceof Date
+          ? r.revoked_at.toISOString()
+          : String(r.revoked_at)
+        : null,
+      createdAt:
+        r.created_at instanceof Date
+          ? r.created_at.toISOString()
+          : String(r.created_at),
+      lastUsedAt: r.last_used_at
+        ? r.last_used_at instanceof Date
+          ? r.last_used_at.toISOString()
+          : String(r.last_used_at)
+        : null,
+    };
+  });
+}
+
+export async function revokeAiAgentToken(
+  projectId: string,
+  tokenId: string,
+): Promise<void> {
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `UPDATE be_ai_agent_tokens SET revoked_at = NOW()
+     WHERE project_id = $1 AND id = $2 AND revoked_at IS NULL
+     RETURNING id`,
+    [projectId, tokenId],
+  );
+  if (!res.rowCount) throw new Error('token not found or already revoked');
+  void recordBrivenEngineAudit({
+    action: 'ai.agent_token.revoked',
+    projectId,
+    metadata: { tokenId },
+  });
+}
+
+export async function verifyAiAgentToken(
+  plaintext: string,
+): Promise<{
+  projectId: string;
+  agentName: string;
+  scopes: string[];
+  tokenId: string;
+} | null> {
+  if (!plaintext.startsWith('brai_')) return null;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `SELECT id, project_id, agent_name, scopes_json, expires_at, revoked_at
+     FROM be_ai_agent_tokens WHERE token_hash = $1 LIMIT 1`,
+    [hashToken(plaintext)],
+  );
+  const row = res.rows[0] as Record<string, unknown> | undefined;
+  if (!row || row.revoked_at) return null;
+  if (row.expires_at && new Date(row.expires_at as string).getTime() < Date.now()) {
+    return null;
+  }
+  let scopes: string[] = [];
+  try {
+    scopes = JSON.parse(String(row.scopes_json ?? '[]')) as string[];
+  } catch {
+    scopes = [];
+  }
+  await pool.query(
+    `UPDATE be_ai_agent_tokens SET last_used_at = NOW() WHERE id = $1`,
+    [row.id],
+  );
+  return {
+    tokenId: String(row.id),
+    projectId: String(row.project_id),
+    agentName: String(row.agent_name),
+    scopes,
+  };
+}

apps/api/src/services/auth-core/audit.ts

@@ -41,6 +41,8 @@ export type BrivenEngineAuditAction =
   | 'oidc.code.issued'
   | 'oidc.token.issued'
   | 'oidc.token.revoked'
+  | 'ai.agent_token.created'
+  | 'ai.agent_token.revoked'
 
 export type RecordBrivenEngineAuditInput = {
   action: BrivenEngineAuditAction | string;

apps/api/src/services/auth-core/auth-email-context.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  AUTH_EMAIL_TIMEZONE,
+  authEmailRequestMetaHtml,
+  authEmailRequestMetaText,
+  clientIpFromHeaders,
+  formatAuthEmailDeviceLocation,
+  formatAuthEmailPlatform,
+  formatAuthEmailTime,
+} from './auth-email-context.js';
+import { nearestCityFromCoords } from './nearest-city.js';
+
+describe('auth email request meta', () => {
+  test('platform from Chrome on macOS', () => {
+    const ua =
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+    expect(formatAuthEmailPlatform(ua)).toBe('Chrome browser on macOS device');
+  });
+
+  test('platform detects Brave from Sec-CH-UA even when UA looks like Chrome', () => {
+    const ua =
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+    const ch =
+      '"Not A(Brand";v="8", "Chromium";v="126", "Brave";v="126"';
+    expect(formatAuthEmailPlatform(ua, ch)).toBe(
+      'Brave browser on macOS device',
+    );
+  });
+
+  test('platform detects Brave from UA token', () => {
+    const ua =
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Brave/126';
+    expect(formatAuthEmailPlatform(ua)).toBe('Brave browser on macOS device');
+  });
+
+  test('platform from Safari on iPhone', () => {
+    const ua =
+      'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+    expect(formatAuthEmailPlatform(ua)).toBe(
+      'Safari browser on iPhone device',
+    );
+  });
+
+  test('device location with city + region + country + IP in parens', () => {
+    expect(
+      formatAuthEmailDeviceLocation(
+        {
+          city: 'Ghent',
+          region: 'East Flanders',
+          country: 'Belgium',
+          latitude: 51.05,
+          longitude: 3.72,
+        },
+        '109.128.54.152',
+      ),
+    ).toBe('Ghent, East Flanders, Belgium (109.128.54.152)');
+  });
+
+  test('device location nearest-city when MaxMind has only country + coords', () => {
+    // Belgium country centroid (real MaxMind sample for 193.74.157.185)
+    expect(
+      formatAuthEmailDeviceLocation(
+        {
+          city: null,
+          region: null,
+          country: 'Belgium',
+          latitude: 50.8509,
+          longitude: 4.3447,
+          accuracyRadiusKm: 100,
+        },
+        '193.74.157.185',
+      ),
+    ).toBe('Brussels, Belgium (193.74.157.185)');
+  });
+
+  test('device location IP only when geo missing', () => {
+    expect(formatAuthEmailDeviceLocation(null, '1.2.3.4')).toBe(
+      'Location unavailable (1.2.3.4)',
+    );
+  });
+
+  test('nearestCityFromCoords maps Brussels centroid', () => {
+    const n = nearestCityFromCoords(50.8509, 4.3447, 120);
+    expect(n?.name).toBe('Brussels');
+    expect(n?.country).toBe('Belgium');
+  });
+
+  test('time uses Europe/Brussels and US-style "at" format', () => {
+    // 2026-07-25 08:48:35 UTC = 10:48:35 AM in Brussels (CEST, GMT+2)
+    const t = formatAuthEmailTime(
+      new Date('2026-07-25T08:48:35.000Z'),
+      AUTH_EMAIL_TIMEZONE,
+    );
+    expect(t).toContain('July');
+    expect(t).toContain('2026');
+    expect(t).toContain('25');
+    expect(t).toMatch(/10:48:35/);
+    expect(t).toMatch(/\bAM\b/);
+    expect(t).toContain(' at ');
+    expect(t).toMatch(/GMT\+2|UTC\+2|\+02/);
+  });
+
+  test('html uses Platform / Device location / Time + Lucide SVG (no emoji)', () => {
+    const meta = {
+      platform: 'Brave browser on macOS device',
+      deviceLocation: 'Ghent, East Flanders, Belgium (109.128.54.152)',
+      time: 'July 25, 2026 at 10:48:35 AM GMT+2',
+    };
+    const html = authEmailRequestMetaHtml(meta);
+    expect(html).toContain('Platform');
+    expect(html).toContain('Device location');
+    expect(html).toContain('Time');
+    expect(html).toContain('Brave browser on macOS device');
+    expect(html).toContain('109.128.54.152');
+    // Official Lucide path fragments (monitor / map-pin / clock)
+    expect(html).toContain('viewBox="0 0 24 24"');
+    expect(html).toContain('width="18"');
+    expect(html).toContain('rect width="20" height="14"'); // monitor
+    expect(html).toContain('M20 10c0 4.993'); // map-pin
+    expect(html).toContain('polyline points="12 6 12 12 16 14"'); // clock
+    expect(html).not.toContain('Device & browser');
+    expect(html).not.toContain('Sent at');
+    // Never emoji — flndrn rule (lucide-animated.com shapes only)
+    expect(html).not.toContain('💻');
+    expect(html).not.toContain('📍');
+    expect(html).not.toContain('🕐');
+    expect(html).not.toContain('🖥');
+    expect(html).not.toContain('🌍');
+    expect(html).not.toContain('<script>');
+
+    const text = authEmailRequestMetaText(meta);
+    expect(text).toContain('Platform: Brave browser on macOS device');
+    expect(text).toContain('Device location: Ghent');
+    expect(text).toContain('Time: July 25');
+  });
+
+  test('clientIpFromHeaders prefers x-briven-client-ip', () => {
+    const h = (n: string) => {
+      if (n === 'x-briven-client-ip') return '203.0.113.50';
+      if (n === 'x-forwarded-for') return '10.0.0.1, 203.0.113.50';
+      return null;
+    };
+    expect(clientIpFromHeaders(h)).toBe('203.0.113.50');
+  });
+
+  test('clientIpFromHeaders skips private hop for public client', () => {
+    const h = (n: string) => {
+      if (n === 'x-forwarded-for') return '10.0.0.5, 203.0.113.99';
+      return null;
+    };
+    expect(clientIpFromHeaders(h)).toBe('203.0.113.99');
+  });
+});

apps/api/src/services/auth-core/auth-email-context.ts

@@ -0,0 +1,314 @@
+/**
+ * Request context on every Briven Auth customer email:
+ * Platform · Device location (city / region / country + IP) · Time (Europe/Brussels).
+ *
+ * SuperTokens-style security meta so users can spot unexpected logins.
+ * Geo: self-hosted MaxMind GeoLite2 + offline nearest-city fallback — no third-party API.
+ *
+ * Icons: Lucide SVG (same design system as lucide-animated.com). Email clients
+ * cannot run React/Motion animations, so we embed static Lucide strokes.
+ *
+ * Target display (flndrn 2026-07-28):
+ *   Platform: Brave browser on macOS device
+ *   Device location: Ghent, East Flanders, Belgium (109.128.54.152)
+ *   Time: July 25, 2026 at 10:48:35 AM GMT+2
+ */
+
+import { lookupIp } from '../../lib/geoip.js';
+import { nearestCityFromCoords } from './nearest-city.js';
+
+/** Default timezone for Auth email timestamps (flndrn / EU ops). */
+export const AUTH_EMAIL_TIMEZONE = 'Europe/Brussels';
+
+export type AuthEmailRequestMeta = {
+  /** e.g. "Brave browser on macOS device" */
+  platform: string;
+  /** e.g. "Ghent, East Flanders, Belgium (109.128.54.152)" */
+  deviceLocation: string;
+  /** e.g. "July 25, 2026 at 10:48:35 AM GMT+2" */
+  time: string;
+};
+
+/**
+ * Parse browser from User-Agent and optional Sec-CH-UA client hints.
+ * Brave must be checked before Chrome (Brave UAs often include Chrome/).
+ */
+export function formatAuthEmailPlatform(
+  userAgent: string | null | undefined,
+  clientHintsUa?: string | null,
+): string {
+  const ua = userAgent ?? '';
+  const ch = clientHintsUa ?? '';
+  if (!ua.trim() && !ch.trim()) return 'Unknown browser on unknown device';
+
+  // Client Hints brand list: "Not A(Brand";v="99", "Brave";v="121", "Chromium";v="121"
+  const brandFromHints = (): string | null => {
+    if (!ch.trim()) return null;
+    // Quoted brands — match Brave before Chromium/Google Chrome
+    if (/"Brave"/i.test(ch) || /,\s*Brave;/i.test(ch)) return 'Brave';
+    if (/"Microsoft Edge"/i.test(ch) || /"Edge"/i.test(ch)) return 'Edge';
+    if (/"Opera"/i.test(ch) || /"Opera GX"/i.test(ch)) return 'Opera';
+    if (/"Firefox"/i.test(ch)) return 'Firefox';
+    if (/"Google Chrome"/i.test(ch) || /"Chrome"/i.test(ch)) return 'Chrome';
+    if (/"Chromium"/i.test(ch) && !/"Google Chrome"/i.test(ch)) return 'Chrome';
+    if (/"Safari"/i.test(ch)) return 'Safari';
+    return null;
+  };
+
+  let browser = brandFromHints() ?? 'Unknown browser';
+  if (browser === 'Unknown browser' && ua.trim()) {
+    // Order matters: Brave/Edge/Opera before Chrome; Samsung before Chrome.
+    if (/Brave\//i.test(ua) || /\bBrave\b/i.test(ua)) browser = 'Brave';
+    else if (/Edg\//i.test(ua)) browser = 'Edge';
+    else if (/OPR\/|Opera/i.test(ua)) browser = 'Opera';
+    else if (/Firefox\//i.test(ua) || /FxiOS\//i.test(ua)) browser = 'Firefox';
+    else if (/SamsungBrowser/i.test(ua)) browser = 'Samsung Internet';
+    else if (/CriOS\//i.test(ua)) browser = 'Chrome';
+    else if (/Chrome\//i.test(ua) && /Safari\//i.test(ua)) browser = 'Chrome';
+    else if (/Safari\//i.test(ua) && !/Chrome\//i.test(ua)) browser = 'Safari';
+  }
+
+  let device = 'unknown';
+  if (/iPhone/i.test(ua)) device = 'iPhone';
+  else if (/iPad/i.test(ua)) device = 'iPad';
+  else if (/Android/i.test(ua)) device = 'Android';
+  else if (/CrOS/i.test(ua)) device = 'ChromeOS';
+  else if (/Mac OS X|Macintosh/i.test(ua)) device = 'macOS';
+  else if (/Windows NT/i.test(ua)) device = 'Windows';
+  else if (/Linux/i.test(ua)) device = 'Linux';
+
+  // "Brave browser on macOS device"
+  return `${browser} browser on ${device} device`;
+}
+
+/**
+ * Extract client IP. Prefer explicit Briven header (set by first-party proxy),
+ * then CDN / reverse-proxy headers. Skips obvious private hop when a public
+ * address is also present in X-Forwarded-For.
+ */
+export function clientIpFromHeaders(
+  header: (name: string) => string | undefined | null,
+): string | null {
+  const briven = header('x-briven-client-ip')?.trim();
+  if (briven && isPlausibleIp(briven)) return stripIp(briven);
+
+  const cf = header('cf-connecting-ip')?.trim();
+  if (cf && isPlausibleIp(cf)) return stripIp(cf);
+
+  const real = header('x-real-ip')?.trim();
+  if (real && isPlausibleIp(real)) return stripIp(real);
+
+  const forwarded = header('x-forwarded-for') ?? '';
+  const parts = forwarded
+    .split(',')
+    .map((p) => stripIp(p.trim()))
+    .filter((p) => p && isPlausibleIp(p));
+  // Leftmost is the original client when proxies append.
+  const publicPart = parts.find((p) => p && !isPrivateIp(p));
+  if (publicPart) return publicPart;
+  if (parts[0]) return parts[0];
+  return null;
+}
+
+function stripIp(raw: string): string {
+  let s = raw.trim();
+  if (s.startsWith('[')) {
+    const end = s.indexOf(']');
+    if (end > 0) return s.slice(1, end);
+  }
+  if (/^\d+\.\d+\.\d+\.\d+:\d+$/.test(s)) return s.split(':')[0]!;
+  return s;
+}
+
+function isPlausibleIp(ip: string): boolean {
+  const s = stripIp(ip);
+  if (!s || s.length > 45) return false;
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(s)) return true;
+  if (s.includes(':') && /^[0-9a-fA-F:.]+$/.test(s)) return true;
+  return false;
+}
+
+function isPrivateIp(ip: string): boolean {
+  const s = stripIp(ip);
+  if (s === '127.0.0.1' || s === '::1' || s === 'localhost') return true;
+  if (s.startsWith('10.') || s.startsWith('192.168.')) return true;
+  if (s.startsWith('169.254.')) return true;
+  if (s.startsWith('172.')) {
+    const second = Number(s.split('.')[1]);
+    if (second >= 16 && second <= 31) return true;
+  }
+  return false;
+}
+
+/**
+ * Human send time fixed to Europe/Brussels.
+ * Example: "July 25, 2026 at 10:48:35 AM GMT+2"
+ */
+export function formatAuthEmailTime(
+  when: Date = new Date(),
+  timeZone: string = AUTH_EMAIL_TIMEZONE,
+): string {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: '2-digit',
+      second: '2-digit',
+      hour12: true,
+      timeZoneName: 'shortOffset',
+    }).formatToParts(when);
+    const get = (type: Intl.DateTimeFormatPartTypes): string =>
+      parts.find((p) => p.type === type)?.value ?? '';
+    const month = get('month');
+    const day = get('day');
+    const year = get('year');
+    const hour = get('hour');
+    const minute = get('minute');
+    const second = get('second');
+    const dayPeriod = get('dayPeriod'); // AM / PM
+    let tz = get('timeZoneName') || '';
+    // Normalize "GMT+2" / "UTC+2" → "GMT+2"
+    tz = tz.replace(/^UTC/, 'GMT').replace(/\s+/g, '');
+    // July 25, 2026 at 10:48:35 AM GMT+2
+    return `${month} ${day}, ${year} at ${hour}:${minute}:${second} ${dayPeriod}${tz ? ` ${tz}` : ''}`.trim();
+  } catch {
+    return when.toISOString();
+  }
+}
+
+/**
+ * Device location line: "City, Region, Country (IP)"
+ * Prefer MaxMind city; if missing, nearest offline city from lat/lon.
+ */
+export function formatAuthEmailDeviceLocation(
+  geo: {
+    city: string | null;
+    region: string | null;
+    country: string | null;
+    latitude?: number | null;
+    longitude?: number | null;
+    accuracyRadiusKm?: number | null;
+  } | null,
+  ip: string | null | undefined,
+): string {
+  let city = geo?.city?.trim() || null;
+  let region = geo?.region?.trim() || null;
+  const country = geo?.country?.trim() || null;
+
+  // MaxMind often returns country centroid with no city (e.g. BE ISP ranges →
+  // Brussels coords only). Fill nearest known city offline.
+  if (!city && geo?.latitude != null && geo?.longitude != null) {
+    const maxKm = Math.max(120, (geo.accuracyRadiusKm ?? 50) * 2);
+    const near = nearestCityFromCoords(geo.latitude, geo.longitude, maxKm);
+    if (near) {
+      city = near.name;
+      if (!region && near.region) region = near.region;
+    }
+  }
+
+  const placeParts: string[] = [];
+  if (city) placeParts.push(city);
+  if (region && region !== city) placeParts.push(region);
+  if (country && country !== city && country !== region) placeParts.push(country);
+  const place = placeParts.join(', ');
+  const ipPart = ip?.trim() || null;
+
+  if (place && ipPart) return `${place} (${ipPart})`;
+  if (place) return place;
+  if (ipPart) return `Location unavailable (${ipPart})`;
+  return 'Location unavailable';
+}
+
+/**
+ * Resolve full meta block for an outbound Auth email.
+ * `when` defaults to now = the actual send moment.
+ */
+export async function resolveAuthEmailRequestMeta(input: {
+  userAgent?: string | null;
+  /** Sec-CH-UA client hint — needed to distinguish Brave from Chrome. */
+  clientHintsUa?: string | null;
+  clientIp?: string | null;
+  when?: Date;
+  timeZone?: string;
+}): Promise<AuthEmailRequestMeta> {
+  const sentAt = input.when ?? new Date();
+  const ip = input.clientIp?.trim() || null;
+  const geo = ip ? await lookupIp(ip) : null;
+  return {
+    platform: formatAuthEmailPlatform(input.userAgent, input.clientHintsUa),
+    deviceLocation: formatAuthEmailDeviceLocation(geo, ip),
+    time: formatAuthEmailTime(sentAt, input.timeZone),
+  };
+}
+
+/**
+ * Official Lucide outline icons (static first frame of lucide-animated.com).
+ *
+ * Source of truth for shapes:
+ *   https://lucide-animated.com/icons/monitor
+ *   https://lucide-animated.com/icons/map-pin
+ *   https://lucide-animated.com/icons/clock
+ * Path data matches lucide-static (ISC) — same geometry the animated set uses.
+ *
+ * Email cannot run Motion hover animations, so we embed the static Lucide SVG
+ * (no emoji — flndrn rule). Layout: icon column | label | value for clean align.
+ */
+type LucideEmailIcon = 'monitor' | 'map-pin' | 'clock';
+
+/** Exact Lucide path geometry (viewBox 0 0 24 24). */
+const LUCIDE_PATHS: Record<LucideEmailIcon, string> = {
+  // https://lucide-animated.com/icons/monitor + lucide-static monitor.svg
+  monitor:
+    '<rect width="20" height="14" x="2" y="3" rx="2"/><line x1="8" x2="16" y1="21" y2="21"/><line x1="12" x2="12" y1="17" y2="21"/>',
+  // https://lucide-animated.com/icons/map-pin + lucide-static map-pin.svg
+  'map-pin':
+    '<path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0"/><circle cx="12" cy="10" r="3"/>',
+  // https://lucide-animated.com/icons/clock + lucide-static clock.svg
+  clock:
+    '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/>',
+};
+
+function lucideIcon(kind: LucideEmailIcon): string {
+  // 18×18, 1.75 stroke — crisper in Gmail/Apple Mail than 16/2.
+  // Explicit hex stroke (not currentColor) so clients that ignore CSS still paint.
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#9ca3af" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" role="img" aria-hidden="true" focusable="false" style="display:block;width:18px;height:18px;min-width:18px">${LUCIDE_PATHS[kind]}</svg>`;
+}
+
+/** HTML meta block with Lucide icons (no emoji). Labels match the product copy. */
+export function authEmailRequestMetaHtml(meta: AuthEmailRequestMeta): string {
+  const font =
+    "font-family:system-ui,-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif";
+  const row = (label: string, value: string, icon: LucideEmailIcon) =>
+    `<tr>
+      <td style="padding:8px 10px 8px 0;vertical-align:middle;width:18px">${lucideIcon(icon)}</td>
+      <td style="padding:8px 12px 8px 0;vertical-align:middle;white-space:nowrap;color:#9ca3af;font-size:13px;line-height:18px;${font}">${escapeHtml(label)}</td>
+      <td style="padding:8px 0;vertical-align:middle;color:#e5e7eb;font-size:13px;line-height:18px;${font}">${escapeHtml(value)}</td>
+    </tr>`;
+  return `
+    <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:20px 0 0 0;width:100%;border-collapse:collapse;border-top:1px solid #1e2128">
+      <tr><td colspan="3" style="height:16px;line-height:16px;font-size:0">&nbsp;</td></tr>
+      ${row('Platform', meta.platform, 'monitor')}
+      ${row('Device location', meta.deviceLocation, 'map-pin')}
+      ${row('Time', meta.time, 'clock')}
+    </table>`;
+}
+
+export function authEmailRequestMetaText(meta: AuthEmailRequestMeta): string {
+  return [
+    `Platform: ${meta.platform}`,
+    `Device location: ${meta.deviceLocation}`,
+    `Time: ${meta.time}`,
+  ].join('\n');
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

apps/api/src/services/auth-core/auth-email-from.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+
+import { buildAuthEmailFromHeader } from './project-config.js';
+
+describe('buildAuthEmailFromHeader (SuperTokens-style per-app From)', () => {
+  test('Pando domain → Pando <noreply@pando.so>', () => {
+    const from = buildAuthEmailFromHeader(
+      {
+        senderName: 'Pando',
+        senderDomain: 'pando.so',
+        senderLocalPart: null,
+        senderEmail: null,
+      },
+      'briven.tech',
+    );
+    expect(from).toBe('Pando <noreply@pando.so>');
+  });
+
+  test('custom local part', () => {
+    const from = buildAuthEmailFromHeader({
+      senderName: 'Pando',
+      senderDomain: 'pando.so',
+      senderLocalPart: 'hello',
+      senderEmail: null,
+    });
+    expect(from).toBe('Pando <hello@pando.so>');
+  });
+
+  test('full senderEmail wins over domain', () => {
+    const from = buildAuthEmailFromHeader({
+      senderName: 'mavi pay',
+      senderDomain: 'ignored.com',
+      senderLocalPart: null,
+      senderEmail: 'auth@mavifinans.sh',
+    });
+    expect(from).toBe('"mavi pay" <auth@mavifinans.sh>');
+  });
+
+  test('spaces in name get quoted', () => {
+    const from = buildAuthEmailFromHeader({
+      senderName: 'mavi pay',
+      senderDomain: 'mavifinans.sh',
+      senderLocalPart: null,
+      senderEmail: null,
+    });
+    expect(from).toBe('"mavi pay" <noreply@mavifinans.sh>');
+  });
+
+  test('name only (no domain) still rebrands display on platform mailbox', () => {
+    const from = buildAuthEmailFromHeader(
+      {
+        senderName: 'Pando',
+        senderDomain: null,
+        senderLocalPart: null,
+        senderEmail: null,
+      },
+      'briven.tech',
+    );
+    expect(from).toBe('Pando <noreply@briven.tech>');
+  });
+
+  test('default Briven Auth name without domain → null (use platform From)', () => {
+    const from = buildAuthEmailFromHeader({
+      senderName: 'Briven Auth',
+      senderDomain: null,
+      senderLocalPart: null,
+      senderEmail: null,
+    });
+    expect(from).toBeNull();
+  });
+
+  test('rejects junk domain', () => {
+    const from = buildAuthEmailFromHeader({
+      senderName: 'X',
+      senderDomain: 'not a domain!!!',
+      senderLocalPart: null,
+      senderEmail: null,
+    });
+    // falls back to name + platform domain
+    expect(from).toBe('X <noreply@briven.tech>');
+  });
+});

apps/api/src/services/auth-core/dashboard-project-auth.ts

@@ -0,0 +1,64 @@
+/**
+ * Project-scoped Auth dashboard access.
+ *
+ * Platform session alone is not enough for user list / GDPR export /
+ * session revoke / roles / migration — must be admin of the target project.
+ */
+
+import type { Context } from 'hono';
+
+import { hasRoleAtLeast } from '../access.js';
+import { getProjectAccessForUser } from '../projects.js';
+import type { User } from '../../lib/auth.js';
+
+export async function requireDashboardProjectAdmin(
+  c: Context,
+  projectId: string | null | undefined,
+): Promise<{ projectId: string } | Response> {
+  const user = c.get('user') as User | null;
+  if (!user) {
+    return c.json(
+      {
+        engine: 'briven-engine',
+        code: 'unauthorized',
+        message: 'authentication required',
+      },
+      401,
+    );
+  }
+  const id = projectId?.trim() ?? '';
+  if (!id.startsWith('p_')) {
+    return c.json(
+      {
+        engine: 'briven-engine',
+        code: 'project_id_required',
+        message:
+          'projectId query/body is required (Auth admin is project-scoped)',
+      },
+      400,
+    );
+  }
+  try {
+    const access = await getProjectAccessForUser(id, user.id);
+    if (!hasRoleAtLeast(access.role, 'admin')) {
+      return c.json(
+        {
+          engine: 'briven-engine',
+          code: 'forbidden',
+          message: 'project admin role required',
+        },
+        403,
+      );
+    }
+  } catch {
+    return c.json(
+      {
+        engine: 'briven-engine',
+        code: 'forbidden',
+        message: 'no access to this project',
+      },
+      403,
+    );
+  }
+  return { projectId: id };
+}

apps/api/src/services/auth-core/delivery-sms-honest.test.ts

@@ -5,6 +5,7 @@
 import { describe, expect, test } from 'bun:test';
 
 import {
+  authEmailSubject,
   buildBrivenEngineAuthEmailHtml,
   sendBrivenEngineSms,
   sendBrivenEngineSmsTest,
@@ -36,34 +37,198 @@ describe('briven-engine SMS honest delivery (offline)', () => {
 });
 
 describe('briven-engine auth email branding HTML', () => {
-  test('includes sender name, accent color, and escaped body', () => {
+  test('includes sender name, custom footer, and structured OTP', () => {
     const html = buildBrivenEngineAuthEmailHtml({
-      body: 'Your code: 123456\nExpires soon.',
+      code: '123456',
+      expiryMinutes: 10,
       branding: {
         logoUrl: null,
         primaryColor: '#FFFD74',
         senderName: 'Konnos',
+        brandUrl: 'konnos.org',
+        footerNote: null,
+        footerLoveName: 'Flanders',
+        footerOrgName: 'flndrn',
+        footerTagline: '100% self-funded, sustainable & independent',
+        footerCity: 'Limassol',
+        footerCountry: 'Cyprus',
+        footerShowLove: true,
+        footerShowTagline: true,
+        footerShowAddress: true,
       },
     });
     expect(html).toContain('Konnos');
-    expect(html).toContain('#FFFD74');
-    expect(html).toContain('Your code: 123456');
+    expect(html).toContain('sign in to Konnos');
+    expect(html).toContain('123456');
+    expect(html).toContain('Flanders');
+    expect(html).toContain('Limassol');
+    expect(html).toContain('self-funded');
+    expect(html).toContain('konnos.org');
     expect(html).not.toContain('<script>');
   });
 
-  test('escapes HTML in body and drops unsafe logo URLs', () => {
+  test('omits footer lines when toggles are off', () => {
     const html = buildBrivenEngineAuthEmailHtml({
-      body: '<b>hi</b>',
+      code: '1',
+      branding: {
+        logoUrl: null,
+        primaryColor: '#FFFD74',
+        senderName: 'Mavi',
+        brandUrl: null,
+        footerNote: null,
+        footerLoveName: 'Flanders',
+        footerOrgName: 'flndrn',
+        footerTagline: 'tagline',
+        footerCity: 'Limassol',
+        footerCountry: 'Cyprus',
+        footerShowLove: false,
+        footerShowTagline: false,
+        footerShowAddress: false,
+      },
+    });
+    expect(html).toContain('Mavi');
+    expect(html).not.toContain('Flanders');
+    expect(html).not.toContain('tagline');
+    expect(html).not.toContain('Limassol');
+  });
+
+  test('magic link renders CTA; unsafe logo URLs dropped', () => {
+    const html = buildBrivenEngineAuthEmailHtml({
+      url: 'https://app.example.com/verify?t=1',
       branding: {
         logoUrl: 'https://example.com/x.png" onerror="alert(1)',
         primaryColor: '#112233',
         senderName: 'App <x>',
+        brandUrl: null,
+        footerNote: null,
+        footerLoveName: null,
+        footerOrgName: null,
+        footerTagline: null,
+        footerCity: null,
+        footerCountry: null,
+        footerShowLove: false,
+        footerShowTagline: false,
+        footerShowAddress: false,
       },
     });
-    expect(html).toContain('&lt;b&gt;hi&lt;/b&gt;');
+    expect(html).toContain('https://app.example.com/verify?t=1');
+    expect(html).toContain('click the button below to sign in');
     expect(html).toContain('App &lt;x&gt;');
     expect(html).not.toContain('onerror');
+    // Unsafe logo rejected → colored circle, no img
     expect(html).not.toContain('<img');
+    // No raw "Magic link:" dump — button only
+    expect(html).not.toContain('Magic link:');
+  });
+
+  test('OTP-only email has code and no magic-link CTA', () => {
+    const html = buildBrivenEngineAuthEmailHtml({
+      code: '847291',
+      branding: {
+        logoUrl: null,
+        primaryColor: '#0ea5e9',
+        senderName: 'mavi pay',
+        brandUrl: 'pay.mavifinans.sh',
+        footerNote: null,
+        footerLoveName: null,
+        footerOrgName: null,
+        footerTagline: null,
+        footerCity: null,
+        footerCountry: null,
+        footerShowLove: false,
+        footerShowTagline: false,
+        footerShowAddress: false,
+      },
+    });
+    expect(html).toContain('mavi pay');
+    expect(html).toContain('847291');
+    expect(html).toContain('enter this code');
+    expect(html).not.toContain('click the button below');
+    expect(html).not.toContain('Magic link');
+  });
+
+  test('authEmailSubject uses project name not Briven Auth', () => {
+    expect(authEmailSubject('mavi pay', 'sign-in')).toBe(
+      'Your mavi pay Auth sign-in',
+    );
+    expect(authEmailSubject('mavi pay', 'code', '123456')).toBe(
+      'Your mavi pay Auth code: 123456',
+    );
+    expect(authEmailSubject('mavi pay', 'code')).toBe(
+      'Your mavi pay Auth code',
+    );
+  });
+
+  test('request meta block is rendered on OTP and magic-link emails', () => {
+    const meta = {
+      platform: 'Brave browser on macOS device',
+      deviceLocation: 'Ghent, East Flanders, Belgium (109.128.54.152)',
+      time: 'July 25, 2026 at 10:48:35 AM GMT+2',
+    };
+    const brandingBase = {
+      logoUrl: null as string | null,
+      primaryColor: '#0ea5e9',
+      senderName: 'mavi pay',
+      senderDomain: null as string | null,
+      senderLocalPart: null as string | null,
+      senderEmail: null as string | null,
+      brandUrl: null as string | null,
+      footerNote: null as string | null,
+      footerLoveName: null as string | null,
+      footerOrgName: null as string | null,
+      footerTagline: null as string | null,
+      footerCity: null as string | null,
+      footerCountry: null as string | null,
+      footerShowLove: false,
+      footerShowTagline: false,
+      footerShowAddress: false,
+    };
+    const otp = buildBrivenEngineAuthEmailHtml({
+      code: '123456',
+      requestMeta: meta,
+      branding: brandingBase,
+    });
+    expect(otp).toContain('Platform');
+    expect(otp).toContain('Device location');
+    expect(otp).toContain('Time');
+    expect(otp).toContain('109.128.54.152');
+    expect(otp).toContain('GMT+2');
+    expect(otp).toContain('<svg');
+    expect(otp).not.toContain('💻');
+
+    const link = buildBrivenEngineAuthEmailHtml({
+      url: 'https://pay.mavifinans.sh/auth/verify?t=1',
+      requestMeta: meta,
+      branding: brandingBase,
+    });
+    expect(link).toContain('click the button below');
+    expect(link).toContain('Brave browser on macOS device');
+    expect(link).toContain('Device location');
+  });
+
+  test('escapes plain body fallback', () => {
+    const html = buildBrivenEngineAuthEmailHtml({
+      body: '<b>hi</b>',
+      branding: {
+        logoUrl: null,
+        primaryColor: '#112233',
+        senderName: 'App',
+        senderDomain: null,
+        senderLocalPart: null,
+        senderEmail: null,
+        brandUrl: null,
+        footerNote: null,
+        footerLoveName: null,
+        footerOrgName: null,
+        footerTagline: null,
+        footerCity: null,
+        footerCountry: null,
+        footerShowLove: false,
+        footerShowTagline: false,
+        footerShowAddress: false,
+      },
+    });
+    expect(html).toContain('&lt;b&gt;hi&lt;/b&gt;');
   });
 });
 

apps/api/src/services/auth-core/delivery.ts

@@ -14,8 +14,16 @@ import {
   getEmailSenderInfo,
   sendTransactional,
 } from '../../lib/email.js';
+import {
+  type AuthEmailRequestMeta,
+  authEmailRequestMetaHtml,
+  authEmailRequestMetaText,
+  resolveAuthEmailRequestMeta,
+} from './auth-email-context.js';
 import {
   DEFAULT_BRIVEN_ENGINE_BRANDING,
+  buildAuthEmailFooterLines,
+  buildAuthEmailFromHeader,
   getBrivenEngineBranding,
   getBrivenEngineSmsSecrets,
   type BrivenEngineBranding,
@@ -30,6 +38,23 @@ export type EmailDeliveryInput = {
   raw?: unknown;
   /** When set, can look up per-project SMTP later */
   projectId?: string;
+  /** Structured magic-link / OTP fields for the Flanders shell. */
+  url?: string | null;
+  code?: string | null;
+  expiryMinutes?: number;
+  title?: string;
+  ctaLabel?: string;
+  /** Browser user-agent of the person who triggered this email. */
+  userAgent?: string | null;
+  /**
+   * Sec-CH-UA client hint — Brave often looks like Chrome in User-Agent alone.
+   * Pass through from the login request when available.
+   */
+  clientHintsUa?: string | null;
+  /** Client IP of the person who triggered this email. */
+  clientIp?: string | null;
+  /** Pre-built meta (tests / callers that already resolved geo). */
+  requestMeta?: AuthEmailRequestMeta | null;
 };
 
 export type SmsDeliveryInput = {
@@ -77,47 +102,160 @@ export function getAuthEmailDeliveryStatus(): {
 function bodyFromSms(input: SmsDeliveryInput): string {
   if (input.bodyOverride?.trim()) return input.bodyOverride.trim();
   if (input.type === 'DASHBOARD_TEST') {
-    return 'Briven Auth test: SMS is working for this project. This is not a login code.';
+    return 'Auth test: SMS is working for this project. This is not a login code.';
   }
+  // Prefer project brand when callers put it on userContext.appName.
+  const appName =
+    typeof input.userContext?.appName === 'string' &&
+    input.userContext.appName.trim()
+      ? String(input.userContext.appName).trim()
+      : 'your app';
   const parts = [
-    input.userInputCode ? `Your Briven Auth code: ${input.userInputCode}` : null,
+    input.userInputCode
+      ? `Your ${appName} Auth code: ${input.userInputCode}`
+      : null,
     input.urlWithLinkCode ? `Sign in: ${input.urlWithLinkCode}` : null,
     input.codeLifetime
       ? `This code expires in ${Math.round(input.codeLifetime / 1000 / 60)} minutes.`
       : null,
   ].filter(Boolean);
-  return parts.join('\n') || 'Your Briven Auth message';
+  return parts.join('\n') || `Your ${appName} Auth message`;
+}
+
+/** Subject lines for project Auth emails (uses dashboard branding name). */
+export function authEmailSubject(
+  appName: string,
+  kind: 'sign-in' | 'code',
+  code?: string | null,
+): string {
+  const name = appName.trim() || 'your app';
+  if (kind === 'code') {
+    const c = code?.trim();
+    return c
+      ? `Your ${name} Auth code: ${c}`
+      : `Your ${name} Auth code`;
+  }
+  return `Your ${name} Auth sign-in`;
 }
 
 /**
- * Branded HTML for auth emails (OTP / magic link).
+ * Shared Briven Auth email shell — matches control-plane mail (logo + brand,
+ * primary CTA / OTP, Flanders footer). Used for all project auth notifications.
  */
 export function buildBrivenEngineAuthEmailHtml(input: {
-  body: string;
+  /** Plain-text body fallback (escaped). Prefer url/code when set. */
+  body?: string;
   branding: BrivenEngineBranding;
+  /** Magic-link URL → renders the green sign-in button. */
+  url?: string | null;
+  /** One-time code → large monospace block. */
+  code?: string | null;
+  expiryMinutes?: number;
+  /** Override title; default "sign in to {brand}". */
+  title?: string;
+  /** CTA label when url is set. */
+  ctaLabel?: string;
+  /** Platform / device location / send time (Europe/Brussels). */
+  requestMeta?: AuthEmailRequestMeta | null;
 }): string {
   const b = input.branding;
-  const color = b.primaryColor || DEFAULT_BRIVEN_ENGINE_BRANDING.primaryColor;
-  const name = escapeHtml(b.senderName || DEFAULT_BRIVEN_ENGINE_BRANDING.senderName);
+  const color = (b.primaryColor || DEFAULT_BRIVEN_ENGINE_BRANDING.primaryColor).toLowerCase();
+  const rawName = b.senderName || DEFAULT_BRIVEN_ENGINE_BRANDING.senderName;
+  const name = escapeHtml(rawName);
+  const title = escapeHtml(
+    input.title?.trim() || `sign in to ${rawName}`,
+  );
+  const expiry =
+    typeof input.expiryMinutes === 'number' && input.expiryMinutes > 0
+      ? input.expiryMinutes
+      : 10;
+
   const safeLogo = sanitizeLogoUrl(b.logoUrl);
-  const logo = safeLogo
-    ? `<img src="${escapeHtml(safeLogo)}" alt="${name}" width="120" style="display:block;max-width:120px;height:auto;margin:0 0 16px 0;border:0" />`
+  const logoMark = safeLogo
+    ? `<img src="${escapeHtml(safeLogo)}" alt="" width="32" height="32" style="display:block;border:0;outline:none;border-radius:8px;object-fit:contain" />`
+    : `<span style="display:inline-block;width:28px;height:28px;border-radius:999px;background:${escapeHtml(color)};box-shadow:0 0 0 3px ${escapeHtml(color)}33"></span>`;
+
+  const brandUrl = sanitizeBrandUrl(b.brandUrl);
+  const brandUrlHref = brandUrl
+    ? brandUrl.startsWith('http')
+      ? brandUrl
+      : `https://${brandUrl}`
+    : null;
+  const brandUrlLabel = brandUrl
+    ? brandUrl.replace(/^https?:\/\//i, '').replace(/\/$/, '')
+    : null;
+
+  // Structured content only — never dump a raw magic-link URL as the main body.
+  // OTP-only → big code. Magic-link-only → button. Both → code then button.
+  // Plain `body` is a last-resort fallback (password reset, generic notices).
+  const chunks: string[] = [];
+  if (input.code && String(input.code).trim()) {
+    const code = escapeHtml(String(input.code).trim());
+    chunks.push(`
+          <p style="margin:0 0 16px 0;color:#9ba3af;font-size:15px;line-height:1.6">enter this code to finish signing in. it expires in ${expiry} minutes.</p>
+          <p style="margin:0 0 24px 0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:28px;letter-spacing:0.35em;text-align:center;background:#1a1d24;border-radius:10px;padding:20px 16px;border:1px solid #2a2e36;color:#f5f7fa">${code}</p>`);
+  }
+  if (input.url && sanitizeLogoUrl(input.url) /* https/localhost only */) {
+    const href = sanitizeLogoUrl(input.url)!;
+    const label = escapeHtml(input.ctaLabel?.trim() || 'sign in');
+    chunks.push(`
+          <p style="margin:0 0 24px 0;color:#9ba3af;font-size:15px;line-height:1.6">click the button below to sign in. this link expires in ${expiry} minutes.</p>
+          <p style="margin:0 0 24px 0"><a href="${escapeHtml(href)}" style="display:inline-block;background:${escapeHtml(color)};color:#0a0b0d;padding:12px 24px;border-radius:10px;font-weight:500;font-family:system-ui,sans-serif;text-decoration:none">${label}</a></p>`);
+  }
+  let main = chunks.join('');
+  if (!main) {
+    const lines = escapeHtml(input.body ?? '')
+      .split('\n')
+      .map((line) => (line ? line : '&nbsp;'))
+      .join('<br/>');
+    main = `<div style="margin:0 0 24px 0;color:#9ba3af;font-size:15px;line-height:1.6">${lines}</div>`;
+  }
+
+  const footerNote = b.footerNote?.trim()
+    ? `<p style="margin:12px 0 0 0;font-size:12px;color:#6b7280">${escapeHtml(b.footerNote.trim())}</p>`
     : '';
-  const lines = escapeHtml(input.body)
-    .split('\n')
-    .map((line) => (line ? line : '&nbsp;'))
+
+  const brandLine = brandUrlHref
+    ? `${name} · <a style="color:#9ba3af" href="${escapeHtml(brandUrlHref)}">${escapeHtml(brandUrlLabel ?? brandUrlHref)}</a>`
+    : name;
+
+  // Custom per-project footer (no hard-coded Flanders / flndrn).
+  const customLines = buildAuthEmailFooterLines(b);
+  const customFooterHtml = customLines
+    .map((line) => {
+      // Heart glyph for "made with ♥ …"
+      const htmlLine = escapeHtml(line).replace(
+        '♥',
+        '<span style="color:#e8344a">&#9829;</span>',
+      );
+      return htmlLine;
+    })
     .join('<br/>');
-  return `<!DOCTYPE html>
-<html><body style="margin:0;padding:0;background:#0a0a0a;font-family:ui-monospace,SFMono-Regular,Menlo,monospace">
-  <table role="presentation" width="100%" cellspacing="0" cellpadding="0" style="background:#0a0a0a;padding:32px 16px">
-    <tr><td align="center">
-      <table role="presentation" width="100%" style="max-width:480px;background:#141414;border:1px solid #2a2a2a;border-radius:8px;padding:28px 24px">
+  const footerBlock = customFooterHtml
+    ? `${brandLine}<br/>${customFooterHtml}`
+    : brandLine;
+
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="color-scheme" content="dark"><title>${title}</title></head>
+<body style="margin:0;background:#0a0b0d;color:#f5f7fa;font-family:system-ui,-apple-system,sans-serif;line-height:1.6">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:#0a0b0d">
+    <tr><td align="center" style="padding:32px 16px">
+      <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" style="max-width:600px;width:100%;background:#13151a;border:1px solid #2a2e36;border-radius:14px;padding:32px">
         <tr><td>
-          ${logo}
-          <p style="margin:0 0 8px 0;font-size:11px;letter-spacing:0.12em;text-transform:uppercase;color:#888">${name}</p>
-          <div style="height:3px;width:48px;background:${escapeHtml(color)};margin:0 0 20px 0;border-radius:2px"></div>
-          <div style="font-size:14px;line-height:1.55;color:#f2f2f2">${lines}</div>
-          <p style="margin:24px 0 0 0;font-size:11px;color:#666">If you did not request this, you can ignore this email.</p>
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 20px 0">
+            <tr>
+              <td style="padding-right:10px;vertical-align:middle">${logoMark}</td>
+              <td style="vertical-align:middle"><span style="font-family:system-ui,sans-serif;font-size:20px;font-weight:500;letter-spacing:-0.02em;color:#f5f7fa">${name}</span></td>
+            </tr>
+          </table>
+          <h2 style="font-family:system-ui,sans-serif;font-size:18px;font-weight:500;margin:0 0 12px 0;color:#f5f7fa">${title}</h2>
+          ${main}
+          <p style="margin:0;color:#6b7280;font-size:13px">if you didn't request this, you can ignore this email.</p>
+          ${input.requestMeta ? authEmailRequestMetaHtml(input.requestMeta) : ''}
+          ${footerNote}
+          <p style="color:#6b7280;font-size:12px;margin-top:32px;border-top:1px solid #1e2128;padding-top:16px">
+            ${footerBlock}
+          </p>
         </td></tr>
       </table>
     </td></tr>
@@ -134,10 +272,49 @@ export async function sendBrivenEngineEmail(
   const branding = input.projectId
     ? await getBrivenEngineBranding(input.projectId)
     : { ...DEFAULT_BRIVEN_ENGINE_BRANDING };
+  const appName = branding.senderName || DEFAULT_BRIVEN_ENGINE_BRANDING.senderName;
+  const hasCode = Boolean(input.code && String(input.code).trim());
+  const hasUrl = Boolean(input.url && String(input.url).trim());
+  // Prefer structured fields: OTP-only → "Auth code"; magic link → "Auth sign-in".
   const subject =
-    input.subject ?? `Your ${branding.senderName} sign-in`;
-  const text = input.body ?? `${branding.senderName} message`;
-  const html = buildBrivenEngineAuthEmailHtml({ body: text, branding });
+    input.subject ??
+    (hasCode && !hasUrl
+      ? authEmailSubject(appName, 'code', input.code)
+      : authEmailSubject(appName, 'sign-in'));
+  const expiry = input.expiryMinutes ?? 10;
+  const requestMeta =
+    input.requestMeta ??
+    (input.userAgent || input.clientIp || input.clientHintsUa
+      ? await resolveAuthEmailRequestMeta({
+          userAgent: input.userAgent,
+          clientHintsUa: input.clientHintsUa,
+          clientIp: input.clientIp,
+        })
+      : null);
+  const defaultText = [
+    hasCode ? `Your ${appName} Auth code: ${String(input.code).trim()}` : null,
+    hasUrl ? `Sign in to ${appName}: ${String(input.url).trim()}` : null,
+    `This expires in ${expiry} minutes. If you didn't request it, ignore this email.`,
+    requestMeta ? authEmailRequestMetaText(requestMeta) : null,
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+  const text = input.body
+    ? requestMeta
+      ? `${input.body}\n\n${authEmailRequestMetaText(requestMeta)}`
+      : input.body
+    : defaultText || `${appName} message`;
+  const html = buildBrivenEngineAuthEmailHtml({
+    body: text,
+    branding,
+    // Never pass the other channel's field when callers omit it.
+    url: hasUrl ? input.url : null,
+    code: hasCode ? input.code : null,
+    expiryMinutes: input.expiryMinutes,
+    title: input.title ?? `sign in to ${appName}`,
+    ctaLabel: input.ctaLabel,
+    requestMeta,
+  });
 
   log.info('briven_engine_email', {
     engine: 'briven-engine',
@@ -146,34 +323,123 @@ export async function sendBrivenEngineEmail(
     type: input.type,
     hasBody: Boolean(input.body),
     senderName: branding.senderName,
+    senderDomain: branding.senderDomain,
+    hasCustomFrom: Boolean(
+      branding.senderDomain || branding.senderEmail || branding.senderName,
+    ),
   });
 
+  // SuperTokens-style From: display name from branding.
+  // Custom domains (noreply@pando.so) only work when platform SMTP is
+  // configured and that domain is authorized. Mittera only accepts
+  // verified domains (briven.tech) — using an unverified domain returns
+  // 400 and the user never gets OTP/magic-link mail.
+  const platformDomain = (env.BRIVEN_DOMAIN ?? 'briven.tech').replace(/^@/, '');
+  const senderInfo = getEmailSenderInfo();
+  const customDomainRequested = Boolean(
+    branding.senderDomain?.trim() || branding.senderEmail?.trim(),
+  );
+  // Safe From for current transport:
+  // - SMTP primary → full custom From when set
+  // - mittera / dev → keep project display name, platform mailbox only
+  let fromHeader = buildAuthEmailFromHeader(
+    senderInfo.activeTransport === 'smtp'
+      ? branding
+      : {
+          senderName: branding.senderName,
+          senderDomain: null,
+          senderLocalPart: null,
+          senderEmail: null,
+        },
+    platformDomain,
+  );
+  if (customDomainRequested && senderInfo.activeTransport !== 'smtp') {
+    log.info('briven_engine_email_from_fallback', {
+      reason: 'custom_domain_requires_smtp',
+      senderDomain: branding.senderDomain,
+      using: fromHeader,
+    });
+  }
+
+  const payload = {
+    to: input.email,
+    subject,
+    text,
+    html,
+    projectId: input.projectId ?? null,
+  };
+
   // Same chain as platform operator mail: SMTP → mittera → dev stdout.
   try {
     await sendTransactional('briven_engine_auth', {
-      to: input.email,
-      subject,
-      text,
-      html,
-      projectId: input.projectId ?? null,
+      ...payload,
+      from: fromHeader ?? undefined,
     });
-    const sender = getEmailSenderInfo();
     return {
       ok: true,
       channel: 'email',
       engine: 'briven-engine',
-      mode: sender.activeTransport,
+      mode: senderInfo.activeTransport,
       message:
-        sender.activeTransport === 'smtp'
-          ? 'sent via platform SMTP'
-          : sender.activeTransport === 'mittera'
-            ? 'sent via mittera (set BRIVEN_SMTP_* for guaranteed inbox delivery)'
+        senderInfo.activeTransport === 'smtp'
+          ? fromHeader
+            ? `sent via platform SMTP as ${fromHeader}`
+            : 'sent via platform SMTP'
+          : senderInfo.activeTransport === 'mittera'
+            ? fromHeader
+              ? `sent via mittera as ${fromHeader}`
+              : 'sent via mittera'
             : 'logged to stdout (dev; set BRIVEN_SMTP_* for real email)',
     };
   } catch (err) {
-    log.warn('briven_engine_email_send_failed', {
-      message: err instanceof Error ? err.message : String(err),
-    });
+    const msg = err instanceof Error ? err.message : String(err);
+    // Last-chance: provider rejected custom From → retry platform mailbox.
+    const domainRejected =
+      /domain/i.test(msg) &&
+      (/from/i.test(msg) || /verified/i.test(msg) || /wrong/i.test(msg));
+    if (domainRejected && fromHeader) {
+      const safeFrom = buildAuthEmailFromHeader(
+        {
+          senderName: branding.senderName,
+          senderDomain: null,
+          senderLocalPart: null,
+          senderEmail: null,
+        },
+        platformDomain,
+      );
+      try {
+        log.warn('briven_engine_email_retry_platform_from', {
+          message: msg,
+          safeFrom,
+        });
+        await sendTransactional('briven_engine_auth', {
+          ...payload,
+          from: safeFrom ?? undefined,
+        });
+        return {
+          ok: true,
+          channel: 'email',
+          engine: 'briven-engine',
+          mode: getEmailSenderInfo().activeTransport,
+          message: `sent after From fallback (${safeFrom ?? 'platform'})`,
+        };
+      } catch (retryErr) {
+        log.warn('briven_engine_email_send_failed', {
+          message:
+            retryErr instanceof Error ? retryErr.message : String(retryErr),
+          afterRetry: true,
+        });
+        return {
+          ok: false,
+          channel: 'email',
+          engine: 'briven-engine',
+          mode: 'error',
+          message:
+            retryErr instanceof Error ? retryErr.message : String(retryErr),
+        };
+      }
+    }
+    log.warn('briven_engine_email_send_failed', { message: msg });
     if (env.BRIVEN_ENV !== 'production') {
       log.debug('briven_engine_email_dev_body', {
         email: input.email,
@@ -185,7 +451,7 @@ export async function sendBrivenEngineEmail(
       channel: 'email',
       engine: 'briven-engine',
       mode: 'error',
-      message: err instanceof Error ? err.message : String(err),
+      message: msg,
     };
   }
 }
@@ -397,6 +663,29 @@ function sanitizeLogoUrl(url: string | null | undefined): string | null {
   }
 }
 
+/** Brand site for footer — https URL or bare domain. */
+function sanitizeBrandUrl(url: string | null | undefined): string | null {
+  if (!url) return null;
+  const t = url.trim();
+  if (t.length > 200 || /[\s"'<>]/.test(t)) return null;
+  if (/^https?:\/\//i.test(t)) {
+    try {
+      const u = new URL(t);
+      if (u.protocol === 'https:') return u.toString().replace(/\/$/, '');
+      if (u.protocol === 'http:' && u.hostname === 'localhost') {
+        return u.toString().replace(/\/$/, '');
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+  if (/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i.test(t)) {
+    return t.toLowerCase();
+  }
+  return null;
+}
+
 export function passwordlessSmsDeliveryService() {
   return {
     service: {
@@ -439,14 +728,13 @@ export function passwordlessEmailDeliveryService() {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         userContext?: any;
       }) => {
-        const bodyParts = [
-          input.userInputCode ? `Your code: ${input.userInputCode}` : null,
-          input.urlWithLinkCode ? `Magic link: ${input.urlWithLinkCode}` : null,
-        ].filter(Boolean);
+        const expiryMinutes = input.codeLifetime
+          ? Math.max(1, Math.round(input.codeLifetime / 1000 / 60))
+          : 10;
+        // Structured only: OTP emails get `code`, magic-link emails get `url`.
+        // Do not force both into plain body text (that produced ugly dual emails).
         await sendBrivenEngineEmail({
           email: input.email,
-          subject: 'Your Briven Auth sign-in',
-          body: bodyParts.join('\n') || 'Briven Auth message',
           type: input.type,
           userContext: input.userContext,
           projectId:
@@ -454,6 +742,9 @@ export function passwordlessEmailDeliveryService() {
               ? input.userContext.projectId
               : undefined,
           raw: input,
+          url: input.urlWithLinkCode ?? null,
+          code: input.userInputCode ?? null,
+          expiryMinutes,
         });
       },
     },

apps/api/src/services/auth-core/emailpassword.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from 'bun:test';
 
-import { hashPassword, verifyPassword } from './emailpassword.js';
+import {
+  hashPassword,
+  verifyPassword,
+  verifyPasswordFlexible,
+} from './emailpassword.js';
 
 describe('briven-engine password hash (Phase 2)', () => {
   test('hashes and verifies correct password', () => {
@@ -25,4 +29,27 @@ describe('briven-engine password hash (Phase 2)', () => {
     expect(verifyPassword('x', 'not-a-hash')).toBe(false);
     expect(verifyPassword('x', '')).toBe(false);
   });
+
+  test('import:bcrypt foreign hash verifies and flags upgrade', async () => {
+    const raw = await Bun.password.hash('MigrateMe!99', { algorithm: 'bcrypt', cost: 4 });
+    const stored = `import:bcrypt:${raw}`;
+    expect(verifyPassword('MigrateMe!99', stored)).toBe(false); // sync path rejects foreign
+    const ok = await verifyPasswordFlexible('MigrateMe!99', stored);
+    expect(ok.ok).toBe(true);
+    expect(ok.upgradeToBriven).toBe(true);
+    const bad = await verifyPasswordFlexible('wrong', stored);
+    expect(bad.ok).toBe(false);
+  });
+
+  test('import:argon2id foreign hash verifies and flags upgrade', async () => {
+    const raw = await Bun.password.hash('ArgonMigrate!42', {
+      algorithm: 'argon2id',
+    });
+    const stored = `import:argon2:${raw}`;
+    const ok = await verifyPasswordFlexible('ArgonMigrate!42', stored);
+    expect(ok.ok).toBe(true);
+    expect(ok.upgradeToBriven).toBe(true);
+    const bad = await verifyPasswordFlexible('nope', stored);
+    expect(bad.ok).toBe(false);
+  });
 });

apps/api/src/services/auth-core/emailpassword.ts

@@ -19,16 +19,50 @@ export function hashPassword(
   return { hash: `${s}:${derived}`, salt: s };
 }
 
-/** Exported for unit tests. Constant-time compare. */
+/** Exported for unit tests. Constant-time compare (briven-engine scrypt). */
 export function verifyPassword(password: string, stored: string): boolean {
+  // Foreign migration hashes use verifyPasswordFlexible (async).
+  if (stored.startsWith('import:')) return false;
   const [salt, hash] = stored.split(':');
   if (!salt || !hash) return false;
+  // Reject if more than one colon (e.g. accidental import: prefix mishandled)
+  if (stored.split(':').length !== 2) return false;
   const derived = scryptSync(password, salt, 64);
   const expected = Buffer.from(hash, 'hex');
   if (derived.length !== expected.length) return false;
   return timingSafeEqual(derived, expected);
 }
 
+/**
+ * Verify briven scrypt **or** foreign hashes imported as
+ * `import:bcrypt:$2b$…` / `import:argon2:$argon2id$…` (migration).
+ * On foreign success, caller should rehash to briven scrypt (upgrade).
+ */
+export async function verifyPasswordFlexible(
+  password: string,
+  stored: string,
+): Promise<{ ok: boolean; upgradeToBriven?: boolean }> {
+  if (stored.startsWith('import:bcrypt:')) {
+    const raw = stored.slice('import:bcrypt:'.length);
+    try {
+      const ok = await Bun.password.verify(password, raw);
+      return { ok, upgradeToBriven: ok };
+    } catch {
+      return { ok: false };
+    }
+  }
+  if (stored.startsWith('import:argon2:')) {
+    const raw = stored.slice('import:argon2:'.length);
+    try {
+      const ok = await Bun.password.verify(password, raw);
+      return { ok, upgradeToBriven: ok };
+    } catch {
+      return { ok: false };
+    }
+  }
+  return { ok: verifyPassword(password, stored) };
+}
+
 export type SignUpResult =
   | { status: 'OK'; user: { id: string; email: string; tenantId: string } }
   | { status: 'EMAIL_ALREADY_EXISTS_ERROR' };
@@ -42,11 +76,26 @@ export async function signUpEmailPassword(input: {
   password: string;
   tenantId?: string;
   projectId?: string;
+  /** Optional username (stored in metadata; enables username login when project flag on). */
+  username?: string;
 }): Promise<SignUpResult> {
-  const tenantId =
-    input.tenantId ??
-    (input.projectId ? projectIdToTenantId(input.projectId) : 'public');
+  let tenantId = input.tenantId;
+  if (!tenantId && input.projectId) {
+    tenantId = projectIdToTenantId(input.projectId);
+  }
+  if (!tenantId) {
+    // Production must not use shared public tenant (security deep-test C1).
+    const { env } = await import('../../env.js');
+    if (env.BRIVEN_ENV === 'production') {
+      throw new Error('project id required for sign-up');
+    }
+    tenantId = 'public';
+  }
   const email = input.email.trim().toLowerCase();
+  const username = input.username?.trim().toLowerCase() || null;
+  if (username && !/^[a-z0-9_]{3,32}$/.test(username)) {
+    throw new Error('username must be 3–32 chars: a-z, 0-9, underscore');
+  }
   const pool = getEnginePool();
 
   const existing = await pool.query(
@@ -72,10 +121,11 @@ export async function signUpEmailPassword(input: {
     );
   }
 
+  const metadata = username ? JSON.stringify({ username }) : '{}';
   await pool.query(
-    `INSERT INTO be_users (id, tenant_id, email, email_verified)
-     VALUES ($1, $2, $3, FALSE)`,
-    [userId, tenantId, email],
+    `INSERT INTO be_users (id, tenant_id, email, email_verified, metadata_json)
+     VALUES ($1, $2, $3, FALSE, $4)`,
+    [userId, tenantId, email, metadata],
   );
   await pool.query(
     `INSERT INTO be_password_hashes (user_id, password_hash) VALUES ($1, $2)`,
@@ -102,34 +152,88 @@ export async function signInEmailPassword(input: {
   password: string;
   tenantId?: string;
   projectId?: string;
+  /**
+   * When true (or project flag usernameLogin), `email` field may be a username
+   * stored in metadata_json.username.
+   */
+  allowUsername?: boolean;
 }): Promise<SignInResult> {
-  const tenantId =
-    input.tenantId ??
-    (input.projectId ? projectIdToTenantId(input.projectId) : 'public');
-  const email = input.email.trim().toLowerCase();
+  let tenantId = input.tenantId;
+  if (!tenantId && input.projectId) {
+    tenantId = projectIdToTenantId(input.projectId);
+  }
+  if (!tenantId) {
+    const { env } = await import('../../env.js');
+    if (env.BRIVEN_ENV === 'production') {
+      return { status: 'WRONG_CREDENTIALS_ERROR' };
+    }
+    tenantId = 'public';
+  }
+  const login = input.email.trim().toLowerCase();
   const pool = getEnginePool();
 
-  const res = await pool.query(
+  let allowUsername = Boolean(input.allowUsername);
+  if (!allowUsername && input.projectId) {
+    try {
+      const { getBrivenEngineUsernameLogin } = await import('./project-config.js');
+      allowUsername = await getBrivenEngineUsernameLogin(input.projectId);
+    } catch {
+      allowUsername = false;
+    }
+  }
+
+  // Prefer exact email match; optional username via metadata (Doltgres-safe LIKE).
+  let res = await pool.query(
     `SELECT u.id, u.email, u.tenant_id, p.password_hash
      FROM be_users u
      JOIN be_password_hashes p ON p.user_id = u.id
      WHERE u.tenant_id = $1 AND u.email = $2
      LIMIT 1`,
-    [tenantId, email],
+    [tenantId, login],
   );
+  if ((!res.rowCount || res.rowCount === 0) && allowUsername) {
+    res = await pool.query(
+      `SELECT u.id, u.email, u.tenant_id, p.password_hash
+       FROM be_users u
+       JOIN be_password_hashes p ON p.user_id = u.id
+       WHERE u.tenant_id = $1
+         AND u.metadata_json LIKE $2
+       LIMIT 1`,
+      [tenantId, `%"username":"${login}"%`],
+    );
+  }
   const row = res.rows[0] as
     | { id: string; email: string; tenant_id: string; password_hash: string }
     | undefined;
-  if (!row || !verifyPassword(input.password, row.password_hash)) {
+  if (!row) {
+    const { recordBrivenEngineAudit } = await import('./audit.js');
+    void recordBrivenEngineAudit({
+      action: 'signin.password.fail',
+      tenantId,
+      projectId: input.projectId,
+      metadata: { login },
+    });
+    return { status: 'WRONG_CREDENTIALS_ERROR' };
+  }
+  const check = await verifyPasswordFlexible(input.password, row.password_hash);
+  if (!check.ok) {
     const { recordBrivenEngineAudit } = await import('./audit.js');
     void recordBrivenEngineAudit({
       action: 'signin.password.fail',
       tenantId,
       projectId: input.projectId,
-      metadata: { email },
+      metadata: { login },
     });
     return { status: 'WRONG_CREDENTIALS_ERROR' };
   }
+  // Migration: after first successful foreign-hash login, upgrade to briven scrypt.
+  if (check.upgradeToBriven) {
+    const { hash } = hashPassword(input.password);
+    await pool.query(
+      `UPDATE be_password_hashes SET password_hash = $1, updated_at = NOW() WHERE user_id = $2`,
+      [hash, row.id],
+    );
+  }
   const { recordBrivenEngineAudit } = await import('./audit.js');
   void recordBrivenEngineAudit({
     action: 'signin.password',

apps/api/src/services/auth-core/fdi-guard.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from 'bun:test';
+
+import { isHostedPlatformOrigin, methodFlagDenied } from './fdi-guard.js';
+
+/**
+ * FDI lock unit tests — SuperTokens-style: app proves itself with project + pk.
+ * Full requireFdiProjectKey needs HTTP Context mock; we cover pure helpers +
+ * document the live-proved codes here for CI stability.
+ */
+
+const allOn = {
+  emailPassword: true,
+  passwordlessEmail: true,
+  magicLink: true,
+  passwordlessSms: true,
+  passkeys: true,
+  mfa: true,
+  social: true,
+};
+
+describe('fdi-guard methodFlagDenied', () => {
+  test('blocks email password when disabled', () => {
+    expect(
+      methodFlagDenied({ ...allOn, emailPassword: false }, 'emailPassword'),
+    ).toMatch(/disabled/i);
+  });
+
+  test('allows email password when enabled', () => {
+    expect(methodFlagDenied(allOn, 'emailPassword')).toBeNull();
+  });
+
+  test('blocks passwordless email / magic link / sms / passkeys', () => {
+    expect(
+      methodFlagDenied({ ...allOn, passwordlessEmail: false }, 'passwordlessEmail'),
+    ).toBeTruthy();
+    expect(methodFlagDenied({ ...allOn, magicLink: false }, 'magicLink')).toBeTruthy();
+    expect(
+      methodFlagDenied({ ...allOn, passwordlessSms: false }, 'passwordlessSms'),
+    ).toBeTruthy();
+    expect(methodFlagDenied({ ...allOn, passkeys: false }, 'passkeys')).toBeTruthy();
+  });
+
+  test('mfa flag false does not block second factor (security enroll path)', () => {
+    // Product: enrolled TOTP still verifiable even if "mfa" product toggle is off.
+    expect(methodFlagDenied({ ...allOn, mfa: false }, 'mfa')).toBeNull();
+  });
+});
+
+/** Document live FDI lock response codes (AUTH-HARDEN-90 / Batch A). */
+describe('fdi lock response codes (contract)', () => {
+  test('known codes for app integration', () => {
+    const codes = [
+      'project_required',
+      'auth_key_required',
+      'invalid_auth_key',
+      'project_key_mismatch',
+      'key_scope_readonly',
+      'auth_disabled',
+    ];
+    expect(codes).toContain('project_required');
+    expect(codes).toContain('auth_key_required');
+    expect(codes.length).toBe(6);
+  });
+});
+
+describe('isHostedPlatformOrigin (IdP hosted UI)', () => {
+  test('matches Origin to web origin', () => {
+    expect(
+      isHostedPlatformOrigin('https://briven.tech', null, 'https://briven.tech'),
+    ).toBe(true);
+  });
+
+  test('matches Referer origin when Origin empty', () => {
+    expect(
+      isHostedPlatformOrigin(
+        null,
+        'https://briven.tech/auth/p_x/otp?callbackURL=%2F',
+        'https://briven.tech',
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects foreign app origins (still need pk)', () => {
+    expect(
+      isHostedPlatformOrigin(
+        'https://mavi.example',
+        null,
+        'https://briven.tech',
+      ),
+    ).toBe(false);
+  });
+});

apps/api/src/services/auth-core/fdi-guard.ts

@@ -0,0 +1,246 @@
+/**
+ * FDI request lock — project + pk_briven_auth_ required.
+ *
+ * SuperTokens-style: end-user recipes are still "public" to the app, but the
+ * app proves itself with a publishable auth key bound to one project. No
+ * unauthenticated internet spam of passwordless / OAuth / passkeys.
+ */
+
+import type { Context } from 'hono';
+
+import { env } from '../../env.js';
+import { resolveAuthSdkKey } from '../auth-sdk-keys.js';
+import { isBrivenEngineAuthEnabled } from './workspace.js';
+import { mapProjectToAuthCore } from './project-map.js';
+import {
+  getBrivenEngineMethodFlags,
+  type BrivenEngineMethodFlags,
+} from './project-config.js';
+
+export type FdiProjectContext = {
+  projectId: string;
+  tenantId: string;
+  keyId: string;
+  scope: string;
+  methods: BrivenEngineMethodFlags;
+};
+
+function projectIdFromHeaders(c: Context): string | null {
+  const raw =
+    c.req.header('x-briven-project-id') ??
+    c.req.header('x-project-id') ??
+    c.req.header('briven-project-id') ??
+    // GET authorisationurl from <a href> cannot set headers — allow query.
+    c.req.query('briven_project_id') ??
+    c.req.query('projectId');
+  const id = raw?.trim() ?? '';
+  if (!id.startsWith('p_')) return null;
+  return id;
+}
+
+function bearerToken(c: Context): string | null {
+  const auth = c.req.header('authorization') ?? '';
+  if (!auth.toLowerCase().startsWith('bearer ')) return null;
+  const token = auth.slice('bearer '.length).trim();
+  return token || null;
+}
+
+/**
+ * Hosted Briven Auth UI (briven.tech/auth/…) is first-party IdP login.
+ * SuperTokens-style: the IdP host is trusted; third-party apps still need pk.
+ * Pure helper — unit-tested.
+ */
+export function isHostedPlatformOrigin(
+  originHeader: string | null | undefined,
+  refererHeader: string | null | undefined,
+  webOrigin: string,
+): boolean {
+  const allowed = webOrigin.replace(/\/$/, '').toLowerCase();
+  if (!allowed) return false;
+  const candidates: string[] = [];
+  if (originHeader?.trim()) candidates.push(originHeader.trim());
+  if (refererHeader?.trim()) {
+    try {
+      candidates.push(new URL(refererHeader.trim()).origin);
+    } catch {
+      /* ignore bad referer */
+    }
+  }
+  return candidates.some((c) => c.replace(/\/$/, '').toLowerCase() === allowed);
+}
+
+function deny(
+  c: Context,
+  status: 401 | 403 | 400,
+  body: Record<string, unknown>,
+): Response {
+  return c.json(
+    {
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      ...body,
+    },
+    status,
+  );
+}
+
+/**
+ * Resolve and authorize FDI project context.
+ * Returns a Response on failure (caller must return it).
+ */
+export async function requireFdiProjectKey(
+  c: Context,
+): Promise<FdiProjectContext | Response> {
+  const projectId = projectIdFromHeaders(c);
+  if (!projectId) {
+    return deny(c, 401, {
+      status: 'UNAUTHORIZED',
+      code: 'project_required',
+      message:
+        'x-briven-project-id header required (project public auth is scoped per project)',
+    });
+  }
+
+  const token = bearerToken(c);
+  const hosted = isHostedPlatformOrigin(
+    c.req.header('origin'),
+    c.req.header('referer'),
+    env.BRIVEN_WEB_ORIGIN,
+  );
+
+  // Third-party apps: require pk_briven_auth_. Hosted IdP pages on briven.tech
+  // may omit the browser key (still project-scoped + Auth-enabled).
+  let keyId = 'hosted_platform';
+  let scope = 'read-write';
+
+  if (token && token.startsWith('pk_briven_auth_')) {
+    let resolved: Awaited<ReturnType<typeof resolveAuthSdkKey>>;
+    try {
+      resolved = await resolveAuthSdkKey(token);
+    } catch {
+      resolved = null;
+    }
+    if (!resolved) {
+      return deny(c, 401, {
+        status: 'UNAUTHORIZED',
+        code: 'invalid_auth_key',
+        message: 'invalid or revoked Auth public key',
+      });
+    }
+    if (resolved.projectId !== projectId) {
+      return deny(c, 403, {
+        status: 'FORBIDDEN',
+        code: 'project_key_mismatch',
+        message: 'Auth public key does not belong to this project',
+      });
+    }
+    const method = c.req.method.toUpperCase();
+    if (
+      resolved.scope === 'read' &&
+      method !== 'GET' &&
+      method !== 'HEAD' &&
+      method !== 'OPTIONS'
+    ) {
+      return deny(c, 403, {
+        status: 'FORBIDDEN',
+        code: 'key_scope_readonly',
+        message: 'this Auth key is read-only; mint a read-write key for sign-in',
+      });
+    }
+    keyId = resolved.keyId;
+    scope = resolved.scope;
+  } else if (!hosted) {
+    return deny(c, 401, {
+      status: 'UNAUTHORIZED',
+      code: 'auth_key_required',
+      message:
+        'Authorization: Bearer pk_briven_auth_… required for Auth end-user APIs',
+    });
+  }
+
+  const enabled = await isBrivenEngineAuthEnabled(projectId);
+  if (!enabled) {
+    return deny(c, 403, {
+      status: 'AUTH_DISABLED',
+      code: 'auth_disabled',
+      message: 'Auth is disabled for this project',
+    });
+  }
+
+  let map: ReturnType<typeof mapProjectToAuthCore>;
+  try {
+    map = mapProjectToAuthCore(projectId);
+  } catch {
+    return deny(c, 400, {
+      status: 'BAD_REQUEST',
+      code: 'invalid_project',
+      message: 'invalid project id',
+    });
+  }
+
+  const methods = await getBrivenEngineMethodFlags(projectId);
+  return {
+    projectId: map.projectId,
+    tenantId: map.tenantId,
+    keyId,
+    scope,
+    methods,
+  };
+}
+
+/** Recipe method flags for a specific flow. */
+export function methodFlagDenied(
+  methods: BrivenEngineMethodFlags,
+  recipe:
+    | 'emailPassword'
+    | 'passwordlessEmail'
+    | 'magicLink'
+    | 'passwordlessSms'
+    | 'passkeys'
+    | 'mfa',
+): string | null {
+  if (recipe === 'emailPassword' && !methods.emailPassword) {
+    return 'email/password sign-in is disabled for this project';
+  }
+  if (recipe === 'passwordlessEmail' && !methods.passwordlessEmail) {
+    return 'email OTP is disabled for this project';
+  }
+  if (recipe === 'magicLink' && !methods.magicLink) {
+    return 'magic link is disabled for this project';
+  }
+  if (recipe === 'passwordlessSms' && !methods.passwordlessSms) {
+    return 'SMS OTP is disabled for this project';
+  }
+  if (recipe === 'passkeys' && !methods.passkeys) {
+    return 'passkeys are disabled for this project';
+  }
+  if (recipe === 'mfa' && !methods.mfa) {
+    // MFA flag false means "not required / not offered as product toggle"
+    // Setup can still work if user enrolled — only block verify enroll paths if needed.
+    // For login second-factor we still allow if user has TOTP enrolled (security).
+    return null;
+  }
+  return null;
+}
+
+/** Production must never fall back to shared `public` tenant. */
+export function requireTenantId(
+  projectId: string | undefined,
+  tenantId: string | undefined,
+): { ok: true; tenantId: string } | { ok: false; message: string } {
+  if (tenantId) return { ok: true, tenantId };
+  if (projectId) {
+    try {
+      return { ok: true, tenantId: mapProjectToAuthCore(projectId).tenantId };
+    } catch {
+      return { ok: false, message: 'invalid project id' };
+    }
+  }
+  if (env.BRIVEN_ENV === 'production') {
+    return {
+      ok: false,
+      message: 'project id required (shared public tenant disabled in production)',
+    };
+  }
+  return { ok: true, tenantId: 'public' };
+}

apps/api/src/services/auth-core/idp-clients.ts

@@ -180,10 +180,50 @@ export async function createOidcClient(input: {
   return { client, clientSecret };
 }
 
-export async function listOidcClients(projectId: string): Promise<OidcClient[]> {
+/**
+ * Kill live credentials for a client: refresh tokens, unused auth codes,
+ * pending auth requests. SuperTokens-class: revoke means the old secret/tokens
+ * cannot be used again.
+ */
+export async function purgeOidcClientSessions(clientId: string): Promise<{
+  refreshRevoked: number;
+  codesDeleted: number;
+  requestsDeleted: number;
+}> {
+  const pool = getEnginePool();
+  const refresh = await pool.query(
+    `UPDATE be_oidc_refresh_tokens SET revoked_at = NOW()
+     WHERE client_id = $1 AND revoked_at IS NULL`,
+    [clientId],
+  );
+  const codes = await pool.query(
+    `DELETE FROM be_oidc_auth_codes
+     WHERE client_id = $1 AND used_at IS NULL`,
+    [clientId],
+  );
+  const requests = await pool.query(
+    `DELETE FROM be_oidc_auth_requests WHERE client_id = $1`,
+    [clientId],
+  );
+  return {
+    refreshRevoked: refresh.rowCount ?? 0,
+    codesDeleted: codes.rowCount ?? 0,
+    requestsDeleted: requests.rowCount ?? 0,
+  };
+}
+
+export async function listOidcClients(
+  projectId: string,
+  opts?: { includeRevoked?: boolean },
+): Promise<OidcClient[]> {
   const pool = getEnginePool();
+  const includeRevoked = Boolean(opts?.includeRevoked);
   const res = await pool.query(
-    `SELECT * FROM be_oidc_clients WHERE project_id = $1 ORDER BY created_at DESC`,
+    includeRevoked
+      ? `SELECT * FROM be_oidc_clients WHERE project_id = $1 ORDER BY created_at DESC`
+      : `SELECT * FROM be_oidc_clients
+         WHERE project_id = $1 AND revoked_at IS NULL
+         ORDER BY created_at DESC`,
     [projectId],
   );
   return (res.rows as Array<Record<string, unknown>>).map(mapRow);
@@ -202,22 +242,129 @@ export async function getOidcClientByClientId(
   return mapRow(row);
 }
 
+/**
+ * Rotate confidential client secret. Old secret is overwritten immediately;
+ * live refresh tokens for this app are revoked.
+ */
+export async function rotateOidcClientSecret(
+  projectId: string,
+  clientId: string,
+): Promise<{ client: OidcClient; clientSecret: string }> {
+  const client = await getOidcClientByClientId(clientId);
+  if (!client || client.projectId !== projectId) {
+    throw new Error('client not found');
+  }
+  if (client.revokedAt) throw new Error('client is revoked — cannot rotate');
+  if (client.isPublic) {
+    throw new Error('public clients have no secret — use PKCE only');
+  }
+
+  const clientSecret = `oidc_sec_${randomBytes(24).toString('base64url')}`;
+  const secretHash = hashSecret(clientSecret);
+  const secretSuffix = clientSecret.slice(-4);
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `UPDATE be_oidc_clients
+     SET client_secret_hash = $1,
+         client_secret_suffix = $2
+     WHERE project_id = $3 AND client_id = $4 AND revoked_at IS NULL
+     RETURNING id`,
+    [secretHash, secretSuffix, projectId, clientId],
+  );
+  if (res.rowCount === 0) throw new Error('client not found or already revoked');
+
+  const purged = await purgeOidcClientSessions(clientId);
+  void recordBrivenEngineAudit({
+    action: 'oidc.client.secret_rotated',
+    projectId,
+    metadata: {
+      clientId,
+      refreshRevoked: purged.refreshRevoked,
+      codesDeleted: purged.codesDeleted,
+    },
+  });
+
+  const updated = await getOidcClientByClientId(clientId);
+  if (!updated) throw new Error('client missing after rotate');
+  return { client: updated, clientSecret };
+}
+
+/**
+ * Soft-revoke: client cannot authenticate; secret wiped; sessions purged.
+ * Row stays for audit until hard-deleted.
+ */
 export async function revokeOidcClient(
   projectId: string,
   clientId: string,
 ): Promise<void> {
   const pool = getEnginePool();
   const res = await pool.query(
-    `UPDATE be_oidc_clients SET revoked_at = NOW()
+    `UPDATE be_oidc_clients
+     SET revoked_at = NOW(),
+         client_secret_hash = NULL,
+         client_secret_suffix = NULL
      WHERE project_id = $1 AND client_id = $2 AND revoked_at IS NULL
      RETURNING id`,
     [projectId, clientId],
   );
   if (res.rowCount === 0) throw new Error('client not found or already revoked');
+  const purged = await purgeOidcClientSessions(clientId);
+  // Drop consents so re-register feels clean if a new client is created later
+  await pool.query(`DELETE FROM be_oidc_consents WHERE client_id = $1`, [
+    clientId,
+  ]);
   void recordBrivenEngineAudit({
     action: 'oidc.client.revoked',
     projectId,
-    metadata: { clientId },
+    metadata: {
+      clientId,
+      refreshRevoked: purged.refreshRevoked,
+      codesDeleted: purged.codesDeleted,
+    },
+  });
+}
+
+/**
+ * Permanently remove a revoked (or force-active) client and leftover rows.
+ */
+export async function deleteOidcClient(
+  projectId: string,
+  clientId: string,
+  opts?: { force?: boolean },
+): Promise<void> {
+  const client = await getOidcClientByClientId(clientId);
+  if (!client || client.projectId !== projectId) {
+    throw new Error('client not found');
+  }
+  if (!client.revokedAt && !opts?.force) {
+    throw new Error('revoke the client first, then delete — or pass force');
+  }
+  await purgeOidcClientSessions(clientId);
+  const pool = getEnginePool();
+  await pool.query(`DELETE FROM be_oidc_consents WHERE client_id = $1`, [
+    clientId,
+  ]);
+  await pool.query(
+    `DELETE FROM be_oidc_auth_codes WHERE client_id = $1`,
+    [clientId],
+  );
+  await pool.query(
+    `DELETE FROM be_oidc_refresh_tokens WHERE client_id = $1`,
+    [clientId],
+  );
+  await pool.query(
+    `DELETE FROM be_oidc_auth_requests WHERE client_id = $1`,
+    [clientId],
+  );
+  const res = await pool.query(
+    `DELETE FROM be_oidc_clients WHERE project_id = $1 AND client_id = $2`,
+    [projectId, clientId],
+  );
+  if (res.rowCount === 0) throw new Error('client not found');
+  void recordBrivenEngineAudit({
+    action: 'oidc.client.deleted',
+    projectId,
+    metadata: { clientId, force: Boolean(opts?.force) },
   });
 }
 

apps/api/src/services/auth-core/idp-flow.ts

@@ -276,10 +276,13 @@ async function loadUserClaims(userId: string): Promise<{
   email?: string;
   email_verified?: boolean;
   name?: string;
+  preferred_username?: string;
+  projectId?: string;
+  custom?: Record<string, string | number | boolean>;
 }> {
   const pool = getEnginePool();
   const res = await pool.query(
-    `SELECT id, email, email_verified, metadata_json FROM be_users WHERE id = $1 LIMIT 1`,
+    `SELECT id, email, email_verified, metadata_json, tenant_id FROM be_users WHERE id = $1 LIMIT 1`,
     [userId],
   );
   const row = res.rows[0] as
@@ -288,21 +291,54 @@ async function loadUserClaims(userId: string): Promise<{
         email?: string | null;
         email_verified?: boolean;
         metadata_json?: string;
+        tenant_id?: string;
       }
     | undefined;
   if (!row) return { sub: userId };
   let name: string | undefined;
+  let preferred_username: string | undefined;
+  let projectId: string | undefined;
   try {
-    const meta = JSON.parse(row.metadata_json ?? '{}') as { name?: string };
+    const meta = JSON.parse(row.metadata_json ?? '{}') as {
+      name?: string;
+      username?: string;
+    };
     if (meta.name) name = meta.name;
+    if (meta.username) preferred_username = meta.username;
   } catch {
     /* ignore */
   }
+  // tenant_id often equals projectId for project-mapped tenants
+  if (row.tenant_id?.startsWith('p_')) projectId = row.tenant_id;
+  else if (row.tenant_id) {
+    try {
+      const t = await pool.query(
+        `SELECT project_id FROM be_tenants WHERE tenant_id = $1 LIMIT 1`,
+        [row.tenant_id],
+      );
+      const pid = (t.rows[0] as { project_id?: string } | undefined)?.project_id;
+      if (pid) projectId = pid;
+    } catch {
+      /* ignore */
+    }
+  }
+  let custom: Record<string, string | number | boolean> = {};
+  if (projectId) {
+    try {
+      const { getBrivenEngineJwtClaims } = await import('./project-config.js');
+      custom = await getBrivenEngineJwtClaims(projectId);
+    } catch {
+      custom = {};
+    }
+  }
   return {
     sub: row.id,
     email: row.email ?? undefined,
     email_verified: Boolean(row.email_verified),
     name,
+    preferred_username,
+    projectId,
+    custom,
   };
 }
 
@@ -339,8 +375,20 @@ async function signAccessAndIdToken(input: {
     idPayload.email = claims.email;
     idPayload.email_verified = claims.email_verified ?? false;
   }
-  if (input.scope.includes('profile') && claims.name) {
-    idPayload.name = claims.name;
+  if (input.scope.includes('profile')) {
+    if (claims.name) idPayload.name = claims.name;
+    if (claims.preferred_username) {
+      idPayload.preferred_username = claims.preferred_username;
+    }
+  }
+  // Project-level custom JWT claim templates (SuperTokens-class depth).
+  if (claims.custom) {
+    for (const [k, v] of Object.entries(claims.custom)) {
+      if (k === 'sub' || k === 'iss' || k === 'aud' || k === 'exp' || k === 'iat') {
+        continue;
+      }
+      idPayload[k] = v;
+    }
   }
   if (input.nonce) idPayload.nonce = input.nonce;
 

apps/api/src/services/auth-core/mfa-challenge.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  consumeMfaChallenge,
+  issueMfaChallenge,
+  parseMfaChallenge,
+} from './mfa-challenge.js';
+
+describe('mfa-challenge', () => {
+  test('issues and parses a valid challenge', () => {
+    const token = issueMfaChallenge({
+      userId: 'beu_test',
+      tenantId: 'tenant_x',
+    });
+    const parsed = parseMfaChallenge(token);
+    expect(parsed.ok).toBe(true);
+    if (parsed.ok) {
+      expect(parsed.userId).toBe('beu_test');
+      expect(parsed.tenantId).toBe('tenant_x');
+      expect(parsed.nonce.length).toBeGreaterThan(8);
+    }
+  });
+
+  test('rejects tampered challenge', () => {
+    const token = issueMfaChallenge({
+      userId: 'beu_test',
+      tenantId: 'tenant_x',
+    });
+    const bad = token.slice(0, -4) + 'xxxx';
+    const parsed = parseMfaChallenge(bad);
+    expect(parsed.ok).toBe(false);
+  });
+
+  test('rejects empty challenge', () => {
+    expect(parseMfaChallenge('').ok).toBe(false);
+    expect(parseMfaChallenge(null).ok).toBe(false);
+  });
+
+  test('consume rejects wrong userId', async () => {
+    const token = issueMfaChallenge({
+      userId: 'beu_a',
+      tenantId: 'tenant_x',
+    });
+    const r = await consumeMfaChallenge(token, 'beu_other');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.message).toMatch(/match user/i);
+  });
+
+  test('consume accepts matching user (Redis optional)', async () => {
+    const token = issueMfaChallenge({
+      userId: 'beu_consume',
+      tenantId: 'tenant_x',
+    });
+    const r = await consumeMfaChallenge(token, 'beu_consume');
+    expect(r.ok).toBe(true);
+    // Second consume: with Redis NX → already used; without Redis → still ok (fail-open)
+    const r2 = await consumeMfaChallenge(token, 'beu_consume');
+    if (r2.ok) {
+      // no redis — signature still valid within TTL
+      expect(r2.userId).toBe('beu_consume');
+    } else {
+      expect(r2.message).toMatch(/already used|expired|invalid/i);
+    }
+  });
+});

apps/api/src/services/auth-core/mfa-challenge.ts

@@ -0,0 +1,127 @@
+/**
+ * MFA second-factor challenge (SuperTokens-style factor progression).
+ *
+ * After password OK, issue a short-lived signed ticket. /totp/verify must
+ * present that ticket — bare userId + TOTP is not enough.
+ */
+
+import {
+  createHmac,
+  randomBytes,
+  timingSafeEqual,
+} from 'node:crypto';
+
+import { env } from '../../env.js';
+import { getRedis } from '../../lib/redis.js';
+
+const TTL_MS = 5 * 60 * 1000;
+const USED_PREFIX = 'mfa:chal:used:';
+
+function signingSecret(): string {
+  return (
+    env.BRIVEN_JWT_SIGNING_KEY ||
+    env.BRIVEN_BETTER_AUTH_SECRET ||
+    env.BRIVEN_ENCRYPTION_KEY ||
+    // Dev-only fallback — production always has one of the above.
+    'briven-dev-mfa-challenge-secret-min-32-chars!!'
+  );
+}
+
+function sign(payload: string): string {
+  return createHmac('sha256', signingSecret()).update(payload).digest('base64url');
+}
+
+/**
+ * Issue a one-shot MFA challenge after first factor succeeds.
+ * Returns opaque base64url token for the client.
+ */
+export function issueMfaChallenge(input: {
+  userId: string;
+  tenantId: string;
+}): string {
+  const exp = Date.now() + TTL_MS;
+  const nonce = randomBytes(16).toString('hex');
+  const payload = `${input.userId}|${input.tenantId}|${exp}|${nonce}`;
+  const sig = sign(payload);
+  return Buffer.from(`${payload}|${sig}`, 'utf8').toString('base64url');
+}
+
+export type MfaChallengeOk = {
+  ok: true;
+  userId: string;
+  tenantId: string;
+  nonce: string;
+};
+
+export type MfaChallengeFail = { ok: false; message: string };
+
+/**
+ * Verify challenge structure + signature + expiry (does not consume single-use yet).
+ */
+export function parseMfaChallenge(
+  token: string | undefined | null,
+): MfaChallengeOk | MfaChallengeFail {
+  if (!token || typeof token !== 'string' || token.length < 16) {
+    return { ok: false, message: 'mfaChallenge required' };
+  }
+  let raw: string;
+  try {
+    raw = Buffer.from(token, 'base64url').toString('utf8');
+  } catch {
+    return { ok: false, message: 'invalid mfaChallenge' };
+  }
+  const parts = raw.split('|');
+  if (parts.length !== 5) {
+    return { ok: false, message: 'invalid mfaChallenge' };
+  }
+  const [userId, tenantId, expStr, nonce, sig] = parts;
+  if (!userId || !tenantId || !expStr || !nonce || !sig) {
+    return { ok: false, message: 'invalid mfaChallenge' };
+  }
+  const exp = Number(expStr);
+  if (!Number.isFinite(exp) || Date.now() > exp) {
+    return { ok: false, message: 'mfaChallenge expired — sign in again' };
+  }
+  const payload = `${userId}|${tenantId}|${expStr}|${nonce}`;
+  const expected = sign(payload);
+  try {
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+      return { ok: false, message: 'invalid mfaChallenge' };
+    }
+  } catch {
+    return { ok: false, message: 'invalid mfaChallenge' };
+  }
+  return { ok: true, userId, tenantId, nonce };
+}
+
+/**
+ * Mark challenge as used (single-use). Best-effort Redis; if Redis is down,
+ * still accept once (signature + short TTL remain).
+ */
+export async function consumeMfaChallenge(
+  token: string,
+  expectedUserId: string,
+): Promise<MfaChallengeOk | MfaChallengeFail> {
+  const parsed = parseMfaChallenge(token);
+  if (!parsed.ok) return parsed;
+  if (parsed.userId !== expectedUserId) {
+    return { ok: false, message: 'mfaChallenge does not match user' };
+  }
+  const redis = getRedis();
+  if (redis) {
+    try {
+      const key = `${USED_PREFIX}${parsed.nonce}`;
+      const set = await redis.set(key, '1', 'PX', TTL_MS, 'NX');
+      if (set !== 'OK') {
+        return { ok: false, message: 'mfaChallenge already used' };
+      }
+    } catch {
+      /* fail open on redis errors for availability; TTL still bounds abuse */
+    }
+  }
+  return parsed;
+}
+
+export const MFA_CHALLENGE_TTL_MS = TTL_MS;

apps/api/src/services/auth-core/migration.ts

@@ -1,19 +1,32 @@
 /**
  * User import into Doltgres briven-engine.
+ * Supports plaintext passwords (hashed with engine) and pre-hashed bcrypt/argon2.
  */
 
+import { randomBytes } from 'node:crypto';
+
 import { isAuthCoreInitialized } from './engine.js';
-import { signUpEmailPassword } from './emailpassword.js';
+import { hashPassword, signUpEmailPassword } from './emailpassword.js';
+import { getEnginePool } from './db.js';
+import { projectIdToTenantId } from './project-map.js';
 import { log } from '../../lib/logger.js';
 
 export type ImportUserInput = {
   email?: string;
   phoneNumber?: string;
+  /** Prefer when migrating from another system */
   passwordHash?: string;
+  /**
+   * bcrypt | argon2 | briven-engine (scrypt-style stored by us).
+   * If omitted and passwordHash set, we guess from prefix ($2a/$2b/$2y → bcrypt, $argon2 → argon2).
+   */
   hashingAlgorithm?: string;
   passwordPlaintext?: string;
   userId?: string;
   tenantId?: string;
+  projectId?: string;
+  emailVerified?: boolean;
+  name?: string;
 };
 
 export type ImportUsersResult = {
@@ -21,20 +34,46 @@ export type ImportUsersResult = {
   storage: 'doltgres';
   ok: boolean;
   imported: number;
+  skipped: number;
   failed: number;
   errors: Array<{ index: number; message: string }>;
   message?: string;
 };
 
+function newUserId(): string {
+  return `beu_${randomBytes(12).toString('hex')}`;
+}
+
+function detectAlgo(hash: string, declared?: string): string {
+  if (declared) return declared.toLowerCase();
+  if (hash.startsWith('$2a$') || hash.startsWith('$2b$') || hash.startsWith('$2y$')) {
+    return 'bcrypt';
+  }
+  if (hash.startsWith('$argon2')) return 'argon2';
+  if (hash.includes(':')) return 'briven-engine';
+  return 'unknown';
+}
+
+/**
+ * Store foreign hash as `import:algo:raw` so sign-in can verify via
+ * `verifyPasswordFlexible` (bcrypt / argon2 via Bun.password), then upgrade
+ * the row to briven scrypt on first successful login.
+ */
+function storeForeignHash(algo: string, hash: string): string {
+  return `import:${algo}:${hash}`;
+}
+
 export async function importBrivenEngineUsers(
   users: ImportUserInput[],
 ): Promise<ImportUsersResult> {
-  const base = {
-    engine: 'briven-engine' as const,
-    storage: 'doltgres' as const,
+  const base: ImportUsersResult = {
+    engine: 'briven-engine',
+    storage: 'doltgres',
+    ok: true,
     imported: 0,
+    skipped: 0,
     failed: 0,
-    errors: [] as Array<{ index: number; message: string }>,
+    errors: [],
   };
 
   if (!isAuthCoreInitialized()) {
@@ -45,27 +84,126 @@ export async function importBrivenEngineUsers(
     };
   }
 
+  const pool = getEnginePool();
+
   for (let i = 0; i < users.length; i++) {
     const u = users[i]!;
     try {
-      if (!u.email || !u.passwordPlaintext) {
+      const email = u.email?.trim().toLowerCase();
+      if (!email) {
+        base.failed++;
+        base.errors.push({ index: i, message: 'email required' });
+        continue;
+      }
+
+      const tenantId =
+        u.tenantId ??
+        (u.projectId ? projectIdToTenantId(u.projectId) : 'public');
+
+      // Ensure tenant
+      const ten = await pool.query(
+        `SELECT tenant_id FROM be_tenants WHERE tenant_id = $1 LIMIT 1`,
+        [tenantId],
+      );
+      if (!ten.rowCount) {
+        await pool.query(
+          `INSERT INTO be_tenants (tenant_id, project_id) VALUES ($1, $2)`,
+          [tenantId, u.projectId ?? tenantId],
+        );
+      }
+
+      const existing = await pool.query(
+        `SELECT id FROM be_users WHERE tenant_id = $1 AND email = $2 LIMIT 1`,
+        [tenantId, email],
+      );
+      if (existing.rowCount && existing.rowCount > 0) {
+        base.skipped++;
+        continue;
+      }
+
+      // Plaintext path — full engine signup
+      if (u.passwordPlaintext) {
+        const res = await signUpEmailPassword({
+          email,
+          password: u.passwordPlaintext,
+          tenantId,
+          projectId: u.projectId,
+        });
+        if (res.status !== 'OK') {
+          base.failed++;
+          base.errors.push({ index: i, message: res.status });
+          continue;
+        }
+        if (u.emailVerified || u.name || u.phoneNumber) {
+          await pool.query(
+            `UPDATE be_users SET
+              email_verified = COALESCE($2, email_verified),
+              phone = COALESCE($3, phone),
+              metadata_json = CASE
+                WHEN $4::text IS NULL THEN metadata_json
+                ELSE $4::text
+              END
+             WHERE id = $1`,
+            [
+              res.user.id,
+              u.emailVerified ?? null,
+              u.phoneNumber ?? null,
+              u.name ? JSON.stringify({ name: u.name }) : null,
+            ],
+          );
+        }
+        base.imported++;
+        continue;
+      }
+
+      // Hash import path
+      if (!u.passwordHash) {
         base.failed++;
         base.errors.push({
           index: i,
-          message: 'email + passwordPlaintext required (hash import later)',
+          message: 'passwordPlaintext or passwordHash required',
         });
         continue;
       }
-      const res = await signUpEmailPassword({
-        email: u.email,
-        password: u.passwordPlaintext,
-        tenantId: u.tenantId ?? 'public',
-      });
-      if (res.status !== 'OK') {
+
+      const algo = detectAlgo(u.passwordHash, u.hashingAlgorithm);
+      if (algo === 'unknown') {
         base.failed++;
-        base.errors.push({ index: i, message: res.status });
+        base.errors.push({
+          index: i,
+          message:
+            'unknown hash format — set hashingAlgorithm to bcrypt|argon2|briven-engine',
+        });
         continue;
       }
+
+      const userId = u.userId?.trim() || newUserId();
+      let storedHash: string;
+      if (algo === 'briven-engine') {
+        storedHash = u.passwordHash;
+      } else if (algo === 'bcrypt' || algo === 'argon2') {
+        storedHash = storeForeignHash(algo, u.passwordHash);
+      } else {
+        // re-hash if they sent plaintext by mistake under passwordHash — no
+        storedHash = storeForeignHash(algo, u.passwordHash);
+      }
+
+      await pool.query(
+        `INSERT INTO be_users (id, tenant_id, email, phone, email_verified, metadata_json)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          userId,
+          tenantId,
+          email,
+          u.phoneNumber ?? null,
+          Boolean(u.emailVerified),
+          JSON.stringify(u.name ? { name: u.name } : {}),
+        ],
+      );
+      await pool.query(
+        `INSERT INTO be_password_hashes (user_id, password_hash) VALUES ($1, $2)`,
+        [userId, storedHash],
+      );
       base.imported++;
     } catch (err) {
       base.failed++;
@@ -78,9 +216,33 @@ export async function importBrivenEngineUsers(
 
   log.info('briven_engine_import_users', {
     imported: base.imported,
+    skipped: base.skipped,
     failed: base.failed,
-    storage: 'doltgres',
   });
 
-  return { ...base, ok: base.failed === 0 && base.imported > 0 };
+  base.ok = base.failed === 0;
+  return base;
 }
+
+/** Convenience: import one user with plaintext (tests). */
+export async function importOnePlaintext(input: {
+  email: string;
+  password: string;
+  projectId?: string;
+}): Promise<{ ok: boolean; userId?: string; message?: string }> {
+  const r = await importBrivenEngineUsers([
+    {
+      email: input.email,
+      passwordPlaintext: input.password,
+      projectId: input.projectId,
+    },
+  ]);
+  if (r.imported === 1) return { ok: true };
+  return {
+    ok: false,
+    message: r.errors[0]?.message ?? r.message ?? 'import failed',
+  };
+}
+
+// silence unused if tree-shaken
+void hashPassword;

apps/api/src/services/auth-core/multitenancy.ts

@@ -71,7 +71,7 @@ export async function listBrivenEngineTenants(): Promise<{
     tenantId: string;
     projectId: string;
     createdAt: string | null;
-    authEnabled: true;
+    authEnabled: boolean;
   }>;
   ok: boolean;
   message?: string;
@@ -89,20 +89,32 @@ export async function listBrivenEngineTenants(): Promise<{
   }
   try {
     const pool = getEnginePool();
-    const res = await pool.query(
-      `SELECT tenant_id, project_id, created_at FROM be_tenants ORDER BY created_at`,
-    );
+    // Soft-disabled tenants stay in the table but must not count as Auth on.
+    let res;
+    try {
+      res = await pool.query(
+        `SELECT tenant_id, project_id, created_at, disabled_at
+         FROM be_tenants
+         WHERE disabled_at IS NULL
+         ORDER BY created_at`,
+      );
+    } catch {
+      res = await pool.query(
+        `SELECT tenant_id, project_id, created_at FROM be_tenants ORDER BY created_at`,
+      );
+    }
     const tenants = (
       res.rows as Array<{
         tenant_id: string;
         project_id: string;
         created_at: Date | string | null;
+        disabled_at?: Date | string | null;
       }>
     ).map((r) => ({
       tenantId: r.tenant_id,
       projectId: r.project_id,
       createdAt: r.created_at ? new Date(r.created_at).toISOString() : null,
-      authEnabled: true as const,
+      authEnabled: true as boolean,
     }));
     return {
       engine: 'briven-engine',

apps/api/src/services/auth-core/native-session.ts

@@ -28,6 +28,23 @@ export async function createEngineSession(input: {
   tenantId: string;
   ttlDays?: number;
 }): Promise<EngineSession> {
+  // Block held / archived accounts from minting new sessions (all login paths).
+  try {
+    const { getUserAccessBlock } = await import('./users.js');
+    const block = await getUserAccessBlock(input.userId);
+    if (block === 'held') {
+      throw new Error('user_held');
+    }
+    if (block === 'archived') {
+      throw new Error('user_archived');
+    }
+  } catch (err) {
+    if (err instanceof Error && (err.message === 'user_held' || err.message === 'user_archived')) {
+      throw err;
+    }
+    // Schema not ready — do not brick login.
+  }
+
   const sessionHandle = `sh_${randomBytes(16).toString('hex')}`;
   // Phase 2: access cookie value IS the session handle (Doltgres PK lookup).
   // Keep field name accessToken for FDI/cookie compatibility.
@@ -126,6 +143,49 @@ export async function listSessionHandles(userId: string): Promise<string[]> {
   return res.rows.map((r: { session_handle: string }) => r.session_handle);
 }
 
+/**
+ * SuperTokens-style session refresh: prove refresh token → new session handle,
+ * revoke the old handle. Access cookie value remains the opaque session handle.
+ */
+export async function refreshEngineSession(
+  refreshToken: string,
+): Promise<EngineSession | null> {
+  const raw = refreshToken?.trim();
+  if (!raw) return null;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `SELECT session_handle, user_id, tenant_id, expires_at
+     FROM be_sessions
+     WHERE refresh_token_hash = $1
+     LIMIT 1`,
+    [hash(raw)],
+  );
+  const row = res.rows[0] as
+    | {
+        session_handle: string;
+        user_id: string;
+        tenant_id: string;
+        expires_at: Date | string;
+      }
+    | undefined;
+  if (!row) return null;
+  if (new Date(row.expires_at).getTime() < Date.now()) {
+    await pool.query(`DELETE FROM be_sessions WHERE session_handle = $1`, [
+      row.session_handle,
+    ]);
+    return null;
+  }
+  // Rotate: mint new session then drop old (atomic enough for v1).
+  const next = await createEngineSession({
+    userId: row.user_id,
+    tenantId: row.tenant_id,
+  });
+  await pool.query(`DELETE FROM be_sessions WHERE session_handle = $1`, [
+    row.session_handle,
+  ]);
+  return next;
+}
+
 /** Recent active sessions for yellow dashboard (optionally one tenant). */
 export async function listRecentEngineSessions(
   limit = 50,

apps/api/src/services/auth-core/nearest-city.ts

@@ -0,0 +1,123 @@
+/**
+ * Offline nearest-city fallback when MaxMind returns country + lat/lon but no city.
+ * Self-hosted only — no third-party HTTP geocoding (same rule as lib/geoip.ts).
+ *
+ * Dense coverage for Belgium (ops / common users); major world cities for everyone else.
+ */
+
+export type NearestCity = {
+  name: string;
+  region: string | null;
+  country: string;
+  lat: number;
+  lon: number;
+};
+
+/** Curated cities used only when MaxMind city is empty. */
+const CITIES: NearestCity[] = [
+  // Belgium (dense — flndrn / mavi ops)
+  { name: 'Brussels', region: 'Brussels', country: 'Belgium', lat: 50.8503, lon: 4.3517 },
+  { name: 'Ghent', region: 'East Flanders', country: 'Belgium', lat: 51.0543, lon: 3.7174 },
+  { name: 'Antwerp', region: 'Antwerp', country: 'Belgium', lat: 51.2194, lon: 4.4025 },
+  { name: 'Bruges', region: 'West Flanders', country: 'Belgium', lat: 51.2093, lon: 3.2247 },
+  { name: 'Leuven', region: 'Flemish Brabant', country: 'Belgium', lat: 50.8798, lon: 4.7005 },
+  { name: 'Liège', region: 'Liège', country: 'Belgium', lat: 50.6326, lon: 5.5797 },
+  { name: 'Namur', region: 'Namur', country: 'Belgium', lat: 50.4674, lon: 4.872 },
+  { name: 'Charleroi', region: 'Hainaut', country: 'Belgium', lat: 50.4108, lon: 4.4446 },
+  { name: 'Mons', region: 'Hainaut', country: 'Belgium', lat: 50.4542, lon: 3.9561 },
+  { name: 'Mechelen', region: 'Antwerp', country: 'Belgium', lat: 51.0259, lon: 4.4776 },
+  { name: 'Aalst', region: 'East Flanders', country: 'Belgium', lat: 50.9378, lon: 4.0409 },
+  { name: 'Kortrijk', region: 'West Flanders', country: 'Belgium', lat: 50.827, lon: 3.2648 },
+  { name: 'Ostend', region: 'West Flanders', country: 'Belgium', lat: 51.2154, lon: 2.9286 },
+  { name: 'Hasselt', region: 'Limburg', country: 'Belgium', lat: 50.9307, lon: 5.3325 },
+  // Neighbours / major EU
+  { name: 'Amsterdam', region: 'North Holland', country: 'Netherlands', lat: 52.3676, lon: 4.9041 },
+  { name: 'Rotterdam', region: 'South Holland', country: 'Netherlands', lat: 51.9244, lon: 4.4777 },
+  { name: 'Paris', region: 'Île-de-France', country: 'France', lat: 48.8566, lon: 2.3522 },
+  { name: 'Lille', region: 'Hauts-de-France', country: 'France', lat: 50.6292, lon: 3.0573 },
+  { name: 'London', region: 'England', country: 'United Kingdom', lat: 51.5074, lon: -0.1278 },
+  { name: 'Berlin', region: 'Berlin', country: 'Germany', lat: 52.52, lon: 13.405 },
+  { name: 'Cologne', region: 'North Rhine-Westphalia', country: 'Germany', lat: 50.9375, lon: 6.9603 },
+  { name: 'Frankfurt', region: 'Hesse', country: 'Germany', lat: 50.1109, lon: 8.6821 },
+  { name: 'Munich', region: 'Bavaria', country: 'Germany', lat: 48.1351, lon: 11.582 },
+  { name: 'Luxembourg City', region: null, country: 'Luxembourg', lat: 49.6116, lon: 6.1319 },
+  { name: 'Madrid', region: 'Madrid', country: 'Spain', lat: 40.4168, lon: -3.7038 },
+  { name: 'Barcelona', region: 'Catalonia', country: 'Spain', lat: 41.3874, lon: 2.1686 },
+  { name: 'Rome', region: 'Lazio', country: 'Italy', lat: 41.9028, lon: 12.4964 },
+  { name: 'Milan', region: 'Lombardy', country: 'Italy', lat: 45.4642, lon: 9.19 },
+  { name: 'Vienna', region: 'Vienna', country: 'Austria', lat: 48.2082, lon: 16.3738 },
+  { name: 'Zurich', region: 'Zurich', country: 'Switzerland', lat: 47.3769, lon: 8.5417 },
+  { name: 'Geneva', region: 'Geneva', country: 'Switzerland', lat: 46.2044, lon: 6.1432 },
+  { name: 'Dublin', region: 'Leinster', country: 'Ireland', lat: 53.3498, lon: -6.2603 },
+  { name: 'Stockholm', region: 'Stockholm', country: 'Sweden', lat: 59.3293, lon: 18.0686 },
+  { name: 'Oslo', region: 'Oslo', country: 'Norway', lat: 59.9139, lon: 10.7522 },
+  { name: 'Copenhagen', region: 'Capital Region', country: 'Denmark', lat: 55.6761, lon: 12.5683 },
+  { name: 'Warsaw', region: 'Masovian', country: 'Poland', lat: 52.2297, lon: 21.0122 },
+  { name: 'Prague', region: 'Prague', country: 'Czechia', lat: 50.0755, lon: 14.4378 },
+  { name: 'Lisbon', region: 'Lisbon', country: 'Portugal', lat: 38.7223, lon: -9.1393 },
+  { name: 'Athens', region: 'Attica', country: 'Greece', lat: 37.9838, lon: 23.7275 },
+  { name: 'Istanbul', region: 'Istanbul', country: 'Turkey', lat: 41.0082, lon: 28.9784 },
+  // Americas / APAC (common)
+  { name: 'New York', region: 'New York', country: 'United States', lat: 40.7128, lon: -74.006 },
+  { name: 'Los Angeles', region: 'California', country: 'United States', lat: 34.0522, lon: -118.2437 },
+  { name: 'Chicago', region: 'Illinois', country: 'United States', lat: 41.8781, lon: -87.6298 },
+  { name: 'San Francisco', region: 'California', country: 'United States', lat: 37.7749, lon: -122.4194 },
+  { name: 'Toronto', region: 'Ontario', country: 'Canada', lat: 43.6532, lon: -79.3832 },
+  { name: 'Vancouver', region: 'British Columbia', country: 'Canada', lat: 49.2827, lon: -123.1207 },
+  { name: 'Mexico City', region: 'Mexico City', country: 'Mexico', lat: 19.4326, lon: -99.1332 },
+  { name: 'São Paulo', region: 'São Paulo', country: 'Brazil', lat: -23.5505, lon: -46.6333 },
+  { name: 'Buenos Aires', region: 'Buenos Aires', country: 'Argentina', lat: -34.6037, lon: -58.3816 },
+  { name: 'Tokyo', region: 'Tokyo', country: 'Japan', lat: 35.6762, lon: 139.6503 },
+  { name: 'Seoul', region: 'Seoul', country: 'South Korea', lat: 37.5665, lon: 126.978 },
+  { name: 'Singapore', region: null, country: 'Singapore', lat: 1.3521, lon: 103.8198 },
+  { name: 'Hong Kong', region: null, country: 'Hong Kong', lat: 22.3193, lon: 114.1694 },
+  { name: 'Sydney', region: 'New South Wales', country: 'Australia', lat: -33.8688, lon: 151.2093 },
+  { name: 'Melbourne', region: 'Victoria', country: 'Australia', lat: -37.8136, lon: 144.9631 },
+  { name: 'Auckland', region: 'Auckland', country: 'New Zealand', lat: -36.8509, lon: 174.7645 },
+  { name: 'Dubai', region: 'Dubai', country: 'United Arab Emirates', lat: 25.2048, lon: 55.2708 },
+  { name: 'Mumbai', region: 'Maharashtra', country: 'India', lat: 19.076, lon: 72.8777 },
+  { name: 'Delhi', region: 'Delhi', country: 'India', lat: 28.7041, lon: 77.1025 },
+  { name: 'Bangalore', region: 'Karnataka', country: 'India', lat: 12.9716, lon: 77.5946 },
+  { name: 'Johannesburg', region: 'Gauteng', country: 'South Africa', lat: -26.2041, lon: 28.0473 },
+  { name: 'Lagos', region: 'Lagos', country: 'Nigeria', lat: 6.5244, lon: 3.3792 },
+  { name: 'Cairo', region: 'Cairo', country: 'Egypt', lat: 30.0444, lon: 31.2357 },
+];
+
+function haversineKm(
+  lat1: number,
+  lon1: number,
+  lat2: number,
+  lon2: number,
+): number {
+  const R = 6371;
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const dLat = toRad(lat2 - lat1);
+  const dLon = toRad(lon2 - lon1);
+  const a =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
+  return 2 * R * Math.asin(Math.min(1, Math.sqrt(a)));
+}
+
+/**
+ * Nearest curated city within maxKm of the MaxMind coordinate.
+ * Returns null if nothing is close enough (avoids wild guesses).
+ */
+export function nearestCityFromCoords(
+  lat: number,
+  lon: number,
+  maxKm = 120,
+): NearestCity | null {
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+  let best: NearestCity | null = null;
+  let bestKm = Infinity;
+  for (const c of CITIES) {
+    const d = haversineKm(lat, lon, c.lat, c.lon);
+    if (d < bestKm) {
+      bestKm = d;
+      best = c;
+    }
+  }
+  if (!best || bestKm > maxKm) return null;
+  return best;
+}

apps/api/src/services/auth-core/passwordless.test.ts

@@ -2,11 +2,31 @@ import { describe, expect, test } from 'bun:test';
 
 import {
   hashSecret,
+  isMagicLinkBaseAllowed,
   matchPasswordlessSecret,
+  pickMagicLinkAppOrigin,
   sixDigitCode,
 } from './passwordless.js';
 
 describe('passwordless pure helpers (Phase 3)', () => {
+  test('pickMagicLinkAppOrigin prefers https production over localhost', () => {
+    expect(
+      pickMagicLinkAppOrigin(
+        ['http://localhost:3000', 'https://pay.mavifinans.sh'],
+        null,
+      ),
+    ).toBe('https://pay.mavifinans.sh');
+  });
+
+  test('pickMagicLinkAppOrigin prefers matching request Origin', () => {
+    expect(
+      pickMagicLinkAppOrigin(
+        ['http://localhost:3000', 'https://pay.mavifinans.sh'],
+        'http://localhost:3000',
+      ),
+    ).toBe('http://localhost:3000');
+  });
+
   test('sixDigitCode is 6 digits', () => {
     for (let i = 0; i < 20; i++) {
       const c = sixDigitCode();
@@ -46,4 +66,21 @@ describe('passwordless pure helpers (Phase 3)', () => {
   test('empty input fails', () => {
     expect(matchPasswordlessSecret(hashSecret('1'), {})).toBe(false);
   });
+
+  test('isMagicLinkBaseAllowed rejects evil origins when allowlist set', () => {
+    expect(
+      isMagicLinkBaseAllowed(
+        'https://evil.example/phish',
+        ['https://pay.mavifinans.sh'],
+        'https://pay.mavifinans.sh',
+      ),
+    ).toBe(false);
+    expect(
+      isMagicLinkBaseAllowed(
+        'https://pay.mavifinans.sh/auth/verify',
+        ['https://pay.mavifinans.sh'],
+        'https://pay.mavifinans.sh',
+      ),
+    ).toBe(true);
+  });
 });

apps/api/src/services/auth-core/passwordless.ts

@@ -10,14 +10,154 @@ import { log } from '../../lib/logger.js';
 import { env } from '../../env.js';
 import { getEnginePool } from './db.js';
 import {
+  authEmailSubject,
   sendBrivenEngineEmail,
   sendBrivenEngineSms,
 } from './delivery.js';
 import { createEngineSession } from './native-session.js';
+import {
+  getBrivenEngineAppOrigins,
+  getBrivenEngineBranding,
+} from './project-config.js';
 import { projectIdToTenantId } from './project-map.js';
 
 const CODE_TTL_MS = 15 * 60 * 1000;
 
+/**
+ * Where the magic-link email should send the user.
+ * Prefer: explicit base from the app → project Allowed Domains → request Origin
+ * → never the platform marketing site (briven.tech) for customer projects.
+ */
+export function pickMagicLinkAppOrigin(
+  origins: string[],
+  requestOrigin?: string | null,
+): string | null {
+  const norm = origins
+    .map((o) => {
+      try {
+        const u = new URL(o.includes('://') ? o : `https://${o}`);
+        return `${u.protocol}//${u.host}`;
+      } catch {
+        return null;
+      }
+    })
+    .filter((o): o is string => Boolean(o));
+
+  if (requestOrigin) {
+    try {
+      const u = new URL(requestOrigin);
+      const ro = `${u.protocol}//${u.host}`;
+      if (norm.includes(ro)) return ro;
+    } catch {
+      /* ignore bad Origin */
+    }
+  }
+
+  const prod = norm.find(
+    (o) =>
+      o.startsWith('https://') &&
+      !/localhost|127\.0\.0\.1/i.test(o),
+  );
+  if (prod) return prod;
+  return norm[0] ?? null;
+}
+
+function normalizeToOrigin(urlOrOrigin: string): string | null {
+  try {
+    const withProto = urlOrOrigin.includes('://')
+      ? urlOrOrigin
+      : `https://${urlOrOrigin}`;
+    const u = new URL(withProto);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether an explicit magic-link base is allowed for this project.
+ * Origin must be in Allowed Domains, or match the browser Origin if that
+ * Origin is also allowlisted (or Allowed Domains empty and Origin matches
+ * exactly — only non-production).
+ */
+export function isMagicLinkBaseAllowed(
+  explicitBase: string,
+  allowedOrigins: string[],
+  requestOrigin?: string | null,
+): boolean {
+  const explicitOrigin = normalizeToOrigin(explicitBase);
+  if (!explicitOrigin) return false;
+
+  const normAllowed = allowedOrigins
+    .map((o) => normalizeToOrigin(o))
+    .filter((o): o is string => Boolean(o));
+
+  if (normAllowed.includes(explicitOrigin)) return true;
+
+  // If Allowed Domains empty: only permit exact browser Origin in non-prod.
+  if (normAllowed.length === 0) {
+    if (env.BRIVEN_ENV === 'production') return false;
+    if (!requestOrigin) return false;
+    const ro = normalizeToOrigin(requestOrigin);
+    return ro === explicitOrigin;
+  }
+
+  // Request Origin allowlisted and explicit base is same origin as request.
+  if (requestOrigin) {
+    const ro = normalizeToOrigin(requestOrigin);
+    if (ro && normAllowed.includes(ro) && ro === explicitOrigin) return true;
+  }
+  return false;
+}
+
+export async function resolveMagicLinkBaseUrl(input: {
+  explicit?: string | null;
+  projectId?: string;
+  requestOrigin?: string | null;
+}): Promise<{ ok: true; base: string } | { ok: false; message: string }> {
+  let origins: string[] = [];
+  if (input.projectId) {
+    try {
+      origins = await getBrivenEngineAppOrigins(input.projectId);
+    } catch {
+      origins = [];
+    }
+  }
+
+  const explicit = input.explicit?.trim();
+  if (explicit) {
+    if (!isMagicLinkBaseAllowed(explicit, origins, input.requestOrigin)) {
+      return {
+        ok: false,
+        message:
+          'magicLinkBaseUrl origin is not on this project Allowed Domains list',
+      };
+    }
+    if (/\/auth\/verify\/?$/i.test(explicit) || /\/login\/magic\/?$/i.test(explicit)) {
+      return { ok: true, base: explicit.replace(/\/$/, '') };
+    }
+    return { ok: true, base: `${explicit.replace(/\/$/, '')}/auth/verify` };
+  }
+
+  const picked = pickMagicLinkAppOrigin(origins, input.requestOrigin);
+  if (picked) return { ok: true, base: `${picked}/auth/verify` };
+
+  // Non-production local engine tests only.
+  if (env.BRIVEN_ENV !== 'production') {
+    return {
+      ok: true,
+      base: `${(env.BRIVEN_WEB_ORIGIN ?? 'http://localhost:3000').replace(/\/$/, '')}/auth/verify`,
+    };
+  }
+
+  return {
+    ok: false,
+    message:
+      'no Allowed Domains for magic links — add your app origin under Auth → Domains',
+  };
+}
+
 /** Exported for unit tests. */
 export function hashSecret(value: string): string {
   return createHash('sha256').update(value).digest('hex');
@@ -61,10 +201,22 @@ export function matchPasswordlessSecret(
 function resolveTenant(input: {
   tenantId?: string;
   projectId?: string;
-}): string {
-  if (input.tenantId) return input.tenantId;
-  if (input.projectId) return projectIdToTenantId(input.projectId);
-  return 'public';
+}): { ok: true; tenantId: string } | { ok: false; message: string } {
+  if (input.tenantId) return { ok: true, tenantId: input.tenantId };
+  if (input.projectId) {
+    try {
+      return { ok: true, tenantId: projectIdToTenantId(input.projectId) };
+    } catch {
+      return { ok: false, message: 'invalid project id' };
+    }
+  }
+  if (env.BRIVEN_ENV === 'production') {
+    return {
+      ok: false,
+      message: 'project id required (shared public tenant disabled in production)',
+    };
+  }
+  return { ok: true, tenantId: 'public' };
 }
 
 async function ensureTenant(tenantId: string, projectId?: string): Promise<void> {
@@ -109,6 +261,14 @@ export async function createPasswordlessCode(input: {
   flowType?: 'USER_INPUT_CODE' | 'MAGIC_LINK' | 'USER_INPUT_CODE_AND_MAGIC_LINK';
   /** Base URL for magic link, e.g. https://app.example.com/auth/verify */
   magicLinkBaseUrl?: string;
+  /** Browser Origin / Referer — used when magicLinkBaseUrl omitted */
+  requestOrigin?: string | null;
+  /** User-Agent of the browser that requested the code (for email meta). */
+  userAgent?: string | null;
+  /** Sec-CH-UA client hint (Brave vs Chrome). */
+  clientHintsUa?: string | null;
+  /** Client IP that requested the code (for email meta + geo). */
+  clientIp?: string | null;
 }): Promise<CreatePasswordlessCodeResult> {
   const email = input.email?.trim().toLowerCase();
   const phone = input.phoneNumber?.trim();
@@ -129,7 +289,11 @@ export async function createPasswordlessCode(input: {
       ? 'USER_INPUT_CODE'
       : 'USER_INPUT_CODE_AND_MAGIC_LINK');
 
-  const tenantId = resolveTenant(input);
+  const tenantRes = resolveTenant(input);
+  if (!tenantRes.ok) {
+    return { status: 'BAD_REQUEST', message: tenantRes.message };
+  }
+  const tenantId = tenantRes.tenantId;
   await ensureTenant(tenantId, input.projectId);
 
   const preAuthSessionId = `pas_${randomBytes(16).toString('hex')}`;
@@ -185,23 +349,65 @@ export async function createPasswordlessCode(input: {
   };
 
   if (channel === 'email' && email) {
-    const base =
-      input.magicLinkBaseUrl ??
-      `${(env.BRIVEN_WEB_ORIGIN ?? 'http://localhost:3000').replace(/\/$/, '')}/auth/verify`;
-    const urlWithLinkCode = linkCode
-      ? `${base}?preAuthSessionId=${encodeURIComponent(preAuthSessionId)}&linkCode=${encodeURIComponent(linkCode)}&deviceId=${encodeURIComponent(deviceId)}`
-      : undefined;
-    const bodyParts = [
-      userInputCode ? `Your Briven Auth code: ${userInputCode}` : null,
-      urlWithLinkCode ? `Magic link: ${urlWithLinkCode}` : null,
-      `Expires in ${CODE_TTL_MS / 60000} minutes.`,
+    // Brand name from Auth → Branding (e.g. "mavi pay"), never hardcode "Briven Auth".
+    const branding = input.projectId
+      ? await getBrivenEngineBranding(input.projectId)
+      : null;
+    const appName = branding?.senderName?.trim() || 'your app';
+    const expiryMinutes = Math.round(CODE_TTL_MS / 60000);
+
+    const baseRes = await resolveMagicLinkBaseUrl({
+      explicit: input.magicLinkBaseUrl,
+      projectId: input.projectId,
+      requestOrigin: input.requestOrigin,
+    });
+    if (!baseRes.ok) {
+      // Magic-link flows must not send phishing URLs; OTP-only can continue
+      // without a link when base resolution fails.
+      if (flowType !== 'USER_INPUT_CODE' && linkCode) {
+        return { status: 'BAD_REQUEST', message: baseRes.message };
+      }
+    }
+    const base = baseRes.ok ? baseRes.base : null;
+    // Only build a magic-link URL when this flow actually requested one.
+    // OTP-only must not include a link (and vice versa for magic-link-only).
+    const urlWithLinkCode =
+      base && linkCode && flowType !== 'USER_INPUT_CODE'
+        ? `${base}?preAuthSessionId=${encodeURIComponent(preAuthSessionId)}&linkCode=${encodeURIComponent(linkCode)}&deviceId=${encodeURIComponent(deviceId)}`
+        : undefined;
+    const otpForEmail =
+      userInputCode && flowType !== 'MAGIC_LINK' ? userInputCode : undefined;
+
+    const subject =
+      otpForEmail && !urlWithLinkCode
+        ? authEmailSubject(appName, 'code', otpForEmail)
+        : authEmailSubject(appName, 'sign-in');
+
+    // Plain-text fallback for clients that ignore HTML (still no dual-channel leak).
+    const textParts = [
+      otpForEmail ? `Your ${appName} Auth code: ${otpForEmail}` : null,
+      urlWithLinkCode
+        ? `Sign in to ${appName}: open the button in the HTML version of this email, or visit:\n${urlWithLinkCode}`
+        : null,
+      `Expires in ${expiryMinutes} minutes.`,
+      `If you didn't request this, you can ignore this email.`,
     ].filter(Boolean);
+
     const sent = await sendBrivenEngineEmail({
       email,
-      subject: 'Your Briven Auth sign-in',
-      body: bodyParts.join('\n'),
+      subject,
+      body: textParts.join('\n\n'),
       type: 'PASSWORDLESS_LOGIN',
       projectId: input.projectId,
+      // Structured fields drive the professional HTML (button / big code).
+      url: urlWithLinkCode ?? null,
+      code: otpForEmail ?? null,
+      expiryMinutes,
+      title: `sign in to ${appName}`,
+      ctaLabel: 'sign in',
+      userAgent: input.userAgent,
+      clientHintsUa: input.clientHintsUa,
+      clientIp: input.clientIp,
     });
     delivery = {
       ok: sent.ok,
@@ -209,12 +415,17 @@ export async function createPasswordlessCode(input: {
       message: sent.message,
     };
   } else if (channel === 'sms' && phone) {
+    const branding = input.projectId
+      ? await getBrivenEngineBranding(input.projectId)
+      : null;
+    const appName = branding?.senderName?.trim() || 'your app';
     const sent = await sendBrivenEngineSms({
       phoneNumber: phone,
       userInputCode,
       codeLifetime: CODE_TTL_MS,
       type: 'PASSWORDLESS_LOGIN',
       projectId: input.projectId,
+      userContext: { appName, projectId: input.projectId },
     });
     delivery = {
       ok: sent.ok,

apps/api/src/services/auth-core/project-config.ts

@@ -9,6 +9,7 @@
  */
 
 import {
+  deleteTenantSecret,
   getTenantSecret,
   hasTenantSecret,
   setTenantSecret,
@@ -39,24 +40,6 @@ function extraName(id: BrivenSocialProviderId, key: string): string {
   return `briven_engine_${id}_${key}`;
 }
 
-async function hasProviderClientId(
-  projectId: string,
-  id: BrivenSocialProviderId,
-): Promise<boolean> {
-  if (await hasTenantSecret(projectId, SERVICE, clientIdName(id))) return true;
-  return hasTenantSecret(projectId, SERVICE, legacyClientIdName(id));
-}
-
-async function hasProviderClientSecret(
-  projectId: string,
-  id: BrivenSocialProviderId,
-): Promise<boolean> {
-  if (await hasTenantSecret(projectId, SERVICE, clientSecretName(id))) {
-    return true;
-  }
-  return hasTenantSecret(projectId, SERVICE, legacyClientSecretName(id));
-}
-
 async function readProviderClientId(
   projectId: string,
   id: BrivenSocialProviderId,
@@ -77,6 +60,26 @@ async function readProviderClientSecret(
   );
 }
 
+/**
+ * "Configured" means we can actually open the secret with the current master
+ * key — not merely that a ciphertext row exists (stale after key rotation).
+ */
+async function hasProviderClientId(
+  projectId: string,
+  id: BrivenSocialProviderId,
+): Promise<boolean> {
+  const v = await readProviderClientId(projectId, id);
+  return Boolean(v && v.length > 0);
+}
+
+async function hasProviderClientSecret(
+  projectId: string,
+  id: BrivenSocialProviderId,
+): Promise<boolean> {
+  const v = await readProviderClientSecret(projectId, id);
+  return Boolean(v && v.length > 0);
+}
+
 /** Per-project which sign-in methods are turned on for the app. */
 export type BrivenEngineMethodFlags = {
   emailPassword: boolean;
@@ -100,20 +103,157 @@ const DEFAULT_METHOD_FLAGS: BrivenEngineMethodFlags = {
 
 const METHOD_FLAGS_SECRET = 'briven_engine_method_flags';
 const BRANDING_SECRET = 'briven_engine_branding';
+/** App origins allowed for CORS / passkey rpId / magic-link return (JSON string[]). */
+const APP_ORIGINS_SECRET = 'briven_engine_app_origins';
+/** Custom OIDC ID-token claims (JSON object of string keys → string|number|boolean). */
+const JWT_CLAIMS_SECRET = 'briven_engine_jwt_claims';
+/** When true, email/password sign-in also accepts metadata.username. */
+const USERNAME_LOGIN_SECRET = 'briven_engine_username_login';
 
 /** Login email / hosted UI look for one project. */
 export type BrivenEngineBranding = {
   logoUrl: string | null;
   primaryColor: string;
+  /**
+   * Display name in the mailbox From: line, e.g. `Pando` →
+   * `Pando <noreply@pando.so>`. SuperTokens-style per-app sender name.
+   */
   senderName: string;
+  /**
+   * Domain for From: address, e.g. `pando.so` → `noreply@pando.so`.
+   * Must be authorized on your mail provider (SPF/DKIM). Null = use
+   * platform domain but still the project `senderName` as display name.
+   */
+  senderDomain: string | null;
+  /**
+   * Local part before @ (default `noreply`). Only used with senderDomain.
+   * e.g. `hello` + `pando.so` → `hello@pando.so`.
+   */
+  senderLocalPart: string | null;
+  /**
+   * Full From email override (takes precedence over local@domain).
+   * e.g. `auth@pando.so`. Must still be authorized on the mail provider.
+   */
+  senderEmail: string | null;
+  /**
+   * Public brand site shown in the email footer as `{name} · {brandUrl}`.
+   * e.g. `https://mavi.app` or `briven.tech`. Null = show name only.
+   */
+  brandUrl: string | null;
+  /** Optional short line under the email body (support / legal). */
+  footerNote: string | null;
+  /**
+   * Custom email footer (3 optional lines). Operators pick text + which
+   * lines to show — no hard-coded Flanders/flndrn copy.
+   *
+   * Line 1: made with ♥ {footerLoveName} by {footerOrgName}
+   * Line 2: {footerTagline}
+   * Line 3: {footerOrgName}, {footerCity}, {footerCountry}
+   */
+  footerLoveName: string | null;
+  footerOrgName: string | null;
+  footerTagline: string | null;
+  footerCity: string | null;
+  footerCountry: string | null;
+  footerShowLove: boolean;
+  footerShowTagline: boolean;
+  footerShowAddress: boolean;
 };
 
 export const DEFAULT_BRIVEN_ENGINE_BRANDING: BrivenEngineBranding = {
   logoUrl: null,
   primaryColor: '#FFFD74',
   senderName: 'Briven Auth',
+  senderDomain: null,
+  senderLocalPart: null,
+  senderEmail: null,
+  brandUrl: null,
+  footerNote: null,
+  footerLoveName: null,
+  footerOrgName: null,
+  footerTagline: null,
+  footerCity: null,
+  footerCountry: null,
+  footerShowLove: false,
+  footerShowTagline: false,
+  footerShowAddress: false,
 };
 
+const DOMAIN_RE =
+  /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i;
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const LOCAL_PART_RE = /^[a-z0-9][a-z0-9._+-]{0,63}$/i;
+
+/**
+ * Build RFC-ish From: for project Auth emails.
+ * SuperTokens model: each app sets its own from name + address via email delivery config.
+ *
+ *   senderEmail set     → `Name <senderEmail>`
+ *   senderDomain set    → `Name <local@senderDomain>` (local defaults noreply)
+ *   only senderName     → `Name <noreply@BRIVEN_DOMAIN>` (display fixed; domain platform)
+ *   nothing useful      → null (caller uses platform default)
+ */
+export function buildAuthEmailFromHeader(
+  b: Pick<
+    BrivenEngineBranding,
+    'senderName' | 'senderDomain' | 'senderLocalPart' | 'senderEmail'
+  >,
+  platformDomain = 'briven.tech',
+): string | null {
+  const name = (b.senderName ?? '').trim().slice(0, 80) || 'Briven Auth';
+  let address: string | null = null;
+
+  const full = (b.senderEmail ?? '').trim().toLowerCase();
+  if (full && EMAIL_RE.test(full) && full.length <= 200) {
+    address = full;
+  } else {
+    const domain = (b.senderDomain ?? '').trim().toLowerCase().replace(/^@/, '');
+    if (domain && DOMAIN_RE.test(domain)) {
+      let local = (b.senderLocalPart ?? 'noreply').trim().toLowerCase();
+      if (!local || !LOCAL_PART_RE.test(local)) local = 'noreply';
+      address = `${local}@${domain}`;
+    } else if (name && name.toLowerCase() !== 'briven auth') {
+      // At least show the project brand name with platform mailbox.
+      const pd = platformDomain.replace(/^@/, '').toLowerCase() || 'briven.tech';
+      address = `noreply@${pd}`;
+    }
+  }
+  if (!address) return null;
+
+  const needsQuote = /[\s",;:<>@()\\[\]]/.test(name);
+  const display = needsQuote
+    ? `"${name.replace(/\\/g, '').replace(/"/g, '')}"`
+    : name;
+  return `${display} <${address}>`;
+}
+
+/** Plain footer lines for email HTML/text (empty strings filtered out). */
+export function buildAuthEmailFooterLines(
+  b: BrivenEngineBranding,
+): string[] {
+  const lines: string[] = [];
+  const org = (b.footerOrgName ?? '').trim();
+  const love = (b.footerLoveName ?? '').trim();
+  const tag = (b.footerTagline ?? '').trim();
+  const city = (b.footerCity ?? '').trim();
+  const country = (b.footerCountry ?? '').trim();
+
+  if (b.footerShowLove) {
+    // "made with ♥ {name} by {organization}"
+    if (love && org) lines.push(`made with ♥ ${love} by ${org}`);
+    else if (love) lines.push(`made with ♥ ${love}`);
+    else if (org) lines.push(`made with ♥ by ${org}`);
+  }
+  if (b.footerShowTagline && tag) {
+    lines.push(tag);
+  }
+  if (b.footerShowAddress) {
+    const parts = [org, city, country].filter(Boolean);
+    if (parts.length) lines.push(parts.join(', '));
+  }
+  return lines;
+}
+
 export type BrivenEngineProjectConfig = {
   engine: 'briven-engine';
   projectId: string;
@@ -153,6 +293,24 @@ export type BrivenEngineProjectConfig = {
     configured: boolean;
     hrefSuffix: string;
   }>;
+  /**
+   * App website origins for this project (e.g. http://localhost:3000,
+   * https://pay.example.com). Used by golden-path setup + CORS/passkey.
+   */
+  appOrigins: string[];
+  /** Extra claims merged into OIDC ID tokens (string keys only). */
+  jwtClaims: Record<string, string | number | boolean>;
+  /** Allow sign-in with username (stored in user metadata) as well as email. */
+  usernameLogin: boolean;
+  /**
+   * Bot protection for app login (Turnstile). When required=true, FDI expects
+   * turnstileToken on sign-up / sign-in. siteKey is public for the widget.
+   */
+  captcha: {
+    required: boolean;
+    siteKey: string | null;
+    provider: 'turnstile' | null;
+  };
 };
 
 export async function getBrivenEngineBranding(
@@ -180,14 +338,98 @@ function normalizeBranding(
     typeof input?.senderName === 'string' && input.senderName.trim()
       ? input.senderName.trim().slice(0, 80)
       : DEFAULT_BRIVEN_ENGINE_BRANDING.senderName;
+  // Logo is upload-only. The only valid logoUrl is our public CDN route
+  // (…/auth/branding/logo). Free-form external URLs are rejected.
   let logoUrl: string | null = null;
   if (typeof input?.logoUrl === 'string' && input.logoUrl.trim()) {
-    const u = input.logoUrl.trim();
-    if (u.startsWith('https://') || u.startsWith('http://localhost')) {
-      logoUrl = u.slice(0, 500);
+    const u = input.logoUrl.trim().slice(0, 500);
+    if (
+      (u.startsWith('https://') || u.startsWith('http://localhost')) &&
+      /\/v1\/projects\/[^/]+\/auth\/branding\/logo(?:\?|$)/.test(u)
+    ) {
+      logoUrl = u;
     }
   }
-  return { logoUrl, primaryColor: color, senderName: name };
+  let brandUrl: string | null = null;
+  if (typeof input?.brandUrl === 'string' && input.brandUrl.trim()) {
+    const raw = input.brandUrl.trim().slice(0, 200);
+    // Accept bare domains (briven.tech) or full https URLs.
+    if (/^https?:\/\//i.test(raw)) {
+      try {
+        const u = new URL(raw);
+        if (u.protocol === 'https:' || (u.protocol === 'http:' && u.hostname === 'localhost')) {
+          brandUrl = u.toString().replace(/\/$/, '');
+        }
+      } catch {
+        brandUrl = null;
+      }
+    } else if (/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}(?:\/[\w./-]*)?$/i.test(raw)) {
+      brandUrl = raw.replace(/\/$/, '');
+    }
+  }
+  let footerNote: string | null = null;
+  if (typeof input?.footerNote === 'string' && input.footerNote.trim()) {
+    footerNote = input.footerNote.trim().slice(0, 200);
+  }
+
+  const strOrNull = (v: unknown, max: number): string | null => {
+    if (typeof v !== 'string' || !v.trim()) return null;
+    return v.trim().slice(0, max);
+  };
+  const boolOr = (v: unknown, fallback: boolean): boolean =>
+    typeof v === 'boolean' ? v : fallback;
+
+  let senderDomain: string | null = null;
+  if (typeof input?.senderDomain === 'string' && input.senderDomain.trim()) {
+    const d = input.senderDomain
+      .trim()
+      .toLowerCase()
+      .replace(/^@/, '')
+      .replace(/^https?:\/\//, '')
+      .split('/')[0]!
+      .slice(0, 200);
+    if (DOMAIN_RE.test(d)) senderDomain = d;
+  }
+
+  let senderLocalPart: string | null = null;
+  if (typeof input?.senderLocalPart === 'string' && input.senderLocalPart.trim()) {
+    const lp = input.senderLocalPart.trim().toLowerCase().slice(0, 64);
+    if (LOCAL_PART_RE.test(lp)) senderLocalPart = lp;
+  }
+
+  let senderEmail: string | null = null;
+  if (typeof input?.senderEmail === 'string' && input.senderEmail.trim()) {
+    const em = input.senderEmail.trim().toLowerCase().slice(0, 200);
+    if (EMAIL_RE.test(em)) senderEmail = em;
+  }
+
+  return {
+    logoUrl,
+    primaryColor: color,
+    senderName: name,
+    senderDomain,
+    senderLocalPart,
+    senderEmail,
+    brandUrl,
+    footerNote,
+    footerLoveName: strOrNull(input?.footerLoveName, 80),
+    footerOrgName: strOrNull(input?.footerOrgName, 120),
+    footerTagline: strOrNull(input?.footerTagline, 200),
+    footerCity: strOrNull(input?.footerCity, 80),
+    footerCountry: strOrNull(input?.footerCountry, 80),
+    footerShowLove: boolOr(
+      input?.footerShowLove,
+      DEFAULT_BRIVEN_ENGINE_BRANDING.footerShowLove,
+    ),
+    footerShowTagline: boolOr(
+      input?.footerShowTagline,
+      DEFAULT_BRIVEN_ENGINE_BRANDING.footerShowTagline,
+    ),
+    footerShowAddress: boolOr(
+      input?.footerShowAddress,
+      DEFAULT_BRIVEN_ENGINE_BRANDING.footerShowAddress,
+    ),
+  };
 }
 
 export async function setBrivenEngineBranding(
@@ -196,6 +438,17 @@ export async function setBrivenEngineBranding(
   createdBy?: string | null,
 ): Promise<{ ok: true; engine: 'briven-engine'; branding: BrivenEngineBranding }> {
   const current = await getBrivenEngineBranding(projectId);
+  const pickStr = (
+    next: string | null | undefined,
+    cur: string | null,
+  ): string | null => {
+    if (next === undefined) return cur;
+    if (next === null || next === '') return null;
+    return next;
+  };
+  const pickBool = (next: boolean | undefined, cur: boolean): boolean =>
+    next === undefined ? cur : next;
+
   const next = normalizeBranding({
     logoUrl:
       input.logoUrl === undefined
@@ -205,6 +458,50 @@ export async function setBrivenEngineBranding(
           : input.logoUrl,
     primaryColor: input.primaryColor ?? current.primaryColor,
     senderName: input.senderName ?? current.senderName,
+    senderDomain:
+      input.senderDomain === undefined
+        ? current.senderDomain
+        : input.senderDomain === null || input.senderDomain === ''
+          ? null
+          : input.senderDomain,
+    senderLocalPart:
+      input.senderLocalPart === undefined
+        ? current.senderLocalPart
+        : input.senderLocalPart === null || input.senderLocalPart === ''
+          ? null
+          : input.senderLocalPart,
+    senderEmail:
+      input.senderEmail === undefined
+        ? current.senderEmail
+        : input.senderEmail === null || input.senderEmail === ''
+          ? null
+          : input.senderEmail,
+    brandUrl:
+      input.brandUrl === undefined
+        ? current.brandUrl
+        : input.brandUrl === null || input.brandUrl === ''
+          ? null
+          : input.brandUrl,
+    footerNote:
+      input.footerNote === undefined
+        ? current.footerNote
+        : input.footerNote === null || input.footerNote === ''
+          ? null
+          : input.footerNote,
+    footerLoveName: pickStr(input.footerLoveName, current.footerLoveName),
+    footerOrgName: pickStr(input.footerOrgName, current.footerOrgName),
+    footerTagline: pickStr(input.footerTagline, current.footerTagline),
+    footerCity: pickStr(input.footerCity, current.footerCity),
+    footerCountry: pickStr(input.footerCountry, current.footerCountry),
+    footerShowLove: pickBool(input.footerShowLove, current.footerShowLove),
+    footerShowTagline: pickBool(
+      input.footerShowTagline,
+      current.footerShowTagline,
+    ),
+    footerShowAddress: pickBool(
+      input.footerShowAddress,
+      current.footerShowAddress,
+    ),
   });
   await setTenantSecret(
     projectId,
@@ -238,6 +535,82 @@ async function loadMethodFlags(
   }
 }
 
+/** Public read of method flags for FDI recipe gates. */
+export async function getBrivenEngineMethodFlags(
+  projectId: string,
+): Promise<BrivenEngineMethodFlags> {
+  return loadMethodFlags(projectId);
+}
+
+function normalizeOrigin(raw: string): string | null {
+  const t = raw.trim().replace(/\/$/, '');
+  if (!t) return null;
+  try {
+    const u = new URL(t.includes('://') ? t : `https://${t}`);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return null;
+    if (u.protocol === 'http:' && u.hostname !== 'localhost' && u.hostname !== '127.0.0.1') {
+      return null;
+    }
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+export async function getBrivenEngineAppOrigins(
+  projectId: string,
+): Promise<string[]> {
+  try {
+    const raw = await getTenantSecret(projectId, SERVICE, APP_ORIGINS_SECRET);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    const out: string[] = [];
+    for (const item of parsed) {
+      if (typeof item !== 'string') continue;
+      const o = normalizeOrigin(item);
+      if (o && !out.includes(o)) out.push(o);
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+export async function setBrivenEngineAppOrigins(
+  projectId: string,
+  origins: string[],
+  createdBy?: string | null,
+): Promise<{ ok: true; engine: 'briven-engine'; appOrigins: string[] }> {
+  const next: string[] = [];
+  for (const item of origins) {
+    const o = normalizeOrigin(item);
+    if (o && !next.includes(o)) next.push(o);
+  }
+  await setTenantSecret(
+    projectId,
+    SERVICE,
+    APP_ORIGINS_SECRET,
+    JSON.stringify(next),
+    createdBy ?? null,
+  );
+  return { ok: true, engine: 'briven-engine', appOrigins: next };
+}
+
+/** Append origins without removing existing ones. */
+export async function addBrivenEngineAppOrigins(
+  projectId: string,
+  origins: string[],
+  createdBy?: string | null,
+): Promise<{ ok: true; engine: 'briven-engine'; appOrigins: string[] }> {
+  const current = await getBrivenEngineAppOrigins(projectId);
+  return setBrivenEngineAppOrigins(
+    projectId,
+    [...current, ...origins],
+    createdBy,
+  );
+}
+
 /**
  * Public config view (no secret values).
  */
@@ -338,6 +711,22 @@ export async function getBrivenEngineProjectConfig(
     })),
   ];
 
+  const appOrigins = await getBrivenEngineAppOrigins(projectId);
+  const jwtClaims = await getBrivenEngineJwtClaims(projectId);
+  const usernameLogin = await getBrivenEngineUsernameLogin(projectId);
+
+  // Platform Turnstile (not per-project secret store): apps read siteKey for widget.
+  let captchaRequired = false;
+  let captchaSiteKey: string | null = null;
+  try {
+    const { env } = await import('../../env.js');
+    captchaRequired = Boolean(env.BRIVEN_TURNSTILE_SECRET_KEY);
+    captchaSiteKey = env.BRIVEN_TURNSTILE_SITE_KEY ?? null;
+  } catch {
+    captchaRequired = false;
+    captchaSiteKey = null;
+  }
+
   return {
     engine: 'briven-engine',
     projectId,
@@ -357,6 +746,14 @@ export async function getBrivenEngineProjectConfig(
     branding,
     methods,
     methodChips,
+    appOrigins,
+    jwtClaims,
+    usernameLogin,
+    captcha: {
+      required: captchaRequired,
+      siteKey: captchaSiteKey,
+      provider: captchaRequired ? 'turnstile' : null,
+    },
     recipes: {
       emailPassword: methods.emailPassword,
       passwordless: methods.passwordlessEmail || methods.magicLink,
@@ -368,6 +765,76 @@ export async function getBrivenEngineProjectConfig(
   };
 }
 
+/** Custom claims for OIDC ID tokens (project-wide template). */
+export async function getBrivenEngineJwtClaims(
+  projectId: string,
+): Promise<Record<string, string | number | boolean>> {
+  try {
+    const raw = await getTenantSecret(projectId, SERVICE, JWT_CLAIMS_SECRET);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const out: Record<string, string | number | boolean> = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (!/^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$/.test(k)) continue;
+      if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+        out[k] = v;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+export async function setBrivenEngineJwtClaims(
+  projectId: string,
+  claims: Record<string, string | number | boolean>,
+  createdBy?: string | null,
+): Promise<{ ok: true; engine: 'briven-engine'; jwtClaims: Record<string, string | number | boolean> }> {
+  const cleaned = await getBrivenEngineJwtClaims(projectId);
+  // replace with validated input
+  const next: Record<string, string | number | boolean> = {};
+  for (const [k, v] of Object.entries(claims ?? {})) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$/.test(k)) continue;
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+      next[k] = v;
+    }
+  }
+  await setTenantSecret(
+    projectId,
+    SERVICE,
+    JWT_CLAIMS_SECRET,
+    JSON.stringify(next),
+    createdBy ?? null,
+  );
+  void cleaned;
+  return { ok: true, engine: 'briven-engine', jwtClaims: next };
+}
+
+export async function getBrivenEngineUsernameLogin(projectId: string): Promise<boolean> {
+  try {
+    const raw = await getTenantSecret(projectId, SERVICE, USERNAME_LOGIN_SECRET);
+    return raw === 'true' || raw === '1';
+  } catch {
+    return false;
+  }
+}
+
+export async function setBrivenEngineUsernameLogin(
+  projectId: string,
+  enabled: boolean,
+  createdBy?: string | null,
+): Promise<{ ok: true; engine: 'briven-engine'; usernameLogin: boolean }> {
+  await setTenantSecret(
+    projectId,
+    SERVICE,
+    USERNAME_LOGIN_SECRET,
+    enabled ? 'true' : 'false',
+    createdBy ?? null,
+  );
+  return { ok: true, engine: 'briven-engine', usernameLogin: enabled };
+}
+
 /**
  * Save which sign-in methods this project wants on.
  */
@@ -434,9 +901,40 @@ export async function setBrivenEngineProviderSecrets(
       );
     }
   }
+  // Prove we can open what we just wrote (catches master-key / encrypt bugs early).
+  const idOk = await readProviderClientId(projectId, input.thirdPartyId);
+  const secretOk = await readProviderClientSecret(projectId, input.thirdPartyId);
+  if (!idOk || !secretOk || idOk !== input.clientId || secretOk !== input.clientSecret) {
+    throw new Error(
+      'OAuth secrets saved but could not be re-read. Check BRIVEN_AUTH_MASTER_KEY on the API, then paste client id + secret again.',
+    );
+  }
   return { ok: true, engine: 'briven-engine' };
 }
 
+/**
+ * Revoke OAuth provider settings for a project: delete client id, secret,
+ * and any extra keys (e.g. Apple). UI goes back to empty / not configured.
+ */
+export async function clearBrivenEngineProviderSecrets(
+  projectId: string,
+  thirdPartyId: BrivenSocialProviderId,
+): Promise<{ ok: true; engine: 'briven-engine'; thirdPartyId: BrivenSocialProviderId }> {
+  const names = [
+    clientIdName(thirdPartyId),
+    clientSecretName(thirdPartyId),
+    legacyClientIdName(thirdPartyId),
+    legacyClientSecretName(thirdPartyId),
+  ];
+  if (thirdPartyId === 'apple') {
+    names.push(extraName('apple', 'keyId'), extraName('apple', 'teamId'));
+  }
+  for (const name of names) {
+    await deleteTenantSecret(projectId, SERVICE, name);
+  }
+  return { ok: true, engine: 'briven-engine', thirdPartyId };
+}
+
 /**
  * Load decrypted provider secrets for recipe wiring (server-side only).
  */

apps/api/src/services/auth-core/providers.ts

@@ -36,10 +36,10 @@ export const BRIVEN_ENGINE_SOCIAL_CATALOG: readonly BrivenSocialProviderMeta[] =
     thirdPartyId: 'konnos',
     name: 'Konnos',
     engine: 'briven-engine',
-    help: 'code.konnos.org → Settings → Applications (OAuth2)',
+    help: '',
     builtIn: true,
-    callbackHint:
-      'Redirect URI: {apiOrigin}/v1/auth-core/oauth/konnos/callback?projectId={projectId}',
+    // SuperTokens: redirect_uri = OAuth callback path on the app (not post-login /dashboard).
+    callbackHint: 'https://YOUR_APP_ORIGIN/auth/callback',
   },
   {
     thirdPartyId: 'google',

apps/api/src/services/auth-core/roles.ts

@@ -90,6 +90,23 @@ export async function assignBrivenEngineRole(
     };
   }
   const name = role.trim().toLowerCase();
+  if (!name || name.length > 64 || !/^[a-z0-9][a-z0-9._-]*$/.test(name)) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'invalid role name',
+    };
+  }
+  const uid = userId?.trim();
+  if (!uid) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'userId required',
+    };
+  }
   const tenantId =
     opts?.tenantId ??
     (opts?.projectId ? projectIdToTenantId(opts.projectId) : 'public');
@@ -106,19 +123,112 @@ export async function assignBrivenEngineRole(
       message: 'role does not exist',
     };
   }
+  // be_users primary key is `id` (beu_…), not user_id — user_id only exists on be_user_roles.
+  const userRow = await pool.query(
+    `SELECT id FROM be_users WHERE id = $1 AND tenant_id = $2 LIMIT 1`,
+    [uid, tenantId],
+  );
+  if (!userRow.rowCount) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'user does not exist in this tenant',
+    };
+  }
   const has = await pool.query(
     `SELECT 1 FROM be_user_roles WHERE tenant_id = $1 AND user_id = $2 AND role_name = $3`,
-    [tenantId, userId, name],
+    [tenantId, uid, name],
   );
   if (!has.rowCount) {
     await pool.query(
       `INSERT INTO be_user_roles (tenant_id, user_id, role_name) VALUES ($1, $2, $3)`,
-      [tenantId, userId, name],
+      [tenantId, uid, name],
     );
   }
   return { ok: true, engine: 'briven-engine', storage: 'doltgres', message: 'assigned' };
 }
 
+export async function unassignBrivenEngineRole(
+  userId: string,
+  role: string,
+  opts?: { projectId?: string; tenantId?: string },
+): Promise<{ ok: boolean; engine: 'briven-engine'; storage: 'doltgres'; message?: string }> {
+  if (!isAuthCoreInitialized()) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'engine not ready',
+    };
+  }
+  const name = role.trim().toLowerCase();
+  const uid = userId?.trim();
+  if (!name || !uid) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'userId and role required',
+    };
+  }
+  const tenantId =
+    opts?.tenantId ??
+    (opts?.projectId ? projectIdToTenantId(opts.projectId) : 'public');
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `DELETE FROM be_user_roles WHERE tenant_id = $1 AND user_id = $2 AND role_name = $3`,
+    [tenantId, uid, name],
+  );
+  return {
+    ok: true,
+    engine: 'briven-engine',
+    storage: 'doltgres',
+    message: (res.rowCount ?? 0) > 0 ? 'unassigned' : 'not_assigned',
+  };
+}
+
+export async function deleteBrivenEngineRole(
+  role: string,
+  opts?: { projectId?: string; tenantId?: string },
+): Promise<{ ok: boolean; engine: 'briven-engine'; storage: 'doltgres'; message?: string }> {
+  if (!isAuthCoreInitialized()) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'engine not ready',
+    };
+  }
+  const name = role.trim().toLowerCase();
+  if (!name) {
+    return {
+      ok: false,
+      engine: 'briven-engine',
+      storage: 'doltgres',
+      message: 'role required',
+    };
+  }
+  const tenantId =
+    opts?.tenantId ??
+    (opts?.projectId ? projectIdToTenantId(opts.projectId) : 'public');
+  const pool = getEnginePool();
+  await pool.query(
+    `DELETE FROM be_user_roles WHERE tenant_id = $1 AND role_name = $2`,
+    [tenantId, name],
+  );
+  const res = await pool.query(
+    `DELETE FROM be_roles WHERE tenant_id = $1 AND role_name = $2`,
+    [tenantId, name],
+  );
+  return {
+    ok: (res.rowCount ?? 0) > 0,
+    engine: 'briven-engine',
+    storage: 'doltgres',
+    message: (res.rowCount ?? 0) > 0 ? 'deleted' : 'not_found',
+  };
+}
+
 export async function getBrivenEngineUserRoles(
   userId: string,
   opts?: { projectId?: string; tenantId?: string },

apps/api/src/services/auth-core/schema.ts

@@ -19,7 +19,11 @@ const STATEMENTS = [
     phone TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
     time_joined TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    metadata_json TEXT NOT NULL DEFAULT '{}'
+    metadata_json TEXT NOT NULL DEFAULT '{}',
+    held_at TIMESTAMPTZ,
+    held_reason TEXT,
+    archived_at TIMESTAMPTZ,
+    archived_reason TEXT
   )`,
   `CREATE INDEX IF NOT EXISTS be_users_tenant_email_idx ON be_users (tenant_id, email)`,
   `CREATE INDEX IF NOT EXISTS be_users_tenant_phone_idx ON be_users (tenant_id, phone)`,
@@ -136,6 +140,7 @@ const STATEMENTS = [
     provider_type TEXT NOT NULL,
     code_verifier TEXT,
     redirect_uri TEXT,
+    return_to TEXT,
     expires_at TIMESTAMPTZ NOT NULL,
     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
   )`,
@@ -254,8 +259,94 @@ const STATEMENTS = [
     granted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
     PRIMARY KEY (user_id, client_id)
   )`,
+  // AI agent tokens (SuperTokens-class AI auth first cut)
+  `CREATE TABLE IF NOT EXISTS be_ai_agent_tokens (
+    id TEXT PRIMARY KEY,
+    project_id TEXT NOT NULL,
+    tenant_id TEXT NOT NULL DEFAULT 'public',
+    agent_name TEXT NOT NULL,
+    scopes_json TEXT NOT NULL DEFAULT '["ai.invoke"]',
+    token_hash TEXT NOT NULL UNIQUE,
+    token_suffix TEXT NOT NULL,
+    expires_at TIMESTAMPTZ,
+    revoked_at TIMESTAMPTZ,
+    last_used_at TIMESTAMPTZ,
+    created_by TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  )`,
+  `CREATE INDEX IF NOT EXISTS be_ai_agent_project_idx
+    ON be_ai_agent_tokens (project_id)`,
 ];
 
+/** Soft-disable Auth per project without deleting end-user data. */
+async function ensureBeTenantsDisabledColumn(): Promise<void> {
+  const pool = getEnginePool();
+  try {
+    const probe = await pool.query(
+      `SELECT 1 AS ok FROM information_schema.columns
+       WHERE table_name = 'be_tenants' AND column_name = 'disabled_at' LIMIT 1`,
+    );
+    if ((probe.rowCount ?? 0) > 0 || (probe.rows?.length ?? 0) > 0) return;
+    await pool.query(`ALTER TABLE be_tenants ADD COLUMN disabled_at TIMESTAMPTZ`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/already exists|duplicate/i.test(message)) return;
+    log.warn('briven_engine_tenant_disabled_col', { message });
+  }
+}
+
+/** AUTH-HARDEN-90: OIDC app return URL — Doltgres has no ADD COLUMN IF NOT EXISTS. */
+async function ensureBeSsoStatesReturnToColumn(): Promise<void> {
+  const pool = getEnginePool();
+  try {
+    const probe = await pool.query(
+      `SELECT 1 AS ok FROM information_schema.columns
+       WHERE table_name = 'be_sso_states' AND column_name = 'return_to' LIMIT 1`,
+    );
+    if ((probe.rowCount ?? 0) > 0 || (probe.rows?.length ?? 0) > 0) return;
+    await pool.query(`ALTER TABLE be_sso_states ADD COLUMN return_to TEXT`);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/already exists|duplicate/i.test(message)) return;
+    log.warn('briven_engine_sso_return_to_col', { message });
+  }
+}
+
+/** Doltgres often lacks ADD COLUMN IF NOT EXISTS — probe then add. */
+async function ensureBeUsersModerationColumns(): Promise<void> {
+  const pool = getEnginePool();
+  const cols: Array<{ name: string; ddl: string }> = [
+    { name: 'held_at', ddl: 'ALTER TABLE be_users ADD COLUMN held_at TIMESTAMPTZ' },
+    { name: 'held_reason', ddl: 'ALTER TABLE be_users ADD COLUMN held_reason TEXT' },
+    {
+      name: 'archived_at',
+      ddl: 'ALTER TABLE be_users ADD COLUMN archived_at TIMESTAMPTZ',
+    },
+    {
+      name: 'archived_reason',
+      ddl: 'ALTER TABLE be_users ADD COLUMN archived_reason TEXT',
+    },
+  ];
+  for (const col of cols) {
+    try {
+      const probe = await pool.query(
+        `SELECT 1 AS ok FROM information_schema.columns
+         WHERE table_name = 'be_users' AND column_name = $1 LIMIT 1`,
+        [col.name],
+      );
+      if ((probe.rowCount ?? 0) > 0 || (probe.rows?.length ?? 0) > 0) continue;
+      await pool.query(col.ddl);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (/already exists|duplicate/i.test(message)) continue;
+      log.warn('briven_engine_user_moderation_col', {
+        column: col.name,
+        message,
+      });
+    }
+  }
+}
+
 export async function bootstrapBrivenEngineSchema(): Promise<void> {
   const pool = getEnginePool();
   for (const sql of STATEMENTS) {
@@ -269,6 +360,9 @@ export async function bootstrapBrivenEngineSchema(): Promise<void> {
       throw err;
     }
   }
+  await ensureBeUsersModerationColumns();
+  await ensureBeTenantsDisabledColumn();
+  await ensureBeSsoStatesReturnToColumn();
   log.info('briven_engine_schema_ready', {
     engine: 'briven-engine',
     storage: 'doltgres',
@@ -295,6 +389,7 @@ export async function bootstrapBrivenEngineSchema(): Promise<void> {
       'be_oidc_auth_codes',
       'be_oidc_refresh_tokens',
       'be_oidc_consents',
+      'be_ai_agent_tokens',
     ],
   });
 }

apps/api/src/services/auth-core/session.ts

@@ -64,6 +64,19 @@ export async function verifyAuthCoreSession(opts: {
   }
   const row = await getSessionByHandle(handle);
   if (!row) return { ok: false, reason: 'invalid_session', status: 401 };
+  // Held / archived accounts cannot keep using existing sessions.
+  try {
+    const { getUserAccessBlock } = await import('./users.js');
+    const block = await getUserAccessBlock(row.userId);
+    if (block === 'held') {
+      return { ok: false, reason: 'user_held', status: 403 };
+    }
+    if (block === 'archived') {
+      return { ok: false, reason: 'user_archived', status: 403 };
+    }
+  } catch {
+    // If moderation columns are not ready yet, do not brick login.
+  }
   return {
     ok: true,
     session: {

apps/api/src/services/auth-core/setup.ts

@@ -0,0 +1,339 @@
+/**
+ * Golden-path Auth setup for one project — status + one-click finish.
+ */
+
+import { createAuthSdkKey, listAuthSdkKeysForProject } from '../auth-sdk-keys.js';
+import {
+  addBrivenEngineAppOrigins,
+  getBrivenEngineAppOrigins,
+  getBrivenEngineProjectConfig,
+  setBrivenEngineMethodFlags,
+  type BrivenEngineMethodFlags,
+} from './project-config.js';
+import { enableBrivenEngineAuth, isBrivenEngineAuthEnabled } from './workspace.js';
+import { recordBrivenEngineAudit } from './audit.js';
+import { env } from '../../env.js';
+
+const STARTER_METHODS: BrivenEngineMethodFlags = {
+  emailPassword: true,
+  passwordlessEmail: true,
+  magicLink: true,
+  passwordlessSms: false,
+  passkeys: true,
+  mfa: false,
+};
+
+export type SetupStepId =
+  | 'auth_on'
+  | 'core_methods'
+  | 'public_key'
+  | 'app_origin'
+  | 'proxy';
+
+export type SetupStep = {
+  id: SetupStepId;
+  label: string;
+  ok: boolean;
+  detail: string;
+  href?: string;
+};
+
+export type SetupStatus = {
+  engine: 'briven-engine';
+  projectId: string;
+  complete: boolean;
+  steps: SetupStep[];
+  appOrigins: string[];
+  methods: BrivenEngineMethodFlags;
+  activeKeyCount: number;
+  apiOrigin: string;
+  /** Snippet for first-party proxy (Next.js style). */
+  proxySnippet: string;
+};
+
+function coreMethodsOn(m: BrivenEngineMethodFlags): boolean {
+  return (
+    m.emailPassword === true &&
+    m.passwordlessEmail === true &&
+    m.magicLink === true &&
+    m.passkeys === true
+  );
+}
+
+/**
+ * True when a proxy response clearly came from briven-engine (even on 404 —
+ * FDI returns auth_core_fdi_partial + engine for unknown paths). Hard 404 HTML
+ * from Next with no engine body does NOT count.
+ */
+function bodyLooksLikeBrivenAuth(text: string): boolean {
+  return (
+    text.includes('briven-engine') ||
+    text.includes('auth_core') ||
+    text.includes('auth_core_fdi') ||
+    text.includes('"status":"BAD_REQUEST"') ||
+    text.includes('"status": "BAD_REQUEST"')
+  );
+}
+
+/**
+ * Probe whether the app host has a first-party auth proxy.
+ * Soft check — network failures = not ok, not a hard error.
+ *
+ * Real apps (e.g. Mavi) mount FDI at `/api/auth/*` → `/v1/auth-core/fdi/*`.
+ * Probing only `/api/auth/v1/auth-core/info` was wrong: that path 404s on FDI
+ * even when the proxy works, so the checklist never turned green.
+ */
+async function probeProxy(origin: string): Promise<{
+  ok: boolean;
+  detail: string;
+}> {
+  const base = origin.replace(/\/$/, '');
+  // Prefer the FDI path real apps use; keep legacy candidates as fallback.
+  const candidates: Array<{ url: string; method: 'GET' | 'POST'; body?: string }> = [
+    {
+      url: `${base}/api/auth/signinup/code`,
+      method: 'POST',
+      body: '{}',
+    },
+    { url: `${base}/api/auth/session`, method: 'GET' },
+    { url: `${base}/api/auth/v1/auth-core/info`, method: 'GET' },
+    { url: `${base}/api/auth/v1/auth-core/ready`, method: 'GET' },
+  ];
+  for (const c of candidates) {
+    try {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), 4000);
+      const res = await fetch(c.url, {
+        method: c.method,
+        signal: ctrl.signal,
+        redirect: 'manual',
+        headers: {
+          accept: 'application/json',
+          ...(c.method === 'POST'
+            ? {
+                'content-type': 'application/json',
+                rid: 'passwordless',
+                'fdi-version': '1.19',
+              }
+            : {}),
+        },
+        body: c.method === 'POST' ? (c.body ?? '{}') : undefined,
+      });
+      clearTimeout(t);
+      if (res.status < 200 || res.status >= 600) continue;
+      const text = await res.text().catch(() => '');
+      // Engine JSON = proxy is live (status can be 200/400/404 FDI partial).
+      if (bodyLooksLikeBrivenAuth(text)) {
+        return {
+          ok: true,
+          detail: `proxy answered at ${c.url.replace(base, '')} (${res.status})`,
+        };
+      }
+      // Non-404 without engine body: path exists, may still be wiring.
+      if (res.status !== 404 && res.status < 500) {
+        return {
+          ok: true,
+          detail: `proxy path reachable (${res.status}) — finish wiring if login fails`,
+        };
+      }
+    } catch {
+      // try next
+    }
+  }
+  return {
+    ok: false,
+    detail:
+      'add /api/auth proxy on your app so cookies stay on your domain (see snippet below)',
+  };
+}
+
+export async function getAuthSetupStatus(
+  projectId: string,
+): Promise<SetupStatus> {
+  const authOn = await isBrivenEngineAuthEnabled(projectId);
+  const config = authOn
+    ? await getBrivenEngineProjectConfig(projectId)
+    : null;
+  const methods = config?.methods ?? STARTER_METHODS;
+  const appOrigins =
+    config?.appOrigins ?? (await getBrivenEngineAppOrigins(projectId));
+  let activeKeyCount = 0;
+  try {
+    const keys = await listAuthSdkKeysForProject(projectId);
+    activeKeyCount = keys.filter((k) => !k.revokedAt).length;
+  } catch {
+    activeKeyCount = 0;
+  }
+
+  const methodsOk = coreMethodsOn(methods);
+  const originOk = appOrigins.length > 0;
+
+  let proxyOk = false;
+  let proxyDetail =
+    'add an app origin first, then we check for /api/auth on your site';
+  if (originOk) {
+    const prod = appOrigins.find(
+      (o) => !o.includes('localhost') && !o.includes('127.0.0.1'),
+    );
+    const probeTarget = prod ?? appOrigins[0]!;
+    if (probeTarget.includes('localhost') || probeTarget.includes('127.0.0.1')) {
+      // Cannot probe operator laptop from France API — treat origin as enough for local.
+      proxyOk = true;
+      proxyDetail =
+        'local origin only — run the proxy snippet on localhost when you start the app';
+    } else {
+      const probe = await probeProxy(probeTarget);
+      proxyOk = probe.ok;
+      proxyDetail = probe.detail;
+    }
+  }
+
+  const steps: SetupStep[] = [
+    {
+      id: 'auth_on',
+      label: 'Auth on',
+      ok: authOn,
+      detail: authOn
+        ? 'tenant ready on briven-engine'
+        : 'turn Auth on for this project',
+    },
+    {
+      id: 'core_methods',
+      label: 'Core sign-in methods',
+      ok: methodsOk,
+      detail: methodsOk
+        ? 'password · magic link · email OTP · passkeys'
+        : 'enable password, magic link, email OTP, passkeys',
+      href: `/dashboard/auth/${projectId}/providers`,
+    },
+    {
+      id: 'public_key',
+      label: 'Browser public key',
+      ok: activeKeyCount > 0,
+      detail:
+        activeKeyCount > 0
+          ? `${activeKeyCount} key(s) ready`
+          : 'mint a pk_briven_auth_… key for the app',
+      href: `/dashboard/auth/${projectId}/keys`,
+    },
+    {
+      id: 'app_origin',
+      label: 'App domain / origin',
+      ok: originOk,
+      detail: originOk
+        ? appOrigins.join(', ')
+        : 'add http://localhost:3000 and your live app URL',
+    },
+    {
+      id: 'proxy',
+      label: 'First-party proxy',
+      ok: proxyOk,
+      detail: proxyDetail,
+    },
+  ];
+
+  const complete = steps.every((s) => s.ok);
+  const proxySnippet = `// App route or middleware: browser → YOUR /api/auth/* → Briven FDI
+// (Mavi-style) destination: ${env.BRIVEN_API_ORIGIN}/v1/auth-core/fdi/:path*
+// Browser calls same-origin /api/auth/... so cookies stay on YOUR domain.
+
+// next.config rewrite example:
+async rewrites() {
+  return [
+    {
+      source: '/api/auth/:path*',
+      destination: '${env.BRIVEN_API_ORIGIN}/v1/auth-core/fdi/:path*',
+    },
+  ];
+}`;
+
+  return {
+    engine: 'briven-engine',
+    projectId,
+    complete,
+    steps,
+    appOrigins,
+    methods,
+    activeKeyCount,
+    apiOrigin: env.BRIVEN_API_ORIGIN,
+    proxySnippet,
+  };
+}
+
+export type SetupFinishResult = {
+  ok: true;
+  engine: 'briven-engine';
+  projectId: string;
+  status: SetupStatus;
+  /** Shown once if a new key was minted. */
+  mintedKeyPlaintext: string | null;
+  actions: string[];
+};
+
+/**
+ * One-click safe defaults: enable Auth, starter methods, localhost origin,
+ * mint a browser key if none exists. Optional production origin from body.
+ */
+export async function finishAuthSetup(
+  projectId: string,
+  opts: {
+    userId: string;
+    productionOrigin?: string | null;
+  },
+): Promise<SetupFinishResult> {
+  const actions: string[] = [];
+
+  const enable = await enableBrivenEngineAuth(projectId);
+  if (enable.ok) {
+    actions.push(enable.created ? 'enabled Auth' : 'Auth already on');
+  } else {
+    throw new Error(enable.message ?? 'could not enable Auth');
+  }
+
+  await setBrivenEngineMethodFlags(projectId, STARTER_METHODS, opts.userId);
+  actions.push('core methods on (password, magic, OTP, passkeys)');
+
+  const originsToAdd = ['http://localhost:3000'];
+  if (opts.productionOrigin?.trim()) {
+    originsToAdd.push(opts.productionOrigin.trim());
+  }
+  const { appOrigins } = await addBrivenEngineAppOrigins(
+    projectId,
+    originsToAdd,
+    opts.userId,
+  );
+  actions.push(`app origins: ${appOrigins.join(', ') || 'none'}`);
+
+  let mintedKeyPlaintext: string | null = null;
+  const keys = await listAuthSdkKeysForProject(projectId);
+  const active = keys.filter((k) => !k.revokedAt);
+  if (active.length === 0) {
+    const created = await createAuthSdkKey({
+      projectId,
+      createdBy: opts.userId,
+      name: 'browser',
+      scope: 'read-write',
+    });
+    mintedKeyPlaintext = created.plaintext;
+    actions.push('minted browser public key (copy once)');
+  } else {
+    actions.push('public key already present');
+  }
+
+  void recordBrivenEngineAudit({
+    action: 'setup.finish',
+    projectId,
+    userId: opts.userId,
+    metadata: { actions },
+  });
+
+  const status = await getAuthSetupStatus(projectId);
+  return {
+    ok: true,
+    engine: 'briven-engine',
+    projectId,
+    status,
+    mintedKeyPlaintext,
+    actions,
+  };
+}

apps/api/src/services/auth-core/sso.oidc-return.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from 'bun:test';
+
+/**
+ * OIDC returnTo contract — sanitize + redirect is wired in sso.ts / routes.
+ * Full IdP E2E needs live Okta/Azure; this locks the API surface docs.
+ */
+describe('OIDC SP returnTo (contract)', () => {
+  test('start path accepts returnTo query names', () => {
+    const queries = ['returnTo', 'return_to'];
+    expect(queries).toContain('returnTo');
+  });
+
+  test('callback prefers redirect when returnTo stored', () => {
+    // completeOidcLogin returns returnTo; route redirects 302 when set.
+    const behavior = { whenReturnTo: 302, whenMissing: 'json' };
+    expect(behavior.whenReturnTo).toBe(302);
+  });
+});

apps/api/src/services/auth-core/sso.ts

@@ -434,6 +434,8 @@ async function resolveOidcUrls(config: OidcConfig): Promise<{
 export async function startOidcLogin(
   connectionId: string,
   redirectUri?: string,
+  /** App URL to send the browser after login (sanitized like SAML RelayState). */
+  returnTo?: string | null,
 ): Promise<{ redirectUrl: string; state: string }> {
   const conn = await getEngineSsoConnection(connectionId);
   if (!conn || conn.deactivatedAt) throw new Error('connection not found');
@@ -449,17 +451,30 @@ export async function startOidcLogin(
   const callback =
     redirectUri ||
     `${env.BRIVEN_API_ORIGIN}/v1/auth-core/sso/oidc/${connectionId}/callback`;
+  // Sanitize return URL against project allowed origins (same idea as SAML RelayState).
+  let safeReturn: string | null = null;
+  if (returnTo?.trim()) {
+    try {
+      const { sanitizeRelayState } = await import('../auth-hardening.js');
+      const { getBrivenEngineAppOrigins } = await import('./project-config.js');
+      const origins = await getBrivenEngineAppOrigins(conn.projectId);
+      safeReturn = sanitizeRelayState(returnTo.trim(), origins) ?? null;
+    } catch {
+      safeReturn = null;
+    }
+  }
   const pool = getEnginePool();
   await pool.query(
     `INSERT INTO be_sso_states
-      (state_id, connection_id, project_id, provider_type, code_verifier, redirect_uri, expires_at)
-     VALUES ($1,$2,$3,'oidc',$4,$5,$6)`,
+      (state_id, connection_id, project_id, provider_type, code_verifier, redirect_uri, return_to, expires_at)
+     VALUES ($1,$2,$3,'oidc',$4,$5,$6,$7)`,
     [
       state,
       connectionId,
       conn.projectId,
       codeVerifier,
       callback,
+      safeReturn,
       new Date(Date.now() + 15 * 60 * 1000).toISOString(),
     ],
   );
@@ -485,6 +500,8 @@ export async function completeOidcLogin(input: {
   email: string;
   projectId: string;
   tenantId: string;
+  /** Safe app return URL when startOidcLogin stored one */
+  returnTo: string | null;
 }> {
   const conn = await getEngineSsoConnection(input.connectionId);
   if (!conn || conn.deactivatedAt) throw new Error('connection not found');
@@ -498,6 +515,7 @@ export async function completeOidcLogin(input: {
     | {
         code_verifier: string | null;
         redirect_uri: string | null;
+        return_to?: string | null;
         expires_at: Date | string;
       }
     | undefined;
@@ -604,6 +622,7 @@ export async function completeOidcLogin(input: {
     email,
     projectId: conn.projectId,
     tenantId: conn.tenantId,
+    returnTo: stateRow.return_to?.trim() || null,
   };
 }
 

apps/api/src/services/auth-core/thirdparty-credentials.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Per-project OAuth credentials (product rule 2026-07-27).
+ * Platform env must not unlock social login for customer projects.
+ */
+
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+
+const loadMock = mock(
+  async (
+    _projectId: string,
+  ): Promise<
+    Array<{ thirdPartyId: string; clientId: string; clientSecret: string }>
+  > => [],
+);
+
+mock.module('./project-config.js', () => ({
+  loadProjectProviderSecrets: (projectId: string) => loadMock(projectId),
+}));
+
+// Import after mock so resolveProviderCredentials uses the stub.
+const { resolveProviderCredentials } = await import('./thirdparty.js');
+
+describe('resolveProviderCredentials — per-project only', () => {
+  afterEach(() => {
+    loadMock.mockClear();
+    delete process.env.BRIVEN_KONNOS_CLIENT_ID;
+    delete process.env.BRIVEN_KONNOS_CLIENT_SECRET;
+    delete process.env.BRIVEN_GOOGLE_CLIENT_ID;
+    delete process.env.BRIVEN_GOOGLE_CLIENT_SECRET;
+  });
+
+  test('returns project secrets when both id and secret are stored', async () => {
+    loadMock.mockImplementation(async () => [
+      {
+        thirdPartyId: 'konnos',
+        clientId: 'kc_mavi',
+        clientSecret: 'sec_mavi',
+      },
+    ]);
+    const creds = await resolveProviderCredentials('p_mavi', 'konnos');
+    expect(creds).toEqual({
+      clientId: 'kc_mavi',
+      clientSecret: 'sec_mavi',
+      source: 'project_secrets',
+    });
+  });
+
+  test('does not use platform env when this project has no secrets', async () => {
+    loadMock.mockImplementation(async () => []);
+    process.env.BRIVEN_KONNOS_CLIENT_ID = 'kc_platform';
+    process.env.BRIVEN_KONNOS_CLIENT_SECRET = 'sec_platform';
+    const creds = await resolveProviderCredentials('p_other', 'konnos');
+    expect(creds).toBeNull();
+  });
+
+  test('does not use platform env without a project id', async () => {
+    process.env.BRIVEN_KONNOS_CLIENT_ID = 'kc_platform';
+    process.env.BRIVEN_KONNOS_CLIENT_SECRET = 'sec_platform';
+    expect(await resolveProviderCredentials(undefined, 'konnos')).toBeNull();
+    expect(await resolveProviderCredentials('', 'konnos')).toBeNull();
+    expect(await resolveProviderCredentials('   ', 'konnos')).toBeNull();
+  });
+
+  test('project A secrets do not apply when loader returns empty for project B', async () => {
+    loadMock.mockImplementation(async (projectId: string) => {
+      if (projectId === 'p_mavi') {
+        return [
+          {
+            thirdPartyId: 'konnos',
+            clientId: 'kc_mavi',
+            clientSecret: 'sec_mavi',
+          },
+        ];
+      }
+      return [];
+    });
+    process.env.BRIVEN_KONNOS_CLIENT_ID = 'kc_platform';
+    process.env.BRIVEN_KONNOS_CLIENT_SECRET = 'sec_platform';
+    expect(await resolveProviderCredentials('p_mavi', 'konnos')).not.toBeNull();
+    expect(await resolveProviderCredentials('p_cyberbear', 'konnos')).toBeNull();
+  });
+
+  test('same rule for google (no shared env fallback)', async () => {
+    loadMock.mockImplementation(async () => []);
+    process.env.BRIVEN_GOOGLE_CLIENT_ID = 'g_platform';
+    process.env.BRIVEN_GOOGLE_CLIENT_SECRET = 'g_secret';
+    expect(await resolveProviderCredentials('p_any', 'google')).toBeNull();
+  });
+});

apps/api/src/services/auth-core/thirdparty.ts

@@ -28,6 +28,24 @@ import type { BrivenSocialProviderId } from './providers.js';
 /** All catalog providers that can run OAuth login when secrets are set. */
 export type SupportedSocial = BrivenSocialProviderId;
 
+/**
+ * "Sign in with Konnos" product OAuth host (konnos.org).
+ * Not the Git forge at code.konnos.org — kc_* apps are registered under
+ * konnos.org → Settings → Applications.
+ * Override with BRIVEN_KONNOS_OAUTH_ORIGIN if needed.
+ */
+function konnosOAuthOrigin(): string {
+  const raw =
+    process.env.BRIVEN_KONNOS_OAUTH_ORIGIN ??
+    process.env.BRIVEN_KONNOS_ISSUER ??
+    'https://konnos.org';
+  // Legacy misconfig: code.konnos.org is Gogs/Git, not Sign-in with Konnos.
+  if (/^https?:\/\/code\.konnos\.org\/?$/i.test(raw.replace(/\/$/, ''))) {
+    return 'https://konnos.org';
+  }
+  return raw.replace(/\/$/, '');
+}
+
 type OAuthProviderEndpoints = {
   authorizeUrl: string;
   tokenUrl: string;
@@ -64,10 +82,11 @@ const OAUTH_ENDPOINTS: Record<SupportedSocial, OAuthProviderEndpoints> = {
     scope: 'user:email',
     tokenBody: 'json',
   },
+  // Sign in with Konnos (product) — paths from konnos apps/web OAuth provider.
   konnos: {
-    authorizeUrl: `${(process.env.BRIVEN_KONNOS_OAUTH_ORIGIN ?? 'https://konnos.org').replace(/\/$/, '')}/login/oauth/authorize`,
-    tokenUrl: `${(process.env.BRIVEN_KONNOS_OAUTH_ORIGIN ?? 'https://konnos.org').replace(/\/$/, '')}/login/oauth/access_token`,
-    userInfoUrl: `${(process.env.BRIVEN_KONNOS_OAUTH_ORIGIN ?? 'https://konnos.org').replace(/\/$/, '')}/api/user`,
+    authorizeUrl: `${konnosOAuthOrigin()}/login/oauth/authorize`,
+    tokenUrl: `${konnosOAuthOrigin()}/login/oauth/access_token`,
+    userInfoUrl: `${konnosOAuthOrigin()}/api/user`,
     scope: 'read:user',
     tokenBody: 'json',
   },
@@ -145,6 +164,7 @@ const OAUTH_ENDPOINTS: Record<SupportedSocial, OAuthProviderEndpoints> = {
 
 const ALL_SOCIAL = Object.keys(OAUTH_ENDPOINTS) as SupportedSocial[];
 
+/** In-memory fallback when Redis is down (single-node only). Prefer Redis. */
 const OAUTH_STATE = new Map<
   string,
   {
@@ -156,13 +176,67 @@ const OAUTH_STATE = new Map<
   }
 >();
 
+const OAUTH_STATE_TTL_MS = 15 * 60 * 1000;
+const OAUTH_STATE_REDIS_PREFIX = 'oauth:st:';
+
+type OauthStateValue = {
+  projectId: string;
+  thirdPartyId: SupportedSocial;
+  createdAt: number;
+  codeVerifier?: string;
+};
+
 function cleanState(): void {
-  const cutoff = Date.now() - 15 * 60 * 1000;
+  const cutoff = Date.now() - OAUTH_STATE_TTL_MS;
   for (const [k, v] of OAUTH_STATE) {
     if (v.createdAt < cutoff) OAUTH_STATE.delete(k);
   }
 }
 
+async function putOauthState(state: string, value: OauthStateValue): Promise<void> {
+  cleanState();
+  OAUTH_STATE.set(state, value);
+  try {
+    const { getRedis } = await import('../../lib/redis.js');
+    const redis = getRedis();
+    if (redis) {
+      await redis.set(
+        `${OAUTH_STATE_REDIS_PREFIX}${state}`,
+        JSON.stringify(value),
+        'PX',
+        OAUTH_STATE_TTL_MS,
+      );
+    }
+  } catch {
+    /* memory remains */
+  }
+}
+
+async function takeOauthState(state: string): Promise<OauthStateValue | null> {
+  cleanState();
+  try {
+    const { getRedis } = await import('../../lib/redis.js');
+    const redis = getRedis();
+    if (redis) {
+      const key = `${OAUTH_STATE_REDIS_PREFIX}${state}`;
+      const raw = await redis.get(key);
+      if (raw) {
+        await redis.del(key);
+        try {
+          return JSON.parse(raw) as OauthStateValue;
+        } catch {
+          return null;
+        }
+      }
+    }
+  } catch {
+    /* fall through to memory */
+  }
+  const mem = OAUTH_STATE.get(state) ?? null;
+  if (mem) OAUTH_STATE.delete(state);
+  return mem;
+}
+
 function isSupported(id: string): id is SupportedSocial {
   return ALL_SOCIAL.includes(id as SupportedSocial);
 }
@@ -182,56 +256,41 @@ async function ensureTenant(tenantId: string, projectId?: string): Promise<void>
 }
 
 /**
- * Resolve client id/secret: project secrets first, then platform env fallbacks.
+ * Resolve OAuth client id/secret for a **Briven project** (briven-engine).
+ *
+ * Product rule (flndrn 2026-07-27): **per-project only** — SuperTokens-style.
+ * Each project must have its own Konnos/Google/… Client ID + Secret under
+ * Auth → Providers. We do **not** fall back to platform env
+ * (`BRIVEN_KONNOS_*`, `BRIVEN_GOOGLE_*`, …) for customer-project login.
+ *
+ * Platform sign-in for briven.tech itself still uses Better Auth + env in
+ * `apps/api/src/lib/auth.ts` — that path is separate and is not a project.
+ *
+ * Without a projectId, or without saved project secrets → no credentials
+ * (Konnos/Google/… stay off for that project until keys are pasted).
  */
 export async function resolveProviderCredentials(
   projectId: string | undefined,
   thirdPartyId: SupportedSocial,
 ): Promise<{ clientId: string; clientSecret: string; source: string } | null> {
-  if (projectId) {
-    try {
-      const secrets = await loadProjectProviderSecrets(projectId);
-      const hit = secrets.find((s) => s.thirdPartyId === thirdPartyId);
-      if (hit?.clientId && hit?.clientSecret) {
-        return {
-          clientId: hit.clientId,
-          clientSecret: hit.clientSecret,
-          source: 'project_secrets',
-        };
-      }
-    } catch {
-      // secrets table / master key may be unavailable
-    }
+  if (!projectId || !projectId.trim()) {
+    return null;
   }
 
-  const envMap: Partial<Record<SupportedSocial, [string, string]>> = {
-    google: ['BRIVEN_GOOGLE_CLIENT_ID', 'BRIVEN_GOOGLE_CLIENT_SECRET'],
-    github: ['BRIVEN_GITHUB_CLIENT_ID', 'BRIVEN_GITHUB_CLIENT_SECRET'],
-    konnos: ['BRIVEN_KONNOS_CLIENT_ID', 'BRIVEN_KONNOS_CLIENT_SECRET'],
-    discord: ['BRIVEN_DISCORD_CLIENT_ID', 'BRIVEN_DISCORD_CLIENT_SECRET'],
-    microsoft: [
-      'BRIVEN_MICROSOFT_CLIENT_ID',
-      'BRIVEN_MICROSOFT_CLIENT_SECRET',
-    ],
-    facebook: ['BRIVEN_FACEBOOK_CLIENT_ID', 'BRIVEN_FACEBOOK_CLIENT_SECRET'],
-    twitter: ['BRIVEN_TWITTER_CLIENT_ID', 'BRIVEN_TWITTER_CLIENT_SECRET'],
-    linkedin: ['BRIVEN_LINKEDIN_CLIENT_ID', 'BRIVEN_LINKEDIN_CLIENT_SECRET'],
-    gitlab: ['BRIVEN_GITLAB_CLIENT_ID', 'BRIVEN_GITLAB_CLIENT_SECRET'],
-    bitbucket: [
-      'BRIVEN_BITBUCKET_CLIENT_ID',
-      'BRIVEN_BITBUCKET_CLIENT_SECRET',
-    ],
-    spotify: ['BRIVEN_SPOTIFY_CLIENT_ID', 'BRIVEN_SPOTIFY_CLIENT_SECRET'],
-    apple: ['BRIVEN_APPLE_CLIENT_ID', 'BRIVEN_APPLE_CLIENT_SECRET'],
-  };
-  const keys = envMap[thirdPartyId];
-  if (keys) {
-    const clientId = process.env[keys[0]];
-    const clientSecret = process.env[keys[1]];
-    if (clientId && clientSecret) {
-      return { clientId, clientSecret, source: 'platform_env' };
+  try {
+    const secrets = await loadProjectProviderSecrets(projectId.trim());
+    const hit = secrets.find((s) => s.thirdPartyId === thirdPartyId);
+    if (hit?.clientId && hit?.clientSecret) {
+      return {
+        clientId: hit.clientId,
+        clientSecret: hit.clientSecret,
+        source: 'project_secrets',
+      };
     }
+  } catch {
+    // secrets table / master key may be unavailable — treat as not configured
   }
+
   return null;
 }
 
@@ -272,18 +331,22 @@ export async function getAuthorisationUrl(input: {
   if (!creds) {
     return {
       status: 'NO_CREDENTIALS',
-      message: `Set project OAuth secrets for ${thirdPartyId} under Providers (client id + secret)`,
+      message:
+        `No ${thirdPartyId} Client ID + Secret for this project. ` +
+        `Open Briven Auth → Providers for this project, paste that project’s own OAuth app keys, and save. ` +
+        `Each project needs its own keys (not shared with other projects). ` +
+        `If the dashboard already shows “set”, paste both values again and save — ` +
+        `stale secrets after a key change cannot be read for login.`,
     };
   }
 
-  cleanState();
   const state = randomBytes(16).toString('hex');
   let codeVerifier: string | undefined;
   if (thirdPartyId === 'twitter') {
     // PKCE plain (simple); production apps may prefer S256 later
     codeVerifier = randomBytes(32).toString('base64url');
   }
-  OAUTH_STATE.set(state, {
+  await putOauthState(state, {
     projectId: input.projectId ?? '',
     thirdPartyId,
     createdAt: Date.now(),
@@ -342,13 +405,12 @@ export async function exchangeCodeForProfile(input: {
   let projectId = input.projectId;
   let codeVerifier: string | undefined;
   if (input.state) {
-    const st = OAUTH_STATE.get(input.state);
+    const st = await takeOauthState(input.state);
     if (!st || st.thirdPartyId !== thirdPartyId) {
       return { status: 'ERROR', message: 'invalid or expired OAuth state' };
     }
     if (st.projectId) projectId = st.projectId;
     codeVerifier = st.codeVerifier;
-    OAUTH_STATE.delete(input.state);
   }
 
   const endpoints = OAUTH_ENDPOINTS[thirdPartyId];

apps/api/src/services/auth-core/users.ts

@@ -1,9 +1,13 @@
 /**
- * briven-engine users on Doltgres.
+ * briven-engine users on Doltgres — list, detail, hold, archive, delete.
  */
 
 import { getEnginePool } from './db.js';
 import { isAuthCoreInitialized } from './engine.js';
+import { revokeAllForUser } from './native-session.js';
+import { recordBrivenEngineAudit } from './audit.js';
+
+export type BrivenEngineUserStatus = 'active' | 'held' | 'archived';
 
 export type BrivenEngineUserSummary = {
   id: string;
@@ -11,10 +15,76 @@ export type BrivenEngineUserSummary = {
   phoneNumbers: string[];
   tenantId: string;
   timeJoined: number;
+  status: BrivenEngineUserStatus;
+  heldAt: string | null;
+  heldReason: string | null;
+  archivedAt: string | null;
+  archivedReason: string | null;
   engine: 'briven-engine';
   storage: 'doltgres';
 };
 
+export type BrivenEngineUserDetail = BrivenEngineUserSummary & {
+  emailVerified: boolean;
+  metadata: Record<string, unknown>;
+  roles: string[];
+  linkedLogins: Array<{
+    id: string;
+    provider: string;
+    providerUserId: string;
+    createdAt: string;
+  }>;
+  sessions: Array<{
+    handle: string;
+    expiresAt: string;
+    createdAt: string;
+  }>;
+  passkeyCount: number;
+  totpCount: number;
+};
+
+type UserRow = {
+  id: string;
+  email: string | null;
+  phone: string | null;
+  tenant_id: string;
+  time_joined: Date | string;
+  email_verified?: boolean;
+  metadata_json?: string;
+  held_at?: Date | string | null;
+  held_reason?: string | null;
+  archived_at?: Date | string | null;
+  archived_reason?: string | null;
+};
+
+function toIso(v: Date | string | null | undefined): string | null {
+  if (v == null) return null;
+  return new Date(v).toISOString();
+}
+
+function statusOf(row: UserRow): BrivenEngineUserStatus {
+  if (row.archived_at) return 'archived';
+  if (row.held_at) return 'held';
+  return 'active';
+}
+
+function mapSummary(u: UserRow): BrivenEngineUserSummary {
+  return {
+    id: u.id,
+    emails: u.email ? [u.email] : [],
+    phoneNumbers: u.phone ? [u.phone] : [],
+    tenantId: u.tenant_id,
+    timeJoined: new Date(u.time_joined).getTime(),
+    status: statusOf(u),
+    heldAt: toIso(u.held_at),
+    heldReason: u.held_reason ?? null,
+    archivedAt: toIso(u.archived_at),
+    archivedReason: u.archived_reason ?? null,
+    engine: 'briven-engine',
+    storage: 'doltgres',
+  };
+}
+
 export async function listBrivenEngineUsers(opts?: {
   limit?: number;
   paginationToken?: string;
@@ -32,36 +102,139 @@ export async function listBrivenEngineUsers(opts?: {
   const pool = getEnginePool();
   const res = opts?.tenantId
     ? await pool.query(
-        `SELECT id, email, phone, tenant_id, time_joined FROM be_users
+        `SELECT id, email, phone, tenant_id, time_joined,
+                held_at, held_reason, archived_at, archived_reason
+         FROM be_users
          WHERE tenant_id = $1
          ORDER BY time_joined DESC LIMIT $2`,
         [opts.tenantId, limit],
       )
     : await pool.query(
-        `SELECT id, email, phone, tenant_id, time_joined FROM be_users
+        `SELECT id, email, phone, tenant_id, time_joined,
+                held_at, held_reason, archived_at, archived_reason
+         FROM be_users
          ORDER BY time_joined DESC LIMIT $1`,
         [limit],
       );
-  const users: BrivenEngineUserSummary[] = res.rows.map(
-    (u: {
-      id: string;
-      email: string | null;
-      phone: string | null;
-      tenant_id: string;
-      time_joined: Date | string;
-    }) => ({
-      id: u.id,
-      emails: u.email ? [u.email] : [],
-      phoneNumbers: u.phone ? [u.phone] : [],
-      tenantId: u.tenant_id,
-      timeJoined: new Date(u.time_joined).getTime(),
-      engine: 'briven-engine' as const,
-      storage: 'doltgres' as const,
-    }),
-  );
+  const users = (res.rows as UserRow[]).map(mapSummary);
   return { users, engine: 'briven-engine', storage: 'doltgres' };
 }
 
+export async function getBrivenEngineUser(
+  userId: string,
+  opts?: { tenantId?: string },
+): Promise<BrivenEngineUserDetail | null> {
+  if (!isAuthCoreInitialized()) return null;
+  const pool = getEnginePool();
+  const res = opts?.tenantId
+    ? await pool.query(
+        `SELECT id, email, phone, tenant_id, time_joined, email_verified, metadata_json,
+                held_at, held_reason, archived_at, archived_reason
+         FROM be_users WHERE id = $1 AND tenant_id = $2 LIMIT 1`,
+        [userId, opts.tenantId],
+      )
+    : await pool.query(
+        `SELECT id, email, phone, tenant_id, time_joined, email_verified, metadata_json,
+                held_at, held_reason, archived_at, archived_reason
+         FROM be_users WHERE id = $1 LIMIT 1`,
+        [userId],
+      );
+  const row = res.rows[0] as UserRow | undefined;
+  if (!row) return null;
+
+  let metadata: Record<string, unknown> = {};
+  try {
+    metadata = JSON.parse(row.metadata_json ?? '{}') as Record<string, unknown>;
+  } catch {
+    metadata = {};
+  }
+
+  const [rolesRes, linksRes, sessionsRes, passkeysRes, totpRes] =
+    await Promise.all([
+      pool.query(
+        `SELECT role_name FROM be_user_roles WHERE user_id = $1 ORDER BY role_name`,
+        [userId],
+      ),
+      pool.query(
+        `SELECT id, third_party_id, third_party_user_id, created_at
+         FROM be_third_party_links WHERE user_id = $1 ORDER BY created_at DESC`,
+        [userId],
+      ),
+      pool.query(
+        `SELECT session_handle, expires_at, created_at
+         FROM be_sessions
+         WHERE user_id = $1 AND expires_at > NOW()
+         ORDER BY created_at DESC`,
+        [userId],
+      ),
+      pool.query(
+        `SELECT COUNT(*)::int AS n FROM be_webauthn_credentials WHERE user_id = $1`,
+        [userId],
+      ),
+      pool.query(
+        `SELECT COUNT(*)::int AS n FROM be_totp_devices WHERE user_id = $1 AND verified = TRUE`,
+        [userId],
+      ),
+    ]);
+
+  return {
+    ...mapSummary(row),
+    emailVerified: Boolean(row.email_verified),
+    metadata,
+    roles: (rolesRes.rows as Array<{ role_name: string }>).map((r) => r.role_name),
+    linkedLogins: (
+      linksRes.rows as Array<{
+        id: string;
+        third_party_id: string;
+        third_party_user_id: string;
+        created_at: Date | string;
+      }>
+    ).map((l) => ({
+      id: l.id,
+      provider: l.third_party_id,
+      providerUserId: l.third_party_user_id,
+      createdAt: new Date(l.created_at).toISOString(),
+    })),
+    sessions: (
+      sessionsRes.rows as Array<{
+        session_handle: string;
+        expires_at: Date | string;
+        created_at: Date | string;
+      }>
+    ).map((s) => ({
+      handle: s.session_handle,
+      expiresAt: new Date(s.expires_at).toISOString(),
+      createdAt: new Date(s.created_at).toISOString(),
+    })),
+    passkeyCount: Number(
+      (passkeysRes.rows[0] as { n?: number } | undefined)?.n ?? 0,
+    ),
+    totpCount: Number((totpRes.rows[0] as { n?: number } | undefined)?.n ?? 0),
+  };
+}
+
+/**
+ * Returns null when the user may use Auth. Otherwise a machine code for 403.
+ * Held / archived users cannot sign in or keep using sessions.
+ */
+export async function getUserAccessBlock(
+  userId: string,
+): Promise<'held' | 'archived' | 'not_found' | null> {
+  if (!isAuthCoreInitialized()) return null;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `SELECT held_at, archived_at FROM be_users WHERE id = $1 LIMIT 1`,
+    [userId],
+  );
+  const row = res.rows[0] as
+    | { held_at: Date | string | null; archived_at: Date | string | null }
+    | undefined;
+  if (!row) return 'not_found';
+  if (row.archived_at) return 'archived';
+  if (row.held_at) return 'held';
+  return null;
+}
+
 export async function getBrivenEngineUserMetadata(
   userId: string,
 ): Promise<Record<string, unknown> | null> {
@@ -92,3 +265,222 @@ export async function updateBrivenEngineUserMetadata(
   );
   return (res.rowCount ?? 0) > 0;
 }
+
+async function assertUserInTenant(
+  userId: string,
+  tenantId?: string,
+): Promise<boolean> {
+  if (!tenantId) return true;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `SELECT 1 FROM be_users WHERE id = $1 AND tenant_id = $2 LIMIT 1`,
+    [userId, tenantId],
+  );
+  return (res.rowCount ?? 0) > 0;
+}
+
+/** Put account on hold — cannot sign in / use sessions; data kept. */
+export async function holdBrivenEngineUser(
+  userId: string,
+  opts?: { reason?: string; tenantId?: string },
+): Promise<boolean> {
+  if (!isAuthCoreInitialized()) return false;
+  if (!(await assertUserInTenant(userId, opts?.tenantId))) return false;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `UPDATE be_users
+     SET held_at = NOW(), held_reason = $2
+     WHERE id = $1 AND archived_at IS NULL`,
+    [userId, opts?.reason?.trim() || null],
+  );
+  const ok = (res.rowCount ?? 0) > 0;
+  if (ok) {
+    void recordBrivenEngineAudit({
+      action: 'user.held',
+      userId,
+      tenantId: opts?.tenantId ?? null,
+      metadata: { reason: opts?.reason ?? null },
+    });
+  }
+  return ok;
+}
+
+export async function unholdBrivenEngineUser(
+  userId: string,
+  opts?: { tenantId?: string },
+): Promise<boolean> {
+  if (!isAuthCoreInitialized()) return false;
+  if (!(await assertUserInTenant(userId, opts?.tenantId))) return false;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `UPDATE be_users SET held_at = NULL, held_reason = NULL WHERE id = $1`,
+    [userId],
+  );
+  const ok = (res.rowCount ?? 0) > 0;
+  if (ok) {
+    void recordBrivenEngineAudit({
+      action: 'user.unheld',
+      userId,
+      tenantId: opts?.tenantId ?? null,
+      metadata: {},
+    });
+  }
+  return ok;
+}
+
+/** Archive — hidden/blocked, data kept, can restore. */
+export async function archiveBrivenEngineUser(
+  userId: string,
+  opts?: { reason?: string; tenantId?: string },
+): Promise<boolean> {
+  if (!isAuthCoreInitialized()) return false;
+  if (!(await assertUserInTenant(userId, opts?.tenantId))) return false;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `UPDATE be_users
+     SET archived_at = NOW(), archived_reason = $2,
+         held_at = NULL, held_reason = NULL
+     WHERE id = $1`,
+    [userId, opts?.reason?.trim() || null],
+  );
+  const ok = (res.rowCount ?? 0) > 0;
+  if (ok) {
+    // Archived users should not keep live sessions.
+    await revokeAllForUser(userId);
+    void recordBrivenEngineAudit({
+      action: 'user.archived',
+      userId,
+      tenantId: opts?.tenantId ?? null,
+      metadata: { reason: opts?.reason ?? null },
+    });
+  }
+  return ok;
+}
+
+export async function unarchiveBrivenEngineUser(
+  userId: string,
+  opts?: { tenantId?: string },
+): Promise<boolean> {
+  if (!isAuthCoreInitialized()) return false;
+  if (!(await assertUserInTenant(userId, opts?.tenantId))) return false;
+  const pool = getEnginePool();
+  const res = await pool.query(
+    `UPDATE be_users
+     SET archived_at = NULL, archived_reason = NULL
+     WHERE id = $1`,
+    [userId],
+  );
+  const ok = (res.rowCount ?? 0) > 0;
+  if (ok) {
+    void recordBrivenEngineAudit({
+      action: 'user.unarchived',
+      userId,
+      tenantId: opts?.tenantId ?? null,
+      metadata: {},
+    });
+  }
+  return ok;
+}
+
+/**
+ * GDPR-style data export for one end-user (JSON package).
+ * Operator-triggered; no raw IP columns.
+ */
+export async function exportBrivenEngineUserGdpr(
+  userId: string,
+  opts?: { tenantId?: string },
+): Promise<{
+  ok: true;
+  exportedAt: string;
+  engine: 'briven-engine';
+  package: Record<string, unknown>;
+} | null> {
+  const detail = await getBrivenEngineUser(userId, opts);
+  if (!detail) return null;
+  const pool = getEnginePool();
+  const [pw, codes] = await Promise.all([
+    pool.query(
+      `SELECT COUNT(*)::int AS n FROM be_password_hashes WHERE user_id = $1`,
+      [userId],
+    ),
+    pool.query(
+      `SELECT COUNT(*)::int AS n FROM be_passwordless_codes WHERE user_id = $1`,
+      [userId],
+    ).catch(() => ({ rows: [{ n: 0 }] })),
+  ]);
+  void recordBrivenEngineAudit({
+    action: 'user.gdpr_export',
+    userId,
+    tenantId: detail.tenantId,
+    metadata: {},
+  });
+  return {
+    ok: true,
+    exportedAt: new Date().toISOString(),
+    engine: 'briven-engine',
+    package: {
+      subject: {
+        id: detail.id,
+        emails: detail.emails,
+        phoneNumbers: detail.phoneNumbers,
+        emailVerified: detail.emailVerified,
+        tenantId: detail.tenantId,
+        timeJoined: detail.timeJoined,
+        heldAt: detail.heldAt ?? null,
+        archivedAt: detail.archivedAt ?? null,
+      },
+      metadata: detail.metadata,
+      roles: detail.roles,
+      linkedLogins: detail.linkedLogins,
+      sessions: detail.sessions.map((s) => ({
+        handle: s.handle,
+        expiresAt: s.expiresAt,
+        createdAt: s.createdAt,
+      })),
+      credentials: {
+        hasPassword: Number((pw.rows[0] as { n?: number })?.n ?? 0) > 0,
+        passkeyCount: detail.passkeyCount,
+        totpCount: detail.totpCount,
+        passwordlessCodeRows: Number((codes.rows[0] as { n?: number })?.n ?? 0),
+      },
+      note: 'Password hashes and raw secrets are never included in GDPR export packages.',
+    },
+  };
+}
+
+/**
+ * Hard delete — remove user + credentials + sessions + links.
+ * Email becomes free for a new signup.
+ */
+export async function deleteBrivenEngineUser(
+  userId: string,
+  opts?: { tenantId?: string },
+): Promise<boolean> {
+  if (!isAuthCoreInitialized()) return false;
+  if (!(await assertUserInTenant(userId, opts?.tenantId))) return false;
+  const pool = getEnginePool();
+
+  // Best-effort cascade (no FKs on all tables in Doltgres engine).
+  await Promise.all([
+    pool.query(`DELETE FROM be_sessions WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_password_hashes WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_third_party_links WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_user_roles WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_totp_devices WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_webauthn_credentials WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_webauthn_challenges WHERE user_id = $1`, [userId]),
+    pool.query(`DELETE FROM be_oidc_consents WHERE user_id = $1`, [userId]),
+  ]);
+
+  const res = await pool.query(`DELETE FROM be_users WHERE id = $1`, [userId]);
+  const ok = (res.rowCount ?? 0) > 0;
+  if (ok) {
+    void recordBrivenEngineAudit({
+      action: 'user.deleted',
+      userId,
+      tenantId: opts?.tenantId ?? null,
+      metadata: {},
+    });
+  }
+  return ok;
+}

apps/api/src/services/auth-core/webauthn-rp.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveWebAuthnRp, rpIdMatchesOrigin } from './webauthn.js';
+
+describe('rpIdMatchesOrigin', () => {
+  test('exact host match', () => {
+    expect(rpIdMatchesOrigin('pay.mavifinans.sh', 'https://pay.mavifinans.sh')).toBe(
+      true,
+    );
+  });
+  test('parent domain allowed', () => {
+    expect(rpIdMatchesOrigin('mavifinans.sh', 'https://pay.mavifinans.sh')).toBe(true);
+  });
+  test('unrelated domain rejected', () => {
+    expect(rpIdMatchesOrigin('briven.tech', 'https://pay.mavifinans.sh')).toBe(false);
+  });
+});
+
+describe('resolveWebAuthnRp', () => {
+  test('uses request Origin for tenant app (not briven.tech)', async () => {
+    const r = await resolveWebAuthnRp({
+      // no project → no Allowed Domains; request origin wins
+      requestOrigin: 'https://pay.mavifinans.sh',
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.rpId).toBe('pay.mavifinans.sh');
+    expect(r.expectedOrigin).toBe('https://pay.mavifinans.sh');
+  });
+
+  test('explicit app rpId + origin', async () => {
+    const r = await resolveWebAuthnRp({
+      rpId: 'pay.mavifinans.sh',
+      expectedOrigin: 'https://pay.mavifinans.sh',
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.rpId).toBe('pay.mavifinans.sh');
+  });
+
+  test('ignores mismatched client rpId (briven.tech on mavi host)', async () => {
+    const r = await resolveWebAuthnRp({
+      rpId: 'briven.tech',
+      expectedOrigin: 'https://pay.mavifinans.sh',
+      requestOrigin: 'https://pay.mavifinans.sh',
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.rpId).toBe('pay.mavifinans.sh');
+  });
+});

apps/api/src/services/auth-core/webauthn.ts

@@ -1,5 +1,8 @@
 /**
  * briven-engine passkeys on Doltgres with @simplewebauthn/server verification.
+ *
+ * rpId / expectedOrigin MUST match the app host the user is on (e.g.
+ * pay.mavifinans.sh for mavi pay) — never hard-code briven.tech for tenant apps.
  */
 
 import { randomBytes } from 'node:crypto';
@@ -20,6 +23,7 @@ import { log } from '../../lib/logger.js';
 import { getEnginePool } from './db.js';
 import { isAuthCoreInitialized } from './engine.js';
 import { createEngineSession } from './native-session.js';
+import { getBrivenEngineAppOrigins, getBrivenEngineBranding } from './project-config.js';
 import { projectIdToTenantId } from './project-map.js';
 
 function resolveTenant(projectId?: string, tenantId?: string): string {
@@ -28,25 +32,118 @@ function resolveTenant(projectId?: string, tenantId?: string): string {
   return 'public';
 }
 
-function rpIdFrom(input?: string): string {
-  if (input) return input;
+function normalizeHttpOrigin(raw: string | null | undefined): string | null {
+  if (!raw?.trim()) return null;
   try {
-    return new URL(env.BRIVEN_WEB_ORIGIN ?? 'http://localhost:3000').hostname;
+    const u = new URL(raw.trim());
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+    if (u.protocol === 'http:' && u.hostname !== 'localhost' && u.hostname !== '127.0.0.1') {
+      return null;
+    }
+    return `${u.protocol}//${u.host}`;
   } catch {
-    return 'localhost';
+    return null;
   }
 }
 
-function originFrom(rpId: string): string {
-  const web = env.BRIVEN_WEB_ORIGIN ?? 'http://localhost:3000';
+/**
+ * rpId must equal the origin hostname, or be a parent domain of it
+ * (WebAuthn registrable-domain rule, simplified).
+ */
+export function rpIdMatchesOrigin(rpId: string, origin: string): boolean {
   try {
-    const u = new URL(web);
-    return u.origin;
+    const host = new URL(origin).hostname.toLowerCase();
+    const rp = rpId.toLowerCase().replace(/^\./, '');
+    if (!rp || !host) return false;
+    return host === rp || host.endsWith(`.${rp}`);
   } catch {
-    return rpId === 'localhost' ? 'http://localhost:3000' : `https://${rpId}`;
+    return false;
   }
 }
 
+/**
+ * Resolve which website "owns" this passkey ceremony.
+ *
+ * Priority:
+ *  1) explicit expectedOrigin / rpId from the app (mavi sends window.location)
+ *  2) browser Origin header (proxied by first-party /api/auth)
+ *  3) project's Allowed Domains list
+ *  4) last resort: BRIVEN_WEB_ORIGIN (hosted Briven only — not tenant apps)
+ */
+export async function resolveWebAuthnRp(input: {
+  projectId?: string;
+  rpId?: string | null;
+  expectedOrigin?: string | null;
+  /** Origin header from the browser (or first-party proxy). */
+  requestOrigin?: string | null;
+}): Promise<
+  | { ok: true; rpId: string; expectedOrigin: string; rpName: string }
+  | { ok: false; message: string }
+> {
+  const allowed = input.projectId
+    ? await getBrivenEngineAppOrigins(input.projectId)
+    : [];
+
+  const candidates: string[] = [];
+  const push = (raw: string | null | undefined) => {
+    const o = normalizeHttpOrigin(raw);
+    if (o && !candidates.includes(o)) candidates.push(o);
+  };
+  push(input.expectedOrigin);
+  push(input.requestOrigin);
+  for (const a of allowed) push(a);
+
+  // Hosted dashboard only — never preferred when the project has its own apps.
+  if (candidates.length === 0) {
+    push(env.BRIVEN_WEB_ORIGIN ?? null);
+  }
+
+  let expectedOrigin: string | null = null;
+  for (const o of candidates) {
+    if (allowed.length === 0 || allowed.includes(o)) {
+      expectedOrigin = o;
+      break;
+    }
+  }
+  // If Allowed Domains is empty, still accept https app origin from the request
+  // (first-day projects before they finish the domain checklist).
+  if (!expectedOrigin && candidates[0]) {
+    expectedOrigin = candidates[0];
+  }
+  if (!expectedOrigin) {
+    return {
+      ok: false,
+      message:
+        'Passkey needs an app origin. Open your app over HTTPS and add it under Auth → Allowed Domains.',
+    };
+  }
+
+  let rpId = (input.rpId ?? '').trim().toLowerCase() || null;
+  if (rpId && !rpIdMatchesOrigin(rpId, expectedOrigin)) {
+    // Ignore a mismatched client rpId; derive from origin instead.
+    rpId = null;
+  }
+  if (!rpId) {
+    try {
+      rpId = new URL(expectedOrigin).hostname;
+    } catch {
+      return { ok: false, message: 'invalid passkey origin' };
+    }
+  }
+
+  let rpName = 'Briven Auth';
+  if (input.projectId) {
+    try {
+      const brand = await getBrivenEngineBranding(input.projectId);
+      if (brand.senderName?.trim()) rpName = brand.senderName.trim();
+    } catch {
+      /* keep default */
+    }
+  }
+
+  return { ok: true, rpId, expectedOrigin, rpName };
+}
+
 function b64urlToBuffer(s: string): Buffer {
   const pad = s.length % 4 === 0 ? '' : '='.repeat(4 - (s.length % 4));
   const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + pad;
@@ -59,6 +156,8 @@ export async function createRegistrationOptions(input: {
   projectId?: string;
   tenantId?: string;
   rpId?: string;
+  expectedOrigin?: string;
+  requestOrigin?: string | null;
 }): Promise<
   | {
       status: 'OK';
@@ -73,7 +172,13 @@ export async function createRegistrationOptions(input: {
     return { status: 'ERROR', message: 'engine not ready' };
   }
   const tenantId = resolveTenant(input.projectId, input.tenantId);
-  const rpID = rpIdFrom(input.rpId);
+  const rp = await resolveWebAuthnRp({
+    projectId: input.projectId,
+    rpId: input.rpId,
+    expectedOrigin: input.expectedOrigin,
+    requestOrigin: input.requestOrigin,
+  });
+  if (!rp.ok) return { status: 'ERROR', message: rp.message };
   const pool = getEnginePool();
 
   const existing = await pool.query(
@@ -89,8 +194,8 @@ export async function createRegistrationOptions(input: {
   }));
 
   const options = await generateRegistrationOptions({
-    rpName: 'Briven Auth',
-    rpID,
+    rpName: rp.rpName,
+    rpID: rp.rpId,
     userName: input.userName,
     userID: new TextEncoder().encode(input.userId),
     userDisplayName: input.userName,
@@ -104,12 +209,16 @@ export async function createRegistrationOptions(input: {
 
   const challengeId = `wac_${randomBytes(12).toString('hex')}`;
   const expiresAt = new Date(Date.now() + 5 * 60 * 1000);
-  await pool.query(
-    `INSERT INTO be_webauthn_challenges
-      (challenge_id, tenant_id, user_id, challenge, type, expires_at)
-     VALUES ($1, $2, $3, $4, 'registration', $5)`,
-    [challengeId, tenantId, input.userId, options.challenge, expiresAt.toISOString()],
-  );
+  await insertWebauthnChallenge(pool, {
+    challengeId,
+    tenantId,
+    userId: input.userId,
+    challenge: options.challenge,
+    type: 'registration',
+    expiresAt: expiresAt.toISOString(),
+    rpId: rp.rpId,
+    expectedOrigin: rp.expectedOrigin,
+  });
 
   return {
     status: 'OK',
@@ -120,6 +229,116 @@ export async function createRegistrationOptions(input: {
   };
 }
 
+let rpColumnsReady: Promise<boolean> | null = null;
+/** Best-effort: add rp_id / expected_origin on challenges (Doltgres/Postgres). */
+async function ensureWebauthnRpColumns(
+  pool: ReturnType<typeof getEnginePool>,
+): Promise<boolean> {
+  if (!rpColumnsReady) {
+    rpColumnsReady = (async () => {
+      try {
+        await pool.query(
+          `ALTER TABLE be_webauthn_challenges ADD COLUMN IF NOT EXISTS rp_id TEXT`,
+        );
+        await pool.query(
+          `ALTER TABLE be_webauthn_challenges ADD COLUMN IF NOT EXISTS expected_origin TEXT`,
+        );
+        return true;
+      } catch (err) {
+        log.warn('webauthn_rp_columns_ensure_failed', {
+          message: err instanceof Error ? err.message : String(err),
+        });
+        rpColumnsReady = null;
+        return false;
+      }
+    })();
+  }
+  return rpColumnsReady;
+}
+
+async function insertWebauthnChallenge(
+  pool: ReturnType<typeof getEnginePool>,
+  row: {
+    challengeId: string;
+    tenantId: string;
+    userId: string | null;
+    challenge: string;
+    type: 'registration' | 'authentication';
+    expiresAt: string;
+    rpId: string;
+    expectedOrigin: string;
+  },
+): Promise<void> {
+  const hasCols = await ensureWebauthnRpColumns(pool);
+  if (hasCols) {
+    try {
+      await pool.query(
+        `INSERT INTO be_webauthn_challenges
+          (challenge_id, tenant_id, user_id, challenge, type, expires_at, rp_id, expected_origin)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+        [
+          row.challengeId,
+          row.tenantId,
+          row.userId,
+          row.challenge,
+          row.type,
+          row.expiresAt,
+          row.rpId,
+          row.expectedOrigin,
+        ],
+      );
+      return;
+    } catch {
+      /* fall through to legacy insert */
+    }
+  }
+  await pool.query(
+    `INSERT INTO be_webauthn_challenges
+      (challenge_id, tenant_id, user_id, challenge, type, expires_at)
+     VALUES ($1, $2, $3, $4, $5, $6)`,
+    [
+      row.challengeId,
+      row.tenantId,
+      row.userId,
+      row.challenge,
+      row.type,
+      row.expiresAt,
+    ],
+  );
+}
+
+async function loadWebauthnChallenge(
+  pool: ReturnType<typeof getEnginePool>,
+  challengeId: string,
+  type: 'registration' | 'authentication',
+): Promise<{
+  challenge: string;
+  tenant_id: string;
+  expires_at: string | Date;
+  user_id?: string | null;
+  rp_id?: string | null;
+  expected_origin?: string | null;
+} | null> {
+  await ensureWebauthnRpColumns(pool);
+  try {
+    const ch = await pool.query(
+      `SELECT challenge, tenant_id, expires_at, user_id, rp_id, expected_origin
+       FROM be_webauthn_challenges
+       WHERE challenge_id = $1 AND type = $2 LIMIT 1`,
+      [challengeId, type],
+    );
+    return (ch.rows[0] as never) ?? null;
+  } catch {
+    const ch = await pool.query(
+      `SELECT challenge, tenant_id, expires_at, user_id
+       FROM be_webauthn_challenges
+       WHERE challenge_id = $1 AND type = $2 LIMIT 1`,
+      [challengeId, type],
+    );
+    return (ch.rows[0] as never) ?? null;
+  }
+}
+
 export async function finishRegistration(input: {
   userId: string;
   challengeId: string;
@@ -132,6 +351,7 @@ export async function finishRegistration(input: {
   projectId?: string;
   expectedOrigin?: string;
   rpId?: string;
+  requestOrigin?: string | null;
 }): Promise<{
   status: 'OK' | 'ERROR';
   message?: string;
@@ -142,19 +362,7 @@ export async function finishRegistration(input: {
     return { status: 'ERROR', message: 'engine not ready' };
   }
   const pool = getEnginePool();
-  const ch = await pool.query(
-    `SELECT challenge, tenant_id, expires_at, user_id FROM be_webauthn_challenges
-     WHERE challenge_id = $1 AND type = 'registration' LIMIT 1`,
-    [input.challengeId],
-  );
-  const row = ch.rows[0] as
-    | {
-        challenge: string;
-        tenant_id: string;
-        expires_at: string | Date;
-        user_id: string | null;
-      }
-    | undefined;
+  const row = await loadWebauthnChallenge(pool, input.challengeId, 'registration');
   if (!row || row.user_id !== input.userId) {
     return { status: 'ERROR', message: 'invalid challenge' };
   }
@@ -162,8 +370,16 @@ export async function finishRegistration(input: {
     return { status: 'ERROR', message: 'challenge expired' };
   }
 
-  const rpID = rpIdFrom(input.rpId);
-  const expectedOrigin = input.expectedOrigin ?? originFrom(rpID);
+  const rp = await resolveWebAuthnRp({
+    projectId: input.projectId,
+    // Prefer values bound at options-create time (cannot be spoofed mid-flow).
+    rpId: row.rp_id || input.rpId,
+    expectedOrigin: row.expected_origin || input.expectedOrigin,
+    requestOrigin: input.requestOrigin,
+  });
+  if (!rp.ok) return { status: 'ERROR', message: rp.message };
+  const rpID = rp.rpId;
+  const expectedOrigin = rp.expectedOrigin;
 
   let credentialId: string;
   let publicKey: string;
@@ -237,6 +453,8 @@ export async function createAuthenticationOptions(input: {
   tenantId?: string;
   userId?: string;
   rpId?: string;
+  expectedOrigin?: string;
+  requestOrigin?: string | null;
 }): Promise<
   | {
       status: 'OK';
@@ -251,7 +469,13 @@ export async function createAuthenticationOptions(input: {
     return { status: 'ERROR', message: 'engine not ready' };
   }
   const tenantId = resolveTenant(input.projectId, input.tenantId);
-  const rpID = rpIdFrom(input.rpId);
+  const rp = await resolveWebAuthnRp({
+    projectId: input.projectId,
+    rpId: input.rpId,
+    expectedOrigin: input.expectedOrigin,
+    requestOrigin: input.requestOrigin,
+  });
+  if (!rp.ok) return { status: 'ERROR', message: rp.message };
   const pool = getEnginePool();
 
   let allowCredentials:
@@ -272,25 +496,23 @@ export async function createAuthenticationOptions(input: {
   }
 
   const options = await generateAuthenticationOptions({
-    rpID,
+    rpID: rp.rpId,
     allowCredentials,
     userVerification: 'preferred',
   });
 
   const challengeId = `wac_${randomBytes(12).toString('hex')}`;
   const expiresAt = new Date(Date.now() + 5 * 60 * 1000);
-  await pool.query(
-    `INSERT INTO be_webauthn_challenges
-      (challenge_id, tenant_id, user_id, challenge, type, expires_at)
-     VALUES ($1, $2, $3, $4, 'authentication', $5)`,
-    [
-      challengeId,
-      tenantId,
-      input.userId ?? null,
-      options.challenge,
-      expiresAt.toISOString(),
-    ],
-  );
+  await insertWebauthnChallenge(pool, {
+    challengeId,
+    tenantId,
+    userId: input.userId ?? null,
+    challenge: options.challenge,
+    type: 'authentication',
+    expiresAt: expiresAt.toISOString(),
+    rpId: rp.rpId,
+    expectedOrigin: rp.expectedOrigin,
+  });
 
   return {
     status: 'OK',
@@ -309,6 +531,7 @@ export async function finishAuthentication(input: {
   projectId?: string;
   expectedOrigin?: string;
   rpId?: string;
+  requestOrigin?: string | null;
 }): Promise<
   | {
       status: 'OK';
@@ -327,14 +550,7 @@ export async function finishAuthentication(input: {
     return { status: 'ERROR', message: 'engine not ready' };
   }
   const pool = getEnginePool();
-  const ch = await pool.query(
-    `SELECT challenge, tenant_id, expires_at FROM be_webauthn_challenges
-     WHERE challenge_id = $1 AND type = 'authentication' LIMIT 1`,
-    [input.challengeId],
-  );
-  const row = ch.rows[0] as
-    | { challenge: string; tenant_id: string; expires_at: string | Date }
-    | undefined;
+  const row = await loadWebauthnChallenge(pool, input.challengeId, 'authentication');
   if (!row) return { status: 'ERROR', message: 'invalid challenge' };
   if (new Date(row.expires_at).getTime() < Date.now()) {
     return { status: 'ERROR', message: 'challenge expired' };
@@ -365,14 +581,19 @@ export async function finishAuthentication(input: {
   let newCounter = Number(c.counter) + 1;
 
   if (input.response) {
-    const rpID = rpIdFrom(input.rpId);
-    const expectedOrigin = input.expectedOrigin ?? originFrom(rpID);
+    const rp = await resolveWebAuthnRp({
+      projectId: input.projectId,
+      rpId: row.rp_id || input.rpId,
+      expectedOrigin: row.expected_origin || input.expectedOrigin,
+      requestOrigin: input.requestOrigin,
+    });
+    if (!rp.ok) return { status: 'ERROR', message: rp.message };
     try {
       const verification = await verifyAuthenticationResponse({
         response: input.response,
         expectedChallenge: row.challenge,
-        expectedOrigin,
-        expectedRPID: rpID,
+        expectedOrigin: rp.expectedOrigin,
+        expectedRPID: rp.rpId,
         credential: {
           id: credentialId,
           publicKey: b64urlToBuffer(c.public_key),

apps/api/src/services/auth-core/workspace.ts

@@ -27,7 +27,7 @@ export type BrivenEngineWorkspaceProject = {
 
 /**
  * Enable Auth for a project = create briven-engine tenant island on Doltgres.
- * Idempotent.
+ * Idempotent. Re-enables if previously soft-disabled.
  */
 export async function enableBrivenEngineAuth(projectId: string): Promise<{
   ok: boolean;
@@ -40,6 +40,19 @@ export async function enableBrivenEngineAuth(projectId: string): Promise<{
   storage: 'doltgres';
 }> {
   const result = await ensureBrivenEngineTenant(projectId);
+  if (result.ok) {
+    try {
+      const pool = getEnginePool();
+      // Clear soft-disable so Auth is on again (users/data stay intact).
+      await pool.query(
+        `UPDATE be_tenants SET disabled_at = NULL
+         WHERE tenant_id = $1 OR project_id = $2`,
+        [result.tenantId, result.projectId],
+      );
+    } catch {
+      /* column may not exist yet on very old engines — treat as enabled */
+    }
+  }
   return {
     ok: result.ok,
     engine: 'briven-engine',
@@ -53,8 +66,90 @@ export async function enableBrivenEngineAuth(projectId: string): Promise<{
 }
 
 /**
- * Whether Auth is on for a project (tenant row exists).
- * Prefer exact tenant_id match (always reliable on Doltgres).
+ * Turn Auth off for a project without deleting end-users or credentials.
+ * Soft-disable: tenant stays, disabled_at is set; app login should treat Auth as off.
+ */
+export async function disableBrivenEngineAuth(projectId: string): Promise<{
+  ok: boolean;
+  engine: 'briven-engine';
+  projectId: string;
+  tenantId: string;
+  authEnabled: boolean;
+  message?: string;
+  storage: 'doltgres';
+}> {
+  const map = mapProjectToAuthCore(projectId);
+  const base = {
+    engine: 'briven-engine' as const,
+    storage: 'doltgres' as const,
+    projectId: map.projectId,
+    tenantId: map.tenantId,
+  };
+  if (!isAuthCoreInitialized()) {
+    return {
+      ...base,
+      ok: false,
+      authEnabled: false,
+      message: 'briven-engine not ready on Doltgres',
+    };
+  }
+  try {
+    const pool = getEnginePool();
+    // Ensure soft-disable column exists (older engines may not have run migration).
+    try {
+      await pool.query(`ALTER TABLE be_tenants ADD COLUMN disabled_at TIMESTAMPTZ`);
+    } catch {
+      /* already exists or unsupported — continue */
+    }
+    const existing = await pool.query(
+      `SELECT tenant_id FROM be_tenants
+       WHERE tenant_id = $1 OR project_id = $2
+       LIMIT 1`,
+      [map.tenantId, map.projectId],
+    );
+    if (!existing.rowCount) {
+      return {
+        ...base,
+        ok: true,
+        authEnabled: false,
+        message: 'Auth was already off for this project',
+      };
+    }
+    try {
+      await pool.query(
+        `UPDATE be_tenants SET disabled_at = NOW()
+         WHERE tenant_id = $1 OR project_id = $2`,
+        [map.tenantId, map.projectId],
+      );
+    } catch (err) {
+      // Fallback if disabled_at column missing: leave row (still "on") and report.
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        ...base,
+        ok: false,
+        authEnabled: true,
+        message: `could not disable Auth: ${message}`,
+      };
+    }
+    return {
+      ...base,
+      ok: true,
+      authEnabled: false,
+      message:
+        'Auth disabled for this project. User data is kept — enable Auth again anytime.',
+    };
+  } catch (err) {
+    return {
+      ...base,
+      ok: false,
+      authEnabled: true,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Whether Auth is on for a project (tenant row exists and not soft-disabled).
  */
 export async function isBrivenEngineAuthEnabled(
   projectId: string,
@@ -63,13 +158,25 @@ export async function isBrivenEngineAuthEnabled(
   try {
     const map = mapProjectToAuthCore(projectId);
     const pool = getEnginePool();
-    const res = await pool.query(
-      `SELECT 1 FROM be_tenants
-       WHERE tenant_id = $1 OR project_id = $2
-       LIMIT 1`,
-      [map.tenantId, map.projectId],
-    );
-    return Boolean(res.rowCount && res.rowCount > 0);
+    // Prefer disabled_at IS NULL; if column missing, any tenant row means on.
+    try {
+      const res = await pool.query(
+        `SELECT 1 FROM be_tenants
+         WHERE (tenant_id = $1 OR project_id = $2)
+           AND disabled_at IS NULL
+         LIMIT 1`,
+        [map.tenantId, map.projectId],
+      );
+      return Boolean(res.rowCount && res.rowCount > 0);
+    } catch {
+      const res = await pool.query(
+        `SELECT 1 FROM be_tenants
+         WHERE tenant_id = $1 OR project_id = $2
+         LIMIT 1`,
+        [map.tenantId, map.projectId],
+      );
+      return Boolean(res.rowCount && res.rowCount > 0);
+    }
   } catch {
     return false;
   }
@@ -109,10 +216,16 @@ export async function listBrivenEngineWorkspace(
   if (isAuthCoreInitialized() && maps.length > 0) {
     try {
       const pool = getEnginePool();
-      // Load all tenants (small table) — avoids IN-clause / lower() quirks on Doltgres.
-      const res = await pool.query(
-        `SELECT project_id, tenant_id FROM be_tenants`,
-      );
+      // Active Auth only: tenant row and not soft-disabled.
+      let res;
+      try {
+        res = await pool.query(
+          `SELECT project_id, tenant_id FROM be_tenants
+           WHERE disabled_at IS NULL`,
+        );
+      } catch {
+        res = await pool.query(`SELECT project_id, tenant_id FROM be_tenants`);
+      }
       for (const row of res.rows as Array<{
         project_id: string;
         tenant_id: string;

apps/api/src/services/auth-device-tracking.ts

@@ -94,6 +94,7 @@ export async function maybeAlertNewDevice(
       deviceHint: hint,
       whenIso: new Date().toISOString(),
       manageUrl: `${process.env.BRIVEN_API_ORIGIN ?? 'https://api.briven.tech'}/v1/auth-tenant/get-session?briven_project_id=${projectId}`,
+      userAgent,
     }).catch(() => {
       // Swallow — email failure must not break sign-in.
     });

apps/api/src/services/auth-mailer.test.ts

@@ -112,7 +112,7 @@ describe('auth-mailer — pure helpers (BUILD_PLAN.md §8)', () => {
 
   test('renderMagicLink includes the URL + expiry + sender name', () => {
     const r = renderMagicLink(ctx, { url: 'https://example.com/x', expiryMinutes: 15 });
-    expect(r.subject).toBe('your sign-in link to acme auth');
+    expect(r.subject).toBe('Your acme auth Auth sign-in');
     expect(r.html).toContain('https://example.com/x');
     expect(r.html).toContain('15 minutes');
     expect(r.text).toContain('https://example.com/x');
@@ -155,9 +155,9 @@ describe('auth-mailer — pure helpers (BUILD_PLAN.md §8)', () => {
 
   // ─── renderPasswordReset ────────────────────────────────────────────
 
-  test('renderPasswordReset includes "secure your account" disclaimer', () => {
+  test('renderPasswordReset includes ignore + secure disclaimer', () => {
     const r = renderPasswordReset(ctx, { url: 'https://acme.test/reset?token=xyz' });
-    expect(r.html.toLowerCase()).toContain('secure your account');
+    expect(r.html.toLowerCase()).toContain('ignore this email');
     expect(r.text.toLowerCase()).toContain('secure your account');
     expect(r.html).toContain('https://acme.test/reset?token=xyz');
   });
@@ -179,13 +179,21 @@ describe('auth-mailer — pure helpers (BUILD_PLAN.md §8)', () => {
 
   // ─── cross-render invariants ────────────────────────────────────────
 
-  test('every template renders sender name into the footer', () => {
+  test('every template renders sender name; custom footer when provided', () => {
+    const withFooter: RenderContext = {
+      ...ctx,
+      footerLines: [
+        'made with ♥ Flanders by flndrn',
+        '100% self-funded, sustainable & independent',
+        'flndrn Limited, Limassol, Cyprus',
+      ],
+    };
     const outs = [
-      renderMagicLink(ctx, { url: 'https://x.test', expiryMinutes: 5 }),
-      renderOtpCode(ctx, { code: '111', expiryMinutes: 5 }),
-      renderEmailVerify(ctx, { url: 'https://x.test' }),
-      renderPasswordReset(ctx, { url: 'https://x.test' }),
-      renderNewDeviceLogin(ctx, {
+      renderMagicLink(withFooter, { url: 'https://x.test', expiryMinutes: 5 }),
+      renderOtpCode(withFooter, { code: '111', expiryMinutes: 5 }),
+      renderEmailVerify(withFooter, { url: 'https://x.test' }),
+      renderPasswordReset(withFooter, { url: 'https://x.test' }),
+      renderNewDeviceLogin(withFooter, {
         deviceHint: 'd',
         whenIso: 't',
         manageUrl: 'https://x.test',
@@ -193,6 +201,8 @@ describe('auth-mailer — pure helpers (BUILD_PLAN.md §8)', () => {
     ];
     for (const out of outs) {
       expect(out.html).toContain('acme auth');
+      expect(out.html).toContain('Flanders');
+      expect(out.html).toContain('Limassol');
     }
   });
 

apps/api/src/services/auth-mailer.ts

@@ -4,6 +4,17 @@ import { log } from '../lib/logger.js';
 import { recordAuthMailerFailure } from './auth-reliability.js';
 import { getAuthConfig, type AuthConfig } from './tenant-config-store.js';
 import { getEmailTemplate, renderTemplate, type EmailTemplateName } from './auth-email-templates.js';
+import {
+  type AuthEmailRequestMeta,
+  authEmailRequestMetaHtml,
+  authEmailRequestMetaText,
+  resolveAuthEmailRequestMeta,
+} from './auth-core/auth-email-context.js';
+import {
+  buildAuthEmailFooterLines,
+  getBrivenEngineBranding,
+  type BrivenEngineBranding,
+} from './auth-core/project-config.js';
 
 /**
  * briven auth per-tenant email pipeline (BUILD_PLAN.md §8).
@@ -46,26 +57,111 @@ export function escapeHtml(s: string): string {
     .replace(/'/g, ''');
 }
 
-// ─── shell + cta with per-tenant primary color ──────────────────────────
+// ─── shell + cta (Flanders footer — same layout as control-plane mail) ──
 
 interface ShellArgs {
   title: string;
   body: string;
   primaryColor: string;
   senderName: string;
+  logoUrl?: string | null;
+  brandUrl?: string | null;
+  footerNote?: string | null;
+  /** Optional custom footer lines (from briven-engine branding). */
+  footerLines?: string[];
+  /** Platform / device location / send time. */
+  requestMeta?: AuthEmailRequestMeta | null;
 }
 
-function shell({ title, body, primaryColor, senderName }: ShellArgs): string {
-  // Inline-styled for max email-client compatibility. Dark-themed defaults
-  // per BRAND.md §3; primary color is the only per-tenant variable.
+function safeHttpUrl(url: string | null | undefined): string | null {
+  if (!url) return null;
+  const t = url.trim();
+  if (t.length > 500 || /[\s"'<>]/.test(t)) return null;
+  try {
+    const u = new URL(t);
+    if (u.protocol === 'https:') return u.toString();
+    if (u.protocol === 'http:' && u.hostname === 'localhost') return u.toString();
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function shell({
+  title,
+  body,
+  primaryColor,
+  senderName,
+  logoUrl,
+  brandUrl,
+  footerNote,
+  footerLines,
+  requestMeta,
+}: ShellArgs): string {
   const accent = primaryColor.toLowerCase();
-  return `<!doctype html><html><body style="margin:0;padding:0;background:#0a0b0d;color:#f5f7fa;font-family:system-ui,-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif">
-  <div style="max-width:520px;margin:0 auto;padding:40px 24px">
-    <h1 style="font-size:20px;font-weight:600;margin:0 0 24px;color:#f5f7fa">${escapeHtml(title)}</h1>
-    <div style="font-size:15px;line-height:1.5;color:#d1d5db">${body}</div>
-    <hr style="border:none;border-top:1px solid #2a2e36;margin:32px 0">
-    <p style="font-size:12px;color:#6b7280;margin:0">${escapeHtml(senderName)} · powered by <span style="color:${accent}">briven auth</span></p>
-  </div>
+  const name = escapeHtml(senderName);
+  const safeLogo = safeHttpUrl(logoUrl ?? null);
+  const logoMark = safeLogo
+    ? `<img src="${escapeHtml(safeLogo)}" alt="" width="32" height="32" style="display:block;border:0;outline:none;border-radius:8px;object-fit:contain" />`
+    : `<span style="display:inline-block;width:28px;height:28px;border-radius:999px;background:${escapeHtml(accent)};box-shadow:0 0 0 3px ${escapeHtml(accent)}33"></span>`;
+
+  let brandHref: string | null = null;
+  let brandLabel: string | null = null;
+  if (brandUrl?.trim()) {
+    const raw = brandUrl.trim();
+    if (/^https?:\/\//i.test(raw)) {
+      brandHref = safeHttpUrl(raw);
+      brandLabel = brandHref
+        ? brandHref.replace(/^https?:\/\//i, '').replace(/\/$/, '')
+        : null;
+    } else if (/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/i.test(raw)) {
+      brandHref = `https://${raw}`;
+      brandLabel = raw;
+    }
+  }
+  const brandLine = brandHref
+    ? `${name} · <a style="color:#9ba3af" href="${escapeHtml(brandHref)}">${escapeHtml(brandLabel ?? brandHref)}</a>`
+    : name;
+  const note = footerNote?.trim()
+    ? `<p style="margin:12px 0 0 0;font-size:12px;color:#6b7280">${escapeHtml(footerNote.trim())}</p>`
+    : '';
+
+  const customHtml = (footerLines ?? [])
+    .map((line) =>
+      escapeHtml(line).replace(
+        '♥',
+        '<span style="color:#e8344a">&#9829;</span>',
+      ),
+    )
+    .join('<br/>');
+  const footerBlock = customHtml
+    ? `${brandLine}<br/>${customHtml}`
+    : brandLine;
+
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="color-scheme" content="dark"><title>${escapeHtml(title)}</title></head>
+<body style="margin:0;background:#0a0b0d;color:#f5f7fa;font-family:system-ui,-apple-system,sans-serif;line-height:1.6">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:#0a0b0d">
+    <tr><td align="center" style="padding:32px 16px">
+      <table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0" style="max-width:600px;width:100%;background:#13151a;border:1px solid #2a2e36;border-radius:14px;padding:32px">
+        <tr><td>
+          <table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 20px 0">
+            <tr>
+              <td style="padding-right:10px;vertical-align:middle">${logoMark}</td>
+              <td style="vertical-align:middle"><span style="font-size:20px;font-weight:500;letter-spacing:-0.02em;color:#f5f7fa">${name}</span></td>
+            </tr>
+          </table>
+          <h2 style="font-size:18px;font-weight:500;margin:0 0 12px 0;color:#f5f7fa">${escapeHtml(title)}</h2>
+          <div style="font-size:15px;line-height:1.6;color:#d1d5db">${body}</div>
+          ${requestMeta ? authEmailRequestMetaHtml(requestMeta) : ''}
+          ${note}
+          <p style="color:#6b7280;font-size:12px;margin-top:32px;border-top:1px solid #1e2128;padding-top:16px">
+            ${footerBlock}
+          </p>
+        </td></tr>
+      </table>
+    </td></tr>
+  </table>
 </body></html>`;
 }
 
@@ -74,7 +170,7 @@ function cta(label: string, href: string, primaryColor: string): string {
   // briven brand contrast: text on accent is always #0a0b0d (dark) regardless
   // of which hex the customer picked. Their primary-color picker enforces
   // WCAG-AA against #0a0b0d (BUILD_PLAN.md §6 Branding panel).
-  return `<p style="margin:32px 0"><a href="${escapeHtml(href)}" style="display:inline-block;background:${accent};color:#0a0b0d;padding:12px 24px;border-radius:10px;font-weight:500;text-decoration:none">${escapeHtml(label)}</a></p>`;
+  return `<p style="margin:0 0 24px 0"><a href="${escapeHtml(href)}" style="display:inline-block;background:${accent};color:#0a0b0d;padding:12px 24px;border-radius:10px;font-weight:500;text-decoration:none">${escapeHtml(label)}</a></p>`;
 }
 
 // ─── template renderers (pure; exported for tests) ──────────────────────
@@ -82,25 +178,50 @@ function cta(label: string, href: string, primaryColor: string): string {
 export interface RenderContext {
   primaryColor: string;
   senderName: string;
+  /** Public URL of the *uploaded* logo (never a free-form customer paste). */
+  logoUrl?: string | null;
+  /** Brand site for footer (`name · brandUrl`). */
+  brandUrl?: string | null;
+  footerNote?: string | null;
+  footerLines?: string[];
+  requestMeta?: AuthEmailRequestMeta | null;
+}
+
+function shellOpts(ctx: RenderContext, title: string, body: string): ShellArgs {
+  return {
+    title,
+    body,
+    primaryColor: ctx.primaryColor,
+    senderName: ctx.senderName,
+    logoUrl: ctx.logoUrl,
+    brandUrl: ctx.brandUrl,
+    footerNote: ctx.footerNote,
+    footerLines: ctx.footerLines,
+    requestMeta: ctx.requestMeta,
+  };
 }
 
 export function renderMagicLink(
   ctx: RenderContext,
   args: { url: string; expiryMinutes: number },
 ): { subject: string; html: string; text: string } {
+  const metaText = ctx.requestMeta
+    ? `\n\n${authEmailRequestMetaText(ctx.requestMeta)}`
+    : '';
   return {
-    subject: `your sign-in link to ${ctx.senderName}`,
-    html: shell({
-      title: 'sign in',
-      body: `
-        <p>click below to sign in. this link expires in ${args.expiryMinutes} minutes.</p>
+    subject: `Your ${ctx.senderName} Auth sign-in`,
+    html: shell(
+      shellOpts(
+        ctx,
+        `sign in to ${ctx.senderName}`,
+        `
+        <p style="margin:0 0 24px 0;color:#9ba3af;font-size:15px">click the button below to sign in. this link expires in ${args.expiryMinutes} minutes.</p>
         ${cta('sign in', args.url, ctx.primaryColor)}
-        <p style="color:#6b7280;font-size:13px">if you didn't request this, ignore the email — nothing happens.</p>
+        <p style="margin:0;color:#6b7280;font-size:13px">if you didn't request this, you can ignore this email.</p>
       `,
-      primaryColor: ctx.primaryColor,
-      senderName: ctx.senderName,
-    }),
-    text: `sign in to ${ctx.senderName}\n\n${args.url}\n\nthis link expires in ${args.expiryMinutes} minutes. if you didn't request it, ignore this email.`,
+      ),
+    ),
+    text: `sign in to ${ctx.senderName}\n\n${args.url}\n\nthis link expires in ${args.expiryMinutes} minutes. if you didn't request it, ignore this email.${metaText}`,
   };
 }
 
@@ -109,19 +230,23 @@ export function renderOtpCode(
   args: { code: string; expiryMinutes: number },
 ): { subject: string; html: string; text: string } {
   const escapedCode = escapeHtml(args.code);
+  const metaText = ctx.requestMeta
+    ? `\n\n${authEmailRequestMetaText(ctx.requestMeta)}`
+    : '';
   return {
-    subject: `your ${ctx.senderName} sign-in code: ${args.code}`,
-    html: shell({
-      title: 'one-time code',
-      body: `
-        <p>enter this code to finish signing in. it expires in ${args.expiryMinutes} minutes.</p>
-        <p style="font-family:ui-monospace,SFMono-Regular,monospace;font-size:32px;letter-spacing:8px;text-align:center;background:#1a1d24;border-radius:10px;padding:24px;border:1px solid #2a2e36;color:#f5f7fa">${escapedCode}</p>
-        <p style="color:#6b7280;font-size:13px">if you didn't request this, someone may have typed your email by mistake. you can ignore it safely.</p>
+    subject: `Your ${ctx.senderName} Auth code: ${args.code}`,
+    html: shell(
+      shellOpts(
+        ctx,
+        `sign in to ${ctx.senderName}`,
+        `
+        <p style="margin:0 0 16px 0;color:#9ba3af;font-size:15px">enter this code to finish signing in. it expires in ${args.expiryMinutes} minutes.</p>
+        <p style="margin:0 0 24px 0;font-family:ui-monospace,SFMono-Regular,monospace;font-size:28px;letter-spacing:0.35em;text-align:center;background:#1a1d24;border-radius:10px;padding:20px 16px;border:1px solid #2a2e36;color:#f5f7fa">${escapedCode}</p>
+        <p style="margin:0;color:#6b7280;font-size:13px">if you didn't request this, you can ignore this email.</p>
       `,
-      primaryColor: ctx.primaryColor,
-      senderName: ctx.senderName,
-    }),
-    text: `sign in to ${ctx.senderName}\n\nyour code: ${args.code}\n\nthis code expires in ${args.expiryMinutes} minutes. if you didn't request it, ignore this email.`,
+      ),
+    ),
+    text: `sign in to ${ctx.senderName}\n\nyour code: ${args.code}\n\nthis code expires in ${args.expiryMinutes} minutes. if you didn't request it, ignore this email.${metaText}`,
   };
 }
 
@@ -129,19 +254,23 @@ export function renderEmailVerify(
   ctx: RenderContext,
   args: { url: string },
 ): { subject: string; html: string; text: string } {
+  const metaText = ctx.requestMeta
+    ? `\n\n${authEmailRequestMetaText(ctx.requestMeta)}`
+    : '';
   return {
     subject: `verify your email for ${ctx.senderName}`,
-    html: shell({
-      title: 'verify your email',
-      body: `
-        <p>click below to confirm this email address.</p>
+    html: shell(
+      shellOpts(
+        ctx,
+        `verify your email for ${ctx.senderName}`,
+        `
+        <p style="margin:0 0 24px 0;color:#9ba3af;font-size:15px">click the button below to confirm this email address.</p>
         ${cta('verify email', args.url, ctx.primaryColor)}
-        <p style="color:#6b7280;font-size:13px">if you didn't sign up, ignore the email.</p>
+        <p style="margin:0;color:#6b7280;font-size:13px">if you didn't request this, you can ignore this email.</p>
       `,
-      primaryColor: ctx.primaryColor,
-      senderName: ctx.senderName,
-    }),
-    text: `verify your email for ${ctx.senderName}\n\n${args.url}\n\nif you didn't sign up, ignore this email.`,
+      ),
+    ),
+    text: `verify your email for ${ctx.senderName}\n\n${args.url}\n\nif you didn't sign up, ignore this email.${metaText}`,
   };
 }
 
@@ -149,19 +278,23 @@ export function renderPasswordReset(
   ctx: RenderContext,
   args: { url: string },
 ): { subject: string; html: string; text: string } {
+  const metaText = ctx.requestMeta
+    ? `\n\n${authEmailRequestMetaText(ctx.requestMeta)}`
+    : '';
   return {
     subject: `reset your ${ctx.senderName} password`,
-    html: shell({
-      title: 'reset your password',
-      body: `
-        <p>click below to choose a new password. this link expires in 1 hour.</p>
+    html: shell(
+      shellOpts(
+        ctx,
+        `reset your ${ctx.senderName} password`,
+        `
+        <p style="margin:0 0 24px 0;color:#9ba3af;font-size:15px">click the button below to choose a new password. this link expires in 1 hour.</p>
         ${cta('reset password', args.url, ctx.primaryColor)}
-        <p style="color:#6b7280;font-size:13px">if you didn't request this, secure your account: change your password and review active sessions.</p>
+        <p style="margin:0;color:#6b7280;font-size:13px">if you didn't request this, you can ignore this email. if it wasn't you, secure your account.</p>
       `,
-      primaryColor: ctx.primaryColor,
-      senderName: ctx.senderName,
-    }),
-    text: `reset your ${ctx.senderName} password\n\n${args.url}\n\nthis link expires in 1 hour. if you didn't request this, secure your account.`,
+      ),
+    ),
+    text: `reset your ${ctx.senderName} password\n\n${args.url}\n\nthis link expires in 1 hour. if you didn't request this, secure your account.${metaText}`,
   };
 }
 
@@ -173,23 +306,27 @@ export function renderNewDeviceLogin(
   // the call site so this template doesn't see raw IPs (CLAUDE.md §5.1).
   const escDevice = escapeHtml(args.deviceHint);
   const escWhen = escapeHtml(args.whenIso);
+  const metaText = ctx.requestMeta
+    ? `\n\n${authEmailRequestMetaText(ctx.requestMeta)}`
+    : '';
   return {
     subject: `new sign-in to ${ctx.senderName}`,
-    html: shell({
-      title: 'new device signed in',
-      body: `
-        <p>a new device just signed in to your account.</p>
-        <p style="background:#1a1d24;border-radius:8px;padding:12px;font-family:ui-monospace,SFMono-Regular,monospace;font-size:13px;color:#9ba3af;border:1px solid #2a2e36">
+    html: shell(
+      shellOpts(
+        ctx,
+        `new sign-in to ${ctx.senderName}`,
+        `
+        <p style="margin:0 0 16px 0;color:#9ba3af;font-size:15px">a new device just signed in to your account.</p>
+        <p style="margin:0 0 24px 0;background:#1a1d24;border-radius:8px;padding:12px;font-family:ui-monospace,SFMono-Regular,monospace;font-size:13px;color:#9ba3af;border:1px solid #2a2e36">
           ${escDevice}<br>
           at ${escWhen}
         </p>
         ${cta('manage sessions', args.manageUrl, ctx.primaryColor)}
-        <p style="color:#6b7280;font-size:13px">if this was you, no action needed. if not, revoke the session immediately and change your password.</p>
+        <p style="margin:0;color:#6b7280;font-size:13px">if this was you, no action needed. if not, revoke the session and change your password.</p>
       `,
-      primaryColor: ctx.primaryColor,
-      senderName: ctx.senderName,
-    }),
-    text: `new sign-in to ${ctx.senderName}\n\n${args.deviceHint}\nat ${args.whenIso}\n\nmanage: ${args.manageUrl}\n\nif this wasn't you, revoke the session and change your password.`,
+      ),
+    ),
+    text: `new sign-in to ${ctx.senderName}\n\n${args.deviceHint}\nat ${args.whenIso}\n\nmanage: ${args.manageUrl}\n\nif this wasn't you, revoke the session and change your password.${metaText}`,
   };
 }
 
@@ -294,16 +431,62 @@ async function maybeUseCustomTemplate(
  * config. Used by Better Auth's `magicLink` plugin's `sendMagicLink`
  * callback (wired in `auth-tenant-pool.ts` when the plugin is enabled).
  */
+async function renderCtxForProject(
+  projectId: string,
+  config: AuthConfig,
+  request?: {
+    userAgent?: string | null;
+    clientHintsUa?: string | null;
+    clientIp?: string | null;
+  },
+): Promise<RenderContext> {
+  // Prefer briven-engine branding (dashboard Auth → branding) for logo + footer.
+  let engine: BrivenEngineBranding | null = null;
+  try {
+    engine = await getBrivenEngineBranding(projectId);
+  } catch {
+    engine = null;
+  }
+  const primaryColor =
+    engine?.primaryColor ?? config.branding.primaryColor;
+  const senderName = engine?.senderName ?? config.branding.senderName;
+  const logoUrl = engine?.logoUrl ?? config.branding.logoUrl;
+  const brandUrl = engine?.brandUrl ?? null;
+  const footerNote = engine?.footerNote ?? null;
+  const footerLines = engine ? buildAuthEmailFooterLines(engine) : [];
+  const requestMeta =
+    request?.userAgent || request?.clientIp || request?.clientHintsUa
+      ? await resolveAuthEmailRequestMeta({
+          userAgent: request.userAgent,
+          clientHintsUa: request.clientHintsUa,
+          clientIp: request.clientIp,
+        })
+      : null;
+  return {
+    primaryColor,
+    senderName,
+    logoUrl,
+    brandUrl,
+    footerNote,
+    footerLines,
+    requestMeta,
+  };
+}
+
+export type AuthMailRequestContext = {
+  userAgent?: string | null;
+  clientHintsUa?: string | null;
+  clientIp?: string | null;
+};
+
 export async function sendBrivenAuthMagicLink(
   projectId: string,
   to: string,
   url: string,
+  request?: AuthMailRequestContext,
 ): Promise<void> {
   const config = await getAuthConfig(projectId);
-  const ctx: RenderContext = {
-    primaryColor: config.branding.primaryColor,
-    senderName: config.branding.senderName,
-  };
+  const ctx = await renderCtxForProject(projectId, config, request);
   const tpl = await maybeUseCustomTemplate(
     projectId,
     'magic-link',
@@ -317,12 +500,10 @@ export async function sendBrivenAuthOtp(
   projectId: string,
   to: string,
   code: string,
+  request?: AuthMailRequestContext,
 ): Promise<void> {
   const config = await getAuthConfig(projectId);
-  const ctx: RenderContext = {
-    primaryColor: config.branding.primaryColor,
-    senderName: config.branding.senderName,
-  };
+  const ctx = await renderCtxForProject(projectId, config, request);
   const tpl = await maybeUseCustomTemplate(
     projectId,
     'otp',
@@ -336,12 +517,10 @@ export async function sendBrivenAuthEmailVerification(
   projectId: string,
   to: string,
   url: string,
+  request?: AuthMailRequestContext,
 ): Promise<void> {
   const config = await getAuthConfig(projectId);
-  const ctx: RenderContext = {
-    primaryColor: config.branding.primaryColor,
-    senderName: config.branding.senderName,
-  };
+  const ctx = await renderCtxForProject(projectId, config, request);
   const tpl = await maybeUseCustomTemplate(
     projectId,
     'verification',
@@ -355,12 +534,10 @@ export async function sendBrivenAuthPasswordReset(
   projectId: string,
   to: string,
   url: string,
+  request?: AuthMailRequestContext,
 ): Promise<void> {
   const config = await getAuthConfig(projectId);
-  const ctx: RenderContext = {
-    primaryColor: config.branding.primaryColor,
-    senderName: config.branding.senderName,
-  };
+  const ctx = await renderCtxForProject(projectId, config, request);
   const tpl = await maybeUseCustomTemplate(
     projectId,
     'password-reset',
@@ -373,13 +550,19 @@ export async function sendBrivenAuthPasswordReset(
 export async function sendBrivenAuthNewDeviceLogin(
   projectId: string,
   to: string,
-  args: { deviceHint: string; whenIso: string; manageUrl: string },
+  args: {
+    deviceHint: string;
+    whenIso: string;
+    manageUrl: string;
+    userAgent?: string | null;
+    clientIp?: string | null;
+  },
 ): Promise<void> {
   const config = await getAuthConfig(projectId);
-  const ctx: RenderContext = {
-    primaryColor: config.branding.primaryColor,
-    senderName: config.branding.senderName,
-  };
+  const ctx = await renderCtxForProject(projectId, config, {
+    userAgent: args.userAgent,
+    clientIp: args.clientIp,
+  });
   const tpl = renderNewDeviceLogin(ctx, args);
   await sendForTenant('briven_auth_new_device', { projectId, to, ...tpl });
 }

apps/api/src/services/auth-origin-allowlist.ts

@@ -91,13 +91,35 @@ async function ensureTable(): Promise<void> {
   tableReady = true;
 }
 
-/** Briven's own origins — always trusted, independent of the DB/cache. */
+/**
+ * Briven's own origins — always trusted, independent of the DB/cache.
+ * Includes product host aliases (app./admin./www.) for the apex in
+ * BRIVEN_WEB_ORIGIN — Traefik serves the dashboard on briven.tech AND
+ * app.briven.tech; CLI Allow was failing CSRF on the app host (2026-07-29).
+ */
 export function brivenOwnOrigins(): string[] {
-  return [
+  const list = new Set<string>();
+  for (const o of [
     env.BRIVEN_WEB_ORIGIN,
     env.BRIVEN_STUDIO_ORIGIN,
-    ...(env.BRIVEN_ADMIN_ORIGIN ? [env.BRIVEN_ADMIN_ORIGIN] : []),
-  ].filter(Boolean);
+    env.BRIVEN_ADMIN_ORIGIN,
+    env.BRIVEN_API_ORIGIN,
+  ]) {
+    if (o) list.add(o.replace(/\/$/, ''));
+  }
+  try {
+    const web = new URL(env.BRIVEN_WEB_ORIGIN);
+    const host = web.hostname;
+    // Only add aliases for real product apex hosts (not localhost).
+    if (host && !host.includes('localhost') && host !== '127.0.0.1') {
+      for (const sub of ['app', 'admin', 'www']) {
+        list.add(`${web.protocol}//${sub}.${host}`);
+      }
+    }
+  } catch {
+    /* ignore bad WEB_ORIGIN */
+  }
+  return [...list].filter(Boolean);
 }
 
 /**

apps/api/src/services/auth-tenant-pool.ts

@@ -821,7 +821,7 @@ export function buildGenericOAuthConfigs(
 
   const konnos = config.providers.konnos;
   if (konnos.enabled && konnos.clientId && secrets.konnos) {
-    // Forgejo (code.konnos.org) — gitea-compatible OAuth endpoints, mirroring
+    // Git at code.konnos.org — OAuth endpoints, mirroring
     // the control-plane wiring in lib/auth.ts.
     const issuer = env.BRIVEN_KONNOS_ISSUER.replace(/\/$/, '');
     entries.push({

apps/api/src/services/invoke.ts

@@ -92,14 +92,22 @@ export async function invoke(input: InvokeInput): Promise<InvokeResult> {
 
   if (!res.ok) {
     const body = await res.text().catch(() => '');
-    log.error('runtime_error', {
+    // 401 from the runtime almost always means BRIVEN_RUNTIME_SHARED_SECRET
+    // drifted between api and runtime after a partial redeploy (see skill gotcha #17).
+    const likelySecretMismatch =
+      res.status === 401 && body.includes('runtime is not open to the public');
+    log.error(likelySecretMismatch ? 'runtime_shared_secret_mismatch' : 'runtime_error', {
       projectId: input.projectId,
       status: res.status,
       body: body.slice(0, 500),
     });
-    throw new brivenError('runtime_error', 'function runtime returned an error', {
-      status: 502,
-    });
+    throw new brivenError(
+      likelySecretMismatch ? 'runtime_auth_failed' : 'runtime_error',
+      likelySecretMismatch
+        ? 'function runtime rejected the control plane (shared secret mismatch — recreate runtime with .env.prod)'
+        : 'function runtime returned an error',
+      { status: 502 },
+    );
   }
 
   const payload = (await res.json()) as {

apps/api/src/services/service-badges.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  isMintableServiceBadgeProduct,
+  isServiceBadgeProduct,
+  isServiceBadgeRole,
+  looksLikeServiceBadge,
+  serviceBadgeAllowedOnRoute,
+  SERVICE_BADGE_PREFIX,
+} from './service-badges.js';
+
+describe('service badge product helpers', () => {
+  test('accepts known products', () => {
+    expect(isServiceBadgeProduct('db')).toBe(true);
+    expect(isServiceBadgeProduct('s3')).toBe(true);
+    expect(isServiceBadgeProduct('auth')).toBe(true);
+    expect(isServiceBadgeProduct('pay')).toBe(true);
+  });
+
+  test('rejects unknown products', () => {
+    expect(isServiceBadgeProduct('mcp')).toBe(false);
+    expect(isServiceBadgeProduct('')).toBe(false);
+  });
+
+  test('pay is reserved — not mintable yet', () => {
+    expect(isMintableServiceBadgeProduct('db')).toBe(true);
+    expect(isMintableServiceBadgeProduct('s3')).toBe(true);
+    expect(isMintableServiceBadgeProduct('auth')).toBe(true);
+    expect(isMintableServiceBadgeProduct('pay')).toBe(false);
+  });
+
+  test('roles are viewer | developer | admin', () => {
+    expect(isServiceBadgeRole('viewer')).toBe(true);
+    expect(isServiceBadgeRole('developer')).toBe(true);
+    expect(isServiceBadgeRole('admin')).toBe(true);
+    expect(isServiceBadgeRole('owner')).toBe(false);
+  });
+});
+
+describe('looksLikeServiceBadge', () => {
+  test('matches product prefixes', () => {
+    expect(looksLikeServiceBadge(`${SERVICE_BADGE_PREFIX.db}abc`)).toBe(true);
+    expect(looksLikeServiceBadge(`${SERVICE_BADGE_PREFIX.s3}abc`)).toBe(true);
+    expect(looksLikeServiceBadge(`${SERVICE_BADGE_PREFIX.auth}abc`)).toBe(true);
+  });
+
+  test('rejects other key shapes', () => {
+    expect(looksLikeServiceBadge('brk_abc')).toBe(false);
+    expect(looksLikeServiceBadge('pk_briven_mcp_abc')).toBe(false);
+    expect(looksLikeServiceBadge('m2m_abc')).toBe(false);
+  });
+});
+
+describe('serviceBadgeAllowedOnRoute — product walls', () => {
+  test('session / brk_ (no badge product) may enter any wall', () => {
+    expect(serviceBadgeAllowedOnRoute(null, 'db')).toBe(true);
+    expect(serviceBadgeAllowedOnRoute(null, 's3')).toBe(true);
+    expect(serviceBadgeAllowedOnRoute(null, 'auth')).toBe(true);
+    expect(serviceBadgeAllowedOnRoute(undefined, 'db')).toBe(true);
+  });
+
+  test('db badge only opens Doltgres wall', () => {
+    expect(serviceBadgeAllowedOnRoute('db', 'db')).toBe(true);
+    expect(serviceBadgeAllowedOnRoute('db', 's3')).toBe(false);
+    expect(serviceBadgeAllowedOnRoute('db', 'auth')).toBe(false);
+  });
+
+  test('s3 badge only opens S3 wall', () => {
+    expect(serviceBadgeAllowedOnRoute('s3', 's3')).toBe(true);
+    expect(serviceBadgeAllowedOnRoute('s3', 'db')).toBe(false);
+  });
+
+  test('auth badge only opens Auth wall', () => {
+    expect(serviceBadgeAllowedOnRoute('auth', 'auth')).toBe(true);
+    expect(serviceBadgeAllowedOnRoute('auth', 'db')).toBe(false);
+  });
+
+  test('no badge may open routeProduct=any (everything)', () => {
+    expect(serviceBadgeAllowedOnRoute('db', 'any')).toBe(false);
+    expect(serviceBadgeAllowedOnRoute(null, 'any')).toBe(true);
+  });
+});

apps/api/src/services/service-badges.ts

@@ -0,0 +1,436 @@
+/**
+ * Service badges — project-scoped agent/machine passes.
+ *
+ * One badge opens exactly one product wall inside one project:
+ *   db   → Doltgres (studio / query / tables) via bearer `sb_db_…`
+ *   s3   → this project's MinIO/S3 bucket (storage key under the hood)
+ *   auth → SuperTokens-style M2M client_credentials (briven-engine)
+ *   pay  → reserved (not mintable yet)
+ *
+ * Secrets are returned once at create. Revoke is idempotent.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+
+import { newId, NotFoundError, ValidationError } from '@briven/shared';
+import { and, desc, eq, isNull, sql } from 'drizzle-orm';
+
+import { env } from '../env.js';
+import { getDb } from '../db/client.js';
+import {
+  serviceBadgeProduct,
+  serviceBadgeRole,
+  serviceBadges,
+  type ServiceBadgeProduct,
+  type ServiceBadgeRole,
+} from '../db/schema.js';
+import { createM2mClient, revokeM2mClient } from './auth-core/m2m.js';
+import { createStorageKey, revokeStorageKey } from './storage-keys.js';
+
+const KEY_ENTROPY_BYTES = 32;
+const NAME_MIN = 1;
+const NAME_MAX = 80;
+
+/** Plaintext prefix per product — greppable if leaked. */
+export const SERVICE_BADGE_PREFIX: Record<ServiceBadgeProduct, string> = {
+  db: 'sb_db_',
+  s3: 'sb_s3_',
+  auth: 'sb_auth_',
+  pay: 'sb_pay_',
+};
+
+const MINTABLE: readonly ServiceBadgeProduct[] = ['db', 's3', 'auth'];
+
+export function isServiceBadgeProduct(v: string): v is ServiceBadgeProduct {
+  return (serviceBadgeProduct as readonly string[]).includes(v);
+}
+
+export function isMintableServiceBadgeProduct(v: string): v is 'db' | 's3' | 'auth' {
+  return (MINTABLE as readonly string[]).includes(v);
+}
+
+export function isServiceBadgeRole(v: string): v is ServiceBadgeRole {
+  return (serviceBadgeRole as readonly string[]).includes(v);
+}
+
+/** True when a bearer looks like any service-badge secret. */
+export function looksLikeServiceBadge(token: string): boolean {
+  return (
+    token.startsWith(SERVICE_BADGE_PREFIX.db) ||
+    token.startsWith(SERVICE_BADGE_PREFIX.s3) ||
+    token.startsWith(SERVICE_BADGE_PREFIX.auth) ||
+    token.startsWith(SERVICE_BADGE_PREFIX.pay)
+  );
+}
+
+function hashBearer(plaintext: string): string {
+  return createHash('sha256').update(plaintext).digest('hex');
+}
+
+let tableReady = false;
+async function ensureTable(): Promise<void> {
+  if (tableReady) return;
+  await getDb().execute(
+    sql.raw(`
+      CREATE TABLE IF NOT EXISTS "service_badges" (
+        "id" text PRIMARY KEY NOT NULL,
+        "project_id" text NOT NULL,
+        "product" text NOT NULL,
+        "name" text NOT NULL,
+        "role" text DEFAULT 'developer' NOT NULL,
+        "prefix" text NOT NULL,
+        "suffix" varchar(4) NOT NULL,
+        "hash" text,
+        "storage_key_id" text,
+        "m2m_client_id" text,
+        "created_by" text,
+        "last_used_at" timestamp with time zone,
+        "expires_at" timestamp with time zone,
+        "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+        "revoked_at" timestamp with time zone
+      )`),
+  );
+  await getDb().execute(
+    sql.raw(
+      `CREATE UNIQUE INDEX IF NOT EXISTS "service_badges_hash_idx" ON "service_badges" ("hash")`,
+    ),
+  );
+  await getDb().execute(
+    sql.raw(
+      `CREATE INDEX IF NOT EXISTS "service_badges_project_product_idx" ON "service_badges" ("project_id","product")`,
+    ),
+  );
+  tableReady = true;
+}
+
+export interface MaskedServiceBadge {
+  id: string;
+  product: ServiceBadgeProduct;
+  name: string;
+  role: ServiceBadgeRole;
+  prefix: string;
+  suffix: string;
+  /** product=auth: M2M client id (public half of the machine pair). */
+  m2mClientId: string | null;
+  /** product=s3: MinIO access key id. */
+  storageAccessKeyId: string | null;
+  createdAt: string;
+  lastUsedAt: string | null;
+  expiresAt: string | null;
+  revokedAt: string | null;
+}
+
+export interface CreatedServiceBadge {
+  badge: MaskedServiceBadge;
+  /**
+   * product=db: full bearer secret (sb_db_…).
+   * product=s3 / auth: may be null; product-specific secrets below.
+   */
+  plaintext: string | null;
+  /** product=s3 only — MinIO credentials for this project's bucket. */
+  s3?: {
+    endpoint: string;
+    bucket: string;
+    accessKey: string;
+    secretKey: string;
+  };
+  /** product=auth only — SuperTokens-style M2M client credentials. */
+  auth?: {
+    clientId: string;
+    clientSecret: string;
+    tokenUrl: string;
+  };
+}
+
+function iso(d: Date | null | undefined): string | null {
+  if (!d) return null;
+  return (d instanceof Date ? d : new Date(d)).toISOString();
+}
+
+function toMasked(row: {
+  id: string;
+  product: ServiceBadgeProduct;
+  name: string;
+  role: ServiceBadgeRole;
+  prefix: string;
+  suffix: string;
+  m2mClientId: string | null;
+  storageKeyId: string | null;
+  createdAt: Date;
+  lastUsedAt: Date | null;
+  expiresAt: Date | null;
+  revokedAt: Date | null;
+  storageAccessKeyId?: string | null;
+}): MaskedServiceBadge {
+  return {
+    id: row.id,
+    product: row.product,
+    name: row.name,
+    role: row.role,
+    prefix: row.prefix,
+    suffix: row.suffix,
+    m2mClientId: row.m2mClientId,
+    storageAccessKeyId: row.storageAccessKeyId ?? null,
+    createdAt: iso(row.createdAt) ?? new Date().toISOString(),
+    lastUsedAt: iso(row.lastUsedAt),
+    expiresAt: iso(row.expiresAt),
+    revokedAt: iso(row.revokedAt),
+  };
+}
+
+export async function listServiceBadges(
+  projectId: string,
+  product?: ServiceBadgeProduct,
+): Promise<MaskedServiceBadge[]> {
+  await ensureTable();
+  const db = getDb();
+  const rows = await db
+    .select()
+    .from(serviceBadges)
+    .where(
+      product
+        ? and(eq(serviceBadges.projectId, projectId), eq(serviceBadges.product, product))
+        : eq(serviceBadges.projectId, projectId),
+    )
+    .orderBy(desc(serviceBadges.createdAt));
+
+  return rows.map((r) =>
+    toMasked({
+      ...r,
+      storageAccessKeyId: null,
+    }),
+  );
+}
+
+export async function createServiceBadge(input: {
+  projectId: string;
+  product: ServiceBadgeProduct;
+  name: string;
+  role?: ServiceBadgeRole;
+  createdBy: string | null;
+  expiresAt?: Date;
+}): Promise<CreatedServiceBadge> {
+  await ensureTable();
+  const name = input.name.trim();
+  if (name.length < NAME_MIN || name.length > NAME_MAX) {
+    throw new ValidationError(`name must be ${NAME_MIN}-${NAME_MAX} chars`, { name });
+  }
+  if (!isMintableServiceBadgeProduct(input.product)) {
+    throw new ValidationError(
+      input.product === 'pay'
+        ? 'Briven Pay badges are not available yet'
+        : `product must be one of ${MINTABLE.join(' | ')}`,
+      { product: input.product },
+    );
+  }
+  const role: ServiceBadgeRole =
+    input.role && isServiceBadgeRole(input.role) ? input.role : 'developer';
+  if (!isServiceBadgeRole(role)) {
+    throw new ValidationError(`role must be one of ${serviceBadgeRole.join(' | ')}`, { role });
+  }
+
+  const prefix = SERVICE_BADGE_PREFIX[input.product];
+  const id = newId('sb');
+
+  if (input.product === 'db') {
+    const raw = randomBytes(KEY_ENTROPY_BYTES).toString('base64url');
+    const plaintext = `${prefix}${raw}`;
+    const hash = hashBearer(plaintext);
+    const suffix = plaintext.slice(-4);
+
+    const [record] = await getDb()
+      .insert(serviceBadges)
+      .values({
+        id,
+        projectId: input.projectId,
+        product: 'db',
+        name,
+        role,
+        prefix,
+        suffix,
+        hash,
+        createdBy: input.createdBy,
+        expiresAt: input.expiresAt ?? null,
+      })
+      .returning();
+    if (!record) throw new Error('service_badges insert returned no row');
+
+    return {
+      badge: toMasked({ ...record, storageAccessKeyId: null }),
+      plaintext,
+    };
+  }
+
+  if (input.product === 's3') {
+    const publicEndpoint =
+      env.BRIVEN_MINIO_PUBLIC_ENDPOINT ?? env.BRIVEN_MINIO_ENDPOINT ?? '';
+    const created = await createStorageKey({
+      projectId: input.projectId,
+      name,
+      createdBy: input.createdBy,
+      publicEndpoint,
+    });
+    // Registry row links to the storage key; secret is MinIO's, not a sb_s3_ bearer.
+    const [record] = await getDb()
+      .insert(serviceBadges)
+      .values({
+        id,
+        projectId: input.projectId,
+        product: 's3',
+        name,
+        role,
+        prefix,
+        suffix: created.record.suffix,
+        hash: null,
+        storageKeyId: created.record.id,
+        createdBy: input.createdBy,
+        expiresAt: input.expiresAt ?? null,
+      })
+      .returning();
+    if (!record) throw new Error('service_badges insert returned no row');
+
+    return {
+      badge: toMasked({
+        ...record,
+        storageAccessKeyId: created.accessKey,
+      }),
+      plaintext: null,
+      s3: {
+        endpoint: created.endpoint,
+        bucket: created.bucket,
+        accessKey: created.accessKey,
+        secretKey: created.secretKey,
+      },
+    };
+  }
+
+  // product === 'auth' — SuperTokens-style M2M under the hood
+  const m2m = await createM2mClient({
+    projectId: input.projectId,
+    name,
+    role,
+    createdBy: input.createdBy,
+  });
+  const [record] = await getDb()
+    .insert(serviceBadges)
+    .values({
+      id,
+      projectId: input.projectId,
+      product: 'auth',
+      name,
+      role,
+      prefix,
+      suffix: m2m.client.secretSuffix,
+      hash: null,
+      m2mClientId: m2m.client.clientId,
+      createdBy: input.createdBy,
+      expiresAt: input.expiresAt ?? null,
+    })
+    .returning();
+  if (!record) throw new Error('service_badges insert returned no row');
+
+  const apiBase = (env.BRIVEN_API_ORIGIN ?? '').replace(/\/$/, '');
+  const tokenUrl = apiBase
+    ? `${apiBase}/v1/auth-core/oauth/token`
+    : '/v1/auth-core/oauth/token';
+
+  return {
+    badge: toMasked({ ...record, storageAccessKeyId: null }),
+    plaintext: null,
+    auth: {
+      clientId: m2m.client.clientId,
+      clientSecret: m2m.clientSecret,
+      tokenUrl,
+    },
+  };
+}
+
+export async function revokeServiceBadge(
+  projectId: string,
+  badgeId: string,
+): Promise<void> {
+  await ensureTable();
+  const db = getDb();
+  const [row] = await db
+    .select()
+    .from(serviceBadges)
+    .where(and(eq(serviceBadges.id, badgeId), eq(serviceBadges.projectId, projectId)))
+    .limit(1);
+  if (!row) throw new NotFoundError('service_badge', badgeId);
+  if (row.revokedAt) return; // idempotent
+
+  // Tear down the product credential first, then stamp the registry.
+  if (row.product === 's3' && row.storageKeyId) {
+    try {
+      await revokeStorageKey(projectId, row.storageKeyId);
+    } catch {
+      // storage key may already be gone — still revoke the badge row
+    }
+  }
+  if (row.product === 'auth' && row.m2mClientId) {
+    try {
+      await revokeM2mClient(projectId, row.m2mClientId);
+    } catch {
+      // m2m client may already be gone
+    }
+  }
+
+  await db
+    .update(serviceBadges)
+    .set({ revokedAt: new Date() })
+    .where(eq(serviceBadges.id, badgeId));
+}
+
+/**
+ * Resolve a Doltgres (product=db) bearer secret.
+ * Returns null if invalid, wrong product, revoked, or expired.
+ */
+export async function resolveDbServiceBadge(plaintext: string): Promise<{
+  badgeId: string;
+  projectId: string;
+  role: ServiceBadgeRole;
+  product: 'db';
+} | null> {
+  if (!plaintext.startsWith(SERVICE_BADGE_PREFIX.db)) return null;
+  await ensureTable();
+  const hash = hashBearer(plaintext);
+  const db = getDb();
+  const [row] = await db
+    .select()
+    .from(serviceBadges)
+    .where(
+      and(
+        eq(serviceBadges.hash, hash),
+        eq(serviceBadges.product, 'db'),
+        isNull(serviceBadges.revokedAt),
+      ),
+    )
+    .limit(1);
+  if (!row) return null;
+  if (row.expiresAt && row.expiresAt.getTime() < Date.now()) return null;
+
+  await db
+    .update(serviceBadges)
+    .set({ lastUsedAt: new Date() })
+    .where(eq(serviceBadges.id, row.id));
+
+  return {
+    badgeId: row.id,
+    projectId: row.projectId,
+    role: row.role,
+    product: 'db',
+  };
+}
+
+/**
+ * Product wall check: a service-badge actor may only call routes for its product.
+ * Session / brk_ / CLI / M2M JWT actors have no product lock (full project tools).
+ */
+export function serviceBadgeAllowedOnRoute(
+  badgeProduct: ServiceBadgeProduct | null | undefined,
+  routeProduct: ServiceBadgeProduct | 'any',
+): boolean {
+  if (!badgeProduct) return true; // not a service-badge actor
+  if (routeProduct === 'any') return false; // badge never opens "everything"
+  return badgeProduct === routeProduct;
+}

apps/api/src/services/tenant-config-store.ts

@@ -98,7 +98,7 @@ const authConfigSchema = z.object({
     dropbox: oauthProviderConfig,
     facebook: oauthProviderConfig,
     spotify: oauthProviderConfig,
-    // Generic OIDC/OAuth provider (Forgejo at code.konnos.org). Same
+    // Generic OIDC/OAuth provider (Git at code.konnos.org). Same
     // {enabled, clientId} shape as the built-in social providers — the
     // public client id is non-secret; the secret rides the encrypted
     // tenant-secret-store like the others.

apps/api/src/services/tenant-secrets.ts

@@ -3,6 +3,7 @@ import { and, eq } from 'drizzle-orm';
 
 import { getDb } from '../db/client.js';
 import { tenantSecrets } from '../db/schema.js';
+import { log } from '../lib/logger.js';
 
 import {
   decryptTenantSecret,
@@ -83,7 +84,24 @@ export async function getTenantSecret(
     )
     .limit(1);
   if (!row) return null;
-  return decryptTenantSecret({ service, projectId, ciphertext: row.encryptedValue });
+  try {
+    return decryptTenantSecret({
+      service,
+      projectId,
+      ciphertext: row.encryptedValue,
+    });
+  } catch (err) {
+    // Row exists but ciphertext won't open (e.g. master key rotated). Callers
+    // treat null as "not configured" so the dashboard asks the user to re-save.
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn('tenant_secret_decrypt_failed', {
+      projectId,
+      service,
+      name,
+      message,
+    });
+    return null;
+  }
 }
 
 /**
@@ -111,3 +129,25 @@ export async function hasTenantSecret(
     .limit(1);
   return row !== undefined;
 }
+
+/**
+ * Permanently remove a secret row. Idempotent — missing row is success.
+ */
+export async function deleteTenantSecret(
+  projectId: string,
+  service: TenantService,
+  name: string,
+): Promise<boolean> {
+  const db = getDb();
+  const deleted = await db
+    .delete(tenantSecrets)
+    .where(
+      and(
+        eq(tenantSecrets.projectId, projectId),
+        eq(tenantSecrets.service, service),
+        eq(tenantSecrets.name, name),
+      ),
+    )
+    .returning({ id: tenantSecrets.id });
+  return deleted.length > 0;
+}

apps/api/src/types/app-env.ts

@@ -19,10 +19,15 @@ export type AppEnv = {
  * `apiKeyId` when the request is authenticated via a project-scoped API
  * key (`brk_…`) instead of a session, and `projectRole` — the caller's
  * effective `MemberRole` on the project — for both auth branches.
+ *
+ * When the caller used a **service badge** (product-scoped agent pass),
+ * `serviceBadgeProduct` is set to that badge's product (`db` | `s3` |
+ * `auth` | `pay`). Session / brk_ / CLI / M2M JWT leave it null.
  */
 export type ProjectAppEnv = {
   Variables: AppEnv['Variables'] & {
     apiKeyId: string | null;
     projectRole: MemberRole | null;
+    serviceBadgeProduct: import('../db/schema.js').ServiceBadgeProduct | null;
   };
 };

apps/docs/src/app/auth/frameworks/page.tsx

@@ -0,0 +1,90 @@
+import { DocsShell } from '../../../components/shell';
+
+export const metadata = { title: 'auth · framework packs' };
+
+/**
+ * SuperTokens-class framework integration pack (first cut).
+ * Copy-paste patterns for wiring Briven Auth into common stacks.
+ */
+export default function AuthFrameworksPage() {
+  return (
+    <DocsShell>
+      <h1 className="font-mono text-2xl tracking-tight">auth framework packs</h1>
+      <p className="mt-2 font-mono text-sm text-[var(--color-text-muted)]">
+        drop-in patterns for Briven Auth (briven-engine). Prefer a{' '}
+        <strong className="text-[var(--color-text)]">first-party proxy</strong> on your
+        domain so session cookies stay first-party.
+      </p>
+
+      <h2 className="mt-10 font-mono text-lg">1. Next.js (App Router)</h2>
+      <pre className="mt-3 overflow-x-auto rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-surface)] p-4 font-mono text-[11px] text-[var(--color-text-muted)]">{`// apps/web/src/app/api/auth/[...path]/route.ts
+export async function POST(req: Request, ctx: { params: { path: string[] } }) {
+  const path = ctx.params.path.join('/');
+  const url = \`\${process.env.BRIVEN_API_ORIGIN}/v1/auth-core/fdi/\${path}\`;
+  const body = await req.text();
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': req.headers.get('content-type') ?? 'application/json',
+      cookie: req.headers.get('cookie') ?? '',
+    },
+    body,
+  });
+  // forward Set-Cookie to first-party host
+  return new Response(await res.text(), {
+    status: res.status,
+    headers: res.headers,
+  });
+}`}</pre>
+
+      <h2 className="mt-10 font-mono text-lg">2. Express / Node</h2>
+      <pre className="mt-3 overflow-x-auto rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-surface)] p-4 font-mono text-[11px] text-[var(--color-text-muted)]">{`app.use('/api/auth', async (req, res) => {
+  const target = process.env.BRIVEN_API_ORIGIN + '/v1/auth-core/fdi' + req.url;
+  const r = await fetch(target, {
+    method: req.method,
+    headers: { 'content-type': 'application/json', cookie: req.headers.cookie ?? '' },
+    body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body),
+  });
+  res.status(r.status).send(await r.text());
+});`}</pre>
+
+      <h2 className="mt-10 font-mono text-lg">3. OIDC “Sign in with Briven” (any stack)</h2>
+      <ol className="mt-3 list-decimal space-y-2 pl-5 font-mono text-sm text-[var(--color-text-muted)]">
+        <li>
+          Create a client under dashboard → Auth → <strong className="text-[var(--color-text)]">IdP</strong>
+        </li>
+        <li>
+          Discovery:{' '}
+          <code className="text-[var(--color-text)]">
+            GET https://api.briven.tech/v1/auth-core/oidc/.well-known/openid-configuration
+          </code>
+        </li>
+        <li>Use any OIDC library (Auth.js, passport-openidconnect, appauth) with those endpoints</li>
+      </ol>
+
+      <h2 className="mt-10 font-mono text-lg">4. M2M / server jobs</h2>
+      <pre className="mt-3 overflow-x-auto rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-surface)] p-4 font-mono text-[11px] text-[var(--color-text-muted)]">{`const tok = await fetch('https://api.briven.tech/v1/auth-core/oauth/token', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    grant_type: 'client_credentials',
+    client_id: process.env.M2M_CLIENT_ID,
+    client_secret: process.env.M2M_CLIENT_SECRET,
+  }),
+}).then((r) => r.json());
+// Authorization: Bearer \${tok.access_token}`}</pre>
+
+      <h2 className="mt-10 font-mono text-lg">5. AI agents</h2>
+      <p className="mt-2 font-mono text-sm text-[var(--color-text-muted)]">
+        Mint under Auth → <strong className="text-[var(--color-text)]">AI</strong>, then{' '}
+        <code className="text-[var(--color-text)]">GET /v1/auth-core/ai/me</code> with{' '}
+        <code className="text-[var(--color-text)]">Bearer brai_…</code>.
+      </p>
+
+      <p className="mt-10 font-mono text-xs text-[var(--color-text-muted)]">
+        More: <a className="underline" href="/auth">auth overview</a> ·{' '}
+        <a className="underline" href="/auth/parity">SuperTokens parity walk</a>
+      </p>
+    </DocsShell>
+  );
+}

apps/docs/src/app/auth/parity/page.tsx

@@ -0,0 +1,78 @@
+import { DocsShell } from '../../../components/shell';
+
+export const metadata = { title: 'auth · SuperTokens parity walk' };
+
+type Row = { area: string; status: 'Y' | 'P' | 'N' | 'N/A'; note: string };
+
+const ROWS: Row[] = [
+  { area: 'Email password', status: 'Y', note: 'FDI signin/signup' },
+  { area: 'Passwordless email OTP / magic link', status: 'Y', note: 'Phase 3 live' },
+  { area: 'Passwordless SMS', status: 'P', note: 'UI ready; Twilio human prove' },
+  { area: 'Third-party social', status: 'Y', note: 'Full catalog when secrets set' },
+  { area: 'WebAuthn / passkeys', status: 'Y', note: 'Phase 5' },
+  { area: 'TOTP MFA', status: 'Y', note: 'Phase 5' },
+  { area: 'Session recipe', status: 'Y', note: 'Doltgres sessions' },
+  { area: 'User roles', status: 'Y', note: 'Phase 6' },
+  { area: 'Multitenancy (project→tenant)', status: 'Y', note: 'Path A map' },
+  { area: 'Enterprise SAML SSO (SP)', status: 'Y', note: 'briven-engine native' },
+  { area: 'Enterprise OIDC SSO (SP)', status: 'Y', note: 'briven-engine native' },
+  { area: 'OAuth2/OIDC provider (IdP)', status: 'Y', note: 'authorize/token/userinfo/… + live proof script' },
+  { area: 'M2M client credentials', status: 'Y', note: 'Keys → machine clients' },
+  { area: 'User migration / import', status: 'Y', note: 'plaintext + bcrypt/argon2 hash import' },
+  { area: 'Dashboard (operator)', status: 'Y', note: 'yellow Auth tabs' },
+  { area: 'Security audit trail', status: 'Y', note: 'Security diary' },
+  { area: 'Captcha', status: 'P', note: 'Turnstile when configured' },
+  { area: 'Branding', status: 'Y', note: 'logo/color/sender/footer + email HTML' },
+  { area: 'AI authentication', status: 'Y', note: 'AI agent tokens brai_…' },
+  { area: 'Framework integration pack', status: 'Y', note: 'docs/auth/frameworks' },
+  { area: 'SuperTokens Core Docker', status: 'N/A', note: 'Doltgres path; Core removed' },
+  { area: 'Full 492-URL line-by-line', status: 'P', note: 'covered by this parity matrix + plan; open rows above' },
+  { area: 'Claim 100% ST surface', status: 'P', note: 'SMS live prove still open' },
+];
+
+export default function AuthParityPage() {
+  return (
+    <DocsShell>
+      <h1 className="font-mono text-2xl tracking-tight">SuperTokens parity walk</h1>
+      <p className="mt-2 font-mono text-sm text-[var(--color-text-muted)]">
+        SuperTokens docs are a <strong className="text-[var(--color-text)]">checklist</strong>, not
+        a dependency. Status: <strong className="text-[var(--color-text)]">Y</strong> done ·{' '}
+        <strong className="text-[var(--color-text)]">P</strong> partial ·{' '}
+        <strong className="text-[var(--color-text)]">N</strong> not yet ·{' '}
+        <strong className="text-[var(--color-text)]">N/A</strong> won&apos;t do.
+      </p>
+
+      <div className="mt-8 overflow-x-auto">
+        <table className="w-full min-w-[32rem] border-collapse font-mono text-xs">
+          <thead>
+            <tr className="border-b border-[var(--color-border-subtle)] text-left text-[var(--color-text-muted)]">
+              <th className="py-2 pr-3 font-medium">Area</th>
+              <th className="py-2 pr-3 font-medium">Status</th>
+              <th className="py-2 font-medium">Notes</th>
+            </tr>
+          </thead>
+          <tbody>
+            {ROWS.map((r) => (
+              <tr
+                key={r.area}
+                className="border-b border-[var(--color-border-subtle)] text-[var(--color-text)]"
+              >
+                <td className="py-2 pr-3 align-top">{r.area}</td>
+                <td className="py-2 pr-3 align-top font-semibold">{r.status}</td>
+                <td className="py-2 align-top text-[var(--color-text-muted)]">{r.note}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      <p className="mt-8 font-mono text-xs text-[var(--color-text-muted)]">
+        Related:{' '}
+        <a className="underline" href="/auth/frameworks">
+          framework packs
+        </a>{' '}
+        · IdP proof script <code className="text-[var(--color-text)]">scripts/idp-live-proof.ts</code>
+      </p>
+    </DocsShell>
+  );
+}

apps/docs/src/app/changelog/entries.ts

@@ -293,8 +293,8 @@ export const CHANGELOG_ENTRIES: readonly ChangelogEntry[] = [
   {
     date: '2026-05-11',
     tags: ['infra'],
-    title: 'forgejo actions ci',
-    body: '.forgejo/workflows/ci.yml runs pnpm -r lint + typecheck + test on every push to main. real eslint config replaces 13 lint stubs; 15 packages green workspace-wide.',
+    title: 'git actions ci',
+    body: 'CI workflows run pnpm -r lint + typecheck + test on every push to main. real eslint config replaces 13 lint stubs; 15 packages green workspace-wide.',
   },
   {
     date: '2026-05-11',

apps/web/next.config.ts

@@ -35,7 +35,7 @@ const config: NextConfig = {
   async redirects() {
     // Stable curl-install URL: `curl -fsSL https://briven.tech/install | sh`
     // forwards to whichever install.sh is attached to the latest Codeberg
-    // release. Forgejo's /releases/latest/download/<asset> follows the
+    // release. Codeberg's /releases/latest/download/<asset> follows the
     // newest non-draft release tag.
     return [
       {

apps/web/public/konnos.svg

@@ -1,23 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 32 32">
-  <!-- Generator: Adobe Illustrator 30.4.0, SVG Export Plug-In . SVG Version: 2.1.4 Build 226)  -->
-  <defs>
-    <style>
-      .st0 {
-        fill: #ff3d7f;
-      }
-
-      .st1 {
-        fill: #fff;
-      }
-    </style>
-  </defs>
-  <path class="st1" d="M10.6,19.25c.01-1.3,0-1.48-.71-2.34l-.64-.77-.04-.05c-.3-.36-.44-.53-.5-.76-.06-.24-.08-.58-.08-1.24,0-.45-.02.36-.02-.26v-1.8c.13-.03.18-.09.24-.15.13-.12.21-.3.21-.49s-.07-.36-.2-.48c-.12-.12-.29-.2-.48-.2s-.36.08-.48.2c-.12.12-.2.3-.2.48s.07.36.19.49c.06.07.09.12.22.15v1.8c0,.8.01-.03.01.26,0,.71,0,1.07.08,1.37.09.34.26.54.61.96l.04.05.63.77c.59.72.62.87.61,2.01,0,.23.03.5.03.64v2.84c.16.13.32.26.49.39v-3.22c0-.34-.01-.5-.01-.63ZM8.02,11.4c0-.2.16-.36.36-.36s.36.16.36.36-.16.36-.36.36-.36-.16-.36-.36Z"/>
-  <path class="st1" d="M12.79,17.39l-.63-.77-.04-.05c-.3-.36-.44-.53-.5-.76-.06-.24-.06-.58-.06-1.24v-2.06c.13-.04.17-.09.23-.15.12-.12.2-.3.2-.48s-.08-.36-.2-.49c-.13-.12-.3-.2-.49-.2s-.36.08-.49.2c-.12.12-.2.3-.2.49s.08.36.21.48c.07.07.11.12.23.15v1.8c0,.8,0-.04,0,.26,0,.71,0,1.08.08,1.37.09.34.26.54.6.96l.04.05.63.77c.59.71.57.87.56,2,0,.23-.02.5-.02.64l.02,4.38c.17.11.33.21.5.31l-.02-4.69c0-.34.02-.5.03-.64.01-1.3.03-1.48-.68-2.34ZM10.94,11.88c0-.2.16-.36.36-.36s.36.16.36.36-.16.36-.36.36-.36-.16-.36-.36Z"/>
-  <path class="st1" d="M6.21,8.39h0c-.13-.13-.3-.2-.49-.2s-.36.08-.49.2c-.12.12-.2.3-.2.48s.09.36.21.49c.06.06.11.12.24.15v1.8c0,.62-.01-.2-.01.26,0,.66,0,1-.07,1.24-.06.23-.21.4-.51.76l-.04.05-.63.77c-.3.36-.48.61-.58.87.14.26.28.51.43.76.02-.55.12-.77.56-1.3l.63-.77.04-.05c.34-.42.51-.62.6-.96.08-.3.08-.66.08-1.37,0-.29,0,.54,0-.26v-1.8c.13-.03.16-.09.22-.15.13-.12.2-.3.2-.49s-.08-.36-.2-.48ZM5.73,9.24c-.2,0-.36-.16-.36-.36s.16-.36.36-.36.36.16.36.36-.16.36-.36.36Z"/>
-  <path class="st1" d="M25.24,11.23c-.39,0-.56-.03-.72-.03-1.47-.01-1.67-.03-2.64.77l-.87.71-.05.04c-.41.34-.6.5-.86.57-.27.07-.65.07-1.4.07h-2.33c-.04-.14-.1-.19-.17-.26-.14-.14-.34-.23-.55-.23s-.41.09-.55.23c-.14.14-.23.33-.23.55s.09.41.23.55c.14.14.34.23.55.23s.41-.09.55-.23c.07-.07.13-.12.17-.26h2.03c.9,0-.04,0,.29,0,.8,0,1.21,0,1.55-.09.38-.1.61-.29,1.08-.68l.05-.04.87-.71c.81-.67.98-.65,2.27-.63.27,0,.57.03.72.03l4.03-.03h0c.03-.14.05-.29.07-.43,0-.05.01-.09.02-.14l-4.11.03ZM15.66,14.06c-.23,0-.41-.18-.41-.41s.18-.41.41-.41.41.18.41.41-.18.41-.41.41Z"/>
-  <path class="st1" d="M25.45,14.45c-.37,0-.53.03-.68.02-1.39-.01-1.58,0-2.49.75l-.81.68-.05.05c-.38.32-.57.47-.81.54-.25.07-.62.08-1.32.08-.48,0,.39.02-.27.02h-1.92c-.04-.13-.09-.19-.16-.26-.13-.13-.31-.22-.52-.22s-.38.08-.52.21c-.13.13-.21.31-.21.51s.08.38.21.52c.13.13.32.21.52.21s.38-.07.52-.2c.07-.07.12-.1.16-.23h1.92c.85,0-.04-.01.27-.01.76,0,1.14,0,1.46-.09.36-.1.57-.28,1.02-.64l.05-.04.81-.67c.76-.63.92-.66,2.13-.65.25,0,.53-.03.68-.03l2.94.03s0,0,0,0c.06-.17.12-.35.18-.53l-3.12-.03ZM16.42,17.22c-.21,0-.39-.17-.39-.39s.17-.39.39-.39.39.17.39.39-.17.39-.39.39Z"/>
-  <path class="st1" d="M24.3,20.73l-.82-.67-.05-.04c-.44-.37-.66-.54-1.02-.64-.32-.09-.7-.09-1.46-.09-.31,0,.58,0-.27,0h-1.92c-.04-.13-.09-.17-.16-.24-.13-.13-.32-.21-.52-.21s-.38.08-.52.22c-.13.13-.21.32-.21.52s.08.38.21.52c.13.13.32.21.52.21s.38-.09.52-.23c.07-.07.12-.12.16-.26h1.92c.66,0-.21.01.27.01.7,0,1.07,0,1.32.07.24.07.43.22.81.54l.05.04.81.67c.42.35.69.54.99.65.12-.17.23-.35.34-.53-.33-.06-.57-.21-.99-.56ZM18.08,19.96c-.21,0-.39-.17-.39-.39s.17-.39.39-.39.39.17.39.39-.17.39-.39.39Z"/>
-  <path class="st1" d="M19.82,25.98v-2.13c.13-.04.17-.09.24-.16.13-.13.21-.31.21-.5s-.08-.37-.21-.5c-.13-.13-.31-.21-.5-.21s-.37.08-.5.21c-.13.13-.21.31-.21.5s.08.37.21.5c.07.07.11.12.24.16v1.87c0,.83,0-.04,0,.27,0,.74,0,1.11.08,1.42.07.26.18.44.38.7.13-.13.25-.25.38-.38-.13-.17-.21-.3-.25-.45-.07-.25-.07-.6-.07-1.28ZM19.55,23.57c-.21,0-.38-.17-.38-.38s.17-.38.38-.38.38.17.38.38-.17.38-.38.38Z"/>
-  <path class="st0" d="M30.28,16.51c-1.2,2.69-2.82,5.11-4.76,7.3-1.9,2.15-4.08,4.06-6.5,5.6-.1.06-.23.03-.29-.07-.06-.09-.04-.2.03-.27.34-.32.67-.64.99-.97.13-.13.25-.25.38-.38.53-.54,1.05-1.1,1.55-1.67,1.17-1.34,2.28-2.76,3.27-4.24.12-.17.23-.35.34-.53,1.27-1.98,2.34-4.07,3.11-6.28,0,0,0,0,0,0,.06-.17.12-.35.18-.53.08-.25.16-.5.23-.75.18-.63.34-1.29.46-1.96h0c.03-.14.05-.29.07-.43,0-.05.01-.09.02-.14.14-1.04.16-2.08-.08-3.06-.87-3.43-4.49-3.71-7.17-2.1-.36.21-.69.47-1.02.73-1.4,1.14-2.62,2.5-3.79,3.9-.28.35-.59.73-.87,1.08l-.08.1c-.12.15-.34.18-.49.06-.56-.79-1.1-1.59-1.71-2.32-1.11-1.34-2.39-2.5-3.9-3.35-1.32-.78-2.94-1.15-4.42-.68-1.05.33-2,1.03-2.64,1.93-.86,1.26-.97,2.91-.74,4.4.14.9.41,1.79.82,2.6.08.16.2.41.29.58.03.06.06.12.1.18.14.26.28.51.43.76.76,1.28,1.67,2.48,2.67,3.58,1.02,1.13,2.16,2.17,3.36,3.13.17.13.33.26.5.39.74.57,1.51,1.1,2.29,1.6.02.01.04.02.06.03.17.11.33.21.5.31.59.36,1.18.7,1.79,1.02.15.07.08.32-.1.28-1.35-.35-2.65-.89-3.9-1.51-4.23-2.1-7.98-5.42-10.14-9.67-1.38-2.81-1.7-6.59.28-9.2,1.45-1.89,3.86-3.02,6.25-2.75,1.82.18,3.42,1.13,4.77,2.31,1.59,1.37,2.8,3.15,3.67,5.05,1.08-2.32,2.72-4.83,4.76-6.4,2.46-1.86,6.19-2.33,8.7-.32,3.83,3.14,2.46,8.73.74,12.64Z"/>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 512 512">
+  <!-- Transparent background for OAuth button (no white plate) -->
+  <g>
+    <path d="M423.008,275.386l-147.524,147.623c-10.765,10.655-28.231,10.655-38.886,0l-147.524-147.623c-10.765-10.654-10.765-28.119,0-38.773l104.574-104.676,11.644-11.643,31.306-31.304c10.655-10.655,28.121-10.655,38.886,0l147.524,147.623c10.656,10.654,10.656,28.119,0,38.773Z" fill="#af2cf4"/>
+    <path d="M334.355,261.306c-8.807,8.807-23.145,8.807-31.952,0-6.774-6.774-8.355-16.935-4.629-25.177l-23.822-23.822c-6.21,2.145-13.323.903-18.403-3.726-5.758-5.081-7.452-12.983-5.081-19.758l-7.113-7.113v62.661c2.71,1.016,5.194,2.71,7.339,4.855,8.806,8.806,8.806,23.145,0,31.951-8.807,8.807-23.146,8.807-31.952,0-8.807-8.806-8.807-23.145,0-31.951,2.371-2.371,5.193-4.065,8.129-5.194v-67.742c0-5.984-2.145-12.307-6.21-17.275-.564-.677-1.242-1.355-1.806-2.145-.79-.677-1.355-1.355-2.145-1.919l-23.033-23.032,11.629-11.629,57.242,57.242c5.984-1.919,12.645-.564,17.613,3.839,5.419,4.855,7.113,12.306,5.081,18.855l24.274,24.274c8.242-3.5,18.177-1.807,24.839,4.855,8.806,8.806,8.806,23.145,0,31.951Z" fill="#fff"/>
+    <circle cx="256.459" cy="362.426" r="22.581" fill="#fff"/>
+  </g>
 </svg>

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/ai/page.tsx

@@ -0,0 +1,25 @@
+import { AuthAiAgentsClient } from '../../ai/ai-agents-client';
+
+export const metadata = { title: 'Auth · AI agents' };
+export const dynamic = 'force-dynamic';
+
+export default async function AuthProjectAiPage({
+  params,
+}: {
+  params: Promise<{ projectId: string }>;
+}) {
+  const { projectId } = await params;
+  return (
+    <section>
+      <header className="mb-6">
+        <h2 className="font-mono text-lg tracking-tight text-[var(--color-text)]">
+          AI agents
+        </h2>
+        <p className="mt-1 font-mono text-sm text-[var(--color-text-muted)]">
+          short-lived tokens so tools and agents can act for this project
+        </p>
+      </header>
+      <AuthAiAgentsClient projectId={projectId} />
+    </section>
+  );
+}

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/auth-project-nav.tsx

@@ -1,27 +1,60 @@
 'use client';
 
 import Link from 'next/link';
-import { usePathname } from 'next/navigation';
-
-const TABS: Array<{ href: string; label: string; exact?: boolean }> = [
-  { href: '', label: 'overview', exact: true },
-  { href: '/users', label: 'users' },
-  { href: '/sessions', label: 'sessions' },
-  { href: '/security', label: 'security' },
-  { href: '/keys', label: 'keys' },
-  { href: '/idp', label: 'IdP' },
-  { href: '/providers', label: 'providers' },
-  { href: '/branding', label: 'branding' },
-  { href: '/enterprise', label: 'enterprise' },
-];
+import { usePathname, useRouter } from 'next/navigation';
 
 /**
- * Tabs for one Auth project — same pattern as project tabs.
- * Selected tab = brighter text only (no thick accent underline).
+ * Tabs for one Auth project — same pattern as project-tabs:
+ * clean set by default; advanced tools behind “developer mode”.
  */
-export function AuthProjectNav({ projectId }: { projectId: string }) {
+const TABS = [
+  { href: '', label: 'overview', exact: true, dev: false },
+  { href: '/users', label: 'users', dev: false },
+  { href: '/sessions', label: 'sessions', dev: false },
+  { href: '/security', label: 'security', dev: false },
+  { href: '/keys', label: 'keys', dev: false },
+  { href: '/providers', label: 'providers', dev: false },
+  { href: '/branding', label: 'branding', dev: false },
+  // Advanced / later tools
+  { href: '/idp', label: 'IdP', dev: true },
+  { href: '/migration', label: 'import', dev: true },
+  { href: '/ai', label: 'AI', dev: true },
+  { href: '/enterprise', label: 'enterprise', dev: true },
+] as const;
+
+const AUTH_ACCENT = '#FFFD74';
+const COOKIE = 'briven_auth_project_dev';
+
+export function AuthProjectNav({
+  projectId,
+  developerMode,
+}: {
+  projectId: string;
+  developerMode: boolean;
+}) {
   const pathname = usePathname();
+  const router = useRouter();
   const base = `/dashboard/auth/${projectId}`;
+  const visible = TABS.filter((tab) => developerMode || !tab.dev);
+
+  // If user lands on a hidden dev tab while mode is off, still show that tab
+  // so they aren’t stranded.
+  const forceShow = TABS.filter(
+    (tab) =>
+      tab.dev &&
+      !visible.includes(tab) &&
+      (pathname === `${base}${tab.href}` ||
+        pathname.startsWith(`${base}${tab.href}/`)),
+  );
+  const tabs = [...visible, ...forceShow];
+
+  function toggleDev() {
+    const on = document.cookie
+      .split('; ')
+      .some((c) => c === `${COOKIE}=1`);
+    document.cookie = `${COOKIE}=${on ? '0' : '1'}; path=/; max-age=31536000; samesite=lax`;
+    router.refresh();
+  }
 
   return (
     <div className="flex items-center gap-2 border-b border-[var(--color-border-subtle)]">
@@ -29,12 +62,12 @@ export function AuthProjectNav({ projectId }: { projectId: string }) {
         aria-label="Auth project sections"
         className="flex flex-1 gap-1 overflow-x-auto [-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
       >
-        {TABS.map((tab) => {
+        {tabs.map((tab) => {
           const href = `${base}${tab.href}`;
-          const active =
-            tab.exact === true
-              ? pathname === base || pathname === `${base}/`
-              : pathname === href || pathname.startsWith(`${href}/`);
+          const exact = 'exact' in tab && tab.exact === true;
+          const active = exact
+            ? pathname === base || pathname === `${base}/`
+            : pathname === href || pathname.startsWith(`${href}/`);
           return (
             <Link
               key={tab.href || 'overview'}
@@ -50,12 +83,37 @@ export function AuthProjectNav({ projectId }: { projectId: string }) {
           );
         })}
       </nav>
-      <Link
-        href="/dashboard/auth"
-        className="shrink-0 whitespace-nowrap px-2 py-1 font-mono text-[11px] text-[var(--color-text-muted)] hover:text-[var(--color-text)]"
+      <button
+        type="button"
+        onClick={toggleDev}
+        title={
+          developerMode
+            ? 'Hide advanced Auth tools'
+            : 'Show advanced tools (IdP, import, AI, enterprise…)'
+        }
+        className="flex shrink-0 items-center gap-1 whitespace-nowrap rounded-md px-2.5 py-1 font-mono text-xs transition"
+        style={
+          developerMode
+            ? { background: AUTH_ACCENT, color: '#111' }
+            : {
+                color: `color-mix(in srgb, ${AUTH_ACCENT} 65%, transparent)`,
+              }
+        }
       >
-        ← all Auth
-      </Link>
+        <svg
+          aria-hidden
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className="size-3.5"
+        >
+          <path d="M7 17 17 7M7 7h10v10" />
+        </svg>
+        developer mode
+      </button>
     </div>
   );
 }

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/layout.tsx

@@ -1,5 +1,6 @@
 import Link from 'next/link';
 import type { ReactNode } from 'react';
+import { cookies } from 'next/headers';
 import { notFound } from 'next/navigation';
 
 import { loadAuthV2Workspace } from '../lib/load-workspace';
@@ -8,7 +9,11 @@ import { AuthProjectNav } from './auth-project-nav';
 export const dynamic = 'force-dynamic';
 
 /**
- * Per-project Auth shell: title + tabs (users, sessions, keys, …).
+ * Per-project Auth shell — same header + tabs pattern as Projects:
+ *   ← Auth
+ *   {name}
+ *   {slug} · Auth on|off
+ *   [tabs…]                    [↗ developer mode]
  */
 export default async function AuthProjectLayout({
   children,
@@ -18,6 +23,8 @@ export default async function AuthProjectLayout({
   params: Promise<{ projectId: string }>;
 }) {
   const { projectId } = await params;
+  const developerMode =
+    (await cookies()).get('briven_auth_project_dev')?.value === '1';
   const projects = await loadAuthV2Workspace();
   const project = projects.find(
     (p) => p.id === projectId || p.id.toLowerCase() === projectId.toLowerCase(),
@@ -32,39 +39,27 @@ export default async function AuthProjectLayout({
   return (
     <div className="flex flex-col gap-6">
       <header>
-        <p className="font-mono text-[10px] uppercase tracking-widest text-[var(--color-text-muted)]">
-          <Link href="/dashboard/auth" className="hover:underline">
-            Auth
-          </Link>
-          {' · '}
-          project
-        </p>
-        <h1 className="mt-1 font-mono text-xl tracking-tight text-[var(--color-text)]">
+        <Link
+          href="/dashboard/auth"
+          className="font-mono text-xs text-[var(--color-text-subtle)] hover:text-[var(--color-text-muted)]"
+        >
+          ← Auth
+        </Link>
+        <h1 className="mt-2 font-mono text-xl tracking-tight text-[var(--color-text)]">
           {project.name}
         </h1>
         <p className="mt-1 font-mono text-sm text-[var(--color-text-muted)]">
           {project.slug}
+          {' · '}
           {authOn ? (
-            <span style={{ color: 'var(--auth-accent, #FFFD74)' }}>
-              {' · '}
-              Auth on
-            </span>
+            <span style={{ color: 'var(--auth-accent, #FFFD74)' }}>Auth on</span>
           ) : (
-            <span>
-              {' · '}
-              Auth off
-            </span>
+            <span>Auth off</span>
           )}
-          {project.tenantId ? (
-            <span className="text-[var(--color-text-subtle)]">
-              {' · '}
-              {project.tenantId}
-            </span>
-          ) : null}
         </p>
       </header>
-      <AuthProjectNav projectId={project.id} />
-      {children}
+      <AuthProjectNav projectId={project.id} developerMode={developerMode} />
+      <section>{children}</section>
     </div>
   );
 }

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/migration/page.tsx

@@ -0,0 +1,25 @@
+import { AuthMigrationClient } from '../../migration/migration-client';
+
+export const metadata = { title: 'Auth · import users' };
+export const dynamic = 'force-dynamic';
+
+export default async function AuthProjectMigrationPage({
+  params,
+}: {
+  params: Promise<{ projectId: string }>;
+}) {
+  const { projectId } = await params;
+  return (
+    <section>
+      <header className="mb-6">
+        <h2 className="font-mono text-lg tracking-tight text-[var(--color-text)]">
+          import users
+        </h2>
+        <p className="mt-1 font-mono text-sm text-[var(--color-text-muted)]">
+          move people from SuperTokens, Clerk, or another auth into this project
+        </p>
+      </header>
+      <AuthMigrationClient projectId={projectId} />
+    </section>
+  );
+}

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/page.tsx

@@ -4,12 +4,13 @@ import { notFound } from 'next/navigation';
 import { apiFetch } from '@/lib/api';
 import { fetchAuthDashboard } from '../lib/auth-api';
 import { loadAuthV2Workspace } from '../lib/load-workspace';
+import { AuthSetupChecklist } from './setup-checklist';
 
 export const dynamic = 'force-dynamic';
 
 /**
- * One project's Auth overview — counts + shortcuts.
- * Sign-in methods are managed under Providers.
+ * One project's Auth overview — golden-path setup when incomplete,
+ * then counts + shortcuts.
  */
 export default async function AuthProjectOverviewPage({
   params,
@@ -84,7 +85,8 @@ export default async function AuthProjectOverviewPage({
     }
   }
 
-  const authOn = project.authEnabled === true || tenantRowOn;
+  // tenantRowOn used for light diagnostics in “this project” card below.
+  void tenantRowOn;
 
   const counts = dash.ok
     ? dash.data.counts
@@ -92,19 +94,8 @@ export default async function AuthProjectOverviewPage({
 
   return (
     <section className="space-y-6">
-      {!authOn ? (
-        <div className="rounded-md border border-dashed border-[var(--color-border)] p-6 font-mono text-sm text-[var(--color-text-muted)]">
-          Auth is off for this project. Go back to{' '}
-          <Link
-            href="/dashboard/auth"
-            className="underline"
-            style={{ color: 'var(--auth-accent, #FFFD74)' }}
-          >
-            Auth home
-          </Link>{' '}
-          and enable it.
-        </div>
-      ) : null}
+      {/* Golden path — shown until setup is green (client also collapses). */}
+      <AuthSetupChecklist projectId={id} />
 
       <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
         {[

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/security/advanced-auth-settings.tsx

@@ -0,0 +1,147 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * Product settings: custom JWT claims + username login (SuperTokens-class depth).
+ */
+export function AdvancedAuthSettings({ projectId }: { projectId: string }) {
+  const [claimsJson, setClaimsJson] = useState('{\n  "tenant_plan": "pro"\n}');
+  const [usernameLogin, setUsernameLogin] = useState(false);
+  const [pending, setPending] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+  const [ok, setOk] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    setErr(null);
+    const res = await fetch(
+      `/api/v1/auth-core/projects/${encodeURIComponent(projectId)}/config`,
+      { credentials: 'include', cache: 'no-store' },
+    );
+    if (!res.ok) return;
+    const body = (await res.json()) as {
+      jwtClaims?: Record<string, string | number | boolean>;
+      usernameLogin?: boolean;
+    };
+    if (body.jwtClaims && Object.keys(body.jwtClaims).length > 0) {
+      setClaimsJson(JSON.stringify(body.jwtClaims, null, 2));
+    }
+    setUsernameLogin(Boolean(body.usernameLogin));
+  }, [projectId]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  async function saveClaims(): Promise<void> {
+    setPending(true);
+    setErr(null);
+    setOk(null);
+    try {
+      const claims = JSON.parse(claimsJson) as Record<string, string | number | boolean>;
+      const res = await fetch(
+        `/api/v1/auth-core/projects/${encodeURIComponent(projectId)}/jwt-claims`,
+        {
+          method: 'PUT',
+          credentials: 'include',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(claims),
+        },
+      );
+      if (!res.ok) {
+        const b = (await res.json().catch(() => ({}))) as { message?: string };
+        throw new Error(b.message ?? `save failed (${res.status})`);
+      }
+      setOk('JWT claim template saved — applied on new ID tokens');
+      await load();
+    } catch (e) {
+      setErr(e instanceof Error ? e.message : 'save failed');
+    } finally {
+      setPending(false);
+    }
+  }
+
+  async function saveUsername(enabled: boolean): Promise<void> {
+    setPending(true);
+    setErr(null);
+    setOk(null);
+    try {
+      const res = await fetch(
+        `/api/v1/auth-core/projects/${encodeURIComponent(projectId)}/username-login`,
+        {
+          method: 'PUT',
+          credentials: 'include',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ enabled }),
+        },
+      );
+      if (!res.ok) {
+        const b = (await res.json().catch(() => ({}))) as { message?: string };
+        throw new Error(b.message ?? `save failed (${res.status})`);
+      }
+      setUsernameLogin(enabled);
+      setOk(
+        enabled
+          ? 'username login on — users can sign in with metadata.username'
+          : 'username login off — email only',
+      );
+    } catch (e) {
+      setErr(e instanceof Error ? e.message : 'save failed');
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <div className="space-y-6">
+      <div>
+        <h3 className="font-mono text-sm text-[var(--color-text)]">
+          custom JWT claims
+        </h3>
+        <p className="mt-1 font-mono text-[11px] text-[var(--color-text-muted)]">
+          Extra fields merged into OIDC ID tokens for this project (string / number /
+          boolean only). Reserved claims like sub / iss are ignored.
+        </p>
+        <textarea
+          value={claimsJson}
+          onChange={(e) => setClaimsJson(e.target.value)}
+          rows={6}
+          spellCheck={false}
+          className="mt-3 w-full max-w-lg rounded-md border bg-[var(--color-surface)] px-3 py-2 font-mono text-[11px] text-[var(--color-text)]"
+          style={{ borderColor: 'var(--color-border)' }}
+        />
+        <button
+          type="button"
+          disabled={pending}
+          onClick={() => void saveClaims()}
+          className="mt-2 rounded-md px-3 py-1.5 font-mono text-xs font-medium text-black disabled:opacity-50"
+          style={{ background: '#FFFD74' }}
+        >
+          {pending ? 'saving…' : 'save JWT claims'}
+        </button>
+      </div>
+
+      <div>
+        <h3 className="font-mono text-sm text-[var(--color-text)]">username login</h3>
+        <p className="mt-1 font-mono text-[11px] text-[var(--color-text-muted)]">
+          When on, email + password sign-in also accepts a username stored on the user
+          (metadata.username).
+        </p>
+        <label className="mt-3 flex items-center gap-2 font-mono text-xs text-[var(--color-text)]">
+          <input
+            type="checkbox"
+            checked={usernameLogin}
+            disabled={pending}
+            onChange={(e) => void saveUsername(e.target.checked)}
+          />
+          allow username as login id
+        </label>
+      </div>
+
+      {ok ? (
+        <p className="font-mono text-xs text-[var(--color-text)]">{ok}</p>
+      ) : null}
+      {err ? <p className="font-mono text-xs text-red-400">{err}</p> : null}
+    </div>
+  );
+}

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/security/page.tsx

@@ -3,6 +3,7 @@ import Link from 'next/link';
 import { apiFetch } from '@/lib/api';
 import { AuthAuditTrailClient } from '../../security/audit-trail-client';
 import { AuthRolesForm } from '../../security/roles-form';
+import { AdvancedAuthSettings } from './advanced-auth-settings';
 
 export const metadata = { title: 'Auth · security' };
 export const dynamic = 'force-dynamic';
@@ -125,6 +126,10 @@ export default async function AuthProjectSecurityPage({
         <AuthAuditTrailClient projectId={projectId} />
       </div>
 
+      <div className="rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-surface)] p-6">
+        <AdvancedAuthSettings projectId={projectId} />
+      </div>
+
       <div className="rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-surface)] p-6">
         <h3 className="font-mono text-sm text-[var(--color-text)]">
           login methods

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/setup-checklist.tsx

@@ -0,0 +1,278 @@
+'use client';
+
+import Link from 'next/link';
+import { useCallback, useEffect, useState } from 'react';
+
+type SetupStep = {
+  id: string;
+  label: string;
+  ok: boolean;
+  detail: string;
+  href?: string;
+};
+
+type SetupStatus = {
+  complete: boolean;
+  steps: SetupStep[];
+  appOrigins: string[];
+  activeKeyCount: number;
+  apiOrigin: string;
+  proxySnippet: string;
+};
+
+export function AuthSetupChecklist({ projectId }: { projectId: string }) {
+  const [status, setStatus] = useState<SetupStatus | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+  const [mintedKey, setMintedKey] = useState<string | null>(null);
+  const [productionOrigin, setProductionOrigin] = useState('https://');
+  const [copied, setCopied] = useState(false);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setErr(null);
+    try {
+      const res = await fetch(
+        `/api/dashboard/auth-core/projects/${encodeURIComponent(projectId)}/setup-status`,
+        { credentials: 'include' },
+      );
+      if (!res.ok) {
+        const body = (await res.json().catch(() => ({}))) as {
+          message?: string;
+        };
+        throw new Error(body.message ?? `load failed (${res.status})`);
+      }
+      const body = (await res.json()) as SetupStatus;
+      setStatus(body);
+    } catch (e) {
+      setErr(e instanceof Error ? e.message : 'could not load setup status');
+      setStatus(null);
+    } finally {
+      setLoading(false);
+    }
+  }, [projectId]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  async function finish(): Promise<void> {
+    setBusy(true);
+    setErr(null);
+    setNote(null);
+    setMintedKey(null);
+    try {
+      const origin =
+        productionOrigin.trim() &&
+        productionOrigin.trim() !== 'https://' &&
+        productionOrigin.trim() !== 'http://'
+          ? productionOrigin.trim()
+          : undefined;
+      const res = await fetch(
+        `/api/dashboard/auth-core/projects/${encodeURIComponent(projectId)}/setup-finish`,
+        {
+          method: 'POST',
+          credentials: 'include',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(
+            origin ? { productionOrigin: origin } : {},
+          ),
+        },
+      );
+      const body = (await res.json().catch(() => ({}))) as {
+        message?: string;
+        code?: string;
+        actions?: string[];
+        mintedKeyPlaintext?: string | null;
+        status?: SetupStatus;
+      };
+      if (!res.ok) {
+        throw new Error(body.message ?? body.code ?? `failed (${res.status})`);
+      }
+      if (body.status) setStatus(body.status);
+      if (body.mintedKeyPlaintext) setMintedKey(body.mintedKeyPlaintext);
+      setNote(
+        body.actions?.length
+          ? body.actions.join(' · ')
+          : 'setup finished',
+      );
+      await load();
+    } catch (e) {
+      setErr(e instanceof Error ? e.message : 'finish setup failed');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function copyKey(): Promise<void> {
+    if (!mintedKey) return;
+    try {
+      await navigator.clipboard.writeText(mintedKey);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      setErr('could not copy — select the key and copy manually');
+    }
+  }
+
+  if (loading && !status) {
+    return (
+      <div className="rounded-md border border-[var(--color-border-subtle)] p-6 font-mono text-xs text-[var(--color-text-muted)]">
+        checking Auth setup…
+      </div>
+    );
+  }
+
+  if (!status) {
+    return err ? (
+      <p className="font-mono text-xs text-red-400">{err}</p>
+    ) : null;
+  }
+
+  // When complete, hide the big checklist (overview shows normal stats).
+  if (status.complete && !mintedKey) {
+    return (
+      <div
+        className="rounded-md border px-4 py-3 font-mono text-xs text-[var(--color-text-muted)]"
+        style={{ borderColor: 'color-mix(in srgb, #FFFD74 35%, transparent)' }}
+      >
+        <span style={{ color: 'var(--auth-accent, #FFFD74)' }}>✓</span> Auth
+        setup complete for this project
+        {status.appOrigins.length
+          ? ` · ${status.appOrigins.join(', ')}`
+          : ''}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="rounded-md border p-5"
+      style={{
+        borderColor: 'color-mix(in srgb, #FFFD74 40%, transparent)',
+        background: 'color-mix(in srgb, #FFFD74 4%, transparent)',
+      }}
+    >
+      <h2 className="font-mono text-sm text-[var(--color-text)]">
+        get Auth ready
+      </h2>
+      <p className="mt-1 font-mono text-[11px] text-[var(--color-text-muted)]">
+        one path for apps like Konnos / Mavi — finish these steps so login
+        works the first time
+      </p>
+
+      <ul className="mt-4 flex flex-col gap-2">
+        {status.steps.map((step) => (
+          <li
+            key={step.id}
+            className="flex items-start gap-3 rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-surface)] px-3 py-2 font-mono text-xs"
+          >
+            <span
+              className="mt-0.5 shrink-0"
+              style={{
+                color: step.ok
+                  ? 'var(--auth-accent, #FFFD74)'
+                  : 'var(--color-text-muted)',
+              }}
+              aria-hidden
+            >
+              {step.ok ? '✓' : '○'}
+            </span>
+            <span className="min-w-0 flex-1">
+              <span className="text-[var(--color-text)]">{step.label}</span>
+              <span className="mt-0.5 block text-[10px] text-[var(--color-text-muted)]">
+                {step.detail}
+              </span>
+              {step.href && !step.ok ? (
+                <Link
+                  href={step.href}
+                  className="mt-1 inline-block text-[10px] underline"
+                  style={{ color: 'var(--auth-accent, #FFFD74)' }}
+                >
+                  open →
+                </Link>
+              ) : null}
+            </span>
+          </li>
+        ))}
+      </ul>
+
+      <label className="mt-4 flex flex-col gap-1 font-mono text-xs">
+        <span className="text-[var(--color-text-muted)]">
+          live app URL (optional — also seeds localhost for local dev)
+        </span>
+        <input
+          value={productionOrigin}
+          onChange={(e) => setProductionOrigin(e.target.value)}
+          placeholder="https://pay.yourapp.com"
+          className="rounded-md border bg-[var(--color-surface)] px-3 py-2"
+          style={{ borderColor: 'var(--auth-accent-border, #333)' }}
+        />
+      </label>
+
+      <button
+        type="button"
+        disabled={busy}
+        onClick={() => void finish()}
+        className="mt-4 rounded-md px-4 py-2.5 font-mono text-xs font-medium text-black disabled:opacity-50"
+        style={{ background: '#FFFD74' }}
+      >
+        {busy ? 'finishing…' : 'Finish setup'}
+      </button>
+      <p className="mt-2 font-mono text-[10px] text-[var(--color-text-muted)]">
+        turns Auth on · core methods · localhost origin · mints a browser key
+        if you don’t have one
+      </p>
+
+      {mintedKey ? (
+        <div className="mt-4 rounded-md border border-[var(--color-border)] bg-[var(--color-surface)] p-3">
+          <p className="font-mono text-[10px] uppercase tracking-widest text-[var(--color-text-muted)]">
+            browser key — copy now (shown once)
+          </p>
+          <code className="mt-2 block break-all font-mono text-[11px] text-[var(--color-text)]">
+            {mintedKey}
+          </code>
+          <button
+            type="button"
+            onClick={() => void copyKey()}
+            className="mt-2 font-mono text-[10px] underline"
+            style={{ color: 'var(--auth-accent, #FFFD74)' }}
+          >
+            {copied ? 'copied' : 'copy key'}
+          </button>
+          <p className="mt-2 font-mono text-[10px] text-[var(--color-text-muted)]">
+            put in app env as{' '}
+            <code className="text-[var(--color-text)]">
+              NEXT_PUBLIC_BRIVEN_AUTH_KEY
+            </code>
+          </p>
+        </div>
+      ) : null}
+
+      {!status.steps.find((s) => s.id === 'proxy')?.ok ? (
+        <div className="mt-4 rounded-md border border-dashed border-[var(--color-border)] p-3">
+          <p className="font-mono text-[10px] text-[var(--color-text-muted)]">
+            proxy snippet (your app, not Briven)
+          </p>
+          <pre className="mt-2 max-h-40 overflow-auto whitespace-pre-wrap font-mono text-[10px] text-[var(--color-text)]">
+            {status.proxySnippet}
+          </pre>
+        </div>
+      ) : null}
+
+      {note ? (
+        <p
+          className="mt-3 font-mono text-xs"
+          style={{ color: 'var(--auth-accent, #FFFD74)' }}
+        >
+          {note}
+        </p>
+      ) : null}
+      {err ? (
+        <p className="mt-3 font-mono text-xs text-red-400">{err}</p>
+      ) : null}
+    </div>
+  );
+}

apps/web/src/app/(dashboard)/dashboard/auth/[projectId]/users/[userId]/page.tsx

@@ -0,0 +1,28 @@
+import { notFound } from 'next/navigation';
+
+import { fetchAuthUserDetail } from '../../../lib/auth-api';
+import { UserManageClient } from './user-manage-client';
+
+export const metadata = { title: 'Auth · user' };
+export const dynamic = 'force-dynamic';
+
+export default async function AuthUserDetailPage({
+  params,
+}: {
+  params: Promise<{ projectId: string; userId: string }>;
+}) {
+  const { projectId, userId } = await params;
+  const result = await fetchAuthUserDetail(userId, projectId);
+  if (!result.ok) {
+    if (result.status === 404) notFound();
+    return (
+      <section className="font-mono text-sm text-[var(--color-text-muted)]">
+        {result.message || 'could not load user'}
+      </section>
+    );
+  }
+
+  return (
+    <UserManageClient projectId={projectId} initialUser={result.user} />
+  );
+}