isomer-go: refactor to cleaner workflow and add documentation

Codex authored this with prompting and review by Kent Bull

Author: kentbull

apps/isomer-go/README.md

@@ -4,6 +4,12 @@ Minimal Go verifier sidecar for external W3C acceptance.
 
 This app verifies the same VC-JWT and VP-JWT artifacts as `apps/isomer-node`,
 but uses the local sibling `../vc-go` clone as the independent Go W3C stack.
+The Go sidecar depends on:
+
+- `vc-go` for VC/VP parsing and Data Integrity verification
+- `did-go` for DID document parsing
+- the HTTP `did-webs-resolver` service for latest-key DID resolution
+
 The module uses:
 
 ```go
@@ -38,6 +44,6 @@ ACDC/W3C equivalence remain Python Isomer verifier responsibilities.
 
 VP-JWT verification is intentionally split: the sidecar validates the VP JOSE
 signature and JWT claims directly, parses the VP with `vc-go/verifiable`, and
-then verifies each nested VC-JWT through the same VC path. VP JSON-LD checks are
-disabled in this pass because the current local `vc-go` stack is not the source
-of truth for Isomer's VP Data Integrity model.
+then verifies each nested VC-JWT through the same VC path. VP JSON-LD checks
+remain disabled in this pass because the current local `vc-go` stack is not yet
+the source of truth for Isomer's VP Data Integrity model.

apps/isomer-go/cmd/isomer-go/main.go

@@ -1,8 +1,12 @@
+// Package main is the process entrypoint for the isomer-go sidecar.
+//
+// The real CLI contract lives in the internal sidecar serve runner. This file
+// stays intentionally small so process startup and signal handling remain easy
+// to audit.
 package main
 
 import (
 	"context"
-	"flag"
 	"log"
 	"os"
 	"os/signal"
@@ -12,29 +16,10 @@ import (
 )
 
 func main() {
-	host := flag.String("host", "127.0.0.1", "HTTP host")
-	port := flag.Int("port", 8788, "HTTP port")
-	resolverURL := flag.String("resolver-url", "", "did:webs resolver base URL")
-	resourceRoot := flag.String("resource-root", ".", "w3c-crosswalk repository root")
-	flag.Parse()
-
-	if *resolverURL == "" {
-		log.Fatal("--resolver-url is required")
-	}
-
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 
-	server, err := sidecar.NewServer(sidecar.Config{
-		Host:         *host,
-		Port:         *port,
-		ResolverURL:  *resolverURL,
-		ResourceRoot: *resourceRoot,
-	})
-	if err != nil {
-		log.Fatal(err)
-	}
-	if err = server.Run(ctx); err != nil {
+	if err := sidecar.RunServe(ctx, os.Args[1:]); err != nil {
 		log.Fatal(err)
 	}
 }

apps/isomer-go/internal/sidecar/claims.go

@@ -0,0 +1,91 @@
+package sidecar
+
+import "errors"
+
+// validateVCClaims enforces the local VC-JWT claim relationships the sidecar
+// expects before deeper cryptographic checks run.
+func validateVCClaims(jwtPayload, vc map[string]any) error {
+	if err := requireOptionalClaimMatch(
+		asString(jwtPayload["iss"]),
+		asString(vc["issuer"]),
+		"JWT iss does not match vc.issuer",
+	); err != nil {
+		return err
+	}
+	if err := requireOptionalClaimMatch(
+		asString(jwtPayload["jti"]),
+		asString(vc["id"]),
+		"JWT jti does not match vc.id",
+	); err != nil {
+		return err
+	}
+
+	if subject := asMap(vc["credentialSubject"]); subject != nil {
+		if err := requireOptionalClaimMatch(
+			asString(jwtPayload["sub"]),
+			asString(subject["id"]),
+			"JWT sub does not match credentialSubject.id",
+		); err != nil {
+			return err
+		}
+	}
+
+	if err := requireNumericClaim(jwtPayload, "iat", "VC-JWT requires numeric iat"); err != nil {
+		return err
+	}
+	if err := requireNumericClaim(jwtPayload, "nbf", "VC-JWT requires numeric nbf"); err != nil {
+		return err
+	}
+	return nil
+}
+
+// validateVPClaims enforces the local VP-JWT claim relationships the sidecar
+// expects before nested verification begins.
+func validateVPClaims(jwtPayload, vp map[string]any, audience, nonce string) error {
+	if err := requireOptionalClaimMatch(
+		asString(jwtPayload["iss"]),
+		asString(vp["holder"]),
+		"JWT iss does not match vp.holder",
+	); err != nil {
+		return err
+	}
+	if err := requireOptionalClaimMatch(
+		asString(jwtPayload["aud"]),
+		audience,
+		"JWT aud does not match expected audience",
+	); err != nil {
+		return err
+	}
+	if err := requireOptionalClaimMatch(
+		asString(jwtPayload["nonce"]),
+		nonce,
+		"JWT nonce does not match expected nonce",
+	); err != nil {
+		return err
+	}
+	return requireNumericClaim(jwtPayload, "iat", "VP-JWT requires numeric iat")
+}
+
+// requireOptionalClaimMatch fails only when the expected value is present and
+// the actual value does not match it.
+func requireOptionalClaimMatch(actual, expected, message string) error {
+	if claimMatchesExpected(actual, expected) {
+		return nil
+	}
+	return errors.New(message)
+}
+
+// claimMatchesExpected implements the sidecar's "empty expected means optional"
+// matching rule for JWT claim checks.
+func claimMatchesExpected(actual, expected string) bool {
+	return expected == "" || actual == expected
+}
+
+// requireNumericClaim enforces that one decoded JWT payload claim was parsed as
+// a JSON number.
+func requireNumericClaim(payload map[string]any, claim, message string) error {
+	if _, ok := payload[claim].(float64); ok {
+		return nil
+	}
+	return errors.New(message)
+}

apps/isomer-go/internal/sidecar/context_loader.go

@@ -5,19 +5,27 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sync"
 
 	"github.com/piprate/json-gold/ld"
 )
 
+// localDocumentLoader pins the small set of JSON-LD contexts used by Isomer's
+// VC projection so verification never depends on remote context fetches.
 type localDocumentLoader struct {
 	root  string
+	mu    sync.RWMutex
 	cache map[string]any
 }
 
+// newLocalDocumentLoader builds one pinned local JSON-LD loader rooted at the
+// Python Isomer resource tree.
 func newLocalDocumentLoader(root string) *localDocumentLoader {
 	return &localDocumentLoader{root: root, cache: map[string]any{}}
 }
 
+// LoadDocument returns one pinned JSON-LD context from disk and caches it for
+// later reuse.
 func (l *localDocumentLoader) LoadDocument(url string) (*ld.RemoteDocument, error) {
 	filename, ok := map[string]string{
 		"https://www.w3.org/2018/credentials/v1":          "vc-v1.jsonld",
@@ -27,20 +35,33 @@ func (l *localDocumentLoader) LoadDocument(url string) (*ld.RemoteDocument, erro
 	if !ok {
 		return nil, fmt.Errorf("no local JSON-LD context registered for %s", url)
 	}
-	if _, ok = l.cache[url]; !ok {
+
+	l.mu.RLock()
+	document, ok := l.cache[url]
+	l.mu.RUnlock()
+	if !ok {
 		path := filepath.Join(l.root, "src", "vc_isomer", "resources", "contexts", filename)
 		body, err := os.ReadFile(path)
 		if err != nil {
 			return nil, err
 		}
-		var document any
-		if err = json.Unmarshal(body, &document); err != nil {
+
+		var loaded any
+		if err = json.Unmarshal(body, &loaded); err != nil {
 			return nil, err
 		}
-		l.cache[url] = document
+
+		l.mu.Lock()
+		if cached, exists := l.cache[url]; exists {
+			document = cached
+		} else {
+			l.cache[url] = loaded
+			document = loaded
+		}
+		l.mu.Unlock()
 	}
 	return &ld.RemoteDocument{
 		DocumentURL: url,
-		Document:    l.cache[url],
+		Document:    document,
 	}, nil
 }

apps/isomer-go/internal/sidecar/context_loader_test.go

@@ -0,0 +1,40 @@
+// Contract tests for the pinned local JSON-LD context loader.
+package sidecar
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+func TestLocalDocumentLoaderConcurrentAccess(t *testing.T) {
+	root := t.TempDir()
+	contextPath := filepath.Join(root, "src", "vc_isomer", "resources", "contexts")
+	if err := os.MkdirAll(contextPath, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(contextPath, "vc-v1.jsonld"), []byte(`{"@context":"vc"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	loader := newLocalDocumentLoader(root)
+	var waitGroup sync.WaitGroup
+
+	for index := 0; index < 16; index++ {
+		waitGroup.Add(1)
+		go func() {
+			defer waitGroup.Done()
+			document, err := loader.LoadDocument("https://www.w3.org/2018/credentials/v1")
+			if err != nil {
+				t.Error(err)
+				return
+			}
+			if document.DocumentURL != "https://www.w3.org/2018/credentials/v1" {
+				t.Errorf("unexpected document %#v", document)
+			}
+		}()
+	}
+
+	waitGroup.Wait()
+}

