@tamayrp14/fire-api 0.0.0-stage → 1.0.1

package/src/shield/headers.ts

@@ -0,0 +1,55 @@
+export interface SecurityHeaderOptions {
+  contentSecurityPolicy?: boolean | string;
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | string;
+  nosniff?: boolean;
+  hsts?: boolean | { maxAge: number; includeSubDomains?: boolean };
+}
+
+export function applySecurityHeaders(
+  response: Response,
+  options?: SecurityHeaderOptions | boolean
+): Response {
+  if (options === false) return response;
+
+  const headers = new Headers(response.headers);
+
+  // X-Content-Type-Options: nosniff
+  if (!headers.has('X-Content-Type-Options')) {
+    headers.set('X-Content-Type-Options', 'nosniff');
+  }
+
+  // X-Frame-Options: SAMEORIGIN
+  if (!headers.has('X-Frame-Options')) {
+    const frameOpt = typeof options === 'object' && options.frameOptions ? options.frameOptions : 'SAMEORIGIN';
+    headers.set('X-Frame-Options', frameOpt);
+  }
+
+  // X-XSS-Protection: 0 (Modern standard according to MDN and OWASP)
+  if (!headers.has('X-XSS-Protection')) {
+    headers.set('X-XSS-Protection', '0');
+  }
+
+  // HSTS (Strict-Transport-Security)
+  if (!headers.has('Strict-Transport-Security')) {
+    headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+  }
+
+  // Referrer-Policy
+  if (!headers.has('Referrer-Policy')) {
+    headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
+  }
+
+  // Content-Security-Policy default
+  if (!headers.has('Content-Security-Policy')) {
+    const csp = typeof options === 'object' && typeof options.contentSecurityPolicy === 'string'
+      ? options.contentSecurityPolicy
+      : "default-src 'self'";
+    headers.set('Content-Security-Policy', csp);
+  }
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/src/shield/idempotency.ts

@@ -0,0 +1,76 @@
+export interface CachedIdempotentResponse {
+  status: number;
+  statusText?: string;
+  headers: Record<string, string>;
+  body: string;
+  expiresAt: number;
+}
+
+export class IdempotencyManager {
+  private inFlightKeys = new Set<string>();
+  private cache = new Map<string, CachedIdempotentResponse>();
+
+  public isProcessing(key: string): boolean {
+    return this.inFlightKeys.has(key);
+  }
+
+  public markProcessing(key: string): void {
+    this.inFlightKeys.add(key);
+  }
+
+  public release(key: string): void {
+    this.inFlightKeys.delete(key);
+  }
+
+  public get(key: string): CachedIdempotentResponse | null {
+    const item = this.cache.get(key);
+    if (!item) return null;
+
+    if (Date.now() > item.expiresAt) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return item;
+  }
+
+  public async storeResponse(key: string, response: Response, ttlSeconds = 86400): Promise<void> {
+    try {
+      const cloned = response.clone();
+      const bodyText = await cloned.text();
+      const headersRecord: Record<string, string> = {};
+
+      response.headers.forEach((val, k) => {
+        headersRecord[k] = val;
+      });
+
+      this.cache.set(key, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: headersRecord,
+        body: bodyText,
+        expiresAt: Date.now() + ttlSeconds * 1000,
+      });
+    } catch {
+      // Ignore if response body cannot be read
+    } finally {
+      this.release(key);
+    }
+  }
+
+  public createResponse(cached: CachedIdempotentResponse): Response {
+    const headers = new Headers(cached.headers);
+    headers.set('X-Idempotent-Replay', 'true');
+
+    return new Response(cached.body, {
+      status: cached.status,
+      statusText: cached.statusText,
+      headers,
+    });
+  }
+
+  public clear(): void {
+    this.inFlightKeys.clear();
+    this.cache.clear();
+  }
+}

package/src/shield/rate-limiter.ts

