okengine 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {

package/site/content/docs/get-started/why.mdx

@@ -93,16 +93,16 @@ ninth element — the set of eight is closed.
 
 ## Traditional vs OKE
 
-| Seam               | Maintained by hand                                        | Derived by OKE                                                                  |
-| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                                     |
-| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                                      |
-| HTTP glue          | Middleware copied per repo                                | Official plugins — `securityHeaders`, `cors`, `csrf`, compression, IP allowlist |
-| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                                       |
-| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                               |
-| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                                    |
-| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev --docker`                        |
-| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                           |
+| Seam               | Maintained by hand                                        | Derived by OKE                                                          |
+| ------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                             |
+| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                              |
+| HTTP glue          | Middleware copied per repo                                | Official plugins — `headers`, `cors`, `csrf`, compression, IP allowlist |
+| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                               |
+| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                       |
+| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                            |
+| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev --docker`                |
+| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                   |
 
 ## Ambition, stated plainly
 

package/site/content/docs/plugins/headers.mdx

@@ -2,18 +2,18 @@
 title: "Headers"
 description: "Official plugin — the complete secure-headers set on every HTTP response, failures included. Full helmet.js parity with API-first defaults, a CSP builder with report-only mode, and live DB-driven config."
 icon: "ShieldCheck"
-source: "src/plugins/security-headers.ts"
+source: "src/plugins/headers.ts"
 ---
 
-`securityHeaders()` stamps security headers on **every** HTTP flow response — successes, failures, and short-circuits alike, because it runs at `onResponse`, the last pipeline stage. An explicit value your app already set is never overridden unless you ask for it.
+`headers()` stamps security headers on **every** HTTP flow response — successes, failures, and short-circuits alike, because it runs at `onResponse`, the last pipeline stage. An explicit value your app already set is never overridden unless you ask for it.
 
 ## Quick start
 
 ```typescript title="src/app.ts"
 import { oke } from "okengine";
-import { securityHeaders } from "okengine/plugins";
+import { headers } from "okengine/plugins";
 
-export const app = oke({ name: "shop", env: "dev" }).plug(securityHeaders());
+export const app = oke({ name: "shop", env: "dev" }).plug(headers());
 ```
 
 Every HTTP response now carries:
@@ -75,7 +75,7 @@ Beyond parity: headers land on **failures too** (middleware that only wraps happ
 
 ```typescript
 .plug(
-  securityHeaders({
+  headers({
     contentSecurityPolicy: {
       directives: { scriptSrc: ["'self'", "https://cdn.example.com"] }, // merged over the defaults
       reportOnly: true, // Content-Security-Policy-Report-Only while you tune
@@ -97,18 +97,18 @@ Beyond parity: headers land on **failures too** (middleware that only wraps happ
 Header policy is exactly the config you want to flip without a redeploy — enable HSTS the day HTTPS lands, tighten the CSP after an audit. Pass a `configSource()` and options follow the database within one sync interval:
 
 ```typescript
-const headers = configSource({
-  plugin: "security-headers",
+const headerConfig = configSource({
+  plugin: "headers",
   code: { hsts: false }, // safe floor for local dev
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), headers.sync());
-export const app = oke({ name: "shop", env: "dev" }).plug(securityHeaders(headers));
+on(every("30s"), headerConfig.sync());
+export const app = oke({ name: "shop", env: "dev" }).plug(headers(headerConfig));
 ```
 
 ```sql
-INSERT INTO security_headers_config ("key", "value")
+INSERT INTO headers_config ("key", "value")
 VALUES ('config', '{"hsts": true}');
 ```
 

package/site/content/docs/plugins/passkey.mdx

@@ -1,18 +1,18 @@
 ---
 title: "Passkey"
-description: "Official plugin — simplified WebAuthn register and authenticate under /auth."
+description: "Official plugin — WebAuthn register and authenticate under /auth with signature and origin checks."
 icon: "FingerprintPattern"
 source: "docs/spec/unified-theory.md"
 ---
 
-`passkey()` adds register and authenticate Flows for passkey-shaped credentials (`oke_passkeys`).
-v1 is a simplified ceremony — options return a challenge; register/authenticate accept the
-payload your client posts (not a full browser WebAuthn SDK).
+`passkey()` adds register and authenticate Flows for WebAuthn credentials (`oke_passkeys`).
+Options return a challenge; register and authenticate verify `clientDataJSON` origin + challenge,
+`authenticatorData` rpId hash, and an ECDSA P-256 signature against the stored SPKI public key.
 
 <Callout title="The one rule">
   Enable `gate.auth`, then `.plug(passkey())`. Registration needs a Bearer session; authenticate is
-  public. Wire `navigator.credentials` (or tests) yourself — the plugin stores and verifies the
-  posted fields.
+  public. Post the full ceremony fields — presence of a stored credential alone never issues a
+  session.
 </Callout>
 
 ## Quick start
@@ -30,7 +30,7 @@ export const app = oke({
   name: "shop",
   env: "local",
   gate: { auth: {} },
-}).plug(passkey());
+}).plug(passkey({ origins: ["http://localhost", "https://localhost"] }));
 ```
 
 </Step>
@@ -45,10 +45,13 @@ const opts = await api.auth.passkeyRegisterOptions({});
 // opts.data: { challenge, rpId, userId }
 
 await api.auth.passkeyRegister({
-  credentialId: "...",
-  publicKey: "...",
+  credentialId: "...", // base64url
+  publicKey: "...", // base64url SPKI (ECDSA P-256)
   userId: opts.data!.userId,
   challenge: opts.data!.challenge,
+  clientDataJSON: "...", // base64url JSON { type, challenge, origin }
+  authenticatorData: "...", // base64url
+  signature: "...", // base64url ECDSA over authData || SHA-256(clientDataJSON)
 });
 ```
 
@@ -60,15 +63,18 @@ Paths: `POST /auth/passkey/register/options`, `POST /auth/passkey/register`.
 ### Authenticate
 
 ```typescript
-await api.auth.passkeyAuthenticateOptions({});
+const opts = await api.auth.passkeyAuthenticateOptions({});
 const { data } = await api.auth.passkeyAuthenticate({
   credentialId: "...",
-  userId: "...",
+  challenge: opts.data!.challenge,
+  clientDataJSON: "...",
+  authenticatorData: "...",
+  signature: "...",
 });
 ```
 
 Paths: `POST /auth/passkey/authenticate/options`, `POST /auth/passkey/authenticate`.
-v1 issues a session when the stored credential matches `userId`.
+Challenges are single-use; wrong origin → `invalid_origin`; bad signature → `invalid_credentials`.
 
 </Step>
 
@@ -76,14 +82,15 @@ v1 issues a session when the stored credential matches `userId`.
 
 ## Options
 
-| Option       | Type                | Default       | Meaning                          |
-| ------------ | ------------------- | ------------- | -------------------------------- |
-| `secret`     | `string`            | active\*      | HMAC secret (\*from `gate.auth`) |
-| `sessions`   | `SessionStore`      | active\*      | Session store                    |
-| `now`        | `() => number`      | `Date.now`    | Injectable clock                 |
-| `passkeys`   | `PasskeyStore`      | new           | Credential → user mapping        |
-| `challenges` | `VerificationStore` | new           | Registration / auth challenges   |
-| `rpId`       | `string`            | `"localhost"` | Relying party id in options      |
+| Option       | Type                | Default                                    | Meaning                          |
+| ------------ | ------------------- | ------------------------------------------ | -------------------------------- |
+| `secret`     | `string`            | active\*                                   | HMAC secret (\*from `gate.auth`) |
+| `sessions`   | `SessionStore`      | active\*                                   | Session store                    |
+| `now`        | `() => number`      | `Date.now`                                 | Injectable clock                 |
+| `passkeys`   | `PasskeyStore`      | new                                        | Credential → user mapping        |
+| `challenges` | `VerificationStore` | new                                        | Registration / auth challenges   |
+| `rpId`       | `string`            | `"localhost"`                              | Relying party id                 |
+| `origins`    | `string[]`          | `["http://localhost","https://localhost"]` | Allowed `clientDataJSON.origin`  |
 
 ## Surfaces
 
@@ -94,8 +101,8 @@ v1 issues a session when the stored credential matches `userId`.
 | `auth.passkeyAuthenticateOptions` | `POST /auth/passkey/authenticate/options` | `gate.public` + otp rate |
 | `auth.passkeyAuthenticate`        | `POST /auth/passkey/authenticate`         | `gate.public` + otp rate |
 
-**Consequence:** production apps should replace the simplified verify with a standards-compliant
-WebAuthn verifier when you leave local/test.
+**Consequence:** a stolen `credentialId` without the private key cannot mint a session. Set
+`origins` to your real app origins before production.
 
 ## Troubleshooting
 
@@ -104,11 +111,16 @@ WebAuthn verifier when you leave local/test.
 
 Sign in with another method first. `userId` in the body must match the Bearer session.
 
+</Accordion>
+<Accordion title="authenticate returns invalid_origin">
+
+`clientDataJSON.origin` must be in `passkey({ origins })`. Default allows only localhost HTTP/S.
+
 </Accordion>
 <Accordion title="authenticate returns invalid_credentials">
 
-Unknown `credentialId`, or `userId` does not match the stored credential. Re-run registration
-after a successful session.
+Unknown `credentialId`, consumed/expired challenge, bad signature, or rpId hash mismatch.
+Re-run authenticate options for a fresh challenge, then sign with the enrolled private key.
 
 </Accordion>
 </Accordions>

package/site/content/docs/plugins/two-factor.mdx

@@ -7,6 +7,7 @@ source: "docs/spec/unified-theory.md"
 
 `twoFactor()` adds RFC 6238 TOTP (HMAC-SHA1, 6 digits, 30s) after someone already has a session.
 Enable returns a secret, `otpauth://` URL, and recovery codes; verify mints a new session.
+TOTP codes are compared in constant time (±1 step window).
 
 <Callout title="The one rule">
   Enable `gate.auth`, then `.plug(twoFactor())`. Enable and disable need a Bearer session —
@@ -103,7 +104,7 @@ enable. A recovery code works once, then is consumed.
 
 ## Learn more
 
-- [Passkey](/docs/plugins/passkey) — WebAuthn-shaped register / authenticate
+- [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
 - [Gate](/docs/elements/gate) — session + policies
 - [Username](/docs/plugins/username) — first factor to enroll against
 

package/src/auth/constant-time.ts

@@ -0,0 +1,22 @@
+/**
+ * Constant-time equality for auth secrets (OTP, claim codes, challenges).
+ */
+
+/**
+ * Constant-time string equality (UTF-16 code units).
+ * Length mismatches still scan to `max(len)` so timing does not leak length
+ * beyond the longer operand.
+ *
+ * @param a - Expected
+ * @param b - Candidate
+ */
+export function constantTimeEqual(a: string, b: string): boolean {
+  const len = Math.max(a.length, b.length);
+  let mismatch = a.length === b.length ? 0 : 1;
+  for (let i = 0; i < len; i++) {
+    const ac = a.charCodeAt(i) || 0;
+    const bc = b.charCodeAt(i) || 0;
+    mismatch |= ac ^ bc;
+  }
+  return mismatch === 0;
+}

package/src/auth/index.ts

@@ -75,6 +75,8 @@ export {
   type VerificationRow,
 } from "./verification.ts";
 
+export { constantTimeEqual } from "./constant-time.ts";
+
 export {
   createIdentityStore,
   createUserWithPassword,

package/src/cli/competitor-mention-removal.test.ts

@@ -2,7 +2,7 @@
  * Gate: named competitor comparisons stay gone from the tracked tree.
  *
  * Mirrors {@link ./doc-staleness.test.ts} — `git grep` must find zero hits
- * (the security-headers decoy header fixture may still use a common
+ * (the headers decoy header fixture may still use a common
  * `X-Powered-By` value; that path is allow-listed).
  */
 
@@ -28,8 +28,8 @@ const FORBIDDEN_COMPARISON_PATH = ["get-started/", "comparison"].join("");
 /** Word-boundary classic Node framework — `-F` false-positives on `CallExpression`. */
 const FORBIDDEN_EXPRESS = ["\\b", "Ex", "press", "\\b"].join("");
 
-/** Decoy `X-Powered-By` fixture value in the security-headers plugin tests. */
-const EXPRESS_ALLOW = ["src/plugins/security-headers.test.ts:"];
+/** Decoy `X-Powered-By` fixture value in the headers plugin tests. */
+const EXPRESS_ALLOW = ["src/plugins/headers.test.ts:"];
 
 /**
  * Run `git grep -F` and assert zero matches after ignoring allow-listed paths.