┌──────────────────────────────────────────────────────────────────┐
│                      Feed (Next.js)                            │
│                                                                    │
│  StewardAuthProvider (StewardAuth SDK v0.5.0 from npm)            │
│    ↓ getToken()  ↓ signInWithEmail()  ↓ signInWithPasskey()       │
│  useAuth hook  →  LoginModal  →  auth callbacks                   │
│                                                                    │
│  POST /api/auth/session  →  sets steward-token httpOnly cookie     │
│    (token received via POST body, NOT URL param — see §6 step 10) │
│                                                                    │
│  POST /api/auth/farcaster       → SIWF verify → provision user    │
│  POST /api/auth/farcaster-miniapp → quickAuth verify → same       │
│  POST /api/auth/telegram-miniapp  → HMAC verify → same            │
│                                                                    │
│  auth-middleware  →  jwtVerify(STEWARD_JWT_SECRET, issuer:'steward')│
│    WHERE stewardId = payload.userId    (Steward UUID)             │
│    OR email bridge → set stewardId                                │
│    OR social bridge (fid/telegramId) → set stewardId              │
└────────────────────────────┬─────────────────────────────────────┘
                             │ HTTP to port 3200
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│                   Steward API (:3200)                              │
│                                                                    │
│  POST /auth/email/send      POST /auth/email/verify               │
│  POST /auth/passkey/login/* POST /auth/passkey/register/*         │
│  GET  /auth/oauth/google/*  GET  /auth/oauth/discord/*            │
│  GET  /auth/oauth/twitter/* (after Steward PR, with no-email fix) │
│  POST /auth/refresh         POST /auth/revoke                     │
│  GET  /auth/session                                               │
│  POST /platform/tenants     (platform admin — tenant provisioning) │
│                                                                    │
│  JWT env var: STEWARD_JWT_SECRET  (auth.ts reads this)            │
│  (separate from STEWARD_SESSION_SECRET used by user.ts routes)    │
│                                                                    │
│  HS256 JWT: { userId (UUID), tenantId:"feed", email?, exp }    │
└────────────────────────────┬─────────────────────────────────────┘
                             │ Postgres (steward DB in Feed's PG)
                             ▼
┌──────────────────────────────────────────────────────────────────┐
│  Steward DB (separate 'steward' database in Feed's Postgres)   │
│  users · authenticators · sessions · accounts · refresh_tokens   │
│  tenants · user_tenants                                           │
└──────────────────────────────────────────────────────────────────┘

Local dev:  Docker Compose, build from ../steward sibling directory
Production: ElizaCloud-hosted Steward instance

User: POST /auth/email/send { email }          → Steward sends magic link
User: clicks link → /auth/callback/email?token=...&email=...
Browser: POST /auth/email/verify { token, email, tenantId:"feed" }
Steward: creates/finds user → mints JWT:
  { userId: "uuid", tenantId: "feed", email: "...", iss: "steward", exp: now+900 }
Browser: POST /api/auth/session { token, refreshToken }   ← body, NOT URL param
Feed API route: jwtVerify(token, STEWARD_JWT_SECRET) → sets steward-token httpOnly cookie
All subsequent requests: cookie → auth-middleware → WHERE stewardId = payload.userId

case "twitter": {
  const clientId = process.env.TWITTER_CLIENT_ID;
  const clientSecret = process.env.TWITTER_CLIENT_SECRET;
  if (!clientId || !clientSecret) {
    throw new Error("Twitter OAuth not configured: TWITTER_CLIENT_ID and TWITTER_CLIENT_SECRET are required");
  }
  return {
    clientId, clientSecret,
    authorizationUrl: "https://twitter.com/i/oauth2/authorize",
    tokenUrl: "https://api.twitter.com/2/oauth2/token",
    userInfoUrl: "https://api.twitter.com/2/users/me?user.fields=id,name,username,profile_image_url",
    scopes: ["tweet.read", "users.read", "offline.access"],
  };
}

// Twitter (and potentially other providers) may not return an email.
// Fall back to a deterministic synthetic email using provider + account ID.
// This is never displayed or sent — it's an internal identity key.
const email = providerUser.email
  ? providerUser.email.toLowerCase().trim()
  : `${providerName}.${providerUser.id}@id.steward.internal`;

// After: const data = await res.json()
// Twitter returns { data: { id, name, username } } not flat
const flat = (data as Record<string, unknown>).data
  ? (data as { data: Record<string, unknown> }).data
  : data as Record<string, unknown>;
return {
  id: String(flat["id"] ?? ""),
  email: String(flat["email"] ?? ""),
  name: flat["name"] != null ? String(flat["name"]) : flat["username"] != null ? String(flat["username"]) : undefined,
  // ...
};

TWITTER_CLIENT_ID=
TWITTER_CLIENT_SECRET=

  steward:
    build:
      context: ../steward          # sibling directory — verified Docker supports this
      dockerfile: Dockerfile
    container_name: feed-steward
    restart: unless-stopped
    ports:
      - "3200:3200"
    environment:
      PORT: 3200
      NODE_ENV: development
      STEWARD_MASTER_PASSWORD: ${STEWARD_MASTER_PASSWORD}
      STEWARD_JWT_SECRET: ${STEWARD_JWT_SECRET}
      STEWARD_SESSION_SECRET: ${STEWARD_JWT_SECRET}   # same value; Steward uses both var names
      DATABASE_URL: "postgresql://feed:feed_dev_password@postgres:5432/steward"
      STEWARD_PLATFORM_KEYS: ${STEWARD_PLATFORM_KEYS}
      RESEND_API_KEY: ${RESEND_API_KEY:-}
      EMAIL_FROM: ${EMAIL_FROM:[email protected]}
      APP_URL: ${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
      PASSKEY_RP_NAME: Feed
      PASSKEY_RP_ID: localhost
      PASSKEY_ORIGIN: ${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
      GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
      GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
      DISCORD_CLIENT_ID: ${DISCORD_CLIENT_ID:-}
      DISCORD_CLIENT_SECRET: ${DISCORD_CLIENT_SECRET:-}
      TWITTER_CLIENT_ID: ${TWITTER_CLIENT_ID:-}
      TWITTER_CLIENT_SECRET: ${TWITTER_CLIENT_SECRET:-}
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:3200/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 8
      start_period: 45s

#!/bin/bash
psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" <<-EOSQL
  SELECT 'CREATE DATABASE steward'
    WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = 'steward')\gexec
  GRANT ALL PRIVILEGES ON DATABASE steward TO $POSTGRES_USER;
EOSQL

    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/docker/init-steward-db.sh:/docker-entrypoint-initdb.d/20-steward.sh

const STEWARD_CONTAINER = 'feed-steward';
const stewardRunning = await $`docker ps --filter name=${STEWARD_CONTAINER} --format "{{.Names}}"`.quiet().text();
if (stewardRunning.trim() !== STEWARD_CONTAINER) {
  console.info('[Script] Starting Steward auth service...');
  await dockerComposeUp('steward' as DockerService).catch(() => {
    console.warn('[Script] ⚠️  Steward start failed — auth will not work');
  });
}
let stewardReady = false;
for (let i = 0; i < 30; i++) {
  const ok = await fetch('http://localhost:3200/health').then(r => r.ok).catch(() => false);
  if (ok) { stewardReady = true; break; }
  await new Promise(r => setTimeout(r, 2000));
}
console.info(stewardReady
  ? '[Script] ✅ Steward is ready at http://localhost:3200'
  : '[Script] ⚠️  Steward did not become healthy within 60s');

#!/usr/bin/env bun
/**
 * One-time idempotent script to provision the "feed" tenant in Steward.
 * Run: bun run scripts/steward-init.ts
 * Copy the output STEWARD_TENANT_ID and STEWARD_TENANT_API_KEY into .env
 */
const STEWARD_API_URL = process.env.STEWARD_API_URL ?? 'http://localhost:3200';
const PLATFORM_KEY = (process.env.STEWARD_PLATFORM_KEYS ?? '').split(',')[0].trim();
if (!PLATFORM_KEY) { console.error('❌ STEWARD_PLATFORM_KEYS is required'); process.exit(1); }

const res = await fetch(`${STEWARD_API_URL}/platform/tenants`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Steward-Platform-Key': PLATFORM_KEY,
  },
  body: JSON.stringify({ id: 'feed', name: 'Feed Social' }),
});
const data = await res.json() as { ok: boolean; apiKey?: string; error?: string };

if (res.status === 409) {
  console.info('ℹ️  Tenant "feed" already exists. API key is not re-returned. Check existing .env.');
} else if (!res.ok) {
  console.error('❌ Failed:', data.error); process.exit(1);
} else {
  console.info('✅ Feed tenant created. Add to .env:\n');
  console.info(`STEWARD_TENANT_ID=feed`);
  console.info(`STEWARD_TENANT_API_KEY=${data.apiKey}`);
}

/**
 * POST /platform/users
 * Provision a user record in Steward without sending email.
 * Intended for migration use: pre-seeding users from another auth provider.
 *
 * Body: { email: string; emailVerified?: boolean; name?: string }
 * Returns: { ok: true; userId: string; isNew: boolean }
 */
