# Apple Sign-In Setup

**Time: ~30 minutes. Cost: $99/year — Apple Developer Program membership is required.** There is no free tier for Sign in with Apple on the web.

Worth knowing up front: Apple's "Hide My Email" feature means some users will register with a relay address like `x7k2p9@privaterelay.appleid.com`. Those addresses forward correctly, so your approval emails still arrive.

---

## Prerequisite

Enroll at **https://developer.apple.com/programs/** ($99/year). If you're not going to pay for this, skip Apple — Google and Microsoft will cover your neighbors fine.

---

## Step 1 — Create an App ID

1. **https://developer.apple.com/account/resources/identifiers/list**
2. **+** → **App IDs** → **Continue** → **App** → **Continue**
3. Description: `Paddlers Cove`
4. Bundle ID: **Explicit** → `org.paddlerscove.app`
5. Under **Capabilities**, check **Sign In with Apple**
6. **Continue** → **Register**

---

## Step 2 — Create a Services ID (this is your client ID)

1. Identifiers → **+** → **Services IDs** → **Continue**
2. Description: `Paddlers Cove Web`
3. Identifier: `org.paddlerscove.web`  ← **this becomes `APPLE_CLIENT_ID`**
4. **Continue** → **Register**
5. Click the new Services ID to edit it
6. Check **Sign In with Apple** → **Configure**
   - **Primary App ID:** select `org.paddlerscove.app`
   - **Domains and Subdomains:** `paddlerscove.org`
   - **Return URLs:**
     ```
     https://paddlerscove.org/auth/apple/callback
     ```
   - **Next** → **Done** → **Continue** → **Save**

> Apple will not accept `localhost` here. To test locally, use an ngrok/Cloudflare tunnel HTTPS URL.

---

## Step 3 — Create a private key

1. **Keys** → **+**
2. Key Name: `Paddlers Cove Sign In Key`
3. Check **Sign In with Apple** → **Configure** → Primary App ID `org.paddlerscove.app` → **Save**
4. **Continue** → **Register**
5. **Download** the `.p8` file. **You can only download it once.** If you lose it, revoke and start over.
6. Note the **Key ID** shown on the confirmation page.

---

## Step 4 — Find your Team ID

Top-right of the developer portal, or **Membership details**. It's a 10-character string like `A1B2C3D4E5`.

---

## Step 5 — Install the key on the server

Upload the `.p8` **outside your web root**:

```
/home/USER/paddlerscove/config/keys/AuthKey_ABC1234DEF.p8
```

Lock it down:
```bash
chmod 600 config/keys/AuthKey_*.p8
```

The `.htaccess` and `.gitignore` already block this directory, but the file should live outside `public/` regardless — and with this layout, it does.

---

## Step 6 — Fill in `.env`

```ini
APPLE_CLIENT_ID=org.paddlerscove.web
APPLE_TEAM_ID=A1B2C3D4E5
APPLE_KEY_ID=ABC1234DEF
APPLE_KEY_FILE=config/keys/AuthKey_ABC1234DEF.p8
```

The app generates the required JWT client secret automatically at each sign-in (Apple's "secret" is a short-lived signed token, not a static string — which is why the `.p8` is needed at runtime).

---

## Step 7 — Test

1. `/login` → **Continue with Apple**
2. Note that Apple sends the user's **name only on the very first authorization**. The app captures it from the `user` POST field on that first pass and stores it. If you delete the user row and re-register, the name will come back blank until you revoke access under **Apple ID → Sign in with Apple** on your device.

---

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `invalid_client` | Team ID, Key ID, or Services ID mismatch | Verify all three; confirm the `.p8` matches the Key ID |
| `invalid_request` redirect | Return URL not registered | Must match exactly, HTTPS, no trailing slash |
| Name is blank | Not the first authorization | Expected Apple behavior; let users edit their name in their profile |
| Key file not found | Relative path resolution | Path is relative to the project root, not `public/` |