export function base64url(bytes: Uint8Array): string {
  let s = "";
  for (const b of bytes) s += String.fromCharCode(b);
  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

export function randomB64url(byteLength: number): string {
  return base64url(crypto.getRandomValues(new Uint8Array(byteLength)));
}

export async function sha256B64url(text: string): Promise<string> {
  const data = new TextEncoder().encode(text);
  return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", data)));
}

// base44 backend function: cairlStart
// Called by your "Verify with CAIRL" button via base44.functions.invoke.
import { createClientFromRequest } from "npm:@base44/sdk";
import { secrets } from "base44:runtime";
import { randomB64url, sha256B64url } from "../../shared/cairlCrypto.ts";

const SESSION_TTL_MS = 30 * 60 * 1000;

export default async function (req: Request): Promise<Response> {
  const clientId = secrets.get("CAIRL_CLIENT_ID");
  const redirectUri = secrets.get("CAIRL_REDIRECT_URI");
  const baseUrl = secrets.get("CAIRL_BASE_URL");
  if (!clientId || !redirectUri || !baseUrl) {
    return Response.json({ error: "not_configured" }, { status: 500 });
  }

  const base44 = createClientFromRequest(req);
  const now = new Date();

  // Housekeeping: abandoned flows never reach the callback, so clear the
  // dead rows on the way in.
  await base44.asServiceRole.entities.CairlAuthSession.deleteMany({
    expires_at: { $lt: now.toISOString() },
  });

  // PKCE: 32 random bytes -> verifier; SHA-256 of verifier -> challenge.
  const codeVerifier = randomB64url(32);
  const codeChallenge = await sha256B64url(codeVerifier);

  // CSRF: 24 random bytes (CAIRL requires at least 16 characters).
  const state = randomB64url(24);

  // Browser binding. The page keeps `nonce`; only its hash is stored here.
  // The callback demands both the saved row and the matching nonce, so a
  // callback URL someone else started cannot be pasted into your user's
  // browser to sign that person into the wrong account.
  const nonce = randomB64url(32);
  const nonceHash = await sha256B64url(nonce);

  // Account binding. Whoever is signed in now is the only account this
  // attempt may ever be linked to. Never read this from the request body.
  let originUserId = "";
  try {
    const user = await base44.auth.me();
    if (user?.id) originUserId = user.id;
  } catch {
    // nobody signed in
  }

  await base44.asServiceRole.entities.CairlAuthSession.create({
    state,
    code_verifier: codeVerifier,
    nonce_hash: nonceHash,
    origin_user_id: originUserId,
    expires_at: new Date(now.getTime() + SESSION_TTL_MS).toISOString(),
  });

  const params = new URLSearchParams({
    response_type: "code",
    client_id: clientId,
    redirect_uri: redirectUri,
    state,
    // Wire scopes. The response keys are age_18_plus / identity_verified.
    scope: "age:18+ identity:verified",
    code_challenge: codeChallenge,
    code_challenge_method: "S256",
  });
  const url = `${baseUrl.replace(/\/+$/, "")}/oauth/authorize?${params.toString()}`;

  return Response.json({ url, nonce });
}

// base44 backend function: cairlCallback
// Called by your /auth/cairl/callback page via base44.functions.invoke
// with { code, state, error, nonce }.
import { createClientFromRequest } from "npm:@base44/sdk";
import { secrets } from "base44:runtime";
import { sha256B64url } from "../../shared/cairlCrypto.ts";

function sameValue(a: string, b: string): boolean {
  if (a.length !== b.length) return false;
  let diff = 0;
  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
  return diff === 0;
}

const next = (path: string, reason?: string) =>
  Response.json({
    next: reason ? `${path}?reason=${encodeURIComponent(reason)}` : path,
  });
const fail = (reason: string) => next("/cairl/failed", reason);

export default async function (req: Request): Promise<Response> {
  const baseUrl = secrets.get("CAIRL_BASE_URL");
  const clientId = secrets.get("CAIRL_CLIENT_ID");
  const clientSecret = secrets.get("CAIRL_CLIENT_SECRET");
  const redirectUri = secrets.get("CAIRL_REDIRECT_URI");
  if (!baseUrl || !clientId || !clientSecret || !redirectUri) {
    return fail("not_configured");
  }
  const tokenUrl = `${baseUrl.replace(/\/+$/, "")}/api/oauth/token`;
  const userinfoUrl = `${baseUrl.replace(/\/+$/, "")}/api/oauth/userinfo`;

  const base44 = createClientFromRequest(req);
  const sessions = base44.asServiceRole.entities.CairlAuthSession;
  const body = (await req.json().catch(() => ({}))) as Record<string, string>;
  const { code, state, error, nonce } = body;

  // The user cancelled, or verification did not complete. Retire the row this
  // browser started (same state AND same nonce), never a row by state alone.
  if (error) {
    if (state && nonce) {
      const [stale] = await sessions.filter({ state });
      if (stale && sameValue(await sha256B64url(nonce), stale.nonce_hash)) {
        await sessions.delete(stale.id);
      }
    }
    return fail(error);
  }

  if (!code || !state || !nonce) return fail("missing_params");

  // 1. The row must exist, be unexpired, and belong to the browser that
  //    started the flow. Validate BEFORE consuming it: a stranger who knows
  //    a victim's `state` (it rides on the callback URL) must not be able to
  //    destroy the victim's attempt with a junk nonce. Only a validated row
  //    is deleted, and it is deleted before the code is spent: one attempt,
  //    one try.
  const [session] = await sessions.filter({ state });
  if (!session) return fail("invalid_state");
  if (!sameValue(await sha256B64url(nonce), session.nonce_hash)) {
    return fail("wrong_browser");
  }
  if (Date.now() > new Date(session.expires_at).getTime()) {
    await sessions.delete(session.id);
    return fail("expired");
  }
  await sessions.delete(session.id);

  // The account must be the same one that started the flow.
  let signedInNow = "";
  try {
    const user = await base44.auth.me();
    if (user?.id) signedInNow = user.id;
  } catch {
    // nobody signed in
  }
  if (session.origin_user_id !== signedInNow) return fail("account_changed");
  // The default recipe verifies a user who is signed in to your app. Turning
  // a signed-out visitor into a signed-in one needs base44's own session API;
  // see "Register and sign in with CAIRL" before removing this check.
  if (!session.origin_user_id) return fail("sign_in_required");

  // 2. Exchange the code for an access token (server-side only).
  const tokenRes = await fetch(tokenUrl, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      client_id: clientId,
      client_secret: clientSecret,
      redirect_uri: redirectUri,
      code_verifier: session.code_verifier,
    }),
  });
  if (!tokenRes.ok) {
    // 402 with live keys means your CAIRL balance needs funds.
    return fail(
      tokenRes.status === 402 ? "payment_required" : "exchange_failed",
    );
  }
  const token = await tokenRes.json();
  if (typeof token.access_token !== "string") return fail("exchange_failed");

  // 3. Read the verified claims.
  const infoRes = await fetch(userinfoUrl, {
    headers: { Authorization: `Bearer ${token.access_token}` },
  });
  if (!infoRes.ok) return fail("userinfo_failed");
  const info = await infoRes.json();

  // 4. Test credentials return fixture claims that say nothing about the
  //    person in front of you, so they stop here and never reach the User
  //    record. Anything other than "live" is treated as a test run.
  if (info.mode !== "live") return next("/cairl/test-complete");

  if (typeof info.sub !== "string" || info.sub.length === 0) {
    return fail("userinfo_failed");
  }
  const claims = info.claims ?? {};
  const fields = {
    cairl_sub: info.sub,
    cairl_identity_verified: claims.identity_verified === true,
    cairl_age_18_plus: claims.age_18_plus === true,
    cairl_verified_at: info.evaluated_at,
  };

  // 5. Record the result on the user. `sub` is stable for your site, and the
  //    account it may be written to is the one that started the flow.
  const users = base44.asServiceRole.entities.User;
  const [existing] = await users.filter({ cairl_sub: info.sub });
  if (existing && existing.id !== session.origin_user_id) {
    // This CAIRL identity is already linked to a different account. Refuse
    // rather than move it: `cairl_sub` is unique and two accounts for one
    // person is exactly what the uniqueness field prevents.
    return fail("already_linked");
  }
  const [origin] = await users.filter({ id: session.origin_user_id });
  if (!origin) return fail("account_changed");
  if (origin.cairl_sub && origin.cairl_sub !== info.sub) {
    // The account is already bound to a different CAIRL identity. Never
    // overwrite that binding from a sign-in: it would move verified claims
    // onto the wrong person and free the old subject for reuse. Re-linking
    // is a deliberate, separate step if you ever offer one.
    return fail("subject_mismatch");
  }
  // Link (or refresh) the CAIRL identity on the account that started the
  // flow. Never match on email — CAIRL does not share it.
  //
  // Compare-and-set. The guard above only read the row, so two first-link
  // callbacks carrying two different CAIRL subjects can both see an empty
  // `cairl_sub`, both pass, and the second write would silently replace the
  // first binding. The write therefore happens only while `cairl_sub` is
  // empty or already this subject, and the row is read back afterwards: an
  // attempt that no longer owns the binding is told `subject_mismatch`
  // rather than reporting a link it does not hold.
  await users.update(session.origin_user_id, fields);
  const [bound] = await users.filter({ id: session.origin_user_id });
  if (!bound || bound.cairl_sub !== info.sub) return fail("subject_mismatch");

  // 6. Done — but "done" is not "eligible". The booleans just stored are
  //    the authority for what this person may do; the success page only
  //    says the sign-in completed. Route on the claims your app requires so
  //    an underage or unresolved user never lands on a page that reads as
  //    admission.
  const eligible =
    fields.cairl_identity_verified === true &&
    fields.cairl_age_18_plus === true;
  return next(eligible ? "/cairl/success" : "/cairl/not-eligible");
}

