@hilbras/keystone 1.1.0

package/src/routes/auth.ts

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import type { FastifyInstance } from "fastify";
+import { getSdk } from "../sdk/index.js";
+import {
+  setSessionCookies,
+  clearSessionCookies,
+  getRefreshToken,
+} from "../plugins/auth.js";
+import { rateLimit } from "../plugins/rateLimit.js";
+import { checkImpossibleTravel } from "../services/anomalyDetection.js";
+import { sendSuspiciousLoginAlert } from "../services/email.js";
+import { checkIpAllowed } from "../services/ipControls.js";
+import { toPublicUser } from "../types.js";
+import { verifyTOTP } from "../services/totp.js";
+import { sendResultError } from "./helpers.js";
+
+/**
+ * Fire-and-forget impossible-travel check after a successful login.
+ * Emits a suspicious-login email when the user's previous login came from a
+ * different IP within the anomaly window.
+ */
+function detectImpossibleTravel(user: { id: string; email: string }, ip?: string, userAgent?: string): void {
+  checkImpossibleTravel(user.id, ip)
+    .then(async (suspicious) => {
+      if (!suspicious) return;
+      await sendSuspiciousLoginAlert({
+        email: user.email,
+        ipAddress: ip,
+        userAgent,
+        reason: "Sign-in from a new location within minutes of the previous one",
+      });
+    })
+    .catch((err: unknown) => {
+      console.error("[anomaly] impossible-travel check failed:", err);
+    });
+}
+
+const RegisterSchema = z.object({
+  username: z.string().min(3).max(32).regex(/^[a-zA-Z0-9_-]+$/),
+  email: z.string().email().max(255),
+  password: z.string().min(8).max(128),
+  name: z.string().max(255).optional(),
+  client_id: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+const LoginSchema = z.object({
+  email: z.string().email().max(255),
+  password: z.string().min(1).max(128),
+  client_id: z.string().optional(),
+  totp_code: z.string().min(6).max(8).optional(),
+});
+
+const RefreshSchema = z.object({
+  client_id: z.string().optional(),
+});
+
+export default async function authRoutes(app: FastifyInstance) {
+  const sdk = getSdk();
+
+  app.post(
+    "/register",
+    {
+      preHandler: [
+        rateLimit({
+          keyPrefix: "register",
+          maxAttempts: 5,
+          windowSeconds: 900,
+        }),
+      ],
+    },
+    async (request, reply) => {
+      const body = RegisterSchema.parse(request.body);
+
+      const ipCheck = await checkIpAllowed(body.client_id, request.ip);
+      if (!ipCheck.allowed) {
+        return reply.status(403).send({ error: ipCheck.reason, code: "IP_NOT_ALLOWED" });
+      }
+
+      const result = await sdk.authentication.register({
+        username: body.username,
+        email: body.email,
+        password: body.password,
+        name: body.name,
+        clientId: body.client_id,
+        metadata: body.metadata,
+      });
+
+      if (!result.success) return sendResultError(reply, result);
+
+      await request.audit("user_registered", { userId: result.data.user.id, email: result.data.user.email });
+      setSessionCookies(reply, result.data.accessToken, result.data.refreshToken, body.client_id);
+      return { user: toPublicUser(result.data.user) };
+    }
+  );
+
+  app.post(
+    "/login",
+    {
+      preHandler: [
+        rateLimit({
+          keyPrefix: "login",
+          maxAttempts: 5,
+          windowSeconds: 900,
+        }),
+      ],
+    },
+    async (request, reply) => {
+      const body = LoginSchema.parse(request.body);
+
+      const ipCheck = await checkIpAllowed(body.client_id, request.ip);
+      if (!ipCheck.allowed) {
+        return reply.status(403).send({ error: ipCheck.reason, code: "IP_NOT_ALLOWED" });
+      }
+
+      const result = await sdk.authentication.login({
+        email: body.email,
+        password: body.password,
+        clientId: body.client_id,
+      });
+
+      if (!result.success) return sendResultError(reply, result);
+
+      if (body.totp_code) {
+        const validTotp = await verifyTOTP(result.data.user.id, body.totp_code);
+        if (!validTotp) {
+          return reply.status(401).send({ error: "Invalid two-factor code." });
+        }
+      }
+
+      await request.audit("user_login", { userId: result.data.user.id });
+      detectImpossibleTravel(result.data.user, request.ip, request.headers["user-agent"]);
+      setSessionCookies(reply, result.data.accessToken, result.data.refreshToken, body.client_id);
+      return { user: toPublicUser(result.data.user) };
+    }
+  );
+
+  app.post(
+    "/token-login",
+    {
+      preHandler: [
+        rateLimit({
+          keyPrefix: "login",
+          maxAttempts: 5,
+          windowSeconds: 900,
+        }),
+      ],
+    },
+    async (request, reply) => {
+      const body = LoginSchema.parse(request.body);
+
+      const ipCheck = await checkIpAllowed(body.client_id, request.ip);
+      if (!ipCheck.allowed) {
+        return reply.status(403).send({ error: ipCheck.reason, code: "IP_NOT_ALLOWED" });
+      }
+
+      const result = await sdk.authentication.login({
+        email: body.email,
+        password: body.password,
+        clientId: body.client_id,
+      });
+
+      if (!result.success) return sendResultError(reply, result);
+
+      if (body.totp_code) {
+        const validTotp = await verifyTOTP(result.data.user.id, body.totp_code);
+        if (!validTotp) {
+          return reply.status(401).send({ error: "Invalid two-factor code." });
+        }
+      }
+
+      await request.audit("user_token_login", { userId: result.data.user.id });
+      detectImpossibleTravel(result.data.user, request.ip, request.headers["user-agent"]);
+      return {
+        accessToken: result.data.accessToken,
+        user: toPublicUser(result.data.user),
+      };
+    }
+  );
+
+  app.get("/me", { preHandler: [app.authenticate] }, async (request) => {
+    return { user: request.user ? toPublicUser(request.user) : null };
+  });
+
+  app.post("/refresh", async (request, reply) => {
+    const body = RefreshSchema.parse(request.body ?? {});
+    const clientId = body.client_id;
+
+    const refreshToken = getRefreshToken(request, clientId) || getRefreshToken(request);
+    if (!refreshToken) {
+      return reply.status(401).send({ error: "Unauthorized" });
+    }
+
+    const result = await sdk.authentication.refresh(refreshToken, clientId);
+    if (!result.success) return sendResultError(reply, result);
+
+    await request.audit("token_refresh", {});
+    setSessionCookies(reply, result.data.accessToken, result.data.refreshToken, clientId);
+    return { success: true };
+  });
+
+  app.post("/logout", async (request, reply) => {
+    const appClientId = request.state?.app?.clientId;
+    const refreshToken =
+      getRefreshToken(request, appClientId) || getRefreshToken(request);
+    const result = await sdk.authentication.logout(refreshToken);
+    if (!result.success) return sendResultError(reply, result);
+
+    await request.audit("user_logout", { userId: request.user?.id });
+    clearSessionCookies(reply, appClientId);
+    clearSessionCookies(reply);
+    return { success: true };
+  });
+}

package/src/routes/authz.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { getSdk } from "../sdk/index.js";
+
+const CheckSchema = z.object({
+  resource: z.string().min(1),
+  action: z.string().min(1),
+});
+
+export default async function authzRoutes(app: FastifyInstance) {
+  const sdk = getSdk();
+
+  app.post(
+    "/authz/check",
+    { preHandler: [app.authenticate] },
+    async (request: FastifyRequest, reply: FastifyReply) => {
+      const body = CheckSchema.parse(request.body);
+      const membership = request.state?.membership;
+
+      if (!membership) {
+        return reply.status(403).send({
+          allowed: false,
+          reason: "No organization context",
+        });
+      }
+
+      const allowed = await sdk.authorization.hasPermission(membership.role, body.resource, body.action);
+      await request.audit("authz_check", {
+        resource: body.resource,
+        action: body.action,
+        role: membership.role,
+        allowed,
+      });
+
+      return { allowed };
+    }
+  );
+}

package/src/routes/config.ts

@@ -0,0 +1,67 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { z } from "zod";
+import { createConfigWriter } from "../services/setup/configWriter.js";
+import { queue } from "../services/queue/index.js";
+
+const UpdateConfigSchema = z.object({
+  values: z.record(z.string()),
+});
+
+async function requireOwner(request: FastifyRequest, reply: FastifyReply) {
+  await request.server.authenticate(request, reply);
+  if (reply.sent) return;
+  if (request.user!.role !== "owner") {
+    return reply.status(403).send({ error: "Forbidden: owner access required" });
+  }
+}
+
+export default async function configRoutes(app: FastifyInstance) {
+  // Read current configuration values from the configured store (.env by default).
+  app.get("/", { preHandler: [requireOwner] }, async (_request: FastifyRequest, reply: FastifyReply) => {
+    try {
+      const writer = createConfigWriter();
+      const values = await writer.read();
+      return reply.send({ values });
+    } catch (err) {
+      app.log.error({ err }, "Failed to read configuration");
+      return reply.status(500).send({ error: "Failed to read configuration" });
+    }
+  });
+
+  // Update configuration values. A restart is required for most changes to take effect.
+  app.put("/", { preHandler: [requireOwner] }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const parsed = UpdateConfigSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ error: "Invalid input", details: parsed.error.issues });
+    }
+
+    try {
+      const writer = createConfigWriter();
+      const backup = await writer.backup();
+      if (!backup.success) {
+        return reply.status(500).send({ error: backup.error.message, code: backup.error.code });
+      }
+
+      const writeResult = await writer.write(parsed.data.values);
+      if (!writeResult.success) {
+        return reply.status(500).send({ error: writeResult.error.message, code: writeResult.error.code });
+      }
+
+      return reply.send({ ok: true, backupPath: backup.data || undefined });
+    } catch (err) {
+      request.log.error({ err }, "Failed to update configuration");
+      return reply.status(500).send({ error: "Failed to update configuration" });
+    }
+  });
+
+  // Restart the server so new configuration is loaded.
+  app.post("/restart", { preHandler: [requireOwner] }, async (_request: FastifyRequest, reply: FastifyReply) => {
+    reply.status(202).send({ ok: true, message: "Server is restarting" });
+    try {
+      await queue.close?.();
+    } catch {
+      // ignore
+    }
+    setTimeout(() => process.exit(0), 500);
+  });
+}

package/src/routes/emailVerification.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { findUserByEmail } from "../services/users.js";
+import {
+  sendVerificationEmail,
+  consumeVerificationToken,
+} from "../services/emailVerification.js";
+import { rateLimit } from "../plugins/rateLimit.js";
+
+const SendSchema = z.object({
+  email: z.string().email(),
+});
+
+export default async function emailVerificationRoutes(app: FastifyInstance) {
+  // Authenticated: resend the verification email for the signed-in user.
+  app.post("/email-verification/send", { preHandler: [app.authenticate] }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const user = request.user;
+    if (!user) return reply.status(401).send({ error: "Unauthorized" });
+    if (user.emailVerified) return { success: true, alreadyVerified: true };
+
+    try {
+      await sendVerificationEmail(user);
+    } catch (err) {
+      request.log.error({ err }, "Failed to send verification email");
+      return reply.status(500).send({ error: "Failed to send verification email" });
+    }
+
+    await request.audit("email_verification_sent", { userId: user.id });
+    return { success: true };
+  });
+
+  // Unauthenticated: request a verification email by address.
+  // Always returns success to avoid user enumeration.
+  app.post("/email-verification/request", {
+    preHandler: [
+      rateLimit({
+        keyPrefix: "email-verification",
+        maxAttempts: 3,
+        windowSeconds: 900,
+      }),
+    ],
+  }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const body = SendSchema.parse(request.body);
+    const user = await findUserByEmail(body.email);
+    if (!user || user.emailVerified) {
+      return reply.status(200).send({ success: true });
+    }
+
+    try {
+      await sendVerificationEmail(user);
+      await request.audit("email_verification_sent", { userId: user.id });
+    } catch (err) {
+      request.log.error({ err }, "Failed to send verification email");
+    }
+
+    return { success: true };
+  });
+
+  app.get("/email-verification/verify", async (request: FastifyRequest, reply: FastifyReply) => {
+    const query = request.query as { token?: string };
+    if (!query.token) {
+      return reply.status(400).send({ error: "Missing token" });
+    }
+
+    const user = await consumeVerificationToken(query.token);
+    if (!user) {
+      return reply.status(400).send({ error: "Invalid or expired token" });
+    }
+
+    await request.audit("email_verified", { userId: user.id });
+    return { success: true, email: user.email };
+  });
+}

