@hilbras/keystone 1.1.0

package/src/services/webauthn.ts

@@ -0,0 +1,193 @@
+import crypto from "node:crypto";
+import { eq } from "drizzle-orm";
+import {
+  generateRegistrationOptions,
+  verifyRegistrationResponse,
+  generateAuthenticationOptions,
+  verifyAuthenticationResponse,
+  type RegistrationResponseJSON,
+  type AuthenticationResponseJSON,
+  type AuthenticatorTransportFuture,
+} from "@simplewebauthn/server";
+import { db } from "../db/index.js";
+import {
+  webauthnCredentials,
+  users,
+  type User,
+  type WebAuthnCredential as DbWebAuthnCredential,
+} from "../db/schema.js";
+import { config } from "../config.js";
+
+const RP_NAME = "Hilbras Keystone";
+
+function rpID(): string {
+  const url = config.AUTH_API_PUBLIC_URL || `http://localhost:${config.PORT}`;
+  return new URL(url).hostname;
+}
+
+function origin(): string {
+  return config.AUTH_API_PUBLIC_URL || `http://localhost:${config.PORT}`;
+}
+
+export interface WebAuthnChallenge {
+  challenge: string;
+  userId?: string;
+  expiresAt: number;
+}
+
+const challenges = new Map<string, WebAuthnChallenge>();
+
+function cleanupChallenges(): void {
+  const now = Date.now();
+  for (const [key, value] of challenges) {
+    if (value.expiresAt < now) challenges.delete(key);
+  }
+}
+
+export function createChallenge(userId?: string): string {
+  cleanupChallenges();
+  const challenge = crypto.randomBytes(32).toString("base64url");
+  challenges.set(challenge, { challenge, userId, expiresAt: Date.now() + 5 * 60 * 1000 });
+  return challenge;
+}
+
+export function consumeChallenge(challenge: string): WebAuthnChallenge | undefined {
+  const record = challenges.get(challenge);
+  challenges.delete(challenge);
+  if (!record) return undefined;
+  if (record.expiresAt < Date.now()) return undefined;
+  return record;
+}
+
+export async function listCredentialsByUser(userId: string): Promise<DbWebAuthnCredential[]> {
+  return db.select().from(webauthnCredentials).where(eq(webauthnCredentials.userId, userId));
+}
+
+export async function findCredentialById(credentialId: string): Promise<DbWebAuthnCredential | undefined> {
+  const [record] = await db
+    .select()
+    .from(webauthnCredentials)
+    .where(eq(webauthnCredentials.credentialId, credentialId))
+    .limit(1);
+  return record;
+}
+
+export async function buildRegistrationOptions(user: User) {
+  const options = await generateRegistrationOptions({
+    rpName: RP_NAME,
+    rpID: rpID(),
+    userName: user.email,
+    userDisplayName: user.name || user.username,
+    userID: Buffer.from(user.id, "utf8"),
+    challenge: createChallenge(user.id),
+    attestationType: "none",
+    authenticatorSelection: {
+      residentKey: "preferred",
+      userVerification: "preferred",
+    },
+  });
+  return options;
+}
+
+export async function verifyAndStoreRegistration(
+  user: User,
+  response: RegistrationResponseJSON,
+  expectedChallenge: string,
+  deviceName?: string
+) {
+  const verification = await verifyRegistrationResponse({
+    response,
+    expectedChallenge,
+    expectedOrigin: origin(),
+    expectedRPID: rpID(),
+    requireUserVerification: false,
+  });
+
+  if (!verification.verified || !verification.registrationInfo) {
+    throw new Error("WebAuthn registration verification failed");
+  }
+
+  const info = verification.registrationInfo;
+  const credential = info.credential;
+  await db.insert(webauthnCredentials).values({
+    userId: user.id,
+    credentialId: credential.id,
+    publicKey: Buffer.from(credential.publicKey).toString("base64url"),
+    counter: credential.counter,
+    transports: (credential.transports || []) as AuthenticatorTransportFuture[],
+    aaguid: info.aaguid || null,
+    deviceName: deviceName || null,
+  });
+
+  return { verified: true };
+}
+
+export async function buildAuthenticationOptions(email?: string) {
+  let allowCredentials:
+    | { id: string; type: "public-key"; transports?: AuthenticatorTransportFuture[] }[]
+    | undefined;
+  let userId: string | undefined;
+
+  if (email) {
+    const [user] = await db.select().from(users).where(eq(users.email, email.toLowerCase())).limit(1);
+    if (user) {
+      userId = user.id;
+      const credentials = await listCredentialsByUser(user.id);
+      allowCredentials = credentials.map((c) => ({
+        id: c.credentialId,
+        type: "public-key" as const,
+        transports: (c.transports || []) as AuthenticatorTransportFuture[],
+      }));
+    }
+  }
+
+  const options = await generateAuthenticationOptions({
+    rpID: rpID(),
+    challenge: createChallenge(userId),
+    allowCredentials,
+    userVerification: "preferred",
+  });
+
+  return options;
+}
+
+export async function verifyAuthentication(response: AuthenticationResponseJSON, expectedChallenge: string) {
+  const credentialId = response.id;
+  const credential = await findCredentialById(credentialId);
+  if (!credential) {
+    throw new Error("Credential not found");
+  }
+
+  const verification = await verifyAuthenticationResponse({
+    response,
+    expectedChallenge,
+    expectedOrigin: origin(),
+    expectedRPID: rpID(),
+    credential: {
+      id: credential.credentialId,
+      publicKey: Buffer.from(credential.publicKey, "base64url"),
+      counter: credential.counter,
+      transports: (credential.transports || []) as AuthenticatorTransportFuture[],
+    },
+    requireUserVerification: false,
+  });
+
+  if (!verification.verified) {
+    throw new Error("WebAuthn authentication verification failed");
+  }
+
+  await db
+    .update(webauthnCredentials)
+    .set({
+      counter: verification.authenticationInfo.newCounter,
+      lastUsedAt: new Date(),
+    })
+    .where(eq(webauthnCredentials.id, credential.id));
+
+  const [user] = await db.select().from(users).where(eq(users.id, credential.userId)).limit(1);
+  if (!user) {
+    throw new Error("User not found");
+  }
+
+  return { verified: true, user };
+}

package/src/services/webhooks.ts

@@ -0,0 +1,190 @@
+import crypto from "node:crypto";
+import { and, desc, eq } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { webhookDeliveries, webhookEndpoints, type WebhookEndpoint } from "../db/schema.js";
+import { signWebhookPayload } from "../lib/webhookSignature.js";
+import { queue } from "./queue/index.js";
+import type { KeystoneEvent } from "./events/types.js";
+
+const MAX_ATTEMPTS = 5;
+const RETRY_DELAY_MS = 30_000;
+
+export type { WebhookEndpoint };
+
+export async function listEndpoints(appId?: string) {
+  if (appId) {
+    return db.select().from(webhookEndpoints).where(eq(webhookEndpoints.appId, appId)).orderBy(webhookEndpoints.createdAt);
+  }
+  return db.select().from(webhookEndpoints).orderBy(webhookEndpoints.createdAt);
+}
+
+export async function createEndpoint(input: {
+  appId?: string | null;
+  url: string;
+  description?: string;
+  events?: string[];
+}): Promise<WebhookEndpoint & { signingSecret: string }> {
+  const secret = `whsec_${crypto.randomBytes(24).toString("base64url")}`;
+  const [endpoint] = await db
+    .insert(webhookEndpoints)
+    .values({
+      appId: input.appId ?? null,
+      url: input.url,
+      description: input.description ?? null,
+      events: input.events ?? [],
+      secret,
+    })
+    .returning();
+  return { ...endpoint, signingSecret: secret };
+}
+
+export async function updateEndpoint(
+  id: string,
+  input: Partial<{ url: string; description: string | null; events: string[]; isActive: boolean }>
+) {
+  const [updated] = await db
+    .update(webhookEndpoints)
+    .set({ ...input, updatedAt: new Date() })
+    .where(eq(webhookEndpoints.id, id))
+    .returning();
+  return updated;
+}
+
+export async function deleteEndpoint(id: string) {
+  const [deleted] = await db.delete(webhookEndpoints).where(eq(webhookEndpoints.id, id)).returning();
+  return deleted;
+}
+
+export async function rotateEndpointSecret(id: string) {
+  const secret = `whsec_${crypto.randomBytes(24).toString("base64url")}`;
+  const [updated] = await db
+    .update(webhookEndpoints)
+    .set({ secret, updatedAt: new Date() })
+    .where(eq(webhookEndpoints.id, id))
+    .returning();
+  return updated ? { endpoint: updated, signingSecret: secret } : undefined;
+}
+
+export async function listDeliveries(endpointId: string, limit = 50) {
+  return db
+    .select()
+    .from(webhookDeliveries)
+    .where(eq(webhookDeliveries.endpointId, endpointId))
+    .orderBy(desc(webhookDeliveries.createdAt))
+    .limit(limit);
+}
+
+/**
+ * Fan an event out to every active endpoint subscribed to it.
+ * Each delivery is persisted first, then handed to the queue worker.
+ */
+export async function dispatchEvent(event: KeystoneEvent): Promise<void> {
+  const endpoints = await db.select().from(webhookEndpoints).where(eq(webhookEndpoints.isActive, true));
+
+  for (const endpoint of endpoints) {
+    // App-scoped endpoints only receive events for their own application.
+    if (endpoint.appId && event.payload.appId && endpoint.appId !== event.payload.appId) continue;
+    if (endpoint.events.length > 0 && !endpoint.events.includes(event.type)) continue;
+
+    const body = {
+      id: crypto.randomUUID(),
+      type: event.type,
+      version: event.version,
+      timestamp: event.timestamp,
+      payload: event.payload,
+    };
+
+    const [delivery] = await db
+      .insert(webhookDeliveries)
+      .values({ endpointId: endpoint.id, eventType: event.type, payload: body })
+      .returning();
+
+    await queue.enqueue({
+      type: "webhook-delivery",
+      payload: { deliveryId: delivery.id },
+    });
+  }
+}
+
+export async function deliverNow(deliveryId: string): Promise<void> {
+  const [delivery] = await db.select().from(webhookDeliveries).where(eq(webhookDeliveries.id, deliveryId)).limit(1);
+  if (!delivery) return;
+
+  const [endpoint] = await db.select().from(webhookEndpoints).where(eq(webhookEndpoints.id, delivery.endpointId)).limit(1);
+  if (!endpoint || !endpoint.isActive) return;
+
+  const attempts = delivery.attempts + 1;
+  const now = new Date();
+
+  try {
+    const response = await fetch(endpoint.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Keystone-Signature": signWebhookPayload(endpoint.secret, delivery.payload),
+        "X-Keystone-Event": delivery.eventType,
+        "X-Keystone-Delivery": delivery.id,
+      },
+      body: JSON.stringify(delivery.payload),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    const responseBody = (await response.text()).slice(0, 2000);
+    await db
+      .update(webhookDeliveries)
+      .set({
+        attempts,
+        lastAttemptAt: now,
+        responseStatus: response.status,
+        responseBody,
+        status: response.ok ? "success" : "failed",
+      })
+      .where(eq(webhookDeliveries.id, deliveryId));
+
+    if (!response.ok && attempts < MAX_ATTEMPTS) {
+      await retryLater(deliveryId);
+    }
+  } catch (err) {
+    await db
+      .update(webhookDeliveries)
+      .set({
+        attempts,
+        lastAttemptAt: now,
+        responseBody: err instanceof Error ? err.message.slice(0, 2000) : "Delivery error",
+        status: attempts >= MAX_ATTEMPTS ? "failed" : "pending",
+      })
+      .where(eq(webhookDeliveries.id, deliveryId));
+
+    if (attempts < MAX_ATTEMPTS) {
+      await retryLater(deliveryId);
+    }
+  }
+}
+
+async function retryLater(deliveryId: string): Promise<void> {
+  setTimeout(() => {
+    queue.enqueue({ type: "webhook-delivery", payload: { deliveryId } }).catch((err: unknown) => {
+      console.error("[webhooks] failed to re-enqueue delivery:", err);
+    });
+  }, RETRY_DELAY_MS).unref();
+}
+
+/** Manual retry from the dashboard: reset to pending and enqueue. */
+export async function retryDelivery(deliveryId: string): Promise<boolean> {
+  const [updated] = await db
+    .update(webhookDeliveries)
+    .set({ status: "pending" })
+    .where(and(eq(webhookDeliveries.id, deliveryId), eq(webhookDeliveries.status, "failed")))
+    .returning();
+  if (!updated) return false;
+  await queue.enqueue({ type: "webhook-delivery", payload: { deliveryId } });
+  return true;
+}
+
+/** Register the delivery worker with the queue. */
+export function startWebhookWorker(): void {
+  queue.process("webhook-delivery", async (job) => {
+    const { deliveryId } = job.payload as { deliveryId: string };
+    await deliverNow(deliveryId);
+  });
+}

package/src/services/workflows/engine.ts

@@ -0,0 +1,125 @@
+import { eq, and } from "drizzle-orm";
+import { db } from "../../db/index.js";
+import { workflows, workflowRuns, type Workflow, type WorkflowRun } from "../../db/schema.js";
+import { findUserById } from "../users.js";
+import { subscribe } from "../events/bus.js";
+import type { KeystoneEvent } from "../events/types.js";
+import { queue } from "../queue/index.js";
+import { executeStep, type WorkflowStep } from "./steps.js";
+
+export interface WorkflowDefinition {
+  steps: WorkflowStep[];
+  [key: string]: unknown;
+}
+
+let loaded = false;
+
+export async function loadWorkflows(): Promise<void> {
+  if (loaded) return;
+  loaded = true;
+
+  const activeWorkflows = await db
+    .select()
+    .from(workflows)
+    .where(and(eq(workflows.isActive, true)));
+
+  for (const workflow of activeWorkflows) {
+    subscribe(workflow.trigger, async (event) => {
+      await triggerWorkflowRun(workflow, event);
+    });
+  }
+}
+
+export async function registerWorkflow(input: {
+  orgId?: string;
+  name: string;
+  trigger: string;
+  definition: WorkflowDefinition;
+}): Promise<Workflow> {
+  const [workflow] = await db
+    .insert(workflows)
+    .values({
+      orgId: input.orgId ?? null,
+      name: input.name,
+      trigger: input.trigger,
+      definition: input.definition,
+    })
+    .returning();
+  subscribe(workflow.trigger, async (event) => {
+    await triggerWorkflowRun(workflow, event);
+  });
+  return workflow;
+}
+
+export async function triggerWorkflowRun(workflow: Workflow, event: KeystoneEvent): Promise<WorkflowRun> {
+  const [run] = await db
+    .insert(workflowRuns)
+    .values({
+      workflowId: workflow.id,
+      triggerEvent: event.type,
+      payload: event.payload as Record<string, unknown>,
+      status: "running",
+      startedAt: new Date(),
+    })
+    .returning();
+
+  // Dispatch to the background queue so the HTTP response is not blocked.
+  await queue.enqueue({
+    type: "workflow_run",
+    payload: { runId: run.id, workflowId: workflow.id },
+  });
+
+  return run;
+}
+
+export async function executeRunById(runId: string, workflowId: string): Promise<void> {
+  const [run] = await db.select().from(workflowRuns).where(eq(workflowRuns.id, runId)).limit(1);
+  const [workflow] = await db.select().from(workflows).where(eq(workflows.id, workflowId)).limit(1);
+  if (!run || !workflow) {
+    console.error(`[workflow-engine] run or workflow not found: ${runId}, ${workflowId}`);
+    return;
+  }
+  await executeRun(run, workflow);
+}
+
+async function executeRun(run: WorkflowRun, workflow: Workflow): Promise<void> {
+  const definition = (workflow.definition ?? { steps: [] }) as WorkflowDefinition;
+  const payload = (run.payload ?? {}) as Record<string, unknown>;
+  const userId = payload.userId as string | undefined;
+  const user = userId ? await findUserById(userId) : undefined;
+  const outputs: Record<string, string> = {};
+  const log: Array<{ step: string; status: string; output?: Record<string, string>; error?: string }> = [];
+
+  for (const step of definition.steps ?? []) {
+    const result = await executeStep(step, { payload, outputs, user });
+    if (result.output) {
+      Object.assign(outputs, result.output);
+      if (step.name) outputs[step.name] = Object.values(result.output)[0] ?? "";
+    }
+    log.push({
+      step: step.type,
+      status: result.error ? "failed" : "ok",
+      output: result.output,
+      error: result.error,
+    });
+    if (result.error) {
+      await db
+        .update(workflowRuns)
+        .set({ status: "failed", finishedAt: new Date(), log })
+        .where(eq(workflowRuns.id, run.id));
+      return;
+    }
+  }
+
+  await db
+    .update(workflowRuns)
+    .set({ status: "completed", finishedAt: new Date(), log })
+    .where(eq(workflowRuns.id, run.id));
+}
+
+export async function listWorkflowRuns(workflowId?: string): Promise<WorkflowRun[]> {
+  if (workflowId) {
+    return db.select().from(workflowRuns).where(eq(workflowRuns.workflowId, workflowId));
+  }
+  return db.select().from(workflowRuns);
+}

