@rdlabo/workers-hono-kit 0.12.2 → 0.12.3

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,11 @@ 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.
 
+Google and Apple login endpoints can use the root exports `verifyGoogleIdentityToken`,
+`verifyAppleIdentityToken`, and `hasFirebaseProviderIdentity`. Apple token exchange can additionally
+use `createAppleClientSecret`. Applications keep ownership of HTTP responses, persistence, and
+provider token exchange or revocation; the Kit owns only reusable token verification and signing.
+
 ## 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,13 @@
+import type { JWTVerifyGetKey } from 'jose';
+import type { DecodedIdToken } from './firebase-verifier.js';
+export declare const APPLE_IDENTITY_ISSUER = "https://appleid.apple.com";
+export declare const GOOGLE_IDENTITY_ISSUERS: readonly ["https://accounts.google.com", "accounts.google.com"];
+export declare const verifyAppleIdentityToken: (idToken: string, audience: string, getKey?: JWTVerifyGetKey) => Promise<string>;
+export declare const verifyGoogleIdentityToken: (idToken: string, audience: string | readonly string[], getKey?: JWTVerifyGetKey) => Promise<string>;
+export declare const hasFirebaseProviderIdentity: (token: DecodedIdToken, providerId: string, subject: string, requireSignInProvider?: boolean) => boolean;
+export interface AppleClientSecretConfig {
+    privateKey: string;
+    keyId: string;
+    teamId: string;
+}
+export declare const createAppleClientSecret: (config: AppleClientSecretConfig, clientId: string, now?: number) => Promise<string>;

package/dist/firebase/social-auth.js

@@ -0,0 +1,37 @@
+import { SignJWT, createRemoteJWKSet, importPKCS8, jwtVerify } from 'jose';
+export const APPLE_IDENTITY_ISSUER = 'https://appleid.apple.com';
+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'));
+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;
+};
+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;
+};
+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));
+};
+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",
   "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",
+    "@rdlabo/workers-timezone": "^0.12.3",
     "ai": "^6.0.0",
     "ai-gateway-provider": "^3.1.0",
     "aws4fetch": "^1.0.20",