@agent-native/creative-context 0.1.0

package/src/server/brand-context.ts

@@ -0,0 +1,160 @@
+const HEX_COLOR = /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/i;
+const SAFE_TOKEN = /^[\p{L}\p{N}][\p{L}\p{N} ._+\-/]{0,79}$/u;
+const VOICE_DESCRIPTORS = new Set([
+  "bold",
+  "casual",
+  "concise",
+  "direct",
+  "formal",
+  "optimistic",
+  "playful",
+  "restrained",
+  "technical",
+  "warm",
+]);
+
+export interface PublishedBrandContextInput {
+  profileId: string;
+  dnaVersionId: string;
+  colors?: unknown;
+  fonts?: unknown;
+  numericScales?: unknown;
+  voiceDescriptors?: unknown;
+  layoutPatterns?: unknown;
+  logos?: unknown;
+  terminology?: unknown;
+  exclusions?: unknown;
+  inventory?: unknown;
+}
+
+function safeToken(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim().replace(/\s+/g, " ");
+  return SAFE_TOKEN.test(normalized) ? normalized : null;
+}
+
+function stringArray(value: unknown, limit = 30): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map(safeToken)
+    .filter((entry): entry is string => Boolean(entry))
+    .slice(0, limit);
+}
+
+function structuredColors(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const value = entry.toUpperCase();
+        return HEX_COLOR.test(value) ? { value } : null;
+      }
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const value =
+        typeof record.value === "string" ? record.value.toUpperCase() : "";
+      if (!HEX_COLOR.test(value)) return null;
+      return {
+        ...(safeToken(record.name) ? { name: safeToken(record.name) } : {}),
+        ...(safeToken(record.role) ? { role: safeToken(record.role) } : {}),
+        value,
+      };
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .slice(0, 40);
+}
+
+function structuredFonts(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        const family = safeToken(entry);
+        return family ? { family } : null;
+      }
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const family = safeToken(record.family);
+      if (!family) return null;
+      const weight = Number(record.weight);
+      return {
+        family,
+        ...(safeToken(record.role) ? { role: safeToken(record.role) } : {}),
+        ...(Number.isInteger(weight) && weight >= 100 && weight <= 1000
+          ? { weight }
+          : {}),
+      };
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .slice(0, 20);
+}
+
+function numericScales(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result: Record<string, number[]> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    const name = safeToken(key);
+    if (!name || !Array.isArray(raw)) continue;
+    const values = raw
+      .map(Number)
+      .filter((entry) => Number.isFinite(entry) && entry >= 0 && entry <= 10000)
+      .slice(0, 20);
+    if (values.length) result[name] = values;
+  }
+  return result;
+}
+
+function structuredTerminology(value: unknown) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((entry) => {
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const use = safeToken(record.use);
+      if (!use) return null;
+      const avoid = safeToken(record.avoid);
+      return { use, ...(avoid ? { avoid } : {}) };
+    })
+    .filter((entry): entry is NonNullable<typeof entry> => Boolean(entry))
+    .slice(0, 40);
+}
+
+function structuredInventory(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const result: Record<string, number> = {};
+  for (const [key, raw] of Object.entries(value as Record<string, unknown>)) {
+    const name = safeToken(key);
+    const count = Number(raw);
+    if (name && Number.isInteger(count) && count >= 0 && count <= 10_000_000) {
+      result[name] = count;
+    }
+  }
+  return result;
+}
+
+export function compilePublishedBrandContext(
+  input: PublishedBrandContextInput,
+): string {
+  const voiceDescriptors = stringArray(input.voiceDescriptors).filter((value) =>
+    VOICE_DESCRIPTORS.has(value.toLowerCase()),
+  );
+  const data = {
+    profileId: safeToken(input.profileId) ?? "published-profile",
+    dnaVersionId: safeToken(input.dnaVersionId) ?? "published-version",
+    colors: structuredColors(input.colors),
+    fonts: structuredFonts(input.fonts),
+    numericScales: numericScales(input.numericScales),
+    voiceDescriptors,
+    layoutPatterns: stringArray(input.layoutPatterns),
+    logos: stringArray(input.logos),
+    terminology: structuredTerminology(input.terminology),
+    exclusions: stringArray(input.exclusions),
+    inventory: structuredInventory(input.inventory),
+  };
+  return [
+    `<brand-context profile-id=${JSON.stringify(data.profileId)} dna-version-id=${JSON.stringify(data.dnaVersionId)}>`,
+    JSON.stringify(data),
+    "Use approved company examples before generating new creative work. Search creative context for 2-5 task-relevant examples, keep style/layout examples separate from factual evidence, and preserve the resulting context pack as provenance.",
+    "</brand-context>",
+  ].join("\n");
+}

package/src/server/context.ts

@@ -0,0 +1,162 @@
+import { createGetDb, getDbExec, isPostgres } from "@agent-native/core/db";
+
+import {
+  createDefaultContextConnectorExecutionContext,
+  createDefaultContextImportConnectorRegistry,
+} from "../connectors/index.js";
+import type { ContextImportConnectorRegistry } from "../connectors/registry.js";
+import type { ContextConnectorExecutionContext } from "../connectors/types.js";
+import * as defaultSchema from "../schema/index.js";
+import type { PgVectorAdapter } from "../types.js";
+import type {
+  CreativeContextElementProvenance,
+  ContextMedia,
+} from "../types.js";
+import {
+  deletePgVectors,
+  queryPgVectorIndex,
+  upsertPgVector,
+} from "../vector/pgvector.js";
+
+export type CreativeContextSchema = typeof defaultSchema;
+export type CreativeContextGetDb = () => any;
+
+export interface CreativeContextServerContext {
+  getDb: CreativeContextGetDb;
+  schema: CreativeContextSchema;
+  vectorAdapter?: PgVectorAdapter;
+  connectors: ContextImportConnectorRegistry;
+  connectorContext: ContextConnectorExecutionContext;
+  projections?: CreativeContextProjectionAdapters;
+  enrichment?: CreativeContextEnrichmentAdapters;
+}
+
+export interface CreativeContextProjectionAdapters {
+  canonicalLogo?: {
+    apply(input: {
+      profileId: string | null;
+      itemId: string;
+      itemVersionId: string;
+      payload: Record<string, unknown>;
+    }): Promise<void>;
+  };
+  layoutTemplate?: {
+    promote(input: {
+      suggestionId: string;
+      itemId: string;
+      itemVersionId: string;
+      projectionItemId: string;
+      htmlSnapshot: string | null;
+    }): Promise<void>;
+    demote(input: {
+      suggestionId: string;
+      projectionItemId: string | null;
+    }): Promise<void>;
+  };
+  generation?: {
+    record(input: {
+      appId: string;
+      artifactType: string;
+      artifactId: string;
+      contextPackId: string | null;
+      elementProvenance: readonly CreativeContextElementProvenance[];
+    }): Promise<void>;
+  };
+  media?: {
+    project(input: {
+      sourceId: string;
+      itemId: string;
+      itemVersionId: string;
+      media: ContextMedia;
+      sourceType: "brand-import";
+      dedupeKey: string;
+    }): Promise<void>;
+  };
+}
+
+export interface CreativeContextEnrichmentAdapters {
+  captionImage?(input: {
+    data: Uint8Array;
+    mimeType: string;
+    itemId: string;
+    itemVersionId: string;
+    mediaId: string;
+  }): Promise<string | null>;
+  ocrImage?(input: {
+    data: Uint8Array;
+    mimeType: string;
+    itemId: string;
+    itemVersionId: string;
+    mediaId: string;
+  }): Promise<string | null>;
+}
+
+const defaultGetDb = createGetDb(defaultSchema);
+const CONTEXT_KEY = Symbol.for("@agent-native/creative-context.context");
+
+type GlobalContext = {
+  [CONTEXT_KEY]?: CreativeContextServerContext;
+};
+
+function defaultVectorAdapter(): PgVectorAdapter | undefined {
+  if (!isPostgres()) return undefined;
+  return {
+    async upsert(input) {
+      const vectorKey = input.embeddingId;
+      await upsertPgVector(getDbExec(), {
+        vectorKey,
+        embeddingSetId: input.embeddingSetId,
+        dimensions: input.vector.length,
+        vector: input.vector,
+      });
+      return { vectorKey };
+    },
+    async search(input) {
+      const hits = await queryPgVectorIndex(getDbExec(), {
+        embeddingSetId: input.embeddingSetId,
+        dimensions: input.vector.length,
+        vector: input.vector,
+        limit: input.limit,
+        allowedVectorKeys: input.allowedVectorKeys,
+      });
+      return hits.map((hit) => ({
+        embeddingId: hit.vectorKey,
+        score: hit.score,
+      }));
+    },
+    async delete(input) {
+      await deletePgVectors(getDbExec(), {
+        dimensions: input.dimensions,
+        vectorKeys: [input.vectorKey],
+      });
+    },
+  };
+}
+
+export function configureCreativeContext(
+  context: Partial<CreativeContextServerContext> = {},
+): CreativeContextServerContext {
+  const appId = context.connectorContext?.appId ?? "creative-context";
+  const configured: CreativeContextServerContext = {
+    getDb: context.getDb ?? defaultGetDb,
+    schema: context.schema ?? defaultSchema,
+    vectorAdapter: context.vectorAdapter ?? defaultVectorAdapter(),
+    connectors:
+      context.connectors ?? createDefaultContextImportConnectorRegistry(),
+    connectorContext: {
+      ...createDefaultContextConnectorExecutionContext({ appId }),
+      ...context.connectorContext,
+      appId,
+    },
+    projections: context.projections,
+    enrichment: context.enrichment,
+  };
+  (globalThis as GlobalContext)[CONTEXT_KEY] = configured;
+  return configured;
+}
+
+export function getCreativeContext(): CreativeContextServerContext {
+  return (
+    (globalThis as GlobalContext)[CONTEXT_KEY] ?? configureCreativeContext()
+  );
+}