platform.post("/users", async (c) => {
  const body = await safeJsonParse<{ email: string; emailVerified?: boolean; name?: string }>(c);
  if (!body?.email) {
    return c.json<ApiResponse>({ ok: false, error: "email is required" }, 400);
  }
  const db = getDb();
  const email = body.email.toLowerCase().trim();
  const [existing] = await db.select({ id: users.id }).from(users).where(eq(users.email, email));
  if (existing) {
    return c.json({ ok: true, userId: existing.id, isNew: false });
  }
  const [newUser] = await db
    .insert(users)
    .values({ email, emailVerified: body.emailVerified ?? false, name: body.name ?? null })
    .returning({ id: users.id });
  return c.json({ ok: true, userId: newUser.id, isNew: true });
});

stewardId: text('stewardId').unique(),

bun run db:generate
bun run db:migrate

#!/usr/bin/env bun
/**
 * Migrate all Privy users to Steward.
 *
 * Phase A: Export from Privy Admin API
 * Phase B: Pre-seed each user in Steward via POST /platform/users
 * Phase C: Build manifest of email-less users (social-only accounts)
 * Phase D: Report (no DB writes to Feed — those happen at runtime via bridge)
 *
 * Usage:
 *   bun run scripts/migrate-privy-to-steward.ts --dry-run    # report only
 *   bun run scripts/migrate-privy-to-steward.ts              # actually migrate
 */
import { writeFileSync } from 'fs';

const PRIVY_APP_ID = process.env.NEXT_PUBLIC_PRIVY_APP_ID ?? '';
const PRIVY_APP_SECRET = process.env.PRIVY_APP_SECRET ?? '';
const STEWARD_API_URL = process.env.STEWARD_API_URL ?? 'http://localhost:3200';
const PLATFORM_KEY = (process.env.STEWARD_PLATFORM_KEYS ?? '').split(',')[0].trim();
const DRY_RUN = process.argv.includes('--dry-run');

if (!PRIVY_APP_ID || !PRIVY_APP_SECRET) {
  console.error('❌ NEXT_PUBLIC_PRIVY_APP_ID and PRIVY_APP_SECRET required (read Privy dashboard)');
  process.exit(1);
}
if (!PLATFORM_KEY) {
  console.error('❌ STEWARD_PLATFORM_KEYS required');
  process.exit(1);
}

const basicAuth = Buffer.from(`${PRIVY_APP_ID}:${PRIVY_APP_SECRET}`).toString('base64');

// Phase A: paginate all Privy users
// Privy Admin API: GET https://auth.privy.io/api/v1/users
// Auth: Basic base64(appId:appSecret) + privy-app-id header
// Returns: { data: User[], next_cursor?: string }
const allUsers: Array<{
  id: string; // did:privy:xxx
  email?: { address: string };
  farcaster?: { fid: number; username: string };
  twitter?: { username: string };
  telegram?: { telegram_user_id: string; username: string };
}> = [];

