@veap/auth 0.0.0-stage → 0.1.1

package/dist/common/logic.js

@@ -0,0 +1,133 @@
+import { augmentSession, augmentUser, registerIdentityAugmenter, registerPasswordResetSessionAugmenter, registerSessionAugmenter, unregisterIdentityAugmenter, unregisterPasswordResetSessionAugmenter, unregisterSessionAugmenter, } from "./augment.js";
+import { authContext, isAuthContextBound } from "./context.js";
+import { AuthCallbackRegistry } from "./registry.js";
+const globalForAuth = globalThis;
+export const authValidators = globalForAuth.__VEAP_AUTH_VALIDATORS__ ??
+    new AuthCallbackRegistry();
+export const securityRequirements = globalForAuth.__VEAP_SECURITY_REQUIREMENTS__ ??
+    new AuthCallbackRegistry();
+export const passwordResetValidators = globalForAuth.__VEAP_PASSWORD_RESET_VALIDATORS__ ??
+    new AuthCallbackRegistry();
+export const emailVerificationValidators = globalForAuth.__VEAP_EMAIL_VERIFICATION_VALIDATORS__ ??
+    new AuthCallbackRegistry();
+globalForAuth.__VEAP_AUTH_VALIDATORS__ = authValidators;
+globalForAuth.__VEAP_SECURITY_REQUIREMENTS__ = securityRequirements;
+globalForAuth.__VEAP_PASSWORD_RESET_VALIDATORS__ = passwordResetValidators;
+globalForAuth.__VEAP_EMAIL_VERIFICATION_VALIDATORS__ =
+    emailVerificationValidators;
+export function registerAuthValidator(idOrValidator, validator) {
+    authValidators.register(idOrValidator, validator);
+}
+export function unregisterAuthValidator(idOrValidator) {
+    return authValidators.unregister(idOrValidator);
+}
+export function registerPasswordResetValidator(idOrValidator, validator) {
+    passwordResetValidators.register(idOrValidator, validator);
+}
+export function unregisterPasswordResetValidator(idOrValidator) {
+    return passwordResetValidators.unregister(idOrValidator);
+}
+export function registerEmailVerificationValidator(idOrValidator, validator) {
+    emailVerificationValidators.register(idOrValidator, validator);
+}
+export function unregisterEmailVerificationValidator(idOrValidator) {
+    return emailVerificationValidators.unregister(idOrValidator);
+}
+export { augmentSession, augmentUser, registerIdentityAugmenter, registerPasswordResetSessionAugmenter, registerSessionAugmenter, unregisterIdentityAugmenter, unregisterPasswordResetSessionAugmenter, unregisterSessionAugmenter, };
+export function registerSecurityRequirement(idOrRequirement, requirement) {
+    securityRequirements.register(idOrRequirement, requirement);
+}
+export function unregisterSecurityRequirement(idOrRequirement) {
+    return securityRequirements.unregister(idOrRequirement);
+}
+export async function runPasswordResetValidators(userId) {
+    for (const validator of passwordResetValidators) {
+        const interception = await validator(userId);
+        if (interception)
+            return interception;
+    }
+    return null;
+}
+export async function runEmailVerificationValidators(userId) {
+    for (const validator of emailVerificationValidators) {
+        const interception = await validator(userId);
+        if (interception)
+            return interception;
+    }
+    return null;
+}
+/**
+ * Checks if the current session satisfies all registered security requirements.
+ */
+export async function checkSecurity(session, user, requiredRoles, requiredPermissions, fallbackRedirect, 
+/** Request path this check runs for; forwarded to modular requirements. */
+path) {
+    if (!user) {
+        console.warn("User is required for security check");
+        return { satisfied: false, redirect: fallbackRedirect ?? "/signin" };
+    }
+    const userRoles = Array.isArray(user.roles) ? user.roles : [];
+    const userPermissions = Array.isArray(user.permissions)
+        ? user.permissions
+        : [];
+    // 1. Core Role Check (At least one role must match)
+    if (requiredRoles && requiredRoles.length > 0) {
+        const hasRole = requiredRoles.some((role) => userRoles.includes(role));
+        if (!hasRole) {
+            console.warn(`User lacks required roles: ${requiredRoles.join(", ")}`);
+            return {
+                satisfied: false,
+                redirect: fallbackRedirect,
+            };
+        }
+    }
+    // 2. Core Permission Check (ALL permissions must match)
+    if (requiredPermissions && requiredPermissions.length > 0) {
+        const hasAllPermissions = requiredPermissions.every((perm) => userPermissions.includes(perm));
+        if (!hasAllPermissions) {
+            console.warn(`User lacks required permissions: ${requiredPermissions.join(", ")}`);
+            return {
+                satisfied: false,
+                redirect: fallbackRedirect,
+            };
+        }
+    }
+    // 3. Modular Requirements Check
+    if (securityRequirements) {
+        for (const requirement of securityRequirements) {
+            try {
+                const result = await requirement(session, user, path);
+                if (result && !result.satisfied) {
+                    return {
+                        ...result,
+                        redirect: result.redirect ?? fallbackRedirect,
+                    };
+                }
+            }
+            catch (error) {
+                console.error("[veap:security] Requirement failed:", error);
+            }
+        }
+    }
+    return { satisfied: true };
+}
+/**
+ * Performs full augmentation on a user by merging core RBAC roles/permissions
+ * and running all registered modular identity augmenters.
+ */
+export async function performFullUserAugmentation(user, session) {
+    let rbacData = {};
+    if (isAuthContextBound()) {
+        try {
+            const ctx = authContext();
+            if (ctx.rbac &&
+                typeof ctx.rbac.coreRbacAugmenter === "function") {
+                rbacData = await ctx.rbac.coreRbacAugmenter(user);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return await augmentUser(user, rbacData);
+}

package/dist/common/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Generic callback registry supporting both keyed (string ID) and anonymous registrations.
+ * Implements Iterable<T> so it can be looped directly in `for (const fn of registry)`.
+ * Also implements Set-like methods (.add, .delete, .has, .size) for backward compatibility.
+ */
+export declare class AuthCallbackRegistry<T extends Function> implements Iterable<T> {
+    private keyed;
+    private anonymous;
+    /**
+     * Registers a callback with an optional string ID.
+     * If registered with a string ID, re-registering with the same ID replaces the previous handler.
+     */
+    register(idOrHandler: string | T, maybeHandler?: T): void;
+    /**
+     * Unregisters a callback by its string ID or function reference.
+     * Returns true if an entry was removed, false otherwise.
+     */
+    unregister(idOrHandler: string | T): boolean;
+    /**
+     * Iterable implementation so `for (const fn of registry)` works seamlessly.
+     */
+    [Symbol.iterator](): Iterator<T>;
+    add(handler: T): this;
+    delete(idOrHandler: string | T): boolean;
+    has(idOrHandler: string | T): boolean;
+    clear(): void;
+    get size(): number;
+}

package/dist/common/registry.js

@@ -0,0 +1,76 @@
+/**
+ * Generic callback registry supporting both keyed (string ID) and anonymous registrations.
+ * Implements Iterable<T> so it can be looped directly in `for (const fn of registry)`.
+ * Also implements Set-like methods (.add, .delete, .has, .size) for backward compatibility.
+ */
+export class AuthCallbackRegistry {
+    keyed = new Map();
+    anonymous = new Set();
+    /**
+     * Registers a callback with an optional string ID.
+     * If registered with a string ID, re-registering with the same ID replaces the previous handler.
+     */
+    register(idOrHandler, maybeHandler) {
+        if (typeof idOrHandler === "string") {
+            if (!maybeHandler) {
+                throw new Error(`[AuthCallbackRegistry] A handler function must be provided when registering with ID "${idOrHandler}".`);
+            }
+            this.keyed.set(idOrHandler, maybeHandler);
+        }
+        else {
+            this.anonymous.add(idOrHandler);
+        }
+    }
+    /**
+     * Unregisters a callback by its string ID or function reference.
+     * Returns true if an entry was removed, false otherwise.
+     */
+    unregister(idOrHandler) {
+        if (typeof idOrHandler === "string") {
+            return this.keyed.delete(idOrHandler);
+        }
+        let removed = this.anonymous.delete(idOrHandler);
+        for (const [key, handler] of this.keyed.entries()) {
+            if (handler === idOrHandler) {
+                this.keyed.delete(key);
+                removed = true;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Iterable implementation so `for (const fn of registry)` works seamlessly.
+     */
+    *[Symbol.iterator]() {
+        yield* this.keyed.values();
+        yield* this.anonymous.values();
+    }
+    // Set-compatible interface for backward compatibility
+    add(handler) {
+        this.anonymous.add(handler);
+        return this;
+    }
+    delete(idOrHandler) {
+        return this.unregister(idOrHandler);
+    }
+    has(idOrHandler) {
+        if (typeof idOrHandler === "string") {
+            return this.keyed.has(idOrHandler);
+        }
+        if (this.anonymous.has(idOrHandler)) {
+            return true;
+        }
+        for (const handler of this.keyed.values()) {
+            if (handler === idOrHandler)
+                return true;
+        }
+        return false;
+    }
+    clear() {
+        this.keyed.clear();
+        this.anonymous.clear();
+    }
+    get size() {
+        return this.keyed.size + this.anonymous.size;
+    }
+}

package/dist/common/routes.d.ts

@@ -0,0 +1,3 @@
+export { AUTH_ROUTES, ROUTER_SERVICE } from "./tokens.js";
+export type { AuthConfig, AuthRoutesConfig } from "./types.js";
+export { DEFAULT_AUTH_ROUTES } from "./types.js";

package/dist/common/routes.js

@@ -0,0 +1,2 @@
+export { AUTH_ROUTES, ROUTER_SERVICE } from "./tokens.js";
+export { DEFAULT_AUTH_ROUTES } from "./types.js";

package/dist/common/tokens.d.ts

@@ -0,0 +1,10 @@
+import type { Token } from "@veap/kernel";
+import type { AuthRoutesConfig } from "./types.js";
+/**
+ * IoC Token for application authentication routes configuration.
+ */
+export declare const AUTH_ROUTES: Token<AuthRoutesConfig>;
+/**
+ * IoC Token for application router service (used for route rewrites).
+ */
+export declare const ROUTER_SERVICE: Token<any>;

package/dist/common/tokens.js

@@ -0,0 +1,8 @@
+/**
+ * IoC Token for application authentication routes configuration.
+ */
+export const AUTH_ROUTES = Symbol.for("veap:auth:routes");
+/**
+ * IoC Token for application router service (used for route rewrites).
+ */
+export const ROUTER_SERVICE = Symbol.for("veap:router:service");

package/dist/common/types.d.ts

@@ -0,0 +1,178 @@
+export type UserRole = "user" | "admin" | string;
+export type UserPermission = string;
+export interface User {
+    id: string;
+    email: string;
+    name: string;
+    password: string | null;
+    image: string | null;
+    recovery_code: any;
+    emailVerifiedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date | null;
+    [key: string]: any;
+}
+export interface Session {
+    id: string;
+    userId?: string;
+    user_id?: string;
+    metadata?: Record<string, any> | null;
+    expiresAt: Date;
+    expires_at?: Date;
+    createdAt?: Date;
+    created_at?: Date;
+    updatedAt?: Date | null;
+    updated_at?: Date | null;
+    [key: string]: any;
+}
+export interface PasswordResetSession {
+    id: string;
+    email: string;
+    code: string;
+    emailVerified?: boolean | null;
+    email_verified?: boolean | null;
+    userId: string;
+    user_id?: string;
+    expiresAt: Date;
+    expires_at?: Date;
+    createdAt?: Date;
+    created_at?: Date;
+    updatedAt?: Date | null;
+    updated_at?: Date | null;
+    [key: string]: any;
+}
+/**
+ * Represents a user with all potential extensions.
+ * Use this type in UI components that require data added by modules.
+ */
+export type FullUser = User & Record<string, any> & {
+    roles: UserRole[];
+    permissions: UserPermission[];
+};
+/**
+ * Basic session context.
+ */
+export interface AuthSession {
+    session: Session | null;
+    user: FullUser | null;
+}
+export interface SessionFlags {
+    [key: string]: any;
+}
+export type UserSession = {
+    id: string;
+    createdAt: Date;
+    expiresAt: Date;
+    isCurrent: boolean;
+    [key: string]: any;
+};
+export type AuthResponse = {
+    status: "SUCCESS";
+    session: Session;
+    user: FullUser;
+    redirect?: string;
+} | {
+    status: "CHALLENGE_REQUIRED";
+    type: string;
+    userId: string;
+    tempToken?: string;
+    redirect?: string;
+} | {
+    status: "ERROR";
+    message: string;
+    redirect?: string;
+};
+export interface PasswordResetAuthSession {
+    session: PasswordResetSession | null;
+    user: FullUser | null;
+}
+/**
+ * Configuration of public and private authentication route URLs.
+ */
+export interface AuthRoutesConfig {
+    /** Sign in / login page URL. Default: "/signin" */
+    signIn: string;
+    /** Sign up / registration page URL. Default: "/signup" */
+    signUp: string;
+    /** Forgot password page URL. Default: "/forgot-password" */
+    forgotPassword: string;
+    /** Reset password page URL. Default: "/reset-password" */
+    resetPassword: string;
+    /** Email verification page URL. Default: "/verify-email" */
+    verifyEmail: string;
+    /** Redirect target after successful login. Default: "/" */
+    afterLogin: string;
+    /** Redirect target after logout. Default: "/signin" */
+    afterLogout: string;
+}
+export declare const DEFAULT_AUTH_ROUTES: AuthRoutesConfig;
+export interface AuthConfig {
+    routes?: Partial<AuthRoutesConfig>;
+    /**
+     * Whether to automatically run auth database migrations during AuthServiceProvider.boot().
+     * Defaults to `true` when database connection is initialized.
+     */
+    autoMigrate?: boolean;
+}
+export type AuthEventPayloads = {
+    /**
+     * Emitted after password/base credentials are verified,
+     * but BEFORE the final session is created.
+     * Listeners can return a "veto" to require additional factors.
+     */
+    "system:auth:validate-factors": {
+        userId: string;
+        email: string;
+    };
+    /**
+     * Emitted after a full session is successfully created.
+     */
+    "system:auth:session-created": {
+        session: Session;
+        user: User;
+    };
+    "system:auth:login": {
+        session: Session;
+        user: User;
+    };
+    /**
+     * Emitted after a new user successfully signs up.
+     */
+    "system:auth:signup": {
+        session: Session;
+        user: User;
+    };
+    /**
+     * Emitted after a user signs out.
+     */
+    "system:auth:signed-out": {
+        user: User;
+    };
+    /**
+     * Emitted when a password reset is requested.
+     */
+    "system:auth:password-reset:requested": {
+        userId: string;
+        email: string;
+    };
+    /**
+     * Emitted when a password has been successfully reset.
+     */
+    "system:auth:password-reset:completed": {
+        userId: string;
+    };
+    /**
+     * Emitted when a verification email is sent.
+     */
+    "system:auth:verification-requested": {
+        userId: string;
+        email: string;
+    };
+    /**
+     * Emitted when a user successfully verifies their email.
+     */
+    "system:auth:email-verified": {
+        userId: string;
+        email: string;
+    };
+};

package/dist/common/types.js

@@ -0,0 +1,9 @@
+export const DEFAULT_AUTH_ROUTES = {
+    signIn: "/signin",
+    signUp: "/signup",
+    forgotPassword: "/forgot-password",
+    resetPassword: "/reset-password",
+    verifyEmail: "/verify-email",
+    afterLogin: "/",
+    afterLogout: "/signin",
+};

package/dist/crypto/aes-cipher.d.ts

@@ -0,0 +1,8 @@
+import type { ISecretCipher } from "./contracts.js";
+/**
+ * AES-GCM adapter for the ISecretCipher port.
+ */
+export declare class AesSecretCipher implements ISecretCipher {
+    encrypt(secret: string): Uint8Array;
+    decryptToString(data: Uint8Array): string;
+}

package/dist/crypto/aes-cipher.js

@@ -0,0 +1,12 @@
+import { decryptToString, encryptString } from "./encryption.js";
+/**
+ * AES-GCM adapter for the ISecretCipher port.
+ */
+export class AesSecretCipher {
+    encrypt(secret) {
+        return encryptString(secret);
+    }
+    decryptToString(data) {
+        return decryptToString(data);
+    }
+}

package/dist/crypto/bcrypt-hasher.d.ts

@@ -0,0 +1,12 @@
+import type { IPasswordHasher } from "./contracts.js";
+/**
+ * Bcrypt adapter for the IPasswordHasher port.
+ */
+export declare class BcryptPasswordHasher implements IPasswordHasher {
+    readonly rounds: number;
+    readonly minLength: number;
+    constructor(rounds?: number, minLength?: number);
+    hash(password: string): Promise<string>;
+    verify(hash: string, password: string): Promise<boolean>;
+    validateStrength(password: string): Promise<boolean>;
+}

package/dist/crypto/bcrypt-hasher.js

@@ -0,0 +1,37 @@
+import bcrypt from "bcryptjs";
+/**
+ * Bcrypt adapter for the IPasswordHasher port.
+ */
+export class BcryptPasswordHasher {
+    rounds;
+    minLength;
+    constructor(rounds, minLength) {
+        const envRounds = process.env.AUTH_BCRYPT_ROUNDS
+            ? Number(process.env.AUTH_BCRYPT_ROUNDS)
+            : NaN;
+        const resolvedRounds = rounds !== undefined ? Number(rounds) : envRounds;
+        this.rounds =
+            !Number.isNaN(resolvedRounds) &&
+                resolvedRounds >= 4 &&
+                resolvedRounds <= 31
+                ? Math.floor(resolvedRounds)
+                : 10;
+        const envMinLength = process.env.AUTH_PASSWORD_MIN_LENGTH
+            ? Number(process.env.AUTH_PASSWORD_MIN_LENGTH)
+            : NaN;
+        const resolvedMinLength = minLength !== undefined ? Number(minLength) : envMinLength;
+        this.minLength =
+            !Number.isNaN(resolvedMinLength) && resolvedMinLength >= 1
+                ? Math.floor(resolvedMinLength)
+                : 8;
+    }
+    async hash(password) {
+        return await bcrypt.hash(password, this.rounds);
+    }
+    async verify(hash, password) {
+        return await bcrypt.compare(password, hash);
+    }
+    async validateStrength(password) {
+        return password.length >= this.minLength && password.length <= 255;
+    }
+}

package/dist/crypto/contracts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Password hashing port.
+ */
+export interface IPasswordHasher {
+    /** Creates a secure hash of a plaintext password. */
+    hash(password: string): Promise<string>;
+    /** Verifies a plaintext password against a stored hash. */
+    verify(hash: string, password: string): Promise<boolean>;
+    /** Validates password complexity/length requirements. */
+    validateStrength(password: string): Promise<boolean>;
+}
+export declare const PASSWORD_HASHER: unique symbol;
+/**
+ * Secret-at-rest encryption port.
+ */
+export interface ISecretCipher {
+    /** Encrypts a secret string into storable bytes. */
+    encrypt(secret: string): Uint8Array;
+    /** Decrypts stored bytes back into the secret string. */
+    decryptToString(data: Uint8Array): string;
+}
+export declare const SECRET_CIPHER: unique symbol;
+/**
+ * Secret-token generation port.
+ */
+export interface ITokenGenerator {
+    /** Generates a random one-time code (default 6 characters, uppercase base32). */
+    generateOtp(length?: number): string;
+    /** Generates a random recovery code (uppercase base32). */
+    generateRecoveryCode(): string;
+    /** Generates a random session token (lowercase base32). */
+    generateSessionToken(): string;
+    /** Hashes a token for storage/lookup (deterministic, keyed by content). */
+    hashToken(token: string): string;
+}
+export declare const TOKEN_GENERATOR: unique symbol;

package/dist/crypto/contracts.js

@@ -0,0 +1,3 @@
+export const PASSWORD_HASHER = Symbol.for("veap:auth:password-hasher");
+export const SECRET_CIPHER = Symbol.for("veap:auth:secret-cipher");
+export const TOKEN_GENERATOR = Symbol.for("veap:auth:token-generator");

package/dist/crypto/encryption.d.ts

@@ -0,0 +1,18 @@
+export declare function getEncryptionKey(): Uint8Array;
+export declare function getAlgorithm(key: Uint8Array): string;
+/**
+ * Encrypts data using AES-GCM.
+ */
+export declare function encrypt(data: Uint8Array): Uint8Array;
+/**
+ * Encrypts a string.
+ */
+export declare function encryptString(data: string): Uint8Array;
+/**
+ * Decrypts data using AES-GCM.
+ */
+export declare function decrypt(encrypted: Uint8Array): Uint8Array;
+/**
+ * Decrypts data to a string.
+ */
+export declare function decryptToString(data: Uint8Array): string;

package/dist/crypto/encryption.js

@@ -0,0 +1,69 @@
+import { createCipheriv, createDecipheriv } from "node:crypto";
+import { DynamicBuffer } from "@oslojs/binary";
+import { decodeBase64 } from "@oslojs/encoding";
+export function getEncryptionKey() {
+    const envKey = process.env.ENCRYPTION_KEY;
+    if (!envKey) {
+        throw new Error("ENCRYPTION_KEY environment variable is not set. Generate one with: openssl rand -base64 16");
+    }
+    const key = decodeBase64(envKey);
+    if (key.length !== 16 && key.length !== 24 && key.length !== 32) {
+        throw new Error(`ENCRYPTION_KEY must decode to 16, 24 or 32 bytes (got ${key.length}). ` +
+            "Provide a base64-encoded key, e.g. from: openssl rand -base64 16");
+    }
+    return key;
+}
+export function getAlgorithm(key) {
+    return key.length === 16
+        ? "aes-128-gcm"
+        : key.length === 24
+            ? "aes-192-gcm"
+            : "aes-256-gcm";
+}
+// Configuration contract: validate key on module load
+getEncryptionKey();
+/**
+ * Encrypts data using AES-GCM.
+ */
+export function encrypt(data) {
+    const key = getEncryptionKey();
+    const iv = new Uint8Array(16);
+    crypto.getRandomValues(iv);
+    const cipher = createCipheriv(getAlgorithm(key), key, iv);
+    const encrypted = new DynamicBuffer(0);
+    encrypted.write(iv);
+    encrypted.write(cipher.update(data));
+    encrypted.write(cipher.final());
+    encrypted.write(cipher.getAuthTag());
+    return encrypted.bytes();
+}
+/**
+ * Encrypts a string.
+ */
+export function encryptString(data) {
+    return encrypt(new TextEncoder().encode(data));
+}
+/**
+ * Decrypts data using AES-GCM.
+ */
+export function decrypt(encrypted) {
+    if (encrypted.byteLength < 33) {
+        throw new Error("Invalid encrypted data length");
+    }
+    const key = getEncryptionKey();
+    const iv = encrypted.slice(0, 16);
+    const authTag = encrypted.slice(encrypted.byteLength - 16);
+    const content = encrypted.slice(16, encrypted.byteLength - 16);
+    const decipher = createDecipheriv(getAlgorithm(key), key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = new DynamicBuffer(0);
+    decrypted.write(decipher.update(content));
+    decrypted.write(decipher.final());
+    return decrypted.bytes();
+}
+/**
+ * Decrypts data to a string.
+ */
+export function decryptToString(data) {
+    return new TextDecoder().decode(decrypt(data));
+}

package/dist/crypto/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./aes-cipher.js";
+export * from "./bcrypt-hasher.js";
+export * from "./contracts.js";
+export * from "./encryption.js";
+export * from "./password.js";
+export * from "./token-generator.js";

package/dist/crypto/index.js

@@ -0,0 +1,6 @@
+export * from "./aes-cipher.js";
+export * from "./bcrypt-hasher.js";
+export * from "./contracts.js";
+export * from "./encryption.js";
+export * from "./password.js";
+export * from "./token-generator.js";