@mantiq/core 0.5.22 → 0.6.0

package/src/url/UrlSigner.ts

@@ -0,0 +1,131 @@
+import type { AesEncrypter } from '../encryption/Encrypter.ts'
+
+/**
+ * URL signing utility.
+ *
+ * Generates signed URLs with HMAC-based signatures so you can create links
+ * that prove they haven't been tampered with (e.g. email verification links,
+ * temporary download URLs).
+ *
+ * Uses the application's AesEncrypter key to derive HMAC-SHA256 signatures.
+ *
+ * @example
+ * ```ts
+ * const signer = new UrlSigner(encrypter)
+ * const signed = await signer.sign('https://example.com/verify?user=42')
+ * const isValid = await signer.validate(signed) // true
+ *
+ * const temp = await signer.temporarySignedUrl('https://example.com/download/file.zip', 60)
+ * ```
+ */
+export class UrlSigner {
+  private signingKey: CryptoKey | null = null
+
+  constructor(private readonly encrypter: AesEncrypter) {}
+
+  /**
+   * Sign a URL by appending a signature (and optional expiration) as query parameters.
+   */
+  async sign(url: string, expiresAt?: Date): Promise<string> {
+    const parsed = new URL(url)
+
+    // Remove any existing signature params to prevent double-signing
+    parsed.searchParams.delete('signature')
+    parsed.searchParams.delete('expires')
+
+    if (expiresAt) {
+      parsed.searchParams.set('expires', String(Math.floor(expiresAt.getTime() / 1000)))
+    }
+
+    const signature = await this.createSignature(parsed.toString())
+    parsed.searchParams.set('signature', signature)
+
+    return parsed.toString()
+  }
+
+  /**
+   * Validate a signed URL — verify the signature and check expiration.
+   */
+  async validate(url: string): Promise<boolean> {
+    const parsed = new URL(url)
+
+    const signature = parsed.searchParams.get('signature')
+    if (!signature) return false
+
+    // Check expiration before verifying signature
+    const expires = parsed.searchParams.get('expires')
+    if (expires) {
+      const expiresAt = Number(expires) * 1000
+      if (Date.now() > expiresAt) return false
+    }
+
+    // Reconstruct the URL without the signature to verify
+    parsed.searchParams.delete('signature')
+    const expectedSignature = await this.createSignature(parsed.toString())
+
+    return timingSafeEqual(signature, expectedSignature)
+  }
+
+  /**
+   * Create a temporary signed URL that expires after the given number of minutes.
+   */
+  async temporarySignedUrl(url: string, minutes: number): Promise<string> {
+    return this.sign(url, new Date(Date.now() + minutes * 60_000))
+  }
+
+  // ── Internal ────────────────────────────────────────────────────────────
+
+  /**
+   * Derive the HMAC signing key from the encrypter's raw AES key.
+   */
+  private async getSigningKey(): Promise<CryptoKey> {
+    if (this.signingKey) return this.signingKey
+
+    this.signingKey = await crypto.subtle.importKey(
+      'raw',
+      this.encrypter.getKey() as ArrayBuffer,
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign', 'verify'],
+    )
+
+    return this.signingKey
+  }
+
+  /**
+   * Create an HMAC-SHA256 signature for the given data string.
+   */
+  private async createSignature(data: string): Promise<string> {
+    const key = await this.getSigningKey()
+    const encoded = new TextEncoder().encode(data)
+    const signature = await crypto.subtle.sign('HMAC', key, encoded)
+    return encodeHex(new Uint8Array(signature))
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function encodeHex(bytes: Uint8Array): string {
+  let hex = ''
+  for (let i = 0; i < bytes.length; i++) {
+    hex += bytes[i]!.toString(16).padStart(2, '0')
+  }
+  return hex
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks on signature verification.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false
+
+  const encoder = new TextEncoder()
+  const bufA = encoder.encode(a)
+  const bufB = encoder.encode(b)
+
+  let result = 0
+  for (let i = 0; i < bufA.length; i++) {
+    result |= bufA[i]! ^ bufB[i]!
+  }
+  return result === 0
+}

package/src/websocket/WebSocketKernel.ts

@@ -8,11 +8,30 @@ import { parseCookies } from '../http/Cookie.ts'
  *
  * Core only provides the infrastructure — @mantiq/realtime registers
  * its handler via registerHandler(). Without it, all upgrades return 426.
+ *
+ * IMPORTANT: WebSocket upgrade requests bypass the HTTP middleware pipeline
+ * entirely. This means middleware like VerifyCsrfToken, StartSession, and
+ * CorsMiddleware do NOT run on WebSocket connections. Authentication must
+ * be handled in the onUpgrade hook (via the registered WebSocketHandler's
+ * `onUpgrade` method). Cookie decryption is handled manually below.
+ *
+ * If you need additional request validation on upgrade, register an
+ * `onUpgrade` callback in your WebSocketHandler implementation that
+ * performs the necessary checks (e.g., origin verification, rate limiting).
  */
 export class WebSocketKernel {
   private handler: WebSocketHandler | null = null
   private encrypter: AesEncrypter | null = null
 
+  /**
+   * Optional hooks that run during the upgrade request before the handler's
+   * onUpgrade. Use this to add origin checks, rate limiting, or other
+   * validation that would normally be done by HTTP middleware.
+   *
+   * Return a Response to reject the upgrade, or void/undefined to continue.
+   */
+  private upgradeHooks: Array<(request: MantiqRequest) => Promise<Response | void>> = []
+
   /**
    * Called by @mantiq/realtime to register its WebSocket handler.
    */
@@ -20,6 +39,18 @@ export class WebSocketKernel {
     this.handler = handler
   }
 
+  /**
+   * Register a hook that runs on every WebSocket upgrade request.
+   * Since WebSocket upgrades bypass the HTTP middleware pipeline,
+   * use this to add checks that middleware would normally handle
+   * (e.g., origin validation, rate limiting, auth).
+   *
+   * Return a Response to reject the upgrade, or void to continue.
+   */
+  onUpgrade(hook: (request: MantiqRequest) => Promise<Response | void>): void {
+    this.upgradeHooks.push(hook)
+  }
+
   /**
    * Inject the encrypter so WebSocket upgrades can decrypt cookies.
    * Called during CoreServiceProvider boot.
@@ -30,6 +61,9 @@ export class WebSocketKernel {
 
   /**
    * Called by HttpKernel when an upgrade request is detected.
+   *
+   * NOTE: The HTTP middleware pipeline does NOT run for WebSocket upgrades.
+   * Authentication is delegated to the handler's onUpgrade method.
    */
   async handleUpgrade(request: Request, server: any): Promise<Response> {
     if (!this.handler) {
@@ -47,6 +81,15 @@ export class WebSocketKernel {
       await this.decryptCookies(mantiqRequest)
     }
 
+    // Run onUpgrade hooks — these substitute for HTTP middleware that
+    // would normally run (auth, origin checks, rate limiting, etc.).
+    for (const hook of this.upgradeHooks) {
+      const rejection = await hook(mantiqRequest)
+      if (rejection instanceof Response) {
+        return rejection
+      }
+    }
+
     const context = await this.handler.onUpgrade(mantiqRequest)
 
     if (!context) {
@@ -65,15 +108,26 @@ export class WebSocketKernel {
   /**
    * Returns the Bun WebSocket handlers object for Bun.serve().
    * If no handler is registered, provides no-op stubs.
+   *
+   * Includes maxPayloadLength from the handler if available, which tells
+   * Bun to enforce a transport-level message size limit.
    */
   getBunHandlers(): object {
     const h = this.handler
-    return {
+    const handlers: Record<string, any> = {
       open: (ws: any) => h?.open(ws),
       message: (ws: any, msg: any) => h?.message(ws, msg),
       close: (ws: any, code: number, reason: string) => h?.close(ws, code, reason),
       drain: (ws: any) => h?.drain(ws),
     }
+
+    // Pass maxPayloadLength to Bun's WebSocket config if the handler provides it.
+    // This enforces a transport-level limit on incoming message sizes.
+    if (h && typeof (h as any).getMaxPayloadLength === 'function') {
+      handlers.maxPayloadLength = (h as any).getMaxPayloadLength()
+    }
+
+    return handlers
   }
 
   // ── Private ───────────────────────────────────────────────────────────────
@@ -94,7 +148,9 @@ export class WebSocketKernel {
       try {
         decrypted[name] = await this.encrypter!.decrypt(value)
       } catch {
-        decrypted[name] = value
+        // Can't decrypt — expired key, tampered, or wrong format.
+        // Don't pass through the encrypted blob; discard it.
+        decrypted[name] = ''
       }
     }