@hilbras/keystone 2.5.0 → 3.0.0

package/docs/LOGIN_FORM_INTEGRATION.md

@@ -0,0 +1,306 @@
+# Connect Your Login/Signup Form to Keystone
+
+If you already have a login/signup page with email/password and a "Login with Google" button, this guide shows you exactly how to wire it to Keystone.
+
+---
+
+## The big picture
+
+Your frontend does **not** talk directly to Google. It talks to Keystone. Keystone handles Google, passwords, tokens, and sessions.
+
+```
+User
+  │
+  ▼
+Your React login page
+  │
+  ├── email/password ──► POST /auth/login
+  │                          │
+  │                          ├── MFA enabled ──► 401 MFA_REQUIRED + challenge
+  │                          │                        │
+  │                          │                        └── POST /auth/mfa/verify ──► tokens
+  │                          │
+  │                          └── no MFA ─────────► session cookie
+  │
+  └── Google button ───► GET /auth/oauth/google
+                              │
+                              ▼
+                         Keystone
+                              │
+                              ▼
+                         Google OAuth
+                              │
+                              ▼
+                         Keystone creates/updates user
+                              │
+                              ▼
+                         Redirects back to your app
+                              │
+                              ▼
+                   Your app calls GET /auth/me
+```
+
+After either login method, Keystone sets an HTTP-only session cookie. Your frontend uses that cookie to identify the user.
+
+---
+
+## Step 1 — Configure Keystone
+
+Edit Keystone's `.env` file:
+
+```env
+# Database and Redis (already set by the setup wizard)
+DATABASE_URL=postgresql://...
+REDIS_URL=redis://localhost:6379
+
+# Google OAuth credentials from https://console.cloud.google.com/
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# Cookie settings — very important
+COOKIE_DOMAIN=localhost
+COOKIE_SECURE=false
+
+# Your frontend URL
+ALLOWED_ORIGINS=http://localhost:5173
+AUTH_API_PUBLIC_URL=http://localhost:4001
+
+# Optional: where to send users after Google login
+CLIENT_APP_URL=http://localhost:5173
+```
+
+Restart Keystone after changing `.env`.
+
+### Why `COOKIE_DOMAIN=localhost`?
+
+Your React app runs on `http://localhost:5173` and Keystone on `http://localhost:4001`. Browsers treat these as the same site only if the cookie domain is `localhost`. For production, put both apps under the same root domain (e.g. `app.yoursite.com` and `api.yoursite.com`) and set `COOKIE_DOMAIN=.yoursite.com`.
+
+---
+
+## Step 2 — Choose how to integrate
+
+### Option A: One-line CDN script (fastest — nothing in your project folder)
+
+Add one script tag to your page. The script is served directly by Keystone, so you do not copy any files into your project.
+
+```html
+<script
+  src="http://localhost:4001/sdk/keystone-dropin.js"
+  data-keystone-url="http://localhost:4001"
+  data-keystone-after-login="/dashboard"
+></script>
+```
+
+Then add IDs/classes to your existing form:
+
+```html
+<form id="keystone-login-form">
+  <input class="keystone-email" type="email" />
+  <input class="keystone-password" type="password" />
+  <button type="submit">Login</button>
+</form>
+
+<button id="keystone-google-btn">Login with Google</button>
+```
+
+No other code needed. The script auto-wires the forms and talks to Keystone for you.
+
+To connect/register your project with Keystone, add one more line:
+
+```html
+<script>
+  Keystone.connect("my-project", "http://localhost:5173/callback")
+    .then((c) => console.log("Connected:", c.clientId));
+</script>
+```
+
+### Option B: Self-hosted drop-in script
+
+If you prefer to host the script yourself, copy `examples/drop-in-login/dropin.js` into your project and include it:
+
+```html
+<script>
+  window.KEYSTONE_URL = "http://localhost:4001";
+  window.KEYSTONE_AFTER_LOGIN = "/dashboard";
+</script>
+<script src="/keystone-dropin.js"></script>
+```
+
+See `examples/drop-in-login/README.md`.
+
+### Option C: React helper
+
+Create `keystone-auth.ts` in your React project and copy the code from `examples/login-form-react/keystone-auth.ts`.
+
+The key thing: every request uses `credentials: "include"` so the browser sends the session cookie.
+
+---
+
+## Step 3 — Replace your form handlers
+
+Before (fake example):
+
+```tsx
+async function handleLogin(e) {
+  e.preventDefault();
+  const res = await fetch("/api/login", { ... });
+}
+```
+
+After:
+
+```tsx
+import {
+  loginWithPassword,
+  completeMfaLogin,
+  MfaRequiredError,
+  registerAccount,
+  loginWithGoogle,
+} from "./keystone-auth";
+
+const [mfaChallenge, setMfaChallenge] = useState<string | null>(null);
+
+async function handleLogin(e) {
+  e.preventDefault();
+  setMfaChallenge(null);
+  try {
+    const { user } = await loginWithPassword(email, password);
+    setUser(user);
+  } catch (err) {
+    // The password was correct; this account just needs a second factor.
+    if (err instanceof MfaRequiredError) {
+      setMfaChallenge(err.challenge);
+      return;
+    }
+    setError(err.message);
+  }
+}
+
+async function handleMfaSubmit(e) {
+  e.preventDefault();
+  const { user } = await completeMfaLogin(mfaChallenge, code);
+  setUser(user);
+  setMfaChallenge(null);
+}
+
+async function handleSignup(e) {
+  e.preventDefault();
+  const { user } = await registerAccount(username, email, password, name);
+  setUser(user);
+}
+
+// Google button just redirects:
+<button onClick={loginWithGoogle}>Login with Google</button>
+```
+
+When `mfaChallenge` is set, render a code field instead of the password form:
+
+```tsx
+{mfaChallenge && (
+  <form onSubmit={handleMfaSubmit}>
+    <input
+      autoFocus
+      autoComplete="one-time-code"
+      inputMode="numeric"
+      value={code}
+      onChange={(e) => setCode(e.target.value.replace(/\D/g, "").slice(0, 6))}
+    />
+    <button type="submit">Verify</button>
+  </form>
+)}
+```
+
+The challenge is single-use and expires, so render it only while the user is on
+the code step and send the user back to the password form on failure.
+
+See `examples/login-form-react/LoginPage.example.tsx` for a complete working page.
+
+---
+
+## Step 4 — Check login status on page load
+
+```tsx
+import { useEffect, useState } from "react";
+import { getCurrentUser } from "./keystone-auth";
+
+function App() {
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    getCurrentUser().then(setUser);
+  }, []);
+
+  // ...
+}
+```
+
+`GET /auth/me` returns the current user if the cookie is valid.
+
+---
+
+## Step 5 — Protect your backend API
+
+If your backend needs to know who the user is, you have two options.
+
+### Option A: Send the access token to your backend
+
+After login, Keystone also returns an `accessToken` in the response body (for `/auth/token-login`) or in cookies. Your frontend can read it and send:
+
+```ts
+fetch("/api/profile", {
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+  },
+});
+```
+
+Your backend verifies the JWT using Keystone's public keys:
+
+```ts
+import { jwtVerify, createLocalJWKSet } from "jose";
+
+const jwks = createLocalJWKSet(await fetch("http://localhost:4001/.well-known/jwks.json").then(r => r.json()));
+const { payload } = await jwtVerify(token, jwks, { issuer: "http://localhost:4001" });
+// payload.sub = user id, payload.email = email
+```
+
+See `examples/login-form-react/backend-example.ts`.
+
+### Option B: Use API keys for server-to-server calls
+
+For microservices or scripts, create an API key in Keystone and send:
+
+```ts
+fetch("/api/admin/users", {
+  headers: { "X-API-Key": "keystone_xxxxxxxx" },
+});
+```
+
+---
+
+## Common problems
+
+### CORS error
+
+Make sure `ALLOWED_ORIGINS` includes your frontend URL exactly, including the port.
+
+### Cookie not sent
+
+Make sure every fetch uses `credentials: "include"` and `COOKIE_DOMAIN` is set correctly.
+
+### Google login fails
+
+- Check that the Google OAuth redirect URI is exactly: `http://localhost:4001/auth/callback/google`
+- Make sure `AUTH_API_PUBLIC_URL` matches the URL Google redirects to.
+
+### "Invalid OAuth state"
+
+This usually means cookies are blocked. Check the cookie domain and `COOKIE_SECURE` settings.
+
+---
+
+## Next steps
+
+- Add roles and permissions in the Keystone admin portal.
+- Use `/v1/authz/check` to ask Keystone "can this user do X?" from your backend.
+- Turn on audit logs and webhooks to track logins.

