@corenel/harness 0.11.0 → 0.13.0

package/dist/sidecar/host.js

@@ -1,4 +1,5 @@
-import { SIDECAR_PROTOCOL, HOST_METHODS, errMessage, RUN_TASK_FEATURE, CREW_DEPLOY_FEATURE, } from '@corenel/protocol';
+import { asEcPublicJwk, jwkThumbprint, verifySignature, randomToken, serverProofPayload, clientProofPayload, parseEnrollmentCode, bytesToB64url, codeProof, codeHash, } from './deviceKeys.js';
+import { SIDECAR_PROTOCOL, HOST_METHODS, errMessage, RUN_TASK_FEATURE, RUN_PLAN_FEATURE, CREW_DEPLOY_FEATURE, DEVICES_FEATURE, isClerkOrgId, } from '@corenel/protocol';
 /** Decode a base64 chunk to bytes (atob is available in the browser and Node 18+). */
 function b64ToBytes(b64) {
     const bin = atob(b64);
@@ -7,6 +8,34 @@ function b64ToBytes(b64) {
         out[i] = bin.charCodeAt(i);
     return out;
 }
+/** Prefix of the error a connection rejects with when the daemon's key is not
+ * the one this client pinned (or it cannot prove it holds it). A caller shows
+ * this state as its own, never as a generic connection failure, and never
+ * retries it. */
+export const SIDECAR_KEY_MISMATCH = 'sidecar key mismatch';
+/** The mismatch error, recognisable by `isSidecarKeyMismatch`. */
+export function sidecarKeyMismatchError() {
+    return new Error(`${SIDECAR_KEY_MISMATCH}: this is not the sidecar you paired with`);
+}
+/** Prefix of the error `connect()` rejects with when this client has nothing
+ * to pair with (no device key, no code). */
+export const SIDECAR_NOT_PAIRED = 'sidecar not paired';
+export function isSidecarKeyMismatch(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return msg.startsWith(SIDECAR_KEY_MISMATCH);
+}
+/* NOT ADMITTED, AS OPPOSED TO A DEAD DEVICE. A daemon sends identity-challenge
+ * only AFTER the device (or enrollment) proof passed, so a denial that follows
+ * a challenge in the same handshake is about the ACCOUNT (not verified, not
+ * the owner, not a member, another user's device), never the device. This
+ * needs no new signal from the daemon: the order of its own messages says it.
+ * Deliberately a different prefix from 'sidecar denied connection', so no
+ * caller that forgets a device on a denial can mistake one for the other. */
+export const SIDECAR_NOT_ADMITTED = 'sidecar did not admit this account';
+export function isSidecarAccountRefusal(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return msg.startsWith(SIDECAR_NOT_ADMITTED);
+}
 export class SidecarHost {
     constructor(opts) {
         Object.defineProperty(this, "ch", {
@@ -216,6 +245,18 @@ export class SidecarHost {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "runPlanSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "runPlanPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "hostsSeq", {
             enumerable: true,
             configurable: true,
@@ -377,6 +418,98 @@ export class SidecarHost {
             writable: true,
             value: {}
         });
+        /** This client's device on this daemon: given, or just recorded. */
+        Object.defineProperty(this, "device", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** How the CURRENT hello authenticates, and what its proofs are bound to. */
+        Object.defineProperty(this, "mode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'none'
+        });
+        Object.defineProperty(this, "clientNonce", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        /** The sidecar key this connection is pinned to. */
+        Object.defineProperty(this, "pinnedJkt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The device id (device hello) or the offered key's jkt (enroll) that both
+         * proofs name. */
+        Object.defineProperty(this, "proofSubject", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        /** Whether a proof exchange is expected on this connection at all. */
+        Object.defineProperty(this, "expectProof", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /** The sidecar key this connection VERIFIED, once it has. */
+        Object.defineProperty(this, "verifiedSidecarJkt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The sidecar id the daemon signed into its server-proof. An identity
+         * challenge is answered only for this daemon, and only once it proved the
+         * pinned key: an assertion is never fetched for a peer that has not. */
+        Object.defineProperty(this, "provenSidecarId", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** An identity challenge arrived from the proven daemon during this
+         * handshake: the device credential was accepted (SIDECAR_NOT_ADMITTED). */
+        Object.defineProperty(this, "challengedInHandshake", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /** The credential failed before sending (a malformed code, no key). */
+        Object.defineProperty(this, "credentialError", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The pairing code's random part, for `codeProof` (enroll only). */
+        Object.defineProperty(this, "codeSecret", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "devicesSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "devicesPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "imported", {
             enumerable: true,
             configurable: true,
@@ -391,10 +524,86 @@ export class SidecarHost {
         });
         this.opts = opts;
         this.ch = opts.channel;
+        this.device = opts.device;
         this.ch.onMessage((m) => this.onMessage(m));
     }
+    /** The hello's credential: the device if this client has one, else the
+     * enrollment code. Exactly one is sent, and no secret. Sets up what the
+     * proof exchange will be bound to. Without either (or without a key) there
+     * is nothing to pair with and `credentialError` is set. */
+    credentialFields() {
+        const key = this.opts.deviceKey;
+        this.clientNonce = randomToken();
+        if (this.device && key) {
+            this.mode = 'device';
+            this.pinnedJkt = this.device.sidecarJkt;
+            this.proofSubject = this.device.id;
+            this.expectProof = true;
+            return { clientNonce: this.clientNonce, device: { id: this.device.id } };
+        }
+        if (this.opts.enroll) {
+            const parsed = parseEnrollmentCode(this.opts.enroll);
+            if (!parsed || !key) {
+                this.credentialError = new Error('that is not a pairing code this app can use');
+                return {};
+            }
+            this.mode = 'enroll';
+            this.pinnedJkt = parsed.sidecarJkt;
+            this.codeSecret = parsed.secret;
+            this.proofSubject = key.jkt;
+            this.expectProof = true;
+            // The public key only: the code is proven later, never sent.
+            return { clientNonce: this.clientNonce, enroll: { publicKey: key.publicJwk } };
+        }
+        this.mode = 'none';
+        this.credentialError = new Error(`${SIDECAR_NOT_PAIRED}: pair it with a code from the sidecar`);
+        return {};
+    }
+    /** This client's device on this daemon (given, or just recorded), or
+     * undefined when it is still pairing by code. */
+    deviceCredential() { return this.device; }
+    /** The sidecar key this connection verified, or null before it has. */
+    sidecarKeyJkt() { return this.verifiedSidecarJkt; }
+    /** The daemon's `server-proof`: check it is the PINNED key and that it
+     * signed THIS exchange, then prove this client's key. On any
+     * failure nothing more is sent: the connection is dropped and `connect()`
+     * rejects with the key-mismatch error. */
+    async answerServerProof(m) {
+        const key = this.opts.deviceKey;
+        if (!this.expectProof || !key || this.verifiedSidecarJkt !== null)
+            return;
+        this.expectProof = false; // one exchange per connection
+        const sidecarKey = asEcPublicJwk(m.publicKey);
+        const sidecarJkt = sidecarKey ? await jwkThumbprint(sidecarKey) : null;
+        const ok = !!sidecarKey && !!sidecarJkt
+            && this.pinnedJkt !== null && sidecarJkt === this.pinnedJkt
+            && typeof m.serverNonce === 'string' && typeof m.sidecarId === 'string'
+            && await verifySignature(sidecarKey, serverProofPayload({
+                clientNonce: this.clientNonce, serverNonce: m.serverNonce, sidecarId: m.sidecarId, sidecarJkt, subject: this.proofSubject,
+            }), m.sig);
+        if (!ok || !sidecarJkt) {
+            this.failKeyMismatch();
+            return;
+        }
+        this.verifiedSidecarJkt = sidecarJkt;
+        this.provenSidecarId = m.sidecarId;
+        const payload = clientProofPayload({
+            serverNonce: m.serverNonce, clientNonce: this.clientNonce, sidecarId: m.sidecarId, sidecarJkt, subject: this.proofSubject,
+        });
+        const sig = bytesToB64url(await key.sign(payload));
+        // Knowledge of the code, bound to this exchange, only now that the daemon
+        // proved the key the code named.
+        const proofOfCode = this.mode === 'enroll' && this.codeSecret ? await codeProof(await codeHash(this.codeSecret), payload) : undefined;
+        this.ch.send(proofOfCode ? { t: 'client-proof', sig, codeProof: proofOfCode } : { t: 'client-proof', sig });
+    }
+    failKeyMismatch() {
+        const pending = this.welcome;
+        this.welcome = null;
+        pending?.reject(sidecarKeyMismatchError());
+        this.disconnect(SIDECAR_KEY_MISMATCH);
+    }
     /** Authenticate, then import the sidecar's tools. Resolves with their names,
-     * or rejects if the sidecar denies the token / protocol.
+     * or rejects if the sidecar refuses the credential or protocol, or proves a key other than the pinned one.
      *
      * `timeoutMs`, when given, rejects the connection if no `welcome`/`denied`
      * ever arrives -- a handshake that silently never completes (a peer that
@@ -418,29 +627,42 @@ export class SidecarHost {
                     pending?.reject(new Error(`sidecar handshake timed out after ${timeoutMs}ms waiting for welcome`));
                 }, timeoutMs);
             }
+            const credential = this.credentialFields();
+            if (this.credentialError) {
+                const pending = this.welcome;
+                this.welcome = null;
+                pending?.reject(this.credentialError);
+                return;
+            }
             this.ch.send({
-                t: 'hello', protocol: SIDECAR_PROTOCOL, token: this.opts.token,
+                t: 'hello', protocol: SIDECAR_PROTOCOL, ...credential,
                 ...(this.opts.stateDir ? { stateDir: this.opts.stateDir } : {}),
                 ...(this.opts.clientId ? { clientId: this.opts.clientId } : {}),
                 ...(this.opts.clientName ? { clientName: this.opts.clientName } : {}),
                 ...(this.opts.accounts?.length ? { accounts: this.opts.accounts } : {}),
-                ...(this.opts.wantsIdentity ? { wantsIdentity: true } : {}),
                 // What THIS client understands, so a daemon can tell an older app
                 // (whose agents sync but never fire until deployed) from this one.
-                capabilities: [CREW_DEPLOY_FEATURE],
+                // DEVICES_FEATURE only when the caller has somewhere to KEEP an issued
+                // device credential: a daemon issues one only to a client that says
+                // so, since one thrown away is a ghost device on the daemon for ever.
+                capabilities: [CREW_DEPLOY_FEATURE, ...(this.opts.onDeviceIssued && this.opts.deviceKey ? [DEVICES_FEATURE] : [])],
             });
         });
     }
     /** Answers the daemon's `identity-challenge`. `onIdentityChallenge` resolving
      * a string sends it as the assertion; resolving `null`, having no handler
      * at all, or THROWING all send `identity-assert` with no assertion -- every
-     * one of those is a considered "no identity to offer", never a reason to
-     * fail the handshake. The Clerk token itself never reaches this class: only
-     * whatever assertion the callback hands back does. */
+     * one of those is a considered "no identity to offer", which the daemon
+     * refuses at once rather than waiting out its bound. The Clerk token itself
+     * never reaches this class: only whatever assertion the callback hands back
+     * does. A malformed `orgId` is not forwarded. */
     async answerIdentityChallenge(m) {
         let assertion = null;
         try {
-            assertion = (await this.opts.onIdentityChallenge?.({ nonce: m.nonce, sidecarId: m.sidecarId })) ?? null;
+            const proven = this.verifiedSidecarJkt !== null && this.provenSidecarId !== null && m.sidecarId === this.provenSidecarId;
+            const jkt = proven ? this.opts.deviceKey?.jkt : undefined;
+            const orgId = isClerkOrgId(m.orgId) ? m.orgId : undefined;
+            assertion = jkt ? (await this.opts.onIdentityChallenge?.({ nonce: m.nonce, sidecarId: m.sidecarId, jkt, ...(orgId ? { orgId } : {}) })) ?? null : null;
         }
         catch {
             assertion = null;
@@ -517,6 +739,9 @@ export class SidecarHost {
         for (const p of this.releasePending.values())
             p.reject(new Error(reason));
         this.releasePending.clear();
+        for (const p of this.runPlanPending.values())
+            p.reject(new Error(reason));
+        this.runPlanPending.clear();
         for (const p of this.hostsPending.values())
             p.reject(new Error(reason));
         this.hostsPending.clear();
@@ -557,6 +782,9 @@ export class SidecarHost {
         for (const p of this.pushPending.values())
             p.reject(new Error(reason));
         this.pushPending.clear();
+        for (const p of this.devicesPending.values())
+            p.reject(new Error(reason));
+        this.devicesPending.clear();
         /* The rejections above already drop each login's waiter via the wrapper
          * mcpLogin installs. Cleared here too so that stays true if sendMcpAdmin
          * is ever the one carrying a login -- a stale waiter would fire a consent
@@ -568,7 +796,18 @@ export class SidecarHost {
     }
     onMessage(m) {
         switch (m.t) {
+            case 'server-proof': {
+                void this.answerServerProof(m);
+                return;
+            }
             case 'welcome': {
+                /* Welcomed ONLY after the daemon proved the pinned key. A welcome
+                 * before that is an impostor (or a daemon too old for keys) skipping
+                 * the proof: refuse it. */
+                if (this.verifiedSidecarJkt === null) {
+                    this.failKeyMismatch();
+                    return;
+                }
                 this.features = m.features ?? [];
                 // Runtime-validated: an untrusted/older daemon's `vapidPublicKey` is
                 // just a JSON-parsed `string`, and a malformed one must never be
@@ -584,6 +823,21 @@ export class SidecarHost {
                 this.identity = m.identity && typeof m.identity === 'object' && typeof m.identity.verified === 'boolean'
                     ? m.identity : undefined;
                 this.info = m.info ?? {};
+                /* A recorded device: accepted only as the answer to an enrollment or
+                 * an upgrade (a device hello is never re-issued), only after this
+                 * connection verified the daemon's key -- that key is what gets
+                 * pinned -- and only in the shape the daemon mints. Anything else is
+                 * ignored, so this client keeps pairing the way it just did. */
+                const issued = m.device;
+                const issuedId = typeof issued === 'object' && issued !== null ? issued.id : undefined;
+                if (this.mode !== 'device' && this.verifiedSidecarJkt !== null
+                    && typeof issuedId === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(issuedId)) {
+                    this.device = { id: issuedId, sidecarJkt: this.verifiedSidecarJkt };
+                    try {
+                        this.opts.onDeviceIssued?.({ ...this.device });
+                    }
+                    catch { /* the connection is up either way */ }
+                }
                 for (const decl of m.tools) {
                     const tool = { ...decl, run: (args) => this.invoke(decl.name, args) };
                     this.opts.registerTool(tool);
@@ -594,11 +848,18 @@ export class SidecarHost {
                 return;
             }
             case 'denied': {
-                this.welcome?.reject(new Error(`sidecar denied connection: ${m.reason}`));
+                this.welcome?.reject(new Error(this.challengedInHandshake
+                    ? `${SIDECAR_NOT_ADMITTED}: ${m.reason}`
+                    : `sidecar denied connection: ${m.reason}`));
                 this.welcome = null;
                 return;
             }
             case 'identity-challenge': {
+                // Before the welcome: the device proof has passed (see
+                // SIDECAR_NOT_ADMITTED). Only a daemon that proved the pinned key
+                // counts; anything earlier is ignored here as it is below.
+                if (this.welcome && this.verifiedSidecarJkt !== null)
+                    this.challengedInHandshake = true;
                 void this.answerIdentityChallenge(m);
                 return;
             }
@@ -1029,6 +1290,16 @@ export class SidecarHost {
                 p.resolve(m.ok ? { ok: true, room: m.room } : { ok: false, problems: m.problems });
                 return;
             }
+            case 'devices-list-result':
+            case 'devices-revoke-result': {
+                // One map for both: each carries the COMPLETE list afterwards.
+                const p = this.devicesPending.get(m.id);
+                if (!p)
+                    return;
+                this.devicesPending.delete(m.id);
+                p.resolve(m.ok ? { ok: true, devices: m.devices } : { ok: false, error: m.error });
+                return;
+            }
             case 'hosts-list-result':
             case 'hosts-forget-result': {
                 // One pending map for both, for the same reason as the pause results
@@ -1080,6 +1351,14 @@ export class SidecarHost {
                 p.resolve(m.ok ? { ok: true, released: m.released } : { ok: false, error: m.error });
                 return;
             }
+            case 'run-plan-get-result': {
+                const p = this.runPlanPending.get(m.id);
+                if (!p)
+                    return;
+                this.runPlanPending.delete(m.id);
+                p.resolve(m.ok ? { ok: true, plan: m.plan } : { ok: false, error: m.error });
+                return;
+            }
             case 'room-list-result': {
                 const p = this.roomListPending.get(m.id);
                 if (!p)
@@ -1340,11 +1619,15 @@ export class SidecarHost {
      * An empty list means no record, which a caller renders rather than treats
      * as an error — a daemon that keeps none is a normal daemon.
      */
-    runHistory(agent, limit) {
+    runHistory(agent, limit, crew) {
         return this.sessionCall((id) => ({
-            t: 'run-history', id, agent, ...(limit === undefined ? {} : { limit }),
+            t: 'run-history', id, agent, ...(limit === undefined ? {} : { limit }), ...(crew ? { crew } : {}),
         }));
     }
+    /** True when `runHistory` can be asked about one crew (global vs a
+     * workspace). An older daemon answers every question from the global crew,
+     * so a caller must know before it trusts a workspace answer. */
+    supportsRunHistoryScope() { return this.features.includes('run-history-scope'); }
     /**
      * One run's kept events, as the daemon stored them.
      *
@@ -1561,9 +1844,10 @@ export class SidecarHost {
     }
     /** Answer an outstanding permission ask. Fire-and-forget over the wire — the
      * actual drop of the prompt is driven by the server's `permission-resolved`
-     * broadcast (`onPermissionResolved`), not by this call returning. */
-    answerPermission(id, decision) {
-        this.ch.send({ t: 'permission-answer', id, decision });
+     * broadcast (`onPermissionResolved`), not by this call returning. `note` is
+     * the person's reason for a deny; the daemon trims and caps it. */
+    answerPermission(id, decision, note) {
+        this.ch.send({ t: 'permission-answer', id, decision, ...(note ? { note } : {}) });
     }
     /** Push one definition file's content to the daemon, to be persisted under
      * this client's own `<stateDir>/hosts/<dirName>/` (Slice 2 host sync).
@@ -1630,6 +1914,13 @@ export class SidecarHost {
     configWrite(path, content) {
         return this.configCall({ t: 'config-write', id: ++this.configSeq, path, content }).then(() => { });
     }
+    /** True when this daemon can append to a config file without a rewrite. */
+    supportsConfigAppend() { return this.features.includes('config-append'); }
+    /** Append to one config file (O_APPEND daemon-side). Only call when
+     * supportsConfigAppend(); an older daemon would refuse the message. */
+    configAppend(path, content) {
+        return this.configCall({ t: 'config-append', id: ++this.configSeq, path, content }).then(() => { });
+    }
     /** Delete one config file or subtree (recursive, idempotent). */
     configDelete(path) {
         return this.configCall({ t: 'config-delete', id: ++this.configSeq, path }).then(() => { });
@@ -1659,6 +1950,28 @@ export class SidecarHost {
      * directories. Feature-detected so a client offers a destructive control only
      * where the daemon would actually honour it. */
     supportsHostsAdmin() { return this.features.includes('hosts-admin'); }
+    /** Whether the connected daemon keeps paired devices (enrollment codes,
+     * device credentials, `devices-list`/`devices-revoke`). */
+    supportsDevices() { return this.features.includes(DEVICES_FEATURE); }
+    /** Every device paired with this daemon, with `self` marking this one. */
+    listDevices() {
+        const id = ++this.devicesSeq;
+        return new Promise((resolve, reject) => {
+            this.devicesPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'devices-list', id });
+        });
+    }
+    /** Revoke one device: it can never connect again, and its live connections
+     * close. `ok: false` is the daemon's considered refusal (this client's own
+     * device, an unknown one), so it resolves; only a dropped connection
+     * rejects. Resolves with the COMPLETE list afterwards. */
+    revokeDevice(deviceId) {
+        const id = ++this.devicesSeq;
+        return new Promise((resolve, reject) => {
+            this.devicesPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'devices-revoke', id, deviceId });
+        });
+    }
     /** Whether the connected daemon serves an MCP surface at all. `mcp-list`
      * answers an empty list either way (see sidecar.ts), so this is advisory --
      * a caller uses it to decide whether to bother asking, not as a gate. */
@@ -1864,6 +2177,18 @@ export class SidecarHost {
             this.ch.send({ t: 'workspace-release', id, root: ref.root, stateDir: ref.stateDir, runId: ref.runId });
         });
     }
+    /** True when the daemon answers run-plan-get. */
+    supportsRunPlan() { return this.features.includes(RUN_PLAN_FEATURE); }
+    /** One run's plan from its record; `output: true` adds what the run
+     * produced. `ok: false` is the daemon's answer; only a dropped connection
+     * rejects. Ask only when supportsRunPlan() is true. */
+    runPlanGet(runId, opts = {}) {
+        const id = ++this.runPlanSeq;
+        return new Promise((resolve, reject) => {
+            this.runPlanPending.set(id, { resolve, reject });
+            this.ch.send({ t: 'run-plan-get', id, runId, ...(opts.output ? { output: true } : {}) });
+        });
+    }
     /** Ask the daemon to open a room. `ok: false` here is the daemon's CONSIDERED
      * refusal (validation problems, or an unreachable participant) — a real answer,
      * not a transport failure, so it resolves rather than rejects. Only a dropped