Add direct-APNs sender for WidgetKit push subscriptions

functions/index.js

@@ -8,6 +8,7 @@ initializeApp();
 
 const android = require('./android');
 const legacy = require('./legacy');
+const widgetPush = require('./widget-push');
 
 const region = (functions.config().app && functions.config().app.region) || 'us-central1';
 const regionalFunctions = functions.region(region).runWith({ timeoutSeconds: 10 });
@@ -22,9 +23,17 @@ exports.androidV1 = regionalFunctions.https.onRequest(async (req, res) =>
   handleRequest(req, res, android.createPayload),
 );
 
-exports.sendPushNotification = regionalFunctions.https.onRequest(async (req, res) =>
-  handleRequest(req, res, legacy.createPayload),
-);
+exports.sendPushNotification = functions
+  .region(region)
+  .runWith({ timeoutSeconds: 10, secrets: widgetPush.SECRETS })
+  .https.onRequest(async (req, res) => {
+    // Widget push_subscription payloads target a WidgetKit push token, which FCM
+    // can't route — send those straight to APNs instead of through messaging.send.
+    if (req.body && req.body.push_subscription) {
+      return widgetPush.sendWidgetPush(req, res);
+    }
+    return handleRequest(req, res, legacy.createPayload);
+  });
 
 exports.checkRateLimits = regionalFunctions.https.onRequest(async (req, res) =>
   handleCheckRateLimits(req, res),

functions/test/widget-push.test.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const crypto = require('crypto');
+const { createMockRequest, createMockResponse } = require('./utils/mock-factories');
+
+jest.mock('node:http2', () => ({ connect: jest.fn() }));
+const http2 = require('node:http2');
+
+const widgetPush = require('../widget-push');
+
+const WIDGET_TOKEN = '80f7d67347204c7dda85d331a95ec31c1e3c62b9173836ada8ed9abf';
+
+// A real P-256 key so ES256 signing succeeds; its value is irrelevant to the mock.
+const TEST_P8 = crypto
+  .generateKeyPairSync('ec', { namedCurve: 'P-256' })
+  .privateKey.export({ type: 'pkcs8', format: 'pem' });
+
+// Makes http2.connect return a client whose request replays the given APNs
+// responses in order (one per connect call, so we can exercise the fallback).
+function mockApns(responses, onRequest) {
+  let index = 0;
+  http2.connect.mockImplementation(() => {
+    const response = responses[Math.min(index, responses.length - 1)];
+    index += 1;
+    const handlers = {};
+    const request = {
+      on: jest.fn((event, cb) => {
+        handlers[event] = cb;
+        return request;
+      }),
+      setEncoding: jest.fn(),
+      end: jest.fn(() => {
+        process.nextTick(() => {
+          handlers.response?.({ ':status': response.status, 'apns-id': response.apnsId });
+          if (response.body) handlers.data?.(response.body);
+          handlers.end?.();
+        });
+      }),
+    };
+    return {
+      on: jest.fn(),
+      request: jest.fn((headers) => {
+        onRequest?.(headers);
+        return request;
+      }),
+      close: jest.fn(),
+    };
+  });
+}
+
+function widgetRequest(overrides = {}) {
+  return createMockRequest({
+    body: {
+      push_subscription: { subscription_id: 'ios-widget-sensors', target: 'sensors' },
+      push_token: WIDGET_TOKEN,
+      registration_info: { app_id: 'io.test.HomeAssistant' },
+      ...overrides,
+    },
+  });
+}
+
+describe('widget-push', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env.APNS_KEY_P8 = TEST_P8;
+    process.env.APNS_KEY_ID = 'KEY1234567';
+    process.env.APNS_TEAM_ID = 'TEAM123456';
+  });
+
+  it('returns 201 and echoes the apns-id on a successful send', async () => {
+    mockApns([{ status: 200, apnsId: 'apns-success' }]);
+    const res = createMockResponse();
+
+    await widgetPush.sendWidgetPush(widgetRequest(), res);
+
+    expect(res.status).toHaveBeenCalledWith(201);
+    expect(res.send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        target: WIDGET_TOKEN,
+        messageId: 'apns-success',
+        pushType: 'widgets',
+      }),
+    );
+  });
+
+  it('sends the widgets push type, widget topic and device path', async () => {
+    let headers;
+    mockApns([{ status: 200, apnsId: 'x' }], (h) => {
+      headers = h;
+    });
+
+    await widgetPush.sendWidgetPush(widgetRequest(), createMockResponse());
+
+    expect(headers['apns-push-type']).toBe('widgets');
+    expect(headers['apns-topic']).toBe('io.test.HomeAssistant.push-type.widgets');
+    expect(headers[':path']).toBe(`/3/device/${WIDGET_TOKEN}`);
+    expect(headers.authorization).toMatch(/^bearer /);
+  });
+
+  it('falls back to the sandbox host on BadDeviceToken', async () => {
+    mockApns([
+      { status: 400, body: '{"reason":"BadDeviceToken"}' },
+      { status: 200, apnsId: 'sandbox-ok' },
+    ]);
+    const res = createMockResponse();
+
+    await widgetPush.sendWidgetPush(widgetRequest(), res);
+
+    expect(http2.connect).toHaveBeenCalledTimes(2);
+    expect(http2.connect).toHaveBeenNthCalledWith(1, 'https://api.push.apple.com');
+    expect(http2.connect).toHaveBeenNthCalledWith(2, 'https://api.sandbox.push.apple.com');
+    expect(res.status).toHaveBeenCalledWith(201);
+  });
+
+  it('returns 403 when no token is sent', async () => {
+    const res = createMockResponse();
+    await widgetPush.sendWidgetPush(widgetRequest({ push_token: null }), res);
+    expect(res.status).toHaveBeenCalledWith(403);
+  });
+
+  it('returns 400 when registration_info.app_id is missing', async () => {
+    const res = createMockResponse();
+    await widgetPush.sendWidgetPush(widgetRequest({ registration_info: {} }), res);
+    expect(res.status).toHaveBeenCalledWith(400);
+  });
+
+  it('returns 500 when APNs credentials are not configured', async () => {
+    delete process.env.APNS_KEY_P8;
+    const res = createMockResponse();
+    await widgetPush.sendWidgetPush(widgetRequest(), res);
+    expect(res.status).toHaveBeenCalledWith(500);
+  });
+
+  it('propagates a non-fallback APNs rejection status', async () => {
+    mockApns([{ status: 410, body: '{"reason":"Unregistered"}' }]);
+    const res = createMockResponse();
+    await widgetPush.sendWidgetPush(widgetRequest(), res);
+    expect(res.status).toHaveBeenCalledWith(410);
+  });
+});