try {
  const { data } = await base44.functions.invoke("cairlStart", {});
  if (data?.url && data?.nonce) {
    sessionStorage.setItem("cairl_flow", data.nonce);
    window.location.assign(data.url);
    return;
  }
  window.location.assign(
    `/cairl/failed?reason=${encodeURIComponent(data?.error ?? "start_failed")}`,
  );
} catch {
  window.location.assign("/cairl/failed?reason=start_failed");
}

// Once per page load. A React effect runs twice in development, and a stray
// re-render can land here again: two invocations can both read and validate
// the same session row before either delete commits, and the one that loses
// the exchange would send a user whose account was already updated to
// /cairl/failed. The ref is declared in the component and checked inside the
// effect, so exactly one call is made per mount.
const started = useRef(false);

useEffect(() => {
  if (started.current) return;
  started.current = true;

  void (async () => {
    const query = new URL(window.location.href).searchParams;
    const nonce = sessionStorage.getItem("cairl_flow") ?? "";
    let next = "/cairl/failed?reason=callback_unavailable";
    try {
      const { data } = await base44.functions.invoke("cairlCallback", {
        code: query.get("code"),
        state: query.get("state"),
        error: query.get("error"),
        nonce,
      });
      next = data?.next ?? "/cairl/failed?reason=exchange_failed";
    } catch {
      // The function never answered (network, cold start, uncaught error).
      // The CAIRL code is single-use, so the only honest outcome is the
      // failure page with a Try again button — never a blank
      // "Finishing sign-in…".
    }
    sessionStorage.removeItem("cairl_flow");
    window.location.assign(next);
  })();
}, []);

