@hilbras/keystone 1.1.0

package/src/cli.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+
+const program = new Command();
+
+program.name("keystone").description("Hilbras Keystone CLI").version("1.0.0");
+
+program
+  .command("init")
+  .description("Create a sample .env file for Keystone")
+  .action(async () => {
+    console.log("Keystone init: copy .env.example and configure DATABASE_URL, ZITADEL_DOMAIN, etc.");
+  });
+
+program
+  .command("migrate")
+  .description("Run database migrations")
+  .action(async () => {
+    const { migrate } = await import("drizzle-orm/postgres-js/migrator");
+    const { db } = await import("./db/index.js");
+    const path = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    await migrate(db, { migrationsFolder: path.resolve(__dirname, "./db/migrations") });
+    console.log("Migrations applied");
+  });
+
+program
+  .command("keys:create")
+  .description("Generate a JWT signing key pair")
+  .action(async () => {
+    const { generateKeyPair, exportPKCS8, exportSPKI } = await import("jose");
+    const pair = await generateKeyPair("RS256", { extractable: true });
+    const privateKey = await exportPKCS8(pair.privateKey);
+    const publicKey = await exportSPKI(pair.publicKey);
+    console.log("JWT_PRIVATE_KEY=");
+    console.log(privateKey);
+    console.log("JWT_PUBLIC_KEY=");
+    console.log(publicKey);
+  });
+
+program
+  .command("secrets:rotate")
+  .description("Rotate the active JWT signing key")
+  .action(async () => {
+    const { rotateSigningKeys } = await import("./services/secrets/index.js");
+    const pair = await rotateSigningKeys();
+    console.log(`Rotated signing key. New key id: ${pair.keyId}`);
+  });
+
+program
+  .command("user:create")
+  .description("Create a local user account")
+  .requiredOption("--email <email>", "User email")
+  .requiredOption("--password <password>", "User password")
+  .option("--username <username>", "Username")
+  .option("--name <name>", "Display name")
+  .option("--role <role>", "Role (e.g. owner, admin, member)", "member")
+  .action(
+    async (options: {
+      email: string;
+      password: string;
+      username?: string;
+      name?: string;
+      role: string;
+    }) => {
+      const { initializeContainer } = await import("./di.js");
+      const { AuthenticationDomainService } = await import("./services/domain/index.js");
+      const { db } = await import("./db/index.js");
+      const { users } = await import("./db/schema.js");
+      const { eq } = await import("drizzle-orm");
+
+      const container = initializeContainer();
+      const authService = new AuthenticationDomainService(container.userRepository, container.applicationRepository);
+      const result = await authService.register({
+        email: options.email,
+        password: options.password,
+        username:
+          options.username ||
+          options.email.split("@")[0].toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 32),
+        name: options.name,
+      });
+
+      if (!result.success) {
+        console.error(`Failed to create user: ${result.error.message}`);
+        process.exit(1);
+      }
+
+      if (options.role !== "member") {
+        await db.update(users).set({ role: options.role }).where(eq(users.id, result.data.user.id));
+      }
+
+      console.log(`Created user ${result.data.user.id} (${result.data.user.email}) with role ${options.role}`);
+    }
+  );
+
+program
+  .command("org:create")
+  .description("Create a new organization")
+  .requiredOption("--name <name>", "Organization name")
+  .option("--slug <slug>", "Organization slug")
+  .option("--plan <plan>", "Billing plan", "free")
+  .option("--owner-email <email>", "Owner email")
+  .action(async (options: { name: string; slug?: string; plan: string; ownerEmail?: string }) => {
+    const { initializeContainer } = await import("./di.js");
+    const { OrganizationDomainService } = await import("./services/domain/index.js");
+    const { DrizzleUserRepository, DrizzleOrganizationRepository } = await import(
+      "./repositories/index.js"
+    );
+    const container = initializeContainer();
+    const orgService = new OrganizationDomainService(
+      container.organizationRepository,
+      container.applicationRepository,
+      container.userRepository
+    );
+    const orgResult = await orgService.createOrganization({
+      name: options.name,
+      slug: options.slug,
+      plan: options.plan,
+    });
+    if (!orgResult.success) {
+      console.error(`Failed to create organization: ${orgResult.error.message}`);
+      process.exit(1);
+    }
+    const org = orgResult.data;
+    if (options.ownerEmail) {
+      const users = new DrizzleUserRepository();
+      const owner = await users.findByEmail(options.ownerEmail);
+      if (owner) {
+        const orgs = new DrizzleOrganizationRepository();
+        await orgs.addMembership({
+          orgId: org.id,
+          userId: owner.id,
+          role: "owner",
+        });
+      } else {
+        console.warn(`Owner email ${options.ownerEmail} not found; organization created without owner`);
+      }
+    }
+    console.log(`Created organization ${org.id} (${org.slug})`);
+  });
+
+program
+  .command("keys:list")
+  .description("List active JWT signing keys")
+  .action(async () => {
+    const { listActiveSigningKeys } = await import("./services/secrets/index.js");
+    const keys = await listActiveSigningKeys();
+    for (const key of keys) {
+      console.log(`${key.keyId}\tcreated=${key.createdAt.toISOString()}\texpires=${key.expiresAt?.toISOString() ?? "never"}`);
+    }
+  });
+
+program
+  .command("config:validate")
+  .description("Validate required configuration and print status")
+  .action(async () => {
+    const { config } = await import("./config.js");
+    const required = ["DATABASE_URL"];
+    const missing = required.filter((name) => !process.env[name]);
+    if (missing.length > 0) {
+      console.error(`Missing required environment variables: ${missing.join(", ")}`);
+      process.exit(1);
+    }
+    console.log("Configuration OK");
+    console.log(`  DATABASE_URL: ${config.DATABASE_URL.replace(/\/\/.*@/, "//***@")}`);
+    console.log(`  REDIS_URL: ${config.REDIS_URL.replace(/\/\/.*@/, "//***@")}`);
+    console.log(`  Queue provider: ${config.KEYSTONE_QUEUE_PROVIDER || "auto"}`);
+    console.log(`  Secrets provider: ${config.KEYSTONE_SECRETS_PROVIDER}`);
+  });
+
+program.parse();

