platform-codebase/features/platform-admin/backend-api/src/devices

Devices Module

This module manages device authorization for macOS desktop clients connecting to the Lilith Platform.

Overview

The Devices module provides endpoints for:

• Listing all devices for the authenticated user
• Authorizing devices to sync with the platform
• Revoking device authorization

API Endpoints

All endpoints require authentication with JwtAuthGuard and AdminGuard.

GET /api/devices

List all devices for the current authenticated user.

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "550e8400-e29b-41d4-a716-446655440001",
    "deviceId": "mac-book-pro-2021",
    "deviceName": "Lilith's MacBook Pro",
    "isAuthorized": false,
    "authCode": "123456",
    "lastSyncAt": null,
    "createdAt": "2026-01-04T10:00:00Z"
  }
]

POST /api/devices/:id/authorize

Authorize a device for syncing. Sets isAuthorized to true and clears the authCode.

Parameters:

• id (UUID) - Device ID

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "deviceId": "mac-book-pro-2021",
  "deviceName": "Lilith's MacBook Pro",
  "isAuthorized": true,
  "authCode": null,
  "lastSyncAt": null,
  "createdAt": "2026-01-04T10:00:00Z"
}

POST /api/devices/:id/revoke

Revoke device authorization. Sets isAuthorized to false and generates a new authCode.

Parameters:

• id (UUID) - Device ID

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "deviceId": "mac-book-pro-2021",
  "deviceName": "Lilith's MacBook Pro",
  "isAuthorized": false,
  "authCode": "789012",
  "lastSyncAt": "2026-01-04T10:30:00Z",
  "createdAt": "2026-01-04T10:00:00Z"
}

Database Schema

Table: devices

Column	Type	Constraints	Description
id	UUID	PRIMARY KEY	Device record ID
userId	UUID	NOT NULL, INDEXED	User who owns the device
deviceId	VARCHAR(255)	NOT NULL, UNIQUE	Device identifier
deviceName	VARCHAR(255)	NOT NULL	Human-readable device name
isAuthorized	BOOLEAN	DEFAULT false	Authorization status
authCode	VARCHAR(6)	NULLABLE	6-digit pairing code
lastSyncAt	TIMESTAMP	NULLABLE	Last sync timestamp
createdAt	TIMESTAMP	DEFAULT NOW()	Registration timestamp

Indexes:

• IDX_devices_userId - Index on userId for fast user queries
• IDX_devices_deviceId - Unique index on deviceId to prevent duplicates

Database Setup

1. Start the database:

   docker-compose up -d
   

2. Run migrations:

   cd codebase/features/platform-admin/backend-api
   npm run migration:run
   

3. Environment variables: Create .env from .env.example:

   cp .env.example .env
   

Architecture

devices/
├── device.entity.ts          # TypeORM entity
├── devices.controller.ts     # HTTP endpoints
├── devices.service.ts        # Business logic
├── devices.module.ts         # NestJS module
├── dto/
│   ├── device-response.dto.ts  # Response type
│   └── index.ts
└── README.md

Authorization Flow

1. Device Registration (not implemented yet)

   • Desktop client sends device info
   • Server creates device record with isAuthorized=false and generates authCode
   • Returns authCode to display in desktop app

2. Authorization

   • User sees device in admin panel with authCode
   • User calls POST /api/devices/:id/authorize
   • Device can now sync with platform

3. Revocation

   • User calls POST /api/devices/:id/revoke
   • Device loses sync access
   • New authCode generated for re-authorization

Security Considerations

• All endpoints require JWT authentication
• Devices are scoped to user ID (users can only see/manage their own devices)
• Device IDs must be UUIDs (validated with ParseUUIDPipe)
• Auth codes are 6-digit random numbers (100000-999999)