@reclaimprotocol/agent 0.1.0-dev.1

package/src/provider/schema.ts

@@ -0,0 +1,92 @@
+import type { ProviderParams } from '@reclaimprotocol/attestor-core'
+
+/** The attestor's HTTP provider parameters — the canonical source for the
+ *  request/match/redaction shapes we draft. */
+type HttpParams = ProviderParams<'http'>
+
+/** HTTP methods the attestor accepts. */
+export type HttpMethod = HttpParams['method']
+
+/**
+ * A pattern the attestor checks against the revealed slice of the response.
+ * The prover selectively reveals portions of the TLS response (via
+ * responseRedactions), so the attestor only ever sees a substring —
+ * jsonPath/xPath belong on the redaction, not here.
+ */
+export type ResponseMatch = HttpParams['responseMatches'][number]
+
+/**
+ * Selector telling the prover which portion of the response to reveal:
+ * `xPath`/`jsonPath` narrows the slice, `regex` (with named groups) matches
+ * within, and `hash` applies an OPRF so the attestor sees a nullifier
+ * instead of the cleartext value.
+ */
+export type ResponseRedaction =
+	NonNullable<HttpParams['responseRedactions']>[number]
+
+/**
+ * OPRF mode for hashed redactions. `oprf-raw` is what the dev-loop defaults
+ * to when privacy is requested — the only variant that runs without external
+ * deps (gnark for `oprf`, a TEE for `oprf-mpc`). It is the weakest of the
+ * three (the attestor participates in hashing) and is meant to be swapped
+ * out before production.
+ */
+export type OprfMode = NonNullable<ResponseRedaction['hash']>
+
+/** A single captured request + response, as we store it server-side. */
+export interface CapturedRequest {
+	requestId: string
+	method: string
+	url: string
+	status: number
+	contentType: string
+	size: number
+	requestHeaders: Record<string, string>
+	requestBody?: string
+	responseHeaders: Record<string, string>
+	responseBody?: string
+	/** Parsed GraphQL operationName if request body is a GraphQL query. */
+	graphqlOp?: string
+	/** ms since epoch when the response finished. */
+	finishedAt: number
+}
+
+/**
+ * Reclaim provider JSON shape we draft, then translate to the attestor's HTTP
+ * params (proof/attestor.ts) and the API version request (to-version.ts). The
+ * request fields derive from the attestor's own `HttpProviderParameters`, so
+ * the method enum and match/redaction shapes can't drift from what the
+ * attestor accepts. `body` is narrowed to `string` (the SDK also allows
+ * `Uint8Array`, but we only ever template text bodies).
+ */
+export interface ReclaimProvider {
+	name: string
+	url: string
+	method: HttpMethod
+	headers?: Record<string, string>
+	body?: string
+	responseMatches: ResponseMatch[]
+	responseRedactions?: ResponseRedaction[]
+	/** Public param refs (templated into URL/body), populated by draft layer. */
+	paramValues?: Record<string, string>
+}
+
+/** A reference to a secret param. Raw value lives only in server memory. */
+export interface SecretParamRef {
+	name: string
+	source: 'header' | 'cookie' | 'query'
+	redacted: true
+}
+
+/** Concerns flagged about a captured request. Informational, never blocking. */
+export interface RequestConcern {
+	code:
+		| 'signedRequest'
+		| 'wasmSigned'
+		| 'botChallenge'
+		| 'csrfDependency'
+		| 'shortLivedToken'
+		| 'encryptedBody'
+		| 'graphql'
+	message: string
+}

package/src/provider/secrets.ts

