@hilbras/keystone 1.6.0 → 2.5.0

package/src/lib/result.ts

@@ -1,44 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,230 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,94 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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 });
-        }
-      };
-    }
-  );
-});