@suluk/harden 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@suluk/harden",
+  "version": "0.1.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"
+},
+"license": "Apache-2.0",
+"repository": {
+"type": "git",
+"url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+"directory": "tooling/ts/packages/harden"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
+},
+"dependencies": {
+"@suluk/core": "^0.1.7"
+},
+"devDependencies": {
+"@types/bun": "latest"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/audit.ts

@@ -0,0 +1,127 @@
+/**
+ * Schema HARDENING audit — a derived facet (like cost/access) that scores how well a v4 document's INPUT schemas
+ * bound untrusted input, the validations that keep weird/oversized data from breaking the system:
+ *   • no `any`/`unknown` — every input has a determinable type (or enum/const)
+ *   • every string a maxLength AND a pattern (a character allowlist) — unless bounded by enum/const/format
+ *   • 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 produces per-operation + document scores + a letter grade, concrete fixes, and a CI gate — to INCENTIVISE the
+ * author to harden the contract. Audits the request body + typed parameter slots (the attack surface).
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { isReference, deref } from "@suluk/core";
+
+export type Severity = "high" | "medium" | "low";
+export type Grade = "A" | "B" | "C" | "D" | "F";
+export interface Finding { rule: string; severity: Severity; path: string; message: string; fix: string }
+export interface Audit { findings: Finding[]; nodes: number; clean: number; score: number; grade: Grade }
+export interface OpAudit extends Audit { operation: string; method: string; path: string }
+export interface DocAudit extends Audit { byOperation: OpAudit[]; bySeverity: Record<Severity, number> }
+
+export function grade(score: number): Grade { return score >= 90 ? "A" : score >= 75 ? "B" : score >= 60 ? "C" : score >= 40 ? "D" : "F"; }
+
+interface Acc { findings: Finding[]; nodes: Map<string, boolean> } // path → clean
+
+const has = (o: Record<string, unknown>, k: string) => o[k] != null;
+
+function walk(doc: OpenAPIv4Document, schema: unknown, path: string, seen: Set<string>, acc: Acc): void {
+  if (schema == null || schema === false) return; // absent / `never` — nothing to audit
+  if (isReference(schema)) {
+    const id = String((schema as { $ref: string }).$ref);
+    if (seen.has(id)) return;
+    let r: unknown; try { r = deref(doc, schema); } catch { return; } // dangling — the renderer flags it; skip here
+    if (r && !isReference(r)) walk(doc, r, id.replace(/^#\//, ""), new Set([...seen, id]), acc); // model-rooted path → dedupe across ops
+    return;
+  }
+  if (schema === true) { mark(acc, path, false); acc.findings.push({ rule: "no-any", severity: "high", path, message: `'${path}' is \`true\` — permits ANY value`, fix: "replace with a typed, bounded schema" }); return; }
+  const s = schema as Record<string, unknown>;
+  if (Array.isArray(s.oneOf) || Array.isArray(s.anyOf) || Array.isArray(s.allOf)) { for (const b of (s.oneOf ?? s.anyOf ?? s.allOf) as unknown[]) walk(doc, b, `${path}/~`, seen, acc); return; }
+  if (s.enum !== undefined || s.const !== undefined) { mark(acc, path, true); return; } // bounded by an explicit value set → clean
+
+  const types = Array.isArray(s.type) ? (s.type as string[]) : s.type ? [s.type as string] : [];
+  mark(acc, path, true); // optimistic; failures flip it
+  const fail = (rule: string, sev: Severity, message: string, fix: string) => { acc.findings.push({ rule, severity: sev, path, message, fix }); mark(acc, path, false); };
+
+  if (!types.length) { fail("no-any", "high", `'${path}' has no \`type\` (any/unknown)`, "give it a concrete type + bounds — never accept unconstrained input"); return; }
+  for (const t of types) {
+    if (t === "string") {
+      const bounded = has(s, "format");
+      if (!has(s, "maxLength") && !bounded) fail("string-max-length", "high", `string '${path}' has no maxLength`, "add maxLength (e.g. 256) so the field can't be unboundedly large");
+      if (!has(s, "pattern") && !bounded) fail("string-pattern", "medium", `string '${path}' has no pattern`, "add a pattern allowlisting characters (e.g. ^[\\w .@-]{0,256}$) to reject weird/injection input");
+    } else if (t === "integer" || t === "number") {
+      if (!has(s, "maximum") && !has(s, "exclusiveMaximum")) fail("number-maximum", "medium", `number '${path}' has no maximum`, "add a maximum to bound magnitude / digit count");
+      if (!has(s, "minimum") && !has(s, "exclusiveMinimum")) fail("number-minimum", "low", `number '${path}' has no minimum`, "add a minimum");
+    } else if (t === "array") {
+      if (!has(s, "maxItems")) fail("array-max-items", "high", `array '${path}' has no maxItems`, "add maxItems to cap array size (DoS guard)");
+      walk(doc, s.items, `${path}[]`, seen, acc);
+    } else if (t === "object") {
+      const open = s.additionalProperties !== false;
+      if (open) fail("object-closed", "medium", `object '${path}' allows additionalProperties`, "set additionalProperties:false to forbid unexpected keys");
+      const props = (s.properties ?? {}) as Record<string, unknown>;
+      if (Object.keys(props).length) for (const [k, v] of Object.entries(props)) walk(doc, v, `${path}/${k}`, seen, acc);
+      else if (open) fail("object-typed", "medium", `object '${path}' has no defined properties (a free-form bag)`, "define properties with explicit types (a closed empty object additionalProperties:false is fine for no-input)");
+      // a CLOSED object with no properties (additionalProperties:false) accepts only {} → fully bounded, clean.
+    }
+  }
+}
+
+function mark(acc: Acc, path: string, clean: boolean) { acc.nodes.set(path, (acc.nodes.get(path) ?? true) && clean); }
+
+function score(acc: Acc): Audit {
+  const nodes = acc.nodes.size;
+  const clean = [...acc.nodes.values()].filter(Boolean).length;
+  const sc = nodes === 0 ? 100 : Math.round((clean / nodes) * 100);
+  // dedupe findings by rule@path (a shared model audited under many ops collapses)
+  const seen = new Set<string>();
+  const findings = acc.findings.filter((f) => { const k = `${f.rule}@${f.path}`; if (seen.has(k)) return false; seen.add(k); return true; });
+  return { findings, nodes, clean, score: sc, grade: grade(sc) };
+}
+
+interface RawReq { method: string; contentSchema?: unknown; parameterSchema?: Record<string, unknown> }
+
+/** Audit one request's INPUT surface (request body + typed parameter slots). */
+export function auditOperation(doc: OpenAPIv4Document, uri: string, name: string, req: RawReq): OpAudit {
+  const acc: Acc = { findings: [], nodes: new Map() };
+  const ps = req.parameterSchema ?? {};
+  walk(doc, req.contentSchema ?? ps.body, `${name}/body`, new Set(), acc);
+  for (const loc of ["path", "query", "header", "cookie"] as const) walk(doc, ps[loc], `${name}/${loc}`, new Set(), acc);
+  return { ...score(acc), operation: name, method: req.method.toLowerCase(), path: uri };
+}
+
+export interface AuditOptions {
+  /** skip operations (e.g. third-party/ingested surfaces you don't author) — they don't count toward the grade. */
+  ignore?: (uri: string, name: string) => boolean;
+}
+
+/** Audit the document's input surface → per-op grades + a deduped rollup + a severity breakdown. */
+export function auditDocument(doc: OpenAPIv4Document, opts: AuditOptions = {}): DocAudit {
+  const byOperation: OpAudit[] = [];
+  const acc: Acc = { findings: [], nodes: new Map() };
+  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;
+      byOperation.push(auditOperation(doc, uri, name, req));
+      // accumulate into the doc-wide map (model-rooted paths dedupe shared schemas)
+      const ps = req.parameterSchema ?? {};
+      walk(doc, req.contentSchema ?? ps.body, `${name}/body`, new Set(), acc);
+      for (const loc of ["path", "query", "header", "cookie"] as const) walk(doc, ps[loc], `${name}/${loc}`, new Set(), acc);
+    }
+  }
+  const s = score(acc);
+  const bySeverity: Record<Severity, number> = { high: 0, medium: 0, low: 0 };
+  for (const f of s.findings) bySeverity[f.severity]++;
+  return { ...s, byOperation: byOperation.sort((a, b) => a.score - b.score), bySeverity };
+}
+
+const ORDER: Grade[] = ["F", "D", "C", "B", "A"];
+/** CI gate (the hard incentive): throw if the document's hardening grade is below `min`. */
+export function assertGrade(doc: OpenAPIv4Document, min: Grade, opts: AuditOptions = {}): DocAudit {
+  const a = auditDocument(doc, opts);
+  if (ORDER.indexOf(a.grade) < ORDER.indexOf(min)) {
+    const worst = a.byOperation.slice(0, 5).map((o) => `${o.operation} (${o.grade})`).join(", ");
+    throw new Error(`@suluk/harden: contract grade ${a.grade} (${a.score}/100) is below the required ${min}. ${a.bySeverity.high} high · ${a.bySeverity.medium} medium findings. Weakest: ${worst}. Add maxLength/pattern/maximum/maxItems + close objects.`);
+  }
+  return a;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @suluk/harden — schema hardening as a derived, scored contract facet. Audit a v4 'Suluk' document's INPUT
+ * schemas for the validations that keep malformed/oversized input from breaking the system, grade them A–F,
+ * surface the grade to incentivise the author, and gate CI on a minimum.
+ *
+ *   import { auditDocument, assertGrade } from "@suluk/harden";
+ *   const report = auditDocument(doc);   // { grade, score, byOperation, findings, bySeverity }
+ *   assertGrade(doc, "B");               // throws if the contract is too weak (the hard incentive)
+ */
+export {
+  auditDocument, auditOperation, assertGrade, grade,
+  type Audit, type OpAudit, type DocAudit, type Finding, type Severity, type Grade,
+} from "./audit";

package/test/harden.test.ts

@@ -0,0 +1,65 @@
+import { test, expect, describe } from "bun:test";
+import { auditOperation, auditDocument, assertGrade, grade } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+const weakReq = { method: "post", contentSchema: { type: "object", properties: {
+  name: { type: "string" },                                            // ✗ no maxLength, ✗ no pattern
+  age: { type: "integer" },                                            // ✗ no maximum, ✗ no minimum
+  tags: { type: "array", items: { type: "string", maxLength: 10, pattern: "^x$" } }, // ✗ no maxItems
+  meta: { type: "object" },                                            // ✗ open, ✗ no properties
+  anything: {},                                                        // ✗ any
+} } };
+const strongReq = { method: "post", contentSchema: { type: "object", additionalProperties: false, properties: {
+  name: { type: "string", maxLength: 64, pattern: "^[\\w ]+$" },
+  age: { type: "integer", minimum: 0, maximum: 130 },
+  tags: { type: "array", maxItems: 10, items: { type: "string", maxLength: 16, pattern: "^[a-z]+$" } },
+  status: { type: "string", enum: ["draft", "published"] },            // bounded by enum → clean
+} } };
+const doc = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { weak: { requests: { createWeak: weakReq } }, strong: { requests: { createStrong: strongReq } } } } as unknown as OpenAPIv4Document;
+
+describe("@suluk/harden — schema hardening as a scored facet", () => {
+  test("a weak operation collects the right findings + a low grade", () => {
+    const a = auditOperation(doc, "weak", "createWeak", weakReq);
+    const rules = new Set(a.findings.map((f) => f.rule));
+    expect(rules).toContain("no-any");
+    expect(rules).toContain("string-max-length");
+    expect(rules).toContain("string-pattern");
+    expect(rules).toContain("number-maximum");
+    expect(rules).toContain("array-max-items");
+    expect(rules).toContain("object-closed");
+    expect(rules).toContain("object-typed");
+    expect(["D", "F"]).toContain(a.grade);
+    expect(a.findings.find((f) => f.rule === "string-max-length")!.fix).toContain("maxLength");
+  });
+
+  test("a fully-hardened operation scores A (enum/const + bounds count as clean)", () => {
+    const a = auditOperation(doc, "strong", "createStrong", strongReq);
+    expect(a.findings).toEqual([]);
+    expect(a.score).toBe(100);
+    expect(a.grade).toBe("A");
+  });
+
+  test("auditDocument rolls up per-op grades + a severity breakdown, weakest first", () => {
+    const d = auditDocument(doc);
+    expect(d.byOperation[0].operation).toBe("createWeak"); // weakest first
+    expect(d.bySeverity.high).toBeGreaterThan(0);
+    expect(d.grade).toBe(grade(d.score));
+    expect(d.byOperation.find((o) => o.operation === "createStrong")!.grade).toBe("A");
+  });
+
+  test("assertGrade is the CI gate — throws below the minimum, passes a hardened doc", () => {
+    expect(() => assertGrade(doc, "A")).toThrow(/grade .* below the required A/);
+    const strongDoc = { openapi: "4.0.0-candidate", info: { title: "T" }, paths: { strong: { requests: { createStrong: strongReq } } } } as unknown as OpenAPIv4Document;
+    expect(assertGrade(strongDoc, "A").grade).toBe("A");
+  });
+
+  test("$ref'd models dedupe across operations (audited once)", () => {
+    const refDoc = { openapi: "4.0.0-candidate", info: { title: "T" },
+      paths: { a: { requests: { createA: { method: "post", contentSchema: { $ref: "#/components/schemas/Thing" } } } }, b: { requests: { createB: { method: "post", contentSchema: { $ref: "#/components/schemas/Thing" } } } } },
+      components: { schemas: { Thing: { type: "object", additionalProperties: false, properties: { x: { type: "string" } } } } },
+    } as unknown as OpenAPIv4Document;
+    const d = auditDocument(refDoc);
+    // Thing.x (no maxLength/pattern) is ONE node deduped across both ops → one string-max-length finding, not two
+    expect(d.findings.filter((f) => f.rule === "string-max-length").length).toBe(1);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }