@starklabs/forge 1.3.25-builtin-configs.0 → 2.0.0

package/dist/auth/AuthService.js

@@ -0,0 +1,119 @@
+import { ConflictError, ErrorCode, UnauthorizedError } from "../errors/index.js";
+import { omitKeys } from "../utils/sanitizeInput.js";
+import { AppError } from "../errors/index.js";
+/** The authentication use cases. Knows nothing about HTTP responses. */
+export class AuthService {
+    config;
+    data;
+    userModel;
+    hasher;
+    sessions;
+    otp;
+    completer;
+    constructor(config, data, userModel, hasher, sessions, otp, completer) {
+        this.config = config;
+        this.data = data;
+        this.userModel = userModel;
+        this.hasher = hasher;
+        this.sessions = sessions;
+        this.otp = otp;
+        this.completer = completer;
+    }
+    get users() {
+        return this.data.repository(this.userModel);
+    }
+    get fields() {
+        return this.config.auth.fields;
+    }
+    async signup(body, mode, req) {
+        const email = this.emailOf(body);
+        if (await this.users.findOne({ [this.fields.email]: email })) {
+            throw new ConflictError({ message: "An account with this e-mail already exists.", code: ErrorCode.USER_ALREADY_EXISTS });
+        }
+        const data = await this.prepareNewUser(body);
+        if (mode === "credentials") {
+            const user = await this.users.create(data);
+            return { kind: "session", user, tokens: await this.sessions.start(user._id, req), created: true };
+        }
+        await this.otp.issue({ email, purpose: "signup", payload: data, userName: this.nameOf(body) });
+        return { kind: "code-sent" };
+    }
+    async login(body, mode, req) {
+        const user = await this.checkCredentials(this.emailOf(body), String(body[this.fields.password] ?? ""));
+        if (mode === "credentials")
+            return this.completer.complete(user, req);
+        await this.otp.issue({ email: this.emailOf(body), purpose: "login", userName: this.nameOf(user) });
+        return { kind: "code-sent" };
+    }
+    async verifyOtp(email, purpose, code, req) {
+        const { record, resetToken } = await this.otp.verify(email, purpose, code);
+        if (purpose === "password_reset")
+            return { kind: "reset-token", resetToken: resetToken };
+        if (purpose === "signup") {
+            const payload = (record.payload ?? {});
+            const user = await this.users.create(payload);
+            return { kind: "session", user, tokens: await this.sessions.start(user._id, req), created: true };
+        }
+        const user = await this.users.findOne({ [this.fields.email]: email.toLowerCase() });
+        if (!user)
+            throw new UnauthorizedError({ message: "Invalid credentials.", code: ErrorCode.INVALID_CREDENTIALS });
+        return this.completer.complete(user, req);
+    }
+    async resendOtp(email, purpose) {
+        await this.otp.resend(email, purpose);
+    }
+    /** Always succeeds from the caller's point of view, so it cannot be used to discover registered e-mails. */
+    async forgotPassword(email) {
+        const user = await this.users.findOne({ [this.fields.email]: email.toLowerCase() });
+        if (!user)
+            return;
+        try {
+            await this.otp.issue({ email, purpose: "password_reset", userName: this.nameOf(user) });
+        }
+        catch (error) {
+            const swallow = [ErrorCode.OTP_RESEND_COOLDOWN, ErrorCode.OTP_RESEND_LIMIT];
+            if (!(error instanceof AppError && swallow.includes(error.code)))
+                throw error;
+        }
+    }
+    async resetPassword(email, resetToken, newPassword) {
+        await this.otp.consumeResetToken(email, resetToken);
+        const user = await this.users.findOne({ [this.fields.email]: email.toLowerCase() });
+        if (!user) {
+            throw new UnauthorizedError({ message: "The reset link is invalid or has expired.", code: ErrorCode.RESET_TOKEN_INVALID });
+        }
+        await this.users.updateById(user._id, { [this.fields.password]: await this.hasher.hash(newPassword) });
+        await this.sessions.revokeAll(user._id);
+    }
+    /** Verifies e-mail + password with the same error and timing for "no such user" and "wrong password". */
+    async checkCredentials(email, password) {
+        const user = await this.users.findOne({ [this.fields.email]: email }, { withSecrets: [this.fields.password] });
+        const stored = user?.[this.fields.password];
+        if (!user || !stored) {
+            await this.hasher.verifyAgainstDummy(password);
+            throw this.invalidCredentials();
+        }
+        if (!(await this.hasher.verify(password, stored)))
+            throw this.invalidCredentials();
+        if (await this.hasher.needsRehash(stored)) {
+            await this.users.updateById(user._id, { [this.fields.password]: await this.hasher.hash(password) });
+        }
+        return user;
+    }
+    async prepareNewUser(body) {
+        // Roles and other privileged fields can never be chosen during sign-up.
+        const safe = omitKeys(body, this.config.protectedFields);
+        return { ...safe, [this.fields.password]: await this.hasher.hash(String(body[this.fields.password])) };
+    }
+    emailOf(body) {
+        return String(body[this.fields.email]).toLowerCase();
+    }
+    nameOf(source) {
+        const name = source.name ?? source.firstName ?? source.username;
+        return typeof name === "string" && name ? name : undefined;
+    }
+    invalidCredentials() {
+        return new UnauthorizedError({ message: "Invalid e-mail or password.", code: ErrorCode.INVALID_CREDENTIALS });
+    }
+}
+//# sourceMappingURL=AuthService.js.map

package/dist/auth/AuthService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthService.js","sourceRoot":"","sources":["../../src/auth/AuthService.ts"],"names":[],"mappings":"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"}

package/dist/auth/AuthServices.d.ts

@@ -0,0 +1,43 @@
+import type { Services } from "../core/Services.js";
+import { OAuthService } from "../oauth/OAuthService.js";
+import { AccountLinkPolicy } from "./AccountLinkPolicy.js";
+import { AuthService } from "./AuthService.js";
+import { LoginCompleter } from "./LoginCompleter.js";
+import { MagicLinkService } from "./MagicLinkService.js";
+import { MfaService } from "./MfaService.js";
+import { OtpService } from "./OtpService.js";
+import { UserProvisioner } from "./UserProvisioner.js";
+/**
+ * The auth object graph. Each service is built the first time it is needed (so features that are
+ * not configured cost nothing) and then shared. To add a sign-in method: write its service, add one
+ * lazy getter here, and end its flow in {@link LoginCompleter}.
+ */
+export declare class AuthServices {
+    private readonly s;
+    /** Fields of the user schema (read when first needed, after the collection was prepared). */
+    private readonly userFields;
+    private _linkPolicy;
+    private _provisioner;
+    private _mfa;
+    private _completer;
+    private _otp;
+    private _auth;
+    private _oauth;
+    private _magicLink;
+    constructor(s: Services, 
+    /** Fields of the user schema (read when first needed, after the collection was prepared). */
+    userFields: () => ReadonlySet<string>);
+    private get userModel();
+    private users;
+    get linkPolicy(): AccountLinkPolicy;
+    get provisioner(): UserProvisioner;
+    /** `undefined` when `auth.mfa` is not configured. */
+    get mfa(): MfaService | undefined;
+    requireMfa(): MfaService;
+    get completer(): LoginCompleter;
+    get otp(): OtpService;
+    get auth(): AuthService;
+    get oauth(): OAuthService;
+    get magicLink(): MagicLinkService;
+}
+//# sourceMappingURL=AuthServices.d.ts.map

package/dist/auth/AuthServices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthServices.d.ts","sourceRoot":"","sources":["../../src/auth/AuthServices.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD;;;;GAIG;AACH,qBAAa,YAAY;IAWrB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClB,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZ7B,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAA+B;IAEjD,YACmB,CAAC,EAAE,QAAQ;IAC5B,6FAA6F;IAC5E,UAAU,EAAE,MAAM,WAAW,CAAC,MAAM,CAAC,EACpD;IAEJ,OAAO,KAAK,SAAS,GAGpB;IAED,OAAO,CAAC,KAAK,CAA4D;IAEzE,IAAI,UAAU,IAAI,iBAAiB,CAElC;IAED,IAAI,WAAW,IAAI,eAAe,CAEjC;IAED,qDAAqD;IACrD,IAAI,GAAG,IAAI,UAAU,GAAG,SAAS,CAGhC;IAED,UAAU,IAAI,UAAU,CAIvB;IAED,IAAI,SAAS,IAAI,cAAc,CAE9B;IAED,IAAI,GAAG,IAAI,UAAU,CAEpB;IAED,IAAI,IAAI,IAAI,WAAW,CAEtB;IAED,IAAI,KAAK,IAAI,YAAY,CAOxB;IAED,IAAI,SAAS,IAAI,gBAAgB,CAOhC;CACF"}

package/dist/auth/AuthServices.js

@@ -0,0 +1,78 @@
+import { ConfigurationError } from "../errors/index.js";
+import { OAuthService } from "../oauth/OAuthService.js";
+import { AccountLinkPolicy } from "./AccountLinkPolicy.js";
+import { AuthService } from "./AuthService.js";
+import { LoginCompleter } from "./LoginCompleter.js";
+import { MagicLinkService } from "./MagicLinkService.js";
+import { MfaService } from "./MfaService.js";
+import { OtpService } from "./OtpService.js";
+import { UserProvisioner } from "./UserProvisioner.js";
+/**
+ * The auth object graph. Each service is built the first time it is needed (so features that are
+ * not configured cost nothing) and then shared. To add a sign-in method: write its service, add one
+ * lazy getter here, and end its flow in {@link LoginCompleter}.
+ */
+export class AuthServices {
+    s;
+    userFields;
+    _linkPolicy;
+    _provisioner;
+    _mfa;
+    _completer;
+    _otp;
+    _auth;
+    _oauth;
+    _magicLink;
+    constructor(s, 
+    /** Fields of the user schema (read when first needed, after the collection was prepared). */
+    userFields) {
+        this.s = s;
+        this.userFields = userFields;
+    }
+    get userModel() {
+        if (!this.s.userModel)
+            throw new ConfigurationError({ message: "Authentication needs a user model." });
+        return this.s.userModel;
+    }
+    users = () => this.s.data.repository(this.userModel);
+    get linkPolicy() {
+        return (this._linkPolicy ??= new AccountLinkPolicy(this.s.config));
+    }
+    get provisioner() {
+        return (this._provisioner ??= new UserProvisioner(this.s.config, this.users, this.s.hasher, this.userFields()));
+    }
+    /** `undefined` when `auth.mfa` is not configured. */
+    get mfa() {
+        if (!this.s.config.auth.mfa)
+            return undefined;
+        return (this._mfa ??= new MfaService(this.s.config, this.s.data, this.s.vault, this.s.tokens));
+    }
+    requireMfa() {
+        const mfa = this.mfa;
+        if (!mfa)
+            throw new ConfigurationError({ message: "Two-factor authentication is not configured.", hint: "Add auth.mfa to builtinConfig." });
+        return mfa;
+    }
+    get completer() {
+        return (this._completer ??= new LoginCompleter(this.s.config, this.s.sessions, this.s.tokens, () => this.mfa));
+    }
+    get otp() {
+        return (this._otp ??= new OtpService(this.s.config, this.s.data, this.s.emails, this.s.logger));
+    }
+    get auth() {
+        return (this._auth ??= new AuthService(this.s.config, this.s.data, this.userModel, this.s.hasher, this.s.sessions, this.otp, this.completer));
+    }
+    get oauth() {
+        if (!this.s.config.auth.oauth) {
+            throw new ConfigurationError({ message: "Social sign-in is not configured.", hint: "Add auth.oauth to builtinConfig." });
+        }
+        return (this._oauth ??= new OAuthService(this.s.config, this.s.data, this.userModel, this.provisioner, this.linkPolicy, this.s.oauth, this.s.tokens, this.s.sessions, this.s.logger));
+    }
+    get magicLink() {
+        if (!this.s.config.auth.magicLink) {
+            throw new ConfigurationError({ message: "Magic links are not configured.", hint: "Add auth.magicLink to builtinConfig." });
+        }
+        return (this._magicLink ??= new MagicLinkService(this.s.config, this.s.data, this.users, this.s.emails, this.provisioner, this.linkPolicy, this.completer, this.s.logger));
+    }
+}
+//# sourceMappingURL=AuthServices.js.map

