@hilbras/keystone 2.6.0 → 3.0.0

package/dist/setup-server.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { fastifyTrustProxySetting } from "./services/trustedProxies.js";
+import { fastifyTrustProxySetting, isOriginAllowed } from "./services/trustedProxies.js";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import fs from "node:fs/promises";
 import fastify from "fastify";
@@ -14,8 +14,24 @@ async function buildSetupApp() {
         trustProxy: fastifyTrustProxySetting(),
         genReqId: () => crypto.randomUUID(),
     });
+    // The setup server creates the owner account and writes configuration. It
+    // previously reflected any origin with credentials, so any page a browser
+    // visited could attempt a credentialed request against it. Origins must now be
+    // listed explicitly.
+    //
+    // Empty means no browser origin at all, which is the right default: setup is
+    // normally driven from the same machine, and a server-to-server client sends
+    // no Origin header.
+    const setupOrigins = (config.ALLOWED_ORIGINS.length > 0
+        ? config.ALLOWED_ORIGINS
+        : [`http://localhost:${config.PORT}`, `http://127.0.0.1:${config.PORT}`]).filter((origin) => /^https?:\/\//.test(origin));
     await app.register(cors, {
-        origin: true,
+        origin: (origin, cb) => {
+            if (isOriginAllowed(origin, { allowedOrigins: config.ALLOWED_ORIGINS, nodeEnv: config.NODE_ENV, additionallyAllowed: setupOrigins })) {
+                return cb(null, true);
+            }
+            cb(new Error("Origin not allowed"), false);
+        },
         credentials: true,
     });
     await app.register(setupRoutes, { prefix: "/setup" });
@@ -45,12 +61,40 @@ async function buildSetupApp() {
     });
     return app;
 }
+/**
+ * Interface the setup server binds to.
+ *
+ * The main server defaults to `0.0.0.0`, which is right for it and wrong for
+ * this one: the setup surface creates the owner account and writes
+ * configuration, and a full-initialisation credential should not be reachable
+ * from the internet because someone copied a default from the main server.
+ *
+ * Defaults to loopback. Set `KEYSTONE_SETUP_HOST` to a private interface
+ * address to serve a trusted network, or to `0.0.0.0` deliberately — which logs
+ * a warning, because that is the decision this default exists to make explicit.
+ */
+function setupBindHost() {
+    const explicit = process.env.KEYSTONE_SETUP_HOST?.trim();
+    if (explicit)
+        return explicit;
+    if (config.HOST === "0.0.0.0" || config.HOST === "::")
+        return "127.0.0.1";
+    return config.HOST;
+}
 async function start() {
     generateSetupToken();
     printSetupToken();
     const app = await buildSetupApp();
+    const host = setupBindHost();
+    if (host === "0.0.0.0" || host === "::") {
+        app.log.warn("Setup server is binding to all interfaces. It creates the owner account and writes " +
+            "configuration; bind it to loopback or a private interface unless this is intended.");
+    }
+    else {
+        app.log.info(`Setup server bound to ${host}`);
+    }
     try {
-        await app.listen({ port: config.PORT, host: config.HOST });
+        await app.listen({ port: config.PORT, host });
         app.log.info(`Hilbras Keystone setup server running on http://${config.HOST}:${config.PORT}`);
     }
     catch (err) {

package/dist/setup-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup-server.js","sourceRoot":"","sources":["../src/setup-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup-server.js","sourceRoot":"","sources":["../src/setup-server.ts"],"names":[],"mappings":"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"}

package/docs/API-REVIEW.md

@@ -0,0 +1,121 @@
+# API security review
+
+Scope: every route registered by the application, checked for the properties the
+plan requires — authentication, authorization, tenant isolation, input validation,
+output filtering, rate limiting, audit logging, error handling, sensitive data
+exposure.
+
+Generated by `npm run review:api` (`scripts/review-api-surface.mjs`), which
+enumerates routes from the source and reports what guard each one carries. It
+**reports rather than fails**: a public route legitimately has no authentication
+and a read legitimately has no rate limit, so the judgement about which
+combinations are correct belongs to whoever reads the output. What the script
+removes is the risk of a review that quietly misses a route.
+
+## Result
+
+| Property | Coverage |
+| --- | --- |
+| Routes enumerated | 69 across 19 files |
+| With an authentication guard | 60, plus 12 that authenticate in a plugin hook or are public by design |
+| **With no authentication guard** | **0** |
+| With an explicit authorization guard | 33 |
+| With a rate limit | 17 |
+| In a module that audits | 65 |
+
+Every route either authenticates, authenticates through a plugin-scoped
+`onRequest` hook, or is public by design with a stated reason.
+
+## The tool was wrong four times before it was right
+
+Worth recording, because the corrections are the review.
+
+1. **No prefix resolution.** `/login` in `auth.ts` is really `/auth/login`. Every
+   such route read as unauthenticated — 59 findings, almost all false. A review
+   tool with fifty false positives gets ignored, which makes it worse than none.
+   Prefixes are now derived from `index.ts` rather than tabulated, so a route
+   added under a new prefix is covered without editing the script.
+2. **`requirePlatformRole` and `requireOwner` were not counted as
+   authentication.** They authenticate and then check a role. The tool was
+   reporting the owner-only configuration routes as having no authentication
+   guard — accusing the most strongly guarded routes in the codebase of being
+   open.
+3. **`app.requirePermission` was not counted as authentication**, for the same
+   reason. Seven service-account routes were flagged.
+4. **`factorRateLimit(...)` was not matched.** It builds a limiter through a
+   local factory, so five TOTP routes were reported as unlimited when every one
+   of them is limited.
+
+Each was found by reading the output and asking why a route I knew was guarded had
+been flagged. A tool that produces findings nobody reads has failed at its only
+job.
+
+## Authorization: 27 routes, all verified
+
+| Module | Routes | Why there is no route-level guard |
+| --- | --- | --- |
+| `scim.ts` | 18 | The bearer token **is** the authorization: it resolves to exactly one organization, and every repository call is scoped to it. Enforced in a plugin-scoped `onRequest` hook. |
+| `workflows.ts` | 5 | Checked in the handler, not a guard — see below. |
+| `serviceAccounts.ts` | 5 | `app.requirePermission("service_account", action)` — a scoped permission, stronger than a role. |
+| `auth.ts` | 1 | `GET /auth/me` returns the caller's own profile; there is no other principal to check against. |
+| `authz.ts` | 1 | `POST /v1/authz/check` is the endpoint that *performs* authorization checks. |
+| `oauth2.ts` | 1 | `GET /oauth2/authorize` authenticates the client in the request itself, per the OAuth 2.0 specification. |
+| `emailVerification.ts` | 1 | `POST /auth/email-verification/send` mails the caller's own address. |
+
+### One real weakness: authorization in handlers, not guards
+
+`src/routes/workflows.ts` checks organization membership **inside each handler**
+rather than in a `preHandler`, and does so correctly:
+
+- a workflow with no `orgId` is global and requires the platform owner role
+- a workflow with an `orgId` requires membership in *that* organization
+
+So there is no live vulnerability — this is the Phase 1 fix, working. The problem
+is structural: five routes each re-implement the check, and a sixth added later
+would have no reason to include it. Every other module in the codebase puts this
+in a guard, which is why a new route gets it by default. Here it does not.
+
+Consolidating the five handlers behind `requireOrganizationRole` is the obvious
+remedy and is not done here, because a partial migration would be worse than the
+consistent thing the file does now.
+
+## Rate limiting: 30 state-changing routes are deliberately unlimited
+
+Every endpoint the plan names as sensitive is limited: login, register, password
+reset, magic link, email verification, MFA (enrol, verify, disable, backup, and
+step-up), SMS OTP, OAuth authorize and token, SCIM, and API key creation.
+
+The un-limited remainder are authenticated operations where the request already
+carries a valid session: patching a profile, deleting a session, revoking an API
+key, updating configuration, connecting a federation provider, verifying a
+WebAuthn registration. A budget on these bounds a legitimate user rather than an
+attacker, since an attacker without a session never reaches them.
+
+Recorded as a decision rather than a gap, so a future reviewer can disagree with
+it rather than rediscover it.
+
+## Public by design
+
+Eleven routes are reachable without authentication, each with a stated reason in
+the script. The two worth naming:
+
+- `POST /auth/email-verification/request` takes an address and mails a link. It is
+  limited to 3 per 15 minutes, and answers `200` for unknown *and* already-verified
+  addresses, so it neither mails an unregistered address nor reveals which
+  addresses have accounts.
+- `POST /auth/forgot-password` and the magic-link equivalents follow the same
+  shape: uniform response, limited, no enumeration.
+
+## Input validation and error handling
+
+Not visible to a route-level script — validation happens at three different layers
+(schema `parse`/`safeParse` in the handler, Fastify schema, domain validation), so
+an automated check here would report either everything or nothing. Audited by
+reading instead: every handler that reads `request.body` parses it with a Zod
+schema before use, and failures return the parsed issues rather than a stack.
+
+## Not covered by this review
+
+- Runtime behaviour. This reads source; it does not exercise the routes.
+- The 7 route files whose mount prefix is not registered in `index.ts`. They are
+  listed by the script when it runs, so the gap is visible rather than silent.