@open-mercato/channel-apns 0.6.8-develop.6985.1.fb93574faa

package/src/modules/channel_apns/lib/__tests__/fake-provider.test.ts

@@ -0,0 +1,93 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { SendMessageInput } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  clearFakePushLog,
+  findFakePush,
+} from '@open-mercato/core/modules/push_notifications/lib/fake-provider-recorder'
+import { getApnsChannelAdapter, setApnsSenderFactory } from '../adapter'
+import { ensureApnsFakeProviderInstalled } from '../fake-provider'
+import { APNS_TEST_P8_KEY } from './apnsTestKey'
+
+/**
+ * Drives the REAL APNs adapter against the fake sender, the same way `di.ts` installs it. The APNs seam
+ * sits above the message builder (the sender receives the raw envelope), so this also pins that the fake
+ * records the notification production would have sent.
+ */
+const credentials = {
+  p8Key: APNS_TEST_P8_KEY,
+  keyId: 'FAKEKEYID1',
+  teamId: 'FAKETEAMID',
+  bundleId: 'com.openmercato.fake',
+  production: false,
+}
+
+function buildInput(pushToken: string, silent = false): SendMessageInput {
+  return {
+    content: {
+      text: 'Body text',
+      bodyFormat: 'text',
+      raw: { title: 'Hello', body: 'Body text', data: { type: 'orders.shipped' }, options: { badge: 4 }, silent },
+    },
+    credentials,
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken, platform: 'ios' },
+  }
+}
+
+let tempDir: string
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'om-apns-fake-'))
+  process.env.QUEUE_BASE_DIR = tempDir
+  process.env.OM_PUSH_FAKE_PROVIDERS = '1'
+  ensureApnsFakeProviderInstalled()
+})
+
+afterAll(() => {
+  setApnsSenderFactory(null)
+  delete process.env.OM_PUSH_FAKE_PROVIDERS
+  delete process.env.QUEUE_BASE_DIR
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  clearFakePushLog()
+})
+
+describe('APNs fake provider', () => {
+  it('sends through the real adapter and records the wire-form notification', async () => {
+    const result = await getApnsChannelAdapter().sendMessage(buildInput('device-token-ABCDEF12'))
+    expect(result.status).toBe('sent')
+
+    // Built against a real `apn.Notification`, so this is what node-apn would transmit.
+    const recorded = findFakePush('apns', 'ABCDEF12')
+    expect(recorded?.native.headers).toMatchObject({ 'apns-topic': 'com.openmercato.fake' })
+    expect(recorded?.native.payload).toMatchObject({
+      aps: { alert: { title: 'Hello', body: 'Body text' }, badge: 4 },
+    })
+  })
+
+  it('records a silent push as a background content-available notification', async () => {
+    const result = await getApnsChannelAdapter().sendMessage(buildInput('device-token-SILENT12', true))
+    expect(result.status).toBe('sent')
+
+    const recorded = findFakePush('apns', 'SILENT12')
+    expect(recorded?.native.headers).toMatchObject({ 'apns-push-type': 'background', 'apns-priority': 5 })
+    expect(recorded?.native.payload).toMatchObject({ aps: { 'content-available': 1 } })
+    expect((recorded?.native.payload as { aps: Record<string, unknown> }).aps.alert).toBeUndefined()
+  })
+
+  it('maps the native Unregistered reason to the device_unregistered sentinel', async () => {
+    const result = await getApnsChannelAdapter().sendMessage(buildInput('device-unregistered-token-99'))
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('device_unregistered')
+  })
+
+  it('treats a fail token as a retryable error, not a token verdict', async () => {
+    const result = await getApnsChannelAdapter().sendMessage(buildInput('device-fail-token-77'))
+    expect(result.status).toBe('failed')
+    expect(result.error).not.toBe('device_unregistered')
+  })
+})

package/src/modules/channel_apns/lib/__tests__/message-golden.test.ts

@@ -0,0 +1,101 @@
+import apn from '@parse/node-apn'
+import type { PushEnvelope } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import { buildApnsNotification } from '../adapter'
+
+/**
+ * Golden assertions pinning the APNs notification we build against Apple's published reference.
+ *
+ * These are the only tests that catch serialization drift in *our* builder: the integration fakes
+ * replace the network provider, so nothing else validates the notification body. Drift in *Apple's*
+ * schema is out of reach of any fake and stays a manual live-key check.
+ *
+ * Built against a REAL `apn.Notification` — exactly as the production sender does
+ * (`adapter.ts:143`) — and asserted on the wire form node-apn actually transmits: the compiled `aps`
+ * payload and the request headers. Pinning a plain-object projection instead would pin a shape the SDK
+ * never serializes, which is precisely the drift these tests exist to catch.
+ *
+ * Reference (aps payload): https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification
+ * Reference (background push requires apns-push-type: background + apns-priority: 5):
+ *   https://developer.apple.com/documentation/usernotifications/pushing-background-updates-to-your-app
+ *
+ * Written as exact `toEqual` fixtures rather than snapshots: a snapshot would re-record drift on
+ * `--updateSnapshot` instead of failing.
+ */
+const TOPIC = 'com.example.app'
+
+function payload(overrides: Partial<PushEnvelope> = {}): PushEnvelope & { topic: string } {
+  return {
+    topic: TOPIC,
+    title: 'Order shipped',
+    body: 'Your order #42 is on its way',
+    data: { type: 'orders.shipped', notificationId: 'n1' },
+    options: {},
+    silent: false,
+    ...overrides,
+  }
+}
+
+type CompiledNotification = { headers: Record<string, unknown>; aps: Record<string, unknown> }
+
+function build(envelope: PushEnvelope & { topic: string }): CompiledNotification {
+  const note = buildApnsNotification(new apn.Notification(), envelope) as unknown as {
+    headers(): Record<string, unknown>
+    compile(): string
+  }
+  return { headers: note.headers(), aps: JSON.parse(note.compile()) as Record<string, unknown> }
+}
+
+describe('buildApnsNotification — golden payloads', () => {
+  it('visible notification compiles to the reference aps payload', () => {
+    const { headers, aps } = build(payload())
+    // The envelope's custom `data` is carried as top-level keys beside `aps` on every branch, visible
+    // or silent — the app reads them from the notification's userInfo.
+    expect(aps).toEqual({
+      type: 'orders.shipped',
+      notificationId: 'n1',
+      aps: {
+        alert: { title: 'Order shipped', body: 'Your order #42 is on its way' },
+        sound: 'default',
+      },
+    })
+    expect(headers).toEqual({ 'apns-priority': 10, 'apns-topic': TOPIC })
+  })
+
+  it('silent notification is a content-available background push at priority 5', () => {
+    const { headers, aps } = build(payload({ silent: true }))
+    // Data-only: the custom keys sit beside `aps`, and no alert/sound is present.
+    expect(aps).toEqual({
+      type: 'orders.shipped',
+      notificationId: 'n1',
+      aps: { 'content-available': 1 },
+    })
+    expect(headers).toEqual({
+      'apns-priority': 5,
+      'apns-topic': TOPIC,
+      'apns-push-type': 'background',
+    })
+  })
+
+  it('full pushOptions map onto the aps payload', () => {
+    const { headers, aps } = build(
+      payload({
+        options: {
+          sound: 'chime.caf',
+          badge: 7,
+          priority: 'normal',
+          body: 'Overridden push body',
+        },
+      }),
+    )
+    expect(aps).toEqual({
+      type: 'orders.shipped',
+      notificationId: 'n1',
+      aps: {
+        alert: { title: 'Order shipped', body: 'Overridden push body' },
+        sound: 'chime.caf',
+        badge: 7,
+      },
+    })
+    expect(headers).toEqual({ 'apns-priority': 5, 'apns-topic': TOPIC })
+  })
+})

