@hardlydifficult/http 1.0.3 → 1.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/http
 
-HTTP utilities for safe request/response handling: constant-time string comparison, body reading with 1MB limit, and JSON responses with CORS.
+HTTP utilities for safe request/response handling: constant-time string comparison, body reading with size limits, and JSON responses with CORS headers.
 
 ## Installation
 
@@ -11,85 +11,104 @@ npm install @hardlydifficult/http
 ## Quick Start
 
 ```typescript
-import { readBody, sendJson, safeCompare, MAX_BODY_BYTES } from "@hardlydifficult/http";
 import { createServer } from "http";
+import { readBody, sendJson, safeCompare } from "@hardlydifficult/http";
 
 const server = createServer(async (req, res) => {
+  // Read request body safely
   const body = await readBody(req);
-  const isValid = safeCompare(body, "expected-secret");
-  
-  sendJson(res, isValid ? 200 : 403, { authorized: isValid }, "https://example.com");
+  const token = JSON.parse(body).token;
+
+  // Compare tokens securely
+  const isMatch = safeCompare(token, process.env.SECRET_TOKEN ?? "");
+  if (!isMatch) {
+    sendJson(res, 401, { error: "Unauthorized" }, "https://example.com");
+    return;
+  }
+
+  // Send JSON response with CORS headers
+  sendJson(res, 200, { message: "Access granted" }, "https://example.com");
 });
 
 server.listen(3000);
-// → Server starts and safely compares incoming request bodies
 ```
 
-## Body Reading with Size Limit
+## Request Handling
+
+### `readBody`
 
-Reads the full HTTP request body as a string, enforcing a configurable maximum size (default 1 MB). Throws an error if the payload exceeds the limit.
+Reads the full request body as a string, rejecting if it exceeds `maxBytes`.
 
 ```typescript
-import { readBody, MAX_BODY_BYTES } from "@hardlydifficult/http";
+import { readBody } from "@hardlydifficult/http";
 
-// Default limit: 1 MB
-const body = await readBody(request);
+// Default limit is 1 MB
+const body = await readBody(req);
 
-// Custom limit: 500 KB
-const body = await readBody(request, 1024 * 500);
+// Custom limit (e.g., 500 KB)
+const body = await readBody(req, 500 * 1024);
 ```
 
-### Error Handling
+| Parameter | Type | Description |
+|---------|------|-------------|
+| `req` | `IncomingMessage` | Node.js HTTP request |
+| `maxBytes?` | `number` | Maximum body size in bytes (default: `1048576`) |
 
-If the body exceeds the specified limit, the promise rejects with an `"Payload too large"` error.
+Throws `"Payload too large"` error when body exceeds limit.
 
-## JSON Response with CORS
+### `MAX_BODY_BYTES`
 
-Sends a JSON response with CORS headers enabled.
+Default maximum body size: `1024 * 1024` (1 MB).
 
-| Parameter | Type | Description |
-|---------|------|-------------|
-| `res` | `ServerResponse` | Node.js HTTP response object |
-| `status` | `number` | HTTP status code |
-| `body` | `unknown` | Any serializable data |
-| `corsOrigin` | `string` | Allowed origin for CORS (e.g., `"*"` or `"https://example.com"`) |
+```typescript
+import { MAX_BODY_BYTES } from "@hardlydifficult/http";
+
+console.log(MAX_BODY_BYTES); // 1048576
+```
+
+## Response Handling
+
+### `sendJson`
+
+Sends a JSON response with CORS headers.
 
 ```typescript
 import { sendJson } from "@hardlydifficult/http";
 
-sendJson(
-  res,
-  201,
-  { id: 123, message: "Created" },
-  "https://frontend.example.com"
-);
-// → Sets headers: Content-Type, Access-Control-Allow-Origin, etc.
+sendJson(res, 200, { data: "example" }, "https://example.com");
 ```
 
-## Constant-Time String Comparison
+| Parameter | Type | Description |
+|---------|------|-------------|
+| `res` | `ServerResponse` | Node.js HTTP response |
+| `status` | `number` | HTTP status code |
+| `body` | `unknown` | Serializable data to send |
+| `corsOrigin` | `string` | `Access-Control-Allow-Origin` value |
 
-Performs secure string comparison using `crypto.timingSafeEqual` to prevent timing attacks.
+Sets headers:
+- `Content-Type: application/json`
+- `Access-Control-Allow-Origin: corsOrigin`
+- `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`
+- `Access-Control-Allow-Headers: Content-Type, Authorization`
+
+## Security
+
+### `safeCompare`
+
+Constant-time string comparison to prevent timing attacks.
 
 ```typescript
 import { safeCompare } from "@hardlydifficult/http";
 
-const isMatch = safeCompare(userProvidedToken, storedToken);
-// → true if strings are identical, false otherwise
+const isValid = safeCompare(userInput, secretToken);
 ```
 
-### Behavior Details
+Returns `true` for identical strings (including empty strings) and `false` otherwise, regardless of string length or content differences.
 
-- Returns `true` only for identical strings (including empty strings).
-- Returns `false` for different-length strings, with constant-time behavior.
-- Handles Unicode correctly by comparing UTF-8 encoded buffers.
+Handles:
+- Equal/unequal strings
+- Different-length strings
+- Unicode characters
+- Empty strings
 
-### Example Edge Cases
-
-```typescript
-safeCompare("", "");               // true
-safeCompare("abc", "abc");         // true
-safeCompare("abc", "abd");         // false
-safeCompare("short", "longer");    // false
-safeCompare("héllo", "héllo");     // true
-safeCompare("héllo", "hello");     // false
-```
+All comparisons run in time proportional to the first string's length.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/http",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [