snulbug 0.2.2__tar.gz → 0.2.3__tar.gz

{snulbug-0.2.2 → snulbug-0.2.3}/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on Keep a Changelog, and this project follows semantic versi
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-10-18
+
+Add Pocket ID setup through the existing OAuth provider and lease machinery.
+
+- Added `share auth init --provider pocket-id` with resource-bound API permissions, deny-by-default scope maps, PKCE/CIMD registration instructions, automation guidance, and lease-aware doctor commands.
+- Extended auth doctor to check exact issuer metadata identity, advertised PKCE S256, and CIMD availability without claiming access to private provider grants or allowlists.
+- Added synthetic RS256 user/bot token fixtures, rejection and JWKS rotation tests, and existing auth conformance-pack coverage; documented setup and identity-claim limitations.
+
+Pocket ID live passkey/client interoperability remains unverified. This release
+does not add browser console login or authentication to HTTP mounts. No change
+to the default MCP protocol version or the experimental profile's limitations.
+
 ## [0.2.2] - 2026-10-16
 
 Support always-on MCP bots with renewable automation invites, without introducing

{snulbug-0.2.2 → snulbug-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: snulbug
-Version: 0.2.2
+Version: 0.2.3
 Summary: A local-dev MCP policy proxy with Lua policies, replay logs, and learned least-privilege bundles
 Project-URL: Homepage, https://github.com/nahuaque/snulbug
 Project-URL: Repository, https://github.com/nahuaque/snulbug
@@ -468,7 +468,7 @@ Workflow:
 - optional OAuth protected-resource mode with JWT/JWKS, token introspection, DPoP validation, and MCP auth challenges
 - OAuth scope-to-MCP method/tool mapping for least-privilege public shares
 - OAuth resource/audience drift checks for tunnel-safe public shares
-- generated auth setup flows for Keycloak, Auth0, Okta, Entra, Cloudflare Access, and GitHub OIDC
+- generated auth setup flows for Keycloak, Pocket ID, Auth0, Okta, Entra, Cloudflare Access, and GitHub OIDC
 - composable OAuth + auth-bound task lease + Lua policy access decisions
 - anti-passthrough credential brokering so caller OAuth tokens stop at snulbug
 - learned least-privilege bundles from observed traffic

{snulbug-0.2.2 → snulbug-0.2.3}/README.md

@@ -425,7 +425,7 @@ Workflow:
 - optional OAuth protected-resource mode with JWT/JWKS, token introspection, DPoP validation, and MCP auth challenges
 - OAuth scope-to-MCP method/tool mapping for least-privilege public shares
 - OAuth resource/audience drift checks for tunnel-safe public shares
-- generated auth setup flows for Keycloak, Auth0, Okta, Entra, Cloudflare Access, and GitHub OIDC
+- generated auth setup flows for Keycloak, Pocket ID, Auth0, Okta, Entra, Cloudflare Access, and GitHub OIDC
 - composable OAuth + auth-bound task lease + Lua policy access decisions
 - anti-passthrough credential brokering so caller OAuth tokens stop at snulbug
 - learned least-privilege bundles from observed traffic

{snulbug-0.2.2 → snulbug-0.2.3}/docs/auth-providers.md

@@ -5,9 +5,13 @@ snulbug has a small auth provider extension point for two related jobs:
 - generate `snulbug mcp share auth init --provider ...` setup recipes
 - map provider-specific token claims into `context.auth.provider.*` for Lua policy helpers
 
-Built-ins cover Keycloak, Auth0, Okta, Entra, Cloudflare Access, and GitHub
+Built-ins cover Keycloak, Pocket ID, Auth0, Okta, Entra, Cloudflare Access, and GitHub
 Actions OIDC. External providers can register the same surface from Python.
 
+The [Pocket ID recipe](mcp-auth-recipes.md#pocket-id) uses standard verified
+subject/client identity and API scopes. It does not invent provider claims or
+retrieve identity claims from ID tokens/userinfo during MCP requests.
+
 ```python
 from collections.abc import Mapping
 from typing import Any

{snulbug-0.2.2 → snulbug-0.2.3}/docs/devcontainers.md

@@ -10,8 +10,8 @@ servers with a shared control plane.
 ```json
 {
   "features": {
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.2": {
-      "version": "0.2.2",
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.3": {
+      "version": "0.2.3",
       "mode": "member-agent",
       "policy_profile": "tunnel-safe",
       "registry": "redis://redis:6379/0",

{snulbug-0.2.2 → snulbug-0.2.3}/docs/mcp-auth-recipes.md

@@ -37,6 +37,7 @@ snulbug mcp share auth recipe \
 Supported providers:
 
 - `keycloak`
+- `pocket-id`
 - `auth0`
 - `okta`
 - `okta-xaa`
@@ -51,6 +52,8 @@ provider can be validated against a live dev account:
 
 - Keycloak: runnable Docker Compose demo in
   [`examples/keycloak_oauth_demo`](../examples/keycloak_oauth_demo/README.md).
+- Pocket ID: generated setup and synthetic RS256 token/discovery fixtures are
+  covered; a live passkey login or real-client demo has not been validated.
 - Auth0: generated setup recipe is available; live provider demo forthcoming.
 - Okta: generated setup recipe is available; live provider demo forthcoming.
 - Okta XAA / MCP Enterprise-Managed Authorization: generated setup recipe is
@@ -137,9 +140,92 @@ Lua identity policy to constrain the workflow.
 
 ## Provider Notes
 
+### Keycloak
+
 Keycloak often needs an explicit audience mapper so access tokens contain the
 MCP public URL in `aud`.
 
+### Pocket ID
+
+Use Pocket ID as the external issuer, with snulbug as its protected API:
+
+```bash
+snulbug mcp share auth init \
+  --provider pocket-id \
+  --url https://share.example.com/mcp \
+  --issuer https://id.example.com \
+  --client-id "$POCKET_ID_CLIENT_ID"
+```
+
+Use the actual client ID from Pocket ID, not the client's display name. Omit
+`--client-id` to generate instructions before registering a client.
+
+This writes `.snulbug/auth/pocket-id/` with the normal five setup files. Review
+the generated README and merge `snulbug.auth.toml` into your existing share
+config; the overlay is not a standalone upstream/policy configuration. From a
+source checkout, prefix these commands with `uv run`.
+
+In Pocket ID, create an **API** with resource `https://share.example.com/mcp`,
+then add the permission keys listed in the generated setup. Grant those
+permissions to the MCP client under **User-delegated access**. Public clients
+use authorization code with PKCE S256 and their exact callback URLs. The client
+requests `resource=https://share.example.com/mcp` and `openid` plus the API
+permissions. It sends the resulting **access token**, not its ID token, to
+snulbug. See [Pocket ID APIs and permissions](https://pocket-id.org/docs/guides/apis).
+
+`--scope` can narrow the generated permission set. `mcp:connect` is always
+required. Default tool selectors are examples (`filesystem.read_file` and
+`git.status`); change them to match discovered tool names. Custom permissions
+start with empty selector lists, which grant no MCP actions until mapped. A
+connect-only configuration does not implicitly grant all tools. Identity scopes
+such as `openid` are not API permission keys; the client request adds `openid`
+automatically.
+
+For CIMD clients, Pocket ID requires an explicit metadata-document URL allowlist
+and a separate API permission grant. Prefer exact metadata URLs. The API-wide
+metadata-client grant applies to future allowed clients too; it is not a grant
+to just one client. Manual registration remains supported, so disabled CIMD is
+not a doctor failure. See [Pocket ID client metadata](https://pocket-id.org/docs/guides/client-id-metadata-documents).
+
+Keep `lease_required = true` and give the consumer its `x-snulbug-lease` header.
+Automation uses a separate confidential client with **Client access (M2M)**,
+resource-bound API permissions, and an identity-bound renewable invite. Pocket
+ID token acquisition/refresh and snulbug lease renewal remain separate consumer
+operations. No client secret or refresh token belongs in the gateway config.
+
+Do not assume Pocket ID groups or custom tenant claims are present in API access
+tokens: profile/custom claims are documented for ID tokens/userinfo. This recipe
+uses subject/client identity, scopes, and leases, without a new claim mapper or
+userinfo fetch. Inspect actual API tokens before adding claim-dependent Lua.
+See [Pocket ID scopes and claims](https://pocket-id.org/docs/guides/scopes-and-claims).
+
+After starting the share, verify it with the existing doctor:
+
+```bash
+snulbug mcp share auth doctor \
+  --config .snulbug/shares/my-share/snulbug.toml \
+  --url https://share.example.com/mcp \
+  --token "$ACCESS_TOKEN" \
+  --header "x-snulbug-lease: $SNULBUG_LEASE"
+```
+
+Doctor checks public resource/audience alignment, metadata issuer identity,
+PKCE S256 when authorization code is advertised, reachable JWKS, and scope-map
+tool targets. It reports CIMD advertisement but cannot inspect Pocket ID's
+private API grants or allowlist. Global issuer `scopes_supported` is not proof
+that a particular API permission was granted. Prove sample tokens, discovered
+schemas, and recorded evidence with the existing [auth conformance pack](#auth-conformance-pack).
+Token checks cover authentication on initialization; tool-scope behavior also
+needs recorded/replayed calls. DPoP stays optional pending issuer/client testing.
+
+Use stable HTTPS issuer and public resource URLs. If a tunnel URL changes,
+register a replacement Pocket ID API resource, grant it to the client, and align
+the snulbug configuration rather than accepting client-ID audiences. Pocket ID
+API resources cannot be edited after creation. Console authentication is
+unchanged; this recipe does not add Pocket ID console login.
+
+### Other Providers
+
 Auth0 should model the MCP endpoint as an API whose Identifier is the public MCP
 URL, then issue access tokens for that audience.
 
@@ -185,3 +271,29 @@ For provider-specific Lua helper patterns, see
 [`examples/provider_policy_templates`](../examples/provider_policy_templates/README.md).
 It includes copyable Keycloak role gates, Entra app-role gates, GitHub Actions
 workload gates, and Cloudflare Access group gates.
+
+## Auth Conformance Pack
+
+After recording authenticated MCP calls and discovering schemas, use the existing
+auth conformance workflow for any OAuth provider. Set `ACCESS_TOKEN` to a valid
+API access token and `WRONG_AUDIENCE_TOKEN` to a token for a different resource
+or a client-bound ID token. Keep both in the environment, not checked-in files:
+
+```bash
+snulbug mcp share auth conformance generate \
+  --config .snulbug/shares/my-share/snulbug.toml \
+  --url https://share.example.com/mcp \
+  --schema-catalog schemas.json \
+  --log audit.jsonl --kind audit \
+  --token-env valid=ACCESS_TOKEN \
+  --denied-token-env wrong-audience=WRONG_AUDIENCE_TOKEN \
+  --output-dir .snulbug/auth-conformance
+
+snulbug mcp share auth conformance run .snulbug/auth-conformance \
+  --header "x-snulbug-lease: $SNULBUG_LEASE"
+```
+
+Use your actual schema/audit paths. The pack stores token environment references,
+config/schema fingerprints, and evidence summaries, not raw sample tokens. Run
+with `--no-live-checks` for offline validation; this does not prove live login,
+private issuer grants, or client interoperability.

{snulbug-0.2.2 → snulbug-0.2.3}/docs/release.md

@@ -49,7 +49,7 @@ python -m zipfile -l dist/snulbug-*.whl
 8. Install from TestPyPI in a clean environment and smoke test:
 
 ```bash
-uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ snulbug==0.2.2 --help
+uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ snulbug==0.2.3 --help
 ```
 
 9. Run the manual `Publish` workflow with `repository = pypi` when the TestPyPI
@@ -57,4 +57,4 @@ uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org
 10. Create the GitHub release and tag after the PyPI package is available.
 
 The `Publish` workflow uses `workflow_dispatch`, not a tag trigger. Creating or
-pushing `v0.2.2` does not publish a package or automatically create a GitHub release.
+pushing `v0.2.3` does not publish a package or automatically create a GitHub release.

{snulbug-0.2.2 → snulbug-0.2.3}/examples/codespace_local_gateway/.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
   "name": "snulbug Codespace MCP member",
   "features": {
     "ghcr.io/devcontainers/features/python:1": {},
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.2": {
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.3": {
       "install_source": "github",
       "github_ref": "main",
       "mode": "member-agent",

{snulbug-0.2.2 → snulbug-0.2.3}/features/snulbug/README.md

@@ -6,7 +6,7 @@ workspace helpers for Codespaces/devcontainers.
 ```json
 {
   "features": {
-    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.2": {
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.3": {
       "install_source": "github",
       "github_ref": "main",
       "mode": "member-agent",

{snulbug-0.2.2 → snulbug-0.2.3}/features/snulbug/devcontainer-feature.json

@@ -1,6 +1,6 @@
 {
   "id": "snulbug",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "name": "snulbug",
   "description": "Install snulbug and optional helpers for MCP policy gateways and remote fabric members in devcontainers.",
   "documentationURL": "https://github.com/nahuaque/snulbug/blob/main/docs/devcontainers.md",

{snulbug-0.2.2 → snulbug-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "snulbug"
-version = "0.2.2"
+version = "0.2.3"
 description = "A local-dev MCP policy proxy with Lua policies, replay logs, and learned least-privilege bundles"
 readme = "README.md"
 requires-python = ">=3.10"

{snulbug-0.2.2 → snulbug-0.2.3}/snulbug/__init__.py

@@ -1,6 +1,6 @@
 """Local-dev MCP policy proxy and programmable Lua ASGI policy layer."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 from .auth_providers import (
     AuthProvider,

{snulbug-0.2.2 → snulbug-0.2.3}/snulbug/auth_recipes.py

@@ -4,6 +4,7 @@ import json
 from collections.abc import Mapping, Sequence
 from pathlib import Path
 from typing import Any
+from urllib.parse import urlsplit
 
 from .auth_providers import (
     AuthProvider,
@@ -19,6 +20,11 @@ DEFAULT_AUTH_SCOPES = (
     "mcp:tool.files.read",
     "mcp:tool.git.status",
 )
+_DEFAULT_AUTH_SCOPE_MAP = {
+    "mcp:tools.read": ("tools/list", "resources/list"),
+    "mcp:tool.files.read": ("tools/call:filesystem.read_file",),
+    "mcp:tool.git.status": ("tools/call:git.status",),
+}
 ENTERPRISE_MANAGED_AUTH_EXTENSION = "io.modelcontextprotocol/enterprise-managed-authorization"
 
 DEFAULT_AUTH_INIT_ROOT = Path(".snulbug/auth")
@@ -147,6 +153,15 @@ def _register_builtin_auth_recipe_providers() -> None:
             title="Keycloak",
             docs=("https://www.keycloak.org/docs/latest/server_admin/#_clients",),
         ),
+        _OAuthRecipeProvider(
+            name="pocket-id",
+            title="Pocket ID",
+            docs=(
+                "https://pocket-id.org/docs/guides/apis",
+                "https://pocket-id.org/docs/guides/client-id-metadata-documents",
+                "https://pocket-id.org/docs/guides/scopes-and-claims",
+            ),
+        ),
         _OAuthRecipeProvider(
             name="auth0",
             title="Auth0",
@@ -405,6 +420,30 @@ def _oauth_provider_recipe(
     auth_server_id: str | None,
     scopes: Sequence[str],
 ) -> dict[str, Any]:
+    if provider == "pocket-id":
+        for name, value in (("issuer", issuer), ("public MCP URL", public_url)):
+            parsed = urlsplit(value)
+            local = parsed.hostname in {"localhost", "127.0.0.1", "::1"}
+            if (
+                not parsed.hostname
+                or parsed.scheme not in {"http", "https"}
+                or (parsed.scheme != "https" and not local)
+                or parsed.username is not None
+                or parsed.password is not None
+                or parsed.query
+                or parsed.fragment
+            ):
+                raise ValueError(
+                    f"Pocket ID {name} must be an absolute HTTPS URL (HTTP only for localhost), "
+                    "without credentials, query, or fragment"
+                )
+        identity_scopes = {"openid", "profile", "email", "groups", "offline_access"}.intersection(scopes)
+        if identity_scopes:
+            raise ValueError(
+                "Pocket ID --scope values must be API permission keys, not identity scopes; "
+                "openid is added to the client request automatically"
+            )
+        scopes = _unique_strings(["mcp:connect", *scopes])
     provider_steps = _oauth_provider_steps(
         provider,
         public_url=public_url,
@@ -416,7 +455,7 @@ def _oauth_provider_recipe(
         auth_server_id=auth_server_id,
         scopes=scopes,
     )
-    return {
+    recipe = {
         "ok": True,
         "kind": "snulbug.auth.recipe",
         "provider": provider,
@@ -452,6 +491,23 @@ def _oauth_provider_recipe(
         "notes": _oauth_provider_notes(provider, public_url=public_url, audience=audience),
         "docs": list(docs),
     }
+    if provider == "pocket-id":
+        if audience != public_url:
+            raise ValueError("Pocket ID audience must equal the public MCP URL used as the API resource")
+        # Keep an explicit, deny-by-default map even for connect-only or custom permissions.
+        scope_map = {scope: _DEFAULT_AUTH_SCOPE_MAP.get(scope, ()) for scope in scopes}
+        recipe["snulbug_config"] = _oauth_snulbug_config(
+            public_url=public_url, issuer=issuer, audience=audience, scopes=scopes, scope_map=scope_map
+        )
+        recipe["client_request"].update(
+            resource=public_url,
+            scopes=_unique_strings(["openid", *scopes]),
+            grant_type="authorization_code",
+            code_challenge_method="S256",
+            token_endpoint_auth_method="none",
+        )
+        recipe["commands"]["doctor"] += ' --header "x-snulbug-lease: ${SNULBUG_LEASE}"'
+    return recipe
 
 
 def _cloudflare_access_recipe(
@@ -627,8 +683,14 @@ def _oauth_snulbug_config(
     issuer: str,
     audience: str,
     scopes: Sequence[str],
+    scope_map: Mapping[str, Sequence[str]] | None = None,
 ) -> str:
     scope_list = _toml_string_list(scopes)
+    if scope_map is None:
+        scope_map = _DEFAULT_AUTH_SCOPE_MAP
+    mappings = "\n".join(
+        f"{json.dumps(scope)} = {_toml_string_list(selectors)}" for scope, selectors in scope_map.items()
+    )
     return f"""[mcp.proxy]
 tunnel_public_url = {json.dumps(public_url)}
 lease_required = true
@@ -647,9 +709,7 @@ strip_authorization_upstream = true
 dpop_mode = "optional" # set to "required" for DPoP-only clients
 
 [mcp.auth.scope_map]
-"mcp:tools.read" = ["tools/list", "resources/list"]
-"mcp:tool.files.read" = ["tools/call:filesystem.read_file"]
-"mcp:tool.git.status" = ["tools/call:git.status"]
+{mappings}
 """
 
 
@@ -735,6 +795,28 @@ def _oauth_provider_steps(
     scopes: Sequence[str],
 ) -> list[str]:
     scope_text = ", ".join(f"`{scope}`" for scope in scopes)
+    if provider == "pocket-id":
+        return [
+            f"Under Administration -> APIs, add an API named snulbug with resource `{public_url}`. "
+            "Use a stable public MCP URL without a trailing slash; Pocket ID normalizes trailing slashes.",
+            f"Add API permission keys: {scope_text}. These are API permissions, not identity/profile scopes.",
+            f"Create or choose an OIDC client for the MCP client{_client_suffix(client_id)}. "
+            "For a desktop/public client, use authorization code with PKCE S256, no client secret, "
+            "and the client's exact callback URLs.",
+            "On the client's Access tab, add the snulbug API under User-delegated access and select "
+            "the permissions it may request. Restrict allowed user groups as appropriate.",
+            f"Request `resource={public_url}` and `openid` plus the needed API permissions. "
+            "Send the access token to snulbug, never the ID token.",
+            "For Client ID Metadata Document (CIMD) clients, allowlist exact HTTPS metadata document URLs "
+            "under Application Configuration -> OIDC. CIMD is disabled by default. Separately grant API "
+            "permissions to metadata-document clients under Administration -> APIs; this grant covers "
+            "current and future allowed metadata-document clients, so keep the allowlist narrow.",
+            "For an automation bot, use a separate confidential OIDC client with Client access (M2M) "
+            "to the API. Request grant_type=client_credentials with the same resource and needed "
+            "permissions. Keep its secret or federated client assertion in the consumer, not snulbug.",
+            "Review the generated scope_map selectors against discovered tool names. Empty selector "
+            "lists grant no MCP actions; add concrete selectors for custom permissions before using them.",
+        ]
     if provider == "keycloak":
         return [
             f"In realm `{realm or '<realm>'}`, create or choose an OpenID Connect client for the MCP client.",
@@ -787,6 +869,28 @@ def _oauth_provider_notes(provider: str, *, public_url: str, audience: str) -> l
         )
     if provider == "keycloak":
         notes.append("Keycloak often needs an explicit audience mapper for access-token `aud` values.")
+    if provider == "pocket-id":
+        notes.extend(
+            [
+                "Use a stable HTTPS Pocket ID issuer reachable from both the MCP client and snulbug. "
+                "Set --issuer or --domain to its APP_URL, not a discovery-document or token-endpoint URL.",
+                "A normal OIDC login token targets the client ID. Only an API access token requested with "
+                "the MCP resource has the required audience; do not relax audience validation.",
+                "Pocket ID custom claims are in ID tokens/userinfo, not access tokens. Do not assume "
+                "groups or tenant claims are available to Lua; inspect an API access token first. "
+                "This recipe uses verified subject/client identity, API scopes, and leases.",
+                "OAuth does not replace a snulbug lease. Supply x-snulbug-lease for MCP calls; bind "
+                "renewable automation invites to the verified issuer and subject or client ID. OAuth "
+                "token refresh/acquisition and snulbug lease renewal are separate consumer operations.",
+                "Doctor checks metadata, JWKS, public resource/audience alignment, and discovered scope-map "
+                "targets. It cannot inspect Pocket ID's private API grants or CIMD allowlist; prove actual "
+                "permissions with sample tokens in the existing share auth conformance workflow.",
+                "DPoP is optional in the generated config. Require it only after verifying issuer/client "
+                "support. Console login remains protected by the console secret, not Pocket ID.",
+                "This is a generated setup recipe with synthetic token fixture coverage, not a live "
+                "Pocket ID or real-client interoperability certification.",
+            ]
+        )
     return notes
 
 
@@ -804,6 +908,8 @@ def _provider_issuer(
     if provider == "keycloak":
         base = _https_domain(domain or "KEYCLOAK.example")
         return f"{base}/realms/{realm or 'YOUR_REALM'}"
+    if provider == "pocket-id":
+        return _https_domain(domain or "POCKET_ID.example")
     if provider == "auth0":
         return f"{_https_domain(domain or 'YOUR_TENANT.auth0.com')}/"
     if provider == "okta":
@@ -825,13 +931,14 @@ def _auth_recipe_commands(public_url: str) -> dict[str, str]:
 def _auth_init_commands(recipe: Mapping[str, Any], *, directory: Path) -> dict[str, str]:
     public_url = str(recipe.get("public_url") or "")
     config = directory / "snulbug.auth.toml"
+    doctor = _mapping(recipe.get("commands")).get("doctor") or (
+        f"uv run snulbug mcp share auth doctor --config snulbug.toml --url {public_url} --token $ACCESS_TOKEN"
+    )
     return {
         "review": f"less {directory / 'README.md'}",
         "show_config": f"cat {config}",
         "run": "uv run snulbug mcp share run --config snulbug.toml",
-        "doctor": (
-            f"uv run snulbug mcp share auth doctor --config snulbug.toml --url {public_url} --token $ACCESS_TOKEN"
-        ),
+        "doctor": str(doctor),
     }
 
 

{snulbug-0.2.2 → snulbug-0.2.3}/snulbug/share.py

@@ -2348,6 +2348,9 @@ def doctor_mcp_share_auth(
             details={"attempted_urls": issuer_urls},
         )
 
+    if issuer_metadata:
+        _add_auth_issuer_metadata_checks(checks, auth, issuer_metadata, recommendations)
+
     _add_jwks_or_introspection_check(
         checks,
         issuer_metadata,
@@ -4007,6 +4010,69 @@ def _issuer_metadata_urls(auth: Mapping[str, Any]) -> list[str]:
     return _unique_strings(urls)
 
 
+def _add_auth_issuer_metadata_checks(
+    checks: list[dict[str, Any]],
+    auth: Mapping[str, Any],
+    metadata: Mapping[str, Any],
+    recommendations: list[str],
+) -> None:
+    configured_issuer = auth.get("issuer")
+    expected = (
+        [configured_issuer]
+        if isinstance(configured_issuer, str) and configured_issuer
+        else _auth_issuer_candidates(auth)
+    )
+    issuer = metadata.get("issuer")
+    issuer_ok = isinstance(issuer, str) and bool(issuer) and issuer in expected
+    _add_share_doctor_check(
+        checks,
+        "auth.issuer_metadata.issuer",
+        issuer_ok,
+        "issuer metadata identifies the configured authorization server"
+        if issuer_ok
+        else "issuer metadata issuer is missing or does not exactly match the configured authorization server",
+        component="auth",
+        details={"issuer": issuer, "expected": expected},
+    )
+    if not issuer_ok:
+        recommendations.append(
+            "Align mcp.auth.issuer with the issuer's canonical external URL (APP_URL for Pocket ID); "
+            "issuer identifiers must match exactly, including trailing slashes."
+        )
+
+    code_flow = "authorization_code" in _sequence(metadata.get("grant_types_supported")) or "code" in _sequence(
+        metadata.get("response_types_supported")
+    )
+    pkce_methods = _sequence(metadata.get("code_challenge_methods_supported"))
+    pkce_ok = "S256" in pkce_methods
+    _add_share_doctor_check(
+        checks,
+        "auth.issuer_metadata.pkce_s256",
+        pkce_ok if code_flow else None,
+        "authorization server advertises PKCE S256"
+        if pkce_ok
+        else "authorization code flow is advertised without PKCE S256"
+        if code_flow
+        else "authorization code support is not advertised; PKCE check skipped",
+        component="auth",
+        details={"code_challenge_methods_supported": pkce_methods},
+    )
+    if code_flow and not pkce_ok:
+        recommendations.append("Enable PKCE S256 on the authorization server for public MCP clients.")
+
+    cimd = metadata.get("client_id_metadata_document_supported") is True
+    _add_share_doctor_check(
+        checks,
+        "auth.issuer_metadata.cimd",
+        True if cimd else None,
+        "authorization server advertises Client ID Metadata Document support; verify its allowlist and API grants"
+        if cimd
+        else "CIMD is not advertised; register clients manually or enable explicitly allowed metadata documents",
+        component="auth",
+        details={"client_id_metadata_document_supported": cimd},
+    )
+
+
 def _add_jwks_or_introspection_check(
     checks: list[dict[str, Any]],
     issuer_metadata: Mapping[str, Any] | None,

snulbug-0.2.3/tests/fixtures/pocket_id/README.md

@@ -0,0 +1,19 @@
+# Pocket ID Auth Fixtures
+
+These are synthetic claim and discovery-document shapes, not captured production
+tokens or a claim of live Pocket ID interoperability. Tests sign fresh RS256 JWTs
+with an ephemeral test key and relative expiry times. No private signing key or
+usable provider credential is checked in.
+
+The fixtures exercise resource-bound user and M2M access, client-bound ID token
+rejection, scope mapping, issuer/audience checks, and expiry through snulbug's
+existing OAuth validator. API permissions need not appear in the issuer's global
+`scopes_supported` metadata; actual token grants are tested separately.
+
+Provider references:
+
+- https://pocket-id.org/docs/guides/apis
+- https://pocket-id.org/docs/guides/scopes-and-claims
+- https://pocket-id.org/docs/guides/client-id-metadata-documents
+
+The live passkey/client login flow is outside this fixture suite.

snulbug-0.2.3/tests/fixtures/pocket_id/oauth.json

@@ -0,0 +1,66 @@
+{
+  "issuer_metadata": {
+    "issuer": "https://id.example.test",
+    "authorization_endpoint": "https://id.example.test/authorize",
+    "token_endpoint": "https://id.example.test/api/oidc/token",
+    "jwks_uri": "https://id.example.test/.well-known/jwks.json",
+    "response_types_supported": ["code"],
+    "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
+    "code_challenge_methods_supported": ["S256"],
+    "id_token_signing_alg_values_supported": ["RS256"],
+    "scopes_supported": ["openid", "profile", "email", "groups", "offline_access"],
+    "client_id_metadata_document_supported": true
+  },
+  "cases": [
+    {
+      "name": "human-api-access",
+      "claims": {"sub": "user-123", "scope": "mcp:connect mcp:tools.read"},
+      "allowed": true,
+      "reason_code": "oauth.allowed"
+    },
+    {
+      "name": "automation-api-access",
+      "claims": {"sub": "client-agent-client", "scope": "mcp:connect mcp:tools.read"},
+      "allowed": true,
+      "reason_code": "oauth.allowed"
+    },
+    {
+      "name": "wrong-api-audience",
+      "claims": {"aud": "https://another-api.example.test", "scope": "mcp:connect mcp:tools.read"},
+      "allowed": false,
+      "reason_code": "oauth.invalid_token"
+    },
+    {
+      "name": "id-token-is-not-api-access",
+      "typ": "JWT",
+      "claims": {"aud": "agent-client", "nonce": "login-nonce", "groups": ["admins"]},
+      "allowed": false,
+      "reason_code": "oauth.invalid_token"
+    },
+    {
+      "name": "missing-connect-permission",
+      "claims": {"scope": "mcp:tools.read"},
+      "allowed": false,
+      "reason_code": "oauth.insufficient_scope"
+    },
+    {
+      "name": "missing-tools-permission",
+      "claims": {"scope": "mcp:connect"},
+      "allowed": false,
+      "reason_code": "oauth.scope_map_denied"
+    },
+    {
+      "name": "expired-access-token",
+      "expires_in": -3600,
+      "claims": {"scope": "mcp:connect mcp:tools.read"},
+      "allowed": false,
+      "reason_code": "oauth.invalid_token"
+    },
+    {
+      "name": "wrong-issuer",
+      "claims": {"iss": "https://other-id.example.test", "scope": "mcp:connect mcp:tools.read"},
+      "allowed": false,
+      "reason_code": "oauth.invalid_token"
+    }
+  ]
+}