@suluk/harden 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,161 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+# @suluk/harden
+
+**Schema hardening as a derived, scored contract facet — grade a v4 document's input schemas A–F, fail CI below a floor, and fill the gaps with one transform.**
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/harden
+```
+
+## What it does
+
+It audits the **input** surface of an OpenAPI v4 "Suluk" document — every request body and typed parameter slot (`path` / `query` / `header` / `cookie` / `body`) — for the validations that keep malformed or oversized input from breaking the system:
+
+- **no `any`/`unknown`** — every input has a determinable `type` (or is bounded by `enum`/`const`);
+- **every string** a `maxLength` **and** a `pattern` (a character allowlist) — unless bounded by `format`/`enum`/`const`;
+- **every number** a `maximum` (and ideally a `minimum`);
+- **every array** a `maxItems` (a DoS guard);
+- **every object** closed (`additionalProperties: false`) and typed (defined `properties`).
+
+It scores each operation and the whole document (0–100 → letter grade), emits concrete `Finding`s with a `fix` string, and gives you a **CI gate** (`assertGrade`) so a regression below the floor throws. The inverse half — `hardenSchema` / `hardenDocument` — is the transform that *fills* those gaps with sensible baseline bounds, turning an F/D contract into a B with one call (authors then tighten per field).
+
+`$ref`'d models are walked once and deduped across operations, so a shared schema is audited (and reported) a single time.
+
+## When to reach for it
+
+- You build a v4 document (from `@suluk/drizzle`, `@suluk/hono`, or by hand) and want **input-validation coverage** scored and visible — to incentivise hardening rather than hope for it.
+- You want to **gate CI**: `assertGrade(doc, "A")` in a test throws if the authored surface regresses below the floor.
+- You want to **auto-tighten** loose schemas: run `hardenDocument` over a built document to add baseline bounds doc-wide (including the route generator's otherwise-unbounded path-param strings).
+
+This package only *reads and rewrites* the schemas inside a v4 document. It does not validate live requests (that's the wire / `@suluk/core`), and it does not render the grade into a UI — the `@suluk/reference` hardening panel and the `@suluk/editor` diagnostics bar do that by calling `auditDocument` themselves.
+
+## Usage
+
+### Audit — grade the input surface
+
+```ts
+import { auditDocument } from "@suluk/harden";
+
+const report = auditDocument(doc); // doc: OpenAPIv4Document
+report.grade;        // "A" | "B" | "C" | "D" | "F"
+report.score;        // 0–100
+report.bySeverity;   // { high, medium, low } — counts across all findings
+report.byOperation;  // per-operation audits, weakest first
+report.findings;     // Finding[] — { rule, severity, path, message, fix }, deduped by rule@path
+
+for (const f of report.findings) {
+  console.log(`${f.severity.toUpperCase()} ${f.path}: ${f.message} → ${f.fix}`);
+}
+```
+
+Audit a single operation, or skip surfaces you don't author (e.g. a merged third-party auth surface) so they don't count toward the grade:
+
+```ts
+import { auditOperation, auditDocument } from "@suluk/harden";
+
+// One operation: auditOperation(doc, uri, operationName, rawRequest)
+const op = auditOperation(doc, "/users", "createUser", req);
+
+// Exclude ingested surfaces from the rollup:
+const report = auditDocument(doc, {
+  ignore: (uri, name) => uri.toLowerCase().includes("auth"),
+});
+```
+
+### Gate CI — `assertGrade`
+
+The hard incentive: throw if the document's hardening grade falls below `min`. Returns the full `DocAudit` when it passes.
+
+```ts
+import { test } from "bun:test";
+import { assertGrade } from "@suluk/harden";
+
+test("contract input surface stays fully bounded (grade A)", async () => {
+  const document = await app.request("/openapi.json").then((r) => r.json());
+  const audit = assertGrade(document, "A", {
+    ignore: (uri) => uri.toLowerCase().includes("auth"), // auth is third-party
+  });
+  // throws below A; on pass you get the report:
+  expect(audit.bySeverity.high).toBe(0);
+});
+```
+
+The thrown message names the worst operations and the high/medium counts, so a failing build tells the author exactly what to add.
+
+### Unified contract grade — combine the input-schema grade with the agent grade
+
+A v4 document has two graded dimensions: its **input schemas** (this package) and its **agent composition**
+([`@suluk/agents`](../agents)' `gradeAgent`). `combineGrades` folds them into one contract grade — on the **letter**,
+never the raw score (the two scores are non-comparable: a clean/nodes ratio vs an absolute `100 − Σ penalty`). It's a
+pure combinator, so no package depends on the other — the caller passes the letters:
+
+```ts
+import { auditDocument, combineGrades, assertCombinedGrade } from "@suluk/harden";
+import { gradeAgents } from "@suluk/agents";
+
+const grades = [auditDocument(doc).grade, ...gradeAgents(doc).map((g) => g.grade)];
+combineGrades(grades);             // { worst, average, grades } — `worst` is the value to GATE on (a contract is as strong as its weakest dimension)
+                                   //   `average` is informational; its ties round toward the higher letter, so it only ever masks optimistically
+assertCombinedGrade(grades, "B");  // CI gate on the worst dimension; pass `"average"` to soften. Pass at least the doc grade — an empty set passes vacuously.
+```
+
+### Harden — the inverse transform
+
+`hardenSchema` adds baseline bounds to a single JSON Schema; `hardenDocument` does it to **every** input schema in a built v4 document, in place. Both are idempotent and **never override an author-set bound** — they only fill gaps. Strings bounded by `enum`/`const`/`format` are left alone.
+
+```ts
+import { hardenSchema, hardenDocument } from "@suluk/harden";
+
+// Per schema — layer it after your own per-field validations so it only fills what's left:
+const schema = hardenSchema(myInsertSchema);
+// strings → maxLength + a control-char-rejecting pattern; numbers → min/max;
+// arrays → maxItems; objects → additionalProperties:false
+
+// Doc-wide, in place — the transform that makes assertGrade pass:
+const document = hardenDocument(builtDoc);
+```
+
+Override the floors when the defaults (1024 chars / ±1e12 / 1000 items) are wrong for you, or pass `textPattern: null` to skip the string pattern entirely:
+
+```ts
+import { hardenSchema, type HardenOptions } from "@suluk/harden";
+
+const opts: HardenOptions = { maxLength: 80, numberMax: 1_000, maxItems: 50 };
+const tightened = hardenSchema(schema, opts);
+```
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `auditDocument(doc, opts?)` | Audit the whole document → `DocAudit` (per-op grades, deduped rollup, severity breakdown). |
+| `auditOperation(doc, uri, name, req)` | Audit one operation's input surface → `OpAudit`. |
+| `assertGrade(doc, min, opts?)` | CI gate: throw if the grade is below `min`; else return the `DocAudit`. |
+| `grade(score)` | Map a 0–100 score to a letter grade (`A` ≥ 90, `B` ≥ 75, `C` ≥ 60, `D` ≥ 40, else `F`). |
+| `combineGrades(grades)` / `assertCombinedGrade(grades, min, mode?)` | UNIFIED contract grade (Stage 1.5): combine this input-schema grade with `@suluk/agents`' `gradeAgent` grade on the LETTER → `{ worst, average, grades }`; gate on the worst (safe) or `"average"`. |
+| `hardenSchema(schema, opts?)` | Add baseline bounds to one JSON Schema (idempotent; never overrides). |
+| `hardenDocument(doc, opts?)` | Harden every input schema in a built v4 document, in place. |
+| `HardenOptions` | `{ maxLength?, textPattern?, numberMax?, numberMin?, maxItems? }` — overridable floors for the transform. |
+
+Types `Audit`, `OpAudit`, `DocAudit`, `Finding`, `Severity` (`"high" \| "medium" \| "low"`), and `Grade` (`"A" \| "B" \| "C" \| "D" \| "F"`) are exported alongside.
+
+## Boundary
+
+The audit↔transform pair is the template for "ship both halves": the audit grades the gaps, `harden` fills them. Hardening is a **derived contract facet** — like `x-suluk-cost`/`x-suluk-access`/`x-suluk-source`, it is *projected from* the contract, not authored separately.
+
+This package stays L3 — **render/generate, never host**. It reads and rewrites the schemas inside a v4 document and returns reports/transformed documents; it does not run a server, validate live wire requests, or store anything. You inject the document (the built v4 doc) and consume the result (a grade, findings, or a hardened copy). Surfacing the grade to a developer (a docs panel, an editor bar) is the consumer's job; enforcing the bounds at runtime is the wire's job.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/harden",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Schema HARDENING as a derived contract facet: audit a v4 'Suluk' document's input schemas for the validations that keep weird/oversized input from breaking the system — every string a maxLength + a pattern, every number a maximum, every array a maxItems, every object closed + typed, no any/unknown — score it (A-F), surface the grade to INCENTIVISE the author, and gate CI on a minimum. CANDIDATE tooling.",
   "publishConfig": {
   "access": "public"
@@ -19,7 +19,8 @@
 ".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "^0.1.11"
+"@suluk/core": "^0.1.13",
+"@suluk/examples": "^0.1.0"
 },
 "devDependencies": {
 "@types/bun": "latest"

package/src/audit.ts

@@ -125,3 +125,39 @@ export function assertGrade(doc: OpenAPIv4Document, min: Grade, opts: AuditOptio
   }
   return a;
 }
+
+// ─────────────────────────── UNIFIED CONTRACT GRADE (Stage 1.5) ───────────────────────────
+// Combine grades from DIFFERENT dimensions (this package's input-schema grade + `@suluk/agents`' agent-composition
+// grade `gradeAgent`) into ONE contract grade — on the LETTER (ordinal), NEVER the raw score: the two scores live on
+// non-comparable scales (harden = a clean/nodes RATIO; gradeAgent = an absolute 100−Σpenalty), so only the letter is
+// shared. This is a PURE combinator (no `@suluk/agents` dependency — the caller passes the letters): the unified grade
+// is `combineGrades([auditDocument(doc).grade, ...gradeAgents(doc).map(g => g.grade)])`.
+
+export interface CombinedGrade {
+  /** the WORST letter — a contract is as strong as its weakest graded dimension (the safe value to GATE on). */
+  worst: Grade;
+  /** the rounded-mean letter (informational — can mask a single failing dimension, so do not gate on it blindly; ties
+   *  round toward the HIGHER letter, so the masking is always optimistic). */
+  average: Grade;
+  /** the input letters, as given. */
+  grades: Grade[];
+}
+
+/** Combine per-dimension letters into one contract grade (worst + average). Empty ⇒ vacuously A — a caller MUST pass at
+ *  least the doc grade, since gating an empty set passes vacuously (`worst:"A"`). */
+export function combineGrades(grades: Grade[]): CombinedGrade {
+  if (!grades.length) return { worst: "A", average: "A", grades: [] };
+  const ord = grades.map((g) => ORDER.indexOf(g));
+  const worst = ORDER[Math.min(...ord)]!;
+  const average = ORDER[Math.round(ord.reduce((a, b) => a + b, 0) / ord.length)]!;
+  return { worst, average, grades };
+}
+
+/** CI gate over a combined grade. Gates on the WORST dimension by default (safe); pass `mode: "average"` to soften. */
+export function assertCombinedGrade(grades: Grade[], min: Grade, mode: "worst" | "average" = "worst"): CombinedGrade {
+  const c = combineGrades(grades);
+  const g = mode === "average" ? c.average : c.worst;
+  if (ORDER.indexOf(g) < ORDER.indexOf(min))
+    throw new Error(`@suluk/harden: combined contract grade ${g} (${mode} of ${grades.join(", ") || "—"}) is below the required ${min}`);
+  return c;
+}

package/src/index.ts

@@ -9,7 +9,13 @@
  */
 export {
   auditDocument, auditOperation, assertGrade, grade,
+  // Stage 1.5: combine THIS package's input-schema grade with @suluk/agents' agent-composition grade into one
+  // contract grade — on the LETTER (the scores are non-comparable). Pure combinator; the caller passes the letters.
+  combineGrades, assertCombinedGrade, type CombinedGrade,
   type Audit, type OpAudit, type DocAudit, type Finding, type Severity, type Grade,
 } from "./audit";
 // the inverse of the audit — the hardening TRANSFORM that adds the baseline bounds the audit grades for.
 export { hardenSchema, hardenDocument, type HardenOptions } from "./harden";
+// C043: a SECOND dimension — schema-fact READINESS (computed-required, request-without-example), separate from the
+// security grade. Fold its letter into `combineGrades` alongside the security grade + journeys coverage.
+export { auditReadiness, type ReadinessAudit, type ReadinessOptions } from "./readiness";

package/src/readiness.ts

@@ -0,0 +1,79 @@
+/**
+ * READINESS audit (C043) — a SECOND, separate harden dimension (kept apart from the security `auditDocument` grade so a
+ * security score never mixes with a readiness score). It grades schema-FACT readiness the doc can answer alone — the
+ * concerns C040/C041 made expressible:
+ *   • `computed-required` — a request field marked `computed` (or `readOnly`) AND `required`: a client CANNOT send it,
+ *     so the request can never be satisfied (a real contract bug). HIGH.
+ *   • `request-without-example` — a request body with no curated `examples`/`example` (author one in `.meta`, or promote
+ *     a tester `@public` row). A docs/demo readiness gap. LOW.
+ *
+ * BDD COVERAGE is the OTHER readiness gap — but it needs the `.feature` files, so `@suluk/journeys` computes it and the
+ * caller folds its letter in via `combineGrades` (harden never depends on journeys — the established harden+agents seam).
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { fieldOrigin, type JsonSchema } from "@suluk/examples";
+import { grade, type Finding, type Grade } from "./audit";
+
+export interface ReadinessAudit {
+  findings: Finding[];
+  nodes: number;
+  clean: number;
+  score: number;
+  grade: Grade;
+}
+
+export interface ReadinessOptions {
+  /** skip operations (e.g. third-party/ingested surfaces) — they don't count toward the readiness grade. */
+  ignore?: (uri: string, name: string) => boolean;
+}
+
+interface RawReq {
+  method: string;
+  contentSchema?: unknown;
+  parameterSchema?: { body?: unknown };
+}
+
+const hasExample = (s: JsonSchema): boolean => (Array.isArray(s.examples) && s.examples.length > 0) || "example" in s;
+
+/** Audit the document's request bodies for client-sendability + example presence → findings + a readiness grade. */
+export function auditReadiness(doc: OpenAPIv4Document, opts: ReadinessOptions = {}): ReadinessAudit {
+  const findings: Finding[] = [];
+  let nodes = 0;
+  let clean = 0;
+  const pass = () => {
+    nodes++;
+    clean++;
+  };
+  const fail = (f: Finding) => {
+    nodes++;
+    findings.push(f);
+  };
+
+  for (const [uri, piRaw] of Object.entries(doc.paths ?? {})) {
+    const pi = piRaw as { requests?: Record<string, RawReq> };
+    for (const [name, req] of Object.entries(pi.requests ?? {})) {
+      if (opts.ignore?.(uri, name)) continue;
+      const body = (req.contentSchema ?? req.parameterSchema?.body) as JsonSchema | undefined;
+      if (!body || typeof body !== "object") continue; // no request body → nothing to assess
+
+      // node: a curated example present?
+      if (hasExample(body)) pass();
+      else fail({ rule: "request-without-example", severity: "low", path: `${name}/body`, message: `request '${name}' has no example`, fix: "author one in .meta({ examples }), or promote a tester @public row via `journeys promote`" });
+
+      // node per REQUIRED field: is it client-sendable (not computed/readOnly)?
+      const props = (body.properties ?? {}) as Record<string, JsonSchema>;
+      const required = new Set(Array.isArray(body.required) ? (body.required as string[]) : []);
+      for (const [k, sub] of Object.entries(props)) {
+        if (!required.has(k)) continue;
+        if (fieldOrigin(sub) === "computed") {
+          fail({ rule: "computed-required", severity: "high", path: `${name}/body/${k}`, message: `required field '${k}' is computed/readOnly — a client cannot send it`, fix: "make it optional or non-computed (drop x-suluk-origin:computed / readOnly), or remove it from required" });
+        } else {
+          pass();
+        }
+      }
+    }
+  }
+
+  const score = nodes === 0 ? 100 : Math.round((clean / nodes) * 100);
+  return { findings, nodes, clean, score, grade: grade(score) };
+}

package/test/harden.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { auditOperation, auditDocument, assertGrade, grade, hardenSchema, hardenDocument } from "../src/index";
+import { auditOperation, auditDocument, assertGrade, grade, hardenSchema, hardenDocument, combineGrades, assertCombinedGrade } from "../src/index";
 import type { OpenAPIv4Document } from "@suluk/core";
 
 const weakReq = { method: "post", contentSchema: { type: "object", properties: {
@@ -64,6 +64,33 @@ describe("@suluk/harden — schema hardening as a scored facet", () => {
   });
 });
 
+describe("combineGrades — the unified contract grade (Stage 1.5: harden doc-grade × agent grade, on the LETTER)", () => {
+  test("worst is the weakest dimension; average is the rounded mean letter", () => {
+    expect(combineGrades(["A", "F"])).toEqual({ worst: "F", average: "C", grades: ["A", "F"] }); // A=4,F=0 → mean 2 → C
+    expect(combineGrades(["B", "B", "A"])).toEqual({ worst: "B", average: "B", grades: ["B", "B", "A"] });
+    expect(combineGrades(["A"])).toEqual({ worst: "A", average: "A", grades: ["A"] }); // single dimension (e.g. no agents)
+  });
+
+  test("empty ⇒ vacuously A (nothing graded)", () => {
+    expect(combineGrades([])).toEqual({ worst: "A", average: "A", grades: [] });
+  });
+
+  test("the unified grade composes the doc grade + every agent grade as letters (the documented bridge)", () => {
+    const docGrade = grade(82);                 // a 'B' document
+    const agentGrades = ["A", "C"] as const;    // e.g. gradeAgents(doc).map(g => g.grade)
+    const unified = combineGrades([docGrade, ...agentGrades]);
+    expect(unified.worst).toBe("C");            // a contract is as strong as its weakest dimension
+    expect(unified.grades).toEqual(["B", "A", "C"]);
+  });
+
+  test("assertCombinedGrade gates on the WORST by default; `average` softens the gate; passing returns the combined grade", () => {
+    expect(() => assertCombinedGrade(["A", "F"], "B")).toThrow(/below the required B/);  // worst F < B → throws
+    expect(() => assertCombinedGrade(["A", "F"], "B", "average")).toThrow();             // average C < B → still throws
+    expect(() => assertCombinedGrade(["A", "F"], "C", "average")).not.toThrow();         // average C ≥ C → passes (worst F would have failed)
+    expect(assertCombinedGrade(["A", "B"], "B").worst).toBe("B");                        // worst B ≥ B → passes, returns the combined grade
+  });
+});
+
 describe("hardenSchema / hardenDocument — the transform (inverse of the audit)", () => {
   test("adds baseline bounds: string→maxLength+pattern, number→min/max, array→maxItems, object→closed", () => {
     const h = hardenSchema({ type: "object", properties: {

package/test/readiness.test.ts

@@ -0,0 +1,85 @@
+import { test, expect, describe } from "bun:test";
+import { auditReadiness } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C043 — the readiness dimension: computed-required (a required field a client can't send) + request-without-example.
+ * Separate from the security grade; folded into combineGrades alongside security + journeys coverage.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "balance"],
+            properties: {
+              amountCents: { type: "integer" },
+              balance: { type: "integer", "x-suluk-origin": "computed" }, // required AND computed → a bug
+            },
+          },
+        },
+      },
+    },
+    "/good": {
+      requests: {
+        good: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["name"],
+            properties: { name: { type: "string" } },
+            examples: [{ name: "ok" }], // has an example
+          },
+        },
+      },
+    },
+    "/health": { requests: { health: { method: "get", responses: { "200": { status: 200 } } } } }, // no body → not assessed
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("auditReadiness", () => {
+  const audit = auditReadiness(doc);
+  const rules = audit.findings.map((f) => f.rule);
+
+  test("flags a required computed/readOnly field as not client-sendable (high)", () => {
+    const f = audit.findings.find((x) => x.rule === "computed-required");
+    expect(f).toBeDefined();
+    expect(f!.severity).toBe("high");
+    expect(f!.path).toBe("charge/body/balance");
+  });
+
+  test("flags a request body with no example (low)", () => {
+    const f = audit.findings.find((x) => x.rule === "request-without-example" && x.path === "charge/body");
+    expect(f).toBeDefined();
+    expect(f!.severity).toBe("low");
+  });
+
+  test("a body WITH an example + only sendable required fields raises no finding", () => {
+    expect(rules).not.toContain("good/body");
+    expect(audit.findings.some((f) => f.path.startsWith("good/"))).toBe(false);
+  });
+
+  test("a body-less op is not assessed (no nodes for it)", () => {
+    expect(audit.findings.some((f) => f.path.startsWith("health/"))).toBe(false);
+  });
+
+  test("produces a score + grade from the clean/nodes ratio", () => {
+    expect(audit.nodes).toBeGreaterThan(0);
+    expect(["A", "B", "C", "D", "F"]).toContain(audit.grade);
+  });
+
+  test("readOnly is treated as computed (no x-suluk-origin needed)", () => {
+    const ro = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { "/x": { requests: { x: { method: "post", contentSchema: { type: "object", required: ["id"], properties: { id: { type: "string", readOnly: true } } } } } } } } as unknown as OpenAPIv4Document;
+    expect(auditReadiness(ro).findings.some((f) => f.rule === "computed-required")).toBe(true);
+  });
+
+  test("a clean contract grades A", () => {
+    const clean = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { "/x": { requests: { x: { method: "post", contentSchema: { type: "object", required: ["n"], properties: { n: { type: "string" } }, examples: [{ n: "a" }] } } } } } } as unknown as OpenAPIv4Document;
+    expect(auditReadiness(clean).grade).toBe("A");
+  });
+});