@rdlabo/workers-hono-kit 0.9.2 → 0.9.4

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`. |
@@ -209,7 +210,8 @@ client-generated UUID in `local_id` and keep `server_id` null until the server c
 | Export | Description |
 | --- | --- |
 | `defineRestDbMethodConverter(converter)` | Type a product-owned, pure `MethodScheme ↔ TableScheme` converter without hiding HTTP or persistence side effects. |
-| `RestDbMethodConverter` | Product-owned converter contract. Its table scheme requires every represented table and column, including optional nullable/default keys from `$inferInsert`. |
+| `RestDbMethodConverter` | Product-owned converter contract. Select and insert bundles may differ; every represented table and column remains required. |
+| `CompleteRestDbTableScheme` | Compile-time lock requiring every represented table key and row column. |
 | `toReplicaIsoDatetime(value)` | `Date` / datetime string → canonical UTC ISO-8601 wire value. |
 | `toReplicaDateOnly(value)` | `Date` / date string / `null` → canonical `YYYY-MM-DD` / `null`. |
 | `replicaTimestampMs(value)` | Replica datetime → epoch milliseconds for legacy DTOs. |
@@ -254,6 +256,20 @@ type CreateTables = {
 The converter then cannot demand or manufacture `id`; the server adds the generated id to the
 confirmed response before it is stored as `server_id`.
 
+When a write needs authenticated ownership or scope that is intentionally absent from the public
+REST body, use separate select/insert bundles and an explicit write context. The original
+two-generic form remains valid.
+
+```ts
+defineRestDbMethodConverter<Method, SelectTables, InsertTables, { userId: number }>({
+  toMethodScheme: ({ foods, allergens }) => composeFood(foods, allergens),
+  toTableScheme: (method, { userId }) => ({
+    foods: [{ userId, name: method.name, memo: method.memo ?? null }],
+    allergens: method.allergens.map((value) => ({ value })),
+  }),
+});
+```
+
 ```ts
 replicaNowIso(() => new Date('2026-07-23T10:00:00Z')); // '2026-07-23T10:00:00.000Z'
 toReplicaIsoDatetime('2026-07-23T19:00:00+09:00'); // '2026-07-23T10:00:00.000Z'
@@ -461,7 +477,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 +489,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

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

package/dist/offline/rest-db-method-converter.d.ts

@@ -17,7 +17,7 @@ type CompleteDbTableValue<TValue> = TValue extends (infer TRow)[] ? TRow extends
  * intentionally does not own a generated column must exclude it from its
  * product-owned scheme first, for example `Omit<InsertRow, 'id'>`.
  */
-type CompleteRestDbTableScheme<TTableScheme extends object> = {
+export type CompleteRestDbTableScheme<TTableScheme extends object> = {
     [TTableName in keyof TTableScheme]-?: CompleteDbTableValue<TTableScheme[TTableName]>;
 };
 /**
@@ -28,9 +28,9 @@ type CompleteRestDbTableScheme<TTableScheme extends object> = {
  * `$inferInsert` type marks them optional. Nullability does not make a column
  * optional in the conversion contract.
  */
-export interface RestDbMethodConverter<TMethodScheme, TTableScheme extends object> {
-    toMethodScheme(tableScheme: Readonly<CompleteRestDbTableScheme<TTableScheme>>): TMethodScheme;
-    toTableScheme(methodScheme: Readonly<TMethodScheme>): CompleteRestDbTableScheme<TTableScheme>;
+export interface RestDbMethodConverter<TMethodScheme, TSelectTableScheme extends object, TInsertTableScheme extends object = TSelectTableScheme, TWriteContext = never> {
+    toMethodScheme(tableScheme: Readonly<CompleteRestDbTableScheme<TSelectTableScheme>>): TMethodScheme;
+    toTableScheme(methodScheme: Readonly<TMethodScheme>, ...context: [TWriteContext] extends [never] ? [] : [context: Readonly<TWriteContext>]): CompleteRestDbTableScheme<TInsertTableScheme>;
 }
 /**
  * Define a product-specific REST ↔ DB converter with contextual return types.
@@ -38,5 +38,5 @@ export interface RestDbMethodConverter<TMethodScheme, TTableScheme extends objec
  * This is intentionally an identity function: conversion remains explicit,
  * synchronous, and free of hidden persistence or HTTP side effects.
  */
-export declare function defineRestDbMethodConverter<TMethodScheme, TTableScheme extends object>(converter: RestDbMethodConverter<TMethodScheme, TTableScheme>): RestDbMethodConverter<TMethodScheme, TTableScheme>;
+export declare function defineRestDbMethodConverter<TMethodScheme, TSelectTableScheme extends object, TInsertTableScheme extends object = TSelectTableScheme, TWriteContext = never>(converter: RestDbMethodConverter<TMethodScheme, TSelectTableScheme, TInsertTableScheme, TWriteContext>): RestDbMethodConverter<TMethodScheme, TSelectTableScheme, TInsertTableScheme, TWriteContext>;
 export {};

package/package.json

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