Single-Page Apps & CORS

import pathlib
import tempfile

from flask import Flask, jsonify, request, send_from_directory

# Stand-in for the front-end build output (normally `npm run build` writes dist/).
dist = pathlib.Path(tempfile.mkdtemp()) / "dist"
(dist / "assets").mkdir(parents=True)
(dist / "index.html").write_text('<!doctype html><div id="root"></div><script src="/assets/app-3f9a1c.js"></script>')
(dist / "assets" / "app-3f9a1c.js").write_text("console.log('bookshelf');")

# static_url_path="/" serves the build folder at the site root.
app = Flask(__name__, static_folder=str(dist), static_url_path="/")


@app.get("/api/books")
def list_books():
    return jsonify([{"id": 1, "title": "Dune"}])


@app.errorhandler(404)
def history_fallback(error):
    last_segment = request.path.rsplit("/", 1)[-1]
    is_api = request.path.startswith("/api/")
    is_file = "." in last_segment  # /assets/missing.js is a real 404
    if request.method != "GET" or is_api or is_file:
        return jsonify(error="not found"), 404
    return send_from_directory(dist, "index.html", max_age=0)


@app.after_request
def cache_headers(response):
    if request.path.startswith("/assets/") and response.status_code == 200:
        # File names carry a content hash, so they can be cached for a year.
        response.headers["Cache-Control"] = "public, max-age=31536000, immutable"
    return response


client = app.test_client()
assert client.get("/").mimetype == "text/html"
assert client.get("/books/42").mimetype == "text/html"          # history fallback
assert client.get("/assets/app-3f9a1c.js").mimetype == "text/javascript"
assert "immutable" in client.get("/assets/app-3f9a1c.js").headers["Cache-Control"]
assert client.get("/api/books").json[0]["title"] == "Dune"
assert client.get("/api/typo").json == {"error": "not found"}
assert client.get("/assets/missing.js").status_code == 404
assert client.post("/books/42").status_code == 405  # the static rule only matches GET and HEAD

// vite.config.js (frontend project, next to package.json)
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    proxy: {
      // http://localhost:5173/api/books  ->  http://127.0.0.1:5000/api/books
      "/api": {
        target: "http://127.0.0.1:5000",
        changeOrigin: false, // keep the Host header of the dev server
      },
    },
  },
});

from flask import Flask, jsonify, request

ALLOWED_ORIGINS = {"http://localhost:5173"}

hand = Flask(__name__)


@hand.get("/api/books")
def hand_books():
    return jsonify([{"id": 1, "title": "Dune"}])


@hand.after_request
def add_cors_headers(response):
    origin = request.headers.get("Origin")
    if origin in ALLOWED_ORIGINS:
        response.headers["Access-Control-Allow-Origin"] = origin
        response.headers.add("Vary", "Origin")  # the answer depends on the request's Origin
        if request.method == "OPTIONS":
            response.headers["Access-Control-Allow-Methods"] = "GET, POST, PUT, PATCH, DELETE"
            response.headers["Access-Control-Allow-Headers"] = request.headers.get(
                "Access-Control-Request-Headers", "Content-Type"
            )
            response.headers["Access-Control-Max-Age"] = "600"
    return response


c = hand.test_client()
allowed = {"Origin": "http://localhost:5173"}
r = c.get("/api/books", headers=allowed)
assert r.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
assert "Access-Control-Allow-Origin" not in c.get("/api/books", headers={"Origin": "https://other.example"}).headers
pre = c.options("/api/books", headers={**allowed, "Access-Control-Request-Method": "GET"})
assert pre.status_code == 200 and pre.headers["Access-Control-Max-Age"] == "600"

from flask import Flask, jsonify, request
from flask_cors import CORS

app = Flask(__name__)

# Only the API is exposed cross-origin, only to the front end, and cookies are allowed.
CORS(
    app,
    resources={
        r"/api/*": {
            "origins": ["http://localhost:5173"],
            "methods": ["GET", "POST", "PUT", "DELETE"],
            "allow_headers": ["Content-Type", "X-CSRFToken"],
            "expose_headers": ["X-Total-Count"],
            "supports_credentials": True,
            "max_age": 600,
        }
    },
)


@app.route("/api/books", methods=["GET", "POST"])
def books():
    if request.method == "POST":
        return jsonify(id=2), 201
    return jsonify([]), 200, {"X-Total-Count": "0"}


@app.get("/health")
def health():
    return "ok"


client = app.test_client()
origin = {"Origin": "http://localhost:5173"}

simple = client.get("/api/books", headers=origin)
assert simple.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
assert simple.headers["Access-Control-Allow-Credentials"] == "true"
assert simple.headers["Access-Control-Expose-Headers"] == "X-Total-Count"

preflight = client.options(
    "/api/books",
    headers={
        **origin,
        "Access-Control-Request-Method": "POST",
        "Access-Control-Request-Headers": "content-type,x-csrftoken",
    },
)
assert preflight.status_code == 200
assert preflight.headers["Access-Control-Max-Age"] == "600"
assert preflight.headers["Access-Control-Allow-Headers"] == "content-type, x-csrftoken"
assert "POST" in preflight.headers["Access-Control-Allow-Methods"]

# Another origin gets no permission headers at all; the route itself still answers.
stranger = client.get("/api/books", headers={"Origin": "https://evil.example"})
assert "Access-Control-Allow-Origin" not in stranger.headers
# Paths outside the resource pattern are not touched.
assert "Access-Control-Allow-Origin" not in client.get("/health", headers=origin).headers
# A header that is not in allow_headers is dropped from the grant.
refused = client.options(
    "/api/books",
    headers={**origin, "Access-Control-Request-Method": "POST", "Access-Control-Request-Headers": "x-secret"},
)
assert "x-secret" not in refused.headers.get("Access-Control-Allow-Headers", "")

import os
import re

from flask import Flask, jsonify
from flask_cors import CORS

cors = CORS()


def create_app(config=None):
    app = Flask(__name__)
    # BOOKSHELF_ORIGINS="https://shelf.example,https://admin.shelf.example" in production
    origins = os.environ.get("BOOKSHELF_ORIGINS", "http://localhost:5173")
    app.config["CORS_ORIGINS"] = [o.strip() for o in origins.split(",") if o.strip()]
    app.config["CORS_SUPPORTS_CREDENTIALS"] = True
    app.config.update(config or {})
    cors.init_app(app, resources={r"/api/*": {}})  # options come from CORS_* keys

    @app.get("/api/books")
    def api_books():
        return jsonify([])

    @app.get("/other")
    def other():
        return "outside the resource pattern"

    return app


client = create_app().test_client()
granted = client.get("/api/books", headers={"Origin": "http://localhost:5173"})
assert granted.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
assert granted.headers["Access-Control-Allow-Credentials"] == "true"
assert "Access-Control-Allow-Origin" not in client.get("/other", headers={"Origin": "http://localhost:5173"}).headers

# Regular expressions allow one pattern for many sub-domains, but re.match() only anchors the start.
loose = create_app({"CORS_ORIGINS": [re.compile(r"https://[a-z0-9-]+\.shelf\.example")]}).test_client()
strict = create_app({"CORS_ORIGINS": [re.compile(r"https://[a-z0-9-]+\.shelf\.example$")]}).test_client()
lookalike = {"Origin": "https://admin.shelf.example.evil.example"}
assert "Access-Control-Allow-Origin" in loose.get("/api/books", headers=lookalike).headers  # the trap
assert "Access-Control-Allow-Origin" not in strict.get("/api/books", headers=lookalike).headers
assert strict.get("/api/books", headers={"Origin": "https://admin.shelf.example"}).headers["Access-Control-Allow-Origin"]

from flask import Blueprint, Flask, jsonify
from flask_cors import CORS

api = Blueprint("api", __name__, url_prefix="/api")
CORS(api, origins=["http://localhost:5173"])  # blueprint-only CORS


@api.get("/books")
def blueprint_books():
    return jsonify([])


bp_app = Flask(__name__)
bp_app.register_blueprint(api)


@bp_app.get("/other")
def bp_other():
    return "not a blueprint route"


bp_client = bp_app.test_client()
origin = {"Origin": "http://localhost:5173"}
assert bp_client.get("/api/books", headers=origin).headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
assert "Access-Control-Allow-Origin" not in bp_client.get("/other", headers=origin).headers

from flask import Flask
from flask_cors import CORS

trap = Flask(__name__)
CORS(trap, supports_credentials=True)  # origins defaults to "*"


@trap.get("/api/me")
def me():
    return {"user": "ada"}


evil = trap.test_client().get("/api/me", headers={"Origin": "https://evil.example"})
# The extension echoes ANY origin and allows credentials: every site on the internet may now read
# the logged-in user's responses. Never ship this combination.
assert evil.headers["Access-Control-Allow-Origin"] == "https://evil.example"
assert evil.headers["Access-Control-Allow-Credentials"] == "true"

safe = Flask(__name__)
CORS(safe, origins=["https://shelf.example"], supports_credentials=True)
safe.get("/api/me")(lambda: {"user": "ada"})
stranger = safe.test_client().get("/api/me", headers={"Origin": "https://evil.example"})
assert "Access-Control-Allow-Origin" not in stranger.headers

from flask import Flask, jsonify, request
from flask_cors import CORS

ORIGIN = {"Origin": "http://localhost:5173"}
PREFLIGHT = {
    **ORIGIN,
    "Access-Control-Request-Method": "GET",
    "Access-Control-Request-Headers": "authorization",
}


def make_client(skip_options):
    app = Flask(__name__)
    CORS(app, origins=["http://localhost:5173"])

    @app.before_request
    def require_auth():
        if skip_options and request.method == "OPTIONS":
            return None  # the preflight carries no credentials by design
        if not request.headers.get("Authorization", "").startswith("Bearer "):
            return jsonify(error="unauthorized"), 401
        return None

    @app.get("/api/me")
    def me():
        return jsonify(user="ada")

    return app.test_client()


broken = make_client(skip_options=False).options("/api/me", headers=PREFLIGHT)
fixed = make_client(skip_options=True).options("/api/me", headers=PREFLIGHT)
assert broken.status_code == 401  # the browser needs a 2xx preflight, so the real request is never sent
assert fixed.status_code == 200 and fixed.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"

# The exemption is only for OPTIONS: the real request is still authenticated.
real = make_client(skip_options=True).get("/api/me", headers=ORIGIN)
assert real.status_code == 401
assert real.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"  # 401 stays readable by the SPA

import secrets

from flask import Flask, jsonify, request, session
from flask_cors import CORS
from flask_wtf.csrf import CSRFError, CSRFProtect, generate_csrf
from werkzeug.security import check_password_hash, generate_password_hash

PASSWORD = secrets.token_urlsafe(12)  # demo credential, generated for this run only
USERS = {"ada": generate_password_hash(PASSWORD)}

app = Flask(__name__)
app.config.update(
    SECRET_KEY=secrets.token_hex(32),  # load it from the environment or the instance folder in a real project
    SESSION_COOKIE_HTTPONLY=True,
    SESSION_COOKIE_SAMESITE="Lax",
    SESSION_COOKIE_SECURE=False,  # True behind HTTPS
)
CSRFProtect(app)
CORS(
    app,
    resources={r"/api/*": {
        "origins": ["http://localhost:5173"],
        "supports_credentials": True,
        "allow_headers": ["Content-Type", "X-CSRFToken"],
    }},
)


@app.errorhandler(CSRFError)
def csrf_failed(error):
    return jsonify(error="csrf", detail=error.description), 400


@app.get("/api/csrf")
def csrf_token():
    return jsonify(csrf_token=generate_csrf())


@app.post("/api/login")
def login():
    body = request.get_json()
    if not check_password_hash(USERS.get(body.get("user"), ""), body.get("password", "")):
        return jsonify(error="bad credentials"), 401
    session.clear()  # new session on login; this also drops the old CSRF token
    session["user"] = body["user"]
    return jsonify(user=body["user"])


@app.delete("/api/books/<int:book_id>")
def delete_book(book_id):
    if "user" not in session:
        return jsonify(error="login required"), 401
    return "", 204


client = app.test_client()
origin = {"Origin": "http://localhost:5173"}

token = client.get("/api/csrf", headers=origin).json["csrf_token"]
assert client.post("/api/login", json={"user": "ada", "password": PASSWORD}, headers={**origin, "X-CSRFToken": token}).status_code == 200

# Without a token the cookie alone is not enough.
assert client.delete("/api/books/1", headers=origin).status_code == 400
# The token fetched before the login belongs to the old session, so ask for a new one after login.
assert client.delete("/api/books/1", headers={**origin, "X-CSRFToken": token}).status_code == 400
fresh = client.get("/api/csrf", headers=origin).json["csrf_token"]
done = client.delete("/api/books/1", headers={**origin, "X-CSRFToken": fresh})
assert done.status_code == 204 and done.headers["Access-Control-Allow-Credentials"] == "true"
cookie = client.get_cookie("session")
assert cookie.http_only and cookie.same_site == "Lax"

import secrets

from flask import Flask, jsonify, request
from flask_cors import CORS
from flask_jwt_extended import JWTManager, create_access_token, get_jwt_identity, jwt_required
from werkzeug.security import check_password_hash, generate_password_hash

PASSWORD = secrets.token_urlsafe(12)
USERS = {"ada": {"id": "1", "hash": generate_password_hash(PASSWORD)}}

tokens = Flask(__name__)
tokens.config["JWT_SECRET_KEY"] = secrets.token_hex(32)  # read it from the environment in a real project
JWTManager(tokens)
CORS(
    tokens,
    resources={r"/api/*": {
        "origins": ["http://localhost:5173"],
        "allow_headers": ["Authorization", "Content-Type"],
        "max_age": 600,
    }},
)


@tokens.post("/api/login")
def token_login():
    body = request.get_json()
    user = USERS.get(body.get("user"))
    if user is None or not check_password_hash(user["hash"], body.get("password", "")):
        return jsonify(error="bad credentials"), 401
    return jsonify(access_token=create_access_token(identity=user["id"]))  # the identity must be a string


@tokens.get("/api/me")
@jwt_required()  # the parentheses are required in Flask-JWT-Extended 4.x
def token_me():
    return jsonify(user_id=get_jwt_identity())


c = tokens.test_client()
o = {"Origin": "http://localhost:5173"}

pre = c.options("/api/me", headers={**o, "Access-Control-Request-Method": "GET", "Access-Control-Request-Headers": "authorization"})
assert pre.status_code == 200 and pre.headers["Access-Control-Allow-Headers"] == "authorization"  # jwt_required skips OPTIONS

access = c.post("/api/login", json={"user": "ada", "password": PASSWORD}, headers=o).json["access_token"]
ok = c.get("/api/me", headers={**o, "Authorization": "Bearer " + access})
assert ok.status_code == 200 and ok.json == {"user_id": "1"}
assert ok.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
assert c.get("/api/me", headers=o).status_code == 401

import secrets

from flask import Flask, jsonify
from flask_cors import CORS
from flask_jwt_extended import JWTManager, create_access_token, get_jwt_identity, jwt_required, set_access_cookies

