okengine 0.17.2 → 0.18.4

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

@@ -0,0 +1,151 @@
+---
+title: "Apple"
+description: "Official plugin — Sign in with Apple with form_post callbacks and an ES256 client-secret JWT."
+icon: "Apple"
+source: "docs/spec/unified-theory.md"
+---
+
+Sign in with Apple is OIDC with three twists: the web flow **posts** its
+response, every exchange needs an ES256 client-secret **JWT you sign**, and
+`email_verified` can arrive as the _string_ `"false"`.
+
+<Callout title="The one rule">
+  Create a Sign in with Apple key (Team ID, Key ID, `.p8` private key), seed the key in Vault, and
+  register your exact callback URI — Apple validates all three on every exchange.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create a key
+
+In the Apple Developer portal: Identifiers → register an App ID with _Sign In
+with Apple_; Keys → create a key with that capability; note the **Team ID**
+and **Key ID**, and download the `.p8` once.
+
+</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: {
+      apple: {
+        enabled: true,
+        teamId: "ABCDE12345",
+        keyId: "XYZ6789012",
+      },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Seed the private key
+
+```text
+# .env.local
+OAUTH_APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
+MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEH...
+-----END PRIVATE KEY-----"
+```
+
+The driver mints a fresh ES256 client-secret JWT per exchange (`iss` = team,
+`kid` = key, one-hour life) and discards nothing to disk.
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect      | Behavior                                                                  |
+| ----------- | ------------------------------------------------------------------------- |
+| Callback    | Apple posts `code` + `state` as a form body — both GET and POST are bound |
+| Signature   | ES256 against `appleid.apple.com` JWKS                                    |
+| Issuer      | must equal `https://appleid.apple.com`                                    |
+| Name        | delivered only on first authorization via the form-posted `user` field    |
+| Email trust | strict parse — only boolean `true`, `"true"`, or `"1"` count              |
+
+**Consequence:** the string `"false"` stays unverified. Naive truthiness would
+mark every private-relay email verified — that is the takeover bug class this
+parse exists to close.
+
+Default scopes: `name`, `email`.
+
+## Options
+
+| Option                | Type       | Default            | Meaning                                 |
+| --------------------- | ---------- | ------------------ | --------------------------------------- |
+| `enabled`             | `boolean`  | `false`            | Turn the provider on                    |
+| `clientId`            | `string`   | Vault/env\*        | `\*OAUTH_APPLE_CLIENT_ID` (Services ID) |
+| `teamId`              | `string`   | required           | Apple Developer Team ID                 |
+| `keyId`               | `string`   | required           | Private-key identifier                  |
+| `redirectUri`         | `string`   | `{baseUrl}…/apple` | Exact registered URI                    |
+| `scopes`              | `string[]` | `name email`       | Requested scopes                        |
+| `storeProviderTokens` | `boolean`  | `false`            | Keep tokens in Vault                    |
+
+## Surfaces
+
+| Flow     | Path                                  |
+| -------- | ------------------------------------- |
+| Start    | `POST /auth/oauth/apple/start`        |
+| Callback | `GET+POST /auth/oauth/callback/apple` |
+| Link     | `POST /auth/oauth/apple/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="invalid_client at token exchange">
+
+Team ID, Key ID, or the `.p8` does not match the App ID / Services ID you are
+signing for. The JWT is minted fresh per exchange, so fixing the inputs is
+enough — no restart cache to clear.
+
+</Accordion>
+<Accordion title="invalid_request mentioning response_mode">
+
+Your Services ID must allow the callback you registered. Check the return URLs
+on the Sign in with Apple key configuration.
+
+</Accordion>
+<Accordion title="Callback never fires">
+
+Browsers post to `/auth/oauth/callback/apple`; make sure proxies do not strip
+form bodies. The route accepts POST with
+`application/x-www-form-urlencoded`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [Vault](/docs/elements/vault) — seeding `OAUTH_APPLE_PRIVATE_KEY`
+- [Gate](/docs/elements/gate) — `gate.auth`
+
+## Next
+
+<Cards>
+  <Card title="Google" description="OIDC reference provider." href="/docs/plugins/google" />
+  <Card
+    title="Microsoft"
+    description="Entra tenants and issuer templates."
+    href="/docs/plugins/microsoft"
+  />
+  <Card title="X" description="PKCE public client, never-verified emails." href="/docs/plugins/x" />
+</Cards>

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

@@ -0,0 +1,139 @@
+---
+title: "Discord"
+description: "Official plugin — Discord sign-in where email can be real, verified, or legitimately absent."
+icon: "MessageCircle"
+source: "docs/spec/unified-theory.md"
+---
+
+Discord is OAuth2 with one quirk: `/users/@me` `email` can be **null**
+(phone-only accounts). `oauth()` signs those people in without an email
+instead of failing them.
+
+<Callout title="The one rule">
+  Keep the `email` scope in the request (it is on by default). Without it Discord never reports
+  `verified: true`, and unverified emails cannot claim existing accounts.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create an application
+
+Discord Developer Portal → Applications → **New Application** → OAuth2. Add a
+redirect under OAuth2 → Redirects:
+`https://app.example.com/auth/oauth/callback/discord`.
+
+</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: {
+      discord: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_DISCORD_CLIENT_SECRET=...
+```
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect      | Behavior                                                                            |
+| ----------- | ----------------------------------------------------------------------------------- |
+| Profile     | `GET https://discord.com/api/users/@me` (string `id` is the subject)                |
+| Email       | taken as-is when present; `null` flows through as _no email_                        |
+| Email trust | `verified: true` only; the flag silently going missing keeps the address unverified |
+| Name        | `global_name`, falling back to `username`                                           |
+
+**Consequence:** an integration bug that drops the `verified` field degrades
+to unverified — never to falsely verified. That direction of failure is what
+keeps account takeover off the table.
+
+Default scopes: `identify`, `email`. The authorize URL always carries
+`prompt=consent`.
+
+## Options
+
+| Option                | Type       | Default              | Meaning                     |
+| --------------------- | ---------- | -------------------- | --------------------------- |
+| `enabled`             | `boolean`  | `false`              | Turn the provider on        |
+| `clientId`            | `string`   | Vault/env\*          | `\*OAUTH_DISCORD_CLIENT_ID` |
+| `redirectUri`         | `string`   | `{baseUrl}…/discord` | Exact registered URI        |
+| `scopes`              | `string[]` | driver defaults      | Extra scopes                |
+| `storeProviderTokens` | `boolean`  | `false`              | Keep tokens in Vault        |
+
+## Surfaces
+
+| Flow     | Path                                    |
+| -------- | --------------------------------------- |
+| Start    | `POST /auth/oauth/discord/start`        |
+| Callback | `GET+POST /auth/oauth/callback/discord` |
+| Link     | `POST /auth/oauth/discord/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Users sign in with no email attached">
+
+Phone-only Discord accounts expose `email: null`. The session works; the user
+row simply has no address until they add one at Discord.
+
+</Accordion>
+<Accordion title="invalid_oauth2 error code">
+
+The client secret was rotated in the portal while old codes were in flight.
+Restart the flow — flow rows are single-use and expire after ten minutes.
+
+</Accordion>
+<Accordion title="Email never marked verified">
+
+The app lacks the `email` scope or the user has not confirmed their address at
+Discord. Unverified emails provision new accounts but never take over
+existing ones.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [GitHub](/docs/plugins/github) — primary-email lookup pattern
+- [Vault](/docs/elements/vault) — where secrets live
+
+## Next
+
+<Cards>
+  <Card
+    title="GitHub"
+    description="OAuth2 with verified-email lookup."
+    href="/docs/plugins/github"
+  />
+  <Card title="Facebook" description="Never-verified emails." href="/docs/plugins/facebook" />
+  <Card title="Google" description="OIDC reference provider." href="/docs/plugins/google" />
+</Cards>

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

@@ -0,0 +1,134 @@
+---
+title: "Facebook"
+description: "Official plugin — Facebook Login via Graph API with conservative email handling."
+icon: "Share2"
+source: "docs/spec/unified-theory.md"
+---
+
+Facebook Login is OAuth2 against the Graph API, and its trust story is the
+simplest one in `oauth()`: the platform offers **no verification signal to
+apps**, so emails from Facebook are treated as unverified — always.
+
+<Callout title="The one rule">
+  Treat every Facebook-provided address as unverified. The flow provisions new accounts with them
+  but refuses to let them claim accounts that already exist.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create an app
+
+Meta for Developers → **Create App** → _Authentication_. Under Facebook Login
+→ Settings, add `https://app.example.com/auth/oauth/callback/facebook` as a
+Valid OAuth Redirect 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: {
+      facebook: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_FACEBOOK_CLIENT_SECRET=...
+```
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect         | Behavior                                                      |
+| -------------- | ------------------------------------------------------------- |
+| Authorize      | `www.facebook.com/v21.0/dialog/oauth`                         |
+| Token exchange | `graph.facebook.com/v21.0/oauth/access_token`                 |
+| Profile        | `GET /me?fields=id,name,email` (the `id` is the subject)      |
+| Email          | present when the user has one; phone-only accounts have none  |
+| Email trust    | **always unverified** — no trustworthy provider signal exists |
+
+**Consequence:** an attacker completing Facebook login with _your_ email gets
+`email_in_use`, not your session. This exact scenario is the takeover class
+the trust matrix closes.
+
+Default scopes: `email`, `public_profile`.
+
+## Options
+
+| Option                | Type       | Default               | Meaning                               |
+| --------------------- | ---------- | --------------------- | ------------------------------------- |
+| `enabled`             | `boolean`  | `false`               | Turn the provider on                  |
+| `clientId`            | `string`   | Vault/env\*           | `\*OAUTH_FACEBOOK_CLIENT_ID` (App ID) |
+| `redirectUri`         | `string`   | `{baseUrl}…/facebook` | Exact registered URI                  |
+| `scopes`              | `string[]` | driver defaults       | Extra scopes                          |
+| `storeProviderTokens` | `boolean`  | `false`               | Keep tokens in Vault                  |
+
+## Surfaces
+
+| Flow     | Path                                     |
+| -------- | ---------------------------------------- |
+| Start    | `POST /auth/oauth/facebook/start`        |
+| Callback | `GET+POST /auth/oauth/callback/facebook` |
+| Link     | `POST /auth/oauth/facebook/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="URL Blocked: redirect_uri">
+
+The URI is not on the Valid OAuth Redirect URIs list, or the app is in
+development mode and the user lacks a role. Byte-exact matching applies.
+
+</Accordion>
+<Accordion title="Sign-in works but there is no email">
+
+The user declined the email permission or has none on file. The flow proceeds
+without an address — same behavior as Discord phone-only accounts.
+
+</Accordion>
+<Accordion title="Error code 190 at exchange">
+
+The app secret was rotated or the code was replayed. Codes are single-use;
+restart from `/start`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [X](/docs/plugins/x) — also never-verified emails
+- [Vault](/docs/elements/vault) — where secrets live
+
+## Next
+
+<Cards>
+  <Card title="X" description="PKCE public client." href="/docs/plugins/x" />
+  <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/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>