### Create and Start TCP Server

Source: https://context7.com/ggmolly/belfast/llms.txt

Creates a `Server` that accepts concurrent game-client connections, reads framed protobuf packets, and dispatches them. Use `Run()` to start the server; it blocks until a fatal error occurs. Graceful shutdown can be initiated with `DisconnectAll`.

```go
server := connection.NewServer(
    "0.0.0.0",         // bind address
    7000,              // port
    packets.Dispatch,  // dispatcher called per received frame
)
server.SetMaintenance(false)
server.SetRequirePrivateClients(true) // only allow RFC-1918 IPs

if err := server.Run(); err != nil { // blocks until fatal error
    log.Fatal(err)
}
```

```go
// Graceful shutdown — send SC_10999 to all clients then stop
server.DisconnectAll(consts.DR_CONNECTION_TO_SERVER_LOST)
```

```go
// Runtime toggles (safe for concurrent use)
server.SetAcceptingConnections(false) // stops new connections, disconnects existing
server.SetMaintenance(true)           // same effect + maintenance reason code
server.SetAcceptingConnections(true)  // re-open
```

```go
// Inspect live state
fmt.Println(server.ClientCount())    // number of active TCP connections
clients := server.ListClients()      // []*connection.Client snapshot
```

```go
// Kick a specific commander (e.g. duplicate login)
kicked := server.DisconnectCommander(commanderID, consts.DR_DUPLICATE_LOGIN, nil)
```

```go
// Chat room management
server.JoinRoom(roomID, client)
server.LeaveRoom(roomID, client)
server.SendMessage(sender, orm.Message{RoomID: roomID, Content: "hello"})
```

--------------------------------

### Webhook Server Setup and Usage

Source: https://context7.com/ggmolly/belfast/llms.txt

Set up and run a webhook server to listen for GitHub push events, regenerate progress PNGs, and verify signatures. Requires Go and OpenSSL.

```bash
# Environment variables
export WEBHOOK_SECRET="your-github-webhook-secret"
export WEBHOOK_HOST="0.0.0.0"
export WEBHOOK_PORT="8080"
export WEBHOOK_PNG_PATH="/srv/cdn/belfast/implem.png"
export WEBHOOK_FONT_FAMILY="monospace"
export WEBHOOK_SSH_KEY="/home/belfast/.ssh/id_ed25519"   # optional SSH key for git pull

go run ./cmd/webhook_server

# Health check
curl http://localhost:8080/health
# {"status":"ok"}

# GitHub sends POST /webhook with X-Hub-Signature-256 header automatically
# Manual trigger (with correct HMAC):
PAYLOAD='{"ref":"refs/heads/main"}'
SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | sed 's/.*= //')
curl -X POST http://localhost:8080/webhook \
  -H "X-Hub-Signature-256: sha256=${SIG}" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"
# {"status":"queued"}
```

--------------------------------

### connection.NewServer

Source: https://context7.com/ggmolly/belfast/llms.txt

Creates and starts a multiplexed TCP server that accepts concurrent game-client connections and dispatches packets.

```APIDOC
## connection.NewServer

### Description
Creates a `Server` that accepts concurrent game-client connections, reads framed protobuf packets from a ring buffer, and dispatches them via the registered `ServerDispatcher`.

### Usage
```go
server := connection.NewServer(
    bindAddress string,
    port int,
    dispatcher packets.ServerDispatcher, // e.g., packets.Dispatch
)
server.SetMaintenance(false)
server.SetRequirePrivateClients(true)

if err := server.Run(); err != nil { // blocks until fatal error
    log.Fatal(err)
}
```

### Parameters
- **bindAddress** (string): The address to bind the server to (e.g., "0.0.0.0").
- **port** (int): The port number to listen on (e.g., 7000).
- **dispatcher** (packets.ServerDispatcher): A function called for each received packet frame.

### Methods
- **SetMaintenance(bool)**: Enables or disables server maintenance mode.
- **SetRequirePrivateClients(bool)**: If true, only allows RFC-1918 IP addresses.
- **Run() error**: Starts the server and blocks until a fatal error occurs.
- **DisconnectAll(reason int)**: Sends a disconnect message to all clients and stops the server.
- **SetAcceptingConnections(bool)**: Starts or stops accepting new connections.
- **ClientCount() int**: Returns the number of active TCP connections.
- **ListClients() []*connection.Client**: Returns a snapshot of active clients.
- **DisconnectCommander(commanderID string, reason int, msg proto.Message)**: Kicks a specific commander.
- **JoinRoom(roomID string, client *connection.Client)**: Adds a client to a chat room.
- **LeaveRoom(roomID string, client *connection.Client)**: Removes a client from a chat room.
- **SendMessage(sender *connection.Client, message orm.Message)**: Sends a chat message to a room.
```

--------------------------------

### Get Passkey Authentication Options

Source: https://context7.com/ggmolly/belfast/llms.txt

Requests assertion options for passkey authentication (passwordless login). This is the first step in the passkey authentication flow.

