fundus 0.2.0 → 0.4.0

package/dist/server/importers/figma.js

@@ -0,0 +1,386 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import sharp from 'sharp';
+import { SourceImportError, invalidInput } from './contract.js';
+import { requestPinnedHttps } from './pinned-https.js';
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
+const MAX_PIXELS = 32_000_000;
+const MAX_REDIRECTS = 3;
+const REQUEST_TIMEOUT_MS = 30_000;
+const PNG_SIGNATURE = Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function parseFigmaSelectionUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return invalidInput('Enter a valid Figma selection link.');
+    }
+    if (url.protocol !== 'https:' ||
+        (url.hostname !== 'figma.com' && url.hostname !== 'www.figma.com')) {
+        return invalidInput('Figma links must use HTTPS on figma.com.');
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (!['design', 'file', 'proto'].includes(segments[0] ?? '') || !segments[1]) {
+        return invalidInput('The Figma link must point to a design, file, or prototype.');
+    }
+    const nodeIds = url.searchParams.getAll('node-id');
+    if (nodeIds.length !== 1 || !/^\d+[-:]\d+$/.test(nodeIds[0])) {
+        return invalidInput('The Figma link must contain exactly one valid node-id.');
+    }
+    const [left, right] = nodeIds[0].split(/[-:]/);
+    return { fileKey: segments[1], nodeId: `${left}:${right}` };
+}
+function validateScale(value) {
+    if (value !== 1 && value !== 2 && value !== 3 && value !== 4) {
+        return invalidInput('Figma export scale must be 1, 2, 3, or 4.');
+    }
+    return value;
+}
+function validateInput(value) {
+    const input = record(value);
+    if (!input || typeof input.url !== 'string')
+        return invalidInput('Figma import requires a URL.');
+    if (input.format !== undefined && input.format !== 'png') {
+        return invalidInput('Figma import currently supports PNG only.');
+    }
+    return {
+        url: input.url,
+        format: 'png',
+        ...(input.scale !== undefined ? { scale: validateScale(input.scale) } : {})
+    };
+}
+export function validateFigmaSourceParameters(value) {
+    const source = record(value);
+    if (!source ||
+        typeof source.fileKey !== 'string' ||
+        source.fileKey.length === 0 ||
+        typeof source.nodeId !== 'string' ||
+        !/^\d+:\d+$/.test(source.nodeId) ||
+        source.format !== 'png') {
+        return invalidInput('Stored Figma source parameters are invalid.');
+    }
+    return {
+        fileKey: source.fileKey,
+        nodeId: source.nodeId,
+        format: 'png',
+        scale: validateScale(source.scale)
+    };
+}
+function retryAfter(response) {
+    const raw = response.headers.get('retry-after');
+    if (!raw || !/^\d+$/.test(raw.trim()))
+        return undefined;
+    const seconds = Number(raw);
+    return Number.isSafeInteger(seconds) ? seconds : undefined;
+}
+function upstreamStatusError(response) {
+    if (response.status === 401)
+        return new SourceImportError('unauthorized', 'Figma authentication failed.');
+    if (response.status === 403)
+        return new SourceImportError('forbidden', 'Figma authentication or access failed. The token may be invalid or expired, or it may not have access to this file.');
+    if (response.status === 404)
+        return new SourceImportError('not-found', 'The Figma file or node was not found.');
+    if (response.status === 429) {
+        return new SourceImportError('rate-limited', 'Figma rate-limited this request.', retryAfter(response));
+    }
+    return new SourceImportError('upstream-failed', `Figma export failed with status ${response.status}.`);
+}
+function isForbiddenIpv4(address) {
+    const parts = address.split('.').map(Number);
+    const [a, b] = parts;
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 0) ||
+        (a === 192 && b === 0 && parts[2] === 2) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        (a === 198 && b === 51 && parts[2] === 100) ||
+        (a === 203 && b === 0 && parts[2] === 113) ||
+        a >= 224);
+}
+function mappedIpv4Address(address) {
+    const normalized = address.toLowerCase().split('%')[0];
+    const dotted = /^(?:::ffff:|0:0:0:0:0:ffff:)(\d+\.\d+\.\d+\.\d+)$/.exec(normalized);
+    if (dotted && isIP(dotted[1]) === 4)
+        return dotted[1];
+    const halves = normalized.split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] ? halves[0].split(':') : [];
+    const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    const missing = 8 - left.length - right.length;
+    if (missing < 0 || (halves.length === 1 && missing !== 0))
+        return null;
+    const parts = [...left, ...Array.from({ length: missing }, () => '0'), ...right];
+    if (parts.length !== 8 ||
+        parts.slice(0, 5).some((part) => Number.parseInt(part || '0', 16) !== 0) ||
+        Number.parseInt(parts[5] || '0', 16) !== 0xffff) {
+        return null;
+    }
+    const high = Number.parseInt(parts[6], 16);
+    const low = Number.parseInt(parts[7], 16);
+    if (!Number.isInteger(high) ||
+        !Number.isInteger(low) ||
+        high < 0 ||
+        high > 0xffff ||
+        low < 0 ||
+        low > 0xffff) {
+        return null;
+    }
+    return `${high >>> 8}.${high & 0xff}.${low >>> 8}.${low & 0xff}`;
+}
+function isForbiddenIp(address) {
+    if (isIP(address) === 4)
+        return isForbiddenIpv4(address);
+    const normalized = address.toLowerCase().split('%')[0];
+    const mapped = mappedIpv4Address(normalized);
+    if (mapped)
+        return isForbiddenIpv4(mapped);
+    return (normalized === '::' ||
+        normalized === '::1' ||
+        normalized.startsWith('fc') ||
+        normalized.startsWith('fd') ||
+        normalized.startsWith('fe8') ||
+        normalized.startsWith('fe9') ||
+        normalized.startsWith('fea') ||
+        normalized.startsWith('feb') ||
+        normalized.startsWith('ff') ||
+        normalized.startsWith('2001:db8:'));
+}
+export async function resolveSafeDownloadTarget(value) {
+    let url;
+    try {
+        url = value instanceof URL ? value : new URL(value);
+    }
+    catch {
+        throw new SourceImportError('unsafe-download-url', 'Figma returned an unsafe download target.');
+    }
+    if (url.protocol !== 'https:' ||
+        url.username !== '' ||
+        url.password !== '' ||
+        (url.port !== '' && url.port !== '443') ||
+        url.hostname === '' ||
+        url.hostname === 'localhost' ||
+        url.hostname.endsWith('.localhost') ||
+        url.hostname.endsWith('.local') ||
+        url.hostname.startsWith('[') ||
+        isIP(url.hostname) !== 0) {
+        throw new SourceImportError('unsafe-download-url', 'Figma returned an unsafe download target.');
+    }
+    let resolvedAddresses;
+    try {
+        resolvedAddresses = await lookup(url.hostname, { all: true });
+    }
+    catch {
+        throw new SourceImportError('unsafe-download-url', 'Figma returned an unavailable download target.');
+    }
+    if (resolvedAddresses.length === 0 ||
+        resolvedAddresses.some(({ address }) => isIP(address) === 0 || isForbiddenIp(address))) {
+        throw new SourceImportError('unsafe-download-url', 'Figma returned an unsafe download target.');
+    }
+    const addresses = resolvedAddresses.map(({ address }) => ({
+        address,
+        family: isIP(address)
+    }));
+    return { url, addresses };
+}
+export async function assertSafeDownloadUrl(value) {
+    return (await resolveSafeDownloadTarget(value)).url;
+}
+async function fetchWithDeadline(fetcher, url, init, consume) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetcher(url, { ...init, signal: controller.signal });
+        if (!response.ok)
+            throw upstreamStatusError(response);
+        return await consume(response);
+    }
+    catch (cause) {
+        if (controller.signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
+            throw new SourceImportError('download-timeout', 'Figma export timed out.');
+        }
+        if (cause instanceof SourceImportError)
+            throw cause;
+        throw new SourceImportError('upstream-failed', 'Figma export request failed.');
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function readLimitedBody(response, signal) {
+    let canceled = false;
+    const cancel = () => {
+        if (canceled)
+            return;
+        canceled = true;
+        response.cancel();
+    };
+    const declared = response.headers.get('content-length');
+    if (declared && /^\d+$/.test(declared) && Number(declared) > MAX_DOWNLOAD_BYTES) {
+        cancel();
+        throw new SourceImportError('download-too-large', 'Figma export exceeds the 50 MiB limit.');
+    }
+    const iterator = response.body[Symbol.asyncIterator]();
+    const chunks = [];
+    let size = 0;
+    let rejectAbort;
+    const aborted = new Promise((_, reject) => (rejectAbort = reject));
+    const onAbort = () => {
+        rejectAbort(new SourceImportError('download-timeout', 'Figma export download timed out.'));
+        cancel();
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        for (;;) {
+            const { done, value } = await Promise.race([iterator.next(), aborted]);
+            if (signal.aborted) {
+                throw new SourceImportError('download-timeout', 'Figma export download timed out.');
+            }
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_DOWNLOAD_BYTES) {
+                cancel();
+                throw new SourceImportError('download-too-large', 'Figma export exceeds the 50 MiB limit.');
+            }
+            chunks.push(value);
+        }
+    }
+    catch (cause) {
+        cancel();
+        throw cause;
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+async function downloadExport(transport, initial) {
+    let target = await resolveSafeDownloadTarget(initial);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        for (let redirects = 0;; redirects++) {
+            let response;
+            try {
+                response = await transport(target, controller.signal);
+            }
+            catch (cause) {
+                if (controller.signal.aborted || (cause instanceof Error && cause.name === 'AbortError')) {
+                    throw new SourceImportError('download-timeout', 'Figma export download timed out.');
+                }
+                throw new SourceImportError('upstream-failed', 'Figma export download failed.');
+            }
+            if (response.status >= 300 && response.status < 400) {
+                if (redirects >= MAX_REDIRECTS) {
+                    response.cancel();
+                    throw new SourceImportError('unsafe-download-url', 'Figma export redirected too many times.');
+                }
+                const location = response.headers.get('location');
+                if (!location) {
+                    response.cancel();
+                    throw new SourceImportError('invalid-response', 'Figma export redirect was invalid.');
+                }
+                response.cancel();
+                target = await resolveSafeDownloadTarget(new URL(location, target.url));
+                continue;
+            }
+            if (response.status < 200 || response.status >= 300) {
+                response.cancel();
+                throw upstreamStatusError(response);
+            }
+            return await readLimitedBody(response, controller.signal);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function validatePng(bytes) {
+    if (bytes.byteLength < PNG_SIGNATURE.byteLength ||
+        PNG_SIGNATURE.some((value, index) => bytes[index] !== value)) {
+        throw new SourceImportError('invalid-response', 'Figma export is not a valid PNG.');
+    }
+    let metadata;
+    try {
+        metadata = await sharp(bytes).metadata();
+    }
+    catch {
+        throw new SourceImportError('invalid-response', 'Figma export is not a readable PNG.');
+    }
+    if (!metadata.width || !metadata.height) {
+        throw new SourceImportError('invalid-response', 'Figma export has invalid dimensions.');
+    }
+    if (metadata.width * metadata.height > MAX_PIXELS) {
+        throw new SourceImportError('image-too-large', 'Figma export exceeds the 32 megapixel limit.');
+    }
+}
+async function materialize(source, context) {
+    const token = context.config.import.figma.token;
+    if (!token) {
+        throw new SourceImportError('not-configured', 'Figma access is not configured.');
+    }
+    const endpoint = new URL(`https://api.figma.com/v1/images/${encodeURIComponent(source.fileKey)}`);
+    endpoint.searchParams.set('ids', source.nodeId);
+    endpoint.searchParams.set('format', source.format);
+    endpoint.searchParams.set('scale', String(source.scale));
+    const jsonBytes = await fetchWithDeadline(context.fetch, endpoint, { redirect: 'error', headers: { 'X-Figma-Token': token } }, async (response) => new Uint8Array(await response.arrayBuffer()));
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(jsonBytes));
+    }
+    catch {
+        throw new SourceImportError('invalid-response', 'Figma returned an invalid response.');
+    }
+    const body = record(payload);
+    if (!body || body.err || (typeof body.status === 'number' && body.status >= 400)) {
+        throw new SourceImportError('invalid-response', 'Figma could not render this node.');
+    }
+    const images = record(body.images);
+    if (!images || !Object.hasOwn(images, source.nodeId)) {
+        throw new SourceImportError('invalid-response', 'Figma did not return the requested node.');
+    }
+    const imageUrl = images[source.nodeId];
+    if (typeof imageUrl !== 'string' || imageUrl.length === 0) {
+        throw new SourceImportError('invalid-response', 'Figma could not render the requested node.');
+    }
+    const bytes = await downloadExport(context.httpsTransport ?? requestPinnedHttps, imageUrl);
+    await validatePng(bytes);
+    const importSource = { importer: 'figma', parameters: source };
+    return { bytes, extension: 'png', importSource };
+}
+export const figmaSourceImporter = {
+    kind: 'figma',
+    label: 'Figma',
+    validateInput,
+    async importRaw(input, context) {
+        const parsed = parseFigmaSelectionUrl(input.url);
+        return materialize({
+            fileKey: parsed.fileKey,
+            nodeId: parsed.nodeId,
+            format: 'png',
+            scale: input.scale ?? context.config.import.figma.defaults.scale
+        }, context);
+    },
+    validateSourceParameters: validateFigmaSourceParameters,
+    async reimportRaw(source, context) {
+        return materialize(source, context);
+    }
+};

package/dist/server/importers/file.d.ts

@@ -0,0 +1,6 @@
+import { type ServerSourceImporter } from './contract.js';
+export interface FileImportInput {
+    fileName: string;
+    bytes: Uint8Array;
+}
+export declare const fileSourceImporter: ServerSourceImporter<FileImportInput, never>;

package/dist/server/importers/file.js

@@ -0,0 +1,33 @@
+import { extname } from 'node:path';
+import { SourceImportError } from './contract.js';
+function validate(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new SourceImportError('invalid-input', 'File import input must be an object.');
+    }
+    const input = value;
+    if (typeof input.fileName !== 'string' || input.fileName.length === 0) {
+        throw new SourceImportError('invalid-input', 'File import requires a file name.');
+    }
+    if (!(input.bytes instanceof Uint8Array)) {
+        throw new SourceImportError('invalid-input', 'File import requires byte data.');
+    }
+    return { fileName: input.fileName, bytes: input.bytes };
+}
+export const fileSourceImporter = {
+    kind: 'file',
+    label: 'File',
+    validateInput: validate,
+    async importRaw(input) {
+        const extension = extname(input.fileName).slice(1).toLowerCase();
+        if (!extension)
+            throw new SourceImportError('invalid-input', 'The file needs an extension.');
+        return {
+            bytes: input.bytes,
+            extension,
+            suggestedFileName: input.fileName
+        };
+    },
+    validateSourceParameters() {
+        throw new SourceImportError('invalid-input', 'File imports cannot be re-imported.');
+    }
+};

package/dist/server/importers/pinned-https.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage } from 'node:http';
+import { type RequestOptions } from 'node:https';
+import type { ClientRequest } from 'node:http';
+import type { LookupFunction } from 'node:net';
+export interface PinnedAddress {
+    address: string;
+    family: 4 | 6;
+}
+export interface PinnedHttpsTarget {
+    url: URL;
+    addresses: readonly PinnedAddress[];
+}
+export interface PinnedHttpsResponse {
+    status: number;
+    headers: Headers;
+    body: AsyncIterable<Uint8Array>;
+    cancel(): void;
+}
+export type PinnedHttpsTransport = (target: PinnedHttpsTarget, signal: AbortSignal) => Promise<PinnedHttpsResponse>;
+export type HttpsRequester = (url: URL, options: RequestOptions, onResponse: (response: IncomingMessage) => void) => ClientRequest;
+export declare function createPinnedLookup(target: PinnedHttpsTarget): LookupFunction;
+export declare function createPinnedHttpsTransport(requester?: HttpsRequester): PinnedHttpsTransport;
+export declare const requestPinnedHttps: PinnedHttpsTransport;

package/dist/server/importers/pinned-https.js

@@ -0,0 +1,60 @@
+import { request } from 'node:https';
+function lookupError(hostname) {
+    const error = new Error(`No validated address is available for ${hostname}.`);
+    error.code = 'ENOTFOUND';
+    return error;
+}
+export function createPinnedLookup(target) {
+    return (hostname, options, callback) => {
+        if (hostname !== target.url.hostname) {
+            callback(lookupError(hostname), '', 0);
+            return;
+        }
+        const requestedFamily = options.family === 4 || options.family === 6 ? options.family : 0;
+        const addresses = target.addresses.filter((candidate) => requestedFamily === 0 || candidate.family === requestedFamily);
+        if (addresses.length === 0) {
+            callback(lookupError(hostname), '', 0);
+            return;
+        }
+        if (options.all) {
+            callback(null, addresses.map(({ address, family }) => ({ address, family })));
+            return;
+        }
+        callback(null, addresses[0].address, addresses[0].family);
+    };
+}
+function responseHeaders(source) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(source)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(name, item);
+        }
+        else if (value !== undefined) {
+            headers.set(name, value);
+        }
+    }
+    return headers;
+}
+export function createPinnedHttpsTransport(requester = request) {
+    return (target, signal) => new Promise((resolve, reject) => {
+        const request = requester(target.url, {
+            method: 'GET',
+            agent: false,
+            lookup: createPinnedLookup(target),
+            servername: target.url.hostname,
+            rejectUnauthorized: true,
+            signal
+        }, (response) => {
+            resolve({
+                status: response.statusCode ?? 0,
+                headers: responseHeaders(response.headers),
+                body: response,
+                cancel: () => response.destroy()
+            });
+        });
+        request.once('error', reject);
+        request.end();
+    });
+}
+export const requestPinnedHttps = createPinnedHttpsTransport();

package/dist/server/importers/registry.d.ts

@@ -0,0 +1,12 @@
+import type { ImportSourceRecord } from '../../core/index.js';
+import { type ServerSourceImporter } from './contract.js';
+export declare class SourceImporterRegistry {
+    #private;
+    constructor(importers: readonly ServerSourceImporter[]);
+    require(kind: string): ServerSourceImporter;
+    has(kind: string): boolean;
+    requireReimport(source: ImportSourceRecord): {
+        importer: ServerSourceImporter;
+        parameters: unknown;
+    };
+}

package/dist/server/importers/registry.js

@@ -0,0 +1,31 @@
+import { SourceImportError } from './contract.js';
+export class SourceImporterRegistry {
+    #byKind = new Map();
+    constructor(importers) {
+        for (const importer of importers) {
+            if (!importer.kind)
+                throw new Error('Source importer kind must not be empty.');
+            if (this.#byKind.has(importer.kind)) {
+                throw new Error(`Duplicate source importer kind "${importer.kind}".`);
+            }
+            this.#byKind.set(importer.kind, importer);
+        }
+    }
+    require(kind) {
+        const importer = this.#byKind.get(kind);
+        if (!importer) {
+            throw new SourceImportError('invalid-input', `Unknown source importer "${kind}".`);
+        }
+        return importer;
+    }
+    has(kind) {
+        return this.#byKind.has(kind);
+    }
+    requireReimport(source) {
+        const importer = this.require(source.importer);
+        if (!importer.reimportRaw) {
+            throw new SourceImportError('invalid-input', `Source importer "${source.importer}" does not support re-import.`);
+        }
+        return { importer, parameters: importer.validateSourceParameters(source.parameters) };
+    }
+}

