@hilbras/keystone 1.1.0

package/src/services/queue/bullmq.ts

@@ -0,0 +1,104 @@
+import { Queue as BullQueue, Worker, type Job as BullJob } from "bullmq";
+import type { Queue, Job, JobHandler, QueueStats } from "./types.js";
+
+export class BullMQQueue implements Queue {
+  private queue: BullQueue;
+  private workers = new Map<string, Worker>();
+  private handlers = new Map<string, JobHandler>();
+  private redisUrl: string;
+
+  constructor(redisUrl: string) {
+    this.redisUrl = redisUrl;
+    this.queue = new BullQueue("keystone", {
+      connection: { url: redisUrl },
+      defaultJobOptions: {
+        removeOnComplete: 100,
+        removeOnFail: 100,
+        attempts: 3,
+        backoff: { type: "exponential", delay: 1000 },
+      },
+    });
+  }
+
+  async enqueue<T>(job: Job<T>): Promise<void> {
+    await this.queue.add(job.type, job.payload, {
+      jobId: job.id,
+      attempts: job.attempts ?? 3,
+    });
+  }
+
+  process(type: string, handler: JobHandler): void {
+    if (this.handlers.has(type)) {
+      console.warn(`[bullmq-queue] handler for ${type} already registered`);
+      return;
+    }
+    this.handlers.set(type, handler);
+
+    const worker = new Worker(
+      "keystone",
+      async (bullJob: BullJob) => {
+        const job: Job = {
+          id: bullJob.id,
+          type: bullJob.name,
+          payload: bullJob.data,
+          attempts: bullJob.attemptsMade,
+          createdAt: bullJob.timestamp ? new Date(bullJob.timestamp) : undefined,
+        };
+        await handler(job);
+      },
+      {
+        connection: { url: this.redisUrl },
+        concurrency: 5,
+      }
+    );
+
+    worker.on("failed", (job, err) => {
+      console.error(`[bullmq-queue] job ${job?.name} ${job?.id} failed:`, err);
+    });
+
+    this.workers.set(type, worker);
+  }
+
+  async getStats(): Promise<QueueStats[]> {
+    const counts = await this.queue.getJobCounts("waiting", "active", "completed", "failed", "delayed");
+    return [
+      {
+        type: "all",
+        count: (counts.waiting ?? 0) + (counts.active ?? 0) + (counts.completed ?? 0),
+        failed: counts.failed ?? 0,
+        delayed: counts.delayed ?? 0,
+      },
+    ];
+  }
+
+  async getFailed(limit = 50): Promise<Job[]> {
+    const jobs = await this.queue.getFailed(0, limit);
+    return jobs.map((j) => ({
+      id: String(j.id),
+      type: j.name,
+      payload: j.data,
+      attempts: j.attemptsMade,
+      createdAt: j.timestamp ? new Date(j.timestamp) : undefined,
+    }));
+  }
+
+  async retry(jobId: string): Promise<void> {
+    const job = await this.queue.getJob(jobId);
+    if (job) await job.retry();
+  }
+
+  async retryAll(): Promise<void> {
+    const jobs = await this.queue.getFailed();
+    await Promise.all(jobs.map((j) => j.retry()));
+  }
+
+  async close(): Promise<void> {
+    await Promise.all(Array.from(this.workers.values()).map((worker) => worker.close()));
+    await this.queue.close();
+    // Reset registries so a closed instance (e.g. the shared singleton after a
+    // test's app.close()) can accept process()/enqueue() again with fresh
+    // connections instead of silently reusing dead ones.
+    this.workers.clear();
+    this.handlers.clear();
+  }
+}

package/src/services/queue/inProcess.ts

