@hilbras/keystone 1.9.0 → 2.6.0

package/CHANGELOG.md

@@ -5,6 +5,465 @@ All notable changes to Hilbras Keystone are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-09-27
+
+### Security
+
+- **The API key scope guard had a bypass by construction.** It read
+  `scopes.includes(scope) || scopes.includes("service_account")`, so a key whose
+  scope list contained the literal string `"service_account"` satisfied *every*
+  scope requirement. That string was client-suppliable: `POST /api-keys` stored
+  whatever `scopes` it was given, with no validation against any list.
+- **The same guard also failed open.** It returned early whenever
+  `apiKeyScopes` was absent, which is indistinguishable from "this is a session".
+  A key that resolved without a scope list therefore skipped the check entirely.
+- **The guard was never referenced.** `requireScopes` was defined and decorated
+  onto the Fastify instance, but no route in the repository used it. Scopes were
+  stored, returned to callers, and enforced nowhere.
+
+### How exploitable this actually was
+
+Stated precisely, because it matters for prioritising: `app.authenticate` is
+JWT-only and returns 401 for anything that is not a valid access token.
+`authenticateOrApiKey` is the handler with the API key path, and before this
+release exactly one route used it — `GET /auth/validate`. A leaked API key
+therefore reached one endpoint, which returns the caller's own public profile.
+
+So the exposure was a credential whose stated limits were fiction, on a
+credential that could be used almost nowhere. That is a real defect and worth
+fixing, but it is not an authentication bypass, and describing it as one would
+mislead anyone deciding what to do first.
+
+### Changed
+
+- `src/services/scopes.ts` — a scope registry: the canonical names, their
+  descriptions, per-principal defaults, validation, and the allow-list grant
+  check. A scope that is not defined cannot be granted.
+- Unknown or forbidden scopes are refused at key creation with a `400` naming
+  what was rejected and what is allowed, instead of being stored verbatim.
+- `requireScopes` now fails closed, keyed off a new `request.apiKeyId` that is
+  set only when a machine credential authenticated the request. A session is
+  still exempt, since it carries a person's authority and is governed by the
+  permission system.
+- Applied to the routes where a credential's limits matter most: API key
+  creation, listing and revocation, session listing and revocation, and profile
+  read and write.
+- `profile:read`, `profile:write`, and `mfa:manage` are human-only. A service
+  account's profile is a synthesized object with an id of `sa:<uuid>` that
+  matches no user row, so the scope is meaningless for a machine and misleading
+  in an audit log.
+- A service account's default grant is now `organizations:read` only. A personal
+  key's default is read-only on the caller's own resources; the previous
+  `api:read` default was not in any registry, which is a fair indication that
+  nothing was checking it.
+
+### Added
+
+- `src/plugins/machinePrincipal.ts` — `requireHumanPrincipal`, refusing a service
+  account on TOTP, WebAuthn, SMS OTP, identity linking, OAuth consent, and
+  userinfo routes with an explicit `403` and an audit record. This is a backstop
+  rather than a fix for a live hole: those routes are JWT-only today, so a
+  machine credential is refused with a 401 before the guard is reached. It exists
+  so that switching a route to `authenticateOrApiKey` does not silently make a
+  machine principal acceptable somewhere a person was assumed.
+- 25 tests covering the registry, validation, intersection, the grant check, the
+  fail-closed behaviour, HTTP enforcement on the one key-reachable route, and
+  the machine-principal boundary.
+
+### Fixed
+
+- Scope enforcement is keyed on `apiKeyId` rather than the presence of a scope
+  list, closing the fail-open path.
+- The `service_account` wildcard no longer grants anything.
+- Scope ordering is normalised, so two equivalent requests produce identical
+  rows.
+
+## [2.5.0] - 2026-09-27
+
+### Security
+
+- **The OIDC nonce never reached the Google connector.**
+  `GoogleConnector.exchangeCode` overrode the base method and called
+  `super.exchangeCode(code, redirectUri)` without forwarding its options, so the
+  nonce added in 2.4.0 was discarded. Every other OIDC provider validated the
+  nonce; Google — the default, and therefore the most likely to be deployed — did
+  not. An ID token minted for a different user or session would have been
+  accepted on that path.
+- **The unsigned SAML `Issuer` was never validated.** The response-level
+  `<saml:Issuer>` sits outside both signed regions, so rewriting it does not
+  invalidate the signature, and neither samlify nor Keystone compared it to the
+  registered IdP. SAML 2.0 §2.5.1.5 requires a relying party to verify an
+  unsigned issuer against trusted metadata. An assertion could claim to have been
+  issued by a different identity provider. The assertion's own issuer is inside
+  the signed region and was always covered; this closes the element the signature
+  cannot.
+
+### Fixed
+
+- `verifyRelayState` returned by throwing on a missing or non-string signature,
+  turning a malformed RelayState — a bad request an attacker fully controls —
+  into a 500 rather than a 400. It now returns false for anything malformed.
+- A missing `userinfoEndpoint` was passed to the fetcher behind a non-null
+  assertion, producing `userinfoEndpoint must be a valid URL` for a URL that was
+  never configured. It is now reported as unconfigured so enrichment is skipped.
+
+### Added
+
+- 24 adversarial SAML tests covering tampered signatures, untrusted signing keys,
+  rotated-out certificates, unsigned assertions, XML signature wrapping, issuer
+  and audience substitution, destination and recipient prefix / superstring / case
+  variants, expired assertions, `NotBefore` violations, `InResponseTo` mismatch,
+  transaction replay, and five RelayState tampering scenarios.
+- 10 tests for OIDC userinfo endpoint resolution, Google nonce forwarding, and
+  organization-scoped membership.
+- `docs/security/enterprise-sso.md` — SAML and OIDC setup, every check applied to
+  an assertion or ID token, certificate rotation, endpoint SSRF policy,
+  organization scoping, and recommendations.
+
+### Already sound, verified rather than assumed
+
+Membership is keyed on `(orgId, userId)` throughout, with a unique constraint on
+that pair and provisioning via `ON CONFLICT DO NOTHING` — so two simultaneous
+logins cannot create duplicate memberships. SAML connections are resolved by
+`(connectionId, orgId)`, the transaction is consumed atomically for replay
+protection, RelayState is HMAC-signed and bound to a browser nonce compared in
+constant time, and assertions and messages are both required to be signed. A test
+now pins the membership behaviour rather than leaving it to inspection.
+
+## [2.4.0] - 2026-09-27
+
+### Security
+
+- **The `authorization_code` grant did not authenticate the client.** It looked
+  the application up by `client_id` and went straight to redeeming the code,
+  never calling `verifyClientSecret`. RFC 6749 §3.2.1 requires a confidential
+  client to authenticate at the token endpoint. The code and its PKCE verifier
+  were the only factors, so an intercepted code was redeemable by whoever
+  intercepted it. Confidential clients must now present `client_secret`; public
+  clients are exempt because they have none, and PKCE is what authenticates them.
+- **Redirect URIs accepted script-bearing schemes.** Registration validated with
+  `z.string().url()`, which accepts anything the URL parser accepts — verified to
+  include `javascript:alert(1)` and
+  `data:text/html,<script>alert(1)</script>`. A redirect URI becomes a `Location`
+  header that the identity provider itself emits, so an organization admin could
+  register one and hand any user who authorized their application a redirect
+  toward script execution on the auth domain. Browser policy against top-level
+  `javascript:` navigation limits the practical impact, but on an identity
+  provider this is not an acceptable input. Registration now also rejects
+  wildcards, fragments, embedded credentials, and plaintext HTTP to non-loopback
+  hosts. A test records that `z.string().url()` accepted each of these.
+- **OIDC federation sent no nonce and verified none.** `state` proved the callback
+  belonged to a login this browser started, but nothing bound the returned ID
+  token to that login. Any ID token the provider considered valid was accepted,
+  including one minted for a different user or session. A nonce is now generated
+  per authorization request, kept in an httpOnly cookie, sent to the provider, and
+  required to match.
+- **ID token verification inferred rather than required.** Algorithms are now
+  pinned to RS256/ES256/PS256 instead of being derived from the key material, and
+  `exp`, `iat`, `iss`, `aud`, `sub` are required rather than validated only when
+  present — a token with no expiry was previously accepted indefinitely.
+
+### Changed
+
+- **Effective scopes are intersected, not trusted.** The client's `scope`
+  parameter was stored verbatim, with consent as the only filter. The effective
+  set is now registered ∩ requested ∩ consented, and a scope outside the
+  registration is refused with `invalid_scope` rather than silently dropped, so a
+  client asking for authority it was never granted is visible instead of quietly
+  downgraded. An empty `allowed_scopes` preserves existing behaviour.
+- **Public clients.** A `client_type` column distinguishes `confidential` from
+  `public`; a public client is issued no secret rather than a secret it is
+  expected to ignore, and a check constraint keeps the two halves consistent.
+  `client_secret_hash` is now nullable. PKCE is mandatory for a secretless client
+  at both `/authorize` and `/token`; the `verifyPKCE` branch that returned true
+  when no challenge was registered is gone.
+- **Redirect URIs are compared with one shared helper** at registration and at
+  use, so the two cannot drift. Exact string comparison throughout — no prefix
+  matching, no normalization, no case folding. The token endpoint's dead
+  `redirect_uri IS NULL` tolerance was removed: `redirect_uri` is required at
+  `/authorize`, so the branch was unreachable, and it would have accepted any
+  redirect URI had the field ever become optional.
+- **Refresh tokens carry the granted scope set** in a new `scopes` column, so the
+  authorization context survives rotation instead of being dropped at the first
+  refresh. A refresh may narrow the grant but never widen it.
+- **PKCE comparison is constant-time**, so a verifier cannot be recovered byte by
+  byte.
+
+### Already sound, verified rather than assumed
+
+Authorization code consumption was already atomic — a conditional `UPDATE` with
+`used_at IS NULL` and a required returned row — and is now covered by a
+concurrency test (20 parallel redemptions, exactly one winner). PKCE was already
+required at `/authorize` by the request schema, so the dead branch in
+`verifyPKCE` was a latent weakness rather than a live bypass. The refresh grant
+already validated client binding, MFA context, and organization membership.
+
+### Added
+
+- 42 tests: redirect URI registration and exact matching, PKCE verification,
+  scope intersection, client authentication at the token endpoint, public client
+  invariants, atomic code consumption, ID token verification against a locally
+  signed key (missing / wrong / replayed / expired nonce, no-expiry, wrong issuer,
+  wrong audience, foreign signing key), and scope preservation across rotation.
+
+## [2.3.0] - 2026-09-27
+
+### Security
+
+**Completing a password reset did not remove existing access.** It changed the
+password and left every session, every refresh token, and every other
+outstanding reset token working. A password reset is the standard response to a
+suspected compromise, so the previous behaviour defeated its own purpose: an
+attacker who triggered the reset kept their session and kept their access, while
+the victim believed they had locked the intruder out.
+
+- A successful reset now invalidates all sessions, all refresh tokens, and all
+  outstanding recovery credentials for the account.
+- Reset tokens issued alongside the one used are now spent, so a reset email
+  captured earlier cannot be completed after the user has already recovered.
+- Revocation is centralized in `src/services/sessionRevocation.ts`
+  (`revokeUserSessions`, `revokeRefreshTokens`,
+  `revokeAuthenticationSessions`, `revokeRecoveryCredentials`). It was
+  previously open-coded at each call site, which is how the most important site
+  came to omit it. The MFA-enablement path now routes through the same function,
+  so the rule cannot drift between the two.
+- Revocation is scoped to one user, is idempotent, and honours an exclusion for
+  a change the user makes to their own account.
+
+API keys are deliberately **not** revoked by a password reset. They are
+separately issued, long-lived credentials belonging to integrations rather than
+to the person, and killing them silently breaks deployments. The residual gap is
+real — a key minted by an attacker who already held the password survives — and
+key expiry and rotation is the right answer rather than coupling key lifetime to
+a human's password.
+
+### Already sound, verified rather than assumed
+
+- Recovery credentials are 384-bit `crypto.randomBytes`, stored only as a SHA-256
+  digest, single-use (since 2.2.0), valid for one hour, rate-limited to 5 per 15
+  minutes, and audited.
+- `POST /auth/forgot-password` returns `{ success: true }` on both the found and
+  not-found paths, so the response does not disclose whether an account exists.
+  (A residual timing difference remains, since the found path sends mail.)
+
+### Added
+
+- 9 tests, including that an attacker's session and refresh token do not survive
+  a reset, that an intercepted earlier reset token is dead, that a bystander's
+  credentials are untouched, and that the recovered user can still log in.
+
+## [2.2.0] - 2026-09-26
+
+### Security
+
+Three single-use credentials were validated with a conditional `SELECT` and then
+marked used with an **unconditional** `UPDATE`:
+
+```text
+SELECT ... WHERE used_at IS NULL      <- conditional
+if (!row) return
+UPDATE ... SET used_at = now()        <- UNCONDITIONAL: the race
+```
+
+Between those two statements, any number of concurrent requests pass the same
+check. Every one of them then succeeds.
+
+- **Magic links** could be redeemed by any number of parallel requests, each
+  producing a full login. A link that was meant to be usable once was usable
+  indefinitely under concurrency.
+- **Password reset tokens** could be spent by parallel requests, each writing a
+  different password, last writer winning. This was the most consequential of
+  the three: whoever won the race held the account, and an attacker racing the
+  legitimate user could take it over.
+- **SMS OTP codes** could be verified more than once concurrently, so a
+  six-digit code was not single-use.
+
+The fix is to make the write the gate rather than a follow-up:
+
+```text
+UPDATE ... SET used_at = now()
+WHERE token_hash = ? AND expires_at > now() AND used_at IS NULL
+RETURNING ...
+```
+
+PostgreSQL evaluates that predicate while holding a row lock, so exactly one
+transaction updates the row and observes a returned row. The claim and the
+validation become one statement with no window between them.
+
+The four other single-use credentials in scope were already atomic and were
+verified rather than assumed: refresh token rotation, MFA challenges, OAuth2
+authorization codes, and TOTP backup codes all perform a conditional update and
+require a returned row.
+
+### Added
+
+- `src/services/singleUse.ts` — one atomic claim and refusal-classification
+  primitive, used by all three credentials. Consumption now lives in one place,
+  so a credential cannot drift back into a hand-rolled read-then-write.
+- Replay detection. A credential presented after it was already spent now emits
+  `magic_link_replayed`, `sms_otp_replayed`, or
+  `password_reset_token_replayed`, all of which reach the audit log through the
+  event bus. Previously a replay was indistinguishable from a typo, so a leaked
+  token returning was invisible to an operator. An **expired** credential is
+  deliberately not reported as a replay, because that is not a leak.
+- 25 tests, including the plan's 10 / 50 / 100 concurrent-request levels against
+  every affected credential, and the same levels through the service entry points
+  a route actually calls.
+
+### Changed
+
+- `resetPasswordWithToken` now spends the token before doing any work, and
+  reports an expired link distinctly from an invalid one. Spending other live
+  reset tokens for the same user after a successful reset, since any were issued
+  alongside the one just used.
+
+## [2.1.0] - 2026-09-26
+
+### Security
+
+Four moderate advisories in the development tree, from `drizzle-kit` pulling
+`@esbuild-kit/esm-loader`, which pinned its own copy of `esbuild@0.18.20`
+(`GHSA-67mh-4wv8-2f99`, fixed in 0.25.0).
+
+The advisory allows a website to send requests to an esbuild **dev server** and
+read the response. Keystone never calls esbuild's `serve()` API, the packages
+are `devDependencies`, and `npm audit --omit=dev` was already clean, so this was
+not exploitable here. It was still a real advisory in the tree that builds and
+publishes the artifact, and `npm audit fix --force` offered only a downgrade of
+`drizzle-kit` to 0.18.1, which is a breaking change.
+
+Resolved with an `overrides` entry forcing `esbuild >= 0.25.0`, which collapses
+all three copies to 0.28.2 and clears the audit for production and development
+trees alike. Verified that `db:generate`, `db:migrate`, and `db:seed` all still
+work against the forced version, and that no non-dev package resolves esbuild.
+
+### Fixed
+
+- The published container image shipped 8 HIGH-severity advisories that no
+  JavaScript scanner can detect. `npm audit` and OSV both read
+  `package-lock.json` and correctly reported zero, because the vulnerable
+  packages are not in Keystone's dependency tree: they are the ones bundled
+  inside the base image's `npm@10.9.9` (`brace-expansion@2.0.2`,
+  `ip-address@10.1.0`, `pacote@19.0.2`, `picomatch@4.0.3`, `sigstore@3.1.0`).
+  The runtime image never invokes npm — `CMD` is `node dist/index.js`, and the
+  development compose override builds the `builder` target, which keeps its own
+  npm — so it is now removed from the production stage. This clears all 8 and
+  reduces the image from 600 MB to 550 MB.
+
+  Only container scanning finds this class of problem, which is why the gate
+  exists. Keystones own `brace-expansion@5.0.12` is already above the fixed
+  version and was never affected.
+
+### Added
+
+- `.github/dependabot.yml` — weekly updates for npm (root and frontend), GitHub
+  Actions, and Docker. Routine patches are grouped; security updates are not, so
+  a compromised package lands alone and identifiable.
+- `.github/workflows/supply-chain.yml` — OSV scanning (independent advisory
+  source from npm's), enforced `npm audit` over both trees, dependency review on
+  pull requests, SBOM generation, container scanning, and a license gate.
+- `npm run verify:release` — fails on a version that disagrees between
+  `package.json` and the lockfile, a dependency in one and not the other, a
+  missing or malformed license, or a missing `repository` field. Wired into both
+  CI and the release workflow so a bad artifact cannot be published.
+
+### Fixed
+
+- `package.json` declared no `license` field, despite shipping an MIT `LICENSE`
+  file. The published package carried no machine-readable terms.
+
+### Changed
+
+- Fastify is at 5.12.5 and `fast-uri` resolves to 3.1.8, both already above the
+  5.12.2 / 3.1.7 targets. No upgrade was required.
+- The license allowlist permits only permissive terms, with an explicit
+  exception for the pre-SPDX `MIT*` identifier that older packages emit.
+
+## [2.0.0] - 2026-09-26
+
+### Security
+
+The mTLS trust boundary trusted whatever the request said about itself. Any
+client that could reach Keystone could name a service account in a header and
+become it, and could set its own IP address to escape every rate limit. This
+release makes identity come only from values a client cannot forge.
+
+- **`x-service-account-id` no longer authenticates.** It previously resolved a
+  service account on its own, with no certificate and no credential, so anyone
+  who knew or guessed an account ID became that account. It is now read only as a
+  hint alongside a valid certificate, and only when the account it names is the
+  one that certificate is bound to. A mismatch is refused, not fallen back from.
+- **Client identity is bound to a certificate fingerprint.** A new unique
+  `service_accounts.cert_fingerprint` column pins a SHA-256 fingerprint to
+  exactly one account. Fingerprints are stored canonicalized, so the hex and
+  colon-separated spellings of one certificate cannot become two bindings, and
+  malformed values are rejected before reaching the database. Service accounts
+  are resolved by fingerprint rather than by their operator-chosen name.
+- **Identity headers are stripped from untrusted peers.** An `onRequest` hook
+  registered before every plugin and route removes
+  `x-forwarded-client-cert`, `x-client-cert-fingerprint`,
+  `x-forwarded-client-cert-chain`, `x-service-account-id`, `x-forwarded-for`,
+  `x-real-ip`, and `forwarded` unless the peer is a configured trusted proxy.
+  Stripping rather than ignoring means a route added later cannot read a
+  spoofed identity by accident.
+- **Rate limits can no longer be escaped.** The server was created with
+  `trustProxy: true` and the limiter read `x-forwarded-for` unconditionally, so
+  any client could present a fresh address per request and never be limited —
+  including against login, password reset, MFA verification, and SCIM. Limit keys
+  now come from the peer address unless a trusted proxy forwarded one.
+- **Trust decisions do not use `request.ip`.** With `trustProxy` enabled that
+  value is derived from the attacker-controlled header, so the trusted-proxy
+  check uses the socket peer address, the only value a client cannot set.
+- **Forwarded values are validated before use.** Certificate headers are
+  length-capped, and a fingerprint must be a well-formed SHA-256 digest, so
+  garbage cannot be used as a lookup key.
+- **Inactive and revoked service accounts cannot authenticate by certificate.**
+
+### Added
+
+- `KEYSTONE_TRUSTED_PROXIES` — comma-separated proxy IPs, IPv4 CIDRs, or IPv6
+  prefixes permitted to set client-identity headers. Unset by default, which
+  trusts nothing. IPv4-mapped IPv6 peers are normalized before matching, and
+  unrecognized input fails closed.
+- `PUT /v1/admin/organizations/:id/service-accounts/:accountId/certificate` —
+  bind or clear a client-certificate fingerprint, auditing
+  `service_account_certificate_bound` / `service_account_certificate_unbound`.
+  A certificate already held by another account returns `409`.
+- `POST /v1/admin/organizations/:id/service-accounts/:accountId/revoke` —
+  permanently stop an account authenticating, auditing
+  `service_account_revoked`. Revoking an already-revoked account returns `409`
+  rather than a silent success.
+- `docs/security/trust-boundaries.md`, `docs/security/proxy-security.md`, and
+  `docs/security/mtls.md` — the trust model, proxy requirements with working
+  nginx and ALB configuration, and the mTLS identity rules.
+- `docs/MIGRATION-2.0.md` — migration instructions, including the failure mode
+  that presents as unrelated clients sharing a rate-limit budget.
+
+### Fixed
+
+- The SCIM token-hash unique indexes introduced in 1.9.0 were declared in the
+  Drizzle schema but never emitted as a migration, so they did not exist in any
+  deployed database. They are created by migration `0015`.
+- The documented nginx configuration used `$proxy_add_x_forwarded_for`, which
+  appends to a client-supplied value and lets a client prepend a forged address.
+  Corrected to `$remote_addr`, with inbound identity headers stripped.
+
+### Changed
+
+- `trustProxy` is derived from `KEYSTONE_TRUSTED_PROXIES` instead of being
+  unconditionally `true`.
+- `requireMTLS` distinguishes an untrusted peer (`401 MTLS_UNTRUSTED_PEER`) from
+  a missing certificate (`401 MTLS_CERTIFICATE_MISSING`), so a misconfiguration
+  is distinguishable from an attack.
+
+### Breaking
+
+- mTLS clients that authenticated with `x-service-account-id` alone must bind a
+  certificate fingerprint instead.
+- Deployments behind a reverse proxy must set `KEYSTONE_TRUSTED_PROXIES`.
+  Without it, forwarded headers are stripped and every client shares one
+  rate-limit budget, so unrelated users can rate-limit each other.
+
 ## [1.9.0] - 2026-09-25
 
 ### Security