BitRobot Connect examples

Copy-ready implementations of the routes from the BitRobot Connect guide.

Backend implementations

Each example implements GET /bitrobot/connect and POST /bitrobot/connect/confirm, stores request_id and nonce in the server-side session, and reads BITROBOT_API_KEY, BITROBOT_SUBNET_ID, and BITROBOT_API_BASE from the environment. Replace the login guard (requireLogin, current_user, and so on) with your own. If your API is stateless, use the stateless hold instead of the session. The confirm route must reject any request without a valid CSRF token. The Sinatra, Laravel, Spring Boot, and ASP.NET examples use their framework’s own guard. In the Express, FastAPI, and Go examples, replace the CSRF guard placeholder with your own, the same way you replace the login guard.

// routes/bitrobot-connect.js
const express = require("express");
const crypto = require("node:crypto");
const { requireLogin } = require("../middleware/auth"); // your existing login guard
const { csrfProtection } = require("../middleware/csrf"); // your existing CSRF guard

const router = express.Router();

const BITROBOT_API_BASE = process.env.BITROBOT_API_BASE || "https://api.bitrobot.ai";
const BITROBOT_API_KEY = process.env.BITROBOT_API_KEY;
const BITROBOT_SUBNET_ID = process.env.BITROBOT_SUBNET_ID;

// Landing page. Needs a server-side session (for example express-session) mounted before this router.
router.get("/bitrobot/connect", requireLogin, (req, res) => {
  const { request_id: requestId, nonce } = req.query;
  if (typeof requestId !== "string" || typeof nonce !== "string") {
    return res.status(400).send("Missing request_id or nonce");
  }

  req.session.bitrobotConnect = { requestId, nonce };
  res.render("bitrobot-connect", { walletAddress: req.user.walletAddress });
});

// Confirm handler. The Connect button on the landing page posts here.
router.post("/bitrobot/connect/confirm", requireLogin, csrfProtection, async (req, res) => {
  const pending = req.session.bitrobotConnect;
  if (!pending) {
    return res.status(400).send("No connection in progress");
  }

  const response = await fetch(
    `${BITROBOT_API_BASE}/subnets/${BITROBOT_SUBNET_ID}/connect/confirm`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${BITROBOT_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": crypto.randomUUID(),
      },
      body: JSON.stringify({
        request_id: pending.requestId,
        nonce: pending.nonce,
        wallet_address: req.user.walletAddress,
        subnet_user_id: String(req.user.id),
      }),
    }
  );
  const body = await response.json();

  // Branch on auth_code, not the status. Never log or render auth_code.
  const returnUrl = safeReturnUrl(body.return_url);
  if (!body.auth_code || !returnUrl) {
    return res
      .status(400)
      .render("bitrobot-connect-error", { error: body.error, reason: body.reason });
  }

  delete req.session.bitrobotConnect;

  // Redirect to return_url verbatim, fragment included.
  res.redirect(303, returnUrl);
});

// Allow http(s) URLs only. Return the string as given.
function safeReturnUrl(raw) {
  if (!raw) return null;
  try {
    const url = new URL(raw);
    return url.protocol === "https:" || url.protocol === "http:" ? raw : null;
  } catch {
    return null;
  }
}

module.exports = router;

# app/bitrobot_connect.py
import os
import uuid
from urllib.parse import urlsplit

import httpx
from fastapi import APIRouter, Depends, HTTPException, Request
from fastapi.responses import HTMLResponse, RedirectResponse
from fastapi.templating import Jinja2Templates

from app.auth import current_user  # your existing login dependency
from app.csrf import verify_csrf  # your existing CSRF dependency

# Needs SessionMiddleware on the app:
#   app.add_middleware(SessionMiddleware, secret_key=os.environ["SESSION_SECRET"])
router = APIRouter()
templates = Jinja2Templates(directory="templates")

BITROBOT_API_BASE = os.environ.get("BITROBOT_API_BASE", "https://api.bitrobot.ai")
BITROBOT_API_KEY = os.environ["BITROBOT_API_KEY"]
BITROBOT_SUBNET_ID = os.environ["BITROBOT_SUBNET_ID"]


# Landing page.
@router.get("/bitrobot/connect", response_class=HTMLResponse)
async def landing(request: Request, request_id: str, nonce: str, user=Depends(current_user)):
    request.session["bitrobot_connect"] = {"request_id": request_id, "nonce": nonce}
    return templates.TemplateResponse(
        "bitrobot_connect.html",
        {"request": request, "wallet_address": user.wallet_address},
    )


