@hilbras/keystone 2.6.0 → 3.0.0

package/docs/security/scopes.md

@@ -0,0 +1,45 @@
+# API key scopes and machine principals
+
+Covers SEC-023, SEC-024 and SEC-025.
+
+## The scope registry is the authority
+
+`src/services/scopes.ts` holds every scope the API recognises, who may hold it,
+and which principals are permitted to exercise it. Nothing outside that file
+decides what a credential may do.
+
+## There is no wildcard
+
+The registry contained a `service_account` entry that any key carrying could
+present against every scope check. A narrowly scoped key therefore behaved as a
+fully privileged one — the scope list on the key was advisory rather than
+binding.
+
+It is gone. Every scope must be named, and `hasScopes` compares explicitly.
+
+## Enforcement fails closed
+
+`requireScopes` returned early when `request.apiKeyId` was absent, so any
+authenticated path reaching a scoped route without going through key
+authentication skipped the check entirely. A missing key is now treated as *no
+authority*, not as *no restriction*.
+
+## Some operations are human-only
+
+A service account is a machine. It has no password, no second factor and no
+browser, so operations that require a person present are refused to it:
+`profile:*` and `mfa:manage`.
+
+The guard is `requireHumanPrincipal` in `src/plugins/machinePrincipal.ts`.
+
+> **Placement matters.** It must come **after** `app.authenticate` in a
+> `preHandler`, because that is what populates `request.serviceAccount`. Placed
+> before, it never sees a service account and silently permits everything — the
+> guard appears to work and does nothing.
+
+## Migration from 2.4.0
+
+Scope names changed in v2.6.0. The `service_account` wildcard no longer exists,
+so a key that relied on it must be reissued with explicit scopes. Keys whose
+scopes are no longer recognised are rejected at creation rather than accepted and
+silently ignored.

package/docs/security/supply-chain.md

@@ -0,0 +1,49 @@
+# Supply chain
+
+Covers SEC-011.
+
+## What runs on every push and pull request
+
+`.github/workflows/supply-chain.yml`:
+
+| Job | Tool | Gate |
+| --- | --- | --- |
+| OSV vulnerability scan | osv-scanner | fails on any advisory |
+| npm audit | npm | fails at `high` |
+| Dependency review | GitHub action | fails on a new advisory in the diff |
+| SBOM | CycloneDX | artefact, always produced |
+| Container scan | Trivy | image, filesystem and secret scanning |
+| License report | license-checker | fails on an unknown or disallowed licence |
+
+`ci.yml` runs the same dependency and licence gates so a branch cannot be green
+locally and red on the merge.
+
+## The image finding that no scanner could see
+
+The production Dockerfile installed npm so it could prune dev dependencies. That
+npm carried **eight high-severity advisories** — and `npm audit` and the OSV
+scanner both read the lockfile, not the image. Every configured gate was
+satisfied while the shipped artefact was the vulnerable one.
+
+npm is removed from the runtime stage. Pruning happens at build time in a stage
+that is not part of the published image.
+
+This is worth stating plainly because it is not a scanner gap that more
+scanning would close: the tools were all present, all passing, and all reading a
+different artefact from the one being shipped. Finding it required looking at what
+was actually in the image.
+
+## Release gate
+
+`release.yml` refuses to publish unless every one of the following holds:
+
+- a critical or high advisory exists with no documented exception
+- the security suite passes
+- typecheck, lint and build pass
+- the dependency audit passes
+- secret scanning passes
+- the security registry validates
+- the release metadata is consistent
+
+Exceptions live in `docs/security/registry-exceptions.md` and must name the
+advisory, the reason, and an expiry. An undocumented exception fails the gate.

package/docs/security/trust-boundaries.md

