first commit

docs/security-stack/security/hibp/src/error-codes.md

@@ -0,0 +1,63 @@
+# `error-codes.ts`
+
+## Purpose
+
+Hosts the canonical `HIBP_CODES` registry — exactly seven error codes that
+classify every failure path inside `@suaveplan/hibp`. Lives at the package
+root (rather than in a nested `errors/` directory) so the
+`scripts/conformance.ts` scanner can find it and verify every code
+is actually thrown by at least one production source file.
+
+## Features
+
+- Seven stable codes — `RATE_LIMITED`, `UNAUTHORIZED`, `NOT_FOUND`,
+  `MALFORMED_RESPONSE`, `NETWORK_ERROR`, `ABORTED`, `PAYLOAD_TOO_LARGE`.
+- Each value is the namespaced `HIBP.<KEY>` form, suitable for stable
+  string matching in logs and structured-error registries.
+- Registered through `defineCodes` from `@suaveplan/error` so the wider
+  registry knows the namespace and can validate it at startup.
+
+## Usage: Basic Example
+
+```ts
+import { HIBP_CODES, type HibpErrorCode } from "@suaveplan/hibp";
+
+function isFatal(code: HibpErrorCode): boolean {
+    return code === HIBP_CODES.MALFORMED_RESPONSE;
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { HibpError, HIBP_CODES } from "@suaveplan/hibp";
+
+export function classifyHibpFailure(err: unknown): "retry" | "abort" | "report" {
+    if (!(err instanceof HibpError)) return "report";
+    switch (err.code) {
+        case HIBP_CODES.RATE_LIMITED:
+        case HIBP_CODES.NETWORK_ERROR:
+            return "retry";
+        case HIBP_CODES.ABORTED:
+            return "abort";
+        default:
+            return "report";
+    }
+}
+```
+
+## API Reference
+
+- `HIBP_CODES` — frozen record. Keys are bare names (`RATE_LIMITED`, …);
+  values are namespaced strings (`"HIBP.RATE_LIMITED"`, …).
+- `HibpErrorCode` — string-literal union of every registered value.
+
+## Implementation Notes
+
+The seven codes were chosen so each one corresponds to a distinct caller
+remediation path: rate-limit backoff, credential rotation, resource
+absence, schema regression, transport failure, user-driven cancellation,
+and over-sized response. Adding a new code is a breaking change because
+downstream consumers fan out on `code` literally. Removing a code is
+likewise breaking and forbidden by the conformance gate, which verifies
+every registered code is thrown by at least one production path.