Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,6 @@ fuzz:
go test -fuzz=FuzzRemoveEntry -fuzztime=$(FUZZTIME) ./manifest/
go test -fuzz=FuzzRead -fuzztime=$(FUZZTIME) ./lock/
go test -fuzz=FuzzFormat -fuzztime=$(FUZZTIME) ./sniff/
go test -fuzz=FuzzParseSRI -fuzztime=$(FUZZTIME) ./integrity/
go test -fuzz=FuzzRoundTrip -fuzztime=$(FUZZTIME) ./integrity/
go test -fuzz=FuzzIsSticky -fuzztime=$(FUZZTIME) ./source/npm/
go test -fuzz=FuzzFindSignature -fuzztime=$(FUZZTIME) ./source/npm/
go test -fuzz=FuzzSafeOut -fuzztime=$(FUZZTIME) .
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@ assets:

## Lockfile

`pin.lock` is a valid CycloneDX 1.6 SBOM. Each package becomes a `library` component with the registry tarball hash; each vendored file becomes a nested `file` component with its own SHA-384, the CDN URL, and pin-specific metadata under a `pin:` property namespace. Any CycloneDX consumer (Dependency-Track, GUAC, OSV-scanner, `git-pkgs sbom`) reads it directly. `serialNumber` and `metadata.timestamp` are deliberately omitted so re-runs are byte-stable and parallel branches don't conflict on the file.
`pin.lock` is a valid CycloneDX 1.6 SBOM. Each package becomes a `library` component with the registry tarball hashes; each vendored file becomes a nested `file` component with its integrity hashes, the CDN URL, and pin-specific metadata under a `pin:` property namespace. New file entries use SHA-384. Any CycloneDX consumer (Dependency-Track, GUAC, OSV-scanner, `git-pkgs sbom`) reads it directly. `serialNumber` and `metadata.timestamp` are deliberately omitted so re-runs are byte-stable and parallel branches don't conflict on the file.

The schema is in [docs/SPEC.md](docs/SPEC.md), the defences in [docs/SECURITY.md](docs/SECURITY.md), and the adversary-by-asset model in [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md).

