@maestro-js/auth 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import * as _maestro_js_crypt from '@maestro-js/crypt';
+import { Iso } from 'iso-fns2';
+import { Session } from '@maestro-js/session';
+import { Hash } from '@maestro-js/hash';
+
+interface RememberMeTokenType {
+    selector: string;
+    verifier: string;
+}
+interface RememberMeTokenRecordType<Id, DeviceContext> {
+    authenticatableId: Id;
+    deviceContext: DeviceContext;
+    selector: string;
+    verifierHash: string;
+    expirationDate: Iso.Instant | null;
+    rotatedDate: Iso.Instant | null;
+}
+interface RememberMeOptionsType<Id, DeviceContext> {
+    maxRememberMeSeconds: number;
+    tokenReuseGracePeriodSeconds?: number;
+    create(options: RememberMeTokenRecordType<Id, DeviceContext>): Promise<unknown>;
+    getBySelector(selector: string): Promise<RememberMeTokenRecordType<Id, DeviceContext> | null>;
+    rotateBySelector(selector: string, token: {
+        verifierHash: string;
+        selector: string;
+    }): Promise<void>;
+    revokeBySelector(selector: string): Promise<void>;
+    revokeByAuthenticatableId(id: Id): Promise<void>;
+    validateDeviceContext?(creatingDeviceContext: DeviceContext, currentDeviceContext: DeviceContext): Promise<boolean> | boolean;
+}
+
+declare function create<Id, Credentials, DeviceContext>(config: Auth.Internal.AuthServiceConfig<Id, Credentials, DeviceContext>): Auth.Internal.AuthService<Id, Credentials, DeviceContext>;
+declare function provider<Key extends Auth.Provider.Key>(key: Key): Auth.AuthService<Key>;
+/**
+ * Session-based authentication with pluggable credential drivers and optional remember-me tokens.
+ * Call methods directly on the default instance, or use `Auth.Provider.create()` for named instances.
+ */
+declare const AuthBase: {
+    Provider: {
+        create: typeof create;
+        register: (name: Auth.Provider.Key, item: Auth.AnyAuthService) => void;
+    };
+    provider: typeof provider;
+};
+type KeysWithFallback = keyof Auth.Provider.Keys extends never ? {
+    default: {
+        Id: unknown;
+        Credentials: Record<string, unknown>;
+        DeviceContext: unknown;
+    };
+} : Auth.Provider.Keys;
+declare const Auth: Auth.AuthService<'default'> & typeof AuthBase;
+/**
+ * Session-based authentication with pluggable credential drivers and optional remember-me tokens.
+ *
+ * Provides session-based tracking with credential change detection,
+ * and encrypted remember-me cookies with automatic token rotation for
+ * long-lived sessions. Credential verification is handled by a pluggable
+ * driver (e.g. `Auth.drivers.password()`).
+ *
+ * @example
+ * ```ts
+ * // Register with a credential driver (e.g. Password.create().verifyCredentials)
+ * Auth.Provider.register('default', Auth.Provider.create({
+ *   name: 'web',
+ *   verifyCredentials: passwordService.verifyCredentials,
+ *   getAuthenticatableById: (id) => db.findById(id),
+ *   updateCredentialsInvalidBefore: (id, date) => db.updateCredentialsInvalidBefore(id, date),
+ *   crypt: Crypt.provider('default'),
+ *   hash: Hash.provider('default'),
+ *   rememberMeOptions: { maxRememberMeSeconds: 60 * 60 * 24 * 30, ...tokenStore }
+ * }))
+ *
+ * // Per-request usage
+ * const { id, cookie } = await Auth.login({ credentials, session, deviceContext })
+ * ```
+ */
+declare namespace Auth {
+    type AuthService<ProviderKey extends Auth.Provider.Key = 'default'> = Internal.AuthService<KeysWithFallback[ProviderKey]['Id'], KeysWithFallback[ProviderKey]['Credentials'], KeysWithFallback[ProviderKey]['DeviceContext']>;
+    type AnyAuthService = Internal.AuthService<any, any, any>;
+    type AuthServiceConfig<ProviderKey extends Auth.Provider.Key = 'default'> = Internal.AuthServiceConfig<KeysWithFallback[ProviderKey]['Id'], KeysWithFallback[ProviderKey]['Credentials'], KeysWithFallback[ProviderKey]['DeviceContext']>;
+    type Authenticatable<ProviderKey extends Auth.Provider.Key = 'default'> = Internal.Authenticatable<KeysWithFallback[ProviderKey]['Id']>;
+    type RememberMeToken = RememberMeTokenType;
+    type RememberMeTokenRecord<ProviderKey extends Auth.Provider.Key = 'default'> = Internal.RememberMeTokenRecord<KeysWithFallback[ProviderKey]['Id'], KeysWithFallback[ProviderKey]['DeviceContext']>;
+    type RememberMeOptions<ProviderKey extends Auth.Provider.Key = 'default'> = Internal.RememberMeOptions<KeysWithFallback[ProviderKey]['Id'], KeysWithFallback[ProviderKey]['DeviceContext']>;
+    namespace Internal {
+        interface Authenticatable<Id> {
+            id: Id;
+            credentialsInvalidBefore: Iso.Instant | null;
+        }
+        type AuthService<Id, Credentials, DeviceContext> = {
+            login(options: {
+                credentials: Credentials;
+                rememberMe?: boolean | undefined;
+                deviceContext: DeviceContext;
+                session: Session | Promise<Session>;
+            }): Promise<{
+                id: Id | null;
+                cookie: string | null;
+            }>;
+            loginById: (options: {
+                id: Id;
+                rememberMe?: boolean;
+                deviceContext: DeviceContext;
+                session: Promise<Session> | Session;
+            }) => Promise<{
+                id: Id | null;
+                cookie: string | null;
+            }>;
+            authenticate: (options: {
+                cookieHeader: string | null | undefined;
+                deviceContext: DeviceContext;
+                session: Promise<Session> | Session;
+            }) => Promise<{
+                id: Id | null;
+                cookie: string | null;
+            }>;
+            logout: (options: {
+                cookieHeader: string | null | undefined;
+                session: Promise<Session> | Session;
+            }) => Promise<{
+                cookie: string | null;
+                id: Id | null;
+            }>;
+            logoutOtherDevices({ deviceContext, session }: {
+                deviceContext: DeviceContext;
+                session: Session | Promise<Session>;
+            }): Promise<{
+                id: Id | null;
+                cookie: string | null;
+            }>;
+        };
+        interface AuthServiceConfig<Id, Credentials, DeviceContext> {
+            name: string;
+            getAuthenticatableById(id: Id): Promise<Authenticatable<Id> | null>;
+            verifyCredentials(credentials: Credentials): Promise<Internal.Authenticatable<Id> | null>;
+            updateCredentialsInvalidBefore(id: Id, date: Iso.Instant): Promise<void>;
+            /** Used only for hashing remember-me token verifiers. `Hash.drivers.sha256()` is sufficient. */
+            hash: Hash.HashService;
+            crypt: _maestro_js_crypt.Crypt.CryptService;
+            cookieSameSite?: 'Strict' | 'Lax';
+            rememberMeOptions?: RememberMeOptions<Id, DeviceContext>;
+        }
+        type RememberMeTokenRecord<Id, DeviceContext> = RememberMeTokenRecordType<Id, DeviceContext>;
+        type RememberMeOptions<Id, DeviceContext> = RememberMeOptionsType<Id, DeviceContext>;
+    }
+    namespace Provider {
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+
+export { Auth };

package/dist/index.js

@@ -0,0 +1,336 @@
+// src/index.ts
+import { ServiceRegistry } from "@maestro-js/service-registry";
+import { instantFns as instantFns2 } from "iso-fns2";
+
+// src/create-remember-me-provider.ts
+import { instantFns } from "iso-fns2";
+import crypto from "crypto";
+function createRememberMeProvider({
+  hash,
+  validateDeviceContext,
+  tokenReuseGracePeriodSeconds = 60,
+  ...db
+}) {
+  async function create2(options) {
+    const selector = crypto.randomBytes(16).toString("base64url");
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    const verifierHash = await hash.hash(verifier);
+    await db.create({
+      authenticatableId: options.id,
+      deviceContext: options.deviceContext,
+      expirationDate: options.expirationDate,
+      rotatedDate: null,
+      selector,
+      verifierHash
+    });
+    return { selector, verifier };
+  }
+  async function validate(options) {
+    const record = await db.getBySelector(options.token.selector);
+    return validateToken(options, record);
+  }
+  async function validateToken({ token, deviceContext }, record) {
+    if (!record) {
+      return null;
+    }
+    if (record.selector !== token.selector) {
+      return null;
+    }
+    if (record.expirationDate && record.expirationDate < instantFns.now()) {
+      return null;
+    }
+    if (record.rotatedDate && record.rotatedDate < instantFns.subtract(instantFns.now(), { seconds: tokenReuseGracePeriodSeconds })) {
+      await db.revokeByAuthenticatableId(record.authenticatableId);
+      return null;
+    }
+    if (!await hash.verify({ plaintext: token.verifier, hash: record.verifierHash })) {
+      return null;
+    }
+    if (validateDeviceContext && !await validateDeviceContext(record.deviceContext, deviceContext)) {
+      return null;
+    }
+    return record.authenticatableId;
+  }
+  async function rotate(previousSelector) {
+    const selector = crypto.randomBytes(16).toString("base64url");
+    const verifier = crypto.randomBytes(32).toString("base64url");
+    const verifierHash = await hash.hash(verifier);
+    await db.rotateBySelector(previousSelector, {
+      selector,
+      verifierHash
+    });
+    return { selector, verifier };
+  }
+  async function revoke(token) {
+    const record = await db.getBySelector(token.selector);
+    if (!record || record.selector !== token.selector || !await hash.verify({ plaintext: token.verifier, hash: record.verifierHash })) {
+      throw new Error("Failed to revoke");
+    }
+    await db.revokeBySelector(token.selector);
+  }
+  async function revokeAll(id) {
+    await db.revokeByAuthenticatableId(id);
+  }
+  return { create: create2, validate, rotate, revoke, revokeAll };
+}
+var notYetImplementedRememberMe = {
+  create: function(options) {
+    throw new Error("Function not implemented.");
+  },
+  validate: function(options) {
+    throw new Error("Function not implemented.");
+  },
+  rotate: function(selector) {
+    throw new Error("Function not implemented.");
+  },
+  revoke: function(token) {
+    throw new Error("Function not implemented.");
+  },
+  revokeAll: function(id) {
+    throw new Error("Function not implemented.");
+  }
+};
+
+// src/index.ts
+function create(config) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(config.name)) {
+    throw new Error(
+      `Authentication provider name must only contain alphanumeric characters, hyphens, and underscores. Got: "${config.name}"`
+    );
+  }
+  const hashService = config.hash;
+  const rememberMeProvider = config.rememberMeOptions ? createRememberMeProvider({ ...config.rememberMeOptions, hash: hashService }) : notYetImplementedRememberMe;
+  const REMEMBER_COOKIE_NAME = `_remember_${config.name}`;
+  const ID_SESSION_KEY = "_auth_id";
+  const AUTH_PROVIDER_NAME_SESSION_KEY = "_auth_provider_name";
+  const SESSION_CREATED_DATE_KEY = "_auth_session_created_date";
+  const NO_AUTH = { id: null, cookie: null };
+  async function privateLogin({
+    authenticatable,
+    rememberMe,
+    deviceContext,
+    session
+  }) {
+    session.set(ID_SESSION_KEY, authenticatable.id);
+    session.set(AUTH_PROVIDER_NAME_SESSION_KEY, config.name);
+    session.set(SESSION_CREATED_DATE_KEY, instantFns2.now());
+    session.regenerate();
+    let rememberMeCookieValue = null;
+    if (rememberMe && (config.rememberMeOptions?.maxRememberMeSeconds ?? 0) > 0) {
+      const token = await rememberMeProvider.create({
+        id: authenticatable.id,
+        expirationDate: instantFns2.add(instantFns2.now(), { seconds: config.rememberMeOptions?.maxRememberMeSeconds }),
+        deviceContext
+      });
+      rememberMeCookieValue = config.crypt.encryptString(encodeRememberMeToken(token));
+    }
+    return { id: authenticatable.id, cookie: getCookie({ rememberMeCookieValue }) };
+  }
+  async function login({
+    credentials,
+    rememberMe = false,
+    deviceContext,
+    session: sessionPromise
+  }) {
+    const session = await sessionPromise;
+    const authenticatable = await config.verifyCredentials(credentials);
+    if (!authenticatable) return NO_AUTH;
+    return privateLogin({ authenticatable, rememberMe, deviceContext, session });
+  }
+  async function loginById({
+    id,
+    rememberMe = false,
+    deviceContext,
+    session: sessionPromise
+  }) {
+    const session = await sessionPromise;
+    const authenticatable = await config.getAuthenticatableById(id);
+    if (authenticatable) {
+      return privateLogin({ authenticatable, rememberMe, deviceContext, session });
+    } else {
+      return NO_AUTH;
+    }
+  }
+  async function authenticate({
+    cookieHeader,
+    deviceContext,
+    session: sessionPromise
+  }) {
+    const session = await sessionPromise;
+    const authenticatableId = session.get(ID_SESSION_KEY);
+    const sessionAuthName = session.get(AUTH_PROVIDER_NAME_SESSION_KEY);
+    const sessionCreatedDate = session.get(SESSION_CREATED_DATE_KEY);
+    if (authenticatableId) {
+      if (sessionAuthName !== config.name) {
+        return NO_AUTH;
+      }
+      if (!sessionCreatedDate) {
+        return NO_AUTH;
+      }
+      const authenticatable = await config.getAuthenticatableById(authenticatableId);
+      if (!authenticatable) {
+        return NO_AUTH;
+      }
+      if (authenticatable.credentialsInvalidBefore && sessionCreatedDate <= authenticatable.credentialsInvalidBefore) {
+        return NO_AUTH;
+      }
+      return { id: authenticatableId, cookie: null };
+    } else {
+      const rememberMeToken = getRememberMeFromCookies(cookieHeader);
+      if (!rememberMeToken) {
+        return NO_AUTH;
+      }
+      const id = await rememberMeProvider.validate({ token: rememberMeToken, deviceContext });
+      if (!id) {
+        return NO_AUTH;
+      }
+      const authenticatable = await config.getAuthenticatableById(id);
+      if (!authenticatable) {
+        return NO_AUTH;
+      }
+      const newRememberMeToken = await rememberMeProvider.rotate(rememberMeToken.selector);
+      session.set(ID_SESSION_KEY, authenticatable.id);
+      session.set(AUTH_PROVIDER_NAME_SESSION_KEY, config.name);
+      session.set(SESSION_CREATED_DATE_KEY, instantFns2.now());
+      session.regenerate();
+      return {
+        id: authenticatable.id,
+        cookie: getCookie({
+          rememberMeCookieValue: config.crypt.encryptString(encodeRememberMeToken(newRememberMeToken))
+        })
+      };
+    }
+  }
+  function getRememberMeFromCookies(cookieHeader) {
+    const cookies = parseCookies(cookieHeader ?? "");
+    const rememberMeTokenEncoded = cookies[REMEMBER_COOKIE_NAME];
+    if (!rememberMeTokenEncoded) {
+      return null;
+    }
+    try {
+      const rememberMeToken = decodeRememberMeToken(config.crypt.decryptString(rememberMeTokenEncoded));
+      return rememberMeToken;
+    } catch {
+      return null;
+    }
+  }
+  async function logout({
+    cookieHeader,
+    session: sessionPromise
+  }) {
+    const session = await sessionPromise;
+    session.invalidate();
+    const rememberMeToken = getRememberMeFromCookies(cookieHeader);
+    if (rememberMeToken) {
+      try {
+        await rememberMeProvider.revoke(rememberMeToken);
+      } catch {
+      }
+    }
+    return { cookie: getCookie({ rememberMeCookieValue: null }), id: null };
+  }
+  async function logoutOtherDevices({
+    deviceContext,
+    session: sessionPromise
+  }) {
+    const session = await sessionPromise;
+    const authenticatableId = session.get(ID_SESSION_KEY);
+    if (!authenticatableId) return NO_AUTH;
+    const now = instantFns2.now();
+    await config.updateCredentialsInvalidBefore(authenticatableId, now);
+    await rememberMeProvider.revokeAll(authenticatableId);
+    return privateLogin({
+      authenticatable: { id: authenticatableId, credentialsInvalidBefore: now },
+      rememberMe: false,
+      deviceContext,
+      session
+    });
+  }
+  function getCookie({ rememberMeCookieValue }) {
+    if (rememberMeCookieValue) {
+      return buildSetCookieHeader({
+        name: REMEMBER_COOKIE_NAME,
+        value: rememberMeCookieValue,
+        sameSite: config.cookieSameSite ?? "Strict",
+        maxAge: config.rememberMeOptions?.maxRememberMeSeconds ?? 0
+      });
+    } else {
+      return buildSetCookieHeader({
+        name: REMEMBER_COOKIE_NAME,
+        value: "",
+        sameSite: config.cookieSameSite ?? "Strict",
+        maxAge: 0
+      });
+    }
+  }
+  return {
+    login,
+    loginById,
+    authenticate,
+    logout,
+    logoutOtherDevices
+  };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    login: service.login,
+    loginById: service.loginById,
+    authenticate: service.authenticate,
+    logout: service.logout,
+    logoutOtherDevices: service.logoutOtherDevices
+  };
+}
+var AuthBase = {
+  Provider,
+  provider
+};
+var Auth = {
+  ...AuthBase,
+  ...provider("default")
+};
+function encodeRememberMeToken(token) {
+  return `${token.selector}|${token.verifier}`;
+}
+function decodeRememberMeToken(token) {
+  const [selector, verifier] = token.split("|");
+  if (!selector || !verifier) {
+    return null;
+  }
+  return { selector, verifier };
+}
+function buildSetCookieHeader(options) {
+  const parts = [`${options.name}=${encodeURIComponent(options.value)}`];
+  parts.push(`Path=/`);
+  if (options.maxAge !== void 0) parts.push(`Max-Age=${options.maxAge}`);
+  parts.push("HttpOnly");
+  parts.push("Secure");
+  parts.push(`SameSite=${options.sameSite}`);
+  return parts.join("; ");
+}
+function parseCookies(cookieHeader) {
+  const cookies = {};
+  for (const pair of cookieHeader.split(";")) {
+    const index = pair.indexOf("=");
+    if (index === -1) continue;
+    const name = pair.slice(0, index).trim();
+    const value = pair.slice(index + 1).trim();
+    if (name) {
+      try {
+        cookies[name] = decodeURIComponent(value);
+      } catch {
+      }
+    }
+  }
+  return cookies;
+}
+export {
+  Auth
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@maestro-js/auth",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "@maestro-js/service-registry": "1.0.0-alpha.0",
+    "@maestro-js/session": "1.0.0-alpha.0",
+    "@maestro-js/crypt": "1.0.0-alpha.0",
+    "@maestro-js/hash": "1.0.0-alpha.0",
+    "@maestro-js/custom-errors": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}