@corenel/harness 0.12.0 → 0.13.0

package/dist/sidecar/server.js

@@ -1,9 +1,11 @@
-import { DEFAULT_STATE_DIR, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, denialNote } from '@corenel/protocol';
-import { SIDECAR_PROTOCOL, errMessage, isLoopbackHost, isLoopbackAddress, parseMcpToolAddress, isWebPushSubscription, MAX_ASSERTION_LEN, } from '@corenel/protocol';
-import { pairingTokenHash } from './identity.js';
+import { DEFAULT_STATE_DIR, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, DEVICES_FEATURE, denialNote } from '@corenel/protocol';
+import { SIDECAR_PROTOCOL, errMessage, isLoopbackHost, isLoopbackAddress, parseMcpToolAddress, isWebPushSubscription, MAX_ASSERTION_LEN, isClerkOrgId, } from '@corenel/protocol';
+import { asEcPublicJwk, jwkThumbprint, verifySignature, randomToken, serverProofPayload, clientProofPayload, bytesToB64url, codeProof, sameB64, B64URL_32, } from './deviceKeys.js';
 const NO_CHECKS = 'this sidecar does not run checks (start it with --allow-shell)';
-/** Default pre-pairing deadline: a real client sends `hello` immediately. */
-export const HELLO_DEADLINE_MS = 10000;
+/** Default pre-pairing deadline: a real client sends `hello` immediately.
+ * It covers the proof exchange AND the identity exchange (IDENTITY_TIMEOUT_MS),
+ * which now happens before a connection counts as authenticated. */
+export const HELLO_DEADLINE_MS = 20000;
 /** Denied hellos one connection may send before it is closed: a client with a
  *  stale token needs one, not an unbounded guessing loop. */
 export const MAX_FAILED_HELLOS = 3;
@@ -12,12 +14,16 @@ export const MAX_FAILED_HELLOS = 3;
  * a client left with no handshake at all is worse than one that has to fall back
  * to deducing its own directory. */
 const DIR_NAME_TIMEOUT_MS = 3000;
-/** How long pairing waits on the identity verifier before going out
- * UNVERIFIED. The same bound as `DIR_NAME_TIMEOUT_MS`, and run concurrently
- * with it, so a verifier that hangs never makes the handshake slower than a
- * wedged dirName lookup already could. A timeout never refuses the connection:
- * it only withholds the widened trust a verified id would earn. */
-export const IDENTITY_TIMEOUT_MS = 3000;
+/** How long pairing waits for the identity exchange (the client fetching an
+ * assertion from corenel-api, then the verify), from the challenge. Identity
+ * is required, so a timeout REFUSES the hello. Long enough for a browser's own
+ * bounds (a Clerk token, then the assertion request, which may include a
+ * membership lookup at Clerk). */
+export const IDENTITY_TIMEOUT_MS = 10000;
+/** How long an open connection has to answer a periodic re-check
+ * (`SidecarAdmission.recheckMs`) before it is closed. Generous: the client is
+ * mid-session, and a slow answer is not a refusal. */
+export const RECHECK_TIMEOUT_MS = 30000;
 /** True for anything with a callable `.then` -- covers native Promises and any
  * other thenable a caller's `onClient` might return, without assuming it's a
  * real Promise instance (the declared type is `() => void`; an async function
@@ -51,6 +57,13 @@ function announcedCapabilities(v) {
     const list = v;
     return list.every((c) => typeof c === 'string' && c.length <= MAX_CAPABILITY_LEN) ? list : [];
 }
+/** Whether a hello announced that its client persists an issued device
+ * credential (`DEVICES_FEATURE` in `capabilities`). Informational like every
+ * capability: it grants nothing, it only decides whether issuing one is worth
+ * anything. */
+function keepsDevices(m) {
+    return announcedCapabilities(m.capabilities).includes(DEVICES_FEATURE);
+}
 /** Base64-encode bytes without a Node Buffer (btoa is in the browser + Node 18+),
  * so this module stays free of node:* types for the shared harness build. */
 function bytesToB64(bytes) {
@@ -69,17 +82,18 @@ function makeNonce() {
     crypto.getRandomValues(bytes);
     return bytesToB64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-/** Constant-time string compare for the pairing token — avoids leaking it via the
- * early-exit timing of `!==`. Pure JS so this stays host-agnostic (no node:crypto in
- * a possibly-bundled module). The token is a fixed-length hex string, so comparing
- * lengths first reveals nothing secret. */
-function safeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let diff = 0;
-    for (let i = 0; i < a.length; i++)
-        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    return diff === 0;
+/** Bound on a device id, checked before any store lookup. A real one is ~20
+ * characters. */
+const MAX_DEVICE_ID_LEN = 64;
+/** How long the daemon waits for `client-proof` after its `server-proof`.
+ * The hello deadline closes an unauthenticated socket anyway; this bounds the
+ * wait inside it. */
+export const PROOF_TIMEOUT_MS = 10000;
+/** A fresh device id: random, not secret. */
+function makeDeviceId() {
+    const b = new Uint8Array(12);
+    crypto.getRandomValues(b);
+    return `dev_${bytesToB64url(b)}`;
 }
 /** Longest verdict reason the harness will put on a welcome or in a log. */
 const MAX_REASON_LEN = 80;
@@ -103,8 +117,17 @@ function normalizeVerdict(got) {
         if (r.ok === true) {
             const userId = r.identity?.userId;
             const issuer = r.identity?.issuer;
+            const orgId = r.identity?.orgId;
             if (typeof userId === 'string' && userId && userId.length <= MAX_IDENTITY_FIELD_LEN) {
-                return { ok: true, identity: { userId, issuer: typeof issuer === 'string' ? issuer : '' } };
+                return {
+                    ok: true,
+                    identity: {
+                        userId, issuer: typeof issuer === 'string' ? issuer : '',
+                        // Carried only in a usable shape; a malformed org is no org, which
+                        // the team policy then refuses.
+                        ...(isClerkOrgId(orgId) ? { orgId } : {}),
+                    },
+                };
             }
             return { ok: false, reason: 'malformed verdict' };
         }
@@ -147,6 +170,67 @@ export class SidecarServer {
             writable: true,
             value: 0
         });
+        /** A hello's credential is being checked (the check awaits the device
+         * store). A second hello in that window is ignored, exactly as one after
+         * `authed` is. */
+        Object.defineProperty(this, "helloInFlight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /** The device this connection authenticated as (or was just issued), when
+         * the daemon keeps a device store. Stamps `self` in `devices-list`, and is
+         * what a revocation closes. */
+        Object.defineProperty(this, "deviceId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The device id to hand over on the welcome, set only by an enrollment,
+         * cleared the moment the welcome is sent. */
+        Object.defineProperty(this, "issuedDevice", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Resolves the pending `client-proof` wait (single use). */
+        Object.defineProperty(this, "clientProofResolve", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Unsubscribe from the device store's revocations. */
+        Object.defineProperty(this, "revocationOff", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The thumbprint of the device key this connection proved: what every
+         * identity assertion on it, at pairing and at each re-check, must bind. */
+        Object.defineProperty(this, "deviceJkt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The periodic identity re-check (team mode), cleared on close. */
+        Object.defineProperty(this, "recheckTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "recheckInFlight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         Object.defineProperty(this, "clearHelloDeadline", {
             enumerable: true,
             configurable: true,
@@ -205,7 +289,7 @@ export class SidecarServer {
             value: []
         });
         /** The VERIFIED user id (the identity token's `sub`), set at most once, in
-         * `onHello`, after the pairing token passed and the verifier answered. It is
+         * `onHello`, after the device key was proven and the verifier answered. It is
          * never re-assigned: no message re-authenticates, so a hijacked socket cannot
          * swap whose connection this is. Undefined = unverified, which is every
          * connection on a daemon with no `identity` verifier. The token itself is
@@ -446,6 +530,12 @@ export class SidecarServer {
         this.ch.onClose?.(() => {
             this.closed = true;
             this.clearHelloDeadline();
+            this.unwatchRevocation();
+            if (this.recheckTimer !== undefined)
+                clearInterval(this.recheckTimer);
+            this.recheckTimer = undefined;
+            this.clientProofResolve?.(null);
+            this.clientProofResolve = undefined;
             // A connection that drops while `onHello` is awaiting `identity-assert`
             // must not leave that promise pending until the unrelated 3s timer
             // fires -- settle it now, exactly like a timeout, so onHello observes
@@ -485,13 +575,23 @@ export class SidecarServer {
                  * connection. `authed` is set SYNCHRONOUSLY inside onHello, before its
                  * first await, so this also refuses a second hello that arrives while
                  * the first is still waiting on the identity verifier. */
-                if (this.authed)
+                if (this.authed || this.helloInFlight)
                     return;
                 /* onHello is async now, so a throw after its awaits (attendance.attach,
                  * sendWelcome, hosts.attach) would be an UNHANDLED rejection -- which
                  * takes the whole daemon down, not just this connection. Log it. */
                 void this.onHello(m).catch((err) => this.opts.log?.(`hello failed: ${errMessage(err)}`));
                 return;
+            case 'client-proof': {
+                // Only the proof the daemon is waiting for counts; the resolver is
+                // cleared on first use, so a second (or unsolicited) one is ignored.
+                const resolve = this.clientProofResolve;
+                this.clientProofResolve = undefined;
+                resolve?.(typeof m.sig === 'string'
+                    ? { sig: m.sig, ...(typeof m.codeProof === 'string' ? { codeProof: m.codeProof } : {}) }
+                    : null);
+                return;
+            }
             case 'identity-assert': {
                 // Only the FIRST identity-assert on a connection counts -- the
                 // resolver is cleared the instant it is used (right here), so a
@@ -590,7 +690,7 @@ export class SidecarServer {
                 return;
             case 'roots-browse':
                 // Auth-gated like every other request: directory enumeration must never
-                // precede the pairing token. Failures answer ok:false rather than throwing
+                // precede authentication. Failures answer ok:false rather than throwing
                 // across the channel.
                 if (!this.authed) {
                     this.ch.send({ t: 'roots-browse-result', id: m.id, ok: false, error: 'not authenticated' });
@@ -699,6 +799,7 @@ export class SidecarServer {
             case 'config-list':
             case 'config-read':
             case 'config-write':
+            case 'config-append':
             case 'config-delete':
                 // AUTHENTICATION FIRST, and a refusal rather than an empty answer: an
                 // unauthenticated caller must not learn whether a definition exists.
@@ -801,6 +902,20 @@ export class SidecarServer {
             case 'push-unsubscribe':
                 void this.onPushUnsubscribe(m);
                 return;
+            case 'devices-list':
+                if (!this.authed) {
+                    this.ch.send({ t: 'devices-list-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onDevicesList(m);
+                return;
+            case 'devices-revoke':
+                if (!this.authed) {
+                    this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: false, error: 'not authenticated' });
+                    return;
+                }
+                void this.onDevicesRevoke(m);
+                return;
             case 'hosts-list':
                 // `ok: false`, not an empty estate: telling an unauthenticated caller
                 // "this daemon holds no synced hosts" is a claim it has not earned --
@@ -934,21 +1049,375 @@ export class SidecarServer {
             this.ch.close();
         }
     }
+    /** Refuse a hello's credential. ONE reason for every credential failure --
+     * a wrong or unknown device, a revoked one, an expired, used or unknown
+     * code, a hello with no device or code at all, a store that could not be
+     * read -- so a denial is never an oracle for which it was. The log line
+     * says which path failed (the operator's terminal, not the wire). Every
+     * one counts toward MAX_FAILED_HELLOS. */
+    denyCredential(path) {
+        this.opts.log?.(`denied: invalid credentials (${path})`);
+        this.ch.send({ t: 'denied', reason: 'invalid credentials' });
+        this.noteOutcome('denied');
+        this.countFailedHello();
+    }
+    /** Tell the daemon's rate limiter how a hello ended. Its failure is never
+     * the handshake's. */
+    noteOutcome(outcome) {
+        try {
+            this.opts.onHelloOutcome?.(outcome);
+        }
+        catch (err) {
+            this.opts.log?.(`onHelloOutcome threw: ${errMessage(err)}`);
+        }
+    }
+    /** Whether the daemon's policy admits this VERIFIED identity. A policy that
+     * throws admits nobody. No policy (the harness's own tests) admits any
+     * verified identity. */
+    admits(identity) {
+        const a = this.opts.admission;
+        if (!a)
+            return true;
+        try {
+            return a.admits(identity) === true;
+        }
+        catch (err) {
+            this.opts.log?.(`admission policy threw, refusing: ${errMessage(err)}`);
+            return false;
+        }
+    }
+    /** THE IDENTITY GATE (spec 2026-09-29-device-enrollment-design, Phase 2),
+     * run inside the credential check once the device key is proven -- for an
+     * enrollment, BEFORE the code is burned -- so a code alone never enrolls an
+     * unverified or unadmitted identity. With no verifier wired it passes (the
+     * harness's own tests); the node daemon always wires one, which makes a
+     * verified, admitted identity REQUIRED. The challenge names the org the
+     * policy wants asserted (team mode), so the client asks the issuer for it.
+     * On success `verifiedUserId` is set, here and nowhere else. Every failure
+     * is logged with its reason on the operator's terminal and left to the
+     * caller's uniform denial on the wire. */
+    async identityGate(jkt, boundUser) {
+        if (!this.opts.identity)
+            return true;
+        const sidecarId = this.opts.info?.id;
+        if (!sidecarId) {
+            this.opts.log?.('identity: refused (this daemon has no id for an assertion to name)');
+            return false;
+        }
+        const nonce = makeNonce();
+        const orgId = this.opts.admission?.orgId;
+        this.ch.send({ t: 'identity-challenge', nonce, sidecarId, ...(orgId ? { orgId } : {}) });
+        const verdict = await this.awaitAndVerifyIdentity(sidecarId, nonce, jkt, IDENTITY_TIMEOUT_MS);
+        if (!verdict.ok) {
+            this.opts.log?.(`identity: unverified (${verdict.reason})`);
+            return false;
+        }
+        if (!this.admits(verdict.identity)) {
+            this.opts.log?.(orgId ? `identity: verified, but not a member of ${orgId}` : 'identity: verified, but not the account this daemon belongs to');
+            return false;
+        }
+        /* TEAM: ONE USER PER DEVICE. A device belongs to the first verified user
+         * it connected as; another member signed in on the same browser does not
+         * inherit it (its revocations and run ownership follow the recorded
+         * user). A device recorded with no user yet is taken by this one. */
+        if (this.opts.admission?.oneUserPerDevice && boundUser !== undefined && boundUser !== verdict.identity.userId) {
+            this.opts.log?.('identity: verified, but this device belongs to another user');
+            return false;
+        }
+        this.verifiedUserId = verdict.identity.userId;
+        this.identityResult = { verified: true };
+        this.opts.log?.('identity: verified');
+        return true;
+    }
+    /** Start the periodic re-check of an authenticated connection's identity
+     * (`SidecarAdmission.recheckMs`, team mode). */
+    startRecheck() {
+        const every = this.opts.admission?.recheckMs;
+        if (!this.opts.identity || !every || every <= 0 || this.closed)
+            return;
+        const timer = setInterval(() => { void this.recheck(); }, every);
+        timer.unref?.();
+        this.recheckTimer = timer;
+    }
+    /** Re-run the challenge/assert exchange on an open connection. It stays open
+     * only when the SAME user re-asserts within RECHECK_TIMEOUT_MS and the
+     * policy still admits them; a member removed from the org is out at the
+     * next tick. */
+    async recheck() {
+        if (this.closed || !this.authed || this.recheckInFlight)
+            return;
+        const sidecarId = this.opts.info?.id;
+        const jkt = this.deviceJkt;
+        if (!sidecarId || !jkt) {
+            this.ch.close();
+            return;
+        }
+        this.recheckInFlight = true;
+        try {
+            const nonce = makeNonce();
+            const orgId = this.opts.admission?.orgId;
+            this.ch.send({ t: 'identity-challenge', nonce, sidecarId, ...(orgId ? { orgId } : {}) });
+            const verdict = await this.awaitAndVerifyIdentity(sidecarId, nonce, jkt, RECHECK_TIMEOUT_MS);
+            if (this.closed)
+                return;
+            const reason = !verdict.ok ? verdict.reason
+                : verdict.identity.userId !== this.verifiedUserId ? 'a different user answered'
+                    : !this.admits(verdict.identity) ? 'no longer admitted'
+                        : null;
+            if (reason !== null) {
+                this.opts.log?.(`identity re-check failed (${reason}); closing the connection`);
+                this.ch.close();
+            }
+        }
+        finally {
+            this.recheckInFlight = false;
+        }
+    }
+    now() {
+        return this.opts.now?.() ?? Date.now();
+    }
+    /* THE ONE PLACE A CREDENTIAL IS CHECKED is `onHello`, through the helpers
+     * below (spec 2026-09-29-device-enrollment-design). Exactly one credential
+     * is examined, chosen in this order; there is no other, and a hello with
+     * neither is refused:
+     *   1. `device`: the daemon proves its key (`server-proof`), the client
+     *      proves the key recorded for that device id (`client-proof`); unknown
+     *      and revoked ids are refused.
+     *   2. `enroll`: the same exchange over the key the hello SUBMITTED, so the
+     *      client proves possession BEFORE the code is burned; then the code is
+     *      burned and the key recorded, in one store write.
+     * No secret crosses the wire. */
+    /** Send `server-proof` over `subject` and wait for the client's signature.
+     * Null for no answer (timeout, close). The payload is built from values the
+     * DAEMON chose or checked, never from anything the client can echo back. */
+    async exchangeProofs(clientNonce, subject) {
+        const key = this.opts.sidecarKey;
+        if (!key)
+            return null;
+        const serverNonce = randomToken();
+        const sidecarId = this.opts.info?.id ?? '';
+        const sig = bytesToB64url(await key.sign(serverProofPayload({ clientNonce, serverNonce, sidecarId, sidecarJkt: key.jkt, subject })));
+        if (this.closed)
+            return null;
+        const answer = new Promise((resolve) => {
+            this.clientProofResolve = resolve;
+        });
+        this.ch.send({ t: 'server-proof', serverNonce, sidecarId, publicKey: key.publicJwk, sig });
+        let timer;
+        const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(null), PROOF_TIMEOUT_MS); });
+        timer?.unref?.();
+        try {
+            const got = await Promise.race([answer, timeout]);
+            return got ? { serverNonce, ...got } : null;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            this.clientProofResolve = undefined;
+        }
+    }
+    /** Whether `sig` is `key`'s signature over the client-proof payload for
+     * this exchange. */
+    async clientProofValid(key, clientNonce, serverNonce, subject, sig) {
+        const sidecarKey = this.opts.sidecarKey;
+        if (!sidecarKey)
+            return false;
+        return verifySignature(key, clientProofPayload({
+            serverNonce, clientNonce, sidecarId: this.opts.info?.id ?? '', sidecarJkt: sidecarKey.jkt, subject,
+        }), sig);
+    }
+    /** The device or enrollment path. Resolves the device this connection now
+     * is and its key's jkt (what the pairing assertion binds), or null after a
+     * denial has already been sent. */
+    async checkDeviceOrCode(m, deviceName) {
+        const devices = this.opts.devices;
+        const clientNonce = m.clientNonce;
+        const ready = !!devices && !!this.opts.sidecarKey && typeof clientNonce === 'string' && B64URL_32.test(clientNonce);
+        if (m.device !== undefined) {
+            const d = m.device;
+            const id = typeof d === 'object' && d !== null ? d.id : undefined;
+            if (!ready || !devices || typeof clientNonce !== 'string' || typeof id !== 'string' || !id || id.length > MAX_DEVICE_ID_LEN) {
+                this.denyCredential('device');
+                return null;
+            }
+            /* Subscribed BEFORE the exchange, so a revocation that lands between
+             * the read and the welcome still closes this connection. Dropped again
+             * on any refusal. */
+            this.watchRevocation(id);
+            const proof = await this.exchangeProofs(clientNonce, id);
+            let record = null;
+            if (proof) {
+                try {
+                    record = await devices.get(id);
+                }
+                catch (err) {
+                    // FAIL CLOSED: a store that cannot be read admits no device.
+                    this.opts.log?.(`device store unreadable: ${errMessage(err)}`);
+                    record = null;
+                }
+            }
+            const key = record ? asEcPublicJwk(record.publicKeyJwk) : null;
+            if (!proof || !record || !key || record.id !== id || record.revokedAt !== undefined
+                || !(await this.clientProofValid(key, clientNonce, proof.serverNonce, id, proof.sig))) {
+                this.unwatchRevocation();
+                this.denyCredential('device');
+                return null;
+            }
+            const deviceJkt = await jwkThumbprint(key);
+            if (!(await this.identityGate(deviceJkt, record.verifiedUserId))) {
+                this.unwatchRevocation();
+                this.denyCredential('identity');
+                return null;
+            }
+            return { deviceId: id, deviceJkt };
+        }
+        if (m.enroll !== undefined) {
+            const e = m.enroll;
+            const submitted = typeof e === 'object' && e !== null ? asEcPublicJwk(e.publicKey) : null;
+            /* A client that did not announce it can KEEP a device would throw the
+             * one it was issued away, leaving a ghost device behind and the code
+             * spent. Only a new client can obtain a code at all, so this refuses
+             * nobody real. All checked before the store, so nothing is burned. The
+             * same uniform denial as every other failure. */
+            if (!ready || !devices || typeof clientNonce !== 'string' || !keepsDevices(m) || !submitted) {
+                this.denyCredential('enrollment code');
+                return null;
+            }
+            const keyJkt = await jwkThumbprint(submitted);
+            const proof = await this.exchangeProofs(clientNonce, keyJkt);
+            /* PROOF OF POSSESSION FIRST: a hello that cannot sign with the key it
+             * submitted is refused BEFORE the store is touched, so no code is burned
+             * by someone who does not hold the key. */
+            if (!proof || !(await this.clientProofValid(submitted, clientNonce, proof.serverNonce, keyJkt, proof.sig))) {
+                this.denyCredential('enrollment code');
+                return null;
+            }
+            /* WHICH CODE. The client never sent one: it proved it knows one with an
+             * HMAC keyed by the code's hash over this exchange's client-proof
+             * payload. Each redeemable code's hash is tried (there are only ever a
+             * few), in constant time per comparison. A code minted for another
+             * sidecar key never reaches here with a proof, because the client pinned
+             * that key and stopped at this daemon's server-proof. */
+            let matched = null;
+            try {
+                const sidecarKey = this.opts.sidecarKey;
+                if (proof.codeProof && sidecarKey) {
+                    const payload = clientProofPayload({
+                        serverNonce: proof.serverNonce, clientNonce, sidecarId: this.opts.info?.id ?? '', sidecarJkt: sidecarKey.jkt, subject: keyJkt,
+                    });
+                    for (const h of await devices.codeHashes(this.now())) {
+                        if (sameB64(await codeProof(h, payload), proof.codeProof))
+                            matched = h;
+                    }
+                }
+            }
+            catch (err) {
+                this.opts.log?.(`enrollment failed: ${errMessage(err)}`);
+                matched = null;
+            }
+            if (!matched) {
+                this.denyCredential('enrollment code');
+                return null;
+            }
+            /* WHO, before anything is written: an unverified or unadmitted identity
+             * is refused here with the code still unburned. */
+            if (!(await this.identityGate(keyJkt))) {
+                this.denyCredential('identity');
+                return null;
+            }
+            const deviceId = makeDeviceId();
+            this.watchRevocation(deviceId);
+            let ok = false;
+            try {
+                const now = this.now();
+                ok = await devices.enroll(matched, {
+                    id: deviceId, name: deviceName, createdAt: now, lastSeenAt: now, publicKeyJwk: submitted, jkt: keyJkt,
+                    ...(this.verifiedUserId ? { verifiedUserId: this.verifiedUserId } : {}),
+                }, now);
+            }
+            catch (err) {
+                this.opts.log?.(`enrollment failed: ${errMessage(err)}`);
+                ok = false;
+            }
+            if (!ok) {
+                this.unwatchRevocation();
+                this.denyCredential('enrollment code');
+                return null;
+            }
+            this.opts.log?.(`enrolled device ${deviceId} (${deviceName})`);
+            return { deviceId, deviceJkt: keyJkt, issued: { id: deviceId } };
+        }
+        // Unreachable: onHello only calls this with `device` or `enroll` present.
+        this.denyCredential('none');
+        return null;
+    }
+    /** Close this connection the moment its device is revoked. At most one
+     * subscription per connection. */
+    watchRevocation(deviceId) {
+        this.unwatchRevocation();
+        const devices = this.opts.devices;
+        if (!devices)
+            return;
+        this.revocationOff = devices.onRevoked((id) => {
+            if (id !== deviceId)
+                return;
+            this.opts.log?.(`device ${deviceId} revoked; closing its connection`);
+            this.ch.close();
+        });
+    }
+    unwatchRevocation() {
+        this.revocationOff?.();
+        this.revocationOff = undefined;
+    }
     async onHello(m) {
         if (m.protocol !== SIDECAR_PROTOCOL) {
-            this.opts.log?.(`denied: unsupported protocol ${m.protocol}`);
-            this.ch.send({ t: 'denied', reason: `protocol ${m.protocol} unsupported` });
+            /* Echoed only as a number: the field crossed the wire unvalidated, and
+             * anything else (a long string, newlines) would be written into the
+             * operator's log and back onto the wire verbatim. */
+            const named = typeof m.protocol === 'number' && Number.isSafeInteger(m.protocol) ? String(m.protocol) : 'unknown';
+            this.opts.log?.(`denied: unsupported protocol ${named}`);
+            this.ch.send({ t: 'denied', reason: `protocol ${named} unsupported` });
+            this.noteOutcome('denied');
             this.countFailedHello();
             return;
         }
-        if (!safeEqual(m.token ?? '', this.opts.token)) {
-            this.opts.log?.('denied: invalid token');
-            this.ch.send({ t: 'denied', reason: 'invalid token' });
-            this.countFailedHello();
+        const deviceName = typeof m.clientName === 'string' && m.clientName
+            ? m.clientName.slice(0, MAX_IDENTITY_FIELD_LEN)
+            : 'unnamed device';
+        /* NO CREDENTIAL, NO CONNECTION. There is no shared pairing token: a hello
+         * that names neither a device nor an enrollment is refused like any other
+         * failure (a token sent by an older client included). */
+        if (m.device === undefined && m.enroll === undefined) {
+            this.denyCredential('no device or enrollment');
+            return;
+        }
+        /* Latched SYNCHRONOUSLY, before the store is consulted, so a second hello
+         * that arrives while this one is still being checked is ignored (see the
+         * 'hello' case). Released on a denial so a client may try again, up to
+         * MAX_FAILED_HELLOS. */
+        this.helloInFlight = true;
+        const cred = await this.checkDeviceOrCode(m, deviceName);
+        if (!cred) {
+            this.helloInFlight = false;
             return;
         }
+        // Dropped while the store was consulted: nothing to authenticate.
+        if (this.closed) {
+            this.unwatchRevocation();
+            return;
+        }
+        /** What every pairing assertion on this connection binds: the thumbprint
+         * of the device key it proved. */
+        this.deviceJkt = cred.deviceJkt;
+        this.deviceId = cred.deviceId;
+        this.issuedDevice = cred.issued;
+        /* Authenticated only now: the device key is proven AND, when a verifier
+         * is wired, the identity was verified and admitted (inside the credential
+         * check). Nothing this connection sent before this point was served. */
         this.authed = true;
         this.clearHelloDeadline();
+        this.noteOutcome('authed');
+        this.startRecheck();
         this.hostStateDir = m.stateDir ?? DEFAULT_STATE_DIR;
         // Runtime-validate identity, even though the declared type is `string` --
         // the message crossed the wire via `JSON.parse(...) as SidecarMsg`, so
@@ -1044,66 +1513,32 @@ export class SidecarServer {
                 this.opts.log?.(`onClient hook threw: ${errMessage(err)}`);
             }
         }
-        /* THE WAITS, started together. The welcome carries the synced directory
-         * name this daemon resolved for this connection, and the client has no
-         * other way to learn it -- it could previously only deduce it, and got null
-         * whenever no workspace was open or two hosts held the same workspace id,
-         * leaving a management surface unable to say which registrations were its
-         * own.
-         *
-         * The dirName lookup is STARTED here, before the identity verdict is
-         * awaited, so the two bounded waits (DIR_NAME_TIMEOUT_MS,
-         * IDENTITY_TIMEOUT_MS) overlap: the worst case stays one bound, not two.
-         * Both only ever resolve (every failure is null / unverified), so starting
-         * one and then awaiting the other cannot leave a rejection unhandled.
+        /* THE DIRNAME WAIT. The welcome carries the synced directory name this
+         * daemon resolved for this connection, and the client has no other way to
+         * learn it -- it could previously only deduce it, and got null whenever no
+         * workspace was open or two hosts held the same workspace id, leaving a
+         * management surface unable to say which registrations were its own.
          *
-         * Bounded, and every dirName failure ends the same way as an older daemon:
-         * no `dirName` on the welcome. A handshake that never arrives would be a
-         * far worse trade than a client that falls back to deducing. With neither
-         * a resolver nor a verifier nothing is awaited at all, and the welcome
-         * goes out in the same tick as today. */
+         * The identity was already decided inside the credential check (it gates
+         * authentication itself), so this is the only wait left. Bounded
+         * (DIR_NAME_TIMEOUT_MS), and every dirName failure ends the same way as an
+         * older daemon: no `dirName` on the welcome. A handshake that never
+         * arrives would be a far worse trade than a client that falls back to
+         * deducing. With no resolver nothing is awaited at all. */
         const dirIdentity = this.clientId === undefined
             ? undefined
             : { clientId: this.clientId, name: this.clientName ?? this.clientId };
         const dirNamePending = this.opts.clientDirName && dirIdentity
             ? this.resolveDirName(this.opts.clientDirName, dirIdentity)
             : undefined;
-        /* IDENTITY, decided BEFORE attendance or push can see this connection.
-         * Reached only past the pairing-token check above -- the challenge is
-         * never sent for a bad pairing token. Whatever the verdict, the
-         * connection pairs: unverified only withholds the widened trust a verified
-         * id earns. `verifiedUserId` is assigned here and nowhere else, once. The
-         * assertion is never logged; only the reason is. The Clerk token itself
-         * never reaches this class -- this exchange only ever sees a corenel-api
-         * pairing assertion (spec amendment 2026-09-25b). */
-        if (this.opts.identity) {
-            if (!m.wantsIdentity) {
-                this.identityResult = { verified: false, reason: 'not requested' };
-            }
-            else if (!this.opts.info?.id) {
-                this.identityResult = { verified: false, reason: 'no daemon id' };
-            }
-            else {
-                const sidecarId = this.opts.info.id;
-                /* The hash of the pairing token THIS connection presented (it passed
-                 * the check above). The assertion's `cnf.tkh` must equal it: that
-                 * binds the assertion to the pairing the browser actually made, so a
-                 * daemon that holds our token cannot relay our challenge through a
-                 * browser paired with IT (that browser hashed its own, different,
-                 * token). STARTED here but not awaited: the digest is async, and the
-                 * challenge, the resolver and the bound timer must all be in place
-                 * synchronously -- it is awaited only once an assertion is in hand
-                 * (see verdictFromAssertion), inside the same bound. A digest that
-                 * rejects pairs unverified ('error'), never refused. */
-                const tokenHash = pairingTokenHash(m.token ?? '').catch(() => null);
-                const nonce = makeNonce();
-                this.ch.send({ t: 'identity-challenge', nonce, sidecarId });
-                const verdict = await this.awaitAndVerifyIdentity(sidecarId, nonce, tokenHash);
-                if (verdict.ok)
-                    this.verifiedUserId = verdict.identity.userId;
-                this.identityResult = verdict.ok ? { verified: true } : { verified: false, reason: verdict.reason };
-            }
-            this.opts.log?.(`identity: ${this.identityResult.verified ? 'verified' : `unverified (${this.identityResult.reason})`}`);
+        /* Record the connect on the device. Best-effort and never awaited: a store
+         * that cannot be written must not delay or break a handshake that already
+         * passed. */
+        if (this.deviceId && this.opts.devices) {
+            const deviceId = this.deviceId;
+            void this.opts.devices.touch(deviceId, this.now(), this.verifiedUserId).catch((err) => {
+                this.opts.log?.(`could not record a connect for device ${deviceId}: ${errMessage(err)}`);
+            });
         }
         /* OLDER APPS (crew deploy). A client that does not announce it can deploy
          * has agents that sync here but never fire until deployed, and nothing on
@@ -1187,10 +1622,8 @@ export class SidecarServer {
      * 'timed out' unverified for the non-assertion answers, 'assertion too
      * long' WITHOUT calling the verifier for an oversized one, and otherwise
      * the verifier's own verdict (never thrown -- a throw or rejection becomes
-     * an unverified 'error'). The expectation is built here, once the
-     * pairing-token hash has settled; a hash that could not be computed is an
-     * unverified 'error' without calling the verifier. */
-    async verdictFromAssertion(answer, audience, nonce, tokenHashPending) {
+     * an unverified 'error'). */
+    async verdictFromAssertion(answer, audience, nonce, jkt) {
         if (answer.kind === 'none')
             return { ok: false, reason: 'no assertion' };
         if (answer.kind === 'timeout')
@@ -1201,10 +1634,7 @@ export class SidecarServer {
         const v = this.opts.identity;
         if (!v)
             return { ok: false, reason: 'no verifier' };
-        const tokenHash = await tokenHashPending;
-        if (tokenHash === null)
-            return { ok: false, reason: 'error' };
-        const expect = { audience, nonce, tokenHash };
+        const expect = { audience, nonce, jkt };
         try {
             const verdict = v.explain
                 ? await v.explain(assertion, expect)
@@ -1217,20 +1647,21 @@ export class SidecarServer {
         }
     }
     /** The identity verdict for this connection's challenge/assert exchange,
-     * bounded by IDENTITY_TIMEOUT_MS FROM THE CHALLENGE -- covering both the
-     * wait for `identity-assert` and the verify call, in one race, so a slow
-     * verifier cannot add a second timeout's worth of wait on top of a slow
-     * browser. Every failure mode (no assertion, an oversized one, a throw, a
-     * rejection, a malformed answer, a timeout) is an UNVERIFIED verdict with a
-     * reason -- never a refusal. The assertion is passed to the verifier and
-     * nowhere else. */
-    async awaitAndVerifyIdentity(audience, nonce, tokenHash) {
+     * bounded by `timeoutMs` FROM THE CHALLENGE -- covering both the wait for
+     * `identity-assert` and the verify call, in one race, so a slow verifier
+     * cannot add a second timeout's worth of wait on top of a slow browser.
+     * Every failure mode (no assertion, an oversized one, a throw, a rejection,
+     * a malformed answer, a timeout) is an UNVERIFIED verdict with a reason; the
+     * caller (`identityGate`, `recheck`) refuses on it. The assertion is passed
+     * to the verifier and nowhere else. */
+    async awaitAndVerifyIdentity(audience, nonce, jkt, timeoutMs) {
         let timer;
         try {
             const timed = new Promise((res) => {
-                timer = setTimeout(() => res({ ok: false, reason: 'timed out' }), IDENTITY_TIMEOUT_MS);
+                timer = setTimeout(() => res({ ok: false, reason: 'timed out' }), timeoutMs);
+                timer.unref?.();
             });
-            const answered = this.awaitIdentityAssertion().then((answer) => this.verdictFromAssertion(answer, audience, nonce, tokenHash));
+            const answered = this.awaitIdentityAssertion().then((answer) => this.verdictFromAssertion(answer, audience, nonce, jkt));
             const got = await Promise.race([answered, timed]);
             return normalizeVerdict(got);
         }
@@ -1316,6 +1747,8 @@ export class SidecarServer {
             ...(this.opts.runner?.hasDefaultModel ? ['default-model'] : []),
             // A client offers Stop on a watched daemon run only where it would work.
             ...(this.opts.runner?.cancel ? ['run-cancel'] : []),
+            // `run-history` understands `crew` (global vs one workspace).
+            ...(this.opts.runner?.history ? ['run-history-scope'] : []),
             // A client starts a task only where the daemon will honour it: an older
             // runner ignores `task`, and a dropped task must never look like a start.
             ...(this.opts.runner?.supportsTasks ? [RUN_TASK_FEATURE] : []),
@@ -1372,6 +1805,7 @@ export class SidecarServer {
             // daemon's definitions as an empty workspace when what it actually has is
             // no way to read them.
             ...(this.opts.config ? ['config'] : []),
+            ...(this.opts.config?.append ? ['config-append'] : []),
             // Whether this daemon may file a SAME-MACHINE client under the account it
             // is itself signed in as, rather than under the client's per-origin id.
             // Advertised so a client can SAY that its directory is shared across the
@@ -1386,6 +1820,9 @@ export class SidecarServer {
             // Whether this daemon verifies the browser's identity token. Advertised
             // only with a real verifier behind it; the verdict itself is `identity`.
             ...(this.opts.identity ? ['verified-identity'] : []),
+            // Whether this daemon keeps a device store: pairs with enrollment codes,
+            // issues device credentials, and answers devices-list/devices-revoke.
+            ...(this.opts.devices ? [DEVICES_FEATURE] : []),
         ];
         this.ch.send({
             t: 'welcome', tools, features,
@@ -1393,7 +1830,10 @@ export class SidecarServer {
             ...(dirName ? { dirName } : {}),
             ...(this.opts.push ? { vapidPublicKey: this.opts.push.publicKey } : {}),
             ...(this.opts.identity ? { identity: this.identityResult } : {}),
+            // The secret leaves the daemon here, once, and is not kept.
+            ...(this.issuedDevice ? { device: this.issuedDevice } : {}),
         });
+        this.issuedDevice = undefined;
     }
     /** Proxy a host HTTP request server-side. Restricted to LOOPBACK targets — the
      * sidecar must never be usable as an SSRF pivot to internal/metadata hosts. The
@@ -1789,6 +2229,17 @@ export class SidecarServer {
             this.ch.send({ t: 'run-error', id: m.id, error: 'this sidecar does not support watching runs' });
             return;
         }
+        /* TEAM MODE: A RUN IS ITS STARTER'S TO WATCH. Watching streams the run's
+         * events and its final text, which is its content, so it follows the same
+         * rule as a run's output: only the verified user who started it. A run
+         * with no recorded starter (the daemon's own clock) is refused. */
+        if (this.opts.admission?.ownRunsOnly) {
+            const starter = typeof m.runId === 'string' ? hub.startedBy?.(m.runId) : undefined;
+            if (!this.verifiedUserId || starter !== this.verifiedUserId) {
+                this.ch.send({ t: 'run-error', id: m.id, error: 'You can watch only runs you started.' });
+                return;
+            }
+        }
         const attached = hub.subscribe(m.runId, {
             event: (event) => this.ch.send({ t: 'event', id: m.id, runId: m.runId, event }),
             done: (r) => {
@@ -1855,9 +2306,13 @@ export class SidecarServer {
      */
     async onRunHistory(m) {
         try {
-            const runs = this.opts.runner?.history
-                ? await this.opts.runner.history({ clientId: this.clientId }, m.agent, m.limit)
-                : [];
+            const history = this.opts.runner?.history?.bind(this.opts.runner);
+            const crew = runHistoryCrewOf(m.crew);
+            const identity = { clientId: this.clientId };
+            // No crew: asked exactly as an older client asks.
+            const runs = !history ? [] : crew
+                ? await history(identity, m.agent, m.limit, crew)
+                : await history(identity, m.agent, m.limit);
             this.ch.send({ t: 'run-history-result', id: m.id, runs });
         }
         catch {
@@ -1938,7 +2393,11 @@ export class SidecarServer {
             : (agent, input, onEvent, identity) => 
             // Task and autonomy are forwarded as asked; the runner, not this
             // class, decides whether the agent may run that way.
-            this.opts.runner.run(agent, input, onEvent, identity, undefined, undefined, { task: m.task, autonomy: m.autonomy });
+            this.opts.runner.run(agent, input, onEvent, identity, undefined, undefined, {
+                task: m.task, autonomy: m.autonomy,
+                // From THIS connection's verified identity, never the message.
+                ...(this.verifiedUserId ? { startedBy: this.verifiedUserId } : {}),
+            });
         let runId;
         const pending = [];
         const onEvent = (event) => {
@@ -1962,7 +2421,7 @@ export class SidecarServer {
             // `onHostSyncPut`/`onHostSyncDelete` do for `hostSync.put`/`remove`.
             const started = await start(m.agent, m.input, onEvent, { clientId: this.clientId });
             runId = started.runId;
-            this.opts.runs?.open(runId);
+            this.opts.runs?.open(runId, this.verifiedUserId);
             this.ch.send({ t: 'run-accepted', id: m.id, runId });
             for (const event of pending) {
                 this.opts.runs?.publish(runId, event);
@@ -2038,6 +2497,96 @@ export class SidecarServer {
             this.ch.send({ t: 'roots-create-result', id: m.id, ok: false, error: errMessage(e) });
         }
     }
+    /** Every paired device, WITHOUT secret hashes, with `self` stamped from the
+     * device THIS connection authenticated as -- never from the message. */
+    async deviceSummaries() {
+        const devices = this.opts.devices;
+        if (!devices)
+            return [];
+        return (await devices.list()).map((d) => ({
+            id: d.id,
+            name: d.name,
+            jkt: d.jkt,
+            createdAt: d.createdAt,
+            ...(d.lastSeenAt !== undefined ? { lastSeenAt: d.lastSeenAt } : {}),
+            ...(d.revokedAt !== undefined ? { revokedAt: d.revokedAt } : {}),
+            ...(d.verifiedUserId !== undefined ? { verifiedUserId: d.verifiedUserId } : {}),
+            self: this.deviceId !== undefined && d.id === this.deviceId,
+        }));
+    }
+    async onDevicesList(m) {
+        if (!this.opts.devices) {
+            this.ch.send({ t: 'devices-list-result', id: m.id, ok: false, error: 'this daemon does not keep paired devices' });
+            return;
+        }
+        try {
+            this.ch.send({ t: 'devices-list-result', id: m.id, ok: true, devices: await this.deviceSummaries() });
+        }
+        catch (err) {
+            this.ch.send({ t: 'devices-list-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
+    /**
+     * Revoke one device. The store's revocation fan-out closes that device's
+     * live connections, on every per-connection server at once.
+     *
+     * The CALLER'S OWN device is refused here, from this connection's own
+     * credential rather than anything in the message: revoking it would cut off
+     * the screen the person is using, with no way back from it but a fresh code.
+     */
+    async onDevicesRevoke(m) {
+        const devices = this.opts.devices;
+        if (!devices) {
+            this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: false, error: 'this daemon does not keep paired devices' });
+            return;
+        }
+        if (typeof m.deviceId !== 'string' || !m.deviceId || m.deviceId.length > MAX_DEVICE_ID_LEN) {
+            this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: false, error: 'deviceId must be a device id' });
+            return;
+        }
+        if (this.deviceId !== undefined && m.deviceId === this.deviceId) {
+            this.ch.send({
+                t: 'devices-revoke-result', id: m.id, ok: false,
+                error: 'That is the device you are using. Revoke it from another device, or run `devices revoke` on the machine.',
+            });
+            return;
+        }
+        /* TEAM MODE: YOUR OWN DEVICES ONLY. Everyone on a team daemon is an org
+         * member, so "paired" no longer means "the same person": a member may
+         * revoke a device only when its recorded verified user is this
+         * connection's VERIFIED user (never anything the message claims). A
+         * connection with no verified user revokes nothing. The operator's local
+         * `devices revoke` verb keeps full power; it does not come through here. */
+        if (this.opts.admission?.ownDevicesOnly) {
+            let owner;
+            try {
+                owner = (await devices.get(m.deviceId))?.verifiedUserId;
+            }
+            catch (err) {
+                this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: false, error: errMessage(err) });
+                return;
+            }
+            if (!this.verifiedUserId || owner !== this.verifiedUserId) {
+                this.ch.send({
+                    t: 'devices-revoke-result', id: m.id, ok: false,
+                    error: 'You can revoke only your own devices here. The machine owner can revoke any device with `corenel-sidecar devices revoke`.',
+                });
+                return;
+            }
+        }
+        try {
+            const revoked = await devices.revoke(m.deviceId, this.now());
+            if (!revoked) {
+                this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: false, error: 'no such device, or it is already revoked' });
+                return;
+            }
+            this.opts.log?.(`device ${m.deviceId} revoked by a paired client`);
+            this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: true, devices: await this.deviceSummaries() });
+        }
+        catch (err) {
+            this.ch.send({ t: 'devices-revoke-result', id: m.id, ok: false, error: errMessage(err) });
+        }
+    }
     /** Every synced host directory, with `self` stamped from THIS connection's
      * own resolved directory -- never from anything the client sent. */
     async onHostsList(m) {
@@ -2349,8 +2898,21 @@ export class SidecarServer {
             this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: 'runId must be a non-empty string' });
             return;
         }
+        const output = m.output === true;
         try {
-            this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: true, plan: await runner.runPlan(m.runId) });
+            /* TEAM MODE: A RUN'S OUTPUT IS ITS STARTER'S. Reports, check output and
+             * the file list are answered only to the verified user who started the
+             * run (recorded with it, restarts included). A run with no recorded
+             * starter (the daemon's own clock, or an unverified start) is refused
+             * too: fail closed. The plan alone is not gated. */
+            if (output && this.opts.admission?.ownRunsOnly) {
+                const starter = runner.runStartedBy ? await runner.runStartedBy(m.runId) : null;
+                if (!this.verifiedUserId || starter !== this.verifiedUserId) {
+                    this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: 'You can see the output only of runs you started.' });
+                    return;
+                }
+            }
+            this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: true, plan: await runner.runPlan(m.runId, { output }) });
         }
         catch (err) {
             this.ch.send({ t: 'run-plan-get-result', id: m.id, ok: false, error: errMessage(err) });
@@ -2839,6 +3401,11 @@ export class SidecarServer {
             }
             if (m.t === 'config-write')
                 await svc.write(m.path, m.content);
+            else if (m.t === 'config-append') {
+                if (!svc.append)
+                    throw new Error('this sidecar cannot append to its harness config');
+                await svc.append(m.path, m.content);
+            }
             else
                 await svc.remove(m.path);
             this.ch.send({ t: 'config-result', id: m.id, ok: true });
@@ -2908,4 +3475,18 @@ export class SidecarServer {
         });
     }
 }
+/** `run-history`'s `crew`, off the wire: anything but the two known shapes is
+ * treated as absent (the global crew, as an older client meant). The id is
+ * only a selector among the CALLER's own roots -- the runner matches it
+ * exactly against the ones it enumerated -- so it is passed as given. */
+function runHistoryCrewOf(crew) {
+    if (!crew || typeof crew !== 'object')
+        return undefined;
+    const c = crew;
+    if (c.scope === 'global')
+        return { scope: 'global' };
+    if (c.scope !== 'workspace')
+        return undefined;
+    return typeof c.workspaceId === 'string' && c.workspaceId ? { scope: 'workspace', workspaceId: c.workspaceId } : { scope: 'workspace' };
+}
 //# sourceMappingURL=server.js.map