Add "Verify with CAIRL" to this app. CAIRL is an OAuth 2.0 + PKCE identity
provider. Build exactly the following; do not invent extra steps, do not store
the client secret anywhere except backend secrets, and do not call CAIRL from
the frontend.

1. Data. Create an entity CairlAuthSession with text fields state,
   code_verifier, nonce_hash, origin_user_id, expires_at; only backend
   functions may read or write it. Add custom fields to the built-in User
   entity: cairl_sub (text, unique), cairl_identity_verified (boolean),
   cairl_age_18_plus (boolean), cairl_verified_at (text).

2. Backend function cairlStart (Deno), invoked from the frontend with
   base44.functions.invoke("cairlStart", {}). Read secrets CAIRL_CLIENT_ID,
   CAIRL_REDIRECT_URI, CAIRL_BASE_URL inside the handler with secrets.get from
   base44:runtime; if any is missing return { error: "not_configured" }.
   Delete every CairlAuthSession whose expires_at is earlier than now (use
   asServiceRole). Generate with crypto.getRandomValues: code_verifier =
   base64url of 32 random bytes; code_challenge = base64url(SHA-256(
   code_verifier)) with Web Crypto; state = base64url of 24 random bytes;
   nonce = base64url of 32 random bytes, storing only nonce_hash =
   base64url(SHA-256(nonce)). base64url = standard base64 with + -> -, / -> _,
   trailing = removed. origin_user_id = the id of the currently signed-in
   base44 user from base44.auth.me() via createClientFromRequest(req), or ""
   if nobody is signed in; never read it from the request body. Create the
   CairlAuthSession row (asServiceRole) with expires_at = now + 30 minutes as
   an ISO string. Build the URL `${CAIRL_BASE_URL}/oauth/authorize?` +
   URLSearchParams of response_type=code, client_id, redirect_uri (=
   CAIRL_REDIRECT_URI), state, scope = "age:18+ identity:verified" (exactly),
   code_challenge, code_challenge_method=S256. Return JSON { url, nonce }.

