@rdlabo/workers-hono-kit 0.10.1 → 0.10.2

package/README.md

@@ -481,8 +481,10 @@ Repos with a custom DB error classifier (e.g. odss-mobile) pass `classify` to
 ### Auth middleware
 
 Encodes the shared skeleton (read token header → verify → `getAppInfo` → resolve user id →
-set context, with `console.error` + a configurable failure on error). Inject your own
-verify/resolver, context-variable names, and failure mode.
+set context, with configurable reporting and response hooks). Inject your own verify/resolver,
+context-variable names, and failure mode. By default a missing header remains backward compatible
+and calls `verify('')`; set `rejectMissingToken: true` to reject missing/blank input first with
+`AuthTokenMissingError`.
 
 `createAuthMiddleware<Env, Verified, Id>` is generic over your Hono `Env`, so `c.set(...)` in
 `setContext` is type-checked against your `Variables`.
@@ -492,6 +494,7 @@ import { createAuthMiddleware, createIdentityAuthFailureBody } from '@rdlabo/wor
 
 // AuthGuard: verify + resolve (and provision) the DB user id.
 const userAuth = createAuthMiddleware<AppEnv, UserRecord, number>({
+  rejectMissingToken: true,
   verify: (token) => container.firebase.verifyIdToken(token),
   resolveUserId: (record, _c, appInfo) =>
     container.auth.getUserIdFromFirebase(record, appInfo).catch(() => container.auth.createUser(record)),
@@ -500,18 +503,28 @@ const userAuth = createAuthMiddleware<AppEnv, UserRecord, number>({
     c.set('userId', userId);
     c.set('appInfo', appInfo);
   },
-  onFailure: (_error, context) =>
+  reportFailure: (error, context, { stage, tokenPresent }) => {
+    // Suppress expected credential rejection; report dependency/internal failures without tokens.
+  },
+  onFailure: (_error, context, { stage }) =>
     context.json(createIdentityAuthFailureBody(), 401),
 });
 
 // TokenGuard (login): verify only — omit resolveUserId. Override the failure if needed.
 const tokenAuth = createAuthMiddleware<AppEnv, UserRecord>({
+  rejectMissingToken: true,
   verify: (token) => container.firebase.verifyIdToken(token),
   setContext: (c, { verified }) => c.set('userRecord', verified),
   onFailure: (_e, c) => c.json(createIdentityAuthFailureBody(), 401),
 });
 ```
 
+`reportFailure(error, context, details)` receives only the stage (`token`, `verify`, `appInfo`,
+`resolveUserId`, or `setContext`) and a `tokenPresent` boolean; raw token data is never included in
+`details`. If the hook is omitted, the historical `console.error(error)` behavior remains. A reporting
+hook failure is logged but cannot change the authentication response. `onFailure` receives the same
+details as its third argument and may be asynchronous.
+
 Authentication failures use three explicit scopes. Only `identity` permits a client to purge its
 global authenticated session, offline replica boundary, and outbox. `reauthentication` means the
 identity remains valid but a recent sign-in is required; `credential` belongs to a domain feature

package/dist/firebase/jose-firebase-verifier.d.ts

@@ -22,6 +22,18 @@ type KeyInput = CryptoKey | KeyObject | JWK | Uint8Array | JWTVerifyGetKey;
  * be verified against Google's rotating public keys.
  */
 export declare const SECURETOKEN_JWK_URL = "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com";
+/** Expected rejection for Firebase-specific claims that passed JOSE signature/claim verification. */
+export declare class FirebaseIdTokenValidationError extends Error {
+    readonly claim: 'subject' | 'exp' | 'iat' | 'auth_time';
+    /** Stable machine-readable code for authentication failure classifiers. */
+    readonly code = "ERR_FIREBASE_ID_TOKEN_INVALID";
+    /**
+     * Create a Firebase ID-token validation rejection.
+     *
+     * @param claim - Firebase-specific claim which failed validation.
+     */
+    constructor(claim: 'subject' | 'exp' | 'iat' | 'auth_time');
+}
 /**
  * Verifies Firebase ID tokens with `jose` RS256 against Google's securetoken JWKS, and
  * optionally looks up or deletes users via the Google Identity Toolkit REST API.

package/dist/firebase/jose-firebase-verifier.js

@@ -8,6 +8,22 @@ import { jwtVerify } from 'jose';
  * be verified against Google's rotating public keys.
  */
 export const SECURETOKEN_JWK_URL = 'https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com';
+/** Expected rejection for Firebase-specific claims that passed JOSE signature/claim verification. */
+export class FirebaseIdTokenValidationError extends Error {
+    claim;
+    /** Stable machine-readable code for authentication failure classifiers. */
+    code = 'ERR_FIREBASE_ID_TOKEN_INVALID';
+    /**
+     * Create a Firebase ID-token validation rejection.
+     *
+     * @param claim - Firebase-specific claim which failed validation.
+     */
+    constructor(claim) {
+        super(`Firebase ID token has an invalid ${claim}`);
+        this.claim = claim;
+        this.name = 'FirebaseIdTokenValidationError';
+    }
+}
 /**
  * Verifies Firebase ID tokens with `jose` RS256 against Google's securetoken JWKS, and
  * optionally looks up or deletes users via the Google Identity Toolkit REST API.
@@ -74,18 +90,18 @@ export class JoseFirebaseVerifier {
         const { payload } = typeof key === 'function' ? await jwtVerify(idToken, key, options) : await jwtVerify(idToken, key, options);
         // Apply Firebase's documented checks beyond signature/iss/aud/exp.
         if (!payload.sub || typeof payload.sub !== 'string' || payload.sub.length > 128) {
-            throw new Error('Firebase ID token has an invalid subject');
+            throw new FirebaseIdTokenValidationError('subject');
         }
         if (!Number.isFinite(payload.exp)) {
-            throw new Error('Firebase ID token has an invalid exp');
+            throw new FirebaseIdTokenValidationError('exp');
         }
         const issuedAt = payload.iat;
         if (typeof issuedAt !== 'number' || !Number.isFinite(issuedAt) || issuedAt > now) {
-            throw new Error('Firebase ID token has an invalid iat');
+            throw new FirebaseIdTokenValidationError('iat');
         }
         const authTime = payload.auth_time;
         if (typeof authTime !== 'number' || !Number.isFinite(authTime) || authTime > now) {
-            throw new Error('Firebase ID token has an invalid auth_time');
+            throw new FirebaseIdTokenValidationError('auth_time');
         }
         return { ...payload, uid: payload.sub, email: payload.email };
     }

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export { validate, createValidate } from './middleware/validation.js';
 export { createSentryValidate } from './middleware/validation.js';
 export type { ValidateOptions, ValidationTarget, ZodErrorLike, SentryLike, SentryScopeLike, } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
-export { createAuthMiddleware } from './middleware/auth.js';
-export type { AuthMiddlewareOptions } from './middleware/auth.js';
+export { AuthTokenMissingError, createAuthMiddleware } from './middleware/auth.js';
+export type { AuthMiddlewareFailureDetails, AuthMiddlewareFailureStage, AuthMiddlewareOptions, } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
 export type { PerfLogOptions, AnalyticsEngineDatasetLike } from './middleware/perf-log.js';
 export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
@@ -90,7 +90,7 @@ export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
 export { getTemporaryCredentials } from './aws/sts.js';
 export type { GetTemporaryCredentialsOptions, StsCredentials } from './aws/sts.js';
 export type { DecodedIdToken, FirebaseVerifier } from './firebase/firebase-verifier.js';
-export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
+export { FirebaseIdTokenValidationError, JoseFirebaseVerifier, SECURETOKEN_JWK_URL, } from './firebase/jose-firebase-verifier.js';
 export { IdentityToolkit } from './firebase/identity-toolkit.js';
 export type { ServiceAccount } from './firebase/identity-toolkit.js';
 export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';

package/dist/index.js

@@ -16,7 +16,7 @@ export { validate, createValidate } from './middleware/validation.js';
 // eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional public re-export
 export { createSentryValidate } from './middleware/validation.js';
 export { zNum, zNumNullable, zNumOptional, zNumWithDefault } from './middleware/zod-coerce.js';
-export { createAuthMiddleware } from './middleware/auth.js';
+export { AuthTokenMissingError, createAuthMiddleware } from './middleware/auth.js';
 export { perfLog } from './middleware/perf-log.js';
 export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
 export { createIsolateMemo } from './container/isolate-memo.js';
@@ -67,6 +67,6 @@ export { createAiGatewayProvider } from './ai/gateway.js';
 export { getAuthenticationSecret } from './aws/secrets-manager.js';
 export { getCloudFrontSignedUrl } from './aws/cloudfront.js';
 export { getTemporaryCredentials } from './aws/sts.js';
-export { JoseFirebaseVerifier, SECURETOKEN_JWK_URL } from './firebase/jose-firebase-verifier.js';
+export { FirebaseIdTokenValidationError, JoseFirebaseVerifier, SECURETOKEN_JWK_URL, } from './firebase/jose-firebase-verifier.js';
 export { IdentityToolkit } from './firebase/identity-toolkit.js';
 export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';

package/dist/middleware/auth.d.ts

@@ -1,6 +1,21 @@
 import type { Context, Env, MiddlewareHandler } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 import type { AppInfo } from '../http/app-info.js';
+/** Processing stage at which authentication middleware failed. */
+export type AuthMiddlewareFailureStage = 'token' | 'verify' | 'appInfo' | 'resolveUserId' | 'setContext';
+/** Safe metadata describing an authentication middleware failure without including the token. */
+export interface AuthMiddlewareFailureDetails {
+    /** Stage which rejected or failed. */
+    stage: AuthMiddlewareFailureStage;
+    /** Whether the configured token header contained a non-blank value. */
+    tokenPresent: boolean;
+}
+/** Expected rejection raised when the configured authentication header is absent or blank. */
+export declare class AuthTokenMissingError extends Error {
+    /** Stable machine-readable code for application classifiers. */
+    readonly code = "AUTH_TOKEN_MISSING";
+    constructor();
+}
 /**
  * Configuration for {@link createAuthMiddleware}.
  *
@@ -11,10 +26,19 @@ import type { AppInfo } from '../http/app-info.js';
 export interface AuthMiddlewareOptions<E extends Env, Verified, Id = unknown> {
     /** Header carrying the ID token. Defaults to `'x-amz-security-token'`. */
     tokenHeader?: string;
+    /**
+     * Reject an absent or blank token before calling {@link AuthMiddlewareOptions.verify}.
+     *
+     * @remarks
+     * Defaults to `false` for backward compatibility: existing consumers historically receive an
+     * empty string in `verify` when the header is absent. Enable this when the application wants a
+     * typed {@link AuthTokenMissingError} and does not use an empty token as custom input.
+     */
+    rejectMissingToken?: boolean;
     /**
      * Verify the raw token and return the decoded value or user record.
      *
-     * @param token - The raw token read from {@link AuthMiddlewareOptions.tokenHeader} (empty string if absent).
+     * @param token - The raw token, or an empty string when absent unless `rejectMissingToken` is enabled.
      * @param c - The current Hono context.
      * @returns The verified value passed to {@link AuthMiddlewareOptions.resolveUserId}/{@link AuthMiddlewareOptions.setContext}.
      * @throws If the token is invalid; rejecting/throwing triggers the failure path.
@@ -59,7 +83,17 @@ export interface AuthMiddlewareOptions<E extends Env, Verified, Id = unknown> {
      * @param c - The current Hono context.
      * @returns The failure response to send.
      */
-    onFailure?: (err: unknown, c: Context<E>) => Response;
+    onFailure?: (err: unknown, c: Context<E>, details: AuthMiddlewareFailureDetails) => Response | Promise<Response>;
+    /**
+     * Report a failed authentication attempt.
+     *
+     * @remarks
+     * When omitted, the historical behavior (`console.error(err)`) is preserved. Applications should
+     * provide this hook to suppress expected credential rejections while reporting dependency and
+     * internal failures through their normal observability path. The hook must never include raw
+     * authentication tokens in logs or telemetry.
+     */
+    reportFailure?: (err: unknown, c: Context<E>, details: AuthMiddlewareFailureDetails) => void | Promise<void>;
     /** Status used by the default `onFailure`. Defaults to `403`. */
     failureStatus?: ContentfulStatusCode;
     /** Message used by the default `onFailure`. Defaults to `'Forbidden resource'`. */
@@ -69,7 +103,7 @@ export interface AuthMiddlewareOptions<E extends Env, Verified, Id = unknown> {
  * Create an authentication middleware equivalent to a NestJS `AuthGuard` / `TokenGuard`.
  *
  * The middleware runs a fixed skeleton — read the token header, `verify`, `getAppInfo`,
- * `resolveUserId`, `setContext`, and on error `console.error` then `onFailure` — while the
+ * `resolveUserId`, `setContext`, and on error `reportFailure` then `onFailure` — while the
  * application injects the variable parts (token verification, user-id resolution, context variable
  * names, and the failure response). Omitting {@link AuthMiddlewareOptions.resolveUserId} yields a
  * token-only middleware.

package/dist/middleware/auth.js

@@ -1,10 +1,19 @@
 import { HTTPException } from 'hono/http-exception';
 import { getAppInfo } from '../http/app-info.js';
+/** Expected rejection raised when the configured authentication header is absent or blank. */
+export class AuthTokenMissingError extends Error {
+    /** Stable machine-readable code for application classifiers. */
+    code = 'AUTH_TOKEN_MISSING';
+    constructor() {
+        super('Authentication token is missing');
+        this.name = 'AuthTokenMissingError';
+    }
+}
 /**
  * Create an authentication middleware equivalent to a NestJS `AuthGuard` / `TokenGuard`.
  *
  * The middleware runs a fixed skeleton — read the token header, `verify`, `getAppInfo`,
- * `resolveUserId`, `setContext`, and on error `console.error` then `onFailure` — while the
+ * `resolveUserId`, `setContext`, and on error `reportFailure` then `onFailure` — while the
  * application injects the variable parts (token verification, user-id resolution, context variable
  * names, and the failure response). Omitting {@link AuthMiddlewareOptions.resolveUserId} yields a
  * token-only middleware.
@@ -30,22 +39,42 @@ import { getAppInfo } from '../http/app-info.js';
  * ```
  */
 export function createAuthMiddleware(options) {
-    const { tokenHeader = 'x-amz-security-token', verify, resolveUserId, setContext, onFailure, failureStatus = 403, failureMessage = 'Forbidden resource', } = options;
+    const { tokenHeader = 'x-amz-security-token', rejectMissingToken = false, verify, resolveUserId, setContext, onFailure, reportFailure, failureStatus = 403, failureMessage = 'Forbidden resource', } = options;
     return async (c, next) => {
+        let stage = 'token';
+        let tokenPresent = false;
         try {
             const token = c.req.header(tokenHeader) ?? '';
+            tokenPresent = token.trim().length > 0;
+            if (!tokenPresent && rejectMissingToken) {
+                throw new AuthTokenMissingError();
+            }
+            stage = 'verify';
             const verified = await verify(token, c);
+            stage = 'appInfo';
             const appInfo = getAppInfo(c);
+            stage = 'resolveUserId';
             const userId = resolveUserId ? await resolveUserId(verified, c, appInfo) : undefined;
+            stage = 'setContext';
             setContext(c, { verified, appInfo, userId });
         }
         catch (e) {
-            // Equivalent to a guard returning false → ForbiddenException('Forbidden resource'). Log the
-            // cause and, by default, throw so the app's onError renders the error body (callers can
-            // override with onFailure to return a custom response instead).
-            console.error(e);
+            const details = { stage, tokenPresent };
+            if (reportFailure) {
+                try {
+                    await reportFailure(e, c, details);
+                }
+                catch (reportingError) {
+                    // Observability must never alter the authentication response.
+                    console.error(reportingError);
+                }
+            }
+            else {
+                // Preserve the historical default for consumers that have not adopted classified reporting.
+                console.error(e);
+            }
             if (onFailure) {
-                return onFailure(e, c);
+                return onFailure(e, c, details);
             }
             throw new HTTPException(failureStatus, { message: failureMessage });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "private": false,
   "publishConfig": {
     "access": "public"