package/src/services/workflows/steps.ts

@@ -0,0 +1,129 @@
+import { createOrganization, addOrgMembership, findOrganizationBySlug } from "../organizations.js";
+import { findApplicationByClientId } from "../applications.js";
+import { updateUser } from "../users.js";
+import { queue } from "../queue/index.js";
+import { getPluginWorkflowStep } from "../plugins/registry.js";
+import type { EmailMessage } from "../email.js";
+import type { User } from "../../db/schema.js";
+
+export interface StepContext {
+  payload: Record<string, unknown>;
+  outputs: Record<string, string>;
+  user?: User;
+}
+
+export interface WorkflowStep {
+  type: string;
+  name?: string;
+  [key: string]: unknown;
+}
+
+export interface StepResult {
+  output?: Record<string, string>;
+  error?: string;
+}
+
+function interpolate(template: string, context: StepContext): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = context.payload[key] ?? context.outputs[key] ?? "";
+    return String(value);
+  });
+}
+
+export async function executeStep(step: WorkflowStep, context: StepContext): Promise<StepResult> {
+  const log = (msg: string) => console.log(`[workflow] step ${step.type}: ${msg}`);
+
+  switch (step.type) {
+    case "assign_role": {
+      const role = String(step.role || "user");
+      if (context.user) {
+        await updateUser(context.user.id, { role });
+        log(`assigned role ${role} to ${context.user.id}`);
+      }
+      return {};
+    }
+
+    case "create_organization": {
+      const nameTemplate = String(step.orgName || "{{username}}-personal");
+      const name = interpolate(nameTemplate, context);
+      const slugTemplate = String(step.slug || "{{username}}-personal");
+      const slug = interpolate(slugTemplate, context);
+      const existing = await findOrganizationBySlug(slug);
+      if (existing) {
+        return { output: { [String(step.outputKey || "orgId")]: existing.id } };
+      }
+      const org = await createOrganization({ name, slug });
+      log(`created organization ${org.id}`);
+      return { output: { [String(step.outputKey || "orgId")]: org.id } };
+    }
+
+    case "add_membership": {
+      const userId = context.user?.id;
+      if (!userId) return { error: "missing user" };
+      const orgRef = String(step.orgRef || "personalOrgId");
+      const orgId = context.outputs[orgRef];
+      if (!orgId) return { error: `missing output ${orgRef}` };
+      const role = String(step.role || "member");
+      await addOrgMembership({ orgId, userId, role: role as import("../organizations.js").OrgRole });
+      log(`added membership ${userId} -> ${orgId} as ${role}`);
+      return {};
+    }
+
+    case "add_app_membership": {
+      const userId = context.user?.id;
+      if (!userId) return { error: "missing user" };
+      const clientId = String(step.clientId || context.payload.client_id || "");
+      if (!clientId) return { error: "missing client_id" };
+      const app = await findApplicationByClientId(clientId);
+      if (!app) return { error: "application not found" };
+      await addOrgMembership({ orgId: app.orgId, userId, role: "member" });
+      log(`added app membership ${userId} -> ${app.orgId}`);
+      return {};
+    }
+
+    case "send_email": {
+      const to = String(step.to || context.user?.email || "");
+      if (!to) return { error: "missing email" };
+      const message: EmailMessage = {
+        to,
+        subject: String(step.subject || "Hilbras notification"),
+        text: String(step.text || ""),
+      };
+      await queue.enqueue({ type: "email", payload: { message } });
+      log(`enqueued email to ${to}`);
+      return {};
+    }
+
+    case "send_welcome_email": {
+      const to = context.user?.email;
+      if (!to || !context.user) return { error: "missing user email" };
+      const message: EmailMessage = {
+        to,
+        subject: "Welcome to Hilbras",
+        text: `Hi ${context.user.name || context.user.username},\n\nWelcome to Hilbras! Your account has been created.`,
+      };
+      await queue.enqueue({ type: "email", payload: { message } });
+      log(`enqueued welcome email to ${to}`);
+      return {};
+    }
+
+    case "webhook": {
+      const url = String(step.url || "");
+      if (!url) return { error: "missing webhook url" };
+      await queue.enqueue({
+        type: "webhook",
+        payload: { url, method: String(step.method || "POST"), body: context.payload },
+      });
+      log(`enqueued webhook ${url}`);
+      return {};
+    }
+
+    default: {
+      const pluginExecutor = getPluginWorkflowStep(step.type);
+      if (pluginExecutor) {
+        return pluginExecutor(step, context);
+      }
+      return { error: `unknown step type ${step.type}` };
+    }
+  }
+}