@reckona/mreact-router 0.0.65 → 0.0.67

package/src/config.ts

@@ -0,0 +1,146 @@
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type AppRouterBuildTarget = "node" | "cloudflare" | "aws-lambda";
+export type AppRouterClientSourceMapMode = "none" | "hidden" | "linked";
+export type AppRouterClientSourceMapOption = boolean | AppRouterClientSourceMapMode;
+
+export interface AppRouterProjectOptions {
+  assetBaseUrl?: string | undefined;
+  buildTargets?: readonly AppRouterBuildTarget[] | undefined;
+  clientSourceMaps?: AppRouterClientSourceMapOption | undefined;
+  /**
+   * Legacy route root. When provided without routesDir/projectRoot, this keeps
+   * the historical "appDir is the whole app boundary" behavior.
+   *
+   * @deprecated Use projectRoot + routesDir instead. The legacy appDir shortcut
+   * is kept for direct tests and older programmatic callers and is planned for
+   * removal after 0.1.0.
+   */
+  appDir?: string | undefined;
+  allowedSourceDirs?: readonly string[] | undefined;
+  projectRoot?: string | undefined;
+  publicDir?: string | undefined;
+  publicAssetBaseUrl?: string | undefined;
+  routesDir?: string | undefined;
+}
+
+export interface ResolvedAppRouterProject {
+  allowedSourceDirs: readonly string[];
+  assetBaseUrl?: string | undefined;
+  buildTargets: readonly AppRouterBuildTarget[];
+  clientSourceMaps: AppRouterClientSourceMapMode;
+  projectRoot: string;
+  publicAssetBaseUrl?: string | undefined;
+  publicDir: string;
+  routesDir: string;
+}
+
+export function resolveAppRouterProjectOptions(
+  options: AppRouterProjectOptions,
+): ResolvedAppRouterProject {
+  if (
+    options.appDir !== undefined &&
+    options.projectRoot === undefined &&
+    options.routesDir === undefined
+  ) {
+    const appDir = resolve(options.appDir);
+
+    return {
+      allowedSourceDirs: (options.allowedSourceDirs ?? [appDir]).map((directory) =>
+        resolveProjectPath(appDir, directory, "allowedSourceDirs"),
+      ),
+      ...(options.assetBaseUrl === undefined ? {} : { assetBaseUrl: options.assetBaseUrl }),
+      buildTargets: resolveBuildTargets(options.buildTargets),
+      clientSourceMaps: resolveClientSourceMapMode(options.clientSourceMaps),
+      projectRoot: appDir,
+      ...(options.publicAssetBaseUrl === undefined
+        ? {}
+        : { publicAssetBaseUrl: options.publicAssetBaseUrl }),
+      publicDir: resolveProjectPath(appDir, options.publicDir ?? "public", "publicDir"),
+      routesDir: appDir,
+    };
+  }
+
+  const projectRoot = resolve(options.projectRoot ?? process.cwd());
+
+  return {
+    allowedSourceDirs: (options.allowedSourceDirs ?? ["src"]).map((directory) =>
+      resolveProjectPath(projectRoot, directory, "allowedSourceDirs"),
+    ),
+    ...(options.assetBaseUrl === undefined ? {} : { assetBaseUrl: options.assetBaseUrl }),
+    buildTargets: resolveBuildTargets(options.buildTargets),
+    clientSourceMaps: resolveClientSourceMapMode(options.clientSourceMaps),
+    projectRoot,
+    ...(options.publicAssetBaseUrl === undefined
+      ? {}
+      : { publicAssetBaseUrl: options.publicAssetBaseUrl }),
+    publicDir: resolveProjectPath(projectRoot, options.publicDir ?? "public", "publicDir"),
+    routesDir: resolveProjectPath(projectRoot, options.routesDir ?? "src/app", "routesDir"),
+  };
+}
+
+export function resolveClientSourceMapMode(
+  value: AppRouterClientSourceMapOption | undefined,
+): AppRouterClientSourceMapMode {
+  if (value === undefined || value === false || value === "none") {
+    return "none";
+  }
+
+  if (value === true || value === "linked") {
+    return "linked";
+  }
+
+  if (value === "hidden") {
+    return "hidden";
+  }
+
+  throw new Error(
+    `Unsupported mreactRouter clientSourceMaps value ${JSON.stringify(value)}. Expected false, true, "none", "hidden", or "linked".`,
+  );
+}
+
+export function resolveBuildTargets(
+  targets: readonly AppRouterBuildTarget[] | undefined,
+): readonly AppRouterBuildTarget[] {
+  if (targets === undefined) {
+    return ["node", "cloudflare"];
+  }
+
+  const uniqueTargets = [...new Set(targets)];
+
+  if (uniqueTargets.length === 0) {
+    throw new Error("mreactRouter buildTargets must include at least one target.");
+  }
+
+  for (const target of uniqueTargets) {
+    if (target !== "node" && target !== "cloudflare" && target !== "aws-lambda") {
+      throw new Error(
+        `Unsupported mreactRouter build target ${JSON.stringify(target)}. Expected "node", "cloudflare", or "aws-lambda".`,
+      );
+    }
+  }
+
+  return uniqueTargets;
+}
+
+function resolveProjectPath(root: string, path: string, optionName: string): string {
+  const resolvedPath = resolvePath(root, path);
+
+  if (!isInsideDirectory(root, resolvedPath)) {
+    throw new Error(
+      `mreactRouter ${optionName} must resolve inside projectRoot. projectRoot: ${root}; ${optionName}: ${resolvedPath}`,
+    );
+  }
+
+  return resolvedPath;
+}
+
+function resolvePath(root: string, path: string): string {
+  return isAbsolute(path) ? resolve(path) : resolve(root, path);
+}
+
+function isInsideDirectory(root: string, path: string): boolean {
+  const relativePath = relative(root, path);
+
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}

