@codemation/core-nodes 0.9.0 → 0.10.1

package/dist/metadata.json

@@ -1,10 +1,22 @@
 {
   "schemaVersion": 1,
   "packageName": "@codemation/core-nodes",
-  "packageVersion": "0.9.0",
+  "packageVersion": "0.10.1",
   "description": "",
   "kind": "nodes",
   "nodes": [
+    {
+      "name": "Codemation Document Scanner",
+      "kind": "node",
+      "description": "",
+      "inputPorts": [
+        "main"
+      ],
+      "outputPorts": [
+        "main"
+      ],
+      "sourcePath": "src/nodes/codemationDocumentScannerNode.ts"
+    },
     {
       "name": "Collection: Delete",
       "kind": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
     "@ai-sdk/provider": "^3.0.8",
     "ai": "^6.0.168",
     "croner": "^10.0.1",
-    "@codemation/core": "0.12.0"
+    "@codemation/core": "0.13.1"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/chatModels/CodemationChatModelFactory.ts

@@ -1,10 +1,10 @@
-import { createHmac, createHash, randomBytes } from "node:crypto";
 import type { ChatLanguageModel, ChatModelFactory, NodeExecutionContext } from "@codemation/core";
 import { chatModel } from "@codemation/core";
 
 import { createOpenAI } from "@ai-sdk/openai";
 
 import type { CodemationChatModelConfig } from "./CodemationChatModelConfig";
+import { managedHmacFetchFactory } from "./ManagedHmacSignerFactory.types";
 
 @chatModel({ packageName: "@codemation/core-nodes" })
 export class CodemationChatModelFactory implements ChatModelFactory<CodemationChatModelConfig> {
@@ -26,7 +26,7 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
       throw new Error("Codemation managed AI not available in this environment (workspace pairing is not configured).");
     }
 
-    const hmacFetch = this.buildHmacSignedFetch(workspaceId, pairingSecret);
+    const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret);
     // apiKey is required by the AI SDK but unused — authentication is handled by the HMAC-signed fetch wrapper.
     const provider = createOpenAI({ baseURL: `${gatewayUrl}/v1`, apiKey: "codemation-managed", fetch: hmacFetch });
     const languageModel = provider.chat(args.config.model);
@@ -41,63 +41,4 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
       },
     });
   }
-
-  /**
-   * Creates an HMAC-signed fetch wrapper for use with AI SDK's createOpenAI.
-   * Each call signs the request body with the workspace pairing secret so the
-   * LLM broker can authenticate the workspace without a user-managed API key.
-   *
-   * Mirrors HmacRequestSigner from @codemation/host/pairing without importing
-   * that package (which would create a circular dependency since @codemation/host
-   * depends on @codemation/core-nodes).
-   */
-  private buildHmacSignedFetch(workspaceId: string, pairingSecret: string): typeof fetch {
-    return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
-      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
-      const method = init?.method ?? "POST";
-
-      // Normalise body to a string for signing. Chat completions are always JSON strings
-      // but the fetch spec allows other BodyInit types — handle those defensively.
-      let bodyString = "";
-      if (init?.body !== undefined && init.body !== null) {
-        if (typeof init.body === "string") {
-          bodyString = init.body;
-        } else {
-          bodyString = await new Response(init.body).text();
-        }
-      }
-
-      const authHeader = this.buildHmacAuthHeader(workspaceId, pairingSecret, method, url, bodyString);
-
-      const headers = new Headers(init?.headers as Record<string, string> | undefined);
-      headers.set("Authorization", authHeader);
-
-      // Use the same (possibly normalised) body string that was signed.
-      const effectiveBody = bodyString || init?.body;
-      return fetch(input, { ...init, body: effectiveBody, headers });
-    };
-  }
-
-  /**
-   * Produces a Codemation-Hmac v1 Authorization header value.
-   * The algorithm must match HmacVerifier.computeSignature() in the control-plane.
-   */
-  private buildHmacAuthHeader(
-    workspaceId: string,
-    pairingSecret: string,
-    method: string,
-    url: string,
-    body: string,
-  ): string {
-    const ts = Math.floor(Date.now() / 1000);
-    const nonce = randomBytes(16).toString("base64");
-    const parsed = new URL(url);
-    const path = (parsed.pathname + parsed.search).toLowerCase();
-    const bodyHash = createHash("sha256").update(body, "utf8").digest("hex");
-    const baseString = [method.toUpperCase(), path, ts, nonce, bodyHash].join("\n");
-    // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is a fixed 32-byte value, never large
-    const secretBytes = Buffer.from(pairingSecret, "base64");
-    const sig = createHmac("sha256", secretBytes).update(baseString, "utf8").digest("base64");
-    return `Codemation-Hmac v=1,workspaceId=${workspaceId},ts=${ts},nonce=${nonce},sig=${sig}`;
-  }
 }

package/src/chatModels/ManagedHmacSignerFactory.types.ts

@@ -0,0 +1,88 @@
+import { createHmac, createHash, randomBytes } from "node:crypto";
+
+export interface ManagedHmacSignerOptions {
+  /**
+   * When true (the default), the signer hashes the request body and includes
+   * the hash in the HMAC base string. Use for small JSON payloads (LLM chat).
+   *
+   * When false (doc-scanner / LD11 mode), the signer computes the signature
+   * over sha256("") regardless of the actual body bytes, and forwards those
+   * bytes to the upstream fetch untouched. The HMAC binds the workspace
+   * identity, not the file content — enabling streaming without buffering.
+   */
+  signBody?: boolean;
+  /** Override wall-clock seconds for deterministic testing. */
+  now?: () => number;
+  /** Override nonce generation for deterministic testing. */
+  nonce?: () => string;
+}
+
+/**
+ * Creates an HMAC-signing fetch wrapper that authenticates requests to
+ * Codemation managed services (LLM broker, doc-scanner) with the
+ * Codemation-Hmac v=1 scheme.
+ *
+ * Mirrors HmacRequestSigner from @codemation/host/pairing without importing
+ * that package (which would create a circular dependency since @codemation/host
+ * depends on @codemation/core-nodes).
+ *
+ * @param workspaceId   - Workspace identifier injected by the CP provisioner.
+ * @param pairingSecret - Base64-encoded 32-byte HMAC key injected by the provisioner.
+ * @param options       - Optional behaviour flags and test seams.
+ */
+export function managedHmacFetchFactory(
+  workspaceId: string,
+  pairingSecret: string,
+  options?: ManagedHmacSignerOptions,
+): typeof fetch {
+  // LLM chat (the existing caller) signs its small JSON body → signBody defaults true.
+  // The doc-scanner node passes signBody:false (LD11): the HMAC binds the WORKSPACE,
+  // not the file, so we never read/normalise the (possibly large, binary) body —
+  // it is forwarded untouched and the signature covers an empty body hash.
+  const signBody = options?.signBody ?? true;
+
+  return async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const method = init?.method ?? "POST";
+
+    let bodyForSigning = "";
+    if (signBody && init?.body !== undefined && init.body !== null) {
+      bodyForSigning = typeof init.body === "string" ? init.body : await new Response(init.body).text();
+    }
+
+    const authHeader = buildHmacAuthHeader(workspaceId, pairingSecret, method, url, bodyForSigning, options);
+
+    const headers = new Headers(init?.headers as Record<string, string> | undefined);
+    headers.set("Authorization", authHeader);
+
+    // When signing the body, forward the (possibly normalised) string.
+    // When not signing (signBody:false), forward the ORIGINAL body untouched
+    // so binary/streamed payloads are never buffered or re-encoded.
+    const outgoingBody = signBody ? bodyForSigning || init?.body : init?.body;
+    return fetch(input, { ...init, body: outgoingBody, headers });
+  };
+}
+
+/**
+ * Produces a Codemation-Hmac v=1 Authorization header value.
+ * Algorithm must match HmacVerifier.computeSignature() in the control-plane.
+ */
+function buildHmacAuthHeader(
+  workspaceId: string,
+  pairingSecret: string,
+  method: string,
+  url: string,
+  body: string,
+  overrides?: Pick<ManagedHmacSignerOptions, "now" | "nonce">,
+): string {
+  const ts = overrides?.now ? overrides.now() : Math.floor(Date.now() / 1000);
+  const nonce = overrides?.nonce ? overrides.nonce() : randomBytes(16).toString("base64");
+  const parsed = new URL(url);
+  const path = (parsed.pathname + parsed.search).toLowerCase();
+  const bodyHash = createHash("sha256").update(body, "utf8").digest("hex");
+  const baseString = [method.toUpperCase(), path, ts, nonce, bodyHash].join("\n");
+  // eslint-disable-next-line codemation/no-buffer-everything -- pairing secret is a fixed 32-byte value, never large
+  const secretBytes = Buffer.from(pairingSecret, "base64");
+  const sig = createHmac("sha256", secretBytes).update(baseString, "utf8").digest("base64");
+  return `Codemation-Hmac v=1,workspaceId=${workspaceId},ts=${ts},nonce=${nonce},sig=${sig}`;
+}

