@firebreak/vitals 1.3.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/dist/handler-BvjN4Ot9.d.ts

@@ -0,0 +1,20 @@
+import { b as HealthcheckRegistry, H as HealthcheckResponseJson } from './core-Bee03bJm.js';
+
+type ResolveDepthFn = (req: Record<string, unknown>) => 'deep' | 'shallow' | Promise<'deep' | 'shallow'>;
+interface HealthcheckHandlerOptions {
+    registry: HealthcheckRegistry;
+    resolveDepth?: ResolveDepthFn;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface ShallowResponseJson {
+    status: 'ok';
+    timestamp: string;
+    [key: string]: string | number | boolean;
+}
+interface HealthcheckHandlerResult {
+    status: number;
+    body: HealthcheckResponseJson | ShallowResponseJson;
+}
+declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: Record<string, unknown>) => Promise<HealthcheckHandlerResult>;
+
+export { type HealthcheckHandlerOptions as H, type ResolveDepthFn as R, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, createHealthcheckHandler as c };

package/dist/handler-TZOgZvY7.d.cts

@@ -0,0 +1,20 @@
+import { b as HealthcheckRegistry, H as HealthcheckResponseJson } from './core-Bee03bJm.cjs';
+
+type ResolveDepthFn = (req: Record<string, unknown>) => 'deep' | 'shallow' | Promise<'deep' | 'shallow'>;
+interface HealthcheckHandlerOptions {
+    registry: HealthcheckRegistry;
+    resolveDepth?: ResolveDepthFn;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface ShallowResponseJson {
+    status: 'ok';
+    timestamp: string;
+    [key: string]: string | number | boolean;
+}
+interface HealthcheckHandlerResult {
+    status: number;
+    body: HealthcheckResponseJson | ShallowResponseJson;
+}
+declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: Record<string, unknown>) => Promise<HealthcheckHandlerResult>;
+
+export { type HealthcheckHandlerOptions as H, type ResolveDepthFn as R, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, createHealthcheckHandler as c };

package/dist/index.cjs

@@ -220,56 +220,36 @@ function extractToken(options) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
-  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
-  if (deep && isEmptyToken) {
-    throw new Error(
-      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
-    );
-  }
-  const token = rawToken == null || isEmptyToken ? null : rawToken;
+  const { registry, resolveDepth, metadata = {} } = options;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
     }
   }
   return async (req) => {
-    if (token === null) {
-      if (deep) {
-        const response2 = await registry.run();
-        return {
-          status: httpStatusCode(response2.status),
-          body: { ...metadata, ...toJson(response2) }
-        };
+    let depth = "shallow";
+    if (resolveDepth) {
+      try {
+        const result = await resolveDepth(req);
+        if (result === "deep" || result === "shallow") {
+          depth = result;
+        }
+      } catch {
       }
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
-      };
-      return { status: 200, body };
     }
-    const provided = extractToken({
-      queryParams: req.queryParams,
-      authorizationHeader: req.authorizationHeader,
-      queryParamName
-    });
-    if (provided === null) {
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
+    if (depth === "deep") {
+      const response = await registry.run();
+      return {
+        status: httpStatusCode(response.status),
+        body: { ...metadata, ...toJson(response) }
       };
-      return { status: 200, body };
-    }
-    if (!verifyToken(provided, token)) {
-      return { status: 403, body: { error: "Forbidden" } };
     }
-    const response = await registry.run();
-    return {
-      status: httpStatusCode(response.status),
-      body: { ...metadata, ...toJson(response) }
+    const body = {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
     };
+    return { status: 200, body };
   };
 }
 

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { H as HealthcheckResponseJson } from './core-Bee03bJm.cjs';
 export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, b as HealthcheckRegistry, c as HealthcheckResponse, S as Status, d as StatusLabel, e as StatusValue, f as SyncCheckFn, h as httpStatusCode, s as statusFromString, g as statusToLabel, i as syncCheck, t as toJson } from './core-Bee03bJm.cjs';
-import { S as ShallowResponseJson } from './handler-COH7lot9.cjs';
-export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, b as HealthcheckRequest, c as createHealthcheckHandler } from './handler-COH7lot9.cjs';
+import { S as ShallowResponseJson } from './handler-TZOgZvY7.cjs';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-TZOgZvY7.cjs';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { H as HealthcheckResponseJson } from './core-Bee03bJm.js';
 export { A as AsyncCheckFn, C as CheckInput, a as CheckResult, b as HealthcheckRegistry, c as HealthcheckResponse, S as Status, d as StatusLabel, e as StatusValue, f as SyncCheckFn, h as httpStatusCode, s as statusFromString, g as statusToLabel, i as syncCheck, t as toJson } from './core-Bee03bJm.js';
-import { S as ShallowResponseJson } from './handler-CVYUad84.js';
-export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, b as HealthcheckRequest, c as createHealthcheckHandler } from './handler-CVYUad84.js';
+import { S as ShallowResponseJson } from './handler-BvjN4Ot9.js';
+export { H as HealthcheckHandlerOptions, a as HealthcheckHandlerResult, R as ResolveDepthFn, c as createHealthcheckHandler } from './handler-BvjN4Ot9.js';
 
 declare function verifyToken(provided: string, expected: string): boolean;
 declare function extractToken(options: {

package/dist/index.mjs

@@ -184,56 +184,36 @@ function extractToken(options) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
-  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
-  if (deep && isEmptyToken) {
-    throw new Error(
-      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
-    );
-  }
-  const token = rawToken == null || isEmptyToken ? null : rawToken;
+  const { registry, resolveDepth, metadata = {} } = options;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
     }
   }
   return async (req) => {
-    if (token === null) {
-      if (deep) {
-        const response2 = await registry.run();
-        return {
-          status: httpStatusCode(response2.status),
-          body: { ...metadata, ...toJson(response2) }
-        };
+    let depth = "shallow";
+    if (resolveDepth) {
+      try {
+        const result = await resolveDepth(req);
+        if (result === "deep" || result === "shallow") {
+          depth = result;
+        }
+      } catch {
       }
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
-      };
-      return { status: 200, body };
     }
-    const provided = extractToken({
-      queryParams: req.queryParams,
-      authorizationHeader: req.authorizationHeader,
-      queryParamName
-    });
-    if (provided === null) {
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
+    if (depth === "deep") {
+      const response = await registry.run();
+      return {
+        status: httpStatusCode(response.status),
+        body: { ...metadata, ...toJson(response) }
       };
-      return { status: 200, body };
-    }
-    if (!verifyToken(provided, token)) {
-      return { status: 403, body: { error: "Forbidden" } };
     }
-    const response = await registry.run();
-    return {
-      status: httpStatusCode(response.status),
-      body: { ...metadata, ...toJson(response) }
+    const body = {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
     };
+    return { status: 200, body };
   };
 }
 

package/dist/integrations/express.cjs

@@ -24,28 +24,6 @@ __export(express_exports, {
 });
 module.exports = __toCommonJS(express_exports);
 
-// src/auth.ts
-var import_node_crypto = require("crypto");
-function verifyToken(provided, expected) {
-  if (!provided || !expected) return false;
-  const providedHash = (0, import_node_crypto.createHash)("sha256").update(provided).digest();
-  const expectedHash = (0, import_node_crypto.createHash)("sha256").update(expected).digest();
-  return (0, import_node_crypto.timingSafeEqual)(providedHash, expectedHash);
-}
-function extractToken(options) {
-  const { queryParams, authorizationHeader, queryParamName = "token" } = options;
-  if (queryParams) {
-    const value = queryParams[queryParamName];
-    const str = Array.isArray(value) ? value[0] : value;
-    if (str) return str;
-  }
-  if (authorizationHeader?.startsWith("Bearer ")) {
-    const token = authorizationHeader.slice("Bearer ".length);
-    if (token) return token;
-  }
-  return null;
-}
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -83,56 +61,36 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
-  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
-  if (deep && isEmptyToken) {
-    throw new Error(
-      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
-    );
-  }
-  const token = rawToken == null || isEmptyToken ? null : rawToken;
+  const { registry, resolveDepth, metadata = {} } = options;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
     }
   }
   return async (req) => {
-    if (token === null) {
-      if (deep) {
-        const response2 = await registry.run();
-        return {
-          status: httpStatusCode(response2.status),
-          body: { ...metadata, ...toJson(response2) }
-        };
+    let depth = "shallow";
+    if (resolveDepth) {
+      try {
+        const result = await resolveDepth(req);
+        if (result === "deep" || result === "shallow") {
+          depth = result;
+        }
+      } catch {
       }
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
-      };
-      return { status: 200, body };
     }
-    const provided = extractToken({
-      queryParams: req.queryParams,
-      authorizationHeader: req.authorizationHeader,
-      queryParamName
-    });
-    if (provided === null) {
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
+    if (depth === "deep") {
+      const response = await registry.run();
+      return {
+        status: httpStatusCode(response.status),
+        body: { ...metadata, ...toJson(response) }
       };
-      return { status: 200, body };
-    }
-    if (!verifyToken(provided, token)) {
-      return { status: 403, body: { error: "Forbidden" } };
     }
-    const response = await registry.run();
-    return {
-      status: httpStatusCode(response.status),
-      body: { ...metadata, ...toJson(response) }
+    const body = {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
     };
+    return { status: 200, body };
   };
 }
 
@@ -376,6 +334,8 @@ function createHealthcheckMiddleware(options) {
   return async (req, res) => {
     try {
       const result = await handle({
+        ip: req.ip,
+        headers: req.headers,
         queryParams: req.query,
         authorizationHeader: req.headers.authorization ?? null
       });

package/dist/integrations/express.d.cts

@@ -1,5 +1,5 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-COH7lot9.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-TZOgZvY7.cjs';
 import '../core-Bee03bJm.cjs';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;

package/dist/integrations/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler } from 'express';
-import { H as HealthcheckHandlerOptions } from '../handler-CVYUad84.js';
+import { H as HealthcheckHandlerOptions } from '../handler-BvjN4Ot9.js';
 import '../core-Bee03bJm.js';
 
 type HealthcheckMiddlewareOptions = HealthcheckHandlerOptions;

package/dist/integrations/express.mjs

@@ -1,25 +1,3 @@
-// src/auth.ts
-import { createHash, timingSafeEqual } from "crypto";
-function verifyToken(provided, expected) {
-  if (!provided || !expected) return false;
-  const providedHash = createHash("sha256").update(provided).digest();
-  const expectedHash = createHash("sha256").update(expected).digest();
-  return timingSafeEqual(providedHash, expectedHash);
-}
-function extractToken(options) {
-  const { queryParams, authorizationHeader, queryParamName = "token" } = options;
-  if (queryParams) {
-    const value = queryParams[queryParamName];
-    const str = Array.isArray(value) ? value[0] : value;
-    if (str) return str;
-  }
-  if (authorizationHeader?.startsWith("Bearer ")) {
-    const token = authorizationHeader.slice("Bearer ".length);
-    if (token) return token;
-  }
-  return null;
-}
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -57,56 +35,36 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
-  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
-  if (deep && isEmptyToken) {
-    throw new Error(
-      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
-    );
-  }
-  const token = rawToken == null || isEmptyToken ? null : rawToken;
+  const { registry, resolveDepth, metadata = {} } = options;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
     }
   }
   return async (req) => {
-    if (token === null) {
-      if (deep) {
-        const response2 = await registry.run();
-        return {
-          status: httpStatusCode(response2.status),
-          body: { ...metadata, ...toJson(response2) }
-        };
+    let depth = "shallow";
+    if (resolveDepth) {
+      try {
+        const result = await resolveDepth(req);
+        if (result === "deep" || result === "shallow") {
+          depth = result;
+        }
+      } catch {
       }
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
-      };
-      return { status: 200, body };
     }
-    const provided = extractToken({
-      queryParams: req.queryParams,
-      authorizationHeader: req.authorizationHeader,
-      queryParamName
-    });
-    if (provided === null) {
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
+    if (depth === "deep") {
+      const response = await registry.run();
+      return {
+        status: httpStatusCode(response.status),
+        body: { ...metadata, ...toJson(response) }
       };
-      return { status: 200, body };
-    }
-    if (!verifyToken(provided, token)) {
-      return { status: 403, body: { error: "Forbidden" } };
     }
-    const response = await registry.run();
-    return {
-      status: httpStatusCode(response.status),
-      body: { ...metadata, ...toJson(response) }
+    const body = {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
     };
+    return { status: 200, body };
   };
 }
 
@@ -350,6 +308,8 @@ function createHealthcheckMiddleware(options) {
   return async (req, res) => {
     try {
       const result = await handle({
+        ip: req.ip,
+        headers: req.headers,
         queryParams: req.query,
         authorizationHeader: req.headers.authorization ?? null
       });

package/dist/integrations/next.cjs

@@ -24,28 +24,6 @@ __export(next_exports, {
 });
 module.exports = __toCommonJS(next_exports);
 
-// src/auth.ts
-var import_node_crypto = require("crypto");
-function verifyToken(provided, expected) {
-  if (!provided || !expected) return false;
-  const providedHash = (0, import_node_crypto.createHash)("sha256").update(provided).digest();
-  const expectedHash = (0, import_node_crypto.createHash)("sha256").update(expected).digest();
-  return (0, import_node_crypto.timingSafeEqual)(providedHash, expectedHash);
-}
-function extractToken(options) {
-  const { queryParams, authorizationHeader, queryParamName = "token" } = options;
-  if (queryParams) {
-    const value = queryParams[queryParamName];
-    const str = Array.isArray(value) ? value[0] : value;
-    if (str) return str;
-  }
-  if (authorizationHeader?.startsWith("Bearer ")) {
-    const token = authorizationHeader.slice("Bearer ".length);
-    if (token) return token;
-  }
-  return null;
-}
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -83,56 +61,36 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
-  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
-  if (deep && isEmptyToken) {
-    throw new Error(
-      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
-    );
-  }
-  const token = rawToken == null || isEmptyToken ? null : rawToken;
+  const { registry, resolveDepth, metadata = {} } = options;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
     }
   }
   return async (req) => {
-    if (token === null) {
-      if (deep) {
-        const response2 = await registry.run();
-        return {
-          status: httpStatusCode(response2.status),
-          body: { ...metadata, ...toJson(response2) }
-        };
+    let depth = "shallow";
+    if (resolveDepth) {
+      try {
+        const result = await resolveDepth(req);
+        if (result === "deep" || result === "shallow") {
+          depth = result;
+        }
+      } catch {
       }
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
-      };
-      return { status: 200, body };
     }
-    const provided = extractToken({
-      queryParams: req.queryParams,
-      authorizationHeader: req.authorizationHeader,
-      queryParamName
-    });
-    if (provided === null) {
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
+    if (depth === "deep") {
+      const response = await registry.run();
+      return {
+        status: httpStatusCode(response.status),
+        body: { ...metadata, ...toJson(response) }
       };
-      return { status: 200, body };
-    }
-    if (!verifyToken(provided, token)) {
-      return { status: 403, body: { error: "Forbidden" } };
     }
-    const response = await registry.run();
-    return {
-      status: httpStatusCode(response.status),
-      body: { ...metadata, ...toJson(response) }
+    const body = {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
     };
+    return { status: 200, body };
   };
 }
 
@@ -404,6 +362,8 @@ function createNextHandler(options) {
       const url = new URL(request.url);
       const queryParams = Object.fromEntries(url.searchParams);
       const result = await handle({
+        ip: request.headers.get("x-forwarded-for"),
+        headers: Object.fromEntries(request.headers),
         queryParams,
         authorizationHeader: request.headers.get("authorization")
       });

package/dist/integrations/next.d.cts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-COH7lot9.cjs';
+import { H as HealthcheckHandlerOptions } from '../handler-TZOgZvY7.cjs';
 import '../core-Bee03bJm.cjs';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;
@@ -15,7 +15,7 @@ type NextHealthcheckOptions = HealthcheckHandlerOptions;
  *
  * export const GET = createNextHandler({
  *   registry,
- *   token: process.env.VITALS_TOKEN,
+ *   resolveDepth: (req) => req.ip === '10.0.0.1' ? 'deep' : 'shallow',
  * });
  * ```
  */

package/dist/integrations/next.d.ts

@@ -1,4 +1,4 @@
-import { H as HealthcheckHandlerOptions } from '../handler-CVYUad84.js';
+import { H as HealthcheckHandlerOptions } from '../handler-BvjN4Ot9.js';
 import '../core-Bee03bJm.js';
 
 type NextHealthcheckOptions = HealthcheckHandlerOptions;
@@ -15,7 +15,7 @@ type NextHealthcheckOptions = HealthcheckHandlerOptions;
  *
  * export const GET = createNextHandler({
  *   registry,
- *   token: process.env.VITALS_TOKEN,
+ *   resolveDepth: (req) => req.ip === '10.0.0.1' ? 'deep' : 'shallow',
  * });
  * ```
  */

package/dist/integrations/next.mjs

@@ -1,25 +1,3 @@
-// src/auth.ts
-import { createHash, timingSafeEqual } from "crypto";
-function verifyToken(provided, expected) {
-  if (!provided || !expected) return false;
-  const providedHash = createHash("sha256").update(provided).digest();
-  const expectedHash = createHash("sha256").update(expected).digest();
-  return timingSafeEqual(providedHash, expectedHash);
-}
-function extractToken(options) {
-  const { queryParams, authorizationHeader, queryParamName = "token" } = options;
-  if (queryParams) {
-    const value = queryParams[queryParamName];
-    const str = Array.isArray(value) ? value[0] : value;
-    if (str) return str;
-  }
-  if (authorizationHeader?.startsWith("Bearer ")) {
-    const token = authorizationHeader.slice("Bearer ".length);
-    if (token) return token;
-  }
-  return null;
-}
-
 // src/types.ts
 var Status = {
   HEALTHY: 2,
@@ -57,56 +35,36 @@ function httpStatusCode(status) {
 // src/handler.ts
 var RESERVED_METADATA_KEYS = ["status", "timestamp", "checks", "cachedAt"];
 function createHealthcheckHandler(options) {
-  const { registry, token: rawToken, deep = false, queryParamName = "token", metadata = {} } = options;
-  const isEmptyToken = typeof rawToken === "string" && rawToken.trim() === "";
-  if (deep && isEmptyToken) {
-    throw new Error(
-      "Cannot use `deep: true` with an empty string token. This would expose deep healthcheck data without authentication. Either set a non-empty token or explicitly set `token: null`."
-    );
-  }
-  const token = rawToken == null || isEmptyToken ? null : rawToken;
+  const { registry, resolveDepth, metadata = {} } = options;
   for (const key of Object.keys(metadata)) {
     if (RESERVED_METADATA_KEYS.includes(key)) {
       throw new Error(`Metadata key '${key}' is reserved. Use a different key name.`);
     }
   }
   return async (req) => {
-    if (token === null) {
-      if (deep) {
-        const response2 = await registry.run();
-        return {
-          status: httpStatusCode(response2.status),
-          body: { ...metadata, ...toJson(response2) }
-        };
+    let depth = "shallow";
+    if (resolveDepth) {
+      try {
+        const result = await resolveDepth(req);
+        if (result === "deep" || result === "shallow") {
+          depth = result;
+        }
+      } catch {
       }
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
-      };
-      return { status: 200, body };
     }
-    const provided = extractToken({
-      queryParams: req.queryParams,
-      authorizationHeader: req.authorizationHeader,
-      queryParamName
-    });
-    if (provided === null) {
-      const body = {
-        status: "ok",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...metadata
+    if (depth === "deep") {
+      const response = await registry.run();
+      return {
+        status: httpStatusCode(response.status),
+        body: { ...metadata, ...toJson(response) }
       };
-      return { status: 200, body };
-    }
-    if (!verifyToken(provided, token)) {
-      return { status: 403, body: { error: "Forbidden" } };
     }
-    const response = await registry.run();
-    return {
-      status: httpStatusCode(response.status),
-      body: { ...metadata, ...toJson(response) }
+    const body = {
+      status: "ok",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...metadata
     };
+    return { status: 200, body };
   };
 }
 
@@ -378,6 +336,8 @@ function createNextHandler(options) {
       const url = new URL(request.url);
       const queryParams = Object.fromEntries(url.searchParams);
       const result = await handle({
+        ip: request.headers.get("x-forwarded-for"),
+        headers: Object.fromEntries(request.headers),
         queryParams,
         authorizationHeader: request.headers.get("authorization")
       });

package/package.json

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

package/dist/handler-COH7lot9.d.cts

@@ -1,27 +0,0 @@
-import { b as HealthcheckRegistry, H as HealthcheckResponseJson } from './core-Bee03bJm.cjs';
-
-interface HealthcheckHandlerOptions {
-    registry: HealthcheckRegistry;
-    token?: string | null;
-    deep?: boolean;
-    queryParamName?: string;
-    metadata?: Record<string, string | number | boolean>;
-}
-interface HealthcheckRequest {
-    queryParams?: Record<string, string | string[] | undefined>;
-    authorizationHeader?: string | null;
-}
-interface ShallowResponseJson {
-    status: 'ok';
-    timestamp: string;
-    [key: string]: string | number | boolean;
-}
-interface HealthcheckHandlerResult {
-    status: number;
-    body: HealthcheckResponseJson | ShallowResponseJson | {
-        error: string;
-    };
-}
-declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: HealthcheckRequest) => Promise<HealthcheckHandlerResult>;
-
-export { type HealthcheckHandlerOptions as H, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, type HealthcheckRequest as b, createHealthcheckHandler as c };

package/dist/handler-CVYUad84.d.ts

@@ -1,27 +0,0 @@
-import { b as HealthcheckRegistry, H as HealthcheckResponseJson } from './core-Bee03bJm.js';
-
-interface HealthcheckHandlerOptions {
-    registry: HealthcheckRegistry;
-    token?: string | null;
-    deep?: boolean;
-    queryParamName?: string;
-    metadata?: Record<string, string | number | boolean>;
-}
-interface HealthcheckRequest {
-    queryParams?: Record<string, string | string[] | undefined>;
-    authorizationHeader?: string | null;
-}
-interface ShallowResponseJson {
-    status: 'ok';
-    timestamp: string;
-    [key: string]: string | number | boolean;
-}
-interface HealthcheckHandlerResult {
-    status: number;
-    body: HealthcheckResponseJson | ShallowResponseJson | {
-        error: string;
-    };
-}
-declare function createHealthcheckHandler(options: HealthcheckHandlerOptions): (req: HealthcheckRequest) => Promise<HealthcheckHandlerResult>;
-
-export { type HealthcheckHandlerOptions as H, type ShallowResponseJson as S, type HealthcheckHandlerResult as a, type HealthcheckRequest as b, createHealthcheckHandler as c };