let cursor: string | undefined;
do {
  const url = new URL('https://auth.privy.io/api/v1/users');
  url.searchParams.set('limit', '500');
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url.toString(), {
    headers: {
      'Authorization': `Basic ${basicAuth}`,
      'privy-app-id': PRIVY_APP_ID,
    },
  });
  if (!res.ok) { console.error(`Privy API error: ${res.status} ${await res.text()}`); process.exit(1); }

  const body = await res.json() as { data: typeof allUsers; next_cursor?: string };
  allUsers.push(...body.data);
  cursor = body.next_cursor;
  console.info(`Fetched ${allUsers.length} users so far...`);
} while (cursor);

console.info(`✅ Exported ${allUsers.length} Privy users`);

const withEmail = allUsers.filter(u => u.email?.address);
const withoutEmail = allUsers.filter(u => !u.email?.address);

console.info(`  With email: ${withEmail.length}`);
console.info(`  Without email (social-only): ${withoutEmail.length}`);

// Phase B: pre-seed users in Steward
let seeded = 0, existed = 0, failed = 0;
for (const user of withEmail) {
  const email = user.email!.address;
  if (DRY_RUN) { seeded++; continue; }

  const res = await fetch(`${STEWARD_API_URL}/platform/users`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Steward-Platform-Key': PLATFORM_KEY,
    },
    body: JSON.stringify({ email, emailVerified: true }),
  });
  const data = await res.json() as { ok: boolean; isNew?: boolean };
  if (!data.ok) { failed++; console.warn(`Failed: ${email}`); }
  else if (data.isNew) seeded++;
  else existed++;
}

console.info(`\n✅ Steward seeding: ${seeded} created, ${existed} already existed, ${failed} failed`);

// Phase C: write manifest of email-less users
const emaillessManifest = withoutEmail.map(u => ({
  privyId: u.id,
  farcasterFid: u.farcaster?.fid ?? null,
  farcasterUsername: u.farcaster?.username ?? null,
  twitterUsername: u.twitter?.username ?? null,
  telegramId: u.telegram?.telegram_user_id ?? null,
  telegramUsername: u.telegram?.username ?? null,
}));
writeFileSync('migrations/privy-emailless-users.json', JSON.stringify(emaillessManifest, null, 2));
console.info(`📄 Wrote ${emaillessManifest.length} email-less users to migrations/privy-emailless-users.json`);
console.info('   These users will be auto-linked at login time via social profile matching.');

import { jwtVerify } from 'jose';

const STEWARD_JWT_SECRET = new TextEncoder().encode(
  process.env.STEWARD_JWT_SECRET ?? ''
);

// In authenticate():
// Cookie takes priority over Authorization header (same pattern as Privy cookie)
const cookieToken = request.cookies.get('steward-token')?.value;
const authHeaderToken = request.headers.get('authorization')?.startsWith('Bearer ')
  ? request.headers.get('authorization')!.slice(7)
  : undefined;
const token = cookieToken ?? authHeaderToken;

if (!token) throw new AuthenticationError('Missing authentication');

const { payload } = await jwtVerify(token, STEWARD_JWT_SECRET, {
  issuer: 'steward',
  algorithms: ['HS256'],
});
// payload: { userId: string, tenantId: string, email?: string, address?: string }

// 1. Fast path: already linked
let dbUser = await db.select().from(users)
  .where(eq(users.stewardId, payload.userId as string))
  .limit(1).then(r => r[0]);

// 2. Email bridge: existing Privy user logs in via Steward for first time
if (!dbUser && payload.email && !String(payload.email).includes('@id.steward.internal')) {
  const emailUser = await db.select().from(users)
    .where(and(eq(users.email, payload.email as string), isNull(users.stewardId)))
    .limit(1).then(r => r[0]);
  if (emailUser) {
    await db.update(users).set({ stewardId: payload.userId as string })
      .where(eq(users.id, emailUser.id));
    dbUser = { ...emailUser, stewardId: payload.userId as string };
  }
}

