docs: finish Tier 1's docs (Apple plus the two fixes)

README now lists apple among the providers, documents its four env
values and the two real differences (self-signed ES256 secret, identity
from a verified id_token); the env example gains the APPLE_* block.

NEXT.md drops the "except Apple" caveat and records the two Apple
decisions (response_mode=query, no nonce) plus what is still owed:
a DB-backed smoke-test run, a live Apple round trip, and the WebAuthn
ceremonies. CURRENT-STATE.md gains the Apple/what-is-tested section and
the two bug fixes, and its verification-gap paragraph now names exactly
which paths this sandbox could not exercise. PROGRESS.md gains the
continuation entry.

Author: raymondproguy

.env.example

@@ -18,6 +18,13 @@ DISCORD_CLIENT_SECRET=
 GITLAB_CLIENT_ID=
 GITLAB_CLIENT_SECRET=
 
+# Apple needs all four (its "secret" is a JWT this API signs with the .p8
+# key, so there is no static secret). Write the key's newlines as \n.
+APPLE_CLIENT_ID=
+APPLE_TEAM_ID=
+APPLE_KEY_ID=
+APPLE_PRIVATE_KEY=
+
 # Second factors. ENCRYPTION_KEY is required for TOTP and/or passkeys and
 # encrypts TOTP secrets at rest — treat it like JWT_SECRET. Leave it unset
 # to run password-only; the second-factor endpoints then answer 404

README.md

@@ -32,15 +32,30 @@ GITHUB_CLIENT_SECRET=...
 
 A provider missing its client ID or secret is simply unavailable — its endpoints return `404 oauth_provider_not_configured` rather than the server refusing to start.
 
-Supported providers are `google`, `github`, `microsoft`, `discord` and `gitlab` — all the same authorization-code shape, so each is one case in `httpapi/oauth_handlers.go` plus its env vars:
+Supported providers are `google`, `github`, `microsoft`, `discord`, `gitlab` and `apple`.
+
+`google`/`github`/`microsoft`/`discord`/`gitlab` all have the same authorization-code shape, so each is one case in `httpapi/oauth_handlers.go` plus its env vars:
 
 ```
 MICROSOFT_CLIENT_ID=...       MICROSOFT_CLIENT_SECRET=...
 DISCORD_CLIENT_ID=...         DISCORD_CLIENT_SECRET=...
 GITLAB_CLIENT_ID=...          GITLAB_CLIENT_SECRET=...
 ```
 
-Apple is **not** wired up yet — its client "secret" is a short-lived JWT you sign with a key from Apple's developer console rather than a static string, and the email arrives inside a signed `id_token` instead of from a userinfo call. It needs its own piece of work, not another case in that switch.
+Apple is the one that does not fit that shape, and it is the only provider needing more than an ID and a secret:
+
+```
+APPLE_CLIENT_ID=com.example.web        # your Services ID, not the app bundle ID
+APPLE_TEAM_ID=XXXXXXXXXX
+APPLE_KEY_ID=XXXXXXXXXX
+APPLE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\nMIG...\n-----END PRIVATE KEY-----
+```
+
+- Its client "secret" is a short-lived ES256 JWT this API signs itself (`httpapi/apple.go`), which is why it needs the `.p8` key rather than a string. In `.env`, write the key's newlines as `\n`; a real multiline value passed through a secret manager is used as-is.
+- There is no userinfo endpoint. The email and account ID come from the `id_token` in the token response, verified against Apple's published signing keys (issuer, audience, expiry and RS256 all enforced) rather than merely decoded.
+- The authorization request pins `response_mode=query`, so the existing GET callback route works unchanged. Consequently the one-time `user` payload (the name Apple sends only on a first authorization) is not captured — this API stores the id_token's email, not names.
+
+All four `APPLE_*` values are required; a partially configured Apple is simply unavailable, like any other unconfigured provider.
 
 ## Second factors
 
