softwarestatement

Overview

This package provides utilities for creating, parsing, and verifying software statement JWTs as defined in RFC 7591 Section 2.3. Software statements are signed JWTs containing client metadata, used in dynamic client registration^dcr to prove the software publisher's identity. It also includes helpers for the Trusted Issuer Token draft so you can process SPIFFE JWT-SVIDs and Verifiable Credential JWTs as software statements.

Installation

go get github.com/matoous/authlib/softwarestatement

Example

package main

import (
    "crypto/rsa"
    "fmt"
    "log"

    "github.com/golang-jwt/jwt/v5"
    "github.com/matoous/authlib/softwarestatement"
)

func main() {
    statementJWT := "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

    // Parse and validate the software statement
    claims, err := softwarestatement.ParseWithOptions(statementJWT, func(token *jwt.Token) (any, error) {
        // Return the public key for verification
        // In practice, fetch this from a JWKS endpoint or trusted source
        var publicKey *rsa.PublicKey
        // ... load public key ...
        return publicKey, nil
    }, jwt.WithAudience("https://as.example.org/register"))
    if err != nil {
        log.Fatalf("failed to parse software statement: %v", err)
    }

    fmt.Printf("Software ID: %v\n", claims.SoftwareID)
    fmt.Printf("Client Name: %v\n", claims.ClientName)
    fmt.Printf("Redirect URIs: %v\n", claims.RedirectURIs)
}

Trusted Issuer Tokens

Section 5 of the Trusted Issuer Token draft describes how SPIFFE JWT-SVIDs and VC-JWTs may be used as software statements. Use the dedicated helpers to enforce the normative requirements:

spiffeClaims, err := softwarestatement.ValidateSPIFFE(
    req.SoftwareStatement,
    jwk.Keyfunc(),
    softwarestatement.SPIFFEValidationOptions{
        TrustDomain: "spiffe://example.org",
        Audience:    "https://as.example.org/register",
        MetadataValidators: []softwarestatement.MetadataValidator{
            softwarestatement.RequireMetadata(
                softwarestatement.MetadataClientName,
                softwarestatement.MetadataRedirectURIs,
            ),
        },
    },
)

vcClaims, err := softwarestatement.ValidateVerifiableCredential(
    req.SoftwareStatement,
    jwk.Keyfunc(),
    softwarestatement.VCValidationOptions{
        TrustedIssuer: "https://issuer.example",
        Audience:      "https://as.example.org/register",
        StatusValidator: func(status map[string]any) error {
            // implement the VC revocation/status check required by your deployment
            return nil
        },
    },
)

var vcPayload struct {
    CredentialSubject map[string]any `json:"credentialSubject"`
}
if err := vcClaims.UnmarshalVC(&vcPayload); err != nil {
    log.Fatal(err)
}

Issuing trusted issuer tokens

If you operate the trusted issuer, use the helpers below to mint software statements that follow the draft's requirements before distributing them to OAuth clients:

statement, err := softwarestatement.IssueSPIFFESoftwareStatement(signingKey, softwarestatement.SPIFFEIssueOptions{
    TrustDomain: "spiffe://example.org",
    WorkloadPath: "/workload/771",
    Audience: []string{"https://as.example.org/register"},
    TTL: 10 * time.Minute,
    Metadata: &authlib.ClientRegistrationRequest{
        ClientName:   "SPIFFE Client",
        RedirectURIs: []string{"https://spiffe-app.example/callback"},
    },
})

vcStatement, err := softwarestatement.IssueVerifiableCredentialSoftwareStatement(signingKey, softwarestatement.VerifiableCredentialIssueOptions{
    Issuer:   "https://vc-issuer.example",
    Subject:  "client-123",
    Audience: []string{"https://as.example.org/register"},
    TTL:      10 * time.Minute,
    VC: map[string]any{
        "credentialSubject": map[string]any{
            "client_name": "VC Client",
        },
    },
})

SPIFFE JWT-SVID software statements

The draft's Section 5.1 defines a trust relationship between the Issuer (the SPIFFE trust domain) and the OAuth Client Registration Endpoint. ValidateSPIFFE helps you codify that relationship:

• Anchor the registration endpoint's trust configuration to a fixed list of trust domains. Provide the expected value through SPIFFEValidationOptions.TrustDomain and ensure the JWT's iss and sub claims share the same domain.
• Resolve the issuer's signing key through SPIFFE's control plane or a pinned JWKS reference before you call ValidateSPIFFE. The registration endpoint should only accept keys that chain back to the configured trust domain.
• Treat the registration endpoint URL as an OAuth resource server identifier and require it in the aud claim (SPIFFEValidationOptions.Audience). Section 5.1 mandates that the Issuer targets the specific Client Registration Endpoint instance it is talking to.
• After signature and claim validation, inspect the returned Claims to apply policy: e.g., restrict metadata to specific redirect URIs, enforce software identifiers, or map SPIFFE IDs to pre-approved client templates.

Verifiable Credential software statements

Section 5.2 pivots the trust relationship to a VC-JWT Issuer. The authorization server (or its Client Registration Endpoint) needs to pre-establish out-of-band trust in that Issuer. ValidateVerifiableCredential makes those checks explicit:

• Capture the Issuer identifier you negotiated with in VCValidationOptions.TrustedIssuer. ValidateVerifiableCredential rejects any VC signed by an unexpected Issuer so that only trusted credential issuers can influence client onboarding.
• Require the Client Registration Endpoint identifier in the VC audience via VCValidationOptions.Audience. This prevents credentials minted for one AS from being replayed elsewhere.
• If your deployment issues per-client subjects, populate VCValidationOptions.Subject to make sure the VC holder is the party you expect. Use Claims.UnmarshalVC to inspect the VC payload (credentialSubject, evidence, etc.) after the initial checks succeed.
• To honor the draft's guidance on revocation and lifecycle management, pass a StatusValidator. Common implementations dereference the credentialStatus entry, validate its signature, and ensure the status indicates the credential is active before proceeding with client registration.
• Finally, reuse the existing metadata validators (e.g., RequireMetadata) so that a trusted Issuer cannot skip mandatory OAuth client metadata and so that everything is stored exactly as the registration endpoint policy demands.

Documentation

For complete documentation, see the Go package documentation.