tinbase 0.16.2 → 0.18.0

package/dist/auth/handler.js

@@ -116,32 +116,65 @@ export class AuthHandler {
             return null;
         return new Response(JSON.stringify({ code: 429, error_code: 'over_request_rate_limit', msg: 'Request rate limit reached' }), { status: 429, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': String(retryAfter) } });
     }
+    /** GoTrue's 429 for `max_frequency`, with the seconds the caller must wait. */
+    static tooSoon(retryAfter) {
+        return new Response(JSON.stringify({
+            code: 429,
+            error_code: 'over_email_send_rate_limit',
+            msg: `For security purposes, you can only request this after ${retryAfter} seconds.`,
+        }), { status: 429, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': String(retryAfter) } });
+    }
     /**
-     * Enforce `max_frequency`: refuse a second auth email to the same address
-     * within the configured window (GoTrue's `over_email_send_rate_limit`).
+     * Enforce `max_frequency` the way GoTrue does: against the timestamp that
+     * flow last wrote on the user row, not against one budget per address.
      *
-     * Keyed by recipient, not by caller, and checked before the account is looked
-     * up. Both matter: keying by caller lets someone rotate addresses and keep
-     * mailing one victim, and checking after the lookup would answer differently
-     * for an address that exists than for one that does not - handing back the
-     * account enumeration that answering 200 for unknown addresses exists to
-     * prevent.
+     * Which column a flow measures itself by is GoTrue's mapping, quirks
+     * included - a magic link is measured by `recovery_sent_at`, the same column
+     * password recovery uses, because GoTrue mints both from the recovery token.
+     * Sharing that budget is therefore correct rather than an oversight; a
+     * confirmation, by contrast, has its own. An app that sets `max_frequency`
+     * in config.toml gets the pacing Supabase's docs describe, which is the
+     * point of spelling it the same way.
+     *
+     * An address with no account has no row to measure, so those fall back to an
+     * in-memory window keyed the same way. GoTrue simply lets them through,
+     * which makes a 429 proof that an account exists - `/recover` answers 200
+     * for an address it has never seen precisely so the response cannot be used
+     * to enumerate accounts, and a frequency check that only ever fires for real
+     * users hands that back. The fallback keeps the two indistinguishable.
      */
-    limitEmailFrequency(email) {
+    async limitEmailFrequency(email, column) {
         const seconds = this.settings.maxEmailFrequencySeconds;
-        if (!this.rateLimiter || !seconds || seconds <= 0)
+        if (!seconds || seconds <= 0)
+            return null;
+        const normalized = email.toLowerCase().trim();
+        // `column` is one of the four literals in SentAtColumn, never caller input.
+        const res = await this.db.query(`select extract(epoch from (now() - ${column}))::int as elapsed
+       from auth.users where email = $1`, [normalized]);
+        const row = res.rows[0];
+        if (row) {
+            // A row exists: the column is the authority, and it survives a restart,
+            // which an in-memory counter does not.
+            if (row.elapsed !== null && row.elapsed < seconds) {
+                return AuthHandler.tooSoon(Math.max(1, seconds - row.elapsed));
+            }
+            return null;
+        }
+        if (!this.rateLimiter)
             return null;
-        const retryAfter = this.rateLimiter.check('email_frequency', email.toLowerCase().trim(), Date.now(), {
+        const retryAfter = this.rateLimiter.check(`email_frequency:${column}`, normalized, Date.now(), {
             limit: 1,
             windowMs: seconds * 1000,
         });
-        if (retryAfter === null)
-            return null;
-        return new Response(JSON.stringify({
-            code: 429,
-            error_code: 'over_email_send_rate_limit',
-            msg: `For security purposes, you can only request this after ${retryAfter} seconds.`,
-        }), { status: 429, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': String(retryAfter) } });
+        return retryAfter === null ? null : AuthHandler.tooSoon(retryAfter);
+    }
+    /**
+     * Record that this flow has just mailed the address, so the next request is
+     * measured from now. Written only after the mail was accepted - a transport
+     * that refused it has not spent the window.
+     */
+    async markEmailSent(userId, column) {
+        await this.db.query(`update auth.users set ${column} = now() where id = $1`, [userId]);
     }
     /** Stop background timers (rate-limiter sweep). Called on backend close. */
     stop() {
@@ -176,15 +209,17 @@ export class AuthHandler {
             if (path === 'user' && method === 'GET')
                 return await this.getUser(req);
             if (path === 'user' && method === 'PUT')
-                return await this.updateUser(req);
+                return await this.updateUser(req, url);
             if (path === 'logout' && method === 'POST')
                 return await this.logout(req);
             if (path === 'otp' && method === 'POST')
                 return this.limit('otp', req) ?? (await this.sendOtp(req, url));
             if (path === 'recover' && method === 'POST')
                 return this.limit('recover', req) ?? (await this.sendRecovery(req, url));
-            if (['magiclink', 'resend'].includes(path) && method === 'POST')
+            if (path === 'magiclink' && method === 'POST')
                 return this.limit('otp', req) ?? (await this.sendOtp(req, url));
+            if (path === 'resend' && method === 'POST')
+                return this.limit('otp', req) ?? (await this.resend(req, url));
             if (path === 'verify' && method === 'POST')
                 return this.limit('verify', req) ?? (await this.verifyToken(req));
             // Deliberately unlimited, unlike the POST above: a link carries no email,
@@ -246,8 +281,25 @@ export class AuthHandler {
         if (existing.rows.length > 0) {
             return authError(422, 'user_already_exists', 'User already registered');
         }
-        const hashed = await hashPassword(body.password);
+        // A signup that has to be confirmed sends mail, so it belongs under the
+        // same per-recipient budget as /otp and /recover. Repeating a signup was
+        // never the way to abuse that - the second is refused as
+        // `user_already_exists` before any mail is considered - but the
+        // confirmation not counting meant the three flows that can mail an address
+        // each spent the window separately, putting more into one inbox than
+        // `max_frequency` allows.
+        //
+        // Checked before the row is written, so a refusal leaves no half-made
+        // account behind, and only when confirmation is on: under autoconfirm
+        // there is no email to pace, and spending the budget would block a flow
+        // that would actually use it.
         const autoconfirm = this.settings.autoconfirm;
+        if (!autoconfirm) {
+            const tooSoon = await this.limitEmailFrequency(email, 'confirmation_sent_at');
+            if (tooSoon)
+                return tooSoon;
+        }
+        const hashed = await hashPassword(body.password);
         const res = await this.db.query(`insert into auth.users
          (aud, role, email, encrypted_password, email_confirmed_at, last_sign_in_at,
           raw_app_meta_data, raw_user_meta_data)
@@ -334,7 +386,7 @@ export class AuthHandler {
             return authError(401, 'no_authorization', 'Invalid or expired token');
         return json(200, this.userJson(user, await this.getUserFactors(user.id), await this.getUserIdentities(user.id)));
     }
-    async updateUser(req) {
+    async updateUser(req, url) {
         const user = await this.userFromBearer(req);
         if (!user)
             return authError(401, 'no_authorization', 'Invalid or expired token');
@@ -345,14 +397,24 @@ export class AuthHandler {
         // usually a password) keeps the same id + data, flips is_anonymous off, and
         // records an email identity - matching supabase.auth.updateUser({ email }).
         const upgradingAnon = (user.is_anonymous ?? false) && !!body.email;
+        // Changing the address on an account that already has one is a different
+        // operation from naming one for the first time, and only the first is an
+        // email change. An anonymous upgrade has no address to confirm from and
+        // nothing to lose if it is wrong, so it keeps taking effect immediately.
+        let pendingEmail = null;
         if (body.email) {
             const email = body.email.toLowerCase().trim();
             const clash = await this.db.query(`select id from auth.users where email = $1 and id <> $2`, [email, user.id]);
             if (clash.rows.length > 0) {
                 return authError(422, 'email_exists', 'A user with this email address has already been registered');
             }
-            params.push(email);
-            sets.push(`email = $${params.length}, email_confirmed_at = now()`);
+            if (upgradingAnon || this.settings.autoconfirm || email === (user.email ?? '').toLowerCase()) {
+                params.push(email);
+                sets.push(`email = $${params.length}, email_confirmed_at = now()`);
+            }
+            else {
+                pendingEmail = email;
+            }
         }
         if (body.password) {
             if (body.password.length < this.settings.minPasswordLength) {
@@ -369,19 +431,128 @@ export class AuthHandler {
             sets.push(`is_anonymous = false`);
             sets.push(`raw_app_meta_data = coalesce(raw_app_meta_data, '{}'::jsonb) || '{"provider":"email","providers":["email"]}'::jsonb`);
         }
-        if (sets.length === 0)
-            return json(200, this.userJson(user));
-        params.push(user.id);
-        const res = await this.db.query(`update auth.users set ${sets.join(', ')}, updated_at = now() where id = $${params.length} returning *`, params);
-        const updated = res.rows[0];
+        let updated = user;
+        if (sets.length > 0) {
+            params.push(user.id);
+            const res = await this.db.query(`update auth.users set ${sets.join(', ')}, updated_at = now() where id = $${params.length} returning *`, params);
+            updated = res.rows[0];
+        }
         if (upgradingAnon) {
             // record the email identity, unless one somehow already exists
             await this.db.query(`insert into auth.identities (user_id, provider, provider_id, identity_data)
          values ($1, 'email', $2, $3)
          on conflict (provider, provider_id) do nothing`, [updated.id, updated.id, JSON.stringify({ sub: updated.id, email: updated.email })]);
         }
+        if (pendingEmail) {
+            const started = await this.startEmailChange(updated, pendingEmail, url.searchParams.get('redirect_to'));
+            if (started)
+                return started;
+            const res = await this.db.query(`select * from auth.users where id = $1`, [updated.id]);
+            updated = res.rows[0] ?? updated;
+        }
         return json(200, this.userJson(updated));
     }
+    /**
+     * Begin an email change: park the new address, mint a token for each side,
+     * and mail them.
+     *
+     * The address does not move until the tokens come back. Writing it straight
+     * to `auth.users.email` - which is what this did - means a session is all it
+     * takes to walk an account to an address of the holder's choosing, with no
+     * confirmation from either end and nothing sent to the address losing it.
+     *
+     * With `secure_email_change_enabled` (the Supabase default) both ends have
+     * to click: the new address proves it exists and is reachable, and the
+     * current one gets a say in losing the account. The second token is what
+     * makes a stolen session insufficient on its own.
+     *
+     * Returns a Response only when the change could not be started.
+     */
+    async startEmailChange(user, newEmail, redirectTo) {
+        const tooSoon = await this.limitEmailFrequency(user.email ?? newEmail, 'email_change_sent_at');
+        if (tooSoon)
+            return tooSoon;
+        const { newToken, currentToken } = await this.mintEmailChangeTokens(user, newEmail);
+        const redirect = resolveRedirect(redirectTo, this.config.siteUrl, this.config.uriAllowList, this.config.enforceRedirectAllowList);
+        await this.mailEmailChange(user, newEmail, newEmail, newToken, 'email_change_new', redirect, redirectTo !== null);
+        if (currentToken) {
+            await this.mailEmailChange(user, user.email, newEmail, currentToken, 'email_change_current', redirect, redirectTo !== null);
+        }
+        return null;
+    }
+    /**
+     * Park the new address and mint a token per side, without sending anything.
+     *
+     * Shared with `admin/generate_link`, which needs the same tokens but hands
+     * them to the caller. One implementation so the two cannot disagree about
+     * how many sides there are or when the previous attempt is invalidated.
+     */
+    async mintEmailChangeTokens(user, newEmail) {
+        const secure = this.settings.secureEmailChange && !!user.email;
+        const expiry = `${this.settings.otpExpirySeconds} seconds`;
+        const newToken = randomToken(24);
+        const currentToken = secure ? randomToken(24) : null;
+        // A second change replaces the first outright: leaving the old tokens live
+        // would let a link for a superseded address still land.
+        await this.db.query(`delete from auth.one_time_tokens where user_id = $1 and token_type in ('email_change_new', 'email_change_current')`, [user.id]);
+        await this.db.query(`insert into auth.one_time_tokens (user_id, email, token_type, token, expires_at)
+       values ($1, $2, 'email_change_new', $3, now() + $4::interval)`, [user.id, newEmail, newToken, expiry]);
+        if (currentToken) {
+            await this.db.query(`insert into auth.one_time_tokens (user_id, email, token_type, token, expires_at)
+         values ($1, $2, 'email_change_current', $3, now() + $4::interval)`, [user.id, user.email, currentToken, expiry]);
+        }
+        await this.db.query(`update auth.users
+         set email_change = $2, email_change_sent_at = now(), email_change_confirm_status = 0,
+             updated_at = now()
+       where id = $1`, [user.id, newEmail]);
+        return { newToken, currentToken };
+    }
+    /** One side of an email change, to whichever address that side belongs to. */
+    async mailEmailChange(user, to, pending, token, action, redirect, carryRedirect) {
+        let link = `${this.apiUrl}/auth/v1/verify?token=${token}&type=email_change`;
+        if (carryRedirect)
+            link += `&redirect_to=${encodeURIComponent(redirect)}`;
+        if (this.config.sendEmailHook) {
+            // GoTrue sends one payload carrying both sides, so an endpoint can word
+            // them differently. token/token_hash are the side being asked, and
+            // token_new/token_hash_new the new address's - the fields that have been
+            // empty strings here since the hook was added, for want of this flow.
+            const isNew = action === 'email_change_new';
+            await callSendEmailHook(this.config.sendEmailHook, {
+                user: this.userJson(user),
+                email_data: {
+                    token: '',
+                    token_hash: token,
+                    redirect_to: redirect,
+                    email_action_type: action,
+                    site_url: this.config.siteUrl,
+                    token_new: '',
+                    token_hash_new: isNew ? token : '',
+                },
+            }, this.config.hookFetch);
+            return;
+        }
+        const template = this.config.emailTemplates?.email_change;
+        const lead = action === 'email_change_new'
+            ? 'Confirm this address to finish moving your account to it:'
+            : `Confirm moving your account to ${pending}:`;
+        const html = template?.content
+            ? renderTemplate(template.content, {
+                ConfirmationURL: link,
+                Token: '',
+                TokenHash: token,
+                RedirectTo: redirect,
+                SiteURL: this.config.siteUrl,
+                Email: to,
+            })
+            : authEmailHtml({ lead, action: 'Confirm email change', link, code: null });
+        await this.config.mailer.send({
+            to,
+            subject: template?.subject ?? 'Confirm your email change',
+            text: template?.content ? htmlToText(html) : `${lead} ${link}`,
+            html,
+        });
+    }
     /**
      * POST /auth/v1/logout[?scope=global|local|others]
      *
@@ -478,6 +649,9 @@ export class AuthHandler {
         const { code, linkToken } = minted;
         const normalized = email.toLowerCase().trim();
         const kind = tokenType === 'otp' ? 'magiclink' : tokenType;
+        // GoTrue's mapping: a confirmation has its own budget, while a magic link
+        // and a recovery share `recovery_sent_at`.
+        const sentAtColumn = flavor === 'confirm' ? 'confirmation_sent_at' : 'recovery_sent_at';
         let link = `${this.apiUrl}/auth/v1/verify?token=${linkToken}&type=${kind}`;
         const redirectTo = resolveRedirect(opts.redirectTo, this.config.siteUrl, this.config.uriAllowList, this.config.enforceRedirectAllowList);
         if (opts.redirectTo)
@@ -516,6 +690,7 @@ export class AuthHandler {
                     token_hash_new: '',
                 },
             }, this.config.hookFetch);
+            await this.markEmailSent(minted.user.id, sentAtColumn);
             return json(200, {});
         }
         const templateName = tokenType === 'recovery' ? 'recovery' : flavor === 'confirm' ? 'confirmation' : 'magic_link';
@@ -545,13 +720,14 @@ export class AuthHandler {
             text: template?.content ? htmlToText(html) : defaultText,
             html,
         });
+        await this.markEmailSent(minted.user.id, sentAtColumn);
         return json(200, {});
     }
     async sendOtp(req, url) {
         const body = (await req.json().catch(() => ({})));
         if (!body.email)
             return authError(400, 'validation_failed', 'email is required');
-        const tooSoon = this.limitEmailFrequency(body.email);
+        const tooSoon = await this.limitEmailFrequency(body.email, 'recovery_sent_at');
         if (tooSoon)
             return tooSoon;
         return this.issueToken(body.email, 'otp', body.create_user !== false, {
@@ -559,11 +735,61 @@ export class AuthHandler {
             ...AuthHandler.pkceFrom(body),
         });
     }
+    /**
+     * POST /auth/v1/resend - send the confirmation for `type` again.
+     *
+     * This used to be an alias for /magiclink, which is a different email
+     * entirely: it mails a login link measured by `recovery_sent_at`, creates an
+     * account for an address it has never seen, and pays no attention to `type`.
+     * So a resend for an address with no account signed that person up and sent
+     * them a way in, and a resend for a signup was paced by the recovery window.
+     *
+     * GoTrue answers 200 with an empty body both for an address it does not know
+     * and for one already confirmed - the two look identical from outside, which
+     * is what stops the endpoint from reporting who has an account. No mail goes
+     * out in either case.
+     */
+    async resend(req, url) {
+        const body = (await req.json().catch(() => ({})));
+        if (!body.type)
+            return authError(400, 'validation_failed', 'Missing one of these arguments: type');
+        if (body.type === 'sms' || body.type === 'phone_change') {
+            return authError(400, 'validation_failed', `Resend with type "${body.type}" requires phone auth, which is not supported`);
+        }
+        if (body.type === 'email_change') {
+            // The email-change flow itself does not exist yet, so there is no
+            // pending address to confirm. Say that, rather than resending something
+            // else and calling it an email change.
+            return authError(400, 'validation_failed', 'Resend type "email_change" is not supported yet');
+        }
+        if (body.type !== 'signup') {
+            return authError(400, 'validation_failed', `Resend requires a valid type: ${body.type}`);
+        }
+        if (!body.email)
+            return authError(400, 'validation_failed', 'email is required');
+        const normalized = body.email.toLowerCase().trim();
+        const res = await this.db.query(`select id, email_confirmed_at from auth.users where email = $1`, [normalized]);
+        const user = res.rows[0];
+        // Nothing to confirm, either because there is no account or because it is
+        // already confirmed. Answered the same way, and without creating anything:
+        // a resend is a repeat of a mail the address has already been sent, never
+        // the thing that signs someone up.
+        if (!user || user.email_confirmed_at)
+            return json(200, {});
+        const tooSoon = await this.limitEmailFrequency(normalized, 'confirmation_sent_at');
+        if (tooSoon)
+            return tooSoon;
+        return this.issueToken(normalized, 'otp', false, {
+            flavor: 'confirm',
+            redirectTo: url.searchParams.get('redirect_to'),
+            ...AuthHandler.pkceFrom(body),
+        });
+    }
     async sendRecovery(req, url) {
         const body = (await req.json().catch(() => ({})));
         if (!body.email)
             return authError(400, 'validation_failed', 'email is required');
-        const tooSoon = this.limitEmailFrequency(body.email);
+        const tooSoon = await this.limitEmailFrequency(body.email, 'recovery_sent_at');
         if (tooSoon)
             return tooSoon;
         // GoTrue answers 200 for an address it has never seen, so the response
@@ -627,10 +853,68 @@ export class AuthHandler {
     static redeemTypes(type) {
         if (type === 'recovery')
             return ['recovery'];
+        if (type === 'email_change')
+            return ['email_change_new', 'email_change_current'];
         if (type === 'magiclink')
             return ['magiclink'];
         return ['otp', 'magiclink'];
     }
+    /** What a caller is told when one side of an email change is still outstanding. */
+    static EMAIL_CHANGE_PENDING_MSG = 'Confirmation link accepted. Please proceed to confirm link sent to the other email';
+    /**
+     * Redeem one side of an email change.
+     *
+     * Not routed through {@link redeem}, which exists for the login and recovery
+     * tokens and does things that are wrong here: it clears every live token for
+     * the address and stamps `last_sign_in_at`, and an email change is not a
+     * sign-in. It also cannot express the part that matters - that one click may
+     * not be enough.
+     *
+     * The address moves only once no side is left outstanding. With
+     * `secure_email_change_enabled` that means both tokens, in either order;
+     * with it off there is only ever the new address's. Deciding it by what
+     * remains in the table, rather than by counting clicks, is what makes the
+     * order irrelevant and a replay harmless - the row is gone the moment it is
+     * redeemed.
+     */
+    async verifyEmailChange(token) {
+        const res = await this.db.query(`delete from auth.one_time_tokens
+        where token = $1 and token_type in ('email_change_new', 'email_change_current')
+          and expires_at > now()
+        returning user_id`, [token]);
+        const row = res.rows[0];
+        if (!row)
+            return { status: 'invalid' };
+        const outstanding = await this.db.query(`select 1 from auth.one_time_tokens
+        where user_id = $1 and token_type in ('email_change_new', 'email_change_current')
+          and expires_at > now()`, [row.user_id]);
+        if (outstanding.rows.length > 0) {
+            await this.db.query(`update auth.users set email_change_confirm_status = 1, updated_at = now() where id = $1`, [row.user_id]);
+            return { status: 'pending' };
+        }
+        // `nullif` guards the case where the pending address was cleared in
+        // between: better to confirm the address already held than to blank it.
+        const done = await this.db.query(`update auth.users
+          set email = coalesce(nullif(email_change, ''), email),
+              email_confirmed_at = now(),
+              email_change = '',
+              email_change_token_new = '',
+              email_change_token_current = '',
+              email_change_confirm_status = 0,
+              updated_at = now()
+        where id = $1
+        returning *`, [row.user_id]);
+        const user = done.rows[0];
+        if (!user)
+            return { status: 'invalid' };
+        // The email identity carries the address too, and getUser reads it back
+        // through user.identities - left alone it would still name the old one.
+        await this.db.query(`update auth.identities
+          set identity_data = coalesce(identity_data, '{}'::jsonb) || jsonb_build_object('email', $2::text),
+              updated_at = now()
+        where user_id = $1 and provider = 'email'`, [user.id, user.email]);
+        return { status: 'done', user };
+    }
     async verifyToken(req) {
         const body = (await req.json().catch(() => ({})));
         // supabase-js sends `token_hash` for verifyOtp({ token_hash }) - the shape
@@ -640,6 +924,14 @@ export class AuthHandler {
         const token = body.token ?? body.token_hash;
         if (!token)
             return authError(400, 'validation_failed', 'token is required');
+        if (body.type === 'email_change') {
+            const outcome = await this.verifyEmailChange(token);
+            if (outcome.status === 'invalid')
+                return authError(403, 'otp_expired', 'Token has expired or is invalid');
+            if (outcome.status === 'pending')
+                return json(200, { msg: AuthHandler.EMAIL_CHANGE_PENDING_MSG });
+            return json(200, await this.sessionFor(outcome.user));
+        }
         const user = await this.redeem(token, AuthHandler.redeemTypes(body.type), body.email);
         if (!user)
             return authError(403, 'otp_expired', 'Token has expired or is invalid');
@@ -655,6 +947,33 @@ export class AuthHandler {
         // operator hasn't allowed - a crafted magic-link would otherwise exfiltrate
         // the session. Unknown targets fall back to the site URL.
         const redirectTo = resolveRedirect(url.searchParams.get('redirect_to'), this.config.siteUrl, this.config.uriAllowList, this.config.enforceRedirectAllowList);
+        if (type === 'email_change') {
+            const outcome = await this.verifyEmailChange(token);
+            if (outcome.status === 'invalid') {
+                return new Response(null, {
+                    status: 303,
+                    headers: { location: `${redirectTo}#error=access_denied&error_code=otp_expired` },
+                });
+            }
+            if (outcome.status === 'pending') {
+                // Nothing to hand back yet - the account is still on its old address
+                // until the other side answers, so there is no session to mint.
+                return new Response(null, {
+                    status: 303,
+                    headers: {
+                        location: `${redirectTo}#message=${encodeURIComponent(AuthHandler.EMAIL_CHANGE_PENDING_MSG)}`,
+                    },
+                });
+            }
+            const changed = (await this.sessionFor(outcome.user));
+            return new Response(null, {
+                status: 303,
+                headers: {
+                    location: `${redirectTo}#access_token=${changed.access_token}&refresh_token=${changed.refresh_token}` +
+                        `&expires_in=${changed.expires_in}&token_type=bearer&type=email_change`,
+                },
+            });
+        }
         const user = await this.redeem(token, AuthHandler.redeemTypes(type));
         if (!user) {
             return new Response(null, { status: 303, headers: { location: `${redirectTo}#error=access_denied&error_code=otp_expired` } });
@@ -775,11 +1094,10 @@ export class AuthHandler {
         if (!body.email)
             return authError(400, 'validation_failed', 'email is required');
         const type = body.type ?? 'magiclink';
-        // email_change_* would have to mint a token against a pending new address,
-        // which needs the email-change plumbing this handler doesn't have yet. Say
-        // so rather than returning a link that verifies as a plain login.
+        // The two sides of an email change mint against a pending address, so they
+        // need `new_email` as well and cannot share the flow below.
         if (type === 'email_change_current' || type === 'email_change_new') {
-            return authError(400, 'validation_failed', `generate_link type "${type}" is not supported yet`);
+            return await this.generateEmailChangeLink(type, body);
         }
         if (!['signup', 'invite', 'magiclink', 'recovery'].includes(type)) {
             return authError(400, 'validation_failed', `unsupported generate_link type: ${type}`);
@@ -821,6 +1139,48 @@ export class AuthHandler {
             verification_type: type,
         });
     }
+    /**
+     * `admin.generateLink({ type: 'email_change_current' | 'email_change_new' })`.
+     *
+     * Both sides are minted whichever is asked for - they are one change, and
+     * minting only the requested half would leave a secure change that can never
+     * complete. The caller gets the link for the side it named.
+     */
+    async generateEmailChangeLink(type, body) {
+        if (!body.email)
+            return authError(400, 'validation_failed', 'email is required');
+        if (!body.new_email)
+            return authError(400, 'validation_failed', `${type} requires new_email`);
+        const current = body.email.toLowerCase().trim();
+        const next = body.new_email.toLowerCase().trim();
+        const res = await this.db.query(`select * from auth.users where email = $1`, [current]);
+        const user = res.rows[0];
+        if (!user)
+            return authError(404, 'user_not_found', 'User not found');
+        const clash = await this.db.query(`select id from auth.users where email = $1 and id <> $2`, [next, user.id]);
+        if (clash.rows.length > 0) {
+            return authError(422, 'email_exists', 'A user with this address has already been registered');
+        }
+        const { newToken, currentToken } = await this.mintEmailChangeTokens(user, next);
+        // Asking for the current side when secure email change is off: there is no
+        // such token, and returning the new one under that name would quietly hand
+        // back a link that confirms the wrong half.
+        if (type === 'email_change_current' && !currentToken) {
+            return authError(400, 'validation_failed', 'email_change_current requires secure_email_change_enabled; only the new address is confirmed');
+        }
+        const token = type === 'email_change_new' ? newToken : currentToken;
+        const redirectTo = resolveRedirect(body.redirect_to, this.config.siteUrl, this.config.uriAllowList, this.config.enforceRedirectAllowList);
+        await this.audit('generate_link', { actorId: user.id, actorEmail: user.email, traits: { type } });
+        return json(200, {
+            ...this.userJson(user),
+            action_link: `${this.apiUrl}/auth/v1/verify?token=${token}&type=email_change` +
+                `&redirect_to=${encodeURIComponent(redirectTo)}`,
+            email_otp: '',
+            hashed_token: token,
+            redirect_to: redirectTo,
+            verification_type: type,
+        });
+    }
     // ── audit trail ───────────────────────────────────────────────────────
     /**
      * Append a security event to auth.audit_log_entries (GoTrue-compatible
@@ -1095,6 +1455,10 @@ export class AuthHandler {
             aud: u.aud ?? 'authenticated',
             role: u.role ?? 'authenticated',
             email: u.email ?? '',
+            // GoTrue reports a change that has been asked for but not yet confirmed,
+            // so a client can say "we've emailed <new_email>" instead of showing the
+            // old address with no sign anything is pending.
+            new_email: u.email_change || undefined,
             email_confirmed_at: iso(u.email_confirmed_at),
             phone: u.phone ?? '',
             confirmed_at: iso(u.email_confirmed_at),