@bquery/bquery 1.1.2 → 1.3.0

package/src/router/state.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal router state (active router and current route signal).
+ * @module bquery/router
+ */
+
+import { computed, signal, type ReadonlySignal, type Signal } from '../reactive/index';
+import type { Route, Router } from './types';
+
+// ============================================================================
+// Internal State
+// ============================================================================
+
+/** @internal */
+let activeRouter: Router | null = null;
+
+/** @internal */
+export const routeSignal: Signal<Route> = signal<Route>({
+  path: '',
+  params: {},
+  query: {},
+  matched: null,
+  hash: '',
+});
+
+/**
+ * Reactive signal containing the current route.
+ *
+ * @example
+ * ```ts
+ * import { currentRoute } from 'bquery/router';
+ * import { effect } from 'bquery/reactive';
+ *
+ * effect(() => {
+ *   document.title = `Page: ${currentRoute.value.path}`;
+ * });
+ * ```
+ */
+export const currentRoute: ReadonlySignal<Route> = computed(() => routeSignal.value);
+
+/** @internal */
+export const getActiveRouter = (): Router | null => activeRouter;
+
+/** @internal */
+export const setActiveRouter = (router: Router | null): void => {
+  activeRouter = router;
+};

package/src/router/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Router types and public contracts.
+ * @module bquery/router
+ */
+
+import type { ReadonlySignal } from '../reactive/index';
+
+/**
+ * Represents a parsed route with matched params.
+ */
+export type Route = {
+  /** The current path (e.g., '/user/42') */
+  path: string;
+  /** Extracted route params (e.g., { id: '42' }) */
+  params: Record<string, string>;
+  /**
+   * Query string params.
+   * Each key maps to a single string value by default.
+   * Only keys that appear multiple times in the query string become arrays.
+   * @example
+   * // ?foo=1 → { foo: '1' }
+   * // ?tag=a&tag=b → { tag: ['a', 'b'] }
+   * // ?x=1&y=2&x=3 → { x: ['1', '3'], y: '2' }
+   */
+  query: Record<string, string | string[]>;
+  /** The matched route definition */
+  matched: RouteDefinition | null;
+  /** Hash fragment without # */
+  hash: string;
+};
+
+/**
+ * Route definition for configuration.
+ */
+export type RouteDefinition = {
+  /** Path pattern (e.g., '/user/:id', '/posts/*') */
+  path: string;
+  /** Component loader (sync or async) */
+  component: () => unknown | Promise<unknown>;
+  /** Optional route name for programmatic navigation */
+  name?: string;
+  /** Optional metadata */
+  meta?: Record<string, unknown>;
+  /** Nested child routes */
+  children?: RouteDefinition[];
+};
+
+/**
+ * Router configuration options.
+ */
+export type RouterOptions = {
+  /** Array of route definitions */
+  routes: RouteDefinition[];
+  /** Base path for all routes (default: '') */
+  base?: string;
+  /** Use hash-based routing instead of history (default: false) */
+  hash?: boolean;
+};
+
+/**
+ * Navigation guard function type.
+ */
+export type NavigationGuard = (to: Route, from: Route) => boolean | void | Promise<boolean | void>;
+
+/**
+ * Router instance returned by createRouter.
+ */
+export type Router = {
+  /** Navigate to a path */
+  push: (path: string) => Promise<void>;
+  /** Replace current history entry */
+  replace: (path: string) => Promise<void>;
+  /** Go back in history */
+  back: () => void;
+  /** Go forward in history */
+  forward: () => void;
+  /** Go to a specific history entry */
+  go: (delta: number) => void;
+  /** Add a beforeEach guard */
+  beforeEach: (guard: NavigationGuard) => () => void;
+  /** Add an afterEach hook */
+  afterEach: (hook: (to: Route, from: Route) => void) => () => void;
+  /** Current route (reactive) */
+  currentRoute: ReadonlySignal<Route>;
+  /** All route definitions */
+  routes: RouteDefinition[];
+  /** Base path for all routes */
+  base: string;
+  /** Whether hash-based routing is enabled */
+  hash: boolean;
+  /** Destroy the router and cleanup listeners */
+  destroy: () => void;
+};

package/src/router/utils.ts