@@ -0,0 +1,81 @@
+export interface RateLimiterOptions {
+  max: number;
+  windowMs?: number;
+  window?: string; // '1m', '15m', '1h', etc.
+}
+
+export function parseDuration(durationStr: string): number {
+  const match = durationStr.match(/^(\d+)(s|m|h|d)?$/);
+  if (!match) return 60000; // default 1m
+  const val = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case 's': return val * 1000;
+    case 'm': return val * 60 * 1000;
+    case 'h': return val * 3600 * 1000;
+    case 'd': return val * 86400 * 1000;
+    default: return val * 1000;
+  }
+}
+
+export class RateLimiter {
+  private hits: Map<string, number[]> = new Map();
+  private max: number;
+  private windowMs: number;
+  private cleanupTimer?: any;
+
+  constructor(options: RateLimiterOptions) {
+    this.max = options.max;
+    this.windowMs = options.windowMs || (options.window ? parseDuration(options.window) : 60000);
+
+    // Periodically prune stale keys to guarantee zero memory leaks
+    if (typeof setInterval !== 'undefined') {
+      this.cleanupTimer = setInterval(() => this.cleanup(), this.windowMs * 2);
+      if (this.cleanupTimer.unref) {
+        this.cleanupTimer.unref();
+      }
+    }
+  }
+
+  public check(key: string): { allowed: boolean; remaining: number; retryAfter?: number } {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+
+    let timestamps = this.hits.get(key) || [];
+    // Filter timestamps within current sliding window
+    timestamps = timestamps.filter((t) => t > windowStart);
+
+    if (timestamps.length >= this.max) {
+      const oldestHit = timestamps[0];
+      const retryAfter = Math.ceil((oldestHit + this.windowMs - now) / 1000);
+      return { allowed: false, remaining: 0, retryAfter: Math.max(retryAfter, 1) };
+    }
+
+    timestamps.push(now);
+    this.hits.set(key, timestamps);
+
+    return {
+      allowed: true,
+      remaining: this.max - timestamps.length,
+    };
+  }
+
+  public cleanup(): void {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    for (const [key, timestamps] of this.hits.entries()) {
+      const valid = timestamps.filter((t) => t > windowStart);
+      if (valid.length === 0) {
+        this.hits.delete(key);
+      } else {
+        this.hits.set(key, valid);
+      }
+    }
+  }
+
+  public destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+  }
+}

package/src/shield/sanitizer.ts

@@ -0,0 +1,23 @@
+export function sanitizePayload<T = any>(data: T): T {
+  if (data === null || typeof data !== 'object') {
+    return data;
+  }
+
+  if (Array.isArray(data)) {
+    return data.map((item) => sanitizePayload(item)) as any;
+  }
+
+  // Create clean dictionary with null prototype to prevent prototype poisoning
+  const clean: Record<string, any> = {};
+
+  for (const key of Object.keys(data)) {
+    // Strip dangerous prototype keys
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue;
+    }
+    const val = (data as any)[key];
+    clean[key] = typeof val === 'object' && val !== null ? sanitizePayload(val) : val;
+  }
+
+  return clean as T;
+}

package/src/shield/webhook.ts

@@ -0,0 +1,101 @@
+export async function computeHMAC(
+  payload: string | Uint8Array,
+  secret: string,
+  algorithm: 'SHA-256' | 'SHA-1' | 'SHA-512' = 'SHA-256'
+): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(secret),
+    { name: 'HMAC', hash: algorithm },
+    false,
+    ['sign']
+  );
+
+  const data = typeof payload === 'string' ? enc.encode(payload) : payload;
+  const signatureBuf = await crypto.subtle.sign('HMAC', key, data as any);
+
+  return Array.from(new Uint8Array(signatureBuf))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+export function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+
+export interface VerifyHMACOptions {
+  payload: string | Uint8Array;
+  signature: string;
+  secret: string;
+  algorithm?: 'SHA-256' | 'SHA-1' | 'SHA-512';
+}
+
+export async function verifyHMAC(options: VerifyHMACOptions): Promise<boolean> {
+  const algorithm = options.algorithm || 'SHA-256';
+  let sig = options.signature.trim();
+
+  // Strip prefixes like sha256=, sha1=, sha512=
+  if (sig.startsWith('sha256=')) {
+    sig = sig.slice(7);
+  } else if (sig.startsWith('sha1=')) {
+    sig = sig.slice(5);
+  } else if (sig.startsWith('sha512=')) {
+    sig = sig.slice(7);
+  } else if (sig.includes('v1=')) {
+    // Stripe format: t=...,v1=...
+    const match = sig.match(/v1=([a-f0-9]+)/i);
+    if (match) {
+      sig = match[1];
+    }
+  }
+
+  const expected = await computeHMAC(options.payload, options.secret, algorithm);
+  return constantTimeEqual(sig.toLowerCase(), expected.toLowerCase());
+}
+
+export class WebhookVerifier {
+  constructor(private req: Request, private rawBody: string) {}
+
+  public async verifyHMAC(options: {
+    secret: string;
+    header?: string;
+    signature?: string;
+    algorithm?: 'SHA-256' | 'SHA-1' | 'SHA-512';
+  }): Promise<boolean> {
+    const algorithm = options.algorithm || 'SHA-256';
+    let signature = options.signature;
+
+    if (!signature) {
+      if (options.header) {
+        signature = this.req.headers.get(options.header) || undefined;
+      } else {
+        // Auto-detect standard webhook headers (case-insensitive in standard Request headers)
+        signature =
+          this.req.headers.get('x-hub-signature-256') ||
+          this.req.headers.get('x-signature-256') ||
+          this.req.headers.get('stripe-signature') ||
+          this.req.headers.get('x-signature') ||
+          undefined;
+      }
+    }
+
+    if (!signature) {
+      return false;
+    }
+
+    return verifyHMAC({
+      payload: this.rawBody,
+      signature,
+      secret: options.secret,
+      algorithm,
+    });
+  }
+}

