Ensure compatibility with new stateless JWT-format installation tokens

[MariusStorhaug]

Context and Request

GitHub is rolling out a new token format for GitHub App installation tokens. The new format is a stateless JWT (ghs_-prefixed, ~520 characters, containing two dots) replacing the current short opaque string format.

A developer using the PSModule/GitHub module to authenticate via GitHub App installation tokens needs confidence that the module handles both the current stateful (opaque) format and the incoming stateless (JWT) format without errors or data loss.

Today the module already supports ghs_-prefixed installation tokens (resolved in #83), but any assumptions about token length, structure, or validation patterns may break when GitHub begins returning the longer JWT-format tokens.

Acceptance criteria

• No hardcoded token-length assumptions exist in authentication or storage logic.
• Any regex validating installation tokens matches both formats (recommended pattern: ghs_[A-Za-z0-9\._]{36,}).
• Token parameters and variables accept at least 520 characters.
• The module works end-to-end when receiving a stateless JWT-format token from POST /app/installations/:installation_id/access_tokens.
• A test validates both token formats are accepted.

---

Technical Decisions

Validation pattern: Use the regex ghs_[A-Za-z0-9\._]{36,} as recommended by GitHub. This handles both the short opaque tokens and the new JWT tokens.

No token introspection: Tokens are treated as opaque strings regardless of internal structure. No parsing of the JWT payload.

Opt-in testing header: During development, use the X-GitHub-Stateless-S2S-Token: enabled request header on POST /app/installations/:installation_id/access_tokens to force the new format and validate compatibility. Remove the header before merging.

---

Implementation Plan

Audit

• Search for token-length checks, regex patterns, or substring logic applied to ghs_ tokens.
• Identify any database columns, variables, or parameters with length constraints that could reject a ~520 character token.

Fix

• Update any regex or validation logic to use ghs_[A-Za-z0-9\._]{36,}.
• Remove or relax any maximum-length constraints on token storage/parameters.

Test

• Add a unit test that passes both a short opaque token (ghs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx) and a long JWT-format token (ghs_<header>.<payload>.<signature> ~520 chars) through the authentication path.
• Manually verify with X-GitHub-Stateless-S2S-Token: enabled header against a real GitHub App installation.

References

• Changelog: Per-request override header
• Changelog: Notice about upcoming new format (April 2026)
• REST API: Create installation access token