@poppykit/client 0.2.0 → 0.3.0

package/API.md

@@ -11,7 +11,7 @@ for complete option/result types. This map describes the supported integration s
 | `@poppykit/client` | `ApiTarget`, `AgentBrowserController`, `FeedbackReport` types | [integrations](INTEGRATIONS.md) |
 | `@poppykit/client/sqlite` | `SqliteAuthStore`, `SqliteConversationStore` | [storage](STORAGE.md) |
 | `@poppykit/client/memory` | `MemoryConversationStore` (non-durable) | [storage](STORAGE.md) |
-| `@poppykit/client/provider` | `createProvider`, `createProviderClient`, `createResultCipher` | [provider](PROVIDER.md) |
+| `@poppykit/client/provider` | `createProvider`, `createProviderClient`, `createResultCipher`, `createBrowserEnrollmentClient` | [provider](PROVIDER.md) |
 | `@poppykit/client/provider/sqlite` | `SqliteProviderStore` | [provider](PROVIDER.md) |
 
 ClientAuth methods include `start/get/list/target`, `authorization`,

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.0 (release candidate)
+
+Add the optional challenge-bound browser enrollment client under `/provider`.
+Existing provider APIs, storage adapters and all protocol authentication methods
+retain their contracts. Enrollment secrets remain caller-controlled.
+
 ## 0.2.0 (release candidate)
 
 Add bundled Postgres auth/conversation/provider stores and explicit migrations. Provider APIs and targeted storage transactions are asynchronous; await callback/result/revocation operations. SQLite and explicit legacy local-store migration remain supported.

package/PROVIDER.md

@@ -1,5 +1,15 @@
 # Optional identity provider
 
+`createBrowserEnrollmentClient` from this subpath is an optional hosting-service
+client. It is independent of company consent and leaves all secret custody with
+the caller. Configure an HTTPS enrollment URL on the provider origin; call
+`start(SHA256(verifier))`, show only its public `browserUrl`, then call
+`status(requestId, verifier)` from trusted code. A ready response contains the
+credential for immediate secure staging, never for model output. `cancel` revokes
+failed/uncertain delivery; hosts must consume results once, retain replay
+tombstones and revoke on failed/lost retrieval. The CLI implements that workflow.
+This optional service uses version1 JSON requests and is not a Poppy extension.
+
 Import `createProvider`, `createProviderClient`, and `createResultCipher` from
 `@poppykit/client/provider`; durable `SqliteProviderStore` is separately exported
 from `@poppykit/client/provider/sqlite`. Neither is loaded by the core import.

package/README.md

@@ -6,13 +6,13 @@ application supplies the agent and trusted infrastructure. [MIT](LICENSE).
 
 ## Install
 
-Version 0.2.0 is a release candidate until its publishing workflow completes.
+Version 0.3.0 is a release candidate until its publishing workflow completes.
 
 Requires Node **24.12.0+**, ESM and HTTPS. CI tests Node 24.12.0 on Linux, macOS and
 Windows; later majors are not separately certified.
 
 ```sh
-npm install @poppykit/client@0.2.0
+npm install @poppykit/client@0.3.0
 ```
 
 ## Discover a company

package/dist/provider.d.ts

@@ -148,4 +148,30 @@ export declare function createProviderClient(options: {
     cancel: (operationId: string) => Promise<Row>;
     revokeEnrollment: () => Promise<Row>;
 };
+/** Browser enrollment is an optional host service, separate from company consent. Keep verifier/results in trusted custody. */
+export declare function createBrowserEnrollmentClient(options: {
+    url: string;
+    provider: string;
+    company: string;
+    installationId: string;
+    transport: HttpTransport;
+}): {
+    start(challenge: string): Promise<{
+        requestId: string;
+        browserUrl: string;
+        expiresAt: number;
+    }>;
+    status(requestId: string, verifier: string): Promise<{
+        status: "pending" | "denied";
+        credential?: undefined;
+        clientId?: undefined;
+        callbackUrl?: undefined;
+    } | {
+        status: "ready";
+        credential: string;
+        clientId: string;
+        callbackUrl: string;
+    }>;
+    cancel: (requestId: string, verifier: string) => Promise<Row>;
+};
 export {};

package/dist/provider.js

@@ -355,3 +355,42 @@ export function createProviderClient(options) {
         takeResult: (input) => call('takeResult', input),
         cancel: (operationId) => call('cancel', { operationId }), revokeEnrollment: () => call('revokeEnrollment', {}) };
 }
+/** Browser enrollment is an optional host service, separate from company consent. Keep verifier/results in trusted custody. */
+export function createBrowserEnrollmentClient(options) {
+    const base = https(options.url), provider = https(options.provider);
+    if (base.search || base.hash || provider.origin !== base.origin)
+        throw new TypeError('enrollment and provider must share origin');
+    async function call(action, input) {
+        const response = await options.transport.fetch(new Request(`${base.href.replace(/\/$/, '')}/${action}`, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ version: 1, installationId: options.installationId, provider: options.provider, company: options.company, ...input }),
+        }));
+        const body = object(await response.json());
+        if (!response.ok)
+            throw new ProviderError(['unauthorized', 'binding_conflict', 'expired', 'consumed', 'canceled', 'rate_limited'].includes(body.error) ? body.error : 'unavailable');
+        return body;
+    }
+    return {
+        async start(challenge) {
+            if (!/^[\w-]{43}$/.test(challenge))
+                throw new TypeError('enrollment challenge');
+            const body = await call('start', { challenge });
+            const browser = https(text(body.browserUrl));
+            if (browser.origin !== base.origin || typeof body.expiresAt !== 'number' || !/^[\w-]{43}$/.test(body.requestId))
+                fail('binding_conflict');
+            return { requestId: body.requestId, browserUrl: browser.href, expiresAt: body.expiresAt };
+        },
+        async status(requestId, verifier) {
+            const body = await call('status', { requestId, verifier });
+            if (!['pending', 'denied', 'ready'].includes(body.status))
+                fail('binding_conflict');
+            if (body.status !== 'ready')
+                return { status: body.status };
+            const clientId = https(text(body.clientId)).href, callbackUrl = https(text(body.callbackUrl)).href;
+            if (new URL(clientId).origin !== provider.origin || new URL(callbackUrl).origin !== provider.origin)
+                fail('binding_conflict');
+            return { status: 'ready', credential: text(body.credential), clientId, callbackUrl };
+        },
+        cancel: (requestId, verifier) => call('cancel', { requestId, verifier }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/client",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Personal Agent Protocol client SDK",
   "repository": {