@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

package/src/modules/devices/api/admin/devices/route.ts

@@ -0,0 +1,160 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
+import { User } from '@open-mercato/core/modules/auth/data/entities'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { E } from '#generated/entities.ids.generated'
+import { UserDevice } from '../../../data/entities'
+import {
+  registerDeviceAdminSchema,
+  registerDeviceCommandSchema,
+  type RegisterDeviceCommandInput,
+} from '../../../data/validators'
+import { resolveDeviceActorUserId } from '../../auth'
+import { createDevicesCrudOpenApi, createPagedListResponseSchema } from '../../openapi'
+import { deviceListSchema, deviceListFields, deviceListSortFieldMap, deviceListItemSchema } from '../../deviceList'
+import { executeRegister, type DeviceMutationContext } from '../../deviceOps'
+
+const logger = createLogger('devices')
+
+// Admin device administration: cross-user listing + register-on-behalf-of-user. Gated by devices.admin.
+// Self-serve registration/listing stays on /api/devices (scoped to the acting user).
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['devices.admin'] },
+  POST: { requireAuth: true, requireFeatures: ['devices.admin'] },
+}
+
+export const metadata = routeMetadata
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: UserDevice,
+    idField: 'id',
+    // organization_id stays nullable, but scoping follows the standard org-scoped pattern: the factory
+    // auto-filters by the caller's organization scope (null-aware in the query engine). Unrestricted
+    // admins see the whole tenant including null-org rows; org-restricted admins see only their orgs.
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.devices.user_device },
+  // Same cache resource tag as the self route + commands, so any device write busts both list caches.
+  events: { module: 'devices', entity: 'user_device' },
+  list: {
+    schema: deviceListSchema,
+    entityId: E.devices.user_device,
+    fields: deviceListFields,
+    sortFieldMap: deviceListSortFieldMap,
+    // Tenant + org scope is enforced by the factory (orm.tenantField + orm.orgField); only the optional
+    // userId/platform narrowing is left to do here.
+    buildFilters: async (query) => {
+      const filters: Record<string, unknown> = {}
+      if (query.userId) filters.user_id = { $eq: query.userId }
+      if (query.platform) filters.platform = { $eq: query.platform }
+      return filters
+    },
+  },
+})
+
+export const GET = crud.GET
+
+export async function POST(req: Request) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+
+    const body = registerDeviceAdminSchema.parse(await readJsonSafe(req, {}))
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const organizationId = scope?.selectedId ?? auth.orgId ?? null
+
+    // Validate the on-behalf-of target before registering. `body.userId` is caller-supplied, and the
+    // fan-out delivers by `(tenant, org, user)` — so without this an admin could register their OWN push
+    // token under an arbitrary `userId` (even a non-existent or cross-tenant one) and start receiving that
+    // user's notifications. Require a real, active user in the admin's tenant who is also within the
+    // admin's organization scope (org-restricted admins cannot reach users in orgs they can't access).
+    // Only non-encrypted columns are selected, so no decryption is needed.
+    const em = container.resolve('em') as EntityManager
+    const targetUser = await em.findOne(
+      User,
+      { id: body.userId, tenantId: auth.tenantId, deletedAt: null },
+      { fields: ['id', 'organizationId'] },
+    )
+    if (!targetUser) {
+      return NextResponse.json(
+        { error: translate('devices.errors.user_not_found', 'Target user not found in this tenant') },
+        { status: 400 },
+      )
+    }
+    if (!isOrganizationReadAccessAllowed({ scope, auth, organizationId: targetUser.organizationId ?? null })) {
+      return NextResponse.json({ error: translate('devices.errors.forbidden', 'Access denied') }, { status: 403 })
+    }
+
+    // Register is an idempotent upsert keyed per (tenant, org, user, device). organizationId is the
+    // admin's own resolved scope, so the upsert can only ever touch a row inside an org the admin can
+    // access — no cross-org guard is needed here.
+    const commandInput = registerDeviceCommandSchema.parse({
+      ...body,
+      tenantId: auth.tenantId,
+      organizationId,
+      userId: body.userId,
+    } satisfies RegisterDeviceCommandInput)
+
+    // actorUserId is the admin (for the mutation guard/audit); the device is owned by body.userId.
+    const mctx: DeviceMutationContext = { container, auth, scope, organizationId, actorUserId, request: req }
+    return await executeRegister(mctx, commandInput)
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: translate('devices.errors.invalid_payload', 'Invalid device payload'), details: err.flatten() },
+        { status: 400 },
+      )
+    }
+    if (isCrudHttpError(err) && (err.body as { code?: string } | undefined)?.code === 'device_already_registered') {
+      return NextResponse.json(
+        { error: translate('devices.errors.already_registered', 'This device is already registered') },
+        { status: 409 },
+      )
+    }
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.admin.POST failed', { err })
+    return NextResponse.json(
+      { error: translate('devices.errors.register_failed', 'Failed to register device') },
+      { status: 500 },
+    )
+  }
+}
+
+const registerResponseSchema = z.object({
+  id: z.string().uuid(),
+  deviceId: z.string(),
+  revived: z.boolean(),
+})
+
+export const openApi: OpenApiRouteDoc = createDevicesCrudOpenApi({
+  resourceName: 'Device (admin)',
+  pluralName: 'Devices (admin)',
+  querySchema: deviceListSchema,
+  listResponseSchema: createPagedListResponseSchema(deviceListItemSchema),
+  create: {
+    schema: registerDeviceAdminSchema,
+    responseSchema: registerResponseSchema,
+    description: 'Admin: register (idempotently upsert) a device on behalf of any user in the tenant.',
+  },
+})