package/src/server/enrichment.ts

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+
+import {
+  extractDominantColors,
+  fingerprintMedia,
+} from "@agent-native/core/ingestion";
+import { eq } from "drizzle-orm";
+
+import { availableEmbeddingFamilies } from "../embeddings/providers.js";
+import {
+  getActiveEmbeddingSet,
+  getCreativeContextItem,
+  recordEmbeddingMetadata,
+} from "../store/index.js";
+import { getCreativeContext } from "./context.js";
+import { readCreativeContextMedia } from "./media.js";
+
+export async function projectCreativeContextMedia(mediaId: string) {
+  const { getDb, schema, projections } = getCreativeContext();
+  if (!projections?.media) return { mediaId, projected: false as const };
+  const rows = await getDb()
+    .select({
+      itemId: schema.contextMedia.itemId,
+      itemVersionId: schema.contextMedia.itemVersionId,
+    })
+    .from(schema.contextMedia)
+    .where(eq(schema.contextMedia.id, mediaId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) throw new Error("Creative context media was not found.");
+  const detail = await getCreativeContextItem(row.itemId, row.itemVersionId);
+  const media = detail?.media.find((entry) => entry.id === mediaId);
+  if (!detail || !media) {
+    throw new Error("Creative context media is not accessible.");
+  }
+  await projections.media.project({
+    sourceId: detail.item.sourceId,
+    itemId: detail.item.id,
+    itemVersionId: detail.version.id,
+    media,
+    sourceType: "brand-import",
+    dedupeKey: `${media.id}:${detail.version.id}`,
+  });
+  return { mediaId, projected: true as const };
+}
+
+export async function enrichCreativeContextMedia(input: {
+  mediaId: string;
+  paletteLimit?: number;
+}) {
+  const loaded = await readCreativeContextMedia({ mediaId: input.mediaId });
+  if (
+    loaded.mimeType !== "image/png" &&
+    loaded.mimeType !== "image/jpeg" &&
+    loaded.mimeType !== "image/webp" &&
+    loaded.mimeType !== "image/gif"
+  ) {
+    throw new Error(
+      "Creative context media enrichment supports PNG, JPEG, WebP, or GIF images.",
+    );
+  }
+  const { getDb, schema, vectorAdapter, enrichment } = getCreativeContext();
+  const fingerprint = fingerprintMedia(loaded.data, loaded.mimeType);
+  const palette = await extractDominantColors(
+    loaded.data,
+    input.paletteLimit ?? 6,
+  ).catch(() => []);
+  const [caption, ocrText] = await Promise.all([
+    enrichment?.captionImage?.({
+      data: loaded.data,
+      mimeType: loaded.mimeType,
+      itemId: loaded.itemId,
+      itemVersionId: loaded.itemVersionId,
+      mediaId: input.mediaId,
+    }) ?? Promise.resolve(null),
+    enrichment?.ocrImage?.({
+      data: loaded.data,
+      mimeType: loaded.mimeType,
+      itemId: loaded.itemId,
+      itemVersionId: loaded.itemVersionId,
+      mediaId: input.mediaId,
+    }) ?? Promise.resolve(null),
+  ]);
+  await getDb()
+    .update(schema.contextMedia)
+    .set({
+      palette: JSON.stringify(palette),
+      contentHash: fingerprint.sha256,
+      caption: caption ?? loaded.media?.caption ?? null,
+      captionStatus: enrichment?.captionImage
+        ? caption
+          ? "complete"
+          : "failed"
+        : "pending",
+      ocrText: ocrText ?? loaded.media?.ocrText ?? null,
+    })
+    .where(eq(schema.contextMedia.id, input.mediaId));
+
+  const families = await availableEmbeddingFamilies();
+  const set = await getActiveEmbeddingSet();
+  const family = set
+    ? (families.find(
+        (candidate) =>
+          candidate.id === set!.family &&
+          candidate.model === set!.model &&
+          candidate.version === set!.version,
+      ) ?? null)
+    : null;
+  let embeddingId: string | null = null;
+  const imageMimeSupported =
+    !family?.supportedImageMimeTypes ||
+    family.supportedImageMimeTypes.includes(loaded.mimeType);
+  if (set && family && vectorAdapter && imageMimeSupported) {
+    const [vector] = await family.embed(
+      [
+        {
+          text: [caption, ocrText].filter(Boolean).join("\n") || undefined,
+          images: [
+            {
+              mimeType: loaded.mimeType,
+              base64: Buffer.from(loaded.data).toString("base64"),
+            },
+          ],
+        },
+      ],
+      "document",
+    );
+    if (vector) {
+      embeddingId = `ccem_${randomUUID()}`;
+      const stored = await vectorAdapter.upsert({
+        embeddingId,
+        embeddingSetId: set.id,
+        vector,
+      });
+      await recordEmbeddingMetadata({
+        embeddingSetId: set.id,
+        itemId: loaded.itemId,
+        itemVersionId: loaded.itemVersionId,
+        targetType: "media",
+        targetId: input.mediaId,
+        vectorKey: stored.vectorKey,
+        dimensions: vector.length,
+        checksum: fingerprint.sha256,
+      });
+    }
+  }
+  await projectCreativeContextMedia(input.mediaId);
+  return {
+    mediaId: input.mediaId,
+    itemId: loaded.itemId,
+    itemVersionId: loaded.itemVersionId,
+    palette,
+    caption: caption ?? null,
+    ocrText: ocrText ?? null,
+    contentHash: fingerprint.sha256,
+    embeddingId,
+    embeddingFamily: family?.id ?? null,
+    embeddingSkippedReason:
+      set && family && !imageMimeSupported
+        ? `Active embedding family ${family.id} does not accept ${loaded.mimeType}.`
+        : null,
+  };
+}

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

@@ -0,0 +1,216 @@
+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");
+  } 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),
+  );
+}