okengine 0.17.2 → 0.18.3

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

@@ -0,0 +1,138 @@
+---
+title: "Figma"
+description: "Official plugin — Figma sign-in with HTTP Basic client auth and no email verification signal."
+icon: "PenTool"
+source: "docs/spec/unified-theory.md"
+---
+
+Figma is OAuth2 with two twists: the token endpoint uses **HTTP Basic**
+instead of a body field, and the API exposes **no verification flag** — so
+emails are always unverified.
+
+<Callout title="The one rule">
+  Register your exact callback URI in the Figma app, seed the client secret, and expect unverified
+  emails — new accounts only, never takeovers.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create an app
+
+Figma → Settings → Security → **Personal access tokens / OAuth apps** → create
+an OAuth app. Add `https://app.example.com/auth/oauth/callback/figma` as a
+callback URL.
+
+</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: {
+      figma: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_FIGMA_CLIENT_SECRET=...
+```
+
+The driver sends it as `Authorization: Basic base64(client_id:client_secret)`
+on the token call.
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect         | Behavior                                                                          |
+| -------------- | --------------------------------------------------------------------------------- |
+| Token exchange | `POST https://api.figma.com/v1/oauth/token` with the Basic header + PKCE verifier |
+| Profile        | `GET https://api.figma.com/v1/me`                                                 |
+| Subject        | `id`, falling back to `handle` when absent                                        |
+| Email trust    | **always unverified** — no verification field exists                              |
+
+Default scopes: `file_read`. Trim this to what you actually need; sign-in
+itself requires nothing beyond defaults.
+
+## Options
+
+| Option                | Type       | Default            | Meaning                   |
+| --------------------- | ---------- | ------------------ | ------------------------- |
+| `enabled`             | `boolean`  | `false`            | Turn the provider on      |
+| `clientId`            | `string`   | Vault/env\*        | `\*OAUTH_FIGMA_CLIENT_ID` |
+| `redirectUri`         | `string`   | `{baseUrl}…/figma` | Exact registered URI      |
+| `scopes`              | `string[]` | driver defaults    | Extra scopes              |
+| `storeProviderTokens` | `boolean`  | `false`            | Keep tokens in Vault      |
+
+## Surfaces
+
+| Flow     | Path                                  |
+| -------- | ------------------------------------- |
+| Start    | `POST /auth/oauth/figma/start`        |
+| Callback | `GET+POST /auth/oauth/callback/figma` |
+| Link     | `POST /auth/oauth/figma/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="401 on token exchange">
+
+The Basic header is built from _your_ pair — a mismatched id/secret rotation
+or a secret seeded under the wrong provider key. Check
+`OAUTH_FIGMA_CLIENT_SECRET`.
+
+</Accordion>
+<Accordion title="invalid_grant">
+
+Codes are single-use and expire quickly. Flow rows are too — restart from
+`/start`.
+
+</Accordion>
+<Accordion title="Email missing on the profile">
+
+Some Figma accounts expose no email. The session signs in without one;
+nothing else changes.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [GitHub](/docs/plugins/github) — OAuth2 with real verification signal
+- [Vault](/docs/elements/vault) — where secrets live
+
+## 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="X" description="PKCE public client." href="/docs/plugins/x" />
+</Cards>

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

@@ -0,0 +1,138 @@
+---
+title: "GitHub"
+description: "Official plugin — GitHub sign-in with primary-email lookup from the emails API."
+icon: "GitBranch"
+source: "docs/spec/unified-theory.md"
+---
+
+GitHub is OAuth2 without discovery or ID tokens, so `oauth()` builds the
+identity assertion from two REST calls: `/user` for the account and
+`/user/emails` for the address that actually matters.
+
+<Callout title="The one rule">
+  Request the `user:email` scope. The public profile email is usually null; the verified primary
+  address only exists on the emails endpoint.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create an OAuth App
+
+GitHub → Settings → Developer settings → OAuth Apps → **New OAuth App**.
+Authorization callback URL:
+`https://app.example.com/auth/oauth/callback/github`.
+
+</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: {
+      github: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_GITHUB_CLIENT_SECRET=...
+```
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect         | Behavior                                                                       |
+| -------------- | ------------------------------------------------------------------------------ |
+| Token exchange | form POST to `github.com/login/oauth/access_token`, JSON accepted              |
+| Profile        | `GET https://api.github.com/user` (numeric `id` is the subject)                |
+| Email          | `GET https://api.github.com/user/emails`; picks the entry with `primary: true` |
+| Email trust    | verified only when the selected entry has an explicit `verified: true`         |
+
+**Consequence:** a GitHub account whose primary email is unverified never
+claims that address during sign-up — the flow provisions without verified
+status instead of risking someone else's inbox.
+
+Default scopes: `read:user`, `user:email`. PKCE parameters are sent; GitHub
+ignores them but the protection stays uniform across providers.
+
+## Options
+
+| Option                | Type       | Default             | Meaning                    |
+| --------------------- | ---------- | ------------------- | -------------------------- |
+| `enabled`             | `boolean`  | `false`             | Turn the provider on       |
+| `clientId`            | `string`   | Vault/env\*         | `\*OAUTH_GITHUB_CLIENT_ID` |
+| `redirectUri`         | `string`   | `{baseUrl}…/github` | Exact registered URI       |
+| `scopes`              | `string[]` | driver defaults     | Extra scopes               |
+| `storeProviderTokens` | `boolean`  | `false`             | Keep tokens in Vault       |
+
+## Surfaces
+
+| Flow     | Path                                   |
+| -------- | -------------------------------------- |
+| Start    | `POST /auth/oauth/github/start`        |
+| Callback | `GET+POST /auth/oauth/callback/github` |
+| Link     | `POST /auth/oauth/github/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Sign-in succeeds with no email">
+
+The token lacks `user:email` (custom scopes dropped it) or the account has no
+verified addresses. The session is valid; add the scope for future flows.
+
+</Accordion>
+<Accordion title="401 on /user/emails">
+
+App permissions changed or the user revoked the grant under Settings →
+Applications. The driver degrades to no email rather than failing sign-in.
+
+</Accordion>
+<Accordion title="redirect_uri mismatch">
+
+GitHub compares the registered callback URL exactly. Re-copy the value your
+config produces.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [Discord](/docs/plugins/discord) — same OAuth2 shape, nullable email
+- [Vault](/docs/elements/vault) — where secrets live
+
+## Next
+
+<Cards>
+  <Card
+    title="Discord"
+    description="Verified flag with nullable email."
+    href="/docs/plugins/discord"
+  />
+  <Card title="Google" description="OIDC reference provider." href="/docs/plugins/google" />
+  <Card title="X" description="PKCE public client." href="/docs/plugins/x" />
+</Cards>

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>