# Confirm handler. The Connect button on the landing page posts here.
@router.post("/bitrobot/connect/confirm")
async def confirm(request: Request, user=Depends(current_user), _=Depends(verify_csrf)):
    pending = request.session.get("bitrobot_connect")
    if not pending:
        raise HTTPException(status_code=400, detail="No connection in progress")

    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.post(
            f"{BITROBOT_API_BASE}/subnets/{BITROBOT_SUBNET_ID}/connect/confirm",
            headers={
                "Authorization": f"Bearer {BITROBOT_API_KEY}",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={
                "request_id": pending["request_id"],
                "nonce": pending["nonce"],
                "wallet_address": user.wallet_address,
                "subnet_user_id": str(user.id),
            },
        )
    body = response.json()

    # Branch on auth_code, not the status. Never log or render auth_code.
    return_url = safe_return_url(body.get("return_url"))
    if not body.get("auth_code") or return_url is None:
        return templates.TemplateResponse(
            "bitrobot_connect_error.html",
            {"request": request, "error": body.get("error"), "reason": body.get("reason")},
            status_code=400,
        )

    request.session.pop("bitrobot_connect", None)

    # Redirect to return_url verbatim, fragment included.
    return RedirectResponse(return_url, status_code=303)


# Allow http(s) URLs only. Return the string as given.
def safe_return_url(raw):
    if not raw:
        return None
    scheme = urlsplit(raw).scheme.lower()
    return raw if scheme in ("http", "https") else None

# bitrobot_connect.rb
require "sinatra"
require "rack/protection"
require "net/http"
require "json"
require "securerandom"

enable :sessions

# Escapes `<%= %>` output in the templates below. Sinatra's ERB does not do this
# on its own.
set :erb, escape_html: true

# Rejects a POST without a valid authenticity token. Render
# `Rack::Protection::AuthenticityToken.token(session)` into a hidden
# `authenticity_token` field in your form.
use Rack::Protection::AuthenticityToken

BITROBOT_API_BASE = ENV.fetch("BITROBOT_API_BASE", "https://api.bitrobot.ai")
BITROBOT_API_KEY = ENV.fetch("BITROBOT_API_KEY")
BITROBOT_SUBNET_ID = ENV.fetch("BITROBOT_SUBNET_ID")

# Landing page.
get "/bitrobot/connect" do
  require_login! # your existing login guard
  if params[:request_id].to_s.empty? || params[:nonce].to_s.empty?
    halt 400, "Missing request_id or nonce"
  end

  session[:bitrobot_connect] = { "request_id" => params[:request_id], "nonce" => params[:nonce] }
  erb :bitrobot_connect, locals: { wallet_address: current_user.wallet_address }
end

# Confirm handler. The Connect button on the landing page posts here.
post "/bitrobot/connect/confirm" do
  require_login!
  pending = session[:bitrobot_connect]
  halt 400, "No connection in progress" unless pending

  uri = URI("#{BITROBOT_API_BASE}/subnets/#{BITROBOT_SUBNET_ID}/connect/confirm")
  http_request = Net::HTTP::Post.new(uri)
  http_request["Authorization"] = "Bearer #{BITROBOT_API_KEY}"
  http_request["Content-Type"] = "application/json"
  http_request["Idempotency-Key"] = SecureRandom.uuid
  http_request.body = JSON.generate(
    request_id: pending["request_id"],
    nonce: pending["nonce"],
    wallet_address: current_user.wallet_address,
    subnet_user_id: current_user.id.to_s
  )

  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(http_request) }
  body = JSON.parse(response.body)

  # Branch on auth_code, not the status. Never log or render auth_code.
  return_url = safe_return_url(body["return_url"])
  if body["auth_code"].to_s.empty? || return_url.nil?
    halt 400, erb(:bitrobot_connect_error, locals: { error: body["error"], reason: body["reason"] })
  end

  session.delete(:bitrobot_connect)

  # Redirect to return_url verbatim, fragment included.
  redirect return_url, 303
end

# Allow http(s) URLs only. Return the string as given.
def safe_return_url(raw)
  return nil if raw.to_s.empty?

  uri = URI.parse(raw)
  uri.is_a?(URI::HTTP) ? raw : nil
rescue URI::InvalidURIError
  nil
end

// bitrobot_connect.go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"html/template"
	"net/http"
	"net/url"
	"os"

	"github.com/google/uuid"
	"github.com/gorilla/sessions" // any server-side session store works
)

var (
	bitrobotAPIBase  = envOr("BITROBOT_API_BASE", "https://api.bitrobot.ai")
	bitrobotAPIKey   = os.Getenv("BITROBOT_API_KEY")
	bitrobotSubnetID = os.Getenv("BITROBOT_SUBNET_ID")
	sessionStore     = sessions.NewCookieStore([]byte(os.Getenv("SESSION_SECRET")))
	templates        = template.Must(template.ParseGlob("templates/*.html"))
)

type confirmResponse struct {
	Status    string `json:"status"`
	ReturnURL string `json:"return_url"`
	AuthCode  string `json:"auth_code"` // Check its presence only. Never log or render it.
	Error     string `json:"error"`
	Reason    string `json:"reason"`
}

// Landing page.
func connectLanding(w http.ResponseWriter, r *http.Request) {
	user, ok := currentUser(r) // your existing login guard
	if !ok {
		redirectToLogin(w, r)
		return
	}
	requestID, nonce := r.URL.Query().Get("request_id"), r.URL.Query().Get("nonce")
	if requestID == "" || nonce == "" {
		http.Error(w, "Missing request_id or nonce", http.StatusBadRequest)
		return
	}

	session, _ := sessionStore.Get(r, "app")
	session.Values["bitrobot_request_id"] = requestID
	session.Values["bitrobot_nonce"] = nonce
	if err := session.Save(r, w); err != nil {
		http.Error(w, "Could not save session", http.StatusInternalServerError)
		return
	}
	templates.ExecuteTemplate(w, "bitrobot_connect.html", map[string]string{
		"WalletAddress": user.WalletAddress,
	})
}

// Confirm handler. The Connect button on the landing page posts here.
func connectConfirm(w http.ResponseWriter, r *http.Request) {
	user, ok := currentUser(r)
	if !ok {
		redirectToLogin(w, r)
		return
	}
	session, _ := sessionStore.Get(r, "app")
	requestID, _ := session.Values["bitrobot_request_id"].(string)
	nonce, _ := session.Values["bitrobot_nonce"].(string)
	if requestID == "" || nonce == "" {
		http.Error(w, "No connection in progress", http.StatusBadRequest)
		return
	}

	payload, _ := json.Marshal(map[string]string{
		"request_id":     requestID,
		"nonce":          nonce,
		"wallet_address": user.WalletAddress,
		"subnet_user_id": user.ID,
	})
	req, _ := http.NewRequest(
		http.MethodPost,
		fmt.Sprintf("%s/subnets/%s/connect/confirm", bitrobotAPIBase, bitrobotSubnetID),
		bytes.NewReader(payload),
	)
	req.Header.Set("Authorization", "Bearer "+bitrobotAPIKey)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", uuid.NewString())

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		http.Error(w, "BitRobot is unreachable, please try again", http.StatusBadGateway)
		return
	}
	defer resp.Body.Close()

	var body confirmResponse
	_ = json.NewDecoder(resp.Body).Decode(&body)

	// Branch on auth_code, not the status.
	returnURL := safeReturnURL(body.ReturnURL)
	if body.AuthCode == "" || returnURL == "" {
		w.WriteHeader(http.StatusBadRequest)
		templates.ExecuteTemplate(w, "bitrobot_connect_error.html", map[string]string{
			"Error": body.Error, "Reason": body.Reason,
		})
		return
	}

	delete(session.Values, "bitrobot_request_id")
	delete(session.Values, "bitrobot_nonce")
	_ = session.Save(r, w)

	// Redirect to return_url verbatim, fragment included.
	http.Redirect(w, r, returnURL, http.StatusSeeOther)
}

// Allow http(s) URLs only. Return the string as given.
func safeReturnURL(raw string) string {
	parsed, err := url.Parse(raw)
	if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") {
		return ""
	}
	return raw
}

func envOr(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /bitrobot/connect", connectLanding)
	mux.HandleFunc("POST /bitrobot/connect/confirm", connectConfirm)

	// csrfProtect is your existing CSRF middleware.
	http.ListenAndServe(":8080", csrfProtect(mux))
}

<?php
// app/Http/Controllers/BitRobotConnectController.php
//
// routes/web.php: the `web` group verifies the CSRF token on the POST. Add
// `@csrf` to the form.
//   Route::get('/bitrobot/connect', [BitRobotConnectController::class, 'landing'])->middleware('auth');
//   Route::post('/bitrobot/connect/confirm', [BitRobotConnectController::class, 'confirm'])->middleware('auth');
//
// config/services.php:
//   'bitrobot' => [
//       'api_base' => env('BITROBOT_API_BASE', 'https://api.bitrobot.ai'),
//       'api_key' => env('BITROBOT_API_KEY'),
//       'subnet_id' => env('BITROBOT_SUBNET_ID'),
//   ],

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

class BitRobotConnectController extends Controller
{
    // Landing page.
    public function landing(Request $request)
    {
        $validated = $request->validate([
            'request_id' => 'required|string',
            'nonce' => 'required|string',
        ]);

        $request->session()->put('bitrobot_connect', $validated);

        return view('bitrobot.connect', [
            'walletAddress' => $request->user()->wallet_address,
        ]);
    }

    // Confirm handler. The Connect button on the landing page posts here.
    public function confirm(Request $request)
    {
        $pending = $request->session()->get('bitrobot_connect');
        abort_unless($pending, 400, 'No connection in progress');

        $baseUrl = config('services.bitrobot.api_base');
        $subnetId = config('services.bitrobot.subnet_id');

        $response = Http::withToken(config('services.bitrobot.api_key'))
            ->withHeaders(['Idempotency-Key' => (string) Str::uuid()])
            ->post("{$baseUrl}/subnets/{$subnetId}/connect/confirm", [
                'request_id' => $pending['request_id'],
                'nonce' => $pending['nonce'],
                'wallet_address' => $request->user()->wallet_address,
                'subnet_user_id' => (string) $request->user()->id,
            ]);

        // Branch on auth_code, not the status. Never log or render auth_code.
        $returnUrl = $this->safeReturnUrl($response->json('return_url'));
        if (!$response->json('auth_code') || $returnUrl === null) {
            return response()->view('bitrobot.connect-error', [
                'error' => $response->json('error'),
                'reason' => $response->json('reason'),
            ], 400);
        }

        $request->session()->forget('bitrobot_connect');

        // Redirect to return_url verbatim, fragment included.
        return redirect()->away($returnUrl, 303);
    }

    // Allow http(s) URLs only. Return the string as given.
    private function safeReturnUrl(?string $raw): ?string
    {
        if (!$raw) {
            return null;
        }

        $scheme = strtolower((string) parse_url($raw, PHP_URL_SCHEME));

        return in_array($scheme, ['http', 'https'], true) ? $raw : null;
    }
}

// src/main/java/com/example/bitrobot/BitRobotConnectController.java
package com.example.bitrobot;

import java.net.URI;
import java.util.Map;
import java.util.UUID;

import jakarta.servlet.http.HttpSession;

import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.client.HttpStatusCodeException;
import org.springframework.web.client.RestClient;
import org.springframework.web.server.ResponseStatusException;

// Both routes sit behind your existing Spring Security login requirement, which
// also verifies the CSRF token on the POST.
// AppUser is your own principal type; it must expose the user's subnet wallet address.
@Controller
public class BitRobotConnectController {

    private static final ParameterizedTypeReference<Map<String, Object>> JSON_OBJECT =
            new ParameterizedTypeReference<>() {};

    private static final String BITROBOT_API_BASE =
            System.getenv().getOrDefault("BITROBOT_API_BASE", "https://api.bitrobot.ai");
    private static final String BITROBOT_API_KEY = System.getenv("BITROBOT_API_KEY");
    private static final String BITROBOT_SUBNET_ID = System.getenv("BITROBOT_SUBNET_ID");

