Persistent JWT Signing Keys with PostgreSQL

The previous article ended with this caveat:

In production, replace createInMemoryKeyStore() with a persistent store backed by a database or secrets manager so keys survive restarts.

This article does exactly that. We'll swap the in-memory key store for two PostgreSQL-backed implementations:

A JwksKeyStore that stores private keys with envelope encryption (AES-256-GCM, DEK + KEK) and public keys as plain JSON.
A JwksRotationTimestampStore that derives the last rotation time directly from the key record's creation time.

Everything else in index.ts (the flow builder, endpoints, login form) stays identical.

TL;DR

The full runnable example is available at Github (oidc-persistent-app).

The problem with in-memory keys

createInMemoryKeyStore() keeps key material in process memory. This has two consequences in production:

Scenario	What happens
Server restart	A new key pair is generated. All tokens issued before the restart are now unverifiable
Multiple instances / pods	Each instance generates its own key pair. Tokens verified by a different instance than the one that signed them will fail

The fix is straightforward: persist the key material to a shared store. Because private keys are sensitive, they must be stored encrypted.

Key concepts

@saurbit/oauth2-jwt defines two interfaces that JoseJwksAuthority and JwksRotator depend on:

JwksKeyStore manages key material:

interface JwksKeyStore {
  storeKeyPair(kid: string, privateKey: object, publicKey: object, ttl: number): Promise<void>;
  getPublicKeys(): Promise<object[]>;
  getPrivateKey(): Promise<object | undefined>;
}

JwksRotationTimestampStore tracks when the last rotation occurred:

interface JwksRotationTimestampStore {
  getLastRotationTimestamp(): Promise<number>;
  setLastRotationTimestamp(timestamp: number): Promise<void>;
}

In the in-memory version, createInMemoryKeyStore() returns a single object that satisfies both interfaces, so it can be passed for both jwksStore and rotationTimestampStore. For the persistent version we are going to make two separate objects, each backed by database queries.

Envelope encryption

Understanding DEK and KEK in Encryption: A Practical Guide.

Private keys MUST NEVER be stored in plaintext. This implementation uses an envelope encryption pattern:

A fresh random DEK (Data Encryption Key, 256-bit) is generated for each key pair.
The private key is serialized to JSON and encrypted with the DEK using AES-256-GCM.
The DEK itself is wrapped (encrypted) with a master KEK loaded from the MASTER_KEY environment variable.
The encrypted private key and the wrapped DEK are stored together in the database.

This means:

Even if the database is breached, the private keys are unreadable without the KEK.
The KEK lives only in the environment (or a secrets manager) and NEVER in the database.

Prerequisites

Start from the server built in the previous article. You need a PostgreSQL database (local, Neon, Supabase, etc.) and two environment variables:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`MASTER_KEY`	Base64-encoded 32-byte key (256 bits) used as the KEK

MASTER_KEY must be a base64-encoded 32-byte value. In a real deployment, store it in a secrets manager (AWS Secrets Manager, Vault, etc.) and inject it at runtime. Never commit it to source control.
You can generate a random Base64 of 32 bytes at Random Base64 String Generator.

Database schema

Create the two tables below. The private_keys table stores exactly one active row at a time enforced by UNIQUE (id) and CHECK (id = 1). Older private keys are overwritten on rotation, while public_keys accumulates all keys still within their TTL so that tokens signed with a previous key continue to verify until they expire.

CREATE TABLE IF NOT EXISTS private_keys
(
    key_id      character varying(255) NOT NULL,
    id          integer NOT NULL DEFAULT 1,
    private_key text NOT NULL,
    wrapped_dek text NOT NULL,
    expires_at  timestamp with time zone NOT NULL,
    created_at  timestamp with time zone NOT NULL DEFAULT now(),
    CONSTRAINT private_keys_pkey PRIMARY KEY (key_id),
    CONSTRAINT private_keys_id_unique UNIQUE (id),
    CONSTRAINT id CHECK (id = 1)
);

CREATE TABLE IF NOT EXISTS public_keys
(
    key_id     character varying(255) NOT NULL,
    public_key text NOT NULL,
    expires_at timestamp with time zone NOT NULL,
    created_at timestamp with time zone NOT NULL DEFAULT now(),
    CONSTRAINT public_keys_pkey PRIMARY KEY (key_id)
);

Step 1: Install the PostgreSQL driver

bun add pg
bun add -d @types/pg

Step 2: Write `src/db.ts`

This module owns all database access. It exposes typed interfaces and four query functions used by the stores.

import { Pool } from "pg";

const ENV_DATABASE_URL = process.env.DATABASE_URL;