```APIDOC
## POST /api/v1/auth/passkeys/authenticate/options

### Description
Requests assertion options for passkey authentication (passwordless login). This is the first step in the passkey authentication flow.

### Method
POST

### Endpoint
/api/v1/auth/passkeys/authenticate/options

### Parameters
#### Request Body
- **username** (string) - Required - The username of the user attempting to authenticate.

### Request Example
```bash
curl -X POST http://localhost:2289/api/v1/auth/passkeys/authenticate/options \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin"}'
```

### Response
#### Success Response (200)
- Returns `PublicKeyCredentialRequestOptions` object, which is used by the browser's WebAuthn API to initiate the passkey authentication process.
```

--------------------------------

### Get Server Metrics

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves performance metrics for the server. Requires administrator privileges.

```APIDOC
## GET /api/v1/server/metrics

### Description
Retrieves performance metrics for the server. Requires administrator privileges.

### Method
GET

### Endpoint
/api/v1/server/metrics

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains server performance metrics.
  - **client_count** (integer) - The number of currently connected clients.
  - **queue_max** (integer) - The maximum queue size.
  - **queue_blocks** (integer) - The number of blocked queue entries.
  - **handler_errors** (integer) - The number of handler errors.
  - **write_errors** (integer) - The number of write errors.
  - **packets_per_sec** (number) - The average number of packets processed per second.

### Request Example
```bash
curl -b cookies.txt http://localhost:2289/api/v1/server/metrics
```

### Response Example
```json
{"success":true,"data":{
  "client_count":3,
  "queue_max":8,
  "queue_blocks":0,
  "handler_errors":0,
  "write_errors":0,
  "packets_per_sec":12.5
}}
```
```

--------------------------------

### Belfast Game Server Configuration

Source: https://context7.com/ggmolly/belfast/llms.txt

Example TOML configuration for the Belfast game server. Specifies bind address, port, name, database connection details, and API settings.

```toml
[belfast]
bind_address = "0.0.0.0"
port         = 7000
name         = "Belfast"
# maintenance  = false
# require_private_clients = false   # set true to block non-LAN connections

[region]
default = "EN"   # CN | EN | JP | KR | TW

[db]
dsn         = "postgres://user:pass@localhost:5432/belfast"
schema_name = "public"

[api]
enabled  = true
port     = 2289
# cors_origins = ["https://belfast-web.example.com"]

[auth]
session_ttl_hours     = 72
rate_limit_login_max  = 10
webauthn_rpid         = "belfast.example.com"
webauthn_origins      = ["https://belfast.example.com"]
```

--------------------------------

### Get Passkey Authentication Options

Source: https://context7.com/ggmolly/belfast/llms.txt

Obtains assertion options for passkey-based authentication. Requires the username for which to authenticate. The response is used by the browser's WebAuthn API to initiate the authentication challenge.

```bash
# 3. Authenticate with passkey (passwordless login)
# Step A — get assertion options
curl -X POST http://localhost:2289/api/v1/auth/passkeys/authenticate/options \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin"}'
```

--------------------------------

### Get Server Status

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves the current status of the Belfast server, including uptime and client count. No authentication is required.

```bash
curl http://localhost:2289/api/v1/server/status
# {
#   "success": true,
#   "data": {
#     "name": "Belfast",
#     "commit": "abc1234",
#     "running": true,
#     "accepting": true,
#     "maintenance": false,
#     "uptime_sec": 3600,
#     "uptime_human": "1h0m0s",
#     "client_count": 5
#   }
# }
```

--------------------------------

### Get Server Performance Metrics

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves detailed server performance metrics, including client count, queue status, and packet rates. Requires an active session cookie.

```bash
curl -b cookies.txt http://localhost:2289/api/v1/server/metrics
# {"success":true,"data":{
#   "client_count":3,
#   "queue_max":8,
#   "queue_blocks":0,
#   "handler_errors":0,
#   "write_errors":0,
#   "packets_per_sec":12.5
# }}
```

--------------------------------

### Get Server Status

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves the current status of the Belfast server, including uptime and client count. This endpoint is publicly accessible.

```APIDOC
## GET /api/v1/server/status

### Description
Retrieves the current status of the Belfast server, including uptime and client count. This endpoint is publicly accessible.

### Method
GET

### Endpoint
/api/v1/server/status

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains server status details.
  - **name** (string) - The name of the server.
  - **commit** (string) - The current git commit hash.
  - **running** (boolean) - Whether the server is running.
  - **accepting** (boolean) - Whether the server is accepting new connections.
  - **maintenance** (boolean) - Whether maintenance mode is enabled.
  - **uptime_sec** (integer) - Server uptime in seconds.
  - **uptime_human** (string) - Server uptime in a human-readable format.
  - **client_count** (integer) - The number of connected clients.

### Request Example
```bash
curl http://localhost:2289/api/v1/server/status
```

### Response Example
```json
{
  "success": true,
  "data": {
    "name": "Belfast",
    "commit": "abc1234",
    "running": true,
    "accepting": true,
    "maintenance": false,
    "uptime_sec": 3600,
    "uptime_human": "1h0m0s",
    "client_count": 5
  }
}
```
```

--------------------------------

### Register Localized Packet Handlers

Source: https://context7.com/ggmolly/belfast/llms.txt

Registers different handler sets for specific server regions. The 'Default' slot acts as a fallback for regions not explicitly defined. Only the slice matching the active server region is installed.

```go
packets.RegisterLocalizedPacketHandler(13101, packets.LocalizedHandler{
    CN: &[]packets.PacketHandler{answer.ChapterTracking},
    EN: &[]packets.PacketHandler{answer.ChapterTracking},
    JP: &[]packets.PacketHandler{answer.ChapterTracking},
    KR: &[]packets.PacketHandler{answer.ChapterTrackingKR}, // KR uses different handler
    TW: &[]packets.PacketHandler{answer.ChapterTracking},
})
```

```go
packets.RegisterLocalizedPacketHandler(10802, packets.LocalizedHandler{
    CN: &[]packets.PacketHandler{answer.BuildServerInterconnectionResponse},
    TW: &[]packets.PacketHandler{answer.BuildServerInterconnectionResponse},
    JP: &[]packets.PacketHandler{answer.BuildServerInterconnectionResponse},
    KR: &[]packets.PacketHandler{answer.BuildServerInterconnectionResponse},
    // EN has no entry; if Default were set it would be used instead
})
```

--------------------------------

### Create First Admin User

Source: https://context7.com/ggmolly/belfast/llms.txt

Initializes the server by creating the first administrator account. This is a one-time operation and will return a 409 error if an admin already exists. Requires username and password in the JSON payload.

```bash
curl -c cookies.txt -X POST http://localhost:2289/api/v1/auth/bootstrap \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "supersecret"}'
# Returns 409 if an admin already exists
```

--------------------------------

### Run Gateway Server

Source: https://context7.com/ggmolly/belfast/llms.txt

Launches the gateway server. Supports specifying a custom configuration file path.

```bash
# Default config path: gateway.toml
./bin/gateway
```

```bash
# Custom config
./bin/gateway --config /etc/belfast/gateway.toml
```

--------------------------------

### Build Belfast Binaries

Source: https://context7.com/ggmolly/belfast/llms.txt

Builds the game server and gateway binaries. Use COMMIT to embed git hash. Cross-compile for Windows using GOOS. Run with 'air' for hot-reloading.

```bash
# Build game server + gateway (outputs to bin/)
make build
```

```bash
# With embedded git commit in status responses
COMMIT=$(git rev-parse --short HEAD) make build
```

```bash
# Cross-compile for Windows
GOOS=windows make build
```

```bash
# Run game server with hot-reload (uses air)
air
```

--------------------------------

### Bootstrap First Admin

Source: https://context7.com/ggmolly/belfast/llms.txt

Creates the first administrator account on a new server. This is a one-time operation and will return a 409 conflict if an admin already exists.

```APIDOC
## POST /api/v1/auth/bootstrap

### Description
Creates the first administrator account on a new server. This is a one-time operation and will return a 409 conflict if an admin already exists.

### Method
POST

### Endpoint
/api/v1/auth/bootstrap

### Parameters
#### Request Body
- **username** (string) - Required - The desired username for the first admin.
- **password** (string) - Required - The desired password for the first admin.

### Request Example
```bash
curl -c cookies.txt -X POST http://localhost:2289/api/v1/auth/bootstrap \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "supersecret"}'
```

### Response
#### Error Response (409)
- Returns 409 if an admin already exists.
```

--------------------------------

### Create Player

Source: https://context7.com/ggmolly/belfast/llms.txt

Creates a new player on the server. Requires administrator privileges.

```APIDOC
## POST /api/v1/players

### Description
Creates a new player on the server. Requires administrator privileges.

### Method
POST

### Endpoint
/api/v1/players

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new player.
- **level** (integer) - Required - The initial level of the player.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/players \
  -H 'Content-Type: application/json' \
  -d '{"name": "NewPlayer", "level": 1}'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The newly created player object.
  - **id** (integer) - The player's unique identifier.
  - **name** (string) - The player's name.
  - **level** (integer) - The player's level.
  - ... (other player fields)

### Response Example
```json
{"success":true,"data":{"id":42,"name":"NewPlayer",...}}
```
```

--------------------------------

### Register Passkey Options

Source: https://context7.com/ggmolly/belfast/llms.txt

Requests registration options for a hardware passkey. This is the first step in the passkey registration process and requires an active session.

```APIDOC
## POST /api/v1/auth/passkeys/register/options

### Description
Requests registration options for a hardware passkey. This is the first step in the passkey registration process and requires an active session.

### Method
POST

### Endpoint
/api/v1/auth/passkeys/register/options

### Parameters
#### Request Body
- **user_verification** (string) - Optional - Specifies the user verification method (e.g., 'preferred', 'required').
- **resident_key** (string) - Optional - Specifies the resident key requirement (e.g., 'preferred', 'required').
- **label** (string) - Required - A human-readable label for the passkey (e.g., 'YubiKey 5').

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/auth/passkeys/register/options \
  -H 'Content-Type: application/json' \
  -d '{"user_verification": "preferred", "resident_key": "preferred", "label": "YubiKey 5"}'
```

