@hilbras/keystone 2.6.0 → 3.0.0

package/docs/PERFORMANCE.md

@@ -0,0 +1,155 @@
+# Performance and Memory Optimization
+
+This guide explains why Keystone may feel heavy during local development and how to run it efficiently in production.
+
+---
+
+## Why it feels heavy during development
+
+### 1. Development tools use more memory
+
+When you run `./start.sh`, the backend starts with:
+
+```bash
+npx tsx watch src/index.ts
+```
+
+`tsx watch` keeps a TypeScript compiler in memory and recompiles files on every change. This is convenient but uses more RAM than a compiled build.
+
+The frontend runs:
+
+```bash
+npm run dev   # Vite dev server
+```
+
+Vite also keeps modules in memory for fast hot reload.
+
+**Typical dev memory usage:**
+
+| Process | Memory |
+|---------|--------|
+| Backend (`tsx watch`) | ~200–400 MB |
+| Frontend (`vite dev`) | ~150–300 MB |
+| PostgreSQL container | ~100–200 MB |
+| Redis container | ~10–50 MB |
+| Browsers | 500 MB–2 GB |
+
+### 2. Stale processes accumulate
+
+If `./start.sh` is run multiple times or crashes, old `tsx watch` and `vite` processes may stay alive and continue using memory and ports.
+
+### 3. `node_modules` is large
+
+Node projects naturally have large dependency trees:
+
+```
+413 MB   total node_modules across backend + frontend + SDK
+```
+
+This is disk space, not RAM, but it makes the project feel heavy.
+
+---
+
+## Quick fixes
+
+### Kill stale processes
+
+The latest `start.sh` does this automatically. If you still see old processes:
+
+```bash
+./scripts/kill-keystone.sh
+```
+
+Or manually:
+
+```bash
+pkill -f "tsx watch src/index.ts"
+pkill -f "tsx watch src/setup-server.ts"
+pkill -f "frontend/node_modules/.bin/vite"
+```
+
+### Run in production mode
+
+After building:
+
+```bash
+npm run build:all
+./start.sh --production
+```
+
+This uses `node dist/index.js` instead of `tsx watch`, which uses significantly less memory.
+
+### Stop the frontend if you only need the API
+
+If you are integrating an external app and do not need the admin UI:
+
+```bash
+npm start   # backend only
+```
+
+---
+
+## Production deployment optimizations
+
+1. **Use `npm start` or `node dist/index.js`** — never `tsx watch` in production.
+2. **Run with `NODE_ENV=production`** — this disables development logging and tracing overhead.
+3. **Disable OpenTelemetry if not needed** — remove `OTEL_EXPORTER_OTLP_ENDPOINT` from `.env`.
+4. **Use managed PostgreSQL and Redis** — reduces local container overhead.
+5. **Use a process manager** like systemd, PM2, or Docker Compose with restart policies.
+6. **Build the frontend once** and serve the `dist/` folder with Nginx/Caddy instead of `vite dev`.
+
+### Example systemd service
+
+```ini
+[Unit]
+Description=Hilbras Keystone
+After=network.target
+
+[Service]
+Type=simple
+User=keystone
+WorkingDirectory=/opt/keystone
+ExecStart=/usr/bin/node dist/index.js
+Restart=always
+RestartSec=5
+Environment=NODE_ENV=production
+EnvironmentFile=/opt/keystone/.env
+
+[Install]
+WantedBy=multi-user.target
+```
+
+---
+
+## Reducing bundle size
+
+The admin frontend bundle is currently:
+
+```
+252 KB   index.js (gzipped)
+24 KB    index.css (gzipped)
+```
+
+If you need to reduce it further:
+
+- Use route-based code splitting.
+- Lazy-load heavy panels (organizations, audit logs, billing).
+- Remove unused Lucide icons by importing only the ones used.
+
+---
+
+## Monitoring memory
+
+Check Keystone memory usage:
+
+```bash
+ps -eo pid,ppid,%mem,rss,args | grep "node dist/index.js" | grep -v grep
+```
+
+Check Docker container resources:
+
+```bash
+docker stats --no-stream
+```
+
+If memory keeps growing after running for hours, it may be a leak. Enable heap snapshots or contact the maintainers.

package/docs/RBAC.md

