okengine 0.17.2 → 0.18.3

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

@@ -0,0 +1,188 @@
+---
+title: "OAuth"
+description: "Official plugin — social sign-in with eight providers under /auth, Authorization Code + PKCE only."
+icon: "FingerprintPattern"
+source: "docs/spec/unified-theory.md"
+---
+
+`oauth()` adds social login to Gate auth. Start at
+`/auth/oauth/{provider}/start`, approve, then land on
+`/auth/oauth/callback/{provider}` with a session — eight providers.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(oauth({ providers: { ... } }))`. Every
+  provider runs Authorization Code + PKCE with an exact registered redirect URI
+  — implicit and password grants do not exist here.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { oauth } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "dev",
+  gate: { auth: {} },
+}).plug(
+  oauth({
+    baseUrl: "https://app.example.com",
+    providers: {
+      google: { enabled: true },
+      github: { enabled: true },
+    },
+  }),
+);
+```
+
+`baseUrl` synthesizes `{baseUrl}/auth/oauth/callback/{provider}` — register
+that exact string. Client secrets resolve from Vault
+(`OAUTH_GOOGLE_CLIENT_SECRET`, `OAUTH_GITHUB_CLIENT_SECRET`, …).
+
+</Step>
+
+<Step>
+### Start the flow
+
+```typescript
+const { data } = await api.auth.oauthStart({ provider: "google" });
+// redirect the browser to data.authorizationUrl
+```
+
+The response carries `authorizationUrl`, `expiresInMs`, and the provider echo.
+The flow row (state hash, PKCE verifier, nonce) lives for ten minutes.
+
+</Step>
+
+<Step>
+### Callback issues a session
+
+The provider redirects to your callback route; the flow verifies state,
+exchanges the code, and signs the person in:
+
+```typescript
+const body = {
+  accessToken: "...",
+  refreshToken: "...",
+  userId: "usr_...",
+};
+```
+
+A brand-new visitor gets a fresh account. Someone whose email already belongs
+to another credential is refused with `email_in_use`.
+
+</Step>
+
+</Steps>
+
+## Providers
+
+| Provider  | Shape  | Identity source          | Email verified                       |
+| --------- | ------ | ------------------------ | ------------------------------------ |
+| Google    | OIDC   | JWKS-verified ID token   | `email_verified` claim               |
+| Apple     | OIDC   | JWKS-verified ID token   | strict parse — `"false"` stays false |
+| Microsoft | OIDC   | JWKS-verified ID token   | `email_verified` claim               |
+| GitHub    | OAuth2 | `/user` + `/user/emails` | primary `verified` flag              |
+| Discord   | OAuth2 | `/users/@me`             | `verified` flag                      |
+| X         | OAuth2 | `/2/users/me`            | never — no trustworthy signal        |
+| Facebook  | OAuth2 | Graph `/me`              | never — no trustworthy signal        |
+| Figma     | OAuth2 | `/v1/me`                 | never — no verification field        |
+
+Each provider has its own page under this category — endpoints, scopes, setup,
+and trust rules.
+
+## Security model
+
+| Threat                             | Defense                                                                 |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| Code interception                  | PKCE S256 on every provider                                             |
+| CSRF / forged callbacks            | single-use `state`, SHA-256-hashed at rest                              |
+| Mix-up across providers (RFC 9700) | per-provider callback routes + issuer pinning on every assertion        |
+| Unverified-email takeover          | `linkOrProvision` refuses `email_in_use` without an authenticated owner |
+| Redirect manipulation              | byte-exact stored `redirect_uri` at token exchange                      |
+
+**Consequence:** an attacker who completes a social login claiming your email
+gains nothing — the account stays untouched unless they already own a session
+for it.
+
+## Options
+
+| Option          | Type                | Default  | Meaning                                  |
+| --------------- | ------------------- | -------- | ---------------------------------------- |
+| `providers`     | map                 | `{}`     | Per-provider config, disabled by default |
+| `baseUrl`       | `string`            | —        | Origin for synthesized callback URIs     |
+| `secret`        | `string`            | active\* | HMAC secret (\*from `gate.auth`)         |
+| `sessions`      | `SessionStore`      | active\* | Session store                            |
+| `identities`    | `IdentityStore`     | active\* | Shared user store                        |
+| `verifications` | `VerificationStore` | new      | Flow-state store                         |
+| `fetch`         | `typeof fetch`      | global   | Injectable transport (tests)             |
+
+Per-provider config: `enabled`, `clientId`, `redirectUri`, `scopes`,
+`storeProviderTokens`, plus Microsoft `tenant` and Apple `teamId` / `keyId`.
+
+## Surfaces
+
+| Flow                  | Path                                       | Gate                     |
+| --------------------- | ------------------------------------------ | ------------------------ |
+| `auth.oauthStart`     | `POST /auth/oauth/{provider}/start`        | `gate.public` + otp rate |
+| `auth.oauthCallback`  | `GET+POST /auth/oauth/callback/{provider}` | `gate.public` + otp rate |
+| `auth.oauthLinkStart` | `POST /auth/oauth/{provider}/link`         | session + bearer         |
+
+The GET + POST callback pair exists because Apple posts its response instead of
+redirecting.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Boot fails listing OAUTH_…_CLIENT_SECRET">
+
+Every enabled provider needs its secret in Vault before boot. Seed
+`OAUTH_{PROVIDER}_CLIENT_SECRET` (Apple uses `OAUTH_APPLE_PRIVATE_KEY`) through
+your Vault driver or `.env.local`.
+
+</Accordion>
+<Accordion title="Callback returns invalid_state">
+
+The state was consumed, expired (ten-minute TTL), or minted by a different
+provider's start call. Restart from `/start`.
+
+</Accordion>
+<Accordion title="Callback returns issuer_mismatch">
+
+The ID token's issuer does not match the provider that started the flow — the
+signature was valid but the token came from elsewhere. This rejection is the
+mix-up defense working; retry the real provider.
+
+</Accordion>
+<Accordion title="Callback returns email_in_use">
+
+The provider returned an email already registered to another account without
+proof you own that account. Sign in with the original method first, then link
+via `POST /auth/oauth/{provider}/link`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — `gate.auth`
+- [Passkey](/docs/plugins/passkey) — phishing-resistant alternative
+- [Client](/docs/reference/client) — calling `/auth` from the browser
+
+## Next
+
+<Cards>
+  <Card title="Google" description="OIDC reference provider." href="/docs/plugins/google" />
+  <Card
+    title="GitHub"
+    description="OAuth2 with verified-email lookup."
+    href="/docs/plugins/github"
+  />
+  <Card title="Passkey" description="WebAuthn-shaped passkeys." href="/docs/plugins/passkey" />
+</Cards>

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

