JWT-VC Integration

Overview

Corsair encodes CPOEs as W3C Verifiable Credentials in JWT format (vc+jwt). This enables interoperability with any standards-compliant VC verifier while maintaining Corsair's Ed25519 signing and evidence chain integrity.

DID Setup

Organizations identify themselves using did:web — a DID method that resolves to a JSON document hosted at the organization's domain.

Generate a DID Document

Generate keys, then create a DID document from your public key:

# Generate keypair
corsair keygen --output ./keys

# Generate DID document + JWKS
corsair did generate --domain example.com --output did.json
corsair did jwks --domain example.com --output jwks.json

Publish the DID Document

Host the DID document at your domain's well-known path:

https://example.com/.well-known/did.json

Publish the JWKS alongside it:

https://example.com/.well-known/jwks.json

The document contains your Ed25519 public key (JWK):

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:example.com",
  "verificationMethod": [{
    "id": "did:web:example.com#key-1",
    "type": "JsonWebKey2020",
    "controller": "did:web:example.com",
    "publicKeyJwk": {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "..."
    }
  }],
  "assertionMethod": ["did:web:example.com#key-1"]
}

Issuing CPOEs as Verifiable Credentials

Via CLI

# Sign tool output and output as JWT-VC
corsair sign \
  --file tool-output.json \
  --mapping ./mappings/toolx.json \
  --did did:web:example.com

# Output: JWT string written to evidence directory
# eyJhbGciOiJFZERTQSIsInR5cCI6InZjK2p3dCIs...

JWT Structure

The generated JWT contains three parts:

Header:

{
  "alg": "EdDSA",
  "typ": "vc+jwt",
  "kid": "did:web:example.com#key-1"
}

Payload:

{
  "iss": "did:web:example.com",
  "sub": "marque-uuid",
  "exp": 1708041600,
  "iat": 1707436800,
  "jti": "marque-uuid",
  "vc": {
    "@context": [
      "https://www.w3.org/ns/credentials/v2",
      "https://grcorsair.com/credentials/v1"
    ],
    "type": ["VerifiableCredential", "CorsairCPOE"],
    "issuer": {
      "id": "did:web:example.com",
      "name": "Security Engineering"
    },
    "validFrom": "2026-02-07T00:00:00Z",
    "validUntil": "2026-02-14T00:00:00Z",
    "credentialSubject": {
      "type": "CorsairCPOE",
      "schemaVersion": "1.0",
      "scope": "SOC 2 Type II — Cloud Infrastructure Controls",
      "provenance": {
        "source": "tool",
        "sourceIdentity": "Scanner v1.2",
        "sourceDate": "2026-01-15"
      },
      "summary": {
        "controlsTested": 24,
        "controlsPassed": 22,
        "controlsFailed": 2,
        "overallScore": 92
      },
      "extensions": {
        "mapping": { "id": "toolx-evidence-only", "evidenceOnly": true },
        "passthrough": { "summary": { "passed": 12, "failed": 2 } }
      },
      "dependencies": [
        {
          "issuer": "did:web:vendor.com",
          "scope": "SOC 2 Type II — Infrastructure",
          "cpoe": "https://vendor.com/cpoe.jwt",
          "digest": "sha256:4b2c...d91"
        }
      ]
    }
  },
  "parley": "2.0"
}

Signature: Ed25519 signature over base64url(header).base64url(payload)

Extensions namespace: extensions keys must be mapping, passthrough, or namespaced with x- / ext.. Dependencies: Optional dependencies[] link upstream CPOEs for trust graph verification (corsair verify --dependencies).

Verifying CPOEs

Web Verifier

Visit grcorsair.com/marque and paste the JWT string. The verifier auto-detects the format and verifies the Ed25519 signature entirely client-side using the Web Crypto API.

CLI Verification

# Verify a JWT-VC Marque
bun bin/corsair-verify.ts ./evidence/marque.jwt --public-key ./keys/corsair-signing.pub

# Output:
# Format: JWT-VC
# Signature: VALID
# Issuer: did:web:example.com
# Expires: 2026-02-14T00:00:00Z
# Score: 75/100 (18/24 controls passed)

Programmatic Verification

Any W3C VC verifier can validate a Corsair JWT-VC. The credential uses standard claims and Ed25519 signing:

// Using any JWT library with EdDSA support
import { jwtVerify } from "jose";

const { payload } = await jwtVerify(jwt, publicKey, {
  algorithms: ["EdDSA"],
});

const vc = payload.vc;
console.log(vc.credentialSubject.summary.overallScore);

Cross-Platform Verification

Because Corsair uses open standards, CPOEs can be verified by:

• Corsair CLI — bun bin/corsair-verify.ts
• Web browser — grcorsair.com/marque (Web Crypto API)
• Any JWT library — jose, jsonwebtoken, etc. with EdDSA support
• W3C VC verifiers — Any spec-compliant implementation
• Custom tooling — Base64url decode + Ed25519 verify

The verification surface is not locked to Corsair infrastructure. This is the key difference from proprietary attestation formats.