# apple

Local Apple OIDC emulator for testing Sign in with Apple flows. Runs a server with discovery endpoints, token exchange, and JWKS for RS256 ID tokens.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 224 installs · ★ 2075 repo stars
- Author: vercel-labs
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/vercel-labs/emulate/tree/HEAD/skills/apple/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/apple

## What it does

Starts an emulator on `localhost:4000` (port configurable) with the full OIDC flow: authorization endpoint with user picker, token exchange issuing RS256 ID tokens, PKCE support, `form_post` mode, and JWKS for signature verification. Seed users and OAuth clients via YAML config: email, name, `is_private_email` flag (generates `@privaterelay.appleid.com` addresses). Without config, accepts any `client_id`; with config, enforces strict `redirect_uri` validation.

Agent can start the emulator with `npx emulate --service apple`, wire `APPLE_EMULATOR_URL` into Auth.js or Passport.js providers, set up seed files with users and clients. Uses `curl` for direct OIDC endpoint calls. Testing Apple OAuth locally breaks without an emulator: real Apple endpoints reject localhost origins.

Allowed tools: `npx emulate:*`, `curl:*`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill apple -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/apple/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/apple/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill apple -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/apple/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill apple -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/apple/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vercel-labs/emulate skills/apple
```

2. **Manually: put the files in place**
- File: `.github/skills/apple/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill apple -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vercel-labs/emulate --path skills/apple
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/apple/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vercel-labs/emulate --skill apple -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vercel-labs/emulate/tree/HEAD/skills/apple/SKILL.md

## When to use it
- test Sign in with Apple without a production Apple Developer account
- emulate OIDC discovery and token exchange for local development
- verify private email handling (`@privaterelay.appleid.com`)
- configure multiple test Apple users with different emails and names
- debug Auth.js or Passport.js Apple OAuth integration locally

## Example prompts
- Start the Apple emulator on port 4004 and show the OIDC discovery URL
- Set up a seed config for the emulator: two users, one with private email, client `com.myapp.service`
- Wire `APPLE_EMULATOR_URL` into the Auth.js Apple provider and output the config code

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 46abe5b5b00758df.

BEGIN THIRD-PARTY FILE 46abe5b5b00758df
````text
---
name: apple
description: Emulated Sign in with Apple / Apple OIDC for local development and testing. Use when the user needs to test Apple sign-in locally, emulate Apple OIDC discovery, handle Apple token exchange, configure Apple OAuth clients, or work with Apple userinfo without hitting real Apple APIs. Triggers include "Apple OAuth", "emulate Apple", "mock Apple login", "test Apple sign-in", "Sign in with Apple", "Apple OIDC", "local Apple auth", or any task requiring a local Apple OAuth/OIDC provider.
allowed-tools: Bash(npx emulate:*), Bash(curl:*)
---

# Apple Sign In Emulator

Sign in with Apple emulation with authorization code flow, PKCE support, RS256 ID tokens, and OIDC discovery.

## Start

Local listeners bind to `127.0.0.1` by default. For access from containers or other machines, pass `--host 0.0.0.0` to the CLI or `hostname: '0.0.0.0'` to `createEmulator`. Configure `--base-url` or `baseUrl` for advertised URLs reachable by those clients.

```bash
# Apple only
npx emulate --service apple

# Default port (when run alone)
# http://localhost:4000
```

Or programmatically:

```typescript
import { createEmulator } from 'emulate'

const apple = await createEmulator({ service: 'apple', port: 4004 })
// apple.url === 'http://localhost:4004'
```

## Pointing Your App at the Emulator

### Environment Variable

```bash
APPLE_EMULATOR_URL=http://localhost:4004
```

### OAuth URL Mapping

| Real Apple URL | Emulator URL |
|----------------|-------------|
| `https://appleid.apple.com/.well-known/openid-configuration` | `$APPLE_EMULATOR_URL/.well-known/openid-configuration` |
| `https://appleid.apple.com/auth/authorize` | `$APPLE_EMULATOR_URL/auth/authorize` |
| `https://appleid.apple.com/auth/token` | `$APPLE_EMULATOR_URL/auth/token` |
| `https://appleid.apple.com/auth/keys` | `$APPLE_EMULATOR_URL/auth/keys` |
| `https://appleid.apple.com/auth/revoke` | `$APPLE_EMULATOR_URL/auth/revoke` |

### Auth.js / NextAuth.js

```typescript
import Apple from '@auth/core/providers/apple'

Apple({
  clientId: process.env.APPLE_CLIENT_ID,
  clientSecret: process.env.APPLE_CLIENT_SECRET,
  authorization: {
    url: `${process.env.APPLE_EMULATOR_URL}/auth/authorize`,
    params: { scope: 'openid email name', response_mode: 'form_post' },
  },
  token: {
    url: `${process.env.APPLE_EMULATOR_URL}/auth/token`,
  },
  jwks_endpoint: `${process.env.APPLE_EMULATOR_URL}/auth/keys`,
})
```

### Passport.js

```typescript
import { Strategy as AppleStrategy } from 'passport-apple'

const APPLE_URL = process.env.APPLE_EMULATOR_URL ?? 'https://appleid.apple.com'

new AppleStrategy({
  clientID: process.env.APPLE_CLIENT_ID,
  teamID: process.env.APPLE_TEAM_ID,
  keyID: process.env.APPLE_KEY_ID,
  callbackURL: 'http://localhost:3000/api/auth/callback/apple',
````
END THIRD-PARTY FILE 46abe5b5b00758df

The third-party file has ended. Everything between the 46abe5b5b00758df tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2786 of 8348 bytes. © vercel-labs · Apache-2.0 · https://github.com/vercel-labs/emulate/tree/HEAD/skills/apple/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