### Response
#### Success Response (200)
- Returns `PublicKeyCredentialCreationOptions` object, which is used by the browser's WebAuthn API to initiate the passkey registration process.
```

--------------------------------

### Run Go Tests

Source: https://github.com/ggmolly/belfast/blob/main/CONTRIBUTING.md

Execute all Go tests to verify that no regressions have been introduced.

```bash
go test ./...
```

--------------------------------

### Run Belfast Game Server

Source: https://context7.com/ggmolly/belfast/llms.txt

Launches the Belfast game server. Supports custom config paths, DB reseeding, disabling the REST API, and enabling ADB log watcher.

```bash
# Default config path: server.toml
./bin/belfast
```

```bash
# Custom config + force DB reseed
./bin/belfast --config /etc/belfast/server.toml --reseed
```

```bash
# Disable the REST API
./bin/belfast --no-api
```

```bash
# Enable ADB log watcher (experimental, Linux)
./bin/belfast -a --flush-logcat --restart
```

--------------------------------

### Send Protocol Buffer Responses

Source: https://context7.com/ggmolly/belfast/llms.txt

Serializes a proto message, prepends the Belfast frame header, and writes it to the client's write buffer. The buffer is flushed at the end of `Dispatch`. Use either the standalone helper or the client method.

```go
// Using the standalone helper (used from inline handlers)
func MyHandler(b *[]byte, c *connection.Client) (int, int, error) {
    response := &protobuf.SC_12026{
        // ... fill fields
    }
    return connection.SendProtoMessage(12026, c, response)
}
```

```go
// Using the client method (common pattern in answer/ handlers)
func HandleShipAction(b *[]byte, c *connection.Client) (int, int, error) {
    response := protobuf.SC_12030{
        Result: proto.Uint32(1),
    }
    return c.SendMessage(12030, &response)
}
```

```go
// Multiple responses in one handler (all buffered, flushed together)
func PlayerInfoSync(b *[]byte, c *connection.Client) (int, int, error) {
    if _, _, err := c.SendMessage(11002, &playerInfo); err != nil {
        return 0, 0, err
    }
    if _, _, err := c.SendMessage(11004, &resourceInfo); err != nil {
        return 0, 0, err
    }
    return c.SendMessage(11006, &dockData)
}
```

--------------------------------

### Regenerate Protobuf and SQLC Bindings

Source: https://context7.com/ggmolly/belfast/llms.txt

Commands to regenerate Protocol Buffers definitions and SQLC query bindings. Also regenerates Swagger documentation.

```bash
# Install protoc plugin, convert Lua proto sources, run protoc
make proto
```

```bash
# Regenerate SQLC query bindings
make sqlc
```

```bash
# Regenerate Swagger docs from source annotations
make swag
```

--------------------------------

### Analyze packet implementation coverage

Source: https://context7.com/ggmolly/belfast/llms.txt

Analyze Go source code to score packet handler implementation and generate reports. Requires Go. Can output JSON, SVG, or PNG.

```bash
# Generate JSON report + SVG chart (default output paths)
go run ./cmd/packet_progress
```

```bash
# Generate PNG (requires rsvg-convert)
go run ./cmd/packet_progress png -out-png docs/packet-progress.png -png-scale 1.5
```

```bash
# Track only CS_ (client->server) packets
go run ./cmd/packet_progress -cs
```

```bash
# Track only SC_ (server->client) response packets
go run ./cmd/packet_progress -sc
```

```bash
# Custom output paths
go run ./cmd/packet_progress \
  -out-json docs/custom-report.json \
  -out-svg  docs/custom-progress.svg \
  -font-family "monospace"
```

--------------------------------

### Passkey Registration Options

Source: https://context7.com/ggmolly/belfast/llms.txt

Requests registration options for a hardware passkey. Requires an active session cookie and a JSON payload specifying verification preferences. The response is intended for the browser's WebAuthn API.

```bash
# 1. Get registration options (requires active session)
curl -b cookies.txt -X POST http://localhost:2289/api/v1/auth/passkeys/register/options \
  -H 'Content-Type: application/json' \
  -d '{"user_verification": "preferred", "resident_key": "preferred", "label": "YubiKey 5"}'
# Returns PublicKeyCredentialCreationOptions for the browser WebAuthn API
```

--------------------------------

### Create a New Player

Source: https://context7.com/ggmolly/belfast/llms.txt

Creates a new player with a specified name and level. Requires an active session cookie and a JSON payload containing player details. The response includes the newly created player's ID.

```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/players \
  -H 'Content-Type: application/json' \
  -d '{"name": "NewPlayer", "level": 1}'
