@hilbras/keystone 1.1.0

package/src/services/secrets/environment.ts

@@ -0,0 +1,117 @@
+import crypto from "node:crypto";
+import { importPKCS8, importSPKI, exportPKCS8, exportSPKI, generateKeyPair, type KeyLike } from "jose";
+import { config } from "../../config.js";
+import type { SecretsProvider, SigningKeyPair } from "./provider.js";
+import { hashPassword, verifyPassword } from "./password.js";
+
+let envKeyPair: SigningKeyPair | null = null;
+let envEncryptionKey: Buffer | null = null;
+
+export class EnvironmentSecretsProvider implements SecretsProvider {
+  readonly name = "environment";
+
+  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> {
+    if (envKeyPair) return envKeyPair;
+
+    if (config.JWT_PRIVATE_KEY && config.JWT_PUBLIC_KEY) {
+      const privateKey = await importPKCS8(config.JWT_PRIVATE_KEY, "RS256");
+      const publicKey = await importSPKI(config.JWT_PUBLIC_KEY, "RS256");
+      envKeyPair = { keyId: "env", privateKey, publicKey };
+      return envKeyPair;
+    }
+
+    if (config.NODE_ENV === "production") {
+      throw new Error("EnvironmentSecretsProvider requires JWT_PRIVATE_KEY and JWT_PUBLIC_KEY in production");
+    }
+
+    const pair = await generateKeyPair("RS256", { extractable: true });
+    const privatePem = await exportPKCS8(pair.privateKey);
+    const publicPem = await exportSPKI(pair.publicKey);
+    // eslint-disable-next-line no-console
+    console.warn("[secrets] Generated ephemeral JWT keys. Set JWT_PRIVATE_KEY/JWT_PUBLIC_KEY in production.");
+    // eslint-disable-next-line no-console
+    console.warn("[secrets] JWT_PRIVATE_KEY\n", privatePem);
+    // eslint-disable-next-line no-console
+    console.warn("[secrets] JWT_PUBLIC_KEY\n", publicPem);
+    envKeyPair = { keyId: "env-generated", privateKey: pair.privateKey, publicKey: pair.publicKey };
+    return envKeyPair;
+  }
+
+  async getSigningKeyById(keyId: string): Promise<SigningKeyPair | undefined> {
+    const active = await this.getActiveSigningKey();
+    if (active.keyId === keyId) return active;
+    return undefined;
+  }
+
+  async rotateSigningKeys(): Promise<SigningKeyPair> {
+    envKeyPair = null;
+    return this.getActiveSigningKey();
+  }
+
+  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> {
+    if (envEncryptionKey) return envEncryptionKey;
+    if (config.KEYSTONE_ENCRYPTION_KEY) {
+      envEncryptionKey = crypto.createHash("sha256").update(config.KEYSTONE_ENCRYPTION_KEY).digest();
+      return envEncryptionKey;
+    }
+    envEncryptionKey = crypto.randomBytes(32);
+    // eslint-disable-next-line no-console
+    console.warn("[secrets] Generated ephemeral encryption key. Set KEYSTONE_ENCRYPTION_KEY in production.");
+    return envEncryptionKey;
+  }
+
+  async encryptSecret(plain: string): Promise<string> {
+    const key = await this.getEncryptionKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const payload = Buffer.concat([iv, tag, encrypted]);
+    return `aes-256-gcm$${payload.toString("base64url")}`;
+  }
+
+  async decryptSecret(cipherText: string): Promise<string> {
+    if (!cipherText.startsWith("aes-256-gcm$")) {
+      throw new Error("Unsupported cipher format");
+    }
+    const key = await this.getEncryptionKey();
+    const payload = Buffer.from(cipherText.slice("aes-256-gcm$".length), "base64url");
+    const iv = payload.subarray(0, 16);
+    const tag = payload.subarray(16, 32);
+    const encrypted = payload.subarray(32);
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+  }
+}

package/src/services/secrets/index.ts

@@ -0,0 +1,50 @@
+import { config } from "../../config.js";
+import { DatabaseSecretsProvider } from "./database.js";
+import { EnvironmentSecretsProvider } from "./environment.js";
+import { VaultSecretsProvider } from "./vault.js";
+import { AwsKmsSecretsProvider } from "./awsKms.js";
+import { AzureKeyVaultSecretsProvider } from "./azureKeyVault.js";
+import type { SecretsProvider } from "./provider.js";
+
+function createProvider(): SecretsProvider {
+  const providerName = config.KEYSTONE_SECRETS_PROVIDER || "database";
+  switch (providerName) {
+    case "environment":
+      return new EnvironmentSecretsProvider();
+    case "vault":
+      return new VaultSecretsProvider();
+    case "aws-kms":
+      return new AwsKmsSecretsProvider();
+    case "azure-key-vault":
+      return new AzureKeyVaultSecretsProvider();
+    case "database":
+    default:
+      return new DatabaseSecretsProvider();
+  }
+}
+
+export const secretsProvider: SecretsProvider = createProvider();
+
+// Re-export everything for backwards compatibility.
+export * from "./provider.js";
+export { DatabaseSecretsProvider } from "./database.js";
+export { EnvironmentSecretsProvider } from "./environment.js";
+export { VaultSecretsProvider } from "./vault.js";
+export { AwsKmsSecretsProvider } from "./awsKms.js";
+export { AzureKeyVaultSecretsProvider } from "./azureKeyVault.js";
+
+// Convenience re-exports of the active provider's methods.
+export const hashPassword = secretsProvider.hashPassword.bind(secretsProvider);
+export const verifyPassword = secretsProvider.verifyPassword.bind(secretsProvider);
+export const hashApiKey = secretsProvider.hashApiKey.bind(secretsProvider);
+export const hashClientSecret = secretsProvider.hashClientSecret.bind(secretsProvider);
+export const generateClientSecret = secretsProvider.generateClientSecret.bind(secretsProvider);
+export const generateApiKey = secretsProvider.generateApiKey.bind(secretsProvider);
+export const getActiveSigningKey = secretsProvider.getActiveSigningKey.bind(secretsProvider);
+export const getSigningKeyById = secretsProvider.getSigningKeyById.bind(secretsProvider);
+export const rotateSigningKeys = secretsProvider.rotateSigningKeys.bind(secretsProvider);
+export const listActiveSigningKeys = secretsProvider.listActiveSigningKeys.bind(secretsProvider);
+export const listValidSigningKeys = secretsProvider.listValidSigningKeys.bind(secretsProvider);
+export const getEncryptionKey = secretsProvider.getEncryptionKey.bind(secretsProvider);
+export const encryptSecret = secretsProvider.encryptSecret.bind(secretsProvider);
+export const decryptSecret = secretsProvider.decryptSecret.bind(secretsProvider);

package/src/services/secrets/password.ts

@@ -0,0 +1,73 @@
+import crypto from "node:crypto";
+import * as argon2 from "argon2";
+
+// OWASP-recommended minimum parameters for argon2id (as of 2023).
+const ARGON2_MEMORY_COST = 65536;
+const ARGON2_TIME_COST = 3;
+const ARGON2_PARALLELISM = 4;
+
+// Legacy scrypt parameters used by early Keystone deployments.
+const SCRYPT_N = 16384;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+
+function scryptPromise(
+  password: string,
+  salt: Buffer,
+  keylen: number,
+  options: crypto.ScryptOptions
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    crypto.scrypt(password, salt, keylen, options, (err, derived) => {
+      if (err) return reject(err);
+      resolve(derived);
+    });
+  });
+}
+
+async function verifyScryptPassword(plain: string, hash: string): Promise<boolean> {
+  const parts = hash.split("$");
+  if (parts.length !== 6) return false;
+  const [, nStr, rStr, pStr, saltB64, derivedB64] = parts;
+  const salt = Buffer.from(saltB64, "base64url");
+  const expected = Buffer.from(derivedB64, "base64url");
+  const derived = await scryptPromise(plain, salt, expected.length, {
+    N: Number(nStr),
+    r: Number(rStr),
+    p: Number(pStr),
+  });
+  return crypto.timingSafeEqual(derived, expected);
+}
+
+/**
+ * Hash a password using argon2id. The encoded string contains the salt and
+ * parameters, so verification does not need external storage.
+ */
+export async function hashPassword(plain: string): Promise<string> {
+  return argon2.hash(plain, {
+    type: argon2.argon2id,
+    memoryCost: ARGON2_MEMORY_COST,
+    timeCost: ARGON2_TIME_COST,
+    parallelism: ARGON2_PARALLELISM,
+  });
+}
+
+/**
+ * Verify a password against an argon2id or legacy scrypt hash.
+ */
+export async function verifyPassword(
+  plain: string,
+  hash: string | null | undefined
+): Promise<boolean> {
+  if (!hash) return false;
+
+  if (hash.startsWith("scrypt$")) {
+    return verifyScryptPassword(plain, hash);
+  }
+
+  try {
+    return await argon2.verify(hash, plain);
+  } catch {
+    return false;
+  }
+}

