@fungi.computer/darkroom 0.0.0-stage → 0.1.0

package/dist/provenance-export.js

@@ -0,0 +1,103 @@
+import { DOMParser } from "@xmldom/xmldom";
+import ExifReader from "exifreader";
+import { createRiffContainer, parseRiff } from "@fungi.computer/ts-webp";
+import { replacePngXmp } from "./provenance-png.js";
+import { replaceJpegXmp } from "./provenance-jpeg.js";
+import { publicProvenancePacket } from "./provenance-xmp.js";
+/** The admitted Computer file read and generated output share this launch bound. */
+export const maximumPrintDownloadBytes = 32 * 1024 * 1024;
+/** A refusal to export unsafe, unsupported or oversized image bytes. */
+export class ProvenanceExportError extends Error {
+    reason;
+    /** Stable export refusal name. */
+    name = "ProvenanceExportError";
+    constructor(
+    /** Bounded refusal reason. */
+    reason, options) {
+        super(`Print export refused: ${reason}`, options);
+        this.reason = reason;
+    }
+}
+function replaceWebpXmp(bytes, xmp) {
+    const chunks = parseRiff(bytes);
+    // The maintained parser tolerates truncation for inspection. Export must not
+    // turn a partial file into an apparently successful download.
+    if (chunks.some((chunk) => chunk.size !== chunk.data.length) ||
+        chunks.reduce((length, chunk) => length + 8 + chunk.size + (chunk.size % 2), 12) !== bytes.length)
+        throw new Error("Incomplete extended WebP");
+    if (!chunks.some((chunk) => chunk.fourCC === "XMP "))
+        return bytes;
+    if (!chunks.some((chunk) => chunk.fourCC === "VP8X"))
+        throw new Error("XMP without extended WebP header");
+    let inserted = false;
+    return createRiffContainer(chunks.flatMap((chunk) => {
+        if (chunk.fourCC !== "XMP ")
+            return [
+                {
+                    fourCC: chunk.fourCC,
+                    data: chunk.data,
+                },
+            ];
+        if (inserted)
+            return [];
+        inserted = true;
+        return [
+            {
+                fourCC: "XMP ",
+                data: new TextEncoder().encode(xmp),
+            },
+        ];
+    }));
+}
+/** Lossless browser export. Never mutates the input or falls back to private bytes. */
+export async function stripPrivateProvenance(bytes) {
+    if (bytes.length > maximumPrintDownloadBytes)
+        throw new ProvenanceExportError("too-large");
+    // Match the embed owner's conservative signed-image policy. This is not
+    // signature validation, and stripping never silently invalidates a signature.
+    const text = new TextDecoder("latin1").decode(bytes);
+    if (text.includes("c2pa") || text.includes("caBX"))
+        throw new ProvenanceExportError("signed-image");
+    try {
+        const metadata = await ExifReader.loadView(new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), {
+            expanded: true,
+            async: true,
+            domParser: new DOMParser(),
+            includeTags: { xmp: true, png: true, file: true },
+            decompress: { maxDecompressedSize: maximumPrintDownloadBytes },
+        });
+        const format = metadata.file?.FileType?.value;
+        if (format !== "png" &&
+            format !== "jpeg" &&
+            format !== "webp" &&
+            format !== "gif")
+            throw new ProvenanceExportError("unsupported-format");
+        const mime = {
+            type: `image/${format}`,
+            extension: format === "jpeg" ? "jpg" : format,
+        };
+        if (format === "gif" && !metadata.xmp)
+            return { bytes, ...mime };
+        const packet = publicProvenancePacket(metadata.xmp?._raw ?? metadata.pngText?.["XML:com.adobe.xmp"]?.value);
+        const output = format === "png"
+            ? replacePngXmp(bytes, packet)
+            : format === "jpeg"
+                ? replaceJpegXmp(bytes, packet)
+                : format === "webp"
+                    ? replaceWebpXmp(bytes, packet)
+                    : undefined;
+        if (!output)
+            throw new ProvenanceExportError("unsupported-format");
+        if (output.length > maximumPrintDownloadBytes)
+            throw new ProvenanceExportError("too-large");
+        return {
+            bytes: output,
+            ...mime,
+        };
+    }
+    catch (cause) {
+        if (cause instanceof ProvenanceExportError)
+            throw cause;
+        throw new ProvenanceExportError("invalid-image", { cause });
+    }
+}

