@hilbras/keystone 1.1.0

package/src/routes/profile.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { toPublicUser } from "../types.js";
+
+const UpdateProfileSchema = z.object({
+  name: z.string().max(255).optional(),
+  avatarUrl: z.string().url().max(2048).nullable().optional(),
+  phoneNumber: z.string().max(32).nullable().optional(),
+  metadata: z.record(z.unknown()).optional(),
+});
+
+export default async function profileRoutes(app: FastifyInstance) {
+  app.get("/profile", { preHandler: [app.authenticate] }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const userId = request.user?.id;
+    if (!userId) return reply.status(401).send({ error: "Unauthorized" });
+
+    const user = await app.container.userRepository.findById(userId);
+    if (!user) return reply.status(404).send({ error: "User not found" });
+
+    return { user: toPublicUser(user) };
+  });
+
+  app.patch("/profile", { preHandler: [app.authenticate] }, async (request: FastifyRequest, reply: FastifyReply) => {
+    const userId = request.user?.id;
+    if (!userId) return reply.status(401).send({ error: "Unauthorized" });
+
+    const body = UpdateProfileSchema.parse(request.body);
+    const updates: Record<string, unknown> = {};
+    if (body.name !== undefined) updates.name = body.name;
+    if (body.avatarUrl !== undefined) updates.avatarUrl = body.avatarUrl;
+    if (body.metadata !== undefined) updates.metadata = body.metadata;
+    // Changing the phone number resets its verification status.
+    if (body.phoneNumber !== undefined) {
+      updates.phoneNumber = body.phoneNumber;
+      updates.phoneVerified = false;
+    }
+
+    const updated = await app.container.userRepository.update(userId, updates);
+    if (!updated) return reply.status(404).send({ error: "User not found" });
+
+    await request.audit("profile_updated", { userId });
+    return { user: toPublicUser(updated) };
+  });
+}

package/src/routes/saml.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { ServiceProvider, IdentityProvider } from "samlify";
+import type { SamlConnection } from "../db/schema.js";
+import { provisionEnterpriseUser, defaultRoleForOrg } from "../services/enterpriseSso.js";
+import { createTokenSet } from "../services/tokens.js";
+import { setSessionCookies } from "../plugins/auth.js";
+import { fingerprintFromRequest, recordDevice } from "../services/devices.js";
+import { toPublicUser } from "../types.js";
+import { config } from "../config.js";
+import { escapeXml } from "./helpers.js";
+
+const RelayStateSchema = z.object({
+  connectionId: z.string(),
+});
+
+const DEFAULT_ATTRIBUTE_MAPPING: Record<string, string[]> = {
+  email: [
+    "email",
+    "mail",
+    "urn:oid:0.9.2342.19200300.100.1.3",
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
+    "http://schemas.microsoft.com/identity/claims/email",
+  ],
+  name: [
+    "name",
+    "displayName",
+    "cn",
+    "commonName",
+    "urn:oid:2.16.840.1.113730.3.1.241",
+    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
+    "http://schemas.microsoft.com/identity/claims/displayname",
+  ],
+};
+
+function buildSamlEntities(connection: SamlConnection) {
+  if (!connection.idpEntityId || !connection.idpSsoUrl || !connection.idpCertificate) {
+    throw new Error("SAML connection is missing IdP metadata");
+  }
+
+  const sp = ServiceProvider({
+    entityID: connection.spEntityId,
+    wantAssertionsSigned: true,
+    wantMessageSigned: true,
+    assertionConsumerService: [
+      {
+        Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
+        Location: connection.spAcsUrl,
+      },
+    ],
+  });
+
+  const idp = IdentityProvider({
+    entityID: connection.idpEntityId,
+    signingCert: connection.idpCertificate,
+    singleSignOnService: [
+      {
+        Binding: "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
+        Location: connection.idpSsoUrl,
+      },
+    ],
+  });
+
+  return { sp, idp };
+}
+
+function getAttribute(
+  attributes: Record<string, string | string[]> | undefined,
+  key: string,
+  mapping: Record<string, string[]>,
+  fallbackMapping: Record<string, string[]>
+): string | undefined {
+  const candidates = mapping[key] ?? fallbackMapping[key] ?? [key];
+  for (const candidate of candidates) {
+    const value = attributes?.[candidate];
+    if (value === undefined || value === null) continue;
+    const normalized = Array.isArray(value) ? value[0] : value;
+    if (normalized) return normalized;
+  }
+  return undefined;
+}
+
+function parseSamlAttributes(
+  attributes: Record<string, string | string[]> | undefined,
+  connection: SamlConnection
+): { email?: string; name?: string } {
+  const mapping = (connection.attributeMapping ?? {}) as Record<string, string[]>;
+  return {
+    email: getAttribute(attributes, "email", mapping, DEFAULT_ATTRIBUTE_MAPPING),
+    name: getAttribute(attributes, "name", mapping, DEFAULT_ATTRIBUTE_MAPPING),
+  };
+}
+
+function sanitizeSamlError(error: unknown): { statusCode: number; body: { error: string } } {
+  const message = config.NODE_ENV === "development" && error instanceof Error ? error.message : "SAML validation failed";
+  return { statusCode: 400, body: { error: message } };
+}
+
+export default async function samlRoutes(app: FastifyInstance) {
+  app.get("/saml/:connectionId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { connectionId } = request.params as { connectionId: string };
+    const connection = await app.container.samlConnectionRepository.findActiveById(connectionId);
+
+    if (!connection) {
+      return reply.status(404).send({ error: "SAML connection not found" });
+    }
+
+    if (!connection.idpSsoUrl) {
+      return reply.status(400).send({ error: "SAML connection missing IdP SSO URL" });
+    }
+
+    try {
+      const { sp, idp } = buildSamlEntities(connection);
+      const relayState = Buffer.from(JSON.stringify({ connectionId })).toString("base64url");
+      const loginRequest = sp.createLoginRequest(idp, "redirect", { relayState });
+
+      const url = new URL(connection.idpSsoUrl);
+      url.searchParams.set("SAMLRequest", loginRequest.context);
+      if (relayState) url.searchParams.set("RelayState", relayState);
+
+      return reply.redirect(url.toString());
+    } catch (err) {
+      request.log.error({ err }, "Failed to build SAML login request");
+      const { statusCode, body } = sanitizeSamlError(err);
+      return reply.status(statusCode).send(body);
+    }
+  });
+
+  app.post("/saml/acs", async (request: FastifyRequest, reply: FastifyReply) => {
+    const body = request.body as { SAMLResponse?: string; RelayState?: string };
+    if (!body.SAMLResponse) {
+      return reply.status(400).send({ error: "Missing SAMLResponse" });
+    }
+
+    let relayState: { connectionId: string } | undefined;
+    try {
+      relayState = RelayStateSchema.parse(
+        JSON.parse(Buffer.from(body.RelayState || "", "base64url").toString("utf8"))
+      );
+    } catch {
+      return reply.status(400).send({ error: "Invalid RelayState" });
+    }
+
+    const connection = await app.container.samlConnectionRepository.findActiveById(relayState.connectionId);
+
+    if (!connection) {
+      return reply.status(400).send({ error: "SAML connection not found" });
+    }
+
+    try {
+      const { sp, idp } = buildSamlEntities(connection);
+      const result = await sp.parseLoginResponse(idp, "post", { body });
+      const claims = parseSamlAttributes(result.extract.attributes, connection);
+
+      if (!claims.email) {
+        return reply.status(400).send({ error: "SAML response did not contain an email" });
+      }
+
+      const org = await app.container.organizationRepository.findById(connection.orgId);
+
+      const user = await provisionEnterpriseUser(
+        connection.orgId,
+        { email: claims.email, name: claims.name },
+        org ? defaultRoleForOrg(org) : "member"
+      );
+
+      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"],
+        { orgId: connection.orgId },
+        fingerprint
+      );
+      setSessionCookies(reply, tokens.accessToken, tokens.refreshToken);
+
+      await request.audit("saml_sso_login", {
+        orgId: connection.orgId,
+        connectionId: connection.id,
+        userId: user.id,
+      });
+
+      return { user: toPublicUser(user) };
+    } catch (err) {
+      request.log.error({ err }, "SAML ACS validation failed");
+      const { statusCode, body } = sanitizeSamlError(err);
+      return reply.status(statusCode).send(body);
+    }
+  });
+
+  app.get("/saml/:connectionId/metadata", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { connectionId } = request.params as { connectionId: string };
+    const connection = await app.container.samlConnectionRepository.findActiveById(connectionId);
+
+    if (!connection) {
+      return reply.status(404).send({ error: "SAML connection not found" });
+    }
+
+    const metadata = `
+<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="${escapeXml(connection.spEntityId)}">
+  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
+    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="${escapeXml(connection.spAcsUrl)}" index="0"/>
+  </md:SPSSODescriptor>
+</md:EntityDescriptor>`.trim();
+
+    return reply.header("Content-Type", "application/xml").send(metadata);
+  });
+}