@@ -0,0 +1,75 @@
+import type { Queue, Job, JobHandler, QueueStats } from "./types.js";
+
+const DEFAULT_ATTEMPTS = 3;
+
+export class InProcessQueue implements Queue {
+  private handlers = new Map<string, JobHandler>();
+  private stats = new Map<string, { count: number; failed: number }>();
+
+  async enqueue<T>(job: Job<T>): Promise<void> {
+    setImmediate(() => {
+      this.run(job, 1).catch((err) => {
+        console.error(`[in-process-queue] job ${job.type} failed permanently:`, err);
+      });
+    });
+  }
+
+  process(type: string, handler: JobHandler): void {
+    this.handlers.set(type, handler);
+  }
+
+  async getStats(): Promise<QueueStats[]> {
+    return Array.from(this.stats.entries()).map(([type, s]) => ({
+      type,
+      count: s.count,
+      failed: s.failed,
+    }));
+  }
+
+  async getFailed(): Promise<Job[]> {
+    return [];
+  }
+
+  async retry(): Promise<void> {
+    // No persisted failed jobs in the in-process queue.
+  }
+
+  async retryAll(): Promise<void> {
+    // No persisted failed jobs in the in-process queue.
+  }
+
+  async close(): Promise<void> {
+    this.handlers.clear();
+    this.stats.clear();
+  }
+
+  private async run(job: Job, attempt: number): Promise<void> {
+    const handler = this.handlers.get(job.type);
+    if (!handler) {
+      console.warn(`[in-process-queue] no handler registered for ${job.type}`);
+      return;
+    }
+
+    this.increment(job.type, "count");
+
+    try {
+      await handler(job);
+    } catch (err) {
+      const maxAttempts = job.attempts ?? DEFAULT_ATTEMPTS;
+      if (attempt < maxAttempts) {
+        const delay = Math.min(1000 * 2 ** (attempt - 1), 30000);
+        console.warn(`[in-process-queue] job ${job.type} failed (attempt ${attempt}/${maxAttempts}), retrying in ${delay}ms`);
+        setTimeout(() => this.run(job, attempt + 1), delay);
+        return;
+      }
+      this.increment(job.type, "failed");
+      throw err;
+    }
+  }
+
+  private increment(type: string, key: "count" | "failed"): void {
+    const current = this.stats.get(type) ?? { count: 0, failed: 0 };
+    current[key]++;
+    this.stats.set(type, current);
+  }
+}

package/src/services/queue/index.ts

@@ -0,0 +1,19 @@
+import { config } from "../../config.js";
+import { InProcessQueue } from "./inProcess.js";
+import { BullMQQueue } from "./bullmq.js";
+import type { Queue } from "./types.js";
+
+export * from "./types.js";
+export { InProcessQueue } from "./inProcess.js";
+export { BullMQQueue } from "./bullmq.js";
+
+export function createQueue(): Queue {
+  const explicitProvider = config.KEYSTONE_QUEUE_PROVIDER;
+  if (explicitProvider === "in-process") return new InProcessQueue();
+  if (explicitProvider === "bullmq") return new BullMQQueue(config.REDIS_URL);
+  // Default to bullmq when Redis is available, otherwise fall back to in-process.
+  if (config.REDIS_URL) return new BullMQQueue(config.REDIS_URL);
+  return new InProcessQueue();
+}
+
+export const queue = createQueue();

package/src/services/queue/types.ts

@@ -0,0 +1,26 @@
+export interface Job<T = unknown> {
+  id?: string;
+  type: string;
+  payload: T;
+  attempts?: number;
+  createdAt?: Date;
+}
+
+export type JobHandler = (job: Job) => void | Promise<void>;
+
+export interface QueueStats {
+  type: string;
+  count: number;
+  failed?: number;
+  delayed?: number;
+}
+
+export interface Queue {
+  enqueue<T>(job: Job<T>): Promise<void>;
+  process(type: string, handler: JobHandler): void;
+  getStats?(): Promise<QueueStats[]>;
+  getFailed?(limit: number): Promise<Job[]>;
+  retry?(jobId: string): Promise<void>;
+  retryAll?(): Promise<void>;
+  close?(): Promise<void>;
+}

package/src/services/redis.ts

@@ -0,0 +1,16 @@
+import { Redis } from "ioredis";
+import { config } from "../config.js";
+
+/**
+ * Shared Redis connection used by rate limiting, anomaly detection, and any
+ * other distributed state in Keystone. Lazy connection means the process will
+ * not fail at import time if Redis is temporarily unavailable.
+ */
+export const redis = new Redis(config.REDIS_URL, {
+  maxRetriesPerRequest: 3,
+  lazyConnect: true,
+});
+
+export function isRedisReady(): boolean {
+  return redis.status === "ready" || redis.status === "connect";
+}

package/src/services/secrets/awsKms.ts

