emailengine-app 2.67.3 → 2.68.0

package/.github/workflows/test.yml

@@ -88,3 +88,6 @@ jobs:
                   GMAIL_SERVICE_POSTALSYS_SERVICE_EMAIL: ${{ secrets.GMAIL_SERVICE_POSTALSYS_SERVICE_EMAIL }}
                   GMAIL_SERVICE_POSTALSYS_KEY: ${{ secrets.GMAIL_SERVICE_POSTALSYS_KEY }}
                   GMAIL_SERVICE_POSTALSYS_ACCOUNT_EMAIL: ${{ secrets.GMAIL_SERVICE_POSTALSYS_ACCOUNT_EMAIL }}
+                  GMAIL_WIF_SA_KEY: ${{ secrets.GMAIL_WIF_SA_KEY }}
+                  GMAIL_WIF_AUDIENCE: ${{ secrets.GMAIL_WIF_AUDIENCE }}
+                  GMAIL_WIF_ACCOUNT_EMAIL: ${{ secrets.GMAIL_WIF_ACCOUNT_EMAIL }}

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [2.68.0](https://github.com/postalsys/emailengine/compare/v2.67.3...v2.68.0) (2026-05-26)
+
+
+### Features
+
+* accept threadId on the submit reference object ([b1b3dc7](https://github.com/postalsys/emailengine/commit/b1b3dc73ec5870a7a8ab9f0844055822ad046d2a))
+* add direct account registration for email service account apps ([6602b2e](https://github.com/postalsys/emailengine/commit/6602b2ee3f851bcfec00b34e70756007763f5490))
+* add OAuth2 app "Verify setup" diagnostic ([cba9f58](https://github.com/postalsys/emailengine/commit/cba9f58bc58a434c6156cd2e55fee655336a4cf4))
+* add Workload Identity Federation for Gmail service accounts ([1879c5a](https://github.com/postalsys/emailengine/commit/1879c5aaf30ccff1879e74d28b0c76e25b3d77ae))
+* lock Gmail auth method display after app creation ([6ba16c2](https://github.com/postalsys/emailengine/commit/6ba16c2fbca571d500b21be776dbf5eb76fcf8a1))
+* revoke upstream OAuth2 grant on account delete via ?revoke=true ([2a8c8fa](https://github.com/postalsys/emailengine/commit/2a8c8faf7f63acfab31998fb067289d4c6bd2f09))
+* revoke upstream OAuth2 grant on account delete via ?revoke=true ([15bc43a](https://github.com/postalsys/emailengine/commit/15bc43ae0f8dbf70021a1e13de55c80ec7271a15))
+* use tabs for Gmail auth method and lock it after creation ([6c74521](https://github.com/postalsys/emailengine/commit/6c7452138c257ecf0667aa9b44d1fa91186e2302))
+
+
+### Bug Fixes
+
+* clearer error when loading wrong file into WIF config field ([40686d4](https://github.com/postalsys/emailengine/commit/40686d409229347193c1e153e9e47f98b5de86dc))
+* flag WIF support in the gmailService form intro ([61fab27](https://github.com/postalsys/emailengine/commit/61fab2720aa2f289a944ae99629bc47ada8e9e09))
+* force-exit external-account-signer test to unblock CI ([f4a1e4e](https://github.com/postalsys/emailengine/commit/f4a1e4e50ac890d7771e38181a9488837c67757a))
+* let npm run gettext parse object spread and drop non-ASCII from template ([195ce60](https://github.com/postalsys/emailengine/commit/195ce601db50f394164ca05e2efb6de4b784a77a))
+* mask externalAccount in OAuth2 app API responses ([fac18bf](https://github.com/postalsys/emailengine/commit/fac18bfdc11d5d252e0d93980aad7c90d92b246f))
+* pkg config options must be a string array ([6c4702d](https://github.com/postalsys/emailengine/commit/6c4702dbc85171a2987b8cfb6e5a3dc3d656a99d))
+* prefer refresh token and skip gmailService when revoking on delete ([e0dbea8](https://github.com/postalsys/emailengine/commit/e0dbea8a4cd4804bf64d50523c8a1152c2119e26))
+* relax cross-folder assertion in Graph API parentFolderId test ([770279d](https://github.com/postalsys/emailengine/commit/770279ded669efdc5d6a2c33d05290daf91251ea))
+* right-align the service account Add account button ([c6f77b9](https://github.com/postalsys/emailengine/commit/c6f77b9777fb1cb9b1449662d05d4887e36a6ad8))
+
 ## [2.67.3](https://github.com/postalsys/emailengine/compare/v2.67.2...v2.67.3) (2026-04-21)
 
 

package/data/google-crawlers.json

@@ -1,5 +1,5 @@
 {
-    "creationTime": "2026-04-16T14:45:56.000000",
+    "creationTime": "2026-05-25T14:45:59.000000",
     "prefixes": [
         {
             "ipv6Prefix": "2001:4860:4801:2008::/64"

package/lib/account.js

@@ -977,9 +977,32 @@ class Account {
         return { account: this.account, state };
     }
 
-    async delete() {
+    async delete(opts) {
+        opts = opts || {};
+
         let accountData = await this.loadAccountData(this.account);
 
+        if (opts.revoke && accountData.oauth2?.provider) {
+            // Prefer refresh token over access token: revoking either invalidates the grant per Google's docs,
+            // but the stored access token may be expired (a 400 from the provider would leave the grant intact),
+            // while the refresh token is long-lived. Skip gmailService - Workspace service accounts have no
+            // per-user grant to revoke.
+            let token = accountData.oauth2.refreshToken || accountData.oauth2.accessToken;
+            if (token) {
+                try {
+                    let oauth2App = await oauth2Apps.get(accountData.oauth2.provider);
+                    if (oauth2App && oauth2App.provider !== 'gmailService') {
+                        let oauthClient = await oauth2Apps.getClient(accountData.oauth2.provider, { logger: this.logger });
+                        if (oauthClient && typeof oauthClient.revokeToken === 'function') {
+                            await oauthClient.revokeToken(token);
+                        }
+                    }
+                } catch (err) {
+                    this.logger.warn({ msg: 'Failed to revoke OAuth2 grant before account delete', account: this.account, err });
+                }
+            }
+        }
+
         const dateKeyTdy = new Date().toISOString().substring(0, 10).replace(/-/g, '');
         const dateKeyYdy = new Date(Date.now() - 24 * 3600 * 1000).toISOString().substring(0, 10).replace(/-/g, '');
 

package/lib/api-routes/account-routes.js

@@ -530,7 +530,7 @@ async function init(args) {
             });
 
             try {
-                return await accountObject.delete();
+                return await accountObject.delete({ revoke: request.query.revoke });
             } catch (err) {
                 request.logger.error({ msg: 'API request failed', err });
                 if (Boom.isBoom(err)) {
@@ -545,7 +545,7 @@ async function init(args) {
         },
         options: {
             description: 'Remove account',
-            notes: "Stop processing and clear the account's cache",
+            notes: "Stop processing and clear the account's cache. Pass revoke=true to also attempt revocation of the upstream OAuth2 grant at the provider before the account is removed.",
 
             tags: ['api', 'Account'],
 
@@ -567,6 +567,16 @@ async function init(args) {
 
                 params: Joi.object({
                     account: accountIdSchema.required()
+                }),
+
+                query: Joi.object({
+                    revoke: Joi.boolean()
+                        .truthy('Y', 'true', '1')
+                        .falsy('N', 'false', 0)
+                        .default(false)
+                        .description(
+                            'If true, EmailEngine attempts to revoke the upstream OAuth2 grant at the provider before deleting the account. Currently supported for individual Gmail OAuth grants. For Gmail Workspace service-account integrations (gmailService), Outlook, and non-OAuth2 accounts the flag is a no-op. Revoke failures are logged and do not block deletion.'
+                        )
                 })
             },
 

package/lib/email-client/base-client.js

@@ -1687,8 +1687,8 @@ class BaseClient {
                     data.reference.update = true;
                 }
 
-                // Preserve thread ID
-                if (referencedMessage.threadId) {
+                // Preserve thread ID, but let a caller-supplied threadId win
+                if (!data.reference.threadId && referencedMessage.threadId) {
                     data.reference.threadId = referencedMessage.threadId;
                 }
 
@@ -1906,15 +1906,18 @@ class BaseClient {
                 messageId
             };
 
-            if (data.reference && data.reference.message) {
-                response.reference = {
-                    message: data.reference.message,
-                    documentStore: documentStoreUsed,
-                    success: referencedMessage ? true : false
-                };
-
-                if (!referencedMessage) {
-                    response.reference.error = 'Referenced message was not found';
+            if (data.reference && (data.reference.message || data.reference.threadId)) {
+                response.reference = {};
+                if (data.reference.message) {
+                    response.reference.message = data.reference.message;
+                    response.reference.documentStore = documentStoreUsed;
+                    response.reference.success = referencedMessage ? true : false;
+                    if (!referencedMessage) {
+                        response.reference.error = 'Referenced message was not found';
+                    }
+                }
+                if (data.reference.threadId) {
+                    response.reference.threadId = data.reference.threadId;
                 }
             }
 
@@ -2069,15 +2072,18 @@ class BaseClient {
             queueId
         };
 
-        if (data.reference && data.reference.message) {
-            response.reference = {
-                message: data.reference.message,
-                documentStore: documentStoreUsed,
-                success: referencedMessage ? true : false
-            };
-
-            if (!referencedMessage) {
-                response.reference.error = 'Referenced message was not found';
+        if (data.reference && (data.reference.message || data.reference.threadId)) {
+            response.reference = {};
+            if (data.reference.message) {
+                response.reference.message = data.reference.message;
+                response.reference.documentStore = documentStoreUsed;
+                response.reference.success = referencedMessage ? true : false;
+                if (!referencedMessage) {
+                    response.reference.error = 'Referenced message was not found';
+                }
+            }
+            if (data.reference.threadId) {
+                response.reference.threadId = data.reference.threadId;
             }
         }
 

package/lib/email-client/gmail-client.js

@@ -1502,9 +1502,8 @@ class GmailClient extends BaseClient {
             raw: raw.toString('base64url')
         };
 
-        // Maintain thread if replying
-        if (referencedMessage?.threadId) {
-            payload.threadId = referencedMessage.threadId;
+        if (data.reference?.threadId) {
+            payload.threadId = data.reference.threadId;
         }
 
         let uploadInfo;
@@ -1533,15 +1532,18 @@ class GmailClient extends BaseClient {
             messageId
         };
 
-        if (data.reference && data.reference.message) {
-            response.reference = {
-                message: data.reference.message,
-                documentStore: documentStoreUsed,
-                success: referencedMessage ? true : false
-            };
-
-            if (!referencedMessage) {
-                response.reference.error = 'Referenced message was not found';
+        if (data.reference && (data.reference.message || data.reference.threadId)) {
+            response.reference = {};
+            if (data.reference.message) {
+                response.reference.message = data.reference.message;
+                response.reference.documentStore = documentStoreUsed;
+                response.reference.success = referencedMessage ? true : false;
+                if (!referencedMessage) {
+                    response.reference.error = 'Referenced message was not found';
+                }
+            }
+            if (data.reference.threadId) {
+                response.reference.threadId = data.reference.threadId;
             }
         }
 

package/lib/oauth/external-account-config.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// Pure configuration helpers for Google external_account (Workload Identity
+// Federation) credentials. This module intentionally has NO heavy dependencies
+// (no Redis, no undici, no settings) so it can be imported from request
+// validation (lib/schemas.js) as well as the runtime signer without dragging in
+// the database layer.
+
+const ACCEPTED_SUBJECT_TOKEN_TYPES = new Set(['urn:ietf:params:oauth:token-type:jwt', 'urn:ietf:params:oauth:token-type:id_token']);
+const IMPERSONATION_URL_RE = /\/v1\/projects\/-\/serviceAccounts\/([^/]+):generateAccessToken$/;
+
+function makeError(message, code, statusCode, extra) {
+    let err = new Error(message);
+    err.code = code;
+    if (statusCode) {
+        err.statusCode = statusCode;
+    }
+    if (extra && typeof extra === 'object') {
+        Object.assign(err, extra);
+    }
+    return err;
+}
+
+// Validates the structural shape of an external_account credential config and
+// returns the derived target service account email. Throws an error tagged with
+// code 'EExternalAccountConfig' on any problem so callers can surface a clean
+// validation message instead of a late runtime failure.
+function validateConfig(config) {
+    if (!config || typeof config !== 'object') {
+        throw makeError('External account configuration must be a JSON object', 'EExternalAccountConfig');
+    }
+
+    if (config.type !== 'external_account') {
+        throw makeError(`External account configuration must have type "external_account" (got ${JSON.stringify(config.type)})`, 'EExternalAccountConfig');
+    }
+
+    for (let key of ['audience', 'subject_token_type', 'token_url', 'service_account_impersonation_url']) {
+        let value = config[key];
+        if (typeof value !== 'string' || !value) {
+            throw makeError(`External account configuration is missing required string field "${key}"`, 'EExternalAccountConfig');
+        }
+    }
+
+    if (!ACCEPTED_SUBJECT_TOKEN_TYPES.has(config.subject_token_type)) {
+        throw makeError(
+            `External account subject_token_type ${JSON.stringify(config.subject_token_type)} is not supported. ` +
+                `Supported types: ${Array.from(ACCEPTED_SUBJECT_TOKEN_TYPES).join(', ')}.`,
+            'EExternalAccountConfig'
+        );
+    }
+
+    let impersonationMatch = IMPERSONATION_URL_RE.exec(config.service_account_impersonation_url);
+    if (!impersonationMatch) {
+        throw makeError(
+            'External account service_account_impersonation_url must point at iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/{EMAIL}:generateAccessToken',
+            'EExternalAccountConfig'
+        );
+    }
+    let targetServiceAccountEmail = decodeURIComponent(impersonationMatch[1]);
+
+    let source = config.credential_source;
+    if (!source || typeof source !== 'object') {
+        throw makeError('External account configuration is missing credential_source', 'EExternalAccountConfig');
+    }
+
+    let hasFile = typeof source.file === 'string' && source.file;
+    let hasUrl = typeof source.url === 'string' && source.url;
+    let hasExecutable = source.executable && typeof source.executable === 'object';
+    let hasEnvironmentId = typeof source.environment_id === 'string' && source.environment_id;
+
+    if (hasExecutable) {
+        throw makeError('credential_source.executable is not supported by EmailEngine', 'EExternalAccountConfig');
+    }
+    if (hasEnvironmentId) {
+        throw makeError(
+            `credential_source.environment_id (${source.environment_id}) is not supported by EmailEngine. Use a file or url credential source.`,
+            'EExternalAccountConfig'
+        );
+    }
+    if (hasFile && hasUrl) {
+        throw makeError('credential_source must specify either "file" or "url", not both', 'EExternalAccountConfig');
+    }
+    if (!hasFile && !hasUrl) {
+        throw makeError('credential_source must specify a "file" or "url" field', 'EExternalAccountConfig');
+    }
+
+    if (source.format && typeof source.format === 'object') {
+        let formatType = source.format.type;
+        if (formatType && formatType !== 'text' && formatType !== 'json') {
+            throw makeError(`credential_source.format.type must be "text" or "json" (got ${JSON.stringify(formatType)})`, 'EExternalAccountConfig');
+        }
+        if (formatType === 'json' && (typeof source.format.subject_token_field_name !== 'string' || !source.format.subject_token_field_name)) {
+            throw makeError('credential_source.format.subject_token_field_name is required when format.type is "json"', 'EExternalAccountConfig');
+        }
+    }
+
+    return { targetServiceAccountEmail };
+}
+
+// Extracts the subject token string from a raw credential-source payload,
+// honouring the optional text/json format descriptor.
+function extractFromFormat(rawText, format) {
+    let formatType = (format && format.type) || 'text';
+    if (formatType === 'text') {
+        let trimmed = rawText.trim();
+        if (!trimmed) {
+            throw makeError('Subject token source returned an empty value', 'ESubjectTokenRead');
+        }
+        return trimmed;
+    }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(rawText);
+    } catch (err) {
+        throw makeError(`Subject token source did not return valid JSON: ${err.message}`, 'ESubjectTokenRead');
+    }
+    let field = format.subject_token_field_name;
+    let value = parsed && typeof parsed === 'object' ? parsed[field] : undefined;
+    if (typeof value !== 'string' || !value.trim()) {
+        throw makeError(`Subject token JSON did not contain a non-empty string at field "${field}"`, 'ESubjectTokenRead');
+    }
+    return value.trim();
+}
+
+module.exports = {
+    ACCEPTED_SUBJECT_TOKEN_TYPES,
+    IMPERSONATION_URL_RE,
+    makeError,
+    validateConfig,
+    extractFromFormat
+};

package/lib/oauth/external-account-signer.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const fs = require('fs');
+const { fetch: undiciFetch } = require('undici');
+const packageData = require('../../package.json');
+const { httpAgent } = require('../tools');
+const { makeError, validateConfig, extractFromFormat } = require('./external-account-config');
+
+const STS_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:token-exchange';
+const REQUESTED_TOKEN_TYPE = 'urn:ietf:params:oauth:token-type:access_token';
+const CLOUD_PLATFORM_SCOPE = 'https://www.googleapis.com/auth/cloud-platform';
+const DEFAULT_IAM_CREDENTIALS_BASE_URL = 'https://iamcredentials.googleapis.com';
+const SIGN_JWT_URL_TEMPLATE = '/v1/projects/-/serviceAccounts/{email}:signJwt';
+const TOKEN_EXPIRY_SKEW_MS = 60 * 1000;
+const DEFAULT_FEDERATED_TOKEN_TTL_MS = 3600 * 1000;
+const USER_AGENT = `${packageData.name}/${packageData.version} (+${packageData.homepage})`;
+
+class ExternalAccountSigner {
+    constructor(opts) {
+        opts = opts || {};
+
+        let { targetServiceAccountEmail } = validateConfig(opts.config);
+
+        this.config = opts.config;
+        // The service account whose Google-managed key signs the JWT. Exposed so
+        // callers can keep the JWT `iss` claim consistent with the signing identity.
+        this.serviceAccountEmail = targetServiceAccountEmail;
+        this.logger = opts.logger || null;
+        this.logRaw = !!opts.logRaw;
+
+        // Injection points for tests; production code uses undici/fs/Date as defaults.
+        this._fetch = opts.fetchImpl || undiciFetch;
+        this._readFile = opts.readFileImpl || fs.promises.readFile;
+        this._now = opts.nowImpl || (() => Date.now());
+
+        // Allow overriding the IAM Credentials base URL so integration tests
+        // (and unusual forward-proxy deployments) can redirect signJwt traffic.
+        this._iamCredentialsBaseUrl = (opts.iamCredentialsBaseUrl || DEFAULT_IAM_CREDENTIALS_BASE_URL).replace(/\/+$/, '');
+
+        this._cachedToken = null;
+        this._cachedTokenExpiresAt = 0;
+        this._pendingRefresh = null;
+    }
+
+    describeCredentialSource() {
+        let source = this.config.credential_source;
+        if (source.file) {
+            return { type: 'file', location: source.file };
+        }
+        return { type: 'url', location: source.url };
+    }
+
+    async _readSubjectToken() {
+        let source = this.config.credential_source;
+        let format = source.format || { type: 'text' };
+
+        if (source.file) {
+            let rawText;
+            try {
+                rawText = await this._readFile(source.file, 'utf8');
+            } catch (err) {
+                throw makeError(`Failed to read subject token file ${source.file}: ${err.message}`, 'ESubjectTokenRead', null, { cause: err });
+            }
+            return extractFromFormat(rawText, format);
+        }
+
+        let headers = { 'User-Agent': USER_AGENT };
+        if (source.headers && typeof source.headers === 'object') {
+            for (let key of Object.keys(source.headers)) {
+                headers[key] = source.headers[key];
+            }
+        }
+
+        let res;
+        try {
+            res = await this._fetch(source.url, {
+                method: 'GET',
+                headers,
+                dispatcher: httpAgent.retry
+            });
+        } catch (err) {
+            throw makeError(`Failed to fetch subject token from ${source.url}: ${err.message}`, 'ESubjectTokenRead', null, { cause: err });
+        }
+
+        let body = await res.text();
+
+        this._log('readSubjectToken', 'GET', source.url, res.ok, res.status);
+
+        if (!res.ok) {
+            throw makeError(`Subject token endpoint ${source.url} returned HTTP ${res.status}`, 'ESubjectTokenRead', res.status, {
+                responseText: body.slice(0, 1024)
+            });
+        }
+
+        return extractFromFormat(body, format);
+    }
+
+    // Exchange the subject token for a Google federated access token. The
+    // federated identity (the workload principal) carries the cloud-platform
+    // scope and, given roles/iam.serviceAccountTokenCreator on the target
+    // service account, may call signJwt directly. Returns the access token and
+    // its absolute expiry so it can be cached and reused across signJwt calls.
+    async _exchangeAtSts(subjectToken) {
+        let body = new URLSearchParams({
+            grant_type: STS_GRANT_TYPE,
+            audience: this.config.audience,
+            scope: CLOUD_PLATFORM_SCOPE,
+            requested_token_type: REQUESTED_TOKEN_TYPE,
+            subject_token_type: this.config.subject_token_type,
+            subject_token: subjectToken
+        });
+
+        let res;
+        let responseJson;
+        try {
+            res = await this._fetch(this.config.token_url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Accept: 'application/json',
+                    'User-Agent': USER_AGENT
+                },
+                body: body.toString(),
+                dispatcher: httpAgent.retry
+            });
+            responseJson = await res.json().catch(() => null);
+        } catch (err) {
+            throw makeError(`STS token exchange request failed: ${err.message}`, 'ESTSExchange', null, { cause: err });
+        }
+
+        this._log('exchangeAtSts', 'POST', this.config.token_url, res.ok, res.status);
+
+        if (!res.ok) {
+            throw makeError(`STS token exchange at ${this.config.token_url} returned HTTP ${res.status}`, 'ESTSExchange', res.status, {
+                response: responseJson || null
+            });
+        }
+
+        let token = responseJson && responseJson.access_token;
+        if (typeof token !== 'string' || !token) {
+            throw makeError('STS response did not include an access_token', 'ESTSExchange', res.status, { response: responseJson || null });
+        }
+
+        let expiresInSec = responseJson && Number(responseJson.expires_in);
+        let ttlMs = Number.isFinite(expiresInSec) && expiresInSec > 0 ? expiresInSec * 1000 : DEFAULT_FEDERATED_TOKEN_TTL_MS;
+
+        return { accessToken: token, expiresAtMs: this._now() + ttlMs };
+    }
+
+    async _ensureFederatedToken() {
+        if (this._cachedToken && this._now() + TOKEN_EXPIRY_SKEW_MS < this._cachedTokenExpiresAt) {
+            return this._cachedToken;
+        }
+
+        // Deduplicate concurrent refreshes: when many accounts hit a cold cache
+        // at once, share the single in-flight exchange rather than stampeding STS
+        // with redundant token exchanges.
+        if (!this._pendingRefresh) {
+            this._pendingRefresh = (async () => {
+                try {
+                    let subjectToken = await this._readSubjectToken();
+                    let { accessToken, expiresAtMs } = await this._exchangeAtSts(subjectToken);
+                    this._cachedToken = accessToken;
+                    this._cachedTokenExpiresAt = expiresAtMs;
+                    return accessToken;
+                } finally {
+                    this._pendingRefresh = null;
+                }
+            })();
+        }
+
+        return this._pendingRefresh;
+    }
+
+    async _callSignJwt(accessToken, jwtPayload) {
+        let url = this._iamCredentialsBaseUrl + SIGN_JWT_URL_TEMPLATE.replace('{email}', encodeURIComponent(this.serviceAccountEmail));
+        let res;
+        let responseJson;
+        try {
+            res = await this._fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    Authorization: `Bearer ${accessToken}`,
+                    'User-Agent': USER_AGENT
+                },
+                body: JSON.stringify({ payload: JSON.stringify(jwtPayload) }),
+                dispatcher: httpAgent.retry
+            });
+            responseJson = await res.json().catch(() => null);
+        } catch (err) {
+            throw makeError(`signJwt request failed: ${err.message}`, 'ESignJwt', null, { cause: err });
+        }
+
+        this._log('callSignJwt', 'POST', url, res.ok, res.status);
+
+        if (!res.ok) {
+            let retryAfter = null;
+            if (res.status === 429) {
+                let header = res.headers.get('retry-after');
+                if (header) {
+                    let parsed = parseInt(header, 10);
+                    retryAfter = isNaN(parsed) ? null : parsed;
+                }
+            }
+            throw makeError(`signJwt returned HTTP ${res.status}`, 'ESignJwt', res.status, {
+                response: responseJson || null,
+                retryAfter
+            });
+        }
+
+        let signedJwt = responseJson && responseJson.signedJwt;
+        if (typeof signedJwt !== 'string' || !signedJwt) {
+            throw makeError('signJwt response did not include signedJwt', 'ESignJwt', res.status, { response: responseJson || null });
+        }
+        return signedJwt;
+    }
+
+    /**
+     * Sign a JWT payload using the configured external account identity.
+     * Returns the compact JWT string suitable for the `assertion` parameter
+     * in a jwt-bearer grant exchange.
+     */
+    async sign(jwtPayload) {
+        let accessToken = await this._ensureFederatedToken();
+        return this._callSignJwt(accessToken, jwtPayload);
+    }
+
+    _log(fn, method, url, ok, status) {
+        if (!this.logger) {
+            return;
+        }
+        this.logger.info({
+            msg: 'External account signer request',
+            action: 'externalAccountFetch',
+            fn,
+            method,
+            url,
+            success: !!ok,
+            status,
+            credentialSource: this.describeCredentialSource().type,
+            targetServiceAccountEmail: this.serviceAccountEmail
+        });
+    }
+
+    // Test-only: clear the cached federated token.
+    _clearCache() {
+        this._cachedToken = null;
+        this._cachedTokenExpiresAt = 0;
+        this._pendingRefresh = null;
+    }
+}
+
+module.exports.ExternalAccountSigner = ExternalAccountSigner;
+module.exports.__test__ = { validateConfig, extractFromFormat, makeError };