package/dist/server/importers.d.ts

@@ -0,0 +1,2 @@
+import { SourceImporterRegistry } from './importers/registry.js';
+export declare const serverImporters: SourceImporterRegistry;

package/dist/server/importers.js

@@ -0,0 +1,7 @@
+import { figmaSourceImporter } from './importers/figma.js';
+import { fileSourceImporter } from './importers/file.js';
+import { SourceImporterRegistry } from './importers/registry.js';
+export const serverImporters = new SourceImporterRegistry([
+    fileSourceImporter,
+    figmaSourceImporter
+]);

package/dist/server/library-store.d.ts

@@ -1,4 +1,4 @@
-import { type Library, type ValidationIssueDto } from '../core/index.js';
+import { type ImportSourceRecord, type Library, type ValidationIssueDto } from '../core/index.js';
 import type { ResolvedFundusConfig } from './config-loader.js';
 import type { ServerPluginRegistry } from './plugins/contract.js';
 export declare function assertSafeFileName(fileName: string): void;
@@ -23,6 +23,21 @@ export interface IngestOptions {
     /** Registered destination folder; empty string means the implicit root. */
     folder?: string;
 }
+export interface CreateAssetOptions extends IngestOptions {
+    manifests?: string[];
+    importSource?: ImportSourceRecord;
+}
+export interface CreateAssetStaging {
+    rawPath: string;
+    rawFileName: string;
+    parameters: unknown;
+}
+export interface ImportSourceExpectation {
+    raw: string;
+    rawHash: string;
+    type: string;
+    canonicalSource: string;
+}
 export interface ReplaceRawFileOptions {
     /** Original file name of the replacement (sanitized before storing). */
     fileName: string;
@@ -54,12 +69,15 @@ export declare class LibraryStore {
      * the owning plugin's default parameters. Returns the updated library.
      */
     ingest(options: IngestOptions): Promise<Library>;
+    createAsset(options: CreateAssetOptions, prepareParameters?: (staging: CreateAssetStaging) => Promise<unknown>): Promise<Library>;
     /**
      * Replace one asset's raw file while preserving its identity and authored
      * metadata. The replacement stays in the current folder, receives a safe
      * non-colliding name, and must be accepted by the asset's existing type.
      */
     replaceRawFile(id: string, options: ReplaceRawFileOptions): Promise<Library>;
+    /** CAS-protected replacement used only by a repeatable import source. */
+    replaceRawFromImportSource(id: string, bytes: Uint8Array, expected: ImportSourceExpectation, nextSource?: ImportSourceRecord): Promise<Library>;
     /** Replace an asset's parameters (validated by the owning plugin). */
     updateParameters(id: string, parameters: unknown): Promise<Library>;
     /** Replace an asset's manifest membership (every name must exist). */