first commit

docs/security-stack/security/slsa/src/provenance/digest.md

@@ -0,0 +1,58 @@
+# digest
+
+## Purpose
+
+Single canonical entry point for SHA-256 digest computation inside the SLSA
+package. Deliberately routes through `@suaveplan/crypto-hash` instead of
+`node:crypto` so the primitive selector layer chooses the correct backend
+(Noble / WebCrypto / native) at build time, and so the package stays
+runtime-agnostic for non-Node environments.
+
+## Features
+
+- Accepts `Uint8Array` or UTF-8 strings.
+- Returns lowercase hex via `@suaveplan/crypto-utils`'s `toHex`.
+- Uses the package-wide `sha256` selector — no direct noble/webcrypto import.
+
+## Usage: Basic Example
+
+```ts
+import { computeDigest } from "@suaveplan/slsa";
+
+const d = computeDigest("hello");
+```
+
+## Usage: Advanced Example
+
+```ts
+import { computeDigest } from "@suaveplan/slsa";
+import fs from "node:fs/promises";
+
+const artifact = await fs.readFile("./dist/@suaveplan-utils-1.2.3.tgz");
+const digest = computeDigest(new Uint8Array(artifact));
+// feed into generateProvenance({ artifactDigest: digest, ... })
+```
+
+## API Reference
+
+- `computeDigest(content: Uint8Array | string): string` — returns a 64-char
+  lowercase hex SHA-256. Strings are encoded as UTF-8 before hashing.
+
+## Implementation Notes
+
+The string branch uses `TextEncoder` (available in all modern Node / Bun /
+browsers) rather than `Buffer.from(str)` so the helper remains universal.
+SHA-512 is intentionally not exposed here — callers that need it should
+compose `sha512` from `@suaveplan/crypto-hash` with `toHex` directly, which
+keeps the SLSA surface tight and the digest format homogeneous.
+
+### Hash Family
+
+`digestProvenance` computes the SHA-256 of the canonical-JSON encoding of an in-toto statement and returns it as a hex string. SHA-256 is the only algorithm currently surfaced because it is the only one the Sigstore transparency log (Rekor) accepts for hashedrekord v0.0.2 entries. The helper composes `canonicalJson` and `sha256` from `@suaveplan/crypto-hash` so there is no custom hashing logic local to this module.
+
+## Further Usage: Basic Example
+
+```ts
+import { digestProvenance } from "@suaveplan/slsa/provenance/digest";
+const hex = await digestProvenance({ _type: "https://in-toto.io/Statement/v1" } as any);
+```