pypi_attestations

The pypi-attestations APIs.

 1"""The `pypi-attestations` APIs."""
 2
 3__version__ = "0.0.31"
 4
 5from ._impl import (
 6    Attestation,
 7    AttestationBundle,
 8    AttestationError,
 9    AttestationType,
10    CircleCIPublisher,
11    ConversionError,
12    Distribution,
13    Envelope,
14    GitHubPublisher,
15    GitLabPublisher,
16    GooglePublisher,
17    Provenance,
18    Publisher,
19    TransparencyLogEntry,
20    VerificationError,
21    VerificationMaterial,
22)
23
24__all__ = [
25    "Attestation",
26    "AttestationBundle",
27    "AttestationError",
28    "AttestationType",
29    "CircleCIPublisher",
30    "ConversionError",
31    "Distribution",
32    "Envelope",
33    "GitHubPublisher",
34    "GitLabPublisher",
35    "GooglePublisher",
36    "Provenance",
37    "Publisher",
38    "TransparencyLogEntry",
39    "VerificationError",
40    "VerificationMaterial",
41]
class Attestation(pydantic.main.BaseModel):
154class Attestation(BaseModel):
155    """Attestation object as defined in PEP 740."""
156
157    version: Literal[1]
158    """
159    The attestation format's version, which is always 1.
160    """
161
162    verification_material: VerificationMaterial
163    """
164    Cryptographic materials used to verify `message_signature`.
165    """
166
167    envelope: Envelope
168    """
169    The enveloped attestation statement and signature.
170    """
171
172    @property
173    def statement(self) -> dict[str, Any]:
174        """Return the statement within this attestation's envelope.
175
176        The value returned here is a dictionary, in the shape of an
177        in-toto statement.
178        """
179        return json.loads(self.envelope.statement)  # type: ignore[no-any-return]
180
181    @classmethod
182    def sign(cls, signer: Signer, dist: Distribution) -> Attestation:
183        """Create an envelope, with signature, from the given Python distribution.
184
185        On failure, raises `AttestationError`.
186        """
187        try:
188            stmt = (
189                StatementBuilder()
190                .subjects(
191                    [
192                        Subject(
193                            name=dist.name,
194                            digest=DigestSet(root={"sha256": dist.digest}),
195                        )
196                    ]
197                )
198                .predicate_type(AttestationType.PYPI_PUBLISH_V1)
199                .build()
200            )
201        except SigstoreError as e:
202            raise AttestationError(str(e))
203
204        try:
205            bundle = signer.sign_dsse(stmt)
206        except (ExpiredCertificate, ExpiredIdentity) as e:
207            raise AttestationError(str(e))
208
209        try:
210            return Attestation.from_bundle(bundle)
211        except ConversionError as e:
212            raise AttestationError(str(e))
213
214    @property
215    def certificate_claims(self) -> dict[str, str]:
216        """Return the claims present in the certificate.
217
218        We only return claims present in `_FULCIO_CLAIMS_OIDS`.
219        Values are decoded and returned as strings.
220        """
221        certificate = x509.load_der_x509_certificate(self.verification_material.certificate)
222        claims = {}
223        for extension in certificate.extensions:
224            if extension.oid in _FULCIO_CLAIMS_OIDS:
225                # 1.3.6.1.4.1.57264.1.8 through 1.3.6.1.4.1.57264.1.22 are formatted as DER-encoded
226                # strings; the ASN.1 tag is UTF8String (0x0C) and the tag class is universal.
227                value = extension.value.value
228                claims[extension.oid.dotted_string] = asn1.decode_der(str, value)
229
230        return claims
231
232    def verify(
233        self,
234        identity: VerificationPolicy | Publisher,
235        dist: Distribution,
236        *,
237        staging: bool = False,
238        offline: bool = False,
239    ) -> tuple[str, dict[str, Any] | None]:
240        """Verify against an existing Python distribution.
241
242        The `identity` can be an object confirming to
243        `sigstore.policy.VerificationPolicy` or a `Publisher`, which will be
244        transformed into an appropriate verification policy.
245
246        By default, Sigstore's production verifier will be used. The
247        `staging` parameter can be toggled to enable the staging verifier
248        instead.
249
250        If `offline` is `True`, the verifier will not attempt to refresh the
251        TUF repository.
252
253        On failure, raises an appropriate subclass of `AttestationError`.
254        """
255        # NOTE: Can't do `isinstance` with `Publisher` since it's
256        # a `_GenericAlias`; instead we punch through to the inner
257        # `_Publisher` union.
258        if isinstance(identity, _Publisher):
259            policy = identity._as_policy()  # noqa: SLF001
260        else:
261            policy = identity
262
263        if staging:
264            verifier = Verifier.staging(offline=offline)
265        else:
266            verifier = Verifier.production(offline=offline)
267
268        bundle = self.to_bundle()
269        try:
270            type_, payload = verifier.verify_dsse(bundle, policy)
271        except sigstore.errors.VerificationError as err:
272            raise VerificationError(str(err)) from err
273
274        if type_ != DsseEnvelope._TYPE:  # noqa: SLF001
275            raise VerificationError(f"expected JSON envelope, got {type_}")
276
277        try:
278            statement = _Statement.model_validate_json(payload)
279        except ValidationError as e:
280            raise VerificationError(f"invalid statement: {str(e)}")
281
282        if len(statement.subjects) != 1:
283            raise VerificationError("too many subjects in statement (must be exactly one)")
284        subject = statement.subjects[0]
285
286        if not subject.name:
287            raise VerificationError("invalid subject: missing name")
288
289        try:
290            # We don't allow signing of malformed distribution names.
291            # Previous versions of this package went further than this
292            # and "ultranormalized" the name, but this was superfluous
293            # and caused confusion for users who expected the subject to
294            # be an exact match for their distribution filename.
295            # See: https://github.com/pypi/warehouse/issues/18128
296            # See: https://github.com/pypi/pypi-attestations/issues/123
297            parsed_subject_name = _check_dist_filename(subject.name)
298        except ValueError as e:
299            raise VerificationError(f"invalid subject: {str(e)}")
300
301        # NOTE: Cannot fail, since we validate the `Distribution` name
302        # on construction.
303        parsed_dist_name = _check_dist_filename(dist.name)
304
305        if parsed_subject_name != parsed_dist_name:
306            raise VerificationError(
307                f"subject does not match distribution name: {subject.name} != {dist.name}"
308            )
309
310        digest = subject.digest.root.get("sha256")
311        if digest is None or digest != dist.digest:
312            raise VerificationError("subject does not match distribution digest")
313
314        try:
315            AttestationType(statement.predicate_type)
316        except ValueError:
317            raise VerificationError(f"unknown attestation type: {statement.predicate_type}")
318
319        return statement.predicate_type, statement.predicate
320
321    def to_bundle(self) -> Bundle:
322        """Convert a PyPI attestation object as defined in PEP 740 into a Sigstore Bundle."""
323        cert_bytes = self.verification_material.certificate
324        statement = self.envelope.statement
325        signature = self.envelope.signature
326
327        evp = DsseEnvelope(
328            _Envelope(
329                payload=base64.b64encode(statement),
330                payload_type=DsseEnvelope._TYPE,  # noqa: SLF001
331                signatures=[_Signature(sig=base64.b64encode(signature))],
332            )
333        )
334
335        tlog_entry = self.verification_material.transparency_entries[0]
336        try:
337            certificate = x509.load_der_x509_certificate(cert_bytes)
338        except ValueError as err:
339            raise ConversionError("invalid X.509 certificate") from err
340
341        try:
342            inner = _TransparencyLogEntryInner.from_dict(tlog_entry)
343            log_entry = _TransparencyLogEntry(inner)
344        except (ValidationError, sigstore.errors.Error) as err:
345            raise ConversionError("invalid transparency log entry") from err
346
347        return Bundle._from_parts(  # noqa: SLF001
348            cert=certificate,
349            content=evp,
350            log_entry=log_entry,
351        )
352
353    @classmethod
354    def from_bundle(cls, sigstore_bundle: Bundle) -> Attestation:
355        """Convert a Sigstore Bundle into a PyPI attestation as defined in PEP 740."""
356        certificate = sigstore_bundle.signing_certificate.public_bytes(
357            encoding=serialization.Encoding.DER
358        )
359
360        envelope = sigstore_bundle._inner.dsse_envelope  # noqa: SLF001
361
362        if not envelope:
363            raise ConversionError("bundle does not contain a DSSE envelope")
364
365        if len(envelope.signatures) != 1:
366            raise ConversionError(f"expected exactly one signature, got {len(envelope.signatures)}")
367
368        return cls(
369            version=1,
370            verification_material=VerificationMaterial(
371                certificate=base64.b64encode(certificate),
372                transparency_entries=[
373                    sigstore_bundle.log_entry._inner.to_dict()  # noqa: SLF001
374                ],
375            ),
376            envelope=Envelope(
377                statement=base64.b64encode(envelope.payload),
378                signature=base64.b64encode(envelope.signatures[0].sig),
379            ),
380        )

Attestation object as defined in PEP 740.

version: Literal[1] = PydanticUndefined

The attestation format's version, which is always 1.

verification_material: VerificationMaterial = PydanticUndefined

Cryptographic materials used to verify message_signature.

envelope: Envelope = PydanticUndefined

The enveloped attestation statement and signature.

statement: dict[str, typing.Any]
172    @property
173    def statement(self) -> dict[str, Any]:
174        """Return the statement within this attestation's envelope.
175
176        The value returned here is a dictionary, in the shape of an
177        in-toto statement.
178        """
179        return json.loads(self.envelope.statement)  # type: ignore[no-any-return]

Return the statement within this attestation's envelope.

The value returned here is a dictionary, in the shape of an in-toto statement.

@classmethod
def sign( cls, signer: sigstore.sign.Signer, dist: Distribution) -> Attestation:
181    @classmethod
182    def sign(cls, signer: Signer, dist: Distribution) -> Attestation:
183        """Create an envelope, with signature, from the given Python distribution.
184
185        On failure, raises `AttestationError`.
186        """
187        try:
188            stmt = (
189                StatementBuilder()
190                .subjects(
191                    [
192                        Subject(
193                            name=dist.name,
194                            digest=DigestSet(root={"sha256": dist.digest}),
195                        )
196                    ]
197                )
198                .predicate_type(AttestationType.PYPI_PUBLISH_V1)
199                .build()
200            )
201        except SigstoreError as e:
202            raise AttestationError(str(e))
203
204        try:
205            bundle = signer.sign_dsse(stmt)
206        except (ExpiredCertificate, ExpiredIdentity) as e:
207            raise AttestationError(str(e))
208
209        try:
210            return Attestation.from_bundle(bundle)
211        except ConversionError as e:
212            raise AttestationError(str(e))

Create an envelope, with signature, from the given Python distribution.

On failure, raises AttestationError.

certificate_claims: dict[str, str]
214    @property
215    def certificate_claims(self) -> dict[str, str]:
216        """Return the claims present in the certificate.
217
218        We only return claims present in `_FULCIO_CLAIMS_OIDS`.
219        Values are decoded and returned as strings.
220        """
221        certificate = x509.load_der_x509_certificate(self.verification_material.certificate)
222        claims = {}
223        for extension in certificate.extensions:
224            if extension.oid in _FULCIO_CLAIMS_OIDS:
225                # 1.3.6.1.4.1.57264.1.8 through 1.3.6.1.4.1.57264.1.22 are formatted as DER-encoded
226                # strings; the ASN.1 tag is UTF8String (0x0C) and the tag class is universal.
227                value = extension.value.value
228                claims[extension.oid.dotted_string] = asn1.decode_der(str, value)
229
230        return claims

Return the claims present in the certificate.

We only return claims present in _FULCIO_CLAIMS_OIDS. Values are decoded and returned as strings.

def verify( self, identity: sigstore.verify.policy.VerificationPolicy | Annotated[GitHubPublisher | GitLabPublisher | GooglePublisher | CircleCIPublisher, FieldInfo(annotation=NoneType, required=True, discriminator='kind')], dist: Distribution, *, staging: bool = False, offline: bool = False) -> tuple[str, dict[str, typing.Any] | None]:
232    def verify(
233        self,
234        identity: VerificationPolicy | Publisher,
235        dist: Distribution,
236        *,
237        staging: bool = False,
238        offline: bool = False,
239    ) -> tuple[str, dict[str, Any] | None]:
240        """Verify against an existing Python distribution.
241
242        The `identity` can be an object confirming to
243        `sigstore.policy.VerificationPolicy` or a `Publisher`, which will be
244        transformed into an appropriate verification policy.
245
246        By default, Sigstore's production verifier will be used. The
247        `staging` parameter can be toggled to enable the staging verifier
248        instead.
249
250        If `offline` is `True`, the verifier will not attempt to refresh the
251        TUF repository.
252
253        On failure, raises an appropriate subclass of `AttestationError`.
254        """
255        # NOTE: Can't do `isinstance` with `Publisher` since it's
256        # a `_GenericAlias`; instead we punch through to the inner
257        # `_Publisher` union.
258        if isinstance(identity, _Publisher):
259            policy = identity._as_policy()  # noqa: SLF001
260        else:
261            policy = identity
262
263        if staging:
264            verifier = Verifier.staging(offline=offline)
265        else:
266            verifier = Verifier.production(offline=offline)
267
268        bundle = self.to_bundle()
269        try:
270            type_, payload = verifier.verify_dsse(bundle, policy)
271        except sigstore.errors.VerificationError as err:
272            raise VerificationError(str(err)) from err
273
274        if type_ != DsseEnvelope._TYPE:  # noqa: SLF001
275            raise VerificationError(f"expected JSON envelope, got {type_}")
276
277        try:
278            statement = _Statement.model_validate_json(payload)
279        except ValidationError as e:
280            raise VerificationError(f"invalid statement: {str(e)}")
281
282        if len(statement.subjects) != 1:
283            raise VerificationError("too many subjects in statement (must be exactly one)")
284        subject = statement.subjects[0]
285
286        if not subject.name:
287            raise VerificationError("invalid subject: missing name")
288
289        try:
290            # We don't allow signing of malformed distribution names.
291            # Previous versions of this package went further than this
292            # and "ultranormalized" the name, but this was superfluous
293            # and caused confusion for users who expected the subject to
294            # be an exact match for their distribution filename.
295            # See: https://github.com/pypi/warehouse/issues/18128
296            # See: https://github.com/pypi/pypi-attestations/issues/123
297            parsed_subject_name = _check_dist_filename(subject.name)
298        except ValueError as e:
299            raise VerificationError(f"invalid subject: {str(e)}")
300
301        # NOTE: Cannot fail, since we validate the `Distribution` name
302        # on construction.
303        parsed_dist_name = _check_dist_filename(dist.name)
304
305        if parsed_subject_name != parsed_dist_name:
306            raise VerificationError(
307                f"subject does not match distribution name: {subject.name} != {dist.name}"
308            )
309
310        digest = subject.digest.root.get("sha256")
311        if digest is None or digest != dist.digest:
312            raise VerificationError("subject does not match distribution digest")
313
314        try:
315            AttestationType(statement.predicate_type)
316        except ValueError:
317            raise VerificationError(f"unknown attestation type: {statement.predicate_type}")
318
319        return statement.predicate_type, statement.predicate

Verify against an existing Python distribution.

The identity can be an object confirming to sigstore.policy.VerificationPolicy or a Publisher, which will be transformed into an appropriate verification policy.

By default, Sigstore's production verifier will be used. The staging parameter can be toggled to enable the staging verifier instead.

If offline is True, the verifier will not attempt to refresh the TUF repository.

On failure, raises an appropriate subclass of AttestationError.

def to_bundle(self) -> sigstore.models.Bundle:
321    def to_bundle(self) -> Bundle:
322        """Convert a PyPI attestation object as defined in PEP 740 into a Sigstore Bundle."""
323        cert_bytes = self.verification_material.certificate
324        statement = self.envelope.statement
325        signature = self.envelope.signature
326
327        evp = DsseEnvelope(
328            _Envelope(
329                payload=base64.b64encode(statement),
330                payload_type=DsseEnvelope._TYPE,  # noqa: SLF001
331                signatures=[_Signature(sig=base64.b64encode(signature))],
332            )
333        )
334
335        tlog_entry = self.verification_material.transparency_entries[0]
336        try:
337            certificate = x509.load_der_x509_certificate(cert_bytes)
338        except ValueError as err:
339            raise ConversionError("invalid X.509 certificate") from err
340
341        try:
342            inner = _TransparencyLogEntryInner.from_dict(tlog_entry)
343            log_entry = _TransparencyLogEntry(inner)
344        except (ValidationError, sigstore.errors.Error) as err:
345            raise ConversionError("invalid transparency log entry") from err
346
347        return Bundle._from_parts(  # noqa: SLF001
348            cert=certificate,
349            content=evp,
350            log_entry=log_entry,
351        )

Convert a PyPI attestation object as defined in PEP 740 into a Sigstore Bundle.