    private final RestClient bitrobot = RestClient.builder()
            .baseUrl(BITROBOT_API_BASE)
            .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + BITROBOT_API_KEY)
            .build();

    // Landing page.
    @GetMapping("/bitrobot/connect")
    public String landing(@RequestParam("request_id") String requestId,
                          @RequestParam("nonce") String nonce,
                          @AuthenticationPrincipal AppUser user,
                          HttpSession session,
                          Model model) {
        session.setAttribute("bitrobotRequestId", requestId);
        session.setAttribute("bitrobotNonce", nonce);
        model.addAttribute("walletAddress", user.walletAddress());
        return "bitrobot-connect";
    }

    // Confirm handler. The Connect button on the landing page posts here.
    @PostMapping("/bitrobot/connect/confirm")
    public Object confirm(@AuthenticationPrincipal AppUser user, HttpSession session, Model model) {
        String requestId = (String) session.getAttribute("bitrobotRequestId");
        String nonce = (String) session.getAttribute("bitrobotNonce");
        if (requestId == null || nonce == null) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "No connection in progress");
        }

        Map<String, Object> body;
        try {
            body = bitrobot.post()
                    .uri("/subnets/{subnetId}/connect/confirm", BITROBOT_SUBNET_ID)
                    .contentType(MediaType.APPLICATION_JSON)
                    .header("Idempotency-Key", UUID.randomUUID().toString())
                    .body(Map.of(
                            "request_id", requestId,
                            "nonce", nonce,
                            "wallet_address", user.walletAddress(),
                            "subnet_user_id", String.valueOf(user.id())))
                    .retrieve()
                    .body(JSON_OBJECT);
        } catch (HttpStatusCodeException e) {
            // Read the body of a 4xx response too.
            body = e.getResponseBodyAs(JSON_OBJECT);
        }

        // Branch on auth_code, not the status. Never log or render auth_code.
        Object authCode = body == null ? null : body.get("auth_code");
        String returnUrl = safeReturnUrl(body == null ? null : body.get("return_url"));
        if (authCode == null || returnUrl == null) {
            model.addAttribute("error", body == null ? null : body.get("error"));
            model.addAttribute("reason", body == null ? null : body.get("reason"));
            return "bitrobot-connect-error";
        }

        session.removeAttribute("bitrobotRequestId");
        session.removeAttribute("bitrobotNonce");

        // Redirect to return_url verbatim, fragment included, with a 303.
        return ResponseEntity.status(HttpStatus.SEE_OTHER).header(HttpHeaders.LOCATION, returnUrl).build();
    }

    // Allow http(s) URLs only. Return the string as given.
    private static String safeReturnUrl(Object raw) {
        if (!(raw instanceof String value) || value.isBlank()) {
            return null;
        }
        try {
            String scheme = URI.create(value).getScheme();
            return "http".equalsIgnoreCase(scheme) || "https".equalsIgnoreCase(scheme) ? value : null;
        } catch (IllegalArgumentException e) {
            return null;
        }
    }
}

// Program.cs
using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Serialization;
using Microsoft.AspNetCore.Antiforgery;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();
builder.Services.AddAntiforgery();
builder.Services.AddHttpClient("bitrobot", client =>
{
    client.BaseAddress = new Uri(
        Environment.GetEnvironmentVariable("BITROBOT_API_BASE") ?? "https://api.bitrobot.ai");
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
        "Bearer", Environment.GetEnvironmentVariable("BITROBOT_API_KEY"));
});
// Plus your existing authentication/authorization registration.

var app = builder.Build();
app.UseSession();
app.UseAntiforgery();

var subnetId = Environment.GetEnvironmentVariable("BITROBOT_SUBNET_ID");

// Landing page.
app.MapGet("/bitrobot/connect", (HttpContext http, IAntiforgery antiforgery, string request_id, string nonce) =>
{
    var user = http.CurrentUser(); // your existing helper for the signed-in user

    http.Session.SetString("bitrobot_request_id", request_id);
    http.Session.SetString("bitrobot_nonce", nonce);

    // Sets the antiforgery cookie and returns the token for the form.
    var tokens = antiforgery.GetAndStoreTokens(http);
    return Results.Content(ConfirmPage(user.WalletAddress, tokens.RequestToken), "text/html");
}).RequireAuthorization();

// Confirm handler. The Connect button on the landing page posts here.
app.MapPost("/bitrobot/connect/confirm", async (HttpContext http, IHttpClientFactory clients, IAntiforgery antiforgery) =>
{
    // Throws if the request carries no valid CSRF (antiforgery) token.
    try
    {
        await antiforgery.ValidateRequestAsync(http);
    }
    catch (AntiforgeryValidationException)
    {
        return Results.BadRequest("Invalid CSRF token");
    }

    var user = http.CurrentUser();
    var requestId = http.Session.GetString("bitrobot_request_id");
    var nonce = http.Session.GetString("bitrobot_nonce");
    if (requestId is null || nonce is null)
    {
        return Results.BadRequest("No connection in progress");
    }

    var client = clients.CreateClient("bitrobot");
    using var message = new HttpRequestMessage(HttpMethod.Post, $"/subnets/{subnetId}/connect/confirm")
    {
        Content = JsonContent.Create(new
        {
            request_id = requestId,
            nonce,
            wallet_address = user.WalletAddress,
            subnet_user_id = user.Id.ToString(),
        }),
    };
    message.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());

    var response = await client.SendAsync(message);
    var body = await response.Content.ReadFromJsonAsync<ConfirmResponse>();

    // Branch on auth_code, not the status. Never log or render auth_code.
    var returnUrl = SafeReturnUrl(body?.ReturnUrl);
    if (body?.AuthCode is null || returnUrl is null)
    {
        return Results.Content(ErrorPage(body?.Error, body?.Reason), "text/html", statusCode: 400);
    }

    http.Session.Remove("bitrobot_request_id");
    http.Session.Remove("bitrobot_nonce");

    // Redirect to return_url verbatim, fragment included, with a 303.
    http.Response.Headers.Location = returnUrl;
    return Results.StatusCode(StatusCodes.Status303SeeOther);
}).RequireAuthorization();

