@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/csp.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Content Security Policy (CSP) Module
+ *
+ * Provides utilities for generating and managing Content Security Policy headers
+ * and meta tags to protect against XSS and other injection attacks.
+ *
+ * ## Features
+ *
+ * - Generate CSP headers from configuration
+ * - Inject CSP meta tags into HTML
+ * - Nonce generation for inline scripts/styles
+ * - Preset configurations for common use cases
+ * - Template directives for CSP integration
+ *
+ * ## Usage
+ *
+ * ### Configuration in stx.config.ts
+ *
+ * ```typescript
+ * export default {
+ *   csp: {
+ *     enabled: true,
+ *     directives: {
+ *       'default-src': ["'self'"],
+ *       'script-src': ["'self'", "'strict-dynamic'"],
+ *       'style-src': ["'self'", "'unsafe-inline'"],
+ *       'img-src': ["'self'", 'data:', 'https:'],
+ *       'connect-src': ["'self'", 'https://api.example.com'],
+ *     },
+ *     useNonce: true,
+ *     addMetaTag: true,
+ *   }
+ * }
+ * ```
+ *
+ * ### Using Presets
+ *
+ * ```typescript
+ * import { getCspPreset, generateCspHeader } from 'stx'
+ *
+ * const config = getCspPreset('strict')
+ * const header = generateCspHeader(config.directives)
+ * ```
+ *
+ * ### Template Directives
+ *
+ * ```html
+ * <!-- Insert CSP meta tag -->
+ * @csp
+ *
+ * <!-- Get current nonce for inline scripts -->
+ * <script nonce="{{ cspNonce }}">
+ *   console.log('Safe inline script')
+ * </script>
+ * ```
+ *
+ * ### HTTP Headers
+ *
+ * ```typescript
+ * import { generateCspHeader } from 'stx'
+ *
+ * // In your server handler
+ * const cspHeader = generateCspHeader(config.csp.directives)
+ * response.setHeader('Content-Security-Policy', cspHeader)
+ * ```
+ */
+import type { CspConfig, CspDirectives, CspPreset, CustomDirective, StxOptions } from './types';
+/**
+ * Generate a cryptographically secure nonce for CSP
+ *
+ * @param length - Length of nonce in bytes (default 16)
+ * @returns Base64-encoded nonce string
+ *
+ * @example
+ * ```typescript
+ * const nonce = generateNonce()
+ * // Returns something like: "4AiRXmSkM+XRG3E2Y1fO9Q=="
+ * ```
+ */
+export declare function generateNonce(length?: number): string;
+/**
+ * Get or create a nonce for the current request context
+ *
+ * Uses WeakMap to ensure nonce is request-scoped and can be garbage collected.
+ * If no context is provided, generates a new nonce each time.
+ *
+ * @param context - Request context object for nonce scoping
+ * @param config - CSP configuration (may include custom nonce generator)
+ * @returns The nonce for the current context
+ *
+ * @example
+ * ```typescript
+ * // In a request handler
+ * const ctx = { requestId: '123' }
+ * const nonce = getNonce(ctx, cspConfig)
+ * // Same nonce returned for same context object
+ * const sameNonce = getNonce(ctx, cspConfig)
+ * ```
+ */
+export declare function getNonce(context?: object, config?: CspConfig): string;
+/**
+ * Clear the nonce for a context (useful for testing or manual cleanup)
+ *
+ * @param context - Request context to clear nonce for
+ */
+export declare function clearNonce(context: object): void;
+/**
+ * Generate a CSP header string from directive configuration
+ *
+ * @param directives - CSP directive configuration
+ * @param nonce - Optional nonce to inject into script-src and style-src
+ * @returns CSP header string
+ *
+ * @example
+ * ```typescript
+ * const header = generateCspHeader({
+ *   'default-src': ["'self'"],
+ *   'script-src': ["'self'", 'https://cdn.example.com'],
+ *   'upgrade-insecure-requests': true,
+ * })
+ * // Returns: "default-src 'self'; script-src 'self' https://cdn.example.com; upgrade-insecure-requests"
+ * ```
+ */
+export declare function generateCspHeader(directives: CspDirectives, nonce?: string): string;
+/**
+ * Generate CSP meta tag HTML
+ *
+ * @param directives - CSP directive configuration
+ * @param nonce - Optional nonce to inject
+ * @returns HTML meta tag string
+ *
+ * @example
+ * ```typescript
+ * const metaTag = generateCspMetaTag({
+ *   'default-src': ["'self'"],
+ * })
+ * // Returns: '<meta http-equiv="Content-Security-Policy" content="default-src \'self\'">'
+ * ```
+ */
+export declare function generateCspMetaTag(directives: CspDirectives, nonce?: string): string;
+/**
+ * Strict CSP preset - Maximum security, may require nonces for inline content
+ *
+ * - No unsafe-inline or unsafe-eval
+ * - Uses strict-dynamic for scripts
+ * - Blocks object/embed
+ * - Restricts form actions to same origin
+ */
+export declare const strictCspPreset: CspDirectives;
+/**
+ * Moderate CSP preset - Balanced security and compatibility
+ *
+ * - Allows unsafe-inline for styles (common requirement)
+ * - Blocks unsafe-eval
+ * - Allows data: URIs for images
+ */
+export declare const moderateCspPreset: CspDirectives;
+/**
+ * Relaxed CSP preset - Basic protection, maximum compatibility
+ *
+ * - Allows unsafe-inline for both scripts and styles
+ * - Still blocks unsafe-eval and object embeds
+ */
+export declare const relaxedCspPreset: CspDirectives;
+/**
+ * API-only CSP preset - For JSON API responses
+ *
+ * - Blocks all content loading (APIs shouldn't render HTML)
+ * - Prevents framing
+ */
+export declare const apiCspPreset: CspDirectives;
+/**
+ * Get a CSP preset configuration by name
+ *
+ * @param preset - Name of the preset
+ * @returns CSP configuration object
+ *
+ * @example
+ * ```typescript
+ * const config = getCspPreset('strict')
+ * // Returns full CspConfig with strict directives
+ * ```
+ */
+export declare function getCspPreset(preset: CspPreset): CspConfig;
+/**
+ * Merge two CSP directive configurations
+ *
+ * Sources from the second config are added to the first.
+ * Boolean directives are OR'd together.
+ *
+ * @param base - Base CSP directives
+ * @param override - Override/additional directives
+ * @returns Merged CSP directives
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeCspDirectives(
+ *   { 'default-src': ["'self'"], 'script-src': ["'self'"] },
+ *   { 'script-src': ['https://cdn.example.com'], 'img-src': ['https:'] }
+ * )
+ * // Result: {
+ * //   'default-src': ["'self'"],
+ * //   'script-src': ["'self'", "https://cdn.example.com"],
+ * //   'img-src': ["https:"]
+ * // }
+ * ```
+ */
+export declare function mergeCspDirectives(base: CspDirectives, override: CspDirectives): CspDirectives;
+/**
+ * Inject CSP meta tag into HTML head
+ *
+ * @param html - HTML content
+ * @param config - CSP configuration
+ * @param context - Request context for nonce scoping
+ * @returns HTML with CSP meta tag injected
+ */
+export declare function injectCspMetaTag(html: string, config: CspConfig, context?: object): string;
+/**
+ * Add nonce attribute to all inline script and style tags
+ *
+ * @param html - HTML content
+ * @param nonce - Nonce value to add
+ * @returns HTML with nonce attributes added
+ */
+export declare function addNonceToInlineContent(html: string, nonce: string): string;
+/**
+ * Process CSP-related directives in templates
+ *
+ * Handles:
+ * - @csp - Insert CSP meta tag
+ * - @cspNonce - Output current nonce value
+ *
+ * @param template - Template content
+ * @param context - Template context
+ * @param _filePath - Source file path
+ * @param options - STX options
+ * @returns Processed template
+ */
+export declare function processCspDirectives(template: string, context: Record<string, any>, _filePath: string, options: StxOptions): string;
+/**
+ * CSP meta tag directive
+ * Usage: @csp
+ */
+export declare const cspDirective: CustomDirective;
+/**
+ * CSP nonce directive
+ * Usage: @cspNonce
+ */
+export declare const cspNonceDirective: CustomDirective;
+/**
+ * Register CSP-related custom directives
+ *
+ * @returns Array of custom directives for CSP
+ */
+export declare function registerCspDirectives(): CustomDirective[];
+/**
+ * Validate CSP directive configuration
+ *
+ * @param directives - CSP directives to validate
+ * @returns Array of validation warnings
+ *
+ * @example
+ * ```typescript
+ * const warnings = validateCspDirectives({
+ *   'script-src': ["'unsafe-inline'", "'unsafe-eval'"],
+ * })
+ * // Returns warnings about unsafe usage
+ * ```
+ */
+export declare function validateCspDirectives(directives: CspDirectives): string[];
+/**
+ * Get the appropriate CSP header name based on configuration
+ *
+ * @param reportOnly - Whether to use report-only mode
+ * @returns Header name string
+ */
+export declare function getCspHeaderName(reportOnly?: boolean): string;
+/**
+ * Create CSP headers object for HTTP response
+ *
+ * @param config - CSP configuration
+ * @param context - Request context for nonce scoping
+ * @returns Headers object ready to spread into response
+ *
+ * @example
+ * ```typescript
+ * const headers = createCspHeaders(cspConfig, requestContext)
+ * return new Response(body, { headers: { ...headers } })
+ * ```
+ */
+export declare function createCspHeaders(config: CspConfig, context?: object): Record<string, string>;
+/**
+ * Default CSP configuration - moderate preset
+ */
+export declare const defaultCspConfig: CspConfig;

package/dist/csp.js

@@ -0,0 +1,220 @@
+const DEFAULT_NONCE_LENGTH = 16, nonceStorage = new WeakMap;
+export function generateNonce(length = DEFAULT_NONCE_LENGTH) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return btoa(String.fromCharCode(...bytes));
+}
+export function getNonce(context, config) {
+  if (!context)
+    return config?.nonceGenerator?.() ?? generateNonce();
+  let nonce = nonceStorage.get(context);
+  if (!nonce) {
+    nonce = config?.nonceGenerator?.() ?? generateNonce();
+    nonceStorage.set(context, nonce);
+  }
+  return nonce;
+}
+export function clearNonce(context) {
+  nonceStorage.delete(context);
+}
+export function generateCspHeader(directives, nonce) {
+  const parts = [];
+  for (const [directive, value] of Object.entries(directives)) {
+    if (value === void 0 || value === null)
+      continue;
+    if (typeof value === "boolean") {
+      if (value)
+        parts.push(directive);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      let sources = [...value];
+      if (nonce && (directive === "script-src" || directive === "style-src")) {
+        sources = sources.filter((s) => !s.startsWith("'nonce-"));
+        sources.push(`'nonce-${nonce}'`);
+      }
+      if (sources.length > 0)
+        parts.push(`${directive} ${sources.join(" ")}`);
+    }
+  }
+  return parts.join("; ");
+}
+export function generateCspMetaTag(directives, nonce) {
+  return `<meta http-equiv="Content-Security-Policy" content="${generateCspHeader(directives, nonce).replace(/&/g, "&amp;").replace(/"/g, "&quot;")}">`;
+}
+export const strictCspPreset = {
+  "default-src": ["'self'"],
+  "script-src": ["'self'", "'strict-dynamic'"],
+  "style-src": ["'self'"],
+  "img-src": ["'self'", "data:", "https:"],
+  "font-src": ["'self'", "https:", "data:"],
+  "connect-src": ["'self'"],
+  "media-src": ["'self'"],
+  "object-src": ["'none'"],
+  "frame-src": ["'none'"],
+  "base-uri": ["'self'"],
+  "form-action": ["'self'"],
+  "frame-ancestors": ["'self'"],
+  "upgrade-insecure-requests": !0
+}, moderateCspPreset = {
+  "default-src": ["'self'"],
+  "script-src": ["'self'"],
+  "style-src": ["'self'", "'unsafe-inline'"],
+  "img-src": ["'self'", "data:", "https:"],
+  "font-src": ["'self'", "https:", "data:"],
+  "connect-src": ["'self'", "https:"],
+  "media-src": ["'self'"],
+  "object-src": ["'none'"],
+  "frame-src": ["'self'"],
+  "base-uri": ["'self'"],
+  "form-action": ["'self'"],
+  "upgrade-insecure-requests": !0
+}, relaxedCspPreset = {
+  "default-src": ["'self'"],
+  "script-src": ["'self'", "'unsafe-inline'"],
+  "style-src": ["'self'", "'unsafe-inline'"],
+  "img-src": ["'self'", "data:", "https:", "http:"],
+  "font-src": ["'self'", "https:", "http:", "data:"],
+  "connect-src": ["'self'", "https:", "http:", "ws:", "wss:"],
+  "media-src": ["'self'", "https:", "http:"],
+  "object-src": ["'none'"],
+  "frame-src": ["'self'", "https:"],
+  "base-uri": ["'self'"]
+}, apiCspPreset = {
+  "default-src": ["'none'"],
+  "frame-ancestors": ["'none'"]
+};
+export function getCspPreset(preset) {
+  return {
+    enabled: !0,
+    directives: {
+      strict: strictCspPreset,
+      moderate: moderateCspPreset,
+      relaxed: relaxedCspPreset,
+      api: apiCspPreset
+    }[preset] || moderateCspPreset,
+    useNonce: preset === "strict",
+    addMetaTag: !0
+  };
+}
+export function mergeCspDirectives(base, override) {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const directive = key, baseValue = result[directive];
+    if (value === void 0 || value === null)
+      continue;
+    if (typeof value === "boolean")
+      result[directive] = baseValue || value;
+    else if (Array.isArray(value)) {
+      const baseArray = Array.isArray(baseValue) ? baseValue : [], merged = [...new Set([...baseArray, ...value])];
+      result[directive] = merged;
+    }
+  }
+  return result;
+}
+export function injectCspMetaTag(html, config, context) {
+  if (!config.enabled || !config.addMetaTag)
+    return html;
+  if (html.includes('http-equiv="Content-Security-Policy"'))
+    return html;
+  if (!html.includes("<head>") && !html.includes("<head "))
+    return html;
+  const nonce = config.useNonce ? getNonce(context, config) : void 0, metaTag = generateCspMetaTag(config.directives, nonce);
+  return html.replace(/<head([^>]*)>/, `<head$1>
+${metaTag}`);
+}
+export function addNonceToInlineContent(html, nonce) {
+  let result = html;
+  result = result.replace(/<script(?![^>]*\ssrc=)([^>]*)>/gi, (match, attrs) => {
+    if (attrs.includes("nonce="))
+      return match;
+    return `<script nonce="${nonce}"${attrs}>`;
+  });
+  result = result.replace(/<style([^>]*)>/gi, (match, attrs) => {
+    if (attrs.includes("nonce="))
+      return match;
+    return `<style nonce="${nonce}"${attrs}>`;
+  });
+  return result;
+}
+export function processCspDirectives(template, context, _filePath, options) {
+  let output = template;
+  const cspConfig = options.csp;
+  output = output.replace(/@csp\b/g, () => {
+    if (!cspConfig?.enabled || !cspConfig.directives)
+      return "<!-- CSP not configured -->";
+    const nonce = cspConfig.useNonce ? getNonce(context, cspConfig) : void 0;
+    return generateCspMetaTag(cspConfig.directives, nonce);
+  });
+  output = output.replace(/@cspNonce\b/g, () => {
+    if (!cspConfig?.enabled || !cspConfig.useNonce)
+      return "";
+    return getNonce(context, cspConfig);
+  });
+  if (cspConfig?.enabled && cspConfig.useNonce)
+    context.cspNonce = getNonce(context, cspConfig);
+  return output;
+}
+export const cspDirective = {
+  name: "csp",
+  handler: (_content, _params, context, _filePath) => {
+    const cspConfig = context.__stx_options?.csp;
+    if (!cspConfig?.enabled || !cspConfig.directives)
+      return "<!-- CSP not configured -->";
+    const nonce = cspConfig.useNonce ? getNonce(context, cspConfig) : void 0;
+    return generateCspMetaTag(cspConfig.directives, nonce);
+  },
+  hasEndTag: !1,
+  description: "Insert Content-Security-Policy meta tag"
+}, cspNonceDirective = {
+  name: "cspNonce",
+  handler: (_content, _params, context, _filePath) => {
+    const cspConfig = context.__stx_options?.csp;
+    if (!cspConfig?.enabled || !cspConfig.useNonce)
+      return "";
+    return getNonce(context, cspConfig);
+  },
+  hasEndTag: !1,
+  description: "Output the current CSP nonce value"
+};
+export function registerCspDirectives() {
+  return [
+    cspDirective,
+    cspNonceDirective
+  ];
+}
+export function validateCspDirectives(directives) {
+  const warnings = [];
+  if (directives["script-src"]?.includes("'unsafe-inline'"))
+    warnings.push("CSP: Using unsafe-inline in script-src significantly reduces XSS protection");
+  if (directives["script-src"]?.includes("'unsafe-eval'"))
+    warnings.push("CSP: Using unsafe-eval in script-src allows eval() and related functions");
+  if (!directives["default-src"])
+    warnings.push("CSP: No default-src specified. Recommend adding default-src as a fallback");
+  if (directives["default-src"]?.includes("*"))
+    warnings.push("CSP: Using * in default-src provides minimal protection");
+  if (!directives["object-src"] && !directives["default-src"]?.includes("'none'"))
+    warnings.push("CSP: Consider adding object-src: none to block plugins");
+  if (!directives["base-uri"])
+    warnings.push("CSP: Consider adding base-uri to prevent base tag injection attacks");
+  for (const [directive, sources] of Object.entries(directives))
+    if (Array.isArray(sources) && sources.includes("http:"))
+      warnings.push(`CSP: Using http: in ${directive} allows insecure resources`);
+  return warnings;
+}
+export function getCspHeaderName(reportOnly = !1) {
+  return reportOnly ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy";
+}
+export function createCspHeaders(config, context) {
+  if (!config.enabled)
+    return {};
+  const nonce = config.useNonce ? getNonce(context, config) : void 0, headerValue = generateCspHeader(config.directives, nonce);
+  return { [getCspHeaderName(config.reportOnly)]: headerValue };
+}
+export const defaultCspConfig = {
+  enabled: !1,
+  reportOnly: !1,
+  directives: moderateCspPreset,
+  useNonce: !1,
+  addMetaTag: !0
+};

