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

package/src/modules/devices/commands/register.ts

@@ -0,0 +1,199 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { registerCommand, type CommandHandler } from '@open-mercato/shared/lib/commands'
+import { ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
+import { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
+import { emitCrudSideEffects, emitCrudUndoSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { UserDevice } from '../data/entities'
+import { registerDeviceCommandSchema, type RegisterDeviceCommandInput } from '../data/validators'
+import { emitDevicesEvent } from '../events'
+import {
+  applySnapshot,
+  deviceEvents,
+  deviceIndexer,
+  isDeviceUniqueViolation,
+  loadExistingDevice,
+  serializeDevice,
+  type DeviceSnapshot,
+  type DeviceUndoPayload,
+} from './shared'
+
+const registerDeviceCommand: CommandHandler<RegisterDeviceCommandInput, { id: string; deviceId: string; revived: boolean }> = {
+  id: 'devices.user_devices.register',
+  async prepare(rawInput, ctx) {
+    const parsed = registerDeviceCommandSchema.parse(rawInput)
+    // Enforce tenant scope before any DB access so prepare() can't probe across tenants.
+    ensureTenantScope(ctx, parsed.tenantId)
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const existing = await loadExistingDevice(em, {
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId ?? null,
+      userId: parsed.userId,
+      deviceId: parsed.deviceId,
+    })
+    return existing ? { before: serializeDevice(existing) } : {}
+  },
+  async execute(rawInput, ctx) {
+    const parsed = registerDeviceCommandSchema.parse(rawInput)
+    ensureTenantScope(ctx, parsed.tenantId)
+
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const existing = await loadExistingDevice(em, {
+      tenantId: parsed.tenantId,
+      organizationId: parsed.organizationId ?? null,
+      userId: parsed.userId,
+      deviceId: parsed.deviceId,
+    })
+    const now = new Date()
+    const hasPushToken = parsed.pushToken !== undefined && parsed.pushToken !== null
+    const wasActive = existing ? existing.deletedAt == null : false
+
+    let device!: UserDevice
+    try {
+      await withAtomicFlush(
+        em,
+        [
+          () => {
+            if (existing) {
+              device = existing
+              device.platform = parsed.platform
+              device.organizationId = parsed.organizationId ?? device.organizationId ?? null
+              if (parsed.clientAppVersion !== undefined) device.clientAppVersion = parsed.clientAppVersion ?? null
+              if (parsed.osVersion !== undefined) device.osVersion = parsed.osVersion ?? null
+              if (parsed.locale !== undefined) device.locale = parsed.locale ?? null
+              if (hasPushToken) {
+                device.pushToken = parsed.pushToken ?? null
+                device.pushProvider = parsed.pushProvider ?? device.pushProvider ?? null
+                device.pushTokenUpdatedAt = now
+              }
+              device.lastSeenAt = now
+              device.deletedAt = null
+            } else {
+              device = em.create(UserDevice, {
+                tenantId: parsed.tenantId,
+                organizationId: parsed.organizationId ?? null,
+                userId: parsed.userId,
+                deviceId: parsed.deviceId,
+                platform: parsed.platform,
+                clientAppVersion: parsed.clientAppVersion ?? null,
+                osVersion: parsed.osVersion ?? null,
+                locale: parsed.locale ?? null,
+                pushToken: hasPushToken ? parsed.pushToken ?? null : null,
+                pushProvider: hasPushToken ? parsed.pushProvider ?? null : null,
+                pushTokenUpdatedAt: hasPushToken ? now : null,
+                lastSeenAt: now,
+              })
+              em.persist(device)
+            }
+          },
+        ],
+        { transaction: true },
+      )
+    } catch (err) {
+      if (isDeviceUniqueViolation(err)) {
+        // Default English message is a fallback; device routes translate by `code` (see route POST
+        // handlers), matching the customers dictionaries conflict pattern.
+        throw new CrudHttpError(409, {
+          code: 'device_already_registered',
+          error: 'This device is already registered',
+        })
+      }
+      throw err
+    }
+
+    const revived = Boolean(existing) && !wasActive
+    const de = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudSideEffects({
+      dataEngine: de,
+      action: existing ? 'updated' : 'created',
+      entity: device,
+      identifiers: {
+        id: device.id,
+        tenantId: device.tenantId,
+        organizationId: device.organizationId ?? null,
+      },
+      indexer: deviceIndexer,
+      events: deviceEvents,
+    })
+    await emitDevicesEvent(
+      'devices.user_device.registered',
+      {
+        id: device.id,
+        tenantId: device.tenantId,
+        organizationId: device.organizationId ?? null,
+        userId: device.userId,
+        deviceId: device.deviceId,
+        platform: device.platform,
+        revived,
+      },
+      { persistent: true },
+    )
+
+    return { id: device.id, deviceId: device.deviceId, revived }
+  },
+  captureAfter: async (_input, result, ctx) => {
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const device = await findOneWithDecryption(em, UserDevice, { id: result.id })
+    return device ? serializeDevice(device) : null
+  },
+  buildLog: async ({ result, snapshots }) => {
+    const before = (snapshots.before as DeviceSnapshot | undefined) ?? null
+    const after = (snapshots.after as DeviceSnapshot | undefined) ?? null
+    return {
+      actionLabel: before ? 'Update device' : 'Register device',
+      resourceKind: 'devices.user_device',
+      resourceId: result.id,
+      tenantId: after?.tenantId ?? before?.tenantId ?? null,
+      organizationId: after?.organizationId ?? before?.organizationId ?? null,
+      snapshotBefore: before,
+      snapshotAfter: after,
+      payload: {
+        undo: { before, after } satisfies DeviceUndoPayload,
+      },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<DeviceUndoPayload>(logEntry)
+    const after = payload?.after
+    if (!after) return
+    const before = payload?.before ?? null
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const device = await findOneWithDecryption(em, UserDevice, { id: after.id })
+    if (!device) return
+
+    await withAtomicFlush(
+      em,
+      [
+        () => {
+          if (before) {
+            // Upsert/revive: restore the prior row state.
+            applySnapshot(device, before)
+          } else {
+            // Fresh registration: undo by soft-deleting the created row.
+            device.deletedAt = new Date()
+          }
+        },
+      ],
+      { transaction: true },
+    )
+
+    const de = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudUndoSideEffects({
+      dataEngine: de,
+      action: before ? 'updated' : 'deleted',
+      entity: device,
+      identifiers: {
+        id: device.id,
+        tenantId: device.tenantId,
+        organizationId: device.organizationId ?? null,
+      },
+      indexer: deviceIndexer,
+      events: deviceEvents,
+    })
+  },
+}
+
+registerCommand(registerDeviceCommand)

package/src/modules/devices/commands/shared.ts

@@ -0,0 +1,119 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { UniqueConstraintViolationException } from '@mikro-orm/core'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { CrudEventsConfig, CrudIndexerConfig } from '@open-mercato/shared/lib/crud/types'
+import { E } from '#generated/entities.ids.generated'
+import { UserDevice } from '../data/entities'
+
+export type DeviceSnapshot = {
+  id: string
+  tenantId: string
+  organizationId: string | null
+  userId: string
+  deviceId: string
+  platform: string
+  clientAppVersion: string | null
+  osVersion: string | null
+  locale: string | null
+  // Last-8 fingerprint of the push token — NEVER the plaintext. Audit snapshots and the undo payload
+  // both persist to `action_logs` (no TTL, never purged, and `persistLog` permits a null tenantId the
+  // encryption subscriber skips), so storing the real token there would leak a device credential
+  // forever. The live encrypted column is the single source of truth; undo re-reads it (see applySnapshot).
+  pushTokenFingerprint: string | null
+  pushProvider: string | null
+  pushTokenUpdatedAt: string | null
+  lastSeenAt: string
+  deletedAt: string | null
+}
+
+export type DeviceUndoPayload = {
+  before?: DeviceSnapshot | null
+  after?: DeviceSnapshot | null
+}
+
+export const deviceIndexer: CrudIndexerConfig<UserDevice> = {
+  entityType: E.devices.user_device,
+}
+
+export const deviceEvents: CrudEventsConfig<UserDevice> = {
+  module: 'devices',
+  entity: 'user_device',
+  persistent: true,
+  buildPayload: (ctx) => ({
+    id: ctx.identifiers.id,
+    tenantId: ctx.identifiers.tenantId,
+    organizationId: ctx.identifiers.organizationId,
+  }),
+}
+
+function toDate(value: string | null | undefined): Date | null {
+  if (!value) return null
+  const date = new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+// Persist at most the last 8 chars of the (long) provider token — never the full secret. Mirrors the
+// delivery log's `token_snapshot` (push-fanout.ts) so audit/undo carry a stable, non-sensitive fingerprint.
+function fingerprintPushToken(token: string | null): string | null {
+  return token ? token.slice(-8) : null
+}
+
+export function serializeDevice(device: UserDevice): DeviceSnapshot {
+  return {
+    id: device.id,
+    tenantId: device.tenantId,
+    organizationId: device.organizationId ?? null,
+    userId: device.userId,
+    deviceId: device.deviceId,
+    platform: device.platform,
+    clientAppVersion: device.clientAppVersion ?? null,
+    osVersion: device.osVersion ?? null,
+    locale: device.locale ?? null,
+    pushTokenFingerprint: fingerprintPushToken(device.pushToken ?? null),
+    pushProvider: device.pushProvider ?? null,
+    pushTokenUpdatedAt: device.pushTokenUpdatedAt ? device.pushTokenUpdatedAt.toISOString() : null,
+    lastSeenAt: device.lastSeenAt.toISOString(),
+    deletedAt: device.deletedAt ? device.deletedAt.toISOString() : null,
+  }
+}
+
+export function applySnapshot(device: UserDevice, snapshot: DeviceSnapshot): void {
+  device.platform = snapshot.platform as UserDevice['platform']
+  device.clientAppVersion = snapshot.clientAppVersion
+  device.osVersion = snapshot.osVersion
+  device.locale = snapshot.locale
+  // The push credential triple (token, provider, token_updated_at) is deliberately NOT restored from a
+  // snapshot. The snapshot carries only a fingerprint, and the token is a device-issued credential whose
+  // live encrypted column is authoritative — undo preserves whatever token the device currently holds.
+  // Restoring a stale token, or the redacted/undecryptable placeholder a snapshot could otherwise carry,
+  // would unrecoverably brick delivery. Reverting metadata is safe; reverting the secret is not.
+  device.lastSeenAt = toDate(snapshot.lastSeenAt) ?? new Date()
+  device.deletedAt = toDate(snapshot.deletedAt)
+}
+
+export async function loadExistingDevice(
+  em: EntityManager,
+  // organizationId is part of the device identity (a null value matches IS NULL, mirroring the
+  // coalesce(...) bucket in the unique index), so a device is looked up per (tenant, org, user, device).
+  scope: { tenantId: string; organizationId: string | null; userId: string; deviceId: string },
+): Promise<UserDevice | null> {
+  // push_token is encrypted at rest; decrypt on read so snapshots/undo payloads keep the plaintext.
+  const dscope = { tenantId: scope.tenantId, organizationId: scope.organizationId }
+  const active = await findOneWithDecryption(em, UserDevice, { ...scope, deletedAt: null }, undefined, dscope)
+  if (active) return active
+  return findOneWithDecryption(em, UserDevice, scope, { orderBy: { createdAt: 'desc' } }, dscope)
+}
+
+// Postgres SQLSTATE for unique_violation. MikroORM doesn't re-export pg error codes, so name it here.
+const PG_UNIQUE_VIOLATION = '23505'
+
+// A concurrent first-registration of the same (tenant, org, user, device_id) loses the race against the
+// partial unique index. Surface it as a 409 conflict instead of a raw 500 — the endpoint is an
+// idempotent upsert, so the caller can simply re-issue the request to land on the existing row.
+export function isDeviceUniqueViolation(error: unknown): boolean {
+  if (error instanceof UniqueConstraintViolationException) return true
+  if (!error || typeof error !== 'object') return false
+  if ((error as { code?: string }).code === PG_UNIQUE_VIOLATION) return true
+  const message = (error as { message?: string }).message
+  return typeof message === 'string' && message.toLowerCase().includes('duplicate key')
+}

package/src/modules/devices/commands/update.ts

@@ -0,0 +1,142 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { registerCommand, type CommandHandler } from '@open-mercato/shared/lib/commands'
+import { ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
+import { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
+import { emitCrudSideEffects, emitCrudUndoSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { assertFound } from '@open-mercato/shared/lib/crud/errors'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { UserDevice } from '../data/entities'
+import { updateDeviceCommandSchema, type UpdateDeviceCommandInput } from '../data/validators'
+import {
+  applySnapshot,
+  deviceEvents,
+  deviceIndexer,
+  serializeDevice,
+  type DeviceSnapshot,
+  type DeviceUndoPayload,
+} from './shared'
+
+const updateDeviceCommand: CommandHandler<UpdateDeviceCommandInput, { id: string }> = {
+  id: 'devices.user_devices.update',
+  async prepare(rawInput, ctx) {
+    const parsed = updateDeviceCommandSchema.parse(rawInput)
+    // Enforce tenant scope and constrain the snapshot lookup to the caller's tenant.
+    ensureTenantScope(ctx, parsed.tenantId)
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    // No fallback decryption scope: `UserDevice` always carries its own organization_id, which
+    // `decryptEntitiesWithFallbackScope` resolves first — matching the scope-less lookup in execute().
+    const device = await findOneWithDecryption(
+      em,
+      UserDevice,
+      { id: parsed.id, tenantId: parsed.tenantId, deletedAt: null },
+    )
+    return device ? { before: serializeDevice(device) } : {}
+  },
+  async execute(rawInput, ctx) {
+    const parsed = updateDeviceCommandSchema.parse(rawInput)
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const device = assertFound(
+      await findOneWithDecryption(em, UserDevice, { id: parsed.id, deletedAt: null }),
+      'Device not found',
+    )
+    ensureTenantScope(ctx, device.tenantId)
+
+    const now = new Date()
+    await withAtomicFlush(
+      em,
+      [
+        () => {
+          if (Object.prototype.hasOwnProperty.call(parsed, 'clientAppVersion')) {
+            device.clientAppVersion = parsed.clientAppVersion ?? null
+          }
+          if (Object.prototype.hasOwnProperty.call(parsed, 'osVersion')) {
+            device.osVersion = parsed.osVersion ?? null
+          }
+          if (Object.prototype.hasOwnProperty.call(parsed, 'locale')) {
+            device.locale = parsed.locale ?? null
+          }
+          if (Object.prototype.hasOwnProperty.call(parsed, 'pushToken')) {
+            device.pushToken = parsed.pushToken ?? null
+            device.pushTokenUpdatedAt = now
+          }
+          if (Object.prototype.hasOwnProperty.call(parsed, 'pushProvider')) {
+            device.pushProvider = parsed.pushProvider ?? null
+          }
+          // Only a client-supplied lastSeenAt advances presence. Metadata-only edits (e.g. an admin
+          // changing push_provider) must NOT bump last_seen_at — device presence is maintained by the
+          // register heartbeat, not by edits.
+          if (Object.prototype.hasOwnProperty.call(parsed, 'lastSeenAt') && parsed.lastSeenAt) {
+            device.lastSeenAt = parsed.lastSeenAt
+          }
+        },
+      ],
+      { transaction: true },
+    )
+
+    const de = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudSideEffects({
+      dataEngine: de,
+      action: 'updated',
+      entity: device,
+      identifiers: {
+        id: device.id,
+        tenantId: device.tenantId,
+        organizationId: device.organizationId ?? null,
+      },
+      indexer: deviceIndexer,
+      events: deviceEvents,
+    })
+
+    return { id: device.id }
+  },
+  captureAfter: async (_input, result, ctx) => {
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const device = await findOneWithDecryption(em, UserDevice, { id: result.id })
+    return device ? serializeDevice(device) : null
+  },
+  buildLog: async ({ snapshots }) => {
+    const before = (snapshots.before as DeviceSnapshot | undefined) ?? null
+    if (!before) return null
+    const after = (snapshots.after as DeviceSnapshot | undefined) ?? null
+    return {
+      actionLabel: 'Update device',
+      resourceKind: 'devices.user_device',
+      resourceId: before.id,
+      tenantId: before.tenantId,
+      organizationId: before.organizationId,
+      snapshotBefore: before,
+      snapshotAfter: after,
+      payload: {
+        undo: { before, after } satisfies DeviceUndoPayload,
+      },
+    }
+  },
+  undo: async ({ logEntry, ctx }) => {
+    const payload = extractUndoPayload<DeviceUndoPayload>(logEntry)
+    const before = payload?.before
+    if (!before) return
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const device = await findOneWithDecryption(em, UserDevice, { id: before.id })
+    if (!device) return
+
+    await withAtomicFlush(em, [() => applySnapshot(device, before)], { transaction: true })
+
+    const de = ctx.container.resolve('dataEngine') as DataEngine
+    await emitCrudUndoSideEffects({
+      dataEngine: de,
+      action: 'updated',
+      entity: device,
+      identifiers: {
+        id: device.id,
+        tenantId: device.tenantId,
+        organizationId: device.organizationId ?? null,
+      },
+      indexer: deviceIndexer,
+      events: deviceEvents,
+    })
+  },
+}
+
+registerCommand(updateDeviceCommand)

package/src/modules/devices/data/entities.ts

@@ -0,0 +1,79 @@
+import { OptionalProps } from '@mikro-orm/core'
+import { Entity, Index, PrimaryKey, Property } from '@mikro-orm/decorators/legacy'
+
+export type DevicePlatform = 'ios' | 'android' | 'web'
+
+@Entity({ tableName: 'user_devices' })
+@Index({ name: 'user_devices_tenant_user_idx', properties: ['tenantId', 'userId'] })
+@Index({
+  // Device identity is scoped per organization: (tenant, org, user, device). organization_id is
+  // nullable, so the index is declared NULLS NOT DISTINCT — otherwise Postgres treats NULLs as
+  // distinct and would allow duplicate null-org rows for the same (tenant, user, device).
+  name: 'user_devices_tenant_org_user_device_active_unique',
+  expression:
+    'create unique index "user_devices_tenant_org_user_device_active_unique" on "user_devices" ("tenant_id", "organization_id", "user_id", "device_id") nulls not distinct where deleted_at is null',
+})
+export class UserDevice {
+  [OptionalProps]?:
+    | 'organizationId'
+    | 'clientAppVersion'
+    | 'osVersion'
+    | 'locale'
+    | 'pushToken'
+    | 'pushProvider'
+    | 'pushTokenUpdatedAt'
+    | 'lastSeenAt'
+    | 'createdAt'
+    | 'updatedAt'
+    | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid', nullable: true })
+  organizationId?: string | null
+
+  @Property({ name: 'user_id', type: 'uuid' })
+  userId!: string
+
+  @Property({ name: 'device_id', type: 'text' })
+  deviceId!: string
+
+  @Property({ name: 'platform', type: 'text' })
+  platform!: DevicePlatform
+
+  @Property({ name: 'client_app_version', type: 'text', nullable: true })
+  clientAppVersion?: string | null
+
+  @Property({ name: 'os_version', type: 'text', nullable: true })
+  osVersion?: string | null
+
+  // Per-device language the client app picked (BCP-47, e.g. `en` / `en-US`). Normalized to a
+  // supported locale at push send time to translate the notification copy; null ⇒ default locale.
+  @Property({ name: 'locale', type: 'text', nullable: true })
+  locale?: string | null
+
+  @Property({ name: 'push_token', type: 'text', nullable: true })
+  pushToken?: string | null
+
+  @Property({ name: 'push_provider', type: 'text', nullable: true })
+  pushProvider?: string | null
+
+  @Property({ name: 'push_token_updated_at', type: Date, nullable: true })
+  pushTokenUpdatedAt?: Date | null
+
+  @Property({ name: 'last_seen_at', type: Date, onCreate: () => new Date() })
+  lastSeenAt: Date = new Date()
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onCreate: () => new Date(), onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}

package/src/modules/devices/data/validators.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod'
+
+export const devicePlatformSchema = z.enum(['ios', 'android', 'web'])
+export type DevicePlatformInput = z.infer<typeof devicePlatformSchema>
+
+// POST /api/devices — register/upsert. pushToken/pushProvider optional on first register.
+export const registerDeviceSchema = z
+  .object({
+    deviceId: z.string().trim().min(1).max(255),
+    platform: devicePlatformSchema,
+    clientAppVersion: z.string().trim().max(64).nullish(),
+    osVersion: z.string().trim().max(64).nullish(),
+    locale: z.string().trim().min(2).max(35).nullish(),
+    pushToken: z.string().trim().min(1).max(4096).nullish(),
+    pushProvider: z.string().trim().min(1).max(32).nullish(),
+  })
+  .strict()
+export type RegisterDeviceInput = z.infer<typeof registerDeviceSchema>
+
+// POST /api/devices/admin/devices — admin registers a device on behalf of any user in the tenant.
+// Same shape as self-register plus an explicit target userId (self-register derives it from auth).
+export const registerDeviceAdminSchema = registerDeviceSchema.extend({
+  userId: z.string().uuid(),
+})
+export type RegisterDeviceAdminInput = z.infer<typeof registerDeviceAdminSchema>
+
+// PUT /api/devices/:id — partial update.
+// pushToken/pushProvider are tri-state: absent (leave unchanged) vs explicit null (clear).
+// `.nullable().optional()` distinguishes `undefined` from `null`; the command relies on
+// own-property presence to decide whether to touch the column.
+export const updateDeviceSchema = z
+  .object({
+    clientAppVersion: z.string().trim().max(64).nullable().optional(),
+    osVersion: z.string().trim().max(64).nullable().optional(),
+    locale: z.string().trim().min(2).max(35).nullable().optional(),
+    pushToken: z.string().trim().min(1).max(4096).nullable().optional(),
+    pushProvider: z.string().trim().min(1).max(32).nullable().optional(),
+    lastSeenAt: z.coerce.date().optional(),
+  })
+  .strict()
+export type UpdateDeviceInput = z.infer<typeof updateDeviceSchema>
+
+// Command-side schemas append the resolved scope. Scope fields are never accepted from the client body.
+export const registerDeviceCommandSchema = registerDeviceSchema.extend({
+  tenantId: z.string().uuid(),
+  organizationId: z.string().uuid().nullable().optional(),
+  userId: z.string().uuid(),
+})
+export type RegisterDeviceCommandInput = z.infer<typeof registerDeviceCommandSchema>
+
+export const updateDeviceCommandSchema = updateDeviceSchema.extend({
+  id: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  userId: z.string().uuid(),
+  organizationId: z.string().uuid().nullable().optional(),
+})
+export type UpdateDeviceCommandInput = z.infer<typeof updateDeviceCommandSchema>
+
+export const deactivateDeviceCommandSchema = z.object({
+  id: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  userId: z.string().uuid(),
+  organizationId: z.string().uuid().nullable().optional(),
+})
+export type DeactivateDeviceCommandInput = z.infer<typeof deactivateDeviceCommandSchema>

package/src/modules/devices/di.ts

@@ -0,0 +1,9 @@
+import { asValue } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { UserDevice } from './data/entities'
+
+export function register(container: AppContainer) {
+  container.register({
+    UserDevice: asValue(UserDevice),
+  })
+}

package/src/modules/devices/encryption.ts

@@ -0,0 +1,15 @@
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+// `push_token` is a long-lived provider secret. It is never exposed via the API (only a last-8
+// snapshot is persisted on delivery rows) and is redacted from audit-log snapshots, so it is
+// encrypted at rest. Reads route through `findWithDecryption`/`findOneWithDecryption` per the
+// `packages/core/AGENTS.md` Encryption section. No blind-index column is needed: the push delivery
+// path looks devices up by id/user, never by token value.
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: 'devices:user_device',
+    fields: [{ field: 'push_token' }],
+  },
+]
+
+export default defaultEncryptionMaps

package/src/modules/devices/events.ts

@@ -0,0 +1,16 @@
+import { createModuleEvents } from '@open-mercato/shared/modules/events'
+
+const events = [
+  // Domain events (spec contract): emitted explicitly from commands.
+  { id: 'devices.user_device.registered', label: 'User Device Registered', entity: 'user_device', category: 'crud' },
+  { id: 'devices.user_device.deactivated', label: 'User Device Deactivated', entity: 'user_device', category: 'crud' },
+  // CRUD lifecycle events emitted by emitCrudSideEffects (keep declared to avoid undeclared-event warnings).
+  { id: 'devices.user_device.created', label: 'User Device Created', entity: 'user_device', category: 'crud' },
+  { id: 'devices.user_device.updated', label: 'User Device Updated', entity: 'user_device', category: 'crud' },
+  { id: 'devices.user_device.deleted', label: 'User Device Deleted', entity: 'user_device', category: 'crud' },
+] as const
+
+export const eventsConfig = createModuleEvents({ moduleId: 'devices', events })
+export const emitDevicesEvent = eventsConfig.emit
+export type DevicesEventId = typeof events[number]['id']
+export default eventsConfig