@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/figma/figmaSnapshotBuilder.js

@@ -0,0 +1,314 @@
+// Figma Snapshot render orchestration + assembly (Epic #750, Issue #753).
+//
+// The SECOND and final Figma egress of the snapshot-build. For each detected screen FRAME id
+// (from #752's ScreenIrResult — NEVER the canvas root, which times out on `/v1/images`), it:
+//   1. requests an ephemeral render url from `GET /v1/images` (batched, minimal — heavy backoff is
+//      #759), authenticated with the read-only PAT in the `X-Figma-Token` header;
+//   2. downloads the PNG bytes from that ephemeral url via the injectable render port (no auth
+//      header — the url is pre-signed);
+//   3. assembles the immutable Snapshot value: per-screen IR + image + deterministic integrity
+//      hashes + provenance, with a `skippedScreens` list plus structural-only IR rows for any
+//      screen that failed to render.
+//
+// Once this returns, the Snapshot is the communication boundary: nothing downstream contacts
+// Figma. The token flows ONLY into the images-call header; it never reaches the snapshot value,
+// the render-url download, an error, or a log.
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+import { mapWithConcurrency } from "./figmaConcurrency.js";
+import { classifyTokenFailure } from "./figmaTokenSource.js";
+import { DEFAULT_FIGMA_RETRY_POLICY, fetchWithBackoff, realFigmaRetrySleep, } from "./figmaRetry.js";
+import { hashBytes, hashScreen, hashSnapshot, hashStructuralScreen } from "./figmaSnapshotHash.js";
+import { DEFAULT_SCOPED_PAGINATION_LIMITS, SCOPED_PAGINATION_LIMIT_CEILINGS, } from "./figmaScopedPagination.js";
+const FIGMA_API_ORIGIN = "https://api.figma.com";
+const SNAPSHOT_SCHEMA_VERSION = 1;
+const DEFAULT_RENDER_BATCH_SIZE = 20;
+const MAX_RENDER_BATCH_SIZE = 100;
+const DEFAULT_MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+const DEFAULT_RENDER_SCALE = 1;
+const DEFAULT_DOWNLOAD_CONCURRENCY = 4;
+// Bounded retries for a TRANSIENT malformed `/v1/images` body (a 2xx without an `images` map). Figma's
+// render endpoint returns this intermittently when overloaded by back-to-back whole-page builds; an
+// isolated retry recovers it. After this many retries the batch degrades to a skip rather than failing
+// the whole build (F8).
+const MAX_RENDER_BODY_RETRIES = 3;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const chunk = (items, size) => {
+    const safeSize = Number.isInteger(size) && size >= 1 ? size : DEFAULT_RENDER_BATCH_SIZE;
+    const out = [];
+    for (let i = 0; i < items.length; i += safeSize)
+        out.push(items.slice(i, i + safeSize));
+    return out;
+};
+const boundedPositiveInt = (value, fallback, ceiling) => {
+    if (value === undefined || !Number.isInteger(value) || value < 1)
+        return fallback;
+    return Math.min(value, ceiling);
+};
+// Returns true when the hostname is an IP literal or a local/loopback name that must be blocked.
+const isBlockedHostname = (h) => h.length === 0 ||
+    /^\d+\.\d+\.\d+\.\d+$/.test(h) ||
+    h.startsWith("[") ||
+    h === "localhost" ||
+    h.endsWith(".localhost") ||
+    h.endsWith(".local");
+// Validates that a render URL returned by the Figma API is safe to follow. Blocks http:
+// (plaintext) and IP-literal hostnames (RFC-1918, loopback, link-local) to prevent SSRF via
+// a compromised or MITM'd API response. A broad IP-block is preferred over a tight CDN
+// allowlist because Figma's pre-signed render URLs span multiple AWS S3 regions/CDN fronts.
+const isRenderUrlSafe = (raw) => {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "https:")
+        return false;
+    // Normalise: lowercase + strip exactly one trailing dot so "localhost." == "localhost".
+    const h = url.hostname.toLowerCase().replace(/\.$/, "");
+    if (isBlockedHostname(h))
+        return false;
+    if (!isAllowedFigmaRenderUrl(url, h))
+        return false;
+    // Only allow the default HTTPS port (443 or implicit) — non-standard ports indicate an
+    // internal service, not a CDN. url.port is "" when the port is the scheme default.
+    if (url.port !== "" && url.port !== "443")
+        return false;
+    return true;
+};
+const isAllowedFigmaRenderUrl = (url, host) => {
+    if (host === "s3-alpha-sig.figma.com")
+        return true;
+    if (host === "cdn.figma.com" || host === "static.figma.com")
+        return true;
+    if (host.endsWith(".figma.com"))
+        return true;
+    // Multi-region S3 bucket allowlist: accepts any globally-unique bucket whose NAME starts with
+    // "figma" (e.g. figma-prod.s3.eu-west-1.amazonaws.com). The residual risk is that an attacker
+    // who can create an S3 bucket named figma-anything could serve a crafted render response. In
+    // practice the risk is low: (a) render URLs are returned by the authenticated Figma API over
+    // TLS, so a MITM or API compromise is a prerequisite; (b) the URLs are short-lived/pre-signed
+    // and carry no Figma auth header (the token is injected only into the /v1/images API call);
+    // (c) the byte-cap + oversized-skip guard limits the blast radius of a poisoned response.
+    // Tightening to a fixed bucket list would break legitimate Figma render fronts that span many
+    // regions; revisit if Figma publishes an authoritative set of render origins.
+    if (/^figma[-a-z0-9]*\.s3[.-][a-z0-9-]+\.amazonaws\.com$/u.test(host))
+        return true;
+    if ((host === "s3-us-west-2.amazonaws.com" || host === "s3.us-west-2.amazonaws.com") &&
+        /^\/figma[-_/a-z0-9]*/iu.test(url.pathname)) {
+        return true;
+    }
+    return false;
+};
+const buildImagesUrl = (fileKey, ids, version) => {
+    const url = new URL(`${FIGMA_API_ORIGIN}/v1/images/${encodeURIComponent(fileKey)}`);
+    url.searchParams.set("ids", ids.join(","));
+    url.searchParams.set("format", "png");
+    url.searchParams.set("scale", String(DEFAULT_RENDER_SCALE));
+    if (version !== undefined && version.length > 0)
+        url.searchParams.set("version", version);
+    return url.toString();
+};
+const extractFigmaReason = (body) => {
+    if (!isRecord(body))
+        return undefined;
+    const reason = body.err ?? body.message;
+    return typeof reason === "string" ? reason : undefined;
+};
+const statusToError = (status, body) => classifyTokenFailure(status, extractFigmaReason(body));
+// Extracts the `{ images: { id: url|null } }` map from one `/v1/images` response, or `null` when the
+// body is a non-standard 2xx WITHOUT an `images` map. Figma's render endpoint returns such a body
+// intermittently when it is overloaded by back-to-back whole-page builds (#750 F8 — observed live).
+// `null` is a TRANSIENT, retriable signal — the caller retries the batch, then degrades the affected
+// screens to a skip (coverage notice) if it persists, rather than failing the whole build.
+const extractImageUrls = (json) => {
+    if (!isRecord(json) || !isRecord(json.images))
+        return null;
+    const out = {};
+    for (const [id, value] of Object.entries(json.images)) {
+        out[id] = typeof value === "string" && value.length > 0 ? value : null;
+    }
+    return out;
+};
+// Figma's render endpoint can reject a subset of otherwise readable screen node ids with a client
+// status (observed on large boards where some detected screen frames cannot be rendered). That is a
+// renderability problem, not an auth/egress/build integrity problem: keep the snapshot usable by
+// returning an empty render-url map for that batch so the affected screens become structural-only.
+// Auth/scope/proxy/rate-limit/upstream failures remain hard coded errors below.
+const isRenderEndpointSoftFailure = (status) => status === 400 || status === 404 || status === 422;
+// Resolve one `/v1/images` batch to its ephemeral-url map. The fetch is wrapped in the deterministic
+// 429 backoff; auth/scope/upstream non-2xx responses are hard coded errors, while renderability
+// client failures degrade this batch to structural-only. A 2xx with a malformed body is a transient
+// render-overload signal that is retried up to MAX_RENDER_BODY_RETRIES, then degrades to an empty map
+// so the affected screens skip (render-url-missing) instead of aborting the build (F8).
+const resolveRenderBatch = async (input, batch, policy, sleep) => {
+    const requestUrl = buildImagesUrl(input.provenance.fileKey, batch, input.provenance.version);
+    for (let attempt = 0;; attempt += 1) {
+        const response = await fetchWithBackoff(() => input.imagesPort({ url: requestUrl, headers: { "X-Figma-Token": input.token } }), policy, sleep);
+        if (response.status < 200 || response.status >= 300) {
+            if (isRenderEndpointSoftFailure(response.status))
+                return {};
+            throw statusToError(response.status, response.json);
+        }
+        const map = extractImageUrls(response.json);
+        if (map !== null)
+            return map;
+        if (attempt >= MAX_RENDER_BODY_RETRIES)
+            return {};
+        await sleep(Math.min(policy.baseDelayMs * 2 ** attempt, policy.maxDelayMs));
+    }
+};
+// Calls `/v1/images` in bounded batches and merges the ephemeral-url map. The token authenticates
+// each batch via the header only. Each batch is 429-backoff retried AND malformed-body retried
+// (resolveRenderBatch), so a rate-limited or transiently-overloaded huge-board render survives.
+const requestRenderUrls = async (input, screenIds) => {
+    const policy = input.retryPolicy ?? DEFAULT_FIGMA_RETRY_POLICY;
+    const sleep = input.sleep ?? realFigmaRetrySleep;
+    const batchSize = boundedPositiveInt(input.batchSize, DEFAULT_RENDER_BATCH_SIZE, MAX_RENDER_BATCH_SIZE);
+    const urls = new Map();
+    for (const batch of chunk(screenIds, batchSize)) {
+        const map = await resolveRenderBatch(input, batch, policy, sleep);
+        for (const id of batch)
+            urls.set(id, map[id] ?? null);
+    }
+    return urls;
+};
+const structuralOnly = (ir, reason) => ({
+    skipped: { screenId: ir.id, reason },
+    structuralScreen: {
+        screenId: ir.id,
+        ir,
+        reason,
+        integrityHash: hashStructuralScreen(ir.id, ir),
+    },
+});
+// Classifies a finished render download into a skip reason, or null when the bytes are usable.
+const renderSkipReason = (response, maxBytes) => {
+    if (response === null)
+        return "render-fetch-failed";
+    if (response.status < 200 || response.status >= 300)
+        return "render-fetch-failed";
+    if (response.bytes.length === 0)
+        return "render-empty";
+    if (response.bytes.length > maxBytes)
+        return "render-oversized";
+    return null;
+};
+// Hard-egress codes for the render-byte download host (S3/CDN — a DIFFERENT host than
+// api.figma.com). If the render port throws a FigmaConnectorError in this family, it means
+// TLS or proxy is misconfigured for the render CDN; swallowing it would yield a "successful"
+// snapshot with every screen skipped while hiding the root cause. Re-throw to abort the build,
+// consistent with the DEEP_FETCH_ABORT_CODES discipline in figmaScopedPagination.ts.
+// Using ReadonlySet<string> so this set is forward-compatible with the new codes
+// (FIGMA_PROXY_AUTH_REQUIRED, FIGMA_PROXY_BLOCKED_BY_POLICY) landing in a parallel change to
+// figmaConnectorErrors.ts without requiring a re-touch of this file.
+const RENDER_EGRESS_ABORT_CODES = new Set([
+    "FIGMA_TLS_CA_FAILURE",
+    "FIGMA_PROXY_UNREACHABLE",
+    "FIGMA_PROXY_EGRESS_FAILED",
+    "FIGMA_PROXY_AUTH_REQUIRED",
+    "FIGMA_PROXY_BLOCKED_BY_POLICY",
+]);
+// Classifies a render-port throw into a re-throw (hard egress abort) or a coded skip outcome.
+// Hard-egress errors abort the whole build — they affect every screen on the same host so
+// swallowing them would silently produce an empty snapshot.
+const classifyRenderError = (screenId, err) => {
+    if (err instanceof FigmaConnectorError) {
+        if (RENDER_EGRESS_ABORT_CODES.has(err.code))
+            throw err;
+        return { skipped: { screenId, reason: `render-fetch-failed:${err.code}` } };
+    }
+    return { skipped: { screenId, reason: "render-fetch-failed" } };
+};
+// Downloads one screen's render bytes and classifies the result into a kept screen or a skip.
+// A single screen failing after retries degrades to a skip (partial render), never aborting.
+// Exception: hard egress errors (TLS/proxy misconfiguration) abort via classifyRenderError.
+const resolveScreen = async (input, ir, renderUrl) => {
+    if (renderUrl === null)
+        return structuralOnly(ir, "render-url-missing");
+    if (!isRenderUrlSafe(renderUrl))
+        return structuralOnly(ir, "render-url-blocked");
+    const maxBytes = input.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
+    const policy = input.retryPolicy ?? DEFAULT_FIGMA_RETRY_POLICY;
+    const sleep = input.sleep ?? realFigmaRetrySleep;
+    let response;
+    try {
+        response = await fetchWithBackoff(() => input.renderPort({ url: renderUrl, headers: {} }), policy, sleep);
+    }
+    catch (err) {
+        const classified = classifyRenderError(ir.id, err);
+        if (classified.skipped !== undefined) {
+            return structuralOnly(ir, classified.skipped.reason);
+        }
+        return classified;
+    }
+    const reason = renderSkipReason(response, maxBytes);
+    if (reason !== null)
+        return structuralOnly(ir, reason);
+    const sha256 = hashBytes(response.bytes);
+    const screen = {
+        screenId: ir.id,
+        ir,
+        image: {
+            mimeType: "image/png",
+            bytes: response.bytes,
+            byteLength: response.bytes.length,
+            sha256,
+        },
+        integrityHash: hashScreen(ir.id, ir, sha256),
+    };
+    return { screen };
+};
+function collectSnapshotRows(outcomes, cappedScreens) {
+    const screens = [];
+    const skippedScreens = [];
+    const structuralScreens = [];
+    for (const outcome of outcomes) {
+        if (outcome.screen !== undefined)
+            screens.push(outcome.screen);
+        if (outcome.skipped !== undefined)
+            skippedScreens.push(outcome.skipped);
+        if (outcome.structuralScreen !== undefined)
+            structuralScreens.push(outcome.structuralScreen);
+    }
+    for (const ir of cappedScreens) {
+        const outcome = structuralOnly(ir, "render-screen-cap-exceeded");
+        if (outcome.skipped !== undefined)
+            skippedScreens.push(outcome.skipped);
+        if (outcome.structuralScreen !== undefined)
+            structuralScreens.push(outcome.structuralScreen);
+    }
+    return { screens, skippedScreens, structuralScreens };
+}
+/**
+ * Render the screens and assemble the immutable Figma Snapshot. Render failures degrade to a
+ * `skippedScreens` entry plus structural-only IR (partial render); a non-2xx `/v1/images` call is
+ * a hard coded error.
+ */
+export const buildFigmaSnapshot = async (input) => {
+    const maxScreensRendered = boundedPositiveInt(input.maxScreensRendered, DEFAULT_SCOPED_PAGINATION_LIMITS.maxScreensDeep, SCOPED_PAGINATION_LIMIT_CEILINGS.maxScreensDeep);
+    const renderableScreens = input.ir.screens.slice(0, maxScreensRendered);
+    const cappedScreens = input.ir.screens.slice(maxScreensRendered);
+    const screenIds = renderableScreens.map((screen) => screen.id);
+    const renderUrls = screenIds.length === 0
+        ? new Map()
+        : await requestRenderUrls(input, screenIds);
+    const concurrency = boundedPositiveInt(input.downloadConcurrency, DEFAULT_DOWNLOAD_CONCURRENCY, Number.MAX_SAFE_INTEGER);
+    const outcomes = await mapWithConcurrency(renderableScreens, concurrency, (ir) => resolveScreen(input, ir, renderUrls.get(ir.id) ?? null));
+    const { screens, skippedScreens, structuralScreens } = collectSnapshotRows(outcomes, cappedScreens);
+    return {
+        snapshotSchemaVersion: SNAPSHOT_SCHEMA_VERSION,
+        provenance: input.provenance,
+        screens,
+        skippedScreens,
+        structuralScreens,
+        // Carried verbatim from the Screen-IR (#752) for the navigation/flow graph (#811). NOT folded
+        // into the integrity hash below — `links` is non-identity metadata, so drift (#735) is stable.
+        links: input.ir.links,
+        integrityHash: hashSnapshot(SNAPSHOT_SCHEMA_VERSION, input.provenance.version, [
+            ...screens,
+            ...structuralScreens,
+        ]),
+    };
+};

