@agent-native/creative-context 0.0.0-beta-20260820202238

package/src/server/generation-artifact-access.ts

@@ -0,0 +1,217 @@
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+
+export interface GenerationArtifactIdentity {
+  appId: string;
+  artifactType: string;
+  artifactId: string;
+}
+
+export interface GenerationArtifactAccessTarget {
+  resourceType: string;
+  resourceId: string;
+}
+
+const proofBrand = Symbol("creative-context-generation-artifact-access");
+
+export interface GenerationArtifactAccessProof {
+  readonly identityKey: string;
+  readonly minRole: "viewer" | "editor";
+  readonly [proofBrand]: true;
+}
+
+interface CapabilityClaims {
+  version: 1;
+  operation: "read" | "record";
+  identityKey: string;
+  minRole: "viewer" | "editor";
+  resourceType: string;
+  resourceId: string;
+  userEmail: string;
+  orgId: string | null;
+  expiresAt: number;
+}
+
+const CAPABILITY_LIFETIME_MS = 60_000;
+
+export async function assertGenerationArtifactAccess(
+  identity: GenerationArtifactIdentity,
+  target: GenerationArtifactAccessTarget,
+  minRole: "viewer" | "editor",
+): Promise<GenerationArtifactAccessProof> {
+  await assertAccess(
+    target.resourceType,
+    target.resourceId,
+    minRole,
+    undefined,
+    {
+      skipResourceBody: true,
+    },
+  );
+  return createProof(identity, minRole);
+}
+
+export function assertGenerationArtifactAccessProof(
+  identity: GenerationArtifactIdentity,
+  proof: GenerationArtifactAccessProof,
+  minRole: "viewer" | "editor",
+): void {
+  if (
+    proof?.[proofBrand] !== true ||
+    proof.identityKey !== generationIdentityKey(identity) ||
+    (minRole === "editor" && proof.minRole !== "editor")
+  ) {
+    throw new Error(
+      "Generation artifact access must be verified by the host application",
+    );
+  }
+}
+
+export async function createGenerationArtifactAccessCapability(
+  identity: GenerationArtifactIdentity,
+  target: GenerationArtifactAccessTarget,
+  operation: "read" | "record",
+): Promise<string> {
+  const minRole = operation === "record" ? "editor" : "viewer";
+  await assertGenerationArtifactAccess(identity, target, minRole);
+  const actor = requireCapabilityActor();
+  const claims: CapabilityClaims = {
+    version: 1,
+    operation,
+    identityKey: generationIdentityKey(identity),
+    minRole,
+    resourceType: target.resourceType,
+    resourceId: target.resourceId,
+    userEmail: actor.userEmail,
+    orgId: actor.orgId,
+    expiresAt: Date.now() + CAPABILITY_LIFETIME_MS,
+  };
+  const encoded = Buffer.from(JSON.stringify(claims), "utf8").toString(
+    "base64url",
+  );
+  const signature = await signCapability(encoded);
+  return `${encoded}.${signature}`;
+}
+
+export async function verifyGenerationArtifactAccessCapability(
+  token: string,
+  identity: GenerationArtifactIdentity,
+  operation: "read" | "record",
+): Promise<GenerationArtifactAccessProof> {
+  const [encoded, signature, extra] = token.split(".");
+  if (!encoded || !signature || extra) {
+    throw new Error("Invalid generation artifact access capability");
+  }
+  const valid = await verifyCapabilitySignature(encoded, signature);
+  if (!valid) throw new Error("Invalid generation artifact access capability");
+
+  let claims: CapabilityClaims;
+  try {
+    claims = JSON.parse(
+      Buffer.from(encoded, "base64url").toString("utf8"),
+    ) as CapabilityClaims;
+  } catch {
+    throw new Error("Invalid generation artifact access capability");
+  }
+  const actor = requireCapabilityActor();
+  const expectedRole = operation === "record" ? "editor" : "viewer";
+  if (
+    claims.version !== 1 ||
+    claims.operation !== operation ||
+    claims.identityKey !== generationIdentityKey(identity) ||
+    claims.minRole !== expectedRole ||
+    claims.userEmail !== actor.userEmail ||
+    claims.orgId !== actor.orgId ||
+    !Number.isSafeInteger(claims.expiresAt) ||
+    claims.expiresAt < Date.now() ||
+    claims.expiresAt > Date.now() + CAPABILITY_LIFETIME_MS
+  ) {
+    throw new Error("Invalid generation artifact access capability");
+  }
+  return createProof(identity, expectedRole);
+}
+
+function createProof(
+  identity: GenerationArtifactIdentity,
+  minRole: "viewer" | "editor",
+): GenerationArtifactAccessProof {
+  return Object.freeze({
+    identityKey: generationIdentityKey(identity),
+    minRole,
+    [proofBrand]: true as const,
+  });
+}
+
+function generationIdentityKey(identity: GenerationArtifactIdentity): string {
+  return JSON.stringify([
+    identity.appId,
+    identity.artifactType,
+    identity.artifactId,
+  ]);
+}
+
+function requireCapabilityActor(): {
+  userEmail: string;
+  orgId: string | null;
+} {
+  const userEmail = getRequestUserEmail()?.trim().toLowerCase();
+  if (!userEmail) throw new Error("Not authenticated");
+  return { userEmail, orgId: getRequestOrgId() ?? null };
+}
+
+function capabilitySecret(): string {
+  const secret =
+    process.env.CREATIVE_CONTEXT_A2A_KEY?.trim() ||
+    process.env.A2A_SECRET?.trim();
+  if (!secret) {
+    throw new Error(
+      "Generation artifact access capabilities require CREATIVE_CONTEXT_A2A_KEY or A2A_SECRET",
+    );
+  }
+  return secret;
+}
+
+async function signCapability(encoded: string): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(capabilitySecret()),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(encoded),
+  );
+  return Buffer.from(signature).toString("base64url");
+}
+
+async function verifyCapabilitySignature(
+  encoded: string,
+  signature: string,
+): Promise<boolean> {
+  let bytes: Uint8Array;
+  try {
+    bytes = Buffer.from(signature, "base64url");
+    if (Buffer.from(bytes).toString("base64url") !== signature) return false;
+  } catch {
+    return false;
+  }
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(capabilitySecret()),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+  return crypto.subtle.verify(
+    "HMAC",
+    key,
+    bytes as unknown as BufferSource,
+    new TextEncoder().encode(encoded),
+  );
+}

package/src/server/generation-context-a2a.spec.ts

@@ -0,0 +1,282 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  readAppState: vi.fn(),
+  getContextPack: vi.fn(),
+  getCreativeContextItem: vi.fn(),
+  listAccessibleSearchDocuments: vi.fn(),
+  listCreativeContexts: vi.fn(),
+  getCreativeContextById: vi.fn(),
+  getCreativeContextAppBinding: vi.fn(),
+  createContextPack: vi.fn(),
+  performCreativeContextSearch: vi.fn(),
+  recordLocal: vi.fn(),
+  getLocal: vi.fn(),
+  hasA2A: vi.fn(),
+  callA2A: vi.fn(),
+  getRequestOrgId: vi.fn(),
+  createArtifactCapability: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/application-state", () => ({
+  readAppState: mocks.readAppState,
+}));
+
+vi.mock("@agent-native/core/server/request-context", () => ({
+  getRequestOrgId: mocks.getRequestOrgId,
+}));
+
+vi.mock("../store/index.js", () => ({
+  getContextPack: mocks.getContextPack,
+  getCreativeContextItem: mocks.getCreativeContextItem,
+  listAccessibleSearchDocuments: mocks.listAccessibleSearchDocuments,
+  listCreativeContexts: mocks.listCreativeContexts,
+  getCreativeContextById: mocks.getCreativeContextById,
+  getCreativeContextAppBinding: mocks.getCreativeContextAppBinding,
+  createContextPack: mocks.createContextPack,
+}));
+
+vi.mock("../store/generation.js", () => ({
+  recordGenerationCreativeContext: mocks.recordLocal,
+  getGenerationCreativeContext: mocks.getLocal,
+}));
+
+vi.mock("./retrieval.js", () => ({
+  performCreativeContextSearch: mocks.performCreativeContextSearch,
+}));
+
+vi.mock("./isolated-a2a.js", () => ({
+  callIsolatedCreativeContextA2A: mocks.callA2A,
+  hasIsolatedCreativeContextA2A: mocks.hasA2A,
+  isolatedResolvePayload: vi.fn((input) => ({
+    query: input.query,
+    role: input.role,
+    limit: input.limit,
+    contextPackId: input.contextPackId,
+    contextPackSource: input.contextPackSource,
+    ...(input.selectedContextId
+      ? { selectedContextId: input.selectedContextId }
+      : {}),
+  })),
+}));
+
+vi.mock("./generation-artifact-access.js", () => ({
+  assertGenerationArtifactAccess: vi.fn(),
+  createGenerationArtifactAccessCapability: mocks.createArtifactCapability,
+}));
+
+import {
+  getGenerationCreativeContext,
+  recordGenerationCreativeContext,
+  resolveGenerationCreativeContext,
+  validateGenerationCreativeContext,
+} from "./generation-context.js";
+
+const emptyRemoteContext = {
+  contextMode: "auto" as const,
+  contextPackId: null,
+  reuseLabels: [],
+  results: [],
+};
+
+describe("generation context isolated A2A routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.readAppState.mockResolvedValue({ contextMode: "auto" });
+    mocks.hasA2A.mockReturnValue(true);
+    mocks.getRequestOrgId.mockReturnValue("org-1");
+    mocks.createArtifactCapability.mockImplementation(
+      async (_identity, _target, operation) => `cap-${operation}`,
+    );
+    mocks.callA2A.mockResolvedValue(emptyRemoteContext);
+    mocks.listCreativeContexts.mockResolvedValue({ contexts: [] });
+    mocks.getCreativeContextById.mockResolvedValue(null);
+    mocks.getCreativeContextAppBinding.mockResolvedValue(null);
+  });
+
+  it("routes bounded resolve, validate, read, and record operations remotely", async () => {
+    await resolveGenerationCreativeContext({
+      role: "slides",
+      query: "launch deck",
+    });
+    await validateGenerationCreativeContext({ reuseLabels: [] });
+    await getGenerationCreativeContext({
+      appId: "slides",
+      artifactType: "deck",
+      artifactId: "deck-1",
+    });
+    await recordGenerationCreativeContext({
+      appId: "slides",
+      artifactType: "deck",
+      artifactId: "deck-1",
+      contextMode: "auto",
+      contextPackId: null,
+      reuseLabels: [],
+    });
+
+    expect(mocks.callA2A).toHaveBeenNthCalledWith(1, "resolve", {
+      role: "slides",
+      query: "launch deck",
+      limit: undefined,
+      contextPackId: undefined,
+      contextPackSource: undefined,
+    });
+    expect(mocks.callA2A).toHaveBeenNthCalledWith(2, "validate", {
+      contextPackId: undefined,
+      contextPackSource: undefined,
+      reuseLabels: [],
+      reuseLabelsSource: undefined,
+    });
+    expect(mocks.callA2A).toHaveBeenNthCalledWith(3, "read", {
+      identity: {
+        appId: "slides",
+        artifactType: "deck",
+        artifactId: "deck-1",
+      },
+      artifactAccessCapability: "cap-read",
+    });
+    expect(mocks.callA2A).toHaveBeenNthCalledWith(
+      4,
+      "record",
+      expect.objectContaining({
+        artifactId: "deck-1",
+        artifactAccessCapability: "cap-record",
+      }),
+    );
+    expect(mocks.recordLocal).not.toHaveBeenCalled();
+    expect(mocks.getLocal).not.toHaveBeenCalled();
+  });
+
+  it("keeps the in-process path as the zero-configuration default", async () => {
+    mocks.hasA2A.mockReturnValue(false);
+    mocks.performCreativeContextSearch.mockResolvedValue({
+      contextPackId: null,
+      results: [],
+    });
+
+    await expect(
+      resolveGenerationCreativeContext({ role: "content", query: "brief" }),
+    ).resolves.toEqual(emptyRemoteContext);
+    expect(mocks.performCreativeContextSearch).toHaveBeenCalled();
+    expect(mocks.callA2A).not.toHaveBeenCalled();
+  });
+
+  it("fuses Default with the selected specialty and snapshots the provenance", async () => {
+    mocks.hasA2A.mockReturnValue(false);
+    mocks.readAppState.mockResolvedValue({
+      contextMode: "auto",
+      selectedContextId: "specialty-1",
+    });
+    mocks.listCreativeContexts.mockResolvedValue({
+      contexts: [{ id: "default-1", kind: "default" }],
+    });
+    mocks.getCreativeContextById.mockResolvedValue({
+      id: "specialty-1",
+      kind: "specialty",
+    });
+    mocks.performCreativeContextSearch
+      .mockResolvedValueOnce({
+        results: [
+          {
+            itemId: "base-item",
+            itemVersionId: "base-v1",
+            kind: "slide",
+            title: "Default evidence",
+            score: 0.5,
+            reasons: ["default"],
+          },
+        ],
+      })
+      .mockResolvedValueOnce({
+        results: [
+          {
+            itemId: "specialty-item",
+            itemVersionId: "specialty-v1",
+            kind: "slide",
+            title: "Specialty evidence",
+            score: 0.5,
+            reasons: ["specialty"],
+          },
+        ],
+      });
+    mocks.createContextPack.mockResolvedValue({ id: "snapshot-1" });
+
+    await expect(
+      resolveGenerationCreativeContext({ role: "slides", query: "launch" }),
+    ).resolves.toMatchObject({ contextPackId: "snapshot-1" });
+    expect(mocks.performCreativeContextSearch).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ contextId: "default-1", snapshot: false }),
+    );
+    expect(mocks.performCreativeContextSearch).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ contextId: "specialty-1", snapshot: false }),
+    );
+    expect(mocks.createContextPack).toHaveBeenCalledWith(
+      expect.objectContaining({
+        baseContextId: "default-1",
+        specialtyContextId: "specialty-1",
+        selectionReason: "explicit specialty selection",
+      }),
+    );
+  });
+
+  it("uses one matching specialty when no explicit or app binding exists", async () => {
+    mocks.hasA2A.mockReturnValue(false);
+    mocks.listCreativeContexts.mockResolvedValue({
+      contexts: [
+        { id: "default-1", kind: "default", name: "Default" },
+        {
+          id: "marketing-1",
+          kind: "specialty",
+          name: "Marketing",
+          description: "Campaigns, launches, and demand generation",
+        },
+        { id: "product-1", kind: "specialty", name: "Product" },
+      ],
+    });
+    mocks.performCreativeContextSearch
+      .mockResolvedValueOnce({
+        results: [
+          {
+            itemId: "base-item",
+            itemVersionId: "base-v1",
+            kind: "slide",
+            title: "Default evidence",
+            score: 0.5,
+            reasons: ["default"],
+          },
+        ],
+      })
+      .mockResolvedValueOnce({ results: [] });
+    mocks.createContextPack.mockResolvedValue({ id: "snapshot-1" });
+
+    await resolveGenerationCreativeContext({
+      role: "slides",
+      query: "Build the marketing launch deck",
+    });
+
+    expect(mocks.performCreativeContextSearch).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ contextId: "marketing-1" }),
+    );
+    expect(mocks.createContextPack).toHaveBeenCalledWith(
+      expect.objectContaining({
+        specialtyContextId: "marketing-1",
+        selectionReason: "semantic specialty match",
+      }),
+    );
+  });
+
+  it("forwards a selected specialty to isolated resolution", async () => {
+    mocks.readAppState.mockResolvedValue({
+      contextMode: "auto",
+      selectedContextId: "specialty-1",
+    });
+    await resolveGenerationCreativeContext({ role: "design", query: "hero" });
+    expect(mocks.callA2A).toHaveBeenCalledWith(
+      "resolve",
+      expect.objectContaining({ selectedContextId: "specialty-1" }),
+    );
+  });
+});

package/src/server/generation-context-off.spec.ts

@@ -0,0 +1,213 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  readAppState: vi.fn(),
+  getContextPack: vi.fn(),
+  getCreativeContextItem: vi.fn(),
+  listAccessibleSearchDocuments: vi.fn(),
+  performCreativeContextSearch: vi.fn(),
+  callIsolatedCreativeContextA2A: vi.fn(),
+}));
+
+vi.mock("@agent-native/core/application-state", () => ({
+  readAppState: mocks.readAppState,
+}));
+
+vi.mock("../store/index.js", () => ({
+  getContextPack: mocks.getContextPack,
+  getCreativeContextItem: mocks.getCreativeContextItem,
+  listAccessibleSearchDocuments: mocks.listAccessibleSearchDocuments,
+}));
+
+vi.mock("./retrieval.js", () => ({
+  performCreativeContextSearch: mocks.performCreativeContextSearch,
+}));
+
+vi.mock("./isolated-a2a.js", () => ({
+  callIsolatedCreativeContextA2A: mocks.callIsolatedCreativeContextA2A,
+  hasIsolatedCreativeContextA2A: vi.fn(() => true),
+  isolatedResolvePayload: vi.fn((input) => input),
+}));
+
+import {
+  resolveGenerationCreativeContext,
+  validateGenerationCreativeContext,
+} from "./generation-context.js";
+
+describe("creative context structural opt-out", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.readAppState.mockResolvedValue({ contextMode: "off" });
+  });
+
+  it("rejects an explicit pack before resolving any saved evidence", async () => {
+    await expect(
+      resolveGenerationCreativeContext({
+        role: "slides",
+        contextPackId: "pack-1",
+      }),
+    ).rejects.toThrow(/context is off/i);
+    expect(mocks.getContextPack).not.toHaveBeenCalled();
+    expect(mocks.performCreativeContextSearch).not.toHaveBeenCalled();
+    expect(mocks.callIsolatedCreativeContextA2A).not.toHaveBeenCalled();
+  });
+
+  it("rejects an explicit pack before validating final-write provenance", async () => {
+    await expect(
+      validateGenerationCreativeContext({
+        contextPackId: "pack-1",
+        reuseLabels: [],
+      }),
+    ).rejects.toThrow(/context is off/i);
+    expect(mocks.getContextPack).not.toHaveBeenCalled();
+  });
+
+  it("returns no context and permits only generated labels when off", async () => {
+    await expect(
+      resolveGenerationCreativeContext({ role: "design", query: "dashboard" }),
+    ).resolves.toMatchObject({
+      contextMode: "off",
+      contextPackId: null,
+      reuseLabels: [],
+      results: [],
+    });
+    await expect(
+      validateGenerationCreativeContext({
+        reuseLabels: [
+          {
+            kind: "screen",
+            label: "Net-new screen",
+            dataRole: "untrusted-reference",
+            elementId: "screen-1",
+            influence: "generated",
+          },
+        ],
+      }),
+    ).resolves.toMatchObject({
+      contextMode: "off",
+      contextPackId: null,
+      reuseLabels: [{ elementId: "screen-1", influence: "generated" }],
+    });
+  });
+
+  it("applies a one-generation off override without reading or mutating saved preference", async () => {
+    mocks.readAppState.mockResolvedValue({
+      contextMode: "auto",
+      pinnedPackId: "pack-saved",
+    });
+    await expect(
+      resolveGenerationCreativeContext({
+        role: "assets",
+        query: "campaign",
+        contextModeOverride: "off",
+      }),
+    ).resolves.toEqual({
+      contextMode: "off",
+      contextPackId: null,
+      reuseLabels: [],
+      results: [],
+    });
+    await expect(
+      validateGenerationCreativeContext({
+        contextModeOverride: "off",
+        reuseLabels: [
+          {
+            kind: "image",
+            label: "Net-new image",
+            dataRole: "untrusted-reference",
+            influence: "generated",
+          },
+        ],
+      }),
+    ).resolves.toMatchObject({ contextMode: "off", contextPackId: null });
+    expect(mocks.readAppState).not.toHaveBeenCalled();
+    expect(mocks.getContextPack).not.toHaveBeenCalled();
+    expect(mocks.performCreativeContextSearch).not.toHaveBeenCalled();
+    expect(mocks.callIsolatedCreativeContextA2A).not.toHaveBeenCalled();
+  });
+
+  it("rejects a pack combined with a one-generation off override", async () => {
+    await expect(
+      resolveGenerationCreativeContext({
+        role: "content",
+        contextPackId: "pack-1",
+        contextModeOverride: "off",
+      }),
+    ).rejects.toThrow(/off for this generation/i);
+    await expect(
+      validateGenerationCreativeContext({
+        contextPackId: "pack-1",
+        contextModeOverride: "off",
+      }),
+    ).rejects.toThrow(/off for this generation/i);
+    expect(mocks.readAppState).not.toHaveBeenCalled();
+  });
+
+  it("ignores inherited packs when saved or per-request mode is off", async () => {
+    await expect(
+      resolveGenerationCreativeContext({
+        role: "slides",
+        contextPackId: "pack-inherited",
+        contextPackSource: "inherited",
+      }),
+    ).resolves.toMatchObject({ contextMode: "off", contextPackId: null });
+    await expect(
+      validateGenerationCreativeContext({
+        contextPackId: "pack-inherited",
+        contextPackSource: "inherited",
+        contextModeOverride: "off",
+        reuseLabels: [
+          {
+            kind: "slide",
+            label: "Fresh edit",
+            dataRole: "untrusted-reference",
+            influence: "generated",
+          },
+        ],
+      }),
+    ).resolves.toMatchObject({
+      contextMode: "off",
+      contextPackId: null,
+      reuseLabels: [{ influence: "generated" }],
+    });
+    expect(mocks.getContextPack).not.toHaveBeenCalled();
+  });
+
+  it("rejects explicit evidence labels and strips inherited evidence when off", async () => {
+    const evidence = {
+      itemId: "item-1",
+      itemVersionId: "version-1",
+      kind: "slide",
+      label: "Imported slide",
+      dataRole: "untrusted-reference" as const,
+      influence: "adapted" as const,
+    };
+    await expect(
+      validateGenerationCreativeContext({
+        contextModeOverride: "off",
+        reuseLabels: [evidence],
+        reuseLabelsSource: "explicit",
+      }),
+    ).rejects.toThrow(/only generated/i);
+    await expect(
+      validateGenerationCreativeContext({
+        contextModeOverride: "off",
+        reuseLabels: [
+          evidence,
+          {
+            kind: "slide",
+            label: "Fresh slide",
+            dataRole: "untrusted-reference",
+            influence: "generated",
+          },
+        ],
+        reuseLabelsSource: "inherited",
+      }),
+    ).resolves.toMatchObject({
+      contextMode: "off",
+      contextPackId: null,
+      reuseLabels: [{ label: "Fresh slide", influence: "generated" }],
+    });
+    expect(mocks.getContextPack).not.toHaveBeenCalled();
+  });
+});