@harness-fe/mcp-server 3.4.1 → 4.0.0-next.1

package/dist/mcpHttp.js

@@ -21,7 +21,13 @@ export async function startMcpHttpServer(bridge, opts = {}) {
     const eventStore = opts.eventStore === null
         ? undefined
         : opts.eventStore ?? new MemoryEventStore();
-    const server = createMcpServer(bridge, { experimentalEnvVar: opts.experimentalEnvVar });
+    // Pass the daemon's auth so MCP tools can identify the per-call principal
+    // from request headers (4.0 · P4). stdio (startMcpStdioServer) omits this,
+    // so stdio calls resolve to the local principal.
+    const server = createMcpServer(bridge, {
+        experimentalEnvVar: opts.experimentalEnvVar,
+        auth: bridge.getAuthOptions(),
+    });
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: stateful ? () => randomUUID() : undefined,
         eventStore,

package/dist/sessionRouter.d.ts

@@ -8,10 +8,13 @@
  * Caller can override via explicit tabId on every command.
  */
 import type { PeerRole, TabInfo } from '@harness-fe/protocol';
+import type { Principal } from './identity.js';
 export interface PeerSession {
     role: PeerRole;
     projectId: string;
     tabId?: string;
+    /** Caller identity behind this connection (4.0 · P1). Defaults to `local`. */
+    principal?: Principal;
     /** Runtime-client only: identifies the page load (sessionId) this connection belongs to. */
     sessionId?: string;
     /** Runtime-client only: stable per-browser visitor identifier. */

package/dist/store/JsonlStore.js

@@ -401,6 +401,8 @@ export class JsonlStore {
             ...existing,
             ...meta,
             id: sessionId,
+            // Write-once: first principal to open the session owns it.
+            createdBy: existing?.createdBy ?? meta.createdBy,
         };
         // Reset participants — we'll rebuild via dedup loop below
         merged.participants = [];
@@ -552,6 +554,8 @@ export class JsonlStore {
             id: projectId,
             createdAt: existing?.createdAt ?? Date.now(),
             lastActiveAt: Date.now(),
+            // Write-once: the first principal to create the project owns it.
+            createdBy: existing?.createdBy ?? patch.createdBy,
         };
         enforceExtensionBudget(merged, `project ${projectId}`);
         writeJson(metaPath, merged);

package/dist/store/types.d.ts

@@ -63,6 +63,12 @@ export interface ProjectMeta {
     parentProjectId?: string;
     displayName?: string;
     tags?: string[];
+    /**
+     * Caller-identity tag (4.0 · P1): principal id that first created this
+     * project. Write-once (locked on creation like `createdAt`); informational
+     * in P1, the basis for `project → agent` routing/isolation in P3.
+     */
+    createdBy?: string;
     metadata?: Record<string, unknown>;
 }
 /**
@@ -140,6 +146,11 @@ export interface SessionMeta {
         };
         storageTruncated?: boolean;
     };
+    /**
+     * Caller-identity tag (4.0 · P1): principal id of the connection that
+     * opened this session. Write-once. Informational in P1.
+     */
+    createdBy?: string;
     metadata?: Record<string, unknown>;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/mcp-server",
-  "version": "3.4.1",
+  "version": "4.0.0-next.1",
   "description": "Unified MCP daemon: stdio MCP for AI agents + WS bridge for Vite plugin and runtime client.",
   "type": "module",
   "license": "MIT",
@@ -39,7 +39,7 @@
     "ws": "^8.18.0",
     "zod": "^4.4.3",
     "@harness-fe/dashboard-ui": "0.2.0",
-    "@harness-fe/protocol": "3.2.0"
+    "@harness-fe/protocol": "4.0.0-next.0"
   },
   "devDependencies": {
     "@types/ws": "^8.5.10",

package/src/bridge.ts

@@ -18,10 +18,12 @@ import { networkInterfaces } from 'node:os';
 import {
     DEFAULT_LOGIN_PATH,
     handleLoginPost,
+    isAuthEnabled,
     isAuthorized,
     sendUnauthorized,
     type AuthOptions,
 } from './auth.js';
+import { LOCAL_PRINCIPAL, resolvePrincipal, type Principal } from './identity.js';
 import { join as joinPath } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -29,6 +31,7 @@ import {
     DEFAULT_WS_PORT,
     EVENT_NAME,
     PROTOCOL_VERSION,
+    type ConsentPolicy,
     isLoopbackHost,
     pageLoadPayloadSchema,
     rrwebChunkPayloadSchema,
@@ -79,8 +82,8 @@ export interface IBridge {
     ): Promise<unknown>;
     listTabs(): Promise<TabInfo[]>;
     listTasks(filter?: { status?: TaskStatus | 'all'; limit?: number }): Promise<Task[]>;
-    claimTask(id: string): Promise<Task | undefined>;
-    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    claimTask(id: string, principal?: Principal): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string, principal?: Principal): Promise<Task | undefined>;
     getMemoryStore(): IMemoryStore;
     /**
      * Base URL (e.g. http://127.0.0.1:47729) where the replay viewer is reachable.
@@ -139,6 +142,13 @@ export interface BridgeOptions {
      * token disables auth (only valid when bound to a loopback host).
      */
     auth?: AuthOptions;
+    /**
+     * Browser-consent policy for control commands (4.0 · P2). When omitted it
+     * defaults to `session` while auth is enabled (non-loopback / exposed) and
+     * `off` on loopback — so solo dev keeps its zero-friction flow and any
+     * exposed daemon prompts the user before an agent drives the page.
+     */
+    consent?: ConsentPolicy;
     /**
      * Override the host used when building outbound URLs (dashboard links,
      * replay viewer URLs). When omitted and `host` is `0.0.0.0` / `::`, the
@@ -221,8 +231,10 @@ export class Bridge implements IBridge {
     private pending = new Map<string, PendingCommand>();
     private eventListeners = new Set<EventListener>();
     private tasks = new Map<string, Task>();
-    private opts: Required<Omit<BridgeOptions, 'store' | 'taskStore' | 'memoryStore' | 'autoPurge' | 'attachmentsDataDir' | 'auth' | 'publicHost' | 'dataDir' | 'label'>>;
+    private opts: Required<Omit<BridgeOptions, 'store' | 'taskStore' | 'memoryStore' | 'autoPurge' | 'attachmentsDataDir' | 'auth' | 'consent' | 'publicHost' | 'dataDir' | 'label'>>;
     private auth: AuthOptions;
+    /** Browser-consent policy pushed to runtime clients in hello.ack (4.0 · P2). */
+    private readonly consentPolicy: ConsentPolicy;
     private publicHostOverride: string | undefined;
     private readonly attachDataDir: string;
     private autoPurgeOpts: Required<NonNullable<BridgeOptions['autoPurge']>>;
@@ -233,6 +245,15 @@ export class Bridge implements IBridge {
      * or sessionId (for runtime-client connections).
      */
     private connToStoreId = new Map<string, string>();
+    /** Caller identity per connection (4.0 · P1). Resolved at WS upgrade. */
+    private connToPrincipal = new Map<string, Principal>();
+    /**
+     * Identity attributed to MCP-driven writes (task claim/resolve). The MCP
+     * tool layer is a daemon-wide singleton today with no per-call caller
+     * context, so stdio/HTTP agents collapse to one principal. P4 (per-session
+     * MCP transport) replaces this with the real per-call principal.
+     */
+    private readonly defaultPrincipal: Principal = LOCAL_PRINCIPAL;
     /** Connections that already logged a "no store session" warning. */
     private warnedNoSession = new Set<string>();
     /**
@@ -273,6 +294,12 @@ export class Bridge implements IBridge {
             host: opts.host ?? '127.0.0.1',
         };
         this.auth = opts.auth ?? {};
+        // Consent defaults track the auth boundary: exposed (auth on) ⇒ prompt
+        // once per session; loopback solo (auth off) ⇒ no prompts. Explicit
+        // opts.consent always wins.
+        this.consentPolicy = opts.consent ?? {
+            mode: isAuthEnabled(this.auth) ? 'session' : 'off',
+        };
         this.publicHostOverride = opts.publicHost;
         // Default auto-purge ON. CI / tests pass `enabled: false` (or set
         // env HARNESS_FE_PURGE_DISABLED=1) to opt out.
@@ -440,7 +467,7 @@ export class Bridge implements IBridge {
             });
 
             const wss = new WebSocketServer({ noServer: true });
-            wss.on('connection', (ws) => this.onConnection(ws));
+            wss.on('connection', (ws, req: IncomingMessage) => this.onConnection(ws, req));
 
             httpServer.on('upgrade', (req, socket, head) => {
                 if (!isAuthorized(req, this.auth)) {
@@ -560,6 +587,11 @@ export class Bridge implements IBridge {
         return this.auth.token;
     }
 
+    /** Daemon auth options — used by the MCP layer to identify the per-call principal (4.0 · P4). */
+    getAuthOptions(): AuthOptions {
+        return this.auth;
+    }
+
     /**
      * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
      *
@@ -740,11 +772,15 @@ export class Bridge implements IBridge {
         return filtered.slice(0, limit);
     }
 
-    async claimTask(id: string): Promise<Task | undefined> {
+    async claimTask(id: string, principal?: Principal): Promise<Task | undefined> {
         const task = this.tasks.get(id);
         if (!task) return undefined;
         task.status = 'claimed';
         task.claimedAt = Date.now();
+        // Tag which agent picked it up (4.0 · P1/P4). The per-call principal
+        // (HTTP MCP, resolved from request headers) wins; stdio / no-caller
+        // falls back to the daemon's local principal.
+        task.agentId = (principal ?? this.defaultPrincipal).id;
         this.persistTasks();
         // Persist status change to store
         this.persistTaskEvent(task, 'task:claim');
@@ -757,12 +793,13 @@ export class Bridge implements IBridge {
         return this.readTaskAttachment(task.projectId, taskId, attachmentId);
     }
 
-    async resolveTask(id: string, note?: string): Promise<Task | undefined> {
+    async resolveTask(id: string, note?: string, principal?: Principal): Promise<Task | undefined> {
         const task = this.tasks.get(id);
         if (!task) return undefined;
         task.status = 'resolved';
         task.resolvedAt = Date.now();
         if (note !== undefined) task.note = note;
+        if (!task.agentId) task.agentId = (principal ?? this.defaultPrincipal).id;
         this.persistTasks();
         // Persist status change to store
         this.persistTaskEvent(task, 'task:resolve');
@@ -1036,9 +1073,16 @@ export class Bridge implements IBridge {
         return false;
     }
 
-    private onConnection(ws: WebSocket): void {
+    private onConnection(ws: WebSocket, req?: IncomingMessage): void {
         const connectionId = randomUUID();
         this.sockets.set(connectionId, ws);
+        // Resolve caller identity once at connection time (4.0 · P1). The
+        // upgrade handler already enforced isAuthorized, so resolvePrincipal
+        // won't reject here; fall back to LOCAL for the loopback / no-req path.
+        this.connToPrincipal.set(
+            connectionId,
+            (req && resolvePrincipal(req, this.auth)) || LOCAL_PRINCIPAL,
+        );
 
         ws.on('message', (raw) => {
             let parsed: unknown;
@@ -1096,6 +1140,7 @@ export class Bridge implements IBridge {
                 }
             }
             this.router.unregister(connectionId);
+            this.connToPrincipal.delete(connectionId);
         });
 
         ws.on('error', () => {
@@ -1145,6 +1190,7 @@ export class Bridge implements IBridge {
                 // absent. The runtime-client branch below opens its own store
                 // session if one does not already exist for this project.
 
+                const principal = this.connToPrincipal.get(connectionId) ?? LOCAL_PRINCIPAL;
                 const session = this.router.register({
                     role: frame.role,
                     projectId: frame.projectId,
@@ -1154,6 +1200,7 @@ export class Bridge implements IBridge {
                     userId: frame.userId,
                     connectionId,
                     page: frame.page,
+                    principal,
                 });
                 // Persist to store
                 if (this.store) {
@@ -1167,6 +1214,7 @@ export class Bridge implements IBridge {
                             this.store.upsertProject(frame.projectId, {
                                 parentProjectId: frame.parentProjectId,
                                 displayName: frame.displayName,
+                                createdBy: principal.id,
                             });
                         } catch (err) {
                             // Cycle detection or other validation failure —
@@ -1244,6 +1292,7 @@ export class Bridge implements IBridge {
                             referrer: undefined,
                             userAgent: frame.page?.userAgent,
                             participants,
+                            createdBy: principal.id,
                         });
                         this.connToStoreId.set(connectionId, sessionId);
                         this.notifyDashboard({
@@ -1286,6 +1335,7 @@ export class Bridge implements IBridge {
                     id: frame.id,
                     tabId: session.tabId,
                     serverVersion: PROTOCOL_VERSION,
+                    consent: this.consentPolicy,
                 };
                 ws.send(JSON.stringify(ack));
                 // One concise line per accepted peer. Visibility for "is the

package/src/daemon.ts

@@ -25,6 +25,8 @@
 
 import type { IncomingMessage } from 'node:http';
 
+import type { ConsentPolicy } from '@harness-fe/protocol';
+
 import { Bridge } from './bridge.js';
 import { startMcpHttpServer } from './mcpHttp.js';
 import type { EventStore, IStore } from './store/types.js';
@@ -60,6 +62,12 @@ export interface DaemonOptions {
      * flows through here. Mutually exclusive with `authorize`.
      */
     token?: string;
+    /**
+     * Browser-consent policy for control commands (4.0 · P2). Omit to track the
+     * auth boundary automatically: `session` when auth is on (exposed daemon),
+     * `off` on loopback solo dev. Pass `{ mode }` to force a policy.
+     */
+    consent?: ConsentPolicy;
     /**
      * IStore implementation. Omit for the default JSONL store at `dataDir`.
      * Pass `null` to disable session/event persistence entirely.
@@ -150,6 +158,7 @@ export function createDaemon(opts: DaemonOptions = {}): DaemonHandle {
         dataDir: opts.dataDir,
         label: opts.label,
         auth,
+        consent: opts.consent,
     });
 
     let mcpHandle: Awaited<ReturnType<typeof startMcpHttpServer>> | undefined;

package/src/identity.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import type { IncomingMessage } from 'node:http';
+import {
+    HOST_PRINCIPAL,
+    LOCAL_PRINCIPAL,
+    identifyPrincipal,
+    resolvePrincipal,
+    tokenPrincipalId,
+} from './identity.js';
+
+function fakeReq(init: { headers?: Record<string, string>; url?: string } = {}): IncomingMessage {
+    return {
+        headers: init.headers ?? {},
+        url: init.url ?? '/',
+    } as unknown as IncomingMessage;
+}
+
+describe('identity: tokenPrincipalId', () => {
+    it('is stable + prefixed + hashed (never the raw token)', () => {
+        const id = tokenPrincipalId('super-secret');
+        expect(id).toMatch(/^token:[0-9a-f]{12}$/);
+        expect(id).toBe(tokenPrincipalId('super-secret'));
+        expect(id).not.toContain('super-secret');
+    });
+    it('different tokens → different ids', () => {
+        expect(tokenPrincipalId('a')).not.toBe(tokenPrincipalId('b'));
+    });
+});
+
+describe('identity: resolvePrincipal', () => {
+    it('loopback (auth disabled) → LOCAL_PRINCIPAL', () => {
+        expect(resolvePrincipal(fakeReq(), {})).toBe(LOCAL_PRINCIPAL);
+        expect(resolvePrincipal(fakeReq(), { token: '' })).toBe(LOCAL_PRINCIPAL);
+    });
+
+    it('token mode: matching token → token principal', () => {
+        const req = fakeReq({ headers: { authorization: 'Bearer s3cr3t' } });
+        const p = resolvePrincipal(req, { token: 's3cr3t' });
+        expect(p).toEqual({ id: tokenPrincipalId('s3cr3t'), kind: 'token' });
+    });
+
+    it('token mode: missing/wrong token → null (mirrors deny)', () => {
+        expect(resolvePrincipal(fakeReq(), { token: 's3cr3t' })).toBeNull();
+        expect(
+            resolvePrincipal(fakeReq({ headers: { authorization: 'Bearer nope' } }), { token: 's3cr3t' }),
+        ).toBeNull();
+    });
+
+    it('custom authorize: accept → HOST_PRINCIPAL, reject → null', () => {
+        expect(resolvePrincipal(fakeReq(), { authorize: () => true })).toBe(HOST_PRINCIPAL);
+        expect(resolvePrincipal(fakeReq(), { authorize: () => false })).toBeNull();
+    });
+
+    it('authorize wins over token (same precedence as isAuthorized)', () => {
+        const req = fakeReq({ headers: { authorization: 'Bearer wrong' } });
+        expect(resolvePrincipal(req, { token: 'right', authorize: () => true })).toBe(HOST_PRINCIPAL);
+    });
+});
+
+describe('identity: identifyPrincipal (P4 — identify, not authorize)', () => {
+    it('no auth → local', () => {
+        expect(identifyPrincipal({ authorization: 'Bearer x' }, {})).toBe(LOCAL_PRINCIPAL);
+    });
+
+    it('stdio (no headers) → local even when a token is configured', () => {
+        expect(identifyPrincipal(undefined, { token: 's3cr3t' })).toBe(LOCAL_PRINCIPAL);
+    });
+
+    it('token mode: names the caller from the Authorization header', () => {
+        const p = identifyPrincipal({ authorization: 'Bearer s3cr3t' }, { token: 's3cr3t' });
+        expect(p).toEqual({ id: tokenPrincipalId('s3cr3t'), kind: 'token' });
+    });
+
+    it('token mode: handles array-valued headers', () => {
+        const p = identifyPrincipal({ authorization: ['Bearer s3cr3t'] }, { token: 's3cr3t' });
+        expect(p.id).toBe(tokenPrincipalId('s3cr3t'));
+    });
+
+    it('token mode without a bearer header → local (already past auth wrapper)', () => {
+        expect(identifyPrincipal({}, { token: 's3cr3t' })).toBe(LOCAL_PRINCIPAL);
+    });
+
+    it('authorize mode → host', () => {
+        expect(identifyPrincipal({ authorization: 'Bearer x' }, { authorize: () => true })).toBe(HOST_PRINCIPAL);
+    });
+});

package/src/identity.ts

@@ -0,0 +1,116 @@
+/**
+ * Caller identity (4.0 · P1) — turns the auth boundary from a plain
+ * allow/deny into "allow/deny + *who*".
+ *
+ * Phase 1 scope: this module only *establishes* and *carries* a Principal,
+ * and the bridge *tags* writes with it (createdBy). It deliberately does NOT
+ * filter reads by owner — that's P3 (tenant isolation). Keeping the two apart
+ * means identity plumbing lands with zero behaviour change: loopback solo dev
+ * stays a single implicit `local` principal, and an authorized caller sees
+ * everything exactly as before.
+ *
+ * Why a separate module from auth.ts: `isAuthorized` answers a boolean and is
+ * consumed on the hot path of every HTTP route / WS upgrade. `resolvePrincipal`
+ * is the richer, additive view layered on top — it reuses the same primitives
+ * (isAuthEnabled / extractToken / verifyToken) so the two can never disagree on
+ * who is allowed in.
+ */
+
+import { createHash } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+
+import { extractToken, isAuthEnabled, verifyToken, type AuthOptions } from './auth.js';
+
+export type PrincipalKind = 'local' | 'token' | 'host';
+
+export interface Principal {
+    /** Stable id for this caller. Loopback / stdio solo dev → `local`. */
+    id: string;
+    /** How the identity was established. */
+    kind: PrincipalKind;
+    /** Optional human-readable label (for dashboards / audit). */
+    displayName?: string;
+}
+
+/**
+ * The implicit single principal for loopback and stdio solo dev. The daemon
+ * trusts everything that can reach the loopback socket, so there is one
+ * caller and it owns everything — exactly today's behaviour, now named.
+ */
+export const LOCAL_PRINCIPAL: Principal = Object.freeze({
+    id: 'local',
+    kind: 'local',
+    displayName: 'local',
+});
+
+/**
+ * Principal for the custom-`authorize` path. Hosts that embed the daemon own
+ * their own user model; until `authorize` can return a richer identity
+ * (future work), an authorized host caller maps to this single principal.
+ */
+export const HOST_PRINCIPAL: Principal = Object.freeze({
+    id: 'host',
+    kind: 'host',
+    displayName: 'host',
+});
+
+/**
+ * Derive a stable principal id from a bearer token. One token = one principal
+ * in 4.0's trusted-team model. We hash so the raw secret never becomes an id
+ * that could leak into stored `createdBy` tags or audit logs.
+ */
+export function tokenPrincipalId(token: string): string {
+    return `token:${createHash('sha256').update(token).digest('hex').slice(0, 12)}`;
+}
+
+/**
+ * Resolve the caller behind a request.
+ *
+ * Returns `null` when auth is enabled and the request is NOT authorized — this
+ * mirrors `isAuthorized(req) === false` exactly, so callers can treat a null
+ * principal as "reject" without a second auth check.
+ *
+ * - auth disabled (loopback): {@link LOCAL_PRINCIPAL}
+ * - custom `authorize`: {@link HOST_PRINCIPAL} when it accepts, else `null`
+ * - token: a {@link tokenPrincipalId}-derived principal when it matches, else `null`
+ */
+export function resolvePrincipal(req: IncomingMessage, opts: AuthOptions): Principal | null {
+    if (!isAuthEnabled(opts)) return LOCAL_PRINCIPAL;
+    if (opts.authorize) return opts.authorize(req) ? HOST_PRINCIPAL : null;
+    const token = extractToken(req, opts);
+    if (!verifyToken(token, opts.token!)) return null;
+    return { id: tokenPrincipalId(token!), kind: 'token' };
+}
+
+type HeaderBag = Record<string, string | string[] | undefined>;
+
+function bearerFromHeaders(headers: HeaderBag): string | undefined {
+    const raw = headers['authorization'] ?? headers['Authorization'];
+    const v = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof v === 'string' && v.startsWith('Bearer ')) {
+        const t = v.slice(7).trim();
+        if (t) return t;
+    }
+    return undefined;
+}
+
+/**
+ * Identify (not authorize) the caller behind an MCP tool call (4.0 · P4).
+ *
+ * The HTTP MCP request has already cleared the bridge's auth wrapper by the
+ * time a tool runs, so this only needs to *name* the caller — never to
+ * re-check them. Pass the per-request headers from the MCP SDK's
+ * `extra.requestInfo`; stdio calls have no requestInfo and resolve to `local`
+ * (the daemon trusts its local stdio agent).
+ *
+ * - auth disabled, or no headers (stdio) → {@link LOCAL_PRINCIPAL}
+ * - custom authorize → {@link HOST_PRINCIPAL}
+ * - token mode → token principal from the Authorization header (LOCAL if absent)
+ */
+export function identifyPrincipal(headers: HeaderBag | undefined, opts: AuthOptions): Principal {
+    if (!isAuthEnabled(opts)) return LOCAL_PRINCIPAL;
+    if (opts.authorize) return HOST_PRINCIPAL;
+    if (!headers) return LOCAL_PRINCIPAL;
+    const token = bearerFromHeaders(headers);
+    return token ? { id: tokenPrincipalId(token), kind: 'token' } : LOCAL_PRINCIPAL;
+}