tinbase 0.16.1 → 0.17.0

package/dist/auth/handler.d.ts

@@ -13,8 +13,29 @@ import { RateLimiter } from './rate-limit.js';
 export interface AuthConfig {
     /** HS256 secret used to sign and verify access tokens */
     jwtSecret: string;
-    /** public base URL of this instance; used as issuer and default redirect target */
+    /**
+     * Where the *application* lives. The default redirect when a link carries no
+     * `redirect_to` or one the allowlist refuses, and what `{{ .SiteURL }}`
+     * interpolates to in an email template.
+     *
+     * This is GoTrue's `SITE_URL`, and it is not where this server answers - see
+     * {@link apiExternalUrl}.
+     */
     siteUrl: string;
+    /**
+     * Where *this server* answers, as a mail client can reach it. Emailed links
+     * are built on it and it is the token issuer.
+     *
+     * Separate from {@link siteUrl} because the two are different machines: a
+     * link has to come back here to be verified, while a user who finishes the
+     * flow belongs on the app. Collapsing them forces a choice between links
+     * that resolve and a redirect that lands somewhere useful - set to the API,
+     * every fallback dumps the user on this server's root; set to the app, no
+     * emailed link works at all.
+     *
+     * Defaults to {@link siteUrl}, which is the pre-0.17 behaviour.
+     */
+    apiExternalUrl?: string;
     /** Access-token lifetime in seconds. */
     jwtExpiry: number;
     /** Force sign-out after this many seconds (config.toml auth.sessions.timebox). Caps session lifetime. */
@@ -88,23 +109,45 @@ export declare class AuthHandler {
     private settings;
     private rateLimiter;
     constructor(db: Database, config: AuthConfig);
+    /**
+     * Where this server answers: emailed links come back here, and tokens are
+     * issued by it. Falls back to the site URL, which is what a deployment that
+     * has not separated the two is already using for both.
+     */
+    private get apiUrl();
     /**
      * Enforce the rate limit for `action`, keyed by client address. Returns a 429
      * (GoTrue's `over_request_rate_limit`) when exceeded, else null to proceed.
      */
     private limit;
+    /** GoTrue's 429 for `max_frequency`, with the seconds the caller must wait. */
+    private static tooSoon;
     /**
-     * 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.
+     *
+     * 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.
      *
-     * 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.
+     * 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.
      */
     private limitEmailFrequency;
+    /**
+     * 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.
+     */
+    private markEmailSent;
     /** Stop background timers (rate-limiter sweep). Called on backend close. */
     stop(): void;
     /** Dispatch one `/auth/v1/*` request. Any thrown error becomes a 500 `unexpected_failure`. */
@@ -153,6 +196,21 @@ export declare class AuthHandler {
      */
     private issueToken;
     private sendOtp;
+    /**
+     * 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.
+     */
+    private resend;
     private sendRecovery;
     /** Max wrong guesses for a one-time code before its tokens are invalidated. */
     private static readonly MAX_OTP_ATTEMPTS;

package/dist/auth/handler.js

@@ -45,6 +45,21 @@ function authEmailHtml(o) {
     ].join('');
 }
 /** A cryptographically-random numeric OTP of `length` digits (6-10). */
+/**
+ * Whether knowing `token` proves nothing on its own.
+ *
+ * An OTP is six to ten digits - a few hundred thousand guesses, which is
+ * nothing without the address it was sent to. The link token is 24 random
+ * bytes in base64url, which is not guessable and is all an emailed link can
+ * carry, so it stays redeemable unscoped.
+ *
+ * Decided from the token itself rather than from `token_type`, because both
+ * rows a recovery mints share one type - the shape is the only honest
+ * discriminator.
+ */
+function isGuessableToken(token) {
+    return token.length < 20 || /^\d+$/.test(token);
+}
 function randomOtp(length) {
     const n = Math.max(6, Math.min(10, Math.floor(length)));
     const buf = new Uint32Array(n);
@@ -76,10 +91,18 @@ export class AuthHandler {
     constructor(db, config) {
         this.db = db;
         this.config = config;
-        this.oauth = new OAuthService(db, config.siteUrl, config.oauthProviders ?? {}, config.oauthFetch ?? fetch, config.uriAllowList, config.enforceRedirectAllowList);
+        this.oauth = new OAuthService(db, config.siteUrl, config.apiExternalUrl || config.siteUrl, config.oauthProviders ?? {}, config.oauthFetch ?? fetch, config.uriAllowList, config.enforceRedirectAllowList);
         this.settings = config.settings ?? { ...DEFAULT_AUTH_SETTINGS };
         this.rateLimiter = config.rateLimiter === undefined ? new RateLimiter() : config.rateLimiter;
     }
+    /**
+     * Where this server answers: emailed links come back here, and tokens are
+     * issued by it. Falls back to the site URL, which is what a deployment that
+     * has not separated the two is already using for both.
+     */
+    get apiUrl() {
+        return this.config.apiExternalUrl || this.config.siteUrl;
+    }
     /**
      * Enforce the rate limit for `action`, keyed by client address. Returns a 429
      * (GoTrue's `over_request_rate_limit`) when exceeded, else null to proceed.
@@ -93,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() {
@@ -160,10 +216,15 @@ export class AuthHandler {
                 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 await this.verifyToken(req);
+                return this.limit('verify', req) ?? (await this.verifyToken(req));
+            // Deliberately unlimited, unlike the POST above: a link carries no email,
+            // so after the scoping guard in redeem() this path can only redeem the
+            // 24-byte link token. There is nothing here left to guess.
             if (path === 'verify' && method === 'GET')
                 return await this.verifyLink(url);
             if (path === 'factors' && method === 'POST')
@@ -220,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)
@@ -452,7 +530,10 @@ export class AuthHandler {
         const { code, linkToken } = minted;
         const normalized = email.toLowerCase().trim();
         const kind = tokenType === 'otp' ? 'magiclink' : tokenType;
-        let link = `${this.config.siteUrl}/auth/v1/verify?token=${linkToken}&type=${kind}`;
+        // 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)
             link += `&redirect_to=${encodeURIComponent(redirectTo)}`;
@@ -490,6 +571,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';
@@ -519,13 +601,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, {
@@ -533,11 +616,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
@@ -555,7 +688,18 @@ export class AuthHandler {
     /** Max wrong guesses for a one-time code before its tokens are invalidated. */
     static MAX_OTP_ATTEMPTS = 5;
     async redeem(token, types, email) {
-        const normalizedEmail = email?.toLowerCase().trim() ?? null;
+        // `|| null`, not `??`: an empty string is an absent address, not one to
+        // match on. Left as '' it reaches the query as `email = ''`, which matches
+        // nothing, and a client that sends `email: ''` beside a link token has a
+        // good token refused.
+        const normalizedEmail = email?.toLowerCase().trim() || null;
+        // SECURITY: a guessable code is only a credential together with the address
+        // it was sent to. Unscoped, `token = $1` matches whoever happens to hold a
+        // live code - so one guess is tried against every account at once - and the
+        // attempt counter below needs the email to know what to count, so the
+        // lockout never fires either. Refuse rather than widen the match.
+        if (!normalizedEmail && isGuessableToken(token))
+            return null;
         const res = await this.db.query(`delete from auth.one_time_tokens
        where token = $1 and token_type = any($2::text[])
          and ($3::text is null or email = $3) and expires_at > now()
@@ -772,7 +916,7 @@ export class AuthHandler {
             user = res.rows[0] ?? user;
         }
         const redirectTo = resolveRedirect(body.redirect_to, this.config.siteUrl, this.config.uriAllowList, this.config.enforceRedirectAllowList);
-        const actionLink = `${this.config.siteUrl}/auth/v1/verify?token=${linkToken}&type=${type}` +
+        const actionLink = `${this.apiUrl}/auth/v1/verify?token=${linkToken}&type=${type}` +
             `&redirect_to=${encodeURIComponent(redirectTo)}`;
         await this.audit('generate_link', { actorId: user.id, actorEmail: user.email, traits: { type } });
         return json(200, {
@@ -1091,7 +1235,7 @@ export class AuthHandler {
         // moment the client refreshed.
         const sessionId = opts?.sessionId ?? crypto.randomUUID();
         const claims = {
-            iss: `${this.config.siteUrl}/auth/v1`,
+            iss: `${this.apiUrl}/auth/v1`,
             sub: user.id,
             aud: user.aud ?? 'authenticated',
             exp: expiresAt,