package/src/modules/channel_apns/lib/adapter.ts

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto'
+import type {
+  SendMessageInput,
+  SendMessageResult,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  BasePushChannelAdapter,
+  deviceUnregisteredResult,
+  MISSING_PUSH_TOKEN_RESULT,
+  readPushToken,
+} from '@open-mercato/core/modules/communication_channels/lib/push-adapter'
+import { createRefCountedClientCache } from '@open-mercato/core/modules/communication_channels/lib/refcounted-client-cache'
+import { readPushEnvelope, resolvePushBody, type PushEnvelope } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import {
+  apnsCredentialsSchema,
+  resolveApnsCredentials,
+  type ApnsResolvedCredentials,
+} from './credentials'
+
+/**
+ * The ONLY APNs signal that a device token is permanently dead: HTTP 410 with reason `Unregistered`
+ * (the two always travel together — 410 is Apple's irrecoverable "remove this token" status). A bare
+ * `410` status whose reason node-apn could not parse means the same thing, so it is included. Both map
+ * to the uniform `device_unregistered` sentinel so the push worker soft-deletes the device (identical
+ * contract across fcm/apns/expo).
+ *
+ * `BadDeviceToken` is deliberately EXCLUDED. Apple returns it for a VALID token presented to the wrong
+ * environment (a production token hitting the sandbox host, or vice-versa — and `production` defaults
+ * to false), not only for a malformed token, and APNs gives no code to disambiguate the two. Treating
+ * it as permanent would soft-delete every live iOS device in a tenant on a single environment
+ * misconfiguration, with no recovery path. It — like the other non-410 reasons (`DeviceTokenNotForTopic`,
+ * `TopicDisallowed`, `PayloadTooLarge`, `TooManyRequests`, `InternalServerError`, `ServiceUnavailable`,
+ * `ExpiredProviderToken`) — is a transient/config failure: the delivery retries then expires, but the
+ * device is KEPT so it recovers once the sender-side config is fixed.
+ */
+const PERMANENT_APNS_REASONS = new Set(['Unregistered', '410'])
+
+export interface ApnsSendOutcome {
+  ok: boolean
+  /** Provider rejection reason (e.g. `Unregistered`, `BadDeviceToken`), or the stringified HTTP status
+   * (e.g. `410`) when node-apn could not parse a reason from the response body. */
+  reason?: string
+  /** Transport-level error message (network/auth), distinct from a provider rejection. */
+  error?: string
+}
+
+/**
+ * A bound APNs sender for one tenant's credentials. The seam keeps `@parse/node-apn`
+ * (and its HTTP/2 provider) entirely out of the adapter's control flow and tests.
+ */
+export type ApnsSender = (payload: PushEnvelope & { topic: string }, token: string) => Promise<ApnsSendOutcome>
+
+export type ApnsSenderFactory = (credentials: ApnsResolvedCredentials) => ApnsSender
+
+let senderFactory: ApnsSenderFactory | null = null
+
+/** Test-only seam to swap the APNs sender factory. */
+export function setApnsSenderFactory(factory: ApnsSenderFactory | null): void {
+  senderFactory = factory
+}
+
+type ApnsProviderLike = {
+  send(notification: unknown, token: string): Promise<{
+    sent?: Array<{ device: string }>
+    failed?: Array<{ device: string; status?: string | number; error?: Error; response?: { reason?: string } }>
+  }>
+  /** node-apn's Provider exposes `shutdown()` to close its HTTP/2 socket to Apple. */
+  shutdown?(): void
+}
+
+function credentialsHash(credentials: ApnsResolvedCredentials): string {
+  return createHash('sha256')
+    .update(`${credentials.keyId}:${credentials.teamId}:${credentials.bundleId}:${credentials.production}:${credentials.p8Key}`)
+    .digest('hex')
+    .slice(0, 16)
+}
+
+/**
+ * Bounds the number of live HTTP/2 providers cached at once. Each entry holds an
+ * open socket to Apple, so an unbounded cache would leak a connection every time a
+ * tenant rotates their `.p8` key or toggles `production` (the hash changes → a new
+ * entry, while the stale provider never shuts down). LRU-evicting the least-recently
+ * used provider and calling `shutdown()` keeps the connection count bounded. Disposal
+ * is fenced on in-flight sends: an evicted provider is shut down only once its last
+ * concurrent `send` releases (see refcounted-client-cache), so eviction never closes
+ * the HTTP/2 socket out from under a send.
+ */
+const PROVIDER_CACHE_MAX = 32
+const providerCache = createRefCountedClientCache<ApnsProviderLike>({
+  max: PROVIDER_CACHE_MAX,
+  dispose: (provider) => {
+    try {
+      provider.shutdown?.()
+    } catch {
+      // shutdown is best-effort; a throwing/absent shutdown must not break eviction.
+    }
+  },
+})
+
+async function createProvider(credentials: ApnsResolvedCredentials): Promise<ApnsProviderLike> {
+  const apnModule = await import('@parse/node-apn')
+  const apn = (apnModule as { default?: unknown }).default ?? apnModule
+  const Provider = (apn as { Provider: new (options: unknown) => ApnsProviderLike }).Provider
+  return new Provider({
+    token: { key: credentials.p8Key, keyId: credentials.keyId, teamId: credentials.teamId },
+    production: credentials.production,
+  })
+}
+
+/**
+ * Populate an APNs `Notification` from the push envelope, branching on `silent` (background
+ * content-available wake-up — no alert/sound) and applying the recognized push options. Mutates and
+ * returns `note`. Extracted from the sender so it is unit-testable without `@parse/node-apn`.
+ */
+export function buildApnsNotification(
+  note: Record<string, unknown>,
+  payload: PushEnvelope & { topic: string },
+): Record<string, unknown> {
+  const { options, silent } = payload
+  note.topic = payload.topic
+  note.payload = payload.data
+  if (silent) {
+    note.contentAvailable = 1
+    note.pushType = 'background'
+    note.priority = 5
+  } else {
+    note.alert = { title: payload.title, body: resolvePushBody(payload) }
+    note.sound = options.sound ?? 'default'
+    if (typeof options.badge === 'number') note.badge = options.badge
+    if (options.priority === 'normal') note.priority = 5
+  }
+  return note
+}
+
+function defaultSenderFactory(credentials: ApnsResolvedCredentials): ApnsSender {
+  return async (payload, token) => {
+    const apnModule = await import('@parse/node-apn')
+    const apn = (apnModule as { default?: unknown }).default ?? apnModule
+    const Notification = (apn as { Notification: new () => Record<string, unknown> }).Notification
+    const note = buildApnsNotification(new Notification(), payload)
+
+    // Borrow a cached provider for the duration of the send; release() in finally keeps an evicted
+    // provider's socket open until this send completes.
+    const lease = await providerCache.acquire(credentialsHash(credentials), () => createProvider(credentials))
+    try {
+      const result = await lease.client.send(note, token)
+      if (result.sent && result.sent.length > 0) return { ok: true }
+      const failure = result.failed?.[0]
+      if (!failure) return { ok: false, error: 'no_response' }
+      if (failure.error) return { ok: false, error: failure.error.message }
+      const reason = failure.response?.reason ?? (failure.status != null ? String(failure.status) : undefined)
+      return { ok: false, reason }
+    } finally {
+      lease.release()
+    }
+  }
+}
+
+class ApnsChannelAdapter extends BasePushChannelAdapter {
+  readonly providerKey = 'apns'
+  protected readonly credentialsSchema = apnsCredentialsSchema
+
+  async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
+    const token = readPushToken(input)
+    if (!token) return MISSING_PUSH_TOKEN_RESULT
+
+    const parsedCredentials = apnsCredentialsSchema.safeParse(input.credentials)
+    if (!parsedCredentials.success) {
+      return { externalMessageId: '', status: 'failed', error: 'invalid_apns_credentials' }
+    }
+
+    const credentials = resolveApnsCredentials(parsedCredentials.data)
+    const envelope = readPushEnvelope(input.content)
+    const sender = (senderFactory ?? defaultSenderFactory)(credentials)
+
+    try {
+      const outcome = await sender({ ...envelope, topic: credentials.bundleId }, token)
+      if (outcome.ok) {
+        // node-apn returns no provider message id. Return an empty id rather than any slice of the
+        // push token — the worker persists externalMessageId into the admin-exposed provider_response,
+        // and this module only ever surfaces the last-8 via token_snapshot, never raw token material.
+        return { externalMessageId: '', status: 'sent' }
+      }
+      if (outcome.reason && PERMANENT_APNS_REASONS.has(outcome.reason)) {
+        return deviceUnregisteredResult({ reason: outcome.reason })
+      }
+      return { externalMessageId: '', status: 'failed', error: outcome.error ?? outcome.reason ?? 'apns_send_failed' }
+    } catch (err) {
+      return { externalMessageId: '', status: 'failed', error: err instanceof Error ? err.message : String(err) }
+    }
+  }
+}
+
+let cachedAdapter: ApnsChannelAdapter | null = null
+
+export function getApnsChannelAdapter(): ApnsChannelAdapter {
+  if (!cachedAdapter) cachedAdapter = new ApnsChannelAdapter()
+  return cachedAdapter
+}

package/src/modules/channel_apns/lib/credentials.ts

@@ -0,0 +1,88 @@
+import { createPrivateKey } from 'node:crypto'
+import { z } from 'zod'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import {
+  PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID,
+  PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID,
+  PUSH_CREDENTIAL_ERROR_INVALID_P8,
+  PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID,
+  PUSH_CREDENTIAL_ERROR_REQUIRED,
+} from '@open-mercato/core/modules/communication_channels/lib/push-credential-errors'
+
+/** Apple issues both Key IDs and Team IDs as exactly 10 alphanumeric characters. */
+const APPLE_TEN_CHAR_ID = /^[A-Za-z0-9]{10}$/
+/** Reverse-DNS app identifier, e.g. `com.example.app`; also the APNs `topic`. */
+const BUNDLE_ID = /^[A-Za-z0-9][A-Za-z0-9-]*(\.[A-Za-z0-9][A-Za-z0-9-]*)+$/
+
+/**
+ * Structurally verify Apple's `.p8` signing key without contacting APNs.
+ * `createPrivateKey` parses the PEM and rejects anything that is not a readable
+ * private key, which is what makes a pasted-by-mistake string fail at connect
+ * time instead of silently producing a channel that can never deliver.
+ *
+ * This proves the key is well-formed, NOT that Apple accepts it — a
+ * syntactically valid key from the wrong developer account still connects. Live
+ * verification is tracked separately.
+ */
+function isParseablePrivateKey(value: string): boolean {
+  try {
+    createPrivateKey(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Tenant-level APNs credentials persisted on `IntegrationCredentials` for provider
+ * `channel_apns`. Token-based auth (Apple's `.p8` key) — `p8Key` is the PEM
+ * contents (stored encrypted at rest), `keyId`/`teamId` identify the key, and
+ * `bundleId` is the app's APNs `topic`. `production` selects the APNs host
+ * (sandbox by default).
+ */
+export const apnsCredentialsSchema = z
+  .object({
+    p8Key: z
+      .string()
+      .min(1, PUSH_CREDENTIAL_ERROR_REQUIRED)
+      .refine(isParseablePrivateKey, PUSH_CREDENTIAL_ERROR_INVALID_P8),
+    keyId: z
+      .string()
+      .min(1, PUSH_CREDENTIAL_ERROR_REQUIRED)
+      .regex(APPLE_TEN_CHAR_ID, PUSH_CREDENTIAL_ERROR_INVALID_KEY_ID),
+    teamId: z
+      .string()
+      .min(1, PUSH_CREDENTIAL_ERROR_REQUIRED)
+      .regex(APPLE_TEN_CHAR_ID, PUSH_CREDENTIAL_ERROR_INVALID_TEAM_ID),
+    bundleId: z
+      .string()
+      .min(1, PUSH_CREDENTIAL_ERROR_REQUIRED)
+      .regex(BUNDLE_ID, PUSH_CREDENTIAL_ERROR_INVALID_BUNDLE_ID),
+    production: z.union([z.boolean(), z.string()]).optional(),
+  })
+  .passthrough()
+
+export type ApnsCredentials = z.infer<typeof apnsCredentialsSchema>
+
+export interface ApnsResolvedCredentials {
+  p8Key: string
+  keyId: string
+  teamId: string
+  bundleId: string
+  production: boolean
+}
+
+/** Resolve validated credentials into the strongly-typed send config (parsing the production flag). */
+export function resolveApnsCredentials(credentials: ApnsCredentials): ApnsResolvedCredentials {
+  const production =
+    typeof credentials.production === 'boolean'
+      ? credentials.production
+      : parseBooleanWithDefault(credentials.production, false)
+  return {
+    p8Key: credentials.p8Key,
+    keyId: credentials.keyId,
+    teamId: credentials.teamId,
+    bundleId: credentials.bundleId,
+    production,
+  }
+}

package/src/modules/channel_apns/lib/fake-provider.ts

@@ -0,0 +1,54 @@
+import {
+  isPushFakeProvidersEnabled,
+  recordFakePush,
+  warnPushFakeProvidersActive,
+} from '@open-mercato/core/modules/push_notifications/lib/fake-provider-recorder'
+import { buildApnsNotification, setApnsSenderFactory } from './adapter'
+
+/**
+ * Network-free `@parse/node-apn` sender used ONLY by integration tests.
+ *
+ * Swaps the SDK client behind the adapter's existing seam, so the real adapter still runs its
+ * credential resolution and its `Unregistered`/`410` → `device_unregistered` mapping. The adapter
+ * itself is never replaced or re-registered.
+ *
+ * Unlike FCM and Expo, the APNs seam sits *above* the message builder: the sender receives the raw
+ * envelope, and `buildApnsNotification(new Notification(), …)` runs inside the real sender factory this
+ * fake replaces. The fake therefore builds against a **real `apn.Notification`** too, and records the
+ * wire form node-apn would transmit (`headers()` + the compiled `aps` payload) rather than a plain-object
+ * projection the SDK never serializes. Only the network provider is faked. `.p8` parsing lives in the
+ * replaced factory, so fake credentials need only a valid shape.
+ *
+ * Token sentinels match `push_stub`'s convention (see push-stub-adapter.ts):
+ *   - token containing `unregistered` → APNs' native permanent-token reason
+ *   - token containing `fail`         → a retryable error
+ *   - otherwise                        → success
+ *
+ * Production safety: never installed at module import; no-op unless `OM_PUSH_FAKE_PROVIDERS` is set.
+ */
+type ApnsNotificationLike = Record<string, unknown> & {
+  headers(): Record<string, unknown>
+  compile(): string
+}
+
+async function newApnsNotification(): Promise<ApnsNotificationLike> {
+  const apnModule = await import('@parse/node-apn')
+  const apn = (apnModule as { default?: unknown }).default ?? apnModule
+  const Notification = (apn as { Notification: new () => ApnsNotificationLike }).Notification
+  return new Notification()
+}
+
+export function ensureApnsFakeProviderInstalled(): void {
+  if (!isPushFakeProvidersEnabled()) return
+  warnPushFakeProvidersActive('apns')
+  setApnsSenderFactory(() => async (payload, token) => {
+    const note = buildApnsNotification(await newApnsNotification(), payload) as ApnsNotificationLike
+    recordFakePush('apns', token, {
+      headers: note.headers(),
+      payload: JSON.parse(note.compile()) as Record<string, unknown>,
+    })
+    if (token.includes('unregistered')) return { ok: false, reason: 'Unregistered' }
+    if (token.includes('fail')) return { ok: false, error: 'fake apns transient failure' }
+    return { ok: true }
+  })
+}

package/src/modules/channel_apns/lib/health.ts

@@ -0,0 +1,13 @@
+import { makePushClientConfigHealthCheck } from '@open-mercato/core/modules/push_notifications/lib/push-health'
+import { apnsCredentialsSchema } from './credentials'
+
+/**
+ * Liveness probe for the APNs integration. The hub passes the tenant-scoped
+ * credentials (.p8 key + key/team/bundle ids), so the probe confirms they are
+ * present and well-formed — no network call. Per-device token validity surfaces
+ * on delivery (`device_unregistered` soft-deletes).
+ */
+export const channelApnsHealthCheck = makePushClientConfigHealthCheck({
+  schema: apnsCredentialsSchema,
+  providerLabel: 'APNs',
+})

package/src/modules/channel_apns/setup.ts

@@ -0,0 +1,31 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import {
+  hasChannelAdapter,
+  registerChannelAdapter,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter-registry-singleton'
+import { getApnsChannelAdapter } from './lib/adapter'
+
+/**
+ * Register the APNs `ChannelAdapter` once per process at import time. Guarded with
+ * `hasChannelAdapter` to silence the duplicate error on dev-mode HMR + repeated
+ * test imports. Provider credentials (.p8 key + ids) are persisted per tenant via
+ * the standard `IntegrationCredentials` flow for the `channel_apns` provider.
+ */
+function ensureApnsAdapterRegistered(): void {
+  if (hasChannelAdapter('apns')) return
+  registerChannelAdapter(getApnsChannelAdapter())
+}
+
+ensureApnsAdapterRegistered()
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    superadmin: ['channel_apns.view', 'channel_apns.configure'],
+    admin: ['channel_apns.view', 'channel_apns.configure'],
+  },
+  async onTenantCreated() {
+    ensureApnsAdapterRegistered()
+  },
+}
+
+export default setup