CG-1956 multi validator updates

.claude/skills/check-all/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: check-all
+description: Run the full default nox session suite (lint, test, security scan). Equivalent to CI pipeline checks.
+allowed-tools: Bash
+---
+
+Run the full default nox session suite: black lint check, pytest, semgrep security scan, mypy, pyflakes, and pylint.
+
+This is equivalent to the CI pipeline checks.
+
+Run: `nox`

.claude/skills/format/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: format
+description: Auto-format code using Black via nox.
+allowed-tools: Bash
+---
+
+Auto-format code using Black via nox.
+
+Run: `nox -s black_format`
+
+Black is configured in pyproject.toml with line-length=119.

.claude/skills/lint/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: lint
+description: Run all linting checks (black, pyflakes, pylint, mypy) using nox.
+allowed-tools: Bash
+---
+
+Run all linting checks using nox. This runs black (formatting check), pyflakes, pylint, and mypy.
+
+Run: `nox -s black_lint pyflakes_src pyflakes_examples pyflakes_tests pylint_src pylint_examples pylint_tests mypy`

.claude/skills/security-scan/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: security-scan
+description: Run semgrep security scan on source code using nox.
+allowed-tools: Bash
+---
+
+Run semgrep security scan on the source code using nox.
+
+Run: `nox -s semgrep_src`

.claude/skills/test/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: test
+description: Run unit tests using nox. Use when the user wants to run tests.
+allowed-tools: Bash
+---
+
+Run unit tests using nox. Pass any additional arguments through to pytest via nox's posargs.
+
+Examples:
+- Full unit test suite: `nox -s pytest`
+- Tests matching a keyword: `nox -s pytest -- -k "test_name"`
+- Specific test file: `nox -s pytest -- tests/test_planet_auth/unit/path/to/test_file.py`
+
+Run: `nox -s pytest -- $ARGUMENTS`
+
+Note: When `-k` is used, nox automatically disables coverage (`--no-cov`).
+Default test paths are configured in pyproject.toml and include `tests/test_planet_auth/unit` and `tests/test_planet_auth_utils/unit`.

docs/changelog.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.4.0 - 2026-03-30
+- `OidcMultiIssuerValidator` now models trust as explicit (issuer, audience) pairs,
+  allowing the same issuer to appear with different audiences.
+- Minor fixes
+
 ## 2.3.1 - 2025-12-10
 - Fix a bug where sops protected files would be rewritten without preserving
   their sops protection.

docs/examples-service.md

@@ -16,9 +16,10 @@ When a service is acting on behalf of one of its clients...
 ## Verifying OAuth Clients
 The [planet_auth.OidcMultiIssuerValidator][] class is provided to assist with
 common OAuth client authentication scenarios.  This class can be configured
-with a single authority for normal operations, and may optionally be configured
-with a secondary authorities.  This allows for complex deployments such as
-the seamless migration between auth servers over time.
+with one or more trusted issuing authorities, each represented as an
+(issuer, audience) pair.  This allows for complex deployments such as
+the seamless migration between auth servers over time, or accepting tokens
+minted for different audiences by the same authorization server.
 
 This utility class may be configured for entirely local token validation,
 or may be configured to check token validity against the OAuth token inspection

docs/examples/service/flask--oidc-multi-issuer--local-and-remote-validation.py

@@ -48,6 +48,15 @@
 # secret) that is permitted client credentials OAuth flow and grant type.
 # This is not the only possibility.
 
+# Trust is established as (issuer, audience) pairs.  Each entry must specify
+# exactly one audience.  To trust multiple audiences from the same issuer,
+# provide separate entries for each (issuer, audience) pair.
+#
+# Note: The "audiences" config field is a list because the underlying client
+# config schema is shared with OAuth clients that request tokens, where
+# multiple audiences can be meaningful.  For services validating tokens,
+# each trust entry must map to exactly one (issuer, audience) pair.
+
 # TODO: we should have an example of how to use a built-in provider to provide
 #     named application server trust environments through use of the
 #     planet_auth_utils.PlanetAuthFactory.initialize_resource_server_validator

docs/examples/service/flask--oidc-multi-issuer--local-only-validation.py

@@ -49,6 +49,15 @@
 # Do not cross the streams.
 # Seriously.  Don't do it.
 
+# Trust is established as (issuer, audience) pairs.  Each entry must specify
+# exactly one audience.  The same issuer may appear multiple times with
+# different audiences if the auth server issues tokens for more than one
+# audience that this service should accept.
+#
+# Note: The "audiences" config field is a list because the underlying client
+# config schema is shared with OAuth clients that request tokens, where
+# multiple audiences can be meaningful.  For services validating tokens,
+# each trust entry must map to exactly one (issuer, audience) pair.
 auth_validator = planet_auth.OidcMultiIssuerValidator.from_auth_server_configs(
     trusted_auth_server_configs=[
         {

noxfile.py

@@ -3,8 +3,8 @@
 
 import nox
 
-nox.options.stop_on_first_error = True
-nox.options.reuse_existing_virtualenvs = False
+nox.options.stop_on_first_error = False
+nox.options.reuse_existing_virtualenvs = True
 
 # Default sessions - all tests, but not packaging
 nox.options.sessions = [

pyproject.toml

@@ -58,7 +58,7 @@ examples = [
     # "planet-auth-config >= 2.0.0"
 ]
 test = [
-    "black",
+    "black < 26.0.0",
     "coverage[toml]",
     "freezegun",
     "mypy",

src/planet_auth/__init__.py

@@ -112,7 +112,7 @@ class exists.
     TokenValidatorException,
     UnknownSigningKeyTokenException,
 )
-from .oidc.multi_validator import OidcMultiIssuerValidator
+from .oidc.multi_validator import OidcMultiIssuerValidator, TrustEntry
 from .planet_legacy.auth_client import PlanetLegacyAuthClientConfig, PlanetLegacyAuthClient
 from .static_api_key.auth_client import (
     StaticApiKeyAuthClientConfig,
@@ -186,6 +186,7 @@ class exists.
     "OidcClientValidatorAuthClientConfig",
     "OidcClientValidatorAuthClient",
     "OidcMultiIssuerValidator",
+    "TrustEntry",
     "NoOpAuthClient",
     "NoOpAuthClientConfig",
     "PlanetLegacyAuthClient",

src/planet_auth/oidc/auth_client.py

@@ -564,7 +564,7 @@ def validate_access_token_local(
                 )
             if len(conf_audiences) != 1:
                 raise AuthClientException(
-                    message="When using the auth client config's audiences as the source for required token audience during validaiton, only one audience may be specified."
+                    message="When using the auth client config's audiences as the source for required token audience during validation, only one audience may be specified."
                 )
             required_audience = conf_audiences[0]