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

package/dist/bridge.d.ts

@@ -12,7 +12,8 @@
  */
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type AuthOptions } from './auth.js';
-import { type EventFrame, type HttpBatch, type TabInfo, type Task, type TaskStatus } from '@harness-fe/protocol';
+import { type Principal } from './identity.js';
+import { type ConsentPolicy, type EventFrame, type HttpBatch, type TabInfo, type Task, type TaskStatus } from '@harness-fe/protocol';
 import { SessionRouter, type PeerSession } from './sessionRouter.js';
 import { type IStore, type ITaskStore, type IMemoryStore, type RetentionPolicy } from './store/index.js';
 /**
@@ -29,8 +30,8 @@ export interface IBridge {
         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.
@@ -75,6 +76,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
@@ -157,6 +165,8 @@ export declare class Bridge implements IBridge {
     private tasks;
     private opts;
     private auth;
+    /** Browser-consent policy pushed to runtime clients in hello.ack (4.0 · P2). */
+    private readonly consentPolicy;
     private publicHostOverride;
     private readonly attachDataDir;
     private autoPurgeOpts;
@@ -167,6 +177,15 @@ export declare class Bridge implements IBridge {
      * or sessionId (for runtime-client connections).
      */
     private connToStoreId;
+    /** Caller identity per connection (4.0 · P1). Resolved at WS upgrade. */
+    private connToPrincipal;
+    /**
+     * 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;
     /** Connections that already logged a "no store session" warning. */
     private warnedNoSession;
     /**
@@ -228,6 +247,8 @@ export declare class Bridge implements IBridge {
     getBoundPort(): number | undefined;
     getViewerBaseUrl(): string | undefined;
     getAuthToken(): string | undefined;
+    /** Daemon auth options — used by the MCP layer to identify the per-call principal (4.0 · P4). */
+    getAuthOptions(): AuthOptions;
     /**
      * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
      *
@@ -264,9 +285,9 @@ export declare class Bridge implements IBridge {
         status?: TaskStatus | 'all';
         limit?: number;
     }): Promise<Task[]>;
-    claimTask(id: string): Promise<Task | undefined>;
+    claimTask(id: string, principal?: Principal): Promise<Task | undefined>;
     getTaskAttachmentData(taskId: string, attachmentId: string): Promise<string | null>;
-    resolveTask(id: string, note?: string): Promise<Task | undefined>;
+    resolveTask(id: string, note?: string, principal?: Principal): Promise<Task | undefined>;
     private persistTaskEvent;
     private recordTask;
     /**

package/dist/bridge.js

@@ -14,7 +14,8 @@ import { WebSocket, WebSocketServer } from 'ws';
 import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import { networkInterfaces } from 'node:os';
-import { DEFAULT_LOGIN_PATH, handleLoginPost, isAuthorized, sendUnauthorized, } from './auth.js';
+import { DEFAULT_LOGIN_PATH, handleLoginPost, isAuthEnabled, isAuthorized, sendUnauthorized, } from './auth.js';
+import { LOCAL_PRINCIPAL, resolvePrincipal } from './identity.js';
 import { join as joinPath } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -59,6 +60,8 @@ export class Bridge {
     tasks = new Map();
     opts;
     auth;
+    /** Browser-consent policy pushed to runtime clients in hello.ack (4.0 · P2). */
+    consentPolicy;
     publicHostOverride;
     attachDataDir;
     autoPurgeOpts;
@@ -69,6 +72,15 @@ export class Bridge {
      * or sessionId (for runtime-client connections).
      */
     connToStoreId = new Map();
+    /** Caller identity per connection (4.0 · P1). Resolved at WS upgrade. */
+    connToPrincipal = new Map();
+    /**
+     * 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.
+     */
+    defaultPrincipal = LOCAL_PRINCIPAL;
     /** Connections that already logged a "no store session" warning. */
     warnedNoSession = new Set();
     /**
@@ -107,6 +119,12 @@ export class Bridge {
             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.
@@ -272,7 +290,7 @@ export class Bridge {
                 res.end('Not Found');
             });
             const wss = new WebSocketServer({ noServer: true });
-            wss.on('connection', (ws) => this.onConnection(ws));
+            wss.on('connection', (ws, req) => this.onConnection(ws, req));
             httpServer.on('upgrade', (req, socket, head) => {
                 if (!isAuthorized(req, this.auth)) {
                     // Spec-compliant 401 on the upgrade reply so client sees a
@@ -379,6 +397,10 @@ export class Bridge {
     getAuthToken() {
         return this.auth.token;
     }
+    /** Daemon auth options — used by the MCP layer to identify the per-call principal (4.0 · P4). */
+    getAuthOptions() {
+        return this.auth;
+    }
     /**
      * Broadcast a `dashboard.update` frame to every subscribed dashboard SPA.
      *
@@ -539,12 +561,16 @@ export class Bridge {
         filtered.sort((a, b) => b.createdAt - a.createdAt);
         return filtered.slice(0, limit);
     }
-    async claimTask(id) {
+    async claimTask(id, principal) {
         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');
@@ -556,7 +582,7 @@ export class Bridge {
             return null;
         return this.readTaskAttachment(task.projectId, taskId, attachmentId);
     }
-    async resolveTask(id, note) {
+    async resolveTask(id, note, principal) {
         const task = this.tasks.get(id);
         if (!task)
             return undefined;
@@ -564,6 +590,8 @@ export class Bridge {
         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');
@@ -818,9 +846,13 @@ export class Bridge {
         }
         return false;
     }
-    onConnection(ws) {
+    onConnection(ws, req) {
         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;
             try {
@@ -880,6 +912,7 @@ export class Bridge {
                 }
             }
             this.router.unregister(connectionId);
+            this.connToPrincipal.delete(connectionId);
         });
         ws.on('error', () => {
             /* swallow; close will follow */
@@ -924,6 +957,7 @@ export class Bridge {
                 // production / staging deployment where the bundler plugin is
                 // 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,
@@ -933,6 +967,7 @@ export class Bridge {
                     userId: frame.userId,
                     connectionId,
                     page: frame.page,
+                    principal,
                 });
                 // Persist to store
                 if (this.store) {
@@ -944,6 +979,7 @@ export class Bridge {
                             this.store.upsertProject(frame.projectId, {
                                 parentProjectId: frame.parentProjectId,
                                 displayName: frame.displayName,
+                                createdBy: principal.id,
                             });
                         }
                         catch (err) {
@@ -1018,6 +1054,7 @@ export class Bridge {
                             referrer: undefined,
                             userAgent: frame.page?.userAgent,
                             participants,
+                            createdBy: principal.id,
                         });
                         this.connToStoreId.set(connectionId, sessionId);
                         this.notifyDashboard({
@@ -1060,6 +1097,7 @@ export class Bridge {
                     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/dist/daemon.d.ts

@@ -23,6 +23,7 @@
  * not pushed into the factory.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConsentPolicy } from '@harness-fe/protocol';
 import { Bridge } from './bridge.js';
 import type { EventStore, IStore } from './store/types.js';
 import type { ITaskStore, IMemoryStore } from './store/types.js';
@@ -56,6 +57,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.

package/dist/daemon.js

@@ -45,6 +45,7 @@ export function createDaemon(opts = {}) {
         dataDir: opts.dataDir,
         label: opts.label,
         auth,
+        consent: opts.consent,
     });
     let mcpHandle;
     let started = false;

package/dist/identity.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 type { IncomingMessage } from 'node:http';
+import { 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 declare const LOCAL_PRINCIPAL: Principal;
+/**
+ * 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 declare const HOST_PRINCIPAL: Principal;
+/**
+ * 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 declare function tokenPrincipalId(token: string): string;
+/**
+ * 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 declare function resolvePrincipal(req: IncomingMessage, opts: AuthOptions): Principal | null;
+type HeaderBag = Record<string, string | string[] | 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 declare function identifyPrincipal(headers: HeaderBag | undefined, opts: AuthOptions): Principal;
+export {};

package/dist/identity.js

@@ -0,0 +1,101 @@
+/**
+ * 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 { extractToken, isAuthEnabled, verifyToken } from './auth.js';
+/**
+ * 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 = 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 = 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) {
+    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, opts) {
+    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' };
+}
+function bearerFromHeaders(headers) {
+    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, opts) {
+    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;
+}

package/dist/mcp.d.ts

@@ -7,6 +7,7 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { IBridge } from './bridge.js';
+import type { AuthOptions } from './auth.js';
 export interface McpServerOptions {
     /**
      * Name of the environment variable that gates experimental tools.
@@ -17,6 +18,12 @@ export interface McpServerOptions {
      * var is set to a non-empty value at server-construction time.
      */
     experimentalEnvVar?: string;
+    /**
+     * Daemon auth options, used to identify the per-call principal from MCP
+     * request headers (4.0 · P4). Omit for stdio / no-auth — calls resolve to
+     * the local principal.
+     */
+    auth?: AuthOptions;
 }
 /**
  * Experimental-feature gate.

package/dist/mcp.js

@@ -9,6 +9,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { COMMAND, PROTOCOL_VERSION, clickArgsSchema, evaluateArgsSchema, navigateArgsSchema, reloadArgsSchema, screenshotArgsSchema, scrollArgsSchema, setHtmlArgsSchema, setStyleArgsSchema, selectorSchema, typeArgsSchema, waitForArgsSchema, } from '@harness-fe/protocol';
+import { identifyPrincipal } from './identity.js';
 import { RemoteBridge } from './remoteBridge.js';
 import { buildVisitorTimeline } from './visitorTimeline.js';
 import { createReplayExport } from './replayCreate.js';
@@ -47,7 +48,7 @@ export function createMcpServer(bridge, options = {}) {
         name: SERVER_NAME,
         version: PROTOCOL_VERSION,
     });
-    registerTools(server, bridge);
+    registerTools(server, bridge, options.auth);
     // Experimental tools are on by default. They only get gated when the host
     // supplies an env-var name to key off; see experimentalEnabled().
     if (experimentalEnabled(options.experimentalEnvVar)) {
@@ -87,7 +88,7 @@ function err(message) {
         isError: true,
     };
 }
-function registerTools(server, bridge) {
+function registerTools(server, bridge, auth) {
     server.registerTool(COMMAND.PAGE_CLICK, {
         description: 'Click on a DOM element resolved by the selector.',
         inputSchema: {
@@ -480,8 +481,9 @@ function registerTools(server, bridge) {
         inputSchema: {
             taskId: z.string(),
         },
-    }, async ({ taskId }) => {
-        const task = await bridge.claimTask(taskId);
+    }, async ({ taskId }, extra) => {
+        const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+        const task = await bridge.claimTask(taskId, principal);
         if (!task) {
             throw new Error(`tasks.claim: no task with id "${taskId}"`);
         }
@@ -493,8 +495,9 @@ function registerTools(server, bridge) {
             taskId: z.string(),
             note: z.string().optional(),
         },
-    }, async ({ taskId, note }) => {
-        const task = await bridge.resolveTask(taskId, note);
+    }, async ({ taskId, note }, extra) => {
+        const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+        const task = await bridge.resolveTask(taskId, note, principal);
         if (!task) {
             throw new Error(`tasks.resolve: no task with id "${taskId}"`);
         }

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.0",
+  "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",
@@ -38,8 +38,8 @@
     "rrweb-player": "1.0.0-alpha.4",
     "ws": "^8.18.0",
     "zod": "^4.4.3",
-    "@harness-fe/protocol": "3.2.0",
-    "@harness-fe/dashboard-ui": "0.2.0"
+    "@harness-fe/dashboard-ui": "0.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;
+}

package/src/mcp.ts

@@ -26,6 +26,8 @@ import {
 } from '@harness-fe/protocol';
 import type { IBridge } from './bridge.js';
 import type { Bridge } from './bridge.js';
+import type { AuthOptions } from './auth.js';
+import { identifyPrincipal } from './identity.js';
 import { RemoteBridge } from './remoteBridge.js';
 import type { IStore, IMemoryStore } from './store/index.js';
 import { buildVisitorTimeline } from './visitorTimeline.js';
@@ -45,6 +47,12 @@ export interface McpServerOptions {
      * var is set to a non-empty value at server-construction time.
      */
     experimentalEnvVar?: string;
+    /**
+     * Daemon auth options, used to identify the per-call principal from MCP
+     * request headers (4.0 · P4). Omit for stdio / no-auth — calls resolve to
+     * the local principal.
+     */
+    auth?: AuthOptions;
 }
 
 /**
@@ -81,7 +89,7 @@ export function createMcpServer(bridge: IBridge, options: McpServerOptions = {})
         version: PROTOCOL_VERSION,
     });
 
-    registerTools(server, bridge);
+    registerTools(server, bridge, options.auth);
 
     // Experimental tools are on by default. They only get gated when the host
     // supplies an env-var name to key off; see experimentalEnabled().
@@ -134,7 +142,7 @@ function err(message: string): {
 }
 
 
-function registerTools(server: McpServer, bridge: IBridge): void {
+function registerTools(server: McpServer, bridge: IBridge, auth?: AuthOptions): void {
     server.registerTool(
         COMMAND.PAGE_CLICK,
         {
@@ -769,8 +777,9 @@ function registerTools(server: McpServer, bridge: IBridge): void {
                 taskId: z.string(),
             },
         },
-        async ({ taskId }) => {
-            const task = await bridge.claimTask(taskId);
+        async ({ taskId }, extra) => {
+            const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+            const task = await bridge.claimTask(taskId, principal);
             if (!task) {
                 throw new Error(`tasks.claim: no task with id "${taskId}"`);
             }
@@ -788,8 +797,9 @@ function registerTools(server: McpServer, bridge: IBridge): void {
                 note: z.string().optional(),
             },
         },
-        async ({ taskId, note }) => {
-            const task = await bridge.resolveTask(taskId, note);
+        async ({ taskId, note }, extra) => {
+            const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+            const task = await bridge.resolveTask(taskId, note, principal);
             if (!task) {
                 throw new Error(`tasks.resolve: no task with id "${taskId}"`);
             }

package/src/mcpHttp.ts

@@ -61,7 +61,13 @@ export async function startMcpHttpServer(
             ? 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 as Bridge).getAuthOptions(),
+    });
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: stateful ? () => randomUUID() : undefined,
         eventStore,

package/src/sessionRouter.ts

@@ -12,11 +12,14 @@ 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/src/store/JsonlStore.ts

@@ -483,6 +483,8 @@ export class JsonlStore implements IStore {
             ...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 = [];
@@ -650,6 +652,8 @@ export class JsonlStore implements IStore {
             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/src/store/identityTagging.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Caller-identity tagging (4.0 · P1): `createdBy` is write-once on project /
+ * session metadata — the first principal to create the record owns it, and
+ * later upserts (which never carry an identity in normal flow) must not
+ * silently re-attribute ownership.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { JsonlStore } from './JsonlStore.js';
+
+describe('store: createdBy tagging (P1)', () => {
+    let dir: string;
+    let store: JsonlStore;
+
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), 'harness-identity-test-'));
+        store = new JsonlStore(dir);
+    });
+    afterEach(() => {
+        store.close();
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+    });
+
+    it('project: records createdBy on creation', () => {
+        const p = store.upsertProject('proj-a', { createdBy: 'token:abc' });
+        expect(p.createdBy).toBe('token:abc');
+        expect(store.getProject('proj-a')?.createdBy).toBe('token:abc');
+    });
+
+    it('project: createdBy is write-once (later upsert without it is preserved)', () => {
+        store.upsertProject('proj-a', { createdBy: 'local' });
+        const after = store.upsertProject('proj-a', { displayName: 'renamed' });
+        expect(after.createdBy).toBe('local');
+        expect(after.displayName).toBe('renamed');
+    });
+
+    it('project: a later upsert cannot re-attribute ownership', () => {
+        store.upsertProject('proj-a', { createdBy: 'local' });
+        const after = store.upsertProject('proj-a', { createdBy: 'token:evil' });
+        expect(after.createdBy).toBe('local');
+    });
+
+    it('project: createdBy stays undefined when never supplied (back-compat)', () => {
+        const p = store.upsertProject('proj-legacy', { displayName: 'x' });
+        expect(p.createdBy).toBeUndefined();
+    });
+
+    it('session: records and locks createdBy', () => {
+        const sid = randomUUID();
+        store.upsertSession(sid, {
+            tabId: 'tab-1',
+            startedAt: Date.now(),
+            participants: [{ projectId: 'proj-a', joinedAt: Date.now() }],
+            createdBy: 'local',
+        });
+        store.upsertSession(sid, {
+            tabId: 'tab-1',
+            startedAt: Date.now(),
+            participants: [{ projectId: 'proj-a', joinedAt: Date.now() }],
+            createdBy: 'token:other',
+        });
+        expect(store.getSession(sid)?.createdBy).toBe('local');
+    });
+});

package/src/store/types.ts

@@ -104,6 +104,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>;
 }
 
@@ -173,6 +179,11 @@ export interface SessionMeta {
         storageKeys?: { local?: number; session?: number; cookie?: number };
         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>;
 }