@rune-kit/rune 2.10.0 → 2.11.0

package/extensions/backend/skills/async-pipeline.md

@@ -1,193 +1,193 @@
----
-name: "async-pipeline"
-pack: "@rune/backend"
-description: "Multi-stage async processing pipelines with waterfall engine selection, progress streaming, and credit-based billing. Patterns for building services that process data through multiple fallback strategies with real-time status updates."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# async-pipeline
-
-Multi-stage async processing pipelines with waterfall engine selection, progress streaming, and credit-based billing. Patterns for building services that process data through multiple fallback strategies with real-time status updates.
-
-#### Workflow
-
-**Step 1 — Design engine waterfall**
-Multiple processing engines ranked by quality and cost:
-```typescript
-interface ProcessingEngine {
-  name: string;
-  quality: number;       // higher = preferred
-  costMultiplier: number; // credit cost factor
-  execute: (input: Input) => Promise<Result>;
-  canHandle: (input: Input) => boolean;
-}
-
-// Engines race with staggered delays — first valid result wins
-async function waterfallExecute(
-  engines: ProcessingEngine[],
-  input: Input,
-  staggerDelayMs: number = 500
-): Promise<{ result: Result; engine: string }> {
-  const sorted = engines
-    .filter(e => e.canHandle(input))
-    .sort((a, b) => b.quality - a.quality);
-
-  const controller = new AbortController();
-
-  const races = sorted.map((engine, i) =>
-    new Promise<{ result: Result; engine: string }>(async (resolve, reject) => {
-      // Stagger start: engine 0 starts immediately, engine 1 after 500ms, etc.
-      if (i > 0) await delay(i * staggerDelayMs);
-      if (controller.signal.aborted) return reject(new Error('aborted'));
-
-      try {
-        const result = await engine.execute(input);
-        if (isValid(result)) {
-          controller.abort();  // cancel slower engines
-          resolve({ result, engine: engine.name });
-        } else {
-          reject(new Error(`${engine.name}: invalid result`));
-        }
-      } catch (err) {
-        reject(err);
-      }
-    })
-  );
-
-  return Promise.any(races);
-}
-```
-
-**Step 2 — Implement transform pipeline**
-Chain transforms that process data sequentially:
-```typescript
-type Transformer<T> = (data: T, context: PipelineContext) => Promise<T>;
-
-async function runPipeline<T>(
-  data: T,
-  transformers: Transformer<T>[],
-  onProgress: (stage: string, pct: number) => void
-): Promise<T> {
-  let current = data;
-  for (let i = 0; i < transformers.length; i++) {
-    onProgress(transformers[i].name, (i / transformers.length) * 100);
-    current = await transformers[i](current, context);
-  }
-  onProgress('complete', 100);
-  return current;
-}
-```
-
-**Step 3 — Stream progress via SSE**
-Real-time progress from worker to client:
-```typescript
-// Worker side: publish progress to Redis pub/sub
-async function publishProgress(jobId: string, stage: string, pct: number) {
-  await redis.publish(`job:${jobId}:progress`, JSON.stringify({ stage, pct, ts: Date.now() }));
-}
-
-// API side: SSE endpoint
-app.get('/jobs/:id/progress', async (req, res) => {
-  res.setHeader('Content-Type', 'text/event-stream');
-  res.setHeader('Cache-Control', 'no-cache');
-  res.setHeader('Connection', 'keep-alive');
-
-  const subscriber = redis.duplicate();
-  await subscriber.subscribe(`job:${req.params.id}:progress`);
-
-  subscriber.on('message', (_channel, message) => {
-    res.write(`data: ${message}\n\n`);
-  });
-
-  req.on('close', () => subscriber.unsubscribe());
-});
-```
-
-**Step 4 — Two-tier concurrency control**
-```typescript
-// Team-level: limit concurrent jobs per team
-async function canEnqueue(teamId: string): Promise<boolean> {
-  const active = await redis.zcard(`team:${teamId}:active`);
-  const limit = await getTeamConcurrencyLimit(teamId);
-  return active < limit;
-}
-
-// Job-level: track active jobs with TTL (auto-cleanup on crash)
-async function markActive(teamId: string, jobId: string) {
-  await redis.zadd(`team:${teamId}:active`, Date.now(), jobId);
-  await redis.expire(`team:${teamId}:active`, 3600);  // 1h TTL safety net
-}
-
-async function markComplete(teamId: string, jobId: string) {
-  await redis.zrem(`team:${teamId}:active`, jobId);
-}
-```
-
-**Step 5 — Dynamic credit billing**
-```typescript
-interface CreditCost {
-  base: number;
-  engineMultiplier: number;   // stealth proxy = 4x
-  formatMultiplier: number;   // JSON extraction = 5x
-  extras: number;             // per-page for PDFs, per-territory for pricing
-}
-
-function calculateCredits(job: CompletedJob): number {
-  let cost = job.cost.base;
-  cost *= job.cost.engineMultiplier;
-  cost *= job.cost.formatMultiplier;
-  cost += job.cost.extras;
-  return Math.ceil(cost);
-}
-```
-
-**Step 6 — Dead letter queue with retry classification**
-```typescript
-interface FailedJob {
-  id: string;
-  error: string;
-  errorCode: 'TRANSIENT' | 'PERMANENT' | 'TIMEOUT' | 'RATE_LIMITED';
-  attempts: number;
-  stageTiming: Record<string, number>;  // per-stage perf data
-}
-
-// Retry only transient failures; permanent goes to dead letter
-function shouldRetry(job: FailedJob): boolean {
-  if (job.errorCode === 'PERMANENT') return false;
-  if (job.attempts >= 3) return false;
-  return true;
-}
-```
-
-#### Example
-
-```typescript
-// Complete async pipeline for document processing
-const docPipeline = createPipeline({
-  engines: [
-    { name: 'native-parser', quality: 100, costMultiplier: 1, execute: nativeParse },
-    { name: 'llm-extraction', quality: 80, costMultiplier: 5, execute: llmExtract },
-    { name: 'ocr-fallback', quality: 50, costMultiplier: 3, execute: ocrExtract },
-  ],
-  transforms: [
-    cleanHTML,
-    extractMetadata,
-    convertToMarkdown,
-    generateSummary,
-    indexForSearch,
-  ],
-  concurrency: { perTeam: 10, perJob: 3 },
-  billing: { base: 1, jsonFormat: 5 },
-  deadLetter: { maxRetries: 3, alertThreshold: 10 },
-});
-
-// Enqueue
-const jobId = await docPipeline.enqueue(teamId, { url, format: 'json' });
-
-// Stream progress
-const progress = docPipeline.streamProgress(jobId);
-for await (const update of progress) {
-  console.log(`${update.stage}: ${update.pct}%`);
-}
-```
+---
+name: "async-pipeline"
+pack: "@rune/backend"
+description: "Multi-stage async processing pipelines with waterfall engine selection, progress streaming, and credit-based billing. Patterns for building services that process data through multiple fallback strategies with real-time status updates."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# async-pipeline
+
+Multi-stage async processing pipelines with waterfall engine selection, progress streaming, and credit-based billing. Patterns for building services that process data through multiple fallback strategies with real-time status updates.
+
+#### Workflow
+
+**Step 1 — Design engine waterfall**
+Multiple processing engines ranked by quality and cost:
+```typescript
+interface ProcessingEngine {
+  name: string;
+  quality: number;       // higher = preferred
+  costMultiplier: number; // credit cost factor
+  execute: (input: Input) => Promise<Result>;
+  canHandle: (input: Input) => boolean;
+}
+
+// Engines race with staggered delays — first valid result wins
+async function waterfallExecute(
+  engines: ProcessingEngine[],
+  input: Input,
+  staggerDelayMs: number = 500
+): Promise<{ result: Result; engine: string }> {
+  const sorted = engines
+    .filter(e => e.canHandle(input))
+    .sort((a, b) => b.quality - a.quality);
+
+  const controller = new AbortController();
+
+  const races = sorted.map((engine, i) =>
+    new Promise<{ result: Result; engine: string }>(async (resolve, reject) => {
+      // Stagger start: engine 0 starts immediately, engine 1 after 500ms, etc.
+      if (i > 0) await delay(i * staggerDelayMs);
+      if (controller.signal.aborted) return reject(new Error('aborted'));
+
+      try {
+        const result = await engine.execute(input);
+        if (isValid(result)) {
+          controller.abort();  // cancel slower engines
+          resolve({ result, engine: engine.name });
+        } else {
+          reject(new Error(`${engine.name}: invalid result`));
+        }
+      } catch (err) {
+        reject(err);
+      }
+    })
+  );
+
+  return Promise.any(races);
+}
+```
+
+**Step 2 — Implement transform pipeline**
+Chain transforms that process data sequentially:
+```typescript
+type Transformer<T> = (data: T, context: PipelineContext) => Promise<T>;
+
+async function runPipeline<T>(
+  data: T,
+  transformers: Transformer<T>[],
+  onProgress: (stage: string, pct: number) => void
+): Promise<T> {
+  let current = data;
+  for (let i = 0; i < transformers.length; i++) {
+    onProgress(transformers[i].name, (i / transformers.length) * 100);
+    current = await transformers[i](current, context);
+  }
+  onProgress('complete', 100);
+  return current;
+}
+```
+
+**Step 3 — Stream progress via SSE**
+Real-time progress from worker to client:
+```typescript
+// Worker side: publish progress to Redis pub/sub
+async function publishProgress(jobId: string, stage: string, pct: number) {
+  await redis.publish(`job:${jobId}:progress`, JSON.stringify({ stage, pct, ts: Date.now() }));
+}
+
+// API side: SSE endpoint
+app.get('/jobs/:id/progress', async (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  const subscriber = redis.duplicate();
+  await subscriber.subscribe(`job:${req.params.id}:progress`);
+
+  subscriber.on('message', (_channel, message) => {
+    res.write(`data: ${message}\n\n`);
+  });
+
+  req.on('close', () => subscriber.unsubscribe());
+});
+```
+
+**Step 4 — Two-tier concurrency control**
+```typescript
+// Team-level: limit concurrent jobs per team
+async function canEnqueue(teamId: string): Promise<boolean> {
+  const active = await redis.zcard(`team:${teamId}:active`);
+  const limit = await getTeamConcurrencyLimit(teamId);
+  return active < limit;
+}
+
+// Job-level: track active jobs with TTL (auto-cleanup on crash)
+async function markActive(teamId: string, jobId: string) {
+  await redis.zadd(`team:${teamId}:active`, Date.now(), jobId);
+  await redis.expire(`team:${teamId}:active`, 3600);  // 1h TTL safety net
+}
+
+async function markComplete(teamId: string, jobId: string) {
+  await redis.zrem(`team:${teamId}:active`, jobId);
+}
+```
+
+**Step 5 — Dynamic credit billing**
+```typescript
+interface CreditCost {
+  base: number;
+  engineMultiplier: number;   // stealth proxy = 4x
+  formatMultiplier: number;   // JSON extraction = 5x
+  extras: number;             // per-page for PDFs, per-territory for pricing
+}
+
+function calculateCredits(job: CompletedJob): number {
+  let cost = job.cost.base;
+  cost *= job.cost.engineMultiplier;
+  cost *= job.cost.formatMultiplier;
+  cost += job.cost.extras;
+  return Math.ceil(cost);
+}
+```
+
+**Step 6 — Dead letter queue with retry classification**
+```typescript
+interface FailedJob {
+  id: string;
+  error: string;
+  errorCode: 'TRANSIENT' | 'PERMANENT' | 'TIMEOUT' | 'RATE_LIMITED';
+  attempts: number;
+  stageTiming: Record<string, number>;  // per-stage perf data
+}
+
+// Retry only transient failures; permanent goes to dead letter
+function shouldRetry(job: FailedJob): boolean {
+  if (job.errorCode === 'PERMANENT') return false;
+  if (job.attempts >= 3) return false;
+  return true;
+}
+```
+
+#### Example
+
+```typescript
+// Complete async pipeline for document processing
+const docPipeline = createPipeline({
+  engines: [
+    { name: 'native-parser', quality: 100, costMultiplier: 1, execute: nativeParse },
+    { name: 'llm-extraction', quality: 80, costMultiplier: 5, execute: llmExtract },
+    { name: 'ocr-fallback', quality: 50, costMultiplier: 3, execute: ocrExtract },
+  ],
+  transforms: [
+    cleanHTML,
+    extractMetadata,
+    convertToMarkdown,
+    generateSummary,
+    indexForSearch,
+  ],
+  concurrency: { perTeam: 10, perJob: 3 },
+  billing: { base: 1, jsonFormat: 5 },
+  deadLetter: { maxRetries: 3, alertThreshold: 10 },
+});
+
+// Enqueue
+const jobId = await docPipeline.enqueue(teamId, { url, format: 'json' });
+
+// Stream progress
+const progress = docPipeline.streamProgress(jobId);
+for await (const update of progress) {
+  console.log(`${update.stage}: ${update.pct}%`);
+}
+```

