Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,32 @@

# Changelog

## 0.37.2 (2026-11-17)

Fixes from the review of 0.37.1, and what a host needs to push a Direct Sign-In whose redirect
lands in another service. In both SDKs; additive API only.

- **Opening a sign-in link consumes nothing** (spec 4.2). `open_link` (`openLink`) took the
link's record and put it back; an opening paused between the two while `complete` consumed
the sign-in restored a link whose callbacks could no longer succeed. It now reads the record
with the state store's `get`, a new optional method of `AuthorizationStateStore` (a SHOULD:
`get(reference)` returns the record without consuming it, `None`/`undefined` when unknown or
expired). `take` stays the callback's alone. A store without `get` is still accepted and read
by `take` then `put`, which keeps the old race: add `get` to it. The SDKs' own in-memory
stores have it.
- **A link begun by 0.37.0 still opens after an upgrade.** 0.37.0 kept the callback state's
reference under the link's key; 0.37.1 rejected such a link and dropped it. The reader now
follows the reference to the pending sign-in, without consuming it; a store without `get`,
which takes the record to read it, gets it back with the sign-in's expiry, so the link opens
again until the sign-in completes.
*Mixed versions:* a 0.37.0 replica cannot read a link begun by 0.37.1 or later (it takes the
record and rejects it); when replicas share a state store, finish rolling every replica that
serves link pages to 0.37.2 before links are begun on the new version, or route link pages to
upgraded replicas.
- **`DirectSignInStart.state`**: the request's `state`, as a secret (never in `repr`), for a
host whose redirect URI is served by another service that keys the callback by it. With PAR
or a `link_page` the URL the browser opens does not carry it.

## 0.37.1 (2026-11-17)

Fixes from the review of 0.37.0, in both SDKs. No API change.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/concepts/contribution-points.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ other fails CI.
| `pap.signer` | `SIGNERS` | `Signers` | The agent's client assertions and delegations (keys stay in custody) | — (host contributes) | |
| `pap.tokenStore` | `TOKEN_STORES` | `TokenStores` | Refresh tokens behind opaque references | — (host contributes) | |
| `pap.pairwiseUserIdStore` | `PAIRWISE_USER_ID_STORES` | `PairwiseUserIdStores` | Stable pairwise user IDs by tenant, local user, and issuer | — (host contributes) | yes |
| `pap.authorizationStateStore` | `AUTHORIZATION_STATE_STORES` | `AuthorizationStateStores` | Expiring one-use sign-in state (put, take) | — (host contributes) | |
| `pap.authorizationStateStore` | `AUTHORIZATION_STATE_STORES` | `AuthorizationStateStores` | Expiring one-use sign-in state (put, take; get SHOULD, read without consuming, since 0.37.2) | — (host contributes) | |
| `pap.cache` | `CACHES` | `Caches` | Bounded cache of public metadata | `memory` | |
| `pap.browserHandoff` | `BROWSER_HANDOFFS` | `BrowserHandoffs` | Opens a sign-in page on a trusted surface | — (host contributes) | |
| `pap.browserJoin` | `BROWSER_JOINS` | `BrowserJoins` | The agent's own browser: loads the join form's one-time code and submits the form | — (host contributes) | |
Expand Down
9 changes: 9 additions & 0 deletions docs/docs/guides/direct-sign-in.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,15 @@ on their phone, goes to a page of your own: pass
`link_page="https://agent.example/sign-in/{link}"` (`linkPage`) and the browser
handoff gets that page; when it is opened, it calls `open_link(link)`
(`openLink`), which pushes the request then, and redirects to the URL it returns.
Opening a link reads its record without consuming it, through the state store's
`get`; give your store one (a store with only `put` and `take` is read by taking
and putting back, which a completing callback can race). A link may be opened
again until its sign-in completes; then it opens nothing.

With PAR or a link page, the URL the browser opens carries no `state`. When your
redirect URI is served by another service than the one that called `begin`, key
the callback there by `started.state` (`DirectSignInStart.state`, a secret), the
value the company sends back with the code.

A sign-in names no `resource`: it covers every service the company offers, those
it adds later too, and each token request names one (§4.5, see
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/protocol/conformance-report.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Compatibility and conformance report

# Compatibility and conformance report

SDK version **0.37.1**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (1.0 as published 2026-11-14); the suite also runs at 0.4 in every pairing. Each pairing runs every positive, negative and recovery fixture case over real TCP and TLS, the personal agent in one language and the reference company (Manzanita) in the other. A case is skipped, never passed, when a side lacks what it needs; the reason is listed below.
SDK version **0.37.2**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (1.0 as published 2026-11-14); the suite also runs at 0.4 in every pairing. Each pairing runs every positive, negative and recovery fixture case over real TCP and TLS, the personal agent in one language and the reference company (Manzanita) in the other. A case is skipped, never passed, when a side lacks what it needs; the reason is listed below.

## Pairings

Expand Down
3 changes: 2 additions & 1 deletion docs/docs/releases/compatibility.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Compatibility

# Compatibility

This page is versioned with the SDK: it describes **SDK 0.37.1**.
This page is versioned with the SDK: it describes **SDK 0.37.2**.

## The PAP version implemented

Expand Down Expand Up @@ -35,6 +35,7 @@ profile, never picked up from an unattended fetch.

| SDK (PyPI and npm) | PAP profile | Specification revision | Operations | Breaking changes |
| --- | --- | --- | --- | --- |
| `0.37.2` | `0.4` | 2026-11-10 | v3 | none: opening a sign-in link reads its record without consuming it (the state store's optional `get`), a link begun by 0.37.0 still opens after an upgrade, and the Direct Sign-In start names its `state` for hosts whose redirect lands elsewhere |
| `0.37.1` | `0.4` | 2026-11-10 | v3 | none: a bound refresh token keeps its sign-in at a Bearer-only MCP server, `open_link` leaves the callback state to `complete`, an empty SSE event name is a message, and `effectiveContext` keeps a `__proto__` field as a field |
| `0.37.0` | `0.4` | 2026-11-10 | v3 | [0.36 → 0.37](/releases/migration/#036--037): 1.0 as published (`8c02b42`): required conversation protocol descriptions (`agent_description`), Pushed Authorization Requests, `prompt=consent`, refresh tokens bound to their DPoP key, ports in `organization.domain`, one sign-in for every resource, and unknown values read safely |
| `0.36.1` | `0.4` | 2026-11-10 | v3 | none: a Session persisted without its version (before 0.36) restores at 0.4 in TypeScript too, as in Python |
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@datalayer/personal-agent-protocol",
"version": "0.37.1",
"version": "0.37.2",
"description": "TypeScript SDK for Personal Agent Protocol 0.4 (2026-11-10) and its Operations extension v3",
"repository": {
"type": "git",
Expand Down
121 changes: 120 additions & 1 deletion personal_agent_protocol/__tests__/test_published_10.py
Original file line number Diff line number Diff line change
Expand Up @@ -956,7 +956,8 @@ async def recording(reference: str) -> object:

monkeypatch.setattr(store, "take", recording)
await browser.open(await client.open_link(link))
assert taken and all(not reference.startswith("direct:") for reference in taken)
# Read with the store's `get`: an opening consumes nothing, the link's record included.
assert taken == []
# Opened twice, then completed: complete() alone consumes the state, once.
await client.open_link(link)
callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type]
Expand Down Expand Up @@ -995,3 +996,121 @@ async def company(_: httpx.Request) -> httpx.Response:
items = [item async for item in client.stream(f"{SHOP}/poppy", "cnv_1", session=session)]
reactor.stop()
assert [type(item).__name__ for item in items] == ["ConversationEvent"]


async def _pushed_link(world: World, browser: Any) -> tuple[DirectSignInClient, str, Any]:
await world.signed_out_session()
metadata = world.company.oauth_metadata
assert metadata is not None
client = DirectSignInClient(reactor=world.reactor, http_client=world.http)
start = await client.begin(
**_direct_arguments(
world,
pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint,
require_pushed_authorization_requests=True,
link_page="https://atlas.example/sign-in/{link}",
)
)
return client, browser.urls[-1].rsplit("/", 1)[1], start


@pytest.mark.asyncio
async def test_an_opening_paused_while_the_callback_completes_never_restores_the_link() -> None:
"""Copilot's review of 0.37.1: an opening paused between reading the link and writing it
back, while `complete` consumed the sign-in, restored a link whose callbacks could not
succeed. An opening reads only (`get`), so the completed sign-in's link stays gone."""
import asyncio

world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="required"))
client, link, _ = await _pushed_link(world, browser)
await browser.open(await client.open_link(link))
callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type]
store = first_contribution(world.reactor, AUTHORIZATION_STATE_STORES, "state store")
read, resume = asyncio.Event(), asyncio.Event()
get = store.get

async def pausing(reference: str) -> object:
value = await get(reference)
read.set()
await resume.wait()
return value

store.get = pausing # type: ignore[method-assign]
opening = asyncio.create_task(client.open_link(link))
await read.wait()
store.get = get # type: ignore[method-assign]
assert (await client.complete(callback)).token is not None
resume.set()
await opening # it read before the sign-in completed
with pytest.raises(AuthorizationError):
await client.open_link(link)


@pytest.mark.asyncio
async def test_a_link_begun_by_0_37_0_opens_after_an_upgrade_without_consuming_its_state() -> None:
"""0.37.0 kept the callback state's reference under the link's key: the reader follows it,
never consuming the state, so the sign-in still completes."""
from personal_agent_protocol.auth import _link_reference, _state_reference

world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="required"))
client, link, start = await _pushed_link(world, browser)
store = first_contribution(world.reactor, AUTHORIZATION_STATE_STORES, "state store")
reference = _state_reference(start.state.get_secret_value())
until = world.clock.now() + timedelta(minutes=5)
await store.put(_link_reference(link), reference, expires_at=until)
await browser.open(await client.open_link(link))
assert await store.get(reference) is not None # the state is still there
callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type]
assert (await client.complete(callback)).token is not None
with pytest.raises(AuthorizationError):
await client.open_link(link)


@pytest.mark.asyncio
async def test_a_store_without_get_is_read_by_taking_and_putting_back(
monkeypatch: pytest.MonkeyPatch,
) -> None:
world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="offered"))
client, link, _ = await _pushed_link(world, browser)
store = first_contribution(world.reactor, AUTHORIZATION_STATE_STORES, "state store")
# A store written before 0.37.2: `put` and `take` only.
monkeypatch.setattr(store, "get", None)
first = await client.open_link(link)
again = await client.open_link(link)
assert "request_uri=" in first.get_secret_value() and "request_uri=" in again.get_secret_value()


@pytest.mark.asyncio
async def test_the_start_names_the_state_the_callback_carries() -> None:
"""A host whose redirect lands in another service keys the callback by `state`, which a
pushed request's URL does not carry (PAR): the start names it."""
world, browser = _recording_world()
await world.signed_out_session()
client = DirectSignInClient(reactor=world.reactor, http_client=world.http)
start = await client.begin(**_direct_arguments(world))
assert start.state is not None
assert parse_qs(urlsplit(browser.urls[-1]).query)["state"] == [start.state.get_secret_value()]
assert start.state.get_secret_value() not in repr(start)


