ci-oidc-provider

Signing Architecture

The core insight is that Fulcio's role — issuing short-lived certificates with provenance claims — can be performed by the CI action itself. The action reads the build environment, extracts the cosign public key from the encrypted cosign key, creates an X.509 certificate containing both the public key and provenance OID extensions, and signs it with the CA key:

CA key (OIDC_SIGNING_KEY)
  └─ signs X.509 certificate containing:
        ├─ cosign public key (extracted from COSIGN_KEY)
        └─ Fulcio OID extensions:
            ├─ 1.3.6.1.4.1.57264.1.1   issuer URL
            ├─ 1.3.6.1.4.1.57264.1.12  source repository URI
            ├─ 1.3.6.1.4.1.57264.1.13  source repository digest (commit SHA)
            ├─ 1.3.6.1.4.1.57264.1.14  source repository ref
            ├─ 1.3.6.1.4.1.57264.1.9   build signer URI (workflow)
            ├─ 1.3.6.1.4.1.57264.1.20  build trigger
            └─ 1.3.6.1.4.1.57264.1.21  run invocation URI

cosign key (COSIGN_KEY)
  └─ signs Docker images (cosign sign --key --certificate)
  └─ signs binary blobs (cosign sign-blob --key)

The certificate's public key matches cosign's public key, so consumers can verify both the signature (via cosign) and the provenance (by reading the certificate's OID extensions). This is the same certificate format that Fulcio produces — the only difference is that the CA is your own key rather than Sigstore's public CA.

Action vs. Sidecar Mode

Action mode (Gitea, GitHub, Forgejo): Runs as a composite action step inside the workflow. Reads provenance from GITHUB_* environment variables. Outputs a certificate file. Zero infrastructure — the action binary is fetched from the action repository.

Sidecar mode (Jenkins, Woodpecker, Drone): Runs as a long-lived container alongside the CI platform. Authenticates runners via native credentials, independently resolves build context by querying the CI platform's API (runners cannot supply false claims), and issues signed OIDC tokens. Supports Prometheus metrics, structured audit logging, and emergency key rotation.

# Action mode (Gitea/GitHub) — add to your workflow:
- name: Issue signing certificate
  uses: https://git.carefuldream.com/cdos/ci-oidc-provider@main
  with:
    signing-key: ${{ secrets.OIDC_SIGNING_KEY }}
    cosign-key: ${{ secrets.COSIGN_KEY }}
    issuer: https://git.carefuldream.com/cdos/my-project.git/raw/main

# Sidecar mode (Jenkins/Woodpecker/Drone) — docker-compose:
ci-oidc-sidecar:
  image: zot.carefuldream.com/cdos/ci-oidc-provider:latest
  volumes:
    - oidc-keys:/data

OIDC Discovery via Git

OIDC discovery (RFC 8414) requires a configuration document at a well-known URL. Git forges serve raw files over HTTPS. By committing the .well-known/openid-configuration and .well-known/jwks files to a repository, the forge's existing HTTPS endpoint becomes a compliant OIDC discovery URL. The JWKS is version-controlled in git, providing an auditable history of every key change.

In our infrastructure, these files are served by gitview — a lightweight Git server that hosts read-only repositories with a web UI for browsing code, commit history, and downloading signed release binaries. Gitview's raw file endpoint serves the OIDC discovery documents, and its release system verifies cosign signatures server-side before accepting uploads.

Verification Pipeline

ci-oidc-verify uses the sigstore-go library (not a cosign subprocess) for all cryptographic verification. The pipeline runs eight steps:

The JSON provenance receipt is the contract between ci-oidc-verify and downstream tooling. Distro packagers can embed it alongside source packages to create multi-hop provenance chains without depending on ci-oidc-verify itself.

Dependency Scanner

ci-oidc-deps parses lockfiles — flat, already-resolved dependency lists that every modern package manager produces. No dependency resolution engine, no build toolchain required. Each parser is a few hundred lines:

For each dependency, the scanner checks attestation sources in priority order: local cache, public attestation index, package registry metadata (npm provenance API), convention-based URL probing, and transparency log search. Results are cached locally with configurable TTL.

The policy engine supports exemptions with expiry dates — critical for practical adoption. Without exemptions, the first scan of any real project produces a wall of "not attested" results for dependencies outside your control. Exemptions acknowledge reality while ensuring gaps are revisited. Output formats include human-readable, JSON, SARIF (for GitHub/Gitea code scanning integration), shields.io badge URLs, and PR comment markdown.