snulbug 0.2.1__tar.gz → 0.2.3__tar.gz

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

@@ -6,6 +6,32 @@ 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
+a separate permission or approval system.
+
+- Added renewable automation invites using the existing backing lease, with bounded consumer renewal/restart recovery, rotating access tokens, identity bindings, persistent usage budgets, and console/CLI setup snippets.
+- Serialized lease mutations across local workers so renewal, revocation, cleanup, and concurrent call consumption cannot overwrite each other's state.
+- Added renewal visibility and refresh-stable invite forms in the web console, secret-safe renewal audit events, and share closeout that revokes invites as well as the session lease.
+
+Automation renewal is opt-in. Access leases remain short-lived; the owner's
+renewal authorization has a separate hard expiry. Clients must adopt refreshed
+lease headers, and revocation or exhausted budgets prevent recovery. No change
+to the default MCP protocol version or the experimental profile's limitations.
+
 ## [0.2.1] - 2026-10-15
 
 Expose web applications and APIs alongside MCP through one gateway and ngrok tunnel.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: snulbug
-Version: 0.2.1
+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
@@ -63,6 +63,8 @@ It gives you a tight loop for agent-tool safety:
 - review MCP-native capability requests and approve them into normal task leases
 - use task-scoped leases for temporary tool/path grants, optionally bound to
   OAuth subject, tenant, client, group, issuer, or auth profile
+- give always-on bots [renewable automation invites](docs/mcp-share.md#renewable-automation-invites)
+  with short-lived leases, consumer renewal, and restart recovery
 - turn OAuth identity into MCP-specific tool permissions
 - pin facade upstream identity with signed manifests
 
@@ -466,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.1 → snulbug-0.2.3}/README.md

@@ -20,6 +20,8 @@ It gives you a tight loop for agent-tool safety:
 - review MCP-native capability requests and approve them into normal task leases
 - use task-scoped leases for temporary tool/path grants, optionally bound to
   OAuth subject, tenant, client, group, issuer, or auth profile
+- give always-on bots [renewable automation invites](docs/mcp-share.md#renewable-automation-invites)
+  with short-lived leases, consumer renewal, and restart recovery
 - turn OAuth identity into MCP-specific tool permissions
 - pin facade upstream identity with signed manifests
 
@@ -423,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.1 → snulbug-0.2.3}/SECURITY.md

@@ -59,6 +59,16 @@ Limits:
   schemas pass through unless your Lua policy blocks them separately.
 - Leases are bearer-style capabilities. Store `leases.json` locally, rotate or
   revoke leases after sharing, and prefer short TTLs for public tunnel use.
+- Renewable automation invites add a separate, reusable renewal credential with
+  an owner-set hard deadline. Treat it as a long-lived bot secret: theft together
+  with the required gateway authentication permits recovery within the approved
+  capability and call-budget bounds until revocation or expiry. It does not
+  grant console access. Renewal retains the existing lease's usage count and
+  identity bindings; revocation disables recovery. Access-token rotation has a
+  bounded overlap of at most 30 seconds. Lease operations are serialized on the
+  local lease file; independent gateway hosts must not treat copied JSON stores
+  as a shared revocation authority. The owner console's invite secret store
+  contains plaintext setup credentials and must remain private.
 
 ### Malicious or compromised MCP server
 