package/dist/provenance-jpeg.d.ts

@@ -0,0 +1,3 @@
+/** Narrow JPEG splice exception: adr-jpeg-provenance-splice. Never decode or
+ * rewrite scan data; walk bounded header segments and preserve their bytes. */
+export declare function replaceJpegXmp(bytes: Uint8Array, xmp: string): Uint8Array;

package/dist/provenance-jpeg.js

@@ -0,0 +1,76 @@
+import { joinBytes, startsWithBytes } from "./provenance-bytes.js";
+const jpegXmpSignature = "http://ns.adobe.com/xap/1.0/\0";
+const jpegExtendedXmpSignature = "http://ns.adobe.com/xmp/extension/\0";
+/** Narrow JPEG splice exception: adr-jpeg-provenance-splice. Never decode or
+ * rewrite scan data; walk bounded header segments and preserve their bytes. */
+export function replaceJpegXmp(bytes, xmp) {
+    const source = bytes;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (source.length < 4 ||
+        view.getUint16(0) !== 0xffd8 ||
+        view.getUint16(source.length - 2) !== 0xffd9)
+        throw new Error("Invalid JPEG envelope");
+    const payload = new TextEncoder().encode(`${jpegXmpSignature}${xmp}`);
+    if (payload.length > 65_533)
+        throw new Error("XMP exceeds one JPEG APP1 segment");
+    const header = new Uint8Array(4);
+    const headerView = new DataView(header.buffer);
+    headerView.setUint16(0, 0xffe1);
+    headerView.setUint16(2, payload.length + 2);
+    const xmpSegment = joinBytes([header, payload]);
+    const segments = [source.subarray(0, 2)];
+    let insertion = 1;
+    let leading = true;
+    let hasFrame = false;
+    let offset = 2;
+    while (offset + 4 <= source.length) {
+        const start = offset;
+        if (source[offset] !== 0xff)
+            throw new Error("Invalid JPEG marker");
+        while (source[offset] === 0xff)
+            offset++;
+        const marker = source[offset];
+        if (marker === undefined ||
+            marker === 0 ||
+            marker === 0xd8 ||
+            marker === 0xd9)
+            throw new Error("JPEG ended before its scan");
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            segments.push(source.subarray(start, offset + 1));
+            offset++;
+            leading = false;
+            continue;
+        }
+        if (offset + 3 > source.length)
+            throw new Error("Truncated JPEG length");
+        const length = view.getUint16(offset + 1);
+        const end = offset + 1 + length;
+        if (length < 2 || end > source.length)
+            throw new Error("Truncated JPEG segment");
+        if (marker >= 0xc0 &&
+            marker <= 0xcf &&
+            ![0xc4, 0xc8, 0xcc].includes(marker))
+            hasFrame = true;
+        if (marker === 0xda) {
+            if (!hasFrame)
+                throw new Error("JPEG has no frame");
+            segments.splice(insertion, 0, xmpSegment);
+            segments.push(source.subarray(start));
+            return joinBytes(segments);
+        }
+        const data = source.subarray(offset + 3, end);
+        const isXmp = marker === 0xe1 &&
+            [jpegXmpSignature, jpegExtendedXmpSignature].some((signature) => startsWithBytes(data, signature));
+        if (!isXmp) {
+            segments.push(source.subarray(start, end));
+            if (leading &&
+                (marker === 0xe0 ||
+                    (marker === 0xe1 && startsWithBytes(data, "Exif\0\0"))))
+                insertion = segments.length;
+            else
+                leading = false;
+        }
+        offset = end;
+    }
+    throw new Error("JPEG has no scan");
+}

package/dist/provenance-png.d.ts

@@ -0,0 +1 @@
+export declare function replacePngXmp(bytes: Uint8Array, xmp: string): Uint8Array;

package/dist/provenance-png.js

@@ -0,0 +1,21 @@
+import extractPng from "png-chunks-extract";
+import encodePng from "png-chunks-encode";
+import { joinBytes, startsWithBytes } from "./provenance-bytes.js";
+export function replacePngXmp(bytes, xmp) {
+    const chunks = extractPng(bytes);
+    const keyword = "XML:com.adobe.xmp\0";
+    const kept = chunks.filter((chunk) => !(["iTXt", "tEXt", "zTXt"].includes(chunk.name) &&
+        startsWithBytes(chunk.data, keyword)));
+    const imageIndex = kept.findIndex((chunk) => chunk.name === "IDAT");
+    if (imageIndex < 0)
+        throw new Error("PNG has no image data");
+    kept.splice(imageIndex, 0, {
+        name: "iTXt",
+        data: joinBytes([
+            new TextEncoder().encode(keyword),
+            new Uint8Array(4),
+            new TextEncoder().encode(xmp),
+        ]),
+    });
+    return encodePng(kept);
+}

package/dist/provenance-xmp.d.ts

@@ -0,0 +1,2 @@
+/** Whitelist public identity, never copy provider or Fungi private XMP wholesale. */
+export declare function publicProvenancePacket(packet?: string): string;

package/dist/provenance-xmp.js

@@ -0,0 +1,54 @@
+import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
+const fungiNamespace = "https://fungi.computer/ns/provenance/1.0/";
+const iptcNamespace = "http://iptc.org/std/Iptc4xmpExt/2008-02-29/";
+const rdfNamespace = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
+/** Whitelist public identity, never copy provider or Fungi private XMP wholesale. */
+export function publicProvenancePacket(packet) {
+    const parser = new DOMParser({
+        onError: () => {
+            throw new Error("Invalid provenance XML");
+        },
+    });
+    const source = packet
+        ? parser.parseFromString(packet, "application/xml")
+        : undefined;
+    const value = (namespace, name) => {
+        const element = source?.getElementsByTagNameNS(namespace, name).item(0);
+        if (element?.textContent)
+            return element.textContent;
+        const descriptions = source?.getElementsByTagNameNS(rdfNamespace, "Description");
+        if (!descriptions)
+            return undefined;
+        for (let index = 0; index < descriptions.length; index++) {
+            const attribute = descriptions
+                .item(index)
+                ?.getAttributeNS(namespace, name);
+            if (attribute)
+                return attribute;
+        }
+        return undefined;
+    };
+    const output = parser.parseFromString('<x:xmpmeta xmlns:x="adobe:ns:meta/"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description rdf:about=""/></rdf:RDF></x:xmpmeta>', "application/xml");
+    const description = output
+        .getElementsByTagNameNS(rdfNamespace, "Description")
+        .item(0);
+    if (!description)
+        throw new Error("Missing provenance description");
+    const fields = [
+        { namespace: fungiNamespace, name: "printId", qualified: "fungi:printId" },
+        {
+            namespace: iptcNamespace,
+            name: "DigitalSourceType",
+            qualified: "Iptc4xmpExt:DigitalSourceType",
+        },
+    ];
+    for (const { namespace, name, qualified } of fields) {
+        const text = value(namespace, name);
+        if (text === undefined)
+            continue;
+        const element = output.createElementNS(namespace, qualified);
+        element.textContent = text;
+        description.appendChild(element);
+    }
+    return new XMLSerializer().serializeToString(output);
+}

package/dist/provenance.d.ts