@pytest.mark.asyncio
async def test_a_0_37_0_link_in_a_store_without_get_opens_again_until_the_sign_in_completes(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Copilot's review of #20: a store without `get` took the 0.37.0 string record to read it,
and nothing put it back, so the link opened once only."""
from personal_agent_protocol.auth import _link_reference, _state_reference

world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="required"))
client, link, start = await _pushed_link(world, browser)
store = first_contribution(world.reactor, AUTHORIZATION_STATE_STORES, "state store")
reference = _state_reference(start.state.get_secret_value())
until = world.clock.now() + timedelta(minutes=5)
await store.put(_link_reference(link), reference, expires_at=until)
monkeypatch.setattr(store, "get", None)
await client.open_link(link)
await browser.open(await client.open_link(link)) # opens again
callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type]
assert (await client.complete(callback)).token is not None
with pytest.raises(AuthorizationError):
await client.open_link(link)
2 changes: 1 addition & 1 deletion personal_agent_protocol/__version__.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@

"""Personal Agent Protocol."""

__version__ = "0.37.1"
__version__ = "0.37.2"
42 changes: 37 additions & 5 deletions personal_agent_protocol/auth.py
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,10 @@ class DirectSignInStart(ProtocolModel):
#: Whether the authorization URL opens on a device other than the one the User is
#: using (§4.2): a cross-device flow, as Device Sign-In always is (§10.8).
cross_device: bool = False
#: The request's `state`, for a host whose redirect lands in another service than the
#: one that began (its callback keyed by it there): with PAR or a `link_page` the URL the
#: browser opens does not carry it. Never shown to the User or a model.
state: SecretStr | None = None


#: The longest a Direct Sign-In request lives when its link opens on another device: a
Expand All @@ -297,6 +301,22 @@ class _PendingDirectSignIn:
link: str | None = None


async def _peek(store: AuthorizationStateStore, reference: str) -> object | None:
"""A state record read without consuming it: the store's `get` when it has one (the
contract's SHOULD since 0.37.2). A store with only `put` and `take` is read by taking
and putting back, which a `complete` running between the two steps can race: such a
store SHOULD add `get`."""

get = getattr(store, "get", None)
if callable(get):
return await get(reference)
value = await store.take(reference)
expires_at = getattr(value, "expires_at", None)
if value is not None and isinstance(expires_at, datetime):
await store.put(reference, value, expires_at=expires_at)
return value


def _link_reference(link: str) -> str:
try:
encoded = link.encode("ascii")
Expand Down Expand Up @@ -473,6 +493,7 @@ async def begin(
expires_at=expires_at,
requested_scopes=request.scopes,
cross_device=cross_device,
state=request.state,
)

async def open_link(self, link: str) -> SecretStr:
Expand All @@ -489,16 +510,27 @@ async def open_link(self, link: str) -> SecretStr:
),
)
clock = cast(Clock, first_contribution(self.reactor, CLOCKS, "clock"))
# Only the link's own record is read (taken and put back): the callback state, which
# `complete` consumes once, is never touched, so an opening and a completing callback
# can interleave.
# Read, never consumed: only the callback `complete` receives takes state, so an
# opening and a completing callback can interleave, and a completed sign-in's link
# opens nothing more.
link_reference = _link_reference(link)
pending = await store.take(link_reference)
pending = await _peek(store, link_reference)
if isinstance(pending, str):
# A link begun by 0.37.0, whose record names the callback state's reference: that
# state is followed, still never consumed, so a link left unexpired across an
# upgrade opens as before.
legacy = pending
pending = await _peek(store, legacy) if legacy.startswith("direct:") else None
if isinstance(pending, _PendingDirectSignIn) and not callable(
getattr(store, "get", None)
):
# A store without `get` took the string record to read it: put back, with the
# sign-in's expiry, so the link opens again until the sign-in completes.
await store.put(link_reference, legacy, expires_at=pending.expires_at)
if not isinstance(pending, _PendingDirectSignIn) or clock.now() > pending.expires_at:
raise AuthorizationError(
"invalid_or_expired_state", "the sign-in link is unknown or has expired"
)
await store.put(link_reference, pending, expires_at=pending.expires_at)
return await self._authorization_url(pending)

async def _authorization_url(self, pending: _PendingDirectSignIn) -> SecretStr:
Expand Down
6 changes: 6 additions & 0 deletions personal_agent_protocol/cli_host.py
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,12 @@ def __init__(self, now: Callable[[], datetime]) -> None:
async def put(self, reference: str, value: object, *, expires_at: datetime) -> None:
self.values[reference] = (value, expires_at)

async def get(self, reference: str) -> object | None:
value, expires_at = self.values.get(reference, (None, None))
if expires_at is not None and self.now() > expires_at:
return None
return value

async def take(self, reference: str) -> object | None:
value, expires_at = self.values.pop(reference, (None, None))
if expires_at is not None and self.now() > expires_at:
Expand Down
2 changes: 1 addition & 1 deletion personal_agent_protocol/company/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ def build_company(
reactor.register_plugin(
PluginManifest(
name="personal-agent-protocol.company",
version="0.37.1",
version="0.37.2",
contribution_points=[
COMPANY_STORES.id,
COMPANY_ACCOUNTS.id,
Expand Down
11 changes: 9 additions & 2 deletions personal_agent_protocol/reactor.py
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,14 @@ async def get_or_create(

@runtime_checkable
class AuthorizationStateStore(Protocol):
"""Persist and atomically consume short-lived authorization state."""
"""Persist and atomically consume short-lived authorization state.

A store SHOULD also have `async def get(reference) -> object | None`, which reads a
record without consuming it (`None` when unknown or expired): `DirectSignInClient.open_link`
reads a sign-in link's record with it, so opening a link never races the `take` of a
completing callback. Without `get` the link is read by `take` then `put`. `get` is not
part of this runtime-checked Protocol, so stores written before 0.37.2 still qualify.
"""

async def put(self, reference: str, value: object, *, expires_at: datetime) -> None: ...

Expand Down Expand Up @@ -1081,7 +1088,7 @@ def build_pap_reactor(
platform.register_plugin(
PluginManifest(
name="personal-agent-protocol.core",
version="0.37.1",
version="0.37.2",
contribution_points=[
DISCOVERY_TRANSPORTS.id,
URL_SAFETY_POLICIES.id,
Expand Down
Loading
Loading