@@ -0,0 +1,100 @@
+# Keystone RBAC and Authorization Boundaries
+
+## Role namespaces
+
+Keystone maintains two independent role namespaces.
+
+| Namespace | Stored in | Values | Scope |
+| --- | --- | --- | --- |
+| Platform role | `users.role` | `owner`, `user` | The entire Keystone installation |
+| Organization role | `org_memberships.role` | `owner`, `admin`, `member` | One organization membership |
+
+An organization `owner` is not a platform `owner`. Organization membership roles are never copied into `users.role`, and organization APIs cannot modify platform roles.
+
+## Platform administration
+
+Only a platform owner can:
+
+- Change a platform role through `PATCH /v1/admin/platform/users/:userId/role`.
+- Administer platform users, applications, webhooks, configuration, and global audit logs.
+- Change role-permission mappings.
+
+The platform role endpoint accepts only:
+
+```json
+{ "role": "owner" }
+```
+
+or:
+
+```json
+{ "role": "user" }
+```
+
+The last platform owner cannot be demoted. Generic user profile updates do not accept a `role` field.
+
+## Organization membership
+
+Organization membership is always resolved by the pair `(organizationId, userId)`.
+
+- `owner` can manage memberships and grant organization-owner access.
+- `admin` can manage members and administrators, but cannot grant or modify `owner` access.
+- `member` cannot manage memberships.
+- The sole organization owner cannot be demoted or removed.
+- Membership reads and writes never grant platform privileges.
+
+Use the membership endpoints for organization roles:
+
+```text
+PATCH /v1/admin/organizations/:organizationId/members/:userId
+DELETE /v1/admin/organizations/:organizationId/members/:userId
+```
+
+The legacy organization user PATCH/DELETE routes do not mutate global accounts. Use the platform user administration route for account-wide changes.
+
+## Authorization evaluation
+
+Organization permission checks resolve the authenticated actor and route organization explicitly. The internal authorization SDK also requires `userId` and `organizationId`; a bare role string is not a valid cross-tenant authorization decision. Client-supplied application or origin context is not sufficient to establish membership.
+
+For `/v1/authz/check`, provide the organization being evaluated:
+
+```json
+{
+  "organizationId": "00000000-0000-0000-0000-000000000000",
+  "resource": "application",
+  "action": "read"
+}
+```
+
+A user who is not a member of that organization receives `403`; an absent or invalid organization context is not treated as authorization. OAuth/OIDC client context never grants organization claims unless the authenticated user is a member of the application's organization.
+
+## Tenant workflows
+
+Organization workflows may use safe notification and email steps. They cannot:
+
+- Assign a platform or organization role.
+- Add a user to an arbitrary organization.
+- Add a user through an arbitrary application client ID.
+- Send tenant data to arbitrary webhook URLs.
+
+Unsafe or malformed persisted workflow definitions fail closed and are recorded as blocked runs.
+
+## Audit records
+
+Security-relevant transitions emit versioned events with structured metadata, including:
+
+- Actor and target user.
+- Organization and application context.
+- Previous and new state.
+- Request ID, IP address, and user agent where available.
+
+Role, membership, permission, and denied-authorization changes are retained in the audit log. Audit records are asynchronous and should be monitored for subscriber failures in production.
+
+## Migration from v1.6.x
+
+1. Replace organization user PATCH calls that intended to change a platform role with the dedicated platform role endpoint.
+2. Replace organization user deactivation calls with a platform-owner workflow.
+3. Use `/members/:userId` for organization role changes.
+4. Remove workflow definitions containing `assign_role`, `add_membership`, or `add_app_membership` before deployment.
+5. Include `organizationId` in authorization-check requests.
+6. Review existing organization user clients for reliance on password hashes, TOTP secrets, or other internal user fields; those fields are no longer returned.

package/docs/RE-AUDIT.md