# {"success":true,"data":{"id":42,"name":"NewPlayer",...}}
```

--------------------------------

### Go Code Formatting

Source: https://github.com/ggmolly/belfast/blob/main/CONTRIBUTING.md

Ensure all Go files are formatted using `gofmt` before submitting a pull request.

```bash
gofmt
```

--------------------------------

### Packet Progress Heuristics Configuration

Source: https://context7.com/ggmolly/belfast/llms.txt

JSON configuration file for defining weights of heuristics used in packet progress analysis and thresholds for implementation status.

```json
{
  "weights": {
    "send_message":      3,
    "response_struct":   2,
    "request_struct":    1,
    "proto_setter":      1,
    "request_parse":     1,
    "client_usage":      1,
    "commander_usage":   2,
    "orm_usage":         2,
    "misc_usage":        1,
    "db_write":          2
  },
  "thresholds": {
    "implemented_min": 4
  }
}
```

--------------------------------

### Capture Azur Lane traffic and decode

Source: https://context7.com/ggmolly/belfast/llms.txt

Capture traffic from a WireGuard interface and then decode the pcap file using pcap_decode. Ensure capture.sh is executable.

```bash
# Capture WireGuard interface traffic for all Azur Lane hosts
./capture.sh wg0 azurlane.pcap

# Then decode
go run ./cmd/pcap_decode -pcap azurlane.pcap -server-port 7000
```

--------------------------------

### List Players with Pagination

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves a list of players, supporting pagination with 'limit' and 'offset' query parameters. Requires an active session cookie. The response includes player IDs and names.

```bash
curl -b cookies.txt 'http://localhost:2289/api/v1/players?limit=20&offset=0'
# {"success":true,"data":[{"id":1,"name":"CommanderName",...}]}
```

--------------------------------

### Verify Passkey Registration

Source: https://context7.com/ggmolly/belfast/llms.txt

Verifies the registration of a hardware passkey using the authenticator's response. Requires an active session cookie, the passkey label, and the credential object obtained from the browser.

```bash
# 2. Verify registration with the authenticator response
curl -b cookies.txt -X POST http://localhost:2289/api/v1/auth/passkeys/register/verify \
  -H 'Content-Type: application/json' \
  -d '{"label": "YubiKey 5", "credential": { ...navigator.credentials.create() response... }}'
```

--------------------------------

### connection.SendProtoMessage / client.SendMessage

Source: https://context7.com/ggmolly/belfast/llms.txt

Serializes a protobuf message, prepends the Belfast frame header, and writes it to the client's write buffer.

```APIDOC
## connection.SendProtoMessage / client.SendMessage

### Description
Serializes a proto message, prepends the 7-byte Belfast frame header, and writes the frame to the client's write buffer (flushed at end of `Dispatch`).

### Usage (Standalone Helper)
```go
func MyHandler(b *[]byte, c *connection.Client) (int, int, error) {
    response := &protobuf.SC_12026{ /* ... fill fields */ }
    return connection.SendProtoMessage(12026, c, response)
}
```

### Usage (Client Method)
```go
func HandleShipAction(b *[]byte, c *connection.Client) (int, int, error) {
    response := protobuf.SC_12030{
        Result: proto.Uint32(1),
    }
    return c.SendMessage(12030, &response)
}
```

### Usage (Multiple Responses)
```go
func PlayerInfoSync(b *[]byte, c *connection.Client) (int, int, error) {
    if _, _, err := c.SendMessage(11002, &playerInfo); err != nil {
        return 0, 0, err
    }
    if _, _, err := c.SendMessage(11004, &resourceInfo); err != nil {
        return 0, 0, err
    }
    return c.SendMessage(11006, &dockData)
}
```

### Parameters
- **packetID** (int): The ID of the protocol buffer message.
- **c** (*connection.Client): The client connection to send the message to.
- **response** (proto.Message): The protocol buffer message to send.

### Return Value
- **(int, int, error)**: Bytes sent, bytes written, and any error encountered.
```

--------------------------------

### Verify Passkey Registration

Source: https://context7.com/ggmolly/belfast/llms.txt

Verifies the passkey registration using the authenticator's response. This is the second step in the passkey registration process.

```APIDOC
## POST /api/v1/auth/passkeys/register/verify

### Description
Verifies the passkey registration using the authenticator's response. This is the second step in the passkey registration process.

### Method
POST

### Endpoint
/api/v1/auth/passkeys/register/verify

### Parameters
#### Request Body
- **label** (string) - Required - The label of the passkey, matching the one used in registration options.
- **credential** (object) - Required - The `AuthenticatorAttestationResponse` object obtained from `navigator.credentials.create()` in the browser.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/auth/passkeys/register/verify \
  -H 'Content-Type: application/json' \
  -d '{"label": "YubiKey 5", "credential": { ...navigator.credentials.create() response... }}'
```
```

--------------------------------

### Gateway Server Configuration

Source: https://context7.com/ggmolly/belfast/llms.txt

TOML configuration for the gateway server. Defines bind address, port, and server list. Can operate in 'serve' or 'proxy' mode.

```toml
bind_address = "0.0.0.0"
port         = 80

# mode = "serve"   # "serve" replies locally | "proxy" forwards raw TCP
# proxy_remote = "127.0.0.1:80"
# require_private_clients = true

[[servers]]
id   = 1
ip   = "127.0.0.1"
port = 7000
# name = "Belfast"
# assert_online = true   # skip health probe, always report online
```

