@lastshotlabs/bunshot 0.0.21 → 0.0.25

package/docs/sections/logging/full.md

@@ -0,0 +1,83 @@
+## Request Logging & Request IDs
+
+Every request gets a unique **request ID** — either read from the incoming `X-Request-Id` header or generated as a `crypto.randomUUID()`. The ID is:
+
+- Set on context: `c.get("requestId")`
+- Echoed back in the `X-Request-Id` response header
+- Included in error JSON responses (`{ error: "...", requestId: "..." }`)
+- Included in audit log entries (when audit logging is enabled)
+
+### Structured JSON Logging
+
+By default, every request/response is logged as structured JSON (replacing Hono's built-in text logger):
+
+```json
+{
+  "level": "info",
+  "time": 1710000000000,
+  "msg": "GET /api/users 200",
+  "requestId": "550e8400-e29b-41d4-a716-446655440000",
+  "method": "GET",
+  "path": "/api/users",
+  "statusCode": 200,
+  "responseTime": 12.34,
+  "ip": "203.0.113.42",
+  "userAgent": "Mozilla/5.0...",
+  "userId": "user-123",
+  "sessionId": "sess-456",
+  "tenantId": "tenant-789"
+}
+```
+
+Status codes map to log levels: 5xx → `"error"`, 4xx → `"warn"`, else `"info"`.
+
+Default excluded paths: `/health`, `/docs`, `/openapi.json` (prefix matching).
+
+### Configuration
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  logging: {
+    // Default: true. Set false to disable logging entirely (no fallback to Hono's text logger)
+    enabled: true,
+    // Minimum level to emit — "info" (default), "warn", or "error"
+    level: "info",
+    // Custom log handler — plug in Pino, Datadog, etc.
+    onLog: (entry) => pino.info(entry),
+    // Paths to exclude (prefix matching for strings, .test() for RegExp)
+    excludePaths: ["/health", "/docs", "/openapi.json", /^\/internal\//],
+    // HTTP methods to exclude
+    excludeMethods: ["OPTIONS"],
+  },
+});
+```
+
+### Using Request IDs
+
+Access the request ID in any route or middleware:
+
+```ts
+router.get("/api/example", (c) => {
+  const requestId = c.get("requestId");
+  // Pass to downstream services, include in logs, etc.
+  return c.json({ requestId, data: "..." });
+});
+```
+
+### Exports
+
+```ts
+import {
+  requestId,         // middleware — generates/propagates X-Request-Id
+  requestLogger,     // middleware — structured JSON request logging
+  HEADER_REQUEST_ID, // "x-request-id" constant
+} from "@lastshotlabs/bunshot";
+
+import type {
+  RequestLogEntry,      // shape of each log entry
+  RequestLoggerOptions, // options for requestLogger()
+  LogLevel,             // "info" | "warn" | "error"
+  LoggingConfig,        // config shape for createApp/createServer
+} from "@lastshotlabs/bunshot";
+```

package/docs/sections/metrics/full.md

@@ -0,0 +1,127 @@
+## Prometheus Metrics
+
+Opt-in `/metrics` endpoint that Prometheus can scrape. Tracks request counts, latency distributions, and optionally BullMQ queue depths.
+
+### Quick Start
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  metrics: {
+    enabled: true,
+  },
+});
+```
+
+`GET /metrics` now returns Prometheus text exposition format:
+
+```
+# HELP http_requests_total Total http requests total
+# TYPE http_requests_total counter
+http_requests_total{method="GET",path="/users",status="200"} 42
+
+# HELP http_request_duration_seconds http request duration seconds
+# TYPE http_request_duration_seconds histogram
+http_request_duration_seconds_bucket{method="GET",path="/users",le="0.005"} 10
+...
+http_request_duration_seconds_bucket{method="GET",path="/users",le="+Inf"} 42
+http_request_duration_seconds_sum{method="GET",path="/users"} 12.345
+http_request_duration_seconds_count{method="GET",path="/users"} 42
+```
+
+### Configuration
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  metrics: {
+    enabled: true,
+    // Auth for /metrics — "none" (default), "userAuth", or custom middleware stack
+    auth: "userAuth",
+    // Paths excluded from collection (prefix matching for strings, .test() for RegExp)
+    excludePaths: ["/metrics", "/health", "/docs", "/openapi.json"], // defaults
+    // Custom path normalizer (default collapses UUIDs, ObjectIDs, numeric segments to :id)
+    normalizePath: (path) => path.replace(/\/[0-9]+/g, "/:id"),
+    // BullMQ queue names to report depth gauges for (requires Redis)
+    queues: ["email", "reports"],
+  },
+});
+```
+
+### Path Normalization
+
+To prevent high-cardinality labels, dynamic path segments are normalized by default:
+
+| Pattern | Example | Normalized |
+|---------|---------|------------|
+| UUID | `/users/550e8400-e29b-41d4-a716-446655440000` | `/users/:id` |
+| MongoDB ObjectID | `/items/507f1f77bcf86cd799439011` | `/items/:id` |
+| Numeric segment | `/posts/123/comments` | `/posts/:id/comments` |
+| Short slug | `/api/v2/users` | `/api/v2/users` (unchanged) |
+
+Override with `metrics.normalizePath` for custom normalization logic.
+
+### Multi-Tenancy
+
+When tenancy is configured, a `tenant` label is automatically added to all metrics:
+
+```
+http_requests_total{method="GET",path="/data",status="200",tenant="acme"} 15
+```
+
+### BullMQ Queue Depths
+
+When `metrics.queues` is set, a `bullmq_queue_depth` gauge is registered and queried on each scrape:
+
+```
+bullmq_queue_depth{queue="email",state="waiting"} 5
+bullmq_queue_depth{queue="email",state="active"} 2
+bullmq_queue_depth{queue="email",state="delayed"} 0
+bullmq_queue_depth{queue="email",state="failed"} 1
+```
+
+Queue instances are lazily cached and reused across scrapes. Call `closeMetricsQueues()` during graceful shutdown to clean up Redis connections.
+
+### Error Handling
+
+Gauge callback errors never cause a 500. If a gauge callback fails, the gauge is omitted from that scrape and an internal error counter is incremented:
+
+```
+bunshot_gauge_errors_total{gauge="bullmq_queue_depth"} 1
+```
+
+This counter is always present when metrics are enabled so you can alert on scrape failures.
+
+### Security
+
+Auth defaults to `"none"` for easy adoption. A production warning is logged when metrics are enabled without auth. **Recommended:** Lock down `/metrics` in production since it exposes operational details (error rates, queue depths, tenant activity patterns).
+
+```ts
+metrics: {
+  enabled: true,
+  auth: [userAuth, requireRole("admin")], // custom middleware stack
+}
+```
+
+### Self-Exclusion
+
+`/metrics` is excluded from its own collection and from request logging by default, so scraping doesn't inflate your metrics.
+
+### Exports
+
+```ts
+import {
+  metricsCollector,       // middleware — collects request metrics
+  incrementCounter,       // manually increment a counter
+  observeHistogram,       // manually observe a histogram value
+  registerGaugeCallback,  // register an async gauge callback
+  serializeMetrics,       // produce Prometheus text format
+  resetMetrics,           // clear all metrics (for tests)
+  closeMetricsQueues,     // close cached BullMQ queue instances
+} from "@lastshotlabs/bunshot";
+
+import type {
+  MetricsConfig,             // config shape for createApp/createServer
+  MetricsMiddlewareOptions,  // options for metricsCollector()
+} from "@lastshotlabs/bunshot";
+```

package/docs/sections/oauth/full.md

@@ -1,189 +1,189 @@
-## Social Login (OAuth)
-
-Pass `auth.oauth.providers` to `createServer` to enable Google, Apple, Microsoft, and/or GitHub sign-in. Routes are mounted automatically for each configured provider.
-
-```ts
-await createServer({
-  routesDir: import.meta.dir + "/routes",
-  app: { name: "My App", version: "1.0.0" },
-  auth: {
-    oauth: {
-      postRedirect: "/lobby",  // where to redirect after login (default: "/")
-      providers: {
-        google: {
-          clientId: process.env.GOOGLE_CLIENT_ID!,
-          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-          redirectUri: "https://myapp.com/auth/google/callback",
-        },
-        apple: {
-          clientId: process.env.APPLE_CLIENT_ID!,       // Services ID, e.g. "com.myapp.auth"
-          teamId: process.env.APPLE_TEAM_ID!,
-          keyId: process.env.APPLE_KEY_ID!,
-          privateKey: process.env.APPLE_PRIVATE_KEY!,   // PEM string
-          redirectUri: "https://myapp.com/auth/apple/callback",
-        },
-        microsoft: {
-          tenantId: process.env.MICROSOFT_TENANT_ID!,   // "common", "organizations", "consumers", or tenant GUID
-          clientId: process.env.MICROSOFT_CLIENT_ID!,
-          clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
-          redirectUri: "https://myapp.com/auth/microsoft/callback",
-        },
-        github: {
-          clientId: process.env.GITHUB_CLIENT_ID!,
-          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-          redirectUri: "https://myapp.com/auth/github/callback",
-        },
-      },
-    },
-  },
-});
-```
-
-### Routes mounted automatically
-
-| Provider | Initiate login | Callback | Link to existing account | Unlink |
-|---|---|---|---|---|
-| Google | `GET /auth/google` | `GET /auth/google/callback` | `GET /auth/google/link` | `DELETE /auth/google/link` |
-| Apple | `GET /auth/apple` | `POST /auth/apple/callback` | `GET /auth/apple/link` | — |
-| Microsoft | `GET /auth/microsoft` | `GET /auth/microsoft/callback` | `GET /auth/microsoft/link` | `DELETE /auth/microsoft/link` |
-| GitHub | `GET /auth/github` | `GET /auth/github/callback` | `GET /auth/github/link` | `DELETE /auth/github/link` |
-
-> Apple sends its callback as a **POST** with form data. Your server must be publicly reachable and the redirect URI must be registered in the Apple developer console.
-
-> **Microsoft `tenantId` options:** `"common"` accepts any Microsoft account (personal + work/school), `"organizations"` accepts work/school accounts only, `"consumers"` accepts personal accounts only, or pass a specific tenant GUID to restrict to a single Azure AD tenant (recommended for company SSO).
-
-> **GitHub:** Create an OAuth App (not a GitHub App) at [github.com/settings/developers](https://github.com/settings/developers). The `user:email` scope is requested to retrieve the user's verified email address, since the primary `/user` endpoint may not return it for users with private email settings.
-
-Additionally, a shared code exchange endpoint is always mounted:
-
-| Endpoint | Purpose |
-|---|---|
-| `POST /auth/oauth/exchange` | Exchange one-time authorization code for session token |
-
-### Flow
-
-1. Client navigates to `GET /auth/google` (or `/auth/apple`, `/auth/microsoft`, `/auth/github`)
-2. Package redirects to the provider's OAuth page
-3. Provider redirects (or POSTs) back to the callback URL
-4. Package exchanges the code, fetches the user profile, and calls `authAdapter.findOrCreateByProvider`
-5. A session is created and a **one-time authorization code** is generated
-6. User is redirected to `auth.oauth.postRedirect?code=<one-time-code>`
-7. Client exchanges the code for a session token via `POST /auth/oauth/exchange`
-
-> **Security:** The JWT is never exposed in the redirect URL. The one-time code expires after 60 seconds and can only be used once, preventing token leakage via browser history, server logs, or referrer headers.
-
-#### Code exchange
-
-After the OAuth redirect, the client must exchange the one-time code for a session token:
-
-```ts
-// Client-side
-const res = await fetch("/auth/oauth/exchange", {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ code: new URLSearchParams(location.search).get("code") }),
-});
-const { token, userId, email, refreshToken } = await res.json();
-```
-
-The exchange endpoint sets session cookies automatically for browser clients. Mobile/SPA clients can use the JSON response directly. Rate limited to 20 requests per minute per IP.
-
-| Field | Description |
-|---|---|
-| `token` | Session JWT |
-| `userId` | Authenticated user ID |
-| `email` | User email (if available) |
-| `refreshToken` | Refresh token (only when `auth.refreshTokens` is configured) |
-
-### Redirect URL validation
-
-Pass `auth.oauth.allowedRedirectUrls` to restrict where OAuth callbacks can redirect:
-
-```ts
-auth: {
-  oauth: {
-    postRedirect: "/dashboard",
-    allowedRedirectUrls: ["https://myapp.com", "https://staging.myapp.com"],
-    providers: { ... },
-  },
-}
-```
-
-When configured, the `postRedirect` value is validated against the allowlist at startup. If omitted, any redirect URL is accepted (not recommended for production).
-
-### User storage
-
-The default `mongoAuthAdapter` stores social users in `AuthUser` with a `providerIds` field (e.g. `["google:1234567890"]`). If no existing provider key is found, a new account is created — emails are never auto-linked. To connect a social identity to an existing credential account the user must explicitly use the link flow below.
-
-**Email conflict handling:** If a user attempts to sign in via Google (or Apple/Microsoft/GitHub) and the email returned by the provider already belongs to a credential-based account, `findOrCreateByProvider` throws `HttpError(409, ...)`. The OAuth callback catches this and redirects to `auth.oauth.postRedirect?error=<message>` so the client can display a helpful prompt (e.g. "An account with this email already exists — sign in with your password, then link Google from your account settings.").
-
-To support social login with a custom adapter, implement `findOrCreateByProvider`:
-
-```ts
-const myAdapter: AuthAdapter = {
-  findByEmail: ...,
-  create: ...,
-  async findOrCreateByProvider(provider, providerId, profile) {
-    // find or upsert user by provider + providerId
-    // return { id: string }
-  },
-};
-```
-
-### Linking a provider to an existing account
-
-A logged-in user can link their account to a Google, Apple, Microsoft, or GitHub identity by navigating to the link route. This is the only way to associate a social login with an existing credential account — email matching is intentionally not done automatically.
-
-```
-GET /auth/google/link      (requires active session via cookie)
-GET /auth/apple/link       (requires active session via cookie)
-GET /auth/microsoft/link   (requires active session via cookie)
-GET /auth/github/link      (requires active session via cookie)
-```
-
-The link flow:
-1. User is already logged in (session cookie set)
-2. Client navigates to `/auth/google/link`
-3. User completes Google OAuth as normal
-4. On callback, instead of creating a new session, the Google identity is added to their existing account
-5. User is redirected to `auth.oauth.postRedirect?linked=google`
-
-To support linking with a custom adapter, implement `linkProvider`:
-
-```ts
-const myAdapter: AuthAdapter = {
-  // ...
-  async linkProvider(userId, provider, providerId) {
-    const key = `${provider}:${providerId}`;
-    await db.update(users)
-      .set({ providerIds: sql`array_append(provider_ids, ${key})` })
-      .where(eq(users.id, userId));
-  },
-};
-```
-
-### Unlinking a provider
-
-A logged-in user can remove a linked Google, Microsoft, or GitHub identity via:
-
-```
-DELETE /auth/google/link      (requires active session via cookie)
-DELETE /auth/microsoft/link   (requires active session via cookie)
-DELETE /auth/github/link      (requires active session via cookie)
-```
-
-Returns `204 No Content` on success. All `google:*` entries are removed from the user's `providerIds`.
-
-To support unlinking with a custom adapter, implement `unlinkProvider`:
-
-```ts
-const myAdapter: AuthAdapter = {
-  // ...
-  async unlinkProvider(userId, provider) {
-    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
-    if (!user) throw new HttpError(404, "User not found");
-    const filtered = user.providerIds.filter((id: string) => !id.startsWith(`${provider}:`));
-    await db.update(users).set({ providerIds: filtered }).where(eq(users.id, userId));
-  },
-};
-```
+### Social Login (OAuth)
+
+Pass `auth.oauth.providers` to `createServer` to enable Google, Apple, Microsoft, and/or GitHub sign-in. Routes are mounted automatically for each configured provider.
+
+```ts
+await createServer({
+  routesDir: import.meta.dir + "/routes",
+  app: { name: "My App", version: "1.0.0" },
+  auth: {
+    oauth: {
+      postRedirect: "/lobby",  // where to redirect after login (default: "/")
+      providers: {
+        google: {
+          clientId: process.env.GOOGLE_CLIENT_ID!,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/google/callback",
+        },
+        apple: {
+          clientId: process.env.APPLE_CLIENT_ID!,       // Services ID, e.g. "com.myapp.auth"
+          teamId: process.env.APPLE_TEAM_ID!,
+          keyId: process.env.APPLE_KEY_ID!,
+          privateKey: process.env.APPLE_PRIVATE_KEY!,   // PEM string
+          redirectUri: "https://myapp.com/auth/apple/callback",
+        },
+        microsoft: {
+          tenantId: process.env.MICROSOFT_TENANT_ID!,   // "common", "organizations", "consumers", or tenant GUID
+          clientId: process.env.MICROSOFT_CLIENT_ID!,
+          clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/microsoft/callback",
+        },
+        github: {
+          clientId: process.env.GITHUB_CLIENT_ID!,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+          redirectUri: "https://myapp.com/auth/github/callback",
+        },
+      },
+    },
+  },
+});
+```
+
+#### Routes mounted automatically
+
+| Provider | Initiate login | Callback | Link to existing account | Unlink |
+|---|---|---|---|---|
+| Google | `GET /auth/google` | `GET /auth/google/callback` | `GET /auth/google/link` | `DELETE /auth/google/link` |
+| Apple | `GET /auth/apple` | `POST /auth/apple/callback` | `GET /auth/apple/link` | — |
+| Microsoft | `GET /auth/microsoft` | `GET /auth/microsoft/callback` | `GET /auth/microsoft/link` | `DELETE /auth/microsoft/link` |
+| GitHub | `GET /auth/github` | `GET /auth/github/callback` | `GET /auth/github/link` | `DELETE /auth/github/link` |
+
+> Apple sends its callback as a **POST** with form data. Your server must be publicly reachable and the redirect URI must be registered in the Apple developer console.
+
+> **Microsoft `tenantId` options:** `"common"` accepts any Microsoft account (personal + work/school), `"organizations"` accepts work/school accounts only, `"consumers"` accepts personal accounts only, or pass a specific tenant GUID to restrict to a single Azure AD tenant (recommended for company SSO).
+
+> **GitHub:** Create an OAuth App (not a GitHub App) at [github.com/settings/developers](https://github.com/settings/developers). The `user:email` scope is requested to retrieve the user's verified email address, since the primary `/user` endpoint may not return it for users with private email settings.
+
+Additionally, a shared code exchange endpoint is always mounted:
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /auth/oauth/exchange` | Exchange one-time authorization code for session token |
+
+#### Flow
+
+1. Client navigates to `GET /auth/google` (or `/auth/apple`, `/auth/microsoft`, `/auth/github`)
+2. Package redirects to the provider's OAuth page
+3. Provider redirects (or POSTs) back to the callback URL
+4. Package exchanges the code, fetches the user profile, and calls `authAdapter.findOrCreateByProvider`
+5. A session is created and a **one-time authorization code** is generated
+6. User is redirected to `auth.oauth.postRedirect?code=<one-time-code>`
+7. Client exchanges the code for a session token via `POST /auth/oauth/exchange`
+
+> **Security:** The JWT is never exposed in the redirect URL. The one-time code expires after 60 seconds and can only be used once, preventing token leakage via browser history, server logs, or referrer headers.
+
+##### Code exchange
+
+After the OAuth redirect, the client must exchange the one-time code for a session token:
+
+```ts
+// Client-side
+const res = await fetch("/auth/oauth/exchange", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ code: new URLSearchParams(location.search).get("code") }),
+});
+const { token, userId, email, refreshToken } = await res.json();
+```
+
+The exchange endpoint sets session cookies automatically for browser clients. Mobile/SPA clients can use the JSON response directly. Rate limited to 20 requests per minute per IP.
+
+| Field | Description |
+|---|---|
+| `token` | Session JWT |
+| `userId` | Authenticated user ID |
+| `email` | User email (if available) |
+| `refreshToken` | Refresh token (only when `auth.refreshTokens` is configured) |
+
+#### Redirect URL validation
+
+Pass `auth.oauth.allowedRedirectUrls` to restrict where OAuth callbacks can redirect:
+
+```ts
+auth: {
+  oauth: {
+    postRedirect: "/dashboard",
+    allowedRedirectUrls: ["https://myapp.com", "https://staging.myapp.com"],
+    providers: { ... },
+  },
+}
+```
+
+When configured, the `postRedirect` value is validated against the allowlist at startup. If omitted, any redirect URL is accepted (not recommended for production).
+
+#### User storage
+
+The default `mongoAuthAdapter` stores social users in `AuthUser` with a `providerIds` field (e.g. `["google:1234567890"]`). If no existing provider key is found, a new account is created — emails are never auto-linked. To connect a social identity to an existing credential account the user must explicitly use the link flow below.
+
+**Email conflict handling:** If a user attempts to sign in via Google (or Apple/Microsoft/GitHub) and the email returned by the provider already belongs to a credential-based account, `findOrCreateByProvider` throws `HttpError(409, ...)`. The OAuth callback catches this and redirects to `auth.oauth.postRedirect?error=<message>` so the client can display a helpful prompt (e.g. "An account with this email already exists — sign in with your password, then link Google from your account settings.").
+
+To support social login with a custom adapter, implement `findOrCreateByProvider`:
+
+```ts
+const myAdapter: AuthAdapter = {
+  findByEmail: ...,
+  create: ...,
+  async findOrCreateByProvider(provider, providerId, profile) {
+    // find or upsert user by provider + providerId
+    // return { id: string }
+  },
+};
+```
+
+#### Linking a provider to an existing account
+
+A logged-in user can link their account to a Google, Apple, Microsoft, or GitHub identity by navigating to the link route. This is the only way to associate a social login with an existing credential account — email matching is intentionally not done automatically.
+
+```
+GET /auth/google/link      (requires active session via cookie)
+GET /auth/apple/link       (requires active session via cookie)
+GET /auth/microsoft/link   (requires active session via cookie)
+GET /auth/github/link      (requires active session via cookie)
+```
+
+The link flow:
+1. User is already logged in (session cookie set)
+2. Client navigates to `/auth/google/link`
+3. User completes Google OAuth as normal
+4. On callback, instead of creating a new session, the Google identity is added to their existing account
+5. User is redirected to `auth.oauth.postRedirect?linked=google`
+
+To support linking with a custom adapter, implement `linkProvider`:
+
+```ts
+const myAdapter: AuthAdapter = {
+  // ...
+  async linkProvider(userId, provider, providerId) {
+    const key = `${provider}:${providerId}`;
+    await db.update(users)
+      .set({ providerIds: sql`array_append(provider_ids, ${key})` })
+      .where(eq(users.id, userId));
+  },
+};
+```
+
+#### Unlinking a provider
+
+A logged-in user can remove a linked Google, Microsoft, or GitHub identity via:
+
+```
+DELETE /auth/google/link      (requires active session via cookie)
+DELETE /auth/microsoft/link   (requires active session via cookie)
+DELETE /auth/github/link      (requires active session via cookie)
+```
+
+Returns `204 No Content` on success. All `google:*` entries are removed from the user's `providerIds`.
+
+To support unlinking with a custom adapter, implement `unlinkProvider`:
+
+```ts
+const myAdapter: AuthAdapter = {
+  // ...
+  async unlinkProvider(userId, provider) {
+    const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
+    if (!user) throw new HttpError(404, "User not found");
+    const filtered = user.providerIds.filter((id: string) => !id.startsWith(`${provider}:`));
+    await db.update(users).set({ providerIds: filtered }).where(eq(users.id, userId));
+  },
+};
+```

package/docs/sections/oauth/overview.md

@@ -1,4 +1,4 @@
-## Social Login (OAuth)
+### Social Login (OAuth)
 
 Pass `auth.oauth.providers` to enable Google, Apple, Microsoft, and/or GitHub sign-in. Routes are mounted automatically for each configured provider.