package/src/modules/devices/api/auth.ts

@@ -0,0 +1,13 @@
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+
+/**
+ * Resolves the acting user id for device routes. Device ownership is per-user, so API-key
+ * principals (which have no human user) are not valid device actors and yield null. Mirrors the
+ * `auth.isApiKey ? null : auth.sub` convention used across the codebase; the target user id is
+ * validated as a UUID by the command schemas downstream.
+ */
+export function resolveDeviceActorUserId(auth: AuthContext | null): string | null {
+  if (!auth || auth.isApiKey) return null
+  const subjectId = typeof auth.sub === 'string' ? auth.sub.trim() : ''
+  return subjectId || null
+}

package/src/modules/devices/api/deviceList.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+
+// Shared list contract for the self-serve (`/api/devices`) and admin (`/api/devices/admin/devices`)
+// list routes. push_token is a secret and is never part of the exposed field set.
+export const deviceListSchema = z
+  .object({
+    page: z.coerce.number().min(1).default(1),
+    pageSize: z.coerce.number().min(1).max(100).default(50),
+    platform: z.enum(['ios', 'android', 'web']).optional(),
+    userId: z.string().uuid().optional(),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+  })
+  .passthrough()
+
+export const deviceListFields: string[] = [
+  'id',
+  'tenant_id',
+  'organization_id',
+  'user_id',
+  'device_id',
+  'platform',
+  'client_app_version',
+  'os_version',
+  'locale',
+  'push_provider',
+  'push_token_updated_at',
+  'last_seen_at',
+  'created_at',
+  'updated_at',
+]
+
+export const deviceListSortFieldMap: Record<string, string> = {
+  lastSeenAt: 'last_seen_at',
+  createdAt: 'created_at',
+  updatedAt: 'updated_at',
+}
+
+export const deviceListItemSchema = z.object({
+  id: z.string().uuid(),
+  tenant_id: z.string().uuid(),
+  organization_id: z.string().uuid().nullable().optional(),
+  user_id: z.string().uuid(),
+  device_id: z.string(),
+  platform: z.enum(['ios', 'android', 'web']),
+  client_app_version: z.string().nullable().optional(),
+  os_version: z.string().nullable().optional(),
+  locale: z.string().nullable().optional(),
+  push_provider: z.string().nullable().optional(),
+  push_token_updated_at: z.string().nullable().optional(),
+  last_seen_at: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})

package/src/modules/devices/api/deviceOps.ts