--------------------------------

### Admin Login with Session Cookie

Source: https://context7.com/ggmolly/belfast/llms.txt

Logs in an administrator using username and password, saving the session cookie for subsequent authenticated requests. Requires a valid JSON payload with username and password.

```bash
curl -c cookies.txt -X POST http://localhost:2289/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "secret"}'
# {"success":true,"data":{"user":{"id":"...","username":"admin","is_admin":true},"session":{"id":"...","expires_at":"..."}}}
```

--------------------------------

### Verify Passkey Authentication

Source: https://context7.com/ggmolly/belfast/llms.txt

Verifies the passkey authentication using the authenticator's response. This is the second step in the passkey authentication flow.

```APIDOC
## POST /api/v1/auth/passkeys/authenticate/verify

### Description
Verifies the passkey authentication using the authenticator's response. This is the second step in the passkey authentication flow.

### Method
POST

### Endpoint
/api/v1/auth/passkeys/authenticate/verify

### Parameters
#### Request Body
- **username** (string) - Required - The username of the user.
- **credential** (object) - Required - The `AuthenticatorAssertionResponse` object obtained from `navigator.credentials.get()` in the browser.

### Request Example
```bash
curl -c cookies.txt -X POST http://localhost:2289/api/v1/auth/passkeys/authenticate/verify \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "credential": { ...navigator.credentials.get() response... }}'
```
```

--------------------------------

### List Registered Passkeys

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves a list of all passkeys registered to the authenticated user. Requires administrator privileges.

```APIDOC
## GET /api/v1/auth/passkeys

### Description
Retrieves a list of all passkeys registered to the authenticated user. Requires administrator privileges.

### Method
GET

### Endpoint
/api/v1/auth/passkeys

### Request Example
```bash
curl -b cookies.txt http://localhost:2289/api/v1/auth/passkeys
```
```

--------------------------------

### List Registered Passkeys

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves a list of all passkeys registered to the current user. Requires an active session cookie. This endpoint can be used to manage or view associated passkeys.

```bash
curl -b cookies.txt http://localhost:2289/api/v1/auth/passkeys
```

--------------------------------

### List Players

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves a paginated list of all players on the server. Requires administrator privileges.

```APIDOC
## GET /api/v1/players

### Description
Retrieves a paginated list of all players on the server. Requires administrator privileges.

### Method
GET

### Endpoint
/api/v1/players

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of players to return per page. Defaults to 20.
- **offset** (integer) - Optional - The number of players to skip before returning results. Defaults to 0.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of player objects.
  - **id** (integer) - The player's unique identifier.
  - **name** (string) - The player's name.
  - ... (other player fields)

### Request Example
```bash
curl -b cookies.txt 'http://localhost:2289/api/v1/players?limit=20&offset=0'
```

### Response Example
```json
{"success":true,"data":[{"id":1,"name":"CommanderName",...}]}
```
```

--------------------------------

### Verify Passkey Assertion

Source: https://context7.com/ggmolly/belfast/llms.txt

Verifies the passkey assertion response from the authenticator. Requires the username, the credential object obtained from the browser, and a valid session cookie. This completes the passwordless login process.

```bash
# Step B — verify assertion
curl -c cookies.txt -X POST http://localhost:2289/api/v1/auth/passkeys/authenticate/verify \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "credential": { ...navigator.credentials.get() response... }}'
```

--------------------------------

### List Active TCP Connections

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves a list of all active TCP connections to the server. Requires administrator privileges.

```APIDOC
## GET /api/v1/server/connections

### Description
Retrieves a list of all active TCP connections to the server. Requires administrator privileges.

### Method
GET

### Endpoint
/api/v1/server/connections

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of active connections.
  - **hash** (integer) - A unique hash identifier for the connection.
  - **remote_addr** (string) - The remote address and port of the client.
  - **connected_at** (string) - The timestamp when the connection was established (ISO 8601 format).
  - **commander_id** (integer) - The ID of the commander associated with the connection, if any.

### Request Example
```bash
curl -b cookies.txt http://localhost:2289/api/v1/server/connections
```

### Response Example
```json
{"success":true,"data":[
  {"hash":12345678,"remote_addr":"192.168.1.5:50123","connected_at":"2025-01-01T00:00:00Z","commander_id":1001}
]}
```
```

--------------------------------

### Commit Message Format

Source: https://github.com/ggmolly/belfast/blob/main/CONTRIBUTING.md

Follow this format for commit messages: `<type>(<optional-component>): one-line summary`.

```git
feat(auth): add token validation
```

```git
fix: handle nil commander
```

```git
chore(proto): update generator
```

--------------------------------

### List Active TCP Connections

Source: https://context7.com/ggmolly/belfast/llms.txt

Retrieves a list of all active TCP connections to the server. Requires an active session cookie. The response includes connection details like remote address and connection time.

