@attestry/sdk 0.6.0

package/dist/resources/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/resources/check.ts"],"names":[],"mappings":"AAwFA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA2ClD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;;;;;OAeG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;OAeG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;OASG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwLG;IACH,GAAG,CACD,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC;CA8N1B"}

package/dist/resources/check.js

@@ -0,0 +1,543 @@
+// ─── Check resource ─────────────────────────────────────────────────────────
+//
+// Wraps the CI/CD compliance-check surface (session 16):
+//
+//   - POST /api/v1/check  Body: {systemId: <UUID>, frameworks?: string[]}
+//
+// Fourth non-decisions resource on `@attestry/sdk`. Sibling to
+// `IncidentsResource`, `DecisionsResource`, `ChatResource`,
+// `AuditLogResource`, `RegulatoryChangesResource`,
+// `ComplianceCheckResource`. Single public method today (`run`); the
+// resource class exists as the landing pad for future check methods
+// if/when the kernel adds them (resource-class-per-kernel-resource
+// convention, carry-forward invariant #43).
+//
+// Method name `run` rather than `check` — `client.check.check(...)`
+// would be awkward; `run` mirrors the verb pattern of `chat.send`,
+// `decisions.ingest`, `auditLog.export`. User-confirmed at session
+// start.
+//
+// **Multi-permission UNION auth scope**: the kernel route gates on
+// `requireApiKeyWithPermission(request, READ_ASSESSMENTS, READ_SYSTEMS)`
+// which is OR semantics — `permissions.ts:53-55` uses `Array.some()`,
+// NOT `.every()`. A key with EITHER permission (or `ADMIN`, or empty
+// permissions for backwards-compat) succeeds. **HTTP 401** for
+// no/invalid API key; **HTTP 403** for an authenticated key that has
+// NEITHER required permission. Pin BOTH branches separately.
+// Carry-forward invariant #45 (no re-discovery this round — same shape
+// as `complianceCheck.check`).
+//
+// **First SDK route to PRE-VALIDATE every Zod closed-spec rule
+// synchronously**. Other Zod-bodied SDK routes (e.g.,
+// `incidents.create`) pass input through without SDK-side validation,
+// so a 422 from Zod has been a consumer-visible surface there since
+// v0.1. In `check.run` the kernel uses `parseBody(request,
+// checkSchema)` where `checkSchema` is `z.object({systemId:
+// z.string().uuid(), frameworks: z.array(z.string().min(1).max(100))
+// .max(20).optional()})`. The SDK pre-validates EVERY closed-spec
+// rule synchronously (UUID format, string length 1-100, array length
+// cap 20). The SDK's runtime checks always run regardless of
+// TypeScript types — `as any` casts do NOT bypass them. So 422 from
+// this route reaches consumers ONLY via kernel-side rule changes the
+// SDK hasn't synced to. Codifies new invariant candidate #49
+// (pre-validate Zod closed-spec rules SDK-side) and #51 (POST + Zod
+// body — pre-rejected TypeError is the primary path, kernel 422 is
+// the fallback for rules the SDK hasn't synced to).
+//
+// **Asymmetric cross-org error code**: cross-org `systemId` returns
+// **404** (kernel's `and(eq id, eq orgId)` at route.ts:42-51 followed
+// by "System not found" — mirror of `decisions.retrieve` +
+// `complianceCheck.check`'s systemId branch). Partial carry-forward
+// of #47 (no orgName twin here, so only the 404 half applies).
+//
+// **Three silent kernel-side truncations** (faithful courier — SDK
+// does NOT mask):
+//   1. `issues` capped at 20 (`gaps.slice(0, 20)` at route.ts:90).
+//   2. `assessments` capped at 100 (`.limit(100)` at route.ts:62).
+//   3. `attestations` capped at 50 (`.limit(50)` at route.ts:100).
+// Each documented in JSDoc + README + drift-pinned. New invariant
+// candidate #50 (multi-silent-truncation enumeration).
+//
+// **`score` defaults to 0 (NOT null) when no completed assessment
+// exists** (route.ts:84 — `typeof scores?.overallScore === "number"
+// ? scores.overallScore : 0`). Asymmetric with
+// `complianceCheck.check` which used `null` for "no data".
+// Consumers cannot distinguish "scored zero" from "no completed
+// assessment" via `score` alone — must check `lastAssessedAt ===
+// null` to differentiate. Kernel surface gap, documented prominently.
+//
+// **`compliant` threshold stricter than `complianceCheck.check`**:
+// here `compliant === activeAttestations > 0 && overallScore >= 70 &&
+// issues.length === 0` (three conjuncts). Because `score` defaults
+// to 0 (not null), a system with no completed assessment automatically
+// has `compliant: false` here, even when active attestations exist.
+//
+// **NO URIError defense on body fields** — POST body uses
+// `JSON.stringify`, which handles lone UTF-16 surrogates by emitting
+// them as literal `\uDxxx` escapes. The URIError defect class
+// (carry-forward invariant #32) applies only to query-string paths
+// (`encodeURIComponent`); this route has no query string and a fixed
+// path. `assertEncodableQueryString` is NOT invoked here — explicit
+// asymmetry vs `complianceCheck.check` / decisions / incidents /
+// audit-log / regulatory-changes. Documented as D4.
+//
+// Sync JSON request/response: reuses `client._request` and the
+// existing `{success:true, data}` envelope-unwrap (carry-forward
+// invariant #9). NO new SDK primitive needed. Returns
+// `Promise<CheckResponse>`.
+import { AttestryError } from "../errors.js";
+import { readInputField } from "./safe-input-read.js";
+// Module-load snapshot of `Object.hasOwn` — defends against a
+// late-loading hostile/buggy npm dependency that overrides the global
+// (e.g., `Object.hasOwn = () => true`). Without the snapshot, the
+// prototype-pollution defense below uses whatever Object.hasOwn the
+// dependency replaced it with at request time. Snapshotting at module
+// load captures the original implementation BEFORE most consumer
+// code has a chance to monkey-patch.
+//
+// Caveat: this is partial. If the hostile dependency is imported
+// BEFORE @attestry/sdk in the consumer's load graph, the snapshot
+// captures the bad version. Consumers ordering imports
+// SDK-then-untrusted-deps benefit; the reverse ordering does not.
+// Combined with `Object.hasOwn` itself being immune to
+// `obj.hasOwnProperty = ...` overrides (per MDN), this gives a
+// layered defense.
+//
+// Mirror of `complianceCheck.check`'s pattern (hostile review session
+// 15 LOW #2). Generalizes #48 beyond XOR branching: prototype
+// pollution can lie about presence of ANY field where presence affects
+// SDK control flow (here: `systemId` required-vs-missing, `frameworks`
+// provided-vs-not). See build-round audit doc D5.
+const objectHasOwn = Object.hasOwn;
+// UUID format regex — RFC 4122 hyphenated form (8-4-4-4-12 hex,
+// case-insensitive). Matches Zod's `z.string().uuid()` regex
+// effectively (the `\b` word-boundaries in Zod's version are
+// redundant between hex chars and hyphens). Drift-pinned in
+// `sdk-drift.test.ts` spec-diff-round Pin so a kernel-side switch to
+// a different UUID flavor (ULID, KSUID, etc.) fires before consumer
+// regressions.
+//
+// Pre-validation here gives consumers a synchronous `TypeError` for
+// malformed UUID input — faster + clearer than waiting for the
+// kernel's 422 with `fieldErrors`. D2 deviation from
+// `complianceCheck.check` (which deferred to kernel's `isValidUuid`
+// returning 400). Codifies new invariant #49 (Zod-schema-validated
+// input — pre-validate closed-spec rules SDK-side).
+const UUID_REGEX = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/**
+ * `check` resource — sibling to `IncidentsResource`,
+ * `DecisionsResource`, `ChatResource`, `AuditLogResource`,
+ * `RegulatoryChangesResource`, `ComplianceCheckResource`. Today
+ * wraps a single endpoint (`run`); the class is the landing pad for
+ * future check methods if the kernel adds them
+ * (resource-class-per-kernel-resource convention, invariant #43).
+ */
+export class CheckResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Run a CI/CD compliance check for a single system. Returns a flat
+     * 6-field summary: `{compliant, score, issues, activeAttestations,
+     * lastAssessedAt, checkedAt}`. Sync JSON request/response — no
+     * pagination, no streaming.
+     *
+     * **Multi-permission UNION auth scope**: kernel uses
+     * `requireApiKeyWithPermission(req, READ_ASSESSMENTS, READ_SYSTEMS)`
+     * which is OR semantics (`Array.some()` at
+     * `permissions.ts:53-55`). A key with EITHER permission (or
+     * `ADMIN`, or null/empty permissions for backwards-compat)
+     * succeeds. **HTTP 401** for no/invalid API key, **HTTP 403** for
+     * an authenticated key that has NEITHER required permission. Pin
+     * BOTH branches separately. Carry-forward invariant #45 (same
+     * shape as `complianceCheck.check`).
+     *
+     * **Asymmetric cross-org error code** (carry-forward #47, partial):
+     * cross-org `systemId` returns **404** — the kernel's
+     * `and(eq id, eq orgId)` at route.ts:42-51 collapses
+     * cross-org to "System not found" (mirror of
+     * `decisions.retrieve`). Consumers writing defensive error-handling
+     * logic must recognize: a 404 may be "not your org" OR "genuine
+     * missing UUID". No 403-via-orgName twin here (no orgName input
+     * mode).
+     *
+     * **THREE silent kernel-side truncations** (faithful courier;
+     * documented as kernel surface gaps — JSDoc + README + drift
+     * pinned). New invariant candidate #50:
+     *   1. `issues` — `.slice(0, 20)` at route.ts:90. If the latest
+     *      completed assessment has >20 gaps, the 21st+ are invisible.
+     *   2. `assessments` row-population — `.limit(100)` at route.ts:62.
+     *      If the system has >100 assessments, the kernel's JS-side
+     *      `.sort()` operates on the first 100 only; the "latest
+     *      completed" may be missed.
+     *   3. `attestations` row-population — `.limit(50)` at
+     *      route.ts:100. If the system has >50 attestation rows,
+     *      `activeAttestations` may be undercounted.
+     *
+     * **`score` defaults to 0 (NOT null) — kernel surface gap**:
+     * route.ts:84 — `typeof scores?.overallScore === "number" ?
+     * scores.overallScore : 0`. Consumers MUST check `lastAssessedAt
+     * === null` to distinguish "no completed assessment yet" from
+     * "scored zero / fails compliance". Asymmetric with
+     * `complianceCheck.check`'s null-on-no-data.
+     *
+     * **`frameworks` filter is OR-overlap, NOT AND-all-required** —
+     * route.ts:67-71 uses `aFrameworks.some((fw) =>
+     * body.frameworks!.some(...))`. An assessment matches if its
+     * `frameworks` array intersects the filter (at least one in
+     * common), not if it covers ALL of them. Consumers wanting AND
+     * semantics must filter post-hoc.
+     *
+     * Errors — ordered by kernel firing precedence (rate-limit → auth
+     * → Zod body validation → DB lookup → internal). A request with
+     * multiple problems surfaces ONLY the highest-precedence one. For
+     * example: a request with bad auth AND a malformed body surfaces
+     * 401, not 422; a request with valid auth + bad body AND a cross-
+     * org systemId surfaces 422, not 404.
+     *   - `AttestryAPIError` (status 429) — rate limit FIRES FIRST
+     *     (auto-retried by default — invariant #18; per-IP rate-limit
+     *     key `v1-check:${ip}`).
+     *   - `AttestryAPIError` (status 401) — no API key OR invalid key.
+     *     Fires AFTER rate-limit but BEFORE input validation.
+     *   - `AttestryAPIError` (status 403) — authenticated key has
+     *     NEITHER `READ_ASSESSMENTS` nor `READ_SYSTEMS` (the
+     *     permission-check branch). Single test case — the union-auth
+     *     pattern collapses three intuition-suggesting cases to one.
+     *   - `AttestryAPIError` (status 422) — Zod schema rejection
+     *     (kernel's `BodyParseError` surface — `parseBody(request,
+     *     checkSchema)` failed). **Fires BEFORE the systemId/cross-
+     *     org 404 lookup**, so a request with bad UUID format AND
+     *     cross-org-correct UUID surfaces 422 (the kernel's Zod
+     *     `.uuid()` reject), not 404. `apiErr.details` carries the
+     *     full kernel error body verbatim (the transport does NOT
+     *     strip the `{success:false, ...}` envelope on error responses
+     *     — only the `{success:true, data}` envelope on success). The
+     *     wire shape is: `{success: false, error: "Validation failed.",
+     *     details: Array<{path: string; message: string}>}` — `error`
+     *     is the literal string
+     *     "Validation failed." (with trailing period), `details` is
+     *     an array (NOT a keyed map) of `{path, message}` pairs
+     *     derived from Zod's `result.error.errors`. Consumers
+     *     reading field-by-field errors should iterate
+     *     `apiErr.details.details` (the kernel's `details` array
+     *     nested under the SDK's parsed-body wrapper). **The SDK
+     *     pre-validates all closed-spec rules** (UUID format,
+     *     framework element length 1-100, array length ≤20) AND the
+     *     runtime checks always run regardless of TypeScript types —
+     *     `as any` casts do NOT bypass them. So 422 reaches consumers
+     *     ONLY via kernel rule changes the SDK hasn't synced to (e.g.,
+     *     a future kernel tightening that adds a new Zod rule the SDK
+     *     hasn't yet learned to pre-validate). New invariant candidate
+     *     #51.
+     *   - `AttestryAPIError` (status 404) — system not found OR
+     *     cross-org systemId (kernel collapses to "System not found",
+     *     route.ts:53-54). Fires AFTER Zod validation (422).
+     *   - `AttestryAPIError` (status 500) — internal kernel error
+     *     (scrubbed message via `internalErrorResponse`).
+     *   - `AttestryError` ("request aborted by caller") — caller-
+     *     supplied `options.signal` fired (pre-aborted or mid-flight).
+     *   - `AttestryError` (P2 hardening) — kernel response failed
+     *     SDK-side shape validation (not an object, wrong type on any
+     *     of the 6 documented fields).
+     *   - `AttestryAPIError` (P3 hardening) — kernel response had a
+     *     wrong Content-Type (transport-level guard before body
+     *     parsing).
+     *   - `TypeError` (synchronous, no fetch issued) — input failed
+     *     SDK-side validation (null / array / non-object input,
+     *     missing systemId, invalid UUID format, frameworks array too
+     *     long, frameworks element wrong type or length).
+     *
+     * **Notably ABSENT**:
+     *   - **No 400** — all input validation is Zod (422). The "missing
+     *     required field" 400 from compliance-check is irrelevant
+     *     (single required field; SDK pre-rejects as TypeError).
+     *   - **No 413** — body size limit not explicit; the kernel's
+     *     `parseBody` may have one but it isn't documented and the
+     *     SDK doesn't pin it.
+     *   - **No 402** — read-only, doesn't count against
+     *     decisionsPerMonth quota.
+     *
+     * **SDK-side validation** (synchronous `TypeError`, no fetch
+     * issued):
+     *   - `input` itself: required; must be a non-null, non-array
+     *     object.
+     *   - `input.systemId`: required own-property (Object.hasOwn
+     *     defends against prototype pollution lying about presence —
+     *     generalization of invariant #48); must be a non-empty
+     *     string; must match the RFC 4122 hyphenated UUID format
+     *     (D2 — SDK pre-validates closed-spec rule). No
+     *     lone-surrogate URIError defense (D4 — POST body uses
+     *     JSON.stringify, not encodeURIComponent).
+     *   - `input.frameworks` (when provided): must be an array of
+     *     ≤20 strings, each of length 1-100. SDK pre-validates each
+     *     rule (D3 — closed-spec rules mirror Zod). Array is
+     *     snapshotted via `Array.from` for TOCTOU defense (Proxy /
+     *     getter inputs can't yield different values across
+     *     validate-vs-send).
+     *
+     * **Response-shape validation** (P2 hardening — D6, stricter than
+     * `complianceCheck.check`'s 3-field top-level):
+     *   - Rejects with `AttestryError` if the kernel response isn't a
+     *     non-null, non-array object.
+     *   - Rejects if `compliant` isn't a boolean.
+     *   - Rejects if `score` isn't a number.
+     *   - Rejects if `issues` isn't an array.
+     *   - Rejects if `activeAttestations` isn't a number.
+     *   - Rejects if `lastAssessedAt` isn't a string OR null.
+     *   - Rejects if `checkedAt` isn't a string.
+     *   - Each response field read goes through the module-load
+     *     `objectHasOwn` snapshot (symmetric to the input-side
+     *     prototype-pollution defense — D5 generalized to the response
+     *     boundary). A hostile npm dep that pollutes
+     *     `Object.prototype.<field>` cannot mask a kernel regression
+     *     where the field is missing — the SDK requires the field to
+     *     be a kernel-emitted own property.
+     *   - Per-issue-string shape (open string) is faithful-courier —
+     *     NOT validated.
+     *
+     * **Transport-shape validation** (P3 hardening):
+     *   - Rejects with `AttestryAPIError` if the kernel responds with
+     *     a non-`application/json` Content-Type.
+     *
+     * @example Basic check
+     * ```ts
+     * const result = await client.check.run({
+     *   systemId: "11111111-1111-1111-1111-111111111111",
+     * });
+     * if (result.compliant) {
+     *   console.log("OK to deploy — score:", result.score);
+     * } else if (result.lastAssessedAt === null) {
+     *   console.warn("No completed assessment yet — score=0 is the default, not a failing grade");
+     * } else {
+     *   console.warn("Compliance gaps:", result.issues);
+     * }
+     * ```
+     *
+     * @example Filtered by frameworks (OR-overlap)
+     * ```ts
+     * const euOnly = await client.check.run({
+     *   systemId: "11111111-1111-1111-1111-111111111111",
+     *   frameworks: ["EU_AI_ACT", "ISO_42001"],
+     * });
+     * ```
+     */
+    run(input, options) {
+        // Top-level shape — input is REQUIRED. typeof null === "object"
+        // and typeof [] === "object", so guard both explicitly.
+        if (input === null ||
+            typeof input !== "object" ||
+            Array.isArray(input)) {
+            throw new TypeError("check.run: `input` must be a non-null object with `systemId`");
+        }
+        // Snapshot each field's value EXACTLY ONCE up front via the
+        // own-property indexer, then operate only on the locals
+        // downstream. Three motivations:
+        //   1. **Prototype-pollution defense (generalization of #48)**:
+        //      `Object.prototype.systemId = "<some-uuid>"` (set somewhere
+        //      else in the consumer's process) DOES NOT trick the SDK
+        //      into silently sending the polluted value when the user
+        //      passes `{}`. `Object.hasOwn` only checks own properties
+        //      (ES2022, Node 16.9+ — below the SDK's Node 18 floor). Use
+        //      the module-load snapshot (`objectHasOwn`) so a
+        //      late-loading dep that overrides the global doesn't defeat
+        //      the defense (mirror of `complianceCheck.check`'s hostile-
+        //      review LOW #2 fix).
+        //   2. **TOCTOU defense**: a Proxy or getter-defining input could
+        //      yield DIFFERENT values across multiple reads of the same
+        //      field. Snapshotting once collapses validate-then-send to a
+        //      single read per field; the validated value is provably the
+        //      value sent.
+        //   3. An explicit `{systemId: "..."}` (no `frameworks`) is
+        //      treated as frameworks-omitted — `objectHasOwn` correctly
+        //      returns false on the missing key.
+        const hasSystemId = objectHasOwn(input, "systemId");
+        const systemIdRaw = hasSystemId
+            ? readInputField(input, "systemId", "check.run")
+            : undefined;
+        const hasFrameworks = objectHasOwn(input, "frameworks");
+        const frameworksRaw = hasFrameworks
+            ? readInputField(input, "frameworks", "check.run")
+            : undefined;
+        // systemId is REQUIRED. Reject missing-or-undefined first with a
+        // clear "required" message; subsequent checks assume present.
+        if (!hasSystemId || systemIdRaw === undefined) {
+            throw new TypeError("check.run: `systemId` is required");
+        }
+        if (typeof systemIdRaw !== "string" || systemIdRaw.length === 0) {
+            throw new TypeError("check.run: `systemId` must be a non-empty string");
+        }
+        // UUID format pre-validation (D2 — SDK matches kernel's Zod
+        // `z.string().uuid()` closed-spec rule). Faster + clearer than
+        // waiting for kernel 422 + fieldErrors decoding. Drift-pinned so
+        // a future Zod regex change (e.g., adding v7 ULID support) trips
+        // the suite.
+        if (!UUID_REGEX.test(systemIdRaw)) {
+            throw new TypeError("check.run: `systemId` must be an RFC 4122 hyphenated UUID " +
+                "(matched regex: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-" +
+                "[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/)");
+        }
+        // frameworks — optional. When provided, MUST mirror Zod:
+        //   - Array (not other iterable).
+        //   - Length ≤20.
+        //   - Each element a string of length 1-100.
+        // Snapshot via Array.from up front so a Proxy whose `.length` or
+        // `[i]` changes between reads can't slip past validation. The
+        // snapshot is then sent verbatim as the body field — no
+        // re-read.
+        let validatedFrameworks;
+        if (hasFrameworks && frameworksRaw !== undefined) {
+            if (!Array.isArray(frameworksRaw)) {
+                throw new TypeError(`check.run: \`frameworks\` must be an array when provided ` +
+                    `(got ${describeType(frameworksRaw)})`);
+            }
+            const snapshot = Array.from(frameworksRaw);
+            if (snapshot.length > 20) {
+                throw new TypeError(`check.run: \`frameworks\` array exceeds the kernel's max ` +
+                    `length of 20 (got ${snapshot.length})`);
+            }
+            for (let i = 0; i < snapshot.length; i++) {
+                const elem = snapshot[i];
+                if (typeof elem !== "string") {
+                    throw new TypeError(`check.run: \`frameworks[${i}]\` must be a string ` +
+                        `(got ${describeType(elem)})`);
+                }
+                if (elem.length === 0) {
+                    throw new TypeError(`check.run: \`frameworks[${i}]\` must be a non-empty string`);
+                }
+                if (elem.length > 100) {
+                    throw new TypeError(`check.run: \`frameworks[${i}]\` exceeds the kernel's max ` +
+                        `length of 100 chars (got ${elem.length})`);
+                }
+            }
+            // Cast: we've validated every element is a string.
+            validatedFrameworks = snapshot;
+        }
+        // Construct the body. Omit `frameworks` entirely when not
+        // provided — the kernel's Zod schema marks it `.optional()` and a
+        // missing key is the cleanest representation. (JSON.stringify
+        // would also drop `undefined`-valued keys, but explicit
+        // construction is clearer.)
+        const body = {
+            systemId: systemIdRaw,
+        };
+        if (validatedFrameworks !== undefined) {
+            body.frameworks = validatedFrameworks;
+        }
+        return this.client
+            ._request({
+            method: "POST",
+            path: "/api/v1/check",
+            body,
+            options,
+        })
+            .then((result) => {
+            // P2 hardening: validate every documented field type. The
+            // check response is FLAT — all 6 fields are top-level (no
+            // nested wrapper like `complianceCheck.check`'s `systems[]`).
+            // A kernel-side regression that emits the wrong type on any
+            // field would let a malformed shape reach consumers, who
+            // crash downstream with a confusing TypeError. Catch at the
+            // SDK boundary with a clear AttestryError naming the
+            // specific field.
+            if (result === null ||
+                typeof result !== "object" ||
+                Array.isArray(result)) {
+                throw new AttestryError(`check.run: expected an object response from the kernel ` +
+                    `(got ${describeType(result)})`);
+            }
+            const obj = result;
+            // **Prototype-pollution defense on the RESPONSE side**
+            // (symmetric to the input-side D5 generalization of #48).
+            // Snapshot each response field via `objectHasOwn` so a hostile
+            // npm dep that pollutes `Object.prototype.<field> = <value>`
+            // (e.g., `Object.prototype.compliant = true`) cannot mask a
+            // kernel regression where the field is missing from the
+            // response. Without this defense: kernel-regression-drops-field
+            // + prototype-pollution-supplies-default → SDK accepts the
+            // polluted value via prototype walk; consumer silently gets a
+            // wrong response. With this defense: missing own-property →
+            // describeType(undefined) → AttestryError thrown.
+            //
+            // Found by session-16 SECOND independent hostile review as
+            // MEDIUM #3 — symmetric attack to the input-side defense,
+            // previously unguarded on the response path.
+            const compliant = objectHasOwn(obj, "compliant")
+                ? obj.compliant
+                : undefined;
+            if (typeof compliant !== "boolean") {
+                throw new AttestryError(`check.run: expected response.compliant to be a boolean ` +
+                    `(got ${describeType(compliant)})`);
+            }
+            const score = objectHasOwn(obj, "score") ? obj.score : undefined;
+            if (typeof score !== "number") {
+                throw new AttestryError(`check.run: expected response.score to be a number ` +
+                    `(got ${describeType(score)})`);
+            }
+            const issues = objectHasOwn(obj, "issues") ? obj.issues : undefined;
+            if (!Array.isArray(issues)) {
+                throw new AttestryError(`check.run: expected response.issues to be an array ` +
+                    `(got ${describeType(issues)})`);
+            }
+            const activeAttestations = objectHasOwn(obj, "activeAttestations")
+                ? obj.activeAttestations
+                : undefined;
+            if (typeof activeAttestations !== "number") {
+                throw new AttestryError(`check.run: expected response.activeAttestations to be a number ` +
+                    `(got ${describeType(activeAttestations)})`);
+            }
+            const lastAssessedAt = objectHasOwn(obj, "lastAssessedAt")
+                ? obj.lastAssessedAt
+                : undefined;
+            if (lastAssessedAt !== null && typeof lastAssessedAt !== "string") {
+                throw new AttestryError(`check.run: expected response.lastAssessedAt to be a string or null ` +
+                    `(got ${describeType(lastAssessedAt)})`);
+            }
+            const checkedAt = objectHasOwn(obj, "checkedAt")
+                ? obj.checkedAt
+                : undefined;
+            if (typeof checkedAt !== "string") {
+                throw new AttestryError(`check.run: expected response.checkedAt to be a string ` +
+                    `(got ${describeType(checkedAt)})`);
+            }
+            return result;
+        });
+    }
+}
+/**
+ * Human-readable type description for error messages. Distinguishes
+ * `null` and `array` from generic `object`. Duplicated in
+ * `decisions.ts`, `incidents.ts`, `regulatory-changes.ts`,
+ * `compliance-check.ts` per project pattern (small helper, leaf-
+ * resource modules, no shared module yet).
+ *
+ * Every branch is reachable in this file:
+ *   1. The top-level "expected object" path can see null OR scalar
+ *      OR array (the negation of "non-null non-array object").
+ *   2. The `compliant` / `score` / `activeAttestations` / `checkedAt`
+ *      type guards can see any non-matching type (including null and
+ *      array).
+ *   3. The `lastAssessedAt` guard can see any type except string OR
+ *      null (so the null branch is structurally unreachable from
+ *      THAT call site — null would be filtered by the `!== null`
+ *      check upstream).
+ *   4. The `issues` guard can see any type except array (so the
+ *      array branch is structurally unreachable from THAT call
+ *      site).
+ *   5. The `frameworks` non-array case can see any non-array type
+ *      (so the array branch is structurally unreachable from THAT
+ *      call site).
+ *   6. The `frameworks[i]` non-string guard can see any
+ *      non-string type.
+ *
+ * Multiple call sites means every branch IS reachable across the
+ * module's invocations — no v8-ignore markers needed.
+ */
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+//# sourceMappingURL=check.js.map

package/dist/resources/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/resources/check.ts"],"names":[],"mappings":"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"}