cookie_jwt = Flask(__name__)
cookie_jwt.config.update(
    JWT_SECRET_KEY=secrets.token_hex(32),
    JWT_TOKEN_LOCATION=["cookies"],
    JWT_COOKIE_SECURE=False,  # True behind HTTPS
    JWT_COOKIE_SAMESITE="Lax",
    JWT_COOKIE_CSRF_PROTECT=True,
)
JWTManager(cookie_jwt)
CORS(
    cookie_jwt,
    resources={r"/api/*": {
        "origins": ["http://localhost:5173"],
        "supports_credentials": True,
        "allow_headers": ["Content-Type", "X-CSRF-TOKEN"],
    }},
)


@cookie_jwt.post("/api/login")
def cookie_login():
    response = jsonify(login=True)
    set_access_cookies(response, create_access_token(identity="1"))
    return response


@cookie_jwt.post("/api/books")
@jwt_required()
def cookie_add_book():
    return jsonify(created_by=get_jwt_identity()), 201


c2 = cookie_jwt.test_client()
o2 = {"Origin": "http://localhost:5173"}
assert c2.post("/api/login", headers=o2).status_code == 200
assert c2.post("/api/books", headers=o2).status_code == 401  # cookie present, double-submit header missing
csrf_cookie = c2.get_cookie("csrf_access_token")
assert not csrf_cookie.http_only and c2.get_cookie("access_token_cookie").http_only
assert c2.post("/api/books", headers={**o2, "X-CSRF-TOKEN": csrf_cookie.value}).status_code == 201

// src/api.js
const API = import.meta.env.VITE_API_URL ?? ""; // "" = same origin (proxy or Flask-served build)

let csrfToken = null;

async function csrf() {
  if (csrfToken === null) {
    const res = await fetch(`${API}/api/csrf`, { credentials: "include" });
    csrfToken = (await res.json()).csrf_token;
  }
  return csrfToken;
}

export async function listBooks() {
  const res = await fetch(`${API}/api/books`, { credentials: "include" });
  if (!res.ok) throw new Error(`API error ${res.status}`);
  return res.json();
}

export async function addBook(book) {
  const res = await fetch(`${API}/api/books`, {
    method: "POST",
    credentials: "include", // send the session cookie (cross-origin: needs CORS supports_credentials)
    headers: { "Content-Type": "application/json", "X-CSRFToken": await csrf() },
    body: JSON.stringify(book),
  });
  if (res.status === 400) csrfToken = null; // the session changed: fetch a new token on the next call
  if (!res.ok) throw new Error(`API error ${res.status}`);
  return res.json();
}

export async function listBooksWithBearer(token) {
  // The Authorization header is not CORS-safelisted: the browser sends a preflight first.
  return (await fetch(`${API}/api/books`, { headers: { Authorization: `Bearer ${token}` } })).json();
}

from flask import Flask, jsonify
from flask_cors import CORS


def make_cors_client():
    flask_app = Flask(__name__)
    CORS(flask_app, resources={r"/api/*": {"origins": ["http://localhost:5173"], "allow_headers": ["Content-Type"]}})

    @flask_app.get("/api/books")
    def list_books():
        return jsonify([])

    @flask_app.post("/api/books")
    def add_book():
        return jsonify(id=1), 201

    return flask_app.test_client()


# With pytest these are test functions that receive make_cors_client() as a fixture.
def test_preflight_of_json_post(cors_client):
    response = cors_client.options(
        "/api/books",
        headers={
            "Origin": "http://localhost:5173",
            "Access-Control-Request-Method": "POST",
            "Access-Control-Request-Headers": "content-type",
        },
    )
    assert response.status_code == 200  # the browser needs a 2xx
    assert response.headers["Access-Control-Allow-Origin"] == "http://localhost:5173"
    assert "POST" in response.headers["Access-Control-Allow-Methods"]


def test_stranger_gets_no_grant(cors_client):
    response = cors_client.get("/api/books", headers={"Origin": "https://evil.example"})
    assert "Access-Control-Allow-Origin" not in response.headers


test_preflight_of_json_post(make_cors_client())
test_stranger_gets_no_grant(make_cors_client())