@rdlabo/workers-hono-kit 0.9.1 → 0.9.3

package/README.md

@@ -79,6 +79,7 @@ npm install ai ai-gateway-provider    # createAiGatewayProvider
 | `normalizeTrailingSlash(request)` | Strip trailing slash(es) from the request URL before routing (Express/Nest parity). Does **not** 301-redirect — preserves POST/PUT/DELETE bodies. |
 | `HTTP_ERROR_PHRASES` | `{ 400, 401, 403, 404 }` → standard `error` field phrases. |
 | `createAuthMiddleware(options)` / `AuthMiddlewareOptions` | Factory for a Firebase-token auth middleware: reads the token header, verifies, resolves the DB user id, and stashes the result on the context. Omit `resolveUserId` for a token-only (login) guard. |
+| `createIdentityAuthFailureBody()` / `createLegacyIdentityAuthFailureBody()` / `createAuthFailureBody(scope, code, message)` / `AuthFailureScope` | Stable wire contract for distinguishing a lost global identity (`identity`) from recent-login (`reauthentication`) and feature credential (`credential`) failures. The legacy helper tags products whose installed clients still require auth failure as `403`. |
 | `perfLog(options?)` / `PerfLogOptions` / `AnalyticsEngineDatasetLike` | Middleware that records one per-request latency data point (`t_app`, colo, cold/warm, route, status) and emits it to **Workers Logs** (`console.log`) and/or **Workers Analytics Engine** (`writeDataPoint`). Lets you measure low-traffic Workers without a live `wrangler tail`. |
 | `createMaintenanceMiddleware(options)` / `createMaintenanceWaitHandler(options)` / `isMaintenanceEnabled(env)` / `MAINTENANCE_CODE` / `MAINTENANCE_WAIT_PATH` | Fleet maintenance short-circuit: when enabled (`MAINTENANCE=1`), every non-allowlisted request returns `503` + `{ statusCode, message, code: 'MAINTENANCE' }` **before** container/DB. Pair with `GET /public/maintenance/wait` SSE (`event: ping` / `event: ended`) so clients can auto-dismiss a lock UI. Mount after `cors`, before `containerMiddleware`. |
 | `ErrorReporter` / `ErrorReportContext` | Types for a `reportError`-style unhandled-error reporter (e.g. wired to Sentry), paired with `createHttpErrorHandler`'s `onUnhandledError`. |
@@ -461,7 +462,7 @@ verify/resolver, context-variable names, and failure mode.
 `setContext` is type-checked against your `Variables`.
 
 ```ts
-import { createAuthMiddleware } from '@rdlabo/workers-hono-kit';
+import { createAuthMiddleware, createIdentityAuthFailureBody } from '@rdlabo/workers-hono-kit';
 
 // AuthGuard: verify + resolve (and provision) the DB user id.
 const userAuth = createAuthMiddleware<AppEnv, UserRecord, number>({
@@ -473,16 +474,28 @@ const userAuth = createAuthMiddleware<AppEnv, UserRecord, number>({
     c.set('userId', userId);
     c.set('appInfo', appInfo);
   },
+  onFailure: (_error, context) =>
+    context.json(createIdentityAuthFailureBody(), 401),
 });
 
 // TokenGuard (login): verify only — omit resolveUserId. Override the failure if needed.
 const tokenAuth = createAuthMiddleware<AppEnv, UserRecord>({
   verify: (token) => container.firebase.verifyIdToken(token),
   setContext: (c, { verified }) => c.set('userRecord', verified),
-  onFailure: (_e, c) => c.json({ message: 'Unauthorized', statusCode: 401 }, 401),
+  onFailure: (_e, c) => c.json(createIdentityAuthFailureBody(), 401),
 });
 ```
 
+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
+such as a public booking token. New APIs use `401`; products with installed clients that historically
+interpret auth failure as `403` use `createLegacyIdentityAuthFailureBody()` until that compatibility
+contract can be retired. An untagged `403` is an authenticated permission/business denial and must
+not be used as a global-session invalidation signal. Domain-specific `code` values remain product-owned.
+`createAuthMiddleware` retains its historical untagged `403` default for source/runtime compatibility;
+the tagged identity contract is an explicit `onFailure` opt-in as shown above.
+
 ### Latency instrumentation (`perfLog`)
 
 Records one data point per request — `t_app` (time inside the app), `colo`, `cold`/`warm`, matched

package/dist/http/auth-failure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Describes which credential boundary caused an authentication failure.
+ *
+ * Only `identity` means that the application's global authenticated identity is
+ * no longer usable. `reauthentication` keeps the identity but requires a recent
+ * sign-in, while `credential` is limited to a delegated/domain credential.
+ */
+export declare const AUTH_FAILURE_SCOPES: {
+    readonly identity: "identity";
+    readonly reauthentication: "reauthentication";
+    readonly credential: "credential";
+};
+export type AuthFailureScope = (typeof AUTH_FAILURE_SCOPES)[keyof typeof AUTH_FAILURE_SCOPES];
+export declare const AUTH_IDENTITY_INVALID_CODE = "AUTH_IDENTITY_INVALID";
+export interface AuthFailureBody<TScope extends AuthFailureScope = AuthFailureScope, TCode extends string = string, TStatus extends 401 | 403 = 401> {
+    statusCode: TStatus;
+    message: string;
+    code: TCode;
+    authFailureScope: TScope;
+}
+/**
+ * Creates the stable wire body for an authentication failure.
+ *
+ * Domain-specific codes remain owned by each application. The scope is the
+ * shared lifecycle contract consumed by clients deciding which local state may
+ * be invalidated.
+ */
+export declare const createAuthFailureBody: <TScope extends AuthFailureScope, TCode extends string>(authFailureScope: TScope, code: TCode, message: string) => AuthFailureBody<TScope, TCode>;
+export declare const createIdentityAuthFailureBody: (message?: string) => AuthFailureBody<"identity", typeof AUTH_IDENTITY_INVALID_CODE>;
+/**
+ * Creates an explicitly tagged identity failure with the historical HTTP 403
+ * status used by some deployed products.
+ *
+ * New APIs should use {@link createIdentityAuthFailureBody}. This helper exists
+ * for servers that must remain compatible with installed clients whose auth
+ * interceptor recognizes the legacy 403 response.
+ */
+export declare const createLegacyIdentityAuthFailureBody: (message?: string) => AuthFailureBody<"identity", typeof AUTH_IDENTITY_INVALID_CODE, 403>;

package/dist/http/auth-failure.js

@@ -0,0 +1,41 @@
+/**
+ * Describes which credential boundary caused an authentication failure.
+ *
+ * Only `identity` means that the application's global authenticated identity is
+ * no longer usable. `reauthentication` keeps the identity but requires a recent
+ * sign-in, while `credential` is limited to a delegated/domain credential.
+ */
+export const AUTH_FAILURE_SCOPES = {
+    identity: 'identity',
+    reauthentication: 'reauthentication',
+    credential: 'credential',
+};
+export const AUTH_IDENTITY_INVALID_CODE = 'AUTH_IDENTITY_INVALID';
+/**
+ * Creates the stable wire body for an authentication failure.
+ *
+ * Domain-specific codes remain owned by each application. The scope is the
+ * shared lifecycle contract consumed by clients deciding which local state may
+ * be invalidated.
+ */
+export const createAuthFailureBody = (authFailureScope, code, message) => ({
+    statusCode: 401,
+    message,
+    code,
+    authFailureScope,
+});
+export const createIdentityAuthFailureBody = (message = 'Unauthorized') => createAuthFailureBody(AUTH_FAILURE_SCOPES.identity, AUTH_IDENTITY_INVALID_CODE, message);
+/**
+ * Creates an explicitly tagged identity failure with the historical HTTP 403
+ * status used by some deployed products.
+ *
+ * New APIs should use {@link createIdentityAuthFailureBody}. This helper exists
+ * for servers that must remain compatible with installed clients whose auth
+ * interceptor recognizes the legacy 403 response.
+ */
+export const createLegacyIdentityAuthFailureBody = (message = 'Forbidden resource') => ({
+    statusCode: 403,
+    message,
+    code: AUTH_IDENTITY_INVALID_CODE,
+    authFailureScope: AUTH_FAILURE_SCOPES.identity,
+});

package/dist/index.d.ts

@@ -47,6 +47,8 @@ export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export type { DeferExecutor } from './http/defer.js';
 export { createSentryErrorReporter } from './http/http-error.js';
 export type { SentryExceptionReporterLike } from './http/http-error.js';
+export { AUTH_FAILURE_SCOPES, AUTH_IDENTITY_INVALID_CODE, createAuthFailureBody, createIdentityAuthFailureBody, createLegacyIdentityAuthFailureBody, } from './http/auth-failure.js';
+export type { AuthFailureBody, AuthFailureScope } from './http/auth-failure.js';
 export { canonicalJson, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, sha256CanonicalJson, withIdempotencyHttpErrors, } from './idempotency/idempotency.js';
 export type { CreateIdempotencyInputOptions, IdempotencyInput, IdempotencyReservation, IdempotencyScope, IdempotencyScopeValue, IdempotentMutationStore, } from './idempotency/idempotency.js';
 export { acknowledgeHibernationWebSocketClose, broadcastHibernationWebSockets, closeHibernationWebSocket, configureHibernationAutoResponse, upgradeHibernationWebSocket, } from './realtime/hibernation.js';

package/dist/index.js

@@ -35,6 +35,7 @@ export { createAppErrorHandler } from './http/app-error-handler.js';
 export { normalizeTrailingSlash } from './http/trailing-slash.js';
 export { defaultDefer, createWaitUntilDefer } from './http/defer.js';
 export { createSentryErrorReporter } from './http/http-error.js';