@@ -0,0 +1,97 @@
+import crypto from "node:crypto";
+import { importPKCS8, importSPKI, exportPKCS8, exportSPKI, generateKeyPair } from "jose";
+import type { SecretsProvider, SigningKeyPair } from "./provider.js";
+import { hashPassword, verifyPassword } from "./password.js";
+
+/**
+ * AWS KMS secrets provider reference implementation.
+ *
+ * In a real deployment this would use the AWS SDK to:
+ * - Store/retrieve JWT signing keys in AWS Secrets Manager or Parameter Store
+ * - Use KMS for envelope encryption of secrets
+ *
+ * The current implementation keeps keys in memory and encrypts the data
+ * encryption key (DEK) with a KMS key ID supplied via KMS_KEY_ID. It is
+ * intended as a starting point for a full AWS integration.
+ */
+export class AwsKmsSecretsProvider implements SecretsProvider {
+  readonly name = "aws-kms";
+
+  hashPassword = hashPassword;
+  verifyPassword = verifyPassword;
+
+  private kmsKeyId?: string;
+  private keyPair: SigningKeyPair | null = null;
+
+  constructor() {
+    this.kmsKeyId = process.env.KMS_KEY_ID;
+    if (!this.kmsKeyId) {
+      throw new Error("AwsKmsSecretsProvider requires KMS_KEY_ID");
+    }
+  }
+
+  hashApiKey(key: string): string {
+    return crypto.createHash("sha256").update(key).digest("hex");
+  }
+
+  hashClientSecret(secret: string): string {
+    return crypto.createHash("sha256").update(secret).digest("hex");
+  }
+
+  generateClientSecret(): string {
+    return `cs_${crypto.randomBytes(32).toString("base64url")}`;
+  }
+
+  generateApiKey(): { key: string; prefix: string } {
+    const key = `ks_${crypto.randomBytes(32).toString("base64url")}`;
+    return { key, prefix: key.slice(0, 7) };
+  }
+
+  async getActiveSigningKey(): Promise<SigningKeyPair> {
+    if (this.keyPair) return this.keyPair;
+    return this.rotateSigningKeys();
+  }
+
+  async getSigningKeyById(keyId: string): Promise<SigningKeyPair | undefined> {
+    const active = await this.getActiveSigningKey();
+    if (active.keyId === keyId) return active;
+    return undefined;
+  }
+
+  async rotateSigningKeys(): Promise<SigningKeyPair> {
+    const pair = await generateKeyPair("RS256", { extractable: true });
+    const privatePem = await exportPKCS8(pair.privateKey);
+    const publicPem = await exportSPKI(pair.publicKey);
+    const keyId = `aws-${crypto.randomBytes(8).toString("base64url")}`;
+
+    // In production: store privatePem/publicPem in AWS Secrets Manager encrypted by KMS.
+    // eslint-disable-next-line no-console
+    console.warn(`[aws-kms] New signing key ${keyId} generated. In production, store it in AWS Secrets Manager.`);
+
+    this.keyPair = { keyId, privateKey: pair.privateKey, publicKey: pair.publicKey };
+    return this.keyPair;
+  }
+
+  async listActiveSigningKeys(): Promise<{ keyId: string; createdAt: Date; expiresAt?: Date | null }[]> {
+    const active = await this.getActiveSigningKey();
+    return [{ keyId: active.keyId, createdAt: new Date(), expiresAt: null }];
+  }
+
+  async listValidSigningKeys(): Promise<SigningKeyPair[]> {
+    const active = await this.getActiveSigningKey();
+    return [active];
+  }
+
+  async getEncryptionKey(): Promise<Buffer> {
+    // In production: decrypt a stored data key using KMS.
+    throw new Error("AwsKmsSecretsProvider.getEncryptionKey() is not yet implemented");
+  }
+
+  async encryptSecret(plain: string): Promise<string> {
+    throw new Error("AwsKmsSecretsProvider.encryptSecret() is not yet implemented");
+  }
+
+  async decryptSecret(cipherText: string): Promise<string> {
+    throw new Error("AwsKmsSecretsProvider.decryptSecret() is not yet implemented");
+  }
+}

package/src/services/secrets/azureKeyVault.ts