@@ -0,0 +1,111 @@
+# Trust Boundaries
+
+Keystone's security model rests on one distinction: **which values a client
+cannot forge**. This document names those values, states where they come from,
+and lists what is deliberately not trusted.
+
+## The deployment model
+
+```text
+                    ┌──────────────────────────────────────────┐
+                    │              Internet                    │
+                    └───────────────────┬──────────────────────┘
+                                        │  attacker-controlled
+                    ┌───────────────────▼──────────────────────┐
+                    │        Trusted reverse proxy (LB)        │
+                    │  - terminates TLS                         │
+                    │  - validates client certificates (mTLS)   │
+                    │  - overwrites forwarded identity headers │
+                    └───────────────────┬──────────────────────┘
+                                        │  peer address is the proxy's
+                    ┌───────────────────▼──────────────────────┐
+                    │                Keystone                   │
+                    │  trusts forwarded headers ONLY from       │
+                    │  KEYSTONE_TRUSTED_PROXIES                 │
+                    └──────────────────────────────────────────┘
+```
+
+Keystone may also run with no proxy at all. Every rule below holds in both
+layouts; only the trusted-proxy list changes.
+
+## Unforgeable values
+
+| Value | Source | Trustworthy because |
+| --- | --- | --- |
+| Peer address | TCP connection (`socket.remoteAddress`) | Established by the network stack; a client cannot set it |
+| Session cookie / bearer token | Cryptographic check against stored state | Requires a secret the client must already hold |
+| API key | Hashed lookup against a stored secret | Same |
+| Client certificate | Validated by the proxy, forwarded as a fingerprint | Only believed from a trusted peer, and bound to a service account in the database |
+
+## Forged values
+
+These arrive in request headers and are attacker-controlled unless the peer is a
+configured trusted proxy:
+
+- `x-forwarded-for`, `x-real-ip`, `forwarded` — the apparent client address
+- `x-forwarded-client-cert`, `x-client-cert-fingerprint` — the client certificate
+- `x-service-account-id` — a service account identifier
+
+When the peer is **not** a trusted proxy, Keystone deletes these headers in an
+`onRequest` hook before routing, authentication, or any handler runs. Stripping
+rather than ignoring them means a route added later cannot read a spoofed
+identity by accident.
+
+## Trust decisions and where they are made
+
+| Decision | Made in | Rule |
+| --- | --- | --- |
+| Is this peer a trusted proxy? | `isFromTrustedProxy()` | Peer address is in `KEYSTONE_TRUSTED_PROXIES` |
+| What is the client address? | `clientAddress()` | Forwarded headers only when the peer is trusted; otherwise the peer |
+| Is this certificate identity real? | `extractClientCert()` | Requires a trusted peer **and** a well-formed SHA-256 fingerprint |
+| Which service account is it? | `resolveByFingerprint()` | The fingerprint is bound to exactly one account in the database |
+
+All four live in `src/services/trustedProxies.ts` and `src/plugins/mtls.ts`.
+
+## Identity must come from a credential
+
+A service account authenticates in one of two ways, and never a third:
+
+```text
+validated client certificate   (fingerprint bound to the account)
+        OR
+authenticated credential       (API key, session, or bearer token)
+```
+
+There is deliberately **no** header-only path. `x-service-account-id` is accepted
+only as a hint alongside a valid certificate, and only when the account it names
+is the account bound to the presented certificate. A mismatch fails rather than
+falling back — a disagreement is treated as a spoofing signal.
+
+## Threat assumptions
+
+These are believed, and a deployment that violates them is not supported:
+
+1. **The proxy is operated by you.** If an attacker controls a host inside the
+   trusted range, they control the identity headers.
+2. **The proxy overwrites, not appends.** It must set `x-forwarded-for` itself.
+   A proxy that appends to a client-supplied value lets the client prepend.
+3. **The trusted range is as narrow as the deployment allows.** Trusting a
+   whole `0.0.0.0/0` or a large shared-VPC range disables the boundary.
+4. **TLS is terminated before Keystone.** Certificate validity is the proxy's
+   responsibility; Keystone only compares a fingerprint it was told about.
+5. **Database access is trusted.** Whoever can write to `service_accounts` can
+   bind a certificate to an account.
+
+### What is *not* protected here
+
+- **Certificate chain validation** is the proxy's job. Keystone verifies that a
+  fingerprint is well-formed and bound to an account; it does not re-validate the
+  chain or the CA. See [mtls.md](./mtls.md).
+- **A trusted proxy that is compromised** is a full identity bypass by design.
+  This is inherent to the mTLS deployment model, not a Keystone defect.
+- **Spoofing against a shared egress IP** cannot be distinguished by peer
+  address. Deploy per-service egress ranges if callers share a NAT.
+
+## Consequences of a misconfiguration
+
+| Misconfiguration | Result |
+| --- | --- |
+| `KEYSTONE_TRUSTED_PROXIES` unset while behind a proxy | All forwarded headers stripped; rate limiting keys on the proxy's address, so **all** clients share one budget. Clients see rate limits they should not. |
+| Range too broad (e.g. a shared VPC CIDR) | Any host in that range can assert any client identity, including a certificate fingerprint. |
+| Keystone exposed directly to the internet while a proxy range is configured | An attacker's direct request is not from a trusted peer, so it is still safe — but the proxy path is the only one that can carry identity. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilbras/keystone",
-  "version": "2.6.0",
+  "version": "3.0.0",
   "license": "MIT",
   "description": "Hilbras Keystone — standalone identity platform: authentication, MFA, authorization, enterprise SSO, SCIM, and token issuance.",
   "repository": {
@@ -18,6 +18,7 @@
   "files": [
     "dist",
     "!dist/tests",
+    "docs",
     "CHANGELOG.md",
     "README.md"
   ],
@@ -28,7 +29,7 @@
     "dev": "tsx watch src/index.ts",
     "dev:setup": "KEYSTONE_SETUP_MODE=true tsx watch src/setup-server.ts",
     "dev:all": "./start.sh",
-    "build": "tsc && npm run copy:migrations",
+    "build": "npm run clean && tsc && npm run copy:migrations",
     "build:sdk": "cd packages/keystone-sdk && npm run build",
     "build:all": "npm run build:sdk && npm run build && cd frontend && npm run build",
     "copy:migrations": "mkdir -p dist/db/migrations && cp -r src/db/migrations/* dist/db/migrations/",
@@ -43,11 +44,17 @@
     "db:studio": "drizzle-kit studio",
     "db:seed": "tsx src/db/seed.ts",
     "db:reencrypt-oidc-secrets": "node dist/db/reencryptOidcSecrets.js",
-    "test": "node --test --test-force-exit --test-concurrency=1 --test-timeout=60000 dist/tests/*.test.js dist/tests/**/*.test.js dist/tests/**/**/*.test.js",
-    "test:security": "node --test --test-force-exit --test-concurrency=1 --test-timeout=60000 dist/tests/security/*.test.js dist/tests/security/**/*.test.js",
+    "test": "node --test --test-force-exit --test-concurrency=1 --test-timeout=60000 dist/tests/*.test.js dist/tests/*/*.test.js dist/tests/*/*/*.test.js dist/tests/*/*/*/*.test.js",
+    "test:security": "node --test --test-force-exit --test-concurrency=1 --test-timeout=60000 dist/tests/security/*.test.js dist/tests/security/*/*.test.js dist/tests/security/*/*/*.test.js dist/tests/security/*/*/*/*.test.js",
     "test:all": "npm test && cd frontend && npm run test:e2e",
     "setup": "./install.sh",
-    "start:all": "./start.sh"
+    "start:all": "./start.sh",
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "registry:check": "node scripts/verify-security-registry.mjs",
+    "registry:render": "node scripts/render-security-registry.mjs",
+    "reaudit:check": "node scripts/render-reaudit-matrix.mjs --check",
+    "reaudit:render": "node scripts/render-reaudit-matrix.mjs",
+    "review:api": "node scripts/review-api-surface.mjs"
   },
   "dependencies": {
     "@authenio/samlify-node-xmllint": "^2.0.0",
@@ -87,5 +94,7 @@
     "reflect-metadata": "^0.2.2",
     "tsx": "^4.15.0",
     "typescript": "^7.0.2"
-  }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
 }