apps/isomer-go/internal/sidecar/doc.go

@@ -0,0 +1,11 @@
+// Package sidecar implements the Go external verifier used by Isomer's W3C
+// acceptance tests.
+//
+// The package owns only the narrow W3C-facing verification pipeline:
+// decoding VC-JWTs and VP-JWTs, checking local claim relationships, resolving
+// current did:webs key state through the HTTP resolver service, verifying
+// embedded Data Integrity proofs, consulting projected credential status, and
+// recursively checking nested VC-JWTs inside VP-JWTs.
+//
+// It does not attempt Python Isomer's TEL-aware ACDC/W3C pair verification.
+package sidecar

apps/isomer-go/internal/sidecar/jwt.go

@@ -9,13 +9,16 @@ import (
 	"strings"
 )
 
+// jwtParts stores the structurally decoded pieces of one compact JWT.
 type jwtParts struct {
 	Header       map[string]any
 	Payload      map[string]any
 	SigningInput []byte
 	Signature    []byte
 }
 
+// decodeJWT parses one compact JWT into its decoded header, payload, signing
+// input, and detached signature bytes.
 func decodeJWT(token string) (*jwtParts, error) {
 	parts := strings.Split(token, ".")
 	if len(parts) != 3 {
@@ -52,14 +55,16 @@ func decodeJWT(token string) (*jwtParts, error) {
 	}, nil
 }
 
+// verifyJWTSignature checks an EdDSA compact JWT signature against one resolved
+// Ed25519 JWK.
 func verifyJWTSignature(parts *jwtParts, jwk map[string]any) error {
 	if parts.Header["alg"] != "EdDSA" {
 		return fmt.Errorf("unsupported alg: %v", parts.Header["alg"])
 	}
-	x, ok := jwk["x"].(string)
-	if !ok || x == "" {
+	if !isEd25519JWK(jwk) {
 		return errors.New("Ed25519 JWK is missing x")
 	}
+	x := jwk["x"].(string)
 	key, err := base64.RawURLEncoding.DecodeString(x)
 	if err != nil {
 		return fmt.Errorf("decode Ed25519 JWK x: %w", err)
@@ -70,16 +75,25 @@ func verifyJWTSignature(parts *jwtParts, jwk map[string]any) error {
 	return nil
 }
 
+// asMap narrows one generic decoded JSON value to a plain object.
 func asMap(value any) map[string]any {
 	if typed, ok := value.(map[string]any); ok {
 		return typed
 	}
 	return nil
 }
 
+// asString returns the string form of a decoded JSON value when available.
 func asString(value any) string {
 	if typed, ok := value.(string); ok {
 		return typed
 	}
 	return ""
 }
+
+// isEd25519JWK checks whether the sidecar has enough JWK material to perform
+// local Ed25519 signature verification.
+func isEd25519JWK(jwk map[string]any) bool {
+	x := asString(jwk["x"])
+	return x != ""
+}

apps/isomer-go/internal/sidecar/proof.go

@@ -0,0 +1,21 @@
+package sidecar
+
+import "github.com/trustbloc/vc-go/dataintegrity/models"
+
+// ProofOptions aliases the trustbloc proof options type so internal seams can
+// depend on a small local name.
+type ProofOptions = models.ProofOptions
+
+// wrapProofVerifier adapts the concrete trustbloc verifier to the local proof
+// interface used by the verifier runtime.
+type wrapProofVerifier struct {
+	Verifier interface {
+		VerifyProof(doc []byte, opts *models.ProofOptions) error
+	}
+}
+
+// VerifyProof forwards one proof verification request to the wrapped trustbloc
+// verifier.
+func (w wrapProofVerifier) VerifyProof(doc []byte, opts *ProofOptions) error {
+	return w.Verifier.VerifyProof(doc, opts)
+}