@@ -0,0 +1,29 @@
+const SECRET_EXACT = new Set(['cookie', 'authorization', 'proxy-authorization'])
+
+const SECRET_SUFFIXES = ['-token', '-key', '-secret', '-auth']
+
+export function classifyHeader(name: string): boolean {
+	const lower = name.toLowerCase()
+	if(SECRET_EXACT.has(lower)) {
+		return true
+	}
+
+	return SECRET_SUFFIXES.some((s) => lower.endsWith(s))
+}
+
+export function splitSecrets(headers: Record<string, string>): {
+	secrets: Record<string, string>
+	publics: Record<string, string>
+} {
+	const secrets: Record<string, string> = {}
+	const publics: Record<string, string> = {}
+	for(const [k, v] of Object.entries(headers)) {
+		if(classifyHeader(k)) {
+			secrets[k] = v
+		} else {
+			publics[k] = v
+		}
+	}
+
+	return { secrets, publics }
+}

package/src/provider/to-version.ts

@@ -0,0 +1,90 @@
+import type { ReclaimClient } from '@reclaimprotocol/client'
+import type {
+	CreateProviderVersionRequest as CreateVersionBody,
+	ProviderVersionRef as VersionRef,
+} from '../types/openapi.ts'
+import type { ReclaimProvider } from './schema.ts'
+
+/**
+ * Translate a drafted ReclaimProvider into the body for
+ * POST /providers/{providerId}/versions.
+ *
+ * `initialUrl` is the landing page the user navigated to during
+ * capture — distinct from `provider.url` which is the specific
+ * API URL the attestor replays.
+ *
+ * Secrets are NOT persisted — the verification client re-supplies
+ * them at runtime via `credentials: 'include'`.
+ */
+export function providerToCreateVersionRequest(
+	provider: ReclaimProvider,
+	initialUrl: string,
+	notes?: string,
+	version?: VersionRef,
+): CreateVersionBody {
+	// Inline responseRedactions into matches[*].extract (1-to-1 by index).
+	const matches = (provider.responseMatches ?? []).map((match, i) => {
+		const redaction = provider.responseRedactions?.[i]
+		return {
+			type: match.type,
+			value: match.value,
+			isOptional: false,
+			...(redaction ? { extract: redaction } : {}),
+		}
+	})
+
+	return {
+		version: version ?? { major: 1, minor: 0, patch: 0 },
+		initialUrl,
+		requests: [
+			{
+				url: provider.url,
+				method: provider.method,
+				credentials: 'include',
+				...(provider.body ? { requestBodyTemplate: provider.body } : {}),
+				...(matches.length > 0 ? { matches } : {}),
+			},
+		],
+		allowedJsRequests: [],
+		webSettings: { geoLocation: '{{DYNAMIC_GEO}}' },
+		...(provider.paramValues
+			? { requiredParameters: provider.paramValues }
+			: {}),
+		...(notes ? { notes } : {}),
+	}
+}
+
+/**
+ * Fetch the current versions for a provider and return the next version above
+ * the highest existing one (bumping the patch number), or 1.0.0 when the
+ * provider has no versions yet. A failed lookup propagates — silently
+ * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
+ */
+export async function nextVersion(
+	client: ReclaimClient,
+	providerId: string,
+): Promise<VersionRef> {
+	const list = (await client.call('ListProviderVersions', {
+		params: { providerId },
+		query: {},
+	})) as { items?: Array<{ version: VersionRef }> }
+
+	if(!list.items?.length) {
+		return { major: 1, minor: 0, patch: 0 }
+	}
+
+	// Find the highest version and bump its patch
+	let hi = list.items[0].version
+	for(const item of list.items) {
+		const v = item.version
+		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)
+		) {
+			hi = v
+		}
+	}
+
+	return { major: hi.major, minor: hi.minor, patch: hi.patch + 1 }
+}

package/src/types/openapi.ts

@@ -0,0 +1,7 @@
+import type { components } from '@reclaimprotocol/client'
+
+export type CredentialAttachSession =
+	components['schemas']['CredentialAttachSession']
+export type CreateProviderVersionRequest =
+	components['schemas']['CreateProviderVersionRequest']
+export type ProviderVersionRef = components['schemas']['ProviderVersionRef']