package/docs/MIGRATION-1.7.md

@@ -0,0 +1,70 @@
+# Migration Guide: v1.6.x to v1.7.0
+
+## Authorization boundary changes
+
+### Platform roles
+
+Platform roles are now limited to `owner` and `user`. Use:
+
+```http
+PATCH /v1/admin/platform/users/<userId>/role
+Authorization: Bearer <platform-owner-token>
+Content-Type: application/json
+
+{"role":"user"}
+```
+
+The generic platform user PATCH endpoint rejects a `role` field. A platform owner cannot demote the final platform owner.
+
+### Organization membership
+
+Organization membership roles are `owner`, `admin`, and `member`. Use:
+
+```http
+PATCH /v1/admin/organizations/<orgId>/members/<userId>
+```
+
+The old organization user PATCH/DELETE endpoints return a migration response (`410`) and cannot change global user state. Organization user read responses are redacted and no longer include password hashes, TOTP secrets, or sensitive metadata.
+
+### Authorization checks
+
+Add the organization being evaluated to every `/v1/authz/check` request:
+
+```json
+{
+  "organizationId": "<orgId>",
+  "resource": "application",
+  "action": "read"
+}
+```
+
+The actor must be an authenticated member of that organization.
+
+### Workflows
+
+Remove `assign_role`, `add_membership`, `add_app_membership`, `create_organization`, plugin-alias, and arbitrary webhook steps from tenant workflows before deploying v1.7.0. These steps are rejected at creation and blocked at execution for existing definitions. Replace them with an explicitly authorized administrative workflow or an application service call.
+
+## Deployment checklist
+
+- [ ] Run `npm ci` and rebuild backend/frontend artifacts.
+- [ ] Run `npm run build` before `npm run db:reencrypt-oidc-secrets -- --allow-unmarked-plaintext`; the packaged migration command runs the compiled `dist` helper and requires an explicit review flag for unmarked legacy values.
+- [ ] Run the security regression suite against PostgreSQL and Redis.
+- [ ] Review the role-constraint migration; legacy invalid platform roles are normalized to `user` and invalid organization roles to `member` before constraints are applied.
+- [ ] Remove unsafe legacy workflow definitions.
+- [ ] Configure a stable high-entropy `KEYSTONE_INTERNAL_API_KEY` for SAML transaction binding.
+- [ ] Configure a stable `KEYSTONE_ENCRYPTION_KEY`; run `npm run db:reencrypt-oidc-secrets -- --allow-unmarked-plaintext` after reviewing legacy rows, then verify encrypted OIDC secrets. The command executes the compiled `dist/db/reencryptOidcSecrets.js` helper.
+- [ ] Review quarantined legacy accounts: migration `0010` marks ambiguous pre-v1.7 unverified accounts `account_review_required` and inactive; do not bulk-reactivate them without review. Platform owners can resolve an individual account through `/v1/admin/platform/users/<userId>/account-review`.
+- [ ] Update SAML/OIDC initiation and metadata URLs to include `organizationId`; callback state is organization-bound and existing enterprise users must already be organization members.
+- [ ] Update clients using `/v1/authz/check` to send `organizationId`.
+- [ ] Ensure users are organization members before using organization-bound OAuth/OIDC clients; cross-tenant client context no longer adds an organization claim.
+- [ ] Send the bound `client_id` when rotating application-bound refresh tokens; mismatches and inactive/unauthorized applications are rejected.
+- [ ] Keep OIDC endpoints on approved public HTTPS hosts. Private endpoints require the explicit `ALLOW_PRIVATE_SSO_ENDPOINTS=true` deployment decision.
+- [ ] Configure `SCIM_BEARER_TOKEN` together with `SCIM_ORG_ID`; the bearer credential is scoped to that one organization and cannot administer platform users globally.
+- [ ] Use the production-safe cookie defaults from `.env.example` (`__Host-` name, no domain, `Secure=true`); override them only for local HTTP development.
+- [ ] Existing users must have an explicit enterprise SSO identity link before tenant SSO can issue a token; platform owners are rejected from tenant SSO.
+- [ ] Move platform-role mutations to the dedicated endpoint.
+- [ ] Treat platform-user deactivation as irreversible account disablement; sessions, refresh tokens, and user API keys are revoked.
+- [ ] Move organization-role mutations to `/members/:userId`.
+- [ ] Review audit consumers for the new authorization event names.
+- [ ] Verify no client depends on internal user fields in organization responses.
+- [ ] Review the documented dependency-audit exception before publishing.

package/docs/MIGRATION-1.8.md

@@ -0,0 +1,183 @@
+# Migrating to Keystone 1.8.0
+
+Keystone 1.8.0 makes multi-factor authentication enforceable. In 1.7.x, TOTP
+was advisory: a user with `totpEnabled = true` could sign in with only a
+password, and when a code was supplied it was checked *after* tokens had already
+been minted. 1.8.0 removes both behaviours.
+
+Review this page before upgrading a production deployment.
+
+---
+
+## What changes for clients
+
+### `POST /auth/login` and `POST /auth/token-login`
+
+The request body is unchanged, except that the undocumented `totp_code` field is
+gone and is now ignored.
+
+For accounts **without** MFA, the response is unchanged.
+
+For accounts **with** MFA, the response changes from `200` to `401`:
+
+```diff
+- 200 OK
+- { "user": { ... } }
++ 401 Unauthorized
++ {
++   "error": "Multi-factor authentication required",
++   "code": "MFA_REQUIRED",
++   "mfaRequired": true,
++   "challenge": "0hV3...",
++   "expiresAt": "2026-01-01T00:05:00.000Z",
++   "methods": ["totp", "backup_code"]
++ }
+```
+
+No access token, refresh token, or session cookie is issued at this point.
+
+### `POST /auth/mfa/verify` (new)
+
+```http
+POST /auth/mfa/verify
+{ "challenge": "0hV3...", "code": "123456", "factor": "totp" }
+```
+
+On success it returns the same shape as a completed login, plus the factor that
+was used. From a `login` flow, session cookies are also set.
+
+| Code | Meaning |
+| --- | --- |
+| `MFA_CHALLENGE_INVALID` | Unknown challenge |
+| `MFA_CHALLENGE_EXPIRED` | Past `expiresAt` |
+| `MFA_CHALLENGE_REPLAYED` | Already consumed |
+| `MFA_CHALLENGE_LOCKED` | Attempt budget exhausted |
+| `MFA_INVALID_CODE` | Factor did not match |
+| `MFA_NOT_REQUIRED` | Factor disabled while the challenge was open |
+
+### `POST /auth/totp/*`
+
+| Endpoint | 1.7.x | 1.8.0 |
+| --- | --- | --- |
+| `POST /auth/totp/enroll` | `{ }` | `{ password }` — step-up required |
+| `POST /auth/totp/verify` | `{ code }` | `{ password, code }` — step-up required; also revokes existing sessions and refresh tokens |
+| `POST /auth/totp/backup` | Consumed a backup code | **Regenerates** backup codes; requires `{ password, code }` |
+| `POST /auth/totp/disable` | `{ code }` | `{ password, code }` — step-up required; also destroys backup codes |
+| `POST /auth/totp/backup/verify` | — | New. Consumes a backup code without establishing a session |
+| `POST /auth/webauthn/register/verify` | `{ response }` | `{ response, password? }` — password required when TOTP is enabled |
+
+### Step-up on factor management
+
+Every endpoint that changes how an account proves its identity now requires the
+account **password** in the body in addition to a valid session. This closes a
+gap where a leaked 15-minute access token was enough to enroll an attacker's own
+authenticator and take permanent control of the account's second factor.
+
+Step-up failures return `401 STEP_UP_REQUIRED` (no password supplied) or
+`401 INVALID_CREDENTIALS` (wrong password), and count toward the account lockout.
+
+Update any UI that enrolls or disables MFA to prompt for the password.
+
+If your integration used `POST /auth/totp/backup` to burn a recovery code, move
+to `POST /auth/totp/backup/verify`.
+
+### Access-token claims
+
+Sessions that completed MFA carry three additional claims:
+
+```json
+{
+  "mfa_verified": true,
+  "mfa_factor": "totp",
+  "amr": ["password", "totp"]
+}
+```
+
+`mfa_factor` is one of `totp`, `backup_code`, `webauthn`, or `session`.
+Claims are only additive; existing verifiers that ignore unknown claims are
+unaffected.
+
+---
+
+## What changes for operators
+
+### Enforcing MFA on existing accounts
+
+Migrations do **not** enable MFA automatically. To require a second factor for
+an account:
+
+1. The user enrolls via `POST /auth/totp/enroll` and confirms with
+   `POST /auth/totp/verify`.
+2. Confirming revokes every existing refresh token and session for that account.
+
+Existing access tokens remain valid until they expire
+(`ACCESS_TOKEN_TTL_SECONDS`, default 900s). Shorten that value before a rollout
+if you need immediate revocation.
+
+### New configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `MFA_CHALLENGE_TTL_SECONDS` | `300` | Lifetime of a login MFA challenge |
+| `MFA_MAX_ATTEMPTS` | `5` | Factor attempts allowed per challenge |
+| `TOTP_BACKUP_CODE_TTL_SECONDS` | `7776000` (90 days) | Backup-code lifetime |
+
+### Behavior of alternate login methods
+
+| Method | Result for an MFA-enabled account |
+| --- | --- |
+| Password (`/auth/login`, `/auth/token-login`) | Challenge required |
+| WebAuthn / passkey | Succeeds; the assertion is itself a possession factor |
+| Magic link | `403 MFA_REQUIRED` — does not downgrade to mailbox-only access |
+| SAML ACS | `403 mfa_required`; use password + factor |
+| Enterprise OIDC, federation, social OAuth | `mfa_required` error; use password + factor |
+| Passkey registered after TOTP was enabled | `403 MFA_REQUIRED` — treated as a single factor |
+| OAuth2 code exchange | `mfa_required` if the approving session had no recorded factor |
+
+A session created **before** MFA was enabled carries no factor, so it cannot be
+refreshed into a new session. Users must complete a fresh password + factor
+login.
+
+### Backup codes
+
+Backup codes are regenerated in a new format on the next enrollment or
+regeneration: 20 hex characters grouped as `XXXXX-XXXXX-XXXXX-XXXXX` (80 bits),
+stored as a keyed (peppered) hash, and expiring after 90 days.
+
+Existing 8-character backup codes were stored as a bare SHA-256 digest and
+cannot be read by the new keyed lookup. Users must regenerate their codes:
+
+```bash
+curl -X POST https://keystone.example.com/auth/totp/backup \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{"code":"123456"}'
+```
+
+If your deployment used the default encryption key, plan a re-enrollment
+window. `KEYSTONE_TOTP_ENCRYPTION_KEY` (or `KEYSTONE_INTERNAL_API_KEY`) is the
+key for both TOTP secrets and the backup-code pepper; **changing it invalidates
+all enrolled authenticators and backup codes**.
+
+### TOTP secret encryption
+
+New secrets are written with AES-256-GCM. Secrets written by earlier versions
+used AES-256-CBC and remain readable, so no action is required. Secrets are
+re-encrypted to the GCM format the next time they are written.
+
+---
+
+## Deployment checklist
+
+- [ ] Run `npm run db:migrate` before starting the new version.
+- [ ] Review `MFA_CHALLENGE_TTL_SECONDS` and `MFA_MAX_ATTEMPTS` for your
+      threat model.
+- [ ] Confirm `KEYSTONE_TOTP_ENCRYPTION_KEY` (or `KEYSTONE_INTERNAL_API_KEY`) is
+      set and stable. Without it, Keystone derives a predictable default.
+- [ ] Update clients that call `/auth/login`, `/auth/token-login`, or
+      `/auth/totp/backup`.
+- [ ] Ask existing TOTP users to regenerate their backup codes.
+- [ ] Confirm no alternate sign-in path is expected to work for
+      MFA-enabled accounts (SAML, OIDC, federation, magic link).
+- [ ] Shorten `ACCESS_TOKEN_TTL_SECONDS` if you need pre-enrollment access
+      tokens to die quickly.