Add native host management and role-based operator authentication

Introduce an outbound Python host agent, Debian installer, durable remote
operations, immutable game-file libraries, host-aware deployments and ports,
and occupancy-safe campaigns and draining. Native hosts do not require Komodo.

Add administrator, operator and viewer accounts, protected management routes,
secure sessions, password recovery, audit history and separate telemetry tokens.
Document first-admin setup, reporter migration and live-host acceptance checks.

Validation: 1,343 TypeScript tests and 39 agent tests passed, along with type
checking, the production build, compiled SSR/API smoke tests and administrator
recovery. Real Debian/Docker T5/T6 acceptance remains unrun.

src/lib/server/hosts/http.ts

@@ -0,0 +1,50 @@
+import { error, json } from '@sveltejs/kit';
+import type { Host } from '../../hosts.js';
+import { authenticateCredential } from './index.js';
+
+export function requireAgentTransport(request: Request): void {
+    if (new URL(request.url).protocol !== 'https:' && process.env.EC_AGENT_ALLOW_HTTP !== 'true') error(426, 'Host agents require HTTPS.');
+}
+export function authenticateAgent(request: Request): Host {
+    requireAgentTransport(request);
+    const authorization = request.headers.get('authorization');
+    const token = authorization?.match(/^Bearer ([A-Za-z0-9_-]+)$/i)?.[1];
+    const host = token ? authenticateCredential(token) : null;
+    if (!host) error(401, 'A valid host credential is required.');
+    return host;
+}
+export function requireManagementOrigin(request: Request): void {
+    const origin = request.headers.get('origin');
+    if ((origin && origin !== new URL(request.url).origin) || request.headers.get('sec-fetch-site') === 'cross-site') error(403, 'Cross-origin host management requests are not allowed.');
+    // Agent credentials only authorize agent endpoints, never host management.
+    if (request.headers.get('authorization')?.match(/^Bearer ec_(?:host|enroll)_/i)) error(403, 'Agent credentials cannot manage the controller.');
+}
+export async function objectBody(request: Request, maxBytes = 1024 * 1024): Promise<Record<string, unknown>> {
+    if (Number(request.headers.get('content-length')) > maxBytes) error(413, 'Request is too large.');
+    const reader = request.body?.getReader();
+    if (!reader) error(400, 'Request body must be valid JSON.');
+    const chunks: Uint8Array[] = []; let received = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            received += value.byteLength;
+            if (received > maxBytes) { void reader.cancel().catch(() => {}); error(413, 'Request is too large.'); }
+            chunks.push(value);
+        }
+    } finally { reader.releaseLock(); }
+    const raw = Buffer.concat(chunks, received).toString('utf8');
+    let body: unknown;
+    try { body = JSON.parse(raw); } catch { error(400, 'Request body must be valid JSON.'); }
+    if (!body || typeof body !== 'object' || Array.isArray(body)) error(400, 'Request body must be an object.');
+    return body as Record<string, unknown>;
+}
+export function hostApiError(cause: unknown): Response {
+    if (cause && typeof cause === 'object' && 'status' in cause && 'body' in cause) throw cause;
+    return json({ error: cause instanceof Error ? cause.message : 'Host request failed.' }, { status: 400 });
+}
+export function installerCommand(controller: string, token: string): string {
+    const origin = new URL(controller).origin;
+    const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+    return `curl --fail --silent --show-error --proto '=https' ${quote(origin + '/api/agent/install.sh')} | sudo bash -s -- --controller ${quote(origin)} --token ${quote(token)}`;
+}

src/lib/server/hosts/index.ts

