fix(iam): origin-less SDK auth + adopt better-auth 1.7.x - #260

🏁 Script executed:

#!/bin/bash
set -eu
file="blueprint/iam-better-auth/api/middlewares/betterAuth.middleware.ts"
printf '%s\n' '--- file outline ---'
ast-grep outline "$file" --view expanded || true
printf '%s\n' '--- relevant source ---'
cat -n "$file" | sed -n '1,130p'
printf '%s\n' '--- related symbols and tests ---'
rg -n --glob '*.{ts,tsx,js,mjs,cjs,json,md}' 'ensureTrustedOrigin|resolveTrustedOrigin|MISSING_OR_NULL_ORIGIN|Origin: null|origin-less|betterAuth' .

Repository: forklaunch/forklaunch

Length of output: 8537

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- Better Auth configuration ---'
cat -n blueprint/iam-better-auth/auth.ts | sed -n '1,205p'
printf '%s\n' '--- middleware registration ---'
cat -n blueprint/iam-better-auth/server.ts | sed -n '95,130p'
printf '%s\n' '--- relevant package versions ---'
rg -n --glob 'package.json' --glob '*lock*' '"better-auth"|better-auth@' .
printf '%s\n' '--- repository guidance on this error ---'
cat -n cli/assets/forklaunch-skills/vercel-frontend/SKILL.md | sed -n '420,445p'

Repository: forklaunch/forklaunch

Length of output: 10746

🌐 Web query:

Better Auth 1.6.26 MISSING_OR_NULL_ORIGIN origin referer CSRF source code

💡 Result:

The MISSING_OR_NULL_ORIGIN error in Better Auth is a security mechanism intended to prevent Cross-Site Request Forgery (CSRF) attacks by enforcing strict validation of the Origin or Referer header for requests that utilize cookies [1][2][3]. Mechanism: Better Auth's origin validation middleware (located in src/api/middlewares/origin-check.ts) performs the following check: 1. It detects if a request uses cookies (headers.has("cookie")) [4][5]. 2. If cookies are present, it requires a valid Origin or Referer header that matches one of the entries in your trustedOrigins configuration [4][3]. 3. If the header is missing, null, or does not match a trusted origin, the library throws the FORBIDDEN error with the code MISSING_OR_NULL_ORIGIN [4]. Why this happens: - Browsers: Normally, browsers automatically attach Origin/Referer headers to requests [1]. If you see this error, it often means the client environment is stripping these headers or, in the case of some mobile/cross-platform environments (like Expo), the expected header is missing or not automatically translated to the standard Origin header [6][7][8]. - Non-Browser Clients (Postman, CLI, Server-to-server): These clients often do not send an Origin header by default. If the request includes a session cookie (e.g., from a previous sign-in), Better Auth triggers the validation logic, resulting in the error [1][2]. Solutions: 1. Production Environments: Ensure your client explicitly sends a valid Origin header that matches your server's trustedOrigins configuration [2][3]. 2. Expo/Mobile: Ensure you are using the latest @better-auth/expo plugin, which is designed to handle the translation of mobile-specific headers (like expo-origin) into the standard Origin header [6][7]. 3. Development/Non-Browser Clients: If you are using tools like Postman, you can manually add an Origin header to your request that matches a value in your trustedOrigins list [1]. 4. Disabling (Not Recommended for Production): You can disable the check in your configuration using advanced: { disableOriginCheck: true }. This should only be used in isolated development environments as it removes a layer of CSRF protection [6][2]. Note on First-Login CSRF: Better Auth also implements Fetch Metadata protection for sign-in/sign-up routes where cookies might not yet be present [9][5][10]. If Fetch Metadata headers are present but indicate a cross-site navigation, the request will be blocked [9][3]. If no cookies and no Fetch Metadata are present, the library falls back to its standard behavior [9][10].

Citations:

• 1: Origin Header Issue better-auth/better-auth#6257
• 2: Email & Password Sign Up/Logout throws 403 MISSING_OR_NULL_ORIGIN better-auth/better-auth#5573
• 3: https://www.better-auth.com/docs/reference/security
• 4: https://github.com/better-auth/better-auth/blob/cd2ea4cd/packages/better-auth/src/api/middlewares/origin-check.ts
• 5: https://github.com/better-auth/better-auth/blob/cd2ea4cd/docs/content/docs/reference/security.mdx
• 6: Expo Android + Better Auth: 403 MISSING_OR_NULL_ORIGIN on sign-up/sign-in better-auth/better-auth#5750
• 7: [Expo] expo-origin → Origin translation in onRequest doesn't reach origin-check middleware better-auth/better-auth#9490
• 8: better-auth expo plugin expo-origin header bypass takes no effect because of setting readonly request headers better-auth/better-auth#7014
• 9: https://raw.githubusercontent.com/better-auth/better-auth/refs/heads/main/docs/content/docs/reference/security.mdx
• 10: better-auth/better-auth@3f06dd2dd

🌐 Web query:

site:github.com/better-auth/better-auth "MISSING_OR_NULL_ORIGIN"

💡 Result:

MISSING_OR_NULL_ORIGIN is a Better Auth error code (HTTP 403) meaning “Missing or null Origin”. It is thrown when Better Auth’s Origin/CSRF protection logic is triggered for POST requests that include cookies, but the request does not have a valid Origin header (or it resolves to null) [1]. What triggers it (common causes) 1) Cookie-based requests with missing Origin/Referer headers Better Auth introduced stricter Origin header enforcement in v1.3.29+ for POST requests that use cookies (e.g., sign-in/sign-out flows). If the Origin header (or Referer) is missing/null, Better Auth returns 403 with code MISSING_OR_NULL_ORIGIN [2][3]. 2) Using tools/environments that don’t send Origin (e.g., Postman) Because some API clients don’t automatically send an Origin header, subsequent requests that include preserved cookies can start failing with MISSING_OR_NULL_ORIGIN [3]. Workarounds include adding an Origin header that matches trustedOrigins, clearing cookie persistence, or using bearer-token auth instead of cookie sessions [3]. 3) Trusted origin mismatch for mobile/custom schemes For mobile (Expo/React Native), requests may fail if the scheme/value sent from the client doesn’t exactly match entries in trustedOrigins (e.g., myapp:// vs client://). In that case the server’s origin validation fails and you see MISSING_OR_NULL_ORIGIN [4]. 4) Expo plugin Origin translation issues (version-specific) In some cases the Expo plugin’s intended translation of expo-origin → Origin wasn’t reaching the origin-check middleware, causing the origin-check step to still see origin as null and return MISSING_OR_NULL_ORIGIN [5]. Fixes were later merged in PRs referenced by that issue (for users upgrading to newer versions on main/next) [5]. How to fix (practical checklist) 1) Ensure requests that carry cookies include Origin (or Referer) If you’re calling Better Auth with cookies (browser-like flows), the safest fix is to send an Origin header that matches your server configuration [2][3]. 2) Update trustedOrigins to include the exact origin/schemes you’re using Make sure trustedOrigins contains the relevant URL scheme(s) for your client (for example, your custom app scheme and any Expo-related origins) so origin validation can pass [4][6]. 3) For non-browser/dev clients, you can (temporarily) disable origin checking in development Some users resolve this in isolated dev environments by setting advanced.disableOriginCheck: true in the Better Auth config; this bypasses strict Origin checking but reduces CSRF protection and is not recommended for production [2]. 4) If using Expo, upgrade to a version where expo-origin → Origin mapping is correctly applied If you suspect the Expo plugin translation/middleware chaining issue, upgrade to a newer @better-auth/expo and better-auth versions that include the referenced fixes [5].

Citations:

• 1: https://github.com/better-auth/better-auth/blob/938efee3/packages/core/src/error/codes.ts
• 2: Email & Password Sign Up/Logout throws 403 MISSING_OR_NULL_ORIGIN better-auth/better-auth#5573
• 3: Origin Header Issue better-auth/better-auth#6257
• 4: Expo Android + Better Auth: 403 MISSING_OR_NULL_ORIGIN on sign-up/sign-in better-auth/better-auth#5750
• 5: [Expo] expo-origin → Origin translation in onRequest doesn't reach origin-check middleware better-auth/better-auth#9490
• 6: @better-auth/expo with phoneNumber - MISSING_OR_NULL_ORIGIN better-auth/better-auth#5536

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- dependency declarations ---'
cat -n blueprint/iam-better-auth/package.json | sed -n '1,90p'
printf '%s\n' '--- lockfile package metadata ---'
sed -n '4160,4180p' blueprint/pnpm-lock.yaml
sed -n '11190,11225p' blueprint/pnpm-lock.yaml
printf '%s\n' '--- header/request types and middleware call sites ---'
rg -n --glob '*.{ts,tsx}' 'interface .*Request|type .*Request|headers\s*=|req\.headers|enrichBetterAuthApi\(' blueprint packages cli | head -200

Repository: forklaunch/forklaunch

Length of output: 9581

🏁 Script executed:

#!/bin/bash
set -eu
python3 - <<'PY'
import json
import urllib.request

urls = {
    "origin-check-1.6.26": "https://raw.githubusercontent.com/better-auth/better-auth/v1.6.26/packages/better-auth/src/api/middlewares/origin-check.ts",
    "origin-check-main": "https://raw.githubusercontent.com/better-auth/better-auth/main/packages/better-auth/src/api/middlewares/origin-check.ts",
}
for name, url in urls.items():
    print(f"--- {name}: {url} ---")
    try:
        with urllib.request.urlopen(url, timeout=10) as response:
            text = response.read().decode()
        for i, line in enumerate(text.splitlines(), 1):
            if any(term in line for term in (
                "MISSING_OR_NULL_ORIGIN", "cookie", "origin", "referer",
                "Referer", "trustedOrigins", "disableOriginCheck"
            )):
                start = max(1, i - 3)
                end = min(len(text.splitlines()), i + 5)
                lines = text.splitlines()
                for j in range(start, end + 1):
                    print(f"{j}: {lines[j-1]}")
                print()
    except Exception as exc:
        print(type(exc).__name__, str(exc))
PY

Repository: forklaunch/forklaunch

Length of output: 746

🏁 Script executed:

#!/bin/bash
set -eu
for ref in v1.6.26 main; do
  url="https://raw.githubusercontent.com/better-auth/better-auth/${ref}/packages/better-auth/src/api/middlewares/origin-check.ts"
  printf '%s\n' "--- ${ref} ---"
  curl -ksSf "$url" | nl -ba | sed -n '1,220p'
done

Repository: forklaunch/forklaunch

Length of output: 460

🏁 Script executed:

#!/bin/bash
set -eu
for ref in v1.6.26 main; do
  url="https://raw.githubusercontent.com/better-auth/better-auth/${ref}/packages/better-auth/src/api/middlewares/origin-check.ts"
  printf '%s\n' "--- ${ref} ---"
  curl -kL --http1.1 -sS "$url" |
    awk '{ printf "%d:%s\n", NR, $0 }' |
    sed -n '1,220p'
done

Repository: forklaunch/forklaunch

Length of output: 15888

🏁 Script executed:

#!/bin/bash
set -eu
url="https://raw.githubusercontent.com/better-auth/better-auth/v1.6.26/packages/better-auth/src/api/middlewares/origin-check.ts"
curl -kL --http1.1 -sS "$url" |
  awk '{ printf "%d:%s\n", NR, $0 }' |
  sed -n '215,330p'

Repository: forklaunch/forklaunch

Length of output: 3735

🏁 Script executed:

#!/bin/bash
set -eu
printf '%s\n' '--- node adapter ---'
for path in \
  packages/better-auth/src/node.ts \
  packages/better-auth/src/node/index.ts \
  packages/better-auth/src/node/handler.ts \
  packages/better-auth/src/node-adapter.ts
do
  url="https://raw.githubusercontent.com/better-auth/better-auth/v1.6.26/${path}"
  body="$(curl -kL --http1.1 -sS "$url" || true)"
  if [ -n "$body" ]; then
    printf '%s\n' "--- ${path} ---"
    printf '%s\n' "$body" |
      awk '{ printf "%d:%s\n", NR, $0 }' |
      rg -n -C 5 'toNodeHandler|headers|new Headers|fromNodeHeaders'
  fi
done
printf '%s\n' '--- lockfile importer for IAM package ---'
rg -n -A70 '^  blueprint/iam-better-auth:' blueprint/pnpm-lock.yaml | sed -n '1,80p'

Repository: forklaunch/forklaunch

Length of output: 221

🏁 Script executed:

#!/bin/bash
set -u
printf '%s\n' '--- Better Auth v1.6.26 node-related paths ---'
curl -kL --http1.1 -sS \
  'https://api.github.com/repos/better-auth/better-auth/git/trees/v1.6.26?recursive=1' |
  rg -o '"path": "[^"]*(node|adapter|handler)[^"]*"' |
  head -80 || true
printf '%s\n' '--- lockfile importer for IAM package ---'
rg -n -A70 '^  blueprint/iam-better-auth:' blueprint/pnpm-lock.yaml |
  sed -n '1,80p' || true

Repository: forklaunch/forklaunch

Length of output: 4783

🏁 Script executed:

#!/bin/bash
set -eu
python3 - <<'PY'
from dataclasses import dataclass

TRUSTED = "http://localhost:8000"

def current(headers):
    origin = headers.get("origin")
    referer = headers.get("referer", headers.get("referrer"))
    usable = (
        isinstance(origin, str) and len(origin) > 0 and origin != "null"
    ) or (
        isinstance(referer, str) and len(referer) > 0 and referer != "null"
    )
    result = dict(headers)
    if not usable:
        result["origin"] = TRUSTED
    return result

def proposed(headers):
    origin = headers.get("origin")
    referer = headers.get("referer", headers.get("referrer"))
    result = dict(headers)
    if origin is None and referer is None:
        result["origin"] = TRUSTED
    return result

def better_auth_origin(headers):
    # Mirrors Better Auth v1.6.26:
    # headers.get("origin") || headers.get("referer") || ""
    origin = headers.get("origin")
    referer = headers.get("referer")
    return origin or referer or ""

def outcome(headers):
    value = better_auth_origin(headers)
    if not value or value == "null":
        return "MISSING_OR_NULL_ORIGIN"
    return "origin-validation"

cases = {
    "missing": {},
    "null origin": {"origin": "null"},
    "empty origin": {"origin": ""},
    "malformed origin": {"origin": "not an origin"},
    "array origin": {"origin": ["null"]},
    "null origin plus referer": {"origin": "null", "referer": TRUSTED},
    "referer only": {"referer": TRUSTED},
}
for name, headers in cases.items():
    c = current(headers)
    p = proposed(headers)
    print(name)
    print("  current :", c, "=>", outcome(c))
    print("  proposed:", p, "=>", outcome(p))
PY

Repository: forklaunch/forklaunch

Length of output: 1217

🏁 Script executed:

#!/bin/bash
set -u

rg -n -C 8 'clientIamBetterAuthSdkClient\s*\(' --glob '*.ts' --glob '*.tsx' . || true
rg -n -C 8 '\b(BETTER_AUTH_URL|HOST|PROTOCOL|PORT)\b' \
  blueprint/client-sdk blueprint/iam-better-auth || true

Repository: forklaunch/forklaunch

Length of output: 4661

🏁 Script executed:

#!/bin/bash
set -u

echo '--- candidate files ---'
git ls-files 'blueprint/client-sdk/*' 'blueprint/iam-better-auth/*' | sed -n '1,120p'

echo '--- client outline and source ---'
ast-grep outline blueprint/client-sdk/clientSdk.ts || true
sed -n '1,110p' blueprint/client-sdk/clientSdk.ts

echo '--- auth source ---'
ast-grep outline blueprint/iam-better-auth/auth.ts || true
sed -n '90,155p' blueprint/iam-better-auth/auth.ts

echo '--- all factory references ---'
rg -n -C 6 'clientIamBetterAuthSdkClient|clientSdk|BETTER_AUTH_URL|CORS_ORIGINS' \
  --glob '*.ts' --glob '*.tsx' --glob '*.json' --glob '*.yaml' --glob '*.yml' . || true

echo '--- likely tests and package metadata ---'
rg -n -i -C 3 'better.auth|better-auth|0\.0\.0\.0|trustedOrigins|origin' \
  blueprint --glob '*test*' --glob '*spec*' --glob '*.ts' --glob '*.tsx' || true

Repository: forklaunch/forklaunch

Length of output: 44660

🏁 Script executed:

#!/bin/bash
set -u

python3 - <<'PY'
from urllib.parse import urlsplit

for host in [
    "http://0.0.0.0:8000",
    "http://localhost:8000",
    "https://example.test:8443/path",
]:
    origin = f"{urlsplit(host).scheme}://{urlsplit(host).netloc}"
    public_host = urlsplit(host).hostname
    if public_host == "0.0.0.0":
        public_host = "localhost"
    canonical = f"{urlsplit(host).scheme}://{public_host}:{urlsplit(host).port}"
    print(f"host={host!r} origin={origin!r} fallback_baseURL={canonical!r} match={origin == canonical}")
PY

Repository: forklaunch/forklaunch

Length of output: 509

🌐 Web query:

Better Auth documentation baseURL trustedOrigins Origin missing null origin CSRF validation

💡 Result:

In Better Auth, the MISSING_OR_NULL_ORIGIN error occurs because of mandatory, strict CSRF validation introduced to secure cookie-based authentication [1][2]. Better Auth enforces origin validation whenever a request contains cookies [3][2]. If the Origin (or Referer) header is missing, empty, or set to "null", the library rejects the request with a 403 status code to prevent potential CSRF attacks [3][4][2]. Key points regarding this validation and configuration: 1. How it works: When a request includes cookies, Better Auth checks the Origin header against the trustedOrigins allowlist [5][3]. If the header is absent or evaluates to "null", validation fails automatically [3][2]. 2. Development Environments: This frequently affects tools like Postman or server-to-server requests that do not send an Origin header by default [1][2]. To resolve this for local development, you can: - Ensure your client sends a valid Origin header matching your configured trustedOrigins [2]. - Disable cookie persistence in your testing tool if the first request succeeds but subsequent ones fail [2]. - If absolutely necessary for testing, disable the check using advanced: { disableOriginCheck: true } in your configuration, though this should be avoided in production [1]. 3. Configuring Trusted Origins: - You can explicitly allow domains by adding them to the trustedOrigins option in your Better Auth configuration [5][6]. - Better Auth supports exact strings, wildcard patterns (e.g., https://*.example.com), and dynamic functions for per-request validation [7][6]. - The baseURL is trusted by default, and allowedHosts (if using dynamic base URLs) are automatically added to trustedOrigins [7][8][9]. 4. Security Best Practices: Always set an explicit baseURL or use environment variables to ensure consistent origin resolution [10]. Avoid leaving localhost in production configurations [6]. For detailed implementation, refer to the official documentation on Security and Options [7][5].

Citations:

• 1: Email & Password Sign Up/Logout throws 403 MISSING_OR_NULL_ORIGIN better-auth/better-auth#5573
• 2: Origin Header Issue better-auth/better-auth#6257
• 3: https://github.com/better-auth/better-auth/blob/cd2ea4cd/packages/better-auth/src/api/middlewares/origin-check.ts
• 4: Origin check blocks Electron apps using file:// better-auth/better-auth#7793
• 5: https://www.better-auth.com/docs/reference/security
• 6: https://github.com/better-auth/better-auth/blob/fd6b8c13/docs/content/docs/reference/security.mdx
• 7: https://better-auth.com/docs/reference/options
• 8: https://better-auth.com/docs/guides/dynamic-base-url
• 9: https://github.com/better-auth/better-auth/blob/main/docs/content/docs/guides/dynamic-base-url.mdx
• 10: https://github.com/better-auth/better-auth/blob/main/docs/content/docs/reference/options.mdx