@webda/auth 0.0.0-stage → 4.0.0-beta.11

package/lib/compat/upgrade.js

@@ -0,0 +1,200 @@
+import { Ident } from "@webda/core";
+import { IdentConflict } from "../errors.js";
+/**
+ * v3 ident records
+ *
+ * v3 stored idents under `"<providerUid>_<provider>"` (plain JSON, `__type: "Webda/Ident"`, `uuid` kept in the
+ * body). The core `Ident` repository addresses and queries them through `Ident.parseLegacyUID` (a model-level
+ * legacy key hook): they load as `Ident` instances without `providerUid`, recognised by `ident.getLegacyUID()`.
+ * Nothing else may use such an instance: it must go through {@link upgradeIdent} first.
+ */
+/**
+ * @param providerUid - uid on the provider
+ * @param provider - provider name
+ * @returns the v3 key `"<providerUid>_<provider>"`
+ */
+export function legacyKey(providerUid, provider) {
+    return `${providerUid}_${provider}`;
+}
+/**
+ * Split a v3 key on its LAST "_" (provider names never contain "_", emails may)
+ * @param uuid - v3 key
+ * @returns the parts, or undefined when not a v3 key
+ */
+export function splitLegacyKey(uuid) {
+    return Ident.parseLegacyUID(uuid);
+}
+/**
+ * @param value - a v3 date (ISO string, timestamp or Date)
+ * @returns the date, undefined when absent or unreadable
+ */
+function toDate(value) {
+    if (value === undefined || value === null || value === "" || value === false) {
+        return undefined;
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    return isNaN(date.getTime()) ? undefined : date;
+}
+/**
+ * @param value - a v3 timestamp (number, ISO string or Date)
+ * @returns the timestamp in ms, undefined when absent or unreadable
+ */
+function toTimestamp(value) {
+    if (typeof value === "number") {
+        return value || undefined;
+    }
+    return toDate(value)?.getTime();
+}
+/**
+ * Whether a row loaded under a v3 key really is a v3 ident of this application
+ *
+ * The row must be an instance of the ident model, carry a v3 key and be stored untyped, as `Webda/Ident`, or as
+ * the ident model, one of its ancestors or transitive subclasses: a v3-looking key of a shared store may hold
+ * another model's row.
+ * @param row - the loaded row
+ * @param IdentModel - ident model of the application
+ * @returns true for a v3 ident
+ */
+export function isLegacyIdent(row, IdentModel = Ident) {
+    if (!(row instanceof IdentModel) || !row.getLegacyUID()) {
+        return false;
+    }
+    const type = row.__type;
+    return type === undefined || identIdentifiers(IdentModel).has(type) || rowClassIdentifiers(row).has(type);
+}
+/**
+ * Identifiers of the class a row loaded as and of its ancestors: a subclass of the ident model defined by another
+ * package (e.g. an application `MyApp/Ident`) is not listed in the ident model `Metadata.Subclasses`, yet a row
+ * typed as it loads as it
+ * @param row - the loaded row, an instance of the ident model
+ * @returns the identifiers
+ */
+function rowClassIdentifiers(row) {
+    const ids = new Set();
+    for (let clazz = row?.constructor; clazz && clazz !== Function.prototype; clazz = Object.getPrototypeOf(clazz)) {
+        if (clazz.Metadata?.Identifier)
+            ids.add(clazz.Metadata.Identifier);
+    }
+    return ids;
+}
+/**
+ * Identifiers a v3 ident row of this ident model may be stored as: `Webda/Ident`, the model, its ancestors and
+ * its transitive subclasses
+ * @param IdentModel - ident model of the application
+ * @returns the identifiers
+ */
+function identIdentifiers(IdentModel) {
+    const ids = new Set(["Webda/Ident"]);
+    for (let parent = Object.getPrototypeOf(IdentModel); parent && parent !== Function.prototype;) {
+        if (parent.Metadata?.Identifier)
+            ids.add(parent.Metadata.Identifier);
+        parent = Object.getPrototypeOf(parent);
+    }
+    const queue = [IdentModel];
+    const seen = new Set();
+    while (queue.length) {
+        const clazz = queue.shift();
+        if (!clazz || seen.has(clazz))
+            continue;
+        seen.add(clazz);
+        if (clazz.Metadata?.Identifier)
+            ids.add(clazz.Metadata.Identifier);
+        queue.push(...(clazz.Metadata?.Subclasses ?? []));
+    }
+    return ids;
+}
+/**
+ * Upgrade a v3 ident: create the `"<providerUid>:<provider>"` record, then delete the v3 one
+ *
+ * Idempotent and crash-safe: when the new record already exists (an earlier upgrade stopped before the delete,
+ * or a concurrent one won) it is kept as is and only the v3 record is deleted. Field map: `_user` → owner,
+ * `_validation` → `verifiedAt`, `_lastUsed` → `lastUsedAt`, `_failedLogin` → `_loginAttempts`,
+ * `_lastFailedLogin` → `_lastLoginAttemptAt` (number or date; absent, the count is treated as an expired lock),
+ * `_lastValidationEmail` → `_throttle.lastSentAt`; `email`, `__profile` are kept, `__tokens` is encrypted into `tokens`; provider is
+ * `provider ?? _type ?? key suffix`, providerUid the key prefix (normalised for the email provider: v3 kept the
+ * email case). Callers run it as system.
+ * @throws Error when `legacy` is not a v3 ident (see {@link isLegacyIdent})
+ * @throws IdentConflict when the upgraded key exists, or is created concurrently, with another owner: the v3
+ * record is kept for a manual resolution
+ * @param legacy - a v3 ident (`legacy.getLegacyUID()` is set)
+ * @param IdentModel - ident model of the application
+ * @param options - options
+ * @param options.dryRun - run the checks only: nothing is written, the returned ident is not saved
+ * @returns the upgraded ident
+ */
+export async function upgradeIdent(legacy, IdentModel = Ident, options = {}) {
+    const uid = isLegacyIdent(legacy, IdentModel) ? legacy.getLegacyUID() : undefined;
+    const parts = uid ? splitLegacyKey(uid) : undefined;
+    if (!parts) {
+        throw new Error("Not a v3 ident");
+    }
+    const v3 = legacy;
+    const provider = v3.provider ?? v3._type ?? parts.provider;
+    // v3 did not normalise emails: an email key is upgraded under its normalised (lowercase) form
+    const providerUid = provider === "email" ? Ident.normalizeEmail(parts.providerUid) : parts.providerUid;
+    const key = Ident.key(providerUid, provider);
+    const ref = IdentModel.ref(key);
+    const owner = v3._user?.toString();
+    // Another account may already hold the upgraded key (e.g. two v3 keys differing only by case)
+    const checkOwner = (existing) => {
+        if (existing.getUser()?.toString() !== owner)
+            throw new IdentConflict();
+        return existing;
+    };
+    let ident = (await ref.exists()) ? checkOwner(await ref.get()) : undefined;
+    if (!ident) {
+        const created = new IdentModel({
+            ...key,
+            email: v3.email ?? (provider === "email" ? providerUid : undefined),
+            verifiedAt: v3._validation ? (toDate(v3._validation) ?? new Date()) : undefined,
+            lastUsedAt: toDate(v3._lastUsed),
+            _throttle: { lastSentAt: toTimestamp(v3._lastValidationEmail) },
+            _loginAttempts: typeof v3._failedLogin === "number" ? v3._failedLogin : 0,
+            _lastLoginAttemptAt: toTimestamp(v3._lastFailedLogin),
+            __profile: v3.__profile
+        });
+        if (owner) {
+            created.setUser(owner);
+        }
+        // v3 kept plaintext tokens: they are only stored encrypted
+        if (v3.__tokens && !options.dryRun) {
+            await created.tokens.set(v3.__tokens);
+        }
+        if (options.dryRun) {
+            return created;
+        }
+        try {
+            ident = await created.getRepository().create(created);
+        }
+        catch (err) {
+            // Store-agnostic lost race: the record now exists, whatever error the store reported
+            if (!(await ref.exists()))
+                throw err;
+            // The race may have been won by another v3 record of another user: never delete this one then
+            ident = checkOwner(await ref.get());
+        }
+    }
+    if (!options.dryRun) {
+        await IdentModel.ref(uid).delete();
+    }
+    return ident;
+}
+/**
+ * Enumerate the v3 idents of a store, for a batch migration (`webda auth migrate`)
+ *
+ * Iterates the ident model (all idents, the v3 ones are filtered client side: they lack `providerUid`, which
+ * stores cannot portably query for) and yields only the v3 records. Pass each to {@link upgradeIdent}.
+ * Upgrading deletes records, which shifts offset-based pagination (memory and file stores page by position):
+ * a migration upgrading while iterating must run passes until one yields nothing (upgrades are idempotent).
+ * @param IdentModel - ident model of the application
+ * @param query - optional WebdaQL filter, e.g. `"_user = 'uid'"`
+ * @returns the v3 idents
+ */
+export async function* legacyIdents(IdentModel = Ident, query = "") {
+    for await (const ident of IdentModel.iterate(query)) {
+        if (ident.getLegacyUID()) {
+            yield ident;
+        }
+    }
+}
+//# sourceMappingURL=upgrade.js.map

package/lib/compat/upgrade.js.map

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

package/lib/email/emailpassword.service.d.ts

@@ -0,0 +1,249 @@
+import { type AuthResult, Ident, type ProviderInfo, Service, ServiceParameters, type WebContext } from "@webda/core";
+import type { AuthProvider } from "../provider.js";
+/** When the email is verified relative to account creation */
+export type VerificationMode = "before" | "after" | "none";
+/** EmailPasswordProvider parameters */
+export declare class EmailPasswordParameters extends ServiceParameters {
+    /**
+     * Mailer service name
+     * @default "Mailer"
+     */
+    mailer: string;
+    /**
+     * Verification mode
+     * @default "before"
+     */
+    verification: VerificationMode;
+    /** Password rules
+     * @default { "policy": ".{8,}" }
+     */
+    password: {
+        /** @default ".{8,}" */
+        policy: string;
+        verifier?: string;
+    };
+    /** Throttling
+     * @default { "resendDelay": 14400000, "failedBeforeDelay": 3, "lockout": 900000 }
+     */
+    throttle: {
+        /** @default 14400000 */
+        resendDelay: number;
+        /** @default 3 */
+        failedBeforeDelay: number;
+        /** @default 900000 */
+        lockout: number;
+    };
+    /**
+     * Browser redirects for emailed links (no defaults: init() refuses a missing required one). `failure` and `recover`
+     * are always required, `verified` and `register` unless `verification` is "none". `recover` receives the recovery
+     * link as `?token=...` (the page then calls Auth.Password.Recover). `confirm` (default `failure`) receives a
+     * verification link opened without the matching session, with `?reason=LOGIN_REQUIRED&token=...`: log in then call
+     * Auth.Email.Verify with the token
+     */
+    redirects: {
+        verified?: string;
+        failure?: string;
+        register?: string;
+        confirm?: string;
+        recover?: string;
+    };
+    /**
+     * Base url for emailed links
+     * @default "/auth/email"
+     */
+    url: string;
+    /** Only these email domains may use this provider (see ProviderEmailPolicy) */
+    allowedEmailDomains?: string[];
+    /** Whether the verification of the email is believed (see ProviderEmailPolicy) */
+    trustEmailVerification?: boolean | string[];
+    /**
+     * @param params - raw parameters
+     * @returns this
+     */
+    load(params?: any): this;
+}
+/**
+ * Email + password login method
+ *
+ * The password policy is process-wide: resolve() registers the one of this provider and stop() restores the
+ * default. With several instances the last one resolved wins.
+ *
+ * Known residual exposure: Auth.Email.Register answers AccountExists for a registered email (enumeration), and
+ * login timing differs slightly for known emails. An unverified squatter owning an email blocks its registration
+ * until the real owner goes through account recovery.
+ *
+ * Under `allowedEmailDomains` an email must be verified: with `verification` "after" or "none" a new registration is
+ * unverified and therefore refused (EMAIL_DOMAIN_NOT_ALLOWED); use "before".
+ * @WebdaModda EmailPasswordProvider
+ */
+export declare class EmailPasswordProvider<T extends EmailPasswordParameters = EmailPasswordParameters> extends Service<T> implements AuthProvider {
+    static Parameters: typeof EmailPasswordParameters;
+    readonly providerName = "email";
+    /** @override */
+    resolve(): this;
+    /** @override */
+    init(): Promise<this>;
+    /** @override */
+    stop(): Promise<void>;
+    /**
+     * @returns public info
+     */
+    getPublicInfo(): ProviderInfo;
+    /**
+     * @param email - normalised email
+     * @returns the email ident
+     */
+    protected getIdent(email: string): Promise<Ident | undefined>;
+    /**
+     * Absolute link for an emailed token
+     * @param path - path under the provider url
+     * @param token - token
+     * @returns url
+     */
+    buildLink(path: string, token: string): string;
+    /**
+     * @param template - mail template
+     * @param to - recipient
+     * @param url - link
+     * @param token - token
+     */
+    protected sendMail(template: "EMAIL_REGISTER" | "EMAIL_RECOVERY", to: string, url: string, token: string): Promise<void>;
+    /**
+     * Count a login attempt before verifying it and decide whether the ident is locked
+     *
+     * Rule, equivalent to `isLocked(ident, failedBeforeDelay, lockout)` on the state before this attempt:
+     * `_loginAttempts` is incremented first (atomically; the new value is returned by the memory repository and
+     * re-read otherwise), so this attempt is locked when the count of PREVIOUS attempts (`_loginAttempts - 1`) is at
+     * least `failedBeforeDelay`, unless that lock has expired, ie `_lastLoginAttemptAt` as read when this call started
+     * is older than `lockout`. `_lastLoginAttemptAt` is only refreshed by attempts that are not refused, so hammering
+     * a locked ident does not extend the lock; a count reaching the threshold without timestamp is an expired lock.
+     * Both are top-level attributes: stores implement atomic increment and
+     * single attribute set on them (nested-path atomic operations are not portable across stores). The timestamp
+     * is a plain set (last writer wins); the counter is never written back from a snapshot. A burst starting exactly
+     * when an expired lock is read is verified as a whole: it is bounded to one burst per lock window.
+     * @param ident - the ident
+     * @returns true when this attempt must be refused without checking the password
+     */
+    protected countAttempt(ident: Ident): Promise<boolean>;
+    /**
+     * Login with email and password
+     * @param email - email
+     * @param password - password
+     * @returns the auth result
+     */
+    login(email: string, password: string): Promise<AuthResult>;
+    /**
+     * Register with email and password
+     * @param email - email
+     * @param password - password
+     * @param token - register token from the emailed link (verification "before")
+     * @param profile - extra user fields
+     * @returns the auth result, or verification_sent
+     */
+    register(email: string, password: string, token?: string, profile?: any): Promise<any>;
+    /**
+     * Send (or resend) a verification link
+     *
+     * Logged in: the link proves the email for the current account (`sub` is only in the token, the ident stays
+     * unowned until Auth.Email.Verify is called by the same session). Logged out: always answers with no content and
+     * never reveals anything; a link is only sent for an unowned or unknown email.
+     * @param email - email
+     */
+    startVerification(email: string): Promise<void>;
+    /**
+     * Logged-out link: a register link is emailed, without awaiting the mail, only for an unknown or unowned and
+     * unverified email whose send throttle allows it; anything else is silently ignored
+     * @param normalized - normalised email
+     */
+    protected sendUnownedLink(normalized: string): Promise<void>;
+    /**
+     * Check and mark the send throttle of an email ident, then sign the token to email; runs as system
+     * @param normalized - normalised email
+     * @param userId - logged user (verify token), undefined for a logged-out register token
+     * @returns the token to send, undefined when nothing must be sent (logged out only)
+     * @throws IdentLinkedElsewhere / PreconditionFailed / Throttled (logged in only)
+     */
+    protected prepareLink(normalized: string, userId: string | undefined): Promise<string | undefined>;
+    /**
+     * Send a mail without awaiting it; failures are logged without any secret
+     * @param template - mail template
+     * @param to - recipient
+     * @param url - link
+     * @param token - token
+     */
+    protected sendMailDetached(template: "EMAIL_REGISTER" | "EMAIL_RECOVERY", to: string, url: string, token: string): void;
+    /** Mails sent without being awaited */
+    protected pendingMails: Set<Promise<void>>;
+    /**
+     * Wait for the mails sent without being awaited (logged out verification, recovery)
+     */
+    flushMails(): Promise<void>;
+    /**
+     * Mark an email as verified: only the session of the user named by the token can complete it
+     * @param token - verify token
+     * @returns status
+     */
+    verify(token: string): Promise<{
+        status: "verified";
+    }>;
+    /**
+     * Verify with an explicit context
+     * @param token - verify token
+     * @param ctx - context whose session must match the token
+     * @returns status
+     */
+    protected verifyWith(token: string, ctx: any): Promise<{
+        status: "verified";
+    }>;
+    /**
+     * @param claims - verified token claims
+     * @param claims.sub - user id
+     * @param ctx - context
+     * @returns true when the session is logged as the user of the token
+     */
+    protected sessionMatches(claims: {
+        sub?: string;
+    }, ctx: any): boolean;
+    /**
+     * Complete a verification; nothing changes unless every check passes
+     * @param claims - verified token claims
+     * @param claims.email - email of the token
+     * @param claims.sub - user id
+     * @param ctx - context
+     */
+    protected completeVerify(claims: {
+        email: string;
+        sub?: string;
+    }, ctx: any): Promise<void>;
+    /**
+     * Start password recovery; always succeeds to avoid revealing accounts
+     * @param email - email
+     */
+    startRecovery(email: string): Promise<void>;
+    /**
+     * Set a new password from a recovery link (does not log in): revokes the refresh tokens and ends every session of
+     * the user (see `Session.authAt`), resets the login attempts of the email ident
+     * @param token - recover token
+     * @param password - new password
+     */
+    recover(token: string, password: string): Promise<void>;
+    /**
+     * Change the current user's password: revokes the refresh tokens and ends the other sessions of the user, the
+     * calling cookie session is re-stamped and stays logged in
+     * @param current - current password
+     * @param next - new password
+     */
+    changePassword(current: string, next: string): Promise<void>;
+    /**
+     * Browser landing for recovery links: redirects a valid recover token to `redirects.recover` without consuming it,
+     * anything else to `redirects.failure`; never throws
+     * @param ctx - web context
+     */
+    recoverRedirect(ctx: WebContext): Promise<void>;
+    /**
+     * Browser landing for emailed links: verifies then redirects, never throws
+     * @param ctx - web context
+     */
+    verifyRedirect(ctx: WebContext): Promise<void>;
+}
+//# sourceMappingURL=emailpassword.service.d.ts.map

package/lib/email/emailpassword.service.d.ts.map

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