@suluk/harden 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/harden",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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/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

@@ -11,3 +11,5 @@ export {
   auditDocument, auditOperation, assertGrade, grade,
   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 } from "../src/index";
 import type { OpenAPIv4Document } from "@suluk/core";
 
 const weakReq = { method: "post", contentSchema: { type: "object", properties: {
@@ -63,3 +63,49 @@ describe("@suluk/harden — schema hardening as a scored facet", () => {
     expect(d.findings.filter((f) => f.rule === "string-max-length").length).toBe(1);
   });
 });
+
+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);
+  });
+});