chore: drop old client support (#14369)

packages/backend/server/src/base/error/def.ts

@@ -275,6 +275,26 @@ export const USER_FRIENDLY_ERRORS = {
     args: { message: 'string' },
     message: ({ message }) => `HTTP request error, message: ${message}`,
   },
+  ssrf_blocked_error: {
+    type: 'invalid_input',
+    args: { reason: 'string' },
+    message: ({ reason }) => {
+      switch (reason) {
+        case 'unresolvable_hostname':
+          return 'Failed to resolve hostname';
+        case 'too_many_redirects':
+          return 'Too many redirects';
+        default:
+          return 'Invalid URL';
+      }
+    },
+  },
+  response_too_large_error: {
+    type: 'invalid_input',
+    args: { limitBytes: 'number', receivedBytes: 'number' },
+    message: ({ limitBytes, receivedBytes }) =>
+      `Response too large (${receivedBytes} bytes), limit is ${limitBytes} bytes`,
+  },
   email_service_not_configured: {
     type: 'internal_server_error',
     message: 'Email service is not configured.',

packages/backend/server/src/base/error/errors.gen.ts

@@ -54,6 +54,27 @@ export class HttpRequestError extends UserFriendlyError {
     super('bad_request', 'http_request_error', message, args);
   }
 }
+@ObjectType()
+class SsrfBlockedErrorDataType {
+  @Field() reason!: string
+}
+
+export class SsrfBlockedError extends UserFriendlyError {
+  constructor(args: SsrfBlockedErrorDataType, message?: string | ((args: SsrfBlockedErrorDataType) => string)) {
+    super('invalid_input', 'ssrf_blocked_error', message, args);
+  }
+}
+@ObjectType()
+class ResponseTooLargeErrorDataType {
+  @Field() limitBytes!: number
+  @Field() receivedBytes!: number
+}
+
+export class ResponseTooLargeError extends UserFriendlyError {
+  constructor(args: ResponseTooLargeErrorDataType, message?: string | ((args: ResponseTooLargeErrorDataType) => string)) {
+    super('invalid_input', 'response_too_large_error', message, args);
+  }
+}
 
 export class EmailServiceNotConfigured extends UserFriendlyError {
   constructor(message?: string) {
@@ -1131,6 +1152,8 @@ export enum ErrorNames {
   BAD_REQUEST,
   GRAPHQL_BAD_REQUEST,
   HTTP_REQUEST_ERROR,
+  SSRF_BLOCKED_ERROR,
+  RESPONSE_TOO_LARGE_ERROR,
   EMAIL_SERVICE_NOT_CONFIGURED,
   QUERY_TOO_LONG,
   VALIDATION_ERROR,
@@ -1274,5 +1297,5 @@ registerEnumType(ErrorNames, {
 export const ErrorDataUnionType = createUnionType({
   name: 'ErrorDataUnion',
   types: () =>
-    [GraphqlBadRequestDataType, HttpRequestErrorDataType, QueryTooLongDataType, ValidationErrorDataType, WrongSignInCredentialsDataType, UnknownOauthProviderDataType, InvalidOauthCallbackCodeDataType, MissingOauthQueryParameterDataType, InvalidOauthResponseDataType, InvalidEmailDataType, InvalidPasswordLengthDataType, WorkspacePermissionNotFoundDataType, SpaceNotFoundDataType, MemberNotFoundInSpaceDataType, NotInSpaceDataType, AlreadyInSpaceDataType, SpaceAccessDeniedDataType, SpaceOwnerNotFoundDataType, SpaceShouldHaveOnlyOneOwnerDataType, DocNotFoundDataType, DocActionDeniedDataType, DocUpdateBlockedDataType, VersionRejectedDataType, InvalidHistoryTimestampDataType, DocHistoryNotFoundDataType, BlobNotFoundDataType, ExpectToGrantDocUserRolesDataType, ExpectToRevokeDocUserRolesDataType, ExpectToUpdateDocUserRoleDataType, NoMoreSeatDataType, UnsupportedSubscriptionPlanDataType, SubscriptionAlreadyExistsDataType, SubscriptionNotExistsDataType, SameSubscriptionRecurringDataType, SubscriptionPlanNotFoundDataType, CalendarProviderRequestErrorDataType, NoCopilotProviderAvailableDataType, CopilotFailedToGenerateEmbeddingDataType, CopilotDocNotFoundDataType, CopilotMessageNotFoundDataType, CopilotPromptNotFoundDataType, CopilotProviderNotSupportedDataType, CopilotProviderSideErrorDataType, CopilotInvalidContextDataType, CopilotContextFileNotSupportedDataType, CopilotFailedToModifyContextDataType, CopilotFailedToMatchContextDataType, CopilotFailedToMatchGlobalContextDataType, CopilotFailedToAddWorkspaceFileEmbeddingDataType, RuntimeConfigNotFoundDataType, InvalidRuntimeConfigTypeDataType, InvalidLicenseToActivateDataType, InvalidLicenseUpdateParamsDataType, UnsupportedClientVersionDataType, MentionUserDocAccessDeniedDataType, InvalidAppConfigDataType, InvalidAppConfigInputDataType, InvalidSearchProviderRequestDataType, InvalidIndexerInputDataType] as const,
+    [GraphqlBadRequestDataType, HttpRequestErrorDataType, SsrfBlockedErrorDataType, ResponseTooLargeErrorDataType, QueryTooLongDataType, ValidationErrorDataType, WrongSignInCredentialsDataType, UnknownOauthProviderDataType, InvalidOauthCallbackCodeDataType, MissingOauthQueryParameterDataType, InvalidOauthResponseDataType, InvalidEmailDataType, InvalidPasswordLengthDataType, WorkspacePermissionNotFoundDataType, SpaceNotFoundDataType, MemberNotFoundInSpaceDataType, NotInSpaceDataType, AlreadyInSpaceDataType, SpaceAccessDeniedDataType, SpaceOwnerNotFoundDataType, SpaceShouldHaveOnlyOneOwnerDataType, DocNotFoundDataType, DocActionDeniedDataType, DocUpdateBlockedDataType, VersionRejectedDataType, InvalidHistoryTimestampDataType, DocHistoryNotFoundDataType, BlobNotFoundDataType, ExpectToGrantDocUserRolesDataType, ExpectToRevokeDocUserRolesDataType, ExpectToUpdateDocUserRoleDataType, NoMoreSeatDataType, UnsupportedSubscriptionPlanDataType, SubscriptionAlreadyExistsDataType, SubscriptionNotExistsDataType, SameSubscriptionRecurringDataType, SubscriptionPlanNotFoundDataType, CalendarProviderRequestErrorDataType, NoCopilotProviderAvailableDataType, CopilotFailedToGenerateEmbeddingDataType, CopilotDocNotFoundDataType, CopilotMessageNotFoundDataType, CopilotPromptNotFoundDataType, CopilotProviderNotSupportedDataType, CopilotProviderSideErrorDataType, CopilotInvalidContextDataType, CopilotContextFileNotSupportedDataType, CopilotFailedToModifyContextDataType, CopilotFailedToMatchContextDataType, CopilotFailedToMatchGlobalContextDataType, CopilotFailedToAddWorkspaceFileEmbeddingDataType, RuntimeConfigNotFoundDataType, InvalidRuntimeConfigTypeDataType, InvalidLicenseToActivateDataType, InvalidLicenseUpdateParamsDataType, UnsupportedClientVersionDataType, MentionUserDocAccessDeniedDataType, InvalidAppConfigDataType, InvalidAppConfigInputDataType, InvalidSearchProviderRequestDataType, InvalidIndexerInputDataType] as const,
 });

packages/backend/server/src/base/helpers/__tests__/crypto.spec.ts

@@ -1,3 +1,5 @@
+import { generateKeyPairSync } from 'node:crypto';
+
 import ava, { TestFn } from 'ava';
 import Sinon from 'sinon';
 
@@ -7,11 +9,20 @@ const test = ava as TestFn<{
   crypto: CryptoHelper;
 }>;
 
-const privateKey = `-----BEGIN PRIVATE KEY-----
-MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgS3IAkshQuSmFWGpe
-rGTg2vwaC3LdcvBQlYHHMBYJZMyhRANCAAQXdT/TAh4neNEpd4UqpDIEqWv0XvFo
-BRJxGsC5I/fetqObdx1+KEjcm8zFU2xLaUTw9IZCu8OslloOjQv4ur0a
------END PRIVATE KEY-----`;
+function generateTestPrivateKey(): string {
+  const { privateKey } = generateKeyPairSync('ec', {
+    namedCurve: 'prime256v1',
+  });
+  return privateKey
+    .export({
+      type: 'pkcs8',
+      format: 'pem',
+    })
+    .toString();
+}
+
+const privateKey = generateTestPrivateKey();
+const privateKey2 = generateTestPrivateKey();
 
 test.beforeEach(async t => {
   t.context.crypto = new CryptoHelper({
@@ -30,6 +41,21 @@ test('should be able to sign and verify', t => {
   t.false(t.context.crypto.verify(`${data},fake-signature`));
 });
 
+test('should verify signatures across key rotation', t => {
+  const data = 'hello world';
+  const signatureV1 = t.context.crypto.sign(data);
+  t.true(t.context.crypto.verify(signatureV1));
+
+  (t.context.crypto as any).config.crypto.privateKey = privateKey2;
+  t.context.crypto.onConfigChanged({
+    updates: { crypto: { privateKey: privateKey2 } },
+  } as any);
+
+  const signatureV2 = t.context.crypto.sign(data);
+  t.true(t.context.crypto.verify(signatureV1));
+  t.true(t.context.crypto.verify(signatureV2));
+});
+
 test('should same data should get different signature', t => {
   const data = 'hello world';
   const signature = t.context.crypto.sign(data);
@@ -46,11 +72,12 @@ test('should be able to encrypt and decrypt', t => {
   );
 
   const encrypted = t.context.crypto.encrypt(data);
+  const encrypted2 = t.context.crypto.encrypt(data);
   const decrypted = t.context.crypto.decrypt(encrypted);
 
   // we are using a stub to make sure the iv is always 0,
-  // the encrypted result will always be the same
-  t.is(encrypted, 'AAAAAAAAAAAAAAAAOXbR/9glITL3BcO3kPd6fGOMasSkPQ==');
+  // the encrypted result will always be the same for the same key+data
+  t.is(encrypted2, encrypted);
   t.is(decrypted, data);
 
   stub.restore();
@@ -75,6 +102,24 @@ test('should be able to safe compare', t => {
   t.false(t.context.crypto.compare('abc', 'def'));
 });
 
+test('should sign and parse internal access token', t => {
+  const token = t.context.crypto.signInternalAccessToken({
+    method: 'GET',
+    path: '/rpc/workspaces/123/docs/456',
+    now: 1700000000000,
+    nonce: 'nonce-123',
+  });
+
+  const payload = t.context.crypto.parseInternalAccessToken(token);
+  t.deepEqual(payload, {
+    v: 1,
+    ts: 1700000000000,
+    nonce: 'nonce-123',
+    m: 'GET',
+    p: '/rpc/workspaces/123/docs/456',
+  });
+});
+
 test('should be able to hash and verify password', async t => {
   const password = 'mySecurePassword';
   const hash = await t.context.crypto.encryptPassword(password);

packages/backend/server/src/base/helpers/__tests__/url.spec.ts

@@ -1,6 +1,7 @@
 import ava, { TestFn } from 'ava';
 import Sinon from 'sinon';
 
+import { ActionForbidden } from '../../error';
 import { URLHelper } from '../url';
 
 const test = ava as TestFn<{
@@ -85,6 +86,30 @@ test('can create link', t => {
   );
 });
 
+test('can validate callbackUrl allowlist', t => {
+  t.true(t.context.url.isAllowedCallbackUrl('/magic-link'));
+  t.true(
+    t.context.url.isAllowedCallbackUrl('https://app.affine.local/magic-link')
+  );
+  t.false(
+    t.context.url.isAllowedCallbackUrl('https://evil.example/magic-link')
+  );
+});
+
+test('can validate redirect_uri allowlist', t => {
+  t.true(t.context.url.isAllowedRedirectUri('/redirect-proxy'));
+  t.true(t.context.url.isAllowedRedirectUri('https://github.com'));
+  t.false(t.context.url.isAllowedRedirectUri('javascript:alert(1)'));
+  t.false(t.context.url.isAllowedRedirectUri('https://evilgithub.com'));
+});
+
+test('can create safe link', t => {
+  t.is(t.context.url.safeLink('/path'), 'https://app.affine.local/path');
+  t.throws(() => t.context.url.safeLink('https://evil.example/magic-link'), {
+    instanceOf: ActionForbidden,
+  });
+});
+
 test('can safe redirect', t => {
   const res = {
     redirect: (to: string) => to,

packages/backend/server/src/base/helpers/crypto.ts

@@ -76,6 +76,8 @@ export class CryptoHelper implements OnModuleInit {
     };
   };
 
+  private previousPublicKeys: KeyObject[] = [];
+
   AFFiNEProPublicKey: Buffer | null = null;
   AFFiNEProLicenseAESKey: Buffer | null = null;
 
@@ -101,12 +103,23 @@ export class CryptoHelper implements OnModuleInit {
   }
 
   private setup() {
+    const prevPublicKey = this.keyPair?.publicKey;
     const privateKey = this.config.crypto.privateKey || generatePrivateKey();
     const { priv, pub } = parseKey(privateKey);
     const publicKey = pub
       .export({ format: 'pem', type: 'spki' })
       .toString('utf8');
 
+    if (prevPublicKey) {
+      const prevPem = prevPublicKey
+        .export({ format: 'pem', type: 'spki' })
+        .toString('utf8');
+      if (prevPem !== publicKey) {
+        this.previousPublicKeys.unshift(prevPublicKey);
+        this.previousPublicKeys = this.previousPublicKeys.slice(0, 2);
+      }
+    }
+
     this.keyPair = {
       publicKey: pub,
       privateKey: priv,
@@ -143,15 +156,81 @@ export class CryptoHelper implements OnModuleInit {
     }
     const input = Buffer.from(data, 'utf-8');
     const sigBuf = Buffer.from(signature, 'base64');
-    if (this.keyType === 'ed25519') {
-      // Ed25519 verifies the message directly
-      return verify(null, input, this.keyPair.publicKey, sigBuf);
-    } else {
-      // ECDSA with SHA-256
-      const verify = createVerify('sha256');
-      verify.update(input);
-      verify.end();
-      return verify.verify(this.keyPair.publicKey, sigBuf);
+
+    const keys = [this.keyPair.publicKey, ...this.previousPublicKeys];
+    return keys.some(publicKey => {
+      const keyType = (publicKey.asymmetricKeyType as string) || 'ec';
+      if (keyType === 'ed25519') {
+        // Ed25519 verifies the message directly
+        return verify(null, input, publicKey, sigBuf);
+      } else {
+        // ECDSA with SHA-256
+        const verifier = createVerify('sha256');
+        verifier.update(input);
+        verifier.end();
+        return verifier.verify(publicKey, sigBuf);
+      }
+    });
+  }
+
+  signInternalAccessToken(input: {
+    method: string;
+    path: string;
+    now?: number;
+    nonce?: string;
+  }) {
+    const payload = {
+      v: 1 as const,
+      ts: input.now ?? Date.now(),
+      nonce: input.nonce ?? this.randomBytes(16).toString('base64url'),
+      m: input.method.toUpperCase(),
+      p: input.path,
+    };
+    const data = Buffer.from(JSON.stringify(payload), 'utf8').toString(
+      'base64url'
+    );
+    return this.sign(data);
+  }
+
+  parseInternalAccessToken(signatureWithData: string): {
+    v: 1;
+    ts: number;
+    nonce: string;
+    m: string;
+    p: string;
+  } | null {
+    const [data, signature] = signatureWithData.split(',');
+    if (!signature) {
+      return null;
+    }
+    if (!this.verify(signatureWithData)) {
+      return null;
+    }
+    try {
+      const json = Buffer.from(data, 'base64url').toString('utf8');
+      const payload = JSON.parse(json) as unknown;
+      if (!payload || typeof payload !== 'object') {
+        return null;
+      }
+      const val = payload as {
+        v?: unknown;
+        ts?: unknown;
+        nonce?: unknown;
+        m?: unknown;
+        p?: unknown;
+      };
+      if (
+        val.v !== 1 ||
+        typeof val.ts !== 'number' ||
+        typeof val.nonce !== 'string' ||
+        typeof val.m !== 'string' ||
+        typeof val.p !== 'string'
+      ) {
+        return null;
+      }
+      return { v: 1, ts: val.ts, nonce: val.nonce, m: val.m, p: val.p };
+    } catch {
+      return null;
     }
   }
 

packages/backend/server/src/base/helpers/url.ts

@@ -5,8 +5,31 @@ import type { Response } from 'express';
 import { ClsService } from 'nestjs-cls';
 
 import { Config } from '../config';
+import { ActionForbidden } from '../error';
 import { OnEvent } from '../event';
 
+const ALLOWED_REDIRECT_PROTOCOLS = new Set(['http:', 'https:']);
+// Keep in sync with frontend /redirect-proxy allowlist.
+const TRUSTED_REDIRECT_DOMAINS = [
+  'google.com',
+  'stripe.com',
+  'github.com',
+  'twitter.com',
+  'discord.gg',
+  'youtube.com',
+  't.me',
+  'reddit.com',
+  'affine.pro',
+].map(d => d.toLowerCase());
+
+function normalizeHostname(hostname: string) {
+  return hostname.toLowerCase().replace(/\.$/, '');
+}
+
+function hostnameMatchesDomain(hostname: string, domain: string) {
+  return hostname === domain || hostname.endsWith(`.${domain}`);
+}
+
 @Injectable()
 export class URLHelper {
   redirectAllowHosts!: string[];
@@ -110,6 +133,13 @@ export class URLHelper {
     return this.url(path, query).toString();
   }
 
+  safeLink(path: string, query: Record<string, any> = {}) {
+    if (!this.isAllowedCallbackUrl(path)) {
+      throw new ActionForbidden();
+    }
+    return this.link(path, query);
+  }
+
   safeRedirect(res: Response, to: string) {
     try {
       const finalTo = new URL(decodeURIComponent(to), this.requestBaseUrl);
@@ -131,6 +161,68 @@ export class URLHelper {
     return res.redirect(this.baseUrl);
   }
 
+  isAllowedCallbackUrl(url: string): boolean {
+    if (!url) {
+      return false;
+    }
+
+    // Allow same-app relative paths (e.g. `/magic-link?...`).
+    if (url.startsWith('/') && !url.startsWith('//')) {
+      return true;
+    }
+
+    try {
+      const u = new URL(url);
+      if (!ALLOWED_REDIRECT_PROTOCOLS.has(u.protocol)) {
+        return false;
+      }
+      if (u.username || u.password) {
+        return false;
+      }
+      return this.allowedOrigins.includes(u.origin);
+    } catch {
+      return false;
+    }
+  }
+
+  isAllowedRedirectUri(redirectUri: string): boolean {
+    if (!redirectUri) {
+      return false;
+    }
+
+    // Allow internal navigation (e.g. `/` or `/redirect-proxy?...`).
+    if (redirectUri.startsWith('/') && !redirectUri.startsWith('//')) {
+      return true;
+    }
+
+    try {
+      const u = new URL(redirectUri);
+      if (!ALLOWED_REDIRECT_PROTOCOLS.has(u.protocol)) {
+        return false;
+      }
+      if (u.username || u.password) {
+        return false;
+      }
+
+      const hostname = normalizeHostname(u.hostname);
+
+      // Allow server known hosts.
+      for (const origin of this.allowedOrigins) {
+        const allowedHost = normalizeHostname(new URL(origin).hostname);
+        if (hostname === allowedHost) {
+          return true;
+        }
+      }
+
+      // Allow known trusted domains (for redirect-proxy).
+      return TRUSTED_REDIRECT_DOMAINS.some(domain =>
+        hostnameMatchesDomain(hostname, domain)
+      );
+    } catch {
+      return false;
+    }
+  }
+
   verify(url: string | URL) {
     try {
       if (typeof url === 'string') {

packages/backend/server/src/base/utils/index.ts

@@ -1,6 +1,7 @@
 export * from './duration';
 export * from './promise';
 export * from './request';
+export * from './ssrf';
 export * from './stream';
 export * from './types';
 export * from './unit';

packages/backend/server/src/base/utils/ssrf.ts

@@ -0,0 +1,364 @@
+import * as dns from 'node:dns/promises';
+import { BlockList, isIP } from 'node:net';
+import { Readable } from 'node:stream';
+
+import { ResponseTooLargeError, SsrfBlockedError } from '../error/errors.gen';
+import { OneMinute } from './unit';
+
+const DEFAULT_ALLOWED_PROTOCOLS = new Set(['http:', 'https:']);
+const BLOCKED_IPS = new BlockList();
+const ALLOWED_IPV6 = new BlockList();
+
+export type DnsLookup = typeof dns.lookup;
+let dnsLookup: DnsLookup = dns.lookup;
+
+export function __setDnsLookupForTests(lookup: DnsLookup) {
+  dnsLookup = lookup;
+}
+
+export function __resetDnsLookupForTests() {
+  dnsLookup = dns.lookup;
+}
+
+export type SSRFBlockReason =
+  | 'invalid_url'
+  | 'disallowed_protocol'
+  | 'url_has_credentials'
+  | 'blocked_hostname'
+  | 'unresolvable_hostname'
+  | 'blocked_ip'
+  | 'too_many_redirects';
+
+type SsrfErrorContext = { url?: string; hostname?: string; address?: string };
+
+function createSsrfBlockedError(
+  reason: SSRFBlockReason,
+  context?: SsrfErrorContext
+) {
+  const err = new SsrfBlockedError({ reason });
+  // For logging/debugging only (not part of UserFriendlyError JSON).
+  (err as any).context = context;
+  return err;
+}
+
+export interface SSRFProtectionOptions {
+  allowedProtocols?: ReadonlySet<string>;
+  /**
+   * Allow fetching private/reserved IPs when URL.origin is allowlisted.
+   * Defaults to an empty allowlist (i.e. private IPs are blocked).
+   */
+  allowPrivateOrigins?: ReadonlySet<string>;
+}
+
+function stripZoneId(address: string) {
+  const idx = address.indexOf('%');
+  return idx === -1 ? address : address.slice(0, idx);
+}
+
+// IPv4: RFC1918 + loopback + link-local + CGNAT + special/reserved
+for (const [network, prefix] of [
+  ['0.0.0.0', 8],
+  ['10.0.0.0', 8],
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16],
+  ['172.16.0.0', 12],
+  ['192.168.0.0', 16],
+  ['100.64.0.0', 10], // CGNAT
+  ['192.0.0.0', 24],
+  ['192.0.2.0', 24], // TEST-NET-1
+  ['198.51.100.0', 24], // TEST-NET-2
+  ['203.0.113.0', 24], // TEST-NET-3
+  ['198.18.0.0', 15], // benchmark
+  ['192.88.99.0', 24], // 6to4 relay
+  ['224.0.0.0', 4], // multicast
+  ['240.0.0.0', 4], // reserved (includes broadcast)
+] as const) {
+  BLOCKED_IPS.addSubnet(network, prefix, 'ipv4');
+}
+
+// IPv6: block loopback/unspecified/link-local/ULA/multicast/doc; allow only global unicast.
+BLOCKED_IPS.addAddress('::', 'ipv6');
+BLOCKED_IPS.addAddress('::1', 'ipv6');
+BLOCKED_IPS.addSubnet('ff00::', 8, 'ipv6'); // multicast
+BLOCKED_IPS.addSubnet('fc00::', 7, 'ipv6'); // unique local
+BLOCKED_IPS.addSubnet('fe80::', 10, 'ipv6'); // link-local
+BLOCKED_IPS.addSubnet('2001:db8::', 32, 'ipv6'); // documentation
+ALLOWED_IPV6.addSubnet('2000::', 3, 'ipv6'); // global unicast
+
+function extractEmbeddedIPv4FromIPv6(address: string): string | null {
+  if (!address.includes('.')) {
+    return null;
+  }
+  const idx = address.lastIndexOf(':');
+  if (idx === -1) {
+    return null;
+  }
+  const tail = address.slice(idx + 1);
+  return isIP(tail) === 4 ? tail : null;
+}
+
+function isBlockedIpAddress(address: string): boolean {
+  const ip = stripZoneId(address);
+  const family = isIP(ip);
+  if (family === 4) {
+    return BLOCKED_IPS.check(ip, 'ipv4');
+  }
+  if (family === 6) {
+    const embeddedV4 = extractEmbeddedIPv4FromIPv6(ip);
+    if (embeddedV4) {
+      return isBlockedIpAddress(embeddedV4);
+    }
+    if (!ALLOWED_IPV6.check(ip, 'ipv6')) {
+      return true;
+    }
+    return BLOCKED_IPS.check(ip, 'ipv6');
+  }
+  return true;
+}
+
+async function resolveHostAddresses(hostname: string): Promise<string[]> {
+  // Normalize common localhost aliases without DNS.
+  const lowered = hostname.toLowerCase();
+  if (lowered === 'localhost' || lowered.endsWith('.localhost')) {
+    return ['127.0.0.1', '::1'];
+  }
+
+  const results = await dnsLookup(hostname, {
+    all: true,
+    verbatim: true,
+  });
+  return results.map(r => r.address);
+}
+
+export async function assertSsrFSafeUrl(
+  rawUrl: string | URL,
+  options: SSRFProtectionOptions = {}
+): Promise<URL> {
+  const allowedProtocols =
+    options.allowedProtocols ?? DEFAULT_ALLOWED_PROTOCOLS;
+
+  let url: URL;
+  try {
+    url = rawUrl instanceof URL ? rawUrl : new URL(rawUrl);
+  } catch {
+    throw createSsrfBlockedError('invalid_url', {
+      url: typeof rawUrl === 'string' ? rawUrl : undefined,
+    });
+  }
+
+  if (!allowedProtocols.has(url.protocol)) {
+    throw createSsrfBlockedError('disallowed_protocol', {
+      url: url.toString(),
+    });
+  }
+
+  if (url.username || url.password) {
+    throw createSsrfBlockedError('url_has_credentials', {
+      url: url.toString(),
+    });
+  }
+
+  const hostname = url.hostname;
+  if (!hostname) {
+    throw createSsrfBlockedError('blocked_hostname', { url: url.toString() });
+  }
+
+  const allowPrivate =
+    options.allowPrivateOrigins && options.allowPrivateOrigins.has(url.origin);
+
+  // IP literal
+  if (isIP(hostname)) {
+    if (isBlockedIpAddress(hostname) && !allowPrivate) {
+      throw createSsrfBlockedError('blocked_ip', {
+        url: url.toString(),
+        address: hostname,
+      });
+    }
+    return url;
+  }
+
+  let addresses: string[];
+  try {
+    addresses = await resolveHostAddresses(hostname);
+  } catch (error) {
+    throw createSsrfBlockedError('unresolvable_hostname', {
+      url: url.toString(),
+      hostname,
+    });
+  }
+
+  if (addresses.length === 0) {
+    throw createSsrfBlockedError('unresolvable_hostname', {
+      url: url.toString(),
+      hostname,
+    });
+  }
+
+  for (const address of addresses) {
+    if (isBlockedIpAddress(address) && !allowPrivate) {
+      throw createSsrfBlockedError('blocked_ip', {
+        url: url.toString(),
+        hostname,
+        address,
+      });
+    }
+  }
+
+  return url;
+}
+
+export interface SafeFetchOptions extends SSRFProtectionOptions {
+  timeoutMs?: number;
+  maxRedirects?: number;
+}
+
+export async function safeFetch(
+  rawUrl: string | URL,
+  init: RequestInit = {},
+  options: SafeFetchOptions = {}
+): Promise<Response> {
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const maxRedirects = options.maxRedirects ?? 3;
+
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const signal = init.signal
+    ? AbortSignal.any([init.signal, timeoutSignal])
+    : timeoutSignal;
+
+  let current = await assertSsrFSafeUrl(rawUrl, options);
+  let redirects = 0;
+
+  // Always handle redirects manually (SSRF-safe on each hop).
+  let requestInit: RequestInit = {
+    ...init,
+    redirect: 'manual',
+    signal,
+  };
+
+  while (true) {
+    const response = await fetch(current, requestInit);
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get('location');
+      if (!location) {
+        return response;
+      }
+
+      // Drain/cancel body before following redirect to avoid leaking resources.
+      try {
+        await response.body?.cancel();
+      } catch {
+        // ignore
+      }
+
+      if (redirects >= maxRedirects) {
+        throw createSsrfBlockedError('too_many_redirects', {
+          url: current.toString(),
+        });
+      }
+
+      const next = new URL(location, current);
+      current = await assertSsrFSafeUrl(next, options);
+      redirects += 1;
+
+      // 303 forces GET semantics
+      if (
+        response.status === 303 &&
+        requestInit.method &&
+        requestInit.method !== 'GET'
+      ) {
+        requestInit = { ...requestInit, method: 'GET', body: undefined };
+      }
+
+      continue;
+    }
+
+    return response;
+  }
+}
+
+export async function readResponseBufferWithLimit(
+  response: Response,
+  limitBytes: number
+): Promise<Buffer> {
+  const rawLen = response.headers.get('content-length');
+  if (rawLen) {
+    const len = Number.parseInt(rawLen, 10);
+    if (Number.isFinite(len) && len > limitBytes) {
+      try {
+        await response.body?.cancel();
+      } catch {
+        // ignore
+      }
+      throw new ResponseTooLargeError({ limitBytes, receivedBytes: len });
+    }
+  }
+
+  if (!response.body) {
+    return Buffer.alloc(0);
+  }
+
+  // Convert Web ReadableStream -> Node Readable for consistent limit handling.
+  const nodeStream = Readable.fromWeb(response.body);
+  const chunks: Buffer[] = [];
+  let total = 0;
+
+  try {
+    for await (const chunk of nodeStream) {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buf.length;
+      if (total > limitBytes) {
+        try {
+          nodeStream.destroy();
+        } catch {
+          // ignore
+        }
+        throw new ResponseTooLargeError({ limitBytes, receivedBytes: total });
+      }
+      chunks.push(buf);
+    }
+  } finally {
+    if (total > limitBytes) {
+      try {
+        await response.body?.cancel();
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  return Buffer.concat(chunks, total);
+}
+
+type FetchBufferResult = { buffer: Buffer; type: string };
+const ATTACH_GET_PARAMS = { timeoutMs: OneMinute / 6, maxRedirects: 3 };
+
+export async function fetchBuffer(
+  url: string,
+  limit: number,
+  contentType?: string
+): Promise<FetchBufferResult> {
+  const resp = url.startsWith('data:')
+    ? await fetch(url)
+    : await safeFetch(url, { method: 'GET' }, ATTACH_GET_PARAMS);
+
+  if (!resp.ok) {
+    throw new Error(
+      `Failed to fetch attachment: ${resp.status} ${resp.statusText}`
+    );
+  }
+  const type = resp.headers.get('content-type') || 'application/octet-stream';
+  if (contentType && !type.startsWith(contentType)) {
+    throw new Error(
+      `Attachment content-type mismatch: expected ${contentType} but got ${type}`
+    );
+  }
+  const buffer = await readResponseBufferWithLimit(resp, limit);
+  return { buffer, type: type };
+}
+
+export function bufferToArrayBuffer(buffer: Buffer): ArrayBuffer {
+  const copy = new Uint8Array(buffer.byteLength);
+  copy.set(buffer);
+  return copy.buffer;
+}