@datalayer/personal-agent-protocol 0.3.0 → 0.3.2

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Datalayer
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,22 +1,303 @@
-# @datalayer/personal-agent-protocol
+<!--
+  ~ Copyright (c) 2025-2026 Datalayer, Inc.
+  ~
+  ~ BSD 3-Clause License
+-->
 
-TypeScript SDK for Personal Agent Protocol draft 0.1.
+[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai)
+
+# 🤖 🌸 Personal Agent Protocol
+
+![Personal Agent Protocol demo](https://images.datalayer.io/products/personal-agent-protocol/pap-demo.gif)
+
+Python and TypeScript SDKs for the
+[Personal Agent Protocol](https://personalagentprotocol.org), currently
+targeting [draft 0.1](https://personalagentprotocol.org/docs/spec).
+
+PAP lets a personal agent discover and talk to a company's agent on behalf of
+a person. The company remains responsible for its identity, authorization,
+data, and actions; the personal agent does not need the person's company
+password or a copy of their account data.
+
+## Understand PAP in one minute
+
+A typical interaction has five parts:
+
+1. **Discover** — the personal agent reads the company's public
+   `/.well-known/poppy.json` document.
+1. **Start a Session** — the two agents establish a pairwise, initially
+   signed-out relationship.
+1. **Converse** — the personal agent can ask questions without disclosing the
+   person's company identity.
+1. **Sign in when required** — the company opens its own authorization page.
+   Credentials remain between the person and the company.
+1. **Continue safely** — the same conversation resumes with proof-bound access
+   and the scopes the person approved.
+
+```mermaid
+sequenceDiagram
+    actor Person
+    participant PA as Personal agent
+    participant Company as Company agent
+    participant Auth as Company authorization server
+
+    PA->>Company: Discover /.well-known/poppy.json
+    Company-->>PA: Agent, Session, and authorization endpoints
+    PA->>Auth: Start a signed-out Session
+    Auth-->>PA: DPoP-bound Session Token
+    PA->>Company: Start a conversation
+    Company-->>PA: Sign-in required for account data
+    PA-->>Person: Open the company's sign-in page
+    Person->>Auth: Sign in and approve scopes
+    Auth-->>PA: Signed-in Session
+    PA->>Company: Continue the same conversation
+    Company-->>PA: Account-aware response
+```
+
+The SDKs implement these protocol and security mechanics. They do not decide
+what an agent should say, which model it should use, or whether a proposed
+action is appropriate for a person.
+
+## Install and discover a company
+
+### Python
+
+```bash
+python -m pip install personal-agent-protocol
+```
+
+```python
+import asyncio
+
+from personal_agent_protocol import DiscoveryClient
+
+
+async def main() -> None:
+    async with DiscoveryClient() as client:
+        company = await client.discover("example.com")
+        print(company.document.organization.name)
+        print(company.document.agent.protocols)
+
+
+asyncio.run(main())
+```
+
+### TypeScript
+
+```bash
+npm install @datalayer/personal-agent-protocol
+```
+
+```typescript
+import { discoverCompany } from '@datalayer/personal-agent-protocol';
+
+const company = await discoverCompany('example.com');
+console.log(company.document.organization.name);
+console.log(company.document.agent.protocols);
+```
+
+Discovery is deliberately a small first example. Production Session,
+sign-in, and conversation flows also require host-owned signing keys, DPoP
+proof generation, token storage, and browser handoff. Those capabilities are
+provided through Reactor rather than hidden global state.
+
+## Reactor is the extension foundation
+
+Both SDKs are built on
+[Datalayer Reactor](https://github.com/datalayer/reactor), a typed plugin and
+contribution system. An application assembles a PAP host from explicit
+contributions for:
+
+- discovery transport and URL-safety policy;
+- protocol profiles and extension handlers;
+- clocks and cryptographic randomness;
+- signing, protected keys, and DPoP proofs;
+- pairwise identity, token storage, and caching;
+- browser handoff and authorization-state storage;
+- CLI commands supplied by PAP or third-party extensions.
+
+This architecture keeps the protocol core portable while allowing a desktop
+application, browser application, server, or test harness to provide the
+security and platform behavior appropriate to its environment. Missing or
+ambiguous security contributions fail closed.
+
+Python accepts a host-assembled Reactor `PluginPlatform`:
+
+```python
+from reactor import PluginManifest
+
+from personal_agent_protocol import DiscoveryClient, build_pap_reactor
+
+
+async def discover_with_host() -> None:
+    platform, owned_http = build_pap_reactor(
+        plugins=[
+            (PluginManifest(name="my-security", version="1"), my_security_plugin)
+        ]
+    )
+    try:
+        async with DiscoveryClient(reactor=platform) as client:
+            company = await client.discover("example.com")
+            print(company.document.organization.name)
+    finally:
+        platform.stop()
+        if owned_http is not None:
+            await owned_http.aclose()
+```
+
+TypeScript can build a host or receive an existing `ReactorPlatformView`:
+
+```typescript
+import {
+  buildPapReactor,
+  discoverCompany,
+} from '@datalayer/personal-agent-protocol';
+
+const reactor = buildPapReactor({}, [mySecurityPlugin]);
+const company = await discoverCompany('example.com', { reactor });
+```
+
+See the [Reactor repository](https://github.com/datalayer/reactor) for the
+plugin model and contribution lifecycle.
+
+## What is implemented
+
+Python and TypeScript share fixtures and cover the same principal protocol
+surface:
+
+| Area            | Current support                                                                                                                   |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Models          | Forward-compatible discovery, OAuth metadata, client metadata, messages, events, and Operations v1 models                         |
+| Discovery       | `poppy.json`, company-domain and issuer validation, `poppy_domains`, bounded responses, and redirect controls                     |
+| Sessions        | Pairwise user IDs, PAP 4.2 assertions, signed-out start and renewal, redacted tokens, and DPoP nonce retry                        |
+| Cryptography    | ES256/RS256 JOSE, RFC 9449 DPoP creation and verification, freshness, token hash, nonce, and replay checks                        |
+| Direct Sign-In  | State, S256 PKCE, callback validation, browser handoff, and one-use token exchange orchestration                                  |
+| Browser Session | Assertion creation, controlled form POST, replay-safe verification, and company-domain return validation                          |
+| Transport       | Host-owned authorization headers, fresh redirect-bound proofs, one nonce retry, and cross-origin credential isolation             |
+| Conversations   | Start and continue, random user-global message IDs, ordered long polling, cursor recovery, duplicate suppression, and safe errors |
+| Extensibility   | Reactor contribution points for platform, security, protocol, storage, and CLI behavior                                           |
+| CLI             | Non-secret profiles, company verification, extension diagnostics, and versioned JSON output                                       |
+
+Python additionally provides a SQLite pairwise-identity reference provider.
+The portable TypeScript entry rejects obvious local and private literal
+addresses. Its explicit server entry adds `NodeUrlSafetyPolicy`, `JoseSigner`,
+and DPoP verification with A/AAAA resolution checks:
 
 ```typescript
-import { discoverCompany } from "@datalayer/personal-agent-protocol";
-
-const company = await discoverCompany("example.com");
-```
-
-The current release provides forward-compatible discovery, OAuth, client
-metadata, conversation-event, and Operations v1 models; strict
-duplicate-member rejection; local Direct Sign-In primitives; signed-out
-session start and renewal; and safe company discovery built on Datalayer
-Reactor. It also provides ES256/RS256 JOSE signing and DPoP proof creation and
-verification through the maintained `jose` package. Use
-`buildPapReactor(options, plugins)` to install typed transport, URL-policy,
-protocol-profile, clock, randomness, signer, DPoP proof, protected-key,
-token-store, cache, browser-handoff, and extension-handler contributions, or
-pass an existing Reactor host to `discoverCompany`. Security-dependent
-services have no fallback and fail closed when missing or ambiguous. See the
-repository README for current limits and security guidance.
+import {
+  JoseSigner,
+  NodeUrlSafetyPolicy,
+} from '@datalayer/personal-agent-protocol/server';
+```
+
+Duplicate JSON members are rejected at Python and TypeScript trust boundaries.
+
+## What is not implemented yet
+
+The following work remains before the SDKs cover the complete planned PAP
+surface:
+
+- managed key custody and durable replay storage;
+- Account Token exchange;
+- resource-bound MCP Bearer transport;
+- device and mediated sign-in;
+- conversation SSE streaming, handoff, and explicit close requests;
+- the Operations client and server;
+- transport-level address pinning to close the DNS-rebinding interval.
+
+Models for Operations v1 exist, but a complete Operations workflow does not.
+Applications should not infer client support from model availability alone.
+
+## Security boundary
+
+PAP credentials belong to the host, not to an agent model or tool call.
+
+- Session Tokens, Account Tokens, proofs, nonces, authorization codes, and
+  pairwise identifiers must not enter prompts or model-visible tool results.
+- Direct Sign-In requires host-provided state storage, browser handoff,
+  signing, and DPoP contributions.
+- Session requests fail closed until suitable signer and DPoP providers are
+  installed.
+- Redirects receive fresh, target-bound proofs; caller-supplied
+  `Authorization` and `DPoP` headers are rejected.
+- CLI profiles store configuration only—never tokens or private keys.
+
+The guides explain these boundaries at each flow rather than treating them as
+application conventions.
+
+## Command line
+
+The Python distribution installs an extensible `pap` command. Its command
+groups use Reactor's `datalayer.reactor.cli` entry-point contract.
+
+```bash
+pap config set domain example.com --profile work
+pap config show --profile work --json
+pap company verify --profile work --json
+pap extensions list --profile work
+```
+
+See the [CLI guide](https://personalagentprotocol.org/docs/guides/cli) for
+configuration precedence, security boundaries, machine-readable output, and
+third-party extensions.
+
+## Examples and first consumer
+
+The [`examples/pydantic-ai`](./examples/pydantic-ai/) directory contains small,
+focused Python examples. Each example teaches one feature—discovery, identity,
+Sessions, Direct Sign-In, Browser Session, cryptography, conversations, or
+proof-bound transport—without giving protocol secrets to the model.
+
+[Datalayer Agent Runtimes](https://github.com/datalayer/agent-runtimes) is the
+first consumer of these SDKs. Its Personal Agent Protocol gallery turns the
+same features into interactive Reactor/Loop applications, including a guided
+person-to-company journey rendered with the runtime's real message UI. The
+gallery's local company simulators are deterministic and clearly identified;
+the PAP clients, transports, validation, and parsed exchanges are real.
+
+Each implemented feature should have all three learning layers:
+
+1. a focused SDK example in this repository;
+1. a Docusaurus guide with an explanation and Mermaid sequence diagram;
+1. an interactive Agent Runtimes example when a UI materially clarifies the
+   flow.
+
+## Develop the SDKs
+
+Clone the repository, then install the dependencies for the SDK you are
+changing.
+
+### Python
+
+```bash
+python -m pip install -e '.[test,lint,typing,examples]'
+python -m pytest personal_agent_protocol/__tests__
+```
+
+### TypeScript
+
+The TypeScript package is at the repository root. Sources and tests live under
+`src/`; published JavaScript and declarations are emitted to `lib/`.
+
+```bash
+npm install
+npm test
+```
+
+The shared fixtures are in `fixtures/`. Documentation is a Docusaurus site in
+`docs/`.
+
+## Learn more
+
+- [Documentation](https://personalagentprotocol.org/docs)
+- [Overview](https://personalagentprotocol.org/docs/overview)
+- [Specification](https://personalagentprotocol.org/docs/spec)
+- [Implementation guides](https://personalagentprotocol.org/docs/guides)
+- [Extensions](https://personalagentprotocol.org/docs/extensions)
+- [Open topics](https://personalagentprotocol.org/docs/open-topics)
+- [Datalayer Reactor](https://github.com/datalayer/reactor)
+- [Datalayer Agent Runtimes](https://github.com/datalayer/agent-runtimes)
+
+## License
+
+BSD 3-Clause. See [`LICENSE`](./LICENSE).

package/lib/auth.d.ts

@@ -1,4 +1,6 @@
-import { SecretValue, type RandomBytes } from "./sessions.js";
+import type { ReactorPlatformView } from "@datalayer/reactor";
+import { SecretValue } from "./secret.js";
+import { type RandomBytes, type SessionToken } from "./sessions.js";
 export interface DirectSignInOptions {
     readonly authorizationEndpoint: string;
     readonly issuer: string;
@@ -41,4 +43,36 @@ export declare class AuthorizationCodeGrant {
     toForm(): URLSearchParams;
     toJSON(): Record<string, unknown>;
 }
+export interface DirectSignInStart {
+    readonly expiresAt: Date;
+    readonly requestedScopes: readonly string[];
+}
+export interface DirectSignInResult {
+    readonly token: SessionToken;
+    readonly grantedScopes: readonly string[];
+    readonly missingScopes: readonly string[];
+}
+export interface DirectSignInBeginOptions extends DirectSignInOptions {
+    readonly tokenEndpoint: string;
+    readonly tenantId: string;
+    readonly pairwiseUserId: string;
+    readonly sessionId: string;
+    readonly lifetimeSeconds?: number;
+}
+export interface DirectSignInCompleteOptions {
+    readonly callbackUrl: string;
+    readonly signal?: AbortSignal;
+}
+export interface DirectSignInClientOptions {
+    readonly reactor: ReactorPlatformView;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly maxResponseBytes?: number;
+}
+/** Orchestrate one-use browser authorization and proof-bound code exchange. */
+export declare class DirectSignInClient {
+    #private;
+    constructor(options: DirectSignInClientOptions);
+    begin(options: DirectSignInBeginOptions): Promise<DirectSignInStart>;
+    complete(options: DirectSignInCompleteOptions): Promise<DirectSignInResult>;
+}
 //# sourceMappingURL=auth.d.ts.map

package/lib/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AA6DpF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;CACpC;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CA6B9B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAWD,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,mBAAmB,EAC5B,WAAW,EAAE,MAAM,GAClB,oBAAoB,CAuCtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,qBAAa,sBAAsB;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;gBAE1B,OAAO,EAAE,6BAA6B;IAYlD,MAAM,IAAI,eAAe;IAazB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYlC"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/lib/auth.js

@@ -1,5 +1,8 @@
 import { AuthorizationError } from "./errors.js";
-import { JWT_CLIENT_ASSERTION, SecretValue } from "./sessions.js";
+import { parseJsonStrict } from "./json.js";
+import { SecretValue } from "./secret.js";
+import { JWT_CLIENT_ASSERTION, parseSessionToken, } from "./sessions.js";
+import { AuthorizationStateStores, BrowserHandoffs, Clocks, DpopProofProviders, RandomSources, Signers, firstContribution, } from "./reactor.js";
 function defaultRandomBytes(length) {
     if (!globalThis.crypto) {
         throw new AuthorizationError("crypto_unavailable", "Web Crypto is required");
@@ -56,7 +59,11 @@ export async function buildDirectSignInRequest(options) {
     const randomBytes = options.randomBytes ?? defaultRandomBytes;
     const state = base64Url(entropy(16, randomBytes));
     const verifier = base64Url(entropy(32, randomBytes));
-    const challenge = base64Url(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+    const cryptoApi = globalThis.crypto;
+    if (!cryptoApi) {
+        throw new AuthorizationError("crypto_unavailable", "Web Crypto is required");
+    }
+    const challenge = base64Url(new Uint8Array(await cryptoApi.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
     const endpoint = httpsUrl(options.authorizationEndpoint, "authorizationEndpoint");
     const scopes = validScopes(options.scopes);
     const clientId = httpsUrl(options.clientId, "clientId").toString();
@@ -165,4 +172,225 @@ export class AuthorizationCodeGrant {
         };
     }
 }
+async function stateReference(state) {
+    const bytes = new TextEncoder().encode(state);
+    if ([...bytes].some((byte) => byte > 0x7f)) {
+        throw new AuthorizationError("invalid_callback", "Authorization state is invalid");
+    }
+    const cryptoApi = globalThis.crypto;
+    if (!cryptoApi) {
+        throw new AuthorizationError("crypto_unavailable", "Web Crypto is required");
+    }
+    const digest = await cryptoApi.subtle.digest("SHA-256", bytes);
+    return `direct:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function callbackState(callbackUrl) {
+    const callback = httpsUrl(callbackUrl, "callbackUrl");
+    if (callback.hash) {
+        throw new AuthorizationError("invalid_callback", "Authorization callback has a fragment");
+    }
+    const states = callback.searchParams.getAll("state");
+    if (states.length !== 1 || !states[0]) {
+        throw new AuthorizationError("invalid_callback", "Authorization callback must contain one state value");
+    }
+    return states[0];
+}
+function isPendingDirectSignIn(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const pending = value;
+    return (pending.kind === "pap.direct-sign-in.v1" &&
+        typeof pending.tokenEndpoint === "string" &&
+        typeof pending.tenantId === "string" &&
+        typeof pending.pairwiseUserId === "string" &&
+        typeof pending.sessionId === "string" &&
+        pending.expiresAt instanceof Date &&
+        typeof pending.request === "object" &&
+        pending.request !== null);
+}
+/** Orchestrate one-use browser authorization and proof-bound code exchange. */
+export class DirectSignInClient {
+    #reactor;
+    #fetch;
+    #maxResponseBytes;
+    constructor(options) {
+        const fetcher = options.fetch ?? globalThis.fetch;
+        if (!fetcher) {
+            throw new AuthorizationError("fetch_unavailable", "A fetch implementation is required");
+        }
+        const maxResponseBytes = options.maxResponseBytes ?? 100 * 1024;
+        if (!Number.isInteger(maxResponseBytes) || maxResponseBytes <= 0) {
+            throw new RangeError("maxResponseBytes must be a positive integer");
+        }
+        this.#reactor = options.reactor;
+        this.#fetch = fetcher;
+        this.#maxResponseBytes = maxResponseBytes;
+    }
+    async begin(options) {
+        const lifetimeSeconds = options.lifetimeSeconds ?? 600;
+        if (!Number.isInteger(lifetimeSeconds) || lifetimeSeconds < 1 || lifetimeSeconds > 900) {
+            throw new RangeError("Direct Sign-In state lifetime must be between 1 and 900 seconds");
+        }
+        if (!options.tenantId || options.tenantId.length > 256) {
+            throw new RangeError("tenantId must contain between 1 and 256 characters");
+        }
+        if (!/^[A-Za-z0-9_-]{1,256}$/.test(options.pairwiseUserId)) {
+            throw new AuthorizationError("invalid_user_id", "Pairwise user ID must be an opaque URL-safe identifier");
+        }
+        if (!/^[A-Za-z0-9_-]{1,256}$/.test(options.sessionId)) {
+            throw new AuthorizationError("invalid_session_id", "Invalid PAP session ID");
+        }
+        const clock = firstContribution(this.#reactor, Clocks, "clock");
+        const random = firstContribution(this.#reactor, RandomSources, "random source");
+        const store = firstContribution(this.#reactor, AuthorizationStateStores, "authorization state store");
+        const browser = firstContribution(this.#reactor, BrowserHandoffs, "browser handoff");
+        const request = await buildDirectSignInRequest({
+            authorizationEndpoint: options.authorizationEndpoint,
+            issuer: options.issuer,
+            clientId: options.clientId,
+            redirectUri: options.redirectUri,
+            scopes: options.scopes,
+            randomBytes: (length) => random.bytes(length),
+        });
+        const tokenEndpoint = httpsUrl(options.tokenEndpoint, "tokenEndpoint").toString();
+        const expiresAt = new Date(clock.now().getTime() + lifetimeSeconds * 1000);
+        const reference = await stateReference(request.state.reveal());
+        const pending = {
+            kind: "pap.direct-sign-in.v1",
+            request,
+            tokenEndpoint,
+            tenantId: options.tenantId,
+            pairwiseUserId: options.pairwiseUserId,
+            sessionId: options.sessionId,
+            expiresAt,
+        };
+        await store.put(reference, pending, { expiresAt });
+        try {
+            await browser.open(request.authorizationUrl);
+        }
+        catch (cause) {
+            await store.take(reference);
+            throw new AuthorizationError("browser_handoff_failed", "Browser handoff failed", { cause });
+        }
+        return { expiresAt, requestedScopes: request.scopes };
+    }
+    async complete(options) {
+        const state = callbackState(options.callbackUrl);
+        const store = firstContribution(this.#reactor, AuthorizationStateStores, "authorization state store");
+        const pending = await store.take(await stateReference(state));
+        if (!isPendingDirectSignIn(pending)) {
+            throw new AuthorizationError("invalid_or_expired_state", "Authorization state is unknown, expired, or already used");
+        }
+        const clock = firstContribution(this.#reactor, Clocks, "clock");
+        if (clock.now().getTime() > pending.expiresAt.getTime()) {
+            throw new AuthorizationError("invalid_or_expired_state", "Authorization state has expired");
+        }
+        const callback = validateDirectSignInCallback(pending.request, options.callbackUrl);
+        return this.#exchange(pending, callback, options.signal);
+    }
+    async #exchange(pending, callback, signal) {
+        const clock = firstContribution(this.#reactor, Clocks, "clock");
+        const random = firstContribution(this.#reactor, RandomSources, "random source");
+        const signer = firstContribution(this.#reactor, Signers, "signer");
+        const dpop = firstContribution(this.#reactor, DpopProofProviders, "DPoP proof provider");
+        let nonce;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const iat = Math.floor(clock.now().getTime() / 1000);
+            const clientAssertion = await signer.sign({
+                iss: pending.request.clientId,
+                sub: pending.request.clientId,
+                aud: pending.tokenEndpoint,
+                iat,
+                exp: iat + 60,
+                jti: `jti_${base64Url(entropy(16, (length) => random.bytes(length)))}`,
+            }, { purpose: "client_assertion" });
+            const proof = await dpop.create({
+                method: "POST",
+                url: pending.tokenEndpoint,
+                tenantId: pending.tenantId,
+                subject: pending.pairwiseUserId,
+                issuer: pending.request.issuer,
+                ...(nonce === undefined ? {} : { nonce }),
+            });
+            const grant = new AuthorizationCodeGrant({
+                code: callback.code.reveal(),
+                redirectUri: pending.request.redirectUri,
+                codeVerifier: pending.request.codeVerifier.reveal(),
+                sessionId: pending.sessionId,
+                clientId: pending.request.clientId,
+                clientAssertion: clientAssertion.reveal(),
+            });
+            let response;
+            try {
+                response = await this.#fetch(pending.tokenEndpoint, {
+                    method: "POST",
+                    headers: { Accept: "application/json", DPoP: proof.reveal() },
+                    body: grant.toForm(),
+                    credentials: "omit",
+                    redirect: "error",
+                    ...(signal === undefined ? {} : { signal }),
+                });
+            }
+            catch (cause) {
+                throw new AuthorizationError("request_failed", "Direct Sign-In token exchange failed", { cause });
+            }
+            const payload = await this.#decode(response);
+            if (response.ok)
+                return this.#result(response, payload, pending);
+            const source = typeof payload === "object" && payload !== null ? payload : {};
+            const remoteCode = "error" in source ? source.error : undefined;
+            const code = typeof remoteCode === "string" ? remoteCode : "http_error";
+            if (code === "use_dpop_nonce" && attempt === 0) {
+                nonce = response.headers.get("dpop-nonce") ?? undefined;
+                if (!nonce) {
+                    throw new AuthorizationError("missing_dpop_nonce", "Company requested a DPoP nonce but did not send one", { statusCode: response.status });
+                }
+                continue;
+            }
+            throw new AuthorizationError(code, "Company refused the Direct Sign-In token exchange", {
+                statusCode: response.status,
+            });
+        }
+        throw new AuthorizationError("use_dpop_nonce", "Company rejected the refreshed DPoP proof");
+    }
+    async #decode(response) {
+        const contentType = response.headers.get("content-type")?.split(";", 1)[0]?.trim();
+        if (contentType !== "application/json") {
+            throw new AuthorizationError("invalid_content_type", "Direct Sign-In token endpoint must return JSON", { statusCode: response.status });
+        }
+        const body = await response.text();
+        if (new TextEncoder().encode(body).byteLength > this.#maxResponseBytes) {
+            throw new AuthorizationError("response_too_large", "Direct Sign-In response exceeds size limit", { statusCode: response.status });
+        }
+        try {
+            return parseJsonStrict(body);
+        }
+        catch (cause) {
+            throw new AuthorizationError("invalid_json", "Direct Sign-In token endpoint returned invalid JSON", { statusCode: response.status, cause });
+        }
+    }
+    #result(response, payload, pending) {
+        let token;
+        try {
+            token = parseSessionToken(payload);
+        }
+        catch (cause) {
+            throw new AuthorizationError("invalid_token_response", "Direct Sign-In token response is malformed", { statusCode: response.status, cause });
+        }
+        if (token.tokenType !== "DPoP" || !token.signedIn) {
+            throw new AuthorizationError("invalid_token_response", "Direct Sign-In must return a signed-in DPoP Session Token", { statusCode: response.status });
+        }
+        if (token.sessionId !== pending.sessionId) {
+            throw new AuthorizationError("session_mismatch", "Direct Sign-In response changed the existing Session", { statusCode: response.status });
+        }
+        if (token.scopes.some((scope) => !pending.request.scopes.includes(scope))) {
+            throw new AuthorizationError("scope_escalation", "Company returned a scope that was not requested", { statusCode: response.status });
+        }
+        return {
+            token,
+            grantedScopes: token.scopes,
+            missingScopes: pending.request.scopes.filter((scope) => !token.scopes.includes(scope)),
+        };
+    }
+}
 //# sourceMappingURL=auth.js.map