@technomoron/api-server-base 2.0.0-beta.17 → 2.0.0-beta.19

package/dist/esm/token/memory.js

@@ -6,12 +6,12 @@ function comparableUserId(value) {
     return String(value);
 }
 function cloneToken(record) {
-    // this.normalizeToken is not available in static context; caller passes through instance.
-    // cloning handled via store instance methods.
-    const normalized = record;
     return {
-        ...normalized,
-        scope: normalized.scope ? [...normalized.scope] : undefined
+        ...record,
+        scope: record.scope ? [...record.scope] : undefined,
+        expires: record.expires ? new Date(record.expires) : undefined,
+        issuedAt: record.issuedAt ? new Date(record.issuedAt) : undefined,
+        lastSeenAt: record.lastSeenAt ? new Date(record.lastSeenAt) : undefined
     };
 }
 function matchesQuery(record, query, includeExpired) {
@@ -47,15 +47,57 @@ function matchesQuery(record, query, includeExpired) {
 export class MemoryTokenStore extends TokenStore {
     constructor() {
         super(...arguments);
-        this.tokens = [];
+        this.tokens = new Map();
+        this.tokensByUser = new Map();
+    }
+    indexToken(token) {
+        const userId = comparableUserId(token.userId);
+        if (!userId) {
+            return;
+        }
+        let userTokens = this.tokensByUser.get(userId);
+        if (!userTokens) {
+            userTokens = new Set();
+            this.tokensByUser.set(userId, userTokens);
+        }
+        userTokens.add(token.refreshToken);
+    }
+    unindexToken(token) {
+        const userId = comparableUserId(token.userId);
+        if (!userId) {
+            return;
+        }
+        const userTokens = this.tokensByUser.get(userId);
+        if (!userTokens) {
+            return;
+        }
+        userTokens.delete(token.refreshToken);
+        if (userTokens.size === 0) {
+            this.tokensByUser.delete(userId);
+        }
+    }
+    removeByRefreshToken(refreshToken) {
+        const existing = this.tokens.get(refreshToken);
+        if (!existing) {
+            return;
+        }
+        this.unindexToken(existing);
+        this.tokens.delete(refreshToken);
     }
     async save(record) {
         const stored = this.normalizeToken(record);
         const normalizedUserId = comparableUserId(stored.userId);
+        if (!normalizedUserId) {
+            throw new Error('userId is required');
+        }
         const domainProvided = record.domain !== undefined;
         const fingerprintProvided = record.fingerprint !== undefined;
-        for (let index = this.tokens.length - 1; index >= 0; index -= 1) {
-            const existing = this.tokens[index];
+        const userRefreshTokens = [...(this.tokensByUser.get(normalizedUserId) ?? [])];
+        for (const refreshToken of userRefreshTokens) {
+            const existing = this.tokens.get(refreshToken);
+            if (!existing) {
+                continue;
+            }
             if (comparableUserId(existing.userId) !== normalizedUserId) {
                 continue;
             }
@@ -68,44 +110,51 @@ export class MemoryTokenStore extends TokenStore {
             if (fingerprintProvided && existing.fingerprint !== stored.fingerprint) {
                 continue;
             }
-            this.tokens.splice(index, 1);
+            this.removeByRefreshToken(existing.refreshToken);
         }
-        this.tokens.push(stored);
+        this.removeByRefreshToken(stored.refreshToken);
+        this.tokens.set(stored.refreshToken, stored);
+        this.indexToken(stored);
     }
     async get(query, opts) {
         if (!query.refreshToken && !query.accessToken && query.userId === undefined) {
             throw new Error('At least one token lookup field must be provided');
         }
         const includeExpired = opts?.includeExpired ?? false;
-        const record = this.tokens.find((token) => matchesQuery(token, query, includeExpired));
-        return record ? cloneToken(record) : null;
+        if (query.refreshToken) {
+            const record = this.tokens.get(query.refreshToken);
+            return record && matchesQuery(record, query, includeExpired) ? cloneToken(record) : null;
+        }
+        for (const token of this.tokens.values()) {
+            if (matchesQuery(token, query, includeExpired)) {
+                return cloneToken(token);
+            }
+        }
+        return null;
     }
     async delete(query) {
         if (!query.refreshToken && !query.accessToken && query.userId === undefined && !query.clientId) {
             return 0;
         }
         let removed = 0;
-        for (let index = this.tokens.length - 1; index >= 0; index -= 1) {
-            if (matchesQuery(this.tokens[index], query, true)) {
-                this.tokens.splice(index, 1);
+        const refreshTokens = [...this.tokens.keys()];
+        for (const refreshToken of refreshTokens) {
+            const token = this.tokens.get(refreshToken);
+            if (token && matchesQuery(token, query, true)) {
+                this.removeByRefreshToken(refreshToken);
                 removed += 1;
             }
         }
         return removed;
     }
     async update(params) {
-        const token = this.tokens.find((record) => {
-            if (record.refreshToken !== params.refreshToken) {
-                return false;
-            }
-            if (params.clientId && record.clientId !== params.clientId) {
-                return false;
-            }
-            return true;
-        });
+        const token = this.tokens.get(params.refreshToken);
         if (!token) {
             return false;
         }
+        if (params.clientId && token.clientId !== params.clientId) {
+            return false;
+        }
         const merged = { ...token };
         const maybeAssign = (key) => {
             const value = params[key];
@@ -129,12 +178,28 @@ export class MemoryTokenStore extends TokenStore {
         maybeAssign('lastSeenAt');
         maybeAssign('sessionCookie');
         const normalized = this.normalizeToken(merged);
+        const previousUserId = token.userId;
+        const previousRefreshToken = token.refreshToken;
+        const userChanged = comparableUserId(previousUserId) !== comparableUserId(normalized.userId);
         Object.assign(token, normalized);
+        if (userChanged || previousRefreshToken !== token.refreshToken) {
+            this.unindexToken({ ...token, userId: previousUserId, refreshToken: previousRefreshToken });
+            this.indexToken(token);
+            if (previousRefreshToken !== token.refreshToken) {
+                this.tokens.delete(previousRefreshToken);
+                this.tokens.set(token.refreshToken, token);
+            }
+        }
         return true;
     }
     async list(userId, opts = {}) {
         const includeExpired = opts.includeExpired ?? false;
-        const filtered = this.tokens.filter((token) => matchesQuery(token, { userId: comparableUserId(userId) }, includeExpired));
+        const normalizedUserId = comparableUserId(userId);
+        const userRefreshTokens = normalizedUserId ? [...(this.tokensByUser.get(normalizedUserId) ?? [])] : [];
+        const filtered = userRefreshTokens
+            .map((refreshToken) => this.tokens.get(refreshToken))
+            .filter((token) => Boolean(token))
+            .filter((token) => matchesQuery(token, { userId: normalizedUserId }, includeExpired));
         const offset = opts.offset ?? 0;
         const limit = opts.limit ?? filtered.length;
         return filtered.slice(offset, offset + limit).map(cloneToken);

package/dist/esm/token/sequelize.js

@@ -1,17 +1,7 @@
 import { DataTypes, Model, Op } from 'sequelize';
+import { normalizeStringUserId } from '../auth-api/user-id.js';
+import { DIALECTS_SUPPORTING_UNSIGNED, applyTablePrefix } from '../sequelize-utils.js';
 import { TokenStore } from './base.js';
-const DIALECTS_SUPPORTING_UNSIGNED = new Set(['mysql', 'mariadb']);
-function normalizeTablePrefix(prefix) {
-    if (!prefix) {
-        return undefined;
-    }
-    const trimmed = prefix.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function applyTablePrefix(prefix, tableName) {
-    const normalized = normalizeTablePrefix(prefix);
-    return normalized ? `${normalized}${tableName}` : tableName;
-}
 class TokenModel extends Model {
 }
 function tokenTableOptions(sequelize, tablePrefix) {
@@ -64,11 +54,11 @@ function initTokenModel(sequelize, options = {}) {
             defaultValue: DataTypes.NOW
         },
         access: {
-            type: DataTypes.STRING(512),
+            type: DataTypes.STRING(768),
             allowNull: false
         },
         refresh: {
-            type: DataTypes.STRING(512),
+            type: DataTypes.STRING(768),
             allowNull: false
         },
         domain: {
@@ -181,6 +171,13 @@ export class SequelizeTokenStore extends TokenStore {
             removalWhere.client_id = normalized.clientId;
         }
         await this.Tokens.destroy({ where: removalWhere });
+        // Access/refresh columns are unique. Remove stale collisions before insert to avoid
+        // transient uniqueness failures during retries/rotation edge-cases.
+        await this.Tokens.destroy({
+            where: {
+                [Op.or]: [{ access: normalized.accessToken ?? '' }, { refresh: normalized.refreshToken }]
+            }
+        });
         await this.Tokens.create({
             user_id: resolvedUserId,
             real_user_id: resolvedRealUserId,
@@ -340,10 +337,7 @@ export class SequelizeTokenStore extends TokenStore {
         return;
     }
     normalizeUserId(identifier) {
-        if (identifier === undefined || identifier === null) {
-            throw new Error(`Unable to normalise user identifier: ${identifier}`);
-        }
-        return String(identifier);
+        return normalizeStringUserId(identifier);
     }
     resolveRealUserId(ruid) {
         if (ruid === undefined || ruid === null) {

package/dist/esm/token/types.d.ts

@@ -9,7 +9,14 @@ export interface Token {
     status?: TokenStatus;
     ruid?: string;
     clientId?: string;
+    /**
+     * Optional session partition key. Token stores may use `domain` and `fingerprint`
+     * to replace previous sessions that match the same bucket.
+     */
     domain?: string;
+    /**
+     * Optional device/session fingerprint used together with `domain` for session bucketing.
+     */
     fingerprint?: string;
     label?: string;
     browser?: string;

package/dist/esm/user/memory.js

@@ -1,16 +1,9 @@
+import { normalizeNumericUserId } from '../auth-api/user-id.js';
 import { UserStore } from './base.js';
 function cloneUser(user) {
     return { ...user };
 }
-function normalizeUserId(identifier) {
-    if (typeof identifier === 'number' && Number.isFinite(identifier)) {
-        return identifier;
-    }
-    if (typeof identifier === 'string' && /^\d+$/.test(identifier)) {
-        return Number(identifier);
-    }
-    throw new Error(`Unable to normalise user identifier: ${identifier}`);
-}
+const normalizeUserId = normalizeNumericUserId;
 export class MemoryUserStore extends UserStore {
     constructor(options = {}) {
         super({

package/dist/esm/user/sequelize.js

@@ -1,17 +1,7 @@
 import { DataTypes, Model, Op } from 'sequelize';
+import { normalizeNumericUserId } from '../auth-api/user-id.js';
+import { DIALECTS_SUPPORTING_UNSIGNED, applyTablePrefix } from '../sequelize-utils.js';
 import { UserStore } from './base.js';
-const DIALECTS_SUPPORTING_UNSIGNED = new Set(['mysql', 'mariadb']);
-function normalizeTablePrefix(prefix) {
-    if (!prefix) {
-        return undefined;
-    }
-    const trimmed = prefix.trim();
-    return trimmed.length > 0 ? trimmed : undefined;
-}
-function applyTablePrefix(prefix, tableName) {
-    const normalized = normalizeTablePrefix(prefix);
-    return normalized ? `${normalized}${tableName}` : tableName;
-}
 function integerIdType(sequelize) {
     return DIALECTS_SUPPORTING_UNSIGNED.has(sequelize.getDialect()) ? DataTypes.INTEGER.UNSIGNED : DataTypes.INTEGER;
 }
@@ -178,12 +168,6 @@ export class SequelizeUserStore extends UserStore {
         };
     }
     normalizeUserId(identifier) {
-        if (typeof identifier === 'number' && Number.isFinite(identifier)) {
-            return identifier;
-        }
-        if (typeof identifier === 'string' && /^\d+$/.test(identifier)) {
-            return Number(identifier);
-        }
-        throw new Error(`Unable to normalise user identifier: ${identifier}`);
+        return normalizeNumericUserId(identifier);
     }
 }

package/docs/swagger/openapi.json

@@ -2,7 +2,7 @@
 	"openapi": "3.1.0",
 	"info": {
 		"title": "API Server Base",
-		"version": "2.0.0-beta.17",
+		"version": "2.0.0-beta.19",
 		"description": "OpenAPI reference for ApiServer base endpoints and optional modules. Auth, passkey, and oauth modules are optional and require the corresponding module to be enabled in the ApiServer config. Base endpoints are always available."
 	},
 	"servers": [
@@ -34,7 +34,7 @@
 			"get": {
 				"tags": ["base"],
 				"summary": "Health check",
-				"description": "Auth: none. Returns server health and version metadata.",
+				"description": "Auth: none. Returns ApiResponse<PingResponseData> with server health and version metadata.",
 				"security": [],
 				"responses": {
 					"200": {
@@ -760,145 +760,6 @@
 						}
 					}
 				}
-			},
-			"delete": {
-				"tags": ["passkey"],
-				"summary": "Delete a passkey credential",
-				"description": "Auth: strict. Deletes a passkey credential by id provided in the request body.",
-				"security": [{ "accessTokenBearer": [] }, { "accessTokenCookie": [] }, { "apiKeyBearer": [] }],
-				"requestBody": {
-					"required": true,
-					"content": {
-						"application/json": {
-							"schema": {
-								"type": "object",
-								"properties": {
-									"credentialId": {
-										"type": "string",
-										"description": "Credential id (base64url)."
-									}
-								},
-								"required": ["credentialId"]
-							}
-						}
-					}
-				},
-				"responses": {
-					"200": {
-						"description": "Credential deleted.",
-						"content": {
-							"application/json": {
-								"schema": {
-									"allOf": [
-										{ "$ref": "#/components/schemas/ApiResponse" },
-										{
-											"type": "object",
-											"properties": {
-												"data": { "$ref": "#/components/schemas/PasskeyDeleteResponseData" }
-											},
-											"required": ["data"]
-										}
-									]
-								}
-							}
-						}
-					},
-					"400": {
-						"description": "Missing or invalid credentialId.",
-						"content": {
-							"application/json": {
-								"schema": {
-									"allOf": [
-										{ "$ref": "#/components/schemas/ApiResponse" },
-										{
-											"type": "object",
-											"properties": {
-												"data": { "type": "null" }
-											},
-											"required": ["data"]
-										}
-									]
-								}
-							}
-						}
-					},
-					"401": {
-						"description": "Authentication required.",
-						"content": {
-							"application/json": {
-								"schema": {
-									"allOf": [
-										{ "$ref": "#/components/schemas/ApiResponse" },
-										{
-											"type": "object",
-											"properties": {
-												"data": { "type": "null" }
-											},
-											"required": ["data"]
-										}
-									]
-								}
-							}
-						}
-					},
-					"403": {
-						"description": "Authenticated user not found.",
-						"content": {
-							"application/json": {
-								"schema": {
-									"allOf": [
-										{ "$ref": "#/components/schemas/ApiResponse" },
-										{
-											"type": "object",
-											"properties": {
-												"data": { "type": "null" }
-											},
-											"required": ["data"]
-										}
-									]
-								}
-							}
-						}
-					},
-					"404": {
-						"description": "Passkey not found.",
-						"content": {
-							"application/json": {
-								"schema": {
-									"allOf": [
-										{ "$ref": "#/components/schemas/ApiResponse" },
-										{
-											"type": "object",
-											"properties": {
-												"data": { "type": "null" }
-											},
-											"required": ["data"]
-										}
-									]
-								}
-							}
-						}
-					},
-					"501": {
-						"description": "Passkey management not configured.",
-						"content": {
-							"application/json": {
-								"schema": {
-									"allOf": [
-										{ "$ref": "#/components/schemas/ApiResponse" },
-										{
-											"type": "object",
-											"properties": {
-												"data": { "type": "null" }
-											},
-											"required": ["data"]
-										}
-									]
-								}
-							}
-						}
-					}
-				}
 			}
 		},
 		"/api/auth/v1/passkeys/{credentialId}": {
@@ -1431,7 +1292,7 @@
 			},
 			"ApiResponse": {
 				"type": "object",
-				"description": "Standard envelope used by all endpoints (success or error). Mirrors ApiClientBase.ApiResponseData.",
+				"description": "ApiResponse<T> standard envelope used by all endpoints (success or error). T is the endpoint-specific payload type carried in the data field. Mirrors ApiClientBase.ApiResponseData.",
 				"properties": {
 					"success": {
 						"type": "boolean",
@@ -1463,6 +1324,10 @@
 				"type": "object",
 				"description": "Data payload returned by GET /api/v1/ping.",
 				"properties": {
+					"success": {
+						"type": "boolean",
+						"description": "Always true (redundant with ApiResponse.success)."
+					},
 					"status": {
 						"type": "string",
 						"description": "Health indicator (\"ok\")."
@@ -1477,15 +1342,16 @@
 						"type": "number"
 					},
 					"startedAt": {
-						"type": "string",
-						"format": "date-time"
+						"type": "integer",
+						"format": "int64",
+						"description": "Server start time as milliseconds since epoch."
 					},
 					"timestamp": {
 						"type": "string",
 						"format": "date-time"
 					}
 				},
-				"required": ["status", "uptimeSec", "startedAt", "timestamp"]
+				"required": ["success", "status", "uptimeSec", "startedAt", "timestamp"]
 			},
 			"AuthTokensResponseData": {
 				"type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@technomoron/api-server-base",
-	"version": "2.0.0-beta.17",
+	"version": "2.0.0-beta.19",
 	"description": "Api Server Skeleton / Base Class",
 	"type": "module",
 	"main": "./dist/cjs/index.cjs",
@@ -70,34 +70,34 @@
 		"@simplewebauthn/server": "^13.2.2",
 		"@types/cookie-parser": "^1.4.10",
 		"@types/cors": "^2.8.19",
-		"@types/express": "^4.17.25",
+		"@types/express": "^5.0.6",
 		"@types/jsonwebtoken": "^9.0.10",
-		"@types/multer": "^1.4.13",
-		"bcryptjs": "^2.4.3",
+		"@types/multer": "^2.0.0",
+		"bcryptjs": "^3.0.3",
 		"cookie-parser": "^1.4.7",
-		"cors": "^2.8.5",
-		"express": "^4.22.1",
+		"cors": "^2.8.6",
+		"express": "^5.2.1",
 		"jsonwebtoken": "^9.0.3",
 		"multer": "^2.0.2"
 	},
 	"devDependencies": {
-		"@types/bcryptjs": "^2.4.6",
-		"@types/express-serve-static-core": "^5.1.0",
+		"@types/express-serve-static-core": "^5.1.1",
 		"@types/supertest": "^6.0.3",
 		"@typescript-eslint/eslint-plugin": "^8.54.0",
 		"@typescript-eslint/parser": "^8.54.0",
+		"@vitest/coverage-v8": "4.0.18",
 		"eslint": "^9.39.2",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-import": "^2.32.0",
 		"jsonc-eslint-parser": "^2.4.2",
-		"mysql2": "^3.16.0",
-		"pg": "^8.16.3",
+		"mysql2": "^3.16.3",
+		"pg": "^8.18.0",
 		"prettier": "^3.8.1",
 		"sequelize": "^6.37.7",
 		"sqlite3": "^5.1.7",
-		"supertest": "^7.1.4",
+		"supertest": "^7.2.2",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.16"
+		"vitest": "^4.0.18"
 	},
 	"peerDependencies": {
 		"mysql2": "^3.16.0",