package/src/services/secrets/provider.ts

@@ -0,0 +1,38 @@
+import type { KeyLike } from "jose";
+
+export interface SigningKeyPair {
+  keyId: string;
+  privateKey: KeyLike | Uint8Array;
+  publicKey: KeyLike;
+}
+
+export interface SecretsProvider {
+  readonly name: string;
+
+  // Password hashing
+  hashPassword(plain: string): Promise<string>;
+  verifyPassword(plain: string, hash: string | null | undefined): Promise<boolean>;
+
+  // API key / client secret hashing
+  hashApiKey(key: string): string;
+  hashClientSecret(secret: string): string;
+  generateClientSecret(): string;
+  generateApiKey(): { key: string; prefix: string };
+
+  // JWT signing keys
+  getActiveSigningKey(): Promise<SigningKeyPair>;
+  getSigningKeyById(keyId: string): Promise<SigningKeyPair | undefined>;
+  rotateSigningKeys(): Promise<SigningKeyPair>;
+  listActiveSigningKeys(): Promise<{ keyId: string; createdAt: Date; expiresAt?: Date | null }[]>;
+  /**
+   * Return all signing keys that are currently valid: the active key plus any
+   * recently rotated keys still within the grace period. Used to verify tokens
+   * after a key rotation.
+   */
+  listValidSigningKeys(): Promise<SigningKeyPair[]>;
+
+  // Symmetric encryption
+  getEncryptionKey(): Promise<Buffer>;
+  encryptSecret(plain: string): Promise<string>;
+  decryptSecret(cipherText: string): Promise<string>;
+}

package/src/services/secrets/vault.ts

@@ -0,0 +1,149 @@
+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";
+
+/**
+ * HashiCorp Vault secrets provider.
+ *
+ * This is a reference implementation. In production it should call the
+ * Vault HTTP API (or use a Vault client library) to retrieve signing keys,
+ * encryption keys, and credentials. The password hashing helpers are reused
+ * locally because they are compute-bound and do not need external storage.
+ */
+export class VaultSecretsProvider implements SecretsProvider {
+  readonly name = "vault";
+
+  hashPassword = hashPassword;
+  verifyPassword = verifyPassword;
+
+  private vaultAddr: string;
+  private vaultToken: string;
+  private mountPath: string;
+
+  constructor() {
+    this.vaultAddr = (process.env.VAULT_ADDR || "").replace(/\/$/, "");
+    this.vaultToken = process.env.VAULT_TOKEN || "";
+    this.mountPath = (process.env.VAULT_MOUNT_PATH || "secret").replace(/(^\/)|(\/$)/g, "");
+
+    if (!this.vaultAddr || !this.vaultToken) {
+      throw new Error("VaultSecretsProvider requires VAULT_ADDR and VAULT_TOKEN");
+    }
+  }
+
+  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.readPath("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 ?? "vault-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.readPath(`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 = `vault-${crypto.randomBytes(8).toString("base64url")}`;
+
+    await this.writePath("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[]> {
+    const active = await this.getActiveSigningKey();
+    return [active];
+  }
+
+  async getEncryptionKey(): Promise<Buffer> {
+    const stored = await this.readPath("encryption/active");
+    if (stored?.value) {
+      return Buffer.from(String(stored.value), "base64url");
+    }
+    const value = crypto.randomBytes(32);
+    await this.writePath("encryption/active", { value: value.toString("base64url") });
+    return value;
+  }
+
+  async encryptSecret(plain: string): Promise<string> {
+    const key = await this.getEncryptionKey();
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const payload = Buffer.concat([iv, tag, encrypted]);
+    return `aes-256-gcm$${payload.toString("base64url")}`;
+  }
+
+  async decryptSecret(cipherText: string): Promise<string> {
+    if (!cipherText.startsWith("aes-256-gcm$")) {
+      throw new Error("Unsupported cipher format");
+    }
+    const key = await this.getEncryptionKey();
+    const payload = Buffer.from(cipherText.slice("aes-256-gcm$".length), "base64url");
+    const iv = payload.subarray(0, 16);
+    const tag = payload.subarray(16, 32);
+    const encrypted = payload.subarray(32);
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+  }
+
+  private async readPath(path: string): Promise<Record<string, unknown> | undefined> {
+    const url = `${this.vaultAddr}/v1/${this.mountPath}/data/${path}`;
+    const res = await fetch(url, {
+      headers: { "X-Vault-Token": this.vaultToken },
+    });
+    if (res.status === 404) return undefined;
+    if (!res.ok) throw new Error(`Vault read failed: ${res.status}`);
+    const data = (await res.json()) as { data?: { data?: Record<string, unknown> } };
+    return data.data?.data;
+  }
+
+  private async writePath(path: string, data: Record<string, unknown>): Promise<void> {
+    const url = `${this.vaultAddr}/v1/${this.mountPath}/data/${path}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-Vault-Token": this.vaultToken,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ data }),
+    });
+    if (!res.ok) throw new Error(`Vault write failed: ${res.status}`);
+  }
+}

package/src/services/secrets.ts

@@ -0,0 +1,2 @@
+// Backwards-compatible re-export of the secrets provider layer.
+export * from "./secrets/index.js";

package/src/services/serviceAccounts.ts

@@ -0,0 +1,74 @@
+import { eq, and, sql } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { serviceAccounts, apiKeys, type ServiceAccount } from "../db/schema.js";
+
+export async function createServiceAccount(input: {
+  orgId: string;
+  name: string;
+  description?: string;
+}): Promise<ServiceAccount> {
+  const [record] = await db
+    .insert(serviceAccounts)
+    .values({
+      orgId: input.orgId,
+      name: input.name,
+      description: input.description ?? null,
+    })
+    .returning();
+  return record;
+}
+
+export async function findServiceAccountsByOrgId(orgId: string): Promise<ServiceAccount[]> {
+  return db
+    .select()
+    .from(serviceAccounts)
+    .where(and(eq(serviceAccounts.orgId, orgId), eq(serviceAccounts.isActive, true)))
+    .orderBy(serviceAccounts.name);
+}
+
+export async function findServiceAccountById(
+  id: string,
+  orgId: string
+): Promise<ServiceAccount | undefined> {
+  const [record] = await db
+    .select()
+    .from(serviceAccounts)
+    .where(
+      and(
+        eq(serviceAccounts.id, id),
+        eq(serviceAccounts.orgId, orgId),
+        eq(serviceAccounts.isActive, true)
+      )
+    )
+    .limit(1);
+  return record;
+}
+
+export async function updateServiceAccount(
+  id: string,
+  orgId: string,
+  updates: Partial<{ name: string; description: string; isActive: boolean }>
+): Promise<ServiceAccount | undefined> {
+  const [updated] = await db
+    .update(serviceAccounts)
+    .set({ ...updates, updatedAt: sql`now()` })
+    .where(and(eq(serviceAccounts.id, id), eq(serviceAccounts.orgId, orgId)))
+    .returning();
+  return updated;
+}
+
+export async function listServiceAccountApiKeys(serviceAccountId: string) {
+  return db
+    .select({
+      id: apiKeys.id,
+      name: apiKeys.name,
+      prefix: apiKeys.prefix,
+      scopes: apiKeys.scopes,
+      lastUsedAt: apiKeys.lastUsedAt,
+      expiresAt: apiKeys.expiresAt,
+      revokedAt: apiKeys.revokedAt,
+      createdAt: apiKeys.createdAt,
+    })
+    .from(apiKeys)
+    .where(eq(apiKeys.serviceAccountId, serviceAccountId));
+}