@@ -0,0 +1,72 @@
+# v3.0.0 re-audit matrix
+
+<!-- Generated by scripts/render-reaudit-matrix.mjs. Do not edit by hand. -->
+
+Each cell is verified against the repository when this file is generated, not asserted. `Regression Test` is **Yes** only if the named file exists and contains a test; `Fixed` only if the fix site still exists. Deleting a test turns the cell red on the next run rather than leaving a stale assurance behind.
+
+| Finding | Original severity | Findings | Fixed | Regression test | Documentation | Entries |
+| --- | --- | --- | --- | --- | --- | --- |
+| Privilege escalation | Critical | 8 | Yes | Yes | Yes | SEC-001, SEC-002, SEC-003, SEC-007, SEC-023, SEC-025, SEC-028, SEC-032 |
+| MFA bypass | Critical | 4 | Yes | Yes | Yes | SEC-004, SEC-005, SEC-015, SEC-034 |
+| SCIM isolation | Critical | 1 | Yes | Yes | Yes | SEC-006 |
+| mTLS trust | Critical | 3 | Yes | Yes | Yes | SEC-007, SEC-009, SEC-010 |
+| Fastify vulnerability | High | 1 | Yes | Yes | Yes | SEC-011 |
+| fast-uri vulnerabilities | High | 1 | Yes | Yes | Yes | SEC-011 |
+| Rate limiting | High | 5 | Yes | Yes | Yes | SEC-008, SEC-033, SEC-034, SEC-035, SEC-039 |
+| Token races | High | 3 | Yes | Yes | Yes | SEC-012, SEC-013, SEC-038 |
+| Session invalidation | High | 3 | Yes | Yes | Yes | SEC-014, SEC-015, SEC-038 |
+| OAuth hardening | High | 5 | Yes | Yes | Yes | SEC-016, SEC-017, SEC-018, SEC-019, SEC-020 |
+| SAML hardening | Medium | 2 | Yes | Yes | Yes | SEC-021, SEC-022 |
+| Secrets | High | 4 | Yes | Yes | Yes | SEC-026, SEC-029, SEC-030, SEC-031 |
+| CORS | High | 2 | Yes | Yes | Yes | SEC-027, SEC-028 |
+| CI security | High | 6 | Yes | Yes | Yes | SEC-011, SEC-040, SEC-041, SEC-042, SEC-045, SEC-046 |
+| Abuse prevention | High | 5 | Yes | Yes | Yes | SEC-033, SEC-035, SEC-036, SEC-037, SEC-039 |
+| Audit integrity | High | 4 | Yes | Yes | Yes | SEC-036, SEC-037, SEC-045, SEC-046 |
+| Supply chain | High | 1 | Yes | Yes | Yes | SEC-011 |
+| Test integrity | High | 3 | Yes | Yes | Yes | SEC-040, SEC-041, SEC-042 |
+
+## API security review
+
+Every route enumerated from source and checked for a guard. Result in
+[`docs/API-REVIEW.md`](./API-REVIEW.md).
+
+**69 routes. Zero with no authentication guard.** 27 carry no route-level
+authorization and each was traced: SCIM’s bearer token *is* the authorization,
+`GET /me` returns the caller’s own profile, the OAuth authorize endpoint
+authenticates in the request, and `workflows.ts` checks membership in the handler.
+
+One structural weakness found: `workflows.ts` does its organization check inside
+each of five handlers rather than in a guard, so a sixth route added later would
+have no reason to include it. Not a live vulnerability — the checks are correct —
+but the only module in the codebase that does it this way.
+
+## Unresolved Critical findings
+
+None. Every finding the plan classifies as Critical is fixed, has a regression test, and is documented.
+
+## Withdrawn entries
+
+Recorded rather than renumbered, so every id already cited elsewhere keeps its meaning.
+
+### SEC-043 — withdrawn 2026-09-27
+
+Written during the 2.9.0 release with a fix at a path that does not exist and an issue description the test does not cover. src/tests/security/saml/saml-validator.test.ts exercises the *valid* signed-response path; it does not test a missing audience or issuer requirement. There is no evidenced defect behind this entry, so it was not a finding. The suite is recorded under `coverage` instead.
+
+### SEC-044 — withdrawn 2026-09-27
+
+Written during the 2.9.0 release with a fix at a path that does not exist and an issue description the test does not cover. src/tests/security/saml/sso-endpoint.test.ts tests isPrivateAddress, a guard on operator-supplied endpoint addresses; it does not test an unregistered host alias. No defect was evidenced behind this entry. The suite is recorded under `coverage` instead.
+
+## Coverage without a numbered finding
+
+Suites that assert a property but do not correspond to a defect we can evidence. Recording these as findings to satisfy a completeness check is how a registry starts asserting things nobody checked.
+
+- `src/tests/security/saml/saml-validator.test.ts` — A valid signed SAML response is accepted by the registered schema validator, and validateSamlSemantics accepts it.
+  Positive-path coverage for the SAML validator. Not tied to a numbered finding: it asserts that a correct response is accepted, not that a previously-missing check was added.
+- `src/tests/security/saml/sso-endpoint.test.ts` — isPrivateAddress classifies loopback, private, link-local, carrier-grade NAT, benchmarking and both spellings of IPv4-mapped IPv6 as non-public.
+  Coverage for the endpoint address policy in src/services/ssoEndpointPolicy.ts, which keeps operator-supplied SSO endpoint URLs from pointing at internal addresses. No defect was evidenced behind it, so it is not a numbered finding.
+
+## Coverage
+
+- 44 findings recorded in `docs/security/registry.json`.
+- 44 of 44 verified to have a regression test present right now.
+- 6 critical, 25 high, 12 medium, 1 low.

package/docs/README.md

@@ -0,0 +1,54 @@
+# Hilbras Keystone Documentation
+
+Complete documentation for the Hilbras Keystone identity platform.
+
+## Getting started
+
+| Document | Purpose |
+| --- | --- |
+| [README](../README.md) | Feature overview, quick start, environment reference |
+| [Installation & deployment](DEPLOYMENT.md) | Docker Compose, Kubernetes, systemd, production hardening |
+| [Integration guide](INTEGRATION.md) | Connect your apps: tokens, sessions, OAuth2/OIDC, drop-in widget |
+
+## Reference
+
+| Document | Purpose |
+| --- | --- |
+| [HTTP API reference](API.md) | Every endpoint, grouped by area, with auth requirements |
+| [Architecture](ARCHITECTURE.md) | Layered design, services, repositories, events, plugins |
+| [Performance tuning](PERFORMANCE.md) | Connection pools, caching, indexes, load-testing results |
+| [Security model](SECURITY.md) | Threat model, token lifecycle, storage, hardening checklist |
+| [RBAC and authorization](RBAC.md) | Platform/organization role boundaries, policy evaluation, and migration |
+| [v1.7 migration guide](MIGRATION-1.7.md) | Upgrade steps and breaking authorization changes |
+| [v1.8 migration guide](MIGRATION-1.8.md) | MFA enforcement: new endpoints, response changes, and upgrade steps |
+| [v1.9 migration guide](MIGRATION-1.9.md) | SCIM tenancy: per-organization credentials, deprovisioning semantics, and upgrade steps |
+| [v1.7 release checklist](RELEASE-1.7.md) | Local gates, dependency/lint blockers, and publication steps |
+
+## Contributing
+
+| Document | Purpose |
+| --- | --- |
+| [Contributing guide](CONTRIBUTING.md) | Dev environment, branch and commit conventions, PR process |
+| [Code of Conduct](../CODE_OF_CONDUCT.md) | Community standards and enforcement |
+| [Changelog](../CHANGELOG.md) | Release history (Keep a Changelog format) |
+| [Security policy](../.github/SECURITY.md) | How to report vulnerabilities |
+| [Roadmap](ROADMAP.md) | Planned work and priorities |
+
+## Architecture decision records
+
+| ADR | Decision |
+| --- | --- |
+| [001 — Identity connectors as adapters](adrs/001-identity-connectors-as-adapters.md) | Provider-agnostic connector interface |
+| [002 — Versioned event bus](adrs/002-versioned-event-bus.md) | Event envelope versioning strategy |
+| [003 — BullMQ for background work](adrs/003-bullmq-for-background-work.md) | Queue technology choice |
+| [004 — argon2id password hashing](adrs/004-argon2id-password-hashing.md) | Password hashing parameters |
+
+## Guides by example
+
+| Example | Demonstrates |
+| --- | --- |
+| [Drop-in login widget](../examples/drop-in-login/README.md) | Zero-build HTML integration via `/sdk/keystone-dropin.js` |
+| [HTML drop-in](../examples/html-dropin/README.md) | Plain HTML pages with hosted UI |
+| [React SPA](../examples/react-spa/README.md) | Token-based SPA with refresh rotation |
+| [Login form (React)](../examples/login-form-react/README.md) | Custom-branded login against `/auth/*` |
+| [SDK package](../packages/keystone-sdk/README.md) | `@hilbras/keystone-sdk` builds and SRI usage |

package/docs/RELEASE-1.7.md

@@ -0,0 +1,53 @@
+# v1.7.0 Release Checklist
+
+This checklist is for the local release candidate. Tagging, GitHub Release creation, and npm publication still require explicit approval.
+
+## Local verification
+
+- [x] `npm ci` (2026-09-25 local run; release CI repeats the install)
+- [x] `npm run lint`
+- [x] `npm run typecheck`
+- [x] `npm run build`
+- [x] `npm test` with PostgreSQL and Redis (97 passed, 1 skipped)
+- [x] `npm run test:security` (47 passed)
+- [x] `cd frontend && npm run build`
+- [x] `npm pack --dry-run`
+- [x] `git diff --check`
+
+## Security verification
+
+- [x] Organization-to-platform role escalation regression coverage
+- [x] Organization membership rank and last-owner coverage
+- [x] Workflow allowlist, malformed-definition, and tenant-scope coverage
+- [x] SAML/OIDC organization-scope, schema validation, ID-token verification, and one-time RelayState transaction coverage
+- [x] Existing-user enterprise SSO membership/identity-link and platform-owner isolation coverage
+- [x] Generic OAuth verified-identity and no-email-autolink coverage
+- [x] Scoped SCIM credential, organization isolation, review-state, platform-owner isolation, service attribution, and last-owner coverage
+- [x] OIDC endpoint SSRF policy coverage, including private, carrier-grade, dotted/hex mapped, and DNS-pinned address ranges
+- [x] User/application/API-key/configuration secret projection coverage
+- [x] Account deactivation, refresh-token/API-key revocation, and cross-client token-scope coverage
+- [x] Non-burning wrong-client refresh rejection, OAuth2 refresh success/failure audit coverage, and execution-time workflow authorization coverage
+- [x] Fail-closed legacy migration and SAML audience/destination/recipient semantic coverage
+- [x] Authorization audit metadata, top-level tenant attribution, and denied-attempt coverage
+- [x] Runtime role constraints, owner-required organization creation, and legacy-value normalization migration
+
+## Unresolved release blockers
+
+### Dependency audit
+
+The release workflow runs `npm audit --omit=dev --audit-level=high` as a blocking gate. The 2026-09-25 run passes with **0 High** findings after safe transitive overrides for `@xmldom/xmldom`, `fast-uri`, and `find-my-way`. Four Moderate findings remain outside the High-severity release gate and should continue to be tracked.
+
+### Lint
+
+The repository now has a real `oxlint` gate (`npm run lint`) with warnings denied, and CI runs it as a blocking step. Typecheck remains a separate gate.
+
+### npm publication
+
+The release workflow now builds the package, runs `npm pack --dry-run`, installs the packed tarball in a clean temporary prefix, and smoke-tests the CLI before publication. The job still requires the `NPM_TOKEN` GitHub secret, which is not currently configured. Verify trusted publishing or configure the secret before release.
+
+### External actions
+
+- [ ] User approves tag and remote publication
+- [ ] Tag `v1.7.0` is pushed
+- [ ] GitHub Release is verified
+- [ ] npm package is installed and smoke-tested

package/docs/ROADMAP.md

@@ -0,0 +1,41 @@
+# Keystone Roadmap
+
+This roadmap captures completed milestones and planned work. It is ordered by priority and dependency.
+
+## Completed
+
+1. **v1.7 authorization boundary hardening** — separated platform and organization roles, closed tenant workflow escalation paths, scoped SSO lookups, and added security regression coverage.
+2. **Local password reset** — token-based password reset independent of Zitadel, with email queued for delivery.
+2. **BullMQ background queue** — durable Redis-backed queue for email, webhooks, and workflows.
+3. **Sanitized OAuth/Federation errors** — centralized error helper that exposes only opaque public codes.
+4. **Distributed Redis rate limiting** — atomic sliding-window rate limiter with `Retry-After`.
+5. **JWT key rotation grace period** — JWKS publishes active + recently rotated keys for 24 hours.
+6. **Argon2id password hashing** — new hashes use argon2id; legacy scrypt hashes remain verifiable.
+7. **Real email/SMS providers** — SMTP, SendGrid, Mailgun, and Twilio.
+8. **Full SAML signature validation** — SAML responses validated through `samlify`.
+9. **Integration tests + CI** — GitHub Actions job with Postgres/Redis services and a BullMQ integration test.
+10. **CLI enhancements** — `user:create`, `keys:list`, `config:validate`, `org:create`.
+11. **Backend setup endpoints** — `/setup/status` and `/setup/init` for fresh installations.
+12. **Standalone setup frontend** — React + Vite wizard with Playwright E2E tests.
+
+## Near term
+
+- **Audit log UI and export** — paginated admin API, CSV export, SIEM-friendly streaming.
+- **Organization-level SSO** — self-service OIDC and SAML connection configuration.
+- **Branding and email templates** — customizable email HTML and sender identity per organization.
+- **Session management** — list and revoke active sessions per user.
+- **Webhook reliability** — retries, signatures, and delivery logs.
+
+## Mid term
+
+- **Multi-region replication** — read replicas, geo-distributed signing keys.
+- **Advanced authorization** — attribute-based access control (ABAC) and custom policy plugins.
+- **User impersonation** — secure admin impersonation with full audit trail.
+- **SCIM provisioning** — inbound/outbound user and group provisioning.
+- **Billing integration hooks** — seat-count events and plan enforcement.
+
+## Long term
+
+- **FIDO2/WebAuthn passkeys as primary auth** — passwordless-first flows.
+- **Device trust and risk-based authentication** — risk scoring from anomaly detection.
+- **Keystone Operator for Kubernetes** — automated deployments, certificate rotation, and backups.

package/docs/SECURITY.md

@@ -0,0 +1,143 @@
+# Keystone Security
+
+This document outlines the security model and operational practices for Hilbras Keystone.
+
+## Authentication
+
+- **Passwords** are hashed with **argon2id** (OWASP-recommended parameters). Legacy deployments that used scrypt can still verify existing hashes; new hashes always use argon2id.
+- **Multi-factor authentication** is mandatory for any user with TOTP enabled. Password authentication stops at `requires_mfa` and issues no access token, refresh token, or session; only `POST /auth/mfa/verify` completes the transition to `authenticated`.
+- MFA challenges are opaque, stored only as a hash, short-lived (`MFA_CHALLENGE_TTL_SECONDS`, default 300), and single-use. Each state change is a conditional database update, so concurrent verification has exactly one winner. Starting a new password step supersedes any outstanding challenge.
+- TOTP codes are verified against the user's own decrypted secret. Each time-step is accepted once — a captured code is rejected even against a freshly issued challenge.
+- Backup codes carry 80 bits of entropy, are stored as a keyed (peppered) hash, expire after `TOTP_BACKUP_CODE_TTL_SECONDS` (default 90 days), and are consumed by a conditional update so a code can never be used twice.
+- TOTP secrets are encrypted with AES-256-GCM. Values written by earlier versions used AES-256-CBC and remain readable so enrolled authenticators survive the upgrade.
+- 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 can bypass MFA by omission. WebAuthn assertions satisfy the requirement 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.
+- Sessions record the factor that satisfied MFA. Refresh rotation refuses sessions with no recorded factor, and enabling MFA revokes every existing refresh token and session for the account.
+- A verified WebAuthn assertion also satisfies the MFA requirement, so a passkey sign-in does not additionally require a TOTP code. A passkey registered *after* TOTP was enabled does not: it is a single factor, and sign-in is refused. Registering a passkey on a TOTP-protected account requires the account password.
+- Changing how an account proves its identity — enrolling, confirming, regenerating backup codes for, or disabling TOTP — requires step-up: the account password in addition to the session. A stolen access token must not be enough to take over an account's second factor.
+- Failed MFA factor attempts count toward the account lockout, so a stolen password cannot be brute-forced through the slower MFA step.
+- **Social and enterprise login** is handled by connectors that normalize profile data. Keystone acts as the identity broker and issues its own tokens.
+- **Enterprise SSO** uses OIDC or SAML. SAML responses are schema-validated with the configured `xmllint` validator, signature-verified, and checked for audience, destination, and subject recipient. OIDC ID tokens are verified against the connection JWKS and issuer/audience. Existing enterprise users require an explicit `(connection, subject)` identity link and organization membership; platform owners cannot authenticate through tenant SSO.
+- Generic OAuth requires a provider-verified email and never treats email equality alone as an identity link.
+
+## Tokens
+
+- **Access tokens** are short-lived RS256-signed JWTs. Sessions that completed MFA carry `mfa_verified`, `mfa_factor`, and an `amr` list so relying parties can assert the authentication method used.
+- **Refresh tokens** are opaque, rotated on use, and stored as SHA-256 hashes. Rotation validates client, application, membership, and account state before an atomic conditional claim, so a wrong-client request cannot burn a valid token.
+- **API keys** are opaque, prefix-searchable, and hashed at rest.
+- **JWT signing keys** are rotatable. The JWKS endpoint publishes the active key plus recently rotated keys for a 24-hour grace period.
+- **Cookies** use `HttpOnly`, `Secure` (configurable), and `SameSite=lax`.
+- SCIM credentials are per-organization. Every connection belongs to exactly one organization, at most one connection is live per organization, and every user and group read and write is filtered by that organization. A cross-tenant target returns `404`, not `403`, so the endpoint is not a tenant oracle.
+- SCIM 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. Tokens can expire, be rotated, and be revoked. Rotation invalidates the old token immediately unless an explicit grace window is requested — a grace window is a continuity aid, not a revocation.
+- Issuing, rotating, and revoking a SCIM credential is owner-only; a SCIM token can provision and deactivate tenant users, so a mere admin or member must not be able to mint one.
+- A user row is global, so deprovisioning removes the organization's membership first and deactivates the account only once no membership remains. SCIM refuses to change global attributes of a user who also belongs to another organization, and refuses to reactivate a shared account.
+- SCIM cannot remove the last owner of an organization, and never modifies platform owners or accounts pending platform review.
+- SCIM audit rows record the connection id and organization for every mutation, and credential lifecycle transitions emit `scim_connection_created`, `scim_connection_rotated`, and `scim_connection_revoked`. Rejected requests emit `scim_access_denied` and `scim_authentication_failed`.
+- `SCIM_BEARER_TOKEN` and `SCIM_ORG_ID` are deprecated. They are adopted once into a connection at startup and then ignored, so removing them does not affect an adopted credential; revoke through the connection API instead.
+- Configuration and profile responses redact secret-like values before leaving the API; raw database URLs, credentials, signing keys, provider secrets, SCIM tokens, Vault tokens, and generic `*_CLIENT_SECRET` values are not returned.
+- SAML RelayState is bound to a short-lived, one-time Redis transaction and initiating browser cookie; production requires a high-entropy `KEYSTONE_INTERNAL_API_KEY`.
+- Deactivated users are rejected by password, token, API-key, refresh, magic-link, WebAuthn, OAuth, SAML, and OIDC authentication; deactivation revokes refresh tokens, sessions, and user API keys. Ambiguous legacy unverified accounts are quarantined with `account_review_required` during migration.
+
+## Authorization
+
+- Platform roles are exactly `owner` and `user`; organization roles are exactly `owner`, `admin`, and `member`.
+- The namespaces are independent. Organization membership never grants platform-owner access.
+- Platform role changes use the dedicated owner-only endpoint `PATCH /v1/admin/platform/users/:userId/role`.
+- Organization member APIs may change only `organizationMembership.role`; global account writes and deactivation are rejected.
+- Organization permission checks resolve the authenticated actor and route organization explicitly. Client-controlled application/origin context is not an authorization decision.
+- `/v1/authz/check` requires an explicit `organizationId` and fails closed when the actor is not a member.
+- OIDC/SAML endpoint configuration rejects local/private targets by default, including hex-form IPv4-mapped IPv6; private enterprise endpoints require an explicit deployment opt-in and outbound fetches pin DNS answers and reject redirects.
+- The last platform owner and the last organization owner cannot be demoted.
+- Tenant workflows cannot assign roles or add memberships across organizations, cannot be registered or executed by actors lacking current workflow-management permission, and are blocked when inactive. Out-of-scope events do not create durable workflow runs.
+- See [RBAC.md](RBAC.md) for the role matrix and migration guidance.
+
+## Secrets
+
+The secrets provider abstraction stores:
+
+- JWT signing and encryption keys
+- API keys and client secrets
+- Password hashes
+
+Default provider stores secrets in PostgreSQL. Production deployments should use `EnvironmentSecretsProvider` or an enterprise backend (AWS KMS, HashiCorp Vault, Azure Key Vault) via plugin.
+
+## User data exposure
+
+Administrative and organization user responses use a redacted public projection. Password hashes, TOTP secrets, setup tokens, and sensitive metadata are never returned by user-management endpoints. Self-service profile responses may return the authenticated user's own metadata, but API-key validation and cross-principal projections never do. Treat any client that depends on administrative metadata fields as requiring a separate, explicitly authorized migration.
+
+## Sessions and credential revocation
+
+All revocation goes through `src/services/sessionRevocation.ts`. Revocation that is open-coded per call site is revocation that eventually omits the important case — which is how completing a password reset came to change the password while leaving every session and refresh token working, defeating the point of a reset.
+
+A successful password reset invalidates:
+
+- every authentication session,
+- every refresh token, so no further access token can be minted,
+- every outstanding recovery credential, so a reset email captured earlier cannot be completed after the user has already recovered.
+
+Enabling MFA applies the same rule, through the same function.
+
+**API keys are not revoked by a password reset.** They are separately issued, long-lived credentials belonging to integrations rather than to the person, and silently invalidating them on a password reset breaks deployments. The residual gap is that a key minted by an attacker who already held the password survives the recovery. That is a key-lifetime problem, and the fix is expiry and rotation, not coupling key lifetime to a human's password. If your threat model requires otherwise, revoke the keys explicitly through the key API.
+
+## Single-use credentials
+
+Magic links, password reset tokens, SMS OTP codes, MFA challenges, TOTP backup codes, OAuth2 authorization codes, and refresh tokens are each consumable exactly once, enforced by the database rather than by application logic.
+
+The claim is a single conditional write:
+
+```sql
+UPDATE <table> SET used_at = now()
+WHERE <hash> = ? AND expires_at > now() AND used_at IS NULL
+RETURNING *
+```
+
+Exactly one transaction can match that predicate, so concurrency cannot redeem a credential twice. Every consumption goes through `src/services/singleUse.ts`; a credential that reads and then writes inline can be raced.
+
+Presenting an already-spent credential is reported as a **replay** and emits an audit event (`magic_link_replayed`, `sms_otp_replayed`, `password_reset_token_replayed`). An expired credential is not a replay and is not reported as one. A token that never existed is reported only as invalid, so the endpoint does not become an oracle for which tokens once existed.
+
+## Enterprise federation
+
+SAML assertions and OIDC ID tokens are both validated in full: signature, issuer, audience, algorithm, lifetime, subject, and — for OIDC — a nonce binding the token to the authorization request that started it. See [enterprise-sso.md](security/enterprise-sso.md) for every check, the certificate-rotation procedure, and the endpoint SSRF policy.
+
+Two properties are worth stating here because they are easy to get wrong:
+
+- **The response-level SAML `Issuer` is unsigned**, so it is compared to the registered IdP entity ID directly. The assertion's own issuer is inside the signed region and is covered by the signature.
+- **A connector that overrides `exchangeCode` must forward its options.** Doing otherwise silently disabled nonce validation for that provider, which is what happened to Google until 2.5.0.
+
+## Trust boundaries
+
+Keystone trusts exactly two things: the socket peer address, and credentials it can verify cryptographically. Everything arriving in a header is attacker-controlled unless the peer is a configured trusted proxy.
+
+`KEYSTONE_TRUSTED_PROXIES` (comma-separated IPs, IPv4 CIDRs, or IPv6 prefixes) names the proxies permitted to set client-identity headers. It is **empty by default**, which means nothing is trusted: forwarded headers are stripped in an `onRequest` hook before routing, and rate limiting keys on the peer address.
+
+A service account authenticates only with a client certificate whose SHA-256 fingerprint is bound to it in `service_accounts.cert_fingerprint`, or with an authenticated credential (API key, session, bearer token). No header establishes identity — before v2.0.0, `x-service-account-id` alone authenticated as any named service account.
+
+Details: [trust-boundaries.md](security/trust-boundaries.md), [proxy-security.md](security/proxy-security.md), [mtls.md](security/mtls.md). Upgrade notes: [MIGRATION-2.0.md](MIGRATION-2.0.md).
+
+## Rate limiting
+
+A Redis-backed sliding-window rate limiter protects authentication and public endpoints. It returns `429 Too Many Requests` with a `Retry-After` header. It fails open if Redis is unreachable.
+
+Rate-limit keys come from the peer address unless the request came from a configured trusted proxy, in which case the forwarded client address is used. Before v2.0.0 the limiter read `x-forwarded-for` unconditionally, so any client could present a fresh address per request and never be limited.
+
+SCIM carries two budgets: one keyed on the authenticated credential, so one noisy identity provider cannot exhaust every other tenant's allowance, and an address-keyed budget in front of the authentication hook, because that hook runs before the credential limiter and emits audit and webhook events on failure.
+
+MFA verification does not rely on that limiter alone: every challenge carries its own attempt budget (`MFA_MAX_ATTEMPTS`, default 5) enforced in the database, so attempts are counted even when Redis is unavailable. Factor management endpoints (`/auth/totp/*`) have dedicated budgets separate from login.
+
+## Audit and monitoring
+
+Every security-relevant action emits a versioned event:
+
+- `user_registered`, `user_login`, `user_login_failed`
+- `mfa_challenge_created`, `mfa_challenge_failed`, `mfa_challenge_expired`, `mfa_challenge_rejected`, `mfa_verified`, `mfa_bypass_blocked`, `mfa_backup_code_regenerated`
+- `scim_connection_created`, `scim_connection_rotated`, `scim_connection_revoked`, `scim_access_denied`, `scim_authentication_failed`, `scim_group_created`, `scim_group_updated`, `scim_group_deleted`
+- `oauth_callback`, `saml_sso_login`, `oidc_enterprise_login`
+- `api_key_created`, `api_key_revoked`
+- `authz_check`, `password_reset_requested`, `password_reset_completed`
+- `platform_role_changed`, `organization_member_role_updated`, `organization_member_invited`, `organization_member_removed`
+- `permission_role_updated`, `workflow_blocked`, `unauthorized_access`, `api_key_used`, `oauth2_refresh`, `oauth2_refresh_failed`; refresh, OAuth, SCIM, and API-key mutations carry server-derived actor and tenant attribution.
+
+Events are written to the audit log, exported to webhooks, and consumed by anomaly detection. Authorization transitions include actor, target, organization, previous/new state, request ID, IP address, and user agent where available. Audit persistence is asynchronous; production deployments should monitor subscriber failures.
+
+## Reporting vulnerabilities
+
+If you discover a security issue, please report it privately to the Hilbras security team. Do not open a public issue until a fix is released.

package/docs/adrs/001-identity-connectors-as-adapters.md

@@ -0,0 +1,27 @@
+# ADR 001: Identity Connectors as Provider Adapters
+
+## Status
+
+Accepted
+
+## Context
+
+Keystone needs to support many external identity providers (Google, GitHub, Azure AD, Okta, Keycloak, Zitadel) without becoming a wrapper around any single one. Early drafts coupled user creation and token issuance directly inside connector code, making connectors hard to test and reuse.
+
+## Decision
+
+Introduce a dedicated **Identity Connectors** layer. Each connector is a pure adapter responsible only for:
+
+- Building authorization URLs
+- Exchanging codes for tokens
+- Validating identity tokens
+- Retrieving and normalizing profile data
+
+User creation, identity linking, Keystone token issuance, and session management remain in higher-level domain services (`AuthenticationDomainService`, `IdentityDomainService`).
+
+## Consequences
+
+- Connectors are small, stateless, and easy to unit test.
+- New providers can be added without changing core business logic.
+- The platform remains provider-agnostic.
+- A small amount of orchestration code is duplicated across domain services, which is acceptable for clarity.