package/dist/csrf.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Generate a CSRF token
+ */
+export declare function generateCsrfToken(length?: number): string;
+/**
+ * Get the current CSRF token, generating one if it doesn't exist
+ */
+export declare function getCsrfToken(): string;
+/**
+ * Reset the CSRF token (mainly for testing)
+ */
+export declare function resetCsrfToken(): void;
+/**
+ * Set a specific CSRF token (useful for server frameworks that have their own token generation)
+ */
+export declare function setCsrfToken(token: string): void;
+/**
+ * Generate a CSRF input field HTML
+ */
+export declare function csrfField(inputName?: string): string;
+/**
+ * Process @csrf directives in templates
+ */
+export declare function processCsrfDirectives(template: string): string;
+/**
+ * Verify a CSRF token.
+ *
+ * When called with one argument, compares against the module-global token.
+ * When called with two arguments, compares submitted vs expected (for per-request usage).
+ *
+ * Per-request usage avoids the global state race condition under concurrent requests:
+ * ```typescript
+ * const expected = req.session.csrfToken
+ * const submitted = req.body._token
+ * if (!verifyCsrfToken(submitted, expected)) { ... }
+ * ```
+ */
+export declare function verifyCsrfToken(token: string, expectedToken?: string): boolean;

package/dist/csrf.js

@@ -0,0 +1,38 @@
+import { Buffer } from "node:buffer";
+import crypto from "node:crypto";
+const DEFAULT_TOKEN_LENGTH = 40, DEFAULT_INPUT_NAME = "_token";
+let csrfToken = null;
+export function generateCsrfToken(length = DEFAULT_TOKEN_LENGTH) {
+  const token = crypto.randomBytes(Math.ceil(length / 2)).toString("hex").slice(0, length);
+  csrfToken = token;
+  return token;
+}
+export function getCsrfToken() {
+  if (!csrfToken)
+    generateCsrfToken();
+  return csrfToken;
+}
+export function resetCsrfToken() {
+  csrfToken = null;
+}
+export function setCsrfToken(token) {
+  csrfToken = token;
+}
+export function csrfField(inputName = DEFAULT_INPUT_NAME) {
+  const token = getCsrfToken();
+  return `<input type="hidden" name="${inputName}" value="${token}">`;
+}
+export function processCsrfDirectives(template) {
+  return template.replace(/@csrf(?:\((['"])([^'"]*)\1\))?/g, (_, quote, inputName) => {
+    return csrfField(inputName || DEFAULT_INPUT_NAME);
+  });
+}
+export function verifyCsrfToken(token, expectedToken) {
+  const expected = expectedToken ?? csrfToken;
+  if (!expected)
+    return !1;
+  const tokenBuf = Buffer.from(token), csrfBuf = Buffer.from(expected);
+  if (tokenBuf.length !== csrfBuf.length)
+    return !1;
+  return crypto.timingSafeEqual(tokenBuf, csrfBuf);
+}

package/dist/custom-directives.d.ts

@@ -0,0 +1,5 @@
+import type { StxOptions } from './types';
+/**
+ * Process all custom directives registered in the app
+ */
+export declare function processCustomDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): Promise<string>;