Backend v2 foundations

package.json

@@ -36,7 +36,7 @@
     "@opentelemetry/instrumentation-http": "^0.200.0",
     "@opentelemetry/instrumentation-pino": "^0.47.0",
     "@opentelemetry/sdk-node": "^0.200.0",
-    "@prisma/client": "^6.12.0",
+    "@prisma/client": "^6.17.0",
     "@prisma/instrumentation": "^6.7.0",
     "@turnkey/sdk-server": "^3.0.1",
     "@xmtp/node-sdk": "^2.0.8",
@@ -58,8 +58,7 @@
     "uint8array-extras": "^1.4.0",
     "uuid": "^11.0.5",
     "viem": "^2.23.2",
-    "zod": "^3.24.1",
-    "zod-prisma-types": "^3.2.4"
+    "zod": "^3.24.1"
   },
   "devDependencies": {
     "@bufbuild/buf": "^1.50.0",
@@ -79,10 +78,10 @@
     "globals": "^15.14.0",
     "prettier": "^3.4.2",
     "prettier-plugin-packagejson": "^2.5.7",
-    "prisma": "^6.12.0",
+    "prisma": "^6.17.0",
     "rimraf": "^6.0.1",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.20.0"
-  },
-  "packageManager": "yarn@4.6.0+sha512.5383cc12567a95f1d668fbe762dfe0075c595b4bfff433be478dbbe24e05251a8e8c3eb992a986667c1d53b6c3a9c85b8398c35a960587fbd9fa3a0915406728"
+    "typescript-eslint": "^8.20.0",
+    "zod-prisma-types": "^3.2.4"
+  }
 }

prisma/migrations/20251003172324_add_v2_push_notification_models/migration.sql

