#mb-secure-stream

#October 2026 development

#Acknowledgements

#License

#Modules Adapted from moonbit-crypto/mb-crypto

Note: The upstream repository moonbit-crypto/mb-crypto is itself licensed under Apache-2.0. Modifications in this repository are limited to adding convenience wrappers and integration shims; no cryptographic algorithms were changed.

#Project Vision

• Zero-trust security: Every request is authenticated and authorized at the edge
• High performance: Sub-millisecond latency with index-based token splitting (no intermediate string allocations)
• Edge-native: Designed for Cloudflare Workers, Fastly Compute, and WASM runtimes
• Composable: Modular design allows picking only what you need

#Why MoonBit?

#1. WASM-First Design

• Build command: moon build --target wasm or moon build --target wasm-gc
• Test command: moon test --target wasm-gc
• Compiles to WebAssembly for edge deployment
• Cold start time <10ms (estimated)
• Runs on Cloudflare Workers, Fastly Compute, Deno Deploy
• Status: ✅ Production-ready (150/150 tests passing on WASM)

#2. Zero GC Pressure

• No garbage collector means predictable latency
• Index-based token parsing reduces memory allocations
• Suitable for high-throughput stream processing

#3. Type Safety

• Compile-time error detection prevents entire classes of bugs
• Pattern matching ensures exhaustive error handling
• No null pointer exceptions

#4. Block-Style Organization

• Each type/function is self-contained
• Easy to refactor and maintain
• Clear separation of concerns

#5. Built-in Testing

• White-box and black-box testing support
• 150/150 tests passing
• Snapshot testing for complex outputs

#Performance

#Historical JWT benchmark samples

Note: All performance metrics are measured using moon bench --target wasm-gc on the local development machine. Actual performance may vary depending on the target deployment environment (Cloudflare Workers, Fastly Compute, etc.). See crypto/mb-jwt/src/jwt_bench.mbt and gateway/src/gateway_bench.mbt for the full benchmark suite.

#Security Features

#Cryptographic Security

• Signature comparison: Equal-length authentication values use an accumulator comparison; compiled constant-time behavior and timing-attack resistance are not established.
• Algorithm enforcement: Rejects alg:none to prevent signature bypass (CVE-2016-5431)
• Algorithm confusion prevention: Strict algorithm matching prevents HS256/ES256 confusion attacks
• Index-based token splitting: Efficient token parsing via direct string indexing (avoids to_array() allocations)

#Gateway Security

• JWT verification: HS256 (HMAC-SHA256) and ES256 (ECDSA P-256)
• Claims validation: exp, nbf, iss, aud checking with current time binding
• Replay protection: Nonce-based sliding window (configurable)
• Rate limiting: Token bucket algorithm for request rate control
• Bandwidth shaping: Byte-level token bucket for bandwidth management
• Circuit breaker: Failure isolation with automatic recovery
• Connection pooling: Upstream connection limits

#Design Principles

• Stateless: No external dependencies, suitable for edge deployment
• Input validation: Comprehensive bounds checking and type validation
• Fail-safe: Always verify before using decrypted data
• Security review: Implementation-level checks do not replace platform-specific side-channel analysis or an independent audit.

#Use Cases

#1. API Security Gateway

let ctx = new_stream_context(jwt_token)
execute_security_filter(ctx, jwt_key, current_time)
if ctx.is_allowed {
  // Forward to upstream with user context
  // ctx.user_sub is populated from the JWT "sub" claim
  // ctx.user_role is populated from the JWT "role" claim (or "guest" if absent)
  forward_request(ctx.user_sub, ctx.user_role)
}

#2. WebSocket/Streaming Proxy

let fq = new_fair_queue()
let rl = new_rate_limiter(1000L, 100L)

// Authenticate once, then rate-limit each message
if ctx.is_allowed && rl.try_consume(current_time) {
  fq.enqueue(ctx.user_sub, Priority::Normal, byte_size, timestamp)
}

#3. Edge Computing / Zero-Trust Network

// Stateless, no external dependencies
let cb = new_circuit_breaker(5L, 30_000L)
let rp = new_replay_protector(300L)

if cb.allow_request(current_time) && rp.check_nonce(nonce, current_time) {
  // Process request
}

#Modules

#API Reference

#JWT API

#Core Functions

#Key Types

enum JwtKey {
  HS256(String)           // HMAC-SHA256 secret key
  ES256(Array[UInt])      // ECDSA P-256 private key (32 bytes)
}

#Data Structures

struct JWTPayload {
  iss: Option[String]  // Issuer
  sub: Option[String]  // Subject (user ID)
  aud: Option[String]  // Audience
  exp: Option[Int64]   // Expiration time (Unix timestamp)
  nbf: Option[Int64]   // Not before (Unix timestamp)
  iat: Option[Int64]   // Issued at (Unix timestamp)
  jti: Option[String]  // JWT ID
}

#Usage Example

// Sign
let key = JwtKey::HS256("my-secret")
let payload = "{\"sub\":\"user123\",\"exp\":2000000000,\"role\":\"admin\"}"
let token = sign(payload, key)?  // Returns: "header.payload.signature"

// Verify
match verify(token, key) {
  Ok(payload_json) => {
    // Success: payload_json is the decoded JSON string
    println("Valid token: \{payload_json}")
  }
  Err(InvalidSignature) => println("Invalid signature")
  Err(TokenExpired(_, _)) => println("Token expired")
  Err(e) => println("Error: \{e}")
}

#Gateway API

#Core Functions

#Data Structures

