@hilbras/keystone 1.1.0

package/src/lib/result.ts

@@ -0,0 +1,44 @@
+export interface KeystoneError {
+  code: string;
+  message: string;
+  statusCode?: number;
+  details?: Record<string, unknown>;
+}
+
+export type Result<T> =
+  | { success: true; data: T; error?: undefined }
+  | { success: false; data?: undefined; error: KeystoneError };
+
+export function ok<T>(data: T): Result<T> {
+  return { success: true, data };
+}
+
+export function err<T>(error: KeystoneError): Result<T> {
+  return { success: false, error };
+}
+
+export function errFromMessage<T>(
+  code: string,
+  message: string,
+  statusCode?: number,
+  details?: Record<string, unknown>
+): Result<T> {
+  return err({ code, message, statusCode, details });
+}
+
+export function mapResult<T, U>(result: Result<T>, fn: (data: T) => U): Result<U> {
+  if (result.success) {
+    return ok(fn(result.data));
+  }
+  return err(result.error);
+}
+
+export async function flatMapResult<T, U>(
+  result: Result<T>,
+  fn: (data: T) => Promise<Result<U>>
+): Promise<Result<U>> {
+  if (result.success) {
+    return fn(result.data);
+  }
+  return err(result.error);
+}

package/src/lib/webhookSignature.ts

@@ -0,0 +1,41 @@
+import crypto from "node:crypto";
+
+/**
+ * Sign a webhook payload using HMAC-SHA256.
+ * Returns a signature string in the format "t=<timestamp>,v1=<hex>".
+ */
+export function signWebhookPayload(secret: string, payload: unknown): string {
+  const timestamp = Math.floor(Date.now() / 1000);
+  const body = JSON.stringify(payload);
+  const signedPayload = `${timestamp}.${body}`;
+  const signature = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
+  return `t=${timestamp},v1=${signature}`;
+}
+
+/**
+ * Verify a webhook signature.
+ * Returns true if the signature matches the payload and timestamp is within tolerance.
+ */
+export function verifyWebhookPayload(
+  secret: string,
+  signatureHeader: string,
+  payload: unknown,
+  toleranceSeconds = 300
+): boolean {
+  const parts = signatureHeader.split(",").reduce<Record<string, string>>((acc, part) => {
+    const [key, value] = part.split("=");
+    if (key && value) acc[key.trim()] = value.trim();
+    return acc;
+  }, {});
+
+  const timestamp = Number(parts.t);
+  const signature = parts.v1;
+  if (!timestamp || !signature) return false;
+
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
+
+  const body = JSON.stringify(payload);
+  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+  return crypto.timingSafeEqual(Buffer.from(signature, "hex"), Buffer.from(expected, "hex"));
+}

package/src/plugins/appContext.ts

@@ -0,0 +1,76 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import { eq, and, arrayContains } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { applications, organizations, orgMemberships } from "../db/schema.js";
+
+export default fp(async function appContextPlugin(app: FastifyInstance) {
+  app.addHook("onRequest", async (request: FastifyRequest) => {
+    // Ensure every request has a fresh state object.
+    request.state = {};
+
+    const clientId = extractClientId(request);
+    const origin = request.headers.origin;
+
+    const appRecord = clientId
+      ? await findApplicationByClientId(clientId)
+      : origin
+        ? await findApplicationByOrigin(origin)
+        : undefined;
+
+    if (!appRecord) return;
+
+    request.state.app = appRecord;
+    request.state.org = appRecord.organization;
+
+    if (request.user) {
+      const [membership] = await db
+        .select()
+        .from(orgMemberships)
+        .where(
+          and(
+            eq(orgMemberships.orgId, appRecord.organization.id),
+            eq(orgMemberships.userId, request.user.id)
+          )
+        )
+        .limit(1);
+      if (membership) {
+        request.state.membership = membership;
+      }
+    }
+  });
+});
+
+function extractClientId(request: FastifyRequest): string | undefined {
+  const header = request.headers["x-app-client-id"];
+  if (typeof header === "string" && header) return header;
+
+  const query = (request.query as Record<string, string | undefined>).client_id;
+  if (query) return query;
+
+  return undefined;
+}
+
+async function findApplicationByClientId(clientId: string) {
+  const [row] = await db
+    .select()
+    .from(applications)
+    .where(and(eq(applications.clientId, clientId), eq(applications.isActive, true)))
+    .innerJoin(organizations, eq(applications.orgId, organizations.id))
+    .limit(1);
+
+  if (!row) return undefined;
+  return { ...row.applications, organization: row.organizations };
+}
+
+async function findApplicationByOrigin(origin: string) {
+  const [row] = await db
+    .select()
+    .from(applications)
+    .where(and(arrayContains(applications.allowedOrigins, [origin]), eq(applications.isActive, true)))
+    .innerJoin(organizations, eq(applications.orgId, organizations.id))
+    .limit(1);
+
+  if (!row) return undefined;
+  return { ...row.applications, organization: row.organizations };
+}

package/src/plugins/audit.ts

@@ -0,0 +1,42 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import { audit, type AuditEvent } from "../services/audit.js";
+import { emit } from "../services/events/bus.js";
+import type { EventPayload } from "../services/events/types.js";
+
+declare module "fastify" {
+  interface FastifyRequest {
+    audit: (event: AuditEvent, metadata?: Record<string, unknown>) => Promise<void>;
+    emitEvent: (event: string, metadata?: Record<string, unknown>) => Promise<void>;
+  }
+}
+
+function buildPayload(request: FastifyRequest, metadata?: Record<string, unknown>): EventPayload {
+  return {
+    userId: request.user?.id,
+    orgId: request.state?.org?.id,
+    appId: request.state?.app?.id,
+    requestId: request.id,
+    ip: request.ip,
+    userAgent: request.headers["user-agent"],
+    metadata,
+  };
+}
+
+export default fp(async function auditPlugin(app: FastifyInstance) {
+  app.decorateRequest("audit", async function (
+    this: FastifyRequest,
+    event: AuditEvent,
+    metadata?: Record<string, unknown>
+  ) {
+    await audit({ ...buildPayload(this, metadata), event });
+  });
+
+  app.decorateRequest("emitEvent", async function (
+    this: FastifyRequest,
+    event: string,
+    metadata?: Record<string, unknown>
+  ) {
+    await emit({ type: event, payload: buildPayload(this, metadata) });
+  });
+});

package/src/plugins/auth.ts

@@ -0,0 +1,230 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { eq, and, gt, isNull } from "drizzle-orm";
+import { config } from "../config.js";
+import { db } from "../db/index.js";
+import { apiKeys, users, serviceAccounts, type User } from "../db/schema.js";
+import { verifyAccessToken, hashApiKey } from "../services/tokens.js";
+import type { TokenClaims } from "../types.js";
+
+declare module "fastify" {
+  interface FastifyInstance {
+    authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    authenticateOrApiKey: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    requireScopes: (...scopes: string[]) => (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+
+  interface FastifyRequest {
+    serviceAccount?: typeof serviceAccounts.$inferSelect;
+    apiKeyScopes?: string[];
+  }
+}
+
+const DEFAULT_ACCESS_COOKIE = config.COOKIE_NAME;
+const DEFAULT_REFRESH_COOKIE = `${config.COOKIE_NAME}-refresh`;
+
+export function accessCookieName(clientId?: string): string {
+  return clientId ? `app-${clientId}-session` : DEFAULT_ACCESS_COOKIE;
+}
+
+export function refreshCookieName(clientId?: string): string {
+  return clientId ? `app-${clientId}-session-refresh` : DEFAULT_REFRESH_COOKIE;
+}
+
+function cookieOptions(): {
+  path: string;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: "strict" | "lax" | "none";
+  domain: string | undefined;
+} {
+  const sameSite = (config.COOKIE_SAME_SITE as "strict" | "lax" | "none") || (config.NODE_ENV === "production" ? "strict" : "lax");
+  return {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite,
+    domain: config.COOKIE_DOMAIN || undefined,
+  };
+}
+
+export function setSessionCookies(
+  reply: FastifyReply,
+  accessToken: string,
+  refreshToken: string,
+  clientId?: string
+): void {
+  const opts = cookieOptions();
+
+  reply.setCookie(accessCookieName(clientId), accessToken, {
+    ...opts,
+    maxAge: config.ACCESS_TOKEN_TTL_SECONDS,
+  });
+  reply.setCookie(refreshCookieName(clientId), refreshToken, {
+    ...opts,
+    maxAge: config.REFRESH_TOKEN_TTL_SECONDS,
+  });
+}
+
+export function clearSessionCookies(reply: FastifyReply, clientId?: string): void {
+  const opts = cookieOptions();
+  reply.clearCookie(accessCookieName(clientId), opts);
+  reply.clearCookie(refreshCookieName(clientId), opts);
+}
+
+export function getRefreshToken(request: FastifyRequest, clientId?: string): string | undefined {
+  return request.cookies[refreshCookieName(clientId)];
+}
+
+async function resolveUserFromClaims(claims: TokenClaims) {
+  const [user] = await db.select().from(users).where(eq(users.id, claims.sub)).limit(1);
+  return user;
+}
+
+async function resolveApiKeyRecord(key: string) {
+  const hash = hashApiKey(key);
+  const [keyRecord] = await db
+    .select()
+    .from(apiKeys)
+    .where(and(eq(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt)))
+    .limit(1);
+  return keyRecord;
+}
+
+async function resolveUserFromApiKey(key: string): Promise<{ user: User; scopes: string[] } | undefined> {
+  const keyRecord = await resolveApiKeyRecord(key);
+  if (!keyRecord) return undefined;
+  if (keyRecord.expiresAt && keyRecord.expiresAt < new Date()) return undefined;
+
+  await db.update(apiKeys).set({ lastUsedAt: new Date() }).where(eq(apiKeys.id, keyRecord.id));
+
+  if (keyRecord.userId) {
+    const [user] = await db.select().from(users).where(eq(users.id, keyRecord.userId)).limit(1);
+    if (!user) return undefined;
+    return { user, scopes: keyRecord.scopes ?? [] };
+  }
+
+  return undefined;
+}
+
+function extractAccessToken(request: FastifyRequest): string | undefined {
+  // Prefer the app-specific cookie if an app context is present.
+  const appClientId = request.state?.app?.clientId;
+  const appCookie = appClientId ? request.cookies[accessCookieName(appClientId)] : undefined;
+  if (appCookie) return appCookie;
+
+  const defaultCookie = request.cookies[DEFAULT_ACCESS_COOKIE];
+  if (defaultCookie) return defaultCookie;
+
+  const header = request.headers.authorization;
+  if (header?.startsWith("Bearer ")) return header.slice(7);
+  return undefined;
+}
+
+export default fp(async function authPlugin(app: FastifyInstance) {
+  app.decorate("authenticate", async function authenticate(request, reply) {
+    const token = extractAccessToken(request);
+    if (!token) {
+      return reply.status(401).send({ error: "Unauthorized" });
+    }
+    try {
+      const claims = await verifyAccessToken(token);
+      const user = await resolveUserFromClaims(claims);
+      if (!user) {
+        return reply.status(401).send({ error: "User not found" });
+      }
+      request.user = user;
+    } catch {
+      return reply.status(401).send({ error: "Invalid token" });
+    }
+  });
+
+  app.decorate("authenticateOrApiKey", async function authenticateOrApiKey(request, reply) {
+    const token = extractAccessToken(request);
+    if (!token) {
+      return reply.status(401).send({ error: "Unauthorized" });
+    }
+
+    try {
+      const claims = await verifyAccessToken(token);
+      const user = await resolveUserFromClaims(claims);
+      if (!user) {
+        return reply.status(401).send({ error: "User not found" });
+      }
+      request.user = user;
+      return;
+    } catch {
+      // Not a valid access token — try API key.
+    }
+
+    const apiKeyUser = await resolveUserFromApiKey(token);
+    if (apiKeyUser) {
+      request.user = apiKeyUser.user;
+      request.apiKeyScopes = apiKeyUser.scopes;
+      return;
+    }
+
+    const serviceAccount = await resolveServiceAccountFromApiKey(token);
+    if (serviceAccount) {
+      request.serviceAccount = serviceAccount;
+      request.apiKeyScopes = ["api:read", "api:write", "service_account"];
+      // Synthesize a user so existing routes that expect request.user keep working.
+      request.user = {
+        id: `sa:${serviceAccount.id}`,
+        email: `service-account@${serviceAccount.id}.internal`,
+        username: `sa-${serviceAccount.id.slice(0, 8)}`,
+        name: serviceAccount.name,
+        avatarUrl: null,
+        emailVerified: true,
+        plan: "enterprise",
+        role: "service_account",
+        provider: "api_key",
+        zitadelUserId: null,
+        defaultOrgId: serviceAccount.orgId,
+        phoneNumber: null,
+        phoneVerified: false,
+        totpSecret: null,
+        totpEnabled: false,
+        totpVerifiedAt: null,
+        createdAt: serviceAccount.createdAt,
+        updatedAt: serviceAccount.updatedAt,
+      } as User;
+      return;
+    }
+
+    return reply.status(401).send({ error: "Invalid token or API key" });
+  });
+
+  app.decorate("requireScopes", function requireScopes(...required: string[]) {
+    return async function scopeCheck(request: FastifyRequest, reply: FastifyReply) {
+      // Session-based authentication has full scope access.
+      if (!request.apiKeyScopes) return;
+      const scopes = request.apiKeyScopes;
+      const hasAll = required.every((scope) => scopes.includes(scope) || scopes.includes("service_account"));
+      if (!hasAll) {
+        return reply.status(403).send({ error: "Insufficient API key scope", required });
+      }
+    };
+  });
+});
+
+async function resolveServiceAccountFromApiKey(key: string) {
+  const hash = hashApiKey(key);
+  const [keyRecord] = await db
+    .select()
+    .from(apiKeys)
+    .where(and(eq(apiKeys.keyHash, hash), isNull(apiKeys.revokedAt)))
+    .limit(1);
+
+  if (!keyRecord) return undefined;
+  if (keyRecord.expiresAt && keyRecord.expiresAt < new Date()) return undefined;
+  if (!keyRecord.serviceAccountId) return undefined;
+
+  await db.update(apiKeys).set({ lastUsedAt: new Date() }).where(eq(apiKeys.id, keyRecord.id));
+  const [account] = await db
+    .select()
+    .from(serviceAccounts)
+    .where(and(eq(serviceAccounts.id, keyRecord.serviceAccountId), eq(serviceAccounts.isActive, true)))
+    .limit(1);
+  return account;
+}

package/src/plugins/metrics.ts

@@ -0,0 +1,41 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { register, Counter, Histogram } from "prom-client";
+
+export const httpRequestsTotal = new Counter({
+  name: "keystone_http_requests_total",
+  help: "Total HTTP requests",
+  labelNames: ["method", "route", "status_code"],
+});
+
+export const httpRequestDurationSeconds = new Histogram({
+  name: "keystone_http_request_duration_seconds",
+  help: "HTTP request duration in seconds",
+  labelNames: ["method", "route", "status_code"],
+  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+});
+
+export const failedLoginsTotal = new Counter({
+  name: "keystone_failed_logins_total",
+  help: "Total failed login attempts",
+  labelNames: ["reason"],
+});
+
+export default fp(async function metricsPlugin(app: FastifyInstance) {
+  app.addHook("onResponse", async (request: FastifyRequest, reply: FastifyReply) => {
+    const route = (request as unknown as { routeOptions?: { url?: string } }).routeOptions?.url || request.url;
+    const labels = {
+      method: request.method,
+      route,
+      status_code: String(reply.statusCode),
+    };
+    httpRequestsTotal.inc(labels);
+    const elapsedMs = (reply as unknown as { elapsedTime?: number }).elapsedTime ?? 0;
+    httpRequestDurationSeconds.observe(labels, elapsedMs / 1000);
+  });
+
+  app.get("/metrics", async (_request: FastifyRequest, reply: FastifyReply) => {
+    reply.header("Content-Type", register.contentType);
+    return register.metrics();
+  });
+});

package/src/plugins/mtls.ts

@@ -0,0 +1,94 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { eq } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { serviceAccounts } from "../db/schema.js";
+
+/**
+ * mTLS authentication plugin.
+ *
+ * In production, terminate TLS at a reverse proxy (nginx, envoy, AWS ALB, etc.)
+ * that validates the client certificate and forwards the certificate fingerprint
+ * or subject in a trusted header. This plugin reads that header and maps
+ * certificates to service accounts.
+ *
+ * Headers read:
+ *   - x-client-cert-fingerprint: SHA-256 fingerprint of the client certificate
+ *   - x-forwarded-client-cert: PEM-encoded client certificate or DN subject
+ *   - x-service-account-id: Optional explicit service account ID (for non-mTLS fallback)
+ */
+
+const MTLS_HEADER = "x-forwarded-client-cert";
+const MTLS_FINGERPRINT_HEADER = "x-client-cert-fingerprint";
+const SERVICE_ACCOUNT_ID_HEADER = "x-service-account-id";
+
+declare module "fastify" {
+  interface FastifyInstance {
+    requireMTLS: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+}
+
+export function extractClientCert(request: FastifyRequest): { fingerprint?: string; subject?: string } {
+  const fingerprint = request.headers[MTLS_FINGERPRINT_HEADER];
+  const cert = request.headers[MTLS_HEADER];
+  return {
+    fingerprint: typeof fingerprint === "string" ? fingerprint : undefined,
+    subject: typeof cert === "string" ? cert : undefined,
+  };
+}
+
+async function resolveServiceAccount(request: FastifyRequest): Promise<typeof serviceAccounts.$inferSelect | undefined> {
+  const explicitId = request.headers[SERVICE_ACCOUNT_ID_HEADER];
+  if (typeof explicitId === "string" && explicitId) {
+    const [sa] = await db
+      .select()
+      .from(serviceAccounts)
+      .where(eq(serviceAccounts.id, explicitId))
+      .limit(1);
+    if (sa?.isActive) {
+      return sa;
+    }
+  }
+
+  const { fingerprint, subject } = extractClientCert(request);
+  if (!fingerprint && !subject) return undefined;
+
+  // Look up service accounts by name matching the fingerprint or subject.
+  // In a production system, you would store the certificate fingerprint in
+  // the service_accounts table and query by it directly.
+  const [sa] = await db
+    .select()
+    .from(serviceAccounts)
+    .where(eq(serviceAccounts.name, fingerprint || subject || ""))
+    .limit(1);
+
+  if (sa?.isActive) {
+    return sa;
+  }
+
+  return undefined;
+}
+
+export function requireMTLS() {
+  return async function (request: FastifyRequest, reply: FastifyReply) {
+    const { fingerprint, subject } = extractClientCert(request);
+    const explicitId = request.headers[SERVICE_ACCOUNT_ID_HEADER];
+
+    if (!fingerprint && !subject && !explicitId) {
+      return reply.status(401).send({ error: "Client certificate required" });
+    }
+
+    const serviceAccount = await resolveServiceAccount(request);
+    if (!serviceAccount) {
+      request.log.warn({ fingerprint, subject }, "mTLS: no matching service account found");
+      return reply.status(403).send({ error: "Client certificate not mapped to a service account" });
+    }
+
+    request.serviceAccount = serviceAccount;
+    request.log.debug({ serviceAccountId: serviceAccount.id }, "mTLS: service account authenticated");
+  };
+}
+
+export default fp(async function mtlsPlugin(app: FastifyInstance) {
+  app.decorate("requireMTLS", requireMTLS());
+});

package/src/plugins/permissions.ts

@@ -0,0 +1,29 @@
+import fp from "fastify-plugin";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { requirePermission, hasPermission, type PermissionInput } from "../services/permissions.js";
+
+declare module "fastify" {
+  interface FastifyInstance {
+    requirePermission: (resource: string, action: string) => (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  }
+}
+
+export default fp(async function permissionsPlugin(app: FastifyInstance) {
+  app.decorate(
+    "requirePermission",
+    function (resource: string, action: string) {
+      return async function (request: FastifyRequest, reply: FastifyReply) {
+        const membership = request.state?.membership;
+        if (!membership) {
+          return reply.status(403).send({ error: "Organization membership required" });
+        }
+        try {
+          await requirePermission(membership.role, resource, action);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : "Forbidden";
+          return reply.status(403).send({ error: message });
+        }
+      };
+    }
+  );
+});