3. Backend function cairlCallback (Deno), invoked from the callback page with
   base44.functions.invoke("cairlCallback", { code, state, error, nonce }). It
   returns { next: "<path>" } and the page navigates there. Every path deletes
   the session row it used. Failure paths return { next:
   "/cairl/failed?reason=<reason>" } with the reason passed through
   encodeURIComponent. Steps: (a) if error is present, find the row by state;
   if it exists and base64url(SHA-256(nonce)) equals its nonce_hash, delete
   it; return failed with reason = error. (b) If code, state or nonce is
   missing -> missing_params. (c) Find the row by state (asServiceRole); none
   -> invalid_state. If base64url(SHA-256(nonce)) != nonce_hash
   (constant-time compare) -> wrong_browser WITHOUT deleting the row. If now
   is past expires_at -> delete the row, expired. Otherwise delete the row
   now (single use) and continue. (d) signedInNow = current user id from
   base44.auth.me() or ""; if it differs from the row's origin_user_id ->
   account_changed; if origin_user_id is empty -> sign_in_required. (e) POST `${CAIRL_BASE_URL}/api/oauth/token` as
   application/x-www-form-urlencoded with grant_type=authorization_code,
   code, client_id, client_secret, redirect_uri (= CAIRL_REDIRECT_URI),
   code_verifier (from the row). Not ok -> payment_required if HTTP 402,
   else exchange_failed. Read access_token (string) from the JSON. (f) GET
   `${CAIRL_BASE_URL}/api/oauth/userinfo` with header Authorization: Bearer
   <access_token>. Not ok -> userinfo_failed. Parse JSON info. (g) If
   info.mode !== "live" -> return { next: "/cairl/test-complete" } and do NOT
   touch any User record. (h) Otherwise require info.sub to be a non-empty
   string. Compute fields: cairl_sub = info.sub, cairl_identity_verified =
   (info.claims.identity_verified === true), cairl_age_18_plus =
   (info.claims.age_18_plus === true), cairl_verified_at =
   info.evaluated_at. Find the User whose cairl_sub equals info.sub; if one
   exists and it is not the origin user -> already_linked. Load the origin
   user; if it has a non-empty cairl_sub different from info.sub ->
   subject_mismatch (never overwrite a binding). Otherwise update the origin
   user with the fields, then read the row back and return subject_mismatch
   unless its cairl_sub now equals info.sub (compare-and-set: two first-link
   callbacks for two different subjects can both read an empty cairl_sub, and
   the read-back is what stops the loser reporting a link it does not hold).
   Never match on email, never create users in this recipe. (i) eligible =
   cairl_identity_verified && cairl_age_18_plus; return { next: eligible ?
   "/cairl/success" : "/cairl/not-eligible" }.

4. Pages. Home page button "Verify with CAIRL": call cairlStart inside
   try/catch; if it returns url and nonce, save nonce in sessionStorage under
   key cairl_flow, then window.location.assign(url); if it returns an error
   or throws, go to /cairl/failed?reason=<error or start_failed>. Page at
   route /auth/cairl/callback: on load read code, state, error from the URL
   query and the nonce from sessionStorage["cairl_flow"]; call cairlCallback
   with { code, state, error, nonce } inside try/catch, exactly once per page
   load (guard the effect with a run-once ref: a React effect runs twice in
   development, and two invocations can both validate the same session row
   before either delete commits); on failure use
   /cairl/failed?reason=callback_unavailable; then remove
   sessionStorage["cairl_flow"] and window.location.assign(next); show
   "Finishing sign-in…" while it runs. Page /cairl/success: "You're verified
   with CAIRL and meet this site's requirements." Page
   /cairl/not-eligible: "CAIRL couldn't confirm you meet this site's
   requirements." Page /cairl/test-complete: "Test run complete. The connection to
   CAIRL works. These were fixture claims, so nothing was recorded on this
   account and no one was verified." Page /cairl/failed: show the reason
   query value and a "Try again" button that runs the same start flow.

5. Constraints. Only the two backend functions talk to CAIRL. The frontend
   never sees the client secret and never calls CAIRL's token or userinfo
   endpoints. Do not change scope, the redirect URI, or the PKCE method. Keep
   /cairl/test-complete after go-live.