@@ -0,0 +1,186 @@
+import { NextResponse } from 'next/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import {
+  runCrudMutationGuardAfterSuccess,
+  validateCrudMutationGuard,
+} from '@open-mercato/shared/lib/crud/mutation-guard'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import type { CommandBus } from '@open-mercato/shared/lib/commands'
+import type { UserDevice } from '../data/entities'
+import type {
+  RegisterDeviceCommandInput,
+  UpdateDeviceCommandInput,
+  DeactivateDeviceCommandInput,
+} from '../data/validators'
+import { attachOperationMetadataHeader } from '../lib/operationMetadata'
+
+const RESOURCE_KIND = 'devices.user_device'
+
+// push_token is a secret. The mutation guard forwards mutationPayload into record-lock conflict
+// details that are returned to clients, so strip the token before it reaches the guard.
+export function redactMutationPayload(
+  payload: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!payload || !('pushToken' in payload)) return payload
+  const { pushToken: _pushToken, ...rest } = payload
+  return rest
+}
+
+type RequestContainer = Awaited<ReturnType<typeof createRequestContainer>>
+type OrganizationScope = Awaited<ReturnType<typeof resolveOrganizationScopeForRequest>>
+
+// Shared mutation context for device write ops. `actorUserId` is the authenticated caller (used for
+// the mutation guard / audit), independent of which user *owns* the device being mutated.
+export type DeviceMutationContext = {
+  container: RequestContainer
+  auth: NonNullable<AuthContext>
+  scope: OrganizationScope
+  organizationId: string | null
+  actorUserId: string
+  request: Request
+}
+
+function commandCtx(mctx: DeviceMutationContext) {
+  return {
+    container: mctx.container,
+    auth: mctx.auth,
+    organizationScope: mctx.scope ?? null,
+    selectedOrganizationId: mctx.organizationId,
+    organizationIds: mctx.scope?.filterIds ?? (mctx.auth.orgId ? [mctx.auth.orgId] : null),
+    request: mctx.request,
+  }
+}
+
+async function runGuards(
+  mctx: DeviceMutationContext,
+  operation: 'create' | 'update' | 'delete',
+  resourceId: string,
+  mutationPayload?: Record<string, unknown>,
+) {
+  return validateCrudMutationGuard(mctx.container, {
+    tenantId: mctx.auth.tenantId!,
+    organizationId: mctx.organizationId,
+    userId: mctx.actorUserId,
+    resourceKind: RESOURCE_KIND,
+    resourceId,
+    operation,
+    requestMethod: mctx.request.method,
+    requestHeaders: mctx.request.headers,
+    mutationPayload,
+  })
+}
+
+async function runAfter(
+  mctx: DeviceMutationContext,
+  guardResult: Awaited<ReturnType<typeof validateCrudMutationGuard>>,
+  operation: 'create' | 'update' | 'delete',
+  resourceId: string,
+) {
+  if (guardResult?.ok && guardResult.shouldRunAfterSuccess) {
+    await runCrudMutationGuardAfterSuccess(mctx.container, {
+      tenantId: mctx.auth.tenantId!,
+      organizationId: mctx.organizationId,
+      userId: mctx.actorUserId,
+      resourceKind: RESOURCE_KIND,
+      resourceId,
+      operation,
+      requestMethod: mctx.request.method,
+      requestHeaders: mctx.request.headers,
+      metadata: (guardResult.metadata as Record<string, unknown> | null | undefined) ?? null,
+    })
+  }
+}
+
+export async function executeRegister(
+  mctx: DeviceMutationContext,
+  commandInput: RegisterDeviceCommandInput,
+): Promise<NextResponse> {
+  // Register is an upsert, so the device row id isn't known until execution. Key the mutation guard
+  // by the stable, tenant-unique upsert tuple so validate and after-success agree (record locks are
+  // keyed by resourceId); deviceId alone is not unique across users.
+  const guardResourceId = `${commandInput.userId}:${commandInput.deviceId}`
+  const guardResult = await runGuards(mctx, 'create', guardResourceId, redactMutationPayload(commandInput))
+  if (guardResult && !guardResult.ok) return NextResponse.json(guardResult.body, { status: guardResult.status })
+
+  const commandBus = mctx.container.resolve('commandBus') as CommandBus
+  const { result, logEntry } = await commandBus.execute<
+    RegisterDeviceCommandInput,
+    { id: string; deviceId: string; revived: boolean }
+  >('devices.user_devices.register', { input: commandInput, ctx: commandCtx(mctx) })
+
+  await runAfter(mctx, guardResult, 'create', guardResourceId)
+
+  const response = NextResponse.json(
+    { id: result.id, deviceId: result.deviceId, revived: result.revived },
+    { status: 201 },
+  )
+  attachOperationMetadataHeader(response, logEntry, { resourceKind: RESOURCE_KIND, resourceId: result.id })
+  return response
+}
+
+export async function executeUpdate(
+  mctx: DeviceMutationContext,
+  device: UserDevice,
+  body: Omit<UpdateDeviceCommandInput, 'id' | 'tenantId' | 'userId' | 'organizationId'>,
+): Promise<NextResponse> {
+  // Device metadata edits carry lost-update risk (unlike the idempotent soft-delete deactivate), so
+  // enforce OSS optimistic locking when the caller sends the expected-version header. No-ops when the
+  // header is absent (e.g. mobile self-update clients), keeping the contract backward-compatible.
+  enforceCommandOptimisticLock({
+    resourceKind: RESOURCE_KIND,
+    resourceId: device.id,
+    current: device.updatedAt,
+    request: mctx.request,
+  })
+
+  const guardResult = await runGuards(mctx, 'update', device.id, redactMutationPayload(body))
+  if (guardResult && !guardResult.ok) return NextResponse.json(guardResult.body, { status: guardResult.status })
+
+  const commandBus = mctx.container.resolve('commandBus') as CommandBus
+  const { logEntry } = await commandBus.execute<UpdateDeviceCommandInput, { id: string }>('devices.user_devices.update', {
+    input: {
+      ...body,
+      id: device.id,
+      tenantId: device.tenantId,
+      userId: device.userId,
+      organizationId: device.organizationId ?? null,
+    } satisfies UpdateDeviceCommandInput,
+    ctx: commandCtx(mctx),
+  })
+
+  await runAfter(mctx, guardResult, 'update', device.id)
+
+  const response = NextResponse.json({ ok: true, id: device.id })
+  attachOperationMetadataHeader(response, logEntry, { resourceKind: RESOURCE_KIND, resourceId: device.id })
+  return response
+}
+
+export async function executeDeactivate(
+  mctx: DeviceMutationContext,
+  device: UserDevice,
+): Promise<NextResponse> {
+  const guardResult = await runGuards(mctx, 'delete', device.id)
+  if (guardResult && !guardResult.ok) return NextResponse.json(guardResult.body, { status: guardResult.status })
+
+  const commandBus = mctx.container.resolve('commandBus') as CommandBus
+  const { logEntry } = await commandBus.execute<DeactivateDeviceCommandInput, { id: string }>(
+    'devices.user_devices.deactivate',
+    {
+      input: {
+        id: device.id,
+        tenantId: device.tenantId,
+        userId: device.userId,
+        organizationId: device.organizationId ?? null,
+      } satisfies DeactivateDeviceCommandInput,
+      ctx: commandCtx(mctx),
+    },
+  )
+
+  await runAfter(mctx, guardResult, 'delete', device.id)
+
+  const response = NextResponse.json({ ok: true })
+  attachOperationMetadataHeader(response, logEntry, { resourceKind: RESOURCE_KIND, resourceId: device.id })
+  return response
+}

