first commit

docs/security-stack/security/hibp/src/schemas/breach.schema.md

@@ -0,0 +1,68 @@
+# `schemas/breach.schema.ts`
+
+## Purpose
+
+`BreachSchema` is the Zod schema mirroring the [HIBP v3 `Breach`
+payload](https://haveibeenpwned.com/API/v3#Breach). It validates every
+documented field, so the rest of the package can assume a fully populated
+`Breach` value anywhere a parsed breach record flows. Defending the
+boundary at this layer means a server-side schema regression fails fast
+with a typed `HIBP.MALFORMED_RESPONSE` error rather than silently
+producing partial objects.
+
+## Features
+
+- Strict-required fields: missing keys throw at parse time.
+- Per-field type narrowing: `PwnCount` is a non-negative integer,
+  `DataClasses` is `string[]`, every `Is*` field is boolean.
+- Covers `IsStealerLog`, the v3 addition that earlier docs sometimes
+  miss.
+- Type alias `Breach` is exported alongside the schema so consumer code
+  stays single-source-of-truth.
+
+## Usage: Basic Example
+
+```ts
+import { BreachSchema } from "@suaveplan/hibp";
+
+const parsed = BreachSchema.parse(await response.json());
+console.log(parsed.Name);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { BreachSchema, type Breach } from "@suaveplan/hibp";
+
+export function partitionBreaches(items: unknown[]): {
+    verified: Breach[];
+    fabricated: Breach[];
+} {
+    const verified: Breach[] = [];
+    const fabricated: Breach[] = [];
+    for (const item of items) {
+        const b = BreachSchema.parse(item);
+        if (b.IsFabricated) fabricated.push(b);
+        else verified.push(b);
+    }
+    return { verified, fabricated };
+}
+```
+
+## API Reference
+
+- `BreachSchema: ZodObject` — strict v3 breach shape.
+- `Breach` — `z.infer<typeof BreachSchema>` type alias.
+
+## Implementation Notes
+
+The schema does not call `.passthrough()` deliberately — opting out of
+silent forward-compat keeps server-side schema regressions visible. If
+HIBP adds a new field, the integration test in
+`breach-client.test.ts` will fail loudly and we can decide whether to
+add it, mark it optional, or reject the response. The `IsStealerLog`
+field landed in HIBP v3 after the original spec; we include it as
+required because every breach record observed in production carries it,
+and treating it as optional would let silent regressions slip through.
+Consumers concerned about long-tail server inconsistencies can run the
+schema through `.partial()` themselves before parsing.