app.Run();

// Allow http(s) URLs only. Return the string as given.
static string? SafeReturnUrl(string? raw) =>
    Uri.TryCreate(raw, UriKind.Absolute, out var uri)
    && (uri.Scheme == Uri.UriSchemeHttp || uri.Scheme == Uri.UriSchemeHttps)
        ? raw
        : null;

// Render the connect page and the error page from the HTML templates below.
// HTML-encode every substituted value: the wallet address comes from the user,
// and the error and reason come from the API response.
static string ConfirmPage(string walletAddress, string? csrfToken) =>
    File.ReadAllText("Views/bitrobot-connect.html")
        .Replace("{{WALLET_ADDRESS}}", WebUtility.HtmlEncode(walletAddress))
        .Replace("{{CSRF_FIELD}}",
            "<input type=\"hidden\" name=\"__RequestVerificationToken\" value=\""
            + WebUtility.HtmlEncode(csrfToken) + "\" />");

static string ErrorPage(string? error, string? reason) =>
    File.ReadAllText("Views/bitrobot-connect-error.html")
        .Replace("{{ERROR}}", WebUtility.HtmlEncode(error ?? "Something went wrong"))
        .Replace("{{REASON}}", WebUtility.HtmlEncode(reason ?? "unknown"));

record ConfirmResponse(
    [property: JsonPropertyName("status")] string? Status,
    [property: JsonPropertyName("return_url")] string? ReturnUrl,
    [property: JsonPropertyName("auth_code")] string? AuthCode,
    [property: JsonPropertyName("error")] string? Error,
    [property: JsonPropertyName("reason")] string? Reason);

Stateless hold

If your API is stateless, store request_id and nonce in a table instead of the session. Keep one row per user, replace it on each new start, and check expiry on read.

CREATE TABLE bitrobot_connect_attempts (
  id          TEXT PRIMARY KEY,
  user_id     TEXT      NOT NULL REFERENCES users (id),
  request_id  TEXT      NOT NULL,
  nonce       TEXT      NOT NULL,
  expires_at  TIMESTAMP NOT NULL,
  created_at  TIMESTAMP NOT NULL,
  updated_at  TIMESTAMP NOT NULL
);

-- One row per user.
CREATE UNIQUE INDEX index_bitrobot_connect_attempts_on_user_id
  ON bitrobot_connect_attempts (user_id);

# app/models/bitrobot_connect_attempt.rb
class BitrobotConnectAttempt < ApplicationRecord
  TTL = 15.minutes

  belongs_to :user

  validates :request_id, presence: true
  validates :nonce, presence: true

  scope :active, -> { where(expires_at: Time.current..) }

  # Replaces whatever the user had in flight.
  def self.start!(user:, request_id:, nonce:)
    attempt = find_or_initialize_by(user_id: user.id)
    attempt.update!(request_id: request_id, nonce: nonce, expires_at: TTL.from_now)
    attempt
  end

  # The live hold for this user, or nil once it has lapsed.
  def self.active_for(user)
    active.find_by(user_id: user.id)
  end
end

# In your controller. safe_return_url is the helper from the Ruby (Sinatra) example above.
def confirm
  attempt = BitrobotConnectAttempt.active_for(current_user)
  return render_error(:not_found, "no_attempt") if attempt.nil?

  body = Bitrobot::Client.new.confirm_wallet_connection(
    request_id: attempt.request_id,
    nonce: attempt.nonce,
    wallet_address: current_user.wallet_address,
    subnet_user_id: current_user.id.to_s
  )

  # Branch on auth_code, not the status. Never log or render auth_code.
  return_url = safe_return_url(body["return_url"])
  if body["auth_code"].to_s.empty? || return_url.nil?
    return render_error(:bad_request, body["reason"])
  end

  attempt.destroy

  # Redirect to return_url verbatim, fragment included.
  redirect_to return_url, allow_other_host: true, status: :see_other
end

Pages you render

Two pages: the connect page the user lands on, and an error page.

Connect page

Show the wallet address in full and one button that POSTs to your confirm handler. Include your framework’s CSRF token in the form. HTML-escape {{WALLET_ADDRESS}} wherever you substitute it.

<!-- templates/bitrobot-connect.html: substitute the wallet address with your template engine -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Connect to BitRobot</title>
  </head>
  <body>
    <main>
      <h1>Connect your wallet to BitRobot</h1>
      <p>
        BitRobot will link the wallet you use here to your BitRobot account, so the
        Subnet Points and Bolts we grant you reach it.
      </p>
      <p>Wallet: <code style="word-break: break-all">{{WALLET_ADDRESS}}</code></p>
      <form method="post" action="/bitrobot/connect/confirm">
        <!-- Substitute your framework's hidden CSRF token field here. The field
             name must match what your guard reads: authenticity_token for
             Rack::Protection, _token for Laravel, __RequestVerificationToken
             for ASP.NET. -->
        {{CSRF_FIELD}}
        <button type="submit">Connect</button>
      </form>
    </main>
  </body>
</html>

// BitRobotConnectPage.tsx: for an SPA. Your confirm handler returns JSON: return_url on success,
// error on failure, and never auth_code.
import { useState } from "react";

type Props = {
  walletAddress: string;
  csrfToken: string;
};

// Allow http(s) URLs only. Return the string as given.
function safeReturnUrl(raw: unknown): string | null {
  if (typeof raw !== "string" || !raw) return null;
  try {
    const url = new URL(raw);
    return url.protocol === "https:" || url.protocol === "http:" ? raw : null;
  } catch {
    return null;
  }
}

export function BitRobotConnectPage({ walletAddress, csrfToken }: Props) {
  const [submitting, setSubmitting] = useState(false);
  const [error, setError] = useState<string | null>(null);

  async function connect(event: React.FormEvent) {
    event.preventDefault();
    setSubmitting(true);
    setError(null);

    const response = await fetch("/bitrobot/connect/confirm", {
      method: "POST",
      headers: { "X-CSRF-Token": csrfToken },
    });
    const body = await response.json();
    const href = safeReturnUrl(body.return_url);
    if (!href) {
      setSubmitting(false);
      setError(
        typeof body?.error === "string"
          ? body.error
          : "Could not connect to BitRobot. Please try again."
      );
      return;
    }

    window.location.replace(href);
  }

  return (
    <main>
      <h1>Connect your wallet to BitRobot</h1>
      <p>
        BitRobot will link the wallet you use here to your BitRobot account, so the
        Subnet Points and Bolts we grant you reach it.
      </p>
      <p>
        Wallet: <code style={{ wordBreak: "break-all" }}>{walletAddress}</code>
      </p>
      {error ? <p role="alert">{error}</p> : null}
      <form onSubmit={connect}>
        <button type="submit" disabled={submitting}>
          {submitting ? "Connecting…" : "Connect"}
        </button>
      </form>
    </main>
  );
}

In the React version, pass csrfToken in from your server: render it into the page, or serve it from a GET endpoint the page fetches before it posts. It sends the token as X-CSRF-Token — send whatever header your guard reads instead if it differs. The ASP.NET example above reads the __RequestVerificationToken form field, not a header.

Error page

HTML-escape {{ERROR}} and {{REASON}} wherever you substitute them.

Plain HTML

<!-- templates/bitrobot-connect-error.html -->
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Couldn't connect to BitRobot</title>
  </head>
  <body>
    <main>
      <h1>Couldn't connect to BitRobot</h1>
      <p>{{ERROR}}</p>
      <p><small>Reason: <code>{{REASON}}</code></small></p>
      <p><a href="https://app.bitrobot.ai/profile">Go back to BitRobot</a> and press Connect again.</p>
    </main>
  </body>
</html>

Store the destination, query string included, before redirecting to login, and return the user to it after sign-in.

// The guard: remember the destination, including its query string.
export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { ready, authenticated } = useAuth();
  const location = useLocation();

  if (!ready) return <Loading />;
  if (!authenticated) {
    return (
      <Navigate to="/login" replace state={{ from: location.pathname + location.search }} />
    );
  }
  return children;
}

// The login page: accept an in-app path only.
// One leading slash, not followed by another slash or a backslash.
const isInAppPath = (v: unknown): v is string =>
  typeof v === "string" && /^\/(?![/\\])/.test(v);

const from = (location.state as { from?: unknown } | null)?.from;
const destination = isInAppPath(from) ? from : "/dashboard";

// After a successful sign-in:
navigate(destination, { replace: true });

For server-rendered apps, store request.fullpath before the login redirect and redirect to it afterwards. Accept an in-app path only:

RETURN_PATH_FORMAT = %r{\A/(?!/|\\|%2[fF]|%5[cC])[A-Za-z0-9._~!$&'()*+,;=:@%/?-]*\z}

Tests

RSpec examples against the connect page and a confirm handler that returns JSON. park_attempt stores a hold for user; confirm_url, success_body, callback_url, and auth_code are fixtures. Translate the assertions to your framework. 1. The handler ignores a request_id and nonce supplied by the caller.

it "ignores a request_id and nonce supplied by the caller" do
  park_attempt # holds request_id + nonce for `user`
  stub = stub_request(:post, confirm_url)
    .with(body: hash_including("request_id" => request_id, "nonce" => nonce))
    .to_return(status: 200, body: success_body)

  post "/api/v1/bitrobot_connect/confirm",
       params: { request_id: "01JZ8ZP9K3QF7XN2M4RB6TVWCE", nonce: "attacker-nonce" },
       headers: auth_headers_for(user)

  expect(stub).to have_been_requested # the held ids, not the posted ones
  expect(response).to have_http_status(:ok)
end

2. One user’s hold is unusable by another.

it "never reads another user's hold" do
  park_attempt(for_user: create(:user))

  post "/api/v1/bitrobot_connect/confirm", headers: auth_headers_for(user)

  expect(response).to have_http_status(:not_found)
  expect(response.parsed_body.dig("error", "code")).to eq("no_attempt")
  expect(a_request(:post, confirm_url)).not_to have_been_made
end

3. A lapsed hold is treated as no hold.

it "treats a lapsed hold as no hold at all" do
  park_attempt(expires_at: 1.minute.ago)

  post "/api/v1/bitrobot_connect/confirm", headers: auth_headers_for(user)

  expect(response).to have_http_status(:not_found)
  expect(a_request(:post, confirm_url)).not_to have_been_made
end

4. return_url passes through byte for byte, fragment included.

it "passes BitRobot's return_url through with its fragment byte-for-byte" do
  park_attempt
  stub_request(:post, confirm_url).to_return(status: 200, body: success_body)

  post "/api/v1/bitrobot_connect/confirm", headers: auth_headers_for(user)

  expect(response.parsed_body["return_url"]).to eq(callback_url)
  expect(URI.parse(response.parsed_body["return_url"]).fragment).to eq("ac=#{auth_code}")
end

5. The connect page escapes the wallet address.

it "escapes a wallet address that contains HTML" do
  user.update!(wallet_address: %q(HN7c"><script>alert(1)</script>))

  get "/bitrobot/connect", params: { request_id:, nonce: }, headers: auth_headers_for(user)

  expect(response.body).not_to include("<script>alert(1)</script>")
  expect(response.body).to include("&lt;script&gt;")
end

6. The authorization code appears only inside return_url, and never in logs.

it "never renders the auth code as a field of its own, nor logs it" do
  park_attempt
  stub_request(:post, confirm_url).to_return(status: 200, body: success_body)
  logged = []
  allow(Rails.logger).to receive(:warn) { |msg| logged << msg.to_s }
  allow(Rails.logger).to receive(:error) { |msg| logged << msg.to_s }

  post "/api/v1/bitrobot_connect/confirm", headers: auth_headers_for(user)

  expect(response.parsed_body).not_to have_key("auth_code")
  expect(response.body.scan(auth_code).length).to eq(1) # only inside return_url
  expect(logged.join("\n")).not_to include(auth_code)
end

Also cover:

A confirm POST without a valid CSRF token is refused.
An error or reason containing HTML is escaped on the error page.
A 409 already_confirmed with auth_code is treated as success.
A 200 without auth_code is treated as a failure.
A non-http(s) return_url is refused.
The hold is cleared after a successful confirm and kept after a failed one.

​Backend implementations

​Stateless hold

​Pages you render

​Connect page

​Error page

​Returning from login

​Tests