// 3. New user: first time we've seen this Steward userId
if (!dbUser) {
  dbUser = await ensureUserFromSteward(
    payload.userId as string,
    payload.email && !String(payload.email).includes('@id.steward.internal')
      ? payload.email as string : undefined,
  );
}

export async function ensureUserFromSteward(
  stewardUserId: string,
  email?: string,
): Promise<CanonicalUser> {
  const [user] = await db.insert(users)
    .values({
      stewardId: stewardUserId,
      email: email ?? null,
    })
    .onConflictDoUpdate({
      target: users.stewardId,
      set: { email: email ?? sql`excluded.email` },
    })
    .returning(canonicalUserSelect);
  return user;
}

// POST: validates Steward JWT, sets httpOnly steward-token cookie
// DELETE: clears the cookie

export async function POST(req: NextRequest) {
  const { token, refreshToken } = await req.json() as { token: string; refreshToken?: string };

  // Verify locally before storing — reject tampered tokens immediately
  const STEWARD_JWT_SECRET = new TextEncoder().encode(process.env.STEWARD_JWT_SECRET ?? '');
  const { payload } = await jwtVerify(token, STEWARD_JWT_SECRET, {
    issuer: 'steward',
    algorithms: ['HS256'],
  }).catch(() => { throw new Error('Invalid token'); });

  const response = NextResponse.json({ ok: true, userId: payload.userId });
  response.cookies.set('steward-token', token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 30, // 30d (refresh token lifetime)
    path: '/',
  });
  // Refresh token stored in a separate httpOnly cookie
  if (refreshToken) {
    response.cookies.set('steward-refresh', refreshToken, {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'lax',
      maxAge: 60 * 60 * 24 * 30,
      path: '/',
    });
  }
  return response;
}

export async function DELETE() {
  const response = NextResponse.json({ ok: true });
  response.cookies.delete('steward-token');
  response.cookies.delete('steward-refresh');
  return response;
}

'use client';
import { useEffect } from 'react';
import { useRouter, useSearchParams } from 'next/navigation';
import { StewardAuth } from '@stwd/sdk';

export default function EmailCallbackPage() {
  const router = useRouter();
  const params = useSearchParams();

  useEffect(() => {
    const token = params.get('token');
    const email = params.get('email');
    const returnTo = params.get('returnTo') ?? '/feed';
    if (!token || !email) { router.replace('/'); return; }

    const auth = new StewardAuth({ baseUrl: process.env.NEXT_PUBLIC_STEWARD_API_URL! });
    auth.verifyEmailCallback(token, email).then(async (result) => {
      // Send token via POST body — NOT URL params — to avoid browser history / server log exposure
      await fetch('/api/auth/session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token: result.token, refreshToken: result.refreshToken }),
      });
      router.replace(returnTo);
    }).catch(() => router.replace('/?error=auth_failed'));
  }, []);

  return <div>Completing sign in…</div>;
}

'use client';
import { useEffect } from 'react';
import { useRouter, useSearchParams } from 'next/navigation';

export default function OAuthCallbackPage() {
  const router = useRouter();
  const params = useSearchParams();

  useEffect(() => {
    const token = params.get('token');
    const refreshToken = params.get('refreshToken');
    const returnTo = params.get('returnTo') ?? '/feed';

    // SECURITY: Replace URL immediately to remove token from browser history
    // before any async work that could be interrupted
    window.history.replaceState(null, '', window.location.pathname);

    if (!token) { router.replace('/'); return; }

    fetch('/api/auth/session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token, refreshToken }),
    }).then(() => router.replace(returnTo))
      .catch(() => router.replace('/?error=auth_failed'));
  }, []);

  return <div>Completing sign in…</div>;
}

'use client';

import { StewardAuth, type StewardSession } from '@stwd/sdk';
import { createContext, useContext, useEffect, useState } from 'react';

const STEWARD_API_URL = process.env.NEXT_PUBLIC_STEWARD_API_URL!;

// Module-level singleton — one StewardAuth instance for the lifetime of the browser tab
// This is safe because StewardAuth stores state in localStorage and notifies via callbacks
const _stewardAuth = new StewardAuth({ baseUrl: STEWARD_API_URL });

