@hilbras/keystone 1.6.0 → 2.5.0

package/CHANGELOG.md

@@ -5,6 +5,630 @@ 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.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
+
+SCIM was a single global credential. In 1.8.x a deployment could provision
+exactly one organization, the bearer token was stored and compared in plaintext,
+and mutations reached global user records.
+
+- SCIM credentials are per-organization. Every connection belongs to exactly one
+  organization, at most one is live per organization, and every user and group
+  read and write is filtered by it. A cross-tenant target returns `404`, so the
+  endpoint is not a tenant oracle.
+- Bearer tokens are stored only as a SHA-256 digest and resolved by that digest,
+  so a database dump yields no usable token and the comparison carries no timing
+  signal. Connections can expire, be rotated, and be revoked.
+- Issuing, rotating, and revoking a SCIM credential is owner-only. A SCIM token
+  provisions and deactivates tenant users, so a mere admin or member cannot mint
+  one.
+- Deprovisioning removes the organization's membership and deactivates the
+  account only when no membership remains. Previously it deactivated a shared
+  account in every organization that user belonged to, without those
+  organizations' authorization.
+- SCIM refuses to change the global attributes of a shared user, to reactivate a
+  shared account, and to remove the last owner of an organization.
+- SCIM can no longer attach a user who already belongs to another organization,
+  and the conflict message no longer names the organization that holds them.
+- Unauthenticated SCIM traffic is budgeted before the authentication hook emits
+  audit and webhook events, closing an unauthenticated write-amplification path.
+- SCIM request budgets are keyed per credential, so one noisy identity provider
+  cannot exhaust every other tenant's allowance.
+
+### Changed
+
+- `SCIM_BEARER_TOKEN` and `SCIM_ORG_ID` are deprecated. They are adopted once
+  into a connection at startup and then ignored, so an upgrade does not break an
+  existing identity provider. Adoption is one-time in any state, so a restart
+  cannot resurrect a revoked credential.
+- Deprovisioning a single-tenant user now removes the membership as well as
+  deactivating the account. Deprovisioning a shared user removes only the
+  membership, and a follow-up `DELETE` returns `404`.
+- `POST /scim/v2/Users` is create-or-update; profile fields for an existing
+  member are applied rather than dropped.
+- A user removed from an organization can be re-provisioned. Previously the
+  global email lookup found the inactive row and returned `409` forever.
+- Rotating a credential revokes the previous token immediately
+  (`SCIM_ROTATION_GRACE_SECONDS` defaults to `0`). A grace window is now an
+  explicit opt-in and is not a revocation mechanism.
+- Groups are real organization-scoped records. The synthetic role-bucket
+  projection (`<orgId>:<role>` ids) is removed.
+- Malformed path ids return a SCIM `404` instead of surfacing a driver error, and
+  validation and internal failures return SCIM `Error` objects.
+
+### Added
+
+- `scim_connections` with rotation, revocation, expiry, and a token hint.
+- `scim_groups` and `scim_group_members`, organization-scoped throughout.
+- `PATCH /scim/v2/Users/:userId` and `POST /scim/v2/Users/.search`.
+- Group create, replace, patch, delete, and member management endpoints.
+- `filter`, `startIndex`, and `count` on list endpoints; unsupported filters are
+  rejected rather than silently ignored.
+- `GET /scim/v2/ServiceProviderConfig` and `GET /scim/v2/ResourceTypes`.
+- Owner-only admin API for creating, listing, rotating, and revoking SCIM
+  connections, with a dashboard UI for the same.
+- `findByIdInOrg`, `updateInOrg`, `listOrgIdsForUser`, and `removeFromOrg`
+  repository methods for organization-scoped user access.
+- Audit events `scim_connection_created`, `scim_connection_rotated`,
+  `scim_connection_revoked`, `scim_access_denied`, `scim_authentication_failed`,
+  and the `scim_group_*` group events.
+- `docs/MIGRATION-1.9.md`.
+
+## [1.8.0] - 2026-09-25
+
+### Security
+
+MFA was advisory in 1.7.x. A user with TOTP enabled could sign in with only a
+password, and when a code was supplied it was verified *after* the access token,
+refresh token, and session had already been created. 1.8.0 makes the second
+factor mandatory.
+
+- Password authentication now stops at `requires_mfa` for MFA-enabled accounts.
+  No access token, refresh token, or session row is created at that stage.
+- New `POST /auth/mfa/verify` completes the transition. The challenge is opaque,
+  stored only as a hash, short-lived, single-use, and bounded by an attempt
+  budget enforced in the database.
+- Token issuance is guarded at a single chokepoint. A token cannot be minted for
+  an MFA-enabled user without a recorded factor, so no login path bypasses MFA by
+  omission.
+- TOTP verification uses the user's own decrypted secret. Each time-step is
+  accepted exactly once, so a captured code is rejected even against a freshly
+  issued challenge.
+- Enabling MFA revokes every existing refresh token and session for the account.
+  Sessions record how MFA was satisfied, and refresh rotation refuses sessions
+  with no recorded factor.
+- Backup codes carry 80 bits of entropy, are stored as a keyed (peppered) hash,
+  expire after 90 days, and are consumed by a conditional update so concurrent
+  use has exactly one winner.
+- TOTP secrets are written with AES-256-GCM. Values written by earlier versions
+  used AES-256-CBC and remain readable.
+
+### Changed
+
+- `POST /auth/login` and `POST /auth/token-login` return `401` with
+  `code: "MFA_REQUIRED"` and a challenge when MFA is required. See
+  [MIGRATION-1.8.md](docs/MIGRATION-1.8.md).
+- The undocumented `totp_code` field on the login endpoints is removed and
+  ignored.
+- `POST /auth/totp/backup` now regenerates backup codes and requires a current
+  TOTP code. `POST /auth/totp/backup/verify` consumes a backup code.
+- `POST /auth/totp/verify` additionally reports `sessionsRevoked`.
+- WebAuthn assertions satisfy MFA on their own. Magic links refuse to downgrade a
+  TOTP-protected account, and SAML, enterprise OIDC, federation, and OAuth2
+  report a typed `mfa_required` error.
+- OAuth2 authorization codes carry the MFA factor of the session that approved
+  them, so the token exchange cannot launder an unverified login.
+- Access tokens for MFA sessions carry `mfa_verified`, `mfa_factor`, and `amr`.
+- Factor management requires step-up: `/auth/totp/enroll`, `/auth/totp/verify`,
+  `/auth/totp/backup`, `/auth/totp/disable`, and passkey registration for a
+  TOTP-protected account all require the account password in addition to the
+  session.
+- A passkey registered after TOTP was enabled is treated as a single factor and
+  cannot be used to sign in on its own.
+- Disabling TOTP deletes its backup codes.
+- Failed MFA factor attempts count toward the account lockout.
+- `SDK.authentication.login()` returns a discriminated union; `completeMfa()` is
+  new.
+
+### Fixed
+
+- `/auth/mfa/verify` wrote session cookies under a name derived from the login
+  flow instead of the client id, so MFA-completed sessions were not readable by
+  the auth plugin and every application on the cookie domain shared one name.
+- The MFA step no longer accepted accounts that are deactivated, under review,
+  or locked out, which the password step already refused.
+- Repeated password steps no longer cancel an MFA challenge created moments
+  earlier.
+- `MFA_CHALLENGE_TTL_SECONDS`, `MFA_MAX_ATTEMPTS`, and
+  `TOTP_BACKUP_CODE_TTL_SECONDS` are validated at startup and fall back to their
+  defaults instead of silently breaking every login.
+- The MFA factor copied out of a verified token into the authorization-code
+  table is validated against the column's check constraint.
+- SAML now reports `mfa_required` for MFA-protected accounts instead of
+  collapsing the failure into a generic validation error.
+
+### Added
+
+- `mfa_challenges` table, `MfaChallengeRepository`, and `MfaService`.
+- `MFA_CHALLENGE_TTL_SECONDS`, `MFA_MAX_ATTEMPTS`, and
+  `TOTP_BACKUP_CODE_TTL_SECONDS` configuration.
+- Audit events `mfa_challenge_created`, `mfa_challenge_failed`,
+  `mfa_challenge_expired`, `mfa_challenge_rejected`, `mfa_verified`,
+  `mfa_bypass_blocked`, and `mfa_backup_code_regenerated`.
+- Dedicated rate limits for MFA verification and every TOTP management endpoint.
+- MFA challenge step in the admin dashboard login form.
+- `docs/MIGRATION-1.8.md`.
+- MFA security regression suite (`src/tests/security/mfa.test.ts`).
+
+## [1.7.0] - 2026-09-24
+
+### Added
+
+- Dedicated owner-only platform-role endpoint at `PATCH /v1/admin/platform/users/:userId/role`.
+- Centralized platform and organization authorization guards with explicit organization context.
+- Versioned audit events for platform-role, membership, permission, and denied-authorization transitions.
+- Dedicated authorization regression suite covering privilege escalation, tenant isolation, workflow safety, secret disclosure, and audit metadata.
+- RBAC and authorization-boundary documentation.
+
+### Changed
+
+- Platform roles are explicitly limited to `owner` and `user`.
+- Organization roles are explicitly limited to `owner`, `admin`, and `member`.
+- Authorization checks now require an explicit `organizationId`.
+- Frontend administration clients use the dedicated platform-role endpoint and safe workflow definitions.
+- SAML metadata lookups require both connection and organization identifiers.
+
+### Fixed
+
+- Organization user routes can no longer mutate global users or deactivate shared accounts.
+- Generic profile and in-process identity contracts can no longer carry a platform role.
+- Organization admins cannot promote themselves or other members to organization owner.
+- The sole organization owner cannot be demoted or removed.
+- Tenant workflows now use a closed safe-step allowlist; plugin aliases, arbitrary webhooks, organization creation, and authorization-mutating steps fail closed.
+- Global workflows require platform-owner access, and workflow execution rechecks organization membership.
+- Organization creation always assigns an owner; actorless global deactivation APIs were removed from the organization domain.
+- Last-owner transitions use database row locks to prevent concurrent demotion/removal.
+- Platform-user deactivation now disables login, invalidates existing sessions, revokes refresh tokens and user API keys, and preserves the last active owner invariant.
+- User-management responses redact application secret hashes, OIDC/API-key credentials, configuration values, password hashes, TOTP secrets, and metadata.
+- SAML/OIDC public lookups require an organization context; new OIDC client secrets are encrypted at rest, and legacy plaintext values are re-encrypted on first callback use.
+- OAuth/OIDC client context no longer places an organization claim in a user token unless the user is a member of that application's organization.
+- Failed authorization attempts and role transitions now produce structured audit evidence.
+- SAML schema validation now has a signed-response regression test and audience/destination/recipient checks, alongside one-time transaction claiming and OIDC ID-token/JWKS verification.
+- Enterprise SSO requires an explicit connection/subject identity link and rejects platform-owner tenant login; generic OAuth no longer auto-links by email.
+- SCIM is scoped to `SCIM_ORG_ID`, cannot re-enable quarantined or platform-owner accounts, attributes audits to the SCIM credential, and deactivates rather than deleting users.
+- OIDC endpoint checks cover private, carrier-grade, benchmarking, dotted/hex IPv4-mapped, DNS-pinned, and redirecting targets.
+- Legacy account migration quarantines ambiguous unverified rows instead of activating them.
+- SAML semantic validation and OIDC/JWKS checks are covered by signed-response tests; OAuth2 refresh success and failure emit audit events.
+- Refresh-token rotation and OAuth authorization-code consumption are atomic and client-bound.
+- Legacy unverified accounts are quarantined for explicit review during the deactivation migration.
+- OIDC endpoint configuration blocks private/redirected targets by default; SCIM reflects account deactivation.
+- Added a blocking `oxlint` gate with warnings denied; CI now runs lint separately from typecheck.
+- Pinned safe transitive versions for `@xmldom/xmldom`, `fast-uri`, and `find-my-way`; the High-severity production audit gate now passes.
+- API-key validation uses public user projections and emits `api_key_used` audit events; the compiled OIDC re-encryption helper closes its database pool before exit.
+
+### Security
+
+- Critical organization-admin-to-platform-owner escalation paths are closed at HTTP, application, domain, SDK, and repository boundaries.
+- Cross-tenant authorization context is resolved from authenticated database membership rather than client-controlled application context.
+- Workflow definitions that are malformed or contain blocked authorization steps fail closed.
+
+### Breaking Changes
+
+- Organization user PATCH/DELETE endpoints no longer mutate global accounts; they return a migration response. Use platform user administration or organization member endpoints.
+- `/v1/authz/check` requests must include `organizationId`.
+- Custom organization role names are no longer accepted; only `owner`, `admin`, and `member` are supported.
+- Public SAML/OIDC initiation and metadata URLs require `organizationId`.
+- Direct authorization SDK calls now require both actor and organization IDs.
+- OIDC connections require a JWKS URI; OAuth2 application-bound refresh requests must provide the bound `client_id` and `client_secret`.
+- SCIM requires both `SCIM_BEARER_TOKEN` and `SCIM_ORG_ID`, and operates only within that organization.
+- Legacy unverified accounts may be marked `account_review_required` and require explicit review.
+- Tenant workflow definitions containing authorization-mutating, plugin, organization-creation, or arbitrary webhook steps are rejected or blocked.
+
+### Migration
+
+- Move platform role changes to `PATCH /v1/admin/platform/users/:userId/role`.
+- Use `/v1/admin/organizations/:id/members/:userId` for organization role changes.
+- Remove unsafe workflow steps before deployment.
+- Update SAML/OIDC URLs to include the organization ID.
+- Update authorization-check clients to send the organization ID explicitly.
+
+### Dependencies
+
+- No dependency changes in this release. Existing dependency audit findings remain tracked for the planned supply-chain phase.
+
+### Testing
+
+- Backend typecheck and build pass.
+- Backend test suite passes with the security regression suite enabled.
+- Frontend production build passes.
+
 ## [1.1.0] - 2026-09-19
 
 Security hardening, architecture improvements, and enterprise SSO enhancements.
@@ -144,6 +768,7 @@ Frontend upgrades — React 19, Vite 8, Tailwind 4, TypeScript 7.
 - `postcss.config.js` deleted — Tailwind 4 uses Vite plugin directly.
 - `src/index.css` updated to use `@import "./tailwind.css"` instead of `@tailwind base/components/utilities`.
 
+[1.7.0]: https://github.com/Hilbras/Keystone/releases/tag/v1.7.0
 [1.6.0]: https://github.com/Hilbras/Keystone/releases/tag/v1.6.0
 [1.5.0]: https://github.com/Hilbras/Keystone/releases/tag/v1.5.0
 [1.4.0]: https://github.com/Hilbras/Keystone/releases/tag/v1.4.0