@pellux/goodvibes-daemon-sdk 0.30.2 → 0.33.0

package/dist/remote-routes.js

@@ -1,7 +1,114 @@
 import { jsonErrorResponse } from './error-response.js';
-import { serializableJsonResponse } from './route-helpers.js';
+import { createRouteBodySchema, createRouteBodySchemaRegistry, readOptionalStringField, readStringArrayField, serializableJsonResponse, } from './route-helpers.js';
 const MAX_REMOTE_RESULT_BYTES = 1_000_000;
 const MAX_REMOTE_PAYLOAD_BYTES = 1_000_000;
+const MAX_REMOTE_CAPABILITIES = 128;
+const MAX_REMOTE_COMMANDS = 128;
+const MAX_REMOTE_SCOPES = 128;
+const remoteBodySchemas = createRouteBodySchemaRegistry({
+    pairRequest: createRouteBodySchema('POST /api/remote/pair', (body) => {
+        const label = readOptionalStringField(body, 'label');
+        if (!label)
+            return jsonErrorResponse({ error: 'Missing remote peer label' }, { status: 400 });
+        const requestedId = readOptionalStringField(body, 'requestedId');
+        const platform = readOptionalStringField(body, 'platform');
+        const deviceFamily = readOptionalStringField(body, 'deviceFamily');
+        const version = readOptionalStringField(body, 'version');
+        const clientMode = readOptionalStringField(body, 'clientMode');
+        const ttlMs = boundedPositiveNumber(body.ttlMs, 1_000, 86_400_000);
+        return {
+            peerKind: body.peerKind === 'device' ? 'device' : 'node',
+            ...(requestedId ? { requestedId } : {}),
+            label,
+            ...(platform ? { platform } : {}),
+            ...(deviceFamily ? { deviceFamily } : {}),
+            ...(version ? { version } : {}),
+            ...(clientMode ? { clientMode } : {}),
+            capabilities: readStringArrayField(body, 'capabilities', MAX_REMOTE_CAPABILITIES) ?? [],
+            commands: readStringArrayField(body, 'commands', MAX_REMOTE_COMMANDS) ?? [],
+            metadata: readRemoteMetadata(body.metadata),
+            ...(ttlMs !== undefined ? { ttlMs } : {}),
+        };
+    }),
+    pairVerify: createRouteBodySchema('POST /api/remote/pair/verify', (body) => {
+        const requestId = readOptionalStringField(body, 'requestId');
+        const challenge = readOptionalStringField(body, 'challenge');
+        if (!requestId || !challenge) {
+            return jsonErrorResponse({ error: 'Missing requestId or challenge' }, { status: 400 });
+        }
+        return { requestId, challenge, metadata: readRemoteMetadata(body.metadata) };
+    }),
+    peerHeartbeat: createRouteBodySchema('POST /api/remote/heartbeat', (body) => {
+        const capabilities = readStringArrayField(body, 'capabilities', MAX_REMOTE_CAPABILITIES);
+        const commands = readStringArrayField(body, 'commands', MAX_REMOTE_COMMANDS);
+        const version = readOptionalStringField(body, 'version');
+        const clientMode = readOptionalStringField(body, 'clientMode');
+        return {
+            ...(capabilities ? { capabilities } : {}),
+            ...(commands ? { commands } : {}),
+            ...(version ? { version } : {}),
+            ...(clientMode ? { clientMode } : {}),
+            metadata: readRemoteMetadata(body.metadata),
+        };
+    }),
+    workPull: createRouteBodySchema('POST /api/remote/work/pull', (body) => {
+        const maxItems = boundedPositiveNumber(body.maxItems, 1, 100);
+        const leaseMs = boundedPositiveNumber(body.leaseMs, 1_000, 3_600_000);
+        return {
+            ...(maxItems !== undefined ? { maxItems } : {}),
+            ...(leaseMs !== undefined ? { leaseMs } : {}),
+        };
+    }),
+    workComplete: createRouteBodySchema('POST /api/remote/work/:workId/complete', (body) => {
+        const error = readOptionalStringField(body, 'error');
+        return {
+            ...(body.status === 'failed' || body.status === 'cancelled' || body.status === 'completed' ? { status: body.status } : {}),
+            result: body.result,
+            ...(error ? { error } : {}),
+            metadata: readRemoteMetadata(body.metadata),
+        };
+    }),
+    operatorNote: createRouteBodySchema('POST /api/remote/operator-action', (body) => {
+        const note = readOptionalStringField(body, 'note');
+        const reason = readOptionalStringField(body, 'reason');
+        const label = readOptionalStringField(body, 'label');
+        const tokenId = readOptionalStringField(body, 'tokenId');
+        const scopes = readStringArrayField(body, 'scopes', MAX_REMOTE_SCOPES);
+        return {
+            ...(note ? { note } : {}),
+            ...(reason ? { reason } : {}),
+            ...(label ? { label } : {}),
+            ...(tokenId ? { tokenId } : {}),
+            ...(typeof body.requeueClaimedWork === 'boolean' ? { requeueClaimedWork: body.requeueClaimedWork } : {}),
+            ...(scopes ? { scopes } : {}),
+        };
+    }),
+    invoke: createRouteBodySchema('POST /api/remote/peers/:peerId/invoke', (body) => {
+        const command = readOptionalStringField(body, 'command');
+        if (!command)
+            return jsonErrorResponse({ error: 'Missing remote invoke command' }, { status: 400 });
+        const waitMs = boundedPositiveNumber(body.waitMs, 0, 300_000);
+        const timeoutMs = boundedPositiveNumber(body.timeoutMs, 1_000, 300_000);
+        const sessionId = readOptionalStringField(body, 'sessionId');
+        const routeId = readOptionalStringField(body, 'routeId');
+        const automationRunId = readOptionalStringField(body, 'automationRunId');
+        const automationJobId = readOptionalStringField(body, 'automationJobId');
+        const approvalId = readOptionalStringField(body, 'approvalId');
+        return {
+            command,
+            payload: body.payload,
+            priority: body.priority === 'high' || body.priority === 'default' ? body.priority : 'normal',
+            ...(waitMs !== undefined ? { waitMs } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(sessionId ? { sessionId } : {}),
+            ...(routeId ? { routeId } : {}),
+            ...(automationRunId ? { automationRunId } : {}),
+            ...(automationJobId ? { automationJobId } : {}),
+            ...(approvalId ? { approvalId } : {}),
+            metadata: readRemoteMetadata(body.metadata),
+        };
+    }),
+});
 export function createDaemonRemoteRouteHandlers(context) {
     return {
         getRemotePairRequests: () => Response.json({ requests: context.distributedRuntime.listPairRequests() }),
@@ -21,24 +128,13 @@ export async function handleRemotePairRequest(context, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
-    const peerKind = body.peerKind === 'device' ? 'device' : 'node';
-    const label = typeof body.label === 'string' ? body.label.trim() : '';
-    if (!label) {
-        return Response.json({ error: 'Missing remote peer label' }, { status: 400 });
-    }
+    const input = remoteBodySchemas.pairRequest.parse(body);
+    if (input instanceof Response)
+        return input;
     const created = await context.distributedRuntime.requestPairing({
-        peerKind,
-        requestedId: typeof body.requestedId === 'string' ? body.requestedId : undefined,
-        label,
-        platform: typeof body.platform === 'string' ? body.platform : undefined,
-        deviceFamily: typeof body.deviceFamily === 'string' ? body.deviceFamily : undefined,
-        version: typeof body.version === 'string' ? body.version : undefined,
-        clientMode: typeof body.clientMode === 'string' ? body.clientMode : undefined,
-        capabilities: Array.isArray(body.capabilities) ? body.capabilities.filter((value) => typeof value === 'string') : [],
-        commands: Array.isArray(body.commands) ? body.commands.filter((value) => typeof value === 'string') : [],
-        metadata: readMetadataWithClientHintForwardedFor(req, body.metadata),
+        ...input,
+        metadata: readMetadataWithClientHintForwardedFor(req, input.metadata),
         requestedBy: 'remote',
-        ttlMs: boundedPositiveNumber(body.ttlMs, 1_000, 86_400_000),
     });
     return Response.json(created, { status: 201 });
 }
@@ -46,17 +142,15 @@ export async function handleRemotePairVerify(context, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
-    const requestId = typeof body.requestId === 'string' ? body.requestId : '';
-    const challenge = typeof body.challenge === 'string' ? body.challenge : '';
-    if (!requestId || !challenge) {
-        return Response.json({ error: 'Missing requestId or challenge' }, { status: 400 });
-    }
-    const verified = await context.distributedRuntime.verifyPairRequest(requestId, challenge, {
-        metadata: readMetadataWithClientHintForwardedFor(req, body.metadata),
+    const input = remoteBodySchemas.pairVerify.parse(body);
+    if (input instanceof Response)
+        return input;
+    const verified = await context.distributedRuntime.verifyPairRequest(input.requestId, input.challenge, {
+        metadata: readMetadataWithClientHintForwardedFor(req, input.metadata),
     });
     return verified
         ? Response.json(verified)
-        : Response.json({ error: 'Pair request not approved, expired, or invalid' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Pair request not approved, expired, or invalid' }, { status: 404 });
 }
 export async function handleRemotePeerHeartbeat(context, req) {
     const auth = await context.requireRemotePeer(req, 'remote:heartbeat');
@@ -65,12 +159,12 @@ export async function handleRemotePeerHeartbeat(context, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.peerHeartbeat.parse(body);
+    if (input instanceof Response)
+        return input;
     const peer = await context.distributedRuntime.heartbeatPeer(auth, {
-        capabilities: Array.isArray(body.capabilities) ? body.capabilities.filter((value) => typeof value === 'string') : undefined,
-        commands: Array.isArray(body.commands) ? body.commands.filter((value) => typeof value === 'string') : undefined,
-        version: typeof body.version === 'string' ? body.version : undefined,
-        clientMode: typeof body.clientMode === 'string' ? body.clientMode : undefined,
-        metadata: readMetadataWithClientHintForwardedFor(req, body.metadata),
+        ...input,
+        metadata: readMetadataWithClientHintForwardedFor(req, input.metadata),
     });
     return Response.json({ peer });
 }
@@ -81,9 +175,12 @@ export async function handleRemotePeerWorkPull(context, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.workPull.parse(body);
+    if (input instanceof Response)
+        return input;
     const work = await context.distributedRuntime.claimWork(auth, {
-        maxItems: boundedPositiveNumber(body.maxItems, 1, 100),
-        leaseMs: boundedPositiveNumber(body.leaseMs, 1_000, 3_600_000),
+        maxItems: input.maxItems,
+        leaseMs: input.leaseMs,
     });
     return Response.json({ work });
 }
@@ -94,19 +191,24 @@ export async function handleRemotePeerWorkComplete(context, workId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
-    const result = validateRemoteJsonPayload(body.result, MAX_REMOTE_RESULT_BYTES, 'result');
+    const input = remoteBodySchemas.workComplete.parse(body);
+    if (input instanceof Response)
+        return input;
+    const result = validateRemoteJsonPayload(input.result, MAX_REMOTE_RESULT_BYTES, 'result');
     if (result instanceof Response)
         return result;
     const work = await context.distributedRuntime.completeWork(auth, workId, {
-        status: body.status === 'failed' || body.status === 'cancelled' ? body.status : body.status === 'completed' ? 'completed' : undefined,
+        status: input.status,
         result,
-        error: typeof body.error === 'string' ? body.error : undefined,
-        metadata: typeof body.metadata === 'object' && body.metadata !== null ? body.metadata : {},
+        error: input.error,
+        metadata: input.metadata,
     });
     return work
         ? Response.json({ work })
-        : Response.json({ error: 'Unknown or unclaimed remote work item' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown or unclaimed remote work item' }, { status: 404 });
 }
+// Non-numeric input is omitted from downstream calls so services can apply
+// their own defaults.
 function boundedPositiveNumber(value, min, max) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return undefined;
@@ -115,118 +217,95 @@ function boundedPositiveNumber(value, min, max) {
 function validateRemoteJsonPayload(value, maxBytes, field) {
     const size = estimateJsonByteLengthWithinLimit(value ?? null, maxBytes);
     if (size.kind === 'invalid') {
-        return Response.json({
+        return jsonErrorResponse({
             error: `Remote ${field} must be JSON-serializable`,
+            code: 'INVALID_REMOTE_JSON_PAYLOAD',
         }, { status: 400 });
     }
     if (size.byteLength <= maxBytes)
         return value;
-    return Response.json({
-        error: `Remote ${field} exceeds ${maxBytes} byte limit`,
+    return jsonErrorResponse({
+        error: `Remote ${field} exceeds ${maxBytes} bytes after JSON encoding. Reduce payload size before retrying.`,
+        code: 'REMOTE_PAYLOAD_TOO_LARGE',
     }, { status: 413 });
 }
-function estimateJsonByteLengthWithinLimit(value, maxBytes, seen = new Set()) {
-    const byteLength = measureJsonByteLength(value, maxBytes, seen);
-    return byteLength === undefined ? { kind: 'invalid' } : { kind: 'ok', byteLength };
-}
-function measureJsonByteLength(value, maxBytes, seen) {
-    const valueType = typeof value;
-    if (value === null)
-        return 4;
-    if (typeof value === 'string')
-        return jsonStringByteLength(value, maxBytes);
-    if (valueType === 'number')
-        return Number.isFinite(value) ? String(value).length : 4;
-    if (valueType === 'boolean')
-        return value ? 4 : 5;
-    if (valueType === 'undefined' || valueType === 'function' || valueType === 'symbol')
-        return 4;
-    if (valueType !== 'object')
-        return undefined;
-    const objectValue = value;
-    if (seen.has(objectValue))
-        return undefined;
-    seen.add(objectValue);
-    try {
-        let total = 2;
-        if (Array.isArray(value)) {
-            for (let index = 0; index < value.length; index += 1) {
-                if (index > 0)
-                    total += 1;
-                if (total > maxBytes)
-                    return total;
-                const entrySize = measureJsonByteLength(value[index], maxBytes - total, seen);
-                if (entrySize === undefined)
-                    return undefined;
-                total += entrySize;
-                if (total > maxBytes) {
-                    return total;
-                }
-            }
-            return total;
+/**
+ * Compute the exact JSON-encoded byte length of a string without allocating the encoded form.
+ * Walks each code unit and counts the bytes JSON.stringify would emit:
+ *   - 2 bytes for the surrounding quotes
+ *   - 2 bytes for short-escape characters (", \, \b, \t, \n, \f, \r)
+ *   - 6 bytes for other control chars (\uXXXX)
+ *   - 1–4 bytes per non-control code point (UTF-8 encoding length)
+ */
+function jsonStringByteLength(s) {
+    let len = 2; // surrounding quotes
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c === 0x22 || c === 0x5c || c === 0x08 || c === 0x09 || c === 0x0a || c === 0x0c || c === 0x0d) {
+            len += 2; // \" \\ \b \t \n \f \r
         }
-        let count = 0;
-        for (const [key, entryValue] of Object.entries(value)) {
-            const entryType = typeof entryValue;
-            if (entryType === 'undefined' || entryType === 'function' || entryType === 'symbol')
-                continue;
-            if (count > 0)
-                total += 1;
-            total += jsonStringByteLength(key, maxBytes - total) + 1;
-            if (total > maxBytes)
-                return total;
-            const entrySize = measureJsonByteLength(entryValue, maxBytes - total, seen);
-            if (entrySize === undefined)
-                return undefined;
-            total += entrySize;
-            count += 1;
-            if (total > maxBytes) {
-                return total;
-            }
+        else if (c < 0x20) {
+            len += 6; // \uXXXX
         }
-        return total;
-    }
-    finally {
-        seen.delete(objectValue);
-    }
-}
-function jsonStringByteLength(value, maxBytes = Number.POSITIVE_INFINITY) {
-    let total = 2;
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code === 0x22 || code === 0x5c || code === 0x08 || code === 0x0c || code === 0x0a || code === 0x0d || code === 0x09) {
-            total += 2;
+        else if (c < 0x80) {
+            len += 1;
         }
-        else if (code <= 0x1f) {
-            total += 6;
+        else if (c < 0x800) {
+            len += 2;
         }
-        else if (code >= 0xd800 && code <= 0xdbff) {
-            const next = value.charCodeAt(index + 1);
-            if (next >= 0xdc00 && next <= 0xdfff) {
-                total += 4;
-                index += 1;
-            }
-            else {
-                total += 6;
-            }
-        }
-        else if (code >= 0xdc00 && code <= 0xdfff) {
-            total += 6;
+        else if ((c & 0xfc00) === 0xd800 && i + 1 < s.length && (s.charCodeAt(i + 1) & 0xfc00) === 0xdc00) {
+            len += 4; // surrogate pair → 4-byte UTF-8
+            i++;
         }
         else {
-            total += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : 3;
+            len += 3;
         }
-        if (total > maxBytes)
-            return total;
     }
-    return total;
+    return len;
 }
-function readMetadataWithClientHintForwardedFor(req, value) {
-    const metadata = typeof value === 'object' && value !== null && !Array.isArray(value)
-        ? { ...value }
+export function estimateJsonByteLengthWithinLimit(value, maxBytes) {
+    // walk the value with a counting replacer so we never allocate
+    // the full encoded string. The replacer throws a sentinel when the running
+    // byte total exceeds maxBytes, preventing peak allocation before the cap.
+    // switched from `val.length * 6` worst-case to exact
+    // jsonStringByteLength() count — same allocation profile, much tighter near the cap.
+    let byteCount = 0;
+    const OVER_LIMIT = Symbol('over-limit');
+    try {
+        JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'string') {
+                byteCount += jsonStringByteLength(val);
+            }
+            else {
+                // null/number/boolean/object-open/array-open — add a small fixed cost per node.
+                byteCount += 16;
+            }
+            if (byteCount > maxBytes) {
+                // eslint-disable-next-line @typescript-eslint/no-throw-literal
+                throw OVER_LIMIT;
+            }
+            return val;
+        });
+        if (value === undefined)
+            return { kind: 'ok', byteLength: 4 }; // undefined → JSON undefined
+        // Result is an exact-count for strings; node-overhead remains a fixed approximation.
+        return { kind: 'ok', byteLength: Math.min(byteCount, maxBytes + 1) };
+    }
+    catch (err) {
+        if (err === OVER_LIMIT)
+            return { kind: 'ok', byteLength: maxBytes + 1 };
+        return { kind: 'invalid' };
+    }
+}
+function readRemoteMetadata(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
         : {};
+}
+function readMetadataWithClientHintForwardedFor(req, value) {
+    const metadata = { ...readRemoteMetadata(value) };
     const clientHintForwardedFor = readClientHintForwardedFor(req);
-    return clientHintForwardedFor ? { ...metadata, clientHintForwardedFor } : metadata;
+    return clientHintForwardedFor ? { ...metadata, x_forwarded_for_untrusted: clientHintForwardedFor } : metadata;
 }
 function readClientHintForwardedFor(req) {
     // x-forwarded-for is caller-controlled unless the daemon is explicitly behind
@@ -245,15 +324,18 @@ async function handleApproveRemotePairRequest(context, requestId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.operatorNote.parse(body);
+    if (input instanceof Response)
+        return input;
     const approved = await context.distributedRuntime.approvePairRequest(requestId, {
         actor: operatorActor(context, req),
-        note: typeof body.note === 'string' ? body.note : undefined,
-        label: typeof body.label === 'string' ? body.label : undefined,
-        metadata: typeof body.metadata === 'object' && body.metadata !== null ? body.metadata : {},
+        note: input.note,
+        label: input.label,
+        metadata: readRemoteMetadata(body.metadata),
     });
     return approved
         ? Response.json(approved)
-        : Response.json({ error: 'Unknown remote pair request' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown remote pair request' }, { status: 404 });
 }
 async function handleRejectRemotePairRequest(context, requestId, req) {
     const admin = context.requireAdmin(req);
@@ -262,13 +344,16 @@ async function handleRejectRemotePairRequest(context, requestId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.operatorNote.parse(body);
+    if (input instanceof Response)
+        return input;
     const rejected = await context.distributedRuntime.rejectPairRequest(requestId, {
         actor: operatorActor(context, req),
-        note: typeof body.note === 'string' ? body.note : undefined,
+        note: input.note,
     });
     return rejected
         ? Response.json(rejected)
-        : Response.json({ error: 'Unknown remote pair request' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown remote pair request' }, { status: 404 });
 }
 async function handleRotateRemotePeerToken(context, peerId, req) {
     const admin = context.requireAdmin(req);
@@ -277,14 +362,17 @@ async function handleRotateRemotePeerToken(context, peerId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.operatorNote.parse(body);
+    if (input instanceof Response)
+        return input;
     const rotated = await context.distributedRuntime.rotatePeerToken(peerId, {
         actor: operatorActor(context, req),
-        label: typeof body.label === 'string' ? body.label : undefined,
-        scopes: Array.isArray(body.scopes) ? body.scopes.filter((value) => typeof value === 'string') : undefined,
+        label: input.label,
+        scopes: input.scopes,
     });
     return rotated
         ? Response.json(rotated)
-        : Response.json({ error: 'Unknown distributed peer' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown distributed peer' }, { status: 404 });
 }
 async function handleRevokeRemotePeerToken(context, peerId, req) {
     const admin = context.requireAdmin(req);
@@ -293,14 +381,17 @@ async function handleRevokeRemotePeerToken(context, peerId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.operatorNote.parse(body);
+    if (input instanceof Response)
+        return input;
     const peer = await context.distributedRuntime.revokePeerToken(peerId, {
         actor: operatorActor(context, req),
-        tokenId: typeof body.tokenId === 'string' ? body.tokenId : undefined,
-        note: typeof body.note === 'string' ? body.note : undefined,
+        tokenId: input.tokenId,
+        note: input.note,
     });
     return peer
         ? Response.json({ peer })
-        : Response.json({ error: 'Unknown distributed peer' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown distributed peer' }, { status: 404 });
 }
 async function handleDisconnectRemotePeer(context, peerId, req) {
     const admin = context.requireAdmin(req);
@@ -309,14 +400,17 @@ async function handleDisconnectRemotePeer(context, peerId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.operatorNote.parse(body);
+    if (input instanceof Response)
+        return input;
     const peer = await context.distributedRuntime.disconnectPeer(peerId, {
         actor: operatorActor(context, req),
-        note: typeof body.note === 'string' ? body.note : undefined,
-        requeueClaimedWork: typeof body.requeueClaimedWork === 'boolean' ? body.requeueClaimedWork : undefined,
+        note: input.note,
+        requeueClaimedWork: input.requeueClaimedWork,
     });
     return peer
         ? Response.json({ peer })
-        : Response.json({ error: 'Unknown distributed peer' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown distributed peer' }, { status: 404 });
 }
 async function handleInvokeRemotePeer(context, peerId, req) {
     const admin = context.requireAdmin(req);
@@ -325,28 +419,27 @@ async function handleInvokeRemotePeer(context, peerId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
-    const command = typeof body.command === 'string' ? body.command.trim() : '';
-    if (!command) {
-        return Response.json({ error: 'Missing remote invoke command' }, { status: 400 });
-    }
-    const payload = validateRemoteJsonPayload(body.payload, MAX_REMOTE_PAYLOAD_BYTES, 'payload');
+    const input = remoteBodySchemas.invoke.parse(body);
+    if (input instanceof Response)
+        return input;
+    const payload = validateRemoteJsonPayload(input.payload, MAX_REMOTE_PAYLOAD_BYTES, 'payload');
     if (payload instanceof Response)
         return payload;
     try {
         const invoked = await context.distributedRuntime.invokePeer({
             peerId,
-            command,
+            command: input.command,
             payload,
-            priority: body.priority === 'high' || body.priority === 'default' ? body.priority : 'normal',
+            priority: input.priority,
             actor: operatorActor(context, req),
-            waitMs: boundedPositiveNumber(body.waitMs, 0, 300_000),
-            timeoutMs: boundedPositiveNumber(body.timeoutMs, 1_000, 300_000),
-            sessionId: typeof body.sessionId === 'string' ? body.sessionId : undefined,
-            routeId: typeof body.routeId === 'string' ? body.routeId : undefined,
-            automationRunId: typeof body.automationRunId === 'string' ? body.automationRunId : undefined,
-            automationJobId: typeof body.automationJobId === 'string' ? body.automationJobId : undefined,
-            approvalId: typeof body.approvalId === 'string' ? body.approvalId : undefined,
-            metadata: typeof body.metadata === 'object' && body.metadata !== null ? body.metadata : {},
+            waitMs: input.waitMs,
+            timeoutMs: input.timeoutMs,
+            sessionId: input.sessionId,
+            routeId: input.routeId,
+            automationRunId: input.automationRunId,
+            automationJobId: input.automationJobId,
+            approvalId: input.approvalId,
+            metadata: input.metadata,
         });
         return Response.json(invoked, { status: 202 });
     }
@@ -361,11 +454,14 @@ async function handleCancelRemoteWork(context, workId, req) {
     const body = await context.parseJsonBody(req);
     if (body instanceof Response)
         return body;
+    const input = remoteBodySchemas.operatorNote.parse(body);
+    if (input instanceof Response)
+        return input;
     const work = await context.distributedRuntime.cancelWork(workId, {
         actor: operatorActor(context, req),
-        reason: typeof body.reason === 'string' ? body.reason : undefined,
+        reason: input.reason,
     });
     return work
         ? Response.json({ work })
-        : Response.json({ error: 'Unknown remote work item' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown remote work item' }, { status: 404 });
 }

package/dist/route-helpers.d.ts

@@ -1,16 +1,27 @@
 export type JsonRecord = Record<string, unknown>;
+export type JsonBody = JsonRecord;
+export interface RouteBodySchema<T> {
+    readonly routeId: string;
+    readonly parse: (body: JsonRecord) => T | Response;
+}
+export declare function createRouteBodySchema<T>(routeId: string, parse: (body: JsonRecord) => T | Response): RouteBodySchema<T>;
+export declare function createRouteBodySchemaRegistry<const TSchemaMap extends Record<string, RouteBodySchema<unknown>>>(schemas: TSchemaMap): TSchemaMap;
 export declare function isJsonRecord(value: unknown): value is JsonRecord;
 export declare function toSerializableJson(value: unknown, stack?: Map<object, string>, path?: string): unknown;
 export declare function serializableJsonResponse(body: unknown, init?: ResponseInit): Response;
 export interface BoundedIntegerOptions {
     readonly fallback: number;
-    readonly min?: number;
-    readonly max?: number;
+    readonly min?: number | undefined;
+    readonly max?: number | undefined;
 }
 export declare function readBoundedInteger(raw: string | null, options: BoundedIntegerOptions): number;
 export declare function readBoundedPositiveInteger(raw: string | null, fallback: number, max?: number): number;
+export declare function readBoundedBodyInteger(value: unknown, fallback: number, max: number, min?: number): number;
 export declare function readOptionalBoundedInteger(raw: string | null, min: number, max: number): number | undefined;
+export declare function readOptionalStringField(body: JsonRecord, key: string): string | undefined;
+export declare function readStringArrayField(body: JsonRecord, key: string, max?: number): string[] | undefined;
 export declare function scopeMatches(granted: string, required: string): boolean;
+export declare function hasAnyScope(grantedScopes: readonly string[] | undefined, requiredScopes: readonly string[]): boolean;
 export declare function missingScopes(grantedScopes: readonly string[] | undefined, requiredScopes: readonly string[]): string[];
 export type ChannelLifecycleAction = 'inspect' | 'setup' | 'retest' | 'connect' | 'disconnect' | 'start' | 'stop' | 'login' | 'logout' | 'wait_login';
 export type ChannelConversationKind = 'direct' | 'group' | 'channel' | 'thread' | 'service';

package/dist/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../src/route-helpers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,sBAA4B,EAAE,IAAI,SAAM,GAAG,OAAO,CAiBzG;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,QAAQ,CAErF;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAO7F;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAQ,GAAG,MAAM,CAEpG;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK3G;AAMD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMvE;AAED,wBAAgB,aAAa,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAGvH;AAED,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,OAAO,GACP,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,OAAO,GACP,MAAM,GACN,OAAO,GACP,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5F,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAaxF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,GAAG,IAAI,CAI1F"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../src/route-helpers.ts"],"names":[],"mappings":"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"}