@@ -0,0 +1,248 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
+import { db } from '../db/index.js';
+import { ensureHostSchema } from './schema.js';
+import type { Host, HostInventory, HostMode, HostOperation, HostOperationState } from '../../hosts.js';
+
+export const AGENT_PROTOCOL_VERSION = 1;
+export const HEARTBEAT_MAX_AGE_MS = 90_000;
+const now = () => new Date().toISOString();
+const digest = (token: string) => createHash('sha256').update(token).digest('hex');
+function database() { const handle = db(); ensureHostSchema(handle); return handle; }
+type HostRow = { id: string; name: string; hostname: string; mode: HostMode; port_min: number; port_max: number; bind_address: string; public_address: string; minimum_free_bytes: number; created_at: string; enrolled_at: string | null; last_heartbeat: string | null; inventory: string; credential_active: number };
+const hostSql = `SELECT h.*, EXISTS(SELECT 1 FROM ec_host_credentials c WHERE c.host_id = h.id AND c.revoked_at IS NULL) AS credential_active FROM ec_hosts h`;
+function hostFromRow(row: HostRow): Host {
+    const inventory: HostInventory = JSON.parse(row.inventory);
+    const connected = !!row.credential_active && !!row.last_heartbeat && Date.now() - Date.parse(row.last_heartbeat) <= HEARTBEAT_MAX_AGE_MS;
+    const reasons: string[] = [];
+    if (!row.enrolled_at) reasons.push('Agent has not enrolled.');
+    else if (!row.credential_active) reasons.push('Agent credential has been revoked.');
+    if (!connected) reasons.push('Agent heartbeat is unavailable or stale.');
+    if (inventory.protocolVersion !== AGENT_PROTOCOL_VERSION) reasons.push('A compatible agent protocol is required.');
+    if (!inventory.dockerRunning) reasons.push('Docker is not ready.');
+    if (!inventory.directoriesWritable) reasons.push('Managed directories are not writable.');
+    if (typeof inventory.storageAvailable !== 'number' || inventory.storageAvailable < row.minimum_free_bytes) reasons.push('Insufficient available game storage.');
+    const infrastructureReady = reasons.length === 0;
+    if (!inventory.runtimeImages?.length) reasons.push('Prepare a Plutainer runtime image.');
+    if (!inventory.libraries?.some(library => library.state === 'ready')) reasons.push('Download and verify a game-file library.');
+    if (row.mode === 'draining') reasons.push('Host is draining; new deployments are blocked.');
+    if (row.mode === 'disabled') reasons.push('Host is disabled.');
+    return { id: row.id, name: row.name, hostname: row.hostname, mode: row.mode, portMin: row.port_min, portMax: row.port_max,
+        bindAddress: row.bind_address, publicAddress: row.public_address, minimumFreeBytes: row.minimum_free_bytes,
+        createdAt: row.created_at, lastHeartbeat: row.last_heartbeat, connected, connectionState: connected ? 'online' : 'offline',
+        readiness: row.mode === 'draining' ? 'draining' : row.mode === 'disabled' ? 'disabled' : !row.enrolled_at || (infrastructureReady && reasons.length) ? 'preparing' : reasons.length ? 'degraded' : 'ready',
+        readinessReasons: reasons, inventory, enrolled: !!row.enrolled_at, credentialActive: !!row.credential_active };
+}
+export function listHosts(): Host[] { return (database().prepare(hostSql + ' ORDER BY h.name, h.id').all() as HostRow[]).map(hostFromRow); }
+export function getHost(id: string): Host | null {
+    const row = database().prepare(hostSql + ' WHERE h.id = ?').get(id) as HostRow | undefined;
+    return row ? hostFromRow(row) : null;
+}
+function requireHost(id: string): Host { const host = getHost(id); if (!host) throw new Error('Host was not found.'); return host; }
+function textField(value: unknown, label: string, max = 200): string {
+    if (typeof value !== 'string' || !value.trim() || value.length > max || /[\x00-\x1f]/.test(value)) throw new Error(`${label} must be a nonempty string up to ${max} characters.`);
+    return value.trim();
+}
+function port(value: unknown): number { if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65535) throw new Error('Ports must be whole numbers between 1 and 65535.'); return value; }
+export function createHost(input: Record<string, unknown>): Host {
+    const id = randomUUID(); const name = textField(input.name, 'Host name');
+    const min = port(input.portMin ?? 28960); const max = port(input.portMax ?? 28980);
+    if (max < min) throw new Error('The last game port must not precede the first.');
+    const bind = input.bindAddress === undefined ? '0.0.0.0' : textField(input.bindAddress, 'Bind address');
+    if (!isIP(bind)) throw new Error('Bind address must be an IPv4 or IPv6 address.');
+    database().prepare('INSERT INTO ec_hosts(id,name,port_min,port_max,bind_address,created_at) VALUES(?,?,?,?,?,?)').run(id, name, min, max, bind, now());
+    return requireHost(id);
+}
+export function updateHost(id: string, input: Record<string, unknown>): Host {
+    const host = requireHost(id);
+    const name = input.name === undefined ? host.name : textField(input.name, 'Host name');
+    const mode = input.mode ?? host.mode;
+    if (!['active', 'draining', 'disabled'].includes(mode as string)) throw new Error('Host mode must be active, draining, or disabled.');
+    const min = port(input.portMin ?? host.portMin); const max = port(input.portMax ?? host.portMax);
+    if (max < min) throw new Error('The last game port must not precede the first.');
+    const bind = input.bindAddress === undefined ? host.bindAddress : textField(input.bindAddress, 'Bind address');
+    if (!isIP(bind)) throw new Error('Bind address must be an IPv4 or IPv6 address.');
+    const publicAddress = input.publicAddress === undefined ? host.publicAddress : input.publicAddress === '' ? '' : textField(input.publicAddress, 'Public address');
+    const minimum = input.minimumFreeBytes ?? host.minimumFreeBytes;
+    if (typeof minimum !== 'number' || !Number.isSafeInteger(minimum) || minimum < 0) throw new Error('Minimum free storage must be a nonnegative byte count.');
+    database().prepare('UPDATE ec_hosts SET name=?,mode=?,port_min=?,port_max=?,bind_address=?,public_address=?,minimum_free_bytes=? WHERE id=?').run(name, mode, min, max, bind, publicAddress, minimum, id);
+    return requireHost(id);
+}
+
+export function createEnrollment(hostId: string, ttlMs = 15 * 60_000): { id: string; hostId: string; token: string; expiresAt: string } {
+    requireHost(hostId);
+    if (!Number.isInteger(ttlMs) || ttlMs <= 0 || ttlMs > 60 * 60_000) throw new Error('Enrollment lifetime must be at most one hour.');
+    const token = 'ec_enroll_' + randomBytes(32).toString('base64url'); const id = randomUUID();
+    const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+    database().transaction(() => {
+        database().prepare('UPDATE ec_host_enrollments SET consumed_at=? WHERE host_id=? AND consumed_at IS NULL').run(now(), hostId);
+        database().prepare('INSERT INTO ec_host_enrollments(id,host_id,token_hash,created_at,expires_at) VALUES(?,?,?,?,?)').run(id, hostId, digest(token), now(), expiresAt);
+    })();
+    return { id, hostId, token, expiresAt };
+}
+function issueCredential(hostId: string, credential = 'ec_host_' + randomBytes(32).toString('base64url')): string {
+    database().prepare('INSERT INTO ec_host_credentials(id,host_id,token_hash,created_at) VALUES(?,?,?,?)').run(randomUUID(), hostId, digest(credential), now());
+    return credential;
+}
+export function validateInventory(value: unknown): HostInventory {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Host inventory must be an object.');
+    const inventory = value as HostInventory;
+    if (JSON.stringify(inventory).length > 256_000) throw new Error('Host inventory is too large.');
+    for (const key of ['hostname','agentVersion','os','architecture','cpu','dockerVersion']) {
+        if (inventory[key] !== undefined && (typeof inventory[key] !== 'string' || String(inventory[key]).length > 1000)) throw new Error(`Invalid inventory ${key}.`);
+    }
+    for (const key of ['cpuCount','memoryTotal','memoryAvailable','storageTotal','storageAvailable','protocolVersion']) {
+        if (inventory[key] !== undefined && (typeof inventory[key] !== 'number' || !Number.isSafeInteger(inventory[key]) || Number(inventory[key]) < 0)) throw new Error(`Invalid inventory ${key}.`);
+    }
+    for (const key of ['dockerRunning','directoriesWritable']) if (inventory[key] !== undefined && typeof inventory[key] !== 'boolean') throw new Error(`Invalid inventory ${key}.`);
+    if (inventory.runtimeImages !== undefined && (!Array.isArray(inventory.runtimeImages) || inventory.runtimeImages.some(image => typeof image !== 'string'))) throw new Error('Invalid runtime image inventory.');
+    if (inventory.libraries !== undefined && (!Array.isArray(inventory.libraries) || inventory.libraries.length > 2000 || inventory.libraries.some(library =>
+        !library || typeof library !== 'object' || typeof library.id !== 'string' || !library.id || library.id.length > 200 || !['missing','downloading','verifying','ready','failed','outdated'].includes(library.state)))) throw new Error('Invalid game library inventory.');
+    return inventory;
+}
+export function enrollHost(token: unknown, rawInventory: unknown): { hostId: string; credential: string; heartbeatSeconds: number } {
+    if (typeof token !== 'string' || token.length > 200) throw new Error('Enrollment token is invalid or expired.');
+    const inventory = validateInventory(rawInventory);
+    return database().transaction(() => {
+        const enrollment = database().prepare('SELECT id,host_id FROM ec_host_enrollments WHERE token_hash=? AND consumed_at IS NULL AND expires_at>?').get(digest(token), now()) as { id: string; host_id: string } | undefined;
+        if (!enrollment) throw new Error('Enrollment token is invalid or expired.');
+        const changed = database().prepare('UPDATE ec_host_enrollments SET consumed_at=? WHERE id=? AND consumed_at IS NULL').run(now(), enrollment.id);
+        if (changed.changes !== 1) throw new Error('Enrollment token has already been consumed.');
+        revokeCredentials(enrollment.host_id);
+        const credential = issueCredential(enrollment.host_id);
+        database().prepare('UPDATE ec_hosts SET enrolled_at=?,last_heartbeat=?,hostname=?,inventory=? WHERE id=?').run(now(), now(), inventory.hostname ?? '', JSON.stringify(inventory), enrollment.host_id);
+        return { hostId: enrollment.host_id, credential, heartbeatSeconds: 15 };
+    })();
+}
+export function authenticateCredential(token: string): Host | null {
+    if (!token || token.length > 200) return null;
+    const row = database().prepare('SELECT id,host_id FROM ec_host_credentials WHERE token_hash=? AND revoked_at IS NULL').get(digest(token)) as { id: string; host_id: string } | undefined;
+    if (!row) return null;
+    database().prepare('UPDATE ec_host_credentials SET last_used_at=? WHERE id=?').run(now(), row.id);
+    return getHost(row.host_id);
+}
+export function revokeCredentials(hostId: string): void {
+    requireHost(hostId);
+    database().prepare('UPDATE ec_host_credentials SET revoked_at=? WHERE host_id=? AND revoked_at IS NULL').run(now(), hostId);
+}
+export function rotateCredential(hostId: string, nextCredential?: string): string {
+    requireHost(hostId);
+    if (nextCredential !== undefined && !/^ec_host_[A-Za-z0-9_-]{43}$/.test(nextCredential)) throw new Error('New credentials must contain 32 random bytes encoded as base64url.');
+    return database().transaction(() => {
+        if (nextCredential) {
+            const existing = database().prepare('SELECT host_id,revoked_at FROM ec_host_credentials WHERE token_hash=?').get(digest(nextCredential)) as { host_id: string; revoked_at: string | null } | undefined;
+            if (existing) {
+                if (existing.host_id !== hostId || existing.revoked_at) throw new Error('This credential cannot be reused.');
+                return nextCredential;
+            }
+        }
+        revokeCredentials(hostId); return issueCredential(hostId, nextCredential);
+    })();
+}
+export function heartbeat(hostId: string, value: unknown): Host {
+    requireHost(hostId); const inventory = validateInventory(value);
+    database().prepare('UPDATE ec_hosts SET last_heartbeat=?,hostname=?,inventory=? WHERE id=?').run(now(), inventory.hostname ?? '', JSON.stringify(inventory), hostId);
+    return requireHost(hostId);
+}
+export function requireReadyHost(hostId: string, options: { libraryId?: string; requiredBytes?: number; image?: string; port?: number; bindAddress?: string; protocol?: 'udp' | 'tcp' } = {}): Host {
+    const host = requireHost(hostId); const reasons = [...host.readinessReasons];
+    if (options.requiredBytes !== undefined && (host.inventory.storageAvailable ?? 0) < options.requiredBytes + host.minimumFreeBytes) reasons.push('Insufficient storage for this deployment.');
+    if (options.libraryId && !host.inventory.libraries?.some(library => library.id === options.libraryId && library.state === 'ready')) reasons.push('The selected game library is not ready on this host.');
+    if (options.image && !host.inventory.runtimeImages?.includes(options.image)) reasons.push('The selected runtime image is not cached on this host.');
+    if (options.port !== undefined && !hostPortAvailable(hostId, options.port, options.bindAddress, options.protocol)) reasons.push('The selected host port is not available.');
+    if (reasons.length) throw new Error(reasons.join(' '));
+    return host;
+}
+
+type OperationRow = { id: string; host_id: string; kind: string; instance_id: string | null; generation: number | null; payload: string; state: HostOperationState; result: string | null; error: string | null; created_at: string; updated_at: string };
+function operationFromRow(row: OperationRow): HostOperation { return { id: row.id, hostId: row.host_id, kind: row.kind, instanceId: row.instance_id, generation: row.generation, payload: JSON.parse(row.payload), state: row.state, result: row.result === null ? null : JSON.parse(row.result), error: row.error, createdAt: row.created_at, updatedAt: row.updated_at }; }
+export function getHostOperation(id: string): HostOperation | null { const row = database().prepare('SELECT * FROM ec_host_operations WHERE id=?').get(id) as OperationRow | undefined; return row ? operationFromRow(row) : null; }
+export function listHostOperations(hostId: string, limit = 100): HostOperation[] { return (database().prepare('SELECT * FROM ec_host_operations WHERE host_id=? ORDER BY created_at DESC,rowid DESC LIMIT ?').all(hostId, Math.min(500, Math.max(1, limit))) as OperationRow[]).map(operationFromRow); }
+export function queueHostOperation(hostId: string, kind: string, payload: Record<string, unknown>, options: { instanceId?: string; generation?: number; idempotencyKey?: string; id?: string } = {}): HostOperation {
+    const host = requireHost(hostId);
+    if (!/^[a-z][a-z0-9_.-]{0,79}$/.test(kind)) throw new Error('Invalid operation kind.');
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('Operation payload must be an object.');
+    if (options.generation !== undefined && (!Number.isSafeInteger(options.generation) || options.generation < 1)) throw new Error('Instance generation must be a positive integer.');
+    return database().transaction(() => {
+        if (options.idempotencyKey) {
+            const existing = database().prepare('SELECT * FROM ec_host_operations WHERE host_id=? AND idempotency_key=?').get(hostId, options.idempotencyKey) as OperationRow | undefined;
+            if (existing) {
+                if (existing.kind !== kind || existing.instance_id !== (options.instanceId ?? null) || existing.generation !== (options.generation ?? null) || existing.payload !== JSON.stringify(payload)) throw new Error('Operation idempotency key is already associated with a different request.');
+                return operationFromRow(existing);
+            }
+        }
+        if (['instance.create','create'].includes(kind)) requireReadyHost(hostId);
+        if (host.mode === 'disabled') throw new Error('Host is disabled. Enable it before requesting operations.');
+        const id = options.id ?? randomUUID(); const timestamp = now();
+        database().prepare('INSERT INTO ec_host_operations(id,host_id,kind,instance_id,generation,idempotency_key,payload,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?)').run(id, hostId, kind, options.instanceId ?? null, options.generation ?? null, options.idempotencyKey ?? null, JSON.stringify(payload), timestamp, timestamp);
+        database().prepare('INSERT INTO ec_host_operation_events(operation_id,state,created_at) VALUES(?,?,?)').run(id, 'pending', timestamp);
+        return getHostOperation(id)!;
+    })();
+}
+export function pendingHostOperations(hostId: string): HostOperation[] {
+    const host = requireHost(hostId);
+    if (host.mode === 'disabled' || !host.connected) return [];
+    // Accepted/running/unknown commands keep the same immutable ID. The agent
+    // consults its durable journal before acknowledging or executing a replay.
+    return database().transaction(() => {
+        const rows = database().prepare(`SELECT * FROM ec_host_operations WHERE host_id=? AND state IN ('pending','accepted','running','unknown')
+            AND (? OR state != 'pending' OR kind NOT IN ('instance.create','create'))
+            ORDER BY COALESCE(last_delivered_at,''),created_at,rowid LIMIT 25`).all(hostId, Number(host.readiness === 'ready')) as OperationRow[];
+        const deliveredAt = now();
+        for (const operation of rows) database().prepare('UPDATE ec_host_operations SET last_delivered_at=? WHERE id=?').run(deliveredAt, operation.id);
+        return rows.map(operationFromRow);
+    })();
+}
+export function reportHostOperation(hostId: string, id: string, input: { state: unknown; result?: unknown; error?: unknown }): HostOperation {
+    return database().transaction(() => {
+        const operation = getHostOperation(id);
+        if (!operation || operation.hostId !== hostId) throw new Error('Operation was not found for this host.');
+        if (!['accepted','running','completed','failed','unknown'].includes(input.state as string)) throw new Error('Invalid operation state.');
+        if (['completed','failed'].includes(operation.state)) return operation;
+        const state = input.state as HostOperationState;
+        if (operation.state === 'running' && state === 'accepted') return operation;
+        const error = input.error === undefined || input.error === null ? null : String(input.error).slice(0, 4000);
+        const result = input.result === undefined ? null : JSON.stringify(input.result);
+        if (result !== null && Buffer.byteLength(result) > 128 * 1024 * 1024) throw new Error('Operation result exceeds the limit.');
+        database().prepare('UPDATE ec_host_operations SET state=?,result=?,error=?,updated_at=? WHERE id=?').run(state, result, error, now(), id);
+        if (operation.state !== state) database().prepare('INSERT INTO ec_host_operation_events(operation_id,state,created_at,error) VALUES(?,?,?,?)').run(id, state, now(), error);
+        return getHostOperation(id)!;
+    })();
+}
+export async function waitHostOperation(id: string, timeoutMs = 30_000): Promise<HostOperation> {
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        const operation = getHostOperation(id);
+        if (!operation) throw new Error('Host operation was not found.');
+        if (['completed','failed','unknown'].includes(operation.state)) return operation;
+        if (Date.now() >= deadline) throw new Error(`Host operation ${id} is awaiting acknowledgement; reconcile this operation ID before retrying.`);
+        await new Promise(resolve => setTimeout(resolve, 200));
+    }
+}
+
+export function hostPortAvailable(hostId: string, candidate: number, bindAddress?: string, protocol: 'udp' | 'tcp' = 'udp', instanceId?: string): boolean {
+    const host = requireHost(hostId); port(candidate); const bind = bindAddress ?? host.bindAddress;
+    if (candidate < host.portMin || candidate > host.portMax) return false;
+    const rows = database().prepare('SELECT instance_id,bind_address FROM ec_host_ports WHERE host_id=? AND protocol=? AND port=?').all(hostId, protocol, candidate) as { instance_id: string; bind_address: string }[];
+    return !rows.some(row => row.instance_id !== instanceId && (row.bind_address === bind || ['0.0.0.0','::'].includes(bind) || ['0.0.0.0','::'].includes(row.bind_address)));
+}
+export function nextHostPort(hostId: string, additionalPorts: number[] = [], bindAddress?: string, protocol: 'udp' | 'tcp' = 'udp'): number | null {
+    const host = requireHost(hostId);
+    for (let candidate = host.portMin; candidate <= host.portMax; candidate++) if (!additionalPorts.includes(candidate) && hostPortAvailable(hostId, candidate, bindAddress, protocol)) return candidate;
+    return null;
+}
+export function reserveHostPort(hostId: string, instanceId: string, options: { port?: number; bindAddress?: string; protocol?: 'udp' | 'tcp' } = {}): number {
+    const host = requireHost(hostId); const bind = options.bindAddress ?? host.bindAddress; const protocol = options.protocol ?? 'udp';
+    if (!isIP(bind)) throw new Error('Bind address must be an IP address.');
+    if (!['udp','tcp'].includes(protocol)) throw new Error('Port protocol must be UDP or TCP.');
+    if (!instanceId) throw new Error('An immutable instance ID is required.');
+    return database().transaction(() => {
+        const existing = database().prepare('SELECT port FROM ec_host_ports WHERE host_id=? AND instance_id=? AND bind_address=? AND protocol=?').get(hostId, instanceId, bind, protocol) as { port: number } | undefined;
+        if (existing && (options.port === undefined || options.port === existing.port)) return existing.port;
+        const allocated = options.port ?? nextHostPort(hostId, [], bind, protocol);
+        if (allocated === null || !hostPortAvailable(hostId, allocated, bind, protocol, instanceId)) throw new Error('No available game port on the selected host.');
+        database().prepare('INSERT INTO ec_host_ports(host_id,instance_id,bind_address,protocol,port,created_at) VALUES(?,?,?,?,?,?)').run(hostId, instanceId, bind, protocol, allocated, now());
+        return allocated;
+    })();
+}
+export function releaseHostPorts(instanceId: string): void { database().prepare('DELETE FROM ec_host_ports WHERE instance_id=?').run(instanceId); }