{snulbug-0.2.1 → 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.1 → 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.1": {
-      "version": "0.2.1",
+    "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.1 → 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.1 → snulbug-0.2.3}/docs/mcp-proxy.md

@@ -920,6 +920,10 @@ snulbug mcp evidence impact traces/session.jsonl --lease leases.json --report-ou
 In facade mode, leases use the client-facing tool name, such as
 `files.read_file` or `git.status`.
 
+For unattended consumers, [renewable automation invites](mcp-share.md#renewable-automation-invites)
+extend the same task lease with bounded consumer renewal and restart recovery.
+They retain the existing Lua, OAuth identity, revocation, and call-budget checks.
+
 ## Tool Schema Firewall
 
 When `schema_validation = true`, snulbug learns each MCP tool's `inputSchema`

{snulbug-0.2.1 → snulbug-0.2.3}/docs/mcp-share.md

@@ -123,6 +123,94 @@ traffic is observed. The table records evidence source, confidence, risk level,
 categories, and signals such as command-capable arguments, network/path
 arguments, destructive annotations, and open argument schemas.
 
+## Renewable Automation Invites
+
+For an always-on bot, enable **Renewable automation invite** in the console's
+Invites tab, or extend the normal invite command:
+
+```bash
+snulbug mcp share invite create .snulbug/shares/my-share \
+  --recipient nightly-bot --task "Inspect project" \
+  --capability project_readonly \
+  --renewable --ttl 30m --renewal-ttl 7d
+```
+
+`--ttl` controls the short-lived access lease. `--renewal-ttl` is the owner's
+hard authorization deadline, measured from invite creation, not each renewal.
+The backing lease keeps its ID, capabilities, identity bindings, usage count,
+and total `--max-calls` budget. Renewal does not approve policy changes or
+replenish an exhausted budget. Use the existing Lua rate limits for recurring
+request limits; this is not a new daily quota system.
+
+The setup packet includes a renewal credential, a curl command, and a Python
+integration example. Store the renewal credential as a bot secret, separately
+from the short-lived `x-snulbug-lease` token. It is reusable until its deadline
+or revocation, is not an OAuth refresh token, and cannot administer the console
+or create other invites. It is shown only through the existing owner CLI or
+secret-gated console. Protect the share directory and its `invite-secrets.json`.
+
+Consumers use ordinary HTTPS against the **same MCP URL**, so ngrok and other
+generated tunnel routes need no additional public endpoint:
+
+```bash
+export SNULBUG_MCP_URL="https://your-tunnel.example/mcp"
+export SNULBUG_INVITE_ID="invite_..."
+export SNULBUG_RENEWAL_TOKEN="sbr_..."
+# Set SNULBUG_BEARER_TOKEN to the bearer token from the invite packet.
+curl --fail-with-body -sS "$SNULBUG_MCP_URL" \
+  -H "Authorization: Bearer ${SNULBUG_BEARER_TOKEN}" \
+  -H "x-snulbug-renewal: ${SNULBUG_RENEWAL_TOKEN}" \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d "{\"jsonrpc\":\"2.0\",\"id\":\"renew\",\"method\":\"snulbug/lease/renew\",\"params\":{\"invite_id\":\"${SNULBUG_INVITE_ID}\"}}"
+```
+
+`snulbug/lease/renew` is a snulbug JSON-RPC extension, not a standard MCP method
+or an upstream tool. Its only parameter is `invite_id`; the consumer cannot
+choose a longer TTL, larger budget, or different capabilities. The gateway
+terminates the request without forwarding the renewal credential upstream.
+Errors use `error.data.reason_code`, even when the HTTP status is 200.
+
+On success, `result.headers` contains the current lease header;
+`result.lease.expires_at` and `result.lease.renewal.renew_after` tell the bot
+when to refresh its MCP client's headers. Call again at `renew_after`, with
+jitter and backoff for network failures. Retries inside the same lease window
+return the same access token. A renewal rotates it with at most 30 seconds of
+overlap for in-flight requests, bounded by the old token's original expiry.
+After a process restart or an expired access lease, the **same operation**
+recovers access while the owner authorization remains valid. No old lease token
+or installed snulbug client is required. Fixed-header clients need a refresh
+integration; a static client configuration does not renew itself.
+
+OAuth shares still require a valid access token obtained from the configured
+identity provider. Bind automation invites using `--allow-issuer` plus
+`--allow-subject` or `--allow-client-id`; optionally add `--allow-tenant`.
+Use that access token as the renewal request's `Authorization` header and the
+separate invite renewal credential as `x-snulbug-renewal`. Required OAuth scopes,
+DPoP requirements, and identity bindings still apply. Tool scope maps, claim
+policies, and Lua continue to govern every ordinary MCP tool call.
+For DPoP-required shares, the consumer must also sign and attach a fresh proof
+for each renewal request using its existing OAuth/DPoP client integration; the
+plain curl/Python examples do not mint proofs or OAuth access tokens.
+
+Revoking the invite or backing lease disables renewal and restart recovery.
+Closing the share with its default revocation option revokes its invites too.
+Even `invite revoke --keep-lease` revokes renewal authority; it leaves only the
+already-issued access lease usable until expiry. Removed capability labels,
+exhausted budgets, and expired renewal authorizations fail closed. Create a new
+invite for a new approval; operator reactivation cannot reset a renewable lease.
+Cleanup retains expired access leases while their renewal authorization is
+active. The console shows authorization expiry, access expiry, next renewal,
+and last renewal/count, and keeps setup snippets synchronized with token rotation.
+Renewal decisions go to the existing audit/event sinks, not the Lua replay log:
+renewing a credential is a control operation, not a simulated policy decision.
+
+Renewal and lease consumption use the existing JSON lease store with file locks
+and atomic replacement, including across local worker processes. Persist that
+file and the share directory across gateway restarts. This does not introduce
+a distributed lease database; separate hosts need a shared authority rather
+than independent copies of `leases.json`.
+
 ## Generated files
 
 By default, the command writes under `.snulbug/shares/share-*` and creates:

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

@@ -3,7 +3,8 @@
 1. Finalize `CHANGELOG.md`, with a dated release section and upgrade notes. Keep
    protocol preview limitations distinct from package release readiness.
 2. Bump `version` in `pyproject.toml` and `snulbug/__init__.py`, update the
-   devcontainer feature manifest and its docs/example references, and run `uv lock`.
+   devcontainer feature manifest and its docs/example references (including
+   `examples/codespace_local_gateway/.devcontainer/devcontainer.json`), and run `uv lock`.
 3. Run verification:
 
 ```bash
@@ -48,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.1 --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
@@ -56,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.1` 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.1 → 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.1": {
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.3": {
       "install_source": "github",
       "github_ref": "main",
       "mode": "member-agent",

{snulbug-0.2.1 → 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.1": {
+    "ghcr.io/nahuaque/snulbug/features/snulbug:0.2.3": {
       "install_source": "github",
       "github_ref": "main",
       "mode": "member-agent",

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

@@ -1,6 +1,6 @@
 {
   "id": "snulbug",
-  "version": "0.2.1",
+  "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.1 → snulbug-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "snulbug"
-version = "0.2.1"
+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.1 → 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.1"
+__version__ = "0.2.3"
 
 from .auth_providers import (
     AuthProvider,
@@ -206,6 +206,7 @@ from .leases import (
     create_lease,
     list_leases,
     reactivate_lease,
+    renew_lease,
     revoke_lease,
 )
 from .manifests import load_manifest, manifest_digest, sign_upstream_manifest, verify_upstream_manifest, write_manifest
@@ -746,6 +747,7 @@ __all__ = [
     "record_audit_event",
     "record_policy_request",
     "reactivate_lease",
+    "renew_lease",
     "reconcile_fabric_controller",
     "reconcile_policy_activation",
     "register_fabric_member",