Skip to content

0.37.3: a company's services at URLs of their own (resource_servers) - #21

Merged
echarles merged 4 commits into
mainfrom
feat/company-resource-servers
Nov 18, 2026
Merged

echarles merged 4 commits into
mainfrom
feat/company-resource-servers

Conversation

@echarles

Copy link
Copy Markdown
Member

What

CompanyConfig.resource_servers (resourceServers), in both SDKs: a company names its services at URLs of their own that take its access tokens, such as an MCP server on another host than its issuer's.

  • The issuer lists each in protected_resources (spec 3.2) and issues a Bearer token for it when a token request names it as resource (4.5, 7; RFC 8707). Before, only the company's own https://{domain}/mcp could be asked for, and anything else was invalid_target.
  • CompanyService.access_token_for(token, resource) (accessTokenFor): the service verifies what it is sent. The default token and a token for another service are refused (4.5: a token issued for a resource is accepted only at that service).
  • resource_metadata_url(resource) (resourceMetadataUrl): where the service's RFC 9728 metadata is, for its challenges.

Additive. A company that names no resource server behaves exactly as before; the full Python and TypeScript suites pass, the conformance pairings included.

Docs and tests

  • docs/docs/guides/company.mdx, A service at a URL of its own; changelog; compatibility table.
  • test_resource_servers.py (14), resource-servers.test.mjs (5), one docs example case.

…— CompanyConfig.resource_servers (resourceServers): an MCP server on another host than the issuer's is listed in the issuer's protected_resources and gets Bearer tokens issued for it (RFC 8707), at the request that completes a sign-in or at refresh, where it was invalid_target; CompanyService.access_token_for (accessTokenFor) for such a service to verify a token issued for it, and only for it; resource_metadata_url (resourceMetadataUrl), where its RFC 9728 metadata is. In both SDKs, additive: a company that names none behaves as before. Docs: guides/company, A service at a URL of its own. Tests: test_resource_servers (14), resource-servers.test.mjs (5), a docs example case
Copilot AI balanced review requested due to automatic review settings November 18, 2026 09:40

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Resource URL validation allows entries that break company-wide discovery, while inconsistent trailing-slash handling makes some metadata endpoints undiscoverable.

4 open issues
What changed in this PR

This PR adds support for company services hosted at separate URLs in both SDKs, extending the existing issuer to issue and verify resource-specific Bearer tokens.

Changes:

  • Add resource-server configuration, issuer metadata entries, and token issuance support.
  • Expose resource-specific token verification and protected-resource metadata URL helpers.
  • Add tests and documentation, and update SDK versions to 0.37.3.
File Description
src/​reactor.ts Update core plugin version.
src/​company/​service.ts Implement TypeScript resource-server support and helpers.
src/​company/​index.ts Update company plugin version.
src/​__tests__/​resource-servers.test.mjs Test TypeScript configuration, issuance, and verification.
personal_agent_protocol/​reactor.py Update Python core plugin version.
personal_agent_protocol/​company/​service.py Implement Python resource-server support and helpers.
personal_agent_protocol/​company/​__init__.py Export metadata helper and update plugin version.
personal_agent_protocol/​__version__.py Set Python SDK version to 0.37.3.
personal_agent_protocol/​__tests__/​test_resource_servers.py Test Python configuration, issuance, and verification.
personal_agent_protocol/​__tests__/​test_docs_examples.py Validate the new guide example.
package.json Set npm package version to 0.37.3.
docs/​docs/​releases/​compatibility.mdx Add the release compatibility entry.
docs/​docs/​protocol/​conformance-report.mdx Update the documented SDK version.
docs/​docs/​guides/​company.mdx Document external resource services and verification.
CHANGELOG.md Describe the 0.37.3 APIs and behavior.

Review effort: Balanced

Comment thread src/company/service.ts Resolved
Comment thread src/company/service.ts Resolved
…ad with, and published where discovery reads (review of #21). Each URL passes the metadata parser's own HTTPS rule (_https_url, httpsUrl: a host, no user information) and names a well-formed host in small ASCII letters, a port allowed, an internationalized name as its A-labels, with no query or fragment; credentials, an empty or malformed host, a query, a fragment and http are refused when the company is configured, in both SDKs. resource_metadata_url (resourceMetadataUrl) is the helper discovery fetches the metadata at, so a trailing slash on the url cannot make a service undiscoverable. Tests: every accepted URL reads back through the metadata parser; publish URL equals discovery URL for /mcp, /mcp/, / and a nested path

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Python and TypeScript resource-server token lookups still accept tokens from policy-blocked agents, violating the requirement that blocked agents’ tokens stop working immediately.

2 open issues
1 previously missed issue

In code that hasn't changed since last review

Medium severity Reject URLs with out-of-range ports

personal_agent_protocol/​company/​service.py:402

Numeric ports above 65535, such as https://mcp.shop.example:65536/mcp, still pass validation because urlsplit() checks the range only when .port is accessed. Publishing such a URL in protected_resources makes TypeScript clients reject the issuer metadata, preventing company discovery. Access parts.port here to reject invalid ports during configuration, and add an out-of-range port to the rejection tests.

4 resolved since last review

Review effort: Balanced

if resource not in self.config.resource_servers:
raise ValueError(f"{resource} is not one of this company's resource_servers")
issued = await self._access_token(token)
if issued is None or issued.resource != resource or not self._offers(issued.scopes):

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 434cb0d: access_token_for asks the client policy when the token is presented, both allows and allows_resource for that service, and answers nothing for a blocked agent. Test: test_a_blocked_agents_token_stops_working_there_at_once. The out-of-range port from the same review is fixed here too (parts.port is read at configuration; 65536 and 99999 are in the refused cases).

Comment thread src/company/service.ts
throw new RangeError(`${resource} is not one of this company's resourceServers`);
}
const issued = await this.#accessToken(token);
if (issued === undefined || issued.resource !== resource || !this.#offers(issued.scopes)) return undefined;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 434cb0d: accessTokenFor asks allows and allowsResource when the token is presented. Test: "a blocked agent's token stops working there at once".

…d, and a port that is no port is refused (second review of #21). access_token_for (accessTokenFor) answers nothing for an agent the client policy blocks, or for a service it has since left out for that agent, so a blocked agent's unexpired token stops working at a resource server at once, as at the company's own services; a port above 65535 is refused when the company is configured, in Python as in TypeScript. Tests: a blocked agent's token stops working there at once (both SDKs), out-of-range ports
…m (Kirkaldy, independent testing of agent infrastructure), with the link to his conformance kit — and says a re-run on the current release is planned and will be published; its facts are unchanged
@echarles
echarles merged commit 18dfa22 into main Nov 18, 2026
22 checks passed

This branch was successfully deployed

2 active deployments
npm — 8ec2ac8c Deployed Nov 18, 2026 by echarles via npm #49
pypi — 8ec2ac8c Deployed Nov 18, 2026 by echarles via pypi #49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants