feat(signing): support top-level job_workflow_ref claim as fallback

Add support for extracting job_workflow_ref from top-level JWT claim
when not found embedded in the sub claim. This provides flexibility
for different OIDC token formats while maintaining compatibility with
Fulcio's certificate identity generation.

- Try extracting job_workflow_ref from sub claim first (primary path)
- Fall back to top-level job_workflow_ref claim if not in sub
- Add test case for top-level claim scenario
- Update documentation to clarify both extraction paths

Co-authored-by: Ona <no-reply@ona.com>

Author: leodido

pkg/leeway/signing/attestation.go

@@ -378,23 +378,26 @@ func validateSigstoreEnvironment() error {
 	return nil
 }
 
-// extractBuilderIDFromOIDC extracts the builder ID from the GitHub OIDC token's sub claim.
+// extractBuilderIDFromOIDC extracts the builder ID from the GitHub OIDC token.
 // This ensures the builder ID matches the certificate identity issued by Fulcio, which is
 // critical for slsa-verifier compatibility, especially with reusable workflows.
 //
 // For reusable workflows, the OIDC token contains:
-// - sub claim: Contains job_workflow_ref pointing to the actual executing workflow (e.g., _build.yml)
-// - workflow_ref: Points to the calling workflow (e.g., build-main.yml)
+// - job_workflow_ref claim: Points to the actual executing workflow (e.g., _build.yml)
+// - sub claim: May contain job_workflow_ref embedded in colon-separated format
+// - workflow_ref env var: Points to the calling workflow (e.g., build-main.yml)
 //
-// Fulcio uses the sub claim for the certificate identity, so we must use it for the builder ID.
+// Fulcio uses the sub claim for the certificate identity. For reusable workflows,
+// the sub claim includes job_workflow_ref in the format:
+// repo:OWNER/REPO:ref:REF:job_workflow_ref:OWNER/REPO/.github/workflows/WORKFLOW@REF
 func extractBuilderIDFromOIDC(ctx context.Context, githubCtx *GitHubContext) (string, error) {
 	// Fetch the OIDC token with sigstore audience
 	idToken, err := fetchGitHubOIDCToken(ctx, "sigstore")
 	if err != nil {
 		return "", fmt.Errorf("failed to fetch OIDC token: %w", err)
 	}
 
-	// Parse the JWT token to extract the sub claim
+	// Parse the JWT token to extract claims
 	// JWT format: header.payload.signature
 	parts := strings.Split(idToken, ".")
 	if len(parts) != 3 {
@@ -413,17 +416,27 @@ func extractBuilderIDFromOIDC(ctx context.Context, githubCtx *GitHubContext) (st
 		return "", fmt.Errorf("failed to parse JWT claims: %w", err)
 	}
 
-	// Extract the sub claim
+	// Extract the sub claim (required for Fulcio certificate identity)
 	sub, ok := claims["sub"].(string)
 	if !ok || sub == "" {
 		return "", fmt.Errorf("sub claim not found or empty in OIDC token")
 	}
 
-	// Extract job_workflow_ref from the sub claim
-	// Format: repo:OWNER/REPO:ref:REF:job_workflow_ref:OWNER/REPO/.github/workflows/WORKFLOW@REF
+	// Try to extract job_workflow_ref from the sub claim first
+	// This is the format that Fulcio embeds in the certificate
 	jobWorkflowRef := extractJobWorkflowRef(sub)
+	
+	// If not found in sub, try the top-level job_workflow_ref claim
+	// (GitHub provides both, but Fulcio uses the one from sub)
+	if jobWorkflowRef == "" {
+		if jwfRef, ok := claims["job_workflow_ref"].(string); ok && jwfRef != "" {
+			jobWorkflowRef = jwfRef
+			log.WithField("job_workflow_ref", jobWorkflowRef).Debug("Using top-level job_workflow_ref claim (not found in sub)")
+		}
+	}
+	
 	if jobWorkflowRef == "" {
-		return "", fmt.Errorf("job_workflow_ref not found in sub claim: %s", sub)
+		return "", fmt.Errorf("job_workflow_ref not found in sub claim or top-level claims: %s", sub)
 	}
 
 	// Construct the builder ID URL

pkg/leeway/signing/attestation_test.go

@@ -1410,7 +1410,33 @@ func TestExtractBuilderIDFromOIDC(t *testing.T) {
 			errorMsg:    "sub claim not found",
 		},
 		{
-			name: "missing job_workflow_ref in sub claim",
+			name: "job_workflow_ref in top-level claim (not in sub)",
+			setupServer: func() *httptest.Server {
+				return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					header := base64EncodeForTest(`{"alg":"RS256","typ":"JWT"}`)
+					payload := base64EncodeForTest(`{
+						"sub": "repo:org/repo:environment:prod",
+						"aud": "sigstore",
+						"job_workflow_ref": "org/repo/.github/workflows/deploy.yml@refs/heads/main"
+					}`)
+					signature := base64EncodeForTest("fake-signature")
+					token := fmt.Sprintf("%s.%s.%s", header, payload, signature)
+					
+					w.Header().Set("Content-Type", "application/json")
+					if err := json.NewEncoder(w).Encode(map[string]string{"value": token}); err != nil {
+						t.Errorf("Failed to encode response: %v", err)
+					}
+				}))
+			},
+			githubCtx: &GitHubContext{
+				ServerURL:  "https://github.com",
+				Repository: "org/repo",
+			},
+			expectError: false,
+			expectedID:  "https://github.com/org/repo/.github/workflows/deploy.yml@refs/heads/main",
+		},
+		{
+			name: "missing job_workflow_ref in sub claim and top-level",
 			setupServer: func() *httptest.Server {
 				return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 					header := base64EncodeForTest(`{"alg":"RS256","typ":"JWT"}`)
@@ -1422,7 +1448,9 @@ func TestExtractBuilderIDFromOIDC(t *testing.T) {
 					token := fmt.Sprintf("%s.%s.%s", header, payload, signature)
 
 					w.Header().Set("Content-Type", "application/json")
-					json.NewEncoder(w).Encode(map[string]string{"value": token})
+					if err := json.NewEncoder(w).Encode(map[string]string{"value": token}); err != nil {
+						t.Errorf("Failed to encode response: %v", err)
+					}
 				}))
 			},
 			githubCtx: &GitHubContext{