Require explicit JWT key pair

Author: bean1352

demos/example-nextjs/.env.local.template

@@ -9,7 +9,8 @@ POWERSYNC_URL=http://localhost:8080
 # Used by Next.js API routes (localhost, since it runs outside Docker)
 DATABASE_URL=postgresql://postgres:changeme@localhost:5432/postgres
 
-# ── Optional ──────────────────────────────────────────────────────────────────
-# JWT_ISSUER=powersync-nextjs-demo
-# POWERSYNC_PRIVATE_KEY=<base64-encoded JWK>
-# POWERSYNC_PUBLIC_KEY=<base64-encoded JWK>
+# ── JWT key pair (required) ──────────────────────────────────────────────────
+# Generate with: pnpm generate-keys
+# Then paste the output below.
+POWERSYNC_PRIVATE_KEY=
+POWERSYNC_PUBLIC_KEY=

demos/example-nextjs/README.md

@@ -2,7 +2,7 @@
 
 PowerSync demo using [Next.js](https://nextjs.org/) and the [PowerSync JS web SDK](https://docs.powersync.com/client-sdk-references/js-web).
 
-Syncs data from a local Postgres through a self-hosted PowerSync service. No login required; the Next.js server hands out anonymous JWTs.
+Syncs data from a local Postgres through a self-hosted PowerSync service. No login required; the Next.js server hands out anonymous JWTs signed with a local key pair.
 
 ## Architecture
 
@@ -27,21 +27,37 @@ PowerSync -> GET /api/auth/keys -> Next.js API route -> JWKS (public key)
 ## Setup
 
 ```bash
-# Install deps
+# 1. Install deps
 pnpm install
 
-# Create env file (defaults work out of the box)
+# 2. Create env file
 cp .env.local.template .env.local
 
-# Start local Postgres + PowerSync
+# 3. Generate a JWT key pair and paste the output into .env.local
+pnpm generate-keys
+
+# 4. Start local Postgres + PowerSync
 pnpm local:up
 
-# Start Next.js
+# 5. Start Next.js
 pnpm dev
 ```
 
 Open [http://localhost:3000](http://localhost:3000).
 
+### About the key pair
+
+PowerSync validates JWTs the Next.js app issues by fetching a JWKS at [/api/auth/keys](src/app/api/auth/keys/route.ts). The private key signs tokens; the public key is what PowerSync fetches. Both must be set in `.env.local` — the app will refuse to start token issuance without them.
+
+`pnpm generate-keys` prints base64-encoded JWKs to stdout. Copy the two lines into `.env.local`:
+
+```
+POWERSYNC_PRIVATE_KEY=<base64>
+POWERSYNC_PUBLIC_KEY=<base64>
+```
+
+Restart `pnpm dev` after changing these values.
+
 ## Project structure
 
 ```
@@ -54,14 +70,13 @@ src/
 │   │   └── data/route.ts          CRUD writes to Postgres
 │   ├── globals.css
 │   ├── layout.tsx
-│   ├── page.tsx
-│   └── providers.tsx               PowerSync provider
+│   └── page.tsx
 ├── components/
 │   ├── CustomerList.tsx
 │   ├── StatusPanel.tsx
-│   └── SyncedContent.tsx           Client component for sync state
+│   └── SyncedContent.tsx
 └── library/
-    ├── auth-keys.ts                RSA key pair (server only)
+    ├── auth-keys.ts                Loads RSA key pair from env (server only)
     ├── db.ts                       Postgres pool (server only)
     └── powersync/
         ├── connector.ts            Fetch token + upload mutations
@@ -71,25 +86,26 @@ src/
 
 ## Environment variables
 
-All config lives in `.env.local`. Docker Compose also reads from this file (via a symlink at `powersync/docker/.env`). The template has working defaults.
+All config lives in `.env.local`. Docker Compose also reads from this file (via a symlink at `powersync/docker/.env`).
 
-| Variable | What it does |
-|---|---|
-| `POWERSYNC_URL` | PowerSync service URL, also used as the JWT audience |
-| `DATABASE_URL` | Postgres connection for Next.js API routes (uses `localhost`) |
-| `PS_DATABASE_*` | Postgres credentials used by Docker |
-| `PS_STORAGE_*` | Separate Postgres for PowerSync internal storage |
-| `PS_DATA_SOURCE_URI` | Postgres URI inside Docker (uses `pg-db` hostname) |
-| `PS_STORAGE_SOURCE_URI` | Storage Postgres URI inside Docker (uses `pg-storage` hostname) |
-| `POWERSYNC_PRIVATE_KEY` | (Optional) Base64-encoded JWK private key. Auto-generated if not set |
-| `POWERSYNC_PUBLIC_KEY` | (Optional) Base64-encoded JWK public key. Auto-generated if not set |
+| Variable | Required | What it does |
+|---|---|---|
+| `POWERSYNC_URL` | yes | PowerSync service URL, also used as the JWT audience |
+| `DATABASE_URL` | yes | Postgres connection for Next.js API routes (uses `localhost`) |
+| `POWERSYNC_PRIVATE_KEY` | yes | Base64-encoded JWK private key — generate with `pnpm generate-keys` |
+| `POWERSYNC_PUBLIC_KEY` | yes | Base64-encoded JWK public key — generate with `pnpm generate-keys` |
+| `PS_DATABASE_*` | yes | Postgres credentials used by Docker |
+| `PS_STORAGE_*` | yes | Separate Postgres for PowerSync internal storage |
+| `PS_DATA_SOURCE_URI` | yes | Postgres URI inside Docker (uses `pg-db` hostname) |
+| `PS_STORAGE_SOURCE_URI` | yes | Storage Postgres URI inside Docker (uses `pg-storage` hostname) |
 
 ## Scripts
 
 | Command | What it does |
 |---|---|
 | `pnpm dev` | Start Next.js dev server |
 | `pnpm build` | Production build |
+| `pnpm generate-keys` | Print a fresh JWT key pair for `.env.local` |
 | `pnpm local:up` | Start PowerSync + Postgres via Docker |
 | `pnpm local:down` | Stop Docker stack |
 

demos/example-nextjs/package.json

@@ -8,6 +8,7 @@
     "start": "next start",
     "lint": "next lint",
     "clean": "rm -rf .next",
+    "generate-keys": "node --experimental-strip-types scripts/generate-keys.mts",
     "copy-assets": "powersync-web copy-assets -o public",
     "postinstall": "pnpm copy-assets",
     "local:up": "powersync docker start --directory powersync",

demos/example-nextjs/scripts/generate-keys.mts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import * as jose from 'jose';
+import crypto from 'node:crypto';
+
+async function main() {
+  const alg = 'RS256';
+  const kid = `powersync-${crypto.randomBytes(5).toString('hex')}`;
+
+  const { publicKey, privateKey } = await jose.generateKeyPair(alg, { extractable: true });
+
+  const privateJwk: jose.JWK = { ...(await jose.exportJWK(privateKey)), alg, kid };
+  const publicJwk: jose.JWK = { ...(await jose.exportJWK(publicKey)), alg, kid };
+
+  const privateBase64 = Buffer.from(JSON.stringify(privateJwk)).toString('base64');
+  const publicBase64 = Buffer.from(JSON.stringify(publicJwk)).toString('base64');
+
+  console.log(`Public Key:
+${JSON.stringify(publicJwk, null, 2)}
+
+---
+
+Add the following to your .env.local file:
+
+POWERSYNC_PUBLIC_KEY=${publicBase64}
+
+POWERSYNC_PRIVATE_KEY=${privateBase64}
+`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

demos/example-nextjs/src/app/api/auth/keys/route.ts

@@ -4,6 +4,12 @@ import { NextResponse } from 'next/server';
 // JWKS endpoint. PowerSync hits this to verify client tokens.
 // See powersync/service.yaml -> client_auth.jwks_uri
 export async function GET() {
-  const { publicJwk } = await getKeyPair();
-  return NextResponse.json({ keys: [publicJwk] });
+  try {
+    const { publicJwk } = await getKeyPair();
+    return NextResponse.json({ keys: [publicJwk] });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    console.error('[api/auth/keys]', message);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
 }

demos/example-nextjs/src/app/api/auth/token/route.ts

@@ -1,21 +1,28 @@
 import { getKeyPair } from '@/library/auth-keys';
 import { SignJWT } from 'jose';
-import { NextResponse } from 'next/server';
+import { NextRequest, NextResponse } from 'next/server';
 
 const POWERSYNC_URL = process.env.POWERSYNC_URL ?? 'http://localhost:8080';
+const JWT_ISSUER = 'powersync-nextjs-demo';
 
-/** Returns a signed JWT for PowerSync. No login required. */
-export async function GET() {
-  const { privateKey, publicJwk } = await getKeyPair();
+export async function GET(req: NextRequest) {
+  try {
+    const userId = req.nextUrl.searchParams.get('user_id') ?? 'anonymous';
+    const { privateKey, alg, kid } = await getKeyPair();
 
-  const token = await new SignJWT({})
-    .setProtectedHeader({ alg: 'RS256', kid: publicJwk.kid })
-    .setSubject('anonymous')
-    .setIssuedAt()
-    .setIssuer(process.env.JWT_ISSUER ?? 'powersync-nextjs-demo')
-    .setAudience(POWERSYNC_URL)
-    .setExpirationTime('5m')
-    .sign(privateKey);
+    const token = await new SignJWT({})
+      .setProtectedHeader({ alg, kid })
+      .setSubject(userId)
+      .setIssuedAt()
+      .setIssuer(JWT_ISSUER)
+      .setAudience(POWERSYNC_URL)
+      .setExpirationTime('5m')
+      .sign(privateKey);
 
-  return NextResponse.json({ token, powersync_url: POWERSYNC_URL });
+    return NextResponse.json({ token, powersync_url: POWERSYNC_URL });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Unknown error';
+    console.error('[api/auth/token]', message);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
 }

demos/example-nextjs/src/app/layout.tsx

@@ -1,5 +1,5 @@
 import type { Metadata } from 'next';
-import { Providers } from './providers';
+import { PowerSyncProvider } from '@/library/powersync/powersync-provider';
 import './globals.css';
 
 export const metadata: Metadata = {
@@ -10,7 +10,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="en" className="dark">
       <body>
-        <Providers>{children}</Providers>
+        <PowerSyncProvider>{children}</PowerSyncProvider>
       </body>
     </html>
   );

demos/example-nextjs/src/app/providers.tsx

@@ -3,16 +3,14 @@
 import { CustomerList } from '@/components/CustomerList';
 import { StatusPanel } from '@/components/StatusPanel';
 import { useStatus } from '@powersync/react';
-import Image from 'next/image';
 
 export function SyncedContent() {
   const status = useStatus();
 
   if (!status.hasSynced) {
     return (
-      <div className="flex flex-col items-center gap-2 py-24">
-        <Image src="/powersync-logo.svg" alt="PowerSync" width={220} height={34} priority />
-        <div className="mt-4 size-8 animate-spin rounded-full border-2 border-primary border-t-transparent" />
+      <div className="flex flex-col items-center gap-2 py-12">
+        <div className="size-8 animate-spin rounded-full border-2 border-primary border-t-transparent" />
         <p className="mt-2 text-sm text-text-muted">Connecting…</p>
       </div>
     );

demos/example-nextjs/src/components/SyncedContent.tsx

@@ -1,42 +1,47 @@
-import { exportJWK, generateKeyPair as joseGenerateKeyPair, importJWK, KeyLike } from 'jose';
+import { importJWK, type JWK, type KeyLike } from 'jose';
 
-interface KeyPair {
+// For production, consider caching the imported key to avoid re-parsing on every request.
+export async function getKeyPair(): Promise<{
   privateKey: KeyLike;
-  publicJwk: JsonWebKey & { kid: string; alg: string };
-}
-
-/**
- * Generates a key pair if none is available on the env.
- * Uses globalThis to survive Next.js HMR — without this, dev-mode module
- * reloads regenerate the keys while the PowerSync service still holds the
- * old public key, causing "signature verification failed" errors.
- */
-async function ensureKeyPair(): Promise<KeyPair> {
-  const g = globalThis as Record<string, unknown>;
-  if (g.__powersync_keypair) return g.__powersync_keypair as KeyPair;
-
+  publicJwk: JWK & { kid: string; alg: string };
+  alg: string;
+  kid: string;
+}> {
   const envPrivate = process.env.POWERSYNC_PRIVATE_KEY;
   const envPublic = process.env.POWERSYNC_PUBLIC_KEY;
 
-  let privateKey: KeyLike;
-  let publicJwk: JsonWebKey & { kid: string; alg: string };
+  if (!envPrivate || !envPublic) {
+    throw new Error(
+      'POWERSYNC_PRIVATE_KEY and POWERSYNC_PUBLIC_KEY are not set in .env.local. Run `pnpm generate-keys` and paste the output into .env.local, then restart the dev server.'
+    );
+  }
+
+  const privateJwk = parseJwk('POWERSYNC_PRIVATE_KEY', envPrivate);
+  const publicJwk = parseJwk('POWERSYNC_PUBLIC_KEY', envPublic);
 
-  if (envPrivate && envPublic) {
-    const privateJwk = JSON.parse(Buffer.from(envPrivate, 'base64').toString());
-    privateKey = (await importJWK(privateJwk)) as KeyLike;
-    publicJwk = JSON.parse(Buffer.from(envPublic, 'base64').toString());
-  } else {
-    console.warn('POWERSYNC_PRIVATE_KEY not set. Generating a temporary key pair (will not survive restarts).');
-    const generated = await joseGenerateKeyPair('RS256', { extractable: true });
-    privateKey = generated.privateKey;
-    publicJwk = (await exportJWK(generated.publicKey)) as JsonWebKey & { kid: string; alg: string };
-    publicJwk.alg = 'RS256';
-    publicJwk.kid = 'powersync-anon-key';
+  if (privateJwk.kid !== publicJwk.kid) {
+    throw new Error(
+      `POWERSYNC_PRIVATE_KEY and POWERSYNC_PUBLIC_KEY have mismatched kids (${privateJwk.kid} vs ${publicJwk.kid}). Run \`pnpm generate-keys\` to create a matching pair.`
+    );
   }
 
-  const pair: KeyPair = { privateKey, publicJwk };
-  g.__powersync_keypair = pair;
-  return pair;
+  const privateKey = (await importJWK(privateJwk)) as KeyLike;
+  return { privateKey, publicJwk, alg: privateJwk.alg, kid: privateJwk.kid };
 }
 
-export { ensureKeyPair as getKeyPair };
+function parseJwk(name: string, base64: string): JWK & { kid: string; alg: string } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(base64, 'base64').toString());
+  } catch {
+    throw new Error(`${name} could not be decoded. Run \`pnpm generate-keys\` and paste the output into .env.local.`);
+  }
+
+  const jwk = parsed as Partial<JWK> & { kid?: string; alg?: string };
+  if (!jwk || typeof jwk !== 'object' || !jwk.kty || !jwk.alg || !jwk.kid) {
+    throw new Error(
+      `${name} is missing required JWK fields (kty, alg, kid). Run \`pnpm generate-keys\` to create a fresh pair.`
+    );
+  }
+  return jwk as JWK & { kid: string; alg: string };
+}