Skip to main content

​
What are attestations?

An attestation is a cryptographically signed proof that a verification occurred. It:
  • Uses ES256 (ECDSA P-256) signatures
  • Is formatted as a JWT
  • Can be verified independently
  • Can be stored on-chain

​
Requesting attestations

result = client.verify(
    "2+2=4",
    include_attestation=True
)

print(result.attestation)
# eyJhbGciOiJFUzI1NiIsInR5cCI6InF3ZWQtYXR0ZXN...

​
Fail-closed contract

Since PR #194 (Issue #188): create_verification_attestation() never returns None. It always returns an AttestationResult with status set to ISSUED, BLOCKED, or UNVERIFIABLE. You MUST check result.is_issued before you treat the attestation as valid. A missing or failed attestation must hard-block the verification path. Never downgrade it to VERIFIED.

​
AttestationResult

​
status
AttestationStatus
required
Lifecycle state of the attestation. One of ISSUED, BLOCKED, or UNVERIFIABLE.
​
token
string | None
Signed JWT string. Present only when status == ISSUED; None otherwise.
​
error_code
string | None
Machine-readable failure code: "SIGNING_FAILURE" when signing failed, "CRYPTO_UNAVAILABLE" when the cryptography / PyJWT package is not installed, None on success.
​
error
string | None
Human-readable failure detail. None on success.
​
is_issued
bool
Property. True only when status is AttestationStatus.ISSUED. You must check this flag before you use token.

​
AttestationStatus values

StatusMeaningtokenerror_code
ISSUEDQWED signed the attestation.JWT stringNone
BLOCKEDCrypto is available but signing failed (key error, JWT error). Hard block.NoneSIGNING_FAILURE
UNVERIFIABLEcryptography / PyJWT not installed. QWED did not attempt signing.NoneCRYPTO_UNAVAILABLE
VALID / EXPIRED / REVOKEDLifecycle states for previously issued attestations during verification.——

​
Caller pattern

from src.qwed_new.core.attestation import create_verification_attestation

result = create_verification_attestation(
    status="VERIFIED",
    verified=True,
    engine="math",
    query="2+2=4",
)

if not result.is_issued:
    # Fail-closed: do not proceed as VERIFIED without a proof artifact
    raise RuntimeError(f"Attestation unavailable [{result.error_code}]: {result.error}")

use(result.token)

​
Key lifecycle auditability

Every IssuerKeyPair records generated_at (epoch seconds) and key_continuity_policy. QWED emits a structured log entry (attestation.key_generated) on every new key generation, so you can audit continuity events.
​
key_continuity_policy
string
default:"ephemeral"
Policy for the issuer key pair. Must be one of "ephemeral" (in-memory, non-persistent — default) or "persistent" (durably stored, e.g. external KMS). Any other value raises ValueError.
AttestationService.get_issuer_info() now includes key_generated_at and key_continuity_policy alongside the existing issuer registry fields.

​
Attestation structure

{
  "alg": "ES256",
  "typ": "qwed-attestation+jwt",
  "kid": "did:qwed:node:production#signing-key-2024"
}

​
Payload

{
  "iss": "did:qwed:node:production",
  "sub": "sha256:abc123...",
  "iat": 1703073600,
  "exp": 1734609600,
  "jti": "att_xyz789",
  "qwed": {
    "version": "1.0",
    "result": {
      "status": "VERIFIED",
      "verified": true,
      "engine": "math",
      "confidence": 1.0
    },
    "query_hash": "sha256:def456...",
    "proof_hash": "sha256:ghi789..."
  }
}

​
Verifying attestations

​
Using the API

valid, claims, error = client.verify_attestation(jwt)
if valid:
    print(f"Verified by: {claims['iss']}")

​
Using the SDK

from qwed_sdk import verify_attestation

is_valid = verify_attestation(
    jwt="eyJhbGci...",
    trusted_issuers=["did:qwed:node:production"]
)

​
Trust anchors

QWED maintains a registry of trusted attestation issuers:
Issuer DIDNameStatus
did:qwed:node:productionQWED Production✅ Active
did:qwed:node:stagingQWED Staging✅ Active

​
Attestation chains

Link multiple attestations together: 
attestation1 = client.verify("step1", include_attestation=True)
attestation2 = client.verify(
    "step2",
    include_attestation=True,
    chain_id="chain_abc",
    chain_index=1,
    previous_attestation=attestation1.jti
)

​
Use cases

  1. Audit Trails - Prove AI outputs were verified
  2. Compliance - Regulatory verification records
  3. Blockchain - Anchor proofs on-chain
  4. Badges - Show verification status in UIs

​
Badge integration

Embed attestation badges: 
![Verified](https://api.qwedai.com/badge/attestation/att_xyz789)