More docs for sumdb by mhutchinson · Pull Request #46 · transparency-dev/incubator

mhutchinson · 2025-09-24T16:38:25Z

No description provided.

AlCutter · 2025-09-25T10:19:32Z

-[Tessera]: https://github.com/transparency-dev/tessera
+### Background
+
+The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered.


Suggested change

The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered.

The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered in transit.

Not sure about this one - it could have also been altered at rest?

That was more of an example, I should've been clearer - currently it kinda reads like "everyone gets something which isn't malicious", but could be made clearer by either trimming to be "... the exact version of the code that others are using." or it needs some sort of clarifying qualification (which is what I mean by "more of an example").

AlCutter · 2025-09-25T10:25:12Z

+In addition to sum.golang.org, there is also an index at index.golang.org. This index provides a convenient way to discover available Go modules and their versions. However, it's important to note that index.golang.org is not verifiable in the same way as sum.golang.org. While it helps with discovery, it does not offer the same cryptographic guarantees of integrity and immutability as the checksum database. The security and verification of module content rely solely on the auditable records within sum.golang.org.
+
+The entries in the SumDB log match what is written in a `go.sum` file.
+For example, any project depending on the v1.0 release of Tessera will have the following in its `go.sum` file:
+
+```
+github.com/transparency-dev/tessera v1.0.0 h1:4OT1V9xJLa5NnYlFWWlCdZkCm18/o12rdd+bCTje7XE=
+github.com/transparency-dev/tessera v1.0.0/go.mod h1:TLvfjlkbmsmKVEJUtzO2eb9Q2IBnK3EJ0dI4G0oxEOU=
+```
+
+This is the same content written to the SumDB at index 43930254 ([query link](https://sum.golang.org/lookup/github.com/transparency-dev/tessera@v1.0.0)).
+
+The index is built from this log of modules by parsing the module name from every leaf. A pointer to the leaf is added to the index if it represents a [non-pseudo](https://pkg.go.dev/golang.org/x/mod@v0.28.0/module#IsPseudoVersion) version.
+The index can be [queried](#querying) using the client.
+


The flow of this section could be improved. Currently it jumps around a lot - I think the para about index.golang.org is the culprit, could this be moved down to replace/incorporate the "The index is built from this log ..." bit?

Reworked, PTAL?

Much better, ta!

AlCutter · 2025-09-25T10:30:30Z

 ```

-Use left/right cursor to browse, and `q` to quit.
+Note that this matches the list of entries on the unverifiable proxy endpoint: https://proxy.golang.org/github.com/transparency-dev/tessera/@v/list.


Would probably be good to introduce the proxy service in the background bit too?

mhutchinson

Ta! PTAL?

mhutchinson · 2025-09-25T11:36:00Z

-[Tessera]: https://github.com/transparency-dev/tessera
+### Background
+
+The sum.golang.org service, often referred to as Go Checksum DB or SumDB, serves as an auditable checksum database for Go modules. Its primary purpose is to enhance the security and integrity of the Go module ecosystem by providing a public, tamper-proof record of module checksums. This ensures that when developers fetch a module, they receive the exact version of the code that others are using and that hasn't been maliciously altered.


Not sure about this one - it could have also been altered at rest?

mhutchinson · 2025-09-25T11:40:13Z

+In addition to sum.golang.org, there is also an index at index.golang.org. This index provides a convenient way to discover available Go modules and their versions. However, it's important to note that index.golang.org is not verifiable in the same way as sum.golang.org. While it helps with discovery, it does not offer the same cryptographic guarantees of integrity and immutability as the checksum database. The security and verification of module content rely solely on the auditable records within sum.golang.org.
+
+The entries in the SumDB log match what is written in a `go.sum` file.
+For example, any project depending on the v1.0 release of Tessera will have the following in its `go.sum` file:
+
+```
+github.com/transparency-dev/tessera v1.0.0 h1:4OT1V9xJLa5NnYlFWWlCdZkCm18/o12rdd+bCTje7XE=
+github.com/transparency-dev/tessera v1.0.0/go.mod h1:TLvfjlkbmsmKVEJUtzO2eb9Q2IBnK3EJ0dI4G0oxEOU=
+```
+
+This is the same content written to the SumDB at index 43930254 ([query link](https://sum.golang.org/lookup/github.com/transparency-dev/tessera@v1.0.0)).
+
+The index is built from this log of modules by parsing the module name from every leaf. A pointer to the leaf is added to the index if it represents a [non-pseudo](https://pkg.go.dev/golang.org/x/mod@v0.28.0/module#IsPseudoVersion) version.
+The index can be [queried](#querying) using the client.
+


Reworked, PTAL?

mhutchinson · 2025-09-25T11:49:50Z

I've got a better tool for SumDB module authors in a branch that builds on this one: https://github.com/transparency-dev/incubator/compare/main...mhutchinson:incubator:sumdb-fulltool?expand=1

I'll turn that into a PR when this is merged.

mhutchinson assigned AlCutter Sep 24, 2025

mhutchinson requested a review from AlCutter September 24, 2025 16:38

mhutchinson force-pushed the moredocs branch from e4b03d9 to ee4e38e Compare September 25, 2025 09:24

More docs for sumdb

1c77442

mhutchinson force-pushed the moredocs branch from ee4e38e to 1c77442 Compare September 25, 2025 09:31

AlCutter reviewed Sep 25, 2025

View reviewed changes

AlCutter approved these changes Sep 25, 2025

View reviewed changes

review comments

a986b45

mhutchinson commented Sep 25, 2025

View reviewed changes

AlCutter approved these changes Sep 25, 2025

View reviewed changes

mhutchinson merged commit 0882f40 into transparency-dev:main Sep 25, 2025
6 checks passed

Uh oh!

Conversation

mhutchinson commented Sep 24, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mhutchinson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mhutchinson commented Sep 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants