# Apple

## Implemented flow

The mock implements the **Sign in with Apple web authorization code flow**:
authorize, return the code to your callback, exchange it for an access token,
refresh token and signed ID token, then refresh or revoke tokens. It publishes
discovery and signing keys. Apple has no userinfo endpoint in this flow.

Other Apple services and native Apple SDK interactions are not implemented.
The connector uses shared mock credentials in place of Apple's signed client
secret; successful mock sign-in cannot validate your Apple key or Services ID.

Sources: [Sign in with Apple REST API](https://developer.apple.com/documentation/signinwithapplerestapi),
[authorization response](https://developer.apple.com/documentation/signinwithapplerestapi/request-an-authorization-to-the-sign-in-with-apple-server).

## OpenID Connect (OIDC)

This provider supports OpenID Connect (OIDC), which adds signed ID tokens to OAuth
2.0 so your app can verify the signed-in user's identity. Mockatoo publishes OIDC
discovery and signing keys for this provider. See the
[Hono + oauth4webapi example](https://github.com/mockatoo/examples/blob/main/oauth4webapi-hono/src/app.tsx)
for a minimal authorization code flow with discovery and ID-token validation,
including this provider's differences, without an auth abstraction.

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.apple
import { mockApple } from "@mockatoo/connect-better-auth";
const apple = { clientId: process.env.APPLE_CLIENT_ID!,
                clientSecret: process.env.APPLE_CLIENT_SECRET! };
export const auth = betterAuth({
  socialProviders: process.env.NODE_ENV === "production" ? { apple } : {},
  plugins: process.env.NODE_ENV === "production" ? [] : [mockApple(apple)],
});

// Auth.js
import Apple from "next-auth/providers/apple";
import { MockApple } from "@mockatoo/connect-authjs";
providers: [process.env.NODE_ENV === "production" ? Apple() : MockApple()],
```

- With `name` or `email` scope, the callback uses **form POST**. Ensure your
  callback and state handling accept it.
- The name arrives in the separate `user` field, never in the ID token. Store
  it on first sign-in; `+returning` omits that field to exercise later sign-ins.
- Handle private relay addresses and boolean claims encoded as strings; use
  `+hidden` and `+strings` to exercise these cases.
- Refreshing does not return a replacement refresh token. Revocation is
  implemented for testing account deletion flows.
- Better Auth's connector adds the mock origin to trusted origins for local
  form callbacks. The mock accepts HTTP and localhost callbacks; real Apple
  requires an eligible HTTPS callback.

## Special test addresses

Log in as `you+<tag>@example.com` with your own account's password to get a distinct, stable test user. Tags combine with dots, such as `you+hd.unverified@example.com`. Any other tag, such as `you+1@example.com`, is just another user; see [Email tags](../email-tags.md).

| Tag | Behavior | |
| --- | --- | --- |
| `unverified` | `email_verified: false` (GitHub: primary email `verified: false`; Discord: `verified: false`; LinkedIn: `"false"` in the ID token) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/unverified.spec.ts) |
| `renamed` | Same user ID (`sub`, Microsoft `oid`, GitHub, Discord, X and Facebook `id`) as the address without `+renamed`, different email | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/renamed.spec.ts) |
| `noname` | No name (Google: also no `given_name`/`family_name`; GitHub: `name: null`; Discord: `global_name: null`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noname.spec.ts) |
| `hidden` | Hide My Email: a `@privaterelay.appleid.com` address with `is_private_email: true` | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/hidden.spec.ts) |
| `strings` | `email_verified` and `is_private_email` are the strings `"true"`/`"false"` instead of booleans | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/strings.spec.ts) |
| `returning` | Same user and email as without the tag, signing in again. Google: no refresh token unless `prompt=consent`. Apple: no `user` field, so no name | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/returning.spec.ts) |
| `revoked` | Sign-in works; every refresh returns `invalid_grant` (GitHub: `bad_refresh_token`, and only with `offline_access`; X: `invalid_request`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/revoked.spec.ts) |
| `badcode` | The code exchange fails (`invalid_grant`; GitHub: `bad_verification_code`; LinkedIn and X: `invalid_request`; Facebook: `Invalid verification code format.`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/badcode.spec.ts) |
| `down` | The token endpoint returns 503 | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/down.spec.ts) |
| `flaky` | The first exchange of each code returns 503; a retry succeeds | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/flaky.spec.ts) |
| `slow` | Token responses are delayed (10 seconds) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/slow.spec.ts) |

## Known differences



### This provider

| Difference | Effect |
| --- | --- |
| `mockApple()` adds the mock's origin to Better Auth's trusted origins. A mock on `localhost` is the same site as a local app, so Apple's form POST carries the app's cookies and Better Auth would otherwise reject it. Real Apple is cross-site, so Better Auth never checks its origin. | Better Auth trusts one extra origin while you use the mock. |

### Shared mock limits

| Difference | Effect |
| --- | --- |
| ID tokens are issued to the shared mock client. Native bundle IDs and native client registrations are not modeled. | Hides a native audience setting that does not match your production registration. |
| Refresh tokens do not expire from age or inactivity, even when a response advertises `refresh_token_expires_in`. Rotation and revocation still apply where supported; `+revoked` forces refresh failure. | Hides failures after long periods without sign-in. Use `+revoked` to exercise expired or revoked grant handling. |
| Any `http`/`https` callback URL is accepted, including `localhost`. Apple refuses `http` and `localhost`, and Microsoft refuses `http` except for `localhost`, whatever the app registered. | Hides a callback URL the real provider refuses outright. |
| Everyone uses one shared client (`mockatoo` / `mockatoo-secret`). The connectors replace your production client ID and secret, Apple's signed client secret, and Microsoft's client assertion. | Hides wrong production credentials or a broken client-secret setup. |
| The login form and the consent screen appear on every sign-in; there is no remembered session. `prompt=none` fails for Google (`interaction_required`) and Microsoft (`login_required`), and Discord and LinkedIn, which skip consent for a returning user (LinkedIn even with `prompt=consent`), always ask again. | Breaks silent sign-in that works with a real signed-in user. |
| Issuers and signing keys are the mock's (for example `https://app.mockatoo.globalunderdog.com/google`, not `https://accounts.google.com`). Discord's authorization responses carry `iss=https://app.mockatoo.globalunderdog.com/discord`, not `https://discord.com`. | Breaks code that hardcodes a real issuer or key URL. |
| Tokens are only valid at the mock. Real provider APIs (Google APIs, Microsoft Graph, GitHub's `api.github.com`, Discord's `discord.com/api`, LinkedIn's `api.linkedin.com`, X's `api.x.com`, Facebook's `graph.facebook.com`) reject them, and the mock doesn't serve those APIs beyond what sign-in needs. | Breaks app features that call the provider's API after sign-in. |
| A special address (`you+tag@…`) is a different test user with the same password. Apps that strip `+tags` from emails will merge them into one user. | Breaks special addresses in such apps. |