@@ -0,0 +1,171 @@
+import crypto from "node:crypto";
+import { importPKCS8, importSPKI, exportPKCS8, exportSPKI, generateKeyPair } from "jose";
+import type { SecretsProvider, SigningKeyPair } from "./provider.js";
+import { hashPassword, verifyPassword } from "./password.js";
+
+/**
+ * Azure Key Vault secrets provider.
+ *
+ * This is a reference implementation. In production it should use the Azure
+ * SDK (@azure/identity and @azure/keyvault-keys/secrets) to retrieve signing
+ * keys, encryption keys, and credentials from Azure Key Vault. Password hashing
+ * helpers are reused locally because they are compute-bound.
+ */
+export class AzureKeyVaultSecretsProvider implements SecretsProvider {
+  readonly name = "azure-key-vault";
+
+  hashPassword = hashPassword;
+  verifyPassword = verifyPassword;
+
+  private vaultUrl: string;
+  private tenantId: string;
+  private clientId: string;
+  private clientSecret: string;
+
+  constructor() {
+    this.vaultUrl = (process.env.AZURE_KEY_VAULT_URL || "").replace(/\/$/, "");
+    this.tenantId = process.env.AZURE_TENANT_ID || "";
+    this.clientId = process.env.AZURE_CLIENT_ID || "";
+    this.clientSecret = process.env.AZURE_CLIENT_SECRET || "";
+
+    if (!this.vaultUrl || !this.tenantId || !this.clientId || !this.clientSecret) {
+      throw new Error(
+        "AzureKeyVaultSecretsProvider requires AZURE_KEY_VAULT_URL, AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET"
+      );
+    }
+  }
+
+  hashApiKey(key: string): string {
+    return crypto.createHash("sha256").update(key).digest("hex");
+  }
+
+  hashClientSecret(secret: string): string {
+    return crypto.createHash("sha256").update(secret).digest("hex");
+  }
+
+  generateClientSecret(): string {
+    return `cs_${crypto.randomBytes(32).toString("base64url")}`;
+  }
+
+  generateApiKey(): { key: string; prefix: string } {
+    const key = `ks_${crypto.randomBytes(32).toString("base64url")}`;
+    return { key, prefix: key.slice(0, 7) };
+  }
+
+  async getActiveSigningKey(): Promise<SigningKeyPair> {
+    const stored = await this.readKey("jwt-active");
+    if (stored?.private && stored?.public) {
+      const privateKey = await importPKCS8(String(stored.private), "RS256");
+      const publicKey = await importSPKI(String(stored.public), "RS256");
+      return { keyId: String(stored.keyId ?? "azure-active"), privateKey, publicKey };
+    }
+    return this.rotateSigningKeys();
+  }
+
+  async getSigningKeyById(keyId: string): Promise<SigningKeyPair | undefined> {
+    const active = await this.getActiveSigningKey();
+    if (active.keyId === keyId) return active;
+    const stored = await this.readKey(`jwt-${keyId}`);
+    if (!stored?.private) return undefined;
+    const privateKey = await importPKCS8(String(stored.private), "RS256");
+    const publicKey = await importSPKI(String(stored.public), "RS256");
+    return { keyId, privateKey, publicKey };
+  }
+
+  async rotateSigningKeys(): Promise<SigningKeyPair> {
+    const pair = await generateKeyPair("RS256", { extractable: true });
+    const privatePem = await exportPKCS8(pair.privateKey);
+    const publicPem = await exportSPKI(pair.publicKey);
+    const keyId = `azure-${crypto.randomBytes(8).toString("base64url")}`;
+
+    await this.writeKey("jwt-active", { keyId, private: privatePem, public: publicPem, rotatedAt: new Date().toISOString() });
+
+    return { keyId, privateKey: pair.privateKey, publicKey: pair.publicKey };
+  }
+
+  async listActiveSigningKeys(): Promise<{ keyId: string; createdAt: Date; expiresAt?: Date | null }[]> {
+    const active = await this.getActiveSigningKey();
+    return [{ keyId: active.keyId, createdAt: new Date(), expiresAt: null }];
+  }
+
+  async listValidSigningKeys(): Promise<SigningKeyPair[]> {
+    return [await this.getActiveSigningKey()];
+  }
+
+  async getEncryptionKey(): Promise<Buffer> {
+    const stored = await this.readKey("encryption-key");
+    if (stored?.value) {
+      return Buffer.from(String(stored.value), "base64");
+    }
+    const key = crypto.randomBytes(32);
+    await this.writeKey("encryption-key", { value: key.toString("base64") });
+    return key;
+  }
+
+  async encryptSecret(plain: string): Promise<string> {
+    const key = await this.getEncryptionKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plain, "utf-8"), cipher.final()]);
+    return `${iv.toString("base64")}:${encrypted.toString("base64")}`;
+  }
+
+  async decryptSecret(cipherText: string): Promise<string> {
+    const key = await this.getEncryptionKey();
+    const [ivBase64, encryptedBase64] = cipherText.split(":");
+    if (!ivBase64 || !encryptedBase64) throw new Error("Invalid cipher text format");
+    const iv = Buffer.from(ivBase64, "base64");
+    const encrypted = Buffer.from(encryptedBase64, "base64");
+    const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf-8");
+  }
+
+  // Reference stubs for Azure Key Vault HTTP API integration.
+  private async readPath(path: string): Promise<Record<string, unknown> | undefined> {
+    const url = `${this.vaultUrl}/secrets/${path}?api-version=7.4`;
+    const token = await this.getAccessToken();
+    const response = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}`, Accept: "application/json" },
+    });
+    if (response.status === 404) return undefined;
+    if (!response.ok) throw new Error(`Azure Key Vault read failed: ${response.status}`);
+    const body = await response.json();
+    return typeof body.value === "string" ? JSON.parse(body.value) : body.value;
+  }
+
+  private async readKey(name: string): Promise<Record<string, unknown> | undefined> {
+    return this.readPath(name);
+  }
+
+  private async writeKey(name: string, value: Record<string, unknown>): Promise<void> {
+    const url = `${this.vaultUrl}/secrets/${name}?api-version=7.4`;
+    const token = await this.getAccessToken();
+    const response = await fetch(url, {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ value: JSON.stringify(value) }),
+    });
+    if (!response.ok) throw new Error(`Azure Key Vault write failed: ${response.status}`);
+  }
+
+  private async getAccessToken(): Promise<string> {
+    const url = `https://login.microsoftonline.com/${this.tenantId}/oauth2/v2.0/token`;
+    const params = new URLSearchParams();
+    params.set("client_id", this.clientId);
+    params.set("client_secret", this.clientSecret);
+    params.set("scope", "https://vault.azure.net/.default");
+    params.set("grant_type", "client_credentials");
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: params.toString(),
+    });
+    if (!response.ok) throw new Error(`Azure authentication failed: ${response.status}`);
+    const body = await response.json();
+    return String(body.access_token);
+  }
+}

package/src/services/secrets/database.ts

@@ -0,0 +1,166 @@
+import crypto from "node:crypto";
+import { eq, and, or, gt, isNull } from "drizzle-orm";
+import { importPKCS8, importSPKI, exportPKCS8, exportSPKI, generateKeyPair, type KeyLike } from "jose";
+import { db } from "../../db/index.js";
+import { secrets, type Secret } from "../../db/schema.js";
+import { config } from "../../config.js";
+import type { SecretsProvider, SigningKeyPair } from "./provider.js";
+import { hashPassword, verifyPassword } from "./password.js";
+
+const ENCRYPTION_ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 16;
+const AUTH_TAG_LENGTH = 16;
+const KEY_ID_BYTES = 8;
+
+export class DatabaseSecretsProvider implements SecretsProvider {
+  readonly name = "database";
+
+  hashPassword = hashPassword;
+  verifyPassword = verifyPassword;
+
+  hashApiKey(key: string): string {
+    return crypto.createHash("sha256").update(key).digest("hex");
+  }
+
+  hashClientSecret(secret: string): string {
+    return crypto.createHash("sha256").update(secret).digest("hex");
+  }
+
+  generateClientSecret(): string {
+    return `cs_${crypto.randomBytes(32).toString("base64url")}`;
+  }
+
+  generateApiKey(): { key: string; prefix: string } {
+    const key = `ks_${crypto.randomBytes(32).toString("base64url")}`;
+    const prefix = key.slice(0, 7);
+    return { key, prefix };
+  }
+
+  async getActiveSigningKey(): Promise<SigningKeyPair> {
+    const [active] = await db
+      .select()
+      .from(secrets)
+      .where(and(eq(secrets.type, "jwt_signing"), eq(secrets.isActive, true), isNull(secrets.expiresAt)))
+      .orderBy(secrets.createdAt)
+      .limit(1);
+
+    if (active) {
+      return this.loadKeyPair(active);
+    }
+
+    return this.createSigningKey();
+  }
+
+  async getSigningKeyById(keyId: string): Promise<SigningKeyPair | undefined> {
+    const [record] = await db.select().from(secrets).where(eq(secrets.keyId, keyId)).limit(1);
+    if (!record || record.type !== "jwt_signing") return undefined;
+    return this.loadKeyPair(record);
+  }
+
+  async rotateSigningKeys(): Promise<SigningKeyPair> {
+    await db
+      .update(secrets)
+      .set({ isActive: false, expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000) })
+      .where(eq(secrets.type, "jwt_signing"));
+    return this.createSigningKey();
+  }
+
+  private async createSigningKey(): Promise<SigningKeyPair> {
+    const pair = await generateKeyPair("RS256", { extractable: true });
+    const privatePem = await exportPKCS8(pair.privateKey);
+    const publicPem = await exportSPKI(pair.publicKey);
+    const keyId = crypto.randomBytes(KEY_ID_BYTES).toString("base64url");
+
+    await db.insert(secrets).values({
+      keyId,
+      type: "jwt_signing",
+      value: JSON.stringify({ private: privatePem, public: publicPem }),
+      algorithm: "RS256",
+      isActive: true,
+      rotatedAt: new Date(),
+    });
+
+    return { keyId, privateKey: pair.privateKey, publicKey: pair.publicKey };
+  }
+
+  private async loadKeyPair(record: Secret): Promise<SigningKeyPair> {
+    const parsed = JSON.parse(record.value) as { private: string; public: string };
+    const privateKey = await importPKCS8(parsed.private, "RS256");
+    const publicKey = await importSPKI(parsed.public, "RS256");
+    return { keyId: record.keyId, privateKey, publicKey };
+  }
+
+  async getEncryptionKey(): Promise<Buffer> {
+    if (config.KEYSTONE_ENCRYPTION_KEY) {
+      return crypto.createHash("sha256").update(config.KEYSTONE_ENCRYPTION_KEY).digest();
+    }
+
+    const [active] = await db
+      .select()
+      .from(secrets)
+      .where(and(eq(secrets.type, "encryption"), eq(secrets.isActive, true)))
+      .limit(1);
+
+    if (active) {
+      return Buffer.from(active.value, "base64url");
+    }
+
+    const value = crypto.randomBytes(32);
+    await db.insert(secrets).values({
+      keyId: `enc-${crypto.randomBytes(KEY_ID_BYTES).toString("base64url")}`,
+      type: "encryption",
+      value: value.toString("base64url"),
+      algorithm: "aes-256-gcm",
+      isActive: true,
+    });
+    return value;
+  }
+
+  async encryptSecret(plain: string): Promise<string> {
+    const key = await this.getEncryptionKey();
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const cipher = crypto.createCipheriv(ENCRYPTION_ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const payload = Buffer.concat([iv, tag, encrypted]);
+    return `${ENCRYPTION_ALGORITHM}$${payload.toString("base64url")}`;
+  }
+
+  async decryptSecret(cipherText: string): Promise<string> {
+    if (!cipherText.startsWith(`${ENCRYPTION_ALGORITHM}$`)) {
+      throw new Error("Unsupported cipher format");
+    }
+    const key = await this.getEncryptionKey();
+    const payload = Buffer.from(cipherText.slice(`${ENCRYPTION_ALGORITHM}$`.length), "base64url");
+    const iv = payload.subarray(0, IV_LENGTH);
+    const tag = payload.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+    const encrypted = payload.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+    const decipher = crypto.createDecipheriv(ENCRYPTION_ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+  }
+
+  async listActiveSigningKeys(): Promise<{ keyId: string; createdAt: Date; expiresAt?: Date | null }[]> {
+    const rows = await db
+      .select({ keyId: secrets.keyId, createdAt: secrets.createdAt, expiresAt: secrets.expiresAt })
+      .from(secrets)
+      .where(and(eq(secrets.type, "jwt_signing"), eq(secrets.isActive, true)))
+      .orderBy(secrets.createdAt);
+    return rows;
+  }
+
+  async listValidSigningKeys(): Promise<SigningKeyPair[]> {
+    const now = new Date();
+    const rows = await db
+      .select()
+      .from(secrets)
+      .where(
+        and(
+          eq(secrets.type, "jwt_signing"),
+          or(eq(secrets.isActive, true), and(eq(secrets.isActive, false), gt(secrets.expiresAt, now)))
+        )
+      )
+      .orderBy(secrets.createdAt);
+    return Promise.all(rows.map((row) => this.loadKeyPair(row)));
+  }
+}