@classmethod
def from_bundle( cls, sigstore_bundle: sigstore.models.Bundle) -> Attestation:
353    @classmethod
354    def from_bundle(cls, sigstore_bundle: Bundle) -> Attestation:
355        """Convert a Sigstore Bundle into a PyPI attestation as defined in PEP 740."""
356        certificate = sigstore_bundle.signing_certificate.public_bytes(
357            encoding=serialization.Encoding.DER
358        )
359
360        envelope = sigstore_bundle._inner.dsse_envelope  # noqa: SLF001
361
362        if not envelope:
363            raise ConversionError("bundle does not contain a DSSE envelope")
364
365        if len(envelope.signatures) != 1:
366            raise ConversionError(f"expected exactly one signature, got {len(envelope.signatures)}")
367
368        return cls(
369            version=1,
370            verification_material=VerificationMaterial(
371                certificate=base64.b64encode(certificate),
372                transparency_entries=[
373                    sigstore_bundle.log_entry._inner.to_dict()  # noqa: SLF001
374                ],
375            ),
376            envelope=Envelope(
377                statement=base64.b64encode(envelope.payload),
378                signature=base64.b64encode(envelope.signatures[0].sig),
379            ),
380        )

Convert a Sigstore Bundle into a PyPI attestation as defined in PEP 740.

class AttestationBundle(pydantic.main.BaseModel):
758class AttestationBundle(BaseModel):
759    """AttestationBundle object as defined in PEP 740."""
760
761    publisher: Publisher
762    """
763    The publisher associated with this set of attestations.
764    """
765
766    attestations: list[Attestation]
767    """
768    The list of attestations included in this bundle.
769    """

AttestationBundle object as defined in PEP 740.

publisher: Annotated[GitHubPublisher | GitLabPublisher | GooglePublisher | CircleCIPublisher, FieldInfo(annotation=NoneType, required=True, discriminator='kind')] = PydanticUndefined

The publisher associated with this set of attestations.

attestations: list[Attestation] = PydanticUndefined

The list of attestations included in this bundle.

class AttestationError(builtins.ValueError):
120class AttestationError(ValueError):
121    """Base error for all APIs."""

Base error for all APIs.

class AttestationType(enum.StrEnum):
113class AttestationType(StrEnum):
114    """Attestation types known to PyPI."""
115
116    SLSA_PROVENANCE_V1 = "https://slsa.dev/provenance/v1"
117    PYPI_PUBLISH_V1 = "https://docs.pypi.org/attestations/publish/v1"

Attestation types known to PyPI.

SLSA_PROVENANCE_V1 = <AttestationType.SLSA_PROVENANCE_V1: 'https://slsa.dev/provenance/v1'>
PYPI_PUBLISH_V1 = <AttestationType.PYPI_PUBLISH_V1: 'https://docs.pypi.org/attestations/publish/v1'>
class CircleCIPublisher(pypi_attestations._impl._PublisherBase):
713class CircleCIPublisher(_PublisherBase):
714    """A CircleCI-based Trusted Publisher."""
715
716    kind: Literal["CircleCI"] = "CircleCI"
717
718    project_id: str
719    """
720    The CircleCI project ID (UUID) that performed the publishing action.
721    """
722
723    pipeline_definition_id: str
724    """
725    The CircleCI pipeline definition ID (UUID) that defines the pipeline configuration.
726    This uniquely identifies the specific pipeline definition allowed to publish.
727    """
728
729    vcs_origin: str | None = None
730    """
731    The optional source repository URI that triggered the pipeline.
732    This comes from the oidc.circleci.com/vcs-origin claim and looks like
733    "github.com/org/repo" (without the https:// prefix).
734    Not present for pipelines triggered by custom webhooks.
735    """
736
737    vcs_ref: str | None = None
738    """
739    The optional git ref that triggered the pipeline.
740    This comes from the oidc.circleci.com/vcs-ref claim and looks like
741    "refs/heads/main" or "refs/tags/v1.0.0".
742    Not present for pipelines triggered by custom webhooks.
743    """
744
745    def _as_policy(self) -> VerificationPolicy:
746        return _CircleCITrustedPublisherPolicy(
747            self.project_id,
748            self.pipeline_definition_id,
749            self.vcs_origin,
750            self.vcs_ref,
751        )

A CircleCI-based Trusted Publisher.

kind: Literal['CircleCI'] = 'CircleCI'
project_id: str = PydanticUndefined

The CircleCI project ID (UUID) that performed the publishing action.

pipeline_definition_id: str = PydanticUndefined

The CircleCI pipeline definition ID (UUID) that defines the pipeline configuration. This uniquely identifies the specific pipeline definition allowed to publish.

