Trusted-endpoint patterns + API key onboarding docs + drop cluster_b leftover#19
Merged
Merged
Conversation
… registered URLs
A registered URL may now contain FastAPI/Express-style path placeholders so a
single entry covers a family of concrete URLs:
{name} - matches exactly one path segment (no '/').
e.g. https://api.example.com/customers/{id} matches
/customers/42 but NOT /customers/42/orders.
{name:path} - matches any subtree, including '/' separators.
e.g. https://api.example.com/customers/{rest:path} matches
both /customers/42 and /customers/42/orders.
Closes #14.
Why: customer-support-sdk-demo had to enumerate ~70 concrete URLs at startup
for templated routes (/customers/{id}). Runtime-generated ids (e.g. POST
/tickets returning a fresh id) couldn't be trusted until manually registered.
A single placeholder entry replaces the enumeration.
Implementation:
- Plain URLs without '{' keep exact-match semantics. No schema change. No
migration needed for existing rows. Existing exact-match tests unchanged.
- Pattern matching is auto-detected from URL content. Pattern compilation is
LRU-cached so repeated lookups don't recompile the regex.
- is_trusted_endpoint uses a two-phase lookup: exact match first (single
indexed query, fast path), then a pattern-only scan (LIKE '%{%' filter)
for rows containing placeholders. Plain registries see no perf regression.
- The snapshot tamper-check inside check_claim_endpoints_are_trusted honors
the same syntax — a payload built against a pattern entry verifies cleanly
on the receiver side.
Tests: 12 new (94 total). Ruff clean.
…G_ID New 'Getting PROVABLY_API_KEY and PROVABLY_ORG_ID' subsection under Configuration: 1. Sign up at app.provably.ai 2. Create an organisation (org id shown in the URL) 3. Left-side menu → Integrations → create one (generated key) Plus a pointer to provably.ai/docs for full product documentation. Closes the gap surfaced while users were trying to find where these values come from — the env-var table told them they were required but not where to source them.
…h-demo leftover) `default_cluster_b_url()` was extracted verbatim from the langgraph-demo monorepo (per CHANGELOG: 'Initial extraction from the langraph-demo monorepo'). Two problems: 1. The localhost:8082 default presumes a specific deployment shape (the original two-cluster demo); it is meaningless to a fresh SDK user. 2. 'cluster B' is internal terminology a user reading the SDK has no way to understand without context. Configuration of where YOUR receiver lives belongs in your application, not the SDK. `post_handoff` already takes the URL as a positional arg — drop the convenience helper, drop the env var, rename the arg from `cluster_b_url` to `receiver_url` for clarity. Breaking for callers that import `default_cluster_b_url` or pass `cluster_b_url=...` as a keyword arg. CHANGELOG entry added.
This was referenced May 6, 2026
Closed
SimoneBottoni
pushed a commit
that referenced
this pull request
May 11, 2026
…rl_allowlist Parity with the trust gate from PR #19. Reuses the `_matches_registered` helper from `trusted_endpoints.py` instead of duplicating regex logic, so both code paths share one matcher. Implementation: - `set_intercept_url_allowlist` keeps storing entries as a normalized set (no schema change). Pattern detection is by URL content; auto-applied. - New private `_url_in_allowlist(nurl)` does exact set membership first (O(1)), then iterates only the pattern entries (those containing `{`) on a miss. Plain-URL allowlists pay no per-request iteration cost. - The two callsites in `_record_and_maybe_tamper` (recording gate + tamper-hook gate) collapse into one `in_allowlist` boolean to avoid computing the membership twice. Closes #20. 5 new unit tests covering: pattern matches concrete URL, single-segment placeholder rejects extra segments, `{rest:path}` covers subtree, mixed exact+pattern allowlist retains per-entry semantics, plain URLs still exact-only (no accidental prefix match). 121/121 tests pass (was 116, +5).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linear-history rebase of #17 (the original branch had a merge commit; the repo only allows rebase merges). Same content, approved, just replayed cleanly on top of main. Closes #14, supersedes #17.
1.
trusted_endpoints:{id}and{path:path}placeholdersRegistered URLs may now contain FastAPI/Express-style path placeholders:
{name}/customers/{id}matches/customers/42but not/customers/42/orders{name:path}/customers/{rest:path}matches both abovePlain URLs without
{keep exact-match semantics — zero migration.is_trusted_endpointexact match first (fast path); only scans pattern entries on a miss. The snapshot tamper-check honors the same syntax.12 new tests.
2. README: API key onboarding
Short "Getting
PROVABLY_API_KEYandPROVABLY_ORG_ID" subsection — sign up at app.provably.ai, create org, Integrations menu. Plus a link to provably.ai/docs.3. Drop
default_cluster_b_url()+CLUSTER_B_URLBREAKING for callers importing
default_cluster_b_urlor passingcluster_b_url=...as a keyword arg. Helper + env var were leftovers from the langgraph-demo monorepo with alocalhost:8082default. Configuration of where YOUR verifier lives belongs in your application.post_handoff(receiver_url, payload)(positional arg renamed) takes the URL directly.Verified no usages in
verifiable-state-demoorcustomer-support-sdk-demo.Verification