59 lines
2.1 KiB
Markdown
59 lines
2.1 KiB
Markdown
# 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);
|
|
```
|