@edge-base/server 0.1.1

package/src/lib/push-provider.ts

@@ -0,0 +1,409 @@
+/**
+ * PushProvider — FCM 단일 프로바이더 (FCM 일원화,)
+ *
+ * 모든 플랫폼(iOS, Android, Web)에서 Firebase 클라이언트 SDK로 FCM Registration Token을
+ * 발급받고, 서버는 FCM HTTP v1 API로만 발송한다.
+ *
+ * Workers에서는 firebase-admin 불가 → FCM HTTP v1 REST API 직접 호출.
+ * 토픽 구독은 모바일: 클라이언트 직접, 웹: 서버 경유 FCM IID API.
+ */
+
+import type { PushConfig } from '@edge-base/shared';
+import type { Env } from '../types.js';
+
+// ─── Interfaces ───
+
+export interface PushPayload {
+  title?: string;
+  body?: string;
+  image?: string;
+  sound?: string;
+  badge?: number;
+  data?: Record<string, unknown>;
+  silent?: boolean;
+  collapseId?: string;
+  ttl?: number;
+  /** FCM-specific overrides (merged into android config) */
+  fcm?: Record<string, unknown>;
+}
+
+export interface PushSendOptions {
+  token: string;
+  platform: string;
+  payload: PushPayload;
+}
+
+export interface PushSendResult {
+  success: boolean;
+  /** true → token is invalid, should be removed from KV */
+  remove?: boolean;
+  /** true → transient error, should retry */
+  retry?: boolean;
+  error?: string;
+}
+
+// ─── FCM Provider ───
+
+export class FcmProvider {
+  private accessToken: string | null = null;
+  private tokenExpiry: number = 0;
+  private endpoints: { oauth2TokenUrl: string; fcmSendUrl: string; iidBaseUrl: string };
+
+  constructor(
+    private projectId: string,
+    private serviceAccountJson: string,
+    endpoints?: { oauth2TokenUrl?: string; fcmSendUrl?: string; iidBaseUrl?: string },
+    private useMockAccessToken: boolean = false,
+  ) {
+    this.endpoints = {
+      oauth2TokenUrl: endpoints?.oauth2TokenUrl ?? 'https://oauth2.googleapis.com/token',
+      fcmSendUrl: endpoints?.fcmSendUrl ?? `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`,
+      iidBaseUrl: endpoints?.iidBaseUrl ?? 'https://iid.googleapis.com',
+    };
+  }
+
+  async send(options: PushSendOptions): Promise<PushSendResult> {
+    const token = await this.getAccessToken();
+    if (!token) {
+      return { success: false, error: 'Failed to obtain FCM access token' };
+    }
+
+    const message = this.buildMessage(options.payload, { token: options.token });
+
+    return this.sendMessage(token, message, { canRemove: true });
+  }
+
+  /**
+   * Send to an FCM topic. Topic subscription is client-driven (mobile)
+   * or server-driven via IID API (web).
+   */
+  async sendToTopic(topic: string, payload: PushPayload): Promise<PushSendResult> {
+    const token = await this.getAccessToken();
+    if (!token) {
+      return { success: false, error: 'Failed to obtain FCM access token' };
+    }
+
+    const message = this.buildMessage(payload, { topic });
+
+    return this.sendMessage(token, message, { canRemove: false });
+  }
+
+  /**
+   * Broadcast to all devices via /topics/all.
+   * Clients auto-subscribe to 'all' topic on register.
+   */
+  async broadcast(payload: PushPayload): Promise<PushSendResult> {
+    return this.sendToTopic('all', payload);
+  }
+
+  /**
+   * Subscribe a token to an FCM topic via Instance ID API.
+   * Used for web clients (Firebase JS SDK doesn't support client-side subscribeToTopic).
+   */
+  async subscribeTokenToTopic(fcmToken: string, topic: string): Promise<{ success: boolean; error?: string }> {
+    const accessToken = await this.getAccessToken();
+    if (!accessToken) {
+      return { success: false, error: 'Failed to obtain FCM access token' };
+    }
+
+    const url = `${this.endpoints.iidBaseUrl}/iid/v1/${encodeURIComponent(fcmToken)}/rel/topics/${encodeURIComponent(topic)}`;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (resp.ok) return { success: true };
+    const text = await resp.text().catch(() => '');
+    return { success: false, error: `IID ${resp.status}: ${text}` };
+  }
+
+  /**
+   * Unsubscribe a token from an FCM topic via Instance ID API.
+   */
+  async unsubscribeTokenFromTopic(fcmToken: string, topic: string): Promise<{ success: boolean; error?: string }> {
+    const accessToken = await this.getAccessToken();
+    if (!accessToken) {
+      return { success: false, error: 'Failed to obtain FCM access token' };
+    }
+
+    const url = `${this.endpoints.iidBaseUrl}/iid/v1:batchRemove`;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        to: `/topics/${topic}`,
+        registration_tokens: [fcmToken],
+      }),
+    });
+
+    if (resp.ok) return { success: true };
+    const text = await resp.text().catch(() => '');
+    return { success: false, error: `IID ${resp.status}: ${text}` };
+  }
+
+  // ─── Private helpers ───
+
+  private buildMessage(
+    payload: PushPayload,
+    target: { token?: string; topic?: string },
+  ): Record<string, unknown> {
+    const message: Record<string, unknown> = { ...target };
+
+    // Notification payload
+    if (payload.title || payload.body) {
+      message.notification = {
+        title: payload.title,
+        body: payload.body,
+        ...(payload.image ? { image: payload.image } : {}),
+      };
+    }
+
+    // Data payload — FCM data values must be strings
+    if (payload.data) {
+      const stringData: Record<string, string> = {};
+      for (const [k, v] of Object.entries(payload.data)) {
+        stringData[k] = typeof v === 'string' ? v : JSON.stringify(v);
+      }
+      message.data = stringData;
+    }
+
+    // Android-specific
+    const androidConfig: Record<string, unknown> = {};
+    if (payload.collapseId) androidConfig.collapse_key = payload.collapseId;
+    if (payload.ttl !== undefined) androidConfig.ttl = `${payload.ttl}s`;
+    if (payload.sound || payload.image) {
+      androidConfig.notification = {
+        ...(payload.sound ? { sound: payload.sound } : {}),
+        ...(payload.image ? { image: payload.image } : {}),
+      };
+    }
+    if (payload.fcm) Object.assign(androidConfig, payload.fcm);
+    if (Object.keys(androidConfig).length > 0) message.android = androidConfig;
+
+    const aps: Record<string, unknown> = {};
+    if (payload.sound) aps.sound = payload.sound;
+    if (payload.badge !== undefined) aps.badge = payload.badge;
+    if (Object.keys(aps).length > 0) {
+      message.apns = {
+        payload: {
+          aps,
+        },
+      };
+    }
+
+    // Silent push → data-only message (no notification key)
+    if (payload.silent) {
+      delete message.notification;
+    }
+
+    return message;
+  }
+
+  private async sendMessage(
+    accessToken: string,
+    message: Record<string, unknown>,
+    opts: { canRemove: boolean },
+  ): Promise<PushSendResult> {
+    const url = this.endpoints.fcmSendUrl;
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ message }),
+    });
+
+    if (resp.ok) {
+      return { success: true };
+    }
+
+    const status = resp.status;
+    // Token invalid — should be removed (only for individual sends, not topics)
+    if (opts.canRemove && (status === 404 || status === 410)) {
+      return { success: false, remove: true, error: `FCM ${status}: token invalid` };
+    }
+    // Also check for UNREGISTERED error in response body
+    if (status === 400) {
+      try {
+        const body = await resp.json() as { error?: { details?: Array<{ errorCode?: string }> } };
+        if (opts.canRemove && body.error?.details?.some(d => d.errorCode === 'UNREGISTERED')) {
+          return { success: false, remove: true, error: 'FCM: UNREGISTERED' };
+        }
+      } catch { /* skip body parse errors */ }
+      return { success: false, error: `FCM ${status}: bad request` };
+    }
+    // Transient errors — should retry
+    if (status === 429 || status === 503) {
+      return { success: false, retry: true, error: `FCM ${status}: transient error` };
+    }
+    // Auth errors
+    if (status === 401 || status === 403) {
+      this.accessToken = null; // Force token refresh
+      return { success: false, error: `FCM ${status}: authentication error` };
+    }
+
+    return { success: false, error: `FCM ${status}: unexpected error` };
+  }
+
+  /**
+   * Get a cached or fresh OAuth2 access token.
+   * FCM v1 requires: Service Account JWT (RS256) → Google OAuth2 token exchange.
+   */
+  private async getAccessToken(): Promise<string | null> {
+    if (this.accessToken && Date.now() < this.tokenExpiry) {
+      return this.accessToken;
+    }
+
+    if (this.useMockAccessToken) {
+      this.accessToken = 'mock-access-token';
+      this.tokenExpiry = Date.now() + 55 * 60 * 1000;
+      return this.accessToken;
+    }
+
+    try {
+      const sa = JSON.parse(this.serviceAccountJson) as {
+        client_email: string;
+        private_key: string;
+      };
+
+      // Import RS256 private key
+      const pemContent = sa.private_key
+        .replace(/-----BEGIN PRIVATE KEY-----/g, '')
+        .replace(/-----END PRIVATE KEY-----/g, '')
+        .replace(/\n/g, '');
+      const keyData = Uint8Array.from(atob(pemContent), c => c.charCodeAt(0));
+
+      const privateKey = await crypto.subtle.importKey(
+        'pkcs8',
+        keyData,
+        { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+        false,
+        ['sign'],
+      );
+
+      // Create JWT
+      const now = Math.floor(Date.now() / 1000);
+      const header = { alg: 'RS256', typ: 'JWT' };
+      const claimSet = {
+        iss: sa.client_email,
+        scope: 'https://www.googleapis.com/auth/firebase.messaging',
+        aud: this.endpoints.oauth2TokenUrl,
+        iat: now,
+        exp: now + 3600,
+      };
+
+      const encHeader = base64urlEncode(JSON.stringify(header));
+      const encClaims = base64urlEncode(JSON.stringify(claimSet));
+      const signInput = `${encHeader}.${encClaims}`;
+
+      const signature = await crypto.subtle.sign(
+        'RSASSA-PKCS1-v1_5',
+        privateKey,
+        new TextEncoder().encode(signInput),
+      );
+
+      const jwt = `${signInput}.${base64urlEncode(signature)}`;
+
+      // Exchange JWT for access token
+      const tokenResp = await fetch(this.endpoints.oauth2TokenUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${jwt}`,
+      });
+
+      if (!tokenResp.ok) {
+        console.error(
+          '[PushProvider:FCM] Token exchange failed:',
+          tokenResp.status,
+          this.endpoints.oauth2TokenUrl,
+        );
+        return null;
+      }
+
+      const tokenData = await tokenResp.json() as { access_token: string; expires_in: number };
+      this.accessToken = tokenData.access_token;
+      this.tokenExpiry = Date.now() + (tokenData.expires_in - 60) * 1000; // 1 min buffer
+      return this.accessToken;
+    } catch (err) {
+      console.error('[PushProvider:FCM] getAccessToken error:', err, this.endpoints.oauth2TokenUrl);
+      return null;
+    }
+  }
+}
+
+// ─── Factory ───
+
+export function resolveFcmEndpoints(
+  projectId: string,
+  endpoints?: { oauth2TokenUrl?: string; fcmSendUrl?: string; iidBaseUrl?: string },
+  env?: Env,
+): { oauth2TokenUrl: string; fcmSendUrl: string; iidBaseUrl: string } {
+  const mockBaseUrl = env?.MOCK_FCM_BASE_URL?.trim()?.replace(/\/$/, '');
+  if (mockBaseUrl) {
+    return {
+      oauth2TokenUrl: `${mockBaseUrl}/token`,
+      fcmSendUrl: `${mockBaseUrl}/v1/projects/${projectId}/messages:send`,
+      iidBaseUrl: mockBaseUrl,
+    };
+  }
+
+  return {
+    oauth2TokenUrl: endpoints?.oauth2TokenUrl ?? 'https://oauth2.googleapis.com/token',
+    fcmSendUrl: endpoints?.fcmSendUrl ?? `https://fcm.googleapis.com/v1/projects/${projectId}/messages:send`,
+    iidBaseUrl: endpoints?.iidBaseUrl ?? 'https://iid.googleapis.com',
+  };
+}
+
+/**
+ * Create FCM push provider from config + env.
+ * Returns null if FCM is not configured.
+ *
+ * Service account resolution order:
+ *   1. env.PUSH_FCM_SERVICE_ACCOUNT  — direct Worker env binding (production)
+ *   2. config.fcm.serviceAccount     — config-embedded fallback (test/Docker)
+ */
+export function createPushProvider(
+  config?: PushConfig,
+  env?: Env,
+): FcmProvider | null {
+  if (!config?.fcm) return null;
+
+  // Primary: direct env binding
+  const serviceAccountJson =
+    env?.PUSH_FCM_SERVICE_ACCOUNT ?? config.fcm.serviceAccount;
+
+  if (!serviceAccountJson) return null;
+
+  const mockBaseUrl = env?.MOCK_FCM_BASE_URL?.trim()?.replace(/\/$/, '');
+
+  return new FcmProvider(
+    config.fcm.projectId,
+    serviceAccountJson,
+    resolveFcmEndpoints(config.fcm.projectId, config.fcm.endpoints, env),
+    Boolean(mockBaseUrl),
+  );
+}
+
+// ─── Helpers ───
+
+function base64urlEncode(input: string | ArrayBuffer): string {
+  let base64: string;
+  if (typeof input === 'string') {
+    base64 = btoa(input);
+  } else {
+    const bytes = new Uint8Array(input);
+    let binary = '';
+    for (const b of bytes) {
+      binary += String.fromCharCode(b);
+    }
+    base64 = btoa(binary);
+  }
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/src/lib/push-token.ts

@@ -0,0 +1,294 @@
+/**
+ * Push Token Manager — KV-based device token storage
+ *
+ * KV key patterns:
+ *   push:user:{userId}  → JSON array [{ deviceId, platform, token, updatedAt }, ...]
+ *
+ * AUTH_DB._push_devices is the primary source of truth when AUTH_DB is available.
+ * KV remains a mirrored cache plus the storage backend for push logs.
+ * Failed sends (410/404) remove the specific device from the array.
+ */
+
+import type { AuthDb } from './auth-db-adapter.js';
+
+// ─── Types ───
+
+export interface DeviceInfo {
+  deviceId: string;
+  token: string;
+  platform: string;
+  updatedAt: string;
+  /** Device info — name, OS version, app version, locale. */
+  deviceInfo?: {
+    name?: string;
+    osVersion?: string;
+    appVersion?: string;
+    locale?: string;
+  };
+  /** Developer custom metadata (≤1KB JSON). */
+  metadata?: Record<string, unknown>;
+}
+
+// ─── Constants ───
+
+/** Maximum devices per user */
+const MAX_DEVICES_PER_USER = 10;
+
+interface PushTokenStore {
+  kv: KVNamespace;
+  authDb?: AuthDb | null;
+}
+
+interface PushDeviceRow {
+  deviceId: string;
+  token: string;
+  platform: string;
+  updatedAt: string;
+  deviceInfo: string | null;
+  metadata: string | null;
+}
+
+function resolveStore(store: KVNamespace | PushTokenStore): PushTokenStore {
+  if ('kv' in store) return store;
+  return { kv: store };
+}
+
+function parseJsonObject(value: string | null): Record<string, unknown> | undefined {
+  if (!value) return undefined;
+  try {
+    const parsed = JSON.parse(value) as Record<string, unknown>;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseDeviceInfo(value: string | null): DeviceInfo['deviceInfo'] | undefined {
+  const parsed = parseJsonObject(value);
+  return parsed as DeviceInfo['deviceInfo'] | undefined;
+}
+
+function parseMetadata(value: string | null): Record<string, unknown> | undefined {
+  return parseJsonObject(value);
+}
+
+async function readDevicesFromKv(kv: KVNamespace, userId: string): Promise<DeviceInfo[]> {
+  const raw = await kv.get(`push:user:${userId}`);
+  if (!raw) return [];
+  try {
+    return JSON.parse(raw) as DeviceInfo[];
+  } catch {
+    return [];
+  }
+}
+
+async function readDevicesFromAuthDb(authDb: AuthDb, userId: string): Promise<DeviceInfo[]> {
+  const rows = await authDb.query<PushDeviceRow>(
+    `SELECT deviceId, token, platform, updatedAt, deviceInfo, metadata
+       FROM _push_devices
+      WHERE userId = ?
+      ORDER BY updatedAt ASC, deviceId ASC`,
+    [userId],
+  );
+  return rows.map((row) => ({
+    deviceId: row.deviceId,
+    token: row.token,
+    platform: row.platform,
+    updatedAt: row.updatedAt,
+    deviceInfo: parseDeviceInfo(row.deviceInfo),
+    metadata: parseMetadata(row.metadata),
+  }));
+}
+
+async function persistDevices(store: PushTokenStore, userId: string, devices: DeviceInfo[]): Promise<void> {
+  const { kv, authDb } = store;
+  if (devices.length === 0) {
+    await kv.delete(`push:user:${userId}`);
+  } else {
+    await kv.put(`push:user:${userId}`, JSON.stringify(devices));
+  }
+
+  if (!authDb) return;
+
+  const statements: Array<{ sql: string; params?: unknown[] }> = [
+    { sql: 'DELETE FROM _push_devices WHERE userId = ?', params: [userId] },
+  ];
+
+  for (const device of devices) {
+    statements.push({
+      sql: `INSERT INTO _push_devices (userId, deviceId, token, platform, updatedAt, deviceInfo, metadata)
+            VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      params: [
+        userId,
+        device.deviceId,
+        device.token,
+        device.platform,
+        device.updatedAt,
+        device.deviceInfo ? JSON.stringify(device.deviceInfo) : null,
+        device.metadata ? JSON.stringify(device.metadata) : null,
+      ],
+    });
+  }
+
+  await authDb.batch(statements);
+}
+
+async function ensureDevices(store: PushTokenStore, userId: string): Promise<DeviceInfo[]> {
+  if (!store.authDb) {
+    return readDevicesFromKv(store.kv, userId);
+  }
+
+  const authDevices = await readDevicesFromAuthDb(store.authDb, userId);
+  if (authDevices.length > 0) {
+    return authDevices;
+  }
+
+  const kvDevices = await readDevicesFromKv(store.kv, userId);
+  if (kvDevices.length > 0) {
+    await persistDevices(store, userId, kvDevices);
+  }
+  return kvDevices;
+}
+
+// ─── Public API ───
+
+/**
+ * Register a device token for a user.
+ * If the device already exists, update the token.
+ * If the user has too many devices, remove the oldest.
+ */
+export async function registerToken(
+  storeOrKv: KVNamespace | PushTokenStore,
+  userId: string,
+  deviceId: string,
+  token: string,
+  platform: string,
+  deviceInfo?: DeviceInfo['deviceInfo'],
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  const now = new Date().toISOString();
+  const store = resolveStore(storeOrKv);
+
+  const devices = await ensureDevices(store, userId);
+  const existingIdx = devices.findIndex(d => d.deviceId === deviceId);
+
+  if (existingIdx >= 0) {
+    // Update existing device
+    devices[existingIdx] = { deviceId, token, platform, updatedAt: now, deviceInfo, metadata };
+  } else {
+    // Add new device
+    devices.push({ deviceId, token, platform, updatedAt: now, deviceInfo, metadata });
+  }
+
+  // Enforce max devices — remove oldest if exceeded
+  if (devices.length > MAX_DEVICES_PER_USER) {
+    devices.sort((a, b) => a.updatedAt.localeCompare(b.updatedAt));
+    devices.splice(0, devices.length - MAX_DEVICES_PER_USER);
+  }
+
+  await persistDevices(store, userId, devices);
+}
+
+/**
+ * Unregister a specific device token.
+ */
+export async function unregisterToken(
+  storeOrKv: KVNamespace | PushTokenStore,
+  userId: string,
+  deviceId: string,
+): Promise<void> {
+  await removeDeviceFromUser(storeOrKv, userId, deviceId);
+}
+
+/**
+ * Get all registered devices for a user.
+ */
+export async function getDevicesForUser(
+  storeOrKv: KVNamespace | PushTokenStore,
+  userId: string,
+): Promise<DeviceInfo[]> {
+  return ensureDevices(resolveStore(storeOrKv), userId);
+}
+
+/**
+ * Remove a specific device from a user's device list.
+ * Called when push send receives 410/404 (token invalid).
+ */
+export async function removeDeviceFromUser(
+  storeOrKv: KVNamespace | PushTokenStore,
+  userId: string,
+  deviceId: string,
+): Promise<void> {
+  const store = resolveStore(storeOrKv);
+  const devices = await ensureDevices(store, userId);
+  const filtered = devices.filter(d => d.deviceId !== deviceId);
+
+  if (filtered.length !== devices.length) {
+    await persistDevices(store, userId, filtered);
+  }
+}
+
+/**
+ * Unregister all device tokens for a user.
+ * Called on revokeAllSessions / user deletion.
+ */
+export async function unregisterAllTokens(
+  storeOrKv: KVNamespace | PushTokenStore,
+  userId: string,
+): Promise<void> {
+  await persistDevices(resolveStore(storeOrKv), userId, []);
+}
+
+// ─── Push Log ───
+
+const LOG_TTL_SECONDS = 24 * 60 * 60; // 24 hours
+
+export interface PushLogEntry {
+  sentAt: string;
+  userId: string;
+  platform: string;
+  status: 'sent' | 'failed' | 'removed';
+  collapseId?: string;
+  error?: string;
+  runId?: string;
+  probeId?: string;
+  title?: string;
+  body?: string;
+  target?: string;
+  topic?: string;
+}
+
+/**
+ * Store a push send log entry (24h TTL).
+ */
+export async function storePushLog(
+  kv: KVNamespace,
+  userId: string,
+  entry: PushLogEntry,
+): Promise<void> {
+  const logKey = `push:log:${userId}:${Date.now()}:${Math.random().toString(36).slice(2, 6)}`;
+  await kv.put(logKey, JSON.stringify(entry), { expirationTtl: LOG_TTL_SECONDS });
+}
+
+/**
+ * Get push send logs for a user (last 24h).
+ */
+export async function getPushLogs(
+  kv: KVNamespace,
+  userId: string,
+  limit: number = 50,
+): Promise<PushLogEntry[]> {
+  const result = await kv.list({ prefix: `push:log:${userId}:`, limit });
+  const entries: PushLogEntry[] = [];
+
+  for (const key of result.keys) {
+    const raw = await kv.get(key.name);
+    if (raw) {
+      try {
+        entries.push(JSON.parse(raw) as PushLogEntry);
+      } catch { /* skip corrupted */ }
+    }
+  }
+
+  return entries;
+}