@@ -0,0 +1,116 @@
+/**
+ * Router utilities.
+ * @module bquery/router
+ */
+
+import { computed, type ReadonlySignal } from '../reactive/index';
+import { getActiveRouter, routeSignal } from './state';
+import type { RouteDefinition } from './types';
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Flattens nested routes into a single array with full paths.
+ * Does NOT include the router base - base is only for browser history.
+ * @internal
+ */
+export const flattenRoutes = (routes: RouteDefinition[], parentPath = ''): RouteDefinition[] => {
+  const result: RouteDefinition[] = [];
+
+  for (const route of routes) {
+    const fullPath = route.path === '*' ? '*' : `${parentPath}${route.path}`.replace(/\/+/g, '/');
+
+    result.push({
+      ...route,
+      path: fullPath,
+    });
+
+    if (route.children) {
+      result.push(...flattenRoutes(route.children, fullPath));
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Resolves a route by name and params.
+ *
+ * @param name - The route name
+ * @param params - Route params to interpolate
+ * @returns The resolved path
+ *
+ * @example
+ * ```ts
+ * import { resolve } from 'bquery/router';
+ *
+ * const path = resolve('user', { id: '42' });
+ * // Returns '/user/42' if route is defined as { name: 'user', path: '/user/:id' }
+ * ```
+ */
+export const resolve = (name: string, params: Record<string, string> = {}): string => {
+  const activeRouter = getActiveRouter();
+  if (!activeRouter) {
+    throw new Error('bQuery router: No router initialized.');
+  }
+
+  const route = activeRouter.routes.find((r) => r.name === name);
+  if (!route) {
+    throw new Error(`bQuery router: Route "${name}" not found.`);
+  }
+
+  let path = route.path;
+  for (const [key, value] of Object.entries(params)) {
+    path = path.replace(`:${key}`, encodeURIComponent(value));
+  }
+
+  return path;
+};
+
+/**
+ * Checks if a path matches the current route.
+ *
+ * @param path - Path to check
+ * @param exact - Whether to match exactly (default: false)
+ * @returns True if the path matches
+ *
+ * @example
+ * ```ts
+ * import { isActive } from 'bquery/router';
+ *
+ * if (isActive('/dashboard')) {
+ *   // Highlight nav item
+ * }
+ * ```
+ */
+export const isActive = (path: string, exact = false): boolean => {
+  const current = routeSignal.value.path;
+  return exact ? current === path : current.startsWith(path);
+};
+
+/**
+ * Creates a computed signal that checks if a path is active.
+ *
+ * @param path - Path to check
+ * @param exact - Whether to match exactly
+ * @returns A reactive signal
+ *
+ * @example
+ * ```ts
+ * import { isActiveSignal } from 'bquery/router';
+ * import { effect } from 'bquery/reactive';
+ *
+ * const dashboardActive = isActiveSignal('/dashboard');
+ * effect(() => {
+ *   navItem.classList.toggle('active', dashboardActive.value);
+ * });
+ * ```
+ */
+export const isActiveSignal = (path: string, exact = false): ReadonlySignal<boolean> => {
+  return computed(() => {
+    const current = routeSignal.value.path;
+    return exact ? current === path : current.startsWith(path);
+  });
+};

package/src/security/constants.ts

@@ -0,0 +1,209 @@
+/**
+ * Security constants and safe lists.
+ *
+ * @module bquery/security
+ */
+
+/**
+ * Trusted Types policy name.
+ */
+export const POLICY_NAME = 'bquery-sanitizer';
+
+/**
+ * Default allowed HTML tags considered safe.
+ */
+export const DEFAULT_ALLOWED_TAGS = new Set([
+  'a',
+  'abbr',
+  'address',
+  'article',
+  'aside',
+  'b',
+  'bdi',
+  'bdo',
+  'blockquote',
+  'br',
+  'button',
+  'caption',
+  'cite',
+  'code',
+  'col',
+  'colgroup',
+  'data',
+  'dd',
+  'del',
+  'details',
+  'dfn',
+  'div',
+  'dl',
+  'dt',
+  'em',
+  'figcaption',
+  'figure',
+  'footer',
+  'form',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'header',
+  'hgroup',
+  'hr',
+  'i',
+  'img',
+  'input',
+  'ins',
+  'kbd',
+  'label',
+  'legend',
+  'li',
+  'main',
+  'mark',
+  'nav',
+  'ol',
+  'optgroup',
+  'option',
+  'p',
+  'picture',
+  'pre',
+  'progress',
+  'q',
+  'rp',
+  'rt',
+  'ruby',
+  's',
+  'samp',
+  'section',
+  'select',
+  'small',
+  'source',
+  'span',
+  'strong',
+  'sub',
+  'summary',
+  'sup',
+  'table',
+  'tbody',
+  'td',
+  'textarea',
+  'tfoot',
+  'th',
+  'thead',
+  'time',
+  'tr',
+  'u',
+  'ul',
+  'var',
+  'wbr',
+]);
+
+/**
+ * Explicitly dangerous tags that should never be allowed.
+ * These are checked even if somehow added to allowTags.
+ */
+export const DANGEROUS_TAGS = new Set([
+  'script',
+  'iframe',
+  'frame',
+  'frameset',
+  'object',
+  'embed',
+  'applet',
+  'link',
+  'meta',
+  'style',
+  'base',
+  'template',
+  'slot',
+  'math',
+  'svg',
+  'foreignobject',
+  'noscript',
+]);
+
+/**
+ * Reserved IDs that could cause DOM clobbering attacks.
+ * These are prevented to avoid overwriting global browser objects.
+ */
+export const RESERVED_IDS = new Set([
+  // Global objects
+  'document',
+  'window',
+  'location',
+  'top',
+  'self',
+  'parent',
+  'frames',
+  'history',
+  'navigator',
+  'screen',
+  // Dangerous functions
+  'alert',
+  'confirm',
+  'prompt',
+  'eval',
+  'function',
+  // Document properties
+  'cookie',
+  'domain',
+  'referrer',
+  'body',
+  'head',
+  'forms',
+  'images',
+  'links',
+  'scripts',
+  // DOM traversal properties
+  'children',
+  'parentnode',
+  'firstchild',
+  'lastchild',
+  // Content manipulation
+  'innerhtml',
+  'outerhtml',
+  'textcontent',
+]);
+
+/**
+ * Default allowed attributes considered safe.
+ * Note: 'style' is excluded by default because inline CSS can be abused for:
+ * - UI redressing attacks
+ * - Data exfiltration via url() in CSS
+ * - CSS injection vectors
+ * If you need to allow inline styles, add 'style' to allowAttributes in your
+ * sanitizeHtml options, but ensure you implement proper CSS value validation.
+ */
+export const DEFAULT_ALLOWED_ATTRIBUTES = new Set([
+  'alt',
+  'class',
+  'dir',
+  'height',
+  'hidden',
+  'href',
+  'id',
+  'lang',
+  'loading',
+  'name',
+  'rel',
+  'role',
+  'src',
+  'srcset',
+  'tabindex',
+  'target',
+  'title',
+  'type',
+  'width',
+  'aria-*',
+]);
+
+/**
+ * Dangerous attribute prefixes to always remove.
+ */
+export const DANGEROUS_ATTR_PREFIXES = ['on', 'formaction', 'xlink:', 'xmlns:'];
+
+/**
+ * Dangerous URL protocols to block.
+ */
+export const DANGEROUS_PROTOCOLS = ['javascript:', 'data:', 'vbscript:', 'file:'];

package/src/security/csp.ts

@@ -0,0 +1,77 @@
+/**
+ * Content Security Policy helpers.
+ *
+ * @module bquery/security
+ */
+
+/** Maximum allowed nonce length to prevent memory issues */
+const MAX_NONCE_LENGTH = 1024;
+
+/** Chunk size for building strings to avoid argument limit in String.fromCharCode */
+const CHUNK_SIZE = 8192;
+
+/**
+ * Generate a nonce for inline scripts/styles.
+ * Use with Content-Security-Policy nonce directives.
+ *
+ * @param length - Nonce length in bytes (default: 16, max: 1024)
+ * @returns Cryptographically random nonce string
+ * @throws {Error} If crypto.getRandomValues or btoa are not available
+ * @throws {RangeError} If length is invalid (negative, non-integer, or exceeds maximum)
+ */
+export const generateNonce = (length: number = 16): string => {
+  // Validate length parameter
+  if (!Number.isInteger(length) || length < 1) {
+    throw new RangeError('generateNonce length must be a positive integer');
+  }
+  if (length > MAX_NONCE_LENGTH) {
+    throw new RangeError(`generateNonce length must not exceed ${MAX_NONCE_LENGTH}`);
+  }
+
+  // Check for required globals in browser/crypto environments
+  if (
+    typeof globalThis.crypto === 'undefined' ||
+    typeof globalThis.crypto.getRandomValues !== 'function'
+  ) {
+    throw new Error(
+      'generateNonce requires crypto.getRandomValues (not available in this environment)'
+    );
+  }
+  if (typeof globalThis.btoa !== 'function') {
+    throw new Error('generateNonce requires btoa (not available in this environment)');
+  }
+
+  const array = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(array);
+
+  // Build string in chunks to avoid argument limit in String.fromCharCode
+  let binaryString = '';
+  for (let i = 0; i < array.length; i += CHUNK_SIZE) {
+    const chunk = array.subarray(i, Math.min(i + CHUNK_SIZE, array.length));
+    binaryString += String.fromCharCode(...chunk);
+  }
+
+  return globalThis.btoa(binaryString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+};
+
+/**
+ * Check if a CSP header is present with specific directive.
+ * Useful for feature detection and fallback strategies.
+ *
+ * @param directive - The CSP directive to check (e.g., 'script-src')
+ * @returns True if the directive appears to be enforced
+ */
+export const hasCSPDirective = (directive: string): boolean => {
+  // Guard for non-DOM environments (SSR, tests, etc.)
+  if (typeof document === 'undefined') {
+    return false;
+  }
+
+  // Check meta tag
+  const meta = document.querySelector('meta[http-equiv="Content-Security-Policy"]');
+  if (meta) {
+    const content = meta.getAttribute('content') ?? '';
+    return content.includes(directive);
+  }
+  return false;
+};

package/src/security/index.ts

@@ -4,15 +4,7 @@
  * @module bquery/security
  */
 
-export {
-  createTrustedHtml,
-  escapeHtml,
-  generateNonce,
-  getTrustedTypesPolicy,
-  hasCSPDirective,
-  isTrustedTypesSupported,
-  sanitizeHtml as sanitize,
-  sanitizeHtml,
-  stripTags,
-} from './sanitize';
-export type { SanitizeOptions } from './sanitize';
+export { generateNonce, hasCSPDirective } from './csp';
+export { escapeHtml, sanitizeHtml as sanitize, sanitizeHtml, stripTags } from './sanitize';
+export { createTrustedHtml, getTrustedTypesPolicy, isTrustedTypesSupported } from './trusted-types';
+export type { SanitizeOptions } from './types';