package/src/config.ts

@@ -0,0 +1,143 @@
+import dotenv from "dotenv";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.resolve(__dirname, "../.env") });
+dotenv.config();
+
+function getEnv(name: string, fallback = ""): string {
+  return process.env[name] ?? fallback;
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+function requireEnvUnlessSetup(name: string): string {
+  const value = process.env[name];
+  if (!value && process.env.KEYSTONE_SETUP_MODE !== "true") {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value || "";
+}
+
+function getList(name: string): string[] {
+  const value = process.env[name];
+  if (!value) return [];
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+export const config = {
+  NODE_ENV: getEnv("NODE_ENV", "development"),
+  PORT: Number(getEnv("PORT", "4001")),
+  HOST: getEnv("HOST", "0.0.0.0"),
+
+  DATABASE_URL: requireEnvUnlessSetup("DATABASE_URL"),
+  REDIS_URL: getEnv("REDIS_URL", "redis://localhost:6379"),
+
+  // Zitadel is now an optional identity connector, not a hard dependency.
+  ZITADEL_DOMAIN: getEnv("ZITADEL_DOMAIN"),
+  ZITADEL_ORG_ID: getEnv("ZITADEL_ORG_ID"),
+  ZITADEL_PROJECT_ID: getEnv("ZITADEL_PROJECT_ID"),
+
+  // Service account used to call Zitadel management/user APIs.
+  ZITADEL_SERVICE_CLIENT_ID: getEnv("ZITADEL_SERVICE_CLIENT_ID"),
+  ZITADEL_SERVICE_CLIENT_SECRET: getEnv("ZITADEL_SERVICE_CLIENT_SECRET"),
+  ZITADEL_SERVICE_PAT: getEnv("ZITADEL_SERVICE_PAT"),
+
+  // Keystone OIDC app registered in Zitadel (for OAuth callbacks).
+  ZITADEL_CLIENT_ID: getEnv("ZITADEL_CLIENT_ID"),
+  ZITADEL_CLIENT_SECRET: getEnv("ZITADEL_CLIENT_SECRET"),
+
+  // Optional IdP IDs to skip the Zitadel login selector and go straight to Google/GitHub.
+  ZITADEL_GOOGLE_IDP_ID: getEnv("ZITADEL_GOOGLE_IDP_ID"),
+  ZITADEL_GITHUB_IDP_ID: getEnv("ZITADEL_GITHUB_IDP_ID"),
+
+  COOKIE_NAME: getEnv("COOKIE_NAME", "__Host-keystone-session"),
+  COOKIE_DOMAIN: getEnv("COOKIE_DOMAIN", ".local.hilbras.ai"),
+  COOKIE_SECURE: getEnv("COOKIE_SECURE", "false") === "true",
+  COOKIE_SAME_SITE: getEnv("COOKIE_SAME_SITE", getEnv("NODE_ENV", "development") === "production" ? "strict" : "lax") as "strict" | "lax" | "none",
+
+  AUTH_API_PUBLIC_URL: getEnv("AUTH_API_PUBLIC_URL"),
+  ACCESS_TOKEN_TTL_SECONDS: Number(getEnv("JWT_ACCESS_TOKEN_TTL", "900")),
+  REFRESH_TOKEN_TTL_SECONDS: Number(getEnv("JWT_REFRESH_TOKEN_TTL", "604800")),
+
+  // RSA PEM keys. If not provided, a new key pair is generated at startup (dev only).
+  JWT_PRIVATE_KEY: getEnv("JWT_PRIVATE_KEY"),
+  JWT_PUBLIC_KEY: getEnv("JWT_PUBLIC_KEY"),
+
+  // Optional master encryption key. If omitted, a random key is stored in the secrets table (dev only).
+  KEYSTONE_ENCRYPTION_KEY: getEnv("KEYSTONE_ENCRYPTION_KEY"),
+
+  // Secrets provider: "database" (default) or "environment".
+  KEYSTONE_SECRETS_PROVIDER: getEnv("KEYSTONE_SECRETS_PROVIDER", "database"),
+
+  // Queue provider: "in-process" (default/fallback), "bullmq", or "" to auto-select bullmq when REDIS_URL is set.
+  KEYSTONE_QUEUE_PROVIDER: getEnv("KEYSTONE_QUEUE_PROVIDER", "in-process"),
+
+  // Cache key prefix for Redis/in-memory cache entries.
+  CACHE_KEY_PREFIX: getEnv("CACHE_KEY_PREFIX", "keystone:"),
+
+  // Comma-separated list of plugin module paths to load at startup.
+  KEYSTONE_PLUGINS: getEnv("KEYSTONE_PLUGINS"),
+
+  INTERNAL_API_KEY: getEnv("KEYSTONE_INTERNAL_API_KEY") || getEnv("HILBRAS_INTERNAL_API_KEY", ""),
+
+  SEED_OWNER_EMAIL: getEnv("KEYSTONE_SEED_OWNER_EMAIL"),
+
+  ALLOWED_ORIGINS: getList("ALLOWED_ORIGINS"),
+
+  RATE_LIMIT_ATTEMPTS: Number(getEnv("RATE_LIMIT_ATTEMPTS", "5")),
+  RATE_LIMIT_WINDOW_SECONDS: Number(getEnv("RATE_LIMIT_WINDOW_SECONDS", "900")),
+  GLOBAL_RATE_LIMIT_MAX: Number(getEnv("GLOBAL_RATE_LIMIT_MAX", "100")),
+  GLOBAL_RATE_LIMIT_WINDOW: Number(getEnv("GLOBAL_RATE_LIMIT_WINDOW", "60")),
+
+  ACCOUNT_LOCKOUT_THRESHOLD: Number(getEnv("ACCOUNT_LOCKOUT_THRESHOLD", "5")),
+  ACCOUNT_LOCKOUT_DURATION_SECONDS: Number(getEnv("ACCOUNT_LOCKOUT_DURATION_SECONDS", "1800")),
+
+  HIBP_CHECK_ENABLED: getEnv("HIBP_CHECK_ENABLED", "false") === "true",
+  // When true, new registrations start unverified and a verification email
+  // is sent automatically; login still works but emailVerified stays false
+  // until the user clicks the link.
+  EMAIL_VERIFICATION_REQUIRED: getEnv("EMAIL_VERIFICATION_REQUIRED", "false") === "true",
+  MAGIC_LINK_TTL_SECONDS: Number(getEnv("MAGIC_LINK_TTL_SECONDS", "900")),
+  OAUTH_CODE_TTL_SECONDS: Number(getEnv("OAUTH_CODE_TTL_SECONDS", "60")),
+  TOTP_ISSUER: getEnv("TOTP_ISSUER", "Hilbras"),
+  TOTP_ENCRYPTION_KEY: getEnv("KEYSTONE_TOTP_ENCRYPTION_KEY"),
+  EMAIL_PROVIDER: getEnv("EMAIL_PROVIDER", "none"),
+  EMAIL_FROM: getEnv("EMAIL_FROM", "keystone@local.hilbras.ai"),
+  SMTP_HOST: getEnv("SMTP_HOST"),
+  SMTP_PORT: Number(getEnv("SMTP_PORT", "587")),
+  SMTP_USER: getEnv("SMTP_USER"),
+  SMTP_PASS: getEnv("SMTP_PASS"),
+  SMTP_SECURE: getEnv("SMTP_SECURE", "false") === "true",
+  SENDGRID_API_KEY: getEnv("SENDGRID_API_KEY"),
+  MAILGUN_API_KEY: getEnv("MAILGUN_API_KEY"),
+  MAILGUN_DOMAIN: getEnv("MAILGUN_DOMAIN"),
+  SMS_PROVIDER: getEnv("SMS_PROVIDER", "none"),
+  TWILIO_ACCOUNT_SID: getEnv("TWILIO_ACCOUNT_SID"),
+  TWILIO_AUTH_TOKEN: getEnv("TWILIO_AUTH_TOKEN"),
+  TWILIO_FROM_NUMBER: getEnv("TWILIO_FROM_NUMBER"),
+  TWILIO_MESSAGING_SERVICE_SID: getEnv("TWILIO_MESSAGING_SERVICE_SID"),
+  OTEL_EXPORTER_OTLP_ENDPOINT: getEnv("OTEL_EXPORTER_OTLP_ENDPOINT"),
+  AUDIT_WEBHOOK_URL: getEnv("AUDIT_WEBHOOK_URL"),
+  AUDIT_CONSOLE_EXPORT: getEnv("AUDIT_CONSOLE_EXPORT", "false"),
+  WEBHOOK_SIGNING_SECRET: getEnv("WEBHOOK_SIGNING_SECRET") || getEnv("KEYSTONE_WEBHOOK_SIGNING_SECRET"),
+} as const;
+
+export function zitadelBaseUrl(): string {
+  if (!config.ZITADEL_DOMAIN) {
+    throw new Error("Zitadel is not configured");
+  }
+  const domain = config.ZITADEL_DOMAIN.replace(/\/$/, "");
+  return domain.startsWith("http") ? domain : `https://${domain}`;
+}
+
+export function isZitadelConfigured(): boolean {
+  return Boolean(config.ZITADEL_DOMAIN && config.ZITADEL_CLIENT_ID);
+}

package/src/container.ts

@@ -0,0 +1,48 @@
+import type { ConfigurationService } from "./services/configuration.js";
+import type { FeatureFlagService } from "./services/features.js";
+import type {
+  UserRepository,
+  OrganizationRepository,
+  ApplicationRepository,
+  AuditRepository,
+  IdentityRepository,
+  PermissionRepository,
+} from "./repositories/types.js";
+import type { ApiKeyRepository } from "./repositories/apiKey.js";
+import type { SamlConnectionRepository } from "./repositories/samlConnection.js";
+import type { OidcConnectionRepository } from "./repositories/oidcConnection.js";
+import type { SecretsProvider } from "./services/secrets/provider.js";
+import type { Queue } from "./services/queue/types.js";
+
+export interface Container {
+  config: ConfigurationService;
+  features: FeatureFlagService;
+  userRepository: UserRepository;
+  identityRepository: IdentityRepository;
+  organizationRepository: OrganizationRepository;
+  applicationRepository: ApplicationRepository;
+  auditRepository: AuditRepository;
+  permissionRepository: PermissionRepository;
+  apiKeyRepository: ApiKeyRepository;
+  samlConnectionRepository: SamlConnectionRepository;
+  oidcConnectionRepository: OidcConnectionRepository;
+  secretsProvider: SecretsProvider;
+  queue: Queue;
+}
+
+let globalContainer: Container | null = null;
+
+export function setContainer(container: Container): void {
+  globalContainer = container;
+}
+
+export function getContainer(): Container {
+  if (!globalContainer) {
+    throw new Error("DI container has not been initialized");
+  }
+  return globalContainer;
+}
+
+export function resolve<K extends keyof Container>(key: K): Container[K] {
+  return getContainer()[key];
+}

package/src/db/index.ts

@@ -0,0 +1,53 @@
+import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { config } from "../config.js";
+import * as schema from "./schema.js";
+
+let dbClient: postgres.Sql | null = null;
+
+/**
+ * Live binding for the Drizzle database client. Re-assigned by `initDb()` once
+ * DATABASE_URL is known. ES module imports see the updated value, so existing
+ * code that imports `db` continues to work after configuration changes.
+ */
+export let db: PostgresJsDatabase<typeof schema>;
+
+export function initDb(): void {
+  const databaseUrl = config.DATABASE_URL;
+  if (!databaseUrl) {
+    throw new Error("DATABASE_URL is not configured");
+  }
+  if (dbClient) {
+    dbClient.end().catch(() => {});
+  }
+  dbClient = postgres(databaseUrl, { max: 10 });
+  db = drizzle(dbClient, { schema });
+}
+
+export function getDb(): PostgresJsDatabase<typeof schema> {
+  if (!db) {
+    initDb();
+  }
+  return db;
+}
+
+/**
+ * Close the underlying connection pool. Used on graceful shutdown and in tests
+ * so pooled sockets do not keep the Node process alive after work is done.
+ */
+export async function closeDb(): Promise<void> {
+  if (dbClient) {
+    const client = dbClient;
+    dbClient = null;
+    await client.end({ timeout: 5 });
+  }
+}
+
+export { schema };
+
+// Initialize immediately when DATABASE_URL is available so existing code paths
+// keep working without an explicit initDb() call.
+if (config.DATABASE_URL) {
+  initDb();
+}