+export { AUTH_FAILURE_SCOPES, AUTH_IDENTITY_INVALID_CODE, createAuthFailureBody, createIdentityAuthFailureBody, createLegacyIdentityAuthFailureBody, } from './http/auth-failure.js';
 // idempotency
 export { canonicalJson, createIdempotencyInput, IdempotencyConflictError, IdempotencyInFlightError, IdempotencyKeyValidationError, IdempotencyPayloadValidationError, runIdempotentMutation, sha256CanonicalJson, withIdempotencyHttpErrors, } from './idempotency/idempotency.js';
 // realtime

package/dist/offline/index.d.ts

@@ -10,3 +10,5 @@ export { fromTinyIntFlag, replicaTimestampMs, toReplicaDateOnly, toReplicaIsoDat
 export { replicaNowIso } from './clock.js';
 export { defineRestDbMethodConverter } from './rest-db-method-converter.js';
 export type { RestDbMethodConverter } from './rest-db-method-converter.js';
+export { decodeOfflineSnapshotCursor, encodeOfflineSnapshotCursor } from './snapshot-cursor.js';
+export type { OfflineSnapshotCursor } from './snapshot-cursor.js';

package/dist/offline/index.js

@@ -9,3 +9,4 @@
 export { fromTinyIntFlag, replicaTimestampMs, toReplicaDateOnly, toReplicaIsoDatetime, toTinyIntFlag } from './wire.js';
 export { replicaNowIso } from './clock.js';
 export { defineRestDbMethodConverter } from './rest-db-method-converter.js';
+export { decodeOfflineSnapshotCursor, encodeOfflineSnapshotCursor } from './snapshot-cursor.js';

package/dist/offline/snapshot-cursor.d.ts

@@ -0,0 +1,13 @@
+/** Position of a keyset-paginated initial snapshot at a captured journal watermark. */
+export interface OfflineSnapshotCursor {
+    /** Highest journal revision captured before the snapshot scan starts. */
+    watermark: number;
+    /** Zero-based product-defined snapshot source index. */
+    sourceIndex: number;
+    /** Last server-side numeric ID emitted from the current source. */
+    afterId: number;
+}
+/** Encodes an initial-snapshot position as a stable versioned cursor. */
+export declare function encodeOfflineSnapshotCursor(cursor: OfflineSnapshotCursor): string;
+/** Decodes a versioned initial-snapshot cursor, returning null for malformed input. */
+export declare function decodeOfflineSnapshotCursor(value: string): OfflineSnapshotCursor | null;

package/dist/offline/snapshot-cursor.js

@@ -0,0 +1,39 @@
+const SNAPSHOT_CURSOR_PREFIX = 'snapshot:v1';
+const CANONICAL_NON_NEGATIVE_INTEGER = /^(0|[1-9]\d*)$/;
+/** Encodes an initial-snapshot position as a stable versioned cursor. */
+export function encodeOfflineSnapshotCursor(cursor) {
+    assertNonNegativeSafeInteger(cursor.watermark, 'watermark');
+    assertNonNegativeSafeInteger(cursor.sourceIndex, 'sourceIndex');
+    assertNonNegativeSafeInteger(cursor.afterId, 'afterId');
+    return `${SNAPSHOT_CURSOR_PREFIX}:${cursor.watermark}:${cursor.sourceIndex}:${cursor.afterId}`;
+}
+/** Decodes a versioned initial-snapshot cursor, returning null for malformed input. */
+export function decodeOfflineSnapshotCursor(value) {
+    const parts = value.split(':');
+    if (parts.length !== 5 || `${parts[0]}:${parts[1]}` !== SNAPSHOT_CURSOR_PREFIX) {
+        return null;
+    }
+    const [, , watermarkValue, sourceIndexValue, afterIdValue] = parts;
+    if (!CANONICAL_NON_NEGATIVE_INTEGER.test(watermarkValue) ||
+        !CANONICAL_NON_NEGATIVE_INTEGER.test(sourceIndexValue) ||
+        !CANONICAL_NON_NEGATIVE_INTEGER.test(afterIdValue)) {
+        return null;
+    }
+    const watermark = Number(watermarkValue);
+    const sourceIndex = Number(sourceIndexValue);
+    const afterId = Number(afterIdValue);
+    if (!isNonNegativeSafeInteger(watermark) ||
+        !isNonNegativeSafeInteger(sourceIndex) ||
+        !isNonNegativeSafeInteger(afterId)) {
+        return null;
+    }
+    return { watermark, sourceIndex, afterId };
+}
+function isNonNegativeSafeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function assertNonNegativeSafeInteger(value, field) {
+    if (!isNonNegativeSafeInteger(value)) {
+        throw new RangeError(`Offline snapshot cursor ${field} must be a non-negative safe integer.`);
+    }
+}

package/package.json

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