# Register Device Endpoint

**Task**: AZ-196_register_device_endpoint
**Name**: POST /devices endpoint for auto device registration
**Description**: Add POST /devices endpoint to admin API that auto-generates device serial, email, and password for CompanionPC users
**Complexity**: 2 points
**Dependencies**: None
**Component**: Admin API
**Tracker**: AZ-196
**Epic**: AZ-181

## Problem

During Jetson manufacturing, each device needs a unique CompanionPC identity (serial, email, password). Currently the provisioning script generates the email client-side and calls POST /users. The serial/email format should be server-controlled so the admin API is the single source of truth for device numbering.

## Outcome

- Single POST /devices endpoint that requires no request body
- Server auto-assigns the next sequential serial (azj-0000, azj-0001, ...)
- Returns plaintext credentials so the provisioning script can embed them in device.conf

## Scope

### Included

- `RegisterDeviceResponse` DTO in `Azaion.Common/Requests/` with `Serial`, `Email`, `Password` fields
- `RegisterDevice` method on `IUserService` / `UserService`
- `POST /devices` endpoint in `Program.cs` with `RequireAuthorization(apiAdminPolicy)`
- Sequential serial assignment based on most recent CompanionPC user

### Excluded

- Changes to the provisioning shell script (handled in loader repo)
- Removing old POST /users endpoint (still used for non-device users)

## Implementation Details

### Serial number logic

Email format: `azj-NNNN@azaion.com` where NNNN is zero-padded to 4 digits.

Constants at the top of `UserService`:

```csharp
private const int SerialNumberStart = 4;
private const int SerialNumberLength = 4;
```

`RegisterDevice` implementation:

1. Query the single most recent CompanionPC user: `WHERE role = 'CompanionPC' ORDER BY created_at DESC LIMIT 1`
2. If none found, next number is 0000; otherwise extract via `Substring(SerialNumberStart, SerialNumberLength)`, parse, increment
3. Generate email `azj-{number:D4}@azaion.com`
4. Generate random 32-char hex password: `Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLower()`
5. Insert User with `Role = CompanionPC`, `IsEnabled = true`, password hashed via `ToHash()`
6. Return `RegisterDeviceResponse { Serial, Email, Password (plaintext) }`

### Endpoint

```csharp
app.MapPost("/devices",
    async (IUserService userService, CancellationToken cancellationToken)
        => await userService.RegisterDevice(cancellationToken))
    .RequireAuthorization(apiAdminPolicy)
    .WithSummary("Creates a new device");
```

No request body required.

## Acceptance Criteria

**AC-1: First device gets serial azj-0000**
Given no CompanionPC users exist in the database
When POST /devices is called with a valid ApiAdmin JWT
Then the response contains `serial: "azj-0000"`, `email: "azj-0000@azaion.com"`, and a 32-char hex password

**AC-2: Sequential numbering**
Given azj-0000 already exists
When POST /devices is called again
Then the response contains `serial: "azj-0001"`

**AC-3: User persisted with correct role**
Given POST /devices returned successfully
When the users table is queried
Then a user exists with the returned email, Role=CompanionPC, IsEnabled=true

**AC-4: Password is hashed in DB**
Given POST /devices returned a plaintext password
When the users table is inspected
Then PasswordHash contains the SHA-384 hash of the plaintext password, not the plaintext itself

**AC-5: Requires ApiAdmin authorization**
Given a request without a JWT or with a non-ApiAdmin JWT
When POST /devices is called
Then 401 or 403 is returned