package/src/routes/scim.ts

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { eq, and } from "drizzle-orm";
+import { db } from "../db/index.js";
+import { orgMemberships, users } from "../db/schema.js";
+
+const ScimUserSchema = z.object({
+  userName: z.string().email(),
+  name: z.object({ givenName: z.string().optional(), familyName: z.string().optional() }).optional(),
+  emails: z.array(z.object({ value: z.string().email(), primary: z.boolean().optional() })).optional(),
+  active: z.boolean().optional(),
+});
+
+function scimUserResponse(user: { id: string; email: string; name: string | null }): Record<string, unknown> {
+  return {
+    schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"],
+    id: user.id,
+    userName: user.email,
+    name: {
+      givenName: user.name?.split(" ")[0] || "",
+      familyName: user.name?.split(" ").slice(1).join(" ") || "",
+    },
+    emails: [{ value: user.email, primary: true }],
+    active: true,
+    meta: {
+      resourceType: "User",
+    },
+  };
+}
+
+function scimGroupResponse(group: { id: string; displayName: string; members: { value: string; display: string }[] }): Record<string, unknown> {
+  return {
+    schemas: ["urn:ietf:params:scim:schemas:core:2.0:Group"],
+    id: group.id,
+    displayName: group.displayName,
+    members: group.members.map((m) => ({
+      value: m.value,
+      display: m.display,
+      $ref: `Users/${m.value}`,
+    })),
+    meta: {
+      resourceType: "Group",
+    },
+  };
+}
+
+function scimError(status: number, detail: string): Record<string, unknown> {
+  return {
+    schemas: ["urn:ietf:params:scim:api:messages:2.0:Error"],
+    status: String(status),
+    detail,
+  };
+}
+
+export default async function scimRoutes(app: FastifyInstance) {
+  app.addHook("onRequest", async (request: FastifyRequest, reply: FastifyReply) => {
+    const auth = request.headers.authorization;
+    const expected = process.env.SCIM_BEARER_TOKEN;
+    if (!expected) {
+      return reply.status(501).send(scimError(501, "SCIM not configured"));
+    }
+    if (!auth || !auth.startsWith("Bearer ") || auth.slice(7) !== expected) {
+      return reply.status(401).send(scimError(401, "Unauthorized"));
+    }
+  });
+
+  app.get("/scim/v2/Users", async () => {
+    const allUsers = await app.container.userRepository.listAll();
+    return {
+      schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
+      totalResults: allUsers.length,
+      Resources: allUsers.map(scimUserResponse),
+    };
+  });
+
+  app.get("/scim/v2/Users/:userId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { userId } = request.params as { userId: string };
+    const user = await app.container.userRepository.findById(userId);
+    if (!user) {
+      return reply.status(404).send(scimError(404, "User not found"));
+    }
+    return scimUserResponse(user);
+  });
+
+  app.post("/scim/v2/Users", async (request: FastifyRequest, reply: FastifyReply) => {
+    const body = ScimUserSchema.parse(request.body);
+    const email = body.userName.toLowerCase().trim();
+
+    let user = await app.container.userRepository.findByEmail(email);
+    let isNewUser = false;
+    if (!user) {
+      const base = email.split("@")[0];
+      const username = await app.container.userRepository.ensureUniqueUsername(base);
+      const name = body.name
+        ? `${body.name.givenName || ""} ${body.name.familyName || ""}`.trim() || username
+        : username;
+      user = await app.container.userRepository.create({
+        email,
+        username,
+        name,
+        provider: "scim",
+        emailVerified: true,
+      });
+      isNewUser = true;
+    }
+
+    await request.audit(isNewUser ? "scim_user_created" : "scim_user_updated", { userId: user.id, email: user.email });
+    return reply.status(201).send(scimUserResponse(user));
+  });
+
+  app.put("/scim/v2/Users/:userId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { userId } = request.params as { userId: string };
+    const body = ScimUserSchema.parse(request.body);
+
+    const updated = await app.container.userRepository.update(userId, {
+      email: body.userName.toLowerCase().trim(),
+      name: body.name
+        ? `${body.name.givenName || ""} ${body.name.familyName || ""}`.trim()
+        : undefined,
+    });
+
+    if (!updated) {
+      return reply.status(404).send(scimError(404, "User not found"));
+    }
+    await request.audit("scim_user_updated", { userId: updated.id, email: updated.email });
+    return scimUserResponse(updated);
+  });
+
+  app.delete("/scim/v2/Users/:userId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { userId } = request.params as { userId: string };
+    const user = await app.container.userRepository.findById(userId);
+    await app.container.userRepository.deleteById(userId);
+    await request.audit("scim_user_deleted", { userId, email: user?.email });
+    return reply.status(204).send();
+  });
+
+  app.get("/scim/v2/Groups", async () => {
+    const memberships = await db
+      .select({ orgId: orgMemberships.orgId, role: orgMemberships.role })
+      .from(orgMemberships);
+
+    const groupMap = new Map<string, { orgId: string; role: string; members: { value: string; display: string }[] }>();
+    for (const m of memberships) {
+      const key = `${m.orgId}:${m.role}`;
+      if (!groupMap.has(key)) {
+        groupMap.set(key, { orgId: m.orgId, role: m.role, members: [] });
+      }
+    }
+
+    const groups: { id: string; displayName: string; members: { value: string; display: string }[] }[] = [];
+    for (const [key, group] of groupMap) {
+      const org = await app.container.organizationRepository.findById(group.orgId);
+      const orgName = org?.name || group.orgId;
+      const members = await db
+        .select({ userId: orgMemberships.userId, email: users.email })
+        .from(orgMemberships)
+        .where(and(eq(orgMemberships.orgId, group.orgId), eq(orgMemberships.role, group.role)))
+        .innerJoin(users, eq(orgMemberships.userId, users.id));
+
+      groups.push({
+        id: key,
+        displayName: `${orgName}:${group.role}`,
+        members: members.map((m) => ({ value: m.userId, display: m.email })),
+      });
+    }
+
+    return {
+      schemas: ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
+      totalResults: groups.length,
+      Resources: groups.map(scimGroupResponse),
+    };
+  });
+
+  app.get("/scim/v2/Groups/:groupId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { groupId } = request.params as { groupId: string };
+    const [orgId, role] = groupId.split(":");
+
+    if (!orgId || !role) {
+      return reply.status(400).send(scimError(400, "Invalid group ID format. Expected orgId:role"));
+    }
+
+    const org = await app.container.organizationRepository.findById(orgId);
+    if (!org) {
+      return reply.status(404).send(scimError(404, "Organization not found"));
+    }
+
+    const members = await db
+      .select({ userId: orgMemberships.userId, email: users.email })
+      .from(orgMemberships)
+      .where(and(eq(orgMemberships.orgId, orgId), eq(orgMemberships.role, role)))
+      .innerJoin(users, eq(orgMemberships.userId, users.id));
+
+    return scimGroupResponse({
+      id: groupId,
+      displayName: `${org.name}:${role}`,
+      members: members.map((m) => ({ value: m.userId, display: m.email })),
+    });
+  });
+}

package/src/routes/sdk.ts

@@ -0,0 +1,141 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { gzip } from "node:zlib";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { z } from "zod";
+import { createApplication, findApplicationByClientId } from "../services/applications.js";
+import { createOrganization, findOrganizationBySlug, findOrganizationById } from "../services/organizations.js";
+
+const gzipAsync = promisify(gzip);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SDK_FILE = path.resolve(__dirname, "../../packages/keystone-sdk/dist/keystone-dropin.js");
+
+const ConnectSchema = z.object({
+  projectId: z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/),
+  redirectUri: z.string().url().optional(),
+  clientId: z.string().optional(),
+});
+
+export default async function sdkRoutes(app: FastifyInstance) {
+  // Serve the drop-in SDK so external projects can load it with one script tag.
+  app.get("/keystone-dropin.js", async (request: FastifyRequest, reply: FastifyReply) => {
+    try {
+      const content = await fs.readFile(SDK_FILE, "utf-8");
+      const hash = crypto.createHash("sha256").update(content).digest("base64");
+      const etag = `"${hash}"`;
+      const ifNoneMatch = request.headers["if-none-match"];
+      if (ifNoneMatch === etag) {
+        return reply.status(304).send();
+      }
+
+      const acceptEncoding = request.headers["accept-encoding"] || "";
+      const useGzip = acceptEncoding.includes("gzip");
+      const body = useGzip ? await gzipAsync(content) : content;
+
+      reply
+        .header("Content-Type", "application/javascript; charset=utf-8")
+        .header("Cache-Control", "public, max-age=86400, immutable")
+        .header("ETag", etag);
+      if (useGzip) reply.header("Content-Encoding", "gzip");
+      return reply.send(body);
+    } catch (err) {
+      app.log.error({ err }, "SDK file not found");
+      return reply.status(404).send({ error: "SDK not built. Run npm run build:sdk first." });
+    }
+  });
+
+  // SRI hash for the drop-in SDK so consumers can use integrity="sha256-…".
+  app.get("/keystone-dropin.js.sri", async (request: FastifyRequest, reply: FastifyReply) => {
+    try {
+      const content = await fs.readFile(SDK_FILE, "utf-8");
+      const hash = crypto.createHash("sha256").update(content).digest("base64");
+      reply.header("Cache-Control", "public, max-age=86400, immutable");
+      return { integrity: `sha256-${hash}` };
+    } catch (err) {
+      app.log.error({ err }, "SDK file not found");
+      return reply.status(404).send({ error: "SDK not built. Run npm run build:sdk first." });
+    }
+  });
+
+  // Public branding lookup for hosted login pages and the drop-in SDK.
+  // Returns only display-safe fields — never secrets.
+  app.get("/branding/:clientId", async (request: FastifyRequest, reply: FastifyReply) => {
+    const { clientId } = request.params as { clientId: string };
+    const application = await findApplicationByClientId(clientId);
+    if (!application) {
+      return reply.status(404).send({ error: "Application not found" });
+    }
+    const org = await findOrganizationById(application.orgId);
+
+    type Branding = Record<string, unknown>;
+    const orgBranding = (org?.branding ?? {}) as Branding;
+    const appBranding = (application.branding ?? {}) as Branding;
+    // App-level branding wins over org-level defaults.
+    const merged: Branding = { ...orgBranding, ...appBranding };
+    const pick = (key: string) => (typeof merged[key] === "string" ? merged[key] : undefined);
+
+    reply.header("Cache-Control", "public, max-age=300");
+    return {
+      name: pick("companyName") ?? application.name,
+      logoUrl: pick("logoUrl"),
+      primaryColor: pick("primaryColor"),
+      accentColor: pick("accentColor"),
+      supportEmail: pick("supportEmail"),
+      loginTitle: pick("loginTitle"),
+      loginSubtitle: pick("loginSubtitle"),
+    };
+  });
+
+  // Register or connect an external project/application.
+  app.post("/connect", async (request: FastifyRequest, reply: FastifyReply) => {
+    const parsed = ConnectSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ error: "Invalid input", details: parsed.error.issues });
+    }
+
+    const { projectId, redirectUri, clientId } = parsed.data;
+
+    try {
+      // If clientId is provided, verify the application exists.
+      if (clientId) {
+        const existing = await findApplicationByClientId(clientId);
+        if (!existing) {
+          return reply.status(404).send({ error: "Application not found" });
+        }
+        return reply.send({
+          connected: true,
+          clientId: existing.clientId,
+          message: "Connected to existing application",
+        });
+      }
+
+      // Otherwise create a new public client application for this project.
+      // In production this endpoint should be protected or require an admin API key.
+      let defaultOrg = await findOrganizationBySlug("external-projects");
+      if (!defaultOrg) {
+        defaultOrg = await createOrganization({ name: "External Projects", slug: "external-projects" });
+      }
+
+      const app = await createApplication({
+        orgId: defaultOrg.id,
+        name: projectId,
+        clientId: projectId,
+        redirectUris: redirectUri ? [redirectUri] : [],
+        allowedOrigins: [request.headers.origin || "*"].filter(Boolean),
+      });
+
+      return reply.status(201).send({
+        connected: true,
+        clientId: app.clientId,
+        clientSecret: app.clientSecret,
+        message: "Application connected to Keystone",
+      });
+    } catch (err) {
+      request.log.error({ err }, "SDK connect failed");
+      return reply.status(500).send({ error: "Connection failed" });
+    }
+  });
+}