package/src/static/serve.ts

@@ -0,0 +1,51 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+export function getMimeType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+export function createStaticFileResponse(filePath: string): Response | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const stat = fs.statSync(filePath);
+    if (stat.isDirectory()) {
+      return null;
+    }
+
+    const content = fs.readFileSync(filePath);
+    const mime = getMimeType(filePath);
+
+    return new Response(content, {
+      status: 200,
+      headers: {
+        'Content-Type': mime,
+        'Content-Length': String(stat.size),
+        'Cache-Control': 'public, max-age=3600',
+      },
+    });
+  } catch {
+    return null;
+  }
+}

package/src/storage/storage.ts

@@ -0,0 +1,176 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface StoragePutOptions {
+  contentType?: string;
+  access?: 'public' | 'private';
+}
+
+export interface StoragePutResult {
+  path: string;
+  url: string;
+  size: number;
+}
+
+export interface FireStorage {
+  put(filePath: string, content: string | Uint8Array | ArrayBuffer, options?: StoragePutOptions): Promise<StoragePutResult>;
+  get(filePath: string): Promise<Uint8Array | null>;
+  getText(filePath: string): Promise<string | null>;
+  delete(filePath: string): Promise<boolean>;
+  exists(filePath: string): Promise<boolean>;
+  url(filePath: string): string;
+}
+
+export interface StorageOptions {
+  driver?: 'memory' | 'local';
+  rootDir?: string;
+  baseUrl?: string;
+}
+
+export class MemoryStorageAdapter implements FireStorage {
+  private files: Map<string, { data: Uint8Array; contentType?: string }> = new Map();
+  private baseUrl: string;
+
+  constructor(options: { baseUrl?: string } = {}) {
+    this.baseUrl = (options.baseUrl || '/uploads').replace(/\/+$/, '');
+  }
+
+  public async put(
+    filePath: string,
+    content: string | Uint8Array | ArrayBuffer,
+    options?: StoragePutOptions
+  ): Promise<StoragePutResult> {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    let bytes: Uint8Array;
+
+    if (typeof content === 'string') {
+      bytes = new TextEncoder().encode(content);
+    } else if (content instanceof ArrayBuffer) {
+      bytes = new Uint8Array(content);
+    } else {
+      bytes = content;
+    }
+
+    this.files.set(cleanPath, { data: bytes, contentType: options?.contentType });
+
+    return {
+      path: cleanPath,
+      url: this.url(cleanPath),
+      size: bytes.byteLength,
+    };
+  }
+
+  public async get(filePath: string): Promise<Uint8Array | null> {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    const file = this.files.get(cleanPath);
+    return file ? file.data : null;
+  }
+
+  public async getText(filePath: string): Promise<string | null> {
+    const bytes = await this.get(filePath);
+    return bytes ? new TextDecoder().decode(bytes) : null;
+  }
+
+  public async delete(filePath: string): Promise<boolean> {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    return this.files.delete(cleanPath);
+  }
+
+  public async exists(filePath: string): Promise<boolean> {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    return this.files.has(cleanPath);
+  }
+
+  public url(filePath: string): string {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    return `${this.baseUrl}/${cleanPath}`;
+  }
+}
+
+export class LocalDiskStorageAdapter implements FireStorage {
+  private rootDir: string;
+  private baseUrl: string;
+
+  constructor(options: { rootDir?: string; baseUrl?: string } = {}) {
+    this.rootDir = options.rootDir || path.join(process.cwd(), 'uploads');
+    this.baseUrl = (options.baseUrl || '/uploads').replace(/\/+$/, '');
+
+    if (!fs.existsSync(this.rootDir)) {
+      fs.mkdirSync(this.rootDir, { recursive: true });
+    }
+  }
+
+  private resolvePath(filePath: string): string {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    return path.join(this.rootDir, cleanPath);
+  }
+
+  public async put(
+    filePath: string,
+    content: string | Uint8Array | ArrayBuffer,
+    _options?: StoragePutOptions
+  ): Promise<StoragePutResult> {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    const fullPath = this.resolvePath(cleanPath);
+    const dir = path.dirname(fullPath);
+
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    let bytes: Uint8Array;
+    if (typeof content === 'string') {
+      bytes = new TextEncoder().encode(content);
+    } else if (content instanceof ArrayBuffer) {
+      bytes = new Uint8Array(content);
+    } else {
+      bytes = content;
+    }
+
+    fs.writeFileSync(fullPath, bytes);
+
+    return {
+      path: cleanPath,
+      url: this.url(cleanPath),
+      size: bytes.byteLength,
+    };
+  }
+
+  public async get(filePath: string): Promise<Uint8Array | null> {
+    const fullPath = this.resolvePath(filePath);
+    if (!fs.existsSync(fullPath)) return null;
+    const buffer = fs.readFileSync(fullPath);
+    return new Uint8Array(buffer);
+  }
+
+  public async getText(filePath: string): Promise<string | null> {
+    const fullPath = this.resolvePath(filePath);
+    if (!fs.existsSync(fullPath)) return null;
+    return fs.readFileSync(fullPath, 'utf-8');
+  }
+
+  public async delete(filePath: string): Promise<boolean> {
+    const fullPath = this.resolvePath(filePath);
+    if (!fs.existsSync(fullPath)) return false;
+    fs.unlinkSync(fullPath);
+    return true;
+  }
+
+  public async exists(filePath: string): Promise<boolean> {
+    const fullPath = this.resolvePath(filePath);
+    return fs.existsSync(fullPath);
+  }
+
+  public url(filePath: string): string {
+    const cleanPath = filePath.replace(/^\/+/, '');
+    return `${this.baseUrl}/${cleanPath}`;
+  }
+}
+
+export function createStorage(options: StorageOptions = {}): FireStorage {
+  const driver = options.driver || 'memory';
+  if (driver === 'local') {
+    return new LocalDiskStorageAdapter(options);
+  }
+  return new MemoryStorageAdapter(options);
+}

package/src/stream/sse.ts

@@ -0,0 +1,89 @@
+export interface SSEEventOptions {
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+
+export interface SSEStreamWriter {
+  send(data: any, options?: SSEEventOptions): Promise<void>;
+  close(): void;
+}
+
+export function formatSSEMessage(data: any, options: SSEEventOptions = {}): string {
+  let message = '';
+
+  if (options.id !== undefined) {
+    message += `id: ${options.id}\n`;
+  }
+
+  if (options.event !== undefined) {
+    message += `event: ${options.event}\n`;
+  }
+
+  if (options.retry !== undefined) {
+    message += `retry: ${options.retry}\n`;
+  }
+
+  const serialized = typeof data === 'string' ? data : JSON.stringify(data);
+  const lines = serialized.split('\n');
+  for (const line of lines) {
+    message += `data: ${line}\n`;
+  }
+  message += '\n';
+
+  return message;
+}
+
+export function createSSEResponse(
+  handler: (stream: SSEStreamWriter) => Promise<void> | void
+): Response {
+  const encoder = new TextEncoder();
+  let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let isClosed = false;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controllerRef = controller;
+
+      const writer: SSEStreamWriter = {
+        async send(data: any, options?: SSEEventOptions) {
+          if (isClosed || !controllerRef) return;
+          const formatted = formatSSEMessage(data, options);
+          controllerRef.enqueue(encoder.encode(formatted));
+        },
+        close() {
+          if (isClosed || !controllerRef) return;
+          isClosed = true;
+          try {
+            controllerRef.close();
+          } catch {}
+        },
+      };
+
+      Promise.resolve(handler(writer)).catch((err) => {
+        if (!isClosed && controllerRef) {
+          const errMessage = formatSSEMessage({ error: err?.message || 'Stream error' }, { event: 'error' });
+          controllerRef.enqueue(encoder.encode(errMessage));
+          try {
+            controllerRef.close();
+          } catch {}
+          isClosed = true;
+        }
+      });
+    },
+    cancel() {
+      isClosed = true;
+    },
+  });
+
+  const headers = new Headers();
+  headers.set('Content-Type', 'text/event-stream; charset=utf-8');
+  headers.set('Cache-Control', 'no-cache, no-transform');
+  headers.set('Connection', 'keep-alive');
+  headers.set('X-Accel-Buffering', 'no'); // Disable Nginx buffering
+
+  return new Response(stream, {
+    status: 200,
+    headers,
+  });
+}