const pool = new Pool({
  connectionString: ENV_DATABASE_URL,
  max: 10,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 2000,
  ssl: {
    rejectUnauthorized: false,
  },
});

export interface PrivateKeyRecord {
  keyId: string;
  privateKey: string;
  wrappedDek: string;
}

export interface PublicKeyRecord {
  keyId: string;
  publicKey: string;
}

`saveKeyPairRecord`

Persists both keys inside a transaction. The ON CONFLICT (id) DO UPDATE clause on private_keys ensures the table always contains at most one row and new rotations overwrite the old private key in-place.

export async function saveKeyPairRecord(
  privateKey: PrivateKeyRecord,
  publicKey: PublicKeyRecord,
  expirationTime: number
) {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    const createdAt = Date.now();
    const queryPrivateKey = `
      INSERT INTO private_keys (id, key_id, private_key, wrapped_dek, expires_at, created_at)
      VALUES ($1, $2, $3, $4, to_timestamp($5::bigint / 1000), to_timestamp($6::bigint / 1000))
      ON CONFLICT (id)
      DO UPDATE SET
        key_id     = EXCLUDED.key_id,
        private_key = EXCLUDED.private_key,
        wrapped_dek = EXCLUDED.wrapped_dek,
        expires_at  = EXCLUDED.expires_at,
        created_at  = EXCLUDED.created_at
      RETURNING *;
    `;
    const queryPublicKey = `
      INSERT INTO public_keys (key_id, public_key, expires_at, created_at)
      VALUES ($1, $2, to_timestamp($3::bigint / 1000), to_timestamp($4::bigint / 1000))
    `;
    await client.query(queryPrivateKey, [
      1,
      privateKey.keyId,
      privateKey.privateKey,
      privateKey.wrappedDek,
      expirationTime,
      createdAt,
    ]);
    await client.query(queryPublicKey, [
      publicKey.keyId,
      publicKey.publicKey,
      expirationTime,
      createdAt,
    ]);
    await client.query("COMMIT");
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

Read functions

export async function getPrivateKeyRecord(): Promise<PrivateKeyRecord | null> {
  const query = "SELECT * FROM private_keys WHERE expires_at > NOW() LIMIT 1";
  try {
    const res = await pool.query<{ key_id: string; private_key: string; wrapped_dek: string }>(
      query
    );
    if (res.rows.length > 0) {
      const row = res.rows[0];
      return {
        keyId: row.key_id,
        privateKey: row.private_key,
        wrappedDek: row.wrapped_dek,
      };
    }
  } catch (err) {
    console.error("Error fetching record:", err);
  }
  return null;
}

export async function getPublicKeyRecords(): Promise<PublicKeyRecord[] | null> {
  const query = "SELECT * FROM public_keys WHERE expires_at > NOW()";
  try {
    const { rows } = await pool.query<{ key_id: string; public_key: string }>(query);
    return rows.map((row) => ({ keyId: row.key_id, publicKey: row.public_key }));
  } catch (err) {
    console.error("Error fetching record:", err);
  }
  return null;
}

export async function getPrivateKeyCreatedAt(): Promise<Date | null> {
  const query = "SELECT created_at FROM private_keys WHERE expires_at > NOW() LIMIT 1";
  try {
    const { rows } = await pool.query<{ created_at: Date }>(query);
    if (rows.length > 0) {
      return rows[0].created_at;
    }
  } catch (err) {
    console.error("Error fetching record:", err);
  }
  return null;
}

getPublicKeyRecords returns all rows where expires_at is in the future and not just the current key. This is intentional: resource servers need to verify tokens signed with the previous key during the overlap period after a rotation.

Step 3: Write `src/stores.ts`

This module implements the two interfaces (JwksKeyStore, JwksRotationTimestampStore). It imports the DB functions from db.ts and handles all the encryption logic.

Imports and master key

import {
  getPrivateKeyCreatedAt,
  getPrivateKeyRecord,
  getPublicKeyRecords,
  PrivateKeyRecord,
  PublicKeyRecord,
  saveKeyPairRecord,
} from "./db";
import { JwksKeyStore, JwksRotationTimestampStore } from "@saurbit/oauth2-jwt";

/**
 * In a production environment, the master key (KEK) should be stored securely,
 * such as in an environment variable or a secrets manager.
 * It should never be hardcoded in the source code.
 * This should be a base64-encoded 32-byte key (256 bits) for AES-256 encryption.
 */
const ENV_MASTER_KEY = process.env.MASTER_KEY!;

const MASTER_KEY_RAW = base64ToUint8Array(ENV_MASTER_KEY);

Crypto helpers

Two small utilities (base64ToUint8Array, uint8ArrayToBase64) convert between Uint8Array and Base64 for storage, and two functions (decrypt, encrypt) wrap the Web Crypto API for AES-GCM encryption. The IV (12 random bytes) is prepended to the ciphertext so decrypt can split them back apart.

function uint8ArrayToBase64(uint8: Uint8Array): string {
  if (uint8.toBase64) {
    return uint8.toBase64();
  }
  return btoa(String.fromCharCode(...uint8));
}

function base64ToUint8Array(base64: string): Uint8Array<ArrayBuffer> {
  if (Uint8Array.fromBase64) {
    return Uint8Array.fromBase64(base64);
  }
  const binaryString = atob(base64);
  const len = binaryString.length;
  const bytes = new Uint8Array(len);
  for (let i = 0; i < len; i++) {
    bytes[i] = binaryString.charCodeAt(i);
  }
  return bytes;
}

async function encrypt(plaintext: string, rawKey: BufferSource): Promise<Uint8Array> {
  const encoder = new TextEncoder();
  const data = encoder.encode(plaintext);
  const key = await crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, ["encrypt"]);
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, data);
  const combined = new Uint8Array(iv.length + ciphertext.byteLength);
  combined.set(iv);
  combined.set(new Uint8Array(ciphertext), iv.length);
  return combined;
}

