@aiwg/cockpit 2026.9.9 → 2026.9.11

package/README.md

@@ -619,6 +619,7 @@ The detailed review script and screenshot commands live in
 
 ## See also
 
+- [Desktop identity integration](bridge/DESKTOP-IDENTITY.md) — provider contract and remaining desktop work
 - `apps/cockpit/RELEASE.md` — cockpit release pattern (channels, publish leg, config-defaults gate)
 - `.aiwg/architecture/adr-cockpit-session-control-not-cli-runner.md` — the core model
 - `.aiwg/architecture/cockpit-sad.md` + `cockpit-instance-control-interface.md`

package/bridge/DESKTOP-IDENTITY.md

@@ -0,0 +1,190 @@
+# Desktop identity integration
+
+The Bridge provides an optional identity boundary for desktop access (#2545).
+It requires a trusted provider adapter; the default Cockpit launch does not
+configure one. This component alone does not enable RDP or complete #2545.
+
+## Provider contract
+
+Create `createDesktopIdentity({ verify })` from `src/desktop-identity.mjs` and
+pass the result as `desktopIdentity` to `createBridge`. The module documents
+the complete verifier input and result schema. Every bind, status, and
+authorization request requires a fresh authoritative check of the user session,
+workspace membership, action, and instance policy. Token claims cached at login
+do not satisfy that contract.
+
+The adapter must authenticate login evidence, validate issuer, signature and
+audience, and return a gateway-verifiable scoped delegation. Provider failures
+deny access. There is no operator-token fallback. The issuer, claims mapping,
+membership authority, and login flow still need production integration.
+
+After the trusted login callback authenticates the user, call
+`server.bindDesktopIdentity(req, { workspaceId, evidence })` using the original
+browser request. The Bridge derives the browser binding and audience from its
+HttpOnly session cookie. There is no public endpoint accepting identity claims.
+Browser expiration or logout racing verification prevents binding or disclosure.
+
+## Keycloak provider adapter (section9 realm)
+
+`src/desktop-identity-keycloak.mjs` implements the verifier contract against
+the internal Keycloak realm (`https://auth.s9.internal/realms/section9`,
+matching `itops:config/matric-user-secrets.yaml` and
+`itops:configs/keycloak/realms/section9.json`). It is the production issuer
+decision for #2545; the Bridge itself still receives the adapter as the
+trusted `desktopIdentity` seam.
+
+```js
+import { createDesktopIdentity } from './src/desktop-identity.mjs';
+import { createKeycloakDesktopVerifier } from './src/desktop-identity-keycloak.mjs';
+
+const keycloak = createKeycloakDesktopVerifier({
+  issuer: 'https://auth.s9.internal/realms/section9',   // default
+  audience: 'cockpit-bridge',          // exact `aud` on the login token
+  clientId: 'cockpit-bridge',          // confidential client; introspection + exchange
+  clientSecretFile: process.env.AIWG_COCKPIT_KEYCLOAK_SECRET_FILE, // mode 0600, OpenBao handoff
+  delegationAudience: 'agentic-sandbox-desktop',  // gateway client the delegation is minted for
+});
+const desktopIdentity = createDesktopIdentity({ verify: keycloak.verify });
+```
+
+Per call the adapter: verifies the login evidence signature against the realm
+JWKS (cached five minutes) and pins `iss` and the exact `aud` (bind only, the
+token is retained backend-only afterwards); introspects the retained access
+token with the confidential client so every bind, status and authorization is
+a fresh Keycloak session check (`active`, `sid`, `aud`, `exp`); refreshes a
+lapsed access token once through the refresh grant when the login supplied
+one; maps claims to the binding (`workspace_id` or `tenant_id`; groups
+`admins`/`operators` → all desktop actions, `viewers` → `view`, `observe`;
+`desktop:<action>` realm or client roles add actions; `desktop_instances`
+claim or a `resolveInstances({ subject, workspaceId, claims })` hook supplies
+the instance scope); and mints the delegation by RFC 8693 token exchange for
+`delegationAudience`, cached until it expires. The client secret is read from
+the mode-0600 file at point of use and never logged or returned; unreadable
+secrets and Keycloak errors surface as `identity_unavailable`, mismatches as
+`denied`. `expiresAt` is bounded by `auth_time + sessionMaxMs` (ten hours,
+the realm SSO maximum) so authorization never extends a login.
+
+Still required outside this repository: a `cockpit-bridge` confidential
+client and the gateway client in the section9 realm (itops), token-exchange
+permission between them, an OpenBao path for the client secret, and the
+gateway-side verification of the exchanged token (roctinam/agentic-sandbox#853).
+The embedder must call `keycloak.forget(browserSessionId)` on Bridge logout and
+route Keycloak back-channel logout tokens through
+`keycloak.logoutSelector(token)` into `desktopIdentity.revoke(selector)`.
+`test/integration/cockpit-desktop-identity-keycloak.test.js` exercises the
+adapter against an in-memory Keycloak; it does not qualify the live realm.
+
+## Browser boundary
+
+`GET /api/desktop-identity` requires the browser session and an exact local
+origin. A same-origin GET without Origin is accepted only with
+`Sec-Fetch-Site: same-origin`. Validation uses the actual listener port and
+does not trust forwarded headers. Hosted reverse-proxy access needs a separate
+explicit origin configuration before it can be supported.
+
+Without a provider the endpoint returns `state: unsupported`. With a provider
+it returns freshly checked, redacted identity status. Delegations are never
+returned by this endpoint. Native bearer credentials alone cannot access it.
+
+`DELETE /bootstrap/session` requires the browser cookie, exact Origin, and CSRF
+token. It removes browser authority, invalidates its desktop binding, and expires
+the cookie. Browser session expiration and Bridge shutdown also invalidate
+bindings.
+
+## Transport integration still required
+
+The desktop transport must use `withDelegation` for backend calls, register
+`onInvalidate` to close active streams, and renew authorization within its
+revocation budget. The identity module does not poll the provider itself.
+Provider revocation events must call `revoke` with an issuer-scoped selector.
+The existing terminal transport has not been converted into a desktop transport.
+
+Gateway integration, worker attachment, the desktop panel, production identity
+provider integration, and real browser/Tauri/VS Code qualification remain under
+issues #2545, #2546, and #2547. Unit and local HTTP tests do not prove those workflows.
+
+## Desktop control API
+
+The optional `desktopBackend` Bridge setting accepts the dedicated adapter from
+`src/desktop-backend.mjs`. Configure `createDesktopBackend` with an HTTPS origin
+and `tls: { ca, cert, key }` supplied through backend custody. The client
+certificate authenticates the Bridge workload; each request also carries the
+fresh user delegation. The gateway must verify both identities. This adapter
+does not read the existing operator bearer file. TLS peer and hostname checks
+cannot be disabled through its options, and redirects are never followed.
+
+The local browser control routes use the prefix
+`/api/desktops/instances/{instance}`:
+
+| Method | Route | Required identity action |
+| --- | --- | --- |
+| GET | `/capability` | `view` |
+| POST | `/sessions` | `create` |
+| GET | `/sessions/{desktop}` | `view` |
+| POST | `/sessions/{desktop}/close` | See below |
+
+The close action is `revoke_access` or `sign_out`, from the validated body.
+Create requires a 16–128
+character `Idempotency-Key` containing letters, digits, `_` or `-`. Request
+bodies follow the proposed `rdp-cockpit.v1` contract; unknown request fields
+are rejected. Responses are whitelisted and checked against the requested
+instance and authenticated workspace. Arbitrary upstream error text is not
+returned to the browser.
+
+These routes require the browser cookie, exact local origin and mutation CSRF.
+Authorization is rechecked for each request. Browser logout and identity
+invalidation cancel pending backend calls. Limits are 4 KiB browser bodies,
+eight pending requests per browser, 64 across the Bridge, and ten seconds for
+the browser control operation. The backend defaults to 32 concurrent requests,
+64 KiB responses and a five-second deadline. Backend limits are configurable
+within fixed bounds. This is control-plane traffic, not display frames.
+
+An unconfigured backend reports unsupported. A capability lookup returning
+404 or 501 from an older executor also reports unsupported; terminal routes
+retain their existing behavior. Attach grants are available only through the
+backend adapter, with no browser route that serializes them. The authenticated
+WebSocket worker transport and desktop rendering remain unimplemented.
+
+The local TLS tests use generated test certificates and a real HTTPS server.
+They verify client authentication, server trust, hostname validation, response
+limits, redirects, and the browser-to-Bridge-to-HTTPS request path. Their
+identity provider and desktop responses are test fixtures; they do not qualify
+production identity, the Sandbox broker, or RDP.
+
+## Agent login assistance
+
+The intended workflow is an agent-driven, persistent XFCE session. An authorized
+user opens that same desktop when the agent needs help signing into the user's
+internal application, completes the login in the guest browser, and returns
+control so the agent continues in the authenticated session.
+
+The browser client in `../web/src/desktop-api.ts` provides typed capability,
+existing-session lookup, creation and explicit close operations. It uses the
+normal Cockpit cookie/CSRF bootstrap, caller-owned creation idempotency keys,
+cancellation signals and the same response validator as the Bridge. Unknown
+response fields and arbitrary backend diagnostics do not reach its consumers.
+Looking up an existing desktop performs no creation request.
+
+The assistance action must target the authoritative desktop ID associated with
+the agent task. It must not provision a second guest session. Neither
+`revoke_access` nor `sign_out` means "return control to the agent". That handoff
+needs a separate acknowledged controller transition that preserves the browser
+profile and login. A mission pause alone does not fence agent desktop input.
+
+The assistance request/task binding, fenced agent-to-human transfer,
+return-control operation, authenticated display stream and panel remain to be
+implemented. These client calls do not yet provide a user-connectable desktop.
+
+## Verification
+
+Run the focused suites from the repository root after `npm run build:cli`:
+
+```sh
+npx vitest run --config config/vitest.config.js \
+  test/integration/cockpit-desktop-identity.test.js \
+  test/integration/cockpit-desktop-session.test.js \
+  test/integration/cockpit-bridge.test.js
+```
+
+For an isolated worktree, set `AIWG_CONFIG` to a dedicated temporary directory
+so installation identity checks do not use another checkout's configuration.

package/bridge/src/desktop-backend.mjs

@@ -0,0 +1,102 @@
+import https from 'node:https';
+import { createSecureContext } from 'node:tls';
+import { isDesktopUuid, sanitizeDesktopProblem, sanitizeDesktopResponse, validateDesktopRequest } from './desktop-contract.mjs';
+
+const fail = (code, status = 502) => Object.assign(new Error(code), { code, status });
+const operations = {
+  capability: { method: 'GET', path: (id) => `/api/v2/instances/${id}/desktop-capability`, response: 'Capability', status: 200 },
+  create: { method: 'POST', path: (id) => `/api/v2/instances/${id}/desktop-sessions`, request: 'CreateDesktop', response: 'Desktop', status: 202 },
+  get: { method: 'GET', path: (id) => `/api/v2/desktop-sessions/${id}`, response: 'Desktop', status: 200 },
+  attach: { method: 'POST', path: (id) => `/api/v2/desktop-sessions/${id}/attachments`, request: 'AttachmentRequest', response: 'BackendAttachmentGrant', status: 201 },
+  detach: { method: 'DELETE', path: (id) => `/api/v2/desktop-attachments/${id}`, status: 204 },
+  close: { method: 'POST', path: (id) => `/api/v2/desktop-sessions/${id}/close`, request: 'CloseRequest', response: 'Desktop', status: 202 },
+};
+
+/** Dedicated desktop control connection. The client certificate authenticates
+ * the Bridge workload; Authorization carries the freshly verified user delegation.
+ * The gateway must verify BOTH. No operator credential file or generic proxy is
+ * consulted. The attachment grant returned by `attach` is backend-only.
+ */
+export function createDesktopBackend({ url, tls, timeoutMs = 5000, maxConcurrent = 32, maxResponseBytes = 65536 } = {}) {
+  let endpoint;
+  try { endpoint = new URL(url); } catch { throw new TypeError('Desktop HTTPS endpoint required'); }
+  if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password || endpoint.search || endpoint.hash || endpoint.pathname !== '/') {
+    throw new TypeError('Desktop endpoint must be an HTTPS origin');
+  }
+  if (!tls?.ca || !tls?.cert || !tls?.key) throw new TypeError('Desktop workload certificate, key and server CA required');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000 ||
+      !Number.isInteger(maxConcurrent) || maxConcurrent < 1 || maxConcurrent > 128 ||
+      !Number.isInteger(maxResponseBytes) || maxResponseBytes < 1024 || maxResponseBytes > 1048576) throw new TypeError('Invalid desktop transport limits');
+  // Whitelist TLS options: callers cannot disable peer or hostname verification.
+  let secureContext;
+  try { secureContext = createSecureContext({ ca: tls.ca, cert: tls.cert, key: tls.key, minVersion: 'TLSv1.2' }); }
+  catch { throw new TypeError('Invalid desktop TLS configuration'); }
+  const agent = new https.Agent({ keepAlive: true, maxSockets: maxConcurrent, secureContext, rejectUnauthorized: true });
+  const active = new Set();
+  let closed = false;
+
+  async function request({ operation, id, delegation, body, idempotencyKey, signal } = {}) {
+    const spec = Object.hasOwn(operations, operation) ? operations[operation] : undefined;
+    if (!spec || !isDesktopUuid(id) || typeof delegation !== 'string' || !/^[\x21-\x7e]{1,16384}$/.test(delegation)) throw fail('desktop_invalid_request', 400);
+    if (closed || signal?.aborted) throw fail('desktop_backend_unavailable', 503);
+    if (active.size >= maxConcurrent) throw fail('quota_exceeded', 429);
+    let payload;
+    if (spec.request) payload = JSON.stringify(validateDesktopRequest(spec.request, body));
+    else if (body !== undefined) throw fail('desktop_invalid_request', 400);
+    if (operation === 'create' && (typeof idempotencyKey !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(idempotencyKey))) throw fail('desktop_invalid_request', 400);
+    const headers = { authorization: `Bearer ${delegation}`, accept: 'application/json, application/problem+json' };
+    if (payload) Object.assign(headers, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+    if (operation === 'create') headers['idempotency-key'] = idempotencyKey;
+    const result = await new Promise((resolve, reject) => {
+      let settled = false;
+      let timer;
+      const abort = () => finish(fail('desktop_backend_unavailable', 503));
+      const finish = (error, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        active.delete(req);
+        if (error) { req.destroy(); reject(error); }
+        else resolve(value);
+      };
+      const req = https.request(new URL(spec.path(id), endpoint), { method: spec.method, agent, headers }, (res) => {
+        const chunks = [];
+        let size = 0;
+        res.on('data', (chunk) => {
+          size += chunk.length;
+          if (size > maxResponseBytes) finish(fail('desktop_invalid_response'));
+          else chunks.push(chunk);
+        });
+        res.on('aborted', () => finish(fail('desktop_backend_unavailable', 503)));
+        res.on('error', () => finish(fail('desktop_backend_unavailable', 503)));
+        res.on('end', () => finish(null, { status: res.statusCode, contentType: res.headers['content-type'], body: Buffer.concat(chunks).toString('utf8') }));
+      });
+      active.add(req);
+      req.on('error', (err) => finish(fail(/CERT|TLS|SELF_SIGNED|ISSUER|VERIFY/.test(err.code ?? '') ? 'upstream_certificate_invalid' : 'desktop_backend_unavailable', 503)));
+      timer = setTimeout(() => finish(fail('desktop_backend_timeout', 504)), timeoutMs);
+      signal?.addEventListener('abort', abort, { once: true });
+      if (signal?.aborted) abort();
+      else req.end(payload);
+    });
+    if (operation === 'capability' && [404, 501].includes(result.status)) return Object.freeze({ state: 'unsupported', reason: 'desktop_not_supported' });
+    if (result.status === 204 && !spec.response && !result.body) return undefined;
+    if (!/^application\/(?:json|problem\+json)(?:\s*;|$)/i.test(result.contentType ?? '')) throw fail('desktop_invalid_response');
+    let value;
+    try { value = JSON.parse(result.body); } catch { throw fail('desktop_invalid_response'); }
+    if (result.status >= 400) {
+      const problem = sanitizeDesktopProblem(value);
+      throw fail(problem.code, problem.status);
+    }
+    if (result.status !== spec.status) throw fail('desktop_invalid_response');
+    const clean = sanitizeDesktopResponse(spec.response, value);
+    const returnedId = ['capability', 'create'].includes(operation) ? clean.instance_id : operation === 'attach' ? clean.desktop_id : clean.id;
+    if (returnedId?.toLowerCase() !== id.toLowerCase()) throw fail('desktop_invalid_response');
+    return clean;
+  }
+  return Object.freeze({ request, close() {
+    closed = true;
+    for (const req of active) req.destroy(fail('desktop_backend_unavailable', 503));
+    agent.destroy();
+  } });
+}

package/bridge/src/desktop-contract.d.mts

@@ -0,0 +1,46 @@
+export type DesktopMode = 'control' | 'observe';
+export interface DesktopViewport { width: number; height: number; dpi: number }
+export interface CreateDesktopRequest { requested_mode: DesktopMode; viewport: DesktopViewport }
+export interface DesktopAttachmentRequest { mode: DesktopMode; viewport: DesktopViewport }
+export interface DesktopCloseRequest { action: 'revoke_access' | 'sign_out' }
+export interface DesktopPolicy {
+  observe: boolean;
+  control: boolean;
+  sharing: boolean;
+  clipboard_copy: boolean;
+  clipboard_paste: boolean;
+  file_transfer: boolean;
+  audio: boolean;
+  recording: boolean;
+  isolation_tier: 'cooperative' | 'separate_desktop_vm';
+  generation: number;
+}
+interface DesktopResource {
+  schema_version: 'rdp-cockpit.v1';
+  instance_id: string;
+  incarnation: string;
+  policy: DesktopPolicy;
+}
+export interface DesktopCapability extends DesktopResource {
+  supported: boolean;
+  readiness: 'ready' | 'not_ready' | 'unknown';
+  reason_codes: string[];
+}
+export interface DesktopSession extends DesktopResource {
+  id: string;
+  workspace_id: string;
+  state: 'preparing' | 'ready' | 'attached' | 'detached' | 'closing' | 'closed' | 'failed';
+  cleanup: 'none' | 'pending' | 'complete' | 'failed';
+  absolute_expires_at: string;
+  retained_until: string | null;
+}
+export function isDesktopUuid(value: unknown): value is string;
+export function validateDesktopRequest(kind: 'CreateDesktop', value: unknown): CreateDesktopRequest;
+export function validateDesktopRequest(kind: 'AttachmentRequest', value: unknown): DesktopAttachmentRequest;
+export function validateDesktopRequest(kind: 'CloseRequest', value: unknown): DesktopCloseRequest;
+export function sanitizeDesktopResponse(kind: 'Capability', value: unknown): DesktopCapability;
+export function sanitizeDesktopResponse(kind: 'Desktop', value: unknown): DesktopSession;
+export function sanitizeDesktopResponse(kind: 'BackendAttachmentGrant', value: unknown): {
+  attachment_id: string; desktop_id: string; grant: string; expires_at: string; policy_generation: number;
+};
+export function sanitizeDesktopProblem(value: unknown): { code: string; status: number; message: string };

package/bridge/src/desktop-contract.mjs

@@ -0,0 +1,95 @@
+// Boundary validation for the proposed rdp-cockpit.v1 contract. This module does
+// not imply that the executor implements that API or that runtime UAT has passed.
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && [Object.prototype, null].includes(Object.getPrototypeOf(v));
+const fail = (request = false) => { throw Object.assign(new Error(request ? 'Invalid desktop request' : 'Invalid desktop response'), { code: request ? 'desktop_invalid_request' : 'desktop_invalid_response' }); };
+const integer = (v, min, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(v) && v >= min && v <= max;
+const identifier = (v) => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(v);
+export const isDesktopUuid = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);
+const fields = (value, keys, request = false) => {
+  if (!record(value) || keys.some((key) => !own(value, key)) || (request && Reflect.ownKeys(value).some((key) => !keys.includes(key)))) fail(request);
+};
+const member = (v, values, request = false) => { if (!values.includes(v)) fail(request); return v; };
+const mode = (v, request) => member(v, ['control', 'observe'], request);
+function viewport(value) {
+  fields(value, ['width', 'height', 'dpi'], true);
+  if (!integer(value.width, 640, 3840) || !integer(value.height, 480, 2160) || !integer(value.dpi, 72, 240)) fail(true);
+  return { width: value.width, height: value.height, dpi: value.dpi };
+}
+export function validateDesktopRequest(kind, value) {
+  if (kind === 'CloseRequest') {
+    fields(value, ['action'], true);
+    return { action: member(value.action, ['revoke_access', 'sign_out'], true) };
+  }
+  if (!['CreateDesktop', 'AttachmentRequest'].includes(kind)) fail(true);
+  const key = kind === 'CreateDesktop' ? 'requested_mode' : 'mode';
+  fields(value, ['viewport', key], true);
+  return { [key]: mode(value[key], true), viewport: viewport(value.viewport) };
+}
+const booleans = ['observe', 'control', 'sharing', 'clipboard_copy', 'clipboard_paste', 'file_transfer', 'audio', 'recording'];
+function policy(value) {
+  fields(value, [...booleans, 'isolation_tier', 'generation']);
+  if (booleans.some((key) => typeof value[key] !== 'boolean') || !integer(value.generation, 1)) fail();
+  return { ...Object.fromEntries(booleans.map((key) => [key, value[key]])), isolation_tier: member(value.isolation_tier, ['cooperative', 'separate_desktop_vm']), generation: value.generation };
+}
+function timestamp(value) {
+  if (typeof value !== 'string' || value.length > 40) fail();
+  const match = value.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|([+-])(\d{2}):(\d{2}))$/);
+  if (!match) fail();
+  const [, y, m, d, h, minute, second, , oh, om] = match;
+  const year = Number(y), month = Number(m), day = Number(d);
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (month < 1 || month > 12 || day < 1 || day > days[month - 1] || Number(h) > 23 || Number(minute) > 59 || Number(second) > 59 || Number(oh ?? 0) > 23 || Number(om ?? 0) > 59 || !Number.isFinite(Date.parse(value))) fail();
+  return value;
+}
+const PROBLEMS = Object.freeze({
+  desktop_not_supported: [501, 'Desktop access is not supported.'],
+  desktop_not_ready: [409, 'The desktop is not ready.'],
+  access_denied: [403, 'Desktop access denied.'],
+  control_conflict: [409, 'Another controller owns the desktop.'],
+  grant_expired: [410, 'Desktop admission expired. Reconnect to request new admission.'],
+  stale_instance: [409, 'The instance changed. Refresh before reconnecting.'],
+  route_unavailable: [503, 'The desktop route is unavailable.'],
+  credentials_unavailable: [503, 'Desktop credentials are unavailable.'],
+  upstream_certificate_invalid: [502, 'The desktop certificate could not be verified.'],
+  quota_exceeded: [429, 'The desktop capacity limit was reached.'],
+  desktop_session_ended: [410, 'The guest desktop session ended.'],
+  cleanup_pending: [409, 'Desktop cleanup is pending.'],
+  idempotency_conflict: [409, 'The request identifier was already used for a different request.'],
+});
+export function sanitizeDesktopProblem(value) {
+  if (!record(value) || typeof value.code !== 'string' || !own(PROBLEMS, value.code)) fail();
+  const [status, message] = PROBLEMS[value.code];
+  return { code: value.code, status, message };
+}
+function reasons(value) {
+  if (!Array.isArray(value) || value.length > 32 || value.some((code) => typeof code !== 'string' || !/^[a-z][a-z0-9_]{0,63}$/.test(code))) fail();
+  // The draft leaves reason strings open. Never reflect unknown diagnostics;
+  // callers get a stable unknown reason until that code is explicitly reviewed.
+  return [...new Set(value.map((code) => own(PROBLEMS, code) || ['unknown', 'not_ready', 'unsupported'].includes(code) ? code : 'unknown'))];
+}
+/** Returns whitelisted protocol fields. BackendAttachmentGrant intentionally
+ * retains its opaque grant for BACKEND CONSUMPTION ONLY. Never serialize that
+ * result to a browser, URL, log, or persistent store. */
+export function sanitizeDesktopResponse(kind, value) {
+  if (kind === 'BackendAttachmentGrant') {
+    fields(value, ['attachment_id', 'desktop_id', 'grant', 'expires_at', 'policy_generation']);
+    if (!isDesktopUuid(value.attachment_id) || !isDesktopUuid(value.desktop_id) || !integer(value.policy_generation, 1) || typeof value.grant !== 'string' || !/^[A-Za-z0-9._~+/-]{32,4096}={0,2}$/.test(value.grant) || value.grant.length > 4096) fail();
+    return { attachment_id: value.attachment_id, desktop_id: value.desktop_id, grant: value.grant, expires_at: timestamp(value.expires_at), policy_generation: value.policy_generation };
+  }
+  if (!['Capability', 'Desktop'].includes(kind)) fail();
+  const shared = ['schema_version', 'instance_id', 'incarnation', 'policy'];
+  fields(value, [...shared, ...(kind === 'Capability' ? ['supported', 'readiness', 'reason_codes'] : ['id', 'workspace_id', 'state', 'cleanup', 'absolute_expires_at', 'retained_until'])]);
+  if (value.schema_version !== 'rdp-cockpit.v1' || !isDesktopUuid(value.instance_id) || !identifier(value.incarnation)) fail();
+  const common = { schema_version: value.schema_version, instance_id: value.instance_id, incarnation: value.incarnation, policy: policy(value.policy) };
+  if (kind === 'Capability') {
+    if (typeof value.supported !== 'boolean') fail();
+    return { ...common, supported: value.supported, readiness: member(value.readiness, ['ready', 'not_ready', 'unknown']), reason_codes: reasons(value.reason_codes) };
+  }
+  if (!isDesktopUuid(value.id) || !identifier(value.workspace_id)) fail();
+  return { ...common, id: value.id, workspace_id: value.workspace_id,
+    state: member(value.state, ['preparing', 'ready', 'attached', 'detached', 'closing', 'closed', 'failed']),
+    cleanup: member(value.cleanup, ['none', 'pending', 'complete', 'failed']),
+    absolute_expires_at: timestamp(value.absolute_expires_at), retained_until: value.retained_until === null ? null : timestamp(value.retained_until) };
+}

package/bridge/src/desktop-http.mjs

@@ -0,0 +1,105 @@
+import { isDesktopUuid, sanitizeDesktopResponse, validateDesktopRequest } from './desktop-contract.mjs';
+
+const failure = (code, status = 400) => Object.assign(new Error(code), { code, status });
+const errors = new Set(['desktop_invalid_request', 'desktop_invalid_response', 'desktop_backend_unavailable', 'desktop_backend_timeout',
+  'desktop_not_supported', 'desktop_not_ready', 'access_denied', 'control_conflict', 'grant_expired', 'stale_instance',
+  'route_unavailable', 'credentials_unavailable', 'upstream_certificate_invalid', 'quota_exceeded', 'desktop_session_ended', 'cleanup_pending', 'idempotency_conflict']);
+
+async function readBody(req, signal) {
+  if (!/^application\/json(?:\s*;|$)/i.test(req.headers['content-type'] ?? '')) throw failure('desktop_invalid_request');
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    const clean = () => { req.removeListener('data', data); req.removeListener('end', end); req.removeListener('error', abort); signal.removeEventListener('abort', abort); };
+    const abort = () => { clean(); reject(failure('desktop_invalid_request')); };
+    const data = (chunk) => {
+      size += chunk.length;
+      if (size > 4096) abort();
+      else chunks.push(chunk);
+    };
+    const end = () => {
+      clean();
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+      catch { reject(failure('desktop_invalid_request')); }
+    };
+    req.on('data', data); req.on('end', end); req.on('error', abort);
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) abort();
+  });
+}
+
+/** Browser control API only. Attachment grants and display upgrades have a
+ * separate backend-only lifecycle; this handler never exposes the attach call. */
+export function createDesktopHttpHandler({ identity, backend, getAuth, validOrigin, validCsrf, json: writeJson }) {
+  const pending = new Map();
+  const unsubscribe = identity?.onInvalidate(({ browserSessionId }) => {
+    for (const controller of pending.get(browserSessionId) ?? []) controller.abort();
+  });
+  async function handle(req, res, url) {
+    if (url.pathname !== '/api/desktops' && !url.pathname.startsWith('/api/desktops/')) return false;
+    const json = (response, status, value) => {
+      if (status >= 400 && !req.complete) {
+        response.setHeader('connection', 'close');
+        response.once('finish', () => req.socket.destroySoon());
+      }
+      return writeJson(response, status, value);
+    };
+    res.setHeader('cache-control', 'no-store');
+    const auth = getAuth(req);
+    if (!auth) { json(res, 401, { error: 'unauthorized' }); return true; }
+    if (!validOrigin(req, { allowSameOriginFetch: true })) { json(res, 403, { error: 'forbidden_origin' }); return true; }
+    if (!validCsrf(req, auth)) { json(res, 403, { error: 'csrf_required' }); return true; }
+    if (['GET', 'HEAD'].includes(req.method) && (req.headers['transfer-encoding'] || Number(req.headers['content-length']) > 0)) {
+      json(res, 400, { error: 'desktop_invalid_request' }); return true;
+    }
+    const match = url.pathname.match(/^\/api\/desktops\/instances\/([^/]+)\/(capability|sessions)(?:\/([^/]+)(?:\/(close))?)?$/);
+    if (!match || url.search || !isDesktopUuid(match[1]) || (match[3] && !isDesktopUuid(match[3]))) { json(res, 404, { error: 'not_found' }); return true; }
+    const [, instanceId, resource, desktopId, suffix] = match;
+    const operation = resource === 'capability' && !desktopId && req.method === 'GET' ? 'capability'
+      : resource === 'sessions' && !desktopId && req.method === 'POST' ? 'create'
+        : resource === 'sessions' && desktopId && !suffix && req.method === 'GET' ? 'get'
+          : resource === 'sessions' && desktopId && suffix === 'close' && req.method === 'POST' ? 'close' : null;
+    if (!operation) { json(res, 405, { error: 'method_not_allowed' }); return true; }
+    if (!identity || !backend) { json(res, operation === 'capability' ? 200 : 503, { state: 'unsupported', reason: 'desktop_backend_not_configured' }); return true; }
+    const controller = new AbortController();
+    const requests = pending.get(auth.sessionId) ?? new Set();
+    if (requests.size >= 8 || [...pending.values()].reduce((count, items) => count + items.size, 0) >= 64) {
+      json(res, 429, { error: 'quota_exceeded' }); return true;
+    }
+    requests.add(controller); pending.set(auth.sessionId, requests);
+    const abort = () => controller.abort();
+    req.once('aborted', abort);
+    res.once('close', abort);
+    const timer = setTimeout(abort, 10000);
+    try {
+      const body = ['create', 'close'].includes(operation) ? await readBody(req, controller.signal) : undefined;
+      if (['create', 'close'].includes(operation)) validateDesktopRequest(operation === 'create' ? 'CreateDesktop' : 'CloseRequest', body);
+      const action = operation === 'close' ? (body?.action === 'sign_out' ? 'sign_out' : 'revoke_access') : operation === 'create' ? 'create' : 'view';
+      const result = await identity.withDelegation(auth.sessionId, { action, instanceId }, async ({ delegation, identity: verified }) => {
+        const value = await backend.request({ operation, id: desktopId ?? instanceId, body,
+          idempotencyKey: req.headers['idempotency-key'], delegation, signal: controller.signal });
+        if (controller.signal.aborted || getAuth(req)?.sessionId !== auth.sessionId) throw failure('access_denied', 403);
+        if (value?.state === 'unsupported' && operation === 'capability') return { state: 'unsupported', reason: 'desktop_not_supported' };
+        if (value?.instance_id?.toLowerCase() !== instanceId.toLowerCase() ||
+            (desktopId && value?.id?.toLowerCase() !== desktopId.toLowerCase()) ||
+            (operation !== 'capability' && value?.workspace_id !== verified.workspaceId)) throw failure('desktop_invalid_response', 502);
+        return sanitizeDesktopResponse(operation === 'capability' ? 'Capability' : 'Desktop', value);
+      });
+      json(res, operation === 'create' || operation === 'close' ? 202 : 200, result);
+    } catch (error) {
+      const code = error?.code === 'denied' ? 'access_denied' : error?.code === 'identity_unavailable' ? 'desktop_backend_unavailable' : errors.has(error?.code) ? error.code : 'desktop_backend_unavailable';
+      const status = Number.isInteger(error?.status) && error.status >= 400 && error.status < 600 ? error.status : code === 'desktop_invalid_request' ? 400 : 502;
+      if (!res.destroyed) json(res, status, { error: code });
+    } finally {
+      clearTimeout(timer); req.removeListener('aborted', abort); res.removeListener('close', abort);
+      requests.delete(controller);
+      if (!requests.size) pending.delete(auth.sessionId);
+    }
+    return true;
+  }
+  return { handle, close() {
+    unsubscribe?.();
+    for (const requests of pending.values()) for (const controller of requests) controller.abort();
+    pending.clear();
+  } };
+}