---
phase: 08-social-sign-in
plan: 03
subsystem: auth-oauth
tags: [apple, oauth2, oidc, es256, go-jose]
requires:
  - phase: 08-social-sign-in
    provides: shared OAuth primitives and account linking
provides:
  - Apple provider config and ES256 client-secret generation
  - Apple start and callback routes
  - nonce-protected Apple ID token verification path
affects: [auth-ui, account-providers]
tech-stack:
  added: [github.com/go-jose/go-jose/v4]
  patterns: [Apple client-secret signing, provider-specific callback over shared linker]
key-files:
  created: []
  modified:
    - backend/internal/auth/oauth.go
    - backend/internal/auth/oauth_test.go
    - backend/internal/web/handlers_social.go
    - backend/internal/web/handlers_social_test.go
    - backend/internal/web/router.go
    - backend/cmd/web/main.go
key-decisions:
  - "Apple callback uses GET with state and nonce to preserve existing CSRF middleware for local POST forms."
  - "Apple private relay emails are accepted when the provider marks them verified."
patterns-established:
  - "Apple first-login name is treated as display metadata only."
requirements-completed: [AUTH-10, AUTH-11, AUTH-12, AUTH-13]
duration: 30min
completed: 2026-05-15
---

# Phase 8 Plan 03: Apple Social Sign-in Summary

**Sign in with Apple flow using ES256 client-secret JWTs, nonce validation, verified relay email support, and local sessions**

## Performance

- **Duration:** ~30 min
- **Started:** 2026-05-15T19:51:00Z
- **Completed:** 2026-05-15T20:21:00Z
- **Tasks:** 2
- **Files modified:** 7

## Accomplishments

- Added Apple config, private-key normalization, and client-secret signing.
- Added `/auth/apple/start` and `/auth/apple/callback`.
- Extended verifier claim parsing to accept boolean or string `email_verified`.
- Added tests for Apple config, client-secret claims, start redirect, nonce rejection, unverified email, and relay/name persistence.

## Task Commits

1. **Apple social sign-in flow** - `a8b6a03` (`feat(08-03)`)

## Deviations from Plan

Used a GET callback rather than `form_post` to avoid broad CSRF middleware changes. OAuth state and ID-token nonce remain the callback defense.

**Total deviations:** 1 architecture-light deviation. **Impact:** Keeps local form CSRF untouched; Apple dashboard callback mode must match this route.

## Issues Encountered

None beyond local DB-backed tests skipping without `TEST_DATABASE_URL`.

## User Setup Required

Apple Services ID, Team ID, Key ID, private key, and redirect URL are documented in Plan 05 docs.

## Next Phase Readiness

Both provider start routes are ready for login/signup UI entry points.