struct StreamContext {
  token: String           // Input: JWT token
  mut is_allowed: Bool    // Output: true if valid
  mut error_message: String // Output: error reason if invalid
  mut user_sub: String    // Output: JWT "sub" claim (user ID)
  mut user_role: String   // Output: JWT "role" claim ("admin", "guest", etc.)
}

#Usage Example

// Create context with JWT token
let ctx = new_stream_context("eyJhbGciOiJIUzI1NiJ9...")

// Execute security filter
let jwt_key = JwtKey::HS256("my-secret")
let current_time = 1700000000
execute_security_filter(ctx, jwt_key, current_time)

// Check result
if ctx.is_allowed {
  // Success: access granted
  println("Access allowed, sub: \{ctx.user_sub}, role: \{ctx.user_role}")
  // Forward request with user context
  forward_request(ctx.user_sub, ctx.user_role)
} else {
  // Failure: access denied
  println("Access denied: \{ctx.error_message}")
  // Return 401/403 error
}

#Error Messages

#Quick Start

# Install MoonBit
curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash

# Workspace check and full test suite
moon check -d
moon fmt --check crypto/mb-aead crypto/mb-chacha \
  crypto/mb-getrandom crypto/mb-hash crypto/mb-hkdf \
  crypto/mb-hmac crypto/mb-jwt crypto/mb-p256 \
  crypto/mb-poly1305 gateway
moon info
moon test

# Module-level smoke tests
cd crypto/mb-jwt && moon test
cd ../../gateway && moon test

#Examples

#Cloudflare Worker Example

1. JWT Authentication: Verifies Authorization: Bearer <token> using HMAC-SHA256
2. CORS Handling: Manages cross-origin requests with configurable allowed origins
3. Request Forwarding: Proxies authenticated requests to upstream server (ORIGIN_URL)
4. User Context Injection: Adds X-User-ID and X-User-Role headers to upstream requests
5. Security Headers: Adds HSTS and CORS headers to responses

#Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client Request                       │
│                    (JWT Token in Header)                    │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Security Filter                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   verify()  │→ │ parse_claims│→ │  validate_claims()  │  │
│  │ (HMAC/ECDSA)│  │  (JSON)     │  │  (exp/nbf/iss/aud)  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Stream Context                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────────────┐   │
│  │is_allowed│  │user_role │  │      user_sub            │   │
│  └──────────┘  └──────────┘  └──────────────────────────┘   │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Flow Control                             │
│  ┌────────────┐  ┌────────────┐  ┌──────────────────────┐   │
│  │RateLimiter │  │FairQueue   │  │  BandwidthShaper     │   │
│  └────────────┘  └────────────┘  └──────────────────────┘   │
│  ┌────────────┐  ┌────────────┐  ┌──────────────────────┐   │
│  │CircuitBrkr │  │Backoff     │  │  ConnectionPool      │   │
│  └────────────┘  └────────────┘  └──────────────────────┘   │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Upstream Service                         │
│                  (with user context)                        │
└─────────────────────────────────────────────────────────────┘

#Test Coverage

# Run all tests
moon test

# Coverage: 150/150 tests passing
# - JWT sign/verify (HS256, ES256)
# - Security attacks (alg:none, algorithm confusion, signature tampering)
# - Claims validation (exp, nbf, iss, aud)
# - Flow control (rate limiting, fair queue, circuit breaker)
# - Bandwidth shaping and connection pooling
# - Metrics and observability

#Official Test Sources

#Cryptographic Standards

• RFC 8439 — ChaCha20 and Poly1305 for IETF Protocols
  • ChaCha20 block cipher test vectors (Section 2.3.2)
  • ChaCha20-Poly1305 AEAD test vectors (Section 2.8.2)
  • Poly1305 one-time authenticator test vectors (Section 2.5.2)

• RFC 7539 — ChaCha20 and Poly1305 for TLS (superseded by RFC 8439)

• RFC 4231 — Identifiers and Test Vectors for HMAC-SHA-224/256/384/512
  • HMAC-SHA256 test cases 1-3
  • HMAC-SHA512 test cases 1-2

• RFC 5869 — HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
  • HKDF-SHA256 test cases from Appendix A (Test Case 1, Test Case 3)

• RFC 7518 — JSON Web Algorithms (JWA)
  • ES256 (ECDSA P-256 with SHA-256) compliance

• RFC 7519 — JSON Web Token (JWT)
  • Claims validation: exp, nbf, iss, aud (Sections 4.1.4, 4.1.5, 4.1.1, 4.1.3)
  • Security considerations (Section 7.2)

• RFC 4648 §5 — Base64url encoding (no padding, URL-safe alphabet)

• RFC 2104 — HMAC: Keyed-Hashing for Message Authentication

#JWT Test Vectors

• jwt.io — Standard JWT test vector (HS256 with "your-256-bit-secret")
  • Header: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
  • Payload: {"sub":"1234567890","name":"John Doe","iat":1516239022}

#Security Vulnerability Test Suites

• OWASP WSTG-CRYP-04 — JWT Vulnerability Matrix
  • alg:none attack (CVE-2016-5431)
  • Algorithm confusion / key confusion attacks
  • Signature stripping attacks
  • Payload tampering
  • Header injection (kid manipulation)
  • Weak secret brute-force resistance
  • Cross-token signature replay

• jwt_tool — Known CVE and attack test cases
  • Truncated tokens (missing segments)
  • Empty signature rejection
  • Dots-only / malformed structure
  • ES256 degenerate signatures (all-zero r/s)
  • ES256 truncated signatures
  • Base64url parser differential attacks

#P-256 (ECDSA) Tests

• SEC 1 — Elliptic Curve Cryptography
  • Key generation (generator point verification)
  • Sign/verify roundtrip
  • ECDH key exchange
  • Tampered message rejection

#License