@hilbras/keystone 2.5.0 → 3.0.0

package/docs/DEPLOYMENT.md

@@ -0,0 +1,257 @@
+# Deploying Keystone Online
+
+This guide explains how to run Hilbras Keystone on a public server so external projects can connect to it over the internet.
+
+---
+
+## Architecture
+
+```
+Internet
+   │
+   ├──► https://app.yourdomain.com     (your React/Vue/Angular app)
+   │
+   └──► https://auth.yourdomain.com    (Keystone identity server)
+             │
+             ├──► PostgreSQL
+             ├──► Redis
+             └──► Google / GitHub / etc.
+```
+
+Your frontend and Keystone run as two separate services. The frontend loads the Keystone SDK from the Keystone domain and talks to it via HTTPS.
+
+---
+
+## What you need
+
+1. A server or VPS (e.g. AWS, DigitalOcean, Hetzner, Fly.io).
+2. A domain name.
+3. Two DNS records pointing to your server:
+   - `auth.yourdomain.com` → your server IP
+   - `app.yourdomain.com` → your server IP (or another host for your frontend)
+4. Docker and Docker Compose installed on the server.
+5. SSL certificate (use Caddy, Nginx + Let's Encrypt, or Cloudflare).
+
+---
+
+## Step 1 — Prepare environment variables
+
+You can configure almost everything through the Keystone setup wizard in the browser. You only need a minimal `.env` to start the wizard the first time.
+
+Create `.env` on the server with just enough to launch the setup UI:
+
+```env
+NODE_ENV=production
+PORT=4001
+HOST=0.0.0.0
+KEYSTONE_SETUP_MODE=true
+```
+
+Then run:
+
+```bash
+docker compose up -d
+```
+
+Open `https://auth.yourdomain.com/setup` and fill in:
+
+- Database URL
+- Redis URL
+- Public Keystone URL (`https://auth.yourdomain.com`)
+- Client app URL (`https://app.yourdomain.com`)
+- Allowed CORS origins (`https://app.yourdomain.com`)
+- Cookie domain (`.yourdomain.com`)
+- Secure cookies (enabled for HTTPS)
+- Auto-generated internal API key and encryption key
+- Google OAuth credentials
+- Email/SMS providers
+
+The wizard writes `.env` for you. No file editing needed after the first launch.
+
+If you prefer to pre-configure everything in `.env` instead, use:
+
+```env
+NODE_ENV=production
+PORT=4001
+HOST=0.0.0.0
+
+DATABASE_URL=postgresql://hilbras:strong-password@postgres:5432/hilbras
+REDIS_URL=redis://redis:6379
+
+AUTH_API_PUBLIC_URL=https://auth.yourdomain.com
+CLIENT_APP_URL=https://app.yourdomain.com
+ALLOWED_ORIGINS=https://app.yourdomain.com
+
+COOKIE_DOMAIN=.yourdomain.com
+COOKIE_SECURE=true
+
+KEYSTONE_INTERNAL_API_KEY=change-me-to-a-long-random-string
+KEYSTONE_ENCRYPTION_KEY=...
+
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+
+EMAIL_PROVIDER=smtp
+EMAIL_FROM=noreply@yourdomain.com
+SMTP_HOST=smtp.yourprovider.com
+SMTP_PORT=587
+SMTP_USER=...
+SMTP_PASS=...
+SMTP_SECURE=true
+```
+
+---
+
+## Step 2 — Update Google OAuth redirect URI
+
+In Google Cloud Console, add:
+
+```
+https://auth.yourdomain.com/auth/callback/google
+```
+
+Remove or keep the localhost URI only for local development.
+
+---
+
+## Step 3 — Deploy with Docker Compose
+
+Copy the project to the server, then run:
+
+```bash
+docker compose up -d
+```
+
+This starts PostgreSQL, Redis, and Keystone.
+
+For the first run, enable setup mode so the wizard creates the owner account:
+
+```bash
+KEYSTONE_SETUP_MODE=true docker compose up -d
+```
+
+Then open the setup UI (port 5173 if exposed, or use the backend setup endpoints) and complete setup.
+
+---
+
+## Step 4 — Put Keystone behind HTTPS
+
+### Option A: Caddy (simplest)
+
+Create `Caddyfile`:
+
+```
+auth.yourdomain.com {
+  reverse_proxy localhost:4001
+}
+
+app.yourdomain.com {
+  root * /var/www/app
+  file_server
+}
+```
+
+Run Caddy:
+
+```bash
+caddy run
+```
+
+Caddy automatically obtains and renews Let's Encrypt certificates.
+
+### Option B: Nginx + Let's Encrypt
+
+Use `certbot` to obtain certificates and proxy to Keystone:
+
+```nginx
+server {
+  listen 443 ssl;
+  server_name auth.yourdomain.com;
+
+  ssl_certificate /etc/letsencrypt/live/auth.yourdomain.com/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/auth.yourdomain.com/privkey.pem;
+
+  location / {
+    proxy_pass http://localhost:4001;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    # $remote_addr, NOT $proxy_add_x_forwarded_for. The append form lets a client
+    # prepend a forged address, which then becomes the value Keystone believes.
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # Drop inbound identity headers. Keystone ignores them from untrusted peers
+    # anyway, but stripping them here keeps a misconfiguration from being
+    # exploitable and keeps the proxy honest.
+    proxy_set_header X-Forwarded-Client-Cert "";
+    proxy_set_header X-Client-Cert-Fingerprint "";
+    proxy_set_header X-Service-Account-Id "";
+  }
+}
+```
+
+**Set the trusted proxy list.** Since 2.0.0, Keystone does not believe
+forwarded headers unless the request arrived from a configured proxy, and it
+keys rate limits on the peer address otherwise — which, behind a reverse proxy,
+means every client shares one budget:
+
+```bash
+KEYSTONE_TRUSTED_PROXIES="127.0.0.1,::1"
+```
+
+Use the address the proxy connects from. Keep the list as narrow as possible.
+Full requirements, including why each header matters:
+[security/proxy-security.md](security/proxy-security.md).
+
+### Option C: Cloudflare
+
+Point your DNS to Cloudflare, enable the orange cloud, and set SSL/TLS to **Full (strict)**. No extra certificate setup needed.
+
+---
+
+## Step 5 — Update your project's script tag
+
+In your frontend `index.html`, change the SDK URL to production:
+
+```html
+<script
+  src="https://auth.yourdomain.com/sdk/keystone-dropin.js"
+  data-keystone-url="https://auth.yourdomain.com"
+  data-keystone-after-login="https://app.yourdomain.com/dashboard"
+></script>
+```
+
+And connect the project:
+
+```html
+<script>
+  Keystone.connect("my-project", "https://app.yourdomain.com/callback")
+    .then((c) => console.log("Connected:", c.clientId));
+</script>
+```
+
+---
+
+## Important production checklist
+
+- [ ] HTTPS everywhere
+- [ ] `COOKIE_SECURE=true`
+- [ ] `COOKIE_DOMAIN=.yourdomain.com` (with leading dot)
+- [ ] `ALLOWED_ORIGINS` set to your frontend domain only
+- [ ] Strong `KEYSTONE_INTERNAL_API_KEY` and `KEYSTONE_ENCRYPTION_KEY`
+- [ ] Google OAuth redirect URI is the HTTPS production URL
+- [ ] Database and Redis are not exposed to the internet
+- [ ] Regular backups of PostgreSQL data
+- [ ] Server firewall allows only ports 80, 443, and SSH
+
+---
+
+## Scaling
+
+For high traffic:
+
+- Use a managed PostgreSQL (AWS RDS, Supabase, etc.).
+- Use managed Redis (Redis Cloud, AWS ElastiCache).
+- Run multiple Keystone containers behind a load balancer.
+- Ensure `KEYSTONE_ENCRYPTION_KEY` and signing keys are shared between instances.

package/docs/INTEGRATION.md

@@ -0,0 +1,336 @@
+# Integrating Keystone with Your Projects
+
+Keystone exposes **standard OIDC/OAuth2** endpoints, a **REST API**, and **machine credentials**, so any application — web, mobile, CLI, or microservice — can use it as its identity provider.
+
+---
+
+## 1. Web / SPA: OIDC Authorization Code + PKCE
+
+The recommended flow for React, Vue, Angular, Svelte, Next.js (client-side), and mobile apps.
+
+### Discovery
+
+```bash
+curl http://localhost:4001/.well-known/openid-configuration
+```
+
+### Example: React helper
+
+```ts
+// auth.ts
+const ISSUER = "http://localhost:4001";
+const CLIENT_ID = "your-app-client-id"; // from /v1/admin/organizations/:id/applications
+
+export function generateCodeVerifier() {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return btoa(String.fromCharCode(...array))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+async function sha256(plain: string) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(plain);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return btoa(String.fromCharCode(...new Uint8Array(hash)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export async function startLogin() {
+  const verifier = generateCodeVerifier();
+  const challenge = await sha256(verifier);
+  localStorage.setItem("keystone-code-verifier", verifier);
+
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: CLIENT_ID,
+    redirect_uri: "http://localhost:5173/callback",
+    scope: "openid profile email",
+    state: crypto.randomUUID(),
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+  });
+
+  window.location.href = `${ISSUER}/oauth2/authorize?${params.toString()}`;
+}
+
+export async function exchangeCode(code: string) {
+  const verifier = localStorage.getItem("keystone-code-verifier");
+  if (!verifier) throw new Error("Missing PKCE verifier");
+
+  const res = await fetch(`${ISSUER}/oauth2/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: "http://localhost:5173/callback",
+      client_id: CLIENT_ID,
+      code_verifier: verifier,
+    }),
+  });
+
+  const data = await res.json();
+  localStorage.setItem("keystone-access-token", data.access_token);
+  localStorage.setItem("keystone-refresh-token", data.refresh_token);
+  return data;
+}
+```
+
+### Callback page
+
+```tsx
+// pages/callback.tsx
+import { useEffect } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
+import { exchangeCode } from "./auth";
+
+export default function Callback() {
+  const router = useRouter();
+  const params = useSearchParams();
+
+  useEffect(() => {
+    const code = params.get("code");
+    if (!code) return;
+    exchangeCode(code).then(() => router.replace("/dashboard"));
+  }, [params, router]);
+
+  return <p>Signing in…</p>;
+}
+```
+
+---
+
+## 2. Server-side web app (Next.js App Router / SSR)
+
+Use Keystone as an external OAuth provider with NextAuth.js, Auth.js, or a custom server-side OAuth flow.
+
+### NextAuth.js provider example
+
+```ts
+// auth.ts (NextAuth v5 / Auth.js)
+import NextAuth from "next-auth";
+import { OAuthConfig } from "next-auth/providers";
+
+const keystoneProvider: OAuthConfig<any> = {
+  id: "keystone",
+  name: "Keystone",
+  type: "oauth",
+  issuer: "http://localhost:4001",
+  authorization: { params: { scope: "openid profile email" } },
+  checks: ["pkce", "state"],
+  clientId: process.env.KEYSTONE_CLIENT_ID!,
+  clientSecret: process.env.KEYSTONE_CLIENT_SECRET!,
+  profile(profile) {
+    return {
+      id: profile.sub,
+      email: profile.email,
+      name: profile.name,
+      image: profile.picture,
+    };
+  },
+};
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [keystoneProvider],
+});
+```
+
+> Store `clientSecret` server-side only.
+
+---
+
+## 3. Backend / microservice: API keys
+
+For service-to-service or machine-to-machine calls, create an API key in the dashboard or via the API, then send it as a bearer token.
+
+### Create an API key
+
+```bash
+curl -X POST http://localhost:4001/auth/api-keys \
+  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"payment-service","scopes":["read:users","write:orders"]}'
+```
+
+Response includes `key` once. Save it securely.
+
+### Use the API key
+
+```bash
+curl http://localhost:4001/auth/me \
+  -H "Authorization: Bearer $API_KEY"
+```
+
+### Check authorization
+
+```bash
+curl -X POST http://localhost:4001/v1/authz/check \
+  -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "organizationId": "00000000-0000-0000-0000-000000000000",
+    "resource": "order",
+    "action": "create"
+  }'
+```
+
+Authorization checks are organization-scoped. Platform roles (`owner`/`user`) and organization roles (`owner`/`admin`/`member`) are separate; never infer one from the other. User-management responses are redacted and do not include password hashes or TOTP secrets.
+
+---
+
+## 4. Python / FastAPI backend
+
+```python
+import httpx
+from jose import jwt, jwk
+from jose.utils import base64url_decode
+import requests
+
+KEYSTONE_URL = "http://localhost:4001"
+JWKS = requests.get(f"{KEYSTONE_URL}/.well-known/jwks.json").json()
+
+def get_signing_key(token: str):
+    header = jwt.get_unverified_header(token)
+    for key in JWKS["keys"]:
+        if key["kid"] == header["kid"]:
+            return key
+    raise ValueError("Signing key not found")
+
+def verify_token(token: str):
+    key = get_signing_key(token)
+    return jwt.decode(token, key, algorithms=["RS256"], issuer=KEYSTONE_URL)
+
+async def fetch_user(token: str):
+    async with httpx.AsyncClient() as client:
+        r = await client.get(
+            f"{KEYSTONE_URL}/oauth2/userinfo",
+            headers={"Authorization": f"Bearer {token}"}
+        )
+        r.raise_for_status()
+        return r.json()
+```
+
+---
+
+## 5. Mobile apps
+
+Mobile apps should use the same **Authorization Code + PKCE** flow as SPAs. Use a system browser (ASWebAuthenticationSession on iOS, Custom Tabs on Android) to open:
+
+```
+http://localhost:4001/oauth2/authorize?response_type=code&client_id=...&redirect_uri=myapp://callback&scope=openid%20profile%20email&code_challenge=...&code_challenge_method=S256&state=...
+```
+
+Register `myapp://callback` as the redirect scheme in your mobile app.
+
+---
+
+## 6. CLI / scripts
+
+For CLI tools, use `/auth/token-login` with a user's email/password (if you accept password input) or issue a service account / API key.
+
+```bash
+export TOKEN=$(curl -s -X POST http://localhost:4001/auth/token-login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"owner@example.com","password":"..."}' | jq -r .accessToken)
+
+curl -H "Authorization: Bearer $TOKEN" http://localhost:4001/auth/me
+```
+
+If the account has MFA enabled, the password step returns `401` with
+`code: "MFA_REQUIRED"` and no token. Exchange the returned challenge for one:
+
+```bash
+CHALLENGE=$(curl -s -X POST http://localhost:4001/auth/token-login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"owner@example.com","password":"..."}' | jq -r .challenge)
+
+read -r -p "Authenticator code: " CODE
+
+export TOKEN=$(curl -s -X POST http://localhost:4001/auth/mfa/verify \
+  -H "Content-Type: application/json" \
+  -d "$(jq -nc --arg c "$CHALLENGE" --arg k "$CODE" '{challenge:$c, code:$k, factor:"totp"}')" \
+  | jq -r .accessToken)
+```
+
+The challenge is single-use and short-lived, so request a fresh one per attempt.
+A TOTP time-step is also accepted only once: repeating the same code is rejected
+even with a new challenge.
+
+---
+
+## 7. Federation: let users sign in through external IdPs
+
+Keystone acts as the broker. Your app only ever talks to Keystone.
+
+```
+User → Google / Azure / Okta → Keystone → Keystone access token
+```
+
+From your app's perspective, the flow is identical to section 1 — redirect to Keystone's OAuth2 authorize endpoint. Keystone handles the external IdP dance and returns your app a Keystone token.
+
+Enable providers in the admin dashboard or by setting environment variables (`GOOGLE_CLIENT_ID`, `GITHUB_CLIENT_ID`, etc.).
+
+---
+
+## 8. Register your application in Keystone
+
+Before any OAuth2 flow, register your app under an organization:
+
+```bash
+curl -X POST http://localhost:4001/v1/admin/organizations/:orgId/applications \
+  -H "Authorization: Bearer $OWNER_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "My SaaS",
+    "redirectUris": ["http://localhost:5173/callback"],
+    "allowedOrigins": ["http://localhost:5173"]
+  }'
+```
+
+Response:
+
+```json
+{
+  "id": "...",
+  "clientId": "my-saas-...",
+  "clientSecret": "..." // store securely
+}
+```
+
+---
+
+## 9. Token verification summary
+
+| Token type | Verify at | Use case |
+|------------|-----------|----------|
+| JWT access token | `/.well-known/jwks.json` | User sessions, SPAs, mobile |
+| API key | `/auth/me` or locally against hash | Machine-to-machine |
+| Refresh token | `/auth/refresh` | Silent re-authentication |
+| ID token | JWKS + issuer + audience | OIDC clients |
+
+---
+
+## 10. Security checklist
+
+- Always use **PKCE** for public clients (SPAs, mobile, desktop).
+- Store `clientSecret` server-side only.
+- Verify the JWT issuer (`iss`) and audience (`aud`) if you set them.
+- Use short-lived access tokens and rotate refresh tokens.
+- Scope API keys to the minimum permissions required.
+- Call `/v1/authz/check` for sensitive actions even if the user is authenticated.
+
+---
+
+## Quick start for a new project
+
+1. Run Keystone locally: `./start.sh`
+2. Complete setup and create an owner account.
+3. Create an organization and application via the admin dashboard.
+4. Copy the `clientId` and `clientSecret`.
+5. Use the OIDC endpoints above in your app.
+6. Validate tokens with `/.well-known/jwks.json`.