package/src/index.ts

@@ -44,3 +44,4 @@ export * from "./nodes/ConnectionCredentialNodeConfigFactory";
 export * from "./nodes/ConnectionCredentialExecutionContextFactory";
 export * from "./nodes/collections";
 export * from "./nodes/InboxApprovalNode.types";
+export * from "./nodes/codemationDocumentScannerNode";

package/src/nodes/AIAgentNode.ts

@@ -867,10 +867,20 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
     try {
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
-      const outputSchema =
-        structuredOptions?.strict && !this.isZodSchema(schema)
-          ? Output.object({ schema: jsonSchema(schema as Parameters<typeof jsonSchema>[0]) as never })
-          : Output.object({ schema: schema as ZodSchemaAny });
+      // Always feed the AI SDK a plain JSON Schema, never a raw Zod schema. A consumer
+      // workflow's outputSchema is created with the consumer's tsx-loaded Zod — a different
+      // runtime copy than the framework's Zod — so handing that object to `Output.object`
+      // throws "schema is not a function". Convert via the schema's own instance method
+      // (dual-zod safe; see AIAgentExecutionHelpersFactory) before wrapping with jsonSchema().
+      const schemaRecord = this.isZodSchema(schema)
+        ? this.executionHelpers.createJsonSchemaRecord(schema, {
+            schemaName: structuredOptions?.schemaName ?? "structured_output",
+            requireObjectRoot: true,
+          })
+        : schema;
+      const outputSchema = Output.object({
+        schema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]) as never,
+      });
       const result = await generateText({
         model: model.languageModel as LanguageModel,
         messages: [...messages],

package/src/nodes/codemationDocumentScannerNode.ts

@@ -0,0 +1,131 @@
+import { defineNode } from "@codemation/core";
+import { z } from "zod";
+import { managedHmacFetchFactory } from "../chatModels/ManagedHmacSignerFactory.types";
+
+const ANALYZER_TYPES = ["document", "invoice", "image", "auto"] as const;
+export type DocScannerAnalyzerType = (typeof ANALYZER_TYPES)[number];
+
+/** Per-field value/confidence shape as returned by apps/doc-scanner. */
+export type DocScannerField = Readonly<{
+  value: unknown;
+  confidence: number | null;
+}>;
+
+/** Output shape of CodemationDocumentScanner — identical to the service wire response. */
+export type DocScannerOutput = Readonly<{
+  markdown: string;
+  fields: Readonly<Record<string, DocScannerField>>;
+}>;
+
+export type CodemationDocumentScannerConfig = Readonly<{
+  /** Key on `item.binary` that holds the document. Default: "data". */
+  binaryField?: string;
+  /** Analyzer type. Default: "auto" (routes on mime type on the service side). */
+  analyzerType?: DocScannerAnalyzerType;
+  /** MIME type override. Falls back to attachment.mimeType. */
+  contentType?: string;
+  /** Include per-field confidence scores (0–1). Default: false.
+   *  Enabling this roughly doubles contextualization tokens for document analyzers.
+   *  Image and auto-to-image requests silently ignore this flag (confidence stays null). */
+  includeConfidence?: boolean;
+  /** Max bytes checked before any read. Default: 50 MiB (same cap as OCR nodes, LD10). */
+  maxBytes?: number;
+}>;
+
+export const codemationDocumentScannerNode = defineNode({
+  key: "codemation.document-scanner",
+  title: "Codemation Document Scanner",
+  description:
+    "Analyzes a binary attachment (document or image) via the managed Codemation document-scanning service " +
+    "and returns markdown text plus structured fields. No Azure credential required — auth uses the workspace " +
+    "pairing secret. Enable includeConfidence to get per-field confidence scores (0–1).",
+  icon: "lucide:scan-text",
+  input: {
+    binaryField: "data",
+    analyzerType: "auto" as DocScannerAnalyzerType,
+    contentType: undefined as string | undefined,
+    includeConfidence: false,
+    maxBytes: undefined as number | undefined,
+  },
+  configSchema: z.object({
+    binaryField: z.string().optional(),
+    analyzerType: z.enum(ANALYZER_TYPES).optional(),
+    contentType: z.string().optional(),
+    includeConfidence: z.boolean().optional(),
+    maxBytes: z.number().int().positive().optional(),
+  }),
+  // keepBinaries is omitted (false) — the output replaces the item payload.
+  // To carry the source binary forward, set keepBinaries: true at the call site
+  // or use a downstream step that reads item.binary.
+  inspectorSummary({ config }) {
+    const cfg = config as unknown as CodemationDocumentScannerConfig;
+    const rows: Array<{ label: string; value: string }> = [
+      { label: "Analyzer type", value: cfg.analyzerType ?? "auto" },
+    ];
+    const binaryField = cfg.binaryField ?? "data";
+    if (binaryField !== "data") rows.push({ label: "Binary field", value: binaryField });
+    if (cfg.includeConfidence) rows.push({ label: "Confidence", value: "enabled" });
+    if (cfg.contentType) rows.push({ label: "Content type", value: cfg.contentType });
+    return rows;
+  },
+  async execute({ item, ctx }, { config: rawConfig }) {
+    const config = rawConfig as unknown as CodemationDocumentScannerConfig;
+
+    // eslint-disable-next-line no-restricted-properties -- DOC_SCANNER_GATEWAY_URL is injected by the control-plane provisioner into the workspace process env; reading it at execute time is the justified boundary.
+    const gatewayUrl = process.env["DOC_SCANNER_GATEWAY_URL"];
+    if (!gatewayUrl) {
+      throw new Error(
+        "Codemation Document Scanner not available in this environment (DOC_SCANNER_GATEWAY_URL is not set).",
+      );
+    }
+
+    // Workspace pairing identity — injected by the CP provisioner (mirrors
+    // CodemationChatModelFactory). Passed to the signer; the HMAC binds THIS
+    // workspace (LD4) and does not sign the file body (LD11).
+    // eslint-disable-next-line no-restricted-properties -- WORKSPACE_ID is injected by the provisioner; read at execute time.
+    const workspaceId = process.env["WORKSPACE_ID"];
+    // eslint-disable-next-line no-restricted-properties -- WORKSPACE_PAIRING_SECRET is injected by the provisioner; read at execute time.
+    const pairingSecret = process.env["WORKSPACE_PAIRING_SECRET"];
+    if (!workspaceId || !pairingSecret) {
+      throw new Error("Codemation Document Scanner not available (workspace pairing is not configured).");
+    }
+
+    const binaryField = config.binaryField ?? "data";
+    const attachment = item.binary?.[binaryField];
+    if (!attachment) {
+      throw new Error(`Codemation Document Scanner: no binary attachment at key "${binaryField}".`);
+    }
+
+    const body = await ctx.binary.getBytes(attachment, config.maxBytes);
+    const contentType = config.contentType ?? attachment.mimeType ?? "application/octet-stream";
+    const analyzerType = config.analyzerType ?? "auto";
+    const includeConfidence = config.includeConfidence ?? false;
+
+    const confidenceSuffix = includeConfidence ? "&confidence=true" : "";
+    const url = `${gatewayUrl}/analyze?type=${encodeURIComponent(analyzerType)}${confidenceSuffix}`;
+
+    // signBody: false (LD11): the HMAC binds the workspace, not the file body.
+    // The signer forwards the bytes untouched and signs an empty-body hash, so
+    // we never re-read or normalise the binary payload.
+    const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret, { signBody: false });
+
+    const response = await hmacFetch(url, {
+      method: "POST",
+      body: body.buffer as ArrayBuffer,
+      headers: {
+        "Content-Type": contentType,
+        "Content-Length": String(body.byteLength),
+        "X-Codemation-Caller": "workflow-node",
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "(unreadable)");
+      throw new Error(
+        `Codemation Document Scanner: service responded ${response.status} ${response.statusText} — ${text}`,
+      );
+    }
+
+    return (await response.json()) as DocScannerOutput;
+  },
+});