```bash
curl -b cookies.txt http://localhost:2289/api/v1/server/connections
# {"success":true,"data":[
#   {"hash":12345678,"remote_addr":"192.168.1.5:50123","connected_at":"2025-01-01T00:00:00Z","commander_id":1001}
# ]}
```

--------------------------------

### Admin Login

Source: https://context7.com/ggmolly/belfast/llms.txt

Authenticates an administrator user with username and password. Requires a valid session cookie for subsequent admin requests.

```APIDOC
## POST /api/v1/auth/login

### Description
Authenticates an administrator user with username and password. Requires a valid session cookie for subsequent admin requests.

### Method
POST

### Endpoint
/api/v1/auth/login

### Parameters
#### Request Body
- **username** (string) - Required - The administrator's username.
- **password** (string) - Required - The administrator's password.

### Request Example
```bash
curl -c cookies.txt -X POST http://localhost:2289/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "secret"}'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object)
  - **user** (object) - Information about the logged-in user.
    - **id** (string) - The user's unique identifier.
    - **username** (string) - The username.
    - **is_admin** (boolean) - Whether the user is an administrator.
  - **session** (object) - Information about the active session.
    - **id** (string) - The session's unique identifier.
    - **expires_at** (string) - The session expiration timestamp.

### Response Example
```json
{"success":true,"data":{"user":{"id":"...","username":"admin","is_admin":true},"session":{"id":"...","expires_at":"..."}}}
```
```

--------------------------------

### Update Player Data

Source: https://context7.com/ggmolly/belfast/llms.txt

Updates existing player data. Requires administrator privileges.

```APIDOC
## PATCH /api/v1/players/{id}

### Description
Updates existing player data. Requires administrator privileges.

### Method
PATCH

### Endpoint
/api/v1/players/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the player to update.

#### Request Body
- **name** (string) - Optional - The new name for the player.
- **level** (integer) - Optional - The new level for the player.
- ... (other updatable player fields)

### Request Example
```bash
curl -b cookies.txt -X PATCH http://localhost:2289/api/v1/players/42 \
  -H 'Content-Type: application/json' \
  -d '{"name": "RenamedCommander", "level": 120}'
```
```

--------------------------------

### Packet Progress Status Overrides

Source: https://context7.com/ggmolly/belfast/llms.txt

JSON configuration file for manually overriding the status of specific packet IDs in the packet progress analysis.

```json
{
  "10100": "implemented",
  "10991": "stub",
  "10993": "partial"
}
```

--------------------------------

### Register Packet Handlers

Source: https://context7.com/ggmolly/belfast/llms.txt

Associates handler functions with specific client packet IDs. Handlers are executed in sequence for matched packets.

```go
// Register handler(s) for packet CS_15002 (use item)
packets.RegisterPacketHandler(15002, []packets.PacketHandler{answer.UseItem})
```

```go
// Register a chain of handlers for CS_11001 (login/sync — runs all in sequence)
packets.RegisterPacketHandler(11001, []packets.PacketHandler{
    answer.LastLogin,
    answer.PlayerInfo,
    answer.PlayerBuffs,
    answer.OwnedItems,
    answer.PlayerDock,
    answer.CommanderFleet,
    // ... 30+ more sync handlers
})
```

```go
// Inline handler (no separate function)
packets.RegisterPacketHandler(20007, []packets.PacketHandler{
    func(b *[]byte, c *connection.Client) (int, int, error) {
        response := protobuf.SC_20008{Result: proto.Uint32(1)}
        return c.SendMessage(20008, &response)
    },
})
```

--------------------------------

### Grant Ship to Player

Source: https://context7.com/ggmolly/belfast/llms.txt

Grants a specific ship to a player. Requires administrator privileges.

```APIDOC
## POST /api/v1/players/{id}/ships

### Description
Grants a specific ship to a player. Requires administrator privileges.

### Method
POST

### Endpoint
/api/v1/players/{id}/ships

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the player.

#### Request Body
- **ship_id** (integer) - Required - The ID of the ship to grant.
- **level** (integer) - Optional - The level of the granted ship.
- **star** (integer) - Optional - The star rating of the granted ship.
- **affinity** (integer) - Optional - The affinity value for the granted ship.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/players/42/ships \
  -H 'Content-Type: application/json' \
  -d '{"ship_id": 101, "level": 125, "star": 6, "affinity": 200}'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Details of the granted ship.
  - **owned_id** (integer) - The unique ID of the owned ship instance.
  - **ship_id** (integer) - The ID of the ship.
  - ... (other ship instance fields)
```

--------------------------------

### Decode pcap capture to JSON

Source: https://context7.com/ggmolly/belfast/llms.txt

Decode a libpcap or pcapng file into newline-delimited JSON records. TCP streams are reassembled and protobuf payloads are decoded if packet IDs are registered. Requires Go.

```bash
# Decode all packets, infer CS/SC direction using server port 7000
go run ./cmd/pcap_decode -pcap capture.pcap -server-port 7000
```

```bash
# Filter to a single packet type by ID
go run ./cmd/pcap_decode -pcap capture.pcap -server-port 7000 -packet 11001
```

```bash
# Filter by name
go run ./cmd/pcap_decode -pcap capture.pcap -server-port 7000 -packet-name CS_12002
```

```bash
# Limit output to first 50 packets
go run ./cmd/pcap_decode -pcap capture.pcap -server-port 7000 -limit 50
```

```bash
# Filter to a specific TCP stream
go run ./cmd/pcap_decode -pcap capture.pcap -server-port 7000 \
  -stream "192.168.1.5:50123->10.0.0.1:7000"
