Skip to main content

QWED-Attestation Specification v1.0

Status: Draft
Version: 1.0.0
Date: 2025-12-20
Extends: QWED-SPEC v1.0

Table of Contents​

  1. Introduction
  2. Attestation Model
  3. Attestation Format
  4. Cryptographic Operations
  5. Verification Chain
  6. Trust Anchors
  7. Transport & Storage
  8. Implementation Guidelines

1. Introduction​

1.1 Purpose​

QWED-Attestation defines a standard format for cryptographic proofs of verification. An attestation is a signed statement that a specific verification was performed by a trusted verifier at a specific time.

1.2 Use Cases​

Use CaseDescription
Audit TrailProve that verification occurred for compliance
Trust TransferThird party can verify without re-running
Offline VerificationValidate attestation without network
Chain of CustodyTrack verification through system handoffs
Non-RepudiationVerifier cannot deny issuing attestation

1.3 Terminology​

TermDefinition
AttestationSigned proof of verification result
IssuerQWED verifier that creates the attestation
SubjectThe content that was verified
HolderEntity that possesses the attestation
VerifierParty validating the attestation
ClaimStatement within the attestation

2. Attestation Model​

2.1 Conceptual Model​

┌─────────────────────────────────────────────────────────────┐
│                     QWED ATTESTATION                        │
├─────────────────────────────────────────────────────────────┤
│  Header                                                     │
│  ├── Algorithm: ES256                                       │
│  ├── Type: qwed-attestation+jwt                            │
│  └── Key ID: did:qwed:issuer123                            │
├─────────────────────────────────────────────────────────────┤
│  Payload (Claims)                                           │
│  ├── Issuer: qwed-node-xyz                                 │
│  ├── Subject: sha256(original_query)                       │
│  ├── Issued At: 2025-12-20T00:30:00Z                       │
│  ├── Expiration: 2026-12-20T00:30:00Z                      │
│  ├── Verification Result: VERIFIED                          │
│  ├── Engine: math                                           │
│  ├── Confidence: 1.0                                        │
│  └── Proof Hash: sha256(proof_data)                        │
├─────────────────────────────────────────────────────────────┤
│  Signature                                                  │
│  └── ECDSA-P256(header + payload, issuer_private_key)      │
└─────────────────────────────────────────────────────────────┘

2.2 Trust Flow​

1. Client submits verification request
2. QWED Verifier performs verification
3. Verifier creates attestation with result
4. Verifier signs attestation with private key
5. Attestation returned to client
6. Client can share attestation with third parties
7. Third parties verify signature against issuer's public key

2.3 Attestation Lifecycle​

StateDescription
issuedAttestation created and signed
validWithin validity period, signature valid
expiredPast expiration time
revokedExplicitly invalidated by issuer

3. Attestation Format​

3.1 Structure (JWT)​

QWED Attestations use JSON Web Token (JWT) format per RFC 7519.

<header>.<payload>.<signature>

3.2 Header Schema​

{
  "alg": "ES256",
  "typ": "qwed-attestation+jwt",
  "kid": "did:qwed:node:abc123#key-1"
}
FieldRequiredDescription
algREQUIREDSignature algorithm (ES256, EdDSA)
typREQUIREDToken type (MUST be qwed-attestation+jwt)
kidREQUIREDKey identifier (DID-based)

3.3 Payload Schema​

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://qwed.ai/schemas/attestation/v1",
  "type": "object",
  "required": ["iss", "sub", "iat", "qwed"],
  "properties": {
    "iss": {
      "type": "string",
      "description": "Issuer identifier (DID or URL)"
    },
    "sub": {
      "type": "string",
      "description": "Subject hash (SHA-256 of verified content)"
    },
    "iat": {
      "type": "integer",
      "description": "Issued at (Unix timestamp)"
    },
    "exp": {
      "type": "integer",
      "description": "Expiration (Unix timestamp)"
    },
    "nbf": {
      "type": "integer",
      "description": "Not before (Unix timestamp)"
    },
    "jti": {
      "type": "string",
      "description": "Unique attestation ID"
    },
    "qwed": {
      "type": "object",
      "description": "QWED-specific claims",
      "required": ["version", "result"],
      "properties": {
        "version": {
          "type": "string",
          "const": "1.0"
        },
        "result": {
          "type": "object",
          "required": ["status", "verified"],
          "properties": {
            "status": {
              "type": "string",
              "enum": ["VERIFIED", "FAILED", "CORRECTED", "BLOCKED"]
            },
            "verified": {
              "type": "boolean"
            },
            "engine": {
              "type": "string"
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          }
        },
        "query_hash": {
          "type": "string",
          "description": "SHA-256 of original query"
        },
        "proof_hash": {
          "type": "string",
          "description": "SHA-256 of proof data"
        },
        "chain_id": {
          "type": "string",
          "description": "Verification chain ID for linked attestations"
        }
      }
    }
  }
}

3.4 Example Attestation (Decoded)​

Header:

{
  "alg": "ES256",
  "typ": "qwed-attestation+jwt",
  "kid": "did:qwed:node:mainnet-001#signing-key-2025"
}

Payload:

{
  "iss": "did:qwed:node:mainnet-001",
  "sub": "sha256:a1b2c3d4e5f6...",
  "iat": 1734653400,
  "exp": 1766189400,
  "jti": "att_7f8e9d0c1b2a",
  "qwed": {
    "version": "1.0",
    "result": {
      "status": "VERIFIED",
      "verified": true,
      "engine": "math",
      "confidence": 1.0
    },
    "query_hash": "sha256:9f8e7d6c5b4a...",
    "proof_hash": "sha256:1a2b3c4d5e6f..."
  }
}

Encoded JWT:

eyJhbGciOiJFUzI1NiIsInR5cCI6InF3ZWQtYXR0ZXN0YXRpb24rand0Iiwia2lk
IjoiZGlkOnF3ZWQ6bm9kZTptYWlubmV0LTAwMSNzaWduaW5nLWtleS0yMDI1In0.
eyJpc3MiOiJkaWQ6cXdlZDpub2RlOm1haW5uZXQtMDAxIiwic3ViIjoic2hhMjU2
OmExYjJjM2Q0ZTVmNi4uLiIsImlhdCI6MTczNDY1MzQwMCwiZXhwIjoxNzY2MTg5
NDAwLCJqdGkiOiJhdHRfN2Y4ZTlkMGMxYjJhIiwicXdlZCI6eyJ2ZXJzaW9uIjoi
MS4wIiwicmVzdWx0Ijp7InN0YXR1cyI6IlZFUklGSUVEIiwidmVyaWZpZWQiOnRy
dWUsImVuZ2luZSI6Im1hdGgiLCJjb25maWRlbmNlIjoxLjB9fX0.
MEUCIQDKZnw...signature...

4. Cryptographic Operations​

4.1 Algorithms​

AlgorithmUsageRequirement
ES256Attestation signingREQUIRED
EdDSAAttestation signingRECOMMENDED
SHA-256Content hashingREQUIRED
SHA-384Content hashingOPTIONAL

4.2 Key Types​

Issuer Keys:

{
  "kty": "EC",
  "crv": "P-256",
  "x": "base64url...",
  "y": "base64url...",
  "kid": "did:qwed:node:xyz#key-1"
}

4.3 Signing Process​

# Pseudocode
def create_attestation(verification_result, issuer_key):
    header = {
        "alg": "ES256",
        "typ": "qwed-attestation+jwt",
        "kid": issuer_key.kid
    }
    
    payload = {
        "iss": issuer_key.issuer_did,
        "sub": sha256(verification_result.query),
        "iat": current_timestamp(),
        "exp": current_timestamp() + VALIDITY_PERIOD,
        "jti": generate_uuid(),
        "qwed": {
            "version": "1.0",
            "result": {
                "status": verification_result.status,
                "verified": verification_result.verified,
                "engine": verification_result.engine,
                "confidence": verification_result.confidence
            },
            "query_hash": sha256(verification_result.query),
            "proof_hash": sha256(verification_result.proof)
        }
    }
    
    signature = ecdsa_sign(
        base64url(header) + "." + base64url(payload),
        issuer_key.private_key
    )
    
    return base64url(header) + "." + base64url(payload) + "." + base64url(signature)

4.4 Verification Process​

def verify_attestation(attestation_jwt, trusted_issuers):
    # 1. Parse JWT
    header, payload, signature = parse_jwt(attestation_jwt)
    
    # 2. Validate header
    assert header["typ"] == "qwed-attestation+jwt"
    assert header["alg"] in ["ES256", "EdDSA"]
    
    # 3. Get issuer public key
    issuer_did = payload["iss"]
    if issuer_did not in trusted_issuers:
        raise UntrustedIssuerError()
    
    public_key = resolve_did_key(issuer_did, header["kid"])
    
    # 4. Verify signature
    if not ecdsa_verify(header + "." + payload, signature, public_key):
        raise InvalidSignatureError()
    
    # 5. Check validity period
    now = current_timestamp()
    if payload.get("nbf") and now < payload["nbf"]:
        raise NotYetValidError()
    if payload.get("exp") and now > payload["exp"]:
        raise ExpiredError()
    
    # 6. Check revocation (optional)
    if is_revoked(payload["jti"]):
        raise RevokedError()
    
    return payload["qwed"]["result"]

5. Verification Chain​

5.1 Chained Attestations​

For complex verifications, multiple attestations can be chained:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Attestation 1  │────▶│  Attestation 2  │────▶│  Attestation 3  │
│  (Translation)  │     │  (Verification) │     │  (Consensus)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

5.2 Chain Reference​

{
  "qwed": {
    "chain_id": "chain_abc123",
    "chain_index": 2,
    "previous_attestation": "att_xyz789",
    "previous_hash": "sha256:..."
  }
}

5.3 Multi-Engine Attestation​

When multiple engines verify the same query:

{
  "qwed": {
    "result": {
      "status": "VERIFIED",
      "verified": true,
      "consensus": {
        "mode": "unanimous",
        "engines": ["math", "logic"],
        "agreement": 1.0
      }
    }
  }
}

6. Trust Anchors​

6.1 Issuer Registry​

QWED maintains a registry of trusted issuers:

https://qwed.ai/registry/issuers.json
{
  "issuers": [
    {
      "did": "did:qwed:node:mainnet-001",
      "name": "QWED Mainnet Node 1",
      "public_keys": [
        {
          "kid": "did:qwed:node:mainnet-001#key-2025",
          "kty": "EC",
          "crv": "P-256",
          "x": "...",
          "y": "..."
        }
      ],
      "status": "active",
      "certification_level": "full"
    }
  ]
}

6.2 Decentralized Identifiers (DIDs)​

QWED uses DIDs for issuer identification:

did:qwed:node:<node-id>
did:qwed:provider:<provider-id>
did:qwed:user:<user-id>

6.3 Key Rotation​

Issuers SHOULD rotate keys annually. Old keys remain valid for attestation verification until their designated expiry.

7. Transport & Storage​

7.1 HTTP Header​

Attestations can be returned in HTTP headers:

HTTP/1.1 200 OK
Content-Type: application/json
QWED-Attestation: eyJhbGciOiJFUzI1NiIsInR5cCI6...

7.2 Response Body​

Attestations can be included in the response:

{
  "status": "VERIFIED",
  "verified": true,
  "attestation": "eyJhbGciOiJFUzI1NiIsInR5cCI6..."
}

7.3 Standalone Document​

Attestations can be stored as standalone files:

verification_result.qwed-attestation

7.4 Blockchain Anchoring (Optional)​

Attestation hashes can be anchored to public blockchains:

{
  "qwed": {
    "anchor": {
      "chain": "ethereum",
      "tx_hash": "0x...",
      "block_number": 12345678
    }
  }
}

8. Implementation Guidelines​

8.1 Request Attestation​

Request attestation in verification request:

{
  "query": "2+2=4",
  "type": "math",
  "options": {
    "include_attestation": true,
    "attestation_validity_days": 365
  }
}

8.2 SDK Example (Python)​

from qwed_sdk import QWEDClient
from qwed_sdk.attestation import verify_attestation

client = QWEDClient(api_key="qwed_...")

# Request with attestation
result = client.verify(
    "What is 2+2?",
    options={"include_attestation": True}
)

# Get attestation
attestation = result.attestation
print(f"Attestation ID: {attestation.jti}")

# Share with third party
attestation_jwt = attestation.to_jwt()

# Third party verifies
is_valid, claims = verify_attestation(
    attestation_jwt,
    trusted_issuers=["did:qwed:node:mainnet-001"]
)

if is_valid:
    print(f"Verified by {claims['iss']} at {claims['iat']}")

8.3 Storage Recommendations​

Use CaseRecommended Storage
Short-term auditIn-memory / Redis
Long-term complianceDatabase with indexing
Immutable recordBlockchain anchor
Offline verificationFile system

8.4 Security Recommendations​

  1. Protect Private Keys - Use HSM or secure key management
  2. Validate Issuers - Only trust registered issuers
  3. Check Expiration - Reject expired attestations
  4. Verify Chains - Validate all attestations in a chain
  5. Monitor Revocations - Check revocation status

Appendix A: Error Codes​

CodeDescription
ATT-001Invalid attestation format
ATT-002Untrusted issuer
ATT-003Invalid signature
ATT-004Attestation expired
ATT-005Attestation not yet valid
ATT-006Attestation revoked
ATT-007Missing required claim
ATT-008Chain validation failed

Appendix B: MIME Types​

TypeUsage
application/qwed-attestation+jwtAttestation JWT
application/qwed-attestation+jsonDecoded attestation

Appendix C: DID Method​

The did:qwed method specification will be published separately.

© 2025 QWED-AI. This specification is released under Apache 2.0 License.