package/dist/auth/AuthServices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthServices.js","sourceRoot":"","sources":["../../src/auth/AuthServices.ts"],"names":[],"mappings":"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"}

package/dist/auth/CookieWriter.d.ts

@@ -0,0 +1,26 @@
+import type { Response } from "express";
+import type { ForgeConfig } from "../config/ForgeConfig.js";
+import type { SessionTokens } from "./SessionService.js";
+export declare const OAUTH_STATE_COOKIE = "forge_oauth_state";
+export declare const MAGIC_BINDING_COOKIE = "forge_magic_binding";
+/** Sets and clears the HttpOnly session cookies with one consistent set of attributes. */
+export declare class CookieWriter {
+    private readonly config;
+    constructor(config: ForgeConfig);
+    private base;
+    set(res: Response, tokens: Partial<SessionTokens>): void;
+    /**
+     * Holds the signed OAuth state during the provider round-trip. Always `SameSite=Lax`: the provider
+     * sends the browser back with a top-level GET, which `Strict` would drop and `None` would over-share.
+     */
+    setOAuthState(res: Response, value: string, maxAgeMs: number): void;
+    /**
+     * Ties a magic link to the browser that requested it. Uses the configured session-cookie attributes (not forced to
+     * Lax) because the link is redeemed by a `fetch` from the front-end, which may be on another site.
+     */
+    setMagicBinding(res: Response, value: string, maxAgeMs: number): void;
+    clearMagicBinding(res: Response): void;
+    clearOAuthState(res: Response): void;
+    clear(res: Response): void;
+}
+//# sourceMappingURL=CookieWriter.d.ts.map

package/dist/auth/CookieWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CookieWriter.d.ts","sourceRoot":"","sources":["../../src/auth/CookieWriter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AACtD,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAE1D,0FAA0F;AAC1F,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,WAAW,EAAI;IAEpD,OAAO,CAAC,IAAI;IAWZ,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAQvD;IAED;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAElE;IAED;;;OAGG;IACH,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEpE;IAED,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAErC;IAED,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAEnC;IAED,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAGzB;CACF"}

package/dist/auth/CookieWriter.js

@@ -0,0 +1,53 @@
+export const OAUTH_STATE_COOKIE = "forge_oauth_state";
+export const MAGIC_BINDING_COOKIE = "forge_magic_binding";
+/** Sets and clears the HttpOnly session cookies with one consistent set of attributes. */
+export class CookieWriter {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    base() {
+        const { cookie } = this.config.auth;
+        return {
+            httpOnly: true,
+            secure: cookie.secure,
+            sameSite: cookie.sameSite,
+            path: cookie.path,
+            ...(cookie.domain ? { domain: cookie.domain } : {}),
+        };
+    }
+    set(res, tokens) {
+        const { auth } = this.config;
+        if (tokens.accessToken) {
+            res.cookie(auth.accessTokenName, tokens.accessToken, { ...this.base(), maxAge: auth.accessTokenAge.toMs() });
+        }
+        if (tokens.refreshToken) {
+            res.cookie(auth.refreshTokenName, tokens.refreshToken, { ...this.base(), maxAge: auth.refreshTokenAge.toMs() });
+        }
+    }
+    /**
+     * Holds the signed OAuth state during the provider round-trip. Always `SameSite=Lax`: the provider
+     * sends the browser back with a top-level GET, which `Strict` would drop and `None` would over-share.
+     */
+    setOAuthState(res, value, maxAgeMs) {
+        res.cookie(OAUTH_STATE_COOKIE, value, { ...this.base(), sameSite: "lax", maxAge: maxAgeMs });
+    }
+    /**
+     * Ties a magic link to the browser that requested it. Uses the configured session-cookie attributes (not forced to
+     * Lax) because the link is redeemed by a `fetch` from the front-end, which may be on another site.
+     */
+    setMagicBinding(res, value, maxAgeMs) {
+        res.cookie(MAGIC_BINDING_COOKIE, value, { ...this.base(), maxAge: maxAgeMs });
+    }
+    clearMagicBinding(res) {
+        res.clearCookie(MAGIC_BINDING_COOKIE, this.base());
+    }
+    clearOAuthState(res) {
+        res.clearCookie(OAUTH_STATE_COOKIE, { ...this.base(), sameSite: "lax" });
+    }
+    clear(res) {
+        res.clearCookie(this.config.auth.accessTokenName, this.base());
+        res.clearCookie(this.config.auth.refreshTokenName, this.base());
+    }
+}
+//# sourceMappingURL=CookieWriter.js.map

package/dist/auth/CookieWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CookieWriter.js","sourceRoot":"","sources":["../../src/auth/CookieWriter.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,0FAA0F;AAC1F,MAAM,OAAO,YAAY;IACM,MAAM;IAAnC,YAA6B,MAAmB;sBAAnB,MAAM;IAAgB,CAAC;IAE5C,IAAI;QACV,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QACpC,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3C,CAAC;IACb,CAAC;IAED,GAAG,CAAC,GAAa,EAAE,MAA8B;QAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAC7B,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC/G,CAAC;QACD,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAClH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,GAAa,EAAE,KAAa,EAAE,QAAgB;QAC1D,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC/F,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,GAAa,EAAE,KAAa,EAAE,QAAgB;QAC5D,GAAG,CAAC,MAAM,CAAC,oBAAoB,EAAE,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,iBAAiB,CAAC,GAAa;QAC7B,GAAG,CAAC,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,eAAe,CAAC,GAAa;QAC3B,GAAG,CAAC,WAAW,CAAC,kBAAkB,EAAE,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,GAAa;QACjB,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/D,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/auth/LoginCompleter.d.ts

@@ -0,0 +1,37 @@
+import type { Request } from "express";
+import type { ForgeConfig } from "../config/ForgeConfig.js";
+import type { Doc } from "../data/Repository.js";
+import type { TokenService } from "../security/TokenService.js";
+import type { MfaService } from "./MfaService.js";
+import type { SessionService, SessionTokens } from "./SessionService.js";
+export type LoginResult = {
+    kind: "session";
+    user: Doc;
+    tokens: SessionTokens;
+    created: boolean;
+}
+/** The first factor succeeded, but a second one is required before any session exists. */
+ | {
+    kind: "mfa-required";
+    mfaToken: string;
+};
+/**
+ * The single exit of every *first-factor* sign-in (password, e-mailed code, magic link).
+ *
+ * Whatever proved who the user is, this decides whether a session starts now or a second factor
+ * (authenticator code) comes first. Because all methods end here, a new sign-in method cannot forget
+ * the second-factor check. (Social sign-in relies on the provider's own protections and does not pass here.)
+ */
+export declare class LoginCompleter {
+    private readonly config;
+    private readonly sessions;
+    private readonly tokens;
+    private readonly mfa;
+    constructor(config: ForgeConfig, sessions: SessionService, tokens: TokenService, mfa: () => MfaService | undefined);
+    complete(user: Doc, req: Request, options?: {
+        created?: boolean;
+    }): Promise<LoginResult>;
+    /** Starts a session unconditionally. Only call it after every required factor was checked. */
+    startSession(user: Doc, req: Request, created?: boolean): Promise<LoginResult>;
+}
+//# sourceMappingURL=LoginCompleter.d.ts.map

package/dist/auth/LoginCompleter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoginCompleter.d.ts","sourceRoot":"","sources":["../../src/auth/LoginCompleter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE;AACzE,0FAA0F;GACxF;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C;;;;;;GAMG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAJtB,YACmB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,MAAM,UAAU,GAAG,SAAS,EAChD;IAEE,QAAQ,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAOjG;IAED,8FAA8F;IACxF,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC,WAAW,CAAC,CAEjF;CACF"}

package/dist/auth/LoginCompleter.js

@@ -0,0 +1,32 @@
+/**
+ * The single exit of every *first-factor* sign-in (password, e-mailed code, magic link).
+ *
+ * Whatever proved who the user is, this decides whether a session starts now or a second factor
+ * (authenticator code) comes first. Because all methods end here, a new sign-in method cannot forget
+ * the second-factor check. (Social sign-in relies on the provider's own protections and does not pass here.)
+ */
+export class LoginCompleter {
+    config;
+    sessions;
+    tokens;
+    mfa;
+    constructor(config, sessions, tokens, mfa) {
+        this.config = config;
+        this.sessions = sessions;
+        this.tokens = tokens;
+        this.mfa = mfa;
+    }
+    async complete(user, req, options = {}) {
+        const settings = this.config.auth.mfa;
+        // A brand-new account cannot have a second factor yet.
+        if (settings && !options.created && (await this.mfa()?.isEnabled(user._id))) {
+            return { kind: "mfa-required", mfaToken: this.tokens.signMfaChallenge(user._id, settings.challengeAge) };
+        }
+        return this.startSession(user, req, options.created ?? false);
+    }
+    /** Starts a session unconditionally. Only call it after every required factor was checked. */
+    async startSession(user, req, created = false) {
+        return { kind: "session", user, tokens: await this.sessions.start(user._id, req), created };
+    }
+}
+//# sourceMappingURL=LoginCompleter.js.map

package/dist/auth/LoginCompleter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoginCompleter.js","sourceRoot":"","sources":["../../src/auth/LoginCompleter.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAEN,MAAM;IACN,QAAQ;IACR,MAAM;IACN,GAAG;IAJtB,YACmB,MAAmB,EACnB,QAAwB,EACxB,MAAoB,EACpB,GAAiC;sBAHjC,MAAM;wBACN,QAAQ;sBACR,MAAM;mBACN,GAAG;IACnB,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,IAAS,EAAE,GAAY,EAAE,OAAO,GAA0B,EAAE;QACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QACtC,uDAAuD;QACvD,IAAI,QAAQ,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC5E,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3G,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC;IAChE,CAAC;IAED,8FAA8F;IAC9F,KAAK,CAAC,YAAY,CAAC,IAAS,EAAE,GAAY,EAAE,OAAO,GAAG,KAAK;QACzD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;IAC9F,CAAC;CACF"}

package/dist/auth/MagicLinkController.d.ts

@@ -0,0 +1,16 @@
+import type { Request, Response } from "express";
+import type { RouteContext } from "../core/RouteContext.js";
+import type { Services } from "../core/Services.js";
+import type { MagicLinkService } from "./MagicLinkService.js";
+/** HTTP adapter for {@link MagicLinkService}. */
+export declare class MagicLinkController {
+    private readonly services;
+    private readonly magic;
+    constructor(services: Services, magic: () => MagicLinkService);
+    private get settings();
+    /** `POST /auth/magic-link` `{ email, name? }` - always the same answer. */
+    magicLinkRequest: (req: Request, res: Response, ctx: RouteContext) => Promise<void>;
+    /** `POST /auth/magic-link/verify` `{ token }` - called by the front-end page the link opens. */
+    magicLinkVerify: (req: Request, res: Response, ctx: RouteContext) => Promise<void>;
+}
+//# sourceMappingURL=MagicLinkController.d.ts.map

