Skip to content

Commit 0b8aabe

Browse files
steipetesteipete
authored
docs: document auth profile failure policy contract (#89613)
* docs: document markdown marker renderer * docs: document rendered markdown chunking * docs: document markdown text chunking * docs: document shared text chunking * docs: document plugin text chunking exports * docs: document avatar policy constants * docs: document node match candidates * docs: document scoped expiring id cache * docs: document runtime import normalization * docs: document string sample summaries * docs: document session usage timeseries types * docs: document session usage response types * docs: document manifest frontmatter shapes * docs: document channel route input metadata * docs: document pair loop guard settings * docs: document migration config patch helpers * docs: document api provider registry * docs: document tool call repair payloads * docs: document plugin tool payload helpers * docs: document lazy promise loader * docs: document store writer queue state * docs: document thread binding lifecycle * docs: document concurrency helper contract * docs: document gateway client info contract * docs: document delivery context contracts * docs: document secret ref defaults contract * docs: document command gating contract * docs: document avatar policy contract * docs: document node match policy * docs: document message channel normalization * docs: document boolean parsing contract * docs: document zod parse helpers * docs: document direct dm guard policy * docs: document fixed window limiter contract * docs: document node presence event contract * docs: document secret normalization contract * docs: document progress draft line removal * docs: document usage formatting contracts * docs: document agent run status contract * docs: document runtime import helpers * docs: document provider utility ownership * docs: document invalid config helpers * docs: document json compat parser * docs: document channel config metadata ownership * docs: document channel logging helpers * docs: document sender identity validation ownership * docs: document string sampling helper * docs: document global singleton helpers * docs: document transcript tool helpers * docs: document exec safe-bin normalization * docs: document reaction level resolver * docs: document account snapshot redaction boundary * docs: document messaging target helpers * docs: document thread binding messages * docs: document conversation binding context * docs: document conversation resolution helper * docs: document owner display secret retention * docs: document provider request config types * docs: document skills config types * docs: document memory config types * docs: document imessage config types * docs: document crestodian config types * docs: document tools config policies * docs: document shared config base types * docs: document channel config contracts * docs: document openclaw config state types * docs: document model config contracts * docs: document shared agent config types * docs: document agent defaults config types * docs: document secret input contracts * docs: document auth config contracts * docs: document gateway config contracts * docs: document tool call stream repair contracts * docs: document memory host facades * docs: document llm core contracts * docs: document markdown core contracts * docs: document gateway connect error contracts * docs: document gateway protocol primitives * docs: document gateway frame schemas * docs: document gateway device schemas * docs: document gateway environment schemas * docs: document gateway push schemas * docs: document gateway plugin schemas * docs: document gateway artifact schemas * docs: document gateway command schemas * docs: document gateway task schemas * docs: document gateway exec approval schemas * docs: document gateway secret schemas * docs: document gateway config schemas * docs: document gateway snapshot schemas * docs: document gateway chat schemas * docs: document gateway wizard schemas * docs: document gateway node schemas * docs: document gateway plugin approval schemas * docs: document gateway talk schemas * docs: document gateway agent schemas * docs: document gateway session schemas * docs: document gateway cron schemas * docs: document gateway agent model skill schemas * docs: document gateway skill proposal tool schemas * docs: document gateway protocol registry * docs: document gateway channel status schemas * docs: document gateway schema regression tests * docs: document gateway schema barrel * docs: document gateway validator tests * docs: document gateway primitive push tests * docs: document gateway contract tests * docs: document native protocol guard * docs: document channel schema tests * docs: document gateway protocol smoke tests * docs: document gateway protocol entrypoint * docs: document gateway protocol type exports * docs: document gateway error codes * docs: document protocol schema registry * docs: document talk audio codec * docs: document talk activation names * docs: document talk consult questions * docs: document talk consult tool * docs: document talk run control contracts * docs: document talk run control adapter * docs: document talkback consult queue * docs: document talk consult transcript guard * docs: document talk fast context runtime * docs: document forced talk consult coordinator * docs: document talk output activity tracker * docs: document talk event metrics * docs: document talk diagnostics * docs: document talk observability hook * docs: document talk provider resolver * docs: document talk provider registry * docs: document talk runtime primitives * docs: document talk consult controller logs * docs: document channel identity helpers * docs: document channel account allowlist helpers * docs: document channel metadata draft controls * docs: document channel ingress policy * docs: document channel sender access gates * docs: document channel catalog message contracts * docs: document channel account plugin helpers * docs: document configured binding helpers * docs: document channel acp approval config helpers * docs: document channel bundled config write helpers * docs: document channel plugin utility contracts * docs: document channel config access helpers * docs: document channel message action helpers * docs: document channel outbound runtime helpers * docs: document channel pairing promotion helpers * docs: document channel registry helpers * docs: document channel setup wizard helpers * docs: document channel lifecycle status helpers * docs: document channel target thread helpers * docs: document channel session binding helpers * docs: document channel package module probes * docs: document channel setup wizard contracts * docs: document channel plugin API barrels * docs: document channel contract test helpers * docs: document channel core helpers * docs: document small core facades * docs: document provider runtime helpers * docs: document persistence and realtime helpers * docs: document mcp and state helpers * docs: document tool planner contracts * docs: document music generation runtime * docs: document crestodian command flow * docs: document utility helpers * docs: document node host helpers * docs: document transcript contracts * docs: document trajectory export contracts * docs: document image generation contracts * docs: document routing helper contracts * docs: document session helper contracts * docs: document video generation contracts * docs: document model catalog contracts * docs: document proxy capture contracts * docs: document status rendering contracts * docs: document test helper contracts * docs: document wizard setup contracts * docs: document process contracts * docs: document memory host sdk contracts * docs: document tts contracts * docs: document secrets runtime contracts * docs: document shared helper contracts * docs: document hook runtime contracts * docs: document security audit contracts * docs: document flow contracts * docs: document media understanding contracts * docs: document tui contracts * docs: document logging contracts * docs: document llm contracts * docs: document cron contracts * docs: document daemon contracts * docs: document task contracts * docs: document acp contracts * docs: document test utility contracts * docs: document skill contracts * docs: document config contracts * docs: document outbound infra contracts * docs: document command analysis contracts * docs: document provider usage infra contracts * docs: document file safety infra contracts * docs: document exec approval infra contracts * docs: document gateway runtime infra contracts * docs: document infra utility contracts * docs: document infra queue storage contracts * docs: document heartbeat infra contracts * docs: document remaining infra contracts * docs: document gateway auth contracts * docs: document gateway display helpers * docs: document gateway http helpers * docs: document gateway node helpers * docs: document gateway mcp helpers * docs: document gateway support helpers * docs: document gateway server runtime helpers * docs: document gateway runtime bootstrap helpers * docs: document gateway session events * docs: document gateway utility helpers * docs: document gateway talk helpers * docs: document gateway helper contracts * docs: document gateway server method helpers * docs: document gateway server auth helpers * docs: document gateway server tests * docs: document gateway test helpers * docs: document gateway node tests * docs: document gateway channel tests * docs: document gateway session tests * docs: document gateway server startup tests * docs: document gateway tool test helpers * docs: document gateway server test helpers * docs: document gateway server method tests * docs: document remaining gateway tests * docs: document plugin sdk public subpaths * docs: document plugin sdk runtime helpers * docs: document plugin sdk memory provider helpers * docs: document plugin sdk runtime facades * docs: document plugin sdk command approval helpers * docs: document plugin sdk runtime types * docs: document plugin sdk browser account helpers * docs: document plugin sdk media memory helpers * docs: document plugin sdk core tests * docs: document plugin sdk contract helpers * docs: document plugin sdk test helpers * docs: document remaining plugin sdk tests * docs: document cli utility helpers * docs: document cli runtime helpers * docs: document cli command registration helpers * docs: document node cli helpers * docs: document cli program registration * docs: document message cli registration * docs: document daemon cli helpers * docs: document cli route parsers
1 parent 8de37e1 commit 0b8aabe

2,172 files changed

Lines changed: 13969 additions & 363 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎packages/gateway-protocol/src/channels.schema.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,14 @@ import { Compile } from "typebox/compile";
22
import { describe, expect, it } from "vitest";
33
import { ChannelsStatusResultSchema, WebLoginWaitParamsSchema } from "./schema/channels.js";
44

5+
/**
6+
* Channel schema regressions for browser login and status diagnostics.
7+
* These payloads are consumed by dashboard/operator UI, so QR payload bounds
8+
* and event-loop diagnostic shape are part of the public gateway contract.
9+
*/
10+
511
describe("WebLoginWaitParamsSchema", () => {
12+
/** Compiled validator reused across QR bounds cases. */
613
const validate = Compile(WebLoginWaitParamsSchema);
714

815
it("bounds caller-provided QR data URLs", () => {
@@ -26,6 +33,7 @@ describe("WebLoginWaitParamsSchema", () => {
2633
});
2734

2835
describe("ChannelsStatusResultSchema", () => {
36+
/** Compiled status validator for channel docking diagnostics. */
2937
const validate = Compile(ChannelsStatusResultSchema);
3038

3139
it("accepts gateway event-loop diagnostics emitted by channels.status", () => {

‎packages/gateway-protocol/src/client-info.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* Shared gateway client identity contract.
3+
*
4+
* These values cross the WebSocket handshake boundary, so additions must stay
5+
* aligned with protocol schemas and server policy checks.
6+
*/
17
function normalizeOptionalLowercaseString(raw?: string | null): string | undefined {
28
if (typeof raw !== "string") {
39
return undefined;
@@ -6,6 +12,7 @@ function normalizeOptionalLowercaseString(raw?: string | null): string | undefin
612
return normalized || undefined;
713
}
814

15+
/** Canonical client ids accepted in gateway hello/connect payloads. */
916
export const GATEWAY_CLIENT_IDS = {
1017
WEBCHAT_UI: "webchat-ui",
1118
CONTROL_UI: "openclaw-control-ui",
@@ -30,6 +37,7 @@ export const GATEWAY_CLIENT_NAMES = GATEWAY_CLIENT_IDS;
3037
/** Compatibility alias for internal callers that still use "name" terminology. */
3138
export type GatewayClientName = GatewayClientId;
3239

40+
/** Coarse modes let policy group clients without matching every product id. */
3341
export const GATEWAY_CLIENT_MODES = {
3442
WEBCHAT: "webchat",
3543
CLI: "cli",
@@ -45,16 +53,25 @@ export type GatewayClientMode = (typeof GATEWAY_CLIENT_MODES)[keyof typeof GATEW
4553

4654
/** Client metadata sent during gateway connection setup. */
4755
export type GatewayClientInfo = {
56+
/** Stable product/client identifier from `GATEWAY_CLIENT_IDS`. */
4857
id: GatewayClientId;
58+
/** Human-readable label for diagnostics; not used for policy decisions. */
4959
displayName?: string;
60+
/** Client app or package version reported by the connecting process. */
5061
version: string;
62+
/** Runtime platform string, such as `darwin`, `ios`, `android`, or `web`. */
5163
platform: string;
64+
/** Optional device family used by native clients for display and routing hints. */
5265
deviceFamily?: string;
66+
/** Native hardware/model identifier when available. */
5367
modelIdentifier?: string;
68+
/** Coarse category from `GATEWAY_CLIENT_MODES` for policy and diagnostics. */
5469
mode: GatewayClientMode;
70+
/** Per-installation or per-process id used to distinguish same-product clients. */
5571
instanceId?: string;
5672
};
5773

74+
/** Capability flags a client may advertise during the gateway handshake. */
5875
export const GATEWAY_CLIENT_CAPS = {
5976
TOOL_EVENTS: "tool-events",
6077
} as const;
@@ -67,6 +84,8 @@ const GATEWAY_CLIENT_MODE_SET = new Set<GatewayClientMode>(Object.values(GATEWAY
6784

6885
/** Normalizes untrusted client ids and rejects unknown values. */
6986
export function normalizeGatewayClientId(raw?: string | null): GatewayClientId | undefined {
87+
// Handshake input is intentionally case-insensitive, but policy decisions use
88+
// the canonical lowercase ids from the closed registry above.
7089
const normalized = normalizeOptionalLowercaseString(raw);
7190
if (!normalized) {
7291
return undefined;

‎packages/gateway-protocol/src/connect-error-details.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,14 @@ import {
1616
resolveAuthConnectErrorDetailCode,
1717
} from "./connect-error-details.js";
1818

19+
/**
20+
* Connect error detail regressions for Gateway/WebSocket clients.
21+
*
22+
* These tests pin structured auth/pairing details, human-readable fallback
23+
* formatting, and request-id sanitization because these strings surface in
24+
* control UI reconnect flows and device pairing diagnostics.
25+
*/
26+
1927
describe("readConnectErrorDetailCode", () => {
2028
it("reads structured detail codes", () => {
2129
expect(readConnectErrorDetailCode({ code: "AUTH_TOKEN_MISMATCH" })).toBe("AUTH_TOKEN_MISMATCH");

‎packages/gateway-protocol/src/connect-error-details.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* Shared gateway connect-error detail helpers.
3+
*
4+
* These details cross client/server boundaries, so readers normalize untrusted
5+
* payloads before using them in reconnect decisions or user-facing messages.
6+
*/
17
function normalizeOptionalString(value: unknown): string | undefined {
28
if (typeof value !== "string") {
39
return undefined;
@@ -18,6 +24,7 @@ function normalizeArrayBackedTrimmedStringList(value: unknown): string[] | undef
1824
return values.length > 0 ? values : undefined;
1925
}
2026

27+
/** Structured connect-error codes carried in gateway error `details.code`. */
2128
export const ConnectErrorDetailCodes = {
2229
AUTH_REQUIRED: "AUTH_REQUIRED",
2330
AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
@@ -53,6 +60,7 @@ export const ConnectErrorDetailCodes = {
5360
export type ConnectErrorDetailCode =
5461
(typeof ConnectErrorDetailCodes)[keyof typeof ConnectErrorDetailCodes];
5562

63+
/** Pairing-specific reasons clients can display and use for reconnect policy. */
5664
export const ConnectPairingRequiredReasons = {
5765
NOT_PAIRED: "not-paired",
5866
ROLE_UPGRADE: "role-upgrade",
@@ -63,18 +71,21 @@ export const ConnectPairingRequiredReasons = {
6371
export type ConnectPairingRequiredReason =
6472
(typeof ConnectPairingRequiredReasons)[keyof typeof ConnectPairingRequiredReasons];
6573

74+
/** Suggested client-side recovery action for structured connect errors. */
6675
export type ConnectRecoveryNextStep =
6776
| "retry_with_device_token"
6877
| "update_auth_configuration"
6978
| "update_auth_credentials"
7079
| "wait_then_retry"
7180
| "review_auth_configuration";
7281

82+
/** Optional retry guidance extracted from gateway connect-error details. */
7383
export type ConnectErrorRecoveryAdvice = {
7484
canRetryWithDeviceToken?: boolean;
7585
recommendedNextStep?: ConnectRecoveryNextStep;
7686
};
7787

88+
/** Full structured details for pairing-required connect failures. */
7889
export type PairingConnectErrorDetails = {
7990
code: typeof ConnectErrorDetailCodes.PAIRING_REQUIRED;
8091
reason?: ConnectPairingRequiredReason;
@@ -90,6 +101,7 @@ export type PairingConnectErrorDetails = {
90101
approvedScopes?: string[];
91102
};
92103

104+
/** Compact pairing-required subset used by reconnect/status surfaces. */
93105
export type ConnectPairingRequiredDetails = Pick<
94106
PairingConnectErrorDetails,
95107
"reason" | "requestId"
@@ -152,6 +164,7 @@ const CONNECT_PAIRING_REQUIRED_MESSAGE_BY_REASON: Readonly<
152164
"metadata-upgrade": "device metadata change pending approval",
153165
};
154166

167+
/** Maps internal auth failure reasons to public connect-error detail codes. */
155168
export function resolveAuthConnectErrorDetailCode(
156169
reason: string | undefined,
157170
): ConnectErrorDetailCode {
@@ -191,6 +204,7 @@ export function resolveAuthConnectErrorDetailCode(
191204
}
192205
}
193206

207+
/** Maps device-auth verifier reasons to public connect-error detail codes. */
194208
export function resolveDeviceAuthConnectErrorDetailCode(
195209
reason: string | undefined,
196210
): ConnectErrorDetailCode {
@@ -212,6 +226,7 @@ export function resolveDeviceAuthConnectErrorDetailCode(
212226
}
213227
}
214228

229+
/** Reads a non-empty detail code from an untrusted error details payload. */
215230
export function readConnectErrorDetailCode(details: unknown): string | null {
216231
if (!details || typeof details !== "object" || Array.isArray(details)) {
217232
return null;
@@ -220,6 +235,7 @@ export function readConnectErrorDetailCode(details: unknown): string | null {
220235
return typeof code === "string" && code.trim().length > 0 ? code : null;
221236
}
222237

238+
/** Extracts normalized retry advice from untrusted connect-error details. */
223239
export function readConnectErrorRecoveryAdvice(details: unknown): ConnectErrorRecoveryAdvice {
224240
if (!details || typeof details !== "object" || Array.isArray(details)) {
225241
return {};
@@ -249,6 +265,7 @@ function normalizePairingConnectReason(value: unknown): ConnectPairingRequiredRe
249265
: undefined;
250266
}
251267

268+
/** Normalizes pairing request ids before echoing them in close reasons or UI text. */
252269
export function normalizePairingConnectRequestId(value: unknown): string | undefined {
253270
const normalized = normalizeOptionalString(value);
254271
return normalized && PAIRING_CONNECT_REQUEST_ID_PATTERN.test(normalized) ? normalized : undefined;
@@ -287,6 +304,7 @@ function createPairingConnectErrorDetails(params: {
287304
};
288305
}
289306

307+
/** Human-readable requirement summary for a pairing-required reason. */
290308
export function describePairingConnectRequirement(
291309
reason: ConnectPairingRequiredReason | undefined,
292310
): string {
@@ -295,6 +313,7 @@ export function describePairingConnectRequirement(
295313
: "device approval is required";
296314
}
297315

316+
/** Builds the gateway close/error message for a pairing-required connect failure. */
298317
export function buildPairingConnectErrorMessage(
299318
reason: ConnectPairingRequiredReason | undefined,
300319
): string {
@@ -311,6 +330,7 @@ function buildPairingConnectRemediationHint(
311330
: "Approve the pending device request before retrying.";
312331
}
313332

333+
/** Short user-facing recovery title for pairing-required connect failures. */
314334
export function buildPairingConnectRecoveryTitle(
315335
reason: ConnectPairingRequiredReason | undefined,
316336
): string {
@@ -319,6 +339,7 @@ export function buildPairingConnectRecoveryTitle(
319339
: "Gateway pairing approval required.";
320340
}
321341

342+
/** Builds sanitized structured details for a pairing-required connect failure. */
322343
export function buildPairingConnectErrorDetails(params: {
323344
reason: ConnectPairingRequiredReason | undefined;
324345
requestId?: string;
@@ -356,6 +377,7 @@ export function buildPairingConnectErrorDetails(params: {
356377
});
357378
}
358379

380+
/** Builds a sanitized close reason string for WebSocket pairing rejections. */
359381
export function buildPairingConnectCloseReason(params: {
360382
reason: ConnectPairingRequiredReason | undefined;
361383
requestId?: string;
@@ -365,6 +387,7 @@ export function buildPairingConnectCloseReason(params: {
365387
return requestId ? `${message} (requestId: ${requestId})` : message;
366388
}
367389

390+
/** Reads and backfills pairing-required details from an untrusted details object. */
368391
export function readPairingConnectErrorDetails(
369392
details: unknown,
370393
): PairingConnectErrorDetails | null {
@@ -417,6 +440,7 @@ export function readPairingConnectErrorDetails(
417440
});
418441
}
419442

443+
/** Reads the compact pairing-required subset from untrusted connect details. */
420444
export function readConnectPairingRequiredDetails(
421445
details: unknown,
422446
): ConnectPairingRequiredDetails | null {
@@ -430,6 +454,7 @@ export function readConnectPairingRequiredDetails(
430454
};
431455
}
432456

457+
/** Parses legacy/string-only pairing-required messages into structured details. */
433458
export function readConnectPairingRequiredMessage(
434459
message: string | null | undefined,
435460
): ConnectPairingRequiredDetails | null {
@@ -462,6 +487,7 @@ export function readConnectPairingRequiredMessage(
462487
};
463488
}
464489

490+
/** Formats pairing-required details into the canonical user-facing message. */
465491
export function formatConnectPairingRequiredMessage(details: unknown): string {
466492
const pairing = readPairingConnectErrorDetails(details);
467493
const base =
@@ -471,6 +497,7 @@ export function formatConnectPairingRequiredMessage(details: unknown): string {
471497
return pairing?.requestId ? `${base} (requestId: ${pairing.requestId})` : base;
472498
}
473499

500+
/** Formats connect errors using structured details before falling back to raw messages. */
474501
export function formatConnectErrorMessage(params: { message?: string; details?: unknown }): string {
475502
if (readConnectErrorDetailCode(params.details) === ConnectErrorDetailCodes.PAIRING_REQUIRED) {
476503
return formatConnectPairingRequiredMessage(params.details);

‎packages/gateway-protocol/src/cron-validators.test.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ import {
99
validateCronUpdateParams,
1010
} from "./index.js";
1111

12+
/**
13+
* Cron validator regressions for public scheduler RPC payloads.
14+
*
15+
* The cases cover both canonical `id` selectors and legacy `jobId` aliases,
16+
* delivery routing, update clears, and run-log path traversal guards.
17+
*/
18+
19+
/** Smallest valid cron job create payload shared by add/update variations. */
1220
const minimalAddParams = {
1321
name: "daily-summary",
1422
schedule: { kind: "every", everyMs: 60_000 },

‎packages/gateway-protocol/src/exec-approvals-validators.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@ import {
55
validateExecApprovalsSetParams,
66
} from "./index.js";
77

8+
/**
9+
* Exec approval validator regressions for gateway and node-scoped policy
10+
* writes. The fixtures pin runtime-owned allowlist metadata and command-span
11+
* bounds because those contracts are consumed by approval UI and replay logic.
12+
*/
13+
814
describe("exec approvals protocol validators", () => {
915
it("accepts runtime-owned allowlist metadata on gateway and node set payloads", () => {
1016
const file = {

‎packages/gateway-protocol/src/index.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,15 @@ import {
3636
type ValidationError,
3737
} from "./index.js";
3838

39+
/**
40+
* Broad protocol validator smoke tests.
41+
*
42+
* This file exercises exported lazy validators, readable validation errors, and
43+
* representative cross-surface payloads so schema registry changes fail before
44+
* they reach CLI, Gateway, channel, or dashboard consumers.
45+
*/
46+
47+
/** Builds a validation error fixture while keeping only the field under test noisy. */
3948
const makeError = (overrides: Partial<ValidationError>): ValidationError => ({
4049
keyword: "type",
4150
instancePath: "",
@@ -45,6 +54,7 @@ const makeError = (overrides: Partial<ValidationError>): ValidationError => ({
4554
...overrides,
4655
});
4756

57+
/** Runtime shape shared by all exported lazy protocol validator functions. */
4858
type ProtocolValidator = (value: unknown) => boolean;
4959

5060
describe("lazy protocol validators", () => {

0 commit comments

Comments
 (0)