okengine 0.17.2 → 0.18.4

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

@@ -0,0 +1,153 @@
+---
+title: "Google"
+description: "Official plugin — Google sign-in via OIDC discovery and JWKS-verified ID tokens."
+icon: "Globe"
+source: "docs/spec/unified-theory.md"
+---
+
+Google is the reference OIDC provider for `oauth()`: discovery, ID-token
+signature checks, and issuer pinning all work the textbook way. If you are
+wiring your first social provider, start here.
+
+<Callout title="The one rule">
+  Register `https://app.example.com/auth/oauth/callback/google` (your exact origin) as an Authorized
+  Redirect URI, then enable it with `providers.google.enabled`. The comparison is byte-exact.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create OAuth credentials
+
+In Google Cloud Console → APIs & Services → Credentials, create an **OAuth
+client ID** of type _Web application_. Add your callback URI under Authorized
+Redirect URIs.
+
+</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: {
+      google: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...
+```
+
+Boot fails loudly if the secret is missing — the contract is declared by the
+plugin itself.
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+The driver discovers Google's endpoints from
+`https://accounts.google.com/.well-known/openid-configuration` and caches them.
+On callback it verifies the ID token end-to-end:
+
+| Check     | Rule                                                    |
+| --------- | ------------------------------------------------------- |
+| Signature | RS256 / ES256 against Google's published JWKS           |
+| Issuer    | must equal `https://accounts.google.com`                |
+| Audience  | must include your client id (`azp` when multi-audience) |
+| Expiry    | rejected when stale                                     |
+| Nonce     | single-use, bound to the flow row                       |
+
+Email trust follows the OIDC claim: `email_verified: true` marks the address
+verified; anything else — including string `"false"` — stays unverified.
+
+Default scopes: `openid`, `email`, `profile`.
+
+## Options
+
+| Option                | Type       | Default             | Meaning                    |
+| --------------------- | ---------- | ------------------- | -------------------------- |
+| `enabled`             | `boolean`  | `false`             | Turn the provider on       |
+| `clientId`            | `string`   | Vault/env\*         | `\*OAUTH_GOOGLE_CLIENT_ID` |
+| `redirectUri`         | `string`   | `{baseUrl}…/google` | Exact registered URI       |
+| `scopes`              | `string[]` | driver defaults     | Extra scopes               |
+| `storeProviderTokens` | `boolean`  | `false`             | Keep tokens in Vault       |
+
+## Surfaces
+
+| Flow     | Path                                   |
+| -------- | -------------------------------------- |
+| Start    | `POST /auth/oauth/google/start`        |
+| Callback | `GET+POST /auth/oauth/callback/google` |
+| Link     | `POST /auth/oauth/google/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="redirect_uri_mismatch at Google">
+
+The registered URI and the sent URI differ. Byte-exact means scheme, host,
+port, path, no trailing slash drift. Copy the value from
+`providers.google.redirectUri` or `baseUrl` synthesis.
+
+</Accordion>
+<Accordion title="invalid_client at token exchange">
+
+`OAUTH_GOOGLE_CLIENT_SECRET` is missing or stale. Secrets resolve through the
+Vault chain — update `.env.local` or your Vault driver, then restart.
+
+</Accordion>
+<Accordion title="aud_mismatch">
+
+You are using credentials from a different Google project than the one that
+issued the code, or swapped client ids between environments.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [Vault](/docs/elements/vault) — where secrets live
+- [Gate](/docs/elements/gate) — `gate.auth`
+
+## Next
+
+<Cards>
+  <Card
+    title="Apple"
+    description="form_post + ES256 client-secret JWT."
+    href="/docs/plugins/apple"
+  />
+  <Card
+    title="Microsoft"
+    description="Entra tenants and issuer templates."
+    href="/docs/plugins/microsoft"
+  />
+  <Card
+    title="GitHub"
+    description="OAuth2 with verified-email lookup."
+    href="/docs/plugins/github"
+  />
+</Cards>

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

@@ -1,6 +1,6 @@
 ---
 title: "Plugins"
-description: "Official okengine/plugins extensions — authentication, security, operations, and performance."
+description: "Official okengine/plugins extensions — authentication, OAuth, security, operations, and performance."
 icon: "Puzzle"
 source: "docs/spec/unified-theory.md"
 ---
@@ -22,6 +22,52 @@ First-party plugins you `.plug()` onto an app. Each page is one export from `oke
   <Card title="Passkey" description="WebAuthn-shaped passkeys." href="/docs/plugins/passkey" />
 </Cards>
 
+## OAuth
+
+<Cards>
+  <Card
+    title="OAuth"
+    description="Social sign-in — Authorization Code + PKCE for eight providers."
+    href="/docs/plugins/oauth"
+  />
+  <Card
+    title="Apple"
+    description="Sign in with Apple — form_post + ES256 JWT."
+    href="/docs/plugins/apple"
+  />
+  <Card
+    title="Discord"
+    description="Discord OAuth2 with nullable email."
+    href="/docs/plugins/discord"
+  />
+  <Card
+    title="Facebook"
+    description="Facebook Login — never-verified emails."
+    href="/docs/plugins/facebook"
+  />
+  <Card
+    title="Figma"
+    description="Figma OAuth2 with HTTP Basic token auth."
+    href="/docs/plugins/figma"
+  />
+  <Card
+    title="GitHub"
+    description="GitHub OAuth2 with verified-email lookup."
+    href="/docs/plugins/github"
+  />
+  <Card
+    title="Google"
+    description="Google OIDC — JWKS-verified ID tokens."
+    href="/docs/plugins/google"
+  />
+  <Card
+    title="Microsoft"
+    description="Entra ID OIDC with tenant-aware issuer checks."
+    href="/docs/plugins/microsoft"
+  />
+  <Card title="X" description="X OAuth2 public client — PKCE only." href="/docs/plugins/x" />
+</Cards>
+
 ## Security
 
 <Cards>

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

@@ -10,6 +10,16 @@
     "otp",
     "two-factor",
     "passkey",
+    "---OAuth---",
+    "oauth",
+    "apple",
+    "discord",
+    "facebook",
+    "figma",
+    "github",
+    "google",
+    "microsoft",
+    "x",
     "---Security---",
     "headers",
     "cors",

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

@@ -0,0 +1,151 @@
+---
+title: "Microsoft"
+description: "Official plugin — Entra ID sign-in across personal, work, and school accounts with tenant-aware issuer checks."
+icon: "LayoutGrid"
+source: "docs/spec/unified-theory.md"
+---
+
+Microsoft (Entra ID) is OIDC with a tenant twist: `common` discovery advertises
+an issuer with the `{tenantid}` placeholder, so the value you pin at start is
+a _template_ validated against the concrete token at callback.
+
+<Callout title="The one rule">
+  Pick the audience first: `tenant: "common"` for everyone, `organizations` for work/school only,
+  `consumers` for personal accounts, or a tenant GUID to lock sign-in to one directory.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Register an app
+
+In the Azure portal → Microsoft Entra ID → App registrations → New
+registration. Choose _Accounts in any organizational directory and personal
+Microsoft accounts_ for `common`. Add your redirect URI under **Web**.
+
+</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: {
+      microsoft: { enabled: true }, // tenant defaults to "common"
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_MICROSOFT_CLIENT_SECRET=...
+```
+
+Certificates are not used — the driver authenticates with the shared secret
+form field.
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect         | Behavior                                                                                              |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| Discovery      | `{tenant}/oauth2/v2.0/.well-known/openid-configuration`, cached                                       |
+| Issuer pinning | flow stores `https://login.microsoftonline.com/{tenantid}/v2.0`; tokens must match it shape-for-shape |
+| Tenant claim   | the token's `tid` must be GUID-shaped and consistent with `iss`                                       |
+| Signature      | RS256 against the tenant's published keys                                                             |
+| Email trust    | OIDC `email_verified` claim                                                                           |
+
+**Consequence:** an ID token minted by a _different_ tenant fails the issuer
+template even though its signature is perfectly valid — the mix-up defense
+survives multi-tenancy.
+
+Default scopes: `openid`, `email`, `profile`.
+
+## Options
+
+| Option                | Type       | Default                | Meaning                                 |
+| --------------------- | ---------- | ---------------------- | --------------------------------------- |
+| `enabled`             | `boolean`  | `false`                | Turn the provider on                    |
+| `clientId`            | `string`   | Vault/env\*            | `\*OAUTH_MICROSOFT_CLIENT_ID`           |
+| `tenant`              | `string`   | `"common"`             | `organizations`, `consumers`, or a GUID |
+| `redirectUri`         | `string`   | `{baseUrl}…/microsoft` | Exact registered URI                    |
+| `scopes`              | `string[]` | driver defaults        | Extra scopes                            |
+| `storeProviderTokens` | `boolean`  | `false`                | Keep tokens in Vault                    |
+
+## Surfaces
+
+| Flow     | Path                                      |
+| -------- | ----------------------------------------- |
+| Start    | `POST /auth/oauth/microsoft/start`        |
+| Callback | `GET+POST /auth/oauth/callback/microsoft` |
+| Link     | `POST /auth/oauth/microsoft/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="issuer_mismatch on every login">
+
+Your app registration's _supported account types_ disagree with the configured
+`tenant`. `common` requires multi-tenant + personal accounts; a single-tenant
+GUID needs the matching registration.
+
+</Accordion>
+<Accordion title="AADSTS50011 (redirect mismatch)">
+
+The reply URL registered in Azure does not byte-match the stored
+`redirectUri`. Re-copy from your plugin config; trailing slashes count.
+
+</Accordion>
+<Accordion title="No email arrives">
+
+Personal Microsoft accounts can omit email entirely. The flow signs the person
+in without one — exactly like Discord phone-only accounts.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [Google](/docs/plugins/google) — plain single-issuer OIDC
+- [Vault](/docs/elements/vault) — where secrets live
+
+## Next
+
+<Cards>
+  <Card
+    title="Apple"
+    description="form_post + ES256 client-secret JWT."
+    href="/docs/plugins/apple"
+  />
+  <Card
+    title="Discord"
+    description="Nullable emails, verified flag."
+    href="/docs/plugins/discord"
+  />
+  <Card
+    title="GitHub"
+    description="OAuth2 with verified-email lookup."
+    href="/docs/plugins/github"
+  />
+</Cards>

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>