Trusted server-side session mint

​

Enabling the endpoint

# 32+ bytes of CSPRNG. macOS / Linux:
openssl rand -hex 32
# → 2f1e... (use that)

# Pylon Cloud:
pylon secrets set PYLON_TRUSTED_SECRET=2f1e...

# Self-hosted: set the env var on your Pylon server.

​

Wire format

POST /api/auth/sessions/trusted-mint
Content-Type: application/json
X-Pylon-Trusted-Timestamp: 1716177600
X-Pylon-Trusted-Signature: 9f8a2c... (hex HMAC-SHA256)

{
  "email": "buyer@example.com",
  "createIfMissing": true,
  "displayName": "Jane Doe",
  "intent": "stripe_checkout_success"
}

signed_value = "<timestamp>.<raw_request_body>"
signature    = hex(HMAC_SHA256(PYLON_TRUSTED_SECRET, signed_value))

​

Response

{
  "userId":    "usr_01H...",
  "created":   true,
  "token":     "pylon_...",
  "expiresAt": 1716264000
}

​

Failure modes

​

Example: Next.js Stripe Checkout success handler

import { NextRequest } from "next/server";
import { redirect } from "next/navigation";
import { createHmac } from "crypto";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const PYLON_URL = process.env.PYLON_TARGET!;
const TRUSTED_SECRET = process.env.PYLON_TRUSTED_SECRET!;

function sign(secret: string, ts: number, body: string) {
  return createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
}

export async function GET(req: NextRequest) {
  const sessionId = req.nextUrl.searchParams.get("session_id");
  if (!sessionId) return new Response("missing session", { status: 400 });

  const session = await stripe.checkout.sessions.retrieve(sessionId);
  if (session.payment_status !== "paid") return new Response("unpaid", { status: 402 });
  const email = session.customer_details?.email;
  if (!email) return new Response("no email", { status: 400 });

  const ts = Math.floor(Date.now() / 1000);
  const body = JSON.stringify({
    email,
    createIfMissing: true,
    displayName: session.customer_details?.name ?? undefined,
    intent: "stripe_checkout_success",
  });
  const signature = sign(TRUSTED_SECRET, ts, body);

  const mint = await fetch(`${PYLON_URL}/api/auth/sessions/trusted-mint`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Pylon-Trusted-Timestamp": String(ts),
      "X-Pylon-Trusted-Signature": signature,
    },
    body,
  });
  if (!mint.ok) {
    return new Response(`trusted-mint failed: ${await mint.text()}`, { status: 500 });
  }

  // Pass Pylon's Set-Cookie through to the browser, then redirect.
  const res = new Response(null, { status: 302, headers: { Location: "/dashboard" } });
  const setCookie = mint.headers.get("set-cookie");
  if (setCookie) res.headers.set("set-cookie", setCookie);
  return res;
}

​

Edge cases

​

Audit log

​

Replay window — be honest about what HMAC + timestamp buys

• A TLS-MITM in the path (corporate proxy, “log everything” CDN that captures bodies) within the 5-min window can extract a usable session token.
• An attacker who steals one signed request from server logs that capture the URL + headers (rare — sigs are headers, bodies aren’t usually logged) can replay it once per minute for up to 5 minutes.

• Don’t log signed requests with their headers.
• Use HTTPS end-to-end; the HMAC is not a substitute for TLS.
• If your threat model requires single-use semantics, include a nonce in the request body and enforce uniqueness in your own backend before issuing the trusted-mint call. The trusted-mint endpoint itself does not de-duplicate; Pylon’s audit log will show every replay.

​

Security checklist

• PYLON_TRUSTED_SECRET is 32+ bytes of CSPRNG output (openssl rand -hex 32).
• The secret is set only on machines that need to sign or verify — sign-only frontends do not need to know it.
• The endpoint is reachable only from your trusted server-side environments (most production Pylon deployments are public, so the secret is the only thing keeping attackers out — accept that).
• Server clocks are within a few seconds of NTP. ±5 min sounds generous, but a 7-min clock skew bricks the endpoint.
• Rotation playbook: set a new PYLON_TRUSTED_SECRET, redeploy the signing service, wait for in-flight signed requests to flush (~10 min), then rotate the Pylon side. Pylon currently accepts one active secret; multi-key rotation is on the roadmap.
• Audit log shipped somewhere queryable (Tinybird, Loki, Datadog) so a sign_in_failed spike on the trusted_mint method is alertable. Every post-signature rejection (invalid JSON, missing/invalid email, USER_NOT_FOUND, INVALID_USER_ROW, USER_INSERT_FAILED, ACCOUNT_LOCKED) emits one with the matching meta.reason.
• Signed-request payloads aren’t logged at the TLS-terminator (Cloudflare, Fly proxy, etc.) — bodies are sensitive even though headers usually aren’t.

​

Why not service tokens?

• Service tokens leak. Once leaked, the attacker can sign in as anyone forever — same blast radius as PYLON_TRUSTED_SECRET, but the secret never travels with the request, so observability tools that log headers don’t accidentally capture it.
• Service tokens don’t bind to the request body. An attacker who captures one signed request can replay it. HMAC + timestamp kills that.
• Token rotation requires a coordinated cutover on both sides. Secret rotation is a single env-var change on each side; you don’t have to deploy a new long-lived credential.