@@ -0,0 +1,20 @@
+import type { ImageFormat } from "./index.js";
+/** Public file facts only; actor, namespace, billing and reference paths stay private. */
+export type ProvenanceFacts = Readonly<{
+    printId: string;
+    model: string;
+    prompt: string;
+    createdAt: number;
+}>;
+export type ProvenanceEmbedResult = Readonly<{
+    bytes: Uint8Array;
+    embedded: true;
+}> | Readonly<{
+    bytes: Uint8Array;
+    embedded: false;
+    reason: "unsupported-format" | "signed-image" | "invalid-image";
+}>;
+/** Deterministic enrichment. A failed embed never replaces or loses paid bytes.
+ * Conservative C2PA detection preserves signed outputs unchanged rather than
+ * claiming their old signatures still cover a modified file. */
+export declare function embedProvenance(bytes: Uint8Array, format: ImageFormat | "mp4", facts: ProvenanceFacts): Promise<ProvenanceEmbedResult>;

package/dist/provenance.js

@@ -0,0 +1,58 @@
+import { Buffer as NodeBuffer } from "node:buffer";
+import { replacePngXmp } from "./provenance-png.js";
+import { replaceJpegXmp } from "./provenance-jpeg.js";
+import { reportCatchFailure } from "./failure.js";
+// The XMP builder and WebP muxer load on the first embed: a Worker that hosts
+// this module never pays to evaluate them at startup.
+async function packet(facts) {
+    const { create } = await import("xmlbuilder2");
+    const document = create({ invalidCharReplacement: "�" });
+    const description = document
+        .ele("adobe:ns:meta/", "x:xmpmeta")
+        .ele("http://www.w3.org/1999/02/22-rdf-syntax-ns#", "rdf:RDF")
+        .ele("rdf:Description")
+        .att("rdf:about", "")
+        .att("xmlns:xmp", "http://ns.adobe.com/xap/1.0/")
+        .att("xmlns:Iptc4xmpExt", "http://iptc.org/std/Iptc4xmpExt/2008-02-29/")
+        .att("xmlns:fungi", "https://fungi.computer/ns/provenance/1.0/");
+    description
+        .ele("xmp:CreateDate")
+        .txt(new Date(facts.createdAt).toISOString());
+    description
+        .ele("Iptc4xmpExt:DigitalSourceType")
+        .txt("http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia");
+    description.ele("fungi:printId").txt(facts.printId);
+    description.ele("fungi:model").txt(facts.model);
+    description.ele("fungi:prompt").txt(facts.prompt);
+    return document.end({ headless: true });
+}
+async function embedWebp(bytes, xmp) {
+    const { default: webp } = await import("node-webpmux");
+    const image = new webp.Image();
+    await image.load(NodeBuffer.from(bytes));
+    image.xmp = NodeBuffer.from(xmp, "utf8");
+    return image.save(null);
+}
+/** Deterministic enrichment. A failed embed never replaces or loses paid bytes.
+ * Conservative C2PA detection preserves signed outputs unchanged rather than
+ * claiming their old signatures still cover a modified file. */
+export async function embedProvenance(bytes, format, facts) {
+    if (format === "gif" || format === "mp4")
+        return { bytes, embedded: false, reason: "unsupported-format" };
+    if (NodeBuffer.from(bytes).includes("c2pa") ||
+        NodeBuffer.from(bytes).includes("caBX"))
+        return { bytes, embedded: false, reason: "signed-image" };
+    try {
+        const xmp = await packet(facts);
+        const output = format === "png"
+            ? replacePngXmp(bytes, xmp)
+            : format === "jpeg"
+                ? replaceJpegXmp(bytes, xmp)
+                : await embedWebp(bytes, xmp);
+        return { bytes: output, embedded: true };
+    }
+    catch (cause) {
+        reportCatchFailure("embed-provenance", cause);
+        return { bytes, embedded: false, reason: "invalid-image" };
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,158 @@
+export { mediaPendingSchema, mediaBindingCallSchema, mediaBindingGenerationSchema, mediaImageBindingInputSchema, mediaVideoBindingInputSchema, parseMediaBindingCall, mediaBindingRequest, readMediaBindingReply, type MediaBindingCall, type MediaBindingGeneration, type MediaBindingRequest, } from "./media-binding.js";
+import { Hono } from "hono";
+import { z } from "zod";
+import { validateMediaGenerationSettings, type MediaProvider, type MediaReference, type MediaReferenceBytes } from "./index.js";
+import { type MediaExecution, type MediaMetering } from "./media-operation-contract.js";
+import { MediaExecutionError, type MediaBillingRefusalCode } from "./execution-error.js";
+export { MediaBillingRefusal, MediaExecutionError, type MediaBillingRefusalCode, type MediaFailureStage, } from "./execution-error.js";
+export { mediaUnits, type MediaUnits } from "./gateway-models.js";
+export type { MediaMetering, MediaOperation, } from "./media-operation-contract.js";
+export { MediaOperationOwner, mediaOperationDestinationSchema, mediaOperationCoordinatesSchema, mediaOperationStateSchema, mediaImageSchema, mediaOperationResultSchema, } from "./media-operation-owner.js";
+export type { MediaOperationCoordinates, MediaOperationRequest, MediaOperationProjection, MediaOperationDecision, MediaOperationState, MediaOperationResult, MediaOperationEnvironment, MediaOperationHooks, MediaImage, MediaErasurePreflight, MediaErasureReadback, MediaRetentionResult, } from "./media-operation-owner.js";
+export type { MediaOperationContext, MediaOperationStorage, MediaOperationBucket, MediaOperationObject, } from "./media-operation-storage.js";
+/** Decode relative service generation input. Identity comes from the host. */
+export declare const mediaRequestSchema: z.ZodObject<{
+    path: z.ZodString;
+    settings: z.ZodObject<{
+        model: z.ZodString;
+        prompt: z.ZodString;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        steps: z.ZodOptional<z.ZodNumber>;
+        durationSeconds: z.ZodOptional<z.ZodNumber>;
+        resolution: z.ZodOptional<z.ZodEnum<{
+            readonly p480: "480p";
+            readonly p720: "720p";
+            readonly p768: "768p";
+            readonly p1080: "1080p";
+            readonly p4k: "4k";
+        }>>;
+        aspectRatio: z.ZodOptional<z.ZodEnum<{
+            readonly wide: "16:9";
+            readonly landscape: "4:3";
+            readonly square: "1:1";
+            readonly portrait: "3:4";
+            readonly tall: "9:16";
+            readonly ultrawide: "21:9";
+            readonly ultratall: "9:21";
+        }>>;
+        generateAudio: z.ZodOptional<z.ZodBoolean>;
+        references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            computerId: z.ZodString;
+            path: z.ZodString;
+            role: z.ZodOptional<z.ZodEnum<{
+                readonly first: "first-frame";
+                readonly last: "last-frame";
+                readonly reference: "reference";
+            }>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>;
+    outputFormat: z.ZodOptional<z.ZodEnum<{
+        readonly png: "png";
+        readonly jpeg: "jpeg";
+        readonly webp: "webp";
+    }>>;
+}, z.core.$strict>;
+export { mediaResultSchema } from "./media-operation-contract.js";
+/** A background (video) generation in progress; retry the same request id. */
+/** Identity supplied by the admitting host, never selected by a request body. */
+export type MediaScope = Readonly<{
+    /** Host-admitted actor identity. */
+    actorId: string;
+    /** Host-owned isolation namespace. */
+    namespace: string;
+    /** Host-owned application or actor within the namespace. */
+    owner: string;
+    /** Host-admitted destination identity. */
+    destinationId: string;
+}>;
+/** Customer-visible refusal text owned by a metered host. */
+export type MediaRefusalMessages = Readonly<Record<MediaBillingRefusalCode, string>>;
+/** Host authority, durable operations, provider, metering and destination access. */
+export type MediaServiceHost = Readonly<{
+    /** Identity admitted by the host before service construction. */
+    scope: MediaScope;
+    /** Resolve durable operations by their service-selected name. */
+    operations: {
+        /** Resolve the service-selected operation name to its local or RPC owner. */
+        getByName(name: string): MediaExecution["operation"];
+    };
+    /** The provider call for every generation (Workers AI, or the Hub's edge on celld). */
+    provider: MediaProvider;
+    /** Host-owned address roster, committed before the operation can create storage. */
+    beforeAdmit?: ((requestId: string) => Promise<void>) | undefined;
+    /** Recheck the host's generation authority only before a new dispatch.
+     * Retained output still uses destination authorization when saving. */
+    authorizeGeneration?: () => Promise<void>;
+    /** Authorize and save generated bytes, and optionally read references. */
+    destination: Readonly<{
+        /** Check host permission before writing or dispatching generation. */
+        authorize: (path: string) => Promise<void>;
+        /** Save exact generated bytes to the admitted destination. */
+        write: (path: string, bytes: Uint8Array) => Promise<void>;
+        /** Authorize and decode one selected reference image. */
+        readReference?: (reference: MediaReference) => Promise<MediaReferenceBytes>;
+    }>;
+    /** Translate host authority failures; undefined uses the shared Media failure. */
+    onFailure?: (error: MediaExecutionError) => Response | undefined;
+}> & (Readonly<{
+    /** The host pays its own provider directly. */
+    metering: "unmetered";
+    /** Unmetered hosts do not have billing refusal policy. */
+    refusalMessages?: never;
+}> | Readonly<{
+    /** Idempotent admission and settlement owned by the host. */
+    metering: MediaMetering;
+    /** Customer copy for each definitive billing refusal. */
+    refusalMessages: MediaRefusalMessages;
+}>);
+/** One Media generation request, already carrying its idempotency key. */
+export type MediaGenerationRequest = Readonly<{
+    /** Stable request identity reused for retries. */
+    requestId: string;
+    /** Fixed destination path for this operation. */
+    path: string;
+    /** Model settings validated before admission. */
+    settings: Parameters<typeof validateMediaGenerationSettings>[0];
+    /** Optional verified image format pin. */
+    outputFormat?: z.output<typeof mediaRequestSchema>["outputFormat"];
+}>;
+/** The typed result of one generation, shared by the Hono route and the Agent path. */
+export type MediaGenerationOutcome = Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "succeeded";
+    /** Fixed destination or reference file path. */
+    path: string;
+    /** Output byte length. */
+    bytes: number;
+    /** Admitted price in milliunits, where 1 cent is 1,000 milliunits. */
+    costMilliunits: number;
+    /** Actual output encoding. */
+    format: "png" | "jpeg" | "gif" | "webp" | "mp4";
+    /** Requested image height or nominal video selector, not decoded MP4 dimensions. */
+    height: number;
+    /** Provider catalog model identifier. */
+    model: string;
+    /** Requested image width or nominal video selector, not decoded MP4 dimensions. */
+    width: number;
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "pending";
+    /** Whether generation is running through the durable alarm. */
+    background: boolean;
+    /** Delay before retrying the same request, in seconds. */
+    retryAfterSeconds: number;
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "conflict";
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "interrupted";
+}> | Readonly<{
+    /** Outcome or model-kind discriminant. */
+    kind: "unavailable";
+}>;
+/** Generate through the Effect core with a Promise boundary preserving typed domain failures. */
+export declare function generateMedia(host: MediaServiceHost, request: MediaGenerationRequest, signal?: AbortSignal): Promise<MediaGenerationOutcome>;
+/** Relative HTTP routes; the caller admits identity and supplies destination access. */
+export declare function createMediaService(host: MediaServiceHost): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;