```

--------------------------------

### Grant a Ship to a Player

Source: https://context7.com/ggmolly/belfast/llms.txt

Grants a specific ship to a player, with options to set its level, star rating, and affinity. Requires an active session cookie and a JSON payload with ship details. Uses the POST HTTP method on the player's ships endpoint.

```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/players/42/ships \
  -H 'Content-Type: application/json' \
  -d '{"ship_id": 101, "level": 125, "star": 6, "affinity": 200}'
# {"success":true,"data":{"owned_id":999,"ship_id":101,...}}
```

--------------------------------

### Define Packet Handler Type

Source: https://context7.com/ggmolly/belfast/llms.txt

Defines the signature for a PacketHandler function, which processes incoming client packets and returns response details.

```go
// internal/packets/handler.go
type PacketHandler func(*[]byte, *connection.Client) (int, int, error)
```

--------------------------------

### Update Player Item Quantity

Source: https://context7.com/ggmolly/belfast/llms.txt

Updates the quantity of a specific item owned by a player. Requires administrator privileges.

```APIDOC
## PATCH /api/v1/players/{id}/items/{item_id}

### Description
Updates the quantity of a specific item owned by a player. Requires administrator privileges.

### Method
PATCH

### Endpoint
/api/v1/players/{id}/items/{item_id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the player.
- **item_id** (integer) - Required - The unique identifier of the item.

#### Request Body
- **quantity** (integer) - Required - The new quantity for the item.

### Request Example
```bash
curl -b cookies.txt -X PATCH http://localhost:2289/api/v1/players/42/items/5 \
  -H 'Content-Type: application/json' \
  -d '{"quantity": 9999}'
```
```

--------------------------------

### Toggle Maintenance Mode

Source: https://context7.com/ggmolly/belfast/llms.txt

Enables or disables maintenance mode for the server. When enabled, connected clients receive a maintenance notification.

```APIDOC
## POST /api/v1/server/maintenance

### Description
Enables or disables maintenance mode for the server. When enabled, connected clients receive a maintenance notification.

### Method
POST

### Endpoint
/api/v1/server/maintenance

### Parameters
#### Request Body
- **enabled** (boolean) - Required - Set to `true` to enable maintenance mode, `false` to disable.

### Request Example
```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/server/maintenance \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true}'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object)
  - **enabled** (boolean) - The new state of maintenance mode.

### Response Example
```json
{"success":true,"data":{"enabled":true}}
```

### Notes
All connected clients receive SC_10999 with DR_SERVER_MAINTENANCE when maintenance mode is toggled.
```

--------------------------------

### Disconnect Client

Source: https://context7.com/ggmolly/belfast/llms.txt

Terminates a specific client connection identified by its hash ID. Requires administrator privileges.

```APIDOC
## DELETE /api/v1/server/connections/{id}

### Description
Terminates a specific client connection identified by its hash ID. Requires administrator privileges.

### Method
DELETE

### Endpoint
/api/v1/server/connections/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The hash identifier of the connection to disconnect.

### Request Example
```bash
curl -b cookies.txt -X DELETE http://localhost:2289/api/v1/server/connections/12345678
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (null) - Typically null on successful disconnection.
```

--------------------------------

### Remove a passkey

Source: https://context7.com/ggmolly/belfast/llms.txt

Use this curl command to remove a passkey by its credential ID. Ensure cookies.txt is populated with valid session cookies.

```bash
#!/bin/bash
# Remove a passkey
curl -b cookies.txt -X DELETE http://localhost:2289/api/v1/auth/passkeys/abc123credentialID
```

--------------------------------

### Toggle Server Maintenance Mode

Source: https://context7.com/ggmolly/belfast/llms.txt

Enables or disables server maintenance mode. Requires an active session cookie and a JSON payload specifying the desired state of the 'enabled' flag. Connected clients will receive a notification.

```bash
curl -b cookies.txt -X POST http://localhost:2289/api/v1/server/maintenance \
  -H 'Content-Type: application/json' \
  -d '{"enabled": true}'
# {"success":true,"data":{"enabled":true}}
# All connected clients receive SC_10999 with DR_SERVER_MAINTENANCE
```

--------------------------------

### Disconnect a Specific Client

Source: https://context7.com/ggmolly/belfast/llms.txt

Terminates a specific client connection identified by its ID. Requires an active session cookie and the connection ID in the URL path. The request method is DELETE.

```bash
curl -b cookies.txt -X DELETE http://localhost:2289/api/v1/server/connections/12345678
# {"success":true,"data":null}
```