@@ -129,7 +144,7 @@ POST   /v1/login/passkey/finish      (completes a paused login)
 POST   /v1/login/recovery-code       (completes a paused login)
 ```
 
-`{provider}` is `google`, `github`, `microsoft`, `discord` or `gitlab`.
+`{provider}` is `google`, `github`, `microsoft`, `discord`, `gitlab` or `apple`.
 The two OAuth flows are separate
 on purpose:
 - `/oauth/{provider}` → `/oauth/{provider}/callback` is login/signup —

docs/development/CURRENT-STATE.md

@@ -6,11 +6,11 @@ A thin HTTP wrapper around cryden v2.5.0 (bumped from v2.1.0 in Tier
 0, see below). Routes cover signup, login, refresh, logout/logout-all,
 sessions list/revoke, change password, delete account, email
 verification and email change, and OAuth — Google, GitHub, Microsoft,
-Discord and GitLab configured today (the router itself is
+Discord, GitLab and Apple configured today (the router itself is
 provider-agnostic via a `{provider}` path param, so a provider is one
 switch-statement case in `httpapi/oauth_handlers.go` plus its env vars,
-not a router change; Apple is the one provider that does not fit that
-shape and is still open — see `NEXT.md` Tier 1).
+not a router change; Apple is the one that does not fit that shape and
+has its own `httpapi/apple.go` — see `NEXT.md` Tier 1).
 
 Tier 1 also added the second-factor surface: TOTP enroll/confirm/
 disable, passkey registration/list/delete, magic-link request/complete,
@@ -86,7 +86,7 @@ cryden — see `CODEX.md`'s ownership section for why.
 tiers gate behind. The first real use of `RequireAdmin` will be
 whichever Tier 4/5 endpoint lands first.
 
-## Tier 1 — auth methods (all but Apple): DONE
+## Tier 1 — auth methods: DONE
 
 Built on `feat/tier1-auth-methods` (its own branch, per `CODEX.md`'s
 one-branch-per-tier rule), in this order:
@@ -126,28 +126,44 @@ one-branch-per-tier rule), in this order:
   because Microsoft and Discord require it and Google/GitHub accept it,
   replacing the previous query-string form rather than branching per
   provider.
+- **Apple** (`httpapi/apple.go`): the one provider that is not another
+  switch case. Its client secret is an ES256 JWT signed per exchange
+  with the console's `.p8` key, and its identity comes from the token
+  response's `id_token`, verified against Apple's JWKS (issuer,
+  audience, expiry, RS256) with the key set cached and refetched on an
+  unknown `kid`. Authorization uses `response_mode=query` so the
+  existing GET callback route is unchanged. All four `APPLE_*` values
+  are required; a partial config reads as unavailable.
 - **Error mapping** (`httpapi/errors.go`): every new engine error mapped
-  once there — the eight per-method errors and the four "not
-  configured" sentinels (`404`, matching
-  `oauth_provider_not_configured`).
-- `httpapi/errors_test.go` — the first test files in this repo: the new
-  `(status, code)` mappings (including when wrapped) and the paused-
-  login response shape. Chosen deliberately as the largest slice
-  verifiable without a database.
+  once there — the eight per-method errors, the four "not configured"
+  sentinels (`404`, matching `oauth_provider_not_configured`), and the
+  Apple verification failure.
+- **Two pre-existing bugs found in passing and fixed** (their own
+  commit): `auth.ErrPasswordPolicyViolation` and
+  `auth.ErrPasswordBreached` had no `mapError` case, so a signup or
+  password change that broke the configured policy answered `500
+  internal_error`; both are now `400`, with the policy error's broken
+  rule codes reaching the client in an optional `details` array. The
+  tracked env file was also renamed `.env.exampl` → `.env.example` to
+  match what the README has always told you to copy.
+- `httpapi/errors_test.go` and `httpapi/apple_test.go` — the first test
+  files in this repo. The mapping/`writeErr` behaviour, the paused-login
+  response shape, and Apple's signing plus id_token verification
+  (accepted case and seven rejection cases, including an `alg: none`
+  token) are covered; that is deliberately the largest slice verifiable
+  without a database or Apple credentials.
 
 **Verification gap, disclosed rather than glossed over:** `go build
 ./...`, `go vet ./...` and `go test ./...` are clean on this branch
 (Go 1.25.0, cryden v2.5.0 from the local module cache), and `gofmt -l`
 is empty. The DB-backed smoke test was **not** run — this sandbox has
-no Postgres and no network — so the end-to-end paths (especially the
-WebAuthn ceremonies, which need a real browser authenticator) are
-still owed a first run against a real database before Tier 1 counts as
-verified the way cryden's own features are.
-
-**Apple is the one open part of Tier 1** — not a fourth mechanical
-provider case: its client secret is a self-signed short-lived JWT, and
-the email arrives inside a signed `id_token` that has to be verified
-against Apple's JWKS. Left open deliberately rather than half-built.
+no Postgres and no network — so the end-to-end paths are still owed a
+first run against a real database before Tier 1 counts as verified the
+way cryden's own features are. Two paths additionally cannot be
+verified here at all: the WebAuthn ceremonies (need a real browser
+authenticator) and Apple (needs real Apple credentials; what is tested
+offline is the signing and the id_token verification, against a local
+JWKS).
 
 ## Tier 2 through 5
 

docs/development/NEXT.md

@@ -9,21 +9,23 @@ genuinely unspecified, make the most reasonable call consistent with
 `CODEX.md`'s ownership rules and note the assumption in `PROGRESS.md`.
 
 Tier 0 and Tier 0.5 are done — see `CURRENT-STATE.md`.
-Tier 1 is done **except Apple** — see the status note under Tier 1 and
-`PROGRESS.md`'s 2026-09-14 entry for exactly what is left.
+Tier 1 is done — see the status note under Tier 1 and `PROGRESS.md`'s
+2026-09-14 entries for how far it is verified.
 
 ---
 
 ## Tier 1 — auth methods
 
-> **Status: every sub-item below is built and on `feat/tier1-auth-methods`
-> except Apple**, which is deliberately still open (see the Apple bullet
-> at the end of this section — it is not another mechanical provider
-> case). The engine-side pieces are wired and `go build`/`go test` are
-> clean; the DB-backed smoke test has not been run here (no Postgres in
-> this sandbox), so a first run against a real database is still owed
-> before this counts as verified end to end — `PROGRESS.md` says so
-> plainly, per `CODEX.md`'s verification rule.
+> **Status: every sub-item below is built, Apple included, on
+> `feat/tier1-auth-methods`.** `go build`/`go vet`/`go test` are clean
+> and the new mapping/`writeErr` behaviour is unit-tested, including
+> Apple's client-secret signing and its id_token verification
+> (signature, audience, issuer, expiry, algorithm) against a local JWKS.
+> What is still owed: a first DB-backed smoke-test run (no Postgres in
+> this sandbox), a live Apple round trip (no Apple credentials here), and
+> the WebAuthn ceremonies, which need a real browser authenticator.
+> `PROGRESS.md` says all of that plainly, per `CODEX.md`'s verification
+> rule, rather than counting green unit tests as end-to-end coverage.
 
 Each of these mirrors an existing engine feature that already has a
 full smoke-test-verified implementation in cryden. The work here is
@@ -119,14 +121,21 @@ Google/GitHub already use.
   again. Budget real time for this one; don't estimate it at the same
   size as the other three.
 
-**Still open in Tier 1: Apple only.** The other three providers ship in
-`feat/tier1-auth-methods`. Apple needs: an ES256 client-secret JWT
-signed with a console key (so a private key in config, not a static
-secret), reading the email from the token endpoint's signed `id_token`
-(which means verifying it against Apple's JWKS, not parsing it
-unverified), and the callback-URL shape Apple requires. Its own branch
-or its own commit, and it cannot be smoke-test-verified without real
-Apple credentials — say so rather than implying otherwise.
+**Apple: done** (its own commit, `httpapi/apple.go` + `apple_test.go`).
+It needed exactly what was foreseen here: an ES256 client-secret JWT
+signed per exchange with the console key, and the identity read from the
+token response's `id_token` after verifying it against Apple's JWKS.
+Two details were decided rather than assumed, and are recorded in
+`PROGRESS.md`:
+
+- `response_mode=query` so the existing GET callback route works
+  unchanged. The consequence is that Apple's one-time `user` payload
+  (name, first authorization only) is not captured — this repo stores the
+  id_token's email, not names.
+- No `nonce` parameter. Apple requires one for the hybrid/implicit flow;
+  this is the authorization-code flow, where the code is single-use and
+  bound to this client and the redirect already carries a CSRF `state`
+  cookie. Worth revisiting only if a hybrid flow is ever added.
 
 ---
 

docs/development/PROGRESS.md

@@ -127,3 +127,73 @@ rather than silently patched):
 Next: finish Tier 1's Apple provider (its own commit, and it will need
 real credentials before it can be smoke-tested), then a first DB-backed
 smoke-test run of everything above, then Tier 2.
+
+## 2026-09-14 (later) — the two flagged issues, then Apple
+
+Same branch, four more commits. Tier 1 is now complete, Apple included.
+
+**Fixed the two things flagged in the entry above**, each its own commit:
+
+- `fix: map password-policy and breached-password errors to 400` —
+  `auth.ErrPasswordPolicyViolation` and `auth.ErrPasswordBreached` now
+  map to `400`/`password_policy_violation` and `400`/`password_breached`
+  instead of falling through to `500 internal_error`. The policy error
+  keeps its struct case and `writeErr` reads the broken-rule codes off
+  the error into an optional `details` array — the one addition to the
+  error envelope, and it appears on no other error (both halves are
+  pinned by tests, so an existing client sees a byte-identical shape).
+- `chore: rename .env.exampl to .env.example` — renamed rather than
+  rewriting the README, since the README's name is the conventional one
+  and `.gitignore` only ignores `.env` itself.
+
+**Apple** (`feat: add Sign in with Apple`, `httpapi/apple.go` +
+`apple_test.go` + `golang-jwt` promoted from indirect to direct):
+
+- Client secret is an ES256 JWT signed per exchange with the console
+  `.p8` key (10-minute expiry, `kid` header, `iss`=team, `sub`=client
+  ID, `aud`=Apple). `APPLE_CLIENT_ID`/`TEAM_ID`/`KEY_ID`/`PRIVATE_KEY`
+  are all required; a partial config reads as unavailable, same as any
+  other unconfigured provider. `APPLE_PRIVATE_KEY` accepts a `.env`-style
+  `\n`-escaped PEM and leaves a real multiline value alone.
+- No userinfo endpoint: the identity comes from the token response's
+  `id_token`, verified against Apple's JWKS (RS256 only, issuer,
+  audience, expiry, `kid` lookup) with the key set cached for an hour
+  and refetched once on an unknown `kid` so a rotation is picked up.
+  An unverified decode would have let anyone who can reach the callback
+  mint an account, so this is the part that got the most test attention.
+- `exchangeCode` now takes the client secret as an argument and returns
+  both the access token and the id_token, which lets Apple reuse the
+  existing POST plumbing instead of duplicating it. The authorization
+  redirect query is now built in one `authQuery` helper used by both the
+  login and linking flows, so a provider-specific parameter cannot be
+  added to one and forgotten in the other.
+
+Assumptions made while building Apple (recorded, not silent):
+
+- **`response_mode=query`**, so the existing GET callback route works
+  unchanged. Consequence: Apple's one-time `user` payload (the name it
+  sends only on a first authorization, and only under `form_post`) is
+  not captured — this repo stores the id_token's email, never names,
+  which is all `LoginWithOAuth` takes anyway.
+- **No `nonce`.** Apple requires one for the hybrid/implicit flow; this
+  is the authorization-code flow, where the code is single-use, bound to
+  this client, and the redirect already carries a CSRF `state` cookie
+  verified against a signed cookie. Revisit only if a hybrid flow is
+  ever added.
+- **Apple's email is required**, like every other provider here — if the
+  id_token has no email claim the login fails with the existing
+  `oauth_email_not_available` rather than inventing an identity.
+
+Verification: `go build ./...`, `go vet ./...` and `go test ./...` clean,
+`gofmt -l` empty. `apple_test.go` covers the generated secret (parses as
+ES256, correct `kid`/`iss`/`aud`/`sub`, unexpired; RSA and non-PEM keys
+rejected) and id_token verification (accepted when signed by the served
+key; rejected for wrong audience, wrong issuer, expiry, different
+signing key, unknown `kid`, missing subject, and an `alg: none` token).
+Still **not** verified here: a live Apple round trip (no credentials, no
+network), the DB-backed smoke test (no Postgres), and the WebAuthn
+ceremonies (no browser authenticator). Those remain the first things to
+run on a real deployment.
+
+Next: Tier 2, on its own branch per `CODEX.md` — and before or alongside
+it, the first DB-backed smoke-test run of everything in Tier 1.