export interface StewardAuthContextValue {
  auth: StewardAuth;
  session: StewardSession | null;
  isLoading: boolean;
}

const StewardAuthContext = createContext<StewardAuthContextValue | null>(null);

export function StewardAuthProvider({ children }: { children: React.ReactNode }) {
  const [session, setSession] = useState<StewardSession | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    setSession(_stewardAuth.getSession());
    setIsLoading(false);
    return _stewardAuth.onSessionChange(setSession);
  }, []);

  return (
    <StewardAuthContext.Provider value={{ auth: _stewardAuth, session, isLoading }}>
      {children}
    </StewardAuthContext.Provider>
  );
}

export function useStewardAuth(): StewardAuthContextValue {
  const ctx = useContext(StewardAuthContext);
  if (!ctx) throw new Error('useStewardAuth must be used within StewardAuthProvider');
  return ctx;
}

import { createAppClient, viemConnector } from '@farcaster/auth-client';

export async function POST(req: NextRequest) {
  const { message, signature, nonce } = await req.json();

  // Server-side verification using @farcaster/auth-client (already installed)
  const appClient = createAppClient({
    relay: 'https://relay.farcaster.xyz',
    ethereum: viemConnector(),
  });

  const { data, success, fid } = await appClient.verifySignInMessage({
    message,
    signature,
    nonce,
    domain: new URL(process.env.NEXT_PUBLIC_APP_URL!).hostname,
  });

  if (!success) return NextResponse.json({ ok: false, error: 'Invalid Farcaster signature' }, { status: 401 });

  // Look up existing Feed user by FID, then stewardId, then create
  // Use ensureUserFromFarcaster() — create if needed, mint JWT
  const { token, refreshToken } = await mintSessionForFarcasterUser(fid, data);
  return NextResponse.json({ ok: true, token, refreshToken });
}

const token = await new SignJWT({ userId: stewardUserId, tenantId: 'feed', fid })
  .setProtectedHeader({ alg: 'HS256' })
  .setIssuer('steward')
  .setIssuedAt()
  .setExpirationTime('15m')
  .sign(new TextEncoder().encode(process.env.STEWARD_JWT_SECRET!));

import { usePrivy } from '@privy-io/react-auth';
import { useLoginToMiniApp } from '@privy-io/react-auth/farcaster';
// ...
const { initLoginToMiniApp, loginToMiniApp } = useLoginToMiniApp();
const { nonce } = await initLoginToMiniApp();
const result = await sdk.actions.signIn({ nonce });
await loginToMiniApp({ message, signature });

import { sdk } from '@farcaster/miniapp-sdk';
// ...
const { token } = await sdk.quickAuth.getToken();
const res = await fetch('/api/auth/farcaster-miniapp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token }),
});
const { sessionToken, refreshToken } = await res.json();
await fetch('/api/auth/session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token: sessionToken, refreshToken }),
});

import { createClient } from '@farcaster/quick-auth';

export async function POST(req: NextRequest) {
  const { token } = await req.json();

  // VERIFIED: createClient() has verifyJwt() method that fetches JWKS from
  // https://auth.farcaster.xyz — requires network access (not a local verify).
  // This is acceptable for a server-side API route.
  const quickAuthClient = createClient(); // from @farcaster/quick-auth (already installed)
  const payload = await quickAuthClient.verifyJwt({
    token,
    domain: new URL(process.env.NEXT_PUBLIC_APP_URL!).hostname,
  });
  // payload.sub = FID (number), payload.address = custody address

  const fid = payload.sub; // number
  const { sessionToken, refreshToken } = await mintSessionForFarcasterUser(fid, {});
  return NextResponse.json({ ok: true, sessionToken, refreshToken });
}

const initData = window.Telegram?.WebApp?.initData;
if (initData) {
  const res = await fetch('/api/auth/telegram-miniapp', {
    method: 'POST',
    body: JSON.stringify({ initData }),
  });
  const { token, refreshToken } = await res.json();
  await fetch('/api/auth/session', {
    method: 'POST',
    body: JSON.stringify({ token, refreshToken }),
  });
}

