@firebreak/vitals 2.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Vitals (Node.js)
 
-Structured healthcheck endpoints for Node.js services with shallow and deep response tiers. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js. Unauthenticated callers get a lightweight "alive" response with optional metadata; authenticated callers get full diagnostic results.
+Structured healthcheck endpoints for Node.js services with shallow and deep response tiers. Register health checks, run them concurrently with timeouts, and expose them via Express or Next.js. A configurable depth policy controls whether callers get a lightweight "alive" response or full diagnostic results.
 
 ## Install
 
@@ -19,7 +19,7 @@ npm install express   # for Express integration
 ## Quick Start (Express)
 
 ```typescript
-import { HealthcheckRegistry } from '@firebreak/vitals';
+import { HealthcheckRegistry, extractToken, verifyToken } from '@firebreak/vitals';
 import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 import { pgPoolCheck } from '@firebreak/vitals/checks/postgres';
 import { ioredisClientCheck } from '@firebreak/vitals/checks/redis';
@@ -35,7 +35,14 @@ registry.add('api', httpCheck('https://api.example.com/health'));
 const app = express();
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: {
     build: process.env.BUILD_SHA,
     buildTimestamp: process.env.BUILD_TIMESTAMP,
@@ -43,19 +50,19 @@ app.get('/vitals', createHealthcheckMiddleware({
 }));
 ```
 
-Hit `/vitals` without a token to get a shallow response:
+Hit `/vitals` without a valid token to get a shallow response:
 
 ```json
 { "status": "ok", "timestamp": "...", "build": "stg-45d76e5", "buildTimestamp": "2025-02-25T19:41:56Z" }
 ```
 
-Provide the token (`?token=...` or `Authorization: Bearer ...`) to get the full deep response with check results.
+When `resolveDepth` returns `'deep'`, the full deep response with check results is returned.
 
 ## Quick Start (Next.js)
 
 ```typescript
 // app/vitals/route.ts
-import { HealthcheckRegistry } from '@firebreak/vitals';
+import { HealthcheckRegistry, extractToken, verifyToken } from '@firebreak/vitals';
 import { createNextHandler } from '@firebreak/vitals/next';
 import { pgClientCheck } from '@firebreak/vitals/checks/postgres';
 import { httpCheck } from '@firebreak/vitals/checks/http';
@@ -69,7 +76,14 @@ registry.add('api', httpCheck(`${process.env.API_BASE_URL}/health`));
 
 export const GET = createNextHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: {
     build: process.env.BUILD_SHA,
   },
@@ -207,8 +221,14 @@ import { createHealthcheckMiddleware } from '@firebreak/vitals/express';
 
 app.get('/vitals', createHealthcheckMiddleware({
   registry,
-  token: 'my-secret-token',   // optional — omit to disable auth
-  queryParamName: 'token',     // default: 'token'
+  resolveDepth: (req) => {     // optional — omit for always-shallow
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, 'my-secret-token')) return 'deep';
+    return 'shallow';
+  },
   metadata: {                  // optional — included in shallow & deep responses
     build: 'stg-45d76e5',
   },
@@ -222,7 +242,14 @@ import { createNextHandler } from '@firebreak/vitals/next';
 
 export const GET = createNextHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: { build: process.env.BUILD_SHA },
 });
 ```
@@ -232,59 +259,52 @@ export const GET = createNextHandler({
 For other frameworks, use the generic handler directly:
 
 ```typescript
-import { createHealthcheckHandler } from '@firebreak/vitals';
+import { createHealthcheckHandler, extractToken, verifyToken } from '@firebreak/vitals';
 
 const handle = createHealthcheckHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
+  resolveDepth: (req) => {
+    const token = extractToken({
+      queryParams: req.queryParams as Record<string, string>,
+      authorizationHeader: req.authorizationHeader as string | null,
+    });
+    if (token && verifyToken(token, process.env.VITALS_TOKEN!)) return 'deep';
+    return 'shallow';
+  },
   metadata: { build: 'stg-45d76e5' },
 });
 
-// No token → shallow response
+// resolveDepth returns 'shallow' → shallow response
 const shallow = await handle({});
 // { status: 200, body: { status: 'ok', timestamp: '...', build: 'stg-45d76e5' } }
 
-// Valid token → deep response
+// resolveDepth returns 'deep' → deep response
 const deep = await handle({ queryParams: { token: '...' } });
 // { status: 200, body: { status: 'healthy', timestamp: '...', build: 'stg-45d76e5', checks: { ... } } }
 ```
 
 ### Shallow / Deep Responses
 
-When a `token` is configured, the endpoint serves two tiers from a single route:
-
-| Request | Response |
-|---------|----------|
-| No token provided | **Shallow** — `200` with `{ status: "ok", timestamp, ...metadata }` |
-| Valid token provided | **Deep** — `200`/`503` with full check results + metadata |
-| Invalid token provided | `403 Forbidden` |
-| No token configured | **Shallow** by default (see `deep` option below) |
+The endpoint serves two tiers from a single route, controlled by the `resolveDepth` option:
 
-The shallow response lets load balancers and uptime monitors confirm the process is alive without needing a secret. The deep response is a superset of shallow — it includes everything shallow returns plus the `checks` object and a real health status.
+| `resolveDepth` returns | Response |
+|------------------------|----------|
+| `'shallow'` (or omitted) | **Shallow** — `200` with `{ status: "ok", timestamp, ...metadata }` |
+| `'deep'` | **Deep** — `200`/`503` with full check results + metadata |
 
-#### The `deep` Option
+When `resolveDepth` is not provided, the handler always returns a shallow response.
 
-When no `token` is configured, the handler returns a **shallow** response by default. To expose full healthcheck results without requiring token authentication, set `deep: true`:
+The `resolveDepth` function receives the request object (`{ ip, headers, queryParams, authorizationHeader }`) and returns `'deep'` or `'shallow'` (or a promise of either). This lets you implement any depth policy — token-based, IP-based, header-based, or always-deep for internal services:
 
 ```typescript
+// Always deep (internal service behind a private network)
 createHealthcheckHandler({
   registry,
-  deep: true,   // no token → always return deep response
+  resolveDepth: () => 'deep',
 });
 ```
 
-This is useful for internal services behind a private network where token auth is unnecessary. The `deep` option defaults to `false`.
-
-> **Security note:** Using `deep: true` with an empty string token (e.g. `token: ''`) will throw an error at handler creation time. This prevents misconfigured environments (e.g. `VITALS_TOKEN=""`) from silently exposing deep healthcheck data. If you intend to run without authentication, explicitly omit the `token` option or set it to `null`.
-
-When both `token` and `deep` are set, the `token` takes precedence — callers must still authenticate to see deep results:
-
-| Configuration | No token in request | Valid token | Invalid token |
-|---------------|---------------------|-------------|---------------|
-| `token` set, `deep` unset | Shallow | Deep | 403 |
-| `token` set, `deep: true` | Shallow | Deep | 403 |
-| No `token`, `deep` unset | Shallow | — | — |
-| No `token`, `deep: true` | Deep | — | — |
+The shallow response lets load balancers and uptime monitors confirm the process is alive without needing a secret. The deep response is a superset of shallow — it includes everything shallow returns plus the `checks` object and a real health status.
 
 ### Metadata
 
@@ -293,7 +313,6 @@ Attach static key-value pairs that appear in both shallow and deep responses:
 ```typescript
 createHealthcheckHandler({
   registry,
-  token: process.env.VITALS_TOKEN,
   metadata: {
     build: 'stg-45d76e5',
     buildTimestamp: '2025-02-25T19:41:56Z',
@@ -304,29 +323,26 @@ createHealthcheckHandler({
 
 Metadata values can be `string`, `number`, or `boolean`. Keys `status`, `timestamp`, and `checks` are reserved — passing them throws at handler creation time.
 
-### Authentication
-
-Tokens can be provided via:
-- Query parameter: `?token=my-secret-token`
-- Bearer header: `Authorization: Bearer my-secret-token`
+### Utilities
 
-Tokens are compared using timing-safe SHA-256 comparison.
+`extractToken` and `verifyToken` are exported helpers for use inside your `resolveDepth` function.
 
 ```typescript
 import { verifyToken, extractToken } from '@firebreak/vitals';
 
-verifyToken('provided-token', 'expected-token'); // boolean
-
+// Extract a token from query params (?token=...) or Authorization header
 const token = extractToken({
   queryParams: { token: 'abc' },
   authorizationHeader: 'Bearer abc',
-  queryParamName: 'token',
 });
+
+// Timing-safe SHA-256 comparison
+verifyToken('provided-token', 'expected-token'); // boolean
 ```
 
 ## Response Format
 
-**Shallow response** (no token provided):
+**Shallow response** (`resolveDepth` returns `'shallow'` or is omitted):
 
 ```json
 {
@@ -337,7 +353,7 @@ const token = extractToken({
 }
 ```
 
-**Deep response** (valid token provided):
+**Deep response** (`resolveDepth` returns `'deep'`):
 
 ```json
 {
@@ -362,11 +378,10 @@ const token = extractToken({
 
 | Condition | HTTP Code | Status |
 |-----------|-----------|--------|
-| Shallow (no token) | `200` | `"ok"` |
+| Shallow | `200` | `"ok"` |
 | Deep — healthy | `200` | `"healthy"` |
 | Deep — degraded | `503` | `"degraded"` |
 | Deep — outage | `503` | `"outage"` |
-| Invalid token | `403` | — |
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebreak/vitals",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Deep healthcheck endpoints following the HEALTHCHECK_SPEC format",
   "type": "module",
   "exports": {