Authority freshness: treat a change in authority state as an input to trust freshness

[rampyg]

Description

Makes a change in authority state a first-class input to trust freshness, alongside elapsed time and the consequence of the action.

An authority publishes a signed AuthorityState credential carrying a monotonic authorityEpoch and a status. SessionVouchers and heartbeat requests record the epoch they were minted under, and for an action that calls for state freshness a verifier refuses a voucher minted under an older epoch, even when its time-decay trust still passes. A timestamp says when a voucher was minted and never whether authority has changed since, so time alone forces a verifier to guess a safe staleness window. A new epoch is proof that a real transition occurred.

The epoch comparison is local and needs no network call at action time. The top consequence tier stops trusting cached state entirely and requires a live M-of-N co-sign read at the moment of the action, because a cached epoch cannot cover the gap between the last refresh and this action.

Type of Change

• New feature (non-breaking change that adds functionality)
• Documentation update

Related Issues

Closes #374

Changes Made

• AuthorityState build and verify in the Rust core, mirrored to Python, TypeScript, Go, and WebAssembly, signed with eddsa-jcs-2022.
• SessionVoucher and heartbeat requests carry authorityEpoch; the heartbeat validator tracks the highest epoch it has seen per authority.
• A consequence-to-policy map and the epoch-collapse rule in the verify path, with stable reason codes such as authority_epoch_stale:seen=7,voucher=5 that are byte-identical across languages.
• The top tier wires to the existing FROST co-sign, verified as a standard Ed25519 signature so verifiers need no threshold code.
• A shared interop vector at test-vectors/authority-state/, proving a proof built in one language verifies in the others, that a stale-epoch proof is rejected everywhere, and that all five implementations reach identical freshness verdicts.
• Distribution surfaces updated together: the FAQ, the help guides, the home and tools pages, the demos page, the knowledge base, the Claude skill, the custom GPT, the Gem, and the MCP server.
• examples/authority_freshness_demo.py alongside the other demo companions.
• Contributor credential minting can now attest a design contribution, so someone whose design a change implements can be credited without the credential claiming they wrote the code.

Testing

• Existing tests pass (pytest tests/)
• New tests added for new functionality
• Manual testing performed

Python 1339 passed, Rust 168 plus interop, TypeScript 397, Go signer suite, MCP 20, and the WebAssembly smoke test at 20 including reproducing the shared vector's proof value in the browser core. The website static export builds.

Checklist

• My code follows the project's code style
• I have added/updated documentation as needed
• I have added tests for new functionality
• All tests pass locally
• My commits are signed off (DCO)

Credit

The design behind this change did not originate in the repository. It came out of a public discussion with Sudip Chatterjee (@aiconsulting4future), who made two specific contributions: he argued that freshness must be a function of both elapsed time and authority state change, with the consequence of the action setting the threshold, rather than time-decay alone; and he supplied the driving scenario of an autonomous treasury or trading agent whose authority is valid at one moment and, seconds later, is overtaken by a fraud signal, a suspended mandate, or a breached exposure limit, leaving a credential that stays cryptographically valid while no longer representing current authority. He observed that in those cases the acceptable stale window collapses toward zero. That framing is the reason this feature exists. The code here was written in this repository; the design is credited to that discussion, and the feature commit carries a Co-authored-by trailer.

Once this merges, the Verified Contributor credential for that design contribution is minted by running the Verified Contributor credential workflow with the design inputs, which is the path added in this pull request for crediting someone who did not author the commits:

gh workflow run verified-contributor.yml \
  -f pr_number=PR_NUMBER \
  -f design_subject=aiconsulting4future \
  -f design_contribution="Argued that trust freshness must be a function of both elapsed time and authority state change, with the consequence of the action setting the threshold, and supplied the treasury and trading scenario where a credential stays cryptographically valid while no longer representing current authority."

[github-actions]

Vouch Verified Contributor ✨

Thank you @aiconsulting4future. The design this pull request implements came from you, and that earns a signed
Vouch Verified Contributor certificate, chained to the project root authority.

Your certificate (download and share it): https://vouch-protocol.com/c/aiconsulting4future/375

Add the badge to your profile or site (optional):

[![Vouch Verified Contributor](https://img.shields.io/badge/Vouch-Verified_Contributor-7C2D3A?style=for-the-badge&labelColor=2d2d2d)](https://vouch-protocol.com/c/aiconsulting4future/375)

Your Verifiable Credential (eddsa-jcs-2022)

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://vouch-protocol.com/contexts/v1"
  ],
  "id": "urn:uuid:25af0415-4062-4776-88fd-9df9baf04671",
  "type": [
    "VerifiableCredential",
    "VouchCredential"
  ],
  "issuer": "did:web:vouch-protocol.com:contributors",
  "validFrom": "2026-08-01T19:45:27Z",
  "validUntil": "2126-07-08T19:45:27Z",
  "credentialSubject": {
    "id": "did:web:vouch-protocol.com:contributors",
    "vouchVersion": "1.0",
    "intent": {
      "action": "attest",
      "target": "github:aiconsulting4future",
      "resource": "https://github.com/vouch-protocol/vouch/pull/375",
      "role": "design-contributor",
      "repository": "vouch-protocol/vouch",
      "contributionType": "design",
      "implementedIn": 375,
      "contribution": "Argued that trust freshness must be a function of both elapsed time and authority state change, with the consequence of the action setting the threshold, and supplied the treasury and trading scenario where a credential stays cryptographically valid while no longer representing current authority."
    },
    "delegationChain": [
      {
        "issuer": "did:web:vouch-protocol.com",
        "subject": "did:web:vouch-protocol.com:contributors",
        "intent": {
          "action": "attest",
          "target": "github:aiconsulting4future",
          "resource": "https://github.com/vouch-protocol/vouch/pull/375",
          "role": "design-contributor",
          "repository": "vouch-protocol/vouch",
          "contributionType": "design",
          "implementedIn": 375,
          "contribution": "Argued that trust freshness must be a function of both elapsed time and authority state change, with the consequence of the action setting the threshold, and supplied the treasury and trading scenario where a credential stays cryptographically valid while no longer representing current authority."
        },
        "validFrom": "2026-06-19T04:45:43Z",
        "validUntil": "2036-06-16T04:45:43Z",
        "parentProofValue": "z5g1N4udQdy5asdxnV3qFhApB5cAh28DkMqHjEUSNG6cc8hrDDsxWyVbgn1XXUFR"
      }
    ]
  },
  "proof": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-08-01T19:45:27Z",
    "verificationMethod": "did:web:vouch-protocol.com:contributors#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z4barz5UTC8s1SEwDLWqLATs4m82M8Rh3yVJkUAksYEkYPKD8nEtb2iwz2p3L3qkbyGQAchyhxsoQ1rftY46mecd5"
  }
}