@hilbras/keystone 2.6.0 → 3.0.0

package/docs/MIGRATION-1.9.md

@@ -0,0 +1,200 @@
+# Migrating to Keystone 1.9.0
+
+Keystone 1.9.0 makes SCIM provisioning organization-scoped. In 1.8.x, SCIM was a
+pair of environment variables, which allowed exactly one organization in a
+deployment to be provisioned, stored the bearer token in plaintext, and reached
+through global user methods.
+
+Review this page before upgrading a production deployment.
+
+---
+
+## 1. SCIM credentials are now per organization
+
+| 1.8.x | 1.9.0 |
+| --- | --- |
+| `SCIM_BEARER_TOKEN` — one plaintext token, process-wide | A `scim_connections` row per organization, storing a SHA-256 digest |
+| `SCIM_ORG_ID` — one organization, process-wide | `org_id` on the connection, enforced by a foreign key |
+| No rotation, revocation, or expiry | Rotate, revoke, and expire through the connection API |
+| Token compared with `!==` in application code | Token resolved by digest lookup, so no timing signal |
+
+### What happens to your existing configuration automatically
+
+If `SCIM_BEARER_TOKEN` and `SCIM_ORG_ID` are still set at startup, Keystone adopts
+them **once** into a connection for `SCIM_ORG_ID` and logs a deprecation notice.
+Your existing identity provider keeps working with no downtime.
+
+Adoption is one-time. Once a connection exists for the organization, the
+environment variables are ignored — including after a revocation, so a restart
+cannot resurrect a credential you revoked.
+
+### Move to the connection API
+
+Remove the environment variables once the connection exists, then manage
+credentials through the API or the admin dashboard:
+
+```bash
+ORG=<organization-id>
+ADMIN_TOKEN=<platform owner access token>
+
+# Create (returns the bearer token once)
+curl -X POST "https://keystone.example.com/v1/admin/organizations/$ORG/scim-connections" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Okta","expiresInDays":365}'
+
+# Rotate
+curl -X POST "https://keystone.example.com/v1/admin/organizations/$ORG/scim-connections/$ID/rotate" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" -d '{}'
+
+# Revoke
+curl -X DELETE "https://keystone.example.com/v1/admin/organizations/$ORG/scim-connections/$ID" \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+Creating, rotating, and revoking are **owner-only**. A SCIM token can provision
+and deactivate tenant users, so a mere admin or member cannot mint one.
+
+The bearer token is shown exactly once. It is not recoverable afterwards, and
+listings show a four-character hint.
+
+---
+
+## 2. Deprovisioning no longer deactivates shared accounts
+
+This is the most important behavioural change for multi-tenant deployments.
+
+A user row is global. In 1.8.x, `DELETE /scim/v2/Users/:id` called the global
+`deactivate`, which revoked that person's sessions, refresh tokens, and API keys
+**in every organization they belonged to** — including organizations that
+credential had no relationship with.
+
+In 1.9.0:
+
+| Situation | Result |
+| --- | --- |
+| The organization was the user's only membership | Membership removed, account deactivated, sessions revoked |
+| The user also belongs to another organization | Membership removed from **this** organization only; the shared account is untouched |
+
+If your process relied on SCIM deletion disabling an account everywhere, you now
+need to remove the membership in each organization, or have a platform owner
+deactivate the account.
+
+### Writing global attributes of a shared user
+
+A user who belongs to more than one organization cannot have their global
+attributes changed through SCIM, because that would change what the other
+organizations see without their authorization. `PUT`, `PATCH`, and reactivation
+return `409` with `scimType: "mutability"`.
+
+Remove the membership from this organization instead.
+
+---
+
+## 3. Response codes
+
+| Case | 1.8.x | 1.9.0 |
+| --- | --- | --- |
+| Target belongs to another organization | `404` | `404` |
+| Target is a platform owner | `409` | `409` |
+| `userName` already exists elsewhere | `409` (named the other organization) | `409` (generic) |
+| Target is the last owner of the organization | `204` | `409` |
+| Target is a shared user being modified | `200` | `409` |
+| Malformed id in the path | `500` | `404` |
+| Invalid body | generic Fastify error | SCIM `Error` object |
+
+The conflict message no longer says which organization holds the account, so the
+endpoint is not a tenant oracle.
+
+---
+
+## 4. New endpoints
+
+### Users
+
+`PATCH /scim/v2/Users/:userId` and `POST /scim/v2/Users/.search` are new.
+`GET /Users` and `POST /Users/.search` accept `startIndex` and `count`, and
+`filter` supports the single-attribute `eq` form.
+
+`POST /Users` is now create-or-update: provisioning an existing member of the
+organization applies the profile fields in the body, which 1.8.x silently
+dropped.
+
+An unsupported filter is rejected with `400 invalidFilter` rather than ignored.
+Supported attributes are `userName` for users, and `displayName` and `externalId`
+for groups. `externalId` is **not** supported for users.
+
+### Groups
+
+`GET /scim/v2/Groups` previously returned a synthetic projection of organization
+roles, with ids of the form `<orgId>:<role>`. Those endpoints are removed.
+
+Groups are now real records scoped to the organization, with:
+
+```
+GET    /scim/v2/Groups
+POST   /scim/v2/Groups
+GET    /scim/v2/Groups/:groupId
+PUT    /scim/v2/Groups/:groupId
+PATCH  /scim/v2/Groups/:groupId
+DELETE /scim/v2/Groups/:groupId
+GET    /scim/v2/Groups/:groupId/members
+POST   /scim/v2/Groups/:groupId/members
+DELETE /scim/v2/Groups/:groupId/members/:userId
+```
+
+If an identity provider was reading the old role projection, it must be
+reconfigured to push its own groups.
+
+### Service discovery
+
+`GET /scim/v2/ServiceProviderConfig` and `GET /scim/v2/ResourceTypes` are new.
+
+---
+
+## 5. Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SCIM_ROTATION_GRACE_SECONDS` | `0` | Grace window for a rotated token |
+| `SCIM_RATE_LIMIT_MAX` | `600` | Requests per credential per window |
+| `SCIM_RATE_LIMIT_WINDOW_SECONDS` | `60` | Window for the above |
+| `SCIM_AUTH_FAILURE_MAX` | `60` | Unauthenticated requests per address per window |
+| `SCIM_AUTH_FAILURE_WINDOW_SECONDS` | `60` | Window for the above |
+
+`SCIM_BEARER_TOKEN` and `SCIM_ORG_ID` are deprecated and can be removed.
+
+Rotation revokes the previous token immediately. `rotationGraceSeconds` keeps it
+valid for a window, which avoids dropping in-flight provisioning — but it is not
+a revocation mechanism, so do not use a grace window when rotating in response to
+a leak. Revoke instead.
+
+---
+
+## 6. Operational notes
+
+- The connection's `lastUsedAt` is updated on every authenticated SCIM request,
+  which makes an unused or abandoned credential visible.
+- Revoked connections are retained as an audit trail and do not block a
+  replacement; a partial unique index enforces at most one live connection per
+  organization.
+- Every mutation records the connection id and organization in the audit row.
+  Credential lifecycle transitions emit `scim_connection_created`,
+  `scim_connection_rotated`, and `scim_connection_revoked`.
+
+---
+
+## Deployment checklist
+
+- [ ] Run `npm run db:migrate` before starting the new version.
+- [ ] Confirm SCIM still works with the automatically adopted connection.
+- [ ] Create a managed connection, move your identity provider onto it, then
+      remove `SCIM_BEARER_TOKEN` and `SCIM_ORG_ID`.
+- [ ] Set `expiresInDays` so credentials rotate on a schedule.
+- [ ] Check whether any process relied on SCIM deletion disabling an account
+      across all of that user's organizations.
+- [ ] Reconfigure any identity provider that read the old role-based group
+      projection.
+- [ ] Confirm your identity provider's filter attributes are supported
+      (`userName` for users; `displayName` and `externalId` for groups).

package/docs/MIGRATION-2.0.md

@@ -0,0 +1,203 @@
+# Migrating to Keystone 2.0.0
+
+Keystone 2.0.0 reworks the mTLS trust boundary. Before this release, any client
+that could reach Keystone could name a service account in a request header and
+become it, and could set its own IP address to escape every rate limit. Both are
+closed.
+
+**This is a breaking release.** Two behaviours change in ways that will break a
+deployment that relied on the old ones, and one of them fails silently until
+traffic arrives.
+
+Review this page before upgrading a production deployment.
+
+---
+
+## Summary
+
+| # | Change | Impact |
+| --- | --- | --- |
+| 1 | `x-service-account-id` no longer authenticates | **Breaking** — mTLS clients stop working until a certificate is bound |
+| 2 | `trustProxy` and `x-forwarded-for` are no longer believed by default | **Breaking, silent** — all clients behind a proxy share one rate-limit budget |
+| 3 | Service accounts bind to a certificate fingerprint | New: `cert_fingerprint` column, unique |
+| 4 | Service accounts can be revoked | New: `revoked_at` column, `POST .../revoke` |
+| 5 | Identity headers are stripped from untrusted peers | New: hardens any route reading them |
+
+A database migration runs automatically and is additive — no data is rewritten
+or dropped.
+
+---
+
+## 1. `x-service-account-id` no longer authenticates
+
+**Breaking.** Any mTLS integration that authenticated by sending only
+`x-service-account-id` stops working immediately.
+
+In 1.x, that header was sufficient on its own:
+
+```http
+GET /some/protected/route
+X-Service-Account-Id: 6f1c...-...
+```
+
+No certificate, no credential. Anyone who knew or guessed a service account ID
+became that account.
+
+In 2.0.0, a header never establishes identity. A service account must present
+either a client certificate whose fingerprint is bound to it, or an
+authenticated credential (API key, session, or bearer token).
+`x-service-account-id` is still read, but only as a hint alongside a valid
+certificate, and only when the account it names is the one the certificate is
+bound to. A mismatch is refused rather than falling back.
+
+### What to do
+
+If you were using this header, you need a client certificate and a binding:
+
+```bash
+# 1. Fingerprint of the caller's certificate
+openssl x509 -in client.pem -outform DER | openssl dgst -sha256 -hex
+
+# 2. Bind it to the service account
+curl -X PUT https://keystone.example/v1/admin/organizations/$ORG/service-accounts/$ACCOUNT/certificate \
+  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+  -d '{"fingerprint":"abcd...9f"}'
+```
+
+If your callers use API keys instead of certificates, nothing changes — that
+path was always credential-based.
+
+See [security/mtls.md](./security/mtls.md).
+
+---
+
+## 2. `x-forwarded-for` is no longer believed by default
+
+**Breaking, and it fails silently.** Read this one carefully.
+
+In 1.x the server was created with `trustProxy: true`, and the rate limiter read
+`x-forwarded-for` unconditionally. Two consequences:
+
+- Every client behind a proxy was attributed to its real address — which sounds
+  right, but was indistinguishable from a client claiming one.
+- Any client could send a fresh `x-forwarded-for` on every request and never hit
+  a rate limit. Authenticated endpoints with rate limits — login, password
+  reset, MFA verification, SCIM — were all reachable at full speed.
+
+In 2.0.0, forwarded headers are believed only when the request arrived from an
+address in `KEYSTONE_TRUSTED_PROXIES`. That variable is **unset by default**.
+
+**The failure mode:** behind a proxy with the variable unset, every request is
+attributed to the proxy's own address. All of your clients now share a single
+rate-limit budget. Login attempts across the whole deployment count against the
+same counter, so a burst of legitimate traffic from unrelated users will start
+returning `429` to everyone.
+
+This is deliberate — fail-closed, and the previous default was exploitable. But
+it must be configured for a proxied deployment.
+
+### What to do
+
+If Keystone sits behind a proxy, set the proxy's addresses:
+
+```bash
+KEYSTONE_TRUSTED_PROXIES="10.0.0.0/8,192.168.1.1"
+```
+
+Comma-separated exact IPs, IPv4 CIDRs, or IPv6 prefixes. Keep it as narrow as
+your deployment allows — trusting a shared CIDR lets any host in it assert any
+client identity. Leave it unset only when Keystone is genuinely exposed directly
+to clients.
+
+Then confirm your proxy **overwrites** rather than appends `x-forwarded-for`, and
+strips inbound identity headers. Both are required; see
+[security/proxy-security.md](./security/proxy-security.md).
+
+### Verifying
+
+```bash
+# From a host outside the trusted range: this must NOT be believed.
+curl -sS -H 'X-Forwarded-For: 198.51.100.9' https://keystone.example/health
+
+# Repeated logins from two "different" addresses must still share one budget.
+for ip in 198.51.100.1 198.51.100.2 198.51.100.3; do
+  curl -sS -o /dev/null -w '%{http_code} ' -H "X-Forwarded-For: $ip" \
+    https://keystone.example/auth/login -d '{}' -H 'Content-Type: application/json'
+done
+```
+
+Also watch for `429` spikes on `auth/login` after upgrading. That symptom means
+the trusted-proxy list is not set correctly.
+
+---
+
+## 3. Certificates are bound to a fingerprint
+
+New column `service_accounts.cert_fingerprint`, with a unique index. A
+certificate can map to at most one service account.
+
+Fingerprints are stored canonicalized, so the hex and colon-separated spellings
+of one certificate cannot become two bindings. A malformed fingerprint is
+rejected rather than stored.
+
+Existing service accounts have `cert_fingerprint = NULL` and continue to work
+with API keys. Only certificate authentication is affected.
+
+## 4. Service accounts can be revoked
+
+New column `service_accounts.revoked_at`, and:
+
+```http
+POST /v1/admin/organizations/:id/service-accounts/:accountId/revoke
+```
+
+Sets `is_active = false` and stamps `revoked_at`, stopping both certificate and
+API-key authentication. Revoking an already-revoked account returns `409`.
+
+Separate from `is_active` so that re-enabling does not silently restore access.
+
+## 5. Identity headers are stripped from untrusted peers
+
+A new `onRequest` hook deletes `x-forwarded-for`, `x-real-ip`, `forwarded`,
+`x-forwarded-client-cert`, `x-client-cert-fingerprint`, `x-service-account-id`,
+and `x-forwarded-client-cert-chain` from any request whose peer is not a trusted
+proxy.
+
+This runs before routing and before authentication, so a route cannot read a
+spoofed identity even by accident.
+
+**If you have custom middleware that reads these headers**, it will now see
+`undefined` for direct requests. That is intended. Such middleware was reading
+attacker-controlled data.
+
+---
+
+## New configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `KEYSTONE_TRUSTED_PROXIES` | unset (trust nothing) | Proxies permitted to set client-identity headers |
+
+---
+
+## Deployment checklist
+
+- [ ] Read [security/proxy-security.md](./security/proxy-security.md)
+- [ ] Set `KEYSTONE_TRUSTED_PROXIES` if Keystone is behind a proxy
+- [ ] Confirm the proxy **overwrites** `x-forwarded-for` and strips inbound identity headers
+- [ ] Confirm Keystone is not directly reachable from untrusted networks
+- [ ] Bind a certificate fingerprint to every mTLS service account (or confirm none use mTLS)
+- [ ] Verify logins are not being rate-limited across unrelated clients
+- [ ] Review any custom middleware that reads identity headers
+- [ ] Run the database migration (automatic on startup)
+- [ ] After upgrading, watch for `429` on `/auth/login` and `MTLS_UNTRUSTED_PEER` / `MTLS_UNTRUSTED_PEER`-adjacent `401`s
+
+## Rolling back
+
+The migration is additive — `cert_fingerprint` and `revoked_at` are nullable
+columns, and the new unique index is partial (non-null values only). Rolling
+back to 1.9.x leaves both columns in place and unused; nothing needs undoing
+manually.
+
+The application rollback is straightforward, but note that 1.9.x reintroduces the
+`x-service-account-id` bypass. Prefer fixing the configuration forward.

package/docs/MIGRATION-2.4.md

@@ -0,0 +1,185 @@
+# Migrating to Keystone 2.4.0
+
+Keystone 2.4.0 hardens the OAuth 2.0 / OIDC implementation. The most important
+change is that **the `authorization_code` grant now authenticates the client**,
+which is a breaking change for any integration that was not sending its secret.
+
+Review this page before upgrading a production deployment.
+
+---
+
+## 1. The authorization code grant requires a client secret
+
+**Breaking.**
+
+In 2.3.x the `authorization_code` grant looked the application up by
+`client_id` and redeemed the code without ever checking a client secret. RFC
+6749 §3.2.1 requires a confidential client to authenticate at the token
+endpoint, so the code and its PKCE verifier were the only factors protecting the
+exchange.
+
+From 2.4.0, a confidential client must present its `client_secret`:
+
+```bash
+# Before — accepted
+curl -X POST https://auth.example.com/oauth2/token \
+  -d grant_type=authorization_code -d code=... -d client_id=... -d redirect_uri=... -d code_verifier=...
+
+# After — 401 invalid_client
+# After — accepted
+curl -X POST https://auth.example.com/oauth2/token \
+  -d grant_type=authorization_code -d code=... -d client_id=... -d client_secret=... \
+  -d redirect_uri=... -d code_verifier=...
+```
+
+The secret may be sent in the body or via HTTP Basic authentication, as before.
+
+### What to do
+
+Add `client_secret` to your token request. If you are using Keystone's own SDK
+or drop-in, no change is needed — they already send it.
+
+### Public clients
+
+A client registered as `public` is **not** required to send a secret, because it
+has none. PKCE is mandatory for such a client at both `/authorize` and
+`/token`; a request without `code_challenge` is refused with
+`invalid_request`, and one without `code_verifier` with the same.
+
+Existing applications are unaffected: they are all `confidential` and keep
+their secrets.
+
+---
+
+## 2. Redirect URI registration is stricter
+
+**Potentially breaking** if you registered any of the rejected forms.
+
+Registration was validated with `z.string().url()`, which accepts anything the
+URL parser accepts. Now rejected:
+
+| Rejected | Why |
+| --- | --- |
+| `javascript:`, `data:`, `vbscript:`, `blob:`, `file:` | Would execute script or inline a document on the auth domain |
+| `https://*.example.com/cb`, any URI containing `*` | Can never match exactly; registered in the belief that it works |
+| `https://example.com/cb#token` | Fragments are never sent to the server, so an exact match can never succeed |
+| `https://user:pass@example.com/cb` | Embedded credentials are a phishing primitive |
+| `http://example.com/cb` | Plaintext HTTP downgrade. Still allowed on loopback for development |
+
+### What to do
+
+Check every registered redirect URI. If one is a wildcard, register each
+callback explicitly. If one uses plaintext HTTP against a real host, move it to
+HTTPS.
+
+**A validation that used to pass will now fail.** For example, registering
+`javascript:alert(1)` returned 201 before and returns 400 now, with a message
+naming the reason.
+
+Matching itself is unchanged and remains exact string comparison — no prefix
+matching, no normalization, no case folding. This was already the behaviour; it
+is now enforced through one shared helper so registration-time and use-time
+rules cannot drift.
+
+---
+
+## 3. Scope requests are validated against a registration
+
+**New, opt-in.** Applications with no registered scopes are unaffected.
+
+The effective scope set is now:
+
+```text
+registered scopes  ∩  requested scopes  ∩  consented scopes
+```
+
+A scope outside the registration is **refused** with `invalid_scope`, not
+silently dropped:
+
+```json
+{ "error": "invalid_scope", "error_description": "Scope \"admin:all\" is not available to this client" }
+```
+
+An empty `allowed_scopes` means "unrestricted", which preserves the previous
+behaviour for every existing application.
+
+### What to do
+
+Nothing, unless you want the extra control. To adopt it:
+
+```http
+PATCH /v1/admin/organizations/:orgId/applications/:appId
+
+{ "allowedScopes": ["openid", "profile", "email", "api:read"] }
+```
+
+From then on, requesting a scope outside that list is refused rather than
+granted. Scope names may contain letters, digits, `.`, `_`, `:`, `*`, and `-`.
+
+---
+
+## 4. OIDC federation now sends and verifies a nonce
+
+**Behavioural, no configuration needed.** Relevant only if you operate an
+external OIDC or SAML identity provider that Keystone federates with.
+
+Keystone now generates a nonce per authorization request, stores it in an
+httpOnly `oauth_nonce` cookie, sends it to the provider, and requires the
+returned ID token to carry the same value.
+
+If your identity provider does not echo the nonce into its ID token,
+federated logins will fail with a nonce mismatch. Well-behaved providers —
+anything implementing OpenID Connect Discovery, which requires nonce support when
+a nonce is sent — echo it correctly.
+
+Two related changes to ID token verification: the algorithm set is now pinned
+(RS256, ES256, PS256) and `exp`, `iat`, `iss`, `aud`, `sub` are required rather
+than validated only when present. A provider issuing tokens without an `iat` or
+without a `sub` will now be refused.
+
+---
+
+## 5. Refresh tokens carry their granted scopes
+
+**New column, no action required.**
+
+`refresh_tokens.scopes` records the scope set granted at the authorization step,
+and rotation carries it forward. Previously the context was dropped at the first
+refresh.
+
+A refresh may narrow the grant but never widen it: the stored set is
+authoritative, and nothing a caller supplies at the token endpoint can extend it.
+
+---
+
+## New API surface
+
+| Field / parameter | Where | Notes |
+| --- | --- | --- |
+| `clientType` | `POST`/`PATCH` application | `"confidential"` (default) or `"public"`. A public client is issued no secret |
+| `allowedScopes` | `POST`/`PATCH` application | Registration of requestable scopes. Empty means unrestricted |
+| `clientSecret` | `POST` application response | Now `null` for a public client |
+
+## Migration order
+
+The database migration (`0016`, `0017`) is additive: `client_secret_hash`
+becomes nullable, and `client_type`, `allowed_scopes`, and
+`refresh_tokens.scopes` are added with defaults. Existing rows are unaffected —
+every existing application stays `confidential` with its secret intact.
+
+- [ ] Add `client_secret` to every authorization-code token request
+- [ ] Audit registered redirect URIs against the new rules
+- [ ] Optionally register `allowedScopes` on your applications
+- [ ] Confirm your external identity provider echoes the OIDC nonce and issues `iat` and `sub`
+- [ ] Run the database migrations (automatic on startup)
+- [ ] Watch for `invalid_client` at the token endpoint and `invalid_scope` at `/authorize`
+
+## Rolling back
+
+The migration is additive and every new column is nullable or has a default, so
+rolling back to 2.3.x leaves them in place and unused. Nothing needs undoing
+manually.
+
+The application rollback is straightforward, but 2.3.x reintroduces both the
+missing client authentication and the `javascript:` redirect URI acceptance.
+Prefer fixing the integration forward.