@rdlabo/workers-hono-kit 0.12.2 → 0.12.3-beta.pr51.sha3289ea609bb4

package/README.md

@@ -2,24 +2,9 @@
 
 Shared Hono building blocks for Cloudflare Workers APIs: weak ETags, NestJS-shaped validation and
 error bodies, Firebase auth middleware, AWS helpers, AI Gateway wiring, Stripe, KV, queues,
-realtime, and offline contracts. Domain logic and database schemas stay in the consuming
-application.
+realtime, and offline contracts.
 
-## Choose an entry point
-
-| Import                                   | Responsibility                                                       |
-| ---------------------------------------- | -------------------------------------------------------------------- |
-| `@rdlabo/workers-hono-kit`               | HTTP, auth, Firebase, AWS, AI, Stripe, KV, and queue primitives      |
-| `@rdlabo/workers-hono-kit/mysql`         | Hono container adapter for `@rdlabo/workers-mysql`                   |
-| `@rdlabo/workers-hono-kit/offline`       | Offline replica wire, cursor, journal, and compatibility contracts   |
-| `@rdlabo/workers-hono-kit/realtime`      | Durable Object WebSocket and retry helpers                           |
-| `@rdlabo/workers-hono-kit/testing`       | Auth helpers, fakes, Stripe fixtures, and compatibility test exports |
-| `@rdlabo/workers-hono-kit/db`            | Deprecated compatibility path for `@rdlabo/workers-mysql`            |
-| `@rdlabo/workers-hono-kit/business-time` | Deprecated compatibility path for `@rdlabo/workers-timezone`         |
-
-The root entry point does not load MySQL, Drizzle, or Node-only migration modules. MySQL consumers
-install the standalone package, which owns `mysql2`; Hono-specific wiring stays in the `/mysql`
-adapter.
+[Try a Hono API locally](./docs/quickstart.md): send a health request, inspect its weak ETag, and see the missing-route JSON response. No Cloudflare account or open port is needed for the first exercise.
 
 ## Install
 
@@ -72,6 +57,22 @@ app.get('/health', (c) => c.json({ ok: true }));
 export default app;
 ```
 
+## Choose an entry point
+
+| Import                                   | Responsibility                                                       |
+| ---------------------------------------- | -------------------------------------------------------------------- |
+| `@rdlabo/workers-hono-kit`               | HTTP, auth, Firebase, AWS, AI, Stripe, KV, and queue primitives      |
+| `@rdlabo/workers-hono-kit/mysql`         | Hono container adapter for `@rdlabo/workers-mysql`                   |
+| `@rdlabo/workers-hono-kit/offline`       | Offline replica wire, cursor, journal, and compatibility contracts   |
+| `@rdlabo/workers-hono-kit/realtime`      | Durable Object WebSocket and retry helpers                           |
+| `@rdlabo/workers-hono-kit/testing`       | Auth helpers, fakes, Stripe fixtures, and compatibility test exports |
+| `@rdlabo/workers-hono-kit/db`            | Deprecated compatibility path for `@rdlabo/workers-mysql`            |
+| `@rdlabo/workers-hono-kit/business-time` | Deprecated compatibility path for `@rdlabo/workers-timezone`         |
+
+The root entry point does not load MySQL, Drizzle, or Node-only migration modules. MySQL consumers
+install the standalone package, which owns `mysql2`; Hono-specific wiring stays in the `/mysql`
+adapter.
+
 ### Compatibility import deprecations
 
 Kit `/db`, `/business-time`, and the DB-related `/testing` exports (`createTestDb`, pool/noop
@@ -81,6 +82,33 @@ compatibility aliases keep the same runtime identity and signatures; there is no
 Kit-owned helpers such as `reopenGuardedPaymentFailedSet`, `/mysql` `createContainerRuntime`, and
 Firebase/auth/KV/Stripe test helpers are not deprecated by this migration.
 
+### Social auth (Google / Apple)
+
+Root exports `verifyGoogleIdentityToken`, `verifyAppleIdentityToken`,
+`hasFirebaseProviderIdentity`, and `createAppleClientSecret` cover reusable OIDC subject
+verification, Firebase identity matching, and Apple `client_secret` signing. Applications keep
+ownership of HTTP responses, persistence, and provider token exchange or revocation.
+
+`hasFirebaseProviderIdentity` expects a **verified** Firebase ID-token payload. Pass
+`requireSignInProvider: true` when an endpoint requires sign-in through that provider
+(subject linked **and** `firebase.sign_in_provider` matches). Leave it `false` (default)
+for link/unlink checks or combined login/link endpoints that also accept sessions established
+through another provider. This policy belongs to the application.
+
+```ts
+import { hasFirebaseProviderIdentity, verifyGoogleIdentityToken } from '@rdlabo/workers-hono-kit';
+
+// firebaseVerifier is the application's configured FirebaseVerifier.
+const verifiedFirebaseToken = await firebaseVerifier.verifyIdToken(firebaseIdToken);
+const subject = await verifyGoogleIdentityToken(googleIdToken, GOOGLE_CLIENT_IDS);
+// login: require active Google sign-in
+if (!hasFirebaseProviderIdentity(verifiedFirebaseToken, 'google.com', subject, true)) {
+  return c.json({ error: 'Google identity mismatch' }, 401);
+}
+// link / unlink: subject present is enough
+// hasFirebaseProviderIdentity(verifiedFirebaseToken, 'google.com', subject)
+```
+
 ## Documentation
 
 - [HTTP and Authentication](https://docs.rdlabo.dev/projects/workers-hono-kit/docs/http-auth)

package/dist/firebase/social-auth.d.ts

@@ -0,0 +1,90 @@
+import type { JWTVerifyGetKey } from 'jose';
+import type { DecodedIdToken } from './firebase-verifier.js';
+/** Apple Sign In OIDC issuer (`iss`) expected by {@link verifyAppleIdentityToken}. */
+export declare const APPLE_IDENTITY_ISSUER = "https://appleid.apple.com";
+/**
+ * Google OIDC issuers accepted by {@link verifyGoogleIdentityToken}.
+ *
+ * Google issues tokens with either the HTTPS form or the host-only form of
+ * `accounts.google.com`; both are listed so verification matches either claim.
+ */
+export declare const GOOGLE_IDENTITY_ISSUERS: readonly ["https://accounts.google.com", "accounts.google.com"];
+/**
+ * Verify an Apple identity token and return its `sub` (Apple user id).
+ *
+ * Checks signature against Apple's JWKS (or an injected key resolver), enforces
+ * {@link APPLE_IDENTITY_ISSUER}, and requires `aud` to equal the configured Services ID /
+ * bundle id (`audience`).
+ *
+ * @param idToken - Raw Apple identity token JWT from Sign in with Apple.
+ * @param audience - Expected `aud` claim (Apple Services ID or native bundle id).
+ * @param getKey - Optional JWKS / key resolver; defaults to Apple's remote JWKS. Inject a
+ *   static key in tests to avoid network I/O.
+ * @returns The token `sub` (Apple user identifier).
+ * @throws If signature, issuer, audience, or expiry fail verification, or `sub` is missing.
+ */
+export declare const verifyAppleIdentityToken: (idToken: string, audience: string, getKey?: JWTVerifyGetKey) => Promise<string>;
+/**
+ * Verify a Google identity token and return its `sub` (Google user id).
+ *
+ * Checks signature against Google's OAuth2 certs (or an injected key resolver), accepts either
+ * issuer in {@link GOOGLE_IDENTITY_ISSUERS}, and requires `aud` to match the configured OAuth
+ * client id(s) (`audience`).
+ *
+ * @param idToken - Raw Google ID token JWT.
+ * @param audience - Expected `aud` claim: a single OAuth client id, or a list when native and
+ *   web clients share one login endpoint.
+ * @param getKey - Optional JWKS / key resolver; defaults to Google's remote certs. Inject a
+ *   static key in tests to avoid network I/O.
+ * @returns The token `sub` (Google user identifier).
+ * @throws If signature, issuer, audience, or expiry fail verification, or `sub` is missing.
+ */
+export declare const verifyGoogleIdentityToken: (idToken: string, audience: string | readonly string[], getKey?: JWTVerifyGetKey) => Promise<string>;
+/**
+ * Return whether a **verified** Firebase ID token already carries the given provider subject.
+ *
+ * Reads `firebase.identities[providerId]` for `subject`. When `requireSignInProvider` is true,
+ * also requires `firebase.sign_in_provider === providerId` so the session was established with
+ * that provider (login), not merely that the identity is linked while signed in another way.
+ *
+ * @remarks
+ * `token` must already be a verified Firebase ID-token payload (for example from
+ * {@link FirebaseVerifier.verifyIdToken} or auth middleware). This helper does not verify the
+ * Firebase JWT itself.
+ *
+ * Typical policy:
+ * - **Login** (`requireSignInProvider: true`): subject present and active sign-in provider matches.
+ * - **Link / unlink / linkage checks** (default `false`): subject present in identities only.
+ *
+ * @param token - Verified Firebase ID-token payload (`DecodedIdToken`).
+ * @param providerId - Firebase provider id (e.g. `'google.com'`, `'apple.com'`).
+ * @param subject - Provider subject previously returned by {@link verifyGoogleIdentityToken} or
+ *   {@link verifyAppleIdentityToken}.
+ * @param requireSignInProvider - When `true`, also require `sign_in_provider === providerId`.
+ * @returns `true` when the identity (and optional active provider) matches.
+ */
+export declare const hasFirebaseProviderIdentity: (token: DecodedIdToken, providerId: string, subject: string, requireSignInProvider?: boolean) => boolean;
+/**
+ * Apple developer credentials used to mint a Sign in with Apple `client_secret` JWT.
+ */
+export interface AppleClientSecretConfig {
+    /** PEM-encoded PKCS#8 ES256 private key from the Apple developer key. */
+    privateKey: string;
+    /** Key id (`kid`) of the Apple developer key. */
+    keyId: string;
+    /** Apple Team ID used as the JWT `iss` claim. */
+    teamId: string;
+}
+/**
+ * Create a short-lived Sign in with Apple `client_secret` (ES256 JWT).
+ *
+ * The JWT is issued for `clientId` as `sub`, audience {@link APPLE_IDENTITY_ISSUER}, and expires
+ * 120 seconds after `now`. Used for Apple's token and revoke endpoints.
+ *
+ * @param config - Apple Team ID, key id, and PKCS#8 private key.
+ * @param clientId - Apple Services ID or native bundle id (`sub` claim).
+ * @param now - Unix time in seconds for `iat` / `exp`; injectable for deterministic tests.
+ *   Defaults to the system clock.
+ * @returns A compact ES256 JWT suitable as Apple's `client_secret`.
+ */
+export declare const createAppleClientSecret: (config: AppleClientSecretConfig, clientId: string, now?: number) => Promise<string>;

package/dist/firebase/social-auth.js

@@ -0,0 +1,108 @@
+import { SignJWT, createRemoteJWKSet, importPKCS8, jwtVerify } from 'jose';
+/** Apple Sign In OIDC issuer (`iss`) expected by {@link verifyAppleIdentityToken}. */
+export const APPLE_IDENTITY_ISSUER = 'https://appleid.apple.com';
+/**
+ * Google OIDC issuers accepted by {@link verifyGoogleIdentityToken}.
+ *
+ * Google issues tokens with either the HTTPS form or the host-only form of
+ * `accounts.google.com`; both are listed so verification matches either claim.
+ */
+export const GOOGLE_IDENTITY_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
+const appleJwks = createRemoteJWKSet(new URL(`${APPLE_IDENTITY_ISSUER}/auth/keys`));
+const googleJwks = createRemoteJWKSet(new URL('https://www.googleapis.com/oauth2/v3/certs'));
+/**
+ * Verify an Apple identity token and return its `sub` (Apple user id).
+ *
+ * Checks signature against Apple's JWKS (or an injected key resolver), enforces
+ * {@link APPLE_IDENTITY_ISSUER}, and requires `aud` to equal the configured Services ID /
+ * bundle id (`audience`).
+ *
+ * @param idToken - Raw Apple identity token JWT from Sign in with Apple.
+ * @param audience - Expected `aud` claim (Apple Services ID or native bundle id).
+ * @param getKey - Optional JWKS / key resolver; defaults to Apple's remote JWKS. Inject a
+ *   static key in tests to avoid network I/O.
+ * @returns The token `sub` (Apple user identifier).
+ * @throws If signature, issuer, audience, or expiry fail verification, or `sub` is missing.
+ */
+export const verifyAppleIdentityToken = async (idToken, audience, getKey = appleJwks) => {
+    const { payload } = await jwtVerify(idToken, getKey, { issuer: APPLE_IDENTITY_ISSUER, audience });
+    if (!payload.sub) {
+        throw new Error('Apple identity token has no subject');
+    }
+    return payload.sub;
+};
+/**
+ * Verify a Google identity token and return its `sub` (Google user id).
+ *
+ * Checks signature against Google's OAuth2 certs (or an injected key resolver), accepts either
+ * issuer in {@link GOOGLE_IDENTITY_ISSUERS}, and requires `aud` to match the configured OAuth
+ * client id(s) (`audience`).
+ *
+ * @param idToken - Raw Google ID token JWT.
+ * @param audience - Expected `aud` claim: a single OAuth client id, or a list when native and
+ *   web clients share one login endpoint.
+ * @param getKey - Optional JWKS / key resolver; defaults to Google's remote certs. Inject a
+ *   static key in tests to avoid network I/O.
+ * @returns The token `sub` (Google user identifier).
+ * @throws If signature, issuer, audience, or expiry fail verification, or `sub` is missing.
+ */
+export const verifyGoogleIdentityToken = async (idToken, audience, getKey = googleJwks) => {
+    const { payload } = await jwtVerify(idToken, getKey, {
+        issuer: [...GOOGLE_IDENTITY_ISSUERS],
+        audience: typeof audience === 'string' ? audience : [...audience],
+    });
+    if (!payload.sub) {
+        throw new Error('Google identity token has no subject');
+    }
+    return payload.sub;
+};
+/**
+ * Return whether a **verified** Firebase ID token already carries the given provider subject.
+ *
+ * Reads `firebase.identities[providerId]` for `subject`. When `requireSignInProvider` is true,
+ * also requires `firebase.sign_in_provider === providerId` so the session was established with
+ * that provider (login), not merely that the identity is linked while signed in another way.
+ *
+ * @remarks
+ * `token` must already be a verified Firebase ID-token payload (for example from
+ * {@link FirebaseVerifier.verifyIdToken} or auth middleware). This helper does not verify the
+ * Firebase JWT itself.
+ *
+ * Typical policy:
+ * - **Login** (`requireSignInProvider: true`): subject present and active sign-in provider matches.
+ * - **Link / unlink / linkage checks** (default `false`): subject present in identities only.
+ *
+ * @param token - Verified Firebase ID-token payload (`DecodedIdToken`).
+ * @param providerId - Firebase provider id (e.g. `'google.com'`, `'apple.com'`).
+ * @param subject - Provider subject previously returned by {@link verifyGoogleIdentityToken} or
+ *   {@link verifyAppleIdentityToken}.
+ * @param requireSignInProvider - When `true`, also require `sign_in_provider === providerId`.
+ * @returns `true` when the identity (and optional active provider) matches.
+ */
+export const hasFirebaseProviderIdentity = (token, providerId, subject, requireSignInProvider = false) => {
+    const firebase = token;
+    const subjects = firebase.firebase?.identities?.[providerId];
+    return (Array.isArray(subjects) &&
+        subjects.includes(subject) &&
+        (!requireSignInProvider || firebase.firebase?.sign_in_provider === providerId));
+};
+/**
+ * Create a short-lived Sign in with Apple `client_secret` (ES256 JWT).
+ *
+ * The JWT is issued for `clientId` as `sub`, audience {@link APPLE_IDENTITY_ISSUER}, and expires
+ * 120 seconds after `now`. Used for Apple's token and revoke endpoints.
+ *
+ * @param config - Apple Team ID, key id, and PKCS#8 private key.
+ * @param clientId - Apple Services ID or native bundle id (`sub` claim).
+ * @param now - Unix time in seconds for `iat` / `exp`; injectable for deterministic tests.
+ *   Defaults to the system clock.
+ * @returns A compact ES256 JWT suitable as Apple's `client_secret`.
+ */
+export const createAppleClientSecret = async (config, clientId, now = Math.floor(Date.now() / 1000)) => new SignJWT({})
+    .setProtectedHeader({ alg: 'ES256', kid: config.keyId })
+    .setIssuer(config.teamId)
+    .setIssuedAt(now)
+    .setExpirationTime(now + 120)
+    .setAudience(APPLE_IDENTITY_ISSUER)
+    .setSubject(clientId)
+    .sign(await importPKCS8(config.privateKey, 'ES256'));

package/dist/index.d.ts

@@ -91,3 +91,5 @@ export { FirebaseIdTokenValidationError, JoseFirebaseVerifier, SECURETOKEN_JWK_U
 export { IdentityToolkit } from './firebase/identity-toolkit.js';
 export type { ServiceAccount } from './firebase/identity-toolkit.js';
 export { createRemoteFirebaseVerifier, createServiceAccountVerifier } from './firebase/remote-verifier.js';
+export { APPLE_IDENTITY_ISSUER, GOOGLE_IDENTITY_ISSUERS, createAppleClientSecret, hasFirebaseProviderIdentity, verifyAppleIdentityToken, verifyGoogleIdentityToken, } from './firebase/social-auth.js';
+export type { AppleClientSecretConfig } from './firebase/social-auth.js';

package/dist/index.js

@@ -67,3 +67,4 @@ export { getTemporaryCredentials } from './aws/sts.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';
+export { APPLE_IDENTITY_ISSUER, GOOGLE_IDENTITY_ISSUERS, createAppleClientSecret, hasFirebaseProviderIdentity, verifyAppleIdentityToken, verifyGoogleIdentityToken, } from './firebase/social-auth.js';

package/docs/api-db.md

@@ -27,7 +27,7 @@ compatibility_flags = ["nodejs_compat"]
 | `Database` / `DisposableDatabase` / `HyperdriveDatabase` / `ReadTransaction` / `QueryRunner` / `TxOf`                                    | The `read` / `query` / `readTransaction` / `write` / `transaction` API and its supporting types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `hyperdriveConnectionOptions(hyperdrive, overrides?)` / `HyperdriveLike` / `ExecutionContextLike`                                        | Build mysql2 `createConnection` options from a Hyperdrive binding (`disableEval`, `decimalNumbers`, `timezone '+09:00'` by default). `timezone` controls mysql2's JavaScript `Date` conversion; it does not change the MySQL session timezone.                                                                                                                                                                                                                                                                                                                                                                                           |
 | `withMysqlConnections(...)`                                                                                                              | Open primary/replica connections in parallel and run a function. Workers cleans them up at invocation end.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `retryWhenDeadlock(fn, retries?, delay?)`                                                                                                | Retry on MySQL `ER_LOCK_DEADLOCK` with exponential backoff.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `retryWhenDeadlock(fn, retries?, delay?)`                                                                                                | Retry on MySQL `ER_LOCK_DEADLOCK` with a wait of `delay × attempt` between attempts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `insertIdOf` / `affectedRowsOf` / `insertedIdsOf` / `DzWriteResult`                                                                      | Extract `insertId` / `affectedRows` (and derive contiguous bulk-insert ids) from a mysql2 write result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `toJstDate` / `jstTimestampParams` / `jstDatetimeParams` / `jstDateParams`                                                               | JST date/time normalization params (advanced use).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `MYSQL_TIMEZONE`                                                                                                                         | Default mysql2 connection `timezone` (`'+09:00'`) for the JST DB deployment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

package/docs/data-layer.md

@@ -3,11 +3,6 @@
 Standalone MySQL / Hyperdrive access for Workers, plus the thin Hono container adapter. Fixed
 `+09:00` storage helpers are independent of IANA display timezones.
 
-- [HTTP and Authentication](./http-auth.md)
-- [Realtime and Offline](./realtime-offline.md)
-- [Testing and Operations](./testing-operations.md)
-- [API reference](./api.md)
-
 Import database helpers from `@rdlabo/workers-mysql`. The package installs `mysql2` directly. Add
 `drizzle-orm` only when using the `/drizzle` or `/testing` entry point. The old
 `@rdlabo/workers-hono-kit/db` path is a deprecated compatibility re-export.
@@ -26,27 +21,11 @@ npm install -D @types/node@20
 
 For candidate tarball installation, see [Development](./development.md).
 
-## Migrating from workers-hono-kit
-
-The package boundary is a breaking change in `0.12.0`. Update these imports before
-upgrading:
-
-| Current import                                          | Replacement                                           |
-| ------------------------------------------------------- | ----------------------------------------------------- |
-| `createContainerRuntime` from the kit root              | `@rdlabo/workers-hono-kit/mysql`                      |
-| `retryWhenDeadlock` from the kit root                   | `@rdlabo/workers-mysql`                               |
-| DB helpers from `@rdlabo/workers-hono-kit/db`           | `@rdlabo/workers-mysql`, `/drizzle`, or `/migrations` |
-| DB test helpers from `@rdlabo/workers-hono-kit/testing` | `@rdlabo/workers-mysql/testing`                       |
-
-The old `/db` and DB-related `/testing` exports remain available for backward compatibility.
-Their individual functions and types carry `@deprecated` notices pointing to the standalone
-package. No removal release is scheduled. The kit-owned `/mysql` adapter is not deprecated.
-Because `/testing` statically re-exports DB helpers, all kit `/testing` consumers must install the
-MySQL package and `drizzle-orm`, including consumers of non-DB helpers such as Firebase or KV fakes.
-
 ## Hyperdrive database
 
-`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings. `read()` uses the replica query runner; `query()` provides an explicit raw primary SELECT for read-after-write consistency; writes and transactions use the primary Drizzle instance. `readTransaction()` runs Drizzle and raw reads against one primary repeatable-read snapshot. Read transactions are serialized on one separately cached connection so their boundaries cannot mix with each other or with ordinary primary operations. After a fatal mysql2 connection error, a single read or the complete read-only transaction opens a fresh connection and repeats at most once. Writes and write transactions are not repeated because their commit state may be ambiguous. Workers owns connection cleanup at invocation end.
+`createHyperdriveDatabase()` lazily opens primary and replica connections from Hyperdrive bindings.
+For read/write paths, retry boundaries, and invocation lifetime, see
+[Workers MySQL Runtime](https://docs.rdlabo.dev/projects/workers-mysql/docs/runtime).
 
 ```ts
 import { createHyperdriveDatabase } from '@rdlabo/workers-mysql';
@@ -84,7 +63,7 @@ import { createContainerRuntime } from '@rdlabo/workers-hono-kit/mysql';
 
 ## Writes and retries
 
-- `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with exponential backoff.
+- `retryWhenDeadlock()` retries `ER_LOCK_DEADLOCK` with a wait of `delay × attempt` between attempts.
 - `insertIdOf()`, `affectedRowsOf()`, and `insertedIdsOf()` normalize mysql2 write results.
 - `withMysqlConnections()` opens primary and replica connections in parallel for a scoped operation.
 
@@ -110,6 +89,24 @@ addBusinessDays('2026-07-06', 3);
 // '2026-07-09'
 ```
 
+## Migrating from workers-hono-kit
+
+The package boundary is a breaking change in `0.12.0`. Update these imports before
+upgrading:
+
+| Current import                                          | Replacement                                           |
+| ------------------------------------------------------- | ----------------------------------------------------- |
+| `createContainerRuntime` from the kit root              | `@rdlabo/workers-hono-kit/mysql`                      |
+| `retryWhenDeadlock` from the kit root                   | `@rdlabo/workers-mysql`                               |
+| DB helpers from `@rdlabo/workers-hono-kit/db`           | `@rdlabo/workers-mysql`, `/drizzle`, or `/migrations` |
+| DB test helpers from `@rdlabo/workers-hono-kit/testing` | `@rdlabo/workers-mysql/testing`                       |
+
+The old `/db` and DB-related `/testing` exports remain available for backward compatibility.
+Their individual functions and types carry `@deprecated` notices pointing to the standalone
+package. No removal release is scheduled. The kit-owned `/mysql` adapter is not deprecated.
+Because `/testing` statically re-exports DB helpers, all kit `/testing` consumers must install the
+MySQL package and `drizzle-orm`, including consumers of non-DB helpers such as Firebase or KV fakes.
+
 ## Next step
 
 Continue to [Realtime and Offline](./realtime-offline.md), or see

package/docs/http-auth.md

@@ -3,11 +3,6 @@
 Validation, Firebase authentication, shared NestJS-shaped error bodies, and response finalization
 for Hono Workers APIs.
 
-- [Data Layer](./data-layer.md)
-- [Realtime and Offline](./realtime-offline.md)
-- [Testing and Operations](./testing-operations.md)
-- [API reference](./api.md)
-
 ## Validation
 
 `validate(target, schema, options?)` adapts a Zod schema to Hono and returns a NestJS `ValidationPipe`-shaped `400` response. Use `createValidate({ sentry })` to bind optional reporting once.

package/docs/quickstart.md

@@ -0,0 +1,71 @@
+---
+title: Try a Hono API locally
+---
+
+Give a Hono API consistent HTTP behavior: a health response with a weak ETag and a predictable JSON response for missing routes. You will see both without opening a port or creating a Cloudflare account.
+
+## 1. Create a small project
+
+Use Node.js 24 and npm for this exercise. The commands pin the documented kit release. npm installs its required peers; package managers configured to omit peers must follow the [installation requirements](../README.md).
+
+```sh
+mkdir hono-kit-demo
+cd hono-kit-demo
+npm init -y
+npm pkg set type=module
+npm install @rdlabo/workers-hono-kit@0.12.2 hono@4
+npm install --save-dev tsx@4
+```
+
+## 2. Send two requests
+
+Save this as `demo.ts`. `app.request()` exercises the Hono app in the current process.
+
+```ts
+import { Hono } from 'hono';
+import { createAppErrorHandler, finalizeResponse, notFoundHandler } from '@rdlabo/workers-hono-kit';
+
+const app = new Hono();
+app.use('*', finalizeResponse());
+app.onError(createAppErrorHandler());
+app.notFound(notFoundHandler);
+app.get('/health', (c) => c.json({ ok: true }));
+
+const healthy = await app.request('/health');
+console.log(healthy.status, await healthy.text());
+console.log('weak etag:', healthy.headers.get('etag')?.startsWith('W/'));
+
+const missing = await app.request('/missing');
+console.log(missing.status, await missing.text());
+```
+
+```sh
+npx tsx demo.ts
+```
+
+Expected output (JSON property order does not matter):
+
+```text
+200 {"ok":true}
+weak etag: true
+404 {"message":"Cannot GET /missing","error":"Not Found","statusCode":404}
+```
+
+You have checked the HTTP behavior added by the kit. This exercise does not provision Workers bindings, authenticate users, or test a deployed service.
+
+## 3. Move into your application
+
+Keep the middleware and route registrations, remove the demonstration requests, and export `app` as your Worker handler. Continue with [HTTP and authentication](./http-auth.md). Add the [MySQL adapter](./data-layer.md) only when the application needs a database.
+
+Existing kit users should check [the 0.12 import migration](./data-layer.md) before upgrading. The old `/db` and `/business-time` paths are compatibility exports; new integrations use the standalone packages.
+
+## Next steps
+
+| You need                                    | Start with                                                                                     |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Shared Hono HTTP, auth, or queue behavior   | `@rdlabo/workers-hono-kit`                                                                     |
+| MySQL access, with or without Hono          | [Workers MySQL](https://docs.rdlabo.dev/projects/workers-mysql/docs/quickstart)                |
+| Timezone conversions and checks on new code | [Workers Timezone + ESLint](https://docs.rdlabo.dev/projects/workers-timezone/docs/quickstart) |
+| Code conventions during development         | [ESLint Plugin Rules](https://docs.rdlabo.dev/projects/eslint-plugin-rules/docs/quickstart)    |
+
+The kit supplies reusable infrastructure. Your routes, domain rules, credentials, and database schema remain in your application. Adopt one helper first; you do not need to adopt every entry point.

package/docs/realtime-offline.md

@@ -3,11 +3,6 @@
 Durable Object WebSocket helpers and table-agnostic offline replica contracts. Product schemas,
 Zod shapes, and domain policy stay in the application.
 
-- [HTTP and Authentication](./http-auth.md)
-- [Data Layer](./data-layer.md)
-- [Testing and Operations](./testing-operations.md)
-- [API reference](./api.md)
-
 ## Durable Object realtime
 
 The root and `/realtime` entry points expose the same focused realtime primitives:

package/docs/testing-operations.md

@@ -2,11 +2,6 @@
 
 Test helpers, queue batching, operational CLIs, and trust boundaries for Hono Workers applications.
 
-- [HTTP and Authentication](./http-auth.md)
-- [Data Layer](./data-layer.md)
-- [Realtime and Offline](./realtime-offline.md)
-- [API reference](./api.md)
-
 ## Testing entry point
 
 `@rdlabo/workers-hono-kit/testing` is never loaded by production code. Its DB helpers are deprecated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.12.2",
+  "version": "0.12.3-beta.pr51.sha3289ea609bb4",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -108,8 +108,8 @@
   },
   "peerDependencies": {
     "@hono/zod-validator": "^0.8.0",
-    "@rdlabo/workers-mysql": "^0.12.2",
-    "@rdlabo/workers-timezone": "^0.12.2",
+    "@rdlabo/workers-mysql": "0.12.3-beta.pr51.sha3289ea609bb4",
+    "@rdlabo/workers-timezone": "0.12.3-beta.pr51.sha3289ea609bb4",
     "ai": "^6.0.0",
     "ai-gateway-provider": "^3.1.0",
     "aws4fetch": "^1.0.20",