@@ -0,0 +1,37 @@
+-- CreateTable
+CREATE TABLE "DeviceRegistration" (
+    "deviceId" TEXT NOT NULL,
+    "pushToken" TEXT NOT NULL,
+    "pushTokenType" "PushTokenType" NOT NULL DEFAULT 'apns',
+    "apnsEnv" "ApnsEnvironment",
+    "pushFailures" INTEGER NOT NULL DEFAULT 0,
+    "disabled" BOOLEAN NOT NULL DEFAULT false,
+    "addedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "lastSentAt" TIMESTAMP(3),
+    "lastFailureAt" TIMESTAMP(3),
+
+    CONSTRAINT "DeviceRegistration_pkey" PRIMARY KEY ("deviceId")
+);
+
+-- CreateTable
+CREATE TABLE "ClientIdentifier" (
+    "id" TEXT NOT NULL,
+    "deviceId" TEXT NOT NULL,
+    "addedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ClientIdentifier_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "DeviceRegistration_pushToken_idx" ON "DeviceRegistration"("pushToken");
+
+-- CreateIndex
+CREATE INDEX "DeviceRegistration_disabled_pushFailures_idx" ON "DeviceRegistration"("disabled", "pushFailures");
+
+-- CreateIndex
+CREATE INDEX "ClientIdentifier_deviceId_idx" ON "ClientIdentifier"("deviceId");
+
+-- AddForeignKey
+ALTER TABLE "ClientIdentifier" ADD CONSTRAINT "ClientIdentifier_deviceId_fkey" FOREIGN KEY ("deviceId") REFERENCES "DeviceRegistration"("deviceId") ON DELETE CASCADE ON UPDATE CASCADE;

prisma/migrations/20251017193536_add_unique_constraint_to_push_tokens/migration.sql

@@ -0,0 +1,8 @@
+-- AlterTable: Make pushToken nullable
+ALTER TABLE "DeviceRegistration" ALTER COLUMN "pushToken" DROP NOT NULL;
+
+-- Update any empty strings to NULL (clean up existing data)
+UPDATE "DeviceRegistration" SET "pushToken" = NULL WHERE "pushToken" = '';
+
+-- CreateIndex: Add unique constraint on push token combination
+CREATE UNIQUE INDEX "DeviceRegistration_pushTokenType_apnsEnv_pushToken_key" ON "DeviceRegistration"("pushTokenType", "apnsEnv", "pushToken");

prisma/schema.prisma

@@ -24,9 +24,10 @@ enum DeviceOS {
   macos
 }
 
+// NOTE: Only APNS is supported. FCM is not supported.
 enum PushTokenType {
   apns
-  fcm
+  fcm // Not supported - kept for database compatibility only
 }
 
 enum ApnsEnvironment {
@@ -176,3 +177,32 @@ model InviteCodeRequest {
   @@index([inviteCodeId])
   @@index([requesterId])
 }
+
+// v2 Push Notification Models
+model DeviceRegistration {
+  deviceId          String             @id
+  pushToken         String?            @db.Text
+  pushTokenType     PushTokenType      @default(apns)
+  apnsEnv           ApnsEnvironment?
+  pushFailures      Int                @default(0)
+  disabled          Boolean            @default(false)
+  addedAt           DateTime           @default(now())
+  updatedAt         DateTime           @updatedAt
+  lastSentAt        DateTime?
+  lastFailureAt     DateTime?
+  clientIdentifiers ClientIdentifier[]
+
+  @@unique([pushTokenType, apnsEnv, pushToken])
+  @@index([pushToken])
+  @@index([disabled, pushFailures])
+}
+
+model ClientIdentifier {
+  id        String             @id
+  deviceId  String
+  device    DeviceRegistration @relation(fields: [deviceId], references: [deviceId], onDelete: Cascade)
+  addedAt   DateTime           @default(now())
+  updatedAt DateTime           @updatedAt
+
+  @@index([deviceId])
+}

scripts/simple-push-test.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { createApnsService } from "@/api/v1/notifications/services/apns-push.service";
+import { createApnsService } from "@/api/shared/notifications/services/apns-push.service";
 import { prisma } from "@/utils/prisma";
 
 // Simple version - just provide an XMTP ID and it will send a basic test notification

scripts/test-push-notification.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { createApnsService } from "@/api/v1/notifications/services/apns-push.service";
+import { createApnsService } from "@/api/shared/notifications/services/apns-push.service";
 import { prisma } from "@/utils/prisma";
 
 interface TestPushArgs {

src/api/shared/notifications/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Maximum number of consecutive push notification failures before disabling a device
+ */
+export const MAX_PUSH_FAILURES = 10;
+
+/**
+ * Maximum size in bytes for JWT metadata to prevent token bloat
+ */
+export const MAX_JWT_METADATA_SIZE = 1024; // 1KB

src/api/v1/notifications/services/apns-push.service.ts → src/api/shared/notifications/services/apns-push.service.ts

@@ -3,8 +3,8 @@ import type { Device } from "@prisma/client";
 import jwt from "jsonwebtoken";
 import logger from "@/utils/logger";
 import type {
+  AnyNotificationPayloadWithJWT,
   NotificationPayload,
-  NotificationPayloadWithJWTToken,
 } from "./notifications-types";
 
 export interface ApnsConfig {
@@ -75,7 +75,7 @@ export class ApnsPushService {
 
   async sendPushNotification(args: {
     device: Device;
-    notification: NotificationPayloadWithJWTToken;
+    notification: AnyNotificationPayloadWithJWT;
     isSilent?: boolean;
   }): Promise<{ success: boolean; error?: string }> {
     const { device, notification, isSilent } = args;
@@ -137,10 +137,11 @@ export class ApnsPushService {
         "content-type": "application/json",
       };
 
+      const safeHeaders = { ...headers, authorization: "[REDACTED]" };
       logger.info(
         {
           url: `https://${hostname}/3/device/${device.pushToken}`,
-          headers,
+          headers: safeHeaders,
           payload,
           deviceId: device.id,
           verbose: true,

src/api/v1/notifications/services/notifications-types.ts → src/api/shared/notifications/services/notifications-types.ts

@@ -3,7 +3,7 @@ export type NotificationType = "Protocol" | "InviteJoinRequest";
 export type ProtocolNotificationData = {
   contentTopic: string;
   messageType: string;
-  encryptedMessage: string;
+  encryptedMessage?: string;
   timestamp: string;
 };
 
@@ -36,11 +36,15 @@ export type NotificationTypeToData = {
   InviteJoinRequest: InviteJoinRequestNotificationData;
 };
 
+// Base notification payload with XOR semantics for v1/v2 transition
+// Ensures exactly one of inboxId (v1) or clientId (v2) is present
 type NotificationPayloadBase<T extends NotificationType> = {
-  inboxId: string;
   notificationType: T;
   notificationData: NotificationTypeToData[T];
-};
+} & (
+  | { inboxId: string; clientId?: never }
+  | { clientId: string; inboxId?: never }
+);
 
 // Discriminated union over notificationType
 export type NotificationPayload = {
@@ -54,3 +58,16 @@ export type NotificationPayloadFor<T extends NotificationType> =
 export type NotificationPayloadWithJWTToken = NotificationPayload & {
   apiJWT: string;
 };
+
+// V2 notification types (structurally compatible with v2 branch of NotificationPayloadWithJWTToken)
+export type V2NotificationPayload = {
+  clientId: string;
+  apiJWT: string;
+  notificationType: "Protocol";
+  notificationData: ProtocolNotificationData;
+};
+
+// Union type for push services that can handle both v1 and v2
+export type AnyNotificationPayloadWithJWT =
+  | NotificationPayloadWithJWTToken
+  | V2NotificationPayload;

src/api/v1/notifications/services/push-notification.service.ts → src/api/shared/notifications/services/push-notification.service.ts

@@ -105,6 +105,15 @@ export class PushNotificationService {
 
     const xmtpInstallationId = identityOnDevice.xmtpInstallationId;
 
+    // V1 notifications always have inboxId
+    if (!notification.inboxId) {
+      logger.error(
+        { deviceId: device.id },
+        "Missing inboxId for v1 notification",
+      );
+      return { success: false };
+    }
+
     // We add an JWT token to the notification payload to be used by the client
     // So the notification extension is able to communicate with our backend (App Attest not supported in extensions so we can't call authenticate)
     const apiJWT = await createJwtToken({
@@ -147,13 +156,13 @@ export class PushNotificationService {
         break;
 
       case "fcm":
-        logger.warn(
-          `FCM push notifications not yet implemented for device ${device.id}`,
+        logger.error(
+          `FCM push notifications are not supported. Only APNS is supported for device ${device.id}`,
         );
         return { success: false };
 
       default:
-        logger.warn(`No valid push token type for device ${device.id}`);
+        logger.warn(`Invalid push token type for device ${device.id}`);
         return { success: false };
     }