API: Don't do I/O in sign/verify APIs

[woodruffw]

This is an unnecessary source of errors/unpredictability. Instead of taking Path, these APIs should take a filename: str for the subject and digest: str for the expected content match.

[facutuesca]

Thinking out loud about this: In a sense, this makes the API leakier about the details of the Attestation object: we go from sign(artifact) and verify(artifact) to sign(filename, digest) and verify(filename, digest), which to someone not familiar with the attestations objects can be confusing, and it's a worse dev experience for the callers of this library.

Is the convenience of not having to open files and calculate the hashes ourselves worth it?

[woodruffw]

Agreed, although convenience is not the main motivator here:

1. Removing I/O from these APIs removes an error class that "taints" the rest of the API: we either need to leak these I/O errors as their own types, or wrap them as AttestationErrors. It also means that we're at the mercy of the OS and filesystem, e.g. our API is exactly as reliable as the NFS path that someone tries to read from it 🙂
2. For PyPI specifically: PyPI is already separating the filename and performing the hash for us, so providing an API that doesn't do I/O means avoiding doing the work twice.

With that being said, I agree this is a (much) worse dev experience. Three ideas:

1. We could introduce an Artifact type/alias, which would just be a namedtuple or similar of (subject, digest). This would allow us to provide a (slightly) nicer API while still not performing I/O on the user's provided file.
2. We could keep I/O for signing, but not for verifying. The reasoning: I/O during signing is more acceptable (there's network, etc. happening as well), while during verifying it's duplicated effort (per point about PyPI above). This leads to a split interface, but maybe it's worth it.
3. We provide both I/O and non-I/O APIs.

Thoughts?

[facutuesca]

I like the Artifact namedtuple idea!