package/dist/auth/MagicLinkController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MagicLinkController.d.ts","sourceRoot":"","sources":["../../src/auth/MagicLinkController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAK9D,iDAAiD;AACjD,qBAAa,mBAAmB;IAE5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFxB,YACmB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,gBAAgB,EAC5C;IAEJ,OAAO,KAAK,QAAQ,GAEnB;IAED,2EAA2E;IAC3E,gBAAgB,QAAe,OAAO,OAAO,QAAQ,OAAO,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CActF;IAEF,gGAAgG;IAChG,eAAe,QAAe,OAAO,OAAO,QAAQ,OAAO,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CASrF;CACH"}

package/dist/auth/MagicLinkController.js

@@ -0,0 +1,41 @@
+import { randomToken } from "../security/TokenService.js";
+import { MAGIC_BINDING_COOKIE } from "./CookieWriter.js";
+/** What a binding we issued looks like: anything else is ignored rather than trusted. */
+const BINDING_SHAPE = /^[A-Za-z0-9_-]{16,64}$/;
+/** HTTP adapter for {@link MagicLinkService}. */
+export class MagicLinkController {
+    services;
+    magic;
+    constructor(services, magic) {
+        this.services = services;
+        this.magic = magic;
+    }
+    get settings() {
+        return this.services.config.auth.magicLink;
+    }
+    /** `POST /auth/magic-link` `{ email, name? }` - always the same answer. */
+    magicLinkRequest = async (req, res, ctx) => {
+        const body = ctx.parseBody(req.body);
+        const email = String(body[this.services.config.auth.fields.email]);
+        // The binding is a per-browser secret: keep the one this browser already has, so asking again ("resend")
+        // does not invalidate the link that is already in the inbox. Always (re)set it - even when nothing is sent -
+        // so the response never reveals whether an e-mail went out.
+        const cookies = req.cookies;
+        const existing = cookies?.[MAGIC_BINDING_COOKIE];
+        const binding = typeof existing === "string" && BINDING_SHAPE.test(existing) ? existing : randomToken(16);
+        this.services.cookies.setMagicBinding(res, binding, this.settings.expiresIn.toMs());
+        await this.magic().request(email, { name: typeof body.name === "string" ? body.name : undefined, binding });
+        this.services.responses.success(res, { message: "If this address can sign in, a link is on its way." });
+    };
+    /** `POST /auth/magic-link/verify` `{ token }` - called by the front-end page the link opens. */
+    magicLinkVerify = async (req, res, ctx) => {
+        const body = ctx.parseBody(req.body);
+        const cookies = req.cookies;
+        const binding = cookies?.[MAGIC_BINDING_COOKIE];
+        res.setHeader("Cache-Control", "no-store");
+        const result = await this.magic().verify(String(body.token), typeof binding === "string" ? binding : undefined, req);
+        this.services.cookies.clearMagicBinding(res);
+        this.services.sessionResponder.sendLogin(res, result, { message: "Signed in successfully.", hiddenFields: ctx.route.config?.hiddenFields });
+    };
+}
+//# sourceMappingURL=MagicLinkController.js.map

package/dist/auth/MagicLinkController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MagicLinkController.js","sourceRoot":"","sources":["../../src/auth/MagicLinkController.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAGzD,yFAAyF;AACzF,MAAM,aAAa,GAAG,wBAAwB,CAAC;AAE/C,iDAAiD;AACjD,MAAM,OAAO,mBAAmB;IAEX,QAAQ;IACR,KAAK;IAFxB,YACmB,QAAkB,EAClB,KAA6B;wBAD7B,QAAQ;qBACR,KAAK;IACrB,CAAC;IAEJ,IAAY,QAAQ;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,SAAU,CAAC;IAC9C,CAAC;IAED,2EAA2E;IAC3E,gBAAgB,GAAG,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,GAAiB,EAAiB,EAAE;QACzF,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAEnE,yGAAyG;QACzG,6GAA6G;QAC7G,4DAA4D;QAC5D,MAAM,OAAO,GAAG,GAAG,CAAC,OAA8C,CAAC;QACnE,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC,oBAAoB,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC1G,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QAEpF,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,oDAAoD,EAAE,CAAC,CAAC;IAC1G,CAAC,CAAC;IAEF,gGAAgG;IAChG,eAAe,GAAG,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,GAAiB,EAAiB,EAAE;QACxF,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,GAAG,CAAC,OAA8C,CAAC;QACnE,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC,oBAAoB,CAAC,CAAC;QAEhD,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACrH,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,yBAAyB,EAAE,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAC9I,CAAC,CAAC;CACH"}

package/dist/auth/MagicLinkService.d.ts

@@ -0,0 +1,45 @@
+import type { Request } from "express";
+import type { ForgeConfig } from "../config/ForgeConfig.js";
+import type { DataSource, Repository } from "../data/Repository.js";
+import type { EmailService } from "../email/EmailService.js";
+import type { Logger } from "../utils/Logger.js";
+import type { AccountLinkPolicy } from "./AccountLinkPolicy.js";
+import type { LoginCompleter, LoginResult } from "./LoginCompleter.js";
+import type { UserProvisioner } from "./UserProvisioner.js";
+/**
+ * Passwordless sign-in: an e-mailed, single-use link.
+ *
+ * Design choices that matter:
+ * - Requesting a link *always* looks the same to the caller, so it cannot be used to find out which e-mails have accounts.
+ * - The link opens a front-end page, which then `POST`s the token. Mail scanners follow links with GET; if a GET could
+ *   sign someone in (or burn the token), scanners would break the feature and could even use the link.
+ * - Only a hash of the token is stored; it is 256 bits of randomness, so it cannot be guessed.
+ * - The link is bound to the browser that asked for it (cookie), so an attacker cannot mail *their own* link to a victim
+ *   and silently sign them in to the attacker's account (login CSRF).
+ * - Using it deletes it first: of two simultaneous attempts exactly one wins.
+ */
+export declare class MagicLinkService {
+    private readonly config;
+    private readonly data;
+    private readonly users;
+    private readonly emails;
+    private readonly provisioner;
+    private readonly linkPolicy;
+    private readonly completer;
+    private readonly logger;
+    constructor(config: ForgeConfig, data: DataSource, users: () => Repository, emails: EmailService, provisioner: UserProvisioner, linkPolicy: AccountLinkPolicy, completer: LoginCompleter, logger: Logger);
+    private get settings();
+    private get links();
+    /**
+     * Sends a link if the address may sign in. Never reveals whether it did: the caller should answer 200 either way,
+     * and mail-provider failures are logged, not reported (a failure only for real accounts would reveal them).
+     */
+    request(rawEmail: string, options: {
+        name?: string | undefined;
+        binding: string;
+    }): Promise<void>;
+    /** Redeems a link. Expired, used and unknown links are indistinguishable on purpose. */
+    verify(token: string, binding: string | undefined, req: Request): Promise<LoginResult>;
+    private invalid;
+}
+//# sourceMappingURL=MagicLinkService.d.ts.map

package/dist/auth/MagicLinkService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MagicLinkService.d.ts","sourceRoot":"","sources":["../../src/auth/MagicLinkService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,0BAA0B,CAAC;AAGrF,OAAO,KAAK,EAAE,UAAU,EAAO,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,YACmB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,UAAU,EACvB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,eAAe,EAC5B,UAAU,EAAE,iBAAiB,EAC7B,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,MAAM,EAC7B;IAEJ,OAAO,KAAK,QAAQ,GAEnB;IAED,OAAO,KAAK,KAAK,GAEhB;IAED;;;OAGG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDtG;IAED,wFAAwF;IAClF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CA4B3F;IAED,OAAO,CAAC,OAAO;CAGhB"}