Production Hardening · Neon Functions · neondatabase/agent-skills · Skills Docs

Production Hardening · Neon Functions · neondatabase/agent-skills · Skills Docs

Caller	What to do	Do not
Trusted app server (Vercel/Netlify route, server action, queue worker) that finishes within that host’s duration	The server calls the Function. Browser never sees the Function URL or the origin secret. Function returns 401 before any work.	Put the secret in client code. Proxy a long agent, WebSocket, or SSE stream through the app host without checking that host’s duration.
Function Triggers only	`parseTriggerDelivery` (both types). Keep this path outside JWT and `X-Secret` middleware.	Require a user JWT or `X-Secret` on the trigger path. Invent `x-neon-invocation-id`. Treat `invocation_id` as a secret.
Public consumers (Open API, MCP, third-party HTTP)	A Cloudflare Worker Custom Domain you own, not registered as a Neon custom domain, proxies to the native invocation URL, sets `X-Secret`, and rate-limits at the edge. Function requires `X-Secret`, then the route’s existing consumer auth.	Orange-cloud a Neon-registered custom-domain CNAME. Assume the native URL is closed. Put a human challenge in front of MCP.

import { timingSafeEqual } from "node:crypto";

const originSecret = process.env.ORIGIN_SECRET;
if (!originSecret) throw new Error("ORIGIN_SECRET is required");
const expected = Buffer.from(originSecret);

function hasOriginSecret(request: Request): boolean {
  const header = request.headers.get("x-secret");
  if (header === null) return false;
  const provided = Buffer.from(header);
  if (provided.byteLength !== expected.byteLength) return false;
  return timingSafeEqual(provided, expected);
}

export default {
  async fetch(request: Request): Promise<Response> {
    if (!hasOriginSecret(request)) {
      return new Response("Unauthorized", { status: 401 });
    }
    return Response.json({ ok: true });
  },
};

const functionUrl = process.env.NEON_FUNCTION_URL;
const originSecret = process.env.ORIGIN_SECRET;
if (!functionUrl || !originSecret) {
  throw new Error("NEON_FUNCTION_URL and ORIGIN_SECRET are required");
}

const headers = new Headers({ "x-secret": originSecret });
const contentType = request.headers.get("content-type");
if (contentType) headers.set("content-type", contentType);
const authorization = request.headers.get("authorization");
if (authorization) headers.set("authorization", authorization);

return fetch(functionUrl, {
  method: request.method,
  headers,
  body: request.body ? await request.arrayBuffer() : undefined,
  redirect: "manual",
});

const FUNCTION_ORIGIN = "https://<invocation-host>"; // neon functions get

export default {
  async fetch(
    request: Request,
    env: { ORIGIN_SECRET: string },
  ): Promise<Response> {
    const incoming = new URL(request.url);
    const upstream = new URL(FUNCTION_ORIGIN);
    upstream.pathname = incoming.pathname;
    upstream.search = incoming.search;

    const headers = new Headers(request.headers);
    headers.set("x-secret", env.ORIGIN_SECRET);
    headers.delete("host");

    return fetch(upstream, {
      method: request.method,
      headers,
      body: request.body,
      redirect: "manual",
    });
  },
};

import { waitUntil } from "@neon/functions";
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";

const namespace = process.env.RATE_LIMIT_PREFIX;
if (!namespace) throw new Error("RATE_LIMIT_PREFIX is required");

const limiter = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(60, "1 m"),
  prefix: `${namespace}:${process.env.NEON_BRANCH ?? "local"}`,
  timeout: 1_000,
  analytics: false,
});

export async function checkQuota(
  authenticatedPrincipalId: string,
): Promise<Response | null> {
  let result: Awaited<ReturnType<typeof limiter.limit>>;
  try {
    result = await limiter.limit(authenticatedPrincipalId);
  } catch (error) {
    console.error("Rate-limit store failed", error);
    return new Response("Rate limiter unavailable", {
      status: 503,
      headers: { "Retry-After": "1" },
    });
  }

  waitUntil(result.pending);

  if (result.reason === "timeout") {
    console.error("Rate-limit store timed out");
    return new Response("Rate limiter unavailable", {
      status: 503,
      headers: { "Retry-After": "1" },
    });
  }

  if (result.success) return null;

  const retryAfterSeconds = Math.max(
    1,
    Math.ceil((result.reset - Date.now()) / 1000),
  );
  return new Response("Too Many Requests", {
    status: 429,
    headers: {
      "Retry-After": String(retryAfterSeconds),
      "RateLimit-Limit": String(result.limit),
      "RateLimit-Remaining": String(result.remaining),
      "RateLimit-Reset": String(retryAfterSeconds),
    },
  });
}