feat(provenance): freshness and revocation, with the semantics sign.py documents

[lywinged]

Closes #151.

issued_at has been required since this format existed, and _check_structure says why:

A record with no issue time cannot be aged, so a consumer has no way to reject a stale one.

Nothing aged it. Walking the module for Compare nodes mentioning issued_at gives two — the type check and build_record's default — and the only time.time() call was build_record stamping it.

def verify_record(record, trusted_jwk, *,
                  revocation: RevocationStore | None = None,
                  max_age_seconds: int | None = None,
                  max_future_skew_seconds: int = 300) -> None:

Nothing new was needed. RevocationStore and _check_not_revoked already exist in sign.py and are reused rather than reimplemented.

On revocation, precisely

This is not "one format checks and the other does not" — Trust Records skip revocation by default too, as documented. It is that one format gave the consumer the hook and the other did not.

The obvious answer is that the caller holds trusted_jwk and can consult a CRL themselves. That works less well than it looks, because the rule the library uses to decide what a key is listed under is private:

def _key_identifiers(jwk):          # not exported
    identifiers = [jwk_thumbprint(jwk)]
    kid = jwk.get("kid")
    if isinstance(kid, str) and kid and kid not in identifiers:
        identifiers.append(kid)
    return identifiers

A caller writing the check by hand reaches for the thumbprint and misses every entry listed by kid — which is what kid is for. The substitute exists and diverges, in the direction of accepting a revoked key.

Consulted before the signature check, because a signature made by a revoked key stays cryptographically valid and the verifier is the only place the fact can be applied.

On the two defaults

max_age_seconds defaults to None, not to the 86400 of a Trust Record. A provenance record describes an artifact by immutable digest, much like a package signature, and those are conventionally valid indefinitely — a default bound here would be wrong. The docstring names endpoint identity as the case where that reasoning does not hold, since a URL and an SPKI digest decay.

max_future_skew_seconds is enforced whether or not an age bound is set. Adding max_age_seconds alone would have shipped the defect #155 had just fixed for Trust Records: a far-future issued_at sits inside any later age window until that time arrives.

Tests

Ten, and load-bearing rather than decorative — measured by removing each check and counting what notices:

Removed	Tests that fail
the freshness block	3
only the future-skew check	1
the revocation call	3
kid from the revocation identifiers	1

The last row is the point of the whole change: that is the caller-side substitute, and it is why the hook belongs here rather than in the caller.

Verification

Fresh clone in a directory that has never held the repository: 353 pass, 1 skipped. ruff and mypy clean, and ruff was clean on the same files before this change.

Merges with #149 without conflict. That PR makes the revocation half cheaper by bringing jwk_thumbprint into this module, but neither depends on the other and they can land in either order.

[github-actions]

❔ Contributor Check: UNKNOWN

Check	Result
Profile	UNKNOWN
Credential	LOW
Overall	UNKNOWN

Automated check by AgenTrust Contributor Check.

[imran-siddique]

The freshness and revocation hooks are the right shape, but max_age_seconds lacks the validation already applied to max_future_skew_seconds. Passing max_age_seconds=-1 does not report invalid verifier configuration; it classifies essentially every current record as stale. Please require a non-negative integer (excluding bool) when supplied, do the same strict type check for max_future_skew_seconds, and add boundary tests for negative, boolean, and non-integer values. This is a public security-verifier API, so silently accepting malformed policy inputs is unsafe.

[lywinged]

Fixed in 724fe9e. You were right that the asymmetry was the whole problem:
max_age_seconds=-1 was not a stricter bound, it classified every record ever
issued as stale, uniformly, and a caller who meant to disable the bound got
a blanket refusal with no error naming the cause.

Both parameters now go through one _check_seconds, so the validation cannot
drift apart again. It rejects non-integers and negatives, and excludes bool
explicitly - bool subclasses int in Python, so max_age_seconds=True
would otherwise have been accepted as a one-second bound.

Boundary tests cover -1, -86400, True, False, 1.5, "300" and a bare object
for max_age_seconds, and the same set plus None for max_future_skew_seconds.
One more test keeps 0 and None distinct: 0 is the strictest bound expressible

• the record must be issued at this instant - and None disables the bound, so
  a validator treating 0 as falsy would silently accept everything under the
  strictest policy a caller can write.

Load-bearing rather than asserted: removing the max_age check fails 4 tests,
removing the skew check fails 6.

The branch also predated #149 and #154, so main is merged in - the conflicts
were import-level only. 424 passed, 1 skipped, ruff clean.