import crypto from 'node:crypto';

export async function POST(req: NextRequest) {
  const { initData } = await req.json();

  // Standard Telegram WebApp initData HMAC-SHA256 verification
  // https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
  const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
  if (!BOT_TOKEN) return NextResponse.json({ ok: false, error: 'Telegram not configured' }, { status: 503 });

  const params = new URLSearchParams(initData);
  const hash = params.get('hash');
  params.delete('hash');

  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');

  const secretKey = crypto.createHmac('sha256', 'WebAppData').update(BOT_TOKEN).digest();
  const computedHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');

  if (computedHash !== hash) {
    return NextResponse.json({ ok: false, error: 'Invalid Telegram initData' }, { status: 401 });
  }

  const user = JSON.parse(params.get('user') ?? '{}') as { id: number; username?: string };
  const { token, refreshToken } = await mintSessionForTelegramUser(user.id, user.username);
  return NextResponse.json({ ok: true, token, refreshToken });
}

# Remove
bun remove @privy-io/react-auth @privy-io/server-auth @privy-io/node

# Add (only what's actually missing)
bun add @stwd/sdk @simplewebauthn/browser
# Note: @simplewebauthn/browser is a peer dep of StewardAuth passkey flow — not auto-installed

NEXT_PUBLIC_PRIVY_APP_ID
PRIVY_APP_SECRET
PRIVY_APP_ID
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID

# ── Steward Auth Service ────────────────────────────────────────────────────
STEWARD_API_URL=http://localhost:3200
NEXT_PUBLIC_STEWARD_API_URL=http://localhost:3200

# [REQUIRED] Vault master password. Rotating requires re-encrypting all vault entries.
# Generate: openssl rand -hex 32
STEWARD_MASTER_PASSWORD=

# [REQUIRED] JWT signing secret used by Steward's auth.ts module.
# Feed's auth-middleware verifies JWTs using this secret.
# Generate: openssl rand -hex 32
STEWARD_JWT_SECRET=

# [REQUIRED] Same value as STEWARD_JWT_SECRET — Steward's user.ts reads this var name.
# Set both to the same value to avoid confusion.
STEWARD_SESSION_SECRET=   # <- set equal to STEWARD_JWT_SECRET

# [REQUIRED] Platform operator key(s). Comma-separated. Used for tenant admin.
# Generate: openssl rand -hex 32
STEWARD_PLATFORM_KEYS=

# [REQUIRED] Output of bun run steward:init
STEWARD_TENANT_ID=feed
STEWARD_TENANT_API_KEY=

# ── OAuth providers (all routed through Steward) ────────────────────────────
# Google: console.cloud.google.com
# Redirect URI in Google: http://localhost:3200/auth/oauth/google/callback
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Discord: discord.com/developers/applications
# Redirect URI in Discord: http://localhost:3200/auth/oauth/discord/callback
DISCORD_CLIENT_ID=
DISCORD_CLIENT_SECRET=

# Twitter/X: developer.twitter.com
# App type: Confidential client, OAuth2 with PKCE
# Scopes: tweet.read users.read offline.access
# Redirect URI in Twitter: http://localhost:3200/auth/oauth/twitter/callback
# NOTE: Twitter does NOT return email via API.
# Steward uses a synthetic internal email ([email protected]) for Twitter users.
TWITTER_CLIENT_ID=
TWITTER_CLIENT_SECRET=

# ── Email (Steward sends magic links via Resend) ────────────────────────────
# If RESEND_API_KEY is blank, tokens are printed to console (safe for dev)
RESEND_API_KEY=
[email protected]

# ── Telegram (mini-app HMAC verification) ──────────────────────────────────
TELEGRAM_BOT_TOKEN=

Phase A — Steward PR (prerequisite, unblocks Twitter + migration)
├── Twitter/X OAuth to packages/auth/src/oauth.ts (with PKCE + no-email fix)
├── provisionOAuthUser() synthetic email patch
├── POST /platform/users admin endpoint
└── Merge to Steward develop

