@oscharko-dev/keiko 0.2.0-beta.3 → 0.2.0-beta.5

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/exportRoutes.js

@@ -12,8 +12,8 @@
 import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
 import { sha256Hex } from "@oscharko-dev/keiko-security";
 import { QualityIntelligenceExport } from "@oscharko-dev/keiko-quality-intelligence";
-import { loadQualityIntelligenceRun, loadQualityIntelligenceCandidates, } from "@oscharko-dev/keiko-evidence";
-import { loadRunReviewState, candidateReviewStateOf } from "./reviewStore.js";
+import { appendQualityIntelligenceExportRow, loadQualityIntelligenceRun, loadQualityIntelligenceCandidates, } from "@oscharko-dev/keiko-evidence";
+import { loadRunReviewState, candidateReviewStateOf, runReviewStateOf } from "./reviewStore.js";
 import { assemblePdf, assembleZipBundle } from "./exportAssembly.js";
 const ADAPTERS = new Set([
     ...QualityIntelligence.QUALITY_INTELLIGENCE_EXPORT_ADAPTERS,
@@ -27,7 +27,10 @@ const LOCAL_META = {
     json: { contentType: "application/json", ext: "json" },
     markdown: { contentType: "text/markdown", ext: "md" },
     "plain-text": { contentType: "text/plain", ext: "txt" },
-    "quality-center": { contentType: "text/plain", ext: "txt" },
+    // NOTE: no "quality-center" entry — it is a TMS adapter, so a non-dry-run request is rejected with
+    // 403 before LOCAL_META is consulted, and the dry-run path returns a preview object that never
+    // reads LOCAL_META. The `?? { text/plain, txt }` fallback at the materialised-response site covers
+    // any future non-TMS text adapter.
     pdf: { contentType: "application/pdf", ext: "pdf" },
     "zip-bundle": { contentType: "application/zip", ext: "zip" },
 };
@@ -85,6 +88,38 @@ function buildBundle(runId, adapter, candidates, createdAt) {
         contents,
     };
 }
+/**
+ * Build the export-evidence row for an export action (Issue #283, AC4). Records the target type, a
+ * deterministic artifact id, an integrity hash over the exported candidate ids, the redaction
+ * attestation (candidates were redacted at persist time), and whether the action was a dry-run.
+ */
+function buildExportEvidenceRow(runId, target, rows, dryRun) {
+    return {
+        id: `qi-export-${sha256Hex(`${runId}|${target}`).slice(0, 24)}`,
+        targetAdapter: target,
+        integrityHash: sha256Hex(JSON.stringify(rows.map((r) => r.id))),
+        redactionAttested: true,
+        dryRun,
+    };
+}
+/**
+ * Best-effort append of an export-evidence row for a 200 export action (Issue #283, AC4). A failed
+ * audit write must NOT withhold an already-computed local export from the user: the artifact has no
+ * external side effect, the run already exists on disk, and the manifest write is atomic so this path
+ * is rare. Swallow on failure rather than turning a successful export into a 500. No-op for error
+ * responses and for the disabled external-TMS path (which produces no artifact).
+ */
+function recordExportEvidence(runId, outcome, evidenceDir) {
+    if (outcome.evidence === undefined || outcome.result.status !== 200) {
+        return;
+    }
+    try {
+        appendQualityIntelligenceExportRow({ runId, export: outcome.evidence }, { evidenceDir });
+    }
+    catch {
+        // intentionally swallowed — see doc comment
+    }
+}
 function parseExportBody(body) {
     const adapter = body.adapter;
     if (typeof adapter !== "string" || !ADAPTERS.has(adapter))
@@ -99,6 +134,11 @@ function selectRows(rows, approvedOnly, runId, evidenceDir) {
     if (!approvedOnly)
         return rows;
     const review = loadRunReviewState(runId, evidenceDir);
+    // FIX E (Issue #282) — a reviewer can approve the whole RUN instead of each candidate. A
+    // run-level approval is an explicit approval of every candidate, so it satisfies approvedOnly
+    // (incl. the TMS adapters that force it). Otherwise fall back to the per-candidate filter.
+    if (runReviewStateOf(review) === "approved")
+        return rows;
     return rows.filter((r) => candidateReviewStateOf(review, r.id) === "approved");
 }
 async function readExportRequest(req) {
@@ -157,7 +197,11 @@ export async function handleQiExport(ctx, deps) {
         if (artifact === undefined || artifact.candidates.length === 0) {
             return errorResult(409, "QI_NO_CANDIDATES", "This run has no candidates to export.");
         }
-        return serialiseExport(id, parsed.request, artifact.candidates, evidenceDir);
+        const outcome = serialiseExport(id, parsed.request, artifact.candidates, evidenceDir);
+        // Emit audit evidence for every materialised export or dry-run preview (Issue #283, AC4). The
+        // append is best-effort and must not turn a successful export into a 500 — see recordExportEvidence.
+        recordExportEvidence(id, outcome, evidenceDir);
+        return outcome.result;
     }
     catch {
         return errorResult(500, "QI_EXPORT_FAILED", "Failed to build the export.");
@@ -190,16 +234,19 @@ function binaryResponse(runId, mode, rows) {
         bytes = assembleZipBundle(entries);
     }
     return {
-        status: 200,
-        body: {
-            dryRun: false,
-            adapter: mode,
-            filename: `${runId}.${meta.ext}`,
-            contentType: meta.contentType,
-            byteLen: bytes.length,
-            encoding: "base64",
-            body: Buffer.from(bytes).toString("base64"),
+        result: {
+            status: 200,
+            body: {
+                dryRun: false,
+                adapter: mode,
+                filename: `${runId}.${meta.ext}`,
+                contentType: meta.contentType,
+                byteLen: bytes.length,
+                encoding: "base64",
+                body: Buffer.from(bytes).toString("base64"),
+            },
         },
+        evidence: buildExportEvidenceRow(runId, mode, rows, false),
     };
 }
 function serialisedResponse(runId, request, rows) {
@@ -213,27 +260,33 @@ function serialisedResponse(runId, request, rows) {
     const serialized = QualityIntelligenceExport.serializeExportBundle(bundle, candidates);
     if (request.dryRun) {
         return {
-            status: 200,
-            body: {
-                dryRun: true,
-                adapter,
-                candidateCount: rows.length,
-                byteLen: serialized.byteLen,
-                preview: serialized.body.slice(0, 1200),
+            result: {
+                status: 200,
+                body: {
+                    dryRun: true,
+                    adapter,
+                    candidateCount: rows.length,
+                    byteLen: serialized.byteLen,
+                    preview: serialized.body.slice(0, 1200),
+                },
             },
+            evidence: buildExportEvidenceRow(runId, adapter, rows, true),
         };
     }
     const meta = LOCAL_META[adapter] ?? { contentType: "text/plain", ext: "txt" };
     return {
-        status: 200,
-        body: {
-            dryRun: false,
-            adapter,
-            filename: `${runId}.${meta.ext}`,
-            contentType: meta.contentType,
-            byteLen: serialized.byteLen,
-            body: serialized.body,
+        result: {
+            status: 200,
+            body: {
+                dryRun: false,
+                adapter,
+                filename: `${runId}.${meta.ext}`,
+                contentType: meta.contentType,
+                byteLen: serialized.byteLen,
+                body: serialized.body,
+            },
         },
+        evidence: buildExportEvidenceRow(runId, adapter, rows, false),
     };
 }
 function serialiseExport(runId, request, allRows, evidenceDir) {
@@ -243,10 +296,16 @@ function serialiseExport(runId, request, allRows, evidenceDir) {
     const approvedOnly = isTms ? true : request.approvedOnly;
     const rows = selectRows(allRows, approvedOnly, runId, evidenceDir);
     if (rows.length === 0) {
-        return errorResult(409, "QI_NOTHING_TO_EXPORT", approvedOnly ? "No approved candidates to export." : "No candidates to export.");
+        return {
+            result: errorResult(409, "QI_NOTHING_TO_EXPORT", approvedOnly ? "No approved candidates to export." : "No candidates to export."),
+        };
     }
     if (isTms && !request.dryRun) {
-        return errorResult(403, "QI_EXTERNAL_EXPORT_DISABLED", "External TMS export is disabled. Configure the connector and use a dry-run preview.");
+        // External TMS write is disabled — no artifact is produced, so no export-evidence row is
+        // recorded for this rejected action.
+        return {
+            result: errorResult(403, "QI_EXTERNAL_EXPORT_DISABLED", "External TMS export is disabled. Configure the connector and use a dry-run preview."),
+        };
     }
     return serialisedResponse(runId, request, rows);
 }

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaConnectorErrors.d.ts

@@ -1,4 +1,4 @@
-export type FigmaConnectorErrorCode = "FIGMA_MALFORMED_URL" | "FIGMA_TOKEN_MISSING" | "FIGMA_CONSENT_REQUIRED" | "FIGMA_TOKEN_INVALID" | "FIGMA_TOKEN_EXPIRED" | "FIGMA_TOKEN_REVOKED" | "FIGMA_NOT_FOUND" | "FIGMA_INSUFFICIENT_SCOPE" | "FIGMA_RENDER_FAILED" | "FIGMA_PROXY_EGRESS_FAILED" | "FIGMA_PROXY_UNREACHABLE" | "FIGMA_TLS_CA_FAILURE" | "FIGMA_OVERSIZED_SCOPE" | "FIGMA_RATE_LIMITED" | "FIGMA_UPSTREAM_UNAVAILABLE" | "FIGMA_INTERNAL";
+export type FigmaConnectorErrorCode = "FIGMA_MALFORMED_URL" | "FIGMA_TOKEN_MISSING" | "FIGMA_CONSENT_REQUIRED" | "FIGMA_TOKEN_INVALID" | "FIGMA_TOKEN_EXPIRED" | "FIGMA_TOKEN_REVOKED" | "FIGMA_NOT_FOUND" | "FIGMA_INSUFFICIENT_SCOPE" | "FIGMA_RENDER_FAILED" | "FIGMA_PROXY_EGRESS_FAILED" | "FIGMA_PROXY_UNREACHABLE" | "FIGMA_PROXY_AUTH_REQUIRED" | "FIGMA_PROXY_BLOCKED_BY_POLICY" | "FIGMA_TLS_CA_FAILURE" | "FIGMA_OVERSIZED_SCOPE" | "FIGMA_RESPONSE_TOO_LARGE" | "FIGMA_RATE_LIMITED" | "FIGMA_UPSTREAM_UNAVAILABLE" | "FIGMA_NETWORK_UNREACHABLE" | "FIGMA_EGRESS_TIMEOUT" | "FIGMA_EGRESS_FAILED" | "FIGMA_BUILD_TIMEOUT" | "FIGMA_INTERNAL";
 export interface FigmaConnectorErrorBody {
     readonly error: {
         readonly code: FigmaConnectorErrorCode;
@@ -13,7 +13,15 @@ export declare class FigmaConnectorError extends Error {
 /**
  * Classify a transport-level throw from `fetch` or the body read into a stable
  * {@link FigmaConnectorErrorCode}. Side-effect-free and total — any non-Error
- * throwable (string, undefined) maps to `FIGMA_PROXY_EGRESS_FAILED`.
+ * throwable (string, undefined) maps to `FIGMA_EGRESS_FAILED`.
+ *
+ * Precedence:
+ *   (a) OutboundHttpEgressError (or plain Error with outbound code, for cross-package resilience)
+ *       → proxy/TLS-via-proxy codes. FIGMA_PROXY_* codes are ONLY reachable via this branch.
+ *   (b) TLS trust codes / messages → FIGMA_TLS_CA_FAILURE.
+ *   (c) Timeout / abort names (DOMException AbortError, Node TimeoutError) → FIGMA_EGRESS_TIMEOUT.
+ *   (d) Direct connectivity codes / messages → FIGMA_NETWORK_UNREACHABLE.
+ *   (e) Default → FIGMA_EGRESS_FAILED.
  *
  * Inspects `err.code`, `err.cause.code`, and `err.message` in that order of
  * precedence so Node.js `TypeError: fetch failed` wrappers (undici wraps the

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaConnectorErrors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaConnectorErrors.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaConnectorErrors.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,uBAAuB,GAC/B,qBAAqB,GACrB,qBAAqB,GACrB,wBAAwB,GACxB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,GACrB,iBAAiB,GACjB,0BAA0B,GAC1B,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,sBAAsB,GACtB,uBAAuB,GACvB,oBAAoB,GACpB,4BAA4B,GAC5B,gBAAgB,CAAC;AAmCrB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtF;AAED,eAAO,MAAM,uBAAuB,GAClC,MAAM,uBAAuB,KAC5B,uBAED,CAAC;AAEH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;gBAE3B,IAAI,EAAE,uBAAuB;CAK1C;AA6DD;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GAAI,KAAK,OAAO,KAAG,uBAa1D,CAAC"}
+{"version":3,"file":"figmaConnectorErrors.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaConnectorErrors.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,uBAAuB,GAC/B,qBAAqB,GACrB,qBAAqB,GACrB,wBAAwB,GACxB,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,GACrB,iBAAiB,GACjB,0BAA0B,GAC1B,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,GAC3B,+BAA+B,GAC/B,sBAAsB,GACtB,uBAAuB,GACvB,0BAA0B,GAC1B,oBAAoB,GACpB,4BAA4B,GAC5B,2BAA2B,GAC3B,sBAAsB,GACtB,qBAAqB,GACrB,qBAAqB,GACrB,gBAAgB,CAAC;AAgDrB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtF;AAED,eAAO,MAAM,uBAAuB,GAClC,MAAM,uBAAuB,KAC5B,uBAED,CAAC;AAEH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;gBAE3B,IAAI,EAAE,uBAAuB;CAK1C;AA0JD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,GAAI,KAAK,OAAO,KAAG,uBAa1D,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaConnectorErrors.js

@@ -1,26 +1,32 @@
-// Figma connector error shapes (Epic #750, Issues #751, #758, #760).
+// Figma connector error shapes (Epic #750, Issues #751, #758, #760, #884).
 //
 // Coded, safe errors for the server-side Figma connector. A FigmaConnectorError carries
 // ONLY a stable code and a fixed, secret-free message — never the PAT, never a raw Figma
 // payload, never an outbound URL or header value. Mirrors the QI connector error posture
 // in ../connectorErrors.ts so the route tier can serialise it consistently.
 //
-// Complete coded taxonomy (#760); every code is user-actionable. Each ticket-named category maps to
-// one or more codes below:
+// Complete coded taxonomy (#760, #884); every code is user-actionable. Each ticket-named
+// category maps to one or more codes below:
 //   auth          → FIGMA_TOKEN_MISSING | FIGMA_TOKEN_INVALID | FIGMA_TOKEN_EXPIRED
 //                   | FIGMA_TOKEN_REVOKED
 //   consent       → FIGMA_CONSENT_REQUIRED (no recorded read-only-scope acknowledgement)
 //   scope         → FIGMA_INSUFFICIENT_SCOPE
 //   rate-limit    → FIGMA_RATE_LIMITED
 //   not-found     → FIGMA_NOT_FOUND
-//   oversized     → FIGMA_OVERSIZED_SCOPE
+//   oversized     → FIGMA_OVERSIZED_SCOPE | FIGMA_RESPONSE_TOO_LARGE
 //   render-failed → FIGMA_RENDER_FAILED
-//   proxy egress  → FIGMA_PROXY_UNREACHABLE (proxy not reachable / egress refused)
-//                   | FIGMA_PROXY_EGRESS_FAILED (generic egress failure, retained for back-compat)
+//   proxy egress  → FIGMA_PROXY_UNREACHABLE (proxy host unreachable)
+//                   | FIGMA_PROXY_AUTH_REQUIRED (proxy requires authentication)
+//                   | FIGMA_PROXY_BLOCKED_BY_POLICY (proxy denied the request by policy)
+//                   | FIGMA_PROXY_EGRESS_FAILED (generic proxy egress failure, retained for back-compat)
+//   direct egress → FIGMA_NETWORK_UNREACHABLE (DNS/connection/socket error, no proxy)
+//                   | FIGMA_EGRESS_TIMEOUT (request timed out before completion)
+//                   | FIGMA_EGRESS_FAILED (generic direct egress failure; new default)
 //   tls/ca        → FIGMA_TLS_CA_FAILURE (custom-CA / TLS verification failure on egress)
 // FIGMA_MALFORMED_URL, FIGMA_UPSTREAM_UNAVAILABLE, and FIGMA_INTERNAL cover input and last-resort
 // faults. The proxy-aware + custom-CA HTTP client itself is #802; this connector only SURFACES
 // these proxy/TLS codes — it does not implement the proxy transport.
+import { OutboundHttpEgressError, } from "@oscharko-dev/keiko-model-gateway/internal/http";
 const SAFE_MESSAGES = {
     FIGMA_MALFORMED_URL: "The supplied link is not a scoped Figma node link. Paste a board or section link that includes a node id.",
     FIGMA_TOKEN_MISSING: "The Figma connector is not configured. Set a read-only access token before fetching a board.",
@@ -33,10 +39,17 @@ const SAFE_MESSAGES = {
     FIGMA_RENDER_FAILED: "Figma could not render the requested screens. Re-run the snapshot; if it persists, connect a narrower section.",
     FIGMA_PROXY_EGRESS_FAILED: "The Figma request could not be routed through the platform egress proxy. Check proxy connectivity and try again.",
     FIGMA_PROXY_UNREACHABLE: "The platform egress proxy is unreachable. Check the proxy host and port and try again.",
+    FIGMA_PROXY_AUTH_REQUIRED: "The forward proxy requires authentication for the Figma egress request. Configure proxy credentials or an allow rule.",
+    FIGMA_PROXY_BLOCKED_BY_POLICY: "The forward proxy blocked the Figma egress request by policy. Ask the proxy operator to allow api.figma.com and the Figma render hosts.",
     FIGMA_TLS_CA_FAILURE: "The TLS certificate for the Figma egress could not be verified. Check the configured certificate authority bundle and try again.",
     FIGMA_OVERSIZED_SCOPE: "The requested Figma node subtree is too large for a single scoped fetch. Connect a narrower section.",
+    FIGMA_RESPONSE_TOO_LARGE: "The Figma API response exceeded the maximum allowed size. Connect a narrower section to reduce the response.",
     FIGMA_RATE_LIMITED: "Figma rate-limited the snapshot-build after repeated retries. Wait a moment and re-run the snapshot.",
     FIGMA_UPSTREAM_UNAVAILABLE: "The Figma service is currently unavailable. Try the scoped fetch again later.",
+    FIGMA_NETWORK_UNREACHABLE: "The outbound network request to Figma failed (DNS, connection, or socket error). Check network connectivity and egress policy.",
+    FIGMA_EGRESS_TIMEOUT: "The Figma request timed out before completing. Retry; if it persists, raise KEIKO_FIGMA_REQUEST_TIMEOUT_MS or check upstream latency.",
+    FIGMA_EGRESS_FAILED: "The outbound request to Figma failed before a response was received.",
+    FIGMA_BUILD_TIMEOUT: "The snapshot build exceeded the configured deadline. No partial snapshot was stored. Retry or raise KEIKO_FIGMA_BUILD_DEADLINE_MS.",
     FIGMA_INTERNAL: "The Figma connector could not service the request.",
 };
 export const figmaConnectorErrorBody = (code) => ({
@@ -60,7 +73,9 @@ const TLS_CODES = new Set([
     "UNABLE_TO_GET_ISSUER_CERT",
     "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
 ]);
-// Node.js / undici error codes that indicate a connectivity / DNS / timeout failure.
+// Node.js / undici error codes that indicate a direct connectivity / DNS / socket failure.
+// These are only reached when the error did NOT come through the OutboundHttpEgressError proxy
+// path — a raw ECONNREFUSED means no proxy is involved.
 const CONNECTIVITY_CODES = new Set([
     "ECONNREFUSED",
     "ECONNRESET",
@@ -71,20 +86,34 @@ const CONNECTIVITY_CODES = new Set([
     "ECONNABORTED",
     "EHOSTUNREACH",
     "ENETUNREACH",
+    "EPROTO",
+    "EPERM",
+    "EACCES",
     "UND_ERR_CONNECT_TIMEOUT",
     "UND_ERR_HEADERS_TIMEOUT",
     "UND_ERR_BODY_TIMEOUT",
     "UND_ERR_SOCKET",
 ]);
-const OUTBOUND_TLS_CODES = new Set(["TLS_CA_FAILURE"]);
-const OUTBOUND_PROXY_UNREACHABLE_CODES = new Set(["PROXY_UNREACHABLE"]);
-const OUTBOUND_PROXY_EGRESS_CODES = new Set([
+// Mapping from OutboundHttpEgressError codes (proxy path) to FigmaConnectorErrorCodes.
+// FIGMA_PROXY_* codes are ONLY reachable through the OutboundHttpEgressError branch.
+const OUTBOUND_CODE_TO_FIGMA = {
+    TLS_CA_FAILURE: "FIGMA_TLS_CA_FAILURE",
+    PROXY_UNREACHABLE: "FIGMA_PROXY_UNREACHABLE",
+    PROXY_AUTH_REQUIRED: "FIGMA_PROXY_AUTH_REQUIRED",
+    PROXY_BLOCKED_BY_POLICY: "FIGMA_PROXY_BLOCKED_BY_POLICY",
+    PROXY_EGRESS_FAILED: "FIGMA_PROXY_EGRESS_FAILED",
+};
+// String set of OutboundHttpEgressError codes for cross-package-boundary instanceof fallback.
+const OUTBOUND_EGRESS_CODES = new Set([
+    "TLS_CA_FAILURE",
+    "PROXY_UNREACHABLE",
     "PROXY_AUTH_REQUIRED",
     "PROXY_BLOCKED_BY_POLICY",
     "PROXY_EGRESS_FAILED",
 ]);
 const TLS_MSG_RE = /cert|self.?signed|unable to (?:verify|get).*(issuer|cert)|tls/i;
-const CONNECTIVITY_MSG_RE = /socket hang ?up|network|timeout|fetch failed|econn|enotfound/i;
+// "fetch failed" is the Node.js TypeError message for generic direct-network failures (undici).
+const CONNECTIVITY_MSG_RE = /socket hang ?up|network|fetch failed|econn|enotfound/i;
 const extractCode = (err) => {
     if (err !== null && typeof err === "object") {
         const code = err.code;
@@ -106,33 +135,84 @@ const extractMessage = (err) => {
         return err;
     return "";
 };
+const extractName = (err) => {
+    if (err !== null && typeof err === "object") {
+        const name = err.name;
+        if (typeof name === "string")
+            return name;
+    }
+    return "";
+};
+const extractCause = (err) => err !== null && typeof err === "object" ? err.cause : undefined;
+/** Map an outbound egress code string to a FigmaConnectorErrorCode, or return undefined. */
+const mapOutboundCode = (code) => {
+    if (!OUTBOUND_EGRESS_CODES.has(code))
+        return undefined;
+    return OUTBOUND_CODE_TO_FIGMA[code] ?? "FIGMA_PROXY_EGRESS_FAILED";
+};
+// Cross-package-boundary fallback: plain Error with a string .code in the outbound set.
+// Used when instanceof check fails because OutboundHttpEgressError came from a different
+// package copy (e.g. stale dist during tests).
+const mapOutboundCodeFallback = (topCode, causeCode) => {
+    if (topCode !== undefined && OUTBOUND_EGRESS_CODES.has(topCode)) {
+        return mapOutboundCode(topCode) ?? "FIGMA_PROXY_EGRESS_FAILED";
+    }
+    if (causeCode !== undefined && OUTBOUND_EGRESS_CODES.has(causeCode)) {
+        return mapOutboundCode(causeCode) ?? "FIGMA_PROXY_EGRESS_FAILED";
+    }
+    return undefined;
+};
+// (a) OutboundHttpEgressError path — a proxy was genuinely in play.
+// FIGMA_PROXY_* codes are ONLY reachable through this function.
+const classifyOutbound = (err, cause, topCode, causeCode) => {
+    const outbound = err instanceof OutboundHttpEgressError
+        ? err
+        : cause instanceof OutboundHttpEgressError
+            ? cause
+            : undefined;
+    if (outbound !== undefined)
+        return mapOutboundCode(outbound.code) ?? "FIGMA_PROXY_EGRESS_FAILED";
+    return mapOutboundCodeFallback(topCode, causeCode);
+};
+// (b) TLS by code or message.
+const classifyTls = (code, msg) => (code !== undefined && TLS_CODES.has(code)) || TLS_MSG_RE.test(msg)
+    ? "FIGMA_TLS_CA_FAILURE"
+    : undefined;
+// (c) Timeout / abort names — check both err and its cause.
+const isAbortName = (name) => name === "TimeoutError" || name === "AbortError";
+const classifyTimeout = (err, cause) => isAbortName(extractName(err)) || isAbortName(extractName(cause))
+    ? "FIGMA_EGRESS_TIMEOUT"
+    : undefined;
+// (d) Direct connectivity codes / messages — no proxy involved.
+const classifyConnectivity = (code, msg) => (code !== undefined && CONNECTIVITY_CODES.has(code)) || CONNECTIVITY_MSG_RE.test(msg)
+    ? "FIGMA_NETWORK_UNREACHABLE"
+    : undefined;
 /**
  * Classify a transport-level throw from `fetch` or the body read into a stable
  * {@link FigmaConnectorErrorCode}. Side-effect-free and total — any non-Error
- * throwable (string, undefined) maps to `FIGMA_PROXY_EGRESS_FAILED`.
+ * throwable (string, undefined) maps to `FIGMA_EGRESS_FAILED`.
+ *
+ * Precedence:
+ *   (a) OutboundHttpEgressError (or plain Error with outbound code, for cross-package resilience)
+ *       → proxy/TLS-via-proxy codes. FIGMA_PROXY_* codes are ONLY reachable via this branch.
+ *   (b) TLS trust codes / messages → FIGMA_TLS_CA_FAILURE.
+ *   (c) Timeout / abort names (DOMException AbortError, Node TimeoutError) → FIGMA_EGRESS_TIMEOUT.
+ *   (d) Direct connectivity codes / messages → FIGMA_NETWORK_UNREACHABLE.
+ *   (e) Default → FIGMA_EGRESS_FAILED.
  *
  * Inspects `err.code`, `err.cause.code`, and `err.message` in that order of
  * precedence so Node.js `TypeError: fetch failed` wrappers (undici wraps the
  * underlying `cause.code`) are classified correctly.
  */
 export const classifyFigmaTransportError = (err) => {
-    const code = extractCode(err) ?? extractCauseCode(err);
-    if (code !== undefined) {
-        if (OUTBOUND_TLS_CODES.has(code))
-            return "FIGMA_TLS_CA_FAILURE";
-        if (OUTBOUND_PROXY_UNREACHABLE_CODES.has(code))
-            return "FIGMA_PROXY_UNREACHABLE";
-        if (OUTBOUND_PROXY_EGRESS_CODES.has(code))
-            return "FIGMA_PROXY_EGRESS_FAILED";
-        if (TLS_CODES.has(code))
-            return "FIGMA_TLS_CA_FAILURE";
-        if (CONNECTIVITY_CODES.has(code))
-            return "FIGMA_PROXY_UNREACHABLE";
-    }
+    const cause = extractCause(err);
+    const topCode = extractCode(err);
+    const causeCode = extractCauseCode(err);
+    const code = topCode ?? causeCode;
     const msg = extractMessage(err);
-    if (TLS_MSG_RE.test(msg))
-        return "FIGMA_TLS_CA_FAILURE";
-    if (CONNECTIVITY_MSG_RE.test(msg))
-        return "FIGMA_PROXY_UNREACHABLE";
-    return "FIGMA_PROXY_EGRESS_FAILED";
+    return (classifyOutbound(err, cause, topCode, causeCode) ??
+        classifyTls(code, msg) ??
+        classifyTimeout(err, cause) ??
+        classifyConnectivity(code, msg) ??
+        "FIGMA_EGRESS_FAILED");
 };

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaHttpPort.d.ts

@@ -9,11 +9,20 @@ export interface FigmaHttpResponse {
     readonly headers: Readonly<Record<string, string>>;
 }
 export type FigmaHttpPort = (request: FigmaHttpRequest) => Promise<FigmaHttpResponse>;
+/** Optional creation-time overrides for the default HTTP port. */
+export interface FigmaHttpPortOptions {
+    readonly timeoutMs?: number;
+    readonly maxResponseBytes?: number;
+}
 /**
  * Thin default adapter over the platform `fetch`. This is the ONLY place `fetch` is named.
- * It forwards the caller-built headers verbatim and reads the body as JSON; it does not
- * log, retry, or inspect the token. Resilience/backoff is out of scope here (#759); the
- * proxy/custom-CA transport is the platform prerequisite (#802) that replaces this adapter.
+ * It forwards the caller-built headers verbatim and reads the body as JSON with an explicit
+ * byte cap; it does not log, retry, or inspect the token. Resilience/backoff is out of scope
+ * here (#759); the proxy/custom-CA transport is the platform prerequisite (#802) that replaces
+ * this adapter.
+ *
+ * `redirect: "manual"` prevents the PAT auth header from following a cross-origin redirect.
+ * A 3xx response surfaces as a non-2xx port result; the connector treats non-2xx as upstream error.
  */
-export declare const createDefaultFigmaHttpPort: (egress?: OutboundHttpEgressConfig, fetchImpl?: typeof fetch) => FigmaHttpPort;
+export declare const createDefaultFigmaHttpPort: (egress?: OutboundHttpEgressConfig, fetchImpl?: typeof fetch, options?: FigmaHttpPortOptions) => FigmaHttpPort;
 //# sourceMappingURL=figmaHttpPort.d.ts.map

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaHttpPort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaHttpPort.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaHttpPort.ts"],"names":[],"mappings":"AAYA,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,iDAAiD,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAGvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAsBtF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,wBAAwB,EACjC,YAAY,OAAO,KAAK,KACvB,aAiBF,CAAC"}
+{"version":3,"file":"figmaHttpPort.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaHttpPort.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,iDAAiD,CAAC;AAQzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAGvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEtF,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAYD;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,wBAAwB,EACjC,YAAY,OAAO,KAAK,EACxB,UAAU,oBAAoB,KAC7B,aA4BF,CAAC"}

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaHttpPort.js

@@ -8,8 +8,16 @@
 // `X-Figma-Token` auth header). The token is materialised into that header ONLY by the
 // default adapter below, immediately before the platform `fetch` call — it is never
 // logged here and never re-emitted by the port.
+//
+// redirect: "manual" is set so the PAT auth header can never silently follow a
+// cross-origin redirect. A 3xx response surfaces as a non-2xx status; the connector
+// layer treats any non-2xx as an upstream error.
 import { classifyFigmaTransportError, FigmaConnectorError } from "./figmaConnectorErrors.js";
-import { gatewayFetch, } from "@oscharko-dev/keiko-model-gateway/internal/http";
+import { gatewayFetch, readJsonCapped, } from "@oscharko-dev/keiko-model-gateway/internal/http";
+/** Default request timeout in milliseconds for Figma HTTP API calls. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Default maximum JSON response body size (10 MiB). */
+const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 // Collects the response headers into a plain lower-cased map. `Headers` already lower-cases
 // names, so this is a faithful, allocation-bounded copy with no token (request-only header).
 const collectHeaders = (response) => {
@@ -19,34 +27,38 @@ const collectHeaders = (response) => {
     });
     return out;
 };
-const parseJsonBody = async (response) => {
-    const text = await response.text();
-    if (text.length === 0)
-        return undefined;
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-};
 /**
  * Thin default adapter over the platform `fetch`. This is the ONLY place `fetch` is named.
- * It forwards the caller-built headers verbatim and reads the body as JSON; it does not
- * log, retry, or inspect the token. Resilience/backoff is out of scope here (#759); the
- * proxy/custom-CA transport is the platform prerequisite (#802) that replaces this adapter.
+ * It forwards the caller-built headers verbatim and reads the body as JSON with an explicit
+ * byte cap; it does not log, retry, or inspect the token. Resilience/backoff is out of scope
+ * here (#759); the proxy/custom-CA transport is the platform prerequisite (#802) that replaces
+ * this adapter.
+ *
+ * `redirect: "manual"` prevents the PAT auth header from following a cross-origin redirect.
+ * A 3xx response surfaces as a non-2xx port result; the connector treats non-2xx as upstream error.
  */
-export const createDefaultFigmaHttpPort = (egress, fetchImpl) => {
+export const createDefaultFigmaHttpPort = (egress, fetchImpl, options) => {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = options?.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
     return async (request) => {
+        const signal = AbortSignal.timeout(timeoutMs);
         try {
             const response = await gatewayFetch(request.url, {
                 method: "GET",
                 headers: { ...request.headers },
+                redirect: "manual",
+                signal,
                 ...(egress !== undefined ? { egress } : {}),
                 ...(fetchImpl !== undefined ? { fetchImpl } : {}),
             });
             const headers = collectHeaders(response);
-            const json = await parseJsonBody(response);
+            let json;
+            try {
+                json = await readJsonCapped(response, maxResponseBytes);
+            }
+            catch {
+                throw new FigmaConnectorError("FIGMA_RESPONSE_TOO_LARGE");
+            }
             return { status: response.status, json, headers };
         }
         catch (err) {

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaRenderPort.d.ts

@@ -9,11 +9,21 @@ export interface FigmaRenderResponse {
     readonly headers: Readonly<Record<string, string>>;
 }
 export type FigmaRenderPort = (request: FigmaRenderRequest) => Promise<FigmaRenderResponse>;
+/** Optional creation-time overrides for the default render port. */
+export interface FigmaRenderPortOptions {
+    readonly timeoutMs?: number;
+    readonly maxResponseBytes?: number;
+}
 /**
  * Thin default adapter over the platform `fetch`. This is the ONLY place in the render path
  * `fetch` is named. It forwards the caller-built headers verbatim and reads the body as raw
- * bytes; it does not log, retry, or inspect any token. Resilience/backoff is out of scope here
- * (#759); the proxy/custom-CA transport is the platform prerequisite (#802) that replaces this.
+ * bytes with an explicit byte cap; it does not log, retry, or inspect any token. Resilience/
+ * backoff is out of scope here (#759); the proxy/custom-CA transport is the platform
+ * prerequisite (#802) that replaces this.
+ *
+ * `redirect: "manual"` prevents any caller-supplied auth header from following a cross-origin
+ * redirect. A 3xx response surfaces as a non-2xx port result; the connector treats it as
+ * upstream error.
  */
-export declare const createDefaultFigmaRenderPort: (egress?: OutboundHttpEgressConfig, fetchImpl?: typeof fetch) => FigmaRenderPort;
+export declare const createDefaultFigmaRenderPort: (egress?: OutboundHttpEgressConfig, fetchImpl?: typeof fetch, options?: FigmaRenderPortOptions) => FigmaRenderPort;
 //# sourceMappingURL=figmaRenderPort.d.ts.map

package/node_modules/@oscharko-dev/keiko-server/dist/qualityIntelligence/figma/figmaRenderPort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"figmaRenderPort.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaRenderPort.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,iDAAiD,CAAC;AAEzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAG3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAE5F;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,wBAAwB,EACjC,YAAY,OAAO,KAAK,KACvB,eAoBF,CAAC"}
+{"version":3,"file":"figmaRenderPort.d.ts","sourceRoot":"","sources":["../../../src/qualityIntelligence/figma/figmaRenderPort.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,iDAAiD,CAAC;AAQzD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAG3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAE5F,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAiCD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACvC,SAAS,wBAAwB,EACjC,YAAY,OAAO,KAAK,EACxB,UAAU,sBAAsB,KAC/B,eA0BF,CAAC"}