package/dist/qualityIntelligence/figma/figmaSnapshotHash.d.ts

@@ -0,0 +1,18 @@
+import type { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+type ScreenIr = QualityIntelligenceFigma.ScreenIr;
+/** sha256 over the canonical per-screen identity: {screenId, ir, imageSha256}. */
+export declare const hashScreen: (screenId: string, ir: ScreenIr, imageSha256: string) => string;
+/** sha256 over a structural-only screen identity: {screenId, ir, structuralOnly:true}. */
+export declare const hashStructuralScreen: (screenId: string, ir: ScreenIr) => string;
+/**
+ * sha256 over the canonical snapshot identity: schema version + pinned Figma version + the
+ * per-screen hashes sorted by screenId. EXCLUDES `fetchedAt` so the hash is drift-stable across
+ * re-fetches of the same unchanged design.
+ */
+export declare const hashSnapshot: (snapshotSchemaVersion: number, version: string | undefined, perScreen: readonly {
+    readonly screenId: string;
+    readonly integrityHash: string;
+}[]) => string;
+export declare const hashBytes: (bytes: Uint8Array) => string;
+export {};
+//# sourceMappingURL=figmaSnapshotHash.d.ts.map

package/dist/qualityIntelligence/figma/figmaSnapshotHash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaSnapshotHash.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotHash.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAwDlD,kFAAkF;AAClF,eAAO,MAAM,UAAU,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,EAAE,aAAa,MAAM,KAAG,MACV,CAAC;AAExE,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,EAAE,IAAI,QAAQ,KAAG,MACU,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,uBAAuB,MAAM,EAC7B,SAAS,MAAM,GAAG,SAAS,EAC3B,WAAW,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EAAE,KAClF,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,OAAO,UAAU,KAAG,MACI,CAAC"}

package/dist/qualityIntelligence/figma/figmaSnapshotHash.js

@@ -0,0 +1,63 @@
+// Deterministic integrity hashing for the Figma Snapshot (Epic #750, Issue #753, drift #735).
+//
+// The hash is the drift identity: same unchanged design ⇒ byte-identical hash, regardless of when
+// it was fetched. We therefore canonicalise to a stable key order and EXCLUDE the wall-clock
+// `fetchedAt`. The snapshot identity is the pinned Figma `version` + the sorted per-screen
+// identities (each = screenId + structural IR + image content sha256, or a structural-only marker
+// for screens whose PNG render was deliberately skipped/could not be fetched). `version` and the IR
+// are deterministic outputs of #751/#752; the image sha is included so an unexpected render-byte
+// change surfaces as drift too, while structural-only screens still participate in drift detection.
+import { createHash } from "node:crypto";
+const sha256Hex = (input) => createHash("sha256").update(input, "utf8").digest("hex");
+// Stable stringify: object keys are emitted in sorted order at every depth so the serialisation is
+// independent of insertion order. Arrays keep their (already deterministic) order from #752.
+const canonical = (value) => {
+    if (value === undefined)
+        return "null";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    const record = value;
+    const entries = Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`);
+    return `{${entries.join(",")}}`;
+};
+// Keys excluded from the integrity hash. Using a static Set + Object.entries filter avoids both
+// dynamic-delete (no-dynamic-delete) and unused-var issues while keeping the whitelist explicit.
+const HASH_NEUTRAL_KEYS = new Set([
+    "textColor",
+    "backgroundColor",
+    "layout",
+    "sizing",
+    "cornerRadius",
+    "typography",
+]);
+const stripHashNeutralFields = (node) => {
+    const entries = Object.entries(node).filter(([key]) => key !== "children" && !HASH_NEUTRAL_KEYS.has(key));
+    return {
+        ...Object.fromEntries(entries),
+        children: node.children.map(stripHashNeutralFields),
+    };
+};
+const hashStableIr = (ir) => ({
+    ...ir,
+    root: stripHashNeutralFields(ir.root),
+});
+/** sha256 over the canonical per-screen identity: {screenId, ir, imageSha256}. */
+export const hashScreen = (screenId, ir, imageSha256) => sha256Hex(canonical({ imageSha256, ir: hashStableIr(ir), screenId }));
+/** sha256 over a structural-only screen identity: {screenId, ir, structuralOnly:true}. */
+export const hashStructuralScreen = (screenId, ir) => sha256Hex(canonical({ ir: hashStableIr(ir), screenId, structuralOnly: true }));
+/**
+ * sha256 over the canonical snapshot identity: schema version + pinned Figma version + the
+ * per-screen hashes sorted by screenId. EXCLUDES `fetchedAt` so the hash is drift-stable across
+ * re-fetches of the same unchanged design.
+ */
+export const hashSnapshot = (snapshotSchemaVersion, version, perScreen) => {
+    const screens = [...perScreen]
+        .sort((a, b) => (a.screenId < b.screenId ? -1 : a.screenId > b.screenId ? 1 : 0))
+        .map((s) => ({ integrityHash: s.integrityHash, screenId: s.screenId }));
+    return sha256Hex(canonical({ screens, snapshotSchemaVersion, version: version ?? null }));
+};
+export const hashBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");

package/dist/qualityIntelligence/figma/figmaSnapshotTypes.d.ts

@@ -0,0 +1,65 @@
+import type { QualityIntelligenceFigma } from "@oscharko-dev/keiko-quality-intelligence";
+import type { FigmaProvenance } from "./figmaConnector.js";
+type ScreenIr = QualityIntelligenceFigma.ScreenIr;
+/** The rendered image for one screen — raw bytes plus their content hash (tamper-evidence). */
+export interface FigmaRenderedImage {
+    readonly mimeType: "image/png";
+    readonly bytes: Uint8Array;
+    readonly byteLength: number;
+    readonly sha256: string;
+}
+/** One assembled screen: the structural IR plus its render. */
+export interface FigmaSnapshotScreen {
+    readonly screenId: string;
+    readonly ir: ScreenIr;
+    readonly image: FigmaRenderedImage;
+    /** sha256 over the canonical {screenId, ir, imageSha256} body — the per-screen drift identity. */
+    readonly integrityHash: string;
+}
+/** One screen whose structural IR is captured but no PNG side-file exists. */
+export interface FigmaSnapshotStructuralScreen {
+    readonly screenId: string;
+    readonly ir: ScreenIr;
+    readonly reason: FigmaSkippedScreenReason;
+    /** sha256 over the canonical {screenId, ir, structuralOnly:true} body. */
+    readonly integrityHash: string;
+}
+/** Why a detected screen produced no render and was excluded from `screens` (partial-render).
+ * The `render-fetch-failed` member also appears as `render-fetch-failed:<CODE>` when the fetch
+ * threw a FigmaConnectorError — the code suffix lets metrics distinguish an egress
+ * misconfiguration (e.g. `FIGMA_EGRESS_TIMEOUT`) from an unclassified network flake.
+ */
+export type FigmaSkippedScreenReason = "render-url-missing" | "render-url-blocked" | "render-screen-cap-exceeded" | "render-fetch-failed" | `render-fetch-failed:${string}` | "render-empty" | "render-oversized";
+export interface FigmaSkippedScreen {
+    readonly screenId: string;
+    readonly reason: FigmaSkippedScreenReason;
+}
+/**
+ * The immutable Figma Snapshot value. `integrityHash` is DETERMINISTIC for drift detection
+ * (#735): it is keyed on the pinned Figma `version` + the sorted per-screen identities, and
+ * deliberately EXCLUDES the wall-clock `fetchedAt` so two snapshots of the same unchanged design
+ * at different times hash identically. `provenance.fetchedAt` is retained for audit only.
+ */
+export interface FigmaSnapshot {
+    readonly snapshotSchemaVersion: 1;
+    readonly provenance: FigmaProvenance;
+    readonly screens: readonly FigmaSnapshotScreen[];
+    readonly skippedScreens: readonly FigmaSkippedScreen[];
+    /**
+     * Structural IR for screens that did not produce a PNG render. This keeps QI/code consumers from
+     * losing JSON evidence when render fan-out is capped or a single render fetch degrades. Optional
+     * for older snapshots/builders; new builds emit it for every skipped screen that has IR.
+     */
+    readonly structuralScreens?: readonly FigmaSnapshotStructuralScreen[];
+    /**
+     * Raw inter-screen transitions carried from the Screen-IR (#752) for the navigation/flow graph
+     * (#811). OPTIONAL and additive — a constructor that omits it (e.g. an older builder or a test
+     * fixture) yields a valid snapshot, and the navigation derivation degrades to zero nav items. NOT
+     * part of `integrityHash` — non-identity design metadata, so it never affects drift (#735).
+     * Downstream persistence stores it on the snapshot record additively.
+     */
+    readonly links?: readonly QualityIntelligenceFigma.InterScreenLink[];
+    readonly integrityHash: string;
+}
+export {};
+//# sourceMappingURL=figmaSnapshotTypes.d.ts.map

package/dist/qualityIntelligence/figma/figmaSnapshotTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaSnapshotTypes.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaSnapshotTypes.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,KAAK,QAAQ,GAAG,wBAAwB,CAAC,QAAQ,CAAC;AAElD,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,8EAA8E;AAC9E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAChC,oBAAoB,GACpB,oBAAoB,GACpB,4BAA4B,GAC5B,qBAAqB,GACrB,uBAAuB,MAAM,EAAE,GAC/B,cAAc,GACd,kBAAkB,CAAC;AAEvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,QAAQ,CAAC,cAAc,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAC;IACtE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,wBAAwB,CAAC,eAAe,EAAE,CAAC;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

package/dist/qualityIntelligence/figma/figmaSnapshotTypes.js

@@ -0,0 +1,13 @@
+// Figma Snapshot value types (Epic #750, Issue #753).
+//
+// The Snapshot is the immutable, self-contained artifact assembled at the end of the bounded
+// snapshot-build: per-screen IR (from #752) + the rendered PNG bytes + token-free provenance
+// (from #751) + per-screen and snapshot integrity hashes. Once assembled it is the communication
+// boundary — every downstream stage (#754 QI source, #755 codegen) reads ONLY this value and
+// NEVER re-contacts Figma.
+//
+// These are the IN-MEMORY assembly types produced by the builder. The persisted, redacted,
+// side-file-backed evidence shape lives in keiko-evidence (figmaSnapshot/schema.ts); the store
+// strips the inline bytes onto disk and records a side-file ref. NO token is present on any of
+// these types by construction.
+export {};

package/dist/qualityIntelligence/figma/figmaTokenSource.d.ts

@@ -0,0 +1,9 @@
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+export interface FigmaTokenSources {
+    readonly vaultToken?: string | undefined;
+    readonly configToken?: string | undefined;
+    readonly envToken?: string | undefined;
+}
+export declare function resolveFigmaToken(sources: FigmaTokenSources): string;
+export declare function classifyTokenFailure(status: number, reason?: string): FigmaConnectorError;
+//# sourceMappingURL=figmaTokenSource.d.ts.map

package/dist/qualityIntelligence/figma/figmaTokenSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaTokenSource.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaTokenSource.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,mBAAmB,EAAgC,MAAM,2BAA2B,CAAC;AAE9F,MAAM,WAAW,iBAAiB;IAGhC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAUD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAIpE;AA6BD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAGzF"}

package/dist/qualityIntelligence/figma/figmaTokenSource.js

@@ -0,0 +1,61 @@
+// Figma token-resolution seam + token-failure taxonomy (Epic #750, Issue #758).
+//
+// resolveFigmaToken is the single point the connector consults for the read-only PAT. Precedence is
+// vault > config > env, so the encrypted vault entry (#758) takes priority while the
+// FIGMA_ACCESS_TOKEN env var (#751) stays the dev default whenever no vault entry exists. The
+// resolved token is returned for use at the transport boundary only; the resolver itself never logs
+// it and never echoes any candidate value in the FIGMA_TOKEN_MISSING error.
+//
+// classifyTokenFailure maps a failing Figma/proxy HTTP response to a coded, user-actionable error.
+// It is PURE and STRUCTURAL: it keys off the HTTP status plus a small set of generic Figma reason
+// keywords (expired / revoked / scope), and defaults any unrecognised 403 to the safe
+// FIGMA_TOKEN_INVALID rather than guessing. No board-, file-, or message-specific tuning.
+import { FigmaConnectorError } from "./figmaConnectorErrors.js";
+const firstNonEmpty = (...candidates) => {
+    for (const candidate of candidates) {
+        const trimmed = (candidate ?? "").trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return undefined;
+};
+export function resolveFigmaToken(sources) {
+    const token = firstNonEmpty(sources.vaultToken, sources.configToken, sources.envToken);
+    if (token === undefined)
+        throw new FigmaConnectorError("FIGMA_TOKEN_MISSING");
+    return token;
+}
+const includesAny = (haystack, needles) => needles.some((needle) => haystack.includes(needle));
+// Structural reason buckets. Each is a small set of generic substrings that Figma uses across
+// files; none is tied to a specific board, file, or customer-supplied message.
+function classifyForbidden(reason) {
+    if (includesAny(reason, ["expired", "expire"]))
+        return "FIGMA_TOKEN_EXPIRED";
+    if (includesAny(reason, ["revoked", "revoke"]))
+        return "FIGMA_TOKEN_REVOKED";
+    if (includesAny(reason, ["scope", "permission", "not allowed", "forbidden access"])) {
+        return "FIGMA_INSUFFICIENT_SCOPE";
+    }
+    // Unknown 403 → safe default, never a guess.
+    return "FIGMA_TOKEN_INVALID";
+}
+function codeForStatus(status, reason) {
+    if (status === 401)
+        return "FIGMA_TOKEN_INVALID";
+    if (status === 403)
+        return classifyForbidden(reason);
+    if (status === 404)
+        return "FIGMA_NOT_FOUND";
+    // Forward-proxy auth is visible as 407. Other proxy failures arrive as OutboundHttpEgressError
+    // before this status classifier runs; raw upstream 502/504 responses must not be blamed on proxy
+    // egress because that sends operators to the wrong remediation path.
+    if (status === 407)
+        return "FIGMA_PROXY_EGRESS_FAILED";
+    if (status >= 500)
+        return "FIGMA_UPSTREAM_UNAVAILABLE";
+    return "FIGMA_INTERNAL";
+}
+export function classifyTokenFailure(status, reason) {
+    const normalised = (reason ?? "").toLowerCase();
+    return new FigmaConnectorError(codeForStatus(status, normalised));
+}

package/dist/qualityIntelligence/figma/figmaTokenStore.d.ts

@@ -0,0 +1,19 @@
+export type FigmaVaultKeySource = "env" | "keychain" | "keyfile";
+export interface ResolvedFigmaVaultKey {
+    readonly key: Buffer;
+    readonly source: FigmaVaultKeySource;
+}
+export type FigmaKeychainAccess = () => Buffer | undefined;
+export interface FigmaTokenStore {
+    readonly store: (token: string) => void;
+    readonly read: () => string | undefined;
+    readonly revoke: () => void;
+}
+export interface FigmaTokenStoreDeps {
+    readonly key: Buffer;
+    readonly storePath: string;
+}
+export declare const NO_FIGMA_KEYCHAIN: FigmaKeychainAccess;
+export declare function resolveFigmaVaultKey(env: Readonly<Record<string, string | undefined>>, vaultDir: string, keychainAccess?: FigmaKeychainAccess): ResolvedFigmaVaultKey;
+export declare function createFigmaTokenStore(deps: FigmaTokenStoreDeps): FigmaTokenStore;
+//# sourceMappingURL=figmaTokenStore.d.ts.map

package/dist/qualityIntelligence/figma/figmaTokenStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaTokenStore.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaTokenStore.ts"],"names":[],"mappings":"AAwCA,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACtC;AAID,MAAM,MAAM,mBAAmB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAqGD,eAAO,MAAM,iBAAiB,EAAE,mBAAqC,CAAC;AAEtE,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACjD,QAAQ,EAAE,MAAM,EAChB,cAAc,GAAE,mBAAqC,GACpD,qBAAqB,CAMvB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,mBAAmB,GAAG,eAAe,CA0BhF"}