feat(adapters): persist generated GitHub App keys

README.md

@@ -1074,6 +1074,8 @@ export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
 })
 ```
 
+GitHub App seeds may omit `private_key`. Retain the handler to call server-only `generatedSecrets()`; explicit keys are excluded. Persisted snapshots contain generated keys, so keep the backend private.
+
 ### Auth.js / NextAuth configuration
 
 Point your provider at the emulator paths on the same origin:
@@ -1143,7 +1145,7 @@ import { filePersistence } from '@emulators/core'
 persistence: filePersistence('.emulate/state.json'),
 ```
 
-The persistence adapter is called on cold start (load) and after every mutating request (save). Saves are serialized via an internal queue to prevent race conditions.
+The persistence adapter loads on cold start and saves after mutations. Generated identities also require atomic create-or-read `initialize`; see `@emulators/core`.
 
 ## Nuxt Integration
 
@@ -1186,6 +1188,8 @@ export default defineEventHandler(createEmulateHandler({
 }))
 ```
 
+GitHub App seeds may omit `private_key`. Retain the handler to call server-only `generatedSecrets()`; explicit keys are excluded. Persisted snapshots contain generated keys, so keep the backend private.
+
 ### Nuxt config
 
 Emulator UI pages use bundled fonts. Wrap your Nuxt config so Nitro traces the core package assets into production builds:
@@ -1236,7 +1240,7 @@ export default defineEventHandler(createEmulateHandler({
 }))
 ```
 
-The persistence adapter is called on cold start (load) and after every mutating request (save). Saves are serialized via an internal queue to prevent race conditions.
+The persistence adapter loads on cold start and saves after mutations. Generated identities also require atomic create-or-read `initialize`; see `@emulators/core`.
 
 ## Architecture
 

apps/web/app/docs/github/page.mdx