Expand Down Expand Up @@ -215,7 +215,7 @@ Source resolvers are pluggable by purl type. Register a new resolver for any pre
c.RegisterResolver("ipfs", myIPFSResolver{})
```

The full Client surface: `Sync`, `Verify`, `Outdated`, `Add`, `Remove`, plus the package-level `List`, `Path`, `Init`, `SBOM`, `EncodeLock`. The `manifest`, `lock`, `pinfs`, `integrity`, `cdn`, `sniff`, `source` (with `source/npm`, `source/forge`, `source/rawurl`), and `assets` sub-packages are all public.
The full Client surface: `Sync`, `Verify`, `Outdated`, `Add`, `Remove`, plus the package-level `List`, `Path`, `Init`, `SBOM`, `EncodeLock`. The `manifest`, `lock`, `pinfs`, `cdn`, `sniff`, `source` (with `source/npm`, `source/forge`, `source/rawurl`), and `assets` sub-packages are all public.

`SyncOptions.FS` redirects pin's outputs (vendored files + `pin.lock`) into anything that implements `pinfs.Writer`. The default writes to local paths under `SyncOptions.Dir`; `pinfs.NewMemory()` keeps everything in process, and a custom implementation can pipe writes into a tarball, an archive, or an in-memory build artefact.

Expand Down
20 changes: 11 additions & 9 deletions docs/SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,12 +96,14 @@ order is stable and a writer MUST produce it; a reader MAY rely on it.

- `bom-ref` equals `purl`. Both fields exist for CycloneDX consumers
that key by either.
- `hashes[0]` is the package-level integrity anchor. Encoding depends
on the source kind, summarised below:
- `hashes[]` contains the package-level integrity anchors. npm metadata may
contain several supported SRI digests; pin preserves each SHA-256, SHA-384,
and SHA-512 entry in source order. Other source kinds use one entry. Encoding
depends on the source kind, summarised below:

| Source | purl prefix | `hashes[0].alg` | `hashes[0].content` |
| Source | purl prefix | `hashes[].alg` | `hashes[].content` |
|-------------------|-----------------|--------------------------|------------------------------------------------|
| npm | `pkg:npm/` | `SHA-512` (or the algorithm in `dist.integrity`) | hex of the registry tarball |
| npm | `pkg:npm/` | each supported algorithm in `dist.integrity` | hex of the registry tarball |
| github | `pkg:github/` | `SHA-1` | hex of the resolved commit SHA |
| url (TOFU) | `pkg:generic/` | `SHA-384` | hex of the single fetched file |

Expand Down Expand Up @@ -145,11 +147,11 @@ commit SHA; writers MUST write both.
identifying the file inside the package.
- `name` is the file's path inside the package (the source-of-record path,
not the on-disk output path).
- `hashes[0]` is the Subresource Integrity hash of the file's bytes,
encoded as hex per CycloneDX convention. SHA-384 is the default
algorithm chosen because it's what browsers accept in
`<script integrity>` attributes and what jsdelivr publishes natively.
Convert hex to base64 to produce an `sha384-...` SRI string.
- `hashes[]` contains the Subresource Integrity digests of the file's bytes,
encoded as hex per CycloneDX convention. Readers preserve supported entries
in their original order. New file entries use SHA-384 because browsers accept
it in `<script integrity>` attributes and jsdelivr publishes it natively.
Convert each hex value to base64 to produce an SRI metadata list.
- `externalReferences[type=distribution]` is the CDN URL where the file
can be fetched. Recording it as transport metadata; integrity is
anchored to the package, not the CDN.
Expand Down
4 changes: 2 additions & 2 deletions docs/schema/pin.lock.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
},
"hashes": {
"type": "array",
"description": "Package-level integrity anchor. SHA-512 for npm (tarball hash); SHA-1 for github (commit SHA, hex); SHA-384 for url (per-file TOFU).",
"description": "Package-level integrity anchors. npm may carry multiple SHA-256, SHA-384, or SHA-512 tarball hashes; github uses SHA-1 for the commit; url uses SHA-384 for per-file TOFU.",
"items": { "$ref": "#/$defs/hash" }
},
"licenses": {
Expand Down Expand Up @@ -127,7 +127,7 @@
"hashes": {
"type": "array",
"minItems": 1,
"description": "Per-file Subresource Integrity hash, hex-encoded. SHA-384 by default.",
"description": "Per-file Subresource Integrity hashes, hex-encoded. New entries use SHA-384 by default.",
"items": { "$ref": "#/$defs/hash" }
},
"externalReferences": {
Expand Down
1 change: 1 addition & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ require (
github.com/git-pkgs/archives v0.5.0
github.com/git-pkgs/attestation v0.1.0
github.com/git-pkgs/cooldown v0.1.1
github.com/git-pkgs/integrity v0.1.1
github.com/git-pkgs/purl v0.1.15
github.com/git-pkgs/registries v0.6.4
github.com/git-pkgs/sbom v0.1.3
Expand Down
2 changes: 2 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,8 @@ github.com/git-pkgs/attestation v0.1.0 h1:aj10Ls05zHWPL7114r0Se8RKC/w8tJgfnzh3dU
github.com/git-pkgs/attestation v0.1.0/go.mod h1:NSctZpcwmxCiTQ6z3b4X6SCT2N7fQtuPXvizkRgPgBU=
github.com/git-pkgs/cooldown v0.1.1 h1:9OqqzCB8gANz/y44SmqGD0Jp8Qtu81D1sCbKl6Ehg7w=
github.com/git-pkgs/cooldown v0.1.1/go.mod h1:v7APuK/UouTiu8mWQZbdDmj7DfxxkGUeuhjaRB5gv9E=
github.com/git-pkgs/integrity v0.1.1 h1:nHQ7SktOiGM1dOb5BFnkdtttG/6FCgE6r5ru6QnsGts=
github.com/git-pkgs/integrity v0.1.1/go.mod h1:hxu24lcd230377hCF28JQW7sGcCbuNLqo/0ULeb+F1Q=
github.com/git-pkgs/magic v0.1.0 h1:xLrqq7CMXB9g5bJnmJyKw17Rvlh0GFiEmO6e5RFsoeY=
github.com/git-pkgs/magic v0.1.0/go.mod h1:3ndidt+yvFaI1M0aEkkzkOlFnLPkeVQASIUojazcxCI=
github.com/git-pkgs/pom v0.1.5 h1:TGT8Az2OMxGWsXnSagtUMGzZm7Oax8HrSCteA+mi0qY=
Expand Down
21 changes: 0 additions & 21 deletions integrity/bench_test.go

This file was deleted.

58 changes: 0 additions & 58 deletions integrity/fuzz_test.go

This file was deleted.

60 changes: 0 additions & 60 deletions integrity/sri.go

This file was deleted.

52 changes: 0 additions & 52 deletions integrity/sri_test.go

This file was deleted.

Loading
Loading