okengine 0.5.0 → 0.6.0

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/site/content/docs/reference/configuration.mdx

@@ -76,9 +76,12 @@ images: {
   "store.files": "rustfs/rustfs:1.0.0-beta.11",
   "channel.email": "axllent/mailpit:v1.22.3",
   vault: "openbao/openbao:2.6.1",
+  ai: "ollama/ollama:latest",
 },
 ```
 
+For `ai`, the Ollama recipe pulls `OKE_AI_MODEL` (default `qwen3.5:9b` — a balanced local-dev starting point; override freely; on Apple Silicon prefer `qwen3.5:9b-mlx`) and writes `OKE_AI_URL`.
+
 ## i18n
 
 | Option    | Type       | Default | Meaning                                     |
@@ -91,6 +94,10 @@ images: {
 i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
 ```
 
+`fx.t` catalogs are ICU strings from `defineLocale` / `defineMessages` — see
+[i18n](/docs/reference/i18n). Built-ins also cover failure `error.message` and
+OKE cause/fix; Channel templates keep separate `locales` + `{{field}}` bodies.
+
 ## tenancy
 
 Multi-tenant isolation policy.

package/site/content/docs/reference/environment-variables.mdx

@@ -72,11 +72,16 @@ Written by the first-boot bootstrap; you normally only set these when pointing a
 
 ## AI providers
 
-| Variable            | Used for                                |
-| ------------------- | --------------------------------------- |
-| `ANTHROPIC_API_KEY` | `anthropic` driver credential           |
-| `ANTHROPIC_MODEL`   | Model override for the anthropic driver |
-| `OPENAI_API_KEY`    | `openai-compatible` driver credential   |
+| Variable            | Used for                                                                                                                                  | Default when unset                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `ANTHROPIC_API_KEY` | `anthropic` driver credential                                                                                                             | —                                 |
+| `ANTHROPIC_MODEL`   | Model override for the anthropic driver                                                                                                   | —                                 |
+| `OPENAI_API_KEY`    | `openai-compatible` driver credential                                                                                                     | —                                 |
+| `OPENAI_BASE_URL`   | `openai-compatible` base URL                                                                                                              | OpenAI cloud                      |
+| `OKE_AI_DRIVER`     | Force the AI driver id (honoured in docker mode)                                                                                          | config map                        |
+| `OKE_AI_URL`        | Ollama (or openai-compatible) base URL                                                                                                    | `http://127.0.0.1:11434` (ollama) |
+| `OKE_AI_MODEL`      | Default model for `ollama` (any pulled model; `qwen3.5:9b` is a balanced local-dev starting point; on Apple Silicon try `qwen3.5:9b-mlx`) | `qwen3.5:9b`                      |
+| `OLLAMA_HOST`       | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                                                     | —                                 |
 
 ## Framework behavior
 

package/site/content/docs/reference/errors.mdx

@@ -14,6 +14,19 @@ OKE1101  domain table not found — migrations have not been applied.
 
 Codes are permanent once published — you can match on them safely across upgrades.
 
+## Localized messages
+
+Typed failures and OKE codes ship English and Arabic ICU catalogs. Locale comes
+from `Accept-Language` (matched to `i18n.locales`); fallback is `i18n.default`.
+
+| Surface            | Keys                                       | How it appears                           |
+| ------------------ | ------------------------------------------ | ---------------------------------------- |
+| `fx.fail` / `fail` | `errors.{code}` · `errors.{code}.{reason}` | Optional `error.message` on the envelope |
+| Thrown `OkeError`  | `oke.{code}.cause` · `oke.{code}.fix`      | Cause + fix lines in the thrown message  |
+
+Override via `defineLocale`. Pass `fail(code, data, { message })` for a custom
+string. Custom app codes stay message-less until registered.
+
 ## OKE numeric codes
 
 | Code   | Name              | Cause                                            | Fix                                             |
@@ -75,6 +88,7 @@ Thrown by specific subsystems — each names its own cause:
 
 ## Learn more
 
+- [i18n](/docs/reference/i18n) — catalogs, `fx.t`, locale matching
 - [Flow](/docs/elements/flow) — `fx.fail` and the response envelope
 - [Gate](/docs/elements/gate) — where the three denials come from
 - [CLI Reference](/docs/reference/cli) — `oke db migrate` and friends

package/site/content/docs/reference/fx.mdx

@@ -102,20 +102,23 @@ const rows = await fx.using(
 
 ## Channel
 
-| Signature                                 | Records | Notes                                                               |
-| ----------------------------------------- | ------- | ------------------------------------------------------------------- |
-| `fx.send(template, { to?, data?, via? })` | `send`  | `via` orders the fallback chain; dry runs record _would have fired_ |
+| Signature                                    | Records | Notes                                                                                      |
+| -------------------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `fx.send(template, { to?, data?, via?, … })` | `send`  | `via` orders fallback; `locale` / `profileLocale` / `acceptLanguage` feed the locale chain |
+
+Omit locale opts and the send uses `fx.locale`. Dry runs record _would have fired_ and never
+contact a provider. Channel bodies use `{{field}}` catalogs — not ICU (see [Channel](/docs/elements/channel)).
 
 ## AI
 
-| Signature                              | Records | Returns                                     |
-| -------------------------------------- | ------- | ------------------------------------------- |
-| `fx.ask(prompt, input?, { via? })`     | `ask`   | Object validated against the prompt's `out` |
-| `fx.run(agent, input?)`                | `ask`   | Agent result                                |
-| `fx.stream(model, { prompt?, data? })` | `ask`   | `AsyncIterable<string>` of chunks           |
-| `fx.search(embed, query, { topK? })`   | `read`  | Matches from the index/embed                |
+| Signature                                             | Records                   | Returns                                                                       |
+| ----------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------- |
+| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                   |
+| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                  |
+| `fx.stream(model, { prompt?, data? })`                | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` |
+| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                  |
 
-AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them.
+AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. `tools` are Flow refs — each model tool call goes through `fx.call` (same capability and Runs path).
 
 ## Vault
 
@@ -153,11 +156,59 @@ Returning a plain value instead answers 200 with `{ data: value, error: null }`
 
 ## Logging, i18n, ids
 
-| Signature                                  | Notes                                    |
-| ------------------------------------------ | ---------------------------------------- |
-| `fx.log.debug/info/warn/error(msg, data?)` | Redacting — secrets print as `***`       |
-| `fx.t(key, params?)`                       | Localized message from the `i18n` config |
-| `fx.id()`                                  | UUID — the only legal id generator       |
+| Signature                                  | Notes                                                       |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| `fx.log.debug/info/warn/error(msg, data?)` | Redacting — secrets print as `***`                          |
+| `fx.t(key, values?)`                       | ICU MessageFormat — active locale → `i18n.default` → key    |
+| `fx.locale`                                | Active locale (`Accept-Language` matched to `i18n.locales`) |
+| `fx.id()`                                  | UUID — the only legal id generator                          |
+
+`fx.t` uses [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
+(FormatJS): `{name}`, plurals, `select` / `selectordinal`, rich-text tags.
+Full syntax and escaping: [i18n · ICU](/docs/reference/i18n#icu-messageformat).
+
+Register catalogs with `defineLocale` before boot (nested trees → dot keys). Augment
+`Register` so keys autocomplete and typos fail at compile time:
+
+```typescript
+import { defineLocale, defineMessages, type MessagesFor } from "okengine";
+
+export const en = defineMessages({
+  greeting: "Hello, {name}",
+  items: "{count, plural, one {# item} other {# items}}",
+  place: "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!",
+  status: "{status, select, online {Online} offline {Offline} other {Unknown}}",
+  cta: "Read <docs>the docs</docs>",
+});
+defineLocale("en", en);
+
+defineLocale("ar", {
+  greeting: "مرحباً، {name}",
+  items: "{count, plural, zero {لا عناصر} one {عنصر واحد} other {# عناصر}}",
+  place: "أنهيت في المرتبة {place, selectordinal, other {#}}!",
+  status: "{status, select, online {متصل} offline {غير متصل} other {غير معروف}}",
+  cta: "اقرأ <docs>التوثيق</docs>",
+} satisfies MessagesFor<typeof en>);
+
+declare module "okengine" {
+  interface Register {
+    messages: typeof en;
+  }
+}
+```
+
+```typescript
+fx.t("greeting", { name: input.name });
+fx.t("items", { count: 3 });
+fx.t("cta", { docs: (chunks) => `<a href="/docs">${chunks.join("")}</a>` });
+```
+
+Supported locales and the fallback come from `oke.config.ts` `i18n`.
+`create-oke` scaffolds English and Arabic locale modules already wired this way.
+
+Built-in `errors.*` / `oke.*` catalogs localize `fx.fail` messages and thrown
+`OkeError` cause/fix the same way — full i18n guide:
+[i18n](/docs/reference/i18n), [Errors](/docs/reference/errors).
 
 ## Principals
 
@@ -181,5 +232,6 @@ must log who started the call chain.
 ## Learn more
 
 - [Flow](/docs/elements/flow) — why `fx` is the only door
+- [Channel](/docs/elements/channel) — `fx.send`, consent, locale chain, `{{field}}` catalogs
 - [Errors](/docs/reference/errors) — what `fx.fail` produces
-- [Configuration](/docs/reference/configuration) — the drivers behind these calls
+- [Configuration](/docs/reference/configuration) — drivers and the `i18n` block

package/site/content/docs/reference/i18n.mdx

@@ -0,0 +1,313 @@
+---
+title: "i18n"
+description: "ICU message catalogs for fx.t, typed keys, request locale, and how failures and channels pick a language."
+icon: "Languages"
+source: "docs/spec/unified-theory.md"
+---
+
+App copy lives in message catalogs — greetings, plurals, and status lines you
+format inside a Flow with `fx.t`. Configure supported locales once in
+`oke.config.ts`; the request's `Accept-Language` picks the active tag.
+
+<Callout title="The one rule">
+  Register catalogs with `defineLocale` before boot, list every locale in `i18n.locales`, and call
+  `fx.t(key, values?)` for Flow copy. Channel emails use a separate `{{ field }}` catalog — not ICU.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Configure locales
+
+```typescript title="oke.config.ts"
+i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
+```
+
+If `i18n` is omitted, boot still defaults to `locales: ["en", "ar"]` and
+`default: "en"`.
+
+</Step>
+
+<Step>
+### Register catalogs
+
+Side-effect import locale modules before boot (the starter already does this
+from `src/app.ts`):
+
+```typescript title="src/locales/en.ts"
+import { defineMessages, defineLocale } from "okengine";
+
+export const en = defineMessages({
+  greeting: "Hello, {name}",
+  items: "{count, plural, one {# item} other {# items}}",
+  errors: { notFound: "Not found" },
+});
+defineLocale("en", en);
+
+declare module "okengine" {
+  interface Register {
+    messages: typeof en;
+  }
+}
+```
+
+```typescript title="src/locales/ar.ts"
+import { defineLocale, type MessagesFor } from "okengine";
+import { en } from "./en";
+
+defineLocale("ar", {
+  greeting: "مرحباً، {name}",
+  items: "{count, plural, zero {لا عناصر} one {عنصر واحد} other {# عناصر}}",
+  errors: { notFound: "غير موجود" },
+} satisfies MessagesFor<typeof en>);
+```
+
+</Step>
+
+<Step>
+### Use `fx.t` in a Flow
+
+```typescript
+do: async (input, fx) => {
+  return {
+    text: fx.t("greeting", { name: input.name }),
+    countLabel: fx.t("items", { count: input.count }),
+    locale: fx.locale,
+  };
+},
+```
+
+Send `Accept-Language: ar` (or `ar-SA`) against `locales: ["en", "ar"]` and
+`fx.locale` is `"ar"`. Missing keys fall back through `i18n.default`, then the
+key string itself.
+
+</Step>
+
+</Steps>
+
+## Config (`i18n`)
+
+| Option    | Type       | Default (when omitted) | Meaning                                     |
+| --------- | ---------- | ---------------------- | ------------------------------------------- |
+| `locales` | `string[]` | `["en", "ar"]`         | Tags matched against `Accept-Language`      |
+| `default` | string     | `"en"`                 | Fallback for `fx.t`, Channel, fail messages |
+| `dir`     | record     | —                      | Per-locale direction: `"ltr"` \| `"rtl"`    |
+
+Matching: exact tag → language subtag (`ar-SA` → `ar`) → `default`.
+
+## `fx.t` and `fx.locale`
+
+| Signature            | Notes                                                    |
+| -------------------- | -------------------------------------------------------- |
+| `fx.t(key, values?)` | ICU MessageFormat — active locale → `i18n.default` → key |
+| `fx.locale`          | Active BCP 47 tag for this run                           |
+
+Nested trees flatten to dot keys (`errors.notFound`). App overlays win over
+built-in keys for the same locale.
+
+## ICU MessageFormat
+
+`fx.t` formats catalog strings with
+[ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
+(FormatJS). The active locale drives plural/select rules — English `one`/`other` vs Arabic `zero`/`two`/`few`/`many` on the same key.
+
+| Feature         | Syntax sketch                                             | `values`                    |
+| --------------- | --------------------------------------------------------- | --------------------------- |
+| Interpolation   | `Hello, {name}`                                           | `{ name: "Ada" }`           |
+| Exact plural    | `{count, plural, =0 {none} one {# item} other {# items}}` | `{ count: 0 }`              |
+| Cardinal plural | `{count, plural, one {…} other {…}}`                      | `{ count: number }`         |
+| Ordinal         | `{place, selectordinal, one {#st} two {#nd} other {#th}}` | `{ place: number }`         |
+| Select          | `{status, select, online {…} offline {…} other {…}}`      | `{ status: "online" }`      |
+| Rich-text tag   | `Read <docs>the docs</docs>`                              | `{ docs: (chunks) => "…" }` |
+
+`#` inside a plural/ordinal branch is the numeric argument. Always include an
+`other` (or `=N`) branch — ICU requires a fallback.
+
+### Interpolation
+
+```typescript
+// catalog: "Hello, {name}"
+fx.t("greeting", { name: "Ada" }); // → "Hello, Ada"
+```
+
+Values may be `string`, `number`, `boolean`, `Date`, `null` / `undefined`, or a
+rich-text function (below). Missing args leave the source string unformatted.
+
+### Plurals (cardinal)
+
+```typescript
+// en: "{count, plural, =0 {no items} one {# item} other {# items}}"
+fx.t("items", { count: 0 }); // → "no items"
+fx.t("items", { count: 1 }); // → "1 item"
+fx.t("items", { count: 5 }); // → "5 items"
+```
+
+#### Arabic cardinals
+
+Arabic (`ar`) uses six [CLDR](https://cldr.unicode.org/index/cldr-spec/plural-rules)
+cardinal categories. FormatJS picks the branch from `fx.locale` — an English `one`/`other` skeleton on `ar` misfires for dual, paucal, and hundreds.
+
+| Category | When (integers)                        | Typical form                       |
+| -------- | -------------------------------------- | ---------------------------------- |
+| `zero`   | `n = 0`                                | No items / special zero phrasing   |
+| `one`    | `n = 1`                                | Singular                           |
+| `two`    | `n = 2`                                | Dual                               |
+| `few`    | `n % 100` in `3…10` (also `103…110` …) | Paucal — often sound plural        |
+| `many`   | `n % 100` in `11…99`                   | Accusative / “tamyīz” style counts |
+| `other`  | `100…102`, `200…202`, … and fractions  | General plural / leftover integers |
+
+Write every branch on the Arabic catalog (starter `items` key):
+
+```typescript
+// ar catalog
+items: "{count, plural, zero {لا عناصر} one {عنصر واحد} two {عنصران} few {# عناصر} many {# عنصراً} other {# عنصر}}";
+```
+
+```typescript
+// fx.locale === "ar"
+fx.t("items", { count: 0 }); // → "لا عناصر"      (zero)
+fx.t("items", { count: 1 }); // → "عنصر واحد"     (one)
+fx.t("items", { count: 2 }); // → "عنصران"        (two)
+fx.t("items", { count: 5 }); // → "5 عناصر"       (few)
+fx.t("items", { count: 11 }); // → "11 عنصراً"     (many)
+fx.t("items", { count: 100 }); // → "100 عنصر"      (other)
+fx.t("items", { count: 103 }); // → "103 عناصر"     (few — 103 % 100 = 3)
+```
+
+**Consequence:** copy the six-way shape for Arabic noun counts; do not reuse an
+English `one`/`other` skeleton. `#` still inserts the number inside a branch.
+
+### Ordinals (`selectordinal`)
+
+```typescript
+// "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!"
+fx.t("place", { place: 1 }); // → "You finished 1st!"
+fx.t("place", { place: 11 }); // → "You finished 11th!"
+```
+
+### Select (enums)
+
+```typescript
+// "{status, select, online {Online} offline {Offline} other {Unknown}}"
+fx.t("status", { status: "online" }); // → "Online"
+fx.t("status", { status: "away" }); // → "Unknown"
+```
+
+### Rich-text tags
+
+Tags in the message become function values. The function receives the formatted
+inner chunks and returns a string (HTML, Markdown, plain wrappers):
+
+```typescript
+// catalog: "Read <docs>the docs</docs>"
+fx.t("cta", {
+  docs: (chunks) => `<a href="/docs">${chunks.join("")}</a>`,
+});
+// → 'Read <a href="/docs">the docs</a>'
+```
+
+### Escaping
+
+| Need                        | Write                                      |
+| --------------------------- | ------------------------------------------ |
+| Apostrophe in copy          | Double it: `this flow''s effects`          |
+| Literal `{` / `}` in output | Quote the braces: `'{'optional: true'}'`   |
+| Channel-style `{{field}}`   | Not ICU — use Channel catalogs, not `fx.t` |
+
+Malformed ICU falls back to the raw catalog string (no throw from `fx.t`).
+
+## Typed keys
+
+Augment `Register` with your English tree so `fx.t` autocompletes and rejects
+typos. Keep other locales aligned with `satisfies MessagesFor<typeof en>`.
+
+| Helper           | Role                                             |
+| ---------------- | ------------------------------------------------ |
+| `defineMessages` | Preserve a `const` English (or canonical) tree   |
+| `defineLocale`   | Register / replace a locale's flat catalog       |
+| `MessagesFor<T>` | Same key shape as `T`; leaf values are strings   |
+| `AppMessageKey`  | Flattened key union once `Register` is augmented |
+
+## Built-in failure catalogs
+
+English and Arabic ship for typed failures and OKE codes — no app registration
+required:
+
+| Surface            | Keys                                       | Appears as                       |
+| ------------------ | ------------------------------------------ | -------------------------------- |
+| `fx.fail` / `fail` | `errors.{code}` · `errors.{code}.{reason}` | Optional `error.message`         |
+| Thrown `OkeError`  | `oke.{code}.cause` · `oke.{code}.fix`      | Cause + fix lines in the message |
+
+Override any key with `defineLocale`. Pass `fail(code, data, { message })` (or
+`fx.t(...)`) when you need a one-off string. Custom app codes stay message-less
+until registered. Full tables: [Errors](/docs/reference/errors).
+
+## Channel catalogs are separate
+
+`fx.send` templates use `{{field}}` bodies and their own `locales` list — not
+ICU. Omit `locale` / `profileLocale` / `acceptLanguage` on `fx.send` and the
+send uses `fx.locale`. Details: [Channel](/docs/elements/channel).
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="fx.t returns the key string unchanged">
+
+No catalog entry for that key in the active locale or `i18n.default`. Register
+it with `defineLocale`, import the locale module before boot, and check the
+flattened key (`errors.notFound`, not `errors: { notFound }`).
+
+</Accordion>
+<Accordion title="Response is English despite Accept-Language: ar">
+
+The tag must match `i18n.locales` (exact or base language). A request for `fr`
+with only `["en", "ar"]` falls back to `i18n.default`. Confirm the header reaches
+the app (proxies sometimes strip it).
+
+</Accordion>
+<Accordion title="Email body is still English while fx.t is Arabic">
+
+Channel catalogs are separate `{{field}}` strings. Add an `ar` body on the
+template / plugin catalog; `fx.t` does not translate Channel templates.
+
+</Accordion>
+<Accordion title="TypeScript rejects a key that exists at runtime">
+
+Augment `Register` with `messages: typeof en` in the English locale module.
+Without that, `fx.t` accepts any `string` and loses autocomplete.
+
+</Accordion>
+<Accordion title="Plural message looks wrong or returns the raw template">
+
+Missing `other` (or `=N`), a typo in a branch name, or an unescaped `{` / `'`
+makes FormatJS reject the message — `fx.t` then returns the catalog source.
+Keep `#` inside plural/ordinal branches only; double apostrophes (`''`).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [fx](/docs/reference/fx) — full `fx` surface including `fx.t` / `fx.locale`
+- [Errors](/docs/reference/errors) — localized failure messages and OKE codes
+- [Configuration](/docs/reference/configuration) — `i18n` block next to drivers
+- [Channel](/docs/elements/channel) — `{{field}}` templates and locale chain
+- [Flow](/docs/elements/flow) — envelope shape with optional `error.message`
+
+## Next
+
+<Cards>
+  <Card
+    title="Errors"
+    description="OKE codes, denials, and localized messages."
+    href="/docs/reference/errors"
+  />
+  <Card
+    title="Channel"
+    description="Human reach — templates, consent, locale chain."
+    href="/docs/elements/channel"
+  />
+  <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
+</Cards>

package/site/content/docs/reference/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Reference"
-description: "Lookup pages — config, fx, client, env vars, errors, plugins API, CLI, and Console security."
+description: "Lookup pages — config, fx, i18n, client, env vars, errors, plugins API, CLI, and Console security."
 icon: "BookMarked"
 source: "docs/spec/unified-theory.md"
 ---
@@ -16,6 +16,11 @@ Dense tables and command lists. Reach for these when you already know what you a
     href="/docs/reference/configuration"
   />
   <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
+  <Card
+    title="i18n"
+    description="ICU catalogs, fx.t, typed keys, locale matching."
+    href="/docs/reference/i18n"
+  />
   <Card
     title="Client"
     description="Typed createClient — REST, RPC, envelope helpers."

package/site/content/docs/reference/meta.json

@@ -5,6 +5,7 @@
     "index",
     "configuration",
     "fx",
+    "i18n",
     "client",
     "environment-variables",
     "errors",

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

@@ -77,6 +77,7 @@ Every method below exists on both the fluent definition and the boot-time builde
 | `.signal(decl)`                  | A signal declaration — merged into boot signals                                               |
 | `.gate(decl)`                    | A gate declaration — merged into boot gates                                                   |
 | `.channelTemplate(decl)`         | A channel template — merged into boot channel templates                                       |
+| `.channelCatalog(catalog)`       | Template body catalog entries — merged into boot channel catalog (`{{field}}` interpolation)  |
 | `.driver(id, impl)`              | A protocol-named driver for an existing element                                               |
 | `.image(role, recipe)`           | An image recipe for a docker role                                                             |
 | `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |

package/src/auth/auth.test.ts

@@ -102,6 +102,9 @@ describe("auth plugin", () => {
       channelTemplate() {
         return this;
       },
+      channelCatalog() {
+        return this;
+      },
     });
     expect(tables).toContain("oke_operators");
     expect(tables).toContain("oke_operator_credentials");

package/src/auth/bindings.ts

@@ -305,7 +305,7 @@ export function createAuthHttpBindings(
         }
         if (touchRateLimit(bag, ctx.now()) === "rate_limited") {
           return fail("AuthRateLimited", {
-            reason: "too many sign-in attempts; retry later",
+            reason: "rate_limited",
           });
         }
         const user = await authenticateUser(identities, input.email, input.password);

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/auth/method-context.ts

@@ -2,9 +2,13 @@
  * Active Gate auth context for method plugins plugged on the same app.
  *
  * Set during `oke({ gate: { auth } })` so `.plug(username())` etc. share
- * the app session store + HMAC secret without callers re-passing them.
+ * the app session store, HMAC secret, password policy, hash knobs, and
+ * breach check without callers re-passing them.
  */
 
+import type { PasswordHashOptions } from "../runtime/types.ts";
+import type { BreachCheckFn } from "./breach-check.ts";
+import type { PasswordPolicyOptions } from "./password-policy.ts";
 import type { SessionStore } from "./sessions.ts";
 
 /** Shared context for auth method plugins. */
@@ -12,6 +16,12 @@ export interface ActiveGateAuthContext {
   readonly secret: string;
   readonly sessions: SessionStore;
   readonly now?: () => number;
+  /** From `gate.auth.passwordPolicy` — shared by credential method plugins. */
+  readonly passwordPolicy?: PasswordPolicyOptions;
+  /** From `gate.auth.password` — Bun.password cost knobs. */
+  readonly password?: PasswordHashOptions;
+  /** From `gate.auth.breachCheck` — optional breach checker. */
+  readonly breachCheck?: BreachCheckFn;
 }
 
 let active: ActiveGateAuthContext | undefined;
@@ -19,7 +29,7 @@ let active: ActiveGateAuthContext | undefined;
 /**
  * Publish the app's Gate auth binding for subsequent `.plug()` method plugins.
  *
- * @param ctx - Secret + sessions (or undefined to clear)
+ * @param ctx - Shared auth material, or undefined to clear
  */
 export function setActiveGateAuthContext(ctx: ActiveGateAuthContext | undefined): void {
   active = ctx;