@reclaimprotocol/agent 0.1.27 → 0.1.29

package/lib/old/login-cdp.js

@@ -79,12 +79,30 @@ export const EXTRACT_TOKEN_JS = `(async () => {
 	} catch (e) { return null }
 })()`;
 /**
- * Open the dashboard login page in Chrome via CDP, wait for the developer to
- * finish signing in, read the resulting Firebase ID token from page storage,
- * then clean up. If we had to launch a dedicated Chrome for this, we close the
- * whole browser afterwards; if we attached to a Chrome that was already up
- * (for example, the capture flow's), we only close the tab we opened so we
- * don't disrupt it.
+ * Accept only the two loopback Chrome modes used for legacy dashboard login.
+ * Config files are user-editable, so validate at runtime rather than trusting
+ * the TypeScript shape. Remote Builder, container, custom-CDP, and URL inputs
+ * are deliberately unsupported here.
+ */
+export function localDashboardBrowser(value) {
+    if (!value || typeof value !== 'object') {
+        return { mode: 'dedicated', port: 9222 };
+    }
+    const mode = Reflect.get(value, 'attachMode');
+    const port = Reflect.get(value, 'port');
+    if ((mode === 'dedicated' || mode === 'attach')
+        && Number.isInteger(port) && Number(port) > 0 && Number(port) <= 65535) {
+        return { mode, port: Number(port) };
+    }
+    return { mode: 'dedicated', port: 9222 };
+}
+/**
+ * Open the dashboard login page in a local Chrome via loopback CDP, wait for
+ * the developer to finish signing in, read the resulting Firebase ID token
+ * from page storage, then clean up. This never uses a Builder, container,
+ * custom-CDP, or shared browser. If we launch a dedicated Chrome, we close the
+ * whole browser afterward; if we attach to an existing local Chrome, we close
+ * only the tab we opened.
  */
 export async function captureFirebaseTokenViaCdp(opts) {
     const loginUrl = opts.loginUrl || oldLoginUrl() || DEFAULT_LOGIN_URL;
@@ -96,9 +114,7 @@ export async function captureFirebaseTokenViaCdp(opts) {
     // followed looked like a 6-minute hang with no output.
     const timeoutMs = opts.timeoutMs ?? 360000;
     const pollMs = opts.pollMs ?? 1000;
-    const cfg = new ConfigStore().read()?.browser_agent;
-    const mode = cfg?.attachMode ?? 'dedicated';
-    const port = cfg?.port ?? 9222;
+    const { mode, port } = localDashboardBrowser(new ConfigStore().read()?.browser_agent);
     // Ensure something is answering CDP. In dedicated mode we may launch it.
     let launchedByUs = false;
     try {
@@ -106,9 +122,10 @@ export async function captureFirebaseTokenViaCdp(opts) {
     }
     catch {
         if (mode !== 'dedicated') {
-            throw new Error(`attach mode: nothing answering CDP on port ${port}. Launch Chrome ` +
+            throw new Error(`local attach mode: nothing answering CDP on port ${port}. ` +
+                'Launch Chrome ' +
                 `with --remote-debugging-port=${port} AND a non-default ` +
-                '--user-data-dir, or switch to dedicated mode (attach_browser).');
+                '--user-data-dir, or use the dedicated local login mode.');
         }
         launchChrome({ port, profileDir: defaultProfileDir() });
         await waitForCdpReady(port, 10000);

package/lib/old/to-register.d.ts

@@ -127,6 +127,7 @@ export interface SemverTriplet {
     minor: number;
     patch: number;
 }
+export type SemverBump = 'major' | 'minor' | 'patch';
 /**
  * Pull `{major,minor,patch}` triplets out of a `/versions` response, tolerant
  * of the exact envelope (array, `{ providerVersions: [...] }`, `{ items }`,
@@ -140,4 +141,9 @@ export declare function extractVersions(resp: unknown): SemverTriplet[];
  * rather than collide with the guaranteed 1.0.0).
  */
 export declare function bumpPatchString(versions: SemverTriplet[]): string;
+/** Resolve a strictly newer immutable version for old-devtools publishing. */
+export declare function resolveNewVersionString(versions: SemverTriplet[], input?: {
+    version?: SemverTriplet;
+    bump?: SemverBump;
+}): string;
 export {};

package/lib/old/to-register.js

@@ -1,3 +1,4 @@
+import { badRequest, conflict } from '@hapi/boom';
 import assert from 'node:assert';
 /** Default web settings, mirroring the builder openapi defaults
  *  (`ProviderWebSettings.geoLocation`, `PortalClientOptions.useProxy`). The
@@ -208,18 +209,47 @@ export function extractVersions(resp) {
  * rather than collide with the guaranteed 1.0.0).
  */
 export function bumpPatchString(versions) {
-    if (versions.length === 0) {
+    return resolveNewVersionString(versions);
+}
+/** Resolve a strictly newer immutable version for old-devtools publishing. */
+export function resolveNewVersionString(versions, input = {}) {
+    assert(!(input.version && input.bump), badRequest('Pass either `version` or `bump`, not both.'));
+    const highest = highestVersion(versions);
+    if (input.version) {
+        assert(!highest || compareVersions(input.version, highest) > 0, conflict(`Version ${formatVersion(input.version)} must be higher than the ` +
+            `current highest version ${highest ? formatVersion(highest) : 'none'}.`));
+        return formatVersion(input.version);
+    }
+    if (!highest) {
         return '1.0.1';
     }
+    const bump = input.bump ?? 'patch';
+    switch (bump) {
+        case 'major':
+            return `${highest.major + 1}.0.0`;
+        case 'minor':
+            return `${highest.major}.${highest.minor + 1}.0`;
+        case 'patch':
+            return `${highest.major}.${highest.minor}.${highest.patch + 1}`;
+    }
+}
+function highestVersion(versions) {
+    if (versions.length === 0) {
+        return undefined;
+    }
     let hi = versions[0];
     for (const v of versions) {
-        if (v.major > hi.major ||
-            (v.major === hi.major && v.minor > hi.minor) ||
-            (v.major === hi.major && v.minor === hi.minor && v.patch > hi.patch)) {
+        if (compareVersions(v, hi) > 0) {
             hi = v;
         }
     }
-    return `${hi.major}.${hi.minor}.${hi.patch + 1}`;
+    return hi;
+}
+function compareVersions(a, b) {
+    return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+function formatVersion(version) {
+    return `${version.major}.${version.minor}.${version.patch}`;
 }
 function pickArray(resp) {
     if (Array.isArray(resp)) {

package/lib/old/tools/authenticate.d.ts

@@ -1,10 +1,11 @@
 import { type RegisteredTool } from '../../mcp/server.ts';
 import type { ReclaimOldClient } from '../client.ts';
 /**
- * OLD-devtools authenticate. The default, zero-arg flow drives Chrome via CDP:
- * it opens the devtools dashboard, waits for the developer to sign in, reads
- * the Firebase ID token straight from page storage, then closes the tab (or
- * the browser, if it launched one just for this). Two manual overrides remain:
+ * OLD-devtools authenticate. The default, zero-arg flow drives only a local
+ * Chrome through loopback CDP. It never uses a Builder, container, custom-CDP,
+ * or shared browser. It opens the devtools dashboard, waits for the developer
+ * to sign in, reads the Firebase ID token from page storage, then closes the
+ * tab or the dedicated browser it launched. Two manual overrides remain:
  *
  *   - `token`: paste a Firebase ID token yourself (skips the browser).
  *   - `ethAddress`: an `eth:<addr>`/`0x…` uid for an already-provisioned eth

package/lib/old/tools/authenticate.js

@@ -3,10 +3,11 @@ import { defineTool } from "../../mcp/server.js";
 import { persistIdentity, toEthUid } from "../identity.js";
 import { captureFirebaseTokenViaCdp } from "../login-cdp.js";
 /**
- * OLD-devtools authenticate. The default, zero-arg flow drives Chrome via CDP:
- * it opens the devtools dashboard, waits for the developer to sign in, reads
- * the Firebase ID token straight from page storage, then closes the tab (or
- * the browser, if it launched one just for this). Two manual overrides remain:
+ * OLD-devtools authenticate. The default, zero-arg flow drives only a local
+ * Chrome through loopback CDP. It never uses a Builder, container, custom-CDP,
+ * or shared browser. It opens the devtools dashboard, waits for the developer
+ * to sign in, reads the Firebase ID token from page storage, then closes the
+ * tab or the dedicated browser it launched. Two manual overrides remain:
  *
  *   - `token`: paste a Firebase ID token yourself (skips the browser).
  *   - `ethAddress`: an `eth:<addr>`/`0x…` uid for an already-provisioned eth
@@ -31,7 +32,9 @@ export function authenticateTool(client) {
     return defineTool({
         name: 'reclaim_authenticate',
         description: 'Authenticate against the OLD Reclaim devtools backend. \n\n' +
-            'Default (no args): opens the devtools dashboard in Chrome via CDP, ' +
+            'Default (no args): opens the devtools dashboard in a LOCAL Chrome ' +
+            'over loopback CDP. It never uses a Builder, container, custom-CDP, ' +
+            'or shared browser. It ' +
             'waits for you to sign in, grabs the Firebase token automatically, ' +
             'and closes the tab. A previously stored identity that is still ' +
             'valid is reused first (pass `useBrowser: true` to force a fresh ' +
@@ -128,6 +131,7 @@ export function authenticateTool(client) {
         return {
             authenticated: true,
             method: 'browser',
+            browser: 'local-chrome',
             closedBrowser: result.closedBrowser,
             note: 'Signed in via the dashboard; Firebase token captured and cached. ' +
                 'Tokens expire (~1h) — re-run reclaim_authenticate on 401.',

package/lib/old/tools/publish.d.ts

@@ -9,8 +9,8 @@ import type { ReclaimOldClient } from '../client.ts';
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
  *   - WITH `providerId` → `POST /api/providers/:providerId/config`: adds a
- *     new version to an existing provider (auto-bumps the patch above the
- *     highest existing version).
+ *     new immutable version to an existing provider (patch by default;
+ *     major/minor/patch or an exact higher version when requested).
  *
  * Get a `providerId` from `get_me_providers`.
  *

package/lib/old/tools/publish.js

@@ -1,8 +1,10 @@
-import { Boom, isBoom } from '@hapi/boom';
+import { badRequest, Boom, isBoom } from '@hapi/boom';
+import assert from 'node:assert';
 import { defineTool } from "../../mcp/server.js";
-import { ALLOWED_REQUESTS_HINT, USER_SCRIPT_HINT, } from "../../provider/injection-doc.js";
+import { ALLOWED_REQUESTS_HINT, COOKIE_ATTACHMENT_HINT, USER_SCRIPT_HINT, } from "../../provider/injection-doc.js";
 import { countsFor, matchRedactionWarnings, } from "../../provider/match-redaction-warning.js";
-import { bumpPatchString, extractVersions, injectedRequestDataFrom, providerToConfigBody, providerToRegisterBody, } from "../to-register.js";
+import { postPublishBrowserNotes } from "../../provider/post-publish-browser.js";
+import { extractVersions, injectedRequestDataFrom, providerToConfigBody, providerToRegisterBody, resolveNewVersionString, } from "../to-register.js";
 const DEFAULT_VERSION_INFO = 'Updated from MCP browser capture';
 /** Pull the new provider's id out of a register response, tolerant of the
  *  envelope (`{providerId}`, `{provider:{providerId}}`, `{id}`). */
@@ -42,8 +44,8 @@ function rethrowOwnershipError(err, providerId) {
  *   - WITHOUT `providerId` → `POST /api/providers/register`: creates a
  *     brand-new provider + version 1.0.0. Re-running creates a DUPLICATE.
  *   - WITH `providerId` → `POST /api/providers/:providerId/config`: adds a
- *     new version to an existing provider (auto-bumps the patch above the
- *     highest existing version).
+ *     new immutable version to an existing provider (patch by default;
+ *     major/minor/patch or an exact higher version when requested).
  *
  * Get a `providerId` from `get_me_providers`.
  *
@@ -67,8 +69,11 @@ export function createVersionFromCaptureTool(client, attachRef) {
             + 'redactions are supported.\n\n'
             + 'Omit `providerId` to REGISTER A NEW provider (creates it + '
             + 'version 1.0.0 — re-running creates a DUPLICATE). Pass '
-            + '`providerId` (from get_me_providers) to add a NEW VERSION to it; '
-            + 'the patch auto-bumps. You can only version a provider YOU own — '
+            + '`providerId` (from get_me_providers) to add a NEW IMMUTABLE VERSION '
+            + 'to it. Omit `version` and `bump` for a patch bump, pass `bump` for '
+            + 'a major/minor/patch bump, or pass an exact higher `version` when '
+            + 'the user directs it. Never edit an existing version. You can only '
+            + 'version a provider YOU own — '
             + 'to publish your own take on one you don\'t own, omit '
             + '`providerId` to register your own copy.\n\n'
             + 'THIS BACKEND ONLY EVER CREATES A NEW VERSION — there is no '
@@ -167,6 +172,25 @@ export function createVersionFromCaptureTool(client, attachRef) {
                     description: 'Existing provider to add a new version to. Omit to register ' +
                         'a brand-new provider.',
                 },
+                version: {
+                    type: 'object',
+                    description: 'Exact new semver requested by the user. Existing-provider ' +
+                        'publishing only; it must be higher than the current highest ' +
+                        'version. Do not pass with `bump`.',
+                    properties: {
+                        major: { type: 'integer', minimum: 0 },
+                        minor: { type: 'integer', minimum: 0 },
+                        patch: { type: 'integer', minimum: 0 },
+                    },
+                    required: ['major', 'minor', 'patch'],
+                },
+                bump: {
+                    type: 'string',
+                    enum: ['major', 'minor', 'patch'],
+                    description: 'Semantic increment from the highest version. Defaults to ' +
+                        '`patch`. Existing-provider publishing only; do not pass with ' +
+                        'an exact `version`.',
+                },
                 description: {
                     type: 'string',
                     description: 'Provider description (new-provider register only).',
@@ -360,7 +384,8 @@ export function createVersionFromCaptureTool(client, attachRef) {
                         'certain none is configured. Builder calls the equivalent ' +
                         'concept `interceptorType` (no `NONE` there — omitting the ' +
                         'whole `interceptorOptions` object is its no-interception ' +
-                        'signal instead). What each value actually does: ' +
+                        'signal instead). ' + COOKIE_ATTACHMENT_HINT +
+                        'What each value actually does: ' +
                         'how_it_works({ topic: "interception" }).',
                 },
                 disableRequestReplay: {
@@ -379,6 +404,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
             required: ['initialUrl'],
         },
     }, async (args) => {
+        assert(!(args.version && args.bump), badRequest('Pass either `version` or `bump`, not both.'));
+        assert(args.providerId || (!args.version && !args.bump), badRequest('`version` and `bump` require `providerId`; new-provider ' +
+            'registration starts at the backend-defined version.'));
         // `provider` / `providers` are just two spellings of the same input —
         // fold them into one array. Zero drafts is allowed ONLY when adding a
         // version to an EXISTING provider (`providerId` set): that publishes
@@ -427,15 +455,12 @@ export function createVersionFromCaptureTool(client, attachRef) {
         // developer before closing it (a builder-mode session is
         // quota-accounted and otherwise just sits until its TTL expires).
         const attached = attachRef?.current;
-        if (attached) {
-            notes.push(`A "${attached.mode}" browser session is still attached` +
-                (attached.browserSessionId
-                    ? ` (browserSessionId: ${attached.browserSessionId})`
-                    : '') +
-                '. Ask the developer whether they want to keep it open for ' +
-                'further edits — only call dispose_browser once they confirm ' +
-                'they\'re done with it.');
-        }
+        notes.push(...postPublishBrowserNotes(attached, {
+            initialUrl: args.initialUrl,
+            hasUserScript: !!args.customInjection?.trim(),
+            hasInterceptor: args.injectionType !== 'NONE'
+                && !!args.customInjection?.trim(),
+        }));
         const withNotes = (result) => {
             if (notes.length && result && typeof result === 'object') {
                 return { ...result, _notes: notes };
@@ -486,7 +511,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 // providerId.
                 try {
                     const versionsResp = await client.listVersions(newProviderId);
-                    const followVersion = bumpPatchString(extractVersions(versionsResp));
+                    const followVersion = resolveNewVersionString(extractVersions(versionsResp));
                     const configBody = providerToConfigBody(providers, opts, followVersion, DEFAULT_VERSION_INFO);
                     await client.updateProviderConfig(newProviderId, configBody);
                     notes.push(`Created an automatic follow-up version (${followVersion}) to ` +
@@ -517,8 +542,9 @@ export function createVersionFromCaptureTool(client, attachRef) {
             }
             return withNotes(registered);
         }
-        // New version of an existing provider — pick the next patch above
-        // the highest existing version. A provider you don't own (for example, a
+        // New version of an existing provider — resolve the requested semantic
+        // increment above the highest existing version. A provider you don't own
+        // (for example, a
         // public one) fails here with 401/403/404; surface the register-a-copy
         // workaround instead of a bare permission error.
         const providerId = args.providerId;
@@ -541,7 +567,7 @@ export function createVersionFromCaptureTool(client, attachRef) {
                 'version with get_provider_info and re-publish with them ' +
                 'included.');
             const versionsResp = await client.listVersions(providerId);
-            const version = bumpPatchString(extractVersions(versionsResp));
+            const version = resolveNewVersionString(extractVersions(versionsResp), { version: args.version, bump: args.bump });
             const versionInfo = args.notes && args.notes.trim().length >= 10
                 ? args.notes.trim()
                 : DEFAULT_VERSION_INFO;

package/lib/proof/attestor-auth.d.ts

@@ -0,0 +1,13 @@
+import { type proto } from '@reclaimprotocol/attestor-core';
+/** Session-bound authorization in both forms used by Reclaim proof clients. */
+export interface AttestorAuthentication {
+    /** Native object consumed by the JavaScript attestor client. */
+    request: proto.AuthenticationRequest;
+    /** Legacy base64 JSON token consumed by native TEE clients. */
+    token: string;
+}
+/**
+ * Create legacy-compatible attestor authorization when the deployment has an
+ * auth private key. An absent key intentionally means authentication is off.
+ */
+export declare function createAttestorAuthentication(sessionId: string, privateKey: string | undefined): Promise<AttestorAuthentication | undefined>;

package/lib/proof/attestor-auth.js

@@ -0,0 +1,16 @@
+import { createAuthRequest } from '@reclaimprotocol/attestor-core';
+/**
+ * Create legacy-compatible attestor authorization when the deployment has an
+ * auth private key. An absent key intentionally means authentication is off.
+ */
+export async function createAttestorAuthentication(sessionId, privateKey) {
+    if (!privateKey?.trim()) {
+        return undefined;
+    }
+    const request = await createAuthRequest({ id: sessionId }, privateKey);
+    const token = Buffer.from(JSON.stringify({
+        ...request,
+        signature: Buffer.from(request.signature).toString('base64'),
+    }), 'utf8').toString('base64');
+    return { request, token };
+}

package/lib/proof/attestor.d.ts

@@ -1,3 +1,4 @@
+import { type proto } from '@reclaimprotocol/attestor-core';
 import './patch-domhandler.ts';
 import type { ReclaimProvider } from '../provider/schema.ts';
 export interface AttestorLogEntry {
@@ -5,8 +6,8 @@ export interface AttestorLogEntry {
     msg: string;
     ctx?: Record<string, unknown>;
 }
-/** The attestor's signed claim data + signature, for building the nested proof
- *  JWS a Consumer verifies against the attestor's key. Populated when
+/** The attestor's signed claim data + signature, for building the exact legacy
+ *  Proof a Consumer verifies against the attestor's key. Populated when
  *  `includeAttestorClaim` is set (the app's verification runner needs it; the
  *  MCP `run_proof` tool ignores it). */
 export interface AttestorClaim {
@@ -21,6 +22,8 @@ export interface AttestorClaim {
 /** Options for {@link runAttestorProof}. */
 export interface RunAttestorProofOptions {
     attestorUrl?: string;
+    /** Optional session-bound authorization generated by the trusted backend. */
+    authRequest?: proto.AuthenticationRequest;
     /** When resolving the key from env/.env/file, the address the caller expects
      *  to sign with (sanity check). Ignored when `ownerPrivateKey` is given. */
     ownerAddress?: string;
@@ -33,7 +36,7 @@ export interface RunAttestorProofOptions {
      *  want gnark's speed pin it explicitly (for example, the verify runner). */
     zkEngine?: 'gnark' | 'snarkjs' | 'stwo';
     /** Extract the structured {@link AttestorClaim} (claim + attestor signature)
-     *  onto the result for nested-proof construction. */
+     *  onto the result for legacy Proof construction. */
     includeAttestorClaim?: boolean;
 }
 export interface ProofResult {
@@ -44,7 +47,7 @@ export interface ProofResult {
     owner?: string;
     verified: boolean;
     error?: string;
-    /** Structured claim + signature for nested-proof verification. Set only when
+    /** Structured claim + signature for legacy Proof verification. Set only when
      *  `includeAttestorClaim` was requested and the claim carries signatures. */
     attestorClaim?: AttestorClaim;
     /** Set to `'missing-owner-key'` when no credential was available to

package/lib/proof/attestor.js

@@ -6,7 +6,7 @@
 // revealed slice; jsonPath/xPath live on responseRedactions (what the prover
 // reveals), never on responseMatches.
 import { bytesToHex } from '@noble/hashes/utils.js';
-import { createClaimOnAttestor } from '@reclaimprotocol/attestor-core';
+import { createClaimOnAttestor, } from '@reclaimprotocol/attestor-core';
 // Side-effect: make external domhandler nodes DOM-like so attestor-core's
 // bundled `xpath` accepts them (see patch-domhandler.ts). Must load before any
 // proof runs its response-redaction extraction.
@@ -158,7 +158,10 @@ export async function runAttestorProof(provider, secrets, opts = {}) {
                     headers: secrets,
                 },
                 ownerPrivateKey,
-                client: { url: resolveAttestorUrl(opts.attestorUrl) },
+                client: {
+                    url: resolveAttestorUrl(opts.attestorUrl),
+                    ...(opts.authRequest ? { authRequest: opts.authRequest } : {}),
+                },
                 zkEngine: opts.zkEngine ?? 'stwo',
                 ...(capture !== undefined && { logger: capture.logger }),
             });
@@ -190,8 +193,8 @@ export async function runAttestorProof(provider, secrets, opts = {}) {
         if (owner !== undefined) {
             result.owner = owner;
         }
-        // Structured claim + signature so the result JWS can carry a nested,
-        // attestor-signed proof the Consumer verifies independently.
+        // Structured claim + signature so the result JWS can carry the exact
+        // legacy Proof the Consumer verifies independently.
         if (opts.includeAttestorClaim) {
             const sigs = claim.signatures;
             if (claimData

package/lib/proof/index.d.ts

@@ -1,5 +1,6 @@
 export type { AttestorClaim, AttestorLogEntry, ProofResult, RunAttestorProofOptions, } from './attestor.ts';
 export { runAttestorProof, tailLogs, warnsAndErrors } from './attestor.ts';
+export { createAttestorAuthentication, type AttestorAuthentication, } from './attestor-auth.ts';
 export { buildHttpParams, ensureAttestorCrypto, type ParsedClaim, parseClaim, resolveAttestorUrl, } from './proof-core.ts';
 export { type HttpParams, type HttpSecretParams, type PopcornProveOptions, popcornProve, popcornValidateExtraction, type ValidateExtractionResult, } from './pod-prover.ts';
 export { ensureZkFiles } from './zk-files.ts';

package/lib/proof/index.js

@@ -1,4 +1,5 @@
 export { runAttestorProof, tailLogs, warnsAndErrors } from "./attestor.js";
+export { createAttestorAuthentication, } from "./attestor-auth.js";
 export { buildHttpParams, ensureAttestorCrypto, parseClaim, resolveAttestorUrl, } from "./proof-core.js";
 export { popcornProve, popcornValidateExtraction, } from "./pod-prover.js";
 export { ensureZkFiles } from "./zk-files.js";

package/lib/proof/pod-prover.d.ts

@@ -16,6 +16,8 @@ export interface PopcornProveOptions {
     secretParams: HttpSecretParams;
     /** Session context, stringified into the claim context if given. */
     context?: Record<string, unknown>;
+    /** Base64 JSON authorization forwarded by reclaim-tee to the attestor. */
+    authRequest?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ValidateExtractionResult {

package/lib/proof/pod-prover.js

@@ -26,10 +26,9 @@
  *
  * The pod API is unauthenticated (gateway/session is the trust boundary); call
  * it over the same internal host used for CDP. Consumers verify
- * `claim_signature` only (see `@reclaimprotocol/client`'s `verifyNestedProof`),
- * so this hands back a {@link AttestorClaim} whose hex `claimSignature` the
- * shared `wrapProofAsJws` (app-side) turns into the nested result proof.
- * `result_signature` is unused by any consumer.
+ * `claim_signature` with the legacy SDK's `verifyProof`, so this hands back an
+ * {@link AttestorClaim} that the app places in the exact legacy `Proof` shape.
+ * `result_signature` is unused by consumers.
  */
 import { bytesToHex } from '@noble/hashes/utils.js';
 /**
@@ -75,7 +74,7 @@ function b64ToBytes(b64) {
  * the reason (never throws for an expected proof failure).
  */
 export async function popcornProve(opts) {
-    const { apiUrl, params, secretParams, context } = opts;
+    const { apiUrl, params, secretParams, context, authRequest } = opts;
     const doFetch = opts.fetchImpl ?? fetch;
     const base = apiUrl.replace(/\/$/, '');
     const providerParamsJson = JSON.stringify({
@@ -83,6 +82,7 @@ export async function popcornProve(opts) {
         params,
         secretParams,
         ...(context ? { context: JSON.stringify(context) } : {}),
+        ...(authRequest ? { authRequest } : {}),
     });
     const fail = (error) => ({
         proof: undefined,

package/lib/provider/injection-doc.d.ts

@@ -14,6 +14,8 @@
  *
  * Shared by both publish tools so the two can't drift apart.
  */
+/** Auth behavior shared by intercepted and script-requested claims. */
+export declare const COOKIE_ATTACHMENT_HINT: string;
 /** What the script is and where the real guidance lives. */
 export declare const USER_SCRIPT_HINT: string;
 /** Prefixes the `allowedJsRequests` / `allowedInjectedRequestData` field. The

package/lib/provider/injection-doc.js

@@ -14,12 +14,18 @@
  *
  * Shared by both publish tools so the two can't drift apart.
  */
+/** Auth behavior shared by intercepted and script-requested claims. */
+export const COOKIE_ATTACHMENT_HINT = 'For an intercepted request or window.Reclaim.requestClaim, the verification '
+    + 'client automatically attaches cookies applicable to the request URL to '
+    + 'the claim sent to the attestor. Do not read, hardcode, or copy Cookie '
+    + 'values into the script or public params. ';
 /** What the script is and where the real guidance lives. */
 export const USER_SCRIPT_HINT = 'Plain JavaScript injected into the provider page before every page load. '
     + 'Use standard browser APIs (window.location, element.click(), forms) to '
     + 'drive login/navigation so the target request fires — the client already '
     + 'intercepts page requests, and window.Reclaim is only for rare edge cases, '
-    + 'not navigation. Full guide: how_it_works({ topic: "user-script" }).';
+    + 'not navigation. ' + COOKIE_ATTACHMENT_HINT
+    + 'Full guide: how_it_works({ topic: "user-script" }).';
 /** Prefixes the `allowedJsRequests` / `allowedInjectedRequestData` field. The
  *  trap it describes is silent and total — a mis-declared entry makes
  *  `verifyProof({ providerId })` reject EVERY real proof — so the warning

package/lib/provider/post-publish-browser.d.ts

@@ -0,0 +1,12 @@
+interface AttachedBrowser {
+    mode: string;
+    browserSessionId?: string;
+}
+interface BrowserRetestOptions {
+    initialUrl: string;
+    hasUserScript: boolean;
+    hasInterceptor: boolean;
+}
+/** Advisory follow-up when a browser remains after provider creation. */
+export declare function postPublishBrowserNotes(attached: AttachedBrowser | undefined, options: BrowserRetestOptions): string[];
+export {};

package/lib/provider/post-publish-browser.js

@@ -0,0 +1,40 @@
+/** Advisory follow-up when a browser remains after provider creation. */
+export function postPublishBrowserNotes(attached, options) {
+    if (!attached) {
+        return [];
+    }
+    const identity = `A "${attached.mode}" browser session is still attached`
+        + (attached.browserSessionId
+            ? ` (browserSessionId: ${attached.browserSessionId})`
+            : '');
+    const retest = 'Before disposing it, best-effort test the '
+        + 'already-authenticated path only when this profile is still signed in: '
+        + `navigate to initialUrl (${options.initialUrl}) without clearing cookies `
+        + 'or forcing another login. '
+        + (options.hasUserScript
+            ? 'Use test_user_script with this version\'s script and initialUrl; '
+            : 'Navigate to initialUrl normally; ')
+        + 'confirm every required target request still fires, then replay and '
+        + 'prove each one when the existing capture has enough data. Check that '
+        + 'the flow handles '
+        + 'both a fresh sign-in and an already-signed-in landing from current page '
+        + 'state, not only a login transition. This is advisory: skip it when no '
+        + 'authenticated state is available. An inconclusive result must not block '
+        + 'disposal or trigger a republish.';
+    const interceptor = options.hasInterceptor
+        ? 'The attached authoring browser validates page behavior and the user '
+            + 'script, but it does not prove compatibility with an in-page '
+            + 'production interceptor. '
+            + 'For the InApp SDK, verifier app, or browser extension, keep any '
+            + 'client-specific interceptor verification as a separate follow-up.'
+        : undefined;
+    const dispose = 'Ask the developer whether they want to keep the browser '
+        + 'open '
+        + 'for this retest or further edits. Only call dispose_browser after they '
+        + 'confirm they are done.';
+    return [
+        identity + '. ' + retest,
+        ...(interceptor ? [interceptor] : []),
+        dispose,
+    ];
+}