vcs_origin: str | None = None

The optional source repository URI that triggered the pipeline. This comes from the oidc.circleci.com/vcs-origin claim and looks like "github.com/org/repo" (without the https:// prefix). Not present for pipelines triggered by custom webhooks.

vcs_ref: str | None = None

The optional git ref that triggered the pipeline. This comes from the oidc.circleci.com/vcs-ref claim and looks like "refs/heads/main" or "refs/tags/v1.0.0". Not present for pipelines triggered by custom webhooks.

class ConversionError(pypi_attestations.AttestationError):
124class ConversionError(AttestationError):
125    """The base error for all errors during conversion."""

The base error for all errors during conversion.

class Distribution(pydantic.main.BaseModel):
 86class Distribution(BaseModel):
 87    """Represents a Python package distribution.
 88
 89    A distribution is identified by its (sdist or wheel) filename, which
 90    provides the package name and version (at a minimum) plus a SHA-256
 91    digest, which uniquely identifies its contents.
 92    """
 93
 94    name: str
 95    digest: str
 96
 97    @field_validator("name")
 98    @classmethod
 99    def _validate_name(cls, v: str) -> str:
100        _check_dist_filename(v)
101        return v
102
103    @classmethod
104    def from_file(cls, dist: Path) -> Distribution:
105        """Construct a `Distribution` from the given path."""
106        name = dist.name
107        with dist.open(mode="rb", buffering=0) as io:
108            digest = file_digest(io, "sha256").hexdigest()
109
110        return cls(name=name, digest=digest)

Represents a Python package distribution.

A distribution is identified by its (sdist or wheel) filename, which provides the package name and version (at a minimum) plus a SHA-256 digest, which uniquely identifies its contents.

name: str = PydanticUndefined
digest: str = PydanticUndefined
@classmethod
def from_file(cls, dist: pathlib.Path) -> Distribution:
103    @classmethod
104    def from_file(cls, dist: Path) -> Distribution:
105        """Construct a `Distribution` from the given path."""
106        name = dist.name
107        with dist.open(mode="rb", buffering=0) as io:
108            digest = file_digest(io, "sha256").hexdigest()
109
110        return cls(name=name, digest=digest)

Construct a Distribution from the given path.

class Envelope(pydantic.main.BaseModel):
383class Envelope(BaseModel):
384    """The attestation envelope, containing the attested-for payload and its signature."""
385
386    statement: Base64Bytes
387    """
388    The attestation statement.
389
390    This is represented as opaque bytes on the wire (encoded as base64),
391    but it MUST be an JSON in-toto v1 Statement.
392    """
393
394    signature: Base64Bytes
395    """
396    A signature for the above statement, encoded as base64.
397    """

The attestation envelope, containing the attested-for payload and its signature.

statement: Annotated[bytes, EncodedBytes(encoder=<class 'pydantic.types.Base64Encoder'>)] = PydanticUndefined

The attestation statement.

This is represented as opaque bytes on the wire (encoded as base64), but it MUST be an JSON in-toto v1 Statement.

signature: Annotated[bytes, EncodedBytes(encoder=<class 'pydantic.types.Base64Encoder'>)] = PydanticUndefined

A signature for the above statement, encoded as base64.

class GitHubPublisher(pypi_attestations._impl._PublisherBase):
522class GitHubPublisher(_PublisherBase):
523    """A GitHub-based Trusted Publisher."""
524
525    kind: Literal["GitHub"] = "GitHub"
526
527    repository: str
528    """
529    The fully qualified publishing repository slug, e.g. `foo/bar` for
530    repository `bar` owned by `foo`.
531    """
532
533    workflow: str
534    """
535    The filename of the GitHub Actions workflow that performed the publishing
536    action.
537    """
538
539    environment: str | None = None
540    """
541    The optional name GitHub Actions environment that the publishing
542    action was performed from.
543    """
544
545    def _as_policy(self) -> VerificationPolicy:
546        return _GitHubTrustedPublisherPolicy(self.repository, self.workflow)

A GitHub-based Trusted Publisher.

kind: Literal['GitHub'] = 'GitHub'
repository: str = PydanticUndefined

The fully qualified publishing repository slug, e.g. foo/bar for repository bar owned by foo.

workflow: str = PydanticUndefined

The filename of the GitHub Actions workflow that performed the publishing action.

environment: str | None = None

The optional name GitHub Actions environment that the publishing action was performed from.

class GitLabPublisher(pypi_attestations._impl._PublisherBase):
614class GitLabPublisher(_PublisherBase):
615    """A GitLab-based Trusted Publisher."""
616
617    kind: Literal["GitLab"] = "GitLab"
618
619    repository: str
620    """
621    The fully qualified publishing repository slug, e.g. `foo/bar` for
622    repository `bar` owned by `foo` or `foo/baz/bar` for repository
623    `bar` owned by group `foo` and subgroup `baz`.
624    """
625
626    workflow_filepath: str
627    """
628    The path for the CI/CD configuration file. This is usually ".gitlab-ci.yml",
629    but can be customized.
630    """
631
632    environment: str | None = None
633    """
634    The optional environment that the publishing action was performed from.
635    """
636
637    def _as_policy(self) -> VerificationPolicy:
638        return _GitLabTrustedPublisherPolicy(self.repository, self.workflow_filepath)

A GitLab-based Trusted Publisher.

kind: Literal['GitLab'] = 'GitLab'
repository: str = PydanticUndefined

The fully qualified publishing repository slug, e.g. foo/bar for repository bar owned by foo or foo/baz/bar for repository bar owned by group foo and subgroup baz.

workflow_filepath: str = PydanticUndefined

The path for the CI/CD configuration file. This is usually ".gitlab-ci.yml", but can be customized.

environment: str | None = None

The optional environment that the publishing action was performed from.

class GooglePublisher(pypi_attestations._impl._PublisherBase):
641class GooglePublisher(_PublisherBase):
642    """A Google Cloud-based Trusted Publisher."""
643
644    kind: Literal["Google"] = "Google"
645
646    email: str
647    """
648    The email address of the Google Cloud service account that performed
649    the publishing action.
650    """
651
652    def _as_policy(self) -> VerificationPolicy:
653        return policy.Identity(identity=self.email, issuer="https://accounts.google.com")

A Google Cloud-based Trusted Publisher.

kind: Literal['Google'] = 'Google'
email: str = PydanticUndefined

The email address of the Google Cloud service account that performed the publishing action.

class Provenance(pydantic.main.BaseModel):
772class Provenance(BaseModel):
773    """Provenance object as defined in PEP 740."""
774
775    version: Literal[1] = 1
776    """
777    The provenance object's version, which is always 1.
778    """
779
780    attestation_bundles: list[AttestationBundle]
781    """
782    One or more attestation "bundles".
783    """

Provenance object as defined in PEP 740.

version: Literal[1] = 1

The provenance object's version, which is always 1.

attestation_bundles: list[AttestationBundle] = PydanticUndefined

One or more attestation "bundles".

Publisher = typing.Annotated[GitHubPublisher | GitLabPublisher | GooglePublisher | CircleCIPublisher, FieldInfo(annotation=NoneType, required=True, discriminator='kind')]
TransparencyLogEntry = TransparencyLogEntry
class VerificationError(pypi_attestations.AttestationError):
128class VerificationError(AttestationError):
129    """The PyPI Attestation failed verification."""
130
131    def __init__(self: VerificationError, msg: str) -> None:
132        """Initialize an `VerificationError`."""
133        super().__init__(f"Verification failed: {msg}")

The PyPI Attestation failed verification.

VerificationError(msg: str)
131    def __init__(self: VerificationError, msg: str) -> None:
132        """Initialize an `VerificationError`."""
133        super().__init__(f"Verification failed: {msg}")

Initialize an VerificationError.

class VerificationMaterial(pydantic.main.BaseModel):
139class VerificationMaterial(BaseModel):
140    """Cryptographic materials used to verify attestation objects."""
141
142    certificate: Base64Bytes
143    """
144    The signing certificate, as `base64(DER(cert))`.
145    """
146
147    transparency_entries: Annotated[list[TransparencyLogEntry], MinLen(1)]
148    """
149    One or more transparency log entries for this attestation's signature
150    and certificate.
151    """

Cryptographic materials used to verify attestation objects.

certificate: Annotated[bytes, EncodedBytes(encoder=<class 'pydantic.types.Base64Encoder'>)] = PydanticUndefined

The signing certificate, as base64(DER(cert)).

transparency_entries: Annotated[list[TransparencyLogEntry], MinLen(min_length=1)] = PydanticUndefined

One or more transparency log entries for this attestation's signature and certificate.