[djw8605]

Addresses #226.

Problem

Token time claims are checked by jwt-cpp's default verifier, which uses a leeway of 0. If the resource server's clock is even 1 second behind the issuer's, a freshly issued token fails the iat check (now < iat). Issuers such as INDIGO IAM backdate nbf by 60s or more to absorb skew, but the strict iat check defeats that. On top of this, jwt-cpp reports the failure as token_expired, which scitokens-cpp surfaces as a TokenExpiredException with "token expired". That is misleading for a token that looks like it was issued in the future.

Change

• New int config key validation.clock_skew_s (env var SCITOKEN_CONFIG_VALIDATION_CLOCK_SKEW_S), default 60 seconds. Negative values are rejected.
• In Validator::verify_async_continue, the default jwt-cpp iat and nbf checks are replaced via with_claim with checks that allow up to that skew. They keep the jwt-cpp behavior of skipping a claim that is absent, so profiles where nbf is optional are unaffected.
• When a claim is too far in the future, the error now names it, for example: token verification failed: 'iat' claim is 100s in the future, more than the allowed clock skew of 60s. It no longer mentions expiry, so it is not turned into a TokenExpiredException.
• exp is still checked strictly (no leeway), so skew tolerance never extends a token's lifetime.
• Documented the key in scitokens.h next to the other int config keys.

Open questions for review

• Default value. 60s matches the nbf backdating IAM uses. It changes behavior for existing deployments (previously 0). Set validation.clock_skew_s=0 to restore strict checking.
• Key name. validation.clock_skew_s is new, since the existing prefixes (keycache., tls., monitoring.) don't fit. Happy to rename.
• Related, not changed here. Validator::m_now is set once when the object is constructed and is not refreshed on each verify() unless validator_set_time/enforcer_set_time is called. Long-lived Validator/Enforcer objects therefore check claims against a stale clock, which could cause the same symptom. That seems worth a separate change.

Testing

• Added SerializeTest.ClockSkew. It covers: accepted within the default skew; rejected beyond it, with an error that says "in the future" and not "expired"; accepted with a larger configured skew; rejected with skew 0; exp not extended by skew; negative value rejected.
• SerializeTest.* passes locally (18/18), and so do the monitoring and env config tests. In the full unit suite, 44 tests pass. The 3 KeycacheTest refresh tests fail only because the sandbox could not reach demo.scitokens.org ("Failure when receiving data from the peer"), unrelated to this change.
• Formatted with clang-format 18.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pc7RS7J9BoUNRxvG6TZuzb

---

Generated by Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The diagnostic rounds offsets inconsistently, and environment-loading coverage is missing.

Review effort: Balanced
Findings: 2

Open (2)

• Add environment mapping coverage for validation clock skew · New
• Round up sub-second rejected offsets in future-time error messages · New

What changed in this PR

Adds configurable clock-skew tolerance for future iat and nbf claims while retaining strict expiration checks.

Changes:

• Adds the validation.clock_skew_s configuration and environment mapping.
• Applies skew-aware validation with clearer errors.
• Adds unit coverage and public API documentation.

File	Description
src/​scitokens.cpp	Implements configuration storage and environment loading.
src/​scitokens.h	Documents the new integer setting.
src/​scitokens_internal.h	Applies skew-aware claim validation.
test/​main.cpp	Tests skew boundaries, expiration, and invalid configuration.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation matches the stated behavior and includes focused coverage for configuration, validation boundaries, errors, and strict expiration.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Round up sub-second rejected offsets in future-time error messages
• Add environment mapping coverage for validation clock skew