@suluk/harden 0.1.0 → 0.1.2

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.0",
+  "version": "0.1.2",
   "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,7 @@
 ".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "^0.1.7"
+"@suluk/core": "^0.1.11"
 },
 "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/harden.ts

@@ -0,0 +1,64 @@
+/**
+ * The hardening TRANSFORM — the answer to {@link auditDocument}'s findings. It adds sensible default BOUNDS so
+ * untrusted input can't be unboundedly large or carry control characters that break parsers: every string gets a
+ * maxLength + a control-char-rejecting pattern, every number a maximum/minimum, every array a maxItems, every object
+ * is closed (additionalProperties:false). Authors TIGHTEN per field (a slug isn't 1024 chars) — this is the floor
+ * that turns an F/D contract into a B. The inverse of the audit: audit grades the gaps, harden fills them.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+
+type S = Record<string, unknown>;
+
+/** Overridable floors — defaults match the baseline (1024 chars / ±1e12 / 1000 items / no control chars). */
+export interface HardenOptions {
+  maxLength?: number;
+  /** reject NUL + control chars (tab/newline/CR allowed). Pass null to skip adding a pattern. */
+  textPattern?: string | null;
+  numberMax?: number;
+  numberMin?: number;
+  maxItems?: number;
+}
+
+// Reject NUL + control chars that break parsers (tab/newline/CR are allowed by the range below).
+const SAFE_TEXT = "^[^\\u0000-\\u0008\\u000b\\u000c\\u000e-\\u001f]*$";
+const DEFAULTS: Required<HardenOptions> = { maxLength: 1024, textPattern: SAFE_TEXT, numberMax: 1_000_000_000_000, numberMin: -1_000_000_000_000, maxItems: 1000 };
+
+/** Recursively add baseline bounds to a JSON Schema. Idempotent — never overrides an author-set bound. */
+export function hardenSchema(schema: unknown, opts: HardenOptions = {}): unknown {
+  const o = { ...DEFAULTS, ...opts };
+  const go = (sch: unknown): unknown => {
+    if (sch == null || typeof sch !== "object") return sch;
+    if (Array.isArray(sch)) return sch.map(go);
+    const s: S = { ...(sch as S) };
+    const t = Array.isArray(s.type) ? (s.type as string[])[0] : s.type;
+    if (s.properties) { const p: S = {}; for (const [k, v] of Object.entries(s.properties as S)) p[k] = go(v); s.properties = p; if (s.additionalProperties === undefined) s.additionalProperties = false; }
+    if (s.items) s.items = go(s.items);
+    for (const key of ["oneOf", "anyOf", "allOf"] as const) if (Array.isArray(s[key])) s[key] = (s[key] as unknown[]).map(go);
+    const bounded = s.enum !== undefined || s.const !== undefined || s.format !== undefined;
+    if (t === "string" && !bounded) {
+      if (s.maxLength === undefined) s.maxLength = o.maxLength;
+      if (s.pattern === undefined && o.textPattern != null) s.pattern = o.textPattern;
+    }
+    if (t === "integer" || t === "number") {
+      if (s.maximum === undefined && s.exclusiveMaximum === undefined) s.maximum = o.numberMax;
+      if (s.minimum === undefined && s.exclusiveMinimum === undefined) s.minimum = o.numberMin;
+    }
+    if (t === "array" && s.maxItems === undefined) s.maxItems = o.maxItems;
+    return s;
+  };
+  return go(schema);
+}
+
+/** Harden EVERY input schema in a built v4 document IN PLACE — request bodies + all parameter slots (incl. the route
+ *  generator's path params, otherwise unbounded strings). Idempotent. The transform that makes assertGrade pass. */
+export function hardenDocument<T extends OpenAPIv4Document>(doc: T, opts: HardenOptions = {}): T {
+  const d = doc as unknown as { paths?: Record<string, { requests?: Record<string, Record<string, unknown>> }> };
+  for (const pi of Object.values(d.paths ?? {})) {
+    for (const req of Object.values(pi.requests ?? {})) {
+      if (req.contentSchema) req.contentSchema = hardenSchema(req.contentSchema, opts);
+      const ps = req.parameterSchema as Record<string, unknown> | undefined;
+      if (ps) for (const loc of ["query", "path", "header", "cookie", "body"]) if (ps[loc]) ps[loc] = hardenSchema(ps[loc], opts);
+    }
+  }
+  return doc;
+}

package/src/index.ts

@@ -9,5 +9,10 @@
  */
 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";

package/test/harden.test.ts

@@ -1,5 +1,5 @@
 import { test, expect, describe } from "bun:test";
-import { auditOperation, auditDocument, assertGrade, grade } 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: {
@@ -63,3 +63,76 @@ describe("@suluk/harden — schema hardening as a scored facet", () => {
     expect(d.findings.filter((f) => f.rule === "string-max-length").length).toBe(1);
   });
 });
+
+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: {
+      name: { type: "string" }, age: { type: "integer" }, tags: { type: "array", items: { type: "string" } },
+      meta: { type: "object", properties: { k: { type: "string" } } },
+    } }) as Record<string, any>;
+    expect(h.additionalProperties).toBe(false);
+    expect(h.properties.name.maxLength).toBe(1024);
+    expect(h.properties.name.pattern).toContain("u0000");
+    expect(h.properties.age.maximum).toBe(1_000_000_000_000);
+    expect(h.properties.age.minimum).toBe(-1_000_000_000_000);
+    expect(h.properties.tags.maxItems).toBe(1000);
+    expect(h.properties.tags.items.maxLength).toBe(1024);
+    expect(h.properties.meta.additionalProperties).toBe(false); // nested objects WITH properties get closed
+  });
+
+  test("never overrides an author-set bound, and leaves enum/const/format strings alone", () => {
+    const h = hardenSchema({ type: "string", maxLength: 64 }) as Record<string, unknown>;
+    expect(h.maxLength).toBe(64);
+    expect(hardenSchema({ type: "string", enum: ["a", "b"] })).not.toHaveProperty("maxLength");
+    expect(hardenSchema({ type: "string", format: "email" })).not.toHaveProperty("pattern");
+  });
+
+  test("respects overridable floors", () => {
+    const h = hardenSchema({ type: "string" }, { maxLength: 80, textPattern: null }) as Record<string, unknown>;
+    expect(h.maxLength).toBe(80);
+    expect(h).not.toHaveProperty("pattern");
+  });
+
+  test("INVERSE PROPERTY: hardenDocument fills the BOUND gaps → a bounds-only-weak doc then passes assertGrade('A')", () => {
+    // gaps are ONLY missing bounds (every field typed, objects have properties) — exactly what the floor can fill.
+    const boundsOnly = { method: "post", contentSchema: { type: "object", properties: {
+      name: { type: "string" }, age: { type: "integer" }, tags: { type: "array", items: { type: "string" } },
+    } } };
+    const doc2 = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { w: { requests: { createW: boundsOnly } } } } as unknown as OpenAPIv4Document;
+    expect(() => assertGrade(doc2, "A")).toThrow(); // unbounded today
+    hardenDocument(doc2); // in place
+    expect(assertGrade(doc2, "A").grade).toBe("A"); // the audit's gaps are now filled
+  });
+
+  test("idempotent — hardening twice is a no-op", () => {
+    const once = hardenSchema({ type: "object", properties: { a: { type: "string" } } });
+    expect(hardenSchema(once)).toEqual(once);
+  });
+});