@stefanobalocco/honosignedrequests 1.0.0 → 1.1.2

package/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2025, Stefano Balocco <stefano.balocco@gmail.com>
+Copyright (c) 2025-2026, 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:

package/README.md

@@ -128,6 +128,7 @@ These are passed to `SignedRequestsManager` constructor and apply to all storage
 | `validitySignature` | 5000 | Signature validity window in milliseconds |
 | `validityToken` | 3600000 | Session token validity in milliseconds |
 | `tokenLength` | 32 | Token length in bytes (cryptographic secret) |
+| `onError` | undefined | Callback invoked when an error occurs during request validation |
 
 #### SessionsStorageLocal Specific Parameters
 
@@ -147,8 +148,10 @@ These are specific to the in-memory implementation:
   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
+  // You can also specify a base URL for requests
   //const requester = new SignedRequester('https://api.example.com');
+  // You can also specify an error handler for encoding/decoding errors
+  //const requester = new SignedRequester('https://api.example.com', (error) => console.error(error));
   
   // Check if we have session data stored
   let needLogin = true;
@@ -194,6 +197,17 @@ These are specific to the in-memory implementation:
 
 ### Client API
 
+#### Constructor
+
+```javascript
+const requester = new SignedRequester(baseUrl?, onError?);
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `baseUrl` | `string` | Optional base URL for all requests. If not provided, relative paths are used. |
+| `onError` | `(error: unknown) => void` | Optional callback invoked when encoding/decoding errors occur. |
+
 #### `setSession(config)`
 
 Initialize session after login.

package/client/dist/SignedRequester.d.ts

@@ -0,0 +1,38 @@
+type Methods = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type SessionConfig = {
+    sessionId: number;
+    token: string;
+    sequenceNumber: number;
+};
+type SignedRequest<T = Record<string, any>> = {
+    sessionId: number;
+    timestamp: number;
+    signature: string;
+} & T;
+type SignedRequestOptions = {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    method?: Methods;
+};
+declare class SignedRequester {
+    private static readonly _primitives;
+    private readonly _baseUrl;
+    private readonly _onError?;
+    private _sessionId;
+    private _token;
+    private _sequenceNumber;
+    private _semaphore;
+    private _semaphoreQueue;
+    private _semaphoreAcquire;
+    private _semaphoreRelease;
+    private _incrementSequenceNumber;
+    private _loadFromStorage;
+    constructor(baseUrl?: string, onError?: (error: unknown) => void);
+    setSession(config: SessionConfig): void;
+    getSession(): boolean;
+    clearSession(): void;
+    signedRequest(path: string, parameters: Record<string, any>, options?: SignedRequestOptions): Promise<Response>;
+    signedRequestJson<T = any>(path: string, parameters: Record<string, any>, options?: SignedRequestOptions): Promise<T>;
+}
+export type { SessionConfig, SignedRequest, SignedRequestOptions };
+export { SignedRequester };

package/client/dist/SignedRequester.js

@@ -0,0 +1,219 @@
+function _base64url_encode(value, onError) {
+    let returnValue = '';
+    if (0 < value?.length) {
+        try {
+            const base64String = Array.from(value, (byte) => String.fromCharCode(byte)).join('');
+            returnValue = btoa(base64String)
+                .replace(/\+/g, '-')
+                .replace(/\//g, '_')
+                .replace(/=+$/, '');
+        }
+        catch (error) {
+            onError?.(error);
+        }
+    }
+    return returnValue;
+}
+function _base64url_decode(value, onError) {
+    let returnValue;
+    if (0 < value?.length && _base64UrlVerify.test(value)) {
+        const padding = value.length % 4;
+        const paddedValue = 0 === padding ? value : value.padEnd(value.length + (4 - padding), '=');
+        const base64 = paddedValue.replace(/-/g, '+').replace(/_/g, '/');
+        try {
+            const binaryString = atob(base64);
+            returnValue = Uint8Array.from(binaryString, (char) => char.charCodeAt(0));
+        }
+        catch (error) {
+            onError?.(error);
+        }
+    }
+    return returnValue;
+}
+const _base64UrlVerify = /^(?=.)(?:[A-Za-z0-9\-_]{4})*(?:[A-Za-z0-9\-_]{2}(?:==)?|[A-Za-z0-9\-_]{3}=?)?$/;
+class SignedRequester {
+    _semaphoreAcquire(wait = true) {
+        let returnValue = Promise.resolve(false);
+        if (!this._semaphore) {
+            this._semaphore = true;
+            returnValue = Promise.resolve(true);
+        }
+        else if (wait) {
+            returnValue = new Promise((resolve) => {
+                this._semaphoreQueue.push(resolve);
+            });
+        }
+        return returnValue;
+    }
+    _semaphoreRelease() {
+        if (this._semaphore) {
+            if (0 < this._semaphoreQueue.length) {
+                const nextWaiting = this._semaphoreQueue.shift();
+                if (nextWaiting) {
+                    nextWaiting(true);
+                }
+            }
+            else {
+                this._semaphore = false;
+            }
+        }
+    }
+    _incrementSequenceNumber() {
+        if (undefined !== this._sequenceNumber) {
+            this._sequenceNumber++;
+            localStorage.setItem('sequenceNumber', this._sequenceNumber.toString());
+        }
+    }
+    _loadFromStorage() {
+        let returnValue = false;
+        const sessionIdStr = localStorage.getItem('sessionId');
+        const tokenStr = localStorage.getItem('token');
+        const sequenceNumberStr = localStorage.getItem('sequenceNumber');
+        if (sessionIdStr && tokenStr && sequenceNumberStr) {
+            const sessionId = parseInt(sessionIdStr);
+            const sequenceNumber = parseInt(sequenceNumberStr);
+            const token = _base64url_decode(tokenStr, this._onError);
+            if (!isNaN(sessionId) && !isNaN(sequenceNumber) && token) {
+                this._sessionId = sessionId;
+                this._token = token;
+                this._sequenceNumber = sequenceNumber;
+                returnValue = true;
+            }
+        }
+        return returnValue;
+    }
+    constructor(baseUrl, onError) {
+        this._semaphore = false;
+        this._semaphoreQueue = [];
+        this._baseUrl = baseUrl;
+        this._onError = onError;
+    }
+    setSession(config) {
+        const token = _base64url_decode(config.token, this._onError);
+        if (token) {
+            this._sessionId = config.sessionId;
+            this._token = token;
+            this._sequenceNumber = config.sequenceNumber;
+            localStorage.setItem('sessionId', config.sessionId.toString());
+            localStorage.setItem('token', config.token);
+            localStorage.setItem('sequenceNumber', config.sequenceNumber.toString());
+        }
+        else {
+            throw new Error('Invalid token format');
+        }
+    }
+    getSession() {
+        let returnValue;
+        if (undefined !== this._sessionId &&
+            undefined !== this._token &&
+            undefined !== this._sequenceNumber) {
+            returnValue = true;
+        }
+        else {
+            returnValue = this._loadFromStorage();
+        }
+        return returnValue;
+    }
+    clearSession() {
+        localStorage.removeItem('sessionId');
+        localStorage.removeItem('token');
+        localStorage.removeItem('sequenceNumber');
+        this._sessionId = undefined;
+        this._token = undefined;
+        this._sequenceNumber = undefined;
+    }
+    async signedRequest(path, parameters, options = {}) {
+        let returnValue;
+        let error;
+        await this._semaphoreAcquire();
+        try {
+            if (undefined !== this._sessionId &&
+                undefined !== this._token &&
+                undefined !== this._sequenceNumber) {
+                const timestamp = Date.now();
+                const parametersArray = Object.entries(parameters);
+                const parametersOrdered = [
+                    ['sessionId', this._sessionId],
+                    ['sequenceNumber', this._sequenceNumber],
+                    ['timestamp', timestamp],
+                    ...parametersArray.sort((a, b) => a[0].localeCompare(b[0]))
+                ];
+                const dataToSign = parametersOrdered
+                    .map(([name, value]) => {
+                    const serializedValue = SignedRequester._primitives.has(typeof value) || null === value
+                        ? String(value)
+                        : JSON.stringify(value);
+                    return `${name}=${serializedValue}`;
+                })
+                    .join(';');
+                const cryptoKey = await crypto.subtle.importKey('raw', this._token, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+                const encoder = new TextEncoder();
+                const signatureBuffer = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(dataToSign));
+                const signature = _base64url_encode(new Uint8Array(signatureBuffer), this._onError);
+                const signedPayload = {
+                    sessionId: this._sessionId,
+                    timestamp: timestamp,
+                    signature: signature
+                };
+                Object.assign(signedPayload, Object.fromEntries(parametersArray));
+                const url = options.baseUrl
+                    ? `${options.baseUrl}${path}`
+                    : (this._baseUrl ? `${this._baseUrl}${path}` : path);
+                const method = options.method || 'POST';
+                returnValue = await fetch(url, {
+                    method: method,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...options.headers
+                    },
+                    body: JSON.stringify(signedPayload)
+                });
+                if (returnValue.ok) {
+                    this._incrementSequenceNumber();
+                }
+                else if (401 === returnValue.status) {
+                    this.clearSession();
+                }
+            }
+            else {
+                error = new Error('Session not configured');
+            }
+        }
+        catch (e) {
+            error = e instanceof Error ? e : new Error(String(e));
+        }
+        finally {
+            this._semaphoreRelease();
+        }
+        if (error) {
+            throw error;
+        }
+        return returnValue;
+    }
+    async signedRequestJson(path, parameters, options = {}) {
+        let returnValue;
+        let error;
+        try {
+            const response = await this.signedRequest(path, parameters, options);
+            if (response.ok) {
+                returnValue = (await response.json());
+            }
+            else {
+                error = new Error(`Request failed with status ${response.status}`);
+            }
+        }
+        catch (e) {
+            error = e instanceof Error ? e : new Error(String(e));
+        }
+        if (error) {
+            throw error;
+        }
+        return returnValue;
+    }
+}
+SignedRequester._primitives = new Set([
+    'undefined',
+    'string',
+    'number'
+]);
+export { SignedRequester };

package/client/dist/SignedRequester.min.js

@@ -0,0 +1 @@
+function t(t,s){let i;if(0<t?.length&&e.test(t)){const e=t.length%4,o=(0===e?t:t.padEnd(t.length+(4-e),"=")).replace(/-/g,"+").replace(/_/g,"/");try{const t=atob(o);i=Uint8Array.from(t,t=>t.charCodeAt(0))}catch(t){s?.(t)}}return i}const e=/^(?=.)(?:[A-Za-z0-9\-_]{4})*(?:[A-Za-z0-9\-_]{2}(?:==)?|[A-Za-z0-9\-_]{3}=?)?$/;class s{t(t=!0){let e=Promise.resolve(!1);return this.i?t&&(e=new Promise(t=>{this.o.push(t)})):(this.i=!0,e=Promise.resolve(!0)),e}h(){if(this.i)if(0<this.o.length){const t=this.o.shift();t&&t(!0)}else this.i=!1}l(){void 0!==this.u&&(this.u++,localStorage.setItem("sequenceNumber",this.u.toString()))}S(){let e=!1;const s=localStorage.getItem("sessionId"),i=localStorage.getItem("token"),o=localStorage.getItem("sequenceNumber");if(s&&i&&o){const r=parseInt(s),n=parseInt(o),a=t(i,this.m);isNaN(r)||isNaN(n)||!a||(this.p=r,this.N=a,this.u=n,e=!0)}return e}constructor(t,e){this.i=!1,this.o=[],this.v=t,this.m=e}setSession(e){const s=t(e.token,this.m);if(!s)throw new Error("Invalid token format");this.p=e.sessionId,this.N=s,this.u=e.sequenceNumber,localStorage.setItem("sessionId",e.sessionId.toString()),localStorage.setItem("token",e.token),localStorage.setItem("sequenceNumber",e.sequenceNumber.toString())}getSession(){let t;return t=void 0!==this.p&&void 0!==this.N&&void 0!==this.u||this.S(),t}clearSession(){localStorage.removeItem("sessionId"),localStorage.removeItem("token"),localStorage.removeItem("sequenceNumber"),this.p=void 0,this.N=void 0,this.u=void 0}async signedRequest(t,e,i={}){let o,r;await this.t();try{if(void 0!==this.p&&void 0!==this.N&&void 0!==this.u){const r=Date.now(),n=Object.entries(e),a=[["sessionId",this.p],["sequenceNumber",this.u],["timestamp",r],...n.sort((t,e)=>t[0].localeCompare(e[0]))].map(([t,e])=>`${t}=${s.q.has(typeof e)||null===e?String(e):JSON.stringify(e)}`).join(";"),h=await crypto.subtle.importKey("raw",this.N,{name:"HMAC",hash:"SHA-256"},!1,["sign"]),c=new TextEncoder,l=await crypto.subtle.sign("HMAC",h,c.encode(a)),u=function(t,e){let s="";if(0<t?.length)try{const e=Array.from(t,t=>String.fromCharCode(t)).join("");s=btoa(e).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}catch(t){e?.(t)}return s}(new Uint8Array(l),this.m),d={sessionId:this.p,timestamp:r,signature:u};Object.assign(d,Object.fromEntries(n));const g=i.baseUrl?`${i.baseUrl}${t}`:this.v?`${this.v}${t}`:t,S=i.method||"POST";o=await fetch(g,{method:S,headers:{"Content-Type":"application/json",...i.headers},body:JSON.stringify(d)}),o.ok?this.l():401===o.status&&this.clearSession()}else r=new Error("Session not configured")}catch(t){r=t instanceof Error?t:new Error(String(t))}finally{this.h()}if(r)throw r;return o}async signedRequestJson(t,e,s={}){let i,o;try{const r=await this.signedRequest(t,e,s);r.ok?i=await r.json():o=new Error(`Request failed with status ${r.status}`)}catch(t){o=t instanceof Error?t:new Error(String(t))}if(o)throw o;return i}}s.q=new Set(["undefined","string","number"]);export{s as SignedRequester};

package/dist/Common.d.ts

@@ -4,3 +4,5 @@ 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>>;
+export declare const base64Verify: RegExp;
+export declare const base64UrlVerify: RegExp;

package/dist/Common.js

@@ -1,5 +1,5 @@
 export function fromBase64Url(b64url) {
-    const pad = (4 - (b64url.length % 4)) % 4;
+    const pad = (4 - (b64url?.length % 4)) % 4;
     const b64 = (b64url + "=".repeat(pad)).replace(/-/g, "+").replace(/_/g, "/");
     const binary = atob(b64);
     const cFL = binary.length;
@@ -43,3 +43,5 @@ export async function hmacSha256(keyBytes, data) {
     const signature = await crypto.subtle.sign("HMAC", key, textEncoder.encode(data));
     return new Uint8Array(signature);
 }
+export const base64Verify = /^(?=.)(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+export const base64UrlVerify = /^(?=.)(?:[A-Za-z0-9\-_]{4})*(?:[A-Za-z0-9\-_]{2}(?:==)?|[A-Za-z0-9\-_]{3}=?)?$/;

package/dist/SessionsStorage.d.ts

@@ -1,5 +1,5 @@
-import { Undefinedable } from './Common';
-import { Session } from './Session';
+import { Undefinedable } from './Common.js';
+import { Session } from './Session.js';
 export declare abstract class SessionsStorage {
     abstract create(validityToken: number, tokenLength: number, userId: number): Promise<Session>;
     abstract getBySessionId(sessionId: number): Promise<Undefinedable<Session>>;

package/dist/SessionsStorageLocal.d.ts

@@ -1,6 +1,6 @@
-import { Undefinedable } from './Common';
-import { Session } from './Session';
-import { SessionsStorage } from './SessionsStorage';
+import { Undefinedable } from './Common.js';
+import { Session } from './Session.js';
+import { SessionsStorage } from './SessionsStorage.js';
 type SessionStorageLocalConfig = {
     maxSessions: number;
     maxSessionsPerUser: number;

package/dist/SessionsStorageLocal.js

@@ -1,4 +1,4 @@
-import { randomBytes, randomInt } from './Common';
+import { randomBytes, randomInt } from './Common.js';
 export class SessionsStorageLocal {
     _maxSessions;
     _maxSessionsPerUser;

package/dist/SignedRequestsManager.d.ts

@@ -1,11 +1,12 @@
 import { MiddlewareHandler } from 'hono';
-import { Undefinedable } from './Common';
-import { Session } from './Session';
-import { SessionsStorage } from './SessionsStorage';
+import { Undefinedable } from './Common.js';
+import { Session } from './Session.js';
+import { SessionsStorage } from './SessionsStorage.js';
 type SignedRequestsManagerConfig = {
     validitySignature: number;
     validityToken: number;
     tokenLength: number;
+    onError?: (error: unknown) => void;
 };
 export declare class SignedRequestsManager {
     private static readonly _primitives;
@@ -13,6 +14,7 @@ export declare class SignedRequestsManager {
     private readonly _validitySignature;
     private readonly _validityToken;
     private readonly _tokenLength;
+    private readonly _onError?;
     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>>;

package/dist/SignedRequestsManager.js

@@ -1,15 +1,17 @@
-import { constantTimeEqual, fromBase64Url, hmacSha256 } from './Common';
-import { SessionsStorageLocal } from './SessionsStorageLocal';
+import { base64UrlVerify, constantTimeEqual, fromBase64Url, hmacSha256 } from './Common.js';
+import { SessionsStorageLocal } from './SessionsStorageLocal.js';
 export class SignedRequestsManager {
     static _primitives = new Set(['string', 'number', 'boolean']);
     _storage;
     _validitySignature;
     _validityToken;
     _tokenLength;
+    _onError;
     constructor(storage, options) {
         this._validitySignature = options?.validitySignature ?? 5000;
         this._validityToken = options?.validityToken ?? 60 * 60000;
         this._tokenLength = options?.tokenLength ?? 32;
+        this._onError = options?.onError;
         if (!storage) {
             storage = new SessionsStorageLocal();
         }
@@ -59,12 +61,13 @@ export class SignedRequestsManager {
                     break;
                 }
                 case 'POST': {
-                    switch (context.req.header('Content-Type')) {
+                    switch (context.req.header('Content-Type')?.split(';')[0].trim().toLowerCase()) {
                         case 'application/json': {
                             Object.assign(parameters, await context.req.json());
                             break;
                         }
-                        default: {
+                        case 'multipart/form-data':
+                        case 'application/x-www-form-urlencoded': {
                             Object.assign(parameters, await context.req.parseBody());
                             break;
                         }
@@ -73,15 +76,22 @@ export class SignedRequestsManager {
             }
             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);
+            if (sessionId && timestamp) {
+                if (parameters.signature) {
+                    if (base64UrlVerify.test(parameters.signature)) {
+                        const signature = fromBase64Url(parameters.signature);
+                        const { sessionId: _, timestamp: __, signature: ___, ...other } = parameters;
+                        const otherParameters = Object.entries(other);
+                        session = await this.validate(sessionId, timestamp, otherParameters, signature);
+                    }
+                    else {
+                        throw new Error('Invalid signature format');
+                    }
+                }
             }
         }
         catch (error) {
-            console.error('Session validation error:', error);
+            this._onError?.(error);
         }
         if (session) {
             context.set('session', session);

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@stefanobalocco/honosignedrequests",
-  "version": "1.0.0",
+  "version": "1.1.2",
   "description": "An hono middleware to manage signed requests, including a client implementation.",
+  "author": "Stefano Balocco <stefano.balocco@gmail.com>",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/StefanoBalocco/HonoSignedRequests.git"
+  },
+  "bugs": {
+    "url": "https://github.com/StefanoBalocco/HonoSignedRequests/issues"
+  },
+  "homepage": "https://github.com/StefanoBalocco/HonoSignedRequests",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -14,16 +25,29 @@
       "import": "./client/dist/SignedRequester.min.js"
     }
   },
+  "scripts": {
+    "build": "npm run build:server && npm run build:client && npm run build:tests",
+    "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=/^_/",
+    "build:tests": "tsc -p tests/tsconfig.json",
+    "run:tests": "npx ava tests/dist/*.test.js --verbose"
+  },
   "devDependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@types/node": "^22.10.5",
+    "ava": "^6.4.1",
+    "c8": "^10.1.3",
     "hono": "^4.10.6",
     "terser": "^5.44.1",
-    "typescript": "^5.5.3"
+    "typescript": "^5.5.3",
+    "undici": "^7.4.0"
   },
   "peerDependencies": {
     "hono": "^4.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "client/dist"
   ],
   "keywords": [
     "hono",
@@ -32,11 +56,5 @@
     "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=/^_/"
-  }
-}
+  ]
+}