src/lib/server/hosts/releases.ts

@@ -0,0 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+/** adapter-node copies public assets to build/client; Vite serves static in development. */
+export async function agentReleaseAsset(file: 'install.sh' | 'ec-agent.py' | 'manifest.json'): Promise<string> {
+    try { return await readFile(resolve('build/client/agent', file), 'utf8'); }
+    catch (cause) {
+        if ((cause as NodeJS.ErrnoException).code !== 'ENOENT') throw cause;
+        return readFile(resolve('static/agent', file), 'utf8');
+    }
+}

src/lib/server/hosts/schema.ts

@@ -0,0 +1,47 @@
+import type Database from 'better-sqlite3';
+
+const initialized = new WeakSet<Database.Database>();
+export function ensureHostSchema(handle: Database.Database): void {
+    if (initialized.has(handle)) return;
+    handle.exec(`
+        CREATE TABLE IF NOT EXISTS ec_hosts (
+            id TEXT PRIMARY KEY, name TEXT NOT NULL, hostname TEXT NOT NULL DEFAULT '',
+            mode TEXT NOT NULL DEFAULT 'active' CHECK (mode IN ('active','draining','disabled')),
+            port_min INTEGER NOT NULL DEFAULT 28960, port_max INTEGER NOT NULL DEFAULT 28980,
+            bind_address TEXT NOT NULL DEFAULT '0.0.0.0', public_address TEXT NOT NULL DEFAULT '',
+            minimum_free_bytes INTEGER NOT NULL DEFAULT 1073741824,
+            created_at TEXT NOT NULL, enrolled_at TEXT, last_heartbeat TEXT, inventory TEXT NOT NULL DEFAULT '{}'
+        );
+        CREATE TABLE IF NOT EXISTS ec_host_enrollments (
+            id TEXT PRIMARY KEY, host_id TEXT NOT NULL REFERENCES ec_hosts(id), token_hash TEXT NOT NULL UNIQUE,
+            created_at TEXT NOT NULL, expires_at TEXT NOT NULL, consumed_at TEXT
+        );
+        CREATE TABLE IF NOT EXISTS ec_host_credentials (
+            id TEXT PRIMARY KEY, host_id TEXT NOT NULL REFERENCES ec_hosts(id), token_hash TEXT NOT NULL UNIQUE,
+            created_at TEXT NOT NULL, revoked_at TEXT, last_used_at TEXT
+        );
+        CREATE TABLE IF NOT EXISTS ec_host_operations (
+            id TEXT PRIMARY KEY, host_id TEXT NOT NULL REFERENCES ec_hosts(id), kind TEXT NOT NULL,
+            instance_id TEXT, generation INTEGER, idempotency_key TEXT,
+            payload TEXT NOT NULL, state TEXT NOT NULL DEFAULT 'pending'
+                CHECK (state IN ('pending','accepted','running','completed','failed','unknown')),
+            result TEXT, error TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL, last_delivered_at TEXT,
+            UNIQUE(host_id, idempotency_key)
+        );
+        CREATE INDEX IF NOT EXISTS ec_host_operations_queue ON ec_host_operations(host_id, state, created_at);
+        CREATE TABLE IF NOT EXISTS ec_host_operation_events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT, operation_id TEXT NOT NULL REFERENCES ec_host_operations(id),
+            state TEXT NOT NULL, created_at TEXT NOT NULL, error TEXT
+        );
+        CREATE TABLE IF NOT EXISTS ec_host_ports (
+            host_id TEXT NOT NULL REFERENCES ec_hosts(id), instance_id TEXT NOT NULL,
+            bind_address TEXT NOT NULL, protocol TEXT NOT NULL CHECK (protocol IN ('udp','tcp')),
+            port INTEGER NOT NULL CHECK (port BETWEEN 1 AND 65535), created_at TEXT NOT NULL,
+            PRIMARY KEY(host_id,bind_address,protocol,port)
+        );
+        CREATE INDEX IF NOT EXISTS ec_host_ports_instance ON ec_host_ports(instance_id);
+    `);
+    const columns = handle.prepare('PRAGMA table_info(ec_host_operations)').all() as { name: string }[];
+    if (!columns.some(column => column.name === 'last_delivered_at')) handle.exec('ALTER TABLE ec_host_operations ADD COLUMN last_delivered_at TEXT');
+    initialized.add(handle);
+}