feat(cli): adapter-based APNs key setup for init apns --create-key

[ArnabChatterjee20k]

Stacked on #1963 (init apns). This is the base for one-click APNs key creation. The adapters come in separate PRs on top of it:

• appwrite: Appwrite's own Go implementation (SRP sign-in, two-factor, Developer portal calls), from feat(cli): create APNs keys with a native Apple sign-in instead of Node.js #1991.
• expo: @expo/apple-utils through an embedded Node helper, from feat(cli): init apns --create-key creates the APNs key with the Apple ID #1989.
• fastlane: spaceship through an installed fastlane.

Why adapters

Apple has no public API for creating APNs keys. spaceship, @expo/apple-utils and our own implementation all sign in as a person would and call the Developer portal's private API, which Apple changes without notice. With adapters, picking the implementation is a setting, not a release: when Apple breaks one, users (or our docs) switch to another.

Usage

From the CLI

# Create the key with the default setup (appwrite), for both environments
appwrite init apns --create-key

# Pick the setup for one run
appwrite init apns --create-key --provider expo

# Or for every run, for example after Apple breaks the default one
export APPWRITE_APNS_SETUP=fastlane
appwrite init apns --create-key

# Answer the sign-in from the environment (CI, or to skip typing)
export APPWRITE_APPLE_ID=dev@example.com
export APPWRITE_APPLE_PASSWORD=...
appwrite init apns --create-key --team-id ABCDE12345

# Only one environment: one provider, and a key for that environment
appwrite init apns --create-key --environment sandbox

# Replace the key on providers that are already set up
appwrite init apns --create-key --force

How the setup is chosen: --provider, then APPWRITE_APNS_SETUP, then appwrite.

Two-factor still needs a person: the code is asked in the terminal. A setup that keeps a session (stored under ~/.appwrite/apns/<setup>/) skips it on later runs.

What happens when key creation fails:

Case	Result
--create-key and the sign-in or key creation fails	Stops with the reason. Nothing is written to Appwrite
Apple sign-in chosen from the prompt and it fails	Warns, then offers the browser and file options
The team already has the maximum number of APNs keys	Lists the team's keys and stops: reuse a saved .p8 with --key-path, or revoke one
Unknown --provider / APPWRITE_APNS_SETUP	Stops, naming the setups this build has

From Go

Creating a key with a setup:

registry := apns.NewRegistry(appwrite.New(), expo.New())

adapter, err := registry.Get("appwrite")
if err != nil {
    return err
}

key, err := apns.CreateKey(ctx, adapter, apns.Request{
    TeamID:      "ABCDE12345",           // optional: empty lets the sign-in pick or ask
    Name:        "Appwrite Push",
    Environment: apns.EnvironmentAll,    // or EnvironmentProduction / EnvironmentSandbox
    AppleID:     os.Getenv("APPWRITE_APPLE_ID"),       // optional: asked when empty
    Password:    os.Getenv("APPWRITE_APPLE_PASSWORD"), // optional: asked when empty
    SessionDir:  "~/.appwrite/apns/appwrite",
    Asker:       asker, // Ask(question, secret) and Choose(question, options)
    Log:         func(format string, args ...any) { fmt.Printf(format+"\n", args...) },
})

var full *apns.MaxKeysError
switch {
case errors.As(err, &full):
    // full.Keys lists the team's keys
case errors.Is(err, apns.ErrInvalidCredentials):
    // Apple refused the Apple ID or password
case errors.Is(err, apns.ErrUnavailable):
    // the setup cannot run here (for example Node.js missing for expo); nothing was sent to Apple
case err != nil:
    return err
}
// key.KeyID, key.TeamID, key.P8: save key.P8 now, Apple serves it once

Writing a setup:

package mysetup

type Adapter struct{}

func New() *Adapter { return &Adapter{} }

func (*Adapter) Name() string { return "mysetup" }

func (*Adapter) CreateKey(ctx context.Context, request apns.Request) (apns.Key, error) {
    // 1. Return apns.ErrUnavailable before contacting Apple if this setup cannot run here.
    // 2. Sign in with request.AppleID / request.Password, or ask through request.Asker.
    //    Ask for the two-factor code through request.Asker too. Report progress through request.Log.
    // 3. Use request.TeamID, or pick the account's only team, or ask with request.Asker.Choose.
    // 4. Create a team-scoped key with APNs for request.Environment and download its .p8.
    // 5. Map Apple's errors: a refused sign-in to apns.ErrInvalidCredentials,
    //    a full team to &apns.MaxKeysError{Keys: ...}.
    return apns.Key{KeyID: id, TeamID: team, P8: p8}, nil
}

Then add it in one place, apnsAdapters() in internal/cmd/initpush.go:

func apnsAdapters() *apns.Registry {
    return apns.NewRegistry(appwrite.New(), expo.New(), mysetup.New())
}

apns.CreateKey checks what every setup returns: a 10-character key ID, a valid team ID that matches the requested team, and .p8 contents. A setup that breaks this contract fails loudly instead of writing a bad provider. apnstest.Adapter is a scripted fake for testing code that uses a setup.

What's here

internal/apns (no imports from the CLI, so it can move to its own module and repo):

• Adapter interface: Name() and CreateKey(ctx, Request) (Key, error).
• Request: team (optional), key name, environment, optional Apple ID and password, session folder, and the Asker / Log callbacks for prompts and output.
• Shared results and errors: Key, ExistingKey, MaxKeysError, ErrUnavailable, ErrInvalidCredentials, Environment / ParseEnvironment.
• CreateKey(ctx, adapter, request) holds every adapter to the same contract. It checks the request (environment, name, team ID format), then the result: a valid key ID and team, the requested team, and .p8 contents.
• Registry: adapters by name, with clear errors for an unknown name or an empty build.
• apnstest.Adapter: a scripted fake for tests.

init apns:

• --create-key creates the key with the chosen setup:
  • --provider appwrite|expo|fastlane, then APPWRITE_APNS_SETUP, then appwrite. The flag + env pattern matches --config-file / APPWRITE_CONFIG_FILE.
  • Sessions are kept per setup under ~/.appwrite/apns/<setup>/.
• APPWRITE_APPLE_ID / APPWRITE_APPLE_PASSWORD answer the sign-in questions. The CLI prints the variable name, never the value.
• --environment production|sandbox|all (default all) picks which providers are set up, what counts as "already set up", and the environment of a created key.
• Without a known team, the sign-in chooses it, and the team question only comes up for key files and the browser flow.
• The new .p8 is saved (0600, never overwriting) before the providers are written, because Apple allows one download.
• A full team lists the existing keys and stops with --key-path advice.
• A failed --create-key stops instead of falling back to a .p8 already in the folder. Choosing the sign-in from the prompt still falls back to the other options.
• No adapter is registered in this PR, so the sign-in option isn't offered and --create-key says the build has none. Each adapter PR adds itself to apnsAdapters().

Tests

• internal/apns: environment parsing, request checks (the adapter never runs on a bad request), the result contract (bad key ID, missing team, wrong team), error pass-through, registry lookup and errors.
• init apns (through the fake adapter):
  • key creation and saving, with no re-creation on a rerun
  • the team coming from the sign-in
  • stopping on failure, and falling back when the sign-in was chosen from the prompt
  • a full team
  • a single environment
  • choosing the setup: --provider beats APPWRITE_APNS_SETUP, which beats the default; credentials passed through without the password ever printed
  • an unknown setup
  • an empty build
• The full CLI suite (-race), gofmt, Rector and the Generation suite pass.

Supersedes

#1989 and #1991 once the expo and appwrite adapter PRs land on this.

[hansi-codes]

🟢 Tier S · Ready to merge

This PR builds on the shared APNs adapter contract and adds three key-creation backends: Appwrite’s Go-based Apple portal client, an Expo Node helper, and a fastlane lane. It registers those backends in the CLI and adds authentication, session handling, runtime checks, and tests for the adapters and init apns flows.

Latest changes: The newest commits add and register the Appwrite, Expo, and fastlane adapters, including their Apple authentication flows and runtime-specific helpers.

Verdict	New comments	Fixed	Still open
🛑 Changes requested	0	0	0

📂 Walkthrough · 21

File	Change
src/SDK/Language/CLI.php	Registers the APNs adapter implementations and helper assets in generated CLI output.
templates/cli/internal/apns/apns.go	Defines shared APNs adapter contracts, validation, errors, and registry behavior.
templates/cli/internal/apns/apns_test.go	Tests environment parsing, request/result validation, and registry behavior.
templates/cli/internal/apns/apnstest/apnstest.go	Adds a scripted APNs adapter and test key helper.
templates/cli/internal/apns/appwrite/adapter.go	Implements Appwrite's Go-based Apple sign-in and key creation flow.
templates/cli/internal/apns/appwrite/adapter_test.go	Exercises Apple sign-in, two-factor, session reuse, team selection, and key creation against a fake portal.
templates/cli/internal/apns/appwrite/auth.go	Implements Apple authentication, two-factor verification, and widget-key retrieval.
templates/cli/internal/apns/appwrite/jar.go	Persists Apple session cookies for later runs.
templates/cli/internal/apns/appwrite/portal.go	Implements Developer portal team/key listing, creation, and key download calls.
templates/cli/internal/apns/appwrite/srp.go	Implements Apple's SRP password proof and hashcash challenge.
templates/cli/internal/apns/appwrite/srp_test.go	Tests SRP vectors and hashcash behavior.
templates/cli/internal/apns/expo/adapter.go	Installs and runs the embedded Expo helper, checking Node availability and decoding results.
templates/cli/internal/apns/expo/adapter_test.go	Tests Expo runtime checks, helper invocation, and result decoding.
templates/cli/internal/apns/expo/helper/helper.js	Creates APNs keys through @expo/apple-utils and serializes results for the Go adapter.
templates/cli/internal/apns/expo/helper/package.json	Declares the Expo helper's Node package and dependency.
templates/cli/internal/apns/expo/helper/package-lock.json	Pins the Expo helper dependency in its npm lockfile.
templates/cli/internal/apns/fastlane/adapter.go	Runs an embedded fastlane lane and selects the installed or project-bundled fastlane.
templates/cli/internal/apns/fastlane/adapter_test.go	Tests fastlane version checks, credential handling, and Bundler selection.
templates/cli/internal/apns/fastlane/helper/Fastfile	Creates APNs keys through fastlane's spaceship client and serializes lane results.
templates/cli/internal/cmd/initpush.go	Registers the three adapters for init apns setup selection.
templates/cli/internal/cmd/initpush_test.go	Tests adapter selection and key-creation behavior in the CLI.

---

_{Reviewed the commits since 4cfe2c0 · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

[hansi-codes]

🔵 Tier A · See the inline comments. Summary

[hansi-codes]

🟢 Tier S · Looks good to merge. Summary

[hansi-codes]

🟡 Tier B · 1 blocking finding to address. Summary