package/src/cookies.ts

@@ -0,0 +1,113 @@
+export interface CookieOptions {
+  domain?: string;
+  expires?: Date;
+  httpOnly?: boolean;
+  maxAge?: number;
+  path?: string;
+  sameSite?: "Strict" | "Lax" | "None";
+  secure?: boolean;
+}
+
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+function assertCookieName(name: string): void {
+  if (!COOKIE_NAME.test(name)) {
+    throw new TypeError(`invalid cookie name: ${JSON.stringify(name)}`);
+  }
+}
+
+function assertAttributeValue(value: string): void {
+  if (/[\r\n;]/.test(value)) {
+    throw new TypeError(`invalid cookie attribute value: ${JSON.stringify(value)}`);
+  }
+}
+
+export function parseCookieHeader(
+  cookieHeader: string | null | undefined,
+): Map<string, string> {
+  const values = new Map<string, string>();
+
+  for (const part of (cookieHeader ?? "").split(";")) {
+    const [rawName, ...rawValue] = part.trim().split("=");
+
+    if (rawName === undefined || rawName === "") {
+      continue;
+    }
+
+    const raw = rawValue.join("=");
+    if (raw.indexOf("%") === -1) {
+      values.set(rawName, raw);
+      continue;
+    }
+
+    try {
+      values.set(rawName, decodeURIComponent(raw));
+    } catch {
+      // Treat malformed cookie values as absent for this request.
+    }
+  }
+
+  return values;
+}
+
+export function serializeCookie(
+  name: string,
+  value: string,
+  options: CookieOptions = {},
+): string {
+  assertCookieName(name);
+
+  if (options.sameSite === "None" && options.secure !== true) {
+    throw new TypeError("SameSite=None requires Secure");
+  }
+
+  const parts = [`${name}=${encodeURIComponent(value)}`];
+
+  if (options.maxAge !== undefined) {
+    if (!Number.isSafeInteger(options.maxAge)) {
+      throw new TypeError("invalid cookie Max-Age");
+    }
+    parts.push(`Max-Age=${options.maxAge}`);
+  }
+
+  if (options.domain !== undefined) {
+    assertAttributeValue(options.domain);
+    parts.push(`Domain=${options.domain}`);
+  }
+
+  if (options.path !== undefined) {
+    assertAttributeValue(options.path);
+    parts.push(`Path=${options.path}`);
+  }
+
+  if (options.expires !== undefined) {
+    parts.push(`Expires=${options.expires.toUTCString()}`);
+  }
+
+  if (options.httpOnly === true) parts.push("HttpOnly");
+  if (options.secure === true) parts.push("Secure");
+  if (options.sameSite !== undefined) parts.push(`SameSite=${options.sameSite}`);
+
+  return parts.join("; ");
+}
+
+export function setCookie(
+  response: Response,
+  name: string,
+  value: string,
+  options: CookieOptions = {},
+): Response {
+  response.headers.append("set-cookie", serializeCookie(name, value, options));
+  return response;
+}
+
+export function deleteCookie(
+  response: Response,
+  name: string,
+  options: Pick<CookieOptions, "domain" | "path" | "sameSite" | "secure"> = {},
+): Response {
+  return setCookie(response, name, "", {
+    ...options,
+    maxAge: 0,
+  });
+}

package/src/csp.ts