async function decrypt(combinedData: Uint8Array, rawKey: BufferSource): Promise<string> {
  const iv = combinedData.slice(0, 12);
  const ciphertext = combinedData.slice(12);
  const key = await crypto.subtle.importKey("raw", rawKey, { name: "AES-GCM" }, false, ["decrypt"]);
  const decrypted = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);
  return new TextDecoder().decode(decrypted);
}

`jwksStore` (JwksKeyStore)

storeKeyPair is called by JoseJwksAuthority whenever a new key pair is generated. The four-step envelope encryption process runs here:

export const jwksStore: JwksKeyStore = {
  async storeKeyPair(kid: string, privateKey: object, publicKey: object, ttl: number) {
    // 1. Generate a fresh, unique DEK (Data Encryption Key)
    const dekRaw = crypto.getRandomValues(new Uint8Array(32));

    // 2. Encrypt the private key with the DEK
    const encryptedPrivateKey = await encrypt(JSON.stringify(privateKey), dekRaw);

    // 3. Wrap (encrypt) the DEK using the Master Key (KEK)
    const wrappedDek = await encrypt(uint8ArrayToBase64(dekRaw), MASTER_KEY_RAW);

    // 4. Store the encrypted private key and the wrapped DEK together
    const expirationTime = Date.now() + ttl * 1000;
    const privateKeyRecord: PrivateKeyRecord = {
      keyId: kid,
      privateKey: uint8ArrayToBase64(encryptedPrivateKey),
      wrappedDek: uint8ArrayToBase64(wrappedDek),
    };
    const publicKeyRecord: PublicKeyRecord = {
      keyId: kid,
      publicKey: JSON.stringify(publicKey),
    };

    await saveKeyPairRecord(privateKeyRecord, publicKeyRecord, expirationTime);
  },

  async getPublicKeys(): Promise<object[]> {
    const publicKeyRecords = await getPublicKeyRecords();
    if (!publicKeyRecords) {
      return [];
    }
    return publicKeyRecords.map((record) => JSON.parse(record.publicKey));
  },

  async getPrivateKey(): Promise<object | undefined> {
    const privateKeyRecord = await getPrivateKeyRecord();
    if (!privateKeyRecord) {
      return undefined;
    }

    // 1. Unwrap (decrypt) the DEK using the Master Key (KEK)
    const wrappedDekBytes = base64ToUint8Array(privateKeyRecord.wrappedDek);
    const dekRawString = await decrypt(wrappedDekBytes, MASTER_KEY_RAW);
    const dekRaw = base64ToUint8Array(dekRawString);

    // 2. Decrypt the private key using the DEK
    const decryptedPrivateKeyString = await decrypt(
      base64ToUint8Array(privateKeyRecord.privateKey),
      dekRaw
    );

    return JSON.parse(decryptedPrivateKeyString);
  },
};

getPrivateKey reverses the process exactly: decode from Base64, unwrap the DEK with the KEK, then decrypt the private key with the DEK.

`rotationTimestampStore` (JwksRotationTimestampStore)

JwksRotator uses this interface to decide whether it's time to rotate. The persistent implementation reads created_at from the private key row directly, so no additional table is needed here.

setLastRotationTimestamp is intentionally left empty. The rotation timestamp is implicitly captured when storeKeyPair inserts a new row, created_at defaults to now(). Keeping a separate timestamp in sync would be redundant and risk drift.

export const rotationTimestampStore: JwksRotationTimestampStore = {
  async getLastRotationTimestamp(): Promise<number> {
    const createdAt = await getPrivateKeyCreatedAt();
    if (!createdAt) {
      return 0; // No keys yet, treat as never rotated
    }
    return createdAt.getTime();
  },

  async setLastRotationTimestamp(_timestamp: number): Promise<void> {
    // No-op: the rotation timestamp is derived from private_keys.created_at
  },
};

Step 4: Update `src/index.ts`

The change is minimal: swap the import and remove the local createInMemoryKeyStore() call.

Before:

import {
  createInMemoryKeyStore,
  JoseJwksAuthority,
  JwksRotator,
} from "@saurbit/oauth2-jwt";

// ...

const jwksStore = createInMemoryKeyStore();
const jwksAuthority = new JoseJwksAuthority(jwksStore, 8.64e6);

const jwksRotator = new JwksRotator({
  keyGenerator: jwksAuthority,
  rotationTimestampStore: jwksStore, // same object fulfilled both interfaces
  rotationIntervalMs: 7.884e9,
});

After:

import { jwksStore, rotationTimestampStore } from "./stores";
import { JoseJwksAuthority, JwksRotator } from "@saurbit/oauth2-jwt";

// ...

const jwksAuthority = new JoseJwksAuthority(jwksStore, 8.64e6);

const jwksRotator = new JwksRotator({
  keyGenerator: jwksAuthority,
  rotationTimestampStore: rotationTimestampStore, // now a separate object
  rotationIntervalMs: 7.884e9,
});

The rest of index.ts does not change.

Step 5: Run the server

Set the required environment variables and start the server:

bunx cross-env DATABASE_URL="postgres://..." MASTER_KEY="<base64-32-bytes>" bun dev

On startup, jwksRotator.checkAndRotateKeys() runs. If the private_keys table is empty (or the current key has passed the rotation interval), a new RSA key pair is generated, encrypted, and stored. The public key is written to public_keys and will be returned from /.well-known/jwks.json immediately.

Key rotation behavior

The server checks the rotation schedule on startup and then once per hour via setInterval. Here is what happens at each check:

getLastRotationTimestamp() reads created_at from the active private key row. If no row exists, it returns 0.
If now - lastRotation >= rotationIntervalMs (91 days in the example), JoseJwksAuthority.generateKeyPair() is called.
storeKeyPair runs: the new private key overwrites the single private_keys row; a new row is appended to public_keys.
The old public key row stays in public_keys until its expires_at is reached. During this window, both the old and new public keys are served from the JWKS endpoint, so tokens signed with the old key continue to verify correctly.

The key lifetime passed to JoseJwksAuthority (8.64e6 ms = 100 days) controls the expires_at stored in the database. It should be longer than the rotation interval (91 days) to ensure the overlap window exists.

Conclusion

This article showed how to implement a persistent key store for the OIDC server using PostgreSQL and envelope encryption. With this setup, signing keys survive server restarts and work correctly across multiple instances.

The management of cryptographic keys is a critical aspect of any authentication system, and this implementation provides a secure and scalable solution for handling keys in a real-world environment.

What's next

Add a consent screen for multi-tenant or third-party client scenarios
Support the refresh_token grant to issue long-lived sessions

推荐订阅源

DEV Community

TL;DR

The problem with in-memory keys

Key concepts

Envelope encryption

Prerequisites

Database schema

Step 1: Install the PostgreSQL driver

Step 2: Write `src/db.ts`

`saveKeyPairRecord`

Read functions

Step 3: Write `src/stores.ts`

Imports and master key

Crypto helpers

`jwksStore` (JwksKeyStore)

`rotationTimestampStore` (JwksRotationTimestampStore)

Step 4: Update `src/index.ts`

Step 5: Run the server

Key rotation behavior

Conclusion

What's next

推荐订阅源

DEV Community

TL;DR

The problem with in-memory keys

Key concepts

Envelope encryption

Prerequisites

Database schema

Step 1: Install the PostgreSQL driver

Step 2: Write src/db.ts

saveKeyPairRecord

Read functions

Step 3: Write src/stores.ts

Imports and master key

Crypto helpers

jwksStore (JwksKeyStore)

rotationTimestampStore (JwksRotationTimestampStore)

Step 4: Update src/index.ts

Step 5: Run the server

Key rotation behavior

Conclusion

What's next

Step 2: Write `src/db.ts`

`saveKeyPairRecord`

Step 3: Write `src/stores.ts`

`jwksStore` (JwksKeyStore)

`rotationTimestampStore` (JwksRotationTimestampStore)

Step 4: Update `src/index.ts`