package/extensions/backend/skills/auth-patterns.md

@@ -1,97 +1,97 @@
----
-name: "auth-patterns"
-pack: "@rune/backend"
-description: "Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# auth-patterns
-
-Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows.
-
-#### Workflow
-
-**Step 1 — Detect auth implementation**
-Use Grep to find auth-related code: `jwt.sign`, `jwt.verify`, `bcrypt`, `passport`, `next-auth`, `lucia`, `cookie`, `session`, `Bearer`, `x-api-key`, `WebAuthn`, `passkey`. Read auth middleware and login/register handlers to understand the current approach.
-
-**Step 2 — Audit security posture**
-Check for: tokens stored in localStorage (XSS risk → use httpOnly cookies), missing refresh token rotation, JWT without expiry, password hashing without salt rounds check, missing CSRF protection on cookie-based auth, hardcoded secrets. Flag each with severity and specific fix.
-
-**Step 3 — Emit secure auth flow**
-Based on detected framework (Express, Fastify, Next.js, etc.), emit the corrected auth flow: access token (short-lived, 15min) + refresh token (httpOnly cookie, 7d, rotation on use), proper password hashing (bcrypt rounds ≥ 12), RBAC middleware with role hierarchy.
-
-**Step 4 — OAuth 2.0 / OIDC integration**
-Emit OAuth 2.0 authorization code flow with PKCE (required for public clients). Support Google, GitHub, or custom OIDC provider. Key points: validate `state` parameter to prevent CSRF, validate `id_token` signature and `aud`/`iss` claims, exchange code server-side (never client-side), store provider `sub` as stable user identifier. Use `openid-client` (Node.js) or `authlib` (Python) — never hand-roll token exchange.
-
-**Step 5 — API key management and passkeys**
-For API keys: generate with `crypto.randomBytes(32).toString('base64url')`, store hashed (`sha256` is sufficient — no need for bcrypt, keys are long), never store plaintext after initial display. Add scopes (read-only vs read-write), per-key rate limits, and rotation endpoint. For passkeys/WebAuthn: emit registration and authentication ceremonies using `@simplewebauthn/server`. WebAuthn is the correct long-term replacement for passwords — emit as opt-in upgrade path. Stateless vs stateful tradeoff: JWT = stateless, easy to scale horizontally, hard to revoke; sessions = stateful, easy to revoke, requires sticky sessions or shared store (Redis). Recommend JWT + token blacklist on logout for most cases; sessions for admin panels where immediate revocation matters.
-
-#### Example
-
-```typescript
-// BEFORE: JWT in localStorage, no refresh, no expiry
-const token = jwt.sign({ userId: user.id }, SECRET);
-res.json({ token });
-
-// AFTER: short-lived access + httpOnly refresh cookie with rotation
-const accessToken = jwt.sign(
-  { sub: user.id, role: user.role },
-  ACCESS_SECRET,
-  { expiresIn: '15m' }
-);
-const refreshToken = jwt.sign(
-  { sub: user.id, jti: crypto.randomUUID() },
-  REFRESH_SECRET,
-  { expiresIn: '7d' }
-);
-await tokenStore.save(refreshToken, user.id); // rotation tracking — invalidate old on reuse
-
-res.cookie('refresh_token', refreshToken, {
-  httpOnly: true, secure: true, sameSite: 'strict',
-  maxAge: 7 * 24 * 60 * 60 * 1000,
-});
-res.json({ access_token: accessToken, expires_in: 900 });
-
-// API key management
-const generateApiKey = async (userId: string, scopes: string[]): Promise<{ key: string; keyId: string }> => {
-  const rawKey = `rk_${crypto.randomBytes(32).toString('base64url')}`;
-  const keyHash = crypto.createHash('sha256').update(rawKey).digest('hex');
-  const keyId = crypto.randomUUID();
-  await db.apiKey.create({ data: { id: keyId, userId, keyHash, scopes, createdAt: new Date() } });
-  return { key: rawKey, keyId }; // rawKey shown ONCE — never stored plaintext
-};
-
-const authenticateApiKey = async (req, res, next) => {
-  const raw = req.headers['x-api-key'];
-  if (!raw) return next(); // fallback to JWT auth
-  const hash = crypto.createHash('sha256').update(raw).digest('hex');
-  const apiKey = await db.apiKey.findUnique({ where: { keyHash: hash } });
-  if (!apiKey || apiKey.revokedAt) return res.status(401).json({ error: { code: 'INVALID_API_KEY' } });
-  req.user = { id: apiKey.userId, scopes: apiKey.scopes };
-  next();
-};
-
-// OAuth 2.0 with PKCE (using openid-client)
-import { generators, Issuer } from 'openid-client';
-
-const googleIssuer = await Issuer.discover('https://accounts.google.com');
-const client = new googleIssuer.Client({ client_id: GOOGLE_CLIENT_ID, redirect_uris: [CALLBACK_URL], response_types: ['code'] });
-
-app.get('/auth/google', (req, res) => {
-  const codeVerifier = generators.codeVerifier();
-  const codeChallenge = generators.codeChallenge(codeVerifier);
-  const state = generators.state();
-  req.session.codeVerifier = codeVerifier;
-  req.session.state = state;
-  res.redirect(client.authorizationUrl({ scope: 'openid email profile', code_challenge: codeChallenge, code_challenge_method: 'S256', state }));
-});
-
-app.get('/auth/google/callback', async (req, res) => {
-  const params = client.callbackParams(req);
-  const tokens = await client.callback(CALLBACK_URL, params, { code_verifier: req.session.codeVerifier, state: req.session.state });
-  const claims = tokens.claims(); // validated: iss, aud, exp
-  const user = await userRepo.upsertByProvider('google', claims.sub, claims.email);
-  // issue internal JWT...
-});
-```
+---
+name: "auth-patterns"
+pack: "@rune/backend"
+description: "Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# auth-patterns
+
+Authentication and authorization patterns — JWT, OAuth 2.0 / OIDC, passkeys/WebAuthn, session management, RBAC, API key management, MFA flows.
+
+#### Workflow
+
+**Step 1 — Detect auth implementation**
+Use Grep to find auth-related code: `jwt.sign`, `jwt.verify`, `bcrypt`, `passport`, `next-auth`, `lucia`, `cookie`, `session`, `Bearer`, `x-api-key`, `WebAuthn`, `passkey`. Read auth middleware and login/register handlers to understand the current approach.
+
+**Step 2 — Audit security posture**
+Check for: tokens stored in localStorage (XSS risk → use httpOnly cookies), missing refresh token rotation, JWT without expiry, password hashing without salt rounds check, missing CSRF protection on cookie-based auth, hardcoded secrets. Flag each with severity and specific fix.
+
+**Step 3 — Emit secure auth flow**
+Based on detected framework (Express, Fastify, Next.js, etc.), emit the corrected auth flow: access token (short-lived, 15min) + refresh token (httpOnly cookie, 7d, rotation on use), proper password hashing (bcrypt rounds ≥ 12), RBAC middleware with role hierarchy.
+
+**Step 4 — OAuth 2.0 / OIDC integration**
+Emit OAuth 2.0 authorization code flow with PKCE (required for public clients). Support Google, GitHub, or custom OIDC provider. Key points: validate `state` parameter to prevent CSRF, validate `id_token` signature and `aud`/`iss` claims, exchange code server-side (never client-side), store provider `sub` as stable user identifier. Use `openid-client` (Node.js) or `authlib` (Python) — never hand-roll token exchange.
+
+**Step 5 — API key management and passkeys**
+For API keys: generate with `crypto.randomBytes(32).toString('base64url')`, store hashed (`sha256` is sufficient — no need for bcrypt, keys are long), never store plaintext after initial display. Add scopes (read-only vs read-write), per-key rate limits, and rotation endpoint. For passkeys/WebAuthn: emit registration and authentication ceremonies using `@simplewebauthn/server`. WebAuthn is the correct long-term replacement for passwords — emit as opt-in upgrade path. Stateless vs stateful tradeoff: JWT = stateless, easy to scale horizontally, hard to revoke; sessions = stateful, easy to revoke, requires sticky sessions or shared store (Redis). Recommend JWT + token blacklist on logout for most cases; sessions for admin panels where immediate revocation matters.
+
+#### Example
+
+```typescript
+// BEFORE: JWT in localStorage, no refresh, no expiry
+const token = jwt.sign({ userId: user.id }, SECRET);
+res.json({ token });
+
+// AFTER: short-lived access + httpOnly refresh cookie with rotation
+const accessToken = jwt.sign(
+  { sub: user.id, role: user.role },
+  ACCESS_SECRET,
+  { expiresIn: '15m' }
+);
+const refreshToken = jwt.sign(
+  { sub: user.id, jti: crypto.randomUUID() },
+  REFRESH_SECRET,
+  { expiresIn: '7d' }
+);
+await tokenStore.save(refreshToken, user.id); // rotation tracking — invalidate old on reuse
+
+res.cookie('refresh_token', refreshToken, {
+  httpOnly: true, secure: true, sameSite: 'strict',
+  maxAge: 7 * 24 * 60 * 60 * 1000,
+});
+res.json({ access_token: accessToken, expires_in: 900 });
+
+// API key management
+const generateApiKey = async (userId: string, scopes: string[]): Promise<{ key: string; keyId: string }> => {
+  const rawKey = `rk_${crypto.randomBytes(32).toString('base64url')}`;
+  const keyHash = crypto.createHash('sha256').update(rawKey).digest('hex');
+  const keyId = crypto.randomUUID();
+  await db.apiKey.create({ data: { id: keyId, userId, keyHash, scopes, createdAt: new Date() } });
+  return { key: rawKey, keyId }; // rawKey shown ONCE — never stored plaintext
+};
+
+const authenticateApiKey = async (req, res, next) => {
+  const raw = req.headers['x-api-key'];
+  if (!raw) return next(); // fallback to JWT auth
+  const hash = crypto.createHash('sha256').update(raw).digest('hex');
+  const apiKey = await db.apiKey.findUnique({ where: { keyHash: hash } });
+  if (!apiKey || apiKey.revokedAt) return res.status(401).json({ error: { code: 'INVALID_API_KEY' } });
+  req.user = { id: apiKey.userId, scopes: apiKey.scopes };
+  next();
+};
+
+// OAuth 2.0 with PKCE (using openid-client)
+import { generators, Issuer } from 'openid-client';
+
+const googleIssuer = await Issuer.discover('https://accounts.google.com');
+const client = new googleIssuer.Client({ client_id: GOOGLE_CLIENT_ID, redirect_uris: [CALLBACK_URL], response_types: ['code'] });
+
+app.get('/auth/google', (req, res) => {
+  const codeVerifier = generators.codeVerifier();
+  const codeChallenge = generators.codeChallenge(codeVerifier);
+  const state = generators.state();
+  req.session.codeVerifier = codeVerifier;
+  req.session.state = state;
+  res.redirect(client.authorizationUrl({ scope: 'openid email profile', code_challenge: codeChallenge, code_challenge_method: 'S256', state }));
+});
+
+app.get('/auth/google/callback', async (req, res) => {
+  const params = client.callbackParams(req);
+  const tokens = await client.callback(CALLBACK_URL, params, { code_verifier: req.session.codeVerifier, state: req.session.state });
+  const claims = tokens.claims(); // validated: iss, aud, exp
+  const user = await userRepo.upsertByProvider('google', claims.sub, claims.email);
+  // issue internal JWT...
+});
+```