sign, verify: Expose sign and verify as importable modules

[tetsuo-cpp]

Closes #4

[tetsuo-cpp]

Do we also want to somehow expose the web browser workflow and ambient credential detection? The signing side of the API is hard to use without these.

Either that or only expose verification initially.

I'm writing a simple example to test the verify API to get an idea for what this looks like for users.

[tetsuo-cpp]

import base64
from pathlib import Path

from sigstore.verify import Verifier, VerificationMaterials
from sigstore.verify.policy import Identity

artifact = Path("README.md")
cert = Path("README.md.crt")
signature = Path("README.md.sig")

with artifact.open("rb") as a, cert.open("r") as c, signature.open("rb") as s:
    materials = VerificationMaterials(
        input_=a,
        cert_pem=c.read(),
        signature=base64.b64decode(s.read()),
        offline_rekor_entry=None,
    )
    verifier = Verifier.production()
    result = verifier.verify(
        materials,
        Identity(
            identity="alex.cameron@trailofbits.com",
            issuer="https://accounts.google.com",
        ),
    )
    print(result)

[woodruffw]

Do we also want to somehow expose the web browser workflow and ambient credential detection? The signing side of the API is hard to use without these.

Yeah, let's expose these as well. Let's make sure to expose the minimum surface necessary for each -- probably just the top-level functions/classes.

[tetsuo-cpp]

I moved this to_bundle method from the RekorEntry to a from_entry class method. This minimises the public API and means that it doesn't have to know about this bundle type.

[woodruffw]

That works for me. IMO it would also be acceptable to have the RekorBundle be part of the public API, since it's a well-defined public format already. But we can move forwards with this for now.

[tetsuo-cpp]

Had to do this to avoid circular imports. I figured this would be better than further complicating the tree with more modules, but I can try fixing this another way if you'd like.

[tetsuo-cpp]

The sign workflow looks reasonable too.

from pathlib import Path

from sigstore.sign import Signer
from sigstore.oidc import get_identity_token, Issuer

artifact = Path("README.md")
token = get_identity_token("sigstore", "", Issuer("https://oauth2.sigstore.dev/auth"))

with artifact.open("rb") as a:
    signer = Signer.production()
    result = signer.sign(input_=a, identity_token=token)
    print(result)

[tetsuo-cpp]

One thing to note. The constructors for Signer takes FulcioClient and RekorClient and Verifier takes RekorClient. I'm assuming we probably don't want to expose these client types yet so I've left them under _internal. I don't think this is a big deal as most users are going to instantiate with one of the production or staging class methods.

The only issue is that pydoc still generates documentation for this constructor despite it not really being a usable part of the API.

[woodruffw]

Thanks @tetsuo-cpp! I'll review in a bit.

[woodruffw]

One thing to note. The constructors for Signer takes FulcioClient and RekorClient and Verifier takes RekorClient. I'm assuming we probably don't want to expose these client types yet so I've left them under _internal. I don't think this is a big deal as most users are going to instantiate with one of the production or staging class methods.

Yeah, I don't think we want to expose those directly. I'll see about maybe hiding the constructor in the docs.

[woodruffw]

N.B.: Conceptually these common options belong at the global sigstore level, rather than embedded into each subcommand. I've moved one of them in this PR (--staging) because I needed to fix its behavior with get-identity-token, but I'll move the rest in a follow-up.

[woodruffw]

The sign workflow looks reasonable too.

from pathlib import Path

from sigstore.sign import Signer
from sigstore.oidc import get_identity_token, Issuer

artifact = Path("README.md")
token = get_identity_token("sigstore", "", Issuer("https://oauth2.sigstore.dev/auth"))

with artifact.open("rb") as a:
    signer = Signer.production()
    result = signer.sign(input_=a, identity_token=token)
    print(result)

NB, this is now:

from pathlib import Path

from sigstore.sign import Signer
from sigstore.oidc import Issuer

artifact = Path("README.md")
token = Issuer.production().identity_token()

with artifact.open("rb") as a:
    signer = Signer.production()
    result = signer.sign(input_=a, identity_token=token)
    print(result)

[woodruffw]

LGTM, but I'll wait for @di to approve since I've been modifying things.

[tetsuo-cpp]

Thanks @woodruffw. Those changes to the get_identity_token API are looking really good.

I can't approve my own PR but your changes LGTM.

[woodruffw]

I'll go ahead and merge then! 🤞