Push Notifications & Subscriptions (epic)

[leogdion]

Goal

Deliver the complete server-side push-notification workflow for CloudKit Web Services: subscriptions (the change triggers) plus APNs tokens (the delivery path). These endpoints are interdependent — a subscription is useless without a registered push destination, and the token endpoints exist solely to feed subscription-triggered pushes — so they ship together as one epic.

Target: v1.0.0-beta.2.

Sub-issues

Subscriptions

• Fetching Subscriptions (subscriptions/list) #49 — Fetching Subscriptions (subscriptions/list)
• Fetching Subscriptions by Identifier (subscriptions/lookup) #50 — Fetching Subscriptions by Identifier (subscriptions/lookup)
• Modifying Subscriptions (subscriptions/modify) #51 — Modifying Subscriptions (subscriptions/modify)

APNs Tokens

• Creating APNs Tokens (tokens/create) #52 — Creating APNs Tokens (tokens/create)
• Registering Tokens (tokens/register) #53 — Registering Tokens (tokens/register)

Scope notes

• All five endpoints already exist in openapi.yaml with generated client methods in Sources/MistKitOpenAPI/Client.swift.
• Each gets a CloudKitService method (subscriptions → a new CloudKitService+SubscriptionOperations.swift; tokens → CloudKitService+TokenOperations.swift per Creating APNs Tokens (tokens/create) #52/Registering Tokens (tokens/register) #53), routed through the existing dispatcher + CloudKitService+ErrorHandling.
• MistDemo wiring is part of the API implementation for each endpoint: replace the existing CLI command stubs and add an integration phase under Examples/MistDemo/Sources/MistDemoKit/Integration/Phases/ so each operation is exercised against a live container.

Acceptance criteria

• All five CloudKitService methods exist, are documented, and surface errors through CloudKitServiceError.
• Corresponding mistdemo commands run successfully against a real container.
• Integration phases cover each endpoint.

[leogdion]

Live integration finding: tokens/create & tokens/register return HTTP 405 server-side

While running the live MistDemo integration suite (test-private / test-public) against the real container to validate this epic, the subscription endpoints (#49/#50/#51) all pass end-to-end. The two APNs token endpoints (#52 tokens/create, #53 tokens/register) do not work server-side.

What was fixed along the way

• Wrong path (was a 404). The spec originally nested the token endpoints under /{database}/tokens/.... Apple's CloudKit Web Services reference puts them at /database/{version}/{container}/{environment}/tokens/{create,register} — container-scoped, no {database} segment. Corrected in openapi.yaml + regenerated; added a ContainerOperationInputPath protocol for the database-less path init.
• Subscription delete crash. Separately, modifySubscriptions fatal-errored on delete responses — CloudKit echoes a deleted subscription as a bare { subscriptionID } (no subscriptionType). Now filtered as a deletion-ack rather than treated as a conversion failure.

The remaining problem

With the corrected path, both token endpoints return 405 Method Not Allowed (response body literally Method Not Allowed, with Allow: OPTIONS).

This is not an authentication problem — verified by elimination:

• Web-auth (ckAPIToken + ckWebAuthToken) succeeds on every private-DB endpoint (subscriptions, zones, records) → 200.
• Server-to-server key signing succeeds across the full public pipeline (test-public passes) → 200.
• Both auth methods → 405 only on tokens/*. A failed auth would be 401, not 405.

The request path matches Apple's (archived) CloudKit Web Services reference exactly, but the live endpoints reject server-side POST. They appear to be CloudKit-JS / browser-only (the Allow: OPTIONS CORS-preflight behavior is consistent with that) or deprecated.

Status of the token code

The createAPNsToken / registerAPNsToken service methods, CLI commands, web backend wiring, and unit tests are all implemented and correct per the documented spec — they're retained. Only the live TokenRoundtripPhase can't pass, because the endpoint itself is unreachable server-side.

Follow-up

• Decide handling for TokenRoundtripPhase in the live runner (currently it would fail at phase 16).
• Determine whether a non-archived endpoint / different host exists, or confirm these are browser-only and document the limitation for Creating APNs Tokens (tokens/create) #52/Registering Tokens (tokens/register) #53.

[leogdion]

Phase 1 update: spec bugs fixed against Apple's archived REST docs — tokens/create still 405

Following the earlier 405 finding, cross-checked the request against Apple's authoritative archived references:

• https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/CreateTokens.html
• https://developer.apple.com/library/archive/documentation/DataManagement/Conceptual/CloudKitWebServicesReference/RegisterTokens.html

That surfaced two real spec bugs in our implementation, independent of the 405 mystery, which are now fixed on this branch:

1. tokens/register request body was missing apnsEnvironment. Apple lists both apnsEnvironment and apnsToken as required; we were only sending apnsToken. Even if the endpoint were live, this would have rejected.
2. tokens/create response shape was wrong. Apple's response is { apnsEnvironment, apnsToken, webcourierURL } (the long-poll URL browser/Service-Worker callers need); ours was { apnsToken, webcAuthToken } — webcAuthToken doesn't appear in Apple's archived REST docs and seems to be a CloudKit-JS-internal concept conflated with the REST response. Renamed webcourierURL and added apnsEnvironment to the domain model.

What changed on the branch

• openapi.yaml: added required apnsEnvironment to both tokens/create and tokens/register request bodies; reshaped TokenResponse to { apnsEnvironment, apnsToken, webcourierURL } (all required).
• Regenerated Sources/MistKitOpenAPI/.
• APNsTokenResult: replaced webAuthToken: String → webcourierURL: URL; added environment: APNsEnvironment.
• registerAPNsToken(_:database:) → registerAPNsToken(_:environment:database:).
• Updated all callers: TokenRoundtripPhase, RegisterTokenCommand (with new --apns-environment flag), WebBackend, WebRequests+Tokens, WebResponse.Token, the JS panel, and the corresponding mocks/tests.
• All 498 MistKit + 941 MistDemo unit tests pass; Scripts/lint.sh clean.

Live retest result

Ran mistdemo test-private --verbose against iCloud.com.brightdigit.MistDemo. Outcome:

• Phases 1–15 all green, including SubscriptionRoundtripPhase (subscriptions create/list/lookup/delete cleanly).
• Phase 16 TokenRoundtripPhase fails at the first call — createAPNsToken returns HTTP 405 before we ever exercise the (now-corrected) registerAPNsToken. The verbose phase log goes straight from the phase header to the warning + crash, so the 405 is definitely on tokens/create, not the second leg.

🎟️ Create and register an APNs token
warning com.brightdigit.MistKit.api: [MistKit] Unhandled Output (HTTP 405) - treating as generic HTTP error
❌ Error: httpError(statusCode: 405)

Phase 15 success is the new datapoint: subscriptions go through fine with the same auth, container, and environment that fail on tokens/create — the 405 isn't an auth problem and isn't a container-scope problem.

Open question — where to next

We can't yet prove whether the 405 is "endpoint dead server-side" or "we're still sending something subtly wrong" (e.g., header/content-type quirk, version segment, host) because we don't see the actual wire request. MistDemo has no LoggingSystem.bootstrap call, so swift-log's default .info level suppresses the middleware's .debug request/response trace. The fix is to bootstrap swift-log when --verbose is passed — small change, but parked here to avoid scope creep on this push.

Next steps when we pick this up:

1. Wire --verbose → LoggingSystem.bootstrap with com.brightdigit.MistKit.middleware = .debug.
2. Re-run test-private --verbose and capture the exact POST /tokens/create request (URL, headers including signature, body bytes).
3. Compare against Apple's archived REST reference to either find the wrong byte or confirm the endpoint really is server-side-dead. If confirmed dead, apply the gated graceful-skip (catch 405 in TokenRoundtripPhase so the live suite still passes, keep canary in place).

Committing Phase 1 with [skip ci] since the live integration phase still fails by design.