F2F-1528 rtcv scraper protocol routes proxyen via app

.env.example

@@ -9,6 +9,12 @@ RTCV_SERVER=http://rtcv_key_ID_here:rtcv_key_here@localhost:4000
 # This can be set to a staging server so we don't have to run 2 instances of a scraper
 # RTCV_ALTERNATIVE_SERVER=http://rtcv_key_ID_here:rtcv_key_here@localhost:4000
 
+# Optional: route requests through the F2F App instead of directly to RT-CV
+# Uses f2f:// (http) or f2fs:// (https) protocol to distinguish from RTCV_SERVER basic auth
+# RTCV_SERVER is still required for incoming callback authentication
+# F2F_APP=f2fs://keyId:keySecret@app.first2find.nl
+# F2F_ALTERNATIVE_APP=f2fs://keyId:keySecret@app.first2find.nl
+
 # Set to true to skip the alive check that checks if the scraper is allowed to scrape.
 # This is useful for local development when a scraper is disabled on RT-CV.
 # DO NOT DEPLOY A SCRAPER WITH THIS ENABLED!

lib/app_auth.ts

@@ -0,0 +1,67 @@
+/**
+ * Challenge-response authentication for the f2f-app.
+ *
+ * Flow:
+ * 1. POST /api/tokens/challenge {nameSlug} -> {challenge}
+ * 2. proof = lowercase(hex(sha512(challenge + secret)))
+ * 3. POST /api/tokens/exchange {nameSlug, proof} -> {token}
+ * 4. Cache token for 8 minutes (tokens are valid 10 min, 2 min buffer)
+ */
+
+const TOKEN_CACHE_DURATION_MS = 8 * 60 * 1000
+
+export interface AppAuth {
+	url: string // from F2F_APP origin
+	keyId: string // from F2F_APP, API token nameSlug
+	keySecret: string // from F2F_APP, API token secret
+}
+
+export class AppTokenManager {
+	private token: string | null = null
+	private tokenExpiresAt: number = 0
+
+	constructor(private auth: AppAuth) {}
+
+	async getToken(): Promise<string> {
+		if (this.token && Date.now() < this.tokenExpiresAt) {
+			return this.token
+		}
+
+		return await this.authenticate()
+	}
+
+	private async authenticate(): Promise<string> {
+		const base = this.auth.url + "/api/tokens"
+		const headers = { "Content-Type": "application/json" }
+
+		// 1. Request challenge
+		const challengeRes = await fetch(`${base}/challenge`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({ nameSlug: this.auth.keyId }),
+		})
+		if (!challengeRes.ok) throw new Error(`F2F App challenge failed (${challengeRes.status}): ${await challengeRes.text()}`)
+		const { challenge } = await challengeRes.json() as { challenge: string }
+
+		// 2. Calculate proof (SHA-512)
+		const msgUint8 = new TextEncoder().encode(challenge + this.auth.keySecret)
+		const hashBuffer = await crypto.subtle.digest("SHA-512", msgUint8)
+		const hashArray = Array.from(new Uint8Array(hashBuffer))
+		const proof = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("")
+
+		// 3. Exchange for token
+		const tokenRes = await fetch(`${base}/exchange`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({ nameSlug: this.auth.keyId, proof }),
+		})
+		if (!tokenRes.ok) throw new Error(`F2F App token exchange failed (${tokenRes.status}): ${await tokenRes.text()}`)
+		const { token } = await tokenRes.json() as { token: string }
+
+		// 4. Cache token
+		this.token = token
+		this.tokenExpiresAt = Date.now() + TOKEN_CACHE_DURATION_MS
+
+		return token
+	}
+}