@hilbras/keystone 1.1.0

package/src/services/email.ts

@@ -0,0 +1,167 @@
+import { config } from "../config.js";
+import { getPluginEmailProvider } from "./plugins/registry.js";
+
+export interface EmailMessage {
+  to: string;
+  subject: string;
+  text: string;
+  html?: string;
+}
+
+export interface EmailProvider {
+  name?: string;
+  send(message: EmailMessage): Promise<void>;
+}
+
+class NoOpEmailProvider implements EmailProvider {
+  async send(message: EmailMessage): Promise<void> {
+    console.log("[email] no-op provider would send:", JSON.stringify(message));
+  }
+}
+
+class ConsoleEmailProvider implements EmailProvider {
+  async send(message: EmailMessage): Promise<void> {
+    console.log("[email] console provider:");
+    console.log(`To: ${message.to}`);
+    console.log(`Subject: ${message.subject}`);
+    console.log(message.text);
+  }
+}
+
+class SmtpEmailProvider implements EmailProvider {
+  private transporter: import("nodemailer").Transporter | null = null;
+
+  async send(message: EmailMessage): Promise<void> {
+    if (!this.transporter) {
+      const { createTransport } = await import("nodemailer");
+      this.transporter = createTransport({
+        host: config.SMTP_HOST,
+        port: config.SMTP_PORT,
+        secure: config.SMTP_SECURE,
+        auth:
+          config.SMTP_USER && config.SMTP_PASS
+            ? { user: config.SMTP_USER, pass: config.SMTP_PASS }
+            : undefined,
+      });
+    }
+
+    await this.transporter.sendMail({
+      from: config.EMAIL_FROM,
+      to: message.to,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+    });
+  }
+}
+
+class SendGridEmailProvider implements EmailProvider {
+  async send(message: EmailMessage): Promise<void> {
+    if (!config.SENDGRID_API_KEY) {
+      throw new Error("SendGrid provider requires SENDGRID_API_KEY");
+    }
+
+    const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.SENDGRID_API_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        personalizations: [{ to: [{ email: message.to }] }],
+        from: { email: config.EMAIL_FROM },
+        subject: message.subject,
+        content: [
+          { type: "text/plain", value: message.text },
+          ...(message.html ? [{ type: "text/html", value: message.html }] : []),
+        ],
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`SendGrid request failed: ${response.status} ${body}`);
+    }
+  }
+}
+
+class MailgunEmailProvider implements EmailProvider {
+  async send(message: EmailMessage): Promise<void> {
+    if (!config.MAILGUN_API_KEY || !config.MAILGUN_DOMAIN) {
+      throw new Error("Mailgun provider requires MAILGUN_API_KEY and MAILGUN_DOMAIN");
+    }
+
+    const params = new URLSearchParams();
+    params.set("from", config.EMAIL_FROM);
+    params.set("to", message.to);
+    params.set("subject", message.subject);
+    params.set("text", message.text);
+    if (message.html) params.set("html", message.html);
+
+    const response = await fetch(
+      `https://api.mailgun.net/v3/${config.MAILGUN_DOMAIN}/messages`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${Buffer.from(`api:${config.MAILGUN_API_KEY}`).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 createEmailProvider(): EmailProvider {
+  const plugin = getPluginEmailProvider();
+  if (plugin) return plugin;
+
+  const provider = config.EMAIL_PROVIDER || "none";
+  switch (provider) {
+    case "smtp":
+      return new SmtpEmailProvider();
+    case "sendgrid":
+      return new SendGridEmailProvider();
+    case "mailgun":
+      return new MailgunEmailProvider();
+    case "console":
+      return new ConsoleEmailProvider();
+    case "none":
+    default:
+      return new NoOpEmailProvider();
+  }
+}
+
+export const emailProvider = createEmailProvider();
+
+export async function sendNewDeviceAlert(input: {
+  email: string;
+  ipAddress?: string;
+  userAgent?: string;
+  deviceName?: string;
+}): Promise<void> {
+  await emailProvider.send({
+    to: input.email,
+    subject: "New sign-in from an unrecognized device",
+    text: `A new device was used to sign in to your Hilbras account.\n\nIP: ${input.ipAddress || "unknown"}\nDevice: ${input.deviceName || input.userAgent || "unknown"}\n\nIf this wasn't you, please change your password immediately.`,
+  });
+}
+
+export async function sendSuspiciousLoginAlert(input: {
+  email: string;
+  ipAddress?: string;
+  userAgent?: string;
+  reason: string;
+}): Promise<void> {
+  await emailProvider.send({
+    to: input.email,
+    subject: "Suspicious sign-in activity detected",
+    text: `We detected suspicious sign-in activity on your Hilbras account.\n\nReason: ${input.reason}\nIP: ${input.ipAddress || "unknown"}\nDevice: ${input.userAgent || "unknown"}\n\nIf this wasn't you, please change your password immediately and review your active sessions.`,
+    html: `<p>We detected suspicious sign-in activity on your Hilbras account.</p><ul><li><strong>Reason:</strong> ${input.reason}</li><li><strong>IP:</strong> ${input.ipAddress || "unknown"}</li><li><strong>Device:</strong> ${input.userAgent || "unknown"}</li></ul><p>If this wasn't you, please change your password immediately and review your active sessions.</p>`,
+  });
+}

package/src/services/emailVerification.ts

@@ -0,0 +1,75 @@
+import crypto from "node:crypto";
+import { eq, and, gt, isNull } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { emailVerificationTokens, users, type User } from "../db/schema.js";
+import { emailProvider } from "./email.js";
+
+const TOKEN_TTL_SECONDS = 24 * 60 * 60; // 24 hours
+
+function hashToken(token: string): string {
+  return crypto.createHash("sha256").update(token).digest("hex");
+}
+
+export function generateVerificationToken(): { token: string; tokenHash: string } {
+  const token = crypto.randomBytes(48).toString("base64url");
+  return { token, tokenHash: hashToken(token) };
+}
+
+export async function storeVerificationToken(userId: string, tokenHash: string) {
+  const [record] = await db
+    .insert(emailVerificationTokens)
+    .values({
+      userId,
+      tokenHash,
+      expiresAt: new Date(Date.now() + TOKEN_TTL_SECONDS * 1000),
+    })
+    .returning();
+  return record;
+}
+
+export async function consumeVerificationToken(token: string): Promise<User | undefined> {
+  const tokenHash = hashToken(token);
+  const now = new Date();
+
+  const [record] = await db
+    .select()
+    .from(emailVerificationTokens)
+    .where(
+      and(
+        eq(emailVerificationTokens.tokenHash, tokenHash),
+        gt(emailVerificationTokens.expiresAt, now),
+        isNull(emailVerificationTokens.usedAt)
+      )
+    )
+    .limit(1);
+
+  if (!record) return undefined;
+
+  await db.update(emailVerificationTokens).set({ usedAt: now }).where(eq(emailVerificationTokens.id, record.id));
+
+  const [user] = await db
+    .update(users)
+    .set({ emailVerified: true, updatedAt: now })
+    .where(eq(users.id, record.userId))
+    .returning();
+
+  return user;
+}
+
+function verificationUrl(token: string): string {
+  const base = process.env.CLIENT_APP_URL || "http://localhost:5173";
+  return `${base}/#verify-email=${encodeURIComponent(token)}`;
+}
+
+export async function sendVerificationEmail(user: { id: string; email: string; name?: string | null }): Promise<void> {
+  const { token, tokenHash } = generateVerificationToken();
+  await storeVerificationToken(user.id, tokenHash);
+
+  const url = verificationUrl(token);
+  await emailProvider.send({
+    to: user.email,
+    subject: "Verify your email address",
+    text: `Hi${user.name ? ` ${user.name}` : ""},\n\nPlease verify your email address by clicking the link below:\n\n${url}\n\nThis link expires in 24 hours.`,
+    html: `<p>Hi${user.name ? ` ${user.name}` : ""},</p><p>Please verify your email address by clicking <a href="${url}">here</a>.</p><p>This link expires in 24 hours.</p>`,
+  });
+}

package/src/services/enterpriseSso.ts

@@ -0,0 +1,58 @@
+import { eq } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { users, orgMemberships, type Organization } from "../db/schema.js";
+import { slugifyUsername, ensureUniqueUsername } from "./users.js";
+
+export interface EnterpriseUserClaims {
+  email: string;
+  name?: string;
+  username?: string;
+  externalId?: string;
+}
+
+export async function provisionEnterpriseUser(
+  orgId: string,
+  claims: EnterpriseUserClaims,
+  defaultRole: "owner" | "admin" | "member" = "member"
+) {
+  const email = claims.email.toLowerCase().trim();
+
+  let [user] = await db.select().from(users).where(eq(users.email, email)).limit(1);
+
+  if (!user) {
+    const baseUsername = claims.username || claims.email.split("@")[0];
+    const username = await ensureUniqueUsername(slugifyUsername(baseUsername));
+
+    [user] = await db
+      .insert(users)
+      .values({
+        email,
+        username,
+        name: claims.name || username,
+        provider: "enterprise_sso",
+        emailVerified: true,
+      })
+      .returning();
+  }
+
+  const [existingMembership] = await db
+    .select()
+    .from(orgMemberships)
+    .where(eq(orgMemberships.userId, user.id))
+    .limit(1);
+
+  if (!existingMembership) {
+    await db.insert(orgMemberships).values({
+      orgId,
+      userId: user.id,
+      role: defaultRole,
+    });
+  }
+
+  return user;
+}
+
+export function defaultRoleForOrg(_org: Organization): "owner" | "admin" | "member" {
+  // Future: allow org-level default SSO role configuration.
+  return "member";
+}

package/src/services/events/bus.ts

@@ -0,0 +1,43 @@
+import type { KeystoneEvent, EventHandler, EventPayload } from "./types.js";
+import { normalizeEvent } from "./validate.js";
+
+const subscribers = new Map<string, EventHandler[]>();
+const allSubscribers: EventHandler[] = [];
+
+export function subscribe(eventType: string, handler: EventHandler): () => void {
+  const list = subscribers.get(eventType) ?? [];
+  list.push(handler);
+  subscribers.set(eventType, list);
+  return () => {
+    const updated = subscribers.get(eventType)?.filter((h) => h !== handler) ?? [];
+    subscribers.set(eventType, updated);
+  };
+}
+
+export function subscribeAll(handler: EventHandler): () => void {
+  allSubscribers.push(handler);
+  return () => {
+    const idx = allSubscribers.indexOf(handler);
+    if (idx >= 0) allSubscribers.splice(idx, 1);
+  };
+}
+
+export type EmittableEvent = Omit<KeystoneEvent, "timestamp" | "version"> & { version?: number };
+
+export async function emit(event: EmittableEvent): Promise<void> {
+  const fullEvent = normalizeEvent(event);
+  const handlers = [...allSubscribers, ...(subscribers.get(fullEvent.type) ?? [])];
+  await Promise.all(
+    handlers.map(async (handler) => {
+      try {
+        await handler(fullEvent);
+      } catch (err) {
+        console.error(`[event-bus] handler failed for ${fullEvent.type}:`, err);
+      }
+    })
+  );
+}
+
+export function buildEvent(type: string, payload: EventPayload): EmittableEvent {
+  return { type, payload };
+}

package/src/services/events/subscribers/anomaly.ts

@@ -0,0 +1,13 @@
+import { recordFailedLogin, recordNewDevice } from "../../anomalyDetection.js";
+import type { KeystoneEvent } from "../types.js";
+
+export async function anomalySubscriber(event: KeystoneEvent): Promise<void> {
+  if (event.type === "user_login_failed") {
+    const identifier = event.payload.userId || event.payload.metadata?.email || event.payload.ip || "unknown";
+    await recordFailedLogin(String(identifier));
+  }
+  if (event.type === "new_device_detected") {
+    const userId = event.payload.userId;
+    if (userId) await recordNewDevice(userId);
+  }
+}

package/src/services/events/subscribers/auditLog.ts

@@ -0,0 +1,21 @@
+import { db } from "../../../db/index.js";
+import { auditLog } from "../../../db/schema.js";
+import type { KeystoneEvent } from "../types.js";
+
+export async function auditLogSubscriber(event: KeystoneEvent): Promise<void> {
+  try {
+    const { userId, orgId, appId, requestId, ip, userAgent, metadata } = event.payload;
+    await db.insert(auditLog).values({
+      userId: userId ?? null,
+      orgId: orgId ?? null,
+      appId: appId ?? null,
+      requestId: requestId ?? null,
+      event: `${event.type}:v${event.version}`,
+      ipAddress: ip ?? null,
+      userAgent: userAgent ?? null,
+      metadata: { ...(metadata ?? {}), eventVersion: event.version },
+    });
+  } catch (err) {
+    console.error("[audit-log-subscriber] failed to write event:", err);
+  }
+}

package/src/services/events/subscribers/webhook.ts

@@ -0,0 +1,39 @@
+import { config } from "../../../config.js";
+import { queue } from "../../queue/index.js";
+import { signWebhookPayload } from "../../../lib/webhookSignature.js";
+import type { KeystoneEvent } from "../types.js";
+
+function shouldEmit(): boolean {
+  return Boolean(config.AUDIT_WEBHOOK_URL || process.env.AUDIT_WEBHOOK_URL || config.AUDIT_CONSOLE_EXPORT === "true");
+}
+
+export async function webhookSubscriber(event: KeystoneEvent): Promise<void> {
+  if (!shouldEmit()) return;
+  const record = {
+    event: event.type,
+    version: event.version,
+    userId: event.payload.userId,
+    orgId: event.payload.orgId,
+    appId: event.payload.appId,
+    ip: event.payload.ip,
+    userAgent: event.payload.userAgent,
+    metadata: event.payload.metadata,
+    createdAt: event.timestamp,
+  };
+
+  if (config.AUDIT_CONSOLE_EXPORT === "true") {
+    console.log("[audit-export]", JSON.stringify(record));
+  }
+
+  const webhookUrl = config.AUDIT_WEBHOOK_URL || process.env.AUDIT_WEBHOOK_URL;
+  if (webhookUrl) {
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (config.WEBHOOK_SIGNING_SECRET) {
+      headers["X-Keystone-Signature"] = signWebhookPayload(config.WEBHOOK_SIGNING_SECRET, record);
+    }
+    await queue.enqueue({
+      type: "webhook",
+      payload: { url: webhookUrl, method: "POST", body: record, headers },
+    });
+  }
+}

package/src/services/events/subscribers/webhookDispatch.ts

@@ -0,0 +1,14 @@
+import { dispatchEvent } from "../../webhooks.js";
+import type { KeystoneEvent } from "../types.js";
+
+/**
+ * Fans every platform event out to registered webhook endpoints.
+ * Delivery itself happens asynchronously via the queue worker.
+ */
+export async function webhookDispatchSubscriber(event: KeystoneEvent): Promise<void> {
+  try {
+    await dispatchEvent(event);
+  } catch (err) {
+    console.error("[webhooks] dispatch failed:", err);
+  }
+}

package/src/services/events/types.ts

@@ -0,0 +1,106 @@
+export interface EventPayload {
+  userId?: string;
+  orgId?: string;
+  appId?: string;
+  requestId?: string;
+  ip?: string;
+  userAgent?: string;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface KeystoneEvent {
+  type: string;
+  version: number;
+  timestamp: Date;
+  payload: EventPayload;
+}
+
+export type EventHandler = (event: KeystoneEvent) => void | Promise<void>;
+
+export const EVENT_VERSIONS: Record<string, number> = {
+  // Default version for all existing events.
+  default: 1,
+};
+
+export function eventVersion(type: string): number {
+  return EVENT_VERSIONS[type] ?? EVENT_VERSIONS.default;
+}
+
+export type AuditEventType =
+  | "user_registered"
+  | "user_login"
+  | "user_login_failed"
+  | "user_logout"
+  | "token_refresh"
+  | "token_refresh_failed"
+  | "oauth_callback"
+  | "oauth2_authorize"
+  | "oauth2_token"
+  | "oauth2_client_credentials"
+  | "oauth2_revoke"
+  | "oauth2_consent"
+  | "password_reset_requested"
+  | "password_reset_completed"
+  | "api_key_created"
+  | "api_key_revoked"
+  | "api_key_used"
+  | "service_account_created"
+  | "service_account_updated"
+  | "unauthorized_access"
+  | "organization_created"
+  | "organization_updated"
+  | "organization_plan_updated"
+  | "billing_customer_provisioned"
+  | "organization_member_invited"
+  | "organization_member_removed"
+  | "organization_member_role_updated"
+  | "permission_created"
+  | "permission_deleted"
+  | "application_created"
+  | "application_updated"
+  | "magic_link_sent"
+  | "magic_link_verified"
+  | "totp_enrolled"
+  | "totp_verify_failed"
+  | "totp_enabled"
+  | "totp_disable_failed"
+  | "totp_disabled"
+  | "webauthn_registered"
+  | "webauthn_authenticated"
+  | "new_device_detected"
+  | "sms_otp_sent"
+  | "sms_otp_verify_failed"
+  | "sms_otp_verified"
+  | "authz_check"
+  | "saml_sso_login"
+  | "oidc_enterprise_login"
+  | "saml_connection_created"
+  | "saml_connection_deleted"
+  | "oidc_connection_created"
+  | "oidc_connection_deleted"
+  | "scim_user_created"
+  | "scim_user_updated"
+  | "scim_user_deleted"
+  | "federation_login"
+  | "workflow_triggered"
+  | "workflow_step_executed"
+  | "workflow_created"
+  | "workflow_deleted"
+  | "platform_user_updated"
+  | "platform_user_deactivated"
+  | "platform_signing_key_rotated"
+  | "platform_plugin_unregistered"
+  | "platform_feature_flag_updated"
+  | "platform_feature_flag_deleted"
+  | "profile_updated"
+  | "email_verification_sent"
+  | "email_verified"
+  | "platform_webhook_created"
+  | "platform_webhook_updated"
+  | "platform_webhook_deleted"
+  | "platform_webhook_secret_rotated"
+  | "federation_identity_linked"
+  | "user_token_login"
+  | "session_revoked"
+  | "sessions_revoked_all";

package/src/services/events/validate.ts

@@ -0,0 +1,118 @@
+import type { KeystoneEvent } from "./types.js";
+import { eventVersion } from "./types.js";
+import type { EmittableEvent } from "./bus.js";
+
+export interface EventValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+const VALID_EVENT_TYPES = new Set([
+  "user_registered",
+  "user_login",
+  "user_login_failed",
+  "user_logout",
+  "token_refresh",
+  "token_refresh_failed",
+  "oauth_callback",
+  "oauth2_authorize",
+  "oauth2_token",
+  "oauth2_client_credentials",
+  "oauth2_revoke",
+  "oauth2_consent",
+  "password_reset_requested",
+  "password_reset_completed",
+  "api_key_created",
+  "api_key_revoked",
+  "api_key_used",
+  "service_account_created",
+  "service_account_updated",
+  "unauthorized_access",
+  "organization_created",
+  "organization_updated",
+  "organization_plan_updated",
+  "billing_customer_provisioned",
+  "organization_member_invited",
+  "organization_member_removed",
+  "organization_member_role_updated",
+  "permission_created",
+  "permission_deleted",
+  "application_created",
+  "application_updated",
+  "magic_link_sent",
+  "magic_link_verified",
+  "totp_enrolled",
+  "totp_verify_failed",
+  "totp_enabled",
+  "totp_disable_failed",
+  "totp_disabled",
+  "webauthn_registered",
+  "webauthn_authenticated",
+  "new_device_detected",
+  "sms_otp_sent",
+  "sms_otp_verify_failed",
+  "sms_otp_verified",
+  "authz_check",
+  "saml_sso_login",
+  "saml_connection_created",
+  "saml_connection_deleted",
+  "oidc_enterprise_login",
+  "oidc_connection_created",
+  "oidc_connection_deleted",
+  "scim_user_created",
+  "scim_user_updated",
+  "scim_user_deleted",
+  "federation_login",
+  "workflow_triggered",
+  "workflow_step_executed",
+  "workflow_created",
+  "workflow_deleted",
+  "platform_user_updated",
+  "platform_user_deactivated",
+  "platform_signing_key_rotated",
+  "platform_plugin_unregistered",
+  "platform_feature_flag_updated",
+  "platform_feature_flag_deleted",
+  "profile_updated",
+  "email_verification_sent",
+  "email_verified",
+  "platform_webhook_created",
+  "platform_webhook_deleted",
+]);
+
+export function validateEvent(event: EmittableEvent): EventValidationResult {
+  const errors: string[] = [];
+
+  if (!event.type || typeof event.type !== "string") {
+    errors.push("Event type is required and must be a string");
+    return { valid: false, errors };
+  }
+
+  if (!VALID_EVENT_TYPES.has(event.type)) {
+    errors.push(`Unknown event type: ${event.type}`);
+  }
+
+  if (event.version !== undefined && (typeof event.version !== "number" || event.version < 1)) {
+    errors.push("Event version must be a positive integer");
+  }
+
+  if (!event.payload || typeof event.payload !== "object" || Array.isArray(event.payload)) {
+    errors.push("Event payload must be an object");
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function normalizeEvent(event: EmittableEvent): KeystoneEvent {
+  const validation = validateEvent(event);
+  if (!validation.valid) {
+    throw new Error(`Invalid event: ${validation.errors.join("; ")}`);
+  }
+
+  return {
+    type: event.type,
+    version: event.version ?? eventVersion(event.type),
+    timestamp: new Date(),
+    payload: event.payload,
+  };
+}