@stefanobalocco/honosignedrequests 1.0.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025, Stefano Balocco <stefano.balocco@gmail.com>
+All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+* Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+* Neither the name of Stefano Balocco nor the names of its contributors may
+be used to endorse or promote products derived from this software without
+specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,313 @@
+# @stefanobalocco/honosignedrequests
+
+A Hono middleware for HMAC-SHA256 signed requests.
+
+## Overview
+
+This library provides server-side session management and request signature validation for Hono applications, along with a client library for making signed requests.
+
+### Authentication Mechanism
+
+Each session is associated with a cryptographic token (a random byte array) shared between client and server. Every request is authenticated by computing an HMAC-SHA256 signature using this token as the secret key.
+
+The signature is computed over:
+- Session ID
+- Sequence number (monotonically increasing to prevent replay attacks)
+- Timestamp (to limit signature validity window)
+- Request parameters (sorted alphabetically)
+
+The server validates the signature using the same token, verifies the timestamp falls within the allowed window, and checks that the sequence number is the expected next value for that session.
+
+## Features
+- HMAC-SHA256 request signing with shared secret token
+- Replay attack protection via monotonic sequence numbers
+- Timestamp validation with configurable tolerance, to prevent delayed replay
+- Constant-time signature comparison, to prevent timing attacks
+- Pluggable session storage architecture
+- Works with Node.js, Cloudflare Workers, Deno, and Bun
+
+## Installation
+
+```bash
+npm install @stefanobalocco/honosignedrequests
+```
+
+## Server-Side Usage
+
+### Basic Setup
+
+```typescript
+import { Hono } from 'hono';
+import { SignedRequestsManager, SessionsStorageLocal } from '@stefanobalocco/honosignedrequests';
+
+const app = new Hono();
+
+// SessionsStorageLocal is a simple in-memory storage implementation
+// You can implement your own SessionsStorage (e.g., Redis-based) for production
+const storage = new SessionsStorageLocal({
+  maxSessions: 65535,         // Storage-specific: maximum concurrent sessions in memory
+  maxSessionsPerUser: 3       // Storage-specific: maximum sessions per user
+});
+
+// Generic parameters are passed to SignedRequestsManager
+const signedRequests = new SignedRequestsManager(storage, {
+  validitySignature: 5000,      // signature valid for 5 seconds
+  validityToken: 3600000,       // session valid for 1 hour
+  tokenLength: 32               // token size in bytes
+});
+
+app.use('/api/*', signedRequests.middleware);
+```
+
+### Session Creation (Login Endpoint)
+
+```typescript
+app.post('/auth/login', async (c) => {
+  const { username, password } = await c.req.json();
+  
+  // Your authentication logic here
+  const userId = await authenticateUser(username, password);
+  
+  if (!userId) {
+    return c.json({ error: 'Invalid credentials' }, 401);
+  }
+  
+  // Use the manager's createSession method
+  const session = await signedRequests.createSession(userId);
+  
+  // Convert token to Base64URL for transmission to client
+  const tokenBase64 = btoa(String.fromCharCode(...session.token))
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+  
+  return c.json({
+    sessionId: session.id,
+    token: tokenBase64,
+    sequenceNumber: session.sequenceNumber
+  });
+});
+```
+
+### Ping Endpoint (Verify Authentication)
+
+```typescript
+app.post('/api/ping', (c) => {
+  const session = c.get('session');
+  return c.json({ pong: !!session });
+});
+```
+
+### Protected Endpoint
+
+```typescript
+app.post('/api/protected', (c) => {
+  const session = c.get('session');
+  
+  if (!session) {
+    return c.json({ error: 'Unauthorized' }, 401);
+  }
+  
+  return c.json({
+    message: 'Authenticated',
+    userId: session.userId
+  });
+});
+```
+
+### Configuration
+
+The library separates **generic parameters** (common to all storage implementations) from **storage-specific parameters**.
+
+#### Generic Parameters (SignedRequestsManagerConfig)
+
+These are passed to `SignedRequestsManager` constructor and apply to all storage implementations:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `validitySignature` | 5000 | Signature validity window in milliseconds |
+| `validityToken` | 3600000 | Session token validity in milliseconds |
+| `tokenLength` | 32 | Token length in bytes (cryptographic secret) |
+
+#### SessionsStorageLocal Specific Parameters
+
+These are specific to the in-memory implementation:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxSessions` | 65535 | Maximum concurrent sessions in memory |
+| `maxSessionsPerUser` | 3 | Maximum sessions per user (enforced by removing oldest) |
+
+## Client-Side Usage
+
+### Browser Import (CDN)
+
+```html
+<script type="module">
+  import { SignedRequester } from 'https://cdn.jsdelivr.net/gh/StefanoBalocco/HonoSignedRequests/client/dist/SignedRequester.min.js';
+  
+  const requester = new SignedRequester();
+  // You can also specify a base URL for request
+  //const requester = new SignedRequester('https://api.example.com');
+  
+  // Check if we have session data stored
+  let needLogin = true;
+  if (requester.getSession()) {
+    // Try to verify the session is still valid
+    try {
+      const response = await requester.signedRequestJson('/api/ping', {});
+      
+      if (response?.pong) {
+        needLogin = false;
+      }
+    } catch (error) {
+    }
+  }
+  
+  if( needLogin ) {
+    // No session data, need to login
+		const response = await fetch('/auth/login', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				username: 'user@example.com',
+				password: 'password123'
+			})
+		});
+
+		const loginData = await response.json();
+
+		// Store session credentials
+		requester.setSession({
+			sessionId: loginData.sessionId,
+			token: loginData.token,
+			sequenceNumber: loginData.sequenceNumber
+		});
+  }
+  
+  // Now we're authenticated, make protected requests
+  const data = await requester.signedRequestJson('/api/protected', {
+    action: 'getData'
+  });
+</script>
+```
+
+### Client API
+
+#### `setSession(config)`
+
+Initialize session after login.
+
+```javascript
+requester.setSession({
+  sessionId: 12345,
+  token: 'base64url_encoded_token',
+  sequenceNumber: 1
+});
+```
+
+#### `getSession()`
+
+Check if a valid session exists. Loads from localStorage if not in memory.
+
+```javascript
+if (requester.getSession()) {
+  // Session available
+}
+```
+
+#### `signedRequest(path, parameters, options?)`
+
+Make a signed request, returns the raw Response object.
+
+```javascript
+const response = await requester.signedRequest('/api/action', {
+  param1: 'value1',
+  param2: 123
+});
+```
+
+#### `signedRequestJson<T>(path, parameters, options?)`
+
+Make a signed request and parse JSON response.
+
+```javascript
+const data = await requester.signedRequestJson('/api/data', {
+  query: 'example'
+});
+```
+
+#### `clearSession()`
+
+Clear session data (for example after you do a logout).
+
+```javascript
+requester.clearSession();
+```
+
+### Request Options
+
+```typescript
+{
+  baseUrl?: string;           // Override base URL for this request
+  headers?: Record<string, string>;  // Additional headers
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';  // HTTP method (default: POST)
+}
+```
+
+## Signature Format
+
+The signature is computed over the following concatenated string:
+
+```
+sessionId={id};sequenceNumber={seq};timestamp={ts};{sorted_params}
+```
+
+The HMAC-SHA256 signature is computed using the session token as the secret key.
+
+Parameters are sorted alphabetically by key. Values are serialized as:
+- Primitives (string, number, boolean) and null: `String(value)`
+- Objects and arrays: `JSON.stringify(value)`
+
+## Implementing Custom Storage
+
+To implement your own session storage (e.g., Redis-based), extend the `SessionsStorage` abstract class:
+
+```typescript
+import { SessionsStorage } from '@stefanobalocco/honosignedrequests';
+import { Session } from '@stefanobalocco/honosignedrequests';
+
+class RedisSessionsStorage extends SessionsStorage {
+  async create(
+    validityToken: number,
+    tokenLength: number,
+    userId: number
+  ): Promise<Session> {
+    // Implement session creation with Redis
+    // Generate token with specified tokenLength
+    // Use validityToken for Redis TTL or expiration tracking
+    // Implement your own maxSessionsPerUser logic if needed
+  }
+
+  async getBySessionId(sessionId: number): Promise<Session | undefined> {
+    // Implement session lookup with Redis
+  }
+
+  async getByUserId(userId: number): Promise<Session[]> {
+    // Implement session lookup with Redis
+  }
+
+  async delete(sessionId: number): Promise<void> {
+    // Implement session deletion with Redis
+  }
+}
+```
+
+## Considerations
+- Storage should expire sessions
+- Invalid sessions should return 401 and trigger client-side session clearing
+- Client should be forced to serialize requests, otherwise out-of-order sequence number may arise triggering a session cleanup.
+
+## License
+
+BSD-3-Clause

package/dist/Common.d.ts

@@ -0,0 +1,6 @@
+export type Undefinedable<T> = T | undefined;
+export declare function fromBase64Url(b64url: string): Uint8Array<ArrayBuffer>;
+export declare function randomBytes(bytes: number): Uint8Array<ArrayBuffer>;
+export declare function randomInt(min: number, max: number): number;
+export declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+export declare function hmacSha256(keyBytes: Uint8Array<ArrayBuffer>, data: string): Promise<Uint8Array<ArrayBuffer>>;

package/dist/Common.js

@@ -0,0 +1,45 @@
+export function fromBase64Url(b64url) {
+    const pad = (4 - (b64url.length % 4)) % 4;
+    const b64 = (b64url + "=".repeat(pad)).replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(b64);
+    const cFL = binary.length;
+    const returnValue = new Uint8Array(cFL);
+    for (let iFL = 0; iFL < cFL; iFL++) {
+        returnValue[iFL] = binary.charCodeAt(iFL);
+    }
+    return returnValue;
+}
+export function randomBytes(bytes) {
+    const returnValue = new Uint8Array(bytes);
+    crypto.getRandomValues(returnValue);
+    return returnValue;
+}
+export function randomInt(min, max) {
+    let returnValue;
+    const range = max - min;
+    if (range > 0) {
+        const randomBuffer = new Uint32Array(randomBytes(4).buffer);
+        returnValue = min + (randomBuffer[0] % range);
+    }
+    else {
+        throw new Error('max must be > min');
+    }
+    return returnValue;
+}
+export function constantTimeEqual(a, b) {
+    let returnValue = false;
+    if (a.length === b.length) {
+        let diff = 0;
+        for (let i = 0; i < a.length; i++) {
+            diff |= a[i] ^ b[i];
+        }
+        returnValue = (diff === 0);
+    }
+    return returnValue;
+}
+export async function hmacSha256(keyBytes, data) {
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const textEncoder = new TextEncoder();
+    const signature = await crypto.subtle.sign("HMAC", key, textEncoder.encode(data));
+    return new Uint8Array(signature);
+}

package/dist/Session.d.ts

@@ -0,0 +1,8 @@
+export type Session = {
+    id: number;
+    userId: number;
+    sequenceNumber: number;
+    token: Uint8Array<ArrayBuffer>;
+    lastUsed: number;
+    data: [string, any][];
+};

package/dist/Session.js

@@ -0,0 +1 @@
+export {};

package/dist/SessionsStorage.d.ts

@@ -0,0 +1,8 @@
+import { Undefinedable } from './Common';
+import { Session } from './Session';
+export declare abstract class SessionsStorage {
+    abstract create(validityToken: number, tokenLength: number, userId: number): Promise<Session>;
+    abstract getBySessionId(sessionId: number): Promise<Undefinedable<Session>>;
+    abstract getByUserId(userId: number): Promise<Session[]>;
+    abstract delete(sessionId: number): Promise<boolean>;
+}

package/dist/SessionsStorage.js

@@ -0,0 +1,2 @@
+export class SessionsStorage {
+}

package/dist/SessionsStorageLocal.d.ts

@@ -0,0 +1,20 @@
+import { Undefinedable } from './Common';
+import { Session } from './Session';
+import { SessionsStorage } from './SessionsStorage';
+type SessionStorageLocalConfig = {
+    maxSessions: number;
+    maxSessionsPerUser: number;
+};
+export declare class SessionsStorageLocal implements SessionsStorage {
+    private readonly _maxSessions;
+    private readonly _maxSessionsPerUser;
+    private readonly _cleanupSessionLimit;
+    private _sessionsById;
+    private _sessionsByUserId;
+    constructor(options?: Partial<SessionStorageLocalConfig>);
+    create(validityToken: number, tokenLength: number, userId: number): Promise<Session>;
+    delete(sessionId: number): Promise<boolean>;
+    getByUserId(userId: number): Promise<Session[]>;
+    getBySessionId(sessionId: number): Promise<Undefinedable<Session>>;
+}
+export {};

package/dist/SessionsStorageLocal.js

@@ -0,0 +1,88 @@
+import { randomBytes, randomInt } from './Common';
+export class SessionsStorageLocal {
+    _maxSessions;
+    _maxSessionsPerUser;
+    _cleanupSessionLimit;
+    _sessionsById = new Map();
+    _sessionsByUserId = new Map();
+    constructor(options) {
+        this._maxSessions = options?.maxSessions ?? 0xFFFF;
+        this._maxSessionsPerUser = options?.maxSessionsPerUser ?? 3;
+        this._cleanupSessionLimit = Math.floor(this._maxSessions * 0.75);
+    }
+    async create(validityToken, tokenLength, userId) {
+        let returnValue;
+        const now = Date.now();
+        if (this._sessionsById.size > this._cleanupSessionLimit) {
+            await Promise.all(Array.from(this._sessionsById.entries()).filter(([_, session]) => now > (session.lastUsed + validityToken)).map(([sessionId, _]) => this.delete(sessionId)));
+        }
+        const usedIds = [...this._sessionsById.keys()].filter((sessionId) => (now <= (this._sessionsById.get(sessionId).lastUsed + validityToken))).sort((a, b) => a - b);
+        const sessionsRange = this._maxSessions - usedIds.length;
+        if (sessionsRange > 0) {
+            let sessionId = randomInt(0, this._maxSessions - usedIds.length);
+            let left = 0;
+            let right = usedIds.length;
+            while (left < right) {
+                const mid = Math.floor((left + right) / 2);
+                if (usedIds[mid] <= sessionId + mid) {
+                    left = mid + 1;
+                }
+                else {
+                    right = mid;
+                }
+            }
+            sessionId = (sessionId + left) >>> 0;
+            const session = this._sessionsById.get(sessionId);
+            if (session) {
+                if (now > session.lastUsed + validityToken) {
+                    await this.delete(sessionId);
+                }
+                else {
+                    throw new Error(`Session ${sessionId} already in use`);
+                }
+            }
+            const token = randomBytes(tokenLength);
+            returnValue = {
+                id: sessionId,
+                userId,
+                sequenceNumber: 1,
+                token,
+                lastUsed: now,
+                data: []
+            };
+            this._sessionsById.set(sessionId, returnValue);
+            const sessionsByUserId = this._sessionsByUserId.get(userId) ?? [];
+            sessionsByUserId.push(returnValue);
+            if (sessionsByUserId.length > this._maxSessionsPerUser) {
+                const oldestIndex = sessionsByUserId.reduce((minimumIndex, session, index) => session.lastUsed < sessionsByUserId[minimumIndex].lastUsed ? index : minimumIndex, 0);
+                const old = sessionsByUserId.splice(oldestIndex, 1)[0];
+                this._sessionsById.delete(old.id);
+            }
+            this._sessionsByUserId.set(userId, sessionsByUserId);
+        }
+        else {
+            throw new Error(`Session array full`);
+        }
+        return returnValue;
+    }
+    async delete(sessionId) {
+        let returnValue = false;
+        const session = this._sessionsById.get(sessionId);
+        if (session) {
+            returnValue = true;
+            this._sessionsById.delete(sessionId);
+            const userSessions = this._sessionsByUserId.get(session.userId) ?? [];
+            const sessionIndex = userSessions.findIndex((session) => session.id === sessionId);
+            if (-1 !== sessionIndex) {
+                userSessions.splice(sessionIndex, 1);
+            }
+        }
+        return returnValue;
+    }
+    async getByUserId(userId) {
+        return this._sessionsByUserId.get(userId) ?? [];
+    }
+    async getBySessionId(sessionId) {
+        return this._sessionsById.get(sessionId);
+    }
+}

package/dist/SignedRequestsManager.d.ts

@@ -0,0 +1,21 @@
+import { MiddlewareHandler } from 'hono';
+import { Undefinedable } from './Common';
+import { Session } from './Session';
+import { SessionsStorage } from './SessionsStorage';
+type SignedRequestsManagerConfig = {
+    validitySignature: number;
+    validityToken: number;
+    tokenLength: number;
+};
+export declare class SignedRequestsManager {
+    private static readonly _primitives;
+    private readonly _storage;
+    private readonly _validitySignature;
+    private readonly _validityToken;
+    private readonly _tokenLength;
+    constructor(storage?: SessionsStorage, options?: Partial<SignedRequestsManagerConfig>);
+    createSession(userId: number): Promise<Session>;
+    validate(sessionId: number, timestamp: number, parameters: [string, any][], signature: Uint8Array<ArrayBuffer>): Promise<Undefinedable<Session>>;
+    middleware: MiddlewareHandler;
+}
+export {};

package/dist/SignedRequestsManager.js

@@ -0,0 +1,91 @@
+import { constantTimeEqual, fromBase64Url, hmacSha256 } from './Common';
+import { SessionsStorageLocal } from './SessionsStorageLocal';
+export class SignedRequestsManager {
+    static _primitives = new Set(['string', 'number', 'boolean']);
+    _storage;
+    _validitySignature;
+    _validityToken;
+    _tokenLength;
+    constructor(storage, options) {
+        this._validitySignature = options?.validitySignature ?? 5000;
+        this._validityToken = options?.validityToken ?? 60 * 60000;
+        this._tokenLength = options?.tokenLength ?? 32;
+        if (!storage) {
+            storage = new SessionsStorageLocal();
+        }
+        this._storage = storage;
+    }
+    async createSession(userId) {
+        return await this._storage.create(this._validityToken, this._tokenLength, userId);
+    }
+    async validate(sessionId, timestamp, parameters, signature) {
+        let returnValue;
+        const now = Date.now();
+        if ((now > timestamp) && (now < timestamp + this._validitySignature)) {
+            const session = await this._storage.getBySessionId(sessionId);
+            if (session) {
+                if (now < session.lastUsed + this._validityToken) {
+                    const parametersOrdered = [
+                        ['sessionId', session.id],
+                        ['sequenceNumber', session.sequenceNumber],
+                        ['timestamp', timestamp],
+                        ...parameters.sort((a, b) => a[0].localeCompare(b[0]))
+                    ];
+                    const dataToSign = parametersOrdered.map(([name, value]) => {
+                        const serializedValue = (SignedRequestsManager._primitives.has(typeof value) || null === value) ? String(value) : JSON.stringify(value);
+                        return `${name}=${serializedValue}`;
+                    }).join(';');
+                    const signatureExpected = await hmacSha256(session.token, dataToSign);
+                    if (constantTimeEqual(signature, signatureExpected)) {
+                        session.lastUsed = now;
+                        session.sequenceNumber++;
+                        returnValue = session;
+                    }
+                }
+                else {
+                    await this._storage.delete(sessionId);
+                }
+            }
+        }
+        return returnValue;
+    }
+    middleware = async (context, next) => {
+        let session;
+        try {
+            const parameters = {};
+            switch (context.req.method) {
+                case 'GET': {
+                    Object.assign(parameters, context.req.query());
+                    break;
+                }
+                case 'POST': {
+                    switch (context.req.header('Content-Type')) {
+                        case 'application/json': {
+                            Object.assign(parameters, await context.req.json());
+                            break;
+                        }
+                        default: {
+                            Object.assign(parameters, await context.req.parseBody());
+                            break;
+                        }
+                    }
+                }
+            }
+            const sessionId = parseInt(parameters.sessionId, 10);
+            const timestamp = parseInt(parameters.timestamp, 10);
+            const signature = fromBase64Url(parameters.signature);
+            if (sessionId && timestamp && signature) {
+                const { sessionId: _, timestamp: __, signature: ___, ...other } = parameters;
+                const otherParameters = Object.entries(other);
+                session = await this.validate(sessionId, timestamp, otherParameters, signature);
+            }
+        }
+        catch (error) {
+            console.error('Session validation error:', error);
+        }
+        if (session) {
+            context.set('session', session);
+        }
+        await next();
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { Session } from './Session.js';
+export type { SessionsStorage } from './SessionsStorage.js';
+export { SessionsStorageLocal } from './SessionsStorageLocal.js';
+export { SignedRequestsManager } from './SignedRequestsManager.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SessionsStorageLocal } from './SessionsStorageLocal.js';
+export { SignedRequestsManager } from './SignedRequestsManager.js';

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@stefanobalocco/honosignedrequests",
+  "version": "1.0.0",
+  "description": "An hono middleware to manage signed requests, including a client implementation.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./client/dist/SignedRequester.d.ts",
+      "import": "./client/dist/SignedRequester.min.js"
+    }
+  },
+  "devDependencies": {
+    "hono": "^4.10.6",
+    "terser": "^5.44.1",
+    "typescript": "^5.5.3"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "hono",
+    "middleware",
+    "hmac",
+    "signed-requests",
+    "session",
+    "authentication"
+  ],
+  "license": "BSD-3-Clause",
+  "scripts": {
+    "build": "npm run build:server && npm run build:client",
+    "build:server": "tsc",
+    "build:client": "tsc -p client/tsconfig.json && terser client/dist/SignedRequester.js -o client/dist/SignedRequester.min.js --toplevel -m -c --mangle-props regex=/^_/"
+  }
+}