package/src/modules/devices/api/openapi.ts

@@ -0,0 +1,23 @@
+import { type ZodTypeAny } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  createCrudOpenApiFactory,
+  createPagedListResponseSchema as createSharedPagedListResponseSchema,
+  type CrudOpenApiOptions,
+} from '@open-mercato/shared/lib/openapi/crud'
+
+export function createPagedListResponseSchema(itemSchema: ZodTypeAny) {
+  return createSharedPagedListResponseSchema(itemSchema, { paginationMetaOptional: true })
+}
+
+// createCrudOpenApiFactory already falls back to the shared default create/ok response schemas
+// when omitted, so there is nothing module-specific to re-pass or re-export here.
+const buildDevicesCrudOpenApi = createCrudOpenApiFactory({
+  defaultTag: 'Devices',
+  makeListDescription: ({ pluralLower }) =>
+    `Returns the authenticated user's registered ${pluralLower} (admins may list across users).`,
+})
+
+export function createDevicesCrudOpenApi(options: CrudOpenApiOptions): OpenApiRouteDoc {
+  return buildDevicesCrudOpenApi(options)
+}

package/src/modules/devices/api/route.ts

@@ -0,0 +1,165 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { consumeAdvancedFilterState, mergeAdvancedFilterTree } from '@open-mercato/shared/lib/crud/advanced-filter-integration'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { resolveLocaleFromAcceptLanguage } from '@open-mercato/shared/lib/i18n/locale'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { E } from '#generated/entities.ids.generated'
+import { UserDevice } from '../data/entities'
+import {
+  registerDeviceSchema,
+  registerDeviceCommandSchema,
+  type RegisterDeviceCommandInput,
+} from '../data/validators'
+import { resolveDeviceActorUserId } from './auth'
+import { createDevicesCrudOpenApi, createPagedListResponseSchema } from './openapi'
+import { deviceListSchema, deviceListFields, deviceListSortFieldMap, deviceListItemSchema } from './deviceList'
+import { executeRegister, type DeviceMutationContext } from './deviceOps'
+
+const logger = createLogger('devices')
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['devices.view'] },
+  POST: { requireAuth: true, requireFeatures: ['devices.manage'] },
+}
+
+export const metadata = routeMetadata
+
+const NO_MATCH_USER_ID = '00000000-0000-0000-0000-000000000000'
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: UserDevice,
+    idField: 'id',
+    // organization_id stays nullable, but scoping follows the standard org-scoped pattern (like every
+    // other module): the factory auto-filters by the caller's organization scope. The query engine's
+    // org scope is null-aware — callers whose scope includes null (or who have no org restriction) also
+    // see null-org rows; a caller pinned to a specific org does not.
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.devices.user_device },
+  // Align the CRUD cache resource tag with the command's resourceKind ('devices.user_device') so
+  // writes through the device commands invalidate this list cache. Without this, the factory falls
+  // back to the ORM entity name and the cache is never busted (stale list under ENABLE_CRUD_API_CACHE).
+  // The factory does not own the write methods here (custom POST + command bus), so no events are emitted.
+  events: { module: 'devices', entity: 'user_device' },
+  list: {
+    schema: deviceListSchema,
+    entityId: E.devices.user_device,
+    // push_token is a secret and is never exposed via the list API.
+    fields: deviceListFields,
+    sortFieldMap: deviceListSortFieldMap,
+    // Exports are off for the self-serve list. The factory enables them for every list that does not
+    // declare `export` (resolveAvailableExportFormats falls back to csv/json/xml/markdown), and its
+    // full-export branch replaces the filters with `{}` instead of calling `buildFilters`
+    // (`baseFilters = exportFullRequested ? {} : buildFilters(...)`). On this route `buildFilters` is
+    // the only user-level boundary — automatic scoping covers tenant and organization, not the acting
+    // user — so `?format=json&exportScope=full` would return every device in the caller's org scope.
+    // With no available formats, `exportRequested` is never true and that branch is unreachable. Bulk
+    // device data belongs to the admin tree (api/admin/devices), which gates cross-user listing.
+    export: { enabled: false },
+    // Self-serve: always scoped to the acting user. Cross-user listing lives in api/admin/devices.
+    buildFilters: async (query, ctx) => {
+      // Consume the client-supplied advanced filter here (this deletes every `filter[...]` key from
+      // `query`) so the CRUD factory's own merge step becomes a no-op. That step is
+      // `{ ...existingFilters, ...advancedWhere }` (advanced-filter-integration.ts), and condition
+      // field names are never validated — `filter[conditions][0][field]=user_id` or `=$and` would
+      // otherwise overwrite whatever key this route uses for its scope and widen the listing to other
+      // users. `mergeAdvancedFilterTree` instead AND-combines under `$and: [routeFilters, treeWhere]`,
+      // where the scope sits in its own array element and no client key can reach it. Same pattern as
+      // customers/people, companies and deals.
+      const advancedFilterTree = consumeAdvancedFilterState(query)
+      const filters: Record<string, unknown> = {}
+      const actorUserId = resolveDeviceActorUserId(ctx.auth)
+      // Self-serve visibility is strictly the acting user's own devices; cross-user listing lives in
+      // api/admin/devices. Fail closed when there is no resolvable acting user (e.g. API keys).
+      filters.user_id = { $eq: actorUserId ?? NO_MATCH_USER_ID }
+      if (query.platform) filters.platform = { $eq: query.platform }
+      return mergeAdvancedFilterTree(filters, advancedFilterTree)
+    },
+  },
+})
+
+export const GET = crud.GET
+
+export async function POST(req: Request) {
+  const { translate } = await resolveTranslations()
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const actorUserId = resolveDeviceActorUserId(auth)
+    if (!auth || !auth.tenantId || !actorUserId) {
+      return NextResponse.json({ error: translate('devices.errors.unauthorized', 'Unauthorized') }, { status: 401 })
+    }
+
+    const body = registerDeviceSchema.parse(await readJsonSafe(req, {}))
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const organizationId = scope?.selectedId ?? auth.orgId ?? null
+
+    // When the app doesn't send an explicit per-device locale, fall back to the request's
+    // Accept-Language (the mobile client calls this with its own headers). Only on self-register —
+    // PUT stays tri-state, and admin register uses the admin's browser headers, not the device's.
+    const headerLocale = resolveLocaleFromAcceptLanguage(req.headers.get('accept-language'))
+
+    const commandInput = registerDeviceCommandSchema.parse({
+      ...body,
+      locale: body.locale ?? headerLocale ?? undefined,
+      tenantId: auth.tenantId,
+      organizationId,
+      userId: actorUserId,
+    } satisfies RegisterDeviceCommandInput)
+
+    const mctx: DeviceMutationContext = { container, auth, scope, organizationId, actorUserId, request: req }
+    return await executeRegister(mctx, commandInput)
+  } catch (err) {
+    if (err instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: translate('devices.errors.invalid_payload', 'Invalid device payload'), details: err.flatten() },
+        { status: 400 },
+      )
+    }
+    if (isCrudHttpError(err) && (err.body as { code?: string } | undefined)?.code === 'device_already_registered') {
+      return NextResponse.json(
+        { error: translate('devices.errors.already_registered', 'This device is already registered') },
+        { status: 409 },
+      )
+    }
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('devices.POST failed', { err })
+    return NextResponse.json(
+      { error: translate('devices.errors.register_failed', 'Failed to register device') },
+      { status: 500 },
+    )
+  }
+}
+
+const registerResponseSchema = z.object({
+  id: z.string().uuid(),
+  deviceId: z.string(),
+  revived: z.boolean(),
+})
+
+export const openApi: OpenApiRouteDoc = createDevicesCrudOpenApi({
+  resourceName: 'Device',
+  pluralName: 'Devices',
+  querySchema: deviceListSchema,
+  listResponseSchema: createPagedListResponseSchema(deviceListItemSchema),
+  create: {
+    schema: registerDeviceSchema,
+    responseSchema: registerResponseSchema,
+    description:
+      'Registers (or idempotently upserts) the current user\'s device for the given deviceId. May include an initial push token.',
+  },
+})

package/src/modules/devices/backend/devices/[id]/page.meta.ts

@@ -0,0 +1,12 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['devices.admin'],
+  pageTitle: 'Edit device',
+  pageTitleKey: 'devices.form.editTitle',
+  pageContext: 'settings' as const,
+  navHidden: true,
+  breadcrumb: [
+    { label: 'Devices', labelKey: 'devices.nav.devices', href: '/backend/devices' },
+    { label: 'Edit device', labelKey: 'devices.form.editTitle' },
+  ],
+}