@moshaver/cmb-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobin Karam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# `@moshaver/cmb-auth`
+
+Framework-neutral login normalization and secure session credential lifecycle. Account/student eligibility, password hashing, persistence, throttling, and HTTP/CSRF error mapping remain in the API adapter.
+
+## Install and use
+
+```bash
+npm install @moshaver/cmb-auth
+```
+
+```js
+const { SessionCredentialService, InMemorySessionStore } = require("@moshaver/cmb-auth");
+// Use a durable host store instead of InMemorySessionStore in production.
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@moshaver/cmb-auth",
+  "version": "0.1.0",
+  "description": "Composable Modular Backend auth primitives.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cmb",
+    "modular-backend",
+    "backend",
+    "framework-agnostic",
+    "auth"
+  ],
+  "engines": {
+    "node": ">=22.13.0 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mobin-Karam/moshaver.git",
+    "directory": "packages/cmb/auth"
+  },
+  "bugs": {
+    "url": "https://github.com/Mobin-Karam/moshaver/issues"
+  },
+  "homepage": "https://github.com/Mobin-Karam/moshaver/tree/main/packages/cmb",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "@moshaver/cmb-identity": "^0.1.0",
+    "@moshaver/cmb-kernel": "^0.1.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,13 @@
+export const AUTH_MODULE: Readonly<{ id: "auth"; version: string; kind: "platform"; dependencies: readonly string[] }>;
+export type SessionCredentials = { accessToken: string; refreshToken: string; csrfToken: string; expiresAt: Date; refreshExpiresAt: Date };
+export class SessionCredentialService { constructor(options?: { accessTokenTtlMinutes?: number; refreshTokenTtlDays?: number; now?: () => number }); normalizeLogin(username: unknown): string; issue(): SessionCredentials; hash(value: string): string; safeEqual(expectedValue: string, receivedValue: string): boolean }
+export type CmbSession<TAttributes extends object = Record<string, unknown>> = Readonly<{ subjectId: string; csrfToken: string; expiresAt: Date; revokedAt: Date | null; attributes: Readonly<TAttributes> }>;
+export class InMemorySessionStore<TAttributes extends object = Record<string, unknown>> {
+  constructor(options?: { credentials?: SessionCredentialService; accessTokenTtlMinutes?: number; refreshTokenTtlDays?: number; now?: () => number });
+  create(subjectId: string, attributes?: TAttributes): SessionCredentials;
+  authenticate(accessToken: string): CmbSession<TAttributes> | null;
+  require(accessToken: string): CmbSession<TAttributes>;
+  verifyCsrf(accessToken: string, receivedToken: string): CmbSession<TAttributes>;
+  revoke(accessToken: string): boolean;
+  deactivateSubject(subjectId: string): number;
+}

package/src/index.js

@@ -0,0 +1,78 @@
+"use strict";
+const crypto = require("node:crypto");
+const { defineModule } = require("@moshaver/cmb-kernel");
+const { normalizeUsername } = require("@moshaver/cmb-identity");
+const AUTH_MODULE = defineModule({ id: "auth", version: "0.1.0", kind: "platform", dependencies: ["identity", "kernel"], provides: ["security.sessions"], requires: ["identity.context"], configuration: { accessTokenTtlMinutes: 15, refreshTokenTtlDays: 30 } });
+class SessionCredentialService {
+  constructor(options = {}) {
+    this.accessTokenTtlMinutes = Number(options.accessTokenTtlMinutes ?? 15);
+    this.refreshTokenTtlDays = Number(options.refreshTokenTtlDays ?? 30);
+    this.now = options.now ?? Date.now;
+    if (!(this.accessTokenTtlMinutes > 0) || !(this.refreshTokenTtlDays > 0)) throw new TypeError("Session credential TTL values must be positive.");
+  }
+  normalizeLogin(username) { return normalizeUsername(username); }
+  issue() { const now = this.now(); return { accessToken: crypto.randomBytes(32).toString("base64url"), refreshToken: crypto.randomBytes(48).toString("base64url"), csrfToken: crypto.randomBytes(24).toString("base64url"), expiresAt: new Date(now + this.accessTokenTtlMinutes * 60 * 1000), refreshExpiresAt: new Date(now + this.refreshTokenTtlDays * 24 * 60 * 60 * 1000) }; }
+  hash(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
+  safeEqual(expectedValue, receivedValue) { const expected = Buffer.from(expectedValue); const received = Buffer.from(receivedValue); return expected.length === received.length && crypto.timingSafeEqual(expected, received); }
+}
+
+class InMemorySessionStore {
+  constructor(options = {}) {
+    this.credentials = options.credentials ?? new SessionCredentialService(options);
+    this.now = options.now ?? Date.now;
+    this.sessions = new Map();
+    this.inactiveSubjects = new Set();
+  }
+
+  create(subjectId, attributes = {}) {
+    const subject = String(subjectId ?? "").trim();
+    if (!subject) throw new TypeError("Session subjectId is required.");
+    if (this.inactiveSubjects.has(subject)) throw new Error("Session subject is inactive.");
+    const issued = this.credentials.issue();
+    this.sessions.set(this.credentials.hash(issued.accessToken), {
+      subjectId: subject,
+      csrfToken: issued.csrfToken,
+      expiresAt: issued.expiresAt,
+      revokedAt: null,
+      attributes: Object.freeze({ ...attributes }),
+    });
+    return issued;
+  }
+
+  authenticate(accessToken) {
+    const token = String(accessToken ?? "");
+    if (!token) return null;
+    const session = this.sessions.get(this.credentials.hash(token));
+    if (!session || session.revokedAt || session.expiresAt.getTime() <= this.now()) return null;
+    if (this.inactiveSubjects.has(session.subjectId)) return null;
+    return Object.freeze({ ...session });
+  }
+
+  require(accessToken) {
+    const session = this.authenticate(accessToken);
+    if (!session) throw new Error("Authentication required.");
+    return session;
+  }
+
+  verifyCsrf(accessToken, receivedToken) {
+    const session = this.require(accessToken);
+    if (!this.credentials.safeEqual(session.csrfToken, String(receivedToken ?? ""))) throw new Error("Invalid CSRF token.");
+    return session;
+  }
+
+  revoke(accessToken) {
+    const session = this.sessions.get(this.credentials.hash(String(accessToken ?? "")));
+    if (!session || session.revokedAt) return false;
+    session.revokedAt = new Date(this.now());
+    return true;
+  }
+
+  deactivateSubject(subjectId) {
+    const subject = String(subjectId ?? "").trim();
+    if (!subject) throw new TypeError("Session subjectId is required.");
+    this.inactiveSubjects.add(subject);
+    return [...this.sessions.values()].filter((session) => session.subjectId === subject).length;
+  }
+}
+
+module.exports = { AUTH_MODULE, SessionCredentialService, InMemorySessionStore };