@@ -0,0 +1,125 @@
+---
+title: "X"
+description: "Official plugin — X (Twitter) sign-in as a PKCE public client with confidential-client secrets left out."
+icon: "X"
+source: "docs/spec/unified-theory.md"
+---
+
+X is the one provider where `oauth()` behaves as a **public client**: the
+token exchange carries the code verifier but no secret. PKCE is the only
+proof the callback is yours.
+
+<Callout title="The one rule">
+  Enable OAuth 2.0 in the X Developer Portal, set up your exact callback URI, and request
+  `users.email` access if you need addresses. No `OAUTH_X_CLIENT_SECRET` exists — none is read.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Configure the app
+
+X Developer Portal → Project → User authentication settings → **Set up**.
+Choose _Web App_, enable OAuth 2.0, and add
+`https://app.example.com/auth/oauth/callback/x` as a callback URI.
+
+</Step>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { oauth } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "dev",
+  gate: { auth: {} },
+}).plug(
+  oauth({
+    baseUrl: "https://app.example.com",
+    providers: {
+      x: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+</Steps>
+
+That is the whole setup — no Vault contract for this provider.
+
+## How identity works
+
+| Aspect         | Behavior                                                                                    |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| Token exchange | `POST https://api.x.com/2/oauth2/token` with the code verifier, no secret                   |
+| Profile        | `GET /2/users/me?user.fields=id,name,username,confirmed_email`                              |
+| Subject        | the string `id` inside `data`                                                               |
+| Email trust    | **always unverified** — `confirmed_email` gates API access, it does not attest verification |
+
+**Consequence:** an X email never claims an existing account during sign-up.
+It can attach to a fresh account or to an existing one you already control via
+authenticated linking.
+
+Default scopes: `users.read`, `tweet.read`.
+
+## Options
+
+| Option                | Type       | Default         | Meaning                            |
+| --------------------- | ---------- | --------------- | ---------------------------------- |
+| `enabled`             | `boolean`  | `false`         | Turn the provider on               |
+| `clientId`            | `string`   | Vault/env\*     | `\*OAUTH_X_CLIENT_ID`              |
+| `redirectUri`         | `string`   | `{baseUrl}…/x`  | Exact registered URI               |
+| `scopes`              | `string[]` | driver defaults | Extra scopes (`offline.access`, …) |
+| `storeProviderTokens` | `boolean`  | `false`         | Keep tokens in Vault               |
+
+## Surfaces
+
+| Flow     | Path                              |
+| -------- | --------------------------------- |
+| Start    | `POST /auth/oauth/x/start`        |
+| Callback | `GET+POST /auth/oauth/callback/x` |
+| Link     | `POST /auth/oauth/x/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="invalid_request on token exchange">
+
+Callback URIs must match exactly and the code must be fresh. X codes are
+single-use and short-lived; flow rows expire after ten minutes too.
+
+</Accordion>
+<Accordion title="No email ever arrives">
+
+`confirmed_email` requires elevated access plus the `users.email` scope. Even
+then the address stays unverified by design — see the trust table above.
+
+</Accordion>
+<Accordion title="403 forbidden">
+
+Your app tier lacks user-context authentication, or the requested scope set
+exceeds what the portal grants.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [Facebook](/docs/plugins/facebook) — also never-verified emails
+- [Vault](/docs/elements/vault) — optional token storage
+
+## Next
+
+<Cards>
+  <Card title="Facebook" description="Never-verified emails." href="/docs/plugins/facebook" />
+  <Card title="Figma" description="Basic-auth token endpoint." href="/docs/plugins/figma" />
+  <Card title="Discord" description="Nullable emails." href="/docs/plugins/discord" />
+</Cards>

package/site/content/docs/reference/cli.md

@@ -27,7 +27,8 @@ oke test                         # bun test with PGLite posture (NODE_ENV=test,
 oke mode                         # removed — prints error; use oke dev (Compose) / oke test (PGLite)
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
-oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
+oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift, FD headroom,
+                                 #   CDC outbox backlog/retention, live fan-out pressure
 oke console claim-code           # print setup claim code from .oke/claim-code (after Console boot)
                                  #   → `bun run dev:console` boots kernel + Vite with a fixed
                                  #     operator (`dev@oke.dev` / `Okengine123!`) — Sign in (prefilled)
@@ -141,7 +142,7 @@ the hero (not once per process).
 that `@electric-sql/pglite` resolves, then forwards argv to `bun test`.
 
 `oke mode` and `oke dev --local` / `-l` are removed — they exit with an error.
-See [Migrating environments](/docs/reference/migrating-environments).
+Rename the env keys in `oke.config.ts` to `dev` / `test` / `prod`.
 
 ### create-oke
 

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

@@ -172,7 +172,8 @@ const { data } = await api.auth.signInEmail({ email, password });
 if (data) session.set(data);
 ```
 
-React: `useSession(api, session)` and `useLive(api, signal, input?)` from `okengine/client-react`.
+React: `useSession(api, session)`, `useLive(api, signal, input?)`, and
+`useLiveQuery({ api, listFlow, live, query? })` from `okengine/client-react`.
 
 | Step                   | What happens                                                     |
 | ---------------------- | ---------------------------------------------------------------- |
@@ -205,6 +206,7 @@ A 401 with no `{ data, error }` body becomes `TransportError` with `data.status:
 | `AUTH_ERROR_CODES`          | `okengine/client/auth`  | Common auth Flow / gate codes                    |
 | `useSession(api, session?)` | `okengine/client-react` | React status + `auth.me`                         |
 | `useLive(api, signal, …)`   | `okengine/client-react` | React `events` / `latest` / `isConnected`        |
+| `useLiveQuery({ … })`       | `okengine/client-react` | Live list + optimistic `mutate` over a resource  |
 
 Core `okengine/client` stays under the size budget — helpers are separate exports. Not in
 core today: cookie jars or plugin `.client()` decorations. Browser apps: also see
@@ -305,6 +307,61 @@ const { events, latest, error, isConnected } = useLive(
 );
 ```
 
+### Live queries (`store.resource({ live: true })`)
+
+When a resource opts into `live: true`, the compiler mounts `GET <path>/live` next to the CRUD
+verbs. That route streams **classified** row events — not a shared tape — so each subscriber only
+sees rows that still pass their RLS stamp + list filters:
+
+| `kind`    | Meaning                                                        |
+| --------- | -------------------------------------------------------------- |
+| `upsert`  | Row visible under stamp + query — merge/replace by primary key |
+| `revoked` | Row left visibility (`reason: "rls"` \| `"query"`) — remove    |
+| `delete`  | Row deleted in CDC — remove                                    |
+
+```typescript
+import { useLiveQuery } from "okengine/client-react";
+
+const { data, error, isLoading, isConnected, isReconnecting, refetch, mutate } = useLiveQuery({
+  api,
+  listFlow: api.tasks.list,
+  query: { status: "open" },
+  live: { method: "GET", path: "/tasks/live" }, // from app.$routes
+  options: {
+    enabled: session.status === "authenticated", // default true — idle when false
+    refreshKey: tenantId, // identity change → full re-subscribe
+    onAuthRefresh: onAuthRefreshed, // auth.refresh() → new snapshot + replay
+  },
+});
+
+await mutate(
+  api.tasks.update,
+  { id, status: "done" },
+  {
+    optimistic: (rows) => rows.map((r) => (r.id === id ? { ...r, status: "done" } : r)),
+    pkOf: (input) => input.id,
+  },
+);
+```
+
+Every `mutate` call generates a client UUID sent as the `X-Oke-Mutation-Id`
+header — the server echoes it onto that write's CDC events, so:
+
+- Your own late SSE echoes never double-apply (pending-set dedupe).
+- Reconnects replay-guard by event `seq` (`isReplayedEvent`).
+- Manual `refetch()` re-runs only the HTTP list read; reconnects always do a
+  full subscribe-protocol cycle (new snapshot + replay).
+
+| State            | Meaning                                                             |
+| ---------------- | ------------------------------------------------------------------- |
+| `isLoading`      | Waiting for the first snapshot — no data yet                        |
+| `isConnected`    | SSE stream is open                                                  |
+| `isReconnecting` | Stream dropped after a successful load; reconnect backoff in flight |
+
+**Consequence:** optimistic patches roll back automatically when the Flow returns
+`error !== null`. Server CDC / the successful response clear the override so the next upsert is
+authoritative.
+
 ## Exports
 
 | Export                                    | Kind      | Role                                                |

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

@@ -28,8 +28,7 @@ export default defineConfig({
 | `prod` | Production deploy          | Shared durable backends                               |
 
 Missing `dev` pins fill from `prod` (`fillDevFromProd`). Only `dev` / `test` / `prod` keys are
-valid — see [Migrating environments](/docs/reference/migrating-environments) if you still have
-`local` / `docker` maps.
+valid — rename `local` → `dev` and `docker` → `prod` if you still have the old maps.
 
 ## Quick start
 
@@ -246,7 +245,7 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 <Accordion title='oke.config: … uses removed driver "sqlite"'>
   The `sqlite` driver is gone. Pin `postgres` for `dev`/`prod` and `pglite` for `test`. Edit the
-  file by hand — see [Migrating environments](/docs/reference/migrating-environments).
+  file by hand — rename the env keys to `dev` / `test` / `prod` first.
 </Accordion>
 
 <Accordion title='drivers.store.sql.test must be "pglite"'>
@@ -268,7 +267,6 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 ## Learn more
 
-- [Migrating environments](/docs/reference/migrating-environments) — four-key maps → `dev`/`test`/`prod`
 - [CLI Reference](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
 - [Environment Variables](/docs/reference/environment-variables) — URL and secret resolution
 - [Store](/docs/elements/store) — what the store drivers back

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

@@ -230,7 +230,9 @@ Returning a plain value instead answers 200 with `{ data: value, error: null }`
 | `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.id()`                                  | OKID — 21-char native id from `okengine/okid`               |
+
+See [OKID](/docs/reference/okid) for generation options and the entropy model.
 
 `fx.t` uses [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
 (FormatJS): `{name}`, plurals, `select` / `selectordinal`, rich-text tags.

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

@@ -15,11 +15,6 @@ Dense tables and command lists. Reach for these when you already know what you a
     description="Every option in oke.config.ts."
     href="/docs/reference/configuration"
   />
-  <Card
-    title="Migrating environments"
-    description="local/docker maps → dev/test/prod."
-    href="/docs/reference/migrating-environments"
-  />
   <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
   <Card
     title="i18n"

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

@@ -4,7 +4,6 @@
   "pages": [
     "index",
     "configuration",
-    "migrating-environments",
     "fx",
     "i18n",
     "client",
@@ -12,6 +11,7 @@
     "errors",
     "plugins",
     "cli",
-    "security"
+    "security",
+    "okid"
   ]
 }

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

@@ -0,0 +1,137 @@
+---
+title: "OKID"
+description: "OKE's native id generator — compact, URL-safe, cryptographically random ids from okengine/okid, with an opt-in time-sortable and alphabet-controlled variant."
+icon: "Hash"
+source: "docs/spec/unified-theory.md"
+---
+
+Using `okengine/okid` gives you an id for any primary key, request trace, or event that is short (`okid()` is 21 characters), URL-safe, and random from a cryptographic source. Turn to it when a plain UUID string is more than you need; your app already generates them wherever `defaultFn(id)` is used.
+
+<Callout title="The one rule">
+  Use OKID for identity, never for secrets. An id is enumerable by design, so anything you hand to
+  an untrusted client must be a token from the Vault, not an OKID.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Install nothing — it is exported by the package
+
+```typescript
+import { okid } from "okengine/okid";
+```
+
+</Step>
+
+<Step>
+### Generate an id
+
+```typescript
+const userId = okid();
+const requestId = okid(16);
+const eventKey = okid({ sortable: true });
+const inviteCode = okid({ lookAlikes: false, uppercase: false });
+```
+
+</Step>
+
+<Step>
+### Store it anywhere a string fits
+
+```typescript
+// field.id() is shorthand for "default generation id" — currently OK ID.
+field.id().primaryKey();
+// Or pin OK ID explicitly:
+field.okid().primaryKey();
+```
+
+The same 21-character id lands in your SQL primary keys, KV keys, and trace ids.
+
+</Step>
+
+</Steps>
+
+## Reference
+
+| Call                                               | Result                                    | Notes                                   |
+| -------------------------------------------------- | ----------------------------------------- | --------------------------------------- |
+| `okid()`                                           | 21-char URL-safe id, 126 bits of entropy  | 64-char alphabet, `a-zA-Z0-9-_`         |
+| `okid(length)`                                     | id of exactly `length` characters         | integer between 8 and 128               |
+| `okid({ length })`                                 | options form, id of `length`              | default 21                              |
+| `okid({ sortable })`                               | time-prefixed id, 8 prefix + `length − 8` | lexicographic order ≈ creation order    |
+| `okid({ numbers, lowercase, uppercase, symbols })` | charset control                           | each group defaults to on               |
+| `okid({ lookAlikes })`                             | confusable-char control                   | `lookAlikes: false` drops `1lI0Oouv5Ss` |
+
+### Options
+
+| Option       | Type      | Default | Meaning                                                     |
+| ------------ | --------- | ------- | ----------------------------------------------------------- |
+| `length`     | `number`  | `21`    | total id length in characters, between 8 and 128            |
+| `sortable`   | `boolean` | `false` | prefix an 8-char epoch-ms timestamp so sorting follows time |
+| `numbers`    | `boolean` | `true`  | include `0-9`                                               |
+| `lowercase`  | `boolean` | `true`  | include `a-z`                                               |
+| `uppercase`  | `boolean` | `true`  | include `A-Z`                                               |
+| `symbols`    | `boolean` | `true`  | include `-` and `_`                                         |
+| `lookAlikes` | `boolean` | `true`  | include confusable chars `1lI0Oouv5Ss`; set `false` to drop |
+
+### Exported constants
+
+| Constant                   | Value                                     | Meaning                          |
+| -------------------------- | ----------------------------------------- | -------------------------------- |
+| `OKID_ALPHABET`            | `a-zA-Z0-9-_`                             | default, Base64URL order         |
+| `OKID_SORTABLE_ALPHABET`   | alphabet sorted by code unit (same chars) | used by the sortable encoder     |
+| `OKID_LOOKALIKE_CHARS`     | `1lI0Oouv5Ss`                             | dropped when `lookAlikes: false` |
+| `OKID_DEFAULT_LENGTH`      | `21`                                      | default length                   |
+| `OKID_MIN_LENGTH`          | `8`                                       | shortest non-sortable length     |
+| `OKID_MAX_LENGTH`          | `128`                                     | longest length                   |
+| `OKID_SORTABLE_MIN_LENGTH` | `16`                                      | shortest sortable length (8+8)   |
+
+## Collision resistance
+
+Every character is drawn uniformly from the alphabet with `crypto.getRandomValues()`. Because it uses an unbiased character selection (never modulo), each character carries exactly `log2(alphabet)` bits of entropy. At the default 21 characters over 64 symbols, that is 126 bits — the birthday-bound collision probability across one billion ids is on the order of `10⁻²¹`. You do not need a UUID for collision resistance; this is where a UUID is stronger only because it is a different format, not a different amount of randomness.
+
+**Consequence:** two ids minted at the same millisecond are still distinct — the timestamp prefix never replaces entropy, it prefixes it.
+
+## Sortable ids
+
+`sortable: true` prepends 48 bits of `Date.now()` encoded in exactly 8 characters, in an alphabet whose sort order matches time order. Sorting a batch of these ids reproduces the creation order across milliseconds.
+
+**Consequence:** a sortable id embeds its creation time (millisecond precision), so keep them out of public, enumerable surfaces. Clock skew distorts order but can never produce a duplicate — the tail stays random.
+
+## Alphabet control
+
+Turning groups off shrinks the alphabet. With a non-power-of-two alphabet, OKID uses rejection sampling instead of modulo, so every remaining character stays equally likely — the output never becomes measurably biased.
+
+**Consequence:** smaller alphabets mean fewer bits per character. `lookAlikes: false` alone drops the default entropy only slightly (126 → ~120 bits); dropping whole groups costs more. Choose the smallest alphabet that fits the human-transcription use case.
+
+## Under the hood
+
+The generator is a pure function: no counters, no process or machine fingerprint, no shared mutable state. It is safe to call concurrently from any number of workers, and every id uses only the bytes it needs — no hidden timestamp, no hidden prefix.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="I get an error for an empty alphabet">
+
+Passing `numbers: false, lowercase: false, uppercase: false, symbols: false` at the same time throws a `RangeError` with the message `okid: alphabet is empty — enable at least one character group`. Re-enable at least one group, or don't use the option object and rely on the default alphabet.
+
+</Accordion>
+<Accordion title="I get a RangeError for a length">
+
+`okid(0)`, `okid(-1)`, `okid(7)`, `okid(129)`, and non-integer lengths throw a `RangeError`. Sortable ids have a higher floor: passing a sortable length below 16 throws. Keep lengths between 8 and 128 (16–128 for sortable).
+
+</Accordion>
+<Accordion title="My ids are not sortable by the alphabet order I expected">
+
+The default alphabet order is not lexicographic; `_` sorts between uppercase and lowercase. When `sortable` is on, ids use the code-point-ordered alphabet, so plain string comparison matches time order. Do not customize the alphabet in sortable mode — the option exists exactly because the default order is not trustworthy for ordering.
+
+</Accordion>
+</Accordions>
+
+## References
+
+- [Store](/docs/elements/store) — `defaultFn(id)` in table declarations delegates to `okid()`
+- [fx](/docs/reference/fx) — `fx.id()` in the runtime uses `okid()`
+- [Clock](/docs/elements/clock) — process `instanceId` (`inst-<okid>`) is an OKID

package/src/auth/bindings.ts

@@ -175,7 +175,7 @@ export function createAuthHttpBindings(
   } = {},
 ): AuthHttpMaterialization {
   const sessions = options.sessions ?? config.sessions ?? createSessionStore();
-  const identities = options.identities ?? createIdentityStore();
+  const identities = options.identities ?? config.identities ?? createIdentityStore();
   const loginAttempts = createLoginAttemptBag();
   const rateGates = createAuthRateGates(options.rateLimitEnabled !== false);
   const policyGates = createAuthPolicyGates(config);

package/src/auth/config.ts

@@ -8,6 +8,7 @@ import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { SessionStore } from "./sessions.ts";
 import { createApiKeyStore, type ApiKeyStore } from "./api-keys.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
+import { createIdentityStore, type IdentityStore } from "./identity.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import {
   resolveAuthSchema,
@@ -116,6 +117,11 @@ export interface GateAuthOptions extends AuthSchemaOptions {
    * Not part of the public app DX — escape hatch for embedding.
    */
   readonly sessions?: SessionStore;
+  /**
+   * Shared identity / credential store. Created automatically when omitted.
+   * All Gate auth method plugins resolve against this one store by default.
+   */
+  readonly identities?: IdentityStore;
   /**
    * Shared API key store. Created automatically when omitted
    * (`gate.auth.secret` is the HMAC pepper).
@@ -186,6 +192,8 @@ export interface ResolvedGateAuth {
   readonly hooks: AuthDatabaseHooks | undefined;
   readonly sessions: SessionStore | undefined;
   readonly apiKeyStore: ApiKeyStore;
+  /** Shared identity store — the single user/credential source across Gate auth + method plugins. */
+  readonly identities: IdentityStore;
   readonly tenant: ResolvedTenantAuth | undefined;
   readonly tenantStore: TenantStore | undefined;
   readonly now: (() => number) | undefined;
@@ -296,6 +304,7 @@ export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAu
     hooks: auth.hooks,
     sessions: auth.sessions,
     apiKeyStore: auth.apiKeyStore ?? createApiKeyStore({ pepper: secret }),
+    identities: auth.identities ?? createIdentityStore(),
     tenant: auth.tenant ? resolveTenantAuth(auth.tenant) : undefined,
     tenantStore: auth.tenant ? (auth.tenantStore ?? createTenantStore()) : auth.tenantStore,
     now: auth.now,