Melvynx/saveit.now / .agents/skills/ns-setup-apple-auth
ns-setup-apple-auth
VerifiedSet up and verify Sign in with Apple for NowStack Mobile web and iOS against the shared Better Auth and Convex backend. Use for Apple Services IDs, return URLs, Sign in with Apple keys, APPLE_CLIENT_ID or APPLE_CLIENT_SECRET, expiring Apple JWTs, or production Apple auth rotation.
Setup Apple Auth - NowStack Mobile
<critical_distinction>
APPLE_CLIENT_ID is the Apple Services ID used by the web OAuth flow, normally {bundle_id}.web. It is not the native app bundle ID. The native App ID remains the Services ID's primary App ID.
</critical_distinction>
<read_first>
rg -n "enableAppleSignIn|APPLE_CLIENT|apple|getEnabledAuthProviders|bundleId|appleTeamId|CONVEX_SITE" \
site-config.ts convex mobile-app web-app scripts
npx convex env list | sed 's/=.*$/=<set>/'
npx convex run auth:getEnabledAuthProviders '{}'
For --prod, inspect the production deployment too:
npx convex env list --prod | sed 's/=.*$/=<set>/'
npx convex run --prod auth:getEnabledAuthProviders '{}'
Derive:
{bundle_id}and{team_id}fromsite-config.ts.{services_id}as{bundle_id}.webfor development. For--prod, use an existing production-only Services ID or create{bundle_id}.web.prod.{convex_site_host}from the target deployment's.convex.siteURL.- Return URL:
https://{convex_site_host}/api/auth/callback/apple. - Domain:
{convex_site_host}with no scheme and no path. </read_first>
# development
node scripts/generate-apple-client-secret.mjs \
--team-id "<team-id>" \
--client-id "<services-id>" \
--key-id "<key-id>" \
--private-key "/secure/path/AuthKey_<key-id>.p8"
# production
node scripts/generate-apple-client-secret.mjs --prod \
--team-id "<team-id>" \
--client-id "<production-services-id>" \
--key-id "<key-id>" \
--private-key "/secure/path/AuthKey_<key-id>.p8"
Add --dry-run first to validate signing and expiry without changing Convex, then rerun without it to install the credentials.
The script never prints the JWT. It generates an ES256 token with:
- header:
alg=ES256,kid={key_id},typ=JWT; - claims:
iss={team_id}, currentiat,expno more than six months afteriat,aud=https://appleid.apple.com,sub={services_id}; - the
.p8private key and a JOSE-compatible 64-byte IEEE-P1363 signature.
- The script validates required claims, the 64-byte signature, and a lifetime of at most 180 days, then stores
APPLE_CLIENT_IDandAPPLE_CLIENT_SECRETdirectly in the selected Convex deployment. Record the reported expiry in the handoff. - Set
SITE_URLseparately because it is the web origin rather than an Apple credential:
# development
npx convex env set SITE_URL "http://localhost:3111"
# production (--prod)
npx convex env set --prod SITE_URL "https://<production-app-domain>"
Do not print the JWT, .p8 contents, or private-key path in public output. Do not commit any of them.
<jwt_rotation> Apple client-secret JWTs expire. Every production preflight must decode the current JWT expiry without logging the token and generate a fresh JWT when it is missing, expired, close to expiry, or when entering production for the first time. Default to rotating before a production release rather than copying a development value. </jwt_rotation>
production
npx convex run --prod auth:getEnabledAuthProviders '{}'
The result must report `apple: true`. Then:
1. Open the signed-out web sign-in route using the repo's browser-verification workflow.
2. Confirm the Apple button is visible and redirects to `appleid.apple.com` with `{services_id}` and the exact target return URL.
3. Reload the iOS development build against the same Convex deployment and confirm the native Apple button appears.
4. Complete a sign-in when possible and verify the session returns to the intended callback URL.
If Apple reports `invalid_client`, check Services ID versus bundle ID, key association, Team ID, JWT signature format, clock skew, and expiry before changing application code.
</verification>
<production_invariant>
A production deployment is blocked until the production domain/return URL is registered, `APPLE_CLIENT_ID` is the Services ID, a fresh valid JWT is stored with `--prod`, and the production provider query returns `apple: true`.
</production_invariant>
<success_criteria>
- Services ID points to the correct primary App ID and target callback.
- `.p8` remains outside the repository and is never printed.
- Fresh JWT claims and expiry are verified locally.
- Apple credentials exist only in the matching Convex deployment.
- Web redirect and iOS provider visibility are verified.
</success_criteria>
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |