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

package/src/identity.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import type { IncomingMessage } from 'node:http';
+import {
+    HOST_PRINCIPAL,
+    LOCAL_PRINCIPAL,
+    canSee,
+    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);
+    });
+});
+
+describe('identity: canSee (P3 tenant visibility)', () => {
+    const tokenA = { id: 'token:aaa', kind: 'token' as const };
+    const tokenB = { id: 'token:bbb', kind: 'token' as const };
+
+    it('local sees everything (zero behaviour change for solo dev)', () => {
+        expect(canSee(LOCAL_PRINCIPAL, 'token:aaa')).toBe(true);
+        expect(canSee(LOCAL_PRINCIPAL, undefined)).toBe(true);
+        expect(canSee(LOCAL_PRINCIPAL, null)).toBe(true);
+    });
+
+    it('unowned data (no createdBy) is visible to everyone', () => {
+        expect(canSee(tokenA, undefined)).toBe(true);
+        expect(canSee(tokenA, null)).toBe(true);
+    });
+
+    it('named principal sees only its own owned data', () => {
+        expect(canSee(tokenA, 'token:aaa')).toBe(true);
+        expect(canSee(tokenA, 'token:bbb')).toBe(false);
+        expect(canSee(tokenB, 'token:aaa')).toBe(false);
+    });
+});

package/src/identity.ts

@@ -0,0 +1,137 @@
+/**
+ * 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;
+}
+
+/**
+ * Tenant-isolation visibility check (4.0 · P3). Decides whether `principal`
+ * may see a record tagged with `createdBy`.
+ *
+ * - `local` (loopback / stdio solo / no-auth) → sees everything. This keeps
+ *   solo dev's behaviour completely unchanged.
+ * - unowned data (`createdBy` null/undefined — legacy rows from before P1, or
+ *   records the daemon never tagged) → visible to everyone (backward compat).
+ * - otherwise → visible only to the principal that created it.
+ *
+ * Note: in the current single-token / loopback reality the data creator
+ * (plugin / runtime client) and the querying agent share one principal, so
+ * this is exact. A full `project → agent` binding (creator ≠ consumer, once
+ * P6 splits write/read scopes) is deferred to P6.
+ */
+export function canSee(principal: Principal, createdBy: string | null | undefined): boolean {
+    if (principal.kind === 'local') return true;
+    if (createdBy == null) return true;
+    return createdBy === principal.id;
+}

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 { canSee, 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().
@@ -94,7 +102,7 @@ export function createMcpServer(bridge: IBridge, options: McpServerOptions = {})
     const leaderStore = (bridge as Bridge).store;
     if (leaderStore != null) {
         const memoryStore = bridge.getMemoryStore();
-        registerStoreTools(server, leaderStore, memoryStore, bridge);
+        registerStoreTools(server, leaderStore, memoryStore, bridge, options.auth);
     } else if (bridge instanceof RemoteBridge) {
         registerRemoteStoreTools(server, bridge);
     }
@@ -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,
         {
@@ -729,108 +737,106 @@ function registerTools(server: McpServer, bridge: IBridge): void {
     );
 
     // ─── tasks.* tools (user annotations submitted from page) ─────────────
-    // TODO: temporarily hidden — re-enable when the report feature is ready.
-    // To re-enable: remove the `if (false)` wrapper below and restore the block.
 
-    /* eslint-disable no-constant-condition */
-    if (false) {
-        const taskStatusEnum = z.enum(['pending', 'claimed', 'resolved', 'all']);
+    const taskStatusEnum = z.enum(['pending', 'claimed', 'resolved', 'all']);
 
-        server.registerTool(
-            COMMAND.TASKS_PENDING,
-            {
-                description:
-                    'List user-submitted annotation tasks. Default `status="pending"`. Returns id/question/selector/url — call tasks.claim to fetch full element payload.',
-                inputSchema: {
-                    status: taskStatusEnum.optional(),
-                    limit: z.number().int().positive().optional(),
-                },
-            },
-            async ({ status, limit }) => {
-                const tasks = await bridge.listTasks({ status: status ?? 'pending', limit });
-                const summary = tasks.map((t) => ({
-                    id: t.id,
-                    status: t.status,
-                    question: t.question,
-                    selector: t.selector,
-                    url: t.url,
-                    tabId: t.tabId,
-                    createdAt: t.createdAt,
-                    claimedAt: t.claimedAt,
-                    resolvedAt: t.resolvedAt,
-                    note: t.note,
-                }));
-                return ok({ count: summary.length, tasks: summary });
+    server.registerTool(
+        COMMAND.TASKS_PENDING,
+        {
+            description:
+                'List user-submitted annotation tasks. Default `status="pending"`. Returns id/question/selector/url — call tasks.claim to fetch full element payload.',
+            inputSchema: {
+                status: taskStatusEnum.optional(),
+                limit: z.number().int().positive().optional(),
             },
-        );
+        },
+        async ({ status, limit }, extra) => {
+            const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+            const tasks = (await bridge.listTasks({ status: status ?? 'pending', limit }))
+                .filter((t) => canSee(principal, t.createdBy));
+            const summary = tasks.map((t) => ({
+                id: t.id,
+                status: t.status,
+                question: t.question,
+                selector: t.selector,
+                url: t.url,
+                tabId: t.tabId,
+                createdAt: t.createdAt,
+                claimedAt: t.claimedAt,
+                resolvedAt: t.resolvedAt,
+                note: t.note,
+            }));
+            return ok({ count: summary.length, tasks: summary });
+        },
+    );
 
-        server.registerTool(
-            COMMAND.TASKS_CLAIM,
-            {
-                description:
-                    'Claim a task by id. Marks it claimed, returns full payload (selector + element outerHTML + rect).',
-                inputSchema: {
-                    taskId: z.string(),
-                },
-            },
-            async ({ taskId }) => {
-                const task = await bridge.claimTask(taskId);
-                if (!task) {
-                    throw new Error(`tasks.claim: no task with id "${taskId}"`);
-                }
-                return ok(task);
+    server.registerTool(
+        COMMAND.TASKS_CLAIM,
+        {
+            description:
+                'Claim a task by id. Marks it claimed, returns full payload (selector + element outerHTML + rect).',
+            inputSchema: {
+                taskId: z.string(),
             },
-        );
+        },
+        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}"`);
+            }
+            return ok(task);
+        },
+    );
 
-        server.registerTool(
-            COMMAND.TASKS_RESOLVE,
-            {
-                description:
-                    'Mark a task as resolved with an optional note. Use after addressing the user request.',
-                inputSchema: {
-                    taskId: z.string(),
-                    note: z.string().optional(),
-                },
-            },
-            async ({ taskId, note }) => {
-                const task = await bridge.resolveTask(taskId, note);
-                if (!task) {
-                    throw new Error(`tasks.resolve: no task with id "${taskId}"`);
-                }
-                return ok({ ok: true, task });
+    server.registerTool(
+        COMMAND.TASKS_RESOLVE,
+        {
+            description:
+                'Mark a task as resolved with an optional note. Use after addressing the user request.',
+            inputSchema: {
+                taskId: z.string(),
+                note: z.string().optional(),
             },
-        );
+        },
+        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}"`);
+            }
+            return ok({ ok: true, task });
+        },
+    );
 
