@pablozaiden/webapp 0.6.0 → 0.6.1

package/README.md

@@ -22,7 +22,7 @@ Each application package must declare `react` and `react-dom`; they are peer dep
 
 | Export | Use |
 | --- | --- |
-| `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
+| `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, request-origin helpers, SQLite store |
 | `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
 | `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
 | `@pablozaiden/webapp/cli` | One-binary command helpers, device/environment auth credentials and generic API CLI caller |

package/docs/auth.md

@@ -74,8 +74,9 @@ The same normalized request context drives expected same-origin origins,
 WebSocket origin checks, passkey expected origins and RP IDs, the `Secure`
 cookie attribute, cookie paths, setup links, and device/discovery URLs.
 `{PREFIX}_PUBLIC_BASE_URL` is authoritative for origin, hostname, and secure
-state even when forwarded headers are present; trusted prefixes remain
-policy-controlled for path-bearing cookies and links.
+state even when forwarded headers are present. It must be an origin-only
+absolute `http` or `https` URL; trusted prefixes remain policy-controlled for
+path-bearing cookies and links.
 
 Trust mode is a deployment boundary setting, not a way to trust arbitrary
 client input. The reverse proxy must strip client-supplied forwarded headers
@@ -84,3 +85,10 @@ single-value headers. Do not expose the application directly to untrusted
 clients when trust mode is enabled. This release does not implement a
 proxy-address allowlist, so the network boundary and proxy sanitization are
 required.
+
+Applications that generate their own public URLs should use
+`getRequestOriginInfo` or `getRequestBaseUrl` from
+`@pablozaiden/webapp/server` with the server's runtime config instead of
+parsing `{PREFIX}_PUBLIC_BASE_URL` independently. The framework validates the
+configured public base URL during startup and applies the same trusted-proxy
+policy used by its authentication and origin checks.

package/docs/getting-started.md

@@ -186,7 +186,7 @@ The app configures an uppercase `envPrefix`; the framework reads only variables
 | `{PREFIX}_TRUST_PROXY` | `false` | Explicitly trust the documented `X-Forwarded-*` headers; keep disabled for direct deployments |
 | `{PREFIX}_TRUST_PROXY_HEADERS` | `proto,host,prefix` when enabled | Comma-separated subset of supported forwarded values: `proto`, `host`, `prefix` |
 | `{PREFIX}_TRUST_PROXY_CHAIN` | `first` | Select the left-most (`first`) or right-most (`last`) non-empty value from comma-separated forwarded headers |
-| `{PREFIX}_PUBLIC_BASE_URL` | request origin | Authoritative external origin for auth/device URLs; it overrides forwarded protocol and host values |
+| `{PREFIX}_PUBLIC_BASE_URL` | request origin | Authoritative absolute `http` or `https` origin (without a path, query, or fragment) for auth/device URLs; it overrides forwarded protocol and host values |
 | `{PREFIX}_AUTH_ISSUER` | `urn:{prefix}:webapp` | JWT issuer override |
 
 The configured data directory contains the framework-owned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",

package/src/server/index.ts

@@ -3,6 +3,7 @@ export * from "./routes";
 export * from "./route-catalog";
 export * from "./responses";
 export * from "./create-web-app-server";
+export { getRequestBaseUrl, getRequestOriginInfo, type RequestOriginInfo } from "./auth/request-origin";
 export * from "./auth/store";
 export * from "./auth/sqlite-store";
 export * from "./realtime/bus";

package/src/server/runtime-config.ts

@@ -84,6 +84,30 @@ function parseBoolean(raw: string | undefined, fallback: boolean, name: string):
   throw new Error(`${name} must be true or false; received "${raw}"`);
 }
 
+function parsePublicBaseUrl(raw: string | undefined, name: string): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${name} must be a valid absolute http(s) origin; received "${raw}"`);
+  }
+  if (
+    (parsed.protocol !== "http:" && parsed.protocol !== "https:") ||
+    parsed.username ||
+    parsed.password ||
+    parsed.origin === "null" ||
+    parsed.pathname !== "/" ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(`${name} must be a valid absolute http(s) origin; received "${raw}"`);
+  }
+  return parsed.origin;
+}
+
 function parseTrustProxyHeaders(raw: string | undefined, enabled: boolean, name: string): TrustProxyHeader[] {
   if (raw === undefined) {
     return enabled ? [...TRUST_PROXY_HEADERS] : [];
@@ -122,6 +146,7 @@ export function readRuntimeConfig(input: {
   const envPrefix = assertEnvPrefix(input.envPrefix);
   const logLevelRaw = readEnv(envPrefix, "LOG_LEVEL");
   const logLevel = parseLogLevel(logLevelRaw, input.defaultLogLevel ?? "info", envName(envPrefix, "LOG_LEVEL"));
+  const publicBaseUrl = parsePublicBaseUrl(readEnv(envPrefix, "PUBLIC_BASE_URL"), envName(envPrefix, "PUBLIC_BASE_URL"));
   const trustProxyEnabled = parseBoolean(readEnv(envPrefix, "TRUST_PROXY"), false, envName(envPrefix, "TRUST_PROXY"));
   const trustProxy = {
     enabled: trustProxyEnabled,
@@ -138,7 +163,7 @@ export function readRuntimeConfig(input: {
     logLevelFromEnv: Boolean(logLevelRaw),
     passkeyDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_PASSKEY")),
     sameOriginDisabled: isTruthyEnv(readEnv(envPrefix, "DISABLE_SAME_ORIGIN_CHECK")),
-    publicBaseUrl: readEnv(envPrefix, "PUBLIC_BASE_URL"),
+    publicBaseUrl,
     authIssuer: readEnv(envPrefix, "AUTH_ISSUER"),
     trustProxy,
     development: process.env["NODE_ENV"] === "production" ? false : { hmr: true, console: true },