@@ -29,6 +29,8 @@ const privateKey = github.generatedSecrets.find(
 
 The generated RSA-2048 PKCS#1 key remains stable across `reset()` calls. Explicit keys are never included in `generatedSecrets`.
 
+The Next.js and Nuxt adapters also generate omitted keys. Their returned server handlers expose `generatedSecrets()`, and persistence restores the same identity across cold starts. Keep persisted snapshots private because they contain the signing key. Custom persistence backends must implement atomic `initialize()` semantics when generated identities are used.
+
 The CLI can generate omitted keys when you request a private delivery file:
 
 ```bash

apps/web/app/docs/nextjs/page.mdx

@@ -44,6 +44,10 @@ This creates the following routes:
 - `/emulate/github/**` serves the GitHub emulator
 - `/emulate/google/**` serves the Google emulator
 
+## GitHub App Private Keys
+
+GitHub App seeds may omit `private_key`; retain the handler and call server-only `generatedSecrets()`. Keep persisted generated keys private and implement atomic `initialize`.
+
 ## Auth.js / NextAuth Configuration
 
 Point your provider at the emulator paths on the same origin:
@@ -117,6 +121,8 @@ import { filePersistence } from '@emulators/core'
 persistence: filePersistence('.emulate/state.json'),
 ```
 
+Generated identities require atomic create-or-read `initialize`; see `@emulators/core`.
+
 ### How It Works
 
 - **Cold start**: The adapter loads state from the persistence adapter. If found, it restores the full Store and token map (skipping seed). If not found, it seeds from config and saves the initial state.
@@ -134,4 +140,4 @@ persistence: filePersistence('.emulate/state.json'),
 ## Limitations
 
 - Requires the Node.js runtime (not Edge) since emulators use `crypto.randomBytes`
-- Concurrent serverless instances writing to the same persistence adapter use last-write-wins semantics (acceptable for dev/preview traffic)
+- Concurrent mutations use last-write-wins semantics. Generated identities use `initialize` to select the initial snapshot atomically across cold starts.

apps/web/app/docs/nuxt/page.mdx

@@ -44,6 +44,10 @@ This creates these routes:
 - `/emulate/github/**` serves the GitHub emulator
 - `/emulate/google/**` serves the Google emulator
 
+## GitHub App Private Keys
+
+GitHub App seeds may omit `private_key`; retain the handler and call server-only `generatedSecrets()`. Keep persisted generated keys private and implement atomic `initialize`.
+
 ## Nuxt Config
 
 Emulator UI pages use bundled fonts. Wrap your Nuxt config so Nitro traces the core package assets into production builds:
@@ -106,6 +110,8 @@ import { filePersistence } from '@emulators/core'
 persistence: filePersistence('.emulate/state.json'),
 ```
 
+Generated identities require atomic create-or-read `initialize`; see `@emulators/core`.
+
 ### How It Works
 
 - **Cold start**: The adapter loads state from the persistence adapter. If found, it restores the full Store and token map. If not found, it seeds from config and saves the initial state.
@@ -137,4 +143,4 @@ export default defineEventHandler(createEmulateHandler(config, { routePrefix: '/
 ## Limitations
 
 - Requires a Node-compatible Nuxt server runtime since emulators use Node APIs
-- Concurrent serverless instances writing to the same persistence adapter use last write wins semantics, which is acceptable for dev and preview traffic
+- Concurrent mutations use last-write-wins semantics. Generated identities use `initialize` to select the initial snapshot atomically across cold starts.

packages/@emulators/adapter-next/README.md

@@ -26,7 +26,7 @@ import { createEmulateHandler } from '@emulators/adapter-next'
 import * as github from '@emulators/github'
 import * as google from '@emulators/google'
 
-export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
+export const emulator = createEmulateHandler({
   services: {
     github: {
       emulator: github,
@@ -43,8 +43,12 @@ export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
     },
   },
 })
+
+export const { GET, POST, PUT, PATCH, DELETE } = emulator
 ```
 
+GitHub App seeds may omit `private_key`. Read generated keys with the handler's server-only `generatedSecrets()` method. Explicit keys are excluded; persisted snapshots contain generated keys and require a private backend with atomic `initialize`.
+
 ## Auth.js / NextAuth configuration
 
 Point your provider at the emulator paths on the same origin:

packages/@emulators/adapter-next/package.json

@@ -31,14 +31,17 @@
     "build": "tsup --clean",
     "dev": "tsup --watch",
     "clean": "rm -rf dist .turbo",
+    "test": "vitest run",
     "type-check": "tsc --noEmit",
     "lint": "eslint src"
   },
   "dependencies": {
     "@emulators/core": "workspace:*"
   },
   "devDependencies": {
+    "@emulators/github": "workspace:*",
     "tsup": "^8",
-    "typescript": "^5.7"
+    "typescript": "^5.7",
+    "vitest": "^4.1.0"
   }
 }

packages/@emulators/adapter-next/src/__tests__/github-app-identity.test.ts

@@ -0,0 +1,31 @@
+import * as github from "@emulators/github";
+import { githubAppIdentityContract, type TestPersistence } from "../../../../../tests/contracts/github-app-identity.js";
+import { createEmulateHandler, type EmulateHandlerConfig } from "../index.js";
+function config(persistence?: TestPersistence, privateKey?: string): EmulateHandlerConfig {
+  return {
+    services: {
+      github: {
+        emulator: github,
+        seed: { apps: [{ app_id: 123, slug: "embedded", name: "Embedded", private_key: privateKey }] },
+      },
+    },
+    persistence,
+  };
+}
+githubAppIdentityContract<EmulateHandlerConfig, ReturnType<typeof createEmulateHandler>>({
+  createEmulateHandler,
+  config,
+  async createExplicitPrivateKey() {
+    const prepared = await github.materializeGitHubSeedConfig({ apps: [{ app_id: 123, slug: "key", name: "Key" }] });
+    return prepared.config.apps![0]!.private_key!;
+  },
+  requestApp(handler, authorization, method = "GET") {
+    return handler[method](
+      new Request("http://localhost/emulate/github/app", {
+        method,
+        headers: authorization ? { Authorization: authorization } : undefined,
+      }),
+      { params: Promise.resolve({ path: ["github", "app"] }) },
+    );
+  },
+});