/** * Mobile device-token registration routes (Phase 08 #65). * * The Capacitor mobile shell calls `POST /v1/devices/register` once it * has obtained an APNs / FCM / WebPush token from the native plugin. * The endpoint upserts by `token` (globally unique) so the same payload * can be replayed on every cold start without producing duplicate rows. * * Authentication: service-credential (bearer or API-key) — the mobile * client forwards its session bearer through the same auth pipeline as * every other API call. `userId` and `tenantId` come from the request * body because the wrapping service-token has no inherent identity in * the boilerplate's auth model; downstream calls verify these against * the authenticated principal. * * @see packages/db/src/device-tokens.server.ts * @see apps/mobile/src/pushRegistration.ts */ import { parseDevicePlatform, parsePushProvider, registerDeviceToken, revokeDeviceToken, type DeviceTokenRecord, } from "@toolctrl/db/device-tokens.server"; import { Hono, type Context } from "hono"; import type { ApiEnv } from "../api-types.js"; import { apiError } from "../middleware/error-envelope.js"; import { requireServiceCredential, readJsonBody, isPlainObject } from "./shared.js"; const MAX_TOKEN_LENGTH = 4_096; const MAX_USER_ID_LENGTH = 128; const MAX_TENANT_ID_LENGTH = 128; const MAX_APP_VERSION_LENGTH = 64; export function registerDevicesRoutes(app: Hono) { app.post("/v1/devices/register", postDeviceRegisterRequest); app.post("/v1/devices/revoke", postDeviceRevokeRequest); } async function postDeviceRegisterRequest(c: Context) { const unauthorized = requireServiceCredential(c); if (unauthorized) { return unauthorized; } const body = await readJsonBody(c.req.raw); if (!isPlainObject(body)) { return apiError(c, 400, "invalid_request", "Request body must be a JSON object.", { params: { reason: "body_invalid", bodyType: "device_register" } }); } const userId = typeof body.userId === "string" ? body.userId.trim() : ""; const tenantIdRaw = typeof body.tenantId === "string" ? body.tenantId.trim() : ""; const platform = parseDevicePlatform(body.platform); const token = typeof body.token === "string" ? body.token.trim() : ""; const pushProvider = parsePushProvider(body.pushProvider) ?? undefined; const appVersion = typeof body.appVersion === "string" ? body.appVersion.trim() : ""; if (!userId) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_required", field: "userId" } }); } if (userId.length > MAX_USER_ID_LENGTH) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "userId", max: MAX_USER_ID_LENGTH } }); } if (tenantIdRaw.length > MAX_TENANT_ID_LENGTH) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "tenantId", max: MAX_TENANT_ID_LENGTH } }); } if (!platform) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_value_invalid", field: "platform", allowed: "ios,android,web" } }); } if (!token) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_required", field: "token" } }); } if (token.length > MAX_TOKEN_LENGTH) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "token", max: MAX_TOKEN_LENGTH } }); } if (appVersion.length > MAX_APP_VERSION_LENGTH) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_too_long", field: "appVersion", max: MAX_APP_VERSION_LENGTH } }); } let record: DeviceTokenRecord; try { record = await registerDeviceToken({ userId, tenantId: tenantIdRaw || null, platform, token, pushProvider, appVersion: appVersion || null, }); } catch { return apiError(c, 500, "device_token_register_failed", "Device token could not be registered."); } return c.json( { success: true, data: { id: record.id, userId: record.userId, tenantId: record.tenantId, platform: record.platform, pushProvider: record.pushProvider, appVersion: record.appVersion, createdAt: record.createdAt.toISOString(), lastSeenAt: record.lastSeenAt.toISOString(), }, }, 200, ); } async function postDeviceRevokeRequest(c: Context) { const unauthorized = requireServiceCredential(c); if (unauthorized) { return unauthorized; } const body = await readJsonBody(c.req.raw); if (!isPlainObject(body)) { return apiError(c, 400, "invalid_request", "Request body must be a JSON object.", { params: { reason: "body_invalid", bodyType: "device_revoke" } }); } const token = typeof body.token === "string" ? body.token.trim() : ""; if (!token) { return apiError(c, 400, "invalid_request", "Request validation failed.", { params: { reason: "field_required", field: "token" } }); } const record = await revokeDeviceToken(token); if (!record) { return apiError(c, 404, "device_token_not_found", "Device token was not found."); } return c.json( { success: true, data: { id: record.id, token: record.token, revokedAt: record.revokedAt?.toISOString() ?? null, }, }, 200, ); }