@hilbras/keystone 1.5.0 → 1.9.0

package/src/services/setup/configWriter.ts

@@ -1,200 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { ok, err, type Result } from "../../lib/result.js";
-import type { ConfigWriter } from "./types.js";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-function formatEnvValue(value: string): string {
-  // Quote values that contain whitespace or special characters.
-  if (/[\s#'"]/.test(value)) {
-    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-    return `"${escaped}"`;
-  }
-  return value;
-}
-
-function parseEnvLine(line: string): { key?: string; value?: string; comment?: boolean } {
-  const trimmed = line.trim();
-  if (!trimmed || trimmed.startsWith("#")) {
-    return { comment: true };
-  }
-  const match = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
-  if (!match) return { comment: true };
-  let value = match[2];
-  if (value.startsWith('"') && value.endsWith('"')) {
-    value = value
-      .slice(1, -1)
-      .replace(/\\"/g, '"')
-      .replace(/\\\\/g, "\\");
-  }
-  return { key: match[1], value };
-}
-
-export class EnvFileConfigWriter implements ConfigWriter {
-  private readonly filePath: string;
-
-  constructor(filePath?: string) {
-    this.filePath = filePath || path.resolve(__dirname, "../../../.env");
-  }
-
-  async read(): Promise<Record<string, string | undefined>> {
-    try {
-      const content = await fs.readFile(this.filePath, "utf-8");
-      const values: Record<string, string | undefined> = {};
-      for (const line of content.split(/\r?\n/)) {
-        const { key, value } = parseEnvLine(line);
-        if (key) values[key] = value;
-      }
-      return values;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return {};
-      }
-      throw error;
-    }
-  }
-
-  async write(values: Record<string, string>): Promise<Result<void>> {
-    try {
-      const stats = await fs.stat(this.filePath).catch(() => null);
-      if (stats && !stats.isFile()) {
-        return err({ code: "NOT_A_FILE", message: `${this.filePath} is not a regular file`, statusCode: 400 });
-      }
-
-      const existing = await this.read();
-      const merged = { ...existing, ...values };
-
-      // Preserve comments and ordering from existing file when possible.
-      let lines: string[] = [];
-      try {
-        const content = await fs.readFile(this.filePath, "utf-8");
-        lines = content.split(/\r?\n/);
-      } catch {
-        // File does not exist yet; start fresh.
-      }
-
-      const seen = new Set<string>();
-      const updatedLines: string[] = [];
-
-      for (const line of lines) {
-        const { key } = parseEnvLine(line);
-        if (key && key in merged) {
-          updatedLines.push(`${key}=${formatEnvValue(merged[key]!)}`);
-          seen.add(key);
-        } else {
-          updatedLines.push(line);
-        }
-      }
-
-      // Append any new keys at the end.
-      const newKeys = Object.keys(merged).filter((k) => !seen.has(k));
-      if (newKeys.length > 0) {
-        if (updatedLines.length > 0 && updatedLines[updatedLines.length - 1] !== "") {
-          updatedLines.push("");
-        }
-        for (const key of newKeys) {
-          updatedLines.push(`${key}=${formatEnvValue(merged[key]!)}`);
-        }
-      }
-
-      await fs.writeFile(this.filePath, updatedLines.join("\n") + "\n", { mode: 0o600 });
-      return ok(undefined);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return err({ code: "WRITE_FAILED", message, statusCode: 500 });
-    }
-  }
-
-  async backup(): Promise<Result<string>> {
-    try {
-      const stats = await fs.stat(this.filePath).catch(() => null);
-      if (!stats || !stats.isFile()) {
-        return ok("");
-      }
-      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-      const backupPath = `${this.filePath}.backup-${timestamp}`;
-      await fs.copyFile(this.filePath, backupPath);
-      return ok(backupPath);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return err({ code: "BACKUP_FAILED", message, statusCode: 500 });
-    }
-  }
-}
-
-export class JsonConfigWriter implements ConfigWriter {
-  private readonly filePath: string;
-
-  constructor(filePath?: string) {
-    this.filePath = filePath || path.resolve(__dirname, "../../../config/keystone.json");
-  }
-
-  async read(): Promise<Record<string, string | undefined>> {
-    try {
-      const content = await fs.readFile(this.filePath, "utf-8");
-      const parsed = JSON.parse(content);
-      if (typeof parsed !== "object" || parsed === null) return {};
-      const result: Record<string, string | undefined> = {};
-      for (const [key, value] of Object.entries(parsed)) {
-        result[key] = typeof value === "string" ? value : String(value);
-      }
-      return result;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return {};
-      }
-      throw error;
-    }
-  }
-
-  async write(values: Record<string, string>): Promise<Result<void>> {
-    try {
-      const existing = await this.read();
-      const merged = { ...existing, ...values };
-      await fs.mkdir(path.dirname(this.filePath), { recursive: true });
-      await fs.writeFile(this.filePath, JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
-      return ok(undefined);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return err({ code: "WRITE_FAILED", message, statusCode: 500 });
-    }
-  }
-
-  async backup(): Promise<Result<string>> {
-    try {
-      const stats = await fs.stat(this.filePath).catch(() => null);
-      if (!stats || !stats.isFile()) {
-        return ok("");
-      }
-      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-      const backupPath = `${this.filePath}.backup-${timestamp}`;
-      await fs.copyFile(this.filePath, backupPath);
-      return ok(backupPath);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return err({ code: "BACKUP_FAILED", message, statusCode: 500 });
-    }
-  }
-}
-
-export function createConfigWriter(): ConfigWriter {
-  const mode = process.env.KEYSTONE_CONFIG_MODE?.toLowerCase();
-  if (mode === "json" || isRunningInDocker()) {
-    return new JsonConfigWriter();
-  }
-  return new EnvFileConfigWriter();
-}
-
-function isRunningInDocker(): boolean {
-  // Best-effort detection: presence of /.dockerenv or docker in cgroup.
-  try {
-    const fs = require("node:fs");
-    if (fs.existsSync("/.dockerenv")) return true;
-    const cgroup = fs.readFileSync("/proc/self/cgroup", "utf-8");
-    return cgroup.includes("docker") || cgroup.includes("containerd");
-  } catch {
-    return false;
-  }
-}

package/src/services/setup/diagnostics.ts

@@ -1,76 +0,0 @@
-import { sql } from "drizzle-orm";
-import { config } from "../../config.js";
-import { db } from "../../db/index.js";
-import { redis } from "../redis.js";
-import { getPublicJwks } from "../tokens.js";
-
-export interface DiagnosticCheck {
-  name: string;
-  status: "ok" | "error" | "warning" | "skipped";
-  message?: string;
-}
-
-export async function runSetupDiagnostics(): Promise<DiagnosticCheck[]> {
-  const checks: DiagnosticCheck[] = [];
-
-  // Database
-  try {
-    if (db) {
-      await db.execute(sql`SELECT 1`);
-      checks.push({ name: "Database connectivity", status: "ok" });
-    } else {
-      checks.push({ name: "Database connectivity", status: "error", message: "Database not initialized" });
-    }
-  } catch (err) {
-    checks.push({ name: "Database connectivity", status: "error", message: err instanceof Error ? err.message : String(err) });
-  }
-
-  // Redis
-  try {
-    if (redis.status === "ready" || redis.status === "connect") {
-      await redis.ping();
-      checks.push({ name: "Redis connectivity", status: "ok" });
-    } else {
-      checks.push({ name: "Redis connectivity", status: "warning", message: "Redis not connected" });
-    }
-  } catch (err) {
-    checks.push({ name: "Redis connectivity", status: "error", message: err instanceof Error ? err.message : String(err) });
-  }
-
-  // JWT keys
-  try {
-    const jwks = await getPublicJwks();
-    if (jwks.keys.length > 0) {
-      checks.push({ name: "JWT signing keys", status: "ok", message: `${jwks.keys.length} key(s) available` });
-    } else {
-      checks.push({ name: "JWT signing keys", status: "error", message: "No signing keys available" });
-    }
-  } catch (err) {
-    checks.push({ name: "JWT signing keys", status: "error", message: err instanceof Error ? err.message : String(err) });
-  }
-
-  // Internal API key
-  if (config.INTERNAL_API_KEY) {
-    checks.push({ name: "Internal API key", status: "ok" });
-  } else {
-    checks.push({ name: "Internal API key", status: "warning", message: "Internal API key is not set" });
-  }
-
-  // Email provider
-  if (config.EMAIL_PROVIDER === "none") {
-    checks.push({ name: "Email provider", status: "skipped", message: "No email provider configured" });
-  } else if (config.EMAIL_PROVIDER === "console") {
-    checks.push({ name: "Email provider", status: "ok", message: "Console email provider" });
-  } else {
-    checks.push({ name: "Email provider", status: "ok", message: `${config.EMAIL_PROVIDER} configured` });
-  }
-
-  // Allowed origins
-  if (config.ALLOWED_ORIGINS.length > 0) {
-    checks.push({ name: "CORS origins", status: "ok", message: `${config.ALLOWED_ORIGINS.length} origin(s) configured` });
-  } else {
-    checks.push({ name: "CORS origins", status: "warning", message: "No allowed origins configured" });
-  }
-
-  return checks;
-}

package/src/services/setup/token.ts

@@ -1,42 +0,0 @@
-import crypto from "node:crypto";
-
-const SETUP_TOKEN_ENV = "KEYSTONE_SETUP_TOKEN";
-
-let generatedToken: string | null = null;
-
-export function getSetupToken(): string | undefined {
-  return process.env[SETUP_TOKEN_ENV] || generatedToken || undefined;
-}
-
-export function generateSetupToken(): string {
-  if (!generatedToken) {
-    generatedToken = crypto.randomBytes(32).toString("hex");
-  }
-  return generatedToken;
-}
-
-export function validateSetupToken(token: string | undefined): boolean {
-  if (!token) return false;
-  const expected = getSetupToken();
-  if (!expected) return false;
-
-  // Ignore accidental whitespace / newlines when pasting from the terminal.
-  const cleanToken = token.trim().toLowerCase();
-  const cleanExpected = expected.trim().toLowerCase();
-
-  if (cleanToken.length !== cleanExpected.length) {
-    console.log(`[debug] token length mismatch: sent=${cleanToken.length} expected=${cleanExpected.length}`);
-    return false;
-  }
-  return crypto.timingSafeEqual(Buffer.from(cleanToken), Buffer.from(cleanExpected));
-}
-
-export function printSetupToken(): void {
-  const token = getSetupToken();
-  if (token) {
-    // eslint-disable-next-line no-console
-    console.log(`\n🔐 Keystone setup token: ${token}\n`);
-    // eslint-disable-next-line no-console
-    console.log(`   Use this token to complete setup at http://localhost:${process.env.PORT || 4001}/setup\n`);
-  }
-}

package/src/services/setup/types.ts

@@ -1,40 +0,0 @@
-import type { Result } from "../../lib/result.js";
-
-export interface ConfigWriter {
-  read(): Promise<Record<string, string | undefined>>;
-  write(values: Record<string, string>): Promise<Result<void>>;
-  backup(): Promise<Result<string>>;
-}
-
-export interface DatabaseValidationInput {
-  databaseUrl: string;
-}
-
-export interface RedisValidationInput {
-  redisUrl: string;
-}
-
-export interface EmailValidationInput {
-  provider: "none" | "console" | "smtp" | "sendgrid" | "mailgun";
-  from: string;
-  smtpHost?: string;
-  smtpPort?: number;
-  smtpUser?: string;
-  smtpPass?: string;
-  smtpSecure?: boolean;
-  sendgridApiKey?: string;
-  mailgunApiKey?: string;
-  mailgunDomain?: string;
-}
-
-export interface SmsValidationInput {
-  provider: "none" | "console" | "twilio";
-  twilioAccountSid?: string;
-  twilioAuthToken?: string;
-  twilioFromNumber?: string;
-  twilioMessagingServiceSid?: string;
-}
-
-export interface SetupConfigInput {
-  env: Record<string, string>;
-}

package/src/services/setup/validation.ts

@@ -1,205 +0,0 @@
-import postgres from "postgres";
-import { Redis } from "ioredis";
-import { ok, err, type Result } from "../../lib/result.js";
-import type { DatabaseValidationInput, RedisValidationInput, EmailValidationInput, SmsValidationInput } from "./types.js";
-
-export async function validateDatabase(input: DatabaseValidationInput): Promise<Result<void>> {
-  const { databaseUrl } = input;
-  if (!databaseUrl) {
-    return err({ code: "MISSING_DATABASE_URL", message: "Database URL is required", statusCode: 400 });
-  }
-
-  let client: postgres.Sql | undefined;
-  try {
-    client = postgres(databaseUrl, { max: 1, connect_timeout: 5 });
-
-    // Test basic connectivity.
-    await client`SELECT 1`;
-
-    // Test DDL privileges by creating and dropping a temporary table.
-    await client`CREATE TABLE IF NOT EXISTS __keystone_setup_probe (id serial PRIMARY KEY)`;
-    await client`ALTER TABLE __keystone_setup_probe ADD COLUMN IF NOT EXISTS probe_text text`;
-    await client`DROP TABLE __keystone_setup_probe`;
-
-    await client.end();
-    return ok(undefined);
-  } catch (error) {
-    await client?.end().catch(() => {});
-    const message = error instanceof Error ? error.message : "Database validation failed";
-    return err({ code: "DATABASE_VALIDATION_FAILED", message, statusCode: 400 });
-  }
-}
-
-export async function validateRedis(input: RedisValidationInput): Promise<Result<void>> {
-  const { redisUrl } = input;
-  if (!redisUrl) {
-    return err({ code: "MISSING_REDIS_URL", message: "Redis URL is required", statusCode: 400 });
-  }
-
-  const redis = new Redis(redisUrl, {
-    maxRetriesPerRequest: 1,
-    lazyConnect: true,
-    connectTimeout: 5000,
-  });
-
-  try {
-    await redis.connect();
-    await redis.ping();
-    redis.disconnect();
-    return ok(undefined);
-  } catch (error) {
-    try { redis.disconnect(); } catch { /* ignore */ }
-    const message = error instanceof Error ? error.message : "Redis validation failed";
-    return err({ code: "REDIS_VALIDATION_FAILED", message, statusCode: 400 });
-  }
-}
-
-export async function validateEmail(input: EmailValidationInput, to: string): Promise<Result<void>> {
-  if (input.provider === "none" || input.provider === "console") {
-    return ok(undefined);
-  }
-
-  try {
-    const provider = createTransientEmailProvider(input);
-    await provider.send({
-      to,
-      subject: "Hilbras Keystone setup test",
-      text: "This is a test message from the Hilbras Keystone setup wizard.",
-    });
-    return ok(undefined);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Email validation failed";
-    return err({ code: "EMAIL_VALIDATION_FAILED", message, statusCode: 400 });
-  }
-}
-
-export async function validateSms(input: SmsValidationInput, to: string): Promise<Result<void>> {
-  if (input.provider === "none" || input.provider === "console") {
-    return ok(undefined);
-  }
-
-  try {
-    const provider = createTransientSmsProvider(input);
-    await provider.send({
-      to,
-      body: "Hilbras Keystone setup test message.",
-    });
-    return ok(undefined);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "SMS validation failed";
-    return err({ code: "SMS_VALIDATION_FAILED", message, statusCode: 400 });
-  }
-}
-
-function createTransientEmailProvider(input: EmailValidationInput) {
-  return {
-    send: async (message: { to: string; subject: string; text: string }) => {
-      switch (input.provider) {
-        case "smtp":
-          return sendSmtp(input, message);
-        case "sendgrid":
-          return sendSendGrid(input, message);
-        case "mailgun":
-          return sendMailgun(input, message);
-        default:
-          throw new Error("Unsupported email provider");
-      }
-    },
-  };
-}
-
-async function sendSmtp(input: EmailValidationInput, message: { to: string; subject: string; text: string }) {
-  if (!input.smtpHost) throw new Error("SMTP host is required");
-  const { createTransport } = await import("nodemailer");
-  const transporter = createTransport({
-    host: input.smtpHost,
-    port: input.smtpPort || 587,
-    secure: input.smtpSecure || false,
-    auth: input.smtpUser && input.smtpPass ? { user: input.smtpUser, pass: input.smtpPass } : undefined,
-  });
-  await transporter.verify();
-  await transporter.sendMail({
-    from: input.from,
-    to: message.to,
-    subject: message.subject,
-    text: message.text,
-  });
-}
-
-async function sendSendGrid(input: EmailValidationInput, message: { to: string; subject: string; text: string }) {
-  if (!input.sendgridApiKey) throw new Error("SendGrid API key is required");
-  const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${input.sendgridApiKey}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({
-      personalizations: [{ to: [{ email: message.to }] }],
-      from: { email: input.from },
-      subject: message.subject,
-      content: [{ type: "text/plain", value: message.text }],
-    }),
-  });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`SendGrid request failed: ${response.status} ${body}`);
-  }
-}
-
-async function sendMailgun(input: EmailValidationInput, message: { to: string; subject: string; text: string }) {
-  if (!input.mailgunApiKey || !input.mailgunDomain) throw new Error("Mailgun API key and domain are required");
-  const params = new URLSearchParams();
-  params.set("from", input.from);
-  params.set("to", message.to);
-  params.set("subject", message.subject);
-  params.set("text", message.text);
-  const response = await fetch(`https://api.mailgun.net/v3/${input.mailgunDomain}/messages`, {
-    method: "POST",
-    headers: {
-      Authorization: `Basic ${Buffer.from(`api:${input.mailgunApiKey}`).toString("base64")}`,
-      "Content-Type": "application/x-www-form-urlencoded",
-    },
-    body: params.toString(),
-  });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`Mailgun request failed: ${response.status} ${body}`);
-  }
-}
-
-function createTransientSmsProvider(input: SmsValidationInput) {
-  return {
-    send: async (message: { to: string; body: string }) => {
-      if (input.provider !== "twilio") throw new Error("Unsupported SMS provider");
-      if (!input.twilioAccountSid || !input.twilioAuthToken) {
-        throw new Error("Twilio account SID and auth token are required");
-      }
-      const params = new URLSearchParams();
-      params.set("To", message.to);
-      params.set("Body", message.body);
-      if (input.twilioMessagingServiceSid) {
-        params.set("MessagingServiceSid", input.twilioMessagingServiceSid);
-      } else if (input.twilioFromNumber) {
-        params.set("From", input.twilioFromNumber);
-      } else {
-        throw new Error("Twilio messaging service SID or from number is required");
-      }
-      const response = await fetch(
-        `https://api.twilio.com/2010-04-01/Accounts/${input.twilioAccountSid}/Messages.json`,
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Basic ${Buffer.from(`${input.twilioAccountSid}:${input.twilioAuthToken}`).toString("base64")}`,
-            "Content-Type": "application/x-www-form-urlencoded",
-          },
-          body: params.toString(),
-        }
-      );
-      if (!response.ok) {
-        const body = await response.text();
-        throw new Error(`Twilio request failed: ${response.status} ${body}`);
-      }
-    },
-  };
-}

package/src/services/sms.ts

@@ -1,81 +0,0 @@
-import { config } from "../config.js";
-import { getPluginSmsProvider } from "./plugins/registry.js";
-
-export interface SmsMessage {
-  to: string;
-  body: string;
-}
-
-export interface SmsProvider {
-  name?: string;
-  send(message: SmsMessage): Promise<void>;
-}
-
-class NoOpSmsProvider implements SmsProvider {
-  async send(message: SmsMessage): Promise<void> {
-    console.log("[sms] no-op provider would send:", JSON.stringify(message));
-  }
-}
-
-class ConsoleSmsProvider implements SmsProvider {
-  async send(message: SmsMessage): Promise<void> {
-    console.log("[sms] console provider:");
-    console.log(`To: ${message.to}`);
-    console.log(message.body);
-  }
-}
-
-class TwilioSmsProvider implements SmsProvider {
-  async send(message: SmsMessage): Promise<void> {
-    if (!config.TWILIO_ACCOUNT_SID || !config.TWILIO_AUTH_TOKEN) {
-      throw new Error("Twilio provider requires TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN");
-    }
-
-    const params = new URLSearchParams();
-    params.set("To", message.to);
-    params.set("Body", message.body);
-
-    if (config.TWILIO_MESSAGING_SERVICE_SID) {
-      params.set("MessagingServiceSid", config.TWILIO_MESSAGING_SERVICE_SID);
-    } else if (config.TWILIO_FROM_NUMBER) {
-      params.set("From", config.TWILIO_FROM_NUMBER);
-    } else {
-      throw new Error("Twilio provider requires TWILIO_MESSAGING_SERVICE_SID or TWILIO_FROM_NUMBER");
-    }
-
-    const response = await fetch(
-      `https://api.twilio.com/2010-04-01/Accounts/${config.TWILIO_ACCOUNT_SID}/Messages.json`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Basic ${Buffer.from(`${config.TWILIO_ACCOUNT_SID}:${config.TWILIO_AUTH_TOKEN}`).toString("base64")}`,
-          "Content-Type": "application/x-www-form-urlencoded",
-        },
-        body: params.toString(),
-      }
-    );
-
-    if (!response.ok) {
-      const body = await response.text();
-      throw new Error(`Twilio request failed: ${response.status} ${body}`);
-    }
-  }
-}
-
-function createSmsProvider(): SmsProvider {
-  const plugin = getPluginSmsProvider();
-  if (plugin) return plugin;
-
-  const provider = config.SMS_PROVIDER || "none";
-  switch (provider) {
-    case "twilio":
-      return new TwilioSmsProvider();
-    case "console":
-      return new ConsoleSmsProvider();
-    case "none":
-    default:
-      return new NoOpSmsProvider();
-  }
-}
-
-export const smsProvider = createSmsProvider();