feat(run402): adopt @run402/functions v3 auth.* namespace in functions/

v3.0.0 ships throwing-sentinel getUser/getUserId/getRole — every existing
caller would crash with R402_AUTH_UNKNOWN_EXPORT at runtime. Replace each
`await getUser(req)` with `await auth.user()` across the 7 functions that
consult the actor; drop the defensive try/catch (auth.user() returns
Actor | null and never throws on anon). Test mocks of @run402/functions
get a parallel `auth.user` entry so the new code path is intercepted.

Scope intentionally limited to the v3 break: client-side localStorage →
HttpOnly cookie work (src/lib/auth.ts, src/lib/api.ts, six wl_session
readers in components) and SSR auth guards on admin pages remain
deferred until @run402/astro v2.0 ships and we get explicit go-ahead to
drop the Bearer-token flow.

Annotated the 4 adminDb() .eq('user_id', user.id) lookups with
`run402-allow-user-filter: …` so future doctor source-scans don't flag
them — they bypass RLS by design (actor bootstrap, role lookup pre-auth).

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

Author: MajorTal

functions/export-csv.js

@@ -1,8 +1,8 @@
 // schedule: none (triggered manually from admin UI)
-import { adminDb, getUser } from '@run402/functions';
+import { adminDb, auth } from '@run402/functions';
 
 export default async (req) => {
-  const user = await getUser(req);
+  const user = await auth.user();
   if (!user) {
     return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
   }

functions/kychon-api.js

@@ -1,5 +1,5 @@
 // schedule: none (canonical Kychon Capability API gateway at POST /functions/v1/kychon-api)
-import { adminDb, getUser } from '@run402/functions';
+import { adminDb, auth } from '@run402/functions';
 
 const API_VERSION = '2026-05-08';
 const SUPPORTED_API_VERSIONS = [API_VERSION];
@@ -2271,13 +2271,11 @@ function objectRefJson(ref) {
   };
 }
 
-async function resolveActor(req) {
-  let user = null;
-  try {
-    user = await getUser(req);
-  } catch {
-    user = null;
-  }
+async function resolveActor(_req) {
+  // auth.user() returns Actor | null and never throws on anon — drop the try/catch.
+  // The platform-verified actor envelope is the only trusted source; legacy
+  // Bearer-header path is forwarded by the gateway into the same ALS context.
+  const user = await auth.user();
   if (!user?.id) return { state: 'anonymous', authenticated: false, user: null, member: null, authority: {} };
 
   const projectAdmin = isProjectAdmin(user);
@@ -2297,6 +2295,7 @@ async function resolveActor(req) {
 
 async function findMember(user) {
   const db = adminDb();
+  // run402-allow-user-filter: adminDb() bypasses RLS to bootstrap actor → member mapping
   const byUserId = await db
     .from('members')
     .select('id,user_id,email,display_name,role,status')

functions/on-signup.js

@@ -1,6 +1,6 @@
 // Lifecycle hook: called automatically by Run402 after first signup (fire-and-forget).
 // Also supports direct invocation with auth token for backward compatibility.
-import { adminDb, getUser } from '@run402/functions';
+import { adminDb, auth } from '@run402/functions';
 
 export default async (req) => {
   // Determine user identity from lifecycle hook payload or auth token
@@ -17,8 +17,11 @@ export default async (req) => {
       return new Response(JSON.stringify({ error: 'Missing user.id in hook payload' }), { status: 400 });
     }
   } else {
-    // Direct invocation: use auth token
-    const user = await getUser(req);
+    // Direct invocation: read actor from the platform's verified envelope.
+    // Returns null for anonymous; we preserve the legacy `{ error: 'Unauthorized' }`
+    // response shape rather than letting auth.requireUser() throw, because the
+    // platform's 401 envelope shape differs and BC callers parse this body.
+    const user = await auth.user();
     if (!user) {
       return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
     }

functions/site-search.js

@@ -1,5 +1,5 @@
 // schedule: none (native site search endpoint)
-import { adminDb, getUser } from '@run402/functions';
+import { adminDb, auth } from '@run402/functions';
 
 const SEARCH_TYPES = new Set(['all', 'pages', 'resources', 'events']);
 const TYPE_TO_SOURCE = { pages: 'page', resources: 'resource', events: 'event' };
@@ -71,14 +71,11 @@ function emptyResponse(query, type, page, pageSize) {
   };
 }
 
-async function isActiveMember(req) {
-  let user = null;
-  try {
-    user = await getUser(req);
-  } catch {
-    user = null;
-  }
+async function isActiveMember(_req) {
+  // auth.user() returns Actor | null and never throws — no try/catch needed.
+  const user = await auth.user();
   if (!user?.id) return false;
+  // run402-allow-user-filter: adminDb() bypasses RLS to look up member by raw user.id
   const rows = await adminDb().from('members').select('id,status,role').eq('user_id', user.id).limit(1);
   const member = rows?.[0];
   return member?.status === 'active' && ['member', 'moderator', 'admin'].includes(member.role);

functions/translate-content.js

@@ -1,8 +1,8 @@
 // schedule: none (triggered by client after content publish)
-import { adminDb, ai, getUser } from '@run402/functions';
+import { adminDb, ai, auth } from '@run402/functions';
 
 export default async (req) => {
-  const user = await getUser(req);
+  const user = await auth.user();
   if (!user) {
     return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
   }

functions/upload-asset.js

@@ -4,7 +4,7 @@
 // dimensions, blurhash, variants, exif policy) via `internal.blobs.metadata`
 // + intrinsic image columns — Kychon no longer keeps a shadow `media_assets`
 // table. See `openspec/changes/admin-content-management/design.md` Decision 3.
-import { adminDb, assets, getUser } from '@run402/functions';
+import { adminDb, assets, auth } from '@run402/functions';
 
 // Aspect-ratio heuristic for the brand_icon_url upload target. Per
 // brand-identity-fields/design.md §3, when an icon upload's intrinsic width
@@ -39,7 +39,7 @@ const STORAGE_PREFIX = 'assets/';
 const MEDIA_LIST_LIMIT = 40;
 
 export default async (req) => {
-  const user = await getUser(req);
+  const user = await auth.user();
   if (!user) {
     return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
   }
@@ -48,11 +48,10 @@ export default async (req) => {
   // safe today because Run402 issues UUIDs, but a future auth path that
   // produces a different `sub` shape could turn this into SQL injection. (#25)
   //
-  // TODO(verify): Run402 v2.9.0 ships declarative function-level role gates
-  // (requireAuth + requireRole). When the existing per-function role checks
-  // are swept (see `migrate-to-declarative-role-gates` follow-up change), this
-  // block is replaced by `ctx.user` + `ctx.role` populated by the gateway.
-  // Left as-is for this change per the agreed scope.
+  // TODO(auth-aware-ssr): once @run402/astro v2 ships and we drop bearer-token
+  // auth, swap to `await auth.requireRole('admin')` and let the platform's
+  // R402_AUTH_INSUFFICIENT_ROLE bubble up as the 403.
+  // run402-allow-user-filter: adminDb() raw SQL bypasses RLS; user.id binding required
   const memberResult = await adminDb().sql('SELECT role FROM members WHERE user_id = $1 LIMIT 1', [user.id]);
   if (!memberResult.rows?.length || memberResult.rows[0].role !== 'admin') {
     return new Response(JSON.stringify({ error: 'Admin access required' }), { status: 403 });

functions/upload-resource.js

@@ -1,5 +1,5 @@
 // schedule: none (triggered by client on resource upload)
-import { adminDb, assets, getUser } from '@run402/functions';
+import { adminDb, assets, auth } from '@run402/functions';
 
 // File names that flow into the storage path must be limited to safe ASCII
 // segments — `..`, `/`, NUL, and other surprises would let a caller place
@@ -12,14 +12,15 @@ function pickAssetUrl(ref, fallbackKey) {
 }
 
 export default async (req) => {
-  const user = await getUser(req);
+  const user = await auth.user();
   if (!user) {
     return new Response(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
   }
 
   // Admin-only — mirror the role check in upload-asset.js. The legacy "any
   // authenticated user can upload" surface let arbitrary signed-in Run402
   // users write to the project's resources bucket. (#25)
+  // run402-allow-user-filter: adminDb() raw SQL bypasses RLS; user.id binding required
   const memberResult = await adminDb().sql('SELECT role FROM members WHERE user_id = $1 LIMIT 1', [user.id]);
   const role = memberResult?.rows?.[0]?.role;
   if (role !== 'admin') {

package-lock.json

@@ -64,7 +64,7 @@
     "@radix-ui/react-slot": "1.2.4",
     "@radix-ui/react-tooltip": "1.2.8",
     "@run402/astro": "^1.2.2",
-    "@run402/functions": "^2.7.0",
+    "@run402/functions": "^3.0.0",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "lucide-react": "1.14.0",

package.json

@@ -93,6 +93,7 @@ vi.mock(
   '@run402/functions',
   () => ({
     getUser: vi.fn(async () => mockState.user),
+    auth: { user: vi.fn(async () => mockState.user) },
     adminDb: () => ({
       sql(query: string, params: unknown[] = []) {
         return mockSql(query, params);