Phase B — ElizaCloud PR (infrastructure)
├── Steward Docker service in docker-compose.yml
├── Tenant provisioning API
└── Merge to ElizaCloud dev

Phase C — Feed: Infrastructure
├── 1. docker-compose.yml: steward service (../steward build context)
├── 2. scripts/docker/init-steward-db.sh
├── 3. scripts/pre-dev/pre-dev-local.ts: Steward health check
├── 4. scripts/steward-init.ts
└── QG: bun run check + typecheck ✅

Phase D — Feed: Database
├── 5. DB migration: stewardId column
└── QG: bun run db:migrate ✅

Phase E — Feed: Backend auth swap
├── 6. auth-middleware.ts: Steward JWT verification
├── 7. ensure-user.ts + user-lookup.ts
├── 8. /api/auth/session cookie bridge
├── 9. /api/auth/farcaster route
├── 10. /api/auth/farcaster-miniapp route
├── 11. /api/auth/telegram-miniapp route
└── QG: integration tests pass ✅

Phase F — Feed: User migration
├── 12. scripts/migrate-privy-to-steward.ts --dry-run (review output)
└── 13. Run migration against production Steward

Phase G — Feed: Frontend swap
├── 14. StewardAuthProvider.tsx
├── 15. Providers.tsx (remove PrivyProvider)
├── 16. useAuth.ts rewrite
├── 17. Mechanical sweep: 9 getAccessToken callers
└── QG: bun run typecheck ✅

Phase H — Feed: Login + callbacks
├── 18. LoginModal.tsx
├── 19. /auth/callback/email/page.tsx
├── 20. /auth/callback/[provider]/page.tsx (URL sanitization included)
└── QG: manually test each login method ✅

Phase I — Feed: Mini-apps + linking
├── 21. FarcasterMiniAppProvider.tsx (quickAuth.getToken())
├── 22. LinkSocialAccountsModal.tsx
└── QG: test Farcaster + Telegram mini-app flows ✅

Phase J — Feed: Cleanup
├── 23. bun remove @privy-io/react-auth @privy-io/server-auth @privy-io/node
├── 24. bun add @stwd/sdk @simplewebauthn/browser
├── 25. Delete dead files (privy-config.ts, privy-node.ts, etc.)
├── 26. Update .env.example
└── QG: full quality gate ✅

Phase K — Cutover
├── 27. Deploy (users with old privy-token cookies get login prompt — expected)
├── 28. Monitor 2 weeks
└── 29. Remove PRIVY_APP_SECRET from environments, delete Privy app

# Format + lint
bun run check

# TypeScript (zero errors)
bun run typecheck

# Lint (zero warnings)
bun run lint

# Unit tests
bun run test:unit

# Integration tests (after backend changes)
bun run test:integration

# Build
bun run build

# No @privy-io imports remain
rg "@privy-io" apps/web/src packages --type ts

# No usePrivy() calls remain
rg "usePrivy\(\)" apps/web/src

# steward-token cookie set after login
# Browser DevTools → Application → Cookies → steward-token → HttpOnly: ✓

# Token NOT present in URL after OAuth callback
# Browser → check URL bar after login — should be clean (token removed by replaceState)

# JWT verification (curl test)
curl -H "Cookie: steward-token=$(cat /tmp/test-token)" \
  http://localhost:3000/api/users/me | jq .

# Migration report
bun run scripts/migrate-privy-to-steward.ts --dry-run | tail -20

@privy-io/react-auth
@privy-io/server-auth
@privy-io/node

@stwd/[email protected]                # StewardAuth client (verified on npm)
@simplewebauthn/browser        # peer dep for passkey WebAuthn (not auto-installed by @stwd/sdk)

@farcaster/[email protected]      # already in apps/web/package.json
@farcaster/[email protected]   # already in apps/web/package.json
@farcaster/[email protected]   # already in apps/web/package.json (includes quickAuth)
@farcaster/quick-auth          # already pulled in as transitive dep
jose                           # already used in Feed backend