functions/widget-push.js

@@ -0,0 +1,173 @@
+'use strict';
+
+// Direct-to-APNs sender for iOS 26 WidgetKit push subscriptions.
+//
+// Core registers a widget's push token + tracked entities and, when one of those
+// entities changes, POSTs a { push_subscription, push_token, registration_info }
+// payload to this relay (the same push_url as normal notifications).
+//
+// The push_token here is a WidgetKit widget push token — a raw APNs token that
+// FCM has no mapping for, so messaging.send() can't deliver it. This module
+// bypasses the FCM SDK for this one path and talks to APNs directly over HTTP/2,
+// authenticating with the APNs auth key (.p8) provided as a Functions secret.
+
+const http2 = require('node:http2');
+const crypto = require('node:crypto');
+
+// Xcode/dev builds get sandbox tokens; App Store / TestFlight get production ones.
+// The token itself doesn't say which, so we try production and fall back to
+// sandbox when APNs replies BadDeviceToken (wrong environment).
+const APNS_HOST_PRODUCTION = 'api.push.apple.com';
+const APNS_HOST_SANDBOX = 'api.sandbox.push.apple.com';
+
+// iOS 26 WidgetKit push: apns-push-type is "widgets" and the topic is the app's
+// bundle id with a ".push-type.widgets" suffix.
+const APNS_PUSH_TYPE = 'widgets';
+const WIDGET_TOPIC_SUFFIX = '.push-type.widgets';
+
+// Provider JWTs are valid up to 1 hour and APNs rate-limits token creation, so we
+// sign once and reuse well within the window.
+const JWT_TTL_MS = 40 * 60 * 1000;
+
+// Secret Manager names, injected as env vars at runtime via defineSecret/runWith.
+const SECRETS = ['APNS_KEY_P8', 'APNS_KEY_ID', 'APNS_TEAM_ID'];
+
+let cachedJwt = null;
+let cachedJwtAt = 0;
+
+function base64url(value) {
+  return Buffer.from(value)
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+}
+
+// Builds an APNs provider-auth JWT signed with the .p8 key (ES256). The private
+// key never leaves the function; only this signature travels to Apple.
+function signProviderToken() {
+  const header = base64url(JSON.stringify({ alg: 'ES256', kid: process.env.APNS_KEY_ID }));
+  const payload = base64url(
+    JSON.stringify({ iss: process.env.APNS_TEAM_ID, iat: Math.floor(Date.now() / 1000) }),
+  );
+  const signingInput = `${header}.${payload}`;
+
+  // dsaEncoding 'ieee-p1363' yields the raw R||S signature that JWS/ES256 expects
+  // (Node's default is DER, which APNs would reject).
+  const signature = crypto
+    .sign('sha256', Buffer.from(signingInput), {
+      key: process.env.APNS_KEY_P8,
+      dsaEncoding: 'ieee-p1363',
+    })
+    .toString('base64')
+    .replace(/=/g, '')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_');
+
+  return `${signingInput}.${signature}`;
+}
+
+function providerToken() {
+  const now = Date.now();
+  if (!cachedJwt || now - cachedJwtAt > JWT_TTL_MS) {
+    cachedJwt = signProviderToken();
+    cachedJwtAt = now;
+  }
+  return cachedJwt;
+}
+
+// Sends one request to APNs over HTTP/2 and resolves with { status, apnsId, body }.
+function postToApns(host, deviceToken, headers, body) {
+  return new Promise((resolve, reject) => {
+    const client = http2.connect(`https://${host}`);
+    client.on('error', reject);
+
+    const request = client.request({
+      ':method': 'POST',
+      ':path': `/3/device/${deviceToken}`,
+      ...headers,
+    });
+
+    let status;
+    let apnsId;
+    let data = '';
+    request.on('response', (responseHeaders) => {
+      status = responseHeaders[':status'];
+      apnsId = responseHeaders['apns-id'];
+    });
+    request.setEncoding('utf8');
+    request.on('data', (chunk) => {
+      data += chunk;
+    });
+    request.on('end', () => {
+      client.close();
+      resolve({ status, apnsId, body: data });
+    });
+    request.on('error', (err) => {
+      client.close();
+      reject(err);
+    });
+
+    request.end(body);
+  });
+}
+
+// Handles a widget push_subscription payload by sending a silent WidgetKit
+// refresh straight to APNs.
+async function sendWidgetPush(req, res) {
+  const token = req.body.push_token;
+  const appId = req.body.registration_info && req.body.registration_info.app_id;
+
+  if (!token) {
+    return res.status(403).send({ errorMessage: 'You did not send a token!' });
+  }
+  if (!appId) {
+    return res.status(400).send({ errorMessage: 'Missing registration_info.app_id' });
+  }
+  if (!process.env.APNS_KEY_P8 || !process.env.APNS_KEY_ID || !process.env.APNS_TEAM_ID) {
+    return res.status(500).send({ errorMessage: 'APNs credentials are not configured' });
+  }
+
+  const headers = {
+    'apns-topic': `${appId}${WIDGET_TOPIC_SUFFIX}`,
+    'apns-push-type': APNS_PUSH_TYPE,
+    'apns-priority': '5',
+  };
+  // Silent and data-free: WidgetKit just reloads the widget's timeline.
+  const body = JSON.stringify({ aps: { 'content-changed': true } });
+
+  let result;
+  try {
+    result = await postToApns(
+      APNS_HOST_PRODUCTION,
+      token,
+      { ...headers, authorization: `bearer ${providerToken()}` },
+      body,
+    );
+
+    if (result.status === 400 && result.body.includes('BadDeviceToken')) {
+      result = await postToApns(
+        APNS_HOST_SANDBOX,
+        token,
+        { ...headers, authorization: `bearer ${providerToken()}` },
+        body,
+      );
+    }
+  } catch (err) {
+    return res.status(502).send({ errorMessage: `Failed to reach APNs: ${err.message}` });
+  }
+
+  if (result.status === 200) {
+    return res.status(201).send({
+      target: token,
+      messageId: result.apnsId,
+      pushType: APNS_PUSH_TYPE,
+    });
+  }
+
+  return res.status(result.status || 502).send({
+    errorMessage: `APNs rejected the widget push: ${result.body || 'unknown error'}`,
+  });
+}
+
+module.exports = { sendWidgetPush, SECRETS };