package/src/routes/federation.ts

@@ -0,0 +1,156 @@
+import crypto from "node:crypto";
+import { z } from "zod";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { config } from "../config.js";
+import { listSupportedProviders, listConfiguredProviders } from "../services/connectors/registry.js";
+import { getSdk } from "../sdk/index.js";
+import { setSessionCookies, clearSessionCookies } from "../plugins/auth.js";
+import { findApplicationByClientId } from "../services/applications.js";
+import type { Application } from "../db/schema.js";
+import { buildOAuthErrorRedirect, buildOAuthErrorResponse } from "../lib/errors.js";
+import { sendResultError } from "./helpers.js";
+
+function isProvider(value: string): boolean {
+  return listSupportedProviders().includes(value);
+}
+
+function randomState(): string {
+  return crypto.randomBytes(24).toString("base64url");
+}
+
+function publicUrl(): string {
+  return config.AUTH_API_PUBLIC_URL || `http://localhost:${config.PORT}`;
+}
+
+function callbackRedirectUri(provider: string): string {
+  return `${publicUrl()}/federation/${provider}/callback`;
+}
+
+function setFederationState(reply: FastifyReply, state: string, clientId?: string): void {
+  reply.setCookie("fed_state", state, {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite: "lax" as const,
+    domain: config.COOKIE_DOMAIN || undefined,
+    maxAge: 600,
+  });
+  if (clientId) {
+    reply.setCookie("fed_client_id", clientId, {
+      path: "/",
+      httpOnly: true,
+      secure: config.COOKIE_SECURE,
+      sameSite: "lax" as const,
+      domain: config.COOKIE_DOMAIN || undefined,
+      maxAge: 600,
+    });
+  }
+}
+
+function clearFederationCookies(reply: FastifyReply): void {
+  const opts = {
+    path: "/",
+    httpOnly: true,
+    secure: config.COOKIE_SECURE,
+    sameSite: "lax" as const,
+    domain: config.COOKIE_DOMAIN || undefined,
+  };
+  reply.clearCookie("fed_state", opts);
+  reply.clearCookie("fed_client_id", opts);
+}
+
+function redirectTargetUrl(clientId?: string, app?: Application): string {
+  if (app?.redirectUris?.length) return app.redirectUris[0];
+  return process.env.CLIENT_APP_URL || "http://localhost:5173";
+}
+
+const LinkIdentitySchema = z.object({
+  providerType: z.string(),
+  providerId: z.string().uuid(),
+  externalSub: z.string(),
+  email: z.string().email().optional(),
+});
+
+export default async function federationRoutes(app: FastifyInstance) {
+  const sdk = getSdk();
+
+  app.get("/:provider/start", async (request, reply) => {
+    const { provider } = request.params as { provider: string };
+    if (!isProvider(provider)) {
+      return reply.status(400).send({ error: "Unsupported federation provider" });
+    }
+    const query = request.query as { client_id?: string; redirect_uri?: string };
+    const state = randomState();
+    setFederationState(reply, state, query.client_id);
+
+    try {
+      const result = await sdk.identity.getFederationAuthorizeUrl(provider, state, callbackRedirectUri(provider));
+      if (!result.success) return sendResultError(reply, result);
+      return reply.redirect(result.data.url);
+    } catch (err) {
+      request.log.error({ err }, "Federation start failed");
+      clearFederationCookies(reply);
+      const { statusCode, body } = buildOAuthErrorResponse(err);
+      return reply.status(statusCode).send(body);
+    }
+  });
+
+  app.get("/:provider/callback", async (request, reply) => {
+    const { provider } = request.params as { provider: string };
+    if (!isProvider(provider)) {
+      return reply.status(400).send({ error: "Unsupported federation provider" });
+    }
+
+    const { code, state } = request.query as { code?: string; state?: string };
+    const cookieState = request.cookies.fed_state;
+    const clientId = request.cookies.fed_client_id;
+
+    if (!code || !state || state !== cookieState) {
+      clearFederationCookies(reply);
+      return reply.redirect(`${redirectTargetUrl(clientId)}?error=${encodeURIComponent("Invalid federation state")}`);
+    }
+    clearFederationCookies(reply);
+
+    try {
+      const result = await sdk.identity.completeFederationLogin(provider, code, callbackRedirectUri(provider));
+      if (!result.success) return sendResultError(reply, result);
+      const app = clientId ? await findApplicationByClientId(clientId) : undefined;
+      setSessionCookies(reply, result.data.tokens.accessToken, result.data.tokens.refreshToken, app?.clientId);
+      return reply.redirect(redirectTargetUrl(clientId, app));
+    } catch (err) {
+      request.log.error({ err }, "Federation callback failed");
+      clearSessionCookies(reply);
+      const url = buildOAuthErrorRedirect(err, redirectTargetUrl(clientId), { state });
+      return reply.redirect(url);
+    }
+  });
+
+  app.get("/providers", async () => {
+    return {
+      providers: listConfiguredProviders(),
+    };
+  });
+
+  app.post(
+    "/link",
+    { preHandler: [app.authenticate] },
+    async (request: FastifyRequest, reply) => {
+      const body = LinkIdentitySchema.parse(request.body);
+      const result = await sdk.identity.linkUserIdentity(
+        request.user!.id,
+        body.providerId,
+        body.providerType,
+        body.externalSub,
+        body.email
+      );
+      if (!result.success) return sendResultError(reply, result);
+      await request.audit("federation_identity_linked", { userId: request.user!.id, providerType: body.providerType, providerId: body.providerId });
+      return reply.status(201).send({ success: true });
+    }
+  );
+
+  app.get("/identities", { preHandler: [app.authenticate] }, async (request: FastifyRequest) => {
+    const rows = await app.container.identityRepository.listByUserId(request.user!.id);
+    return { identities: rows };
+  });
+}

package/src/routes/helpers.ts

@@ -0,0 +1,17 @@
+import type { FastifyReply } from "fastify";
+
+export function sendResultError(reply: FastifyReply, result: { success: false; error: { statusCode?: number; message: string; code: string } }) {
+  return reply.status(result.error.statusCode ?? 400).send({ error: result.error.message, code: result.error.code });
+}
+
+/**
+ * Escape special XML characters to prevent XML injection.
+ */
+export function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

package/src/routes/magicLinks.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import { findUserByEmail } from "../services/users.js";
+import {
+  generateMagicLink,
+  storeMagicLink,
+  consumeMagicLink,
+  magicLinkExpiresAt,
+} from "../services/magicLinks.js";
+import { createTokenSet } from "../services/tokens.js";
+import { fingerprintFromRequest, recordDevice } from "../services/devices.js";
+import { setSessionCookies } from "../plugins/auth.js";
+import { emailProvider } from "../services/email.js";
+import { toPublicUser } from "../types.js";
+import { config } from "../config.js";
+import { rateLimit } from "../plugins/rateLimit.js";
+
+const SendSchema = z.object({
+  email: z.string().email(),
+});
+
+function magicLinkUrl(token: string): string {
+  // The link lands on the client app (Keystone admin UI or a client
+  // application), which exchanges the token via the verify endpoint.
+  const base = process.env.CLIENT_APP_URL || "http://localhost:5173";
+  return `${base}/#magic-link=${encodeURIComponent(token)}`;
+}
+
+function postLoginRedirect(): string {
+  return process.env.CLIENT_APP_URL || "http://localhost:5173";
+}
+
+export default async function magicLinkRoutes(app: FastifyInstance) {
+  app.post("/magic-link/send", {
+    preHandler: [
+      rateLimit({
+        keyPrefix: "magic-link",
+        maxAttempts: 3,
+        windowSeconds: 900,
+      }),
+    ],
+  }, async (request, reply) => {
+    const body = SendSchema.parse(request.body);
+    const user = await findUserByEmail(body.email);
+    if (!user) {
+      return reply.status(200).send({ success: true });
+    }
+
+    const { token, tokenHash } = generateMagicLink();
+    await storeMagicLink(user.id, tokenHash, magicLinkExpiresAt());
+
+    try {
+      const url = magicLinkUrl(token);
+      const ttlMinutes = Math.round(config.MAGIC_LINK_TTL_SECONDS / 60);
+      await emailProvider.send({
+        to: user.email,
+        subject: "Your sign-in link",
+        text: `Click the link to sign in:\n\n${url}\n\nThis link expires in ${ttlMinutes} minutes and can only be used once.`,
+        html: `<p>Click <a href="${url}">here</a> to sign in.</p><p>This link expires in ${ttlMinutes} minutes and can only be used once.</p>`,
+      });
+    } catch (err) {
+      request.log.error({ err }, "Failed to send magic link email");
+    }
+
+    await request.audit("magic_link_sent", { userId: user.id });
+
+    return { success: true };
+  });
+
+  app.get("/magic-link/verify", async (request: FastifyRequest, reply) => {
+    const query = request.query as { token?: string; redirect?: string };
+    if (!query.token) {
+      return reply.status(400).send({ error: "Missing token" });
+    }
+
+    const user = await consumeMagicLink(query.token);
+    if (!user) {
+      return reply.status(400).send({ error: "Invalid or expired token" });
+    }
+
+    const fingerprint = fingerprintFromRequest(request);
+    await recordDevice(user.id, fingerprint, request.ip, request.headers["user-agent"]);
+
+    const tokens = await createTokenSet(
+      user,
+      request.ip,
+      request.headers["user-agent"],
+      {},
+      fingerprint
+    );
+    setSessionCookies(reply, tokens.accessToken, tokens.refreshToken);
+
+    await request.audit("magic_link_verified", { userId: user.id });
+
+    // Browser flow: redirect back to the app after setting session cookies.
+    const accept = request.headers.accept || "";
+    if (accept.includes("text/html")) {
+      return reply.redirect(postLoginRedirect());
+    }
+
+    return {
+      user: toPublicUser(user),
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+    };
+  });
+}