-        server.registerTool(
-            'tasks.get_attachment',
-            {
-                description:
-                    'Return a task screenshot attachment as a vision-ready image block. ' +
-                    'Call after tasks.claim when the task summary includes an attachment pointer. ' +
-                    'Compatible with Claude vision and GPT-4V.',
-                inputSchema: {
-                    taskId: z.string().describe('Task id (from tasks.pending or tasks.claim).'),
-                    attachmentId: z.string().describe('Attachment id (from task.attachments[].id).'),
-                },
-            },
-            async ({ taskId, attachmentId }) => {
-                const base64 = await bridge.getTaskAttachmentData(taskId, attachmentId);
-                if (!base64) {
-                    throw new Error(`tasks.get_attachment: attachment not found (taskId=${taskId}, attachmentId=${attachmentId})`);
-                }
-                return {
-                    content: [
-                        {
-                            type: 'image' as const,
-                            mimeType: 'image/png' as const,
-                            data: base64,
-                        },
-                    ],
-                };
+    server.registerTool(
+        'tasks.get_attachment',
+        {
+            description:
+                'Return a task screenshot attachment as a vision-ready image block. ' +
+                'Call after tasks.claim when the task summary includes an attachment pointer. ' +
+                'Compatible with Claude vision and GPT-4V.',
+            inputSchema: {
+                taskId: z.string().describe('Task id (from tasks.pending or tasks.claim).'),
+                attachmentId: z.string().describe('Attachment id (from task.attachments[].id).'),
             },
-        );
-    }
-    /* eslint-enable no-constant-condition */
+        },
+        async ({ taskId, attachmentId }) => {
+            const base64 = await bridge.getTaskAttachmentData(taskId, attachmentId);
+            if (!base64) {
+                throw new Error(`tasks.get_attachment: attachment not found (taskId=${taskId}, attachmentId=${attachmentId})`);
+            }
+            return {
+                content: [
+                    {
+                        type: 'image' as const,
+                        mimeType: 'image/png' as const,
+                        data: base64,
+                    },
+                ],
+            };
+        },
+    );
 }
 
 // ─── Experimental tools (gated by HARNESS_FE_EXPERIMENTAL) ────────────────────
@@ -861,7 +867,7 @@ function registerExperimentalTools(server: McpServer, bridge: IBridge): void {
 
 // ─── Store tools (session history, timeline, memory) ──────────────────────────
 
-function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemoryStore, bridge: IBridge): void {
+function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemoryStore, bridge: IBridge, auth?: AuthOptions): void {
     server.registerTool(
         'session.list',
         {
@@ -871,8 +877,11 @@ function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemo
                 limit: z.number().int().positive().default(10).optional(),
             },
         },
-        async ({ projectId, limit }) => {
-            const sessions = store.listSessions({ projectId, limit: limit ?? 10 });
+        async ({ projectId, limit }, extra) => {
+            const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+            const sessions = store
+                .listSessions({ projectId, limit: limit ?? 10 })
+                .filter((s) => canSee(principal, s.createdBy));
             return ok(sessions);
         },
     );
@@ -959,11 +968,14 @@ function registerStoreTools(server: McpServer, store: IStore, memoryStore: IMemo
             description: 'List all projects with their most recent session info.',
             inputSchema: {},
         },
-        async () => {
-            const projects = store.listProjects();
+        async (_args, extra) => {
+            const principal = identifyPrincipal(extra.requestInfo?.headers, auth ?? {});
+            const projects = store.listProjects().filter((p) => canSee(principal, p.createdBy));
             const result = projects.map((p) => ({
                 ...p,
-                recentSessions: store.listSessions({ projectId: p.id, limit: 3 }),
+                recentSessions: store
+                    .listSessions({ projectId: p.id, limit: 3 })
+                    .filter((s) => canSee(principal, s.createdBy)),
             }));
             return ok(result);
         },

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>;
 }