@@ -0,0 +1,103 @@
+// CSP header serializer used by the App Router metadata pipeline.
+//
+// Validates both nonce and directive values before string-concatenating
+// them into the Content-Security-Policy header. Background: directive
+// concatenation with `; ` and quoted-source concatenation with `' '` are
+// trivially escapable if untrusted strings reach the metadata field.
+//
+// Allowed nonce shape: base64 / base64url alphabet only (`+/=` and `-_=`).
+// Allowed directive value shape: no `;`, no quote, no whitespace, no ASCII
+// control characters. Quoted-keyword forms (`'self'`, `'nonce-...'`,
+// `'sha256-...'`, etc.) are accepted via the `'...'` allow-list pattern.
+
+export interface ContentSecurityPolicyInput {
+  disable?: boolean;
+  directives?: Record<string, readonly string[] | string>;
+  nonce?: string;
+  remove?: readonly string[];
+  replace?: Record<string, readonly string[] | string>;
+}
+
+const VALID_NONCE = /^[A-Za-z0-9+/=_-]+$/;
+const VALID_DIRECTIVE_NAME = /^[a-z][a-z0-9-]*$/i;
+// One CSP "source expression". Reject anything containing `;`, quote,
+// whitespace, or ASCII control characters. Quoted keywords like
+// `'self'`, `'unsafe-inline'`, `'nonce-XYZ='` are accepted via the
+// alternate `'...'` shape.
+const VALID_QUOTED_DIRECTIVE_VALUE = /^'[A-Za-z0-9+/=_:.-]+'$/;
+
+function isValidNonce(nonce: string): boolean {
+  return VALID_NONCE.test(nonce);
+}
+
+function isValidDirectiveName(name: string): boolean {
+  return VALID_DIRECTIVE_NAME.test(name);
+}
+
+function isValidDirectiveValue(value: string): boolean {
+  if (VALID_QUOTED_DIRECTIVE_VALUE.test(value)) {
+    return true;
+  }
+
+  if (value.length === 0) {
+    return false;
+  }
+
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+
+    if (
+      code <= 0x20 ||
+      code === 0x22 ||
+      code === 0x27 ||
+      code === 0x3b ||
+      code === 0x7f
+    ) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+export function contentSecurityPolicy(
+  csp: ContentSecurityPolicyInput | undefined,
+): string | undefined {
+  if (csp?.disable === true || csp?.directives === undefined) {
+    return undefined;
+  }
+
+  if (csp.nonce !== undefined && !isValidNonce(csp.nonce)) {
+    throw new TypeError(
+      `invalid CSP nonce: ${JSON.stringify(csp.nonce)} - must be base64 / base64url`,
+    );
+  }
+
+  const serialized: string[] = [];
+
+  for (const [name, value] of Object.entries(csp.directives)) {
+    if (!isValidDirectiveName(name)) {
+      throw new TypeError(`invalid CSP directive name: ${JSON.stringify(name)}`);
+    }
+
+    const rawValues = Array.isArray(value) ? [...value] : [value];
+
+    for (const rawValue of rawValues) {
+      if (typeof rawValue !== "string" || !isValidDirectiveValue(rawValue)) {
+        throw new TypeError(
+          `invalid CSP directive value for ${name}: ${JSON.stringify(rawValue)}`,
+        );
+      }
+    }
+
+    const values = [...rawValues];
+
+    if (csp.nonce !== undefined && (name === "script-src" || name === "style-src")) {
+      values.push(`'nonce-${csp.nonce}'`);
+    }
+
+    serialized.push(`${name} ${values.join(" ")}`);
+  }
+
+  return serialized.join("; ");
+}

package/src/csrf.ts

@@ -0,0 +1,132 @@
+const csrfCookieNameProduction = "__Host-mreact.csrf";
+const csrfCookieNameDevelopment = "mreact.csrf";
+const csrfCookieNamesRead = [csrfCookieNameProduction, csrfCookieNameDevelopment];
+const formFieldCsrf = "__mreact_csrf";
+
+export const formCsrfFieldName = formFieldCsrf;
+
+export function serverActionCookie(csrfToken: string): string {
+  const production = isProductionEnvironment();
+  const parts = [
+    `${currentCsrfCookieName()}=${encodeURIComponent(csrfToken)}`,
+    "Path=/",
+    "SameSite=Lax",
+    "HttpOnly",
+  ];
+
+  if (production) {
+    parts.push("Secure");
+  }
+
+  return parts.join("; ");
+}
+
+export function createFormCsrfToken(request?: Request | undefined): string {
+  return readExistingFormCsrfToken(request) ?? randomToken();
+}
+
+export function formCsrfCookie(csrfToken: string): string {
+  return serverActionCookie(csrfToken);
+}
+
+export function validateFormCsrf(request: Request, formData: FormData): Response | undefined {
+  const formToken = stringFormValue(formData.get(formFieldCsrf));
+  const cookieHeader = request.headers.get("cookie");
+  const cookieToken = csrfCookieNamesRead
+    .map((name) => readCookie(cookieHeader, name))
+    .find((token) => token !== undefined);
+
+  if (formToken === undefined || cookieToken === undefined) {
+    return jsonResponse({ ok: false, error: "Invalid CSRF token." }, 403);
+  }
+
+  return timingSafeStringEqual(formToken, cookieToken)
+    ? undefined
+    : jsonResponse({ ok: false, error: "Invalid CSRF token." }, 403);
+}
+
+export function readExistingFormCsrfToken(request: Request | undefined): string | undefined {
+  const cookieHeader = request?.headers.get("cookie") ?? null;
+
+  for (const name of csrfCookieNamesRead) {
+    const token = readCookie(cookieHeader, name);
+
+    if (token !== undefined && isCsrfTokenShape(token)) {
+      return token;
+    }
+  }
+
+  return undefined;
+}
+
+function isCsrfTokenShape(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function randomToken(): string {
+  const cryptoApi = globalThis.crypto;
+
+  if (typeof cryptoApi?.randomUUID === "function") {
+    return cryptoApi.randomUUID();
+  }
+
+  if (typeof cryptoApi?.getRandomValues !== "function") {
+    throw new Error("Web Crypto is required to create a CSRF token.");
+  }
+
+  const bytes = new Uint8Array(16);
+  cryptoApi.getRandomValues(bytes);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
+}
+
+function isProductionEnvironment(): boolean {
+  return typeof process !== "undefined" && process.env?.NODE_ENV === "production";
+}
+
+function currentCsrfCookieName(): string {
+  return isProductionEnvironment() ? csrfCookieNameProduction : csrfCookieNameDevelopment;
+}
+
+function timingSafeStringEqual(left: string, right: string): boolean {
+  let diff = left.length ^ right.length;
+  const length = Math.max(left.length, right.length);
+
+  for (let index = 0; index < length; index += 1) {
+    diff |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+  }
+
+  return diff === 0;
+}
+
+function stringFormValue(value: FormDataEntryValue | null): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readCookie(cookieHeader: string | null, name: string): string | undefined {
+  if (cookieHeader === null || cookieHeader.trim() === "") {
+    return undefined;
+  }
+
+  for (const part of cookieHeader.split(";")) {
+    const [rawName, ...rawValue] = part.trim().split("=");
+
+    if (rawName !== name) {
+      continue;
+    }
+
+    try {
+      return decodeURIComponent(rawValue.join("="));
+    } catch {
+      return rawValue.join("=");
+    }
+  }
+
+  return undefined;
+}
+
+function jsonResponse(payload: unknown, status: number): Response {
+  return Response.json(payload, { status });
+}

package/src/deferred.ts

@@ -0,0 +1,52 @@
+const deferredLoaderDataSymbol = Symbol.for("mreact.router.deferred-loader-data");
+
+export type DeferredLoaderData<TData extends Record<string, unknown>> = TData & {
+  readonly [deferredLoaderDataSymbol]: true;
+};
+
+export function defer<TData extends Record<string, unknown>>(
+  data: TData,
+): DeferredLoaderData<TData> {
+  markTopLevelPromisesHandled(data);
+
+  return Object.defineProperty(data, deferredLoaderDataSymbol, {
+    enumerable: false,
+    value: true,
+  }) as DeferredLoaderData<TData>;
+}
+
+export function isDeferredLoaderData(
+  value: unknown,
+): value is DeferredLoaderData<Record<string, unknown>> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [deferredLoaderDataSymbol]?: unknown })[deferredLoaderDataSymbol] === true
+  );
+}
+
+export function unwrapDeferredLoaderData<TData extends Record<string, unknown>>(
+  data: DeferredLoaderData<TData>,
+): TData {
+  return data;
+}
+
+function markTopLevelPromisesHandled(data: Record<string, unknown>): void {
+  for (const value of Object.values(data)) {
+    if (isPromiseLike(value)) {
+      // Avoid process-level unhandled rejection noise before <Await> attaches
+      // its boundary handlers. Callers should still render every deferred
+      // promise through <Await catch>; unused rejected fields will not surface
+      // as unhandled rejections.
+      void Promise.resolve(value).catch(() => {});
+    }
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" || typeof value === "function") &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}