├── .gitignore
├── example
    ├── ens.png
    ├── build.js
    ├── node.js
    └── browser.js
├── .npmignore
├── src
    ├── utils
    │   ├── assert.ts
    │   ├── error.ts
    │   ├── isCID.ts
    │   ├── handleSettled.ts
    │   ├── detectPlatform.ts
    │   ├── index.ts
    │   ├── parseNFT.ts
    │   ├── getImageURI.ts
    │   ├── resolveURI.ts
    │   ├── fetch.ts
    │   ├── isImageURI.ts
    │   └── sanitize.ts
    ├── specs
    │   ├── uri.ts
    │   ├── erc721.ts
    │   └── erc1155.ts
    ├── types.ts
    └── index.ts
├── .github
    └── workflows
    │   ├── size.yml
    │   ├── main.yml
    │   └── pages.yml
├── test
    ├── setup.js
    ├── utils.test.ts
    └── resolver.test.ts
├── LICENSE
├── rollup.config.mjs
├── tsconfig.json
├── index.html
├── package.json
├── README.md
└── SECURITY.md


/.gitignore:
--------------------------------------------------------------------------------
1 | *.log
2 | .DS_Store
3 | .env
4 | node_modules
5 | coverage
6 | dist
7 | 


--------------------------------------------------------------------------------
/example/ens.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/ensdomains/ens-avatar/HEAD/example/ens.png


--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
 1 | *.log
 2 | .DS_Store
 3 | .env
 4 | .github
 5 | coverage
 6 | example
 7 | node_modules
 8 | test
 9 | .gitignore
10 | tsconfig.json
11 | yarn.lock
12 | 


--------------------------------------------------------------------------------
/src/utils/assert.ts:
--------------------------------------------------------------------------------
1 | // simple assert without nested check
2 | export function assert(condition: any, message: string) {
3 |   if (!condition) {
4 |     throw message;
5 |   }
6 | }
7 | 


--------------------------------------------------------------------------------
/src/utils/error.ts:
--------------------------------------------------------------------------------
 1 | export interface BaseError {}
 2 | export class BaseError extends Error {
 3 |   __proto__: Error;
 4 |   constructor(message?: string) {
 5 |     const trueProto = new.target.prototype;
 6 |     super(message);
 7 | 
 8 |     this.__proto__ = trueProto;
 9 |   }
10 | }
11 | 


--------------------------------------------------------------------------------
/.github/workflows/size.yml:
--------------------------------------------------------------------------------
 1 | name: size
 2 | on: [pull_request]
 3 | jobs:
 4 |   size:
 5 |     runs-on: ubuntu-latest
 6 |     env:
 7 |       CI_JOB_NUMBER: 1
 8 |     steps:
 9 |       - uses: actions/checkout@v1
10 |       - uses: andresz1/size-limit-action@v1
11 |         with:
12 |           github_token: ${{ secrets.GITHUB_TOKEN }}
13 | 


--------------------------------------------------------------------------------
/src/utils/isCID.ts:
--------------------------------------------------------------------------------
 1 | import { CID } from 'multiformats';
 2 | 
 3 | export function isCID(hash: any) {
 4 |   // check if given string or object is a valid IPFS CID
 5 |   try {
 6 |     if (typeof hash === 'string') {
 7 |       return Boolean(CID.parse(hash));
 8 |     }
 9 | 
10 |     return Boolean(CID.asCID(hash));
11 |   } catch (_error) {
12 |     return false;
13 |   }
14 | }
15 | 


--------------------------------------------------------------------------------
/src/utils/handleSettled.ts:
--------------------------------------------------------------------------------
 1 | export async function handleSettled(promises: Promise<any>[]) {
 2 |   const values = [];
 3 |   const results = await Promise.allSettled(promises);
 4 |   for (let result of results) {
 5 |     if (result.status === 'fulfilled') values.push(result.value);
 6 |     else if (result.status === 'rejected') values.push(null);
 7 |   }
 8 |   return values;
 9 | }
10 | 


--------------------------------------------------------------------------------
/src/utils/detectPlatform.ts:
--------------------------------------------------------------------------------
 1 | const isBrowser: boolean =
 2 |   typeof window !== 'undefined' && typeof window.document !== 'undefined';
 3 | 
 4 | // Detect Node.js environment
 5 | const isNode =
 6 |   typeof process !== 'undefined' && process.release?.name === 'node';
 7 | 
 8 | // Detect Cloudflare Workers and other edge runtimes (not browser, not Node.js)
 9 | const isCloudflareWorker = !isBrowser && !isNode;
10 | 
11 | export { isBrowser, isNode, isCloudflareWorker };
12 | 


--------------------------------------------------------------------------------
/example/build.js:
--------------------------------------------------------------------------------
 1 | require('dotenv').config();
 2 | require('esbuild')
 3 |   .build({
 4 |     bundle: true,
 5 |     entryPoints: ['example/browser.js'],
 6 |     external: ['dotenv'],
 7 |     loader: {
 8 |       '.html': 'text',
 9 |     },
10 |     outfile: 'example/dist/index.js',
11 |     define: {
12 |       process: `{
13 |         "env": {
14 |           "INFURA_KEY": '${process.env.INFURA_KEY}',
15 |           "OPENSEA_KEY": '${process.env.OPENSEA_KEY}'
16 |         },
17 |       }`,
18 |     },
19 |   })
20 |   .catch(() => process.exit(1));
21 | 


--------------------------------------------------------------------------------
/test/setup.js:
--------------------------------------------------------------------------------
 1 | // Jest setup file to polyfill fetch for test environment
 2 | // In Node.js 18+, fetch is built-in but may not be available in Jest's test environment
 3 | // We'll use a lightweight fetch polyfill for testing
 4 | 
 5 | /* eslint-env node */
 6 | /* global globalThis */
 7 | 
 8 | try {
 9 |   // Try to load native fetch from node (Node 18+)
10 |   const nodeFetch = globalThis.fetch;
11 |   if (!nodeFetch) {
12 |     throw new Error('Fetch not available');
13 |   }
14 | } catch (e) {
15 |   // If native fetch is not available, we'll let axios fall back to http adapter
16 |   // which is perfectly fine for testing purposes
17 |   console.log(
18 |     'Note: Using HTTP adapter for tests (fetch not available in Jest environment)'
19 |   );
20 | }
21 | 


--------------------------------------------------------------------------------
/src/utils/index.ts:
--------------------------------------------------------------------------------
 1 | import { assert } from './assert';
 2 | import { handleSettled } from './handleSettled';
 3 | import { parseNFT } from './parseNFT';
 4 | import { BaseError } from './error';
 5 | import { convertToRawSVG, getImageURI } from './getImageURI';
 6 | import { resolveURI } from './resolveURI';
 7 | import {
 8 |   createAgentAdapter,
 9 |   createCacheAdapter,
10 |   createFetcher,
11 |   fetch,
12 | } from './fetch';
13 | import { isCID } from './isCID';
14 | import { ALLOWED_IMAGE_MIMETYPES, isImageURI } from './isImageURI';
15 | import { sanitizeSVG } from './sanitize';
16 | 
17 | export {
18 |   ALLOWED_IMAGE_MIMETYPES,
19 |   BaseError,
20 |   assert,
21 |   convertToRawSVG,
22 |   createAgentAdapter,
23 |   createCacheAdapter,
24 |   createFetcher,
25 |   fetch,
26 |   getImageURI,
27 |   handleSettled,
28 |   isCID,
29 |   isImageURI,
30 |   parseNFT,
31 |   resolveURI,
32 |   sanitizeSVG,
33 | };
34 | 


--------------------------------------------------------------------------------
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
 1 | name: CI
 2 | env:
 3 |   INFURA_KEY: ${{ secrets.INFURA_KEY }}
 4 |   OPENSEA_KEY: ${{ secrets.OPENSEA_KEY }}
 5 | on: [push]
 6 | jobs:
 7 |   build:
 8 |     name: Build, lint, and test on Node ${{ matrix.node }} and ${{ matrix.os }}
 9 | 
10 |     runs-on: ${{ matrix.os }}
11 |     strategy:
12 |       matrix:
13 |         node: ['21.x', '22.x']
14 |         os: [ubuntu-latest, windows-latest, macOS-latest]
15 | 
16 |     steps:
17 |       - name: Checkout repo
18 |         uses: actions/checkout@v2
19 | 
20 |       - name: Use Node ${{ matrix.node }}
21 |         uses: actions/setup-node@v1
22 |         with:
23 |           node-version: ${{ matrix.node }}
24 |           cache: 'yarn'
25 | 
26 |       - run: yarn install --immutable --immutable-cache --check-cache
27 | 
28 |       - name: Lint
29 |         run: yarn lint
30 | 
31 |       - name: Test
32 |         run: yarn test --ci --coverage --maxWorkers=2
33 | 
34 |       - name: Build
35 |         run: yarn build
36 | 


--------------------------------------------------------------------------------
/src/specs/uri.ts:
--------------------------------------------------------------------------------
 1 | import { AvatarResolverOpts } from '../types';
 2 | import { createFetcher, isImageURI, resolveURI } from '../utils';
 3 | 
 4 | export default class URI {
 5 |   async getMetadata(uri: string, options?: AvatarResolverOpts) {
 6 |     // Create a configured fetch instance for this request
 7 |     const fetch = createFetcher({
 8 |       ttl: options?.cache,
 9 |       agents: options?.agents,
10 |       allowPrivateIPs: options?.allowPrivateIPs,
11 |     });
12 | 
13 |     const { uri: resolvedURI, isOnChain } = resolveURI(uri, options);
14 |     if (isOnChain) {
15 |       return resolvedURI;
16 |     }
17 | 
18 |     if (options?.urlDenyList?.includes(new URL(resolvedURI).hostname)) {
19 |       return { image: null };
20 |     }
21 | 
22 |     // check if resolvedURI is an image, if it is return the url
23 |     const isImage = await isImageURI(resolvedURI);
24 |     if (isImage) {
25 |       return { image: resolvedURI };
26 |     }
27 | 
28 |     // if resolvedURI is not an image, try retrieve the data.
29 |     const response = await fetch.get(encodeURI(resolvedURI));
30 |     return await response?.data;
31 |   }
32 | }
33 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2022 Ethereum Name Service
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.


--------------------------------------------------------------------------------
/example/node.js:
--------------------------------------------------------------------------------
 1 | require('dotenv').config();
 2 | const { StaticJsonRpcProvider } = require('@ethersproject/providers');
 3 | const { AvatarResolver, utils: avtUtils } = require('../dist/index');
 4 | const { JSDOM } = require('jsdom');
 5 | 
 6 | const jsdom = new JSDOM().window;
 7 | const ensName = process.argv[2];
 8 | if (!ensName) {
 9 |   console.log(
10 |     'Please provide an ENS name as an argument (> node demo.js nick.eth)'
11 |   );
12 |   process.exit(1);
13 | }
14 | const IPFS = 'https://cf-ipfs.com';
15 | const provider = new StaticJsonRpcProvider(
16 |   `https://mainnet.infura.io/v3/${process.env.INFURA_KEY}`
17 | );
18 | const avt = new AvatarResolver(provider, {
19 |   ipfs: IPFS,
20 |   apiKey: { opensea: process.env.OPENSEA_KEY },
21 | });
22 | avt
23 |   .getMetadata(ensName)
24 |   .then(metadata => {
25 |     if (!metadata) {
26 |       console.log('Avatar not found!');
27 |       return;
28 |     }
29 |     const avatar = avtUtils.getImageURI({
30 |       metadata,
31 |       gateways: {
32 |         ipfs: IPFS,
33 |       },
34 |       jsdomWindow: jsdom,
35 |     });
36 |     console.log('avatar: ', avatar);
37 |   })
38 |   .catch(console.log);
39 | 
40 | try {
41 |   avt
42 |   .getHeader(ensName, { jsdomWindow: jsdom })
43 |   .then(header => {
44 |     console.log('header: ', header);
45 |   })
46 |   .catch(console.log);
47 | } catch {}
48 | 


--------------------------------------------------------------------------------
/rollup.config.mjs:
--------------------------------------------------------------------------------
 1 | import fs from 'fs';
 2 | import path from 'path';
 3 | import tsPlugin from '@rollup/plugin-typescript';
 4 | 
 5 | export default {
 6 |   input: 'src/index.ts',
 7 |   output: [
 8 |     {
 9 |       format: 'cjs',
10 |       file: './dist/index.js',
11 |     },
12 |     {
13 |       format: 'es',
14 |       dir: 'dist',
15 |       preserveModules: true,
16 |       preserveModulesRoot: 'src',
17 |       entryFileNames: chunk => {
18 |         return `${chunk.name === 'index' ? 'index.esm' : chunk.name}.js`;
19 |       },
20 |     },
21 |   ],
22 |   plugins: [
23 |     tsPlugin({
24 |       declarationDir: './dist',
25 |       sourceMap: false,
26 |     }),
27 |     removeDist(),
28 |   ],
29 | };
30 | 
31 | function removeDist(options = {}) {
32 |   const { hook = 'buildStart', buildDir = 'dist' } = options;
33 | 
34 |   return {
35 |     name: 'remove-dist',
36 |     [hook]: async () => {
37 |       const folderPath = path.join(process.cwd(), buildDir);
38 |       try {
39 |         fs.accessSync(folderPath, fs.F_OK);
40 |         fs.rmSync(folderPath, { recursive: true, force: true });
41 |       } catch (err) {
42 |         if (err.code !== 'ENOENT') throw err;
43 |         try {
44 |           fs.rmSync(folderPath, { recursive: true, force: true });
45 |         } catch (innerErr) {
46 |           console.log('An error occurred while removing the folder:', innerErr);
47 |         }
48 |       }
49 |     },
50 |   };
51 | }
52 | 


--------------------------------------------------------------------------------
/src/utils/parseNFT.ts:
--------------------------------------------------------------------------------
 1 | import { assert } from './assert';
 2 | import { BaseError } from './error';
 3 | 
 4 | export interface NFTURIParsingError {}
 5 | export class NFTURIParsingError extends BaseError {}
 6 | 
 7 | export function parseNFT(uri: string, seperator: string = '/') {
 8 |   // parse valid nft spec (CAIP-22/CAIP-29)
 9 |   // @see: https://github.com/ChainAgnostic/CAIPs/tree/master/CAIPs
10 |   try {
11 |     assert(uri, 'parameter URI cannot be empty');
12 | 
13 |     if (uri.startsWith('did:nft:')) {
14 |       // convert DID to CAIP
15 |       uri = uri.replace('did:nft:', '').replace(/_/g, '/');
16 |     }
17 | 
18 |     const [reference, asset_namespace, tokenID] = uri.split(seperator);
19 |     const [eip_namespace, chainID] = reference.split(':');
20 |     const [erc_namespace, contractAddress] = asset_namespace.split(':');
21 | 
22 |     assert(
23 |       eip_namespace && eip_namespace.toLowerCase() === 'eip155',
24 |       'Only EIP-155 is supported'
25 |     );
26 |     assert(chainID, 'chainID not found');
27 |     assert(contractAddress, 'contractAddress not found');
28 |     assert(erc_namespace, 'erc namespace not found');
29 |     assert(tokenID, 'tokenID not found');
30 | 
31 |     return {
32 |       chainID: Number(chainID),
33 |       namespace: erc_namespace.toLowerCase(),
34 |       contractAddress,
35 |       tokenID,
36 |     };
37 |   } catch (error) {
38 |     throw new NFTURIParsingError(`${error as string} - ${uri}`);
39 |   }
40 | }
41 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   // see https://www.typescriptlang.org/tsconfig to better understand tsconfigs
 3 |   "include": ["src", "types", "test"],
 4 |   "compilerOptions": {
 5 |     "module": "esnext",
 6 |     "lib": ["dom", "esnext"],
 7 |     "target": "ES2018",
 8 |     "importHelpers": true,
 9 |     "downlevelIteration": true,
10 |     // output .d.ts declaration files for consumers
11 |     "declaration": true,
12 |     // output .js.map sourcemap files for consumers
13 |     "sourceMap": true,
14 |     // match output dir to input dir. e.g. dist/index instead of dist/src/index
15 |     "rootDir": "./src",
16 |     // stricter type-checking for stronger correctness. Recommended by TS
17 |     "strict": true,
18 |     // linter checks for common issues
19 |     "noImplicitReturns": true,
20 |     "noFallthroughCasesInSwitch": true,
21 |     // noUnused* overlap with @typescript-eslint/no-unused-vars, can disable if duplicative
22 |     "noUnusedLocals": false,
23 |     "noUnusedParameters": true,
24 |     "useUnknownInCatchVariables": false,
25 |     // use Node's module resolution algorithm, instead of the legacy TS one
26 |     "moduleResolution": "node",
27 |     // transpile JSX to React.createElement
28 |     "jsx": "react",
29 |     // interop between ESM and CJS modules. Recommended by TS
30 |     "esModuleInterop": true,
31 |     // significant perf increase by skipping checking .d.ts files, particularly those in node_modules. Recommended by TS
32 |     "skipLibCheck": true,
33 |     // error out if import and file system have a casing mismatch. Recommended by TS
34 |     "forceConsistentCasingInFileNames": true,
35 |     // `tsdx build` ignores this option, but it is commonly used when type-checking separately with `tsc`
36 |     "noEmit": true
37 |   }
38 | }
39 | 


--------------------------------------------------------------------------------
/src/specs/erc721.ts:
--------------------------------------------------------------------------------
 1 | import { Contract, Provider } from 'ethers';
 2 | import { Buffer } from 'buffer/';
 3 | import { createFetcher, resolveURI } from '../utils';
 4 | import { AvatarResolverOpts } from '../types';
 5 | 
 6 | const abi = [
 7 |   'function tokenURI(uint256 tokenId) external view returns (string memory)',
 8 |   'function ownerOf(uint256 tokenId) public view returns (address)',
 9 | ];
10 | 
11 | export default class ERC721 {
12 |   async getMetadata(
13 |     provider: Provider,
14 |     ownerAddress: string | undefined | null,
15 |     contractAddress: string,
16 |     tokenID: string,
17 |     options?: AvatarResolverOpts
18 |   ) {
19 |     // Create a configured fetch instance for this request
20 |     const fetch = createFetcher({
21 |       ttl: options?.cache,
22 |       agents: options?.agents,
23 |       allowPrivateIPs: options?.allowPrivateIPs,
24 |     });
25 | 
26 |     const contract = new Contract(contractAddress, abi, provider);
27 |     const [tokenURI, owner] = await Promise.all([
28 |       contract.tokenURI(tokenID),
29 |       ownerAddress && contract.ownerOf(tokenID),
30 |     ]);
31 |     // if user has valid address and if owner of the nft matches with the owner address
32 |     const isOwner = !!(
33 |       ownerAddress && owner.toLowerCase() === ownerAddress.toLowerCase()
34 |     );
35 | 
36 |     const { uri: resolvedURI, isOnChain, isEncoded } = resolveURI(
37 |       tokenURI,
38 |       options
39 |     );
40 |     let _resolvedUri = resolvedURI;
41 |     if (isOnChain) {
42 |       if (isEncoded) {
43 |         _resolvedUri = Buffer.from(
44 |           resolvedURI.replace('data:application/json;base64,', ''),
45 |           'base64'
46 |         ).toString();
47 |       }
48 |       const metadata = JSON.parse(_resolvedUri);
49 |       return { ...metadata, is_owner: isOwner };
50 |     }
51 |     const response = await fetch.get(
52 |       encodeURI(resolvedURI.replace(/(?:0x)?{id}/, tokenID))
53 |     );
54 |     const metadata = await response?.data;
55 |     return { ...metadata, is_owner: isOwner };
56 |   }
57 | }
58 | 


--------------------------------------------------------------------------------
/src/specs/erc1155.ts:
--------------------------------------------------------------------------------
 1 | import { Contract, Provider } from 'ethers';
 2 | import { Buffer } from 'buffer/';
 3 | import { createFetcher, resolveURI } from '../utils';
 4 | import { AvatarResolverOpts } from '../types';
 5 | 
 6 | const abi = [
 7 |   'function uri(uint256 _id) public view returns (string memory)',
 8 |   'function balanceOf(address account, uint256 id) public view returns (uint256)',
 9 | ];
10 | 
11 | function getMarketplaceAPIKey(uri: string, options?: AvatarResolverOpts) {
12 |   if (
13 |     uri.startsWith('https://api.opensea.io/') &&
14 |     options?.apiKey?.['opensea']
15 |   ) {
16 |     return { 'X-API-KEY': options.apiKey.opensea };
17 |   }
18 |   return false;
19 | }
20 | 
21 | export default class ERC1155 {
22 |   async getMetadata(
23 |     provider: Provider,
24 |     ownerAddress: string | undefined | null,
25 |     contractAddress: string,
26 |     tokenID: string,
27 |     options?: AvatarResolverOpts
28 |   ) {
29 |     // Create a configured fetch instance for this request
30 |     const fetch = createFetcher({
31 |       ttl: options?.cache,
32 |       agents: options?.agents,
33 |       allowPrivateIPs: options?.allowPrivateIPs,
34 |     });
35 | 
36 |     // exclude opensea api which does not follow erc1155 spec
37 |     const tokenIDHex = !tokenID.startsWith('https://api.opensea.io/')
38 |       ? tokenID.replace('0x', '').padStart(64, '0')
39 |       : tokenID;
40 |     const contract = new Contract(contractAddress, abi, provider);
41 |     const [tokenURI, balance] = await Promise.all([
42 |       contract.uri(tokenID),
43 |       ownerAddress ? contract.balanceOf(ownerAddress, tokenID) : BigInt(0),
44 |     ]);
45 |     // if user has valid address and if token balance of given address is greater than 0
46 |     const isOwner = !!(ownerAddress && balance > BigInt(0));
47 | 
48 |     const { uri: resolvedURI, isOnChain, isEncoded } = resolveURI(
49 |       tokenURI,
50 |       options
51 |     );
52 |     let _resolvedUri = resolvedURI;
53 |     if (isOnChain) {
54 |       if (isEncoded) {
55 |         _resolvedUri = Buffer.from(
56 |           resolvedURI.replace('data:application/json;base64,', ''),
57 |           'base64'
58 |         ).toString();
59 |       }
60 |       const metadata = JSON.parse(_resolvedUri);
61 |       return { ...metadata, is_owner: isOwner };
62 |     }
63 | 
64 |     const marketplaceKey = getMarketplaceAPIKey(resolvedURI, options);
65 | 
66 |     const response = await fetch.get(
67 |       encodeURI(resolvedURI.replace(/(?:0x)?{id}/, tokenIDHex)),
68 |       marketplaceKey ? { headers: marketplaceKey } : {}
69 |     );
70 |     const metadata = await response?.data;
71 |     return { ...metadata, is_owner: isOwner };
72 |   }
73 | }
74 | 


--------------------------------------------------------------------------------
/src/utils/getImageURI.ts:
--------------------------------------------------------------------------------
 1 | import isSVG from 'is-svg';
 2 | 
 3 | import { ImageURIOpts } from '../types';
 4 | import { assert } from './assert';
 5 | import { resolveURI } from './resolveURI';
 6 | import { sanitizeSVG } from './sanitize';
 7 | 
 8 | function isSVGDataUri(uri: string): boolean {
 9 |   const svgDataUriPrefix = 'data:image/svg+xml';
10 |   return uri.startsWith(svgDataUriPrefix);
11 | }
12 | 
13 | function isImageDataUri(uri: string): boolean {
14 |   const imageFormats = ['jpeg', 'png', 'gif', 'bmp', 'webp'];
15 |   const dataUriPattern = /^data:image\/([a-zA-Z0-9]+)(?:;base64)?,/;
16 | 
17 |   const match = uri.match(dataUriPattern);
18 |   if (!match || match.length < 2) {
19 |     return false;
20 |   }
21 | 
22 |   const format = match[1].toLowerCase();
23 |   return imageFormats.includes(format);
24 | }
25 | 
26 | export function convertToRawSVG(input: string): string | null {
27 |   const base64Prefix = 'data:image/svg+xml;base64,';
28 |   const encodedPrefix = 'data:image/svg+xml,';
29 | 
30 |   if (input.startsWith(base64Prefix)) {
31 |     const base64Data = input.substring(base64Prefix.length);
32 |     try {
33 |       return Buffer.from(base64Data, 'base64').toString();
34 |     } catch (error) {
35 |       console.error('Invalid base64 encoded SVG');
36 |       return null;
37 |     }
38 |   } else if (input.startsWith(encodedPrefix)) {
39 |     const encodedData = input.substring(encodedPrefix.length);
40 |     try {
41 |       return decodeURIComponent(encodedData);
42 |     } catch (error) {
43 |       console.error('Invalid URL encoded SVG');
44 |       return null;
45 |     }
46 |   } else {
47 |     // The input is already a raw SVG (or another format if not used with isSVGDataUri)
48 |     return input;
49 |   }
50 | }
51 | 
52 | function _sanitize(data: string, jsDomWindow?: any): Buffer {
53 |   // Use platform-specific sanitization (DOMPurify or sanitize-html)
54 |   const cleanSVG = sanitizeSVG(data, jsDomWindow);
55 |   return Buffer.from(cleanSVG);
56 | }
57 | 
58 | export function getImageURI({
59 |   metadata,
60 |   customGateway,
61 |   gateways,
62 |   jsdomWindow,
63 |   urlDenyList,
64 | }: ImageURIOpts) {
65 |   // retrieves image uri from metadata, if image is onchain then convert to base64
66 |   const { image, image_url, image_data } = metadata;
67 | 
68 |   const _image = image || image_url || image_data;
69 |   assert(_image, 'Image is not available');
70 |   const { uri: parsedURI } = resolveURI(_image, gateways, customGateway);
71 | 
72 |   if (isSVG(parsedURI) || isSVGDataUri(parsedURI)) {
73 |     // svg - image_data
74 |     const rawSVG = convertToRawSVG(parsedURI)?.replace(
75 |       /\s*(<[^>]+>)\s*/g,
76 |       '$1'
77 |     );
78 |     if (!rawSVG) return null;
79 | 
80 |     const data = _sanitize(rawSVG, jsdomWindow);
81 |     return `data:image/svg+xml;base64,${data.toString('base64')}`;
82 |   }
83 | 
84 |   if (isImageDataUri(parsedURI) || parsedURI.startsWith('http')) {
85 |     if (urlDenyList?.includes(new URL(parsedURI).hostname)) return null;
86 |     return parsedURI;
87 |   }
88 | 
89 |   return null;
90 | }
91 | 


--------------------------------------------------------------------------------
/.github/workflows/pages.yml:
--------------------------------------------------------------------------------
 1 | name: Deploy ESBuild site to Pages
 2 | 
 3 | on:
 4 |   # Runs on pushes targeting the default branch
 5 |   push:
 6 |     branches: ["main"]
 7 | 
 8 |   # Allows you to run this workflow manually from the Actions tab
 9 |   workflow_dispatch:
10 | 
11 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12 | permissions:
13 |   contents: read
14 |   pages: write
15 |   id-token: write
16 | 
17 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19 | concurrency:
20 |   group: "pages"
21 |   cancel-in-progress: false
22 | 
23 | env:
24 |   BUILD_PATH: "." # default value when not using subfolders
25 | 
26 | jobs:
27 |   build:
28 |     name: Build
29 |     runs-on: ubuntu-latest
30 |     env:
31 |       INFURA_KEY: ${{ secrets.INFURA_KEY }}
32 |       OPENSEA_KEY: ${{ secrets.OPENSEA_KEY }}
33 |     steps:
34 |       - name: Checkout
35 |         uses: actions/checkout@v3
36 |       - name: Detect package manager
37 |         id: detect-package-manager
38 |         run: |
39 |           if [ -f "${{ github.workspace }}/yarn.lock" ]; then
40 |             echo "manager=yarn" >> $GITHUB_OUTPUT
41 |             echo "command=install" >> $GITHUB_OUTPUT
42 |             echo "runner=yarn" >> $GITHUB_OUTPUT
43 |             exit 0
44 |           elif [ -f "${{ github.workspace }}/package.json" ]; then
45 |             echo "manager=npm" >> $GITHUB_OUTPUT
46 |             echo "command=ci" >> $GITHUB_OUTPUT
47 |             echo "runner=npx --no-install" >> $GITHUB_OUTPUT
48 |             exit 0
49 |           else
50 |             echo "Unable to determine package manager"
51 |             exit 1
52 |           fi
53 |       - name: Setup Node
54 |         uses: actions/setup-node@v3
55 |         with:
56 |           node-version: "18"
57 |           cache: ${{ steps.detect-package-manager.outputs.manager }}
58 |       - name: Setup yarn
59 |         run: npm install -g yarn
60 |       - name: Setup Pages
61 |         id: pages
62 |         uses: actions/configure-pages@v3
63 |       - name: Install dependencies
64 |         run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
65 |         working-directory: ${{ env.BUILD_PATH }}
66 |       - name: Build with esbuild
67 |         run: |
68 |           ${{ steps.detect-package-manager.outputs.runner }} build && ${{ steps.detect-package-manager.outputs.runner }} build:demo
69 |         working-directory: ${{ env.BUILD_PATH }}
70 |       - name: Upload artifact
71 |         uses: actions/upload-pages-artifact@v1
72 |         with:
73 |           path: ${{ env.BUILD_PATH }}
74 | 
75 |   deploy:
76 |     environment:
77 |       name: github-pages
78 |       url: ${{ steps.deployment.outputs.page_url }}
79 |     needs: build
80 |     runs-on: ubuntu-latest
81 |     name: Deploy
82 |     steps:
83 |       - name: Deploy to GitHub Pages
84 |         id: deployment
85 |         uses: actions/deploy-pages@v2
86 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html lang="en">
  3 |   <head>
  4 |     <meta charset="utf-8" />
  5 |     <script type="module" src="./example/dist/index.js"></script>
  6 |     <title>ENS Avatar Resolver Library Demo</title>
  7 |   </head>
  8 |   <body>
  9 |     <div class="container">
 10 |       <div id="avatars"></div>
 11 |       <div class="queryContainer">
 12 |         <div id="headerContainer">
 13 |           <h2>Query ENS Avatar</h2>
 14 |           <div>
 15 |             <img
 16 |               class="queryImage"
 17 |               id="queryImage"
 18 |               width="300"
 19 |               height="300"
 20 |               src="./example/ens.png"
 21 |             />
 22 |             <div>
 23 |               <input
 24 |                 class="queryInput"
 25 |                 id="queryInput"
 26 |                 type="text"
 27 |                 placeholder="vitalik.eth"
 28 |                 autofocus
 29 |                 autocomplete="off"
 30 |               />
 31 |               <div class="hint">
 32 |                 (type ENS name and hit the enter button)
 33 |               </div>
 34 |             </div>
 35 |           </div>
 36 |         </div>
 37 |       </div>
 38 |     </div>
 39 |   </body>
 40 |   <style>
 41 |     body {
 42 |       font-family: 'Helvetica', serif;
 43 |     }
 44 |     #avatars {
 45 |       position: absolute;
 46 |       inset: 0;
 47 |       display: grid;
 48 |       background: black;
 49 |       grid-template-columns: repeat(auto-fill, minmax(20rem, 1fr));
 50 |       grid-template-rows: repeat(auto-fill, minmax(20rem, 1fr));
 51 |       align-items: center;
 52 |       justify-items: center;
 53 | 
 54 |       transition: 0.2 grid-template-columns;
 55 |       opacity: 0.3;
 56 |       overflow: hidden;
 57 |       pointer-events: none;
 58 |       user-select: none;
 59 |     }
 60 |     #headerContainer {
 61 |       height: 100%;
 62 |       background-position: 0 55px;
 63 |       background-repeat: no-repeat;
 64 |       background-size: contain;
 65 |     }
 66 |     .hint {
 67 |       margin-top: 0.5rem;
 68 |       color: #aaa;
 69 |     }
 70 |     .queryContainer {
 71 |       position: absolute;
 72 |       inset: 0;
 73 |       margin: auto;
 74 |       opacity: 1;
 75 |       width: 50%;
 76 |       min-width: 20rem;
 77 |       height: 30rem;
 78 |       background-color: white;
 79 |       border-radius: 1.5rem;
 80 |       border: 1px solid #eee;
 81 |       box-shadow: 0.2rem 0.4rem 1rem #ccc;
 82 |       padding: 3rem 2.5rem;
 83 | 
 84 |       /* text */
 85 |       text-align: center;
 86 |     }
 87 |     .queryImage,
 88 |     .queryInput {
 89 |       border-radius: 0.3rem;
 90 |     }
 91 |     .queryImage {
 92 |       object-fit: contain;
 93 |       border: 5px solid white;
 94 |       border-radius: 5px;
 95 |       outline: #d6d6d6 solid 2px;
 96 |     }
 97 |     .queryInput {
 98 |       width: 19rem;
 99 |       box-sizing: border-box;
100 |       padding: 0.5rem 0.5rem;
101 |       margin-top: 10px;
102 |       text-align: center;
103 |       font-size: 1.4rem;
104 |       border: 1px solid #bbb;
105 |     }
106 |   </style>
107 | </html>
108 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
  1 | {
  2 |   "version": "1.0.4",
  3 |   "license": "MIT",
  4 |   "main": "dist/index.js",
  5 |   "module": "dist/index.esm.js",
  6 |   "typings": "dist/index.d.ts",
  7 |   "sideEffects": false,
  8 |   "files": [
  9 |     "dist",
 10 |     "src"
 11 |   ],
 12 |   "engines": {
 13 |     "node": ">=18"
 14 |   },
 15 |   "scripts": {
 16 |     "start": "rollup -c --watch",
 17 |     "build": "rollup -c",
 18 |     "build:demo": "node ./example/build.js",
 19 |     "test": "tsdx test",
 20 |     "lint": "tsdx lint",
 21 |     "size": "size-limit"
 22 |   },
 23 |   "husky": {
 24 |     "hooks": {
 25 |       "pre-commit": "tsdx lint src test"
 26 |     }
 27 |   },
 28 |   "prettier": {
 29 |     "printWidth": 80,
 30 |     "semi": true,
 31 |     "singleQuote": true,
 32 |     "trailingComma": "es5"
 33 |   },
 34 |   "jest": {
 35 |     "testTimeout": 20000,
 36 |     "transformIgnorePatterns": [
 37 |       "node_modules/(?!(axios|axios-cache-interceptor))"
 38 |     ],
 39 |     "moduleNameMapper": {
 40 |       "^axios$": "axios/dist/node/axios.cjs"
 41 |     },
 42 |     "setupFilesAfterEnv": [
 43 |       "<rootDir>/test/setup.js"
 44 |     ]
 45 |   },
 46 |   "name": "@ensdomains/ens-avatar",
 47 |   "author": "Muhammed Tanrıkulu <muhammed@ens.domains>",
 48 |   "size-limit": [
 49 |     {
 50 |       "path": "dist/index.js",
 51 |       "limit": "240 KB",
 52 |       "ignore": [
 53 |         "jsdom",
 54 |         "http",
 55 |         "https",
 56 |         "ssrf-req-filter"
 57 |       ]
 58 |     },
 59 |     {
 60 |       "path": "dist/index.esm.js",
 61 |       "limit": "150 KB",
 62 |       "ignore": [
 63 |         "jsdom",
 64 |         "http",
 65 |         "https",
 66 |         "ssrf-req-filter"
 67 |       ]
 68 |     }
 69 |   ],
 70 |   "devDependencies": {
 71 |     "@rollup/plugin-typescript": "^11.1.5",
 72 |     "@size-limit/preset-small-lib": "^11.0.1",
 73 |     "@types/dompurify": "^3.0.5",
 74 |     "@types/jsdom": "^21.1.6",
 75 |     "@types/moxios": "^0.4.17",
 76 |     "@types/sanitize-html": "^2.16.0",
 77 |     "@types/url-join": "^4.0.1",
 78 |     "@typescript-eslint/eslint-plugin": "^4.0.0",
 79 |     "@typescript-eslint/parser": "^4.0.0",
 80 |     "babel-eslint": "^10.1.0",
 81 |     "dotenv": "^16.3.1",
 82 |     "esbuild": "^0.14.21",
 83 |     "eslint-config-react-app": "6",
 84 |     "eslint-plugin-import": "^2.32.0",
 85 |     "moxios": "^0.4.0",
 86 |     "nock": "^13.2.2",
 87 |     "rollup": "^4.9.1",
 88 |     "sanitize-html": "^2.17.0",
 89 |     "size-limit": "^11.0.1",
 90 |     "tsdx": "^0.14.1",
 91 |     "typescript": "^4.5.5",
 92 |     "undici": "^7.16.0"
 93 |   },
 94 |   "dependencies": {
 95 |     "@ethersproject/contracts": "^5.7.0",
 96 |     "@ethersproject/providers": "^5.7.0",
 97 |     "assert": "^2.1.0",
 98 |     "axios": "^1.12.2",
 99 |     "axios-cache-interceptor": "^1.8.3",
100 |     "buffer": "^6.0.3",
101 |     "dompurify": "^3.0.6",
102 |     "ethers": "6.12.0",
103 |     "is-svg": "^4.3.2",
104 |     "multiformats": "^9.6.2",
105 |     "ssrf-req-filter": "^1.1.1",
106 |     "url-join": "^4.0.1"
107 |   },
108 |   "volta": {
109 |     "node": "18.14.0"
110 |   }
111 | }
112 | 


--------------------------------------------------------------------------------
/src/types.ts:
--------------------------------------------------------------------------------
  1 | import { Provider } from 'ethers';
  2 | 
  3 | export interface Spec {
  4 |   getMetadata: (
  5 |     provider: Provider,
  6 |     ownerAddress: string | undefined | null,
  7 |     contractAddress: string,
  8 |     tokenID: string,
  9 |     options?: AvatarResolverOpts
 10 |   ) => Promise<any>;
 11 | }
 12 | 
 13 | export type MARKETPLACES = 'opensea' | 'coinbase' | 'looksrare' | 'x2y2';
 14 | export type MarketplaceAPIKey = Partial<
 15 |   {
 16 |     [key in MARKETPLACES]: string;
 17 |   }
 18 | >;
 19 | 
 20 | /**
 21 |  * Custom HTTP/HTTPS agents for Node.js environments
 22 |  *
 23 |  * SECURITY NOTE: When you provide custom agents, ens-avatar will use them as-is
 24 |  * without applying SSRF (Server-Side Request Forgery) protection. You are responsible
 25 |  * for ensuring your custom agents have appropriate security measures.
 26 |  *
 27 |  * If no custom agents are provided, ens-avatar creates default agents with built-in
 28 |  * SSRF protection that blocks requests to private IP addresses (localhost, 10.x.x.x,
 29 |  * 192.168.x.x, etc.) unless allowPrivateIPs is set to true.
 30 |  */
 31 | export interface AxiosAgents {
 32 |   httpAgent?: Function;
 33 |   httpsAgent?: Function;
 34 | }
 35 | 
 36 | export type MediaKey = 'avatar' | 'header' | 'banner';
 37 | 
 38 | /**
 39 |  * Configuration options for AvatarResolver
 40 |  *
 41 |  * SSRF PROTECTION:
 42 |  * By default, ens-avatar protects against Server-Side Request Forgery (SSRF) attacks
 43 |  * by blocking requests to private IP addresses. This behavior depends on your configuration:
 44 |  *
 45 |  * 1. No custom agents (default): SSRF protection enabled - blocks localhost, 10.x.x.x, etc.
 46 |  * 2. Custom agents provided: Uses your agents as-is - YOU are responsible for SSRF protection
 47 |  * 3. allowPrivateIPs: true: Disables SSRF protection - only for local development
 48 |  */
 49 | export interface AvatarResolverOpts {
 50 |   /** Cache time-to-live in seconds */
 51 |   cache?: number;
 52 |   /** Custom IPFS gateway URL */
 53 |   ipfs?: string;
 54 |   /** Custom Arweave gateway URL */
 55 |   arweave?: string;
 56 |   /** API keys for NFT marketplaces (OpenSea, etc.) */
 57 |   apiKey?: MarketplaceAPIKey;
 58 |   /** List of hostnames to block (in addition to SSRF protection) */
 59 |   urlDenyList?: string[];
 60 |   /**
 61 |    * Custom HTTP/HTTPS agents for Node.js
 62 |    * WARNING: When provided, SSRF protection is NOT applied to your custom agents.
 63 |    * You are responsible for securing your agents against SSRF attacks.
 64 |    */
 65 |   agents?: AxiosAgents;
 66 |   /** Maximum response content length in bytes */
 67 |   maxContentLength?: number;
 68 |   /**
 69 |    * Allow requests to private IP addresses (localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x, etc.)
 70 |    *
 71 |    * WARNING: Only use this for local development (e.g., local IPFS nodes, test servers).
 72 |    * NEVER enable this in production as it disables SSRF protection.
 73 |    *
 74 |    * This flag is ignored if you provide custom agents (you control security in that case).
 75 |    *
 76 |    * @default false
 77 |    */
 78 |   allowPrivateIPs?: boolean;
 79 | }
 80 | 
 81 | export interface AvatarRequestOpts {
 82 |   jsdomWindow?: any;
 83 | }
 84 | 
 85 | export interface HeaderRequestOpts {
 86 |   jsdomWindow?: any;
 87 |   mediaKey?: Exclude<MediaKey, 'avatar'>;
 88 | }
 89 | 
 90 | export type Gateways = {
 91 |   ipfs?: string;
 92 |   arweave?: string;
 93 | };
 94 | 
 95 | export interface ImageURIOpts {
 96 |   metadata: any;
 97 |   customGateway?: string;
 98 |   gateways?: Gateways;
 99 |   jsdomWindow?: any;
100 |   urlDenyList?: string[];
101 | }
102 | 


--------------------------------------------------------------------------------
/src/utils/resolveURI.ts:
--------------------------------------------------------------------------------
  1 | import urlJoin from 'url-join';
  2 | 
  3 | import { Gateways } from '../types';
  4 | import { isCID } from './isCID';
  5 | import { IMAGE_SIGNATURES } from './isImageURI';
  6 | 
  7 | const IPFS_SUBPATH = '/ipfs/';
  8 | const IPNS_SUBPATH = '/ipns/';
  9 | const networkRegex = /(?<protocol>ipfs:\/|ipns:\/|ar:\/)?(?<root>\/)?(?<subpath>ipfs\/|ipns\/)?(?<target>[\w\-.]+)(?<subtarget>\/.*)?/;
 10 | const base64Regex = /^data:([a-zA-Z\-/+]*);base64,([^"].*)/;
 11 | const dataURIRegex = /^data:([a-zA-Z\-/+]*)?(;[a-zA-Z0-9].*?)?(,)/;
 12 | const JSON_MIMETYPE = 'data:application/json;';
 13 | 
 14 | function _getImageMimeType(uri: string) {
 15 |   const base64Data = uri.replace(base64Regex, '$2');
 16 |   const buffer = Buffer.from(base64Data, 'base64');
 17 | 
 18 |   if (buffer.length < 12) {
 19 |     return null; // not enough data to determine the type
 20 |   }
 21 | 
 22 |   // get the hex representation of the first 12 bytes
 23 |   const hex = buffer.toString('hex', 0, 12).toUpperCase();
 24 | 
 25 |   // check against magic number mapping
 26 |   for (const [magicNumber, mimeType] of Object.entries({
 27 |     ...IMAGE_SIGNATURES,
 28 |     '52494646': 'special_webp_check',
 29 |     '3C737667': 'image/svg+xml',
 30 |   })) {
 31 |     if (hex.startsWith(magicNumber.toUpperCase())) {
 32 |       if (mimeType === 'special_webp_check') {
 33 |         return hex.slice(8, 12) === '5745' ? 'image/webp' : null;
 34 |       }
 35 |       return mimeType;
 36 |     }
 37 |   }
 38 | 
 39 |   return null;
 40 | }
 41 | 
 42 | function _isValidBase64(uri: string) {
 43 |   if (typeof uri !== 'string') {
 44 |     return false;
 45 |   }
 46 | 
 47 |   // check if the string matches the Base64 pattern
 48 |   if (!base64Regex.test(uri)) {
 49 |     return false;
 50 |   }
 51 | 
 52 |   const [header, str] = uri.split('base64,');
 53 |   if (header != JSON_MIMETYPE) {
 54 |     const mimeType = _getImageMimeType(uri);
 55 |     if (!mimeType || !header.includes(mimeType)) {
 56 |       return false;
 57 |     }
 58 |   }
 59 | 
 60 |   // length must be multiple of 4
 61 |   if (str.length % 4 !== 0) {
 62 |     return false;
 63 |   }
 64 | 
 65 |   try {
 66 |     // try to encode/decode the string, to see if matches
 67 |     const buffer = Buffer.from(str, 'base64');
 68 |     const encoded = buffer.toString('base64');
 69 |     return encoded === str;
 70 |   } catch (e) {
 71 |     return false;
 72 |   }
 73 | }
 74 | 
 75 | function _replaceGateway(uri: string, source: string, target?: string) {
 76 |   if (uri.startsWith(source) && target) {
 77 |     try {
 78 |       let _uri = new URL(uri);
 79 |       _uri.hostname = new URL(target).hostname;
 80 |       return _uri.toString();
 81 |     } catch (_error) {
 82 |       return uri;
 83 |     }
 84 |   }
 85 |   return uri;
 86 | }
 87 | 
 88 | export function resolveURI(
 89 |   uri: string,
 90 |   gateways?: Gateways,
 91 |   customGateway?: string
 92 | ): { uri: string; isOnChain: boolean; isEncoded: boolean } {
 93 |   // resolves uri based on its' protocol
 94 |   const isEncoded = _isValidBase64(uri);
 95 |   if (isEncoded || uri.startsWith('http')) {
 96 |     uri = _replaceGateway(uri, 'https://ipfs.io/', gateways?.ipfs);
 97 |     uri = _replaceGateway(uri, 'https://arweave.net/', gateways?.arweave);
 98 |     return { uri, isOnChain: isEncoded, isEncoded };
 99 |   }
100 | 
101 |   // customGateway option will be depreciated after 2 more version bump
102 |   if (!gateways?.ipfs && !!customGateway) {
103 |     console.warn(
104 |       "'customGateway' option depreciated, please use 'gateways: {ipfs: YOUR_IPFS_GATEWAY }' instead"
105 |     );
106 |     gateways = { ...gateways, ipfs: customGateway };
107 |   }
108 | 
109 |   const ipfsGateway = gateways?.ipfs || 'https://ipfs.io';
110 |   const arGateway = gateways?.arweave || 'https://arweave.net';
111 |   const networkRegexResult = uri.match(networkRegex);
112 |   const { protocol, subpath, target, subtarget = '' } =
113 |     networkRegexResult?.groups || {};
114 |   if ((protocol === 'ipns:/' || subpath === 'ipns/') && target) {
115 |     return {
116 |       uri: urlJoin(ipfsGateway, IPNS_SUBPATH, target, subtarget),
117 |       isOnChain: false,
118 |       isEncoded: false,
119 |     };
120 |   } else if (isCID(target)) {
121 |     // Assume that it's a regular IPFS CID and not an IPNS key
122 |     return {
123 |       uri: urlJoin(ipfsGateway, IPFS_SUBPATH, target, subtarget),
124 |       isOnChain: false,
125 |       isEncoded: false,
126 |     };
127 |   } else if (protocol === 'ar:/' && target) {
128 |     return {
129 |       uri: urlJoin(arGateway, target, subtarget || ''),
130 |       isOnChain: false,
131 |       isEncoded: false,
132 |     };
133 |   } else {
134 |     // we may want to throw error here
135 |     return {
136 |       uri: uri.replace(dataURIRegex, ''),
137 |       isOnChain: true,
138 |       isEncoded: false,
139 |     };
140 |   }
141 | }
142 | 


--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
  1 | import { JsonRpcProvider } from 'ethers';
  2 | import ERC1155 from './specs/erc1155';
  3 | import ERC721 from './specs/erc721';
  4 | import URI from './specs/uri';
  5 | import * as utils from './utils';
  6 | import {
  7 |   BaseError,
  8 |   getImageURI,
  9 |   handleSettled,
 10 |   isImageURI,
 11 |   parseNFT,
 12 | } from './utils';
 13 | import {
 14 |   AvatarRequestOpts,
 15 |   AvatarResolverOpts,
 16 |   HeaderRequestOpts,
 17 |   MediaKey,
 18 |   Spec,
 19 | } from './types';
 20 | 
 21 | export const specs: { [key: string]: new () => Spec } = Object.freeze({
 22 |   erc721: ERC721,
 23 |   erc1155: ERC1155,
 24 | });
 25 | 
 26 | export interface UnsupportedNamespace {}
 27 | export class UnsupportedNamespace extends BaseError {}
 28 | 
 29 | export interface UnsupportedMediaKey {}
 30 | export class UnsupportedMediaKey extends BaseError {}
 31 | 
 32 | export interface AvatarResolver {
 33 |   provider: JsonRpcProvider;
 34 |   options?: AvatarResolverOpts;
 35 |   getAvatar(ens: string, data: AvatarRequestOpts): Promise<string | null>;
 36 |   getHeader(ens: string, data: HeaderRequestOpts): Promise<string | null>;
 37 |   getMetadata(ens: string, key?: MediaKey): Promise<any | null>;
 38 | }
 39 | 
 40 | export class AvatarResolver implements AvatarResolver {
 41 |   constructor(provider: JsonRpcProvider, options?: AvatarResolverOpts) {
 42 |     this.provider = provider;
 43 |     this.options = options;
 44 |     // Note: fetch instance configuration is now handled in createFetcher
 45 |     // The global fetch instance already has proper configuration
 46 |     // This constructor no longer needs to modify the fetch instance
 47 |     // as options are passed directly to API methods that create their own instances
 48 |   }
 49 | 
 50 |   async getMetadata(ens: string, key: MediaKey = 'avatar') {
 51 |     // retrieve registrar address and resolver object from ens name
 52 |     const [resolvedAddress, resolver] = await handleSettled([
 53 |       this.provider.resolveName(ens),
 54 |       this.provider.getResolver(ens),
 55 |     ]);
 56 |     if (!resolver) return null;
 57 | 
 58 |     // retrieve 'avatar' text recored from resolver
 59 |     const mediaURI = await resolver.getText(key);
 60 |     if (!mediaURI) return null;
 61 | 
 62 |     // test case-insensitive in case of uppercase records
 63 |     if (!/eip155:/i.test(mediaURI)) {
 64 |       const uriSpec = new URI();
 65 |       const metadata = await uriSpec.getMetadata(mediaURI, this.options);
 66 |       return { uri: ens, ...metadata };
 67 |     }
 68 | 
 69 |     // parse retrieved avatar uri
 70 |     const { chainID, namespace, contractAddress, tokenID } = parseNFT(mediaURI);
 71 |     // detect avatar spec by namespace
 72 |     const Spec = specs[namespace];
 73 |     if (!Spec)
 74 |       throw new UnsupportedNamespace(`Unsupported namespace: ${namespace}`);
 75 |     const spec = new Spec();
 76 | 
 77 |     // add meta information of the avatar record
 78 |     const host_meta = {
 79 |       chain_id: chainID,
 80 |       namespace,
 81 |       contract_address: contractAddress,
 82 |       token_id: tokenID,
 83 |       reference_url: `https://opensea.io/assets/${contractAddress}/${tokenID}`,
 84 |     };
 85 | 
 86 |     // retrieve metadata
 87 |     const metadata = await spec.getMetadata(
 88 |       this.provider,
 89 |       resolvedAddress,
 90 |       contractAddress,
 91 |       tokenID,
 92 |       this.options
 93 |     );
 94 |     return { uri: ens, host_meta, ...metadata };
 95 |   }
 96 | 
 97 |   async getAvatar(
 98 |     ens: string,
 99 |     data?: AvatarRequestOpts
100 |   ): Promise<string | null> {
101 |     return this._getMedia(ens, 'avatar', data);
102 |   }
103 | 
104 |   async getHeader(
105 |     ens: string,
106 |     data?: HeaderRequestOpts
107 |   ): Promise<string | null> {
108 |     const mediaKey = data?.mediaKey || 'header';
109 |     if (!['header', 'banner'].includes(mediaKey)) {
110 |       throw new UnsupportedMediaKey('Unsupported media key');
111 |     }
112 |     return this._getMedia(ens, mediaKey, data);
113 |   }
114 | 
115 |   async _getMedia(
116 |     ens: string,
117 |     mediaKey: MediaKey = 'avatar',
118 |     data?: HeaderRequestOpts
119 |   ) {
120 |     const metadata = await this.getMetadata(ens, mediaKey);
121 |     if (!metadata) return null;
122 |     const imageURI = getImageURI({
123 |       metadata,
124 |       gateways: {
125 |         ipfs: this.options?.ipfs,
126 |         arweave: this.options?.arweave,
127 |       },
128 |       jsdomWindow: data?.jsdomWindow,
129 |       urlDenyList: this.options?.urlDenyList,
130 |     });
131 |     if (
132 |       // do check only NFTs since raw uri has this check built-in
133 |       metadata.hasOwnProperty('host_meta') &&
134 |       imageURI?.startsWith('http')
135 |     ) {
136 |       const isImage = await isImageURI(imageURI);
137 |       return isImage ? imageURI : null;
138 |     }
139 |     return imageURI;
140 |   }
141 | }
142 | 
143 | export { utils };
144 | 


--------------------------------------------------------------------------------
/example/browser.js:
--------------------------------------------------------------------------------
  1 | const { StaticJsonRpcProvider } = require('@ethersproject/providers');
  2 | const { AvatarResolver, utils: avtUtils } = require('../dist/index');
  3 | 
  4 | const ensNames = [
  5 |   'achal.eth',
  6 |   'alisha.eth',
  7 |   'jefflau.eth',
  8 |   'leontalbert.eth',
  9 |   'matoken.eth',
 10 |   'nick.eth',
 11 |   'ricmoo.eth',
 12 |   'tanrikulu.eth',
 13 |   'taytems.eth',
 14 |   'validator.eth',
 15 |   'brantly.eth',
 16 |   'coinbase.eth',
 17 |   'she256.eth',
 18 |   'cory.eth',
 19 |   'avsa.eth',
 20 |   'lefteris.eth',
 21 |   'rainbowwallet.eth',
 22 |   'fireeyesdao.eth',
 23 |   'griff.eth',
 24 | ];
 25 | 
 26 | const notFoundImage =
 27 |   'data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMzAwcHgiIGhlaWdodD0iMzAwcHgiIHZpZXdCb3g9IjAgMCAzMDAgMzAwIiB2ZXJzaW9uPSIxLjEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiPgogICAgPHRpdGxlPkdyb3VwPC90aXRsZT4KICAgIDxnIGlkPSJQYWdlLTEiIHN0cm9rZT0ibm9uZSIgc3Ryb2tlLXdpZHRoPSIxIiBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPgogICAgICAgIDxnIGlkPSJHcm91cCI+CiAgICAgICAgICAgIDxyZWN0IGlkPSJSZWN0YW5nbGUiIGZpbGw9IiMwMDAwMDAiIHg9IjAiIHk9IjAiIHdpZHRoPSIzMDAiIGhlaWdodD0iMzAwIj48L3JlY3Q+CiAgICAgICAgICAgIDx0ZXh0IGlkPSJDb3VsZC1ub3QtbG9hZC06KCIgZm9udC1mYW1pbHk9IlBsdXNKYWthcnRhU2Fucy1Cb2xkLCBQbHVzIEpha2FydGEgU2FucyIgZm9udC1zaXplPSIzMCIgZm9udC13ZWlnaHQ9ImJvbGQiIGZpbGw9IiNGRkZGRkYiPgogICAgICAgICAgICAgICAgPHRzcGFuIHg9IjEwNi4wMDUiIHk9IjEyNCI+Q291bGQgPC90c3Bhbj4KICAgICAgICAgICAgICAgIDx0c3BhbiB4PSIxMjUuMjgiIHk9IjE2MiI+bm90IDwvdHNwYW4+CiAgICAgICAgICAgICAgICA8dHNwYW4geD0iMTAzLjYzNSIgeT0iMjAwIj5sb2FkIDooPC90c3Bhbj4KICAgICAgICAgICAgPC90ZXh0PgogICAgICAgIDwvZz4KICAgIDwvZz4KPC9zdmc+';
 28 | const provider = new StaticJsonRpcProvider(
 29 |   `https://mainnet.infura.io/v3/${process.env.INFURA_KEY}`
 30 | );
 31 | const avt = new AvatarResolver(provider, {
 32 |   apiKey: { opensea: process.env.OPENSEA_KEY },
 33 | });
 34 | for (let ens of ensNames) {
 35 |   avt
 36 |     .getMetadata(ens)
 37 |     .then(metadata => {
 38 |       const avatar = avtUtils.getImageURI({
 39 |         metadata,
 40 |         gateways: { ipfs: 'https://ipfs.io' },
 41 |       });
 42 |       createImage(ens, avatar);
 43 |     })
 44 |     .catch(error => {
 45 |       console.warn(error);
 46 |       createImage(ens);
 47 |     });
 48 | }
 49 | 
 50 | function createImage(ens, avatarUri = notFoundImage) {
 51 |   const elem = document.createElement('img');
 52 |   elem.setAttribute('src', avatarUri);
 53 |   elem.setAttribute('height', '300');
 54 |   elem.setAttribute('width', '300');
 55 |   elem.setAttribute('alt', ens);
 56 |   elem.style = 'border-radius: 5px;';
 57 |   elem.style.opacity = '0';
 58 |   elem.addEventListener('load', fadeImg);
 59 |   document.getElementById('avatars').appendChild(elem);
 60 | }
 61 | 
 62 | function fadeImg() {
 63 |   this.style.transition = 'opacity 2s';
 64 |   this.style.opacity = '1';
 65 | }
 66 | 
 67 | function setImage(ens, avatarUri = notFoundImage, warn = false, headerUri) {
 68 |   const elem = document.getElementById('queryImage');
 69 |   const headerContainer = document.getElementById('headerContainer');
 70 |   elem.setAttribute('src', avatarUri);
 71 |   elem.setAttribute('alt', ens);
 72 |   headerContainer.style.backgroundImage = headerUri ? `url("${headerUri}")` : 'none';
 73 |   const warnText = document.getElementById('warnText');
 74 |   if (warn) {
 75 |     if (warnText) return;
 76 |     const newWarnText = document.createElement('div');
 77 |     newWarnText.id = 'warnText';
 78 |     newWarnText.textContent = 'The query is not valid';
 79 |     newWarnText.style.color = 'red';
 80 |     newWarnText.style.lineHeight = '10px';
 81 |     elem.setAttribute('height', 290);
 82 |     elem.parentNode.insertBefore(newWarnText, elem.nextSibling);
 83 |   } else {
 84 |     elem.setAttribute('height', 300);
 85 |     warnText && warnText.remove();
 86 |   }
 87 | }
 88 | 
 89 | document.getElementById('queryInput').addEventListener('change', event => {
 90 |   let ens = event.target.value;
 91 |   ens = ens.toLowerCase().trim();
 92 | 
 93 |   if (ens === 'nevergonnagiveyouup' || ens === 'rickroll') {
 94 |     setImage(
 95 |       'rickroll',
 96 |       'http://ipfs.io/ipfs/QmPmU7h1rcZkivDntjvfh8BJB5Yk32ozMjPd12HNMoAZZ8'
 97 |     );
 98 |     return;
 99 |   }
100 | 
101 |   if (ens.length < 7 || !ens.endsWith('.eth')) {
102 |     setImage(
103 |       'fail',
104 |       'http://ipfs.io/ipfs/QmYVZtV4Xtbqqj6hKojgbLskf5b1rV2wNfpAwgZ2EBuQnD',
105 |       true
106 |     );
107 |     return;
108 |   }
109 | 
110 |   const elem = document.getElementById('queryImage');
111 |   elem.style.filter = 'blur(5px) grayscale(70%)';
112 |   elem.style.transition = 'filter .5s';
113 |   avt
114 |     .getMetadata(ens)
115 |     .then(metadata => {
116 |       const avatar = avtUtils.getImageURI({ metadata });
117 |       avt.getHeader(ens).then(header => {
118 |         setImage(ens, avatar, false, header);
119 |       });
120 |       elem.style.filter = 'none';
121 |     })
122 |     .catch(error => {
123 |       console.warn(error);
124 |       setImage(ens);
125 |       elem.style.filter = 'none';
126 |     });
127 | });
128 | 


--------------------------------------------------------------------------------
/src/utils/fetch.ts:
--------------------------------------------------------------------------------
  1 | import axios, { Axios, AxiosInstance } from 'axios';
  2 | import { isBrowser, isNode } from './detectPlatform';
  3 | import { AxiosAgents } from '../types';
  4 | 
  5 | let http: any;
  6 | let https: any;
  7 | let requestFilterHandler: any;
  8 | 
  9 | // Dynamically import Node.js modules only in Node.js environment
 10 | if (isNode) {
 11 |   http = require('http');
 12 |   https = require('https');
 13 |   const ssrfFilter = require('ssrf-req-filter');
 14 |   requestFilterHandler = ssrfFilter.requestFilterHandler;
 15 | }
 16 | 
 17 | /**
 18 |  * Creates an axios instance with fetch adapter and optional configuration
 19 |  *
 20 |  * SSRF PROTECTION BEHAVIOR:
 21 |  * - If NO custom agents provided: Automatically creates agents with SSRF protection
 22 |  *   that blocks private IPs (localhost, 127.x.x.x, 10.x.x.x, 192.168.x.x, etc.)
 23 |  * - If custom agents provided: Uses them as-is WITHOUT wrapping or modifying them.
 24 |  *   You are responsible for ensuring your custom agents have appropriate security.
 25 |  * - If allowPrivateIPs=true: Disables SSRF protection (only for local development)
 26 |  *
 27 |  * @param ttl - Cache time-to-live in seconds
 28 |  * @param agents - Custom HTTP/HTTPS agents (bypasses built-in SSRF protection)
 29 |  * @param maxContentLength - Maximum response content length in bytes
 30 |  * @param allowPrivateIPs - Allow private IPs (localhost, 127.0.0.1, etc.) - ONLY for development
 31 |  * @returns Configured axios instance
 32 |  */
 33 | export function createFetcher({
 34 |   ttl,
 35 |   agents,
 36 |   maxContentLength,
 37 |   allowPrivateIPs,
 38 | }: {
 39 |   ttl?: number;
 40 |   agents?: AxiosAgents;
 41 |   maxContentLength?: number;
 42 |   allowPrivateIPs?: boolean;
 43 | } = {}): Axios | AxiosInstance {
 44 |   const baseConfig: any = {
 45 |     // Use fetch adapter when available (browser, Cloudflare Workers, Node.js with fetch support)
 46 |     // Falls back to default adapters (xhr in browser, http in Node.js) if fetch is not available
 47 |     adapter: typeof globalThis.fetch !== 'undefined' ? 'fetch' : undefined,
 48 |     proxy: false,
 49 |     ...(maxContentLength && { maxContentLength }),
 50 |   };
 51 | 
 52 |   const _fetch = axios.create(baseConfig);
 53 | 
 54 |   let fetchInstance: Axios | AxiosInstance = _fetch;
 55 | 
 56 |   // Apply caching if TTL is specified
 57 |   if (ttl && ttl > 0) {
 58 |     const { setupCache } = require('axios-cache-interceptor');
 59 |     fetchInstance = setupCache(_fetch, {
 60 |       ttl: ttl * 1000,
 61 |     });
 62 |   }
 63 | 
 64 |   // Apply agent configuration for Node.js environments only
 65 |   // Cloudflare Workers don't support HTTP agents (use native fetch with built-in SSRF protection)
 66 |   if (isNode) {
 67 |     let finalAgents: AxiosAgents = {};
 68 | 
 69 |     if (agents && Object.values(agents).length) {
 70 |       // User provided custom agents - use them as-is without wrapping
 71 |       // They may have their own SSRF protection or specific requirements
 72 |       finalAgents = agents;
 73 |     } else if (!allowPrivateIPs && http && https && requestFilterHandler) {
 74 |       // No custom agents provided - create default agents with SSRF protection
 75 |       finalAgents = {
 76 |         httpAgent: requestFilterHandler(new http.Agent()),
 77 |         httpsAgent: requestFilterHandler(new https.Agent()),
 78 |       };
 79 |     }
 80 |     // If allowPrivateIPs is true and no custom agents, don't create any agents
 81 |     // (will use axios defaults which allow all IPs)
 82 | 
 83 |     // Apply agents if available
 84 |     if (Object.values(finalAgents).length) {
 85 |       fetchInstance.interceptors.request.use(config => {
 86 |         // Note: In axios 1.x with fetch adapter, use 'dispatcher' for undici agent
 87 |         // For backward compatibility, we support both httpAgent/httpsAgent and dispatcher
 88 |         if (finalAgents.httpAgent || finalAgents.httpsAgent) {
 89 |           // Legacy support - map to dispatcher if available
 90 |           // @ts-ignore - dispatcher is not in standard axios types but supported by fetch adapter
 91 |           config.dispatcher = finalAgents.httpAgent || finalAgents.httpsAgent;
 92 |         }
 93 |         return config;
 94 |       });
 95 |     }
 96 |   }
 97 | 
 98 |   return fetchInstance;
 99 | }
100 | 
101 | /**
102 |  * @deprecated Use createFetcher instead. This will be removed in a future version.
103 |  */
104 | export function createAgentAdapter(fetch: Axios, agents?: AxiosAgents) {
105 |   if (!isBrowser && agents && Object.values(agents || {}).length) {
106 |     fetch.interceptors.request.use(config => {
107 |       // @ts-ignore
108 |       config.dispatcher = agents.httpAgent || agents.httpsAgent;
109 |       return config;
110 |     });
111 |   }
112 | }
113 | 
114 | /**
115 |  * @deprecated Use createFetcher instead. This will be removed in a future version.
116 |  */
117 | export function createCacheAdapter(fetch: Axios, ttl: number): AxiosInstance {
118 |   const { setupCache } = require('axios-cache-interceptor');
119 |   return setupCache(fetch, {
120 |     ttl: ttl * 1000,
121 |   });
122 | }
123 | 
124 | // Default fetch instance without any configuration
125 | export const fetch = createFetcher({});
126 | 


--------------------------------------------------------------------------------
/src/utils/isImageURI.ts:
--------------------------------------------------------------------------------
  1 | import axios, { AxiosError } from 'axios';
  2 | import { Buffer } from 'buffer/';
  3 | 
  4 | import { fetch } from './fetch';
  5 | 
  6 | export const ALLOWED_IMAGE_MIMETYPES = [
  7 |   'application/octet-stream',
  8 |   'image/jpeg',
  9 |   'image/png',
 10 |   'image/gif',
 11 |   'image/webp',
 12 |   'image/svg+xml',
 13 |   'image/bmp',
 14 |   'image/avif',
 15 |   'image/heic',
 16 |   'image/heif',
 17 |   'image/jxl',
 18 | ];
 19 | 
 20 | export const IMAGE_SIGNATURES = {
 21 |   FFD8FF: 'image/jpeg',
 22 |   '89504E47': 'image/png',
 23 |   '47494638': 'image/gif',
 24 |   '424D': 'image/bmp',
 25 |   FF0A: 'image/jxl',
 26 | };
 27 | 
 28 | const MAX_FILE_SIZE = 300 * 1024 * 1024; // 300 MB
 29 | 
 30 | function isURIEncoded(uri: string): boolean {
 31 |   try {
 32 |     return uri !== decodeURIComponent(uri);
 33 |   } catch {
 34 |     return false;
 35 |   }
 36 | }
 37 | 
 38 | async function isStreamAnImage(url: string): Promise<boolean> {
 39 |   try {
 40 |     const source = axios.CancelToken.source();
 41 |     const response = await fetch.get(url, {
 42 |       responseType: 'arraybuffer',
 43 |       headers: {
 44 |         Range: 'bytes=0-1023', // Download only the first 1024 bytes
 45 |       },
 46 |       cancelToken: source.token,
 47 |       onDownloadProgress: progressEvent => {
 48 |         if (progressEvent.loaded > 1024) {
 49 |           // Cancel the request if more than 1024 bytes have been downloaded
 50 |           source.cancel('Aborted to prevent downloading the entire file.');
 51 |         }
 52 |       },
 53 |     });
 54 | 
 55 |     if (response.headers['content-length']) {
 56 |       const contentLength = parseInt(response.headers['content-length'], 10);
 57 |       if (contentLength > MAX_FILE_SIZE) {
 58 |         console.warn(`isStreamAnImage: File too large ${contentLength} bytes`);
 59 |         return false;
 60 |       }
 61 |     }
 62 | 
 63 |     let magicNumbers: string;
 64 |     // Check the binary signature (magic numbers) of the data
 65 |     if (response.data instanceof ArrayBuffer) {
 66 |       magicNumbers = new DataView(response.data).getUint32(0).toString(16);
 67 |     } else {
 68 |       if (
 69 |         !response.data ||
 70 |         typeof response.data === 'string' ||
 71 |         !('readUInt32BE' in response.data)
 72 |       ) {
 73 |         throw 'isStreamAnImage: unsupported data, instance is not BufferLike';
 74 |       }
 75 |       magicNumbers = response.data.readUInt32BE(0).toString(16);
 76 |     }
 77 | 
 78 |     const isBinaryImage = Object.keys(IMAGE_SIGNATURES).some(signature =>
 79 |       magicNumbers.toUpperCase().startsWith(signature)
 80 |     );
 81 | 
 82 |     // Check for SVG image
 83 |     const chunkAsString = Buffer.from(response.data).toString();
 84 |     const isSvgImage = /<svg[\s\S]*?xmlns="http:\/\/www\.w3\.org\/2000\/svg"/.test(
 85 |       chunkAsString
 86 |     );
 87 | 
 88 |     return isBinaryImage || isSvgImage;
 89 |   } catch (error) {
 90 |     if (axios.isCancel(error)) {
 91 |       console.error('Stream request was canceled:', (error as Error).message);
 92 |     } else {
 93 |       console.error('Error checking stream:', error);
 94 |     }
 95 |     return false;
 96 |   }
 97 | }
 98 | 
 99 | export async function isImageURI(url: string): Promise<boolean> {
100 |   const encodedURI = isURIEncoded(url) ? url : encodeURI(url);
101 | 
102 |   try {
103 |     const result = await fetch.head(encodedURI);
104 | 
105 |     if (result.status === 200) {
106 |       const contentType = result.headers['content-type']?.toLowerCase();
107 | 
108 |       if (!contentType || !ALLOWED_IMAGE_MIMETYPES.includes(contentType)) {
109 |         console.warn(`isImageURI: Invalid content type ${contentType}`);
110 |         return false;
111 |       }
112 | 
113 |       const contentLength = parseInt(
114 |         result.headers['content-length'] || '0',
115 |         10
116 |       );
117 |       if (contentLength > MAX_FILE_SIZE) {
118 |         console.warn(`isImageURI: File too large ${contentLength} bytes`);
119 |         return false;
120 |       }
121 | 
122 |       if (contentType === 'application/octet-stream') {
123 |         // if image served with generic mimetype, do additional check
124 |         return isStreamAnImage(encodedURI);
125 |       }
126 | 
127 |       return true;
128 |     } else {
129 |       console.warn(`isImageURI: HTTP error ${result.status}`);
130 |       return false;
131 |     }
132 |   } catch (error) {
133 |     if (error instanceof AxiosError) {
134 |       console.warn(
135 |         'isImageURI: ',
136 |         error.toString(),
137 |         '-',
138 |         error.config?.url || 'unknown'
139 |       );
140 |     } else {
141 |       console.warn('isImageURI: ', error.toString());
142 |     }
143 | 
144 |     // if error is not cors related then fail
145 |     if (typeof (error as any).response !== 'undefined') {
146 |       // in case of cors, use image api to validate if given url is an actual image
147 |       return false;
148 |     }
149 | 
150 |     if (!globalThis.hasOwnProperty('Image')) {
151 |       // fail in NodeJS, since the error is not cors but any other network issue
152 |       return false;
153 |     }
154 | 
155 |     return new Promise<boolean>(resolve => {
156 |       const img = new Image();
157 |       img.onload = () => resolve(true);
158 |       img.onerror = () => resolve(false);
159 |       img.src = encodedURI;
160 |     });
161 |   }
162 | }
163 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # ens-avatar
  2 | 
  3 | Avatar resolver library for Node.js, browsers, and edge runtimes (Cloudflare Workers etc.).
  4 | 
  5 | ## Important Notes
  6 | 
  7 | - **ENS-Avatar >= 1.0.0** is only compatible with ethers v6. If your project is using v5, keep your ens-avatar on latest 0.x version.
  8 | - **Version 1.0.4+** uses the native Fetch API for maximum compatibility across platforms including Cloudflare Workers and other edge runtimes.
  9 | 
 10 | ## Platform Support
 11 | 
 12 | This library works seamlessly across:
 13 | - ✅ **Node.js** 18+ (uses native fetch or http adapter)
 14 | - ✅ **Browsers** (all modern browsers)
 15 | - ✅ **Cloudflare Workers**
 16 | - ✅ **Other edge runtimes** that support standard Fetch API
 17 | 
 18 | ## Getting started
 19 | 
 20 | ### Prerequisites
 21 | 
 22 | - Have your web3 provider ready (web3.js, ethers.js)
 23 | - [Only for node env] Have jsdom installed.
 24 | 
 25 | And good to go!
 26 | 
 27 | ### Installation
 28 | 
 29 | ```bash
 30 | # npm
 31 | npm i @ensdomains/ens-avatar
 32 | # yarn
 33 | yarn add @ensdomains/ens-avatar
 34 | ```
 35 | 
 36 | ### Usage
 37 | 
 38 | ```js
 39 | import { StaticJsonRpcProvider } from '@ethersproject/providers';
 40 | import { AvatarResolver, utils as avtUtils } from '@ensdomains/ens-avatar';
 41 | 
 42 | // const { JSDOM } = require('jsdom'); on nodejs
 43 | // const jsdom = new JSDOM().window; on nodejs
 44 | 
 45 | const provider = new StaticJsonRpcProvider(
 46 |     ...
 47 |   );
 48 | ...
 49 | async function getAvatar() {
 50 |     const resolver = new AvatarResolver(provider);
 51 |     const avatarURI = await resolver.getAvatar('tanrikulu.eth', { /* jsdomWindow: jsdom (on nodejs) */ });
 52 |     // avatarURI = https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR
 53 | }
 54 | 
 55 | async function getHeader() {
 56 |     const resolver = new AvatarResolver(provider);
 57 |     const headerURI = await resolver.getHeader('tanrikulu.eth', { /* jsdomWindow: jsdom (on nodejs) */ });
 58 |     // headerURI = https://ipfs.io/ipfs/QmRFnn6c9rj6NuHenFVyKXb6tuKxynAvGiw7yszQJ2EsjN
 59 | }
 60 | 
 61 | async function getAvatarMetadata() {
 62 |     const resolver = new AvatarResolver(provider);
 63 |     const avatarMetadata = await resolver.getMetadata('tanrikulu.eth');
 64 |     // avatarMetadata = { image: ... , uri: ... , name: ... , description: ... }
 65 |     const headerMetadata = await resolver.getMetadata('tanrikulu.eth', 'header');
 66 |     // headerMetadata = { image: ... , uri: ... , name: ... , description: ... }
 67 |     const avatarURI = avtUtils.getImageURI({ metadata: avatarMetadata /*, jsdomWindow: jsdom (on nodejs) */ });
 68 |     // avatarURI = https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR
 69 | }
 70 | ```
 71 | 
 72 | ## Supported avatar specs
 73 | 
 74 | ### NFTs
 75 | 
 76 | - ERC721
 77 | - ERC1155
 78 | 
 79 | ### URIs
 80 | 
 81 | - HTTP
 82 | - Base64
 83 | - IPFS
 84 | 
 85 | ## Options
 86 | 
 87 | ### Cache _(Default: Disabled)_
 88 | 
 89 | ```js
 90 | const avt = new AvatarResolver(provider, { cache: 300 }); // 5 min response cache in memory
 91 | ```
 92 | 
 93 | ### Custom IPFS Gateway _(Default: https://ipfs.io)_
 94 | 
 95 | ```js
 96 | const avt = new AvatarResolver(provider, { ipfs: 'https://dweb.link' });
 97 | ```
 98 | 
 99 | ### Custom Arweave Gateway _(Default: https://arweave.net)_
100 | 
101 | ```js
102 | const avt = new AvatarResolver(provider, { arweave: 'https://arweave.net' });
103 | ```
104 | 
105 | ### Marketplace Api Keys _(Default: {})_
106 | 
107 | ```js
108 | const avt = new AvatarResolver(provider, {
109 |   apiKey: {
110 |     opensea: 'YOUR_API_KEY',
111 |   },
112 | });
113 | ```
114 | 
115 | ### URL DenyList _(Default: [])_
116 | 
117 | ```js
118 | const avt = new AvatarResolver(provider, {
119 |   urlDenyList: ['https://maliciouswebsite.com'],
120 | });
121 | ```
122 | 
123 | ### Custom Agents (Node.js only)
124 | 
125 | You can provide custom HTTP/HTTPS agents for advanced use cases:
126 | 
127 | ```js
128 | import http from 'http';
129 | import https from 'https';
130 | 
131 | const avt = new AvatarResolver(provider, {
132 |   agents: {
133 |     httpAgent: new http.Agent({ keepAlive: true }),
134 |     httpsAgent: new https.Agent({ keepAlive: true }),
135 |   },
136 | });
137 | ```
138 | 
139 | **⚠️ SECURITY WARNING**: When you provide custom agents, ens-avatar will use them as-is **without applying SSRF protection**. You are responsible for ensuring your custom agents have appropriate security measures to prevent Server-Side Request Forgery attacks.
140 | 
141 | If you need SSRF protection with custom agents, wrap them with `ssrf-req-filter`:
142 | 
143 | ```js
144 | import http from 'http';
145 | import https from 'https';
146 | const { requestFilterHandler } = require('ssrf-req-filter');
147 | 
148 | const avt = new AvatarResolver(provider, {
149 |   agents: {
150 |     httpAgent: requestFilterHandler(new http.Agent({ keepAlive: true })),
151 |     httpsAgent: requestFilterHandler(new https.Agent({ keepAlive: true })),
152 |   },
153 | });
154 | ```
155 | 
156 | ### Allow Private IPs _(Default: false)_ - **Development Only**
157 | 
158 | For local development when you need to access localhost or private network services:
159 | 
160 | ```js
161 | const avt = new AvatarResolver(provider, {
162 |   allowPrivateIPs: true, // Allows localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x, etc.
163 | });
164 | ```
165 | 
166 | **⚠️ WARNING**: This disables SSRF protection. Only use for local development (e.g., local IPFS nodes, test servers). **NEVER enable this in production**.
167 | 
168 | Common local development scenarios:
169 | - Local IPFS node: `http://127.0.0.1:5001`
170 | - Local Ethereum node: `http://localhost:8545`
171 | - Docker containers on private networks
172 | 
173 | **Note**: This flag is ignored if you provide custom agents (you control security in that case).
174 | 
175 | ## Security
176 | 
177 | ### XSS Protection
178 | 
179 | All user-generated SVG content is automatically sanitized to prevent XSS attacks:
180 | 
181 | - **Browser/Node.js**: Uses [DOMPurify](https://github.com/cure53/DOMPurify) (8.74 KB, battle-tested)
182 | - **Cloudflare Workers**: Uses [sanitize-html](https://github.com/apostrophecms/sanitize-html) (parser-based, no DOM dependency)
183 | 
184 | Both sanitizers are production-ready, actively maintained, and specifically configured for secure SVG handling.
185 | 
186 | ### SSRF Protection
187 | 
188 | **By default**, ens-avatar includes built-in protection against Server-Side Request Forgery (SSRF) attacks in Node.js environments. This prevents malicious actors from using avatar URLs to probe internal networks.
189 | 
190 | **Default behavior** (recommended for production):
191 | - ✅ Blocks requests to `localhost`, `127.0.0.1`
192 | - ✅ Blocks private IP ranges: `10.x.x.x`, `192.168.x.x`, `172.16.x.x-172.31.x.x`
193 | - ✅ Blocks link-local and other internal addresses
194 | 
195 | **Custom agents**: If you provide your own HTTP/HTTPS agents, ens-avatar will use them as-is without applying SSRF protection. You are responsible for securing your custom agents.
196 | 
197 | **Local development**: Set `allowPrivateIPs: true` to disable SSRF protection when you need to access local services (e.g., local IPFS nodes). Never use this in production.
198 | 
199 | See the [Custom Agents](#custom-agents-nodejs-only) section for more details.
200 | 
201 | ---
202 | 
203 | > **⚠️ SECURITY DISCLAIMER**
204 | >
205 | > While ens-avatar implements security measures to help protect against XSS and SSRF attacks, **you are ultimately responsible for the security of your application**. We strongly recommend:
206 | >
207 | > - Conducting your own security audits before deploying to production
208 | > - Implementing additional security layers appropriate for your use case
209 | > - Keeping the library updated to receive security patches
210 | > - Following security best practices when handling user-generated content
211 | > - Properly configuring all security-related options for your environment
212 | >
213 | > This library is provided "as-is" without warranty. The maintainers are not liable for any security vulnerabilities in applications using this library.
214 | 
215 | ## Demo
216 | 
217 | - Create .env file with INFURA_KEY env variable
218 | - Build the library
219 | 
220 | - Node example
221 | 
222 | ```bash
223 | node example/node.js ENS_NAME
224 | ```
225 | 
226 | - Browser example
227 | 
228 | ```bash
229 | yarn build:demo
230 | http-server example
231 | ```
232 | 


--------------------------------------------------------------------------------
/src/utils/sanitize.ts:
--------------------------------------------------------------------------------
  1 | /**
  2 |  * Platform-specific SVG sanitization
  3 |  *
  4 |  * - Browser/Node.js: Uses DOMPurify (8.74 KB, battle-tested, superior SVG support)
  5 |  * - Cloudflare Workers: Uses sanitize-html (900 KB, parser-based, works without DOM)
  6 |  *
  7 |  * Both sanitizers are production-ready and actively maintained for security.
  8 |  */
  9 | 
 10 | // Detect runtime environment
 11 | const hasWindow = typeof window !== 'undefined';
 12 | const hasGlobalThis = typeof globalThis !== 'undefined';
 13 | const isCloudflareWorker =
 14 |   hasGlobalThis && !hasWindow && typeof globalThis.fetch === 'function';
 15 | 
 16 | /**
 17 |  * Sanitize SVG content to prevent XSS attacks
 18 |  * @param svg - Raw SVG string
 19 |  * @param jsdomWindow - Optional JSDOM window (required for Node.js when using DOMPurify)
 20 |  * @returns Sanitized SVG string
 21 |  */
 22 | export function sanitizeSVG(svg: string, jsdomWindow?: any): string {
 23 |   // Strategy 1: DOMPurify (Browser or Node.js with JSDOM)
 24 |   if (!isCloudflareWorker) {
 25 |     return sanitizeWithDOMPurify(svg, jsdomWindow);
 26 |   }
 27 | 
 28 |   // Strategy 2: sanitize-html (Cloudflare Workers)
 29 |   return sanitizeWithSanitizeHtml(svg);
 30 | }
 31 | 
 32 | /**
 33 |  * DOMPurify-based sanitization (Browser/Node.js)
 34 |  * Requires window object (native in browser, JSDOM in Node.js)
 35 |  */
 36 | function sanitizeWithDOMPurify(svg: string, jsdomWindow?: any): string {
 37 |   const createDOMPurify = require('dompurify');
 38 | 
 39 |   let domWindow;
 40 |   try {
 41 |     domWindow = window;
 42 |   } catch {
 43 |     // Node.js environment - require JSDOM window
 44 |     if (!jsdomWindow) {
 45 |       throw Error(
 46 |         'In Node.js environment, JSDOM window is required for DOMPurify'
 47 |       );
 48 |     }
 49 |     domWindow = jsdomWindow;
 50 |   }
 51 | 
 52 |   const DOMPurify = createDOMPurify(domWindow as any);
 53 | 
 54 |   // Add security hooks
 55 |   DOMPurify.addHook('uponSanitizeElement', (node: any, data: any) => {
 56 |     // Remove meta refresh tags (can be used for phishing)
 57 |     if (data.tagName === 'meta') {
 58 |       if (node.getAttribute('http-equiv') === 'refresh') {
 59 |         node.remove();
 60 |       }
 61 |     }
 62 |   });
 63 | 
 64 |   // Hook to sanitize xlink:href attributes (XSS vector)
 65 |   DOMPurify.addHook('uponSanitizeAttribute', (node: any, data: any) => {
 66 |     // Block javascript: URLs in href and xlink:href attributes
 67 |     if (data.attrName === 'xlink:href' || data.attrName === 'href') {
 68 |       const value = data.attrValue;
 69 |       if (value && typeof value === 'string') {
 70 |         const normalized = value.toLowerCase().trim();
 71 |         // Block javascript:, data:text/html, and vbscript: URLs
 72 |         if (
 73 |           normalized.startsWith('javascript:') ||
 74 |           normalized.startsWith('data:text/html') ||
 75 |           normalized.startsWith('vbscript:')
 76 |         ) {
 77 |           data.keepAttr = false;
 78 |           node.removeAttribute(data.attrName);
 79 |         }
 80 |       }
 81 |     }
 82 |   });
 83 | 
 84 |   // Sanitize with SVG profile and forbidden tags
 85 |   const cleanDOM = DOMPurify.sanitize(svg, {
 86 |     USE_PROFILES: { svg: true, svgFilters: true },
 87 |     FORBID_TAGS: ['a', 'area', 'base', 'iframe', 'link', 'script'],
 88 |     FORBID_ATTR: ['xlink:href'], // Block xlink:href entirely (deprecated, use href)
 89 |   });
 90 | 
 91 |   return cleanDOM;
 92 | }
 93 | 
 94 | /**
 95 |  * sanitize-html-based sanitization (Cloudflare Workers)
 96 |  * Parser-based, no DOM dependency
 97 |  */
 98 | function sanitizeWithSanitizeHtml(svg: string): string {
 99 |   const sanitizeHtml = require('sanitize-html');
100 | 
101 |   // Comprehensive SVG element and attribute whitelist
102 |   // Based on DOMPurify's SVG profile and SVG 1.1/2.0 specs
103 |   const allowedTags = [
104 |     // SVG root and structure
105 |     'svg',
106 |     'g',
107 |     'defs',
108 |     'symbol',
109 |     'use',
110 |     'marker',
111 |     'clipPath',
112 |     'mask',
113 |     'pattern',
114 |     // Shapes
115 |     'circle',
116 |     'ellipse',
117 |     'line',
118 |     'path',
119 |     'polygon',
120 |     'polyline',
121 |     'rect',
122 |     // Text
123 |     'text',
124 |     'tspan',
125 |     'textPath',
126 |     // Gradients and filters
127 |     'linearGradient',
128 |     'radialGradient',
129 |     'stop',
130 |     'filter',
131 |     'feBlend',
132 |     'feColorMatrix',
133 |     'feComponentTransfer',
134 |     'feComposite',
135 |     'feConvolveMatrix',
136 |     'feDiffuseLighting',
137 |     'feDisplacementMap',
138 |     'feFlood',
139 |     'feGaussianBlur',
140 |     'feImage',
141 |     'feMerge',
142 |     'feMergeNode',
143 |     'feMorphology',
144 |     'feOffset',
145 |     'feSpecularLighting',
146 |     'feTile',
147 |     'feTurbulence',
148 |     'feDistantLight',
149 |     'fePointLight',
150 |     'feSpotLight',
151 |     'feFuncR',
152 |     'feFuncG',
153 |     'feFuncB',
154 |     'feFuncA',
155 |     // Other
156 |     'image',
157 |     'foreignObject',
158 |     'title',
159 |     'desc',
160 |     'metadata',
161 |   ];
162 | 
163 |   const allowedAttributes: { [key: string]: string[] } = {
164 |     // Global SVG attributes (apply to all tags)
165 |     '*': [
166 |       'id',
167 |       'class',
168 |       'style',
169 |       'transform',
170 |       'fill',
171 |       'fill-opacity',
172 |       'fill-rule',
173 |       'stroke',
174 |       'stroke-width',
175 |       'stroke-opacity',
176 |       'stroke-linecap',
177 |       'stroke-linejoin',
178 |       'stroke-dasharray',
179 |       'stroke-dashoffset',
180 |       'opacity',
181 |       'visibility',
182 |       'display',
183 |       'clip-path',
184 |       'clip-rule',
185 |       'mask',
186 |       'filter',
187 |       'color',
188 |       'color-interpolation',
189 |     ],
190 |     svg: [
191 |       'xmlns',
192 |       'xmlns:xlink',
193 |       'viewBox',
194 |       'preserveAspectRatio',
195 |       'width',
196 |       'height',
197 |       'x',
198 |       'y',
199 |       'version',
200 |       'baseProfile',
201 |     ],
202 |     circle: ['cx', 'cy', 'r'],
203 |     ellipse: ['cx', 'cy', 'rx', 'ry'],
204 |     line: ['x1', 'y1', 'x2', 'y2'],
205 |     path: ['d', 'pathLength'],
206 |     polygon: ['points'],
207 |     polyline: ['points'],
208 |     rect: ['x', 'y', 'width', 'height', 'rx', 'ry'],
209 |     text: [
210 |       'x',
211 |       'y',
212 |       'dx',
213 |       'dy',
214 |       'text-anchor',
215 |       'font-family',
216 |       'font-size',
217 |       'font-weight',
218 |     ],
219 |     tspan: ['x', 'y', 'dx', 'dy', 'text-anchor'],
220 |     textPath: ['href', 'startOffset', 'method', 'spacing'],
221 |     use: ['href', 'x', 'y', 'width', 'height'],
222 |     image: ['href', 'x', 'y', 'width', 'height', 'preserveAspectRatio'],
223 |     linearGradient: [
224 |       'id',
225 |       'x1',
226 |       'y1',
227 |       'x2',
228 |       'y2',
229 |       'gradientUnits',
230 |       'gradientTransform',
231 |     ],
232 |     radialGradient: [
233 |       'id',
234 |       'cx',
235 |       'cy',
236 |       'r',
237 |       'fx',
238 |       'fy',
239 |       'gradientUnits',
240 |       'gradientTransform',
241 |     ],
242 |     stop: ['offset', 'stop-color', 'stop-opacity'],
243 |     pattern: [
244 |       'id',
245 |       'x',
246 |       'y',
247 |       'width',
248 |       'height',
249 |       'patternUnits',
250 |       'patternTransform',
251 |     ],
252 |     marker: [
253 |       'id',
254 |       'markerWidth',
255 |       'markerHeight',
256 |       'refX',
257 |       'refY',
258 |       'orient',
259 |       'markerUnits',
260 |     ],
261 |     clipPath: ['id', 'clipPathUnits'],
262 |     mask: ['id', 'x', 'y', 'width', 'height', 'maskUnits', 'maskContentUnits'],
263 |     filter: [
264 |       'id',
265 |       'x',
266 |       'y',
267 |       'width',
268 |       'height',
269 |       'filterUnits',
270 |       'primitiveUnits',
271 |     ],
272 |     g: ['id', 'transform'],
273 |     defs: ['id'],
274 |     symbol: ['id', 'viewBox', 'preserveAspectRatio'],
275 |   };
276 | 
277 |   const cleanSVG = sanitizeHtml(svg, {
278 |     allowedTags,
279 |     allowedAttributes,
280 |     // Preserve case for SVG elements (important!)
281 |     parser: {
282 |       lowerCaseTags: false,
283 |       lowerCaseAttributeNames: false,
284 |     },
285 |     // Disallow all protocols except safe ones
286 |     allowedSchemes: ['http', 'https', 'data'],
287 |     allowedSchemesByTag: {
288 |       image: ['http', 'https', 'data'],
289 |       use: ['http', 'https'],
290 |       textPath: ['http', 'https'],
291 |     },
292 |     // Additional disallowed schemes to be explicit
293 |     disallowedTagsMode: 'discard',
294 |     // Don't allow any iframe-related attributes
295 |     allowIframeRelativeUrls: false,
296 |     // Transform URLs to remove dangerous protocols
297 |     transformTags: {
298 |       use: (tagName: string, attribs: any) => {
299 |         // Additional safety check for href attribute
300 |         if (attribs.href && typeof attribs.href === 'string') {
301 |           const normalized = attribs.href.toLowerCase().trim();
302 |           if (
303 |             normalized.startsWith('javascript:') ||
304 |             normalized.startsWith('data:text/html') ||
305 |             normalized.startsWith('vbscript:')
306 |           ) {
307 |             delete attribs.href;
308 |           }
309 |         }
310 |         return { tagName, attribs };
311 |       },
312 |       image: (tagName: string, attribs: any) => {
313 |         // Additional safety check for href attribute
314 |         if (attribs.href && typeof attribs.href === 'string') {
315 |           const normalized = attribs.href.toLowerCase().trim();
316 |           if (
317 |             normalized.startsWith('javascript:') ||
318 |             normalized.startsWith('vbscript:')
319 |           ) {
320 |             delete attribs.href;
321 |           }
322 |         }
323 |         return { tagName, attribs };
324 |       },
325 |     },
326 |   });
327 | 
328 |   return cleanSVG;
329 | }
330 | 


--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
  1 | # Security
  2 | 
  3 | ## Overview
  4 | 
  5 | ENS Avatar library handles user-generated content (ENS avatar images and metadata) which may include malicious SVG files. This document describes our security measures and best practices.
  6 | 
  7 | ## Threat Model
  8 | 
  9 | ### Primary Threats
 10 | 
 11 | 1. **XSS via SVG**: Malicious users could set SVG avatars containing `<script>` tags, event handlers, `javascript:` URLs, or other XSS vectors
 12 | 2. **XSS via xlink:href**: SVG elements (`<use>`, `<image>`) with `xlink:href="javascript:..."` attributes
 13 | 3. **SSRF (Server-Side Request Forgery)**: Malicious URIs pointing to internal networks, localhost, or cloud metadata endpoints
 14 | 4. **Phishing via Meta Refresh**: SVG with `<meta http-equiv="refresh">` to redirect users to phishing sites
 15 | 5. **Clickjacking**: SVG with embedded `<iframe>` or `<a>` tags linking to malicious sites
 16 | 6. **Data Exfiltration**: SVG with external resource loading to malicious URLs
 17 | 
 18 | ### Attack Surface
 19 | 
 20 | - Avatars and headers in ENS domains can point to any URI (IPFS, HTTP, data URIs)
 21 | - SVG can be base64-encoded or raw
 22 | - Metadata is fetched from untrusted sources (NFT contracts, IPFS, HTTP)
 23 | 
 24 | ## Security Measures
 25 | 
 26 | ### 1. Automatic SVG Sanitization
 27 | 
 28 | All SVG content is sanitized before being returned to users. The library uses **platform-specific sanitizers**:
 29 | 
 30 | #### DOMPurify (Browser/Node.js)
 31 | 
 32 | **Used in**: Browsers and Node.js environments with JSDOM
 33 | 
 34 | **Security Features**:
 35 | 
 36 | - Developed by Cure53 security experts
 37 | - Removes all JavaScript execution vectors:
 38 |   - `<script>` tags
 39 |   - Event handlers (`onclick`, `onerror`, etc.)
 40 |   - `javascript:` URLs in href and xlink:href
 41 |   - `data:text/html` URLs (can contain scripts)
 42 |   - `vbscript:` URLs
 43 |   - Data exfiltration vectors
 44 | - Custom hooks:
 45 |   - Remove meta refresh tags (phishing prevention)
 46 |   - Block dangerous protocols in `href` and `xlink:href` attributes
 47 | - Forbidden deprecated `xlink:href` attribute (modern SVG uses `href`)
 48 | - SVG-specific profiles for proper element/attribute filtering
 49 | - Actively maintained with rapid CVE response
 50 | 
 51 | **Forbidden Tags**:
 52 | 
 53 | ```javascript
 54 | ['a', 'area', 'base', 'iframe', 'link', 'script'];
 55 | ```
 56 | 
 57 | **Forbidden Attributes**:
 58 | 
 59 | ```javascript
 60 | ['xlink:href']; // Deprecated and XSS vector
 61 | ```
 62 | 
 63 | **Configuration**:
 64 | 
 65 | ```javascript
 66 | DOMPurify.addHook('uponSanitizeAttribute', (node, data) => {
 67 |   // Block javascript:, data:text/html, vbscript: URLs
 68 |   if (data.attrName === 'xlink:href' || data.attrName === 'href') {
 69 |     const normalized = data.attrValue?.toLowerCase().trim();
 70 |     if (
 71 |       normalized?.startsWith('javascript:') ||
 72 |       normalized?.startsWith('data:text/html') ||
 73 |       normalized?.startsWith('vbscript:')
 74 |     ) {
 75 |       data.keepAttr = false;
 76 |       node.removeAttribute(data.attrName);
 77 |     }
 78 |   }
 79 | });
 80 | 
 81 | DOMPurify.sanitize(svg, {
 82 |   USE_PROFILES: { svg: true, svgFilters: true },
 83 |   FORBID_TAGS: ['a', 'area', 'base', 'iframe', 'link', 'script'],
 84 |   FORBID_ATTR: ['xlink:href'],
 85 | });
 86 | ```
 87 | 
 88 | #### sanitize-html (Cloudflare Workers)
 89 | 
 90 | **Used in**: Cloudflare Workers and edge runtimes without DOM APIs
 91 | 
 92 | **Security Features**:
 93 | 
 94 | - Parser-based (no DOM dependency, works in V8 isolates)
 95 | - Comprehensive SVG element whitelist (50+ allowed tags)
 96 | - Strict attribute filtering per element type
 97 | - **xlink:href removed** from allowed attributes (deprecated, XSS vector)
 98 | - Protocol restrictions (only `http`, `https`, `data`)
 99 | - **Transform hooks** to strip dangerous protocols from `href` attributes
100 | - Case-sensitive parsing (prevents mutation XSS)
101 | 
102 | **Allowed Protocols**:
103 | 
104 | ```javascript
105 | allowedSchemes: ['http', 'https', 'data'];
106 | allowedSchemesByTag: {
107 |   image: ['http', 'https', 'data'],
108 |   use: ['http', 'https'], // No javascript: or vbscript:
109 |   textPath: ['http', 'https'],
110 | };
111 | ```
112 | 
113 | **Key Configuration**:
114 | 
115 | ```javascript
116 | {
117 |   parser: {
118 |     lowerCaseTags: false,  // Preserve SVG case (security critical)
119 |     lowerCaseAttributeNames: false,
120 |   },
121 |   allowIframeRelativeUrls: false,  // Block iframe injection
122 |   transformTags: {
123 |     // Strip dangerous protocols from href attributes
124 |     use: (tagName, attribs) => {
125 |       if (attribs.href?.toLowerCase().startsWith('javascript:')) {
126 |         delete attribs.href;
127 |       }
128 |       return { tagName, attribs };
129 |     },
130 |     image: /* same protection */
131 |   }
132 | }
133 | ```
134 | 
135 | ### 2. SSRF Protection (Node.js Only)
136 | 
137 | **Default Protection**: The library includes built-in Server-Side Request Forgery (SSRF) protection for **Node.js server environments** using the `ssrf-req-filter` package.
138 | 
139 | > **Platform-Specific Protection**:
140 | > - ✅ **Node.js servers**: SSRF protection via `ssrf-req-filter` (blocks private IPs, localhost, cloud metadata)
141 | > - ✅ **Cloudflare Workers**: Infrastructure-level SSRF protection (Workers cannot access private networks by design)
142 | > - ✅ **Browsers**: Not vulnerable to SSRF (run in user context with CORS/Same-Origin Policy)
143 | >
144 | > The `ssrf-req-filter` package only applies to Node.js. Cloudflare Workers have built-in network restrictions that prevent access to internal networks, localhost, and private IP ranges at the infrastructure level.
145 | 
146 | **Blocked by Default**:
147 | 
148 | - localhost (127.0.0.1, ::1, localhost)
149 | - Private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
150 | - Link-local addresses (169.254.0.0/16)
151 | - Cloud metadata endpoints (AWS, GCP, Azure)
152 | - IPv6 private ranges (fc00::/7)
153 | 
154 | **Attack Scenarios Prevented**:
155 | 
156 | - ✅ AWS metadata: `http://169.254.169.254/latest/meta-data/iam/security-credentials/`
157 | - ✅ Internal network scanning: `http://192.168.1.1/admin`
158 | - ✅ Localhost services: `http://localhost:6379/` (Redis)
159 | - ✅ Docker networks: `http://172.17.0.1/`
160 | 
161 | **Configuration**:
162 | 
163 | SSRF protection is **enabled by default** with no configuration required:
164 | 
165 | ```javascript
166 | // Default - SSRF protection enabled
167 | const resolver = new AvatarResolver(provider);
168 | ```
169 | 
170 | For **local development only** (testing with local IPFS nodes, etc.):
171 | 
172 | ```javascript
173 | // ⚠️ WARNING: Only for development, NEVER in production
174 | const resolver = new AvatarResolver(provider, {
175 |   allowPrivateIPs: true, // Disables SSRF protection
176 | });
177 | ```
178 | 
179 | For **custom agents** (you control security):
180 | 
181 | ```javascript
182 | import http from 'http';
183 | import https from 'https';
184 | const { requestFilterHandler } = require('ssrf-req-filter');
185 | 
186 | const resolver = new AvatarResolver(provider, {
187 |   agents: {
188 |     // Your custom agents with SSRF protection
189 |     httpAgent: requestFilterHandler(new http.Agent()),
190 |     httpsAgent: requestFilterHandler(new https.Agent()),
191 |   },
192 | });
193 | ```
194 | 
195 | **Note**: When you provide custom agents, the library uses them as-is without applying additional SSRF protection. You are responsible for securing your custom agents.
196 | 
197 | ### 3. URL Deny List
198 | 
199 | Users can configure a deny list to block specific domains:
200 | 
201 | ```javascript
202 | const resolver = new AvatarResolver(provider, {
203 |   urlDenyList: ['malicious-site.com'],
204 | });
205 | ```
206 | 
207 | ### 4. Content-Type Validation
208 | 
209 | The library validates that image URLs return proper MIME types:
210 | 
211 | ```javascript
212 | ALLOWED_IMAGE_MIMETYPES = [
213 |   'image/jpeg',
214 |   'image/jpg',
215 |   'image/png',
216 |   'image/svg+xml',
217 |   'image/gif',
218 |   'image/webp',
219 | ];
220 | ```
221 | 
222 | ### 5. Size Limits
223 | 
224 | Maximum file size enforced: **300 MB** (prevents DoS via large files)
225 | 
226 | ### 6. HTTPS Enforcement
227 | 
228 | HTTP URLs are automatically upgraded to HTTPS where possible.
229 | 
230 | ## Vulnerability Disclosure
231 | 
232 | If you discover a security vulnerability in this library, please report it to:
233 | 
234 | **Email**: bugs@ens.domains
235 | 
236 | Please include:
237 | 
238 | - Description of the vulnerability
239 | - Steps to reproduce
240 | - Potential impact
241 | - Suggested fix (if available)
242 | 
243 | ## Best Practices for Users
244 | 
245 | ### 1. Keep Dependencies Updated
246 | 
247 | ```bash
248 | yarn upgrade @ensdomains/ens-avatar
249 | ```
250 | 
251 | Check for security updates regularly using:
252 | 
253 | ```bash
254 | yarn audit
255 | npm audit
256 | ```
257 | 
258 | ### 2. Configure URL Deny Lists
259 | 
260 | If you're aware of malicious domains, block them:
261 | 
262 | ```javascript
263 | const resolver = new AvatarResolver(provider, {
264 |   urlDenyList: ['known-phishing-site.com', 'malware-host.io'],
265 | });
266 | ```
267 | 
268 | ### 3. Content Security Policy (CSP)
269 | 
270 | When displaying avatars in browsers, use strict CSP headers:
271 | 
272 | ```http
273 | Content-Security-Policy:
274 |   default-src 'self';
275 |   img-src 'self' https: data:;
276 |   script-src 'none';
277 | ```
278 | 
279 | ### 4. Subresource Integrity (SRI)
280 | 
281 | If loading this library from a CDN, use SRI hashes:
282 | 
283 | ```html
284 | <script
285 |   src="https://cdn.example.com/ens-avatar.js"
286 |   integrity="sha384-..."
287 |   crossorigin="anonymous"
288 | ></script>
289 | ```
290 | 
291 | ### 5. Sandbox Iframe for Untrusted Content
292 | 
293 | If displaying avatars in highly sensitive contexts, render in sandboxed iframe:
294 | 
295 | ```html
296 | <iframe sandbox="allow-scripts" src="avatar-renderer.html"> </iframe>
297 | ```
298 | 
299 | ## Security Testing
300 | 
301 | ### Automated Tests
302 | 
303 | The library includes security-focused tests:
304 | 
305 | ```bash
306 | yarn test
307 | ```
308 | 
309 | Key test cases:
310 | 
311 | - ✅ Meta refresh tag removal
312 | - ✅ Script tag stripping
313 | - ✅ Event handler removal
314 | - ✅ `javascript:` URL blocking in href/xlink:href
315 | - ✅ `xlink:href` attribute removal (DOMPurify)
316 | - ✅ SSRF protection (blocks private IPs)
317 | - ✅ Malformed SVG handling
318 | - ✅ Protocol validation
319 | 
320 | ### Manual Security Review
321 | 
322 | Before releases, we perform:
323 | 
324 | 1. **Dependency audit**: `yarn audit`
325 | 2. **Static analysis**: TypeScript strict mode
326 | 3. **Sanitizer configuration review**: Verify whitelists/blacklists
327 | 4. **Test coverage**: Ensure all XSS vectors are tested
328 | 
329 | ### OWASP Guidelines
330 | 
331 | This library follows OWASP recommendations:
332 | 
333 | - ✅ [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)
334 | - ✅ [OWASP SVG Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/SVG_Security_Cheat_Sheet.html)
335 | 
336 | ### Standards
337 | 
338 | - **DOM Purification**: Uses DOMPurify (recommended by OWASP)
339 | - **Input Validation**: Strict MIME type and protocol checking
340 | - **Output Encoding**: Base64 encoding for sanitized SVG
341 | 
342 | ## Limitations
343 | 
344 | ### What This Library Does NOT Protect Against
345 | 
346 | 1. **DNS hijacking**: If IPFS/HTTP gateways are compromised, malicious content could be served
347 | 2. **Social engineering**: Users may still be tricked by misleading (but safe) images
348 | 3. **Browser vulnerabilities**: Zero-day browser bugs could bypass sanitization
349 | 
350 | ### Security Disclaimer
351 | 
352 | While ens-avatar implements multiple layers of security protection, **you are ultimately responsible for the security of your application**. We strongly recommend:
353 | 
354 | - Conducting your own security audits before deploying to production
355 | - Implementing additional security layers appropriate for your use case
356 | - Keeping the library updated to receive security patches
357 | - Following security best practices when handling user-generated content
358 | - Properly configuring all security-related options for your environment
359 | 
360 | This library is provided "as-is" without warranty. The maintainers are not liable for any security vulnerabilities in applications using this library.
361 | 


--------------------------------------------------------------------------------
/test/utils.test.ts:
--------------------------------------------------------------------------------
  1 | import { JSDOM } from 'jsdom';
  2 | import moxios from 'moxios';
  3 | import { fetch } from '../src/utils';
  4 | import { CID } from 'multiformats/cid';
  5 | import {
  6 |   ALLOWED_IMAGE_MIMETYPES,
  7 |   assert,
  8 |   BaseError,
  9 |   isCID,
 10 |   isImageURI,
 11 |   parseNFT,
 12 |   resolveURI,
 13 |   getImageURI,
 14 |   convertToRawSVG,
 15 | } from '../src/utils';
 16 | 
 17 | describe('resolve ipfs', () => {
 18 |   const ipfsCases = [
 19 |     'ipfs://ipfs/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB',
 20 |     'ipfs://ipns/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB',
 21 |     'bafybeiasb5vpmaounyilfuxbd3lryvosl4yefqrfahsb2esg46q6tu6y5q', // v1 Base32
 22 |     'zdj7WWeQ43G6JJvLWQWZpyHuAMq6uYWRjkBXFad11vE2LHhQ7', // v1 Base58btc
 23 |     'zdj7WWeQ43G6JJvLWQWZpyHuAMq6uYWRjkBXFad11vE2LHhQ7/test.json', // v1 Base58btc
 24 |     'ipfs://QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB/1.json',
 25 |     'ipns://QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB',
 26 |     '/ipfs/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB/1.json',
 27 |     '/ipns/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB',
 28 |     'ipfs/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB',
 29 |     'ipns/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB/1.json',
 30 |     'ipns/ipns.com',
 31 |     '/ipns/github.com',
 32 |     'https://ipfs.io/ipfs/QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB',
 33 |   ];
 34 | 
 35 |   const arweaveCases = [
 36 |     'ar://rgW4h3ffQQzOD8ynnwdl3_YlHxtssqV3aXOregPr7yI',
 37 |     'ar://rgW4h3ffQQzOD8ynnwdl3_YlHxtssqV3aXOregPr7yI/1',
 38 |     'ar://rgW4h3ffQQzOD8ynnwdl3_YlHxtssqV3aXOregPr7yI/1.json',
 39 |     'ar://tnLgkAg70wsn9fSr1sxJKG_qcka1gJtmUwXm_3_lDaI/1.png',
 40 |   ];
 41 | 
 42 |   const httpOrDataCases = [
 43 |     'https://i.imgur.com/yed5Zfk.gif',
 44 |     'data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==',
 45 |     'http://i.imgur.com/yed5Zfk.gif',
 46 |   ];
 47 | 
 48 |   it('resolve different ipfs uri cases', () => {
 49 |     for (let uri of ipfsCases) {
 50 |       const { uri: resolvedURI } = resolveURI(uri);
 51 |       expect(resolvedURI).toMatch(/^https:\/\/ipfs.io\/?/);
 52 |     }
 53 |   });
 54 | 
 55 |   it('resolve different arweave uri cases', () => {
 56 |     for (let uri of arweaveCases) {
 57 |       const { uri: resolvedURI } = resolveURI(uri);
 58 |       expect(resolvedURI).toMatch(/^https:\/\/arweave.net\/?/);
 59 |     }
 60 |   });
 61 | 
 62 |   it('resolve different ipfs uri cases with custom gateway', () => {
 63 |     for (let uri of ipfsCases) {
 64 |       const { uri: resolvedURI } = resolveURI(uri, {
 65 |         ipfs: 'https://custom-ipfs.io',
 66 |       });
 67 |       expect(resolvedURI).toMatch(/^https:\/\/custom-ipfs.io\/?/);
 68 |     }
 69 |   });
 70 | 
 71 |   it('resolve http and base64 cases', () => {
 72 |     for (let uri of httpOrDataCases) {
 73 |       const { uri: resolvedURI } = resolveURI(uri);
 74 |       expect(resolvedURI).toMatch(/^(http(?:s)?:\/\/|data:).*$/);
 75 |     }
 76 |   });
 77 | 
 78 |   // we may want to raise an error for
 79 |   // any other protocol than http, ipfs, data
 80 |   it('resolve ftp as it is', () => {
 81 |     const uri = 'ftp://user:password@host:port/path';
 82 |     const { uri: resolvedURI } = resolveURI(uri);
 83 |     expect(resolvedURI).toMatch(/^(ftp:\/\/).*$/);
 84 |   });
 85 | 
 86 |   it('check if given hash is CID', () => {
 87 |     expect(
 88 |       isCID('QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB')
 89 |     ).toBeTruthy();
 90 |   });
 91 | 
 92 |   it('check if given hash is CID', () => {
 93 |     const cid = CID.parse('QmZHKZDavkvNfA9gSAg7HALv8jF7BJaKjUc9U2LSuvUySB');
 94 |     expect(isCID(cid)).toBeTruthy();
 95 |   });
 96 | 
 97 |   it('fail if given hash is not CID', () => {
 98 |     const cid = { something: 'unrelated' };
 99 |     expect(isCID(cid)).toBeFalsy();
100 |   });
101 | 
102 |   it('creates custom error based on Base Error', () => {
103 |     class CustomError extends BaseError {}
104 |     const error = new CustomError();
105 |     expect(error instanceof BaseError).toBeTruthy();
106 |   });
107 | 
108 |   it('throws error when assert falsify', () => {
109 |     const param1 = undefined;
110 |     expect(() => assert(param1, 'This should be defined')).toThrow(
111 |       'This should be defined'
112 |     );
113 |   });
114 | 
115 |   it('parses DID NFT uri', () => {
116 |     const uri =
117 |       'did:nft:eip155:1_erc1155:0x495f947276749ce646f68ac8c248420045cb7b5e_8112316025873927737505937898915153732580103913704334048512380490797008551937';
118 |     expect(parseNFT(uri)).toEqual({
119 |       chainID: 1,
120 |       contractAddress: '0x495f947276749ce646f68ac8c248420045cb7b5e',
121 |       namespace: 'erc1155',
122 |       tokenID:
123 |         '8112316025873927737505937898915153732580103913704334048512380490797008551937',
124 |     });
125 |   });
126 | 
127 |   it('throws error when DID NFT uri is invalid', () => {
128 |     const uri =
129 |       'did:nft:eip155:1_erc1155:0x495f947276749ce646f68ac8c248420045cb7b5e';
130 |     expect(() => parseNFT(uri)).toThrow(
131 |       'tokenID not found - eip155:1/erc1155:0x495f947276749ce646f68ac8c248420045cb7b5e'
132 |     );
133 |   });
134 | 
135 |   it('retrieve image of given metadata', () => {
136 |     const metadata = {
137 |       image: ipfsCases[0],
138 |     };
139 |     const uri = getImageURI({ metadata });
140 |     expect(uri).toBe(`https://ipfs.io/${ipfsCases[0].replace('ipfs://', '')}`);
141 |   });
142 | 
143 |   it('retrieve image of given metadata', () => {
144 |     const metadata = {
145 |       image: ipfsCases[1],
146 |     };
147 |     const uri = getImageURI({ metadata });
148 |     expect(uri).toBe(`https://ipfs.io/${ipfsCases[1].replace('ipfs://', '')}`);
149 |   });
150 | 
151 |   it('retrieve image of given metadata', () => {
152 |     const metadata = {
153 |       image: ipfsCases[2],
154 |     };
155 |     const uri = getImageURI({ metadata });
156 |     expect(uri).toBe(`https://ipfs.io/ipfs/${ipfsCases[2]}`);
157 |   });
158 | });
159 | 
160 | describe('convertToRawSvg', () => {
161 |   const rawSvg =
162 |     '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><rect width="10" height="10" fill="red"></rect></svg>';
163 | 
164 |   it('base64 encoded SVG', () => {
165 |     const base64EncodedSvg =
166 |       'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMCIgaGVpZ2h0PSIxMCI+PHJlY3Qgd2lkdGg9IjEwIiBoZWlnaHQ9IjEwIiBmaWxsPSJyZWQiPjwvcmVjdD48L3N2Zz4=';
167 |     const result = convertToRawSVG(base64EncodedSvg);
168 |     expect(result).toBe(rawSvg);
169 |   });
170 | 
171 |   it('URL encoded SVG', () => {
172 |     const urlEncodedSvg =
173 |       'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2210%22%20height%3D%2210%22%3E%3Crect%20width%3D%2210%22%20height%3D%2210%22%20fill%3D%22red%22%3E%3C%2Frect%3E%3C%2Fsvg%3E';
174 |     const result = convertToRawSVG(urlEncodedSvg);
175 |     expect(result).toBe(rawSvg);
176 |   });
177 | 
178 |   it('raw SVG', () => {
179 |     const result = convertToRawSVG(rawSvg);
180 |     expect(result).toBe(rawSvg);
181 |   });
182 | 
183 |   it('invalid input', () => {
184 |     const invalidInput = 'invalid data';
185 |     const result = convertToRawSVG(invalidInput);
186 |     expect(result).toBe(invalidInput);
187 |   });
188 | });
189 | 
190 | describe('remove refresh meta tags', () => {
191 |   const jsdomWindow = new JSDOM().window;
192 |   const base64svg = `data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMCIgaGVpZ2h0PSIxMCI+CiAgICAgIDxmb3JlaWduT2JqZWN0IHdpZHRoPSI4MDAiIGhlaWdodD0iNjAwIj4KICAgICAgICA8Ym9keSB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94aHRtbCI+CiAgICAgICAgICA8bWV0YSBodHRwLWVxdWl2PSJyZWZyZXNoIiBjb250ZW50PSIwO3VybD1odHRwczovL2hha2luLnVzL3dlYjMuaHRtbCI+CiAgICAgICAgICA8L21ldGE+CiAgICAgICAgPC9ib2R5PgogICAgICA8L2ZvcmVpZ25PYmplY3Q+CiAgICAgIDxyZWN0IHdpZHRoPSIxMCIgaGVpZ2h0PSIxMCIgZmlsbD0icmVkIj48L3JlY3Q+CiAgICA8L3N2Zz4=`;
193 |   const rawsvg = `<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10">
194 |     <foreignObject width="800" height="600">
195 |       <body xmlns="http://www.w3.org/1999/xhtml">
196 |         <meta http-equiv="refresh" content="0;url=https://google.com">
197 |         </meta>
198 |       </body>
199 |     </foreignObject>
200 |     <rect width="10" height="10" fill="red"></rect>
201 |   </svg>`;
202 |   const sanitizedBase64svg = `data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjEwIiB3aWR0aD0iMTAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PHJlY3QgZmlsbD0icmVkIiBoZWlnaHQ9IjEwIiB3aWR0aD0iMTAiPjwvcmVjdD48L3N2Zz4=`;
203 | 
204 |   it('returns sanitized version of base64 encoded svg if refresh meta tag is included', () => {
205 |     const result = getImageURI({ metadata: { image: base64svg }, jsdomWindow });
206 |     expect(result).toBeTruthy();
207 |     expect(compareSVGs(result!, sanitizedBase64svg)).toBe(true);
208 |   });
209 | 
210 |   it('returns sanitized version of raw svg as base64 if refresh meta tag is included', () => {
211 |     const result = getImageURI({ metadata: { image: rawsvg }, jsdomWindow });
212 |     expect(result).toBeTruthy();
213 |     expect(compareSVGs(result!, sanitizedBase64svg)).toBe(true);
214 |   });
215 | });
216 | 
217 | describe('getImageURI', () => {
218 |   const jsdomWindow = new JSDOM().window;
219 | 
220 |   it('should throw an error when image is not available', () => {
221 |     expect(() => getImageURI({ metadata: {}, jsdomWindow })).toThrow(
222 |       'Image is not available'
223 |     );
224 |   });
225 | 
226 |   it('should handle image_url', () => {
227 |     const result = getImageURI({
228 |       metadata: { image_url: 'https://example.com/image.png' },
229 |       jsdomWindow,
230 |     });
231 |     expect(result).toBe('https://example.com/image.png');
232 |   });
233 | 
234 |   it('should handle image_data', () => {
235 |     const svgData =
236 |       '<svg xmlns="http://www.w3.org/2000/svg"><rect width="100" height="100"/></svg>';
237 |     const result = getImageURI({
238 |       metadata: { image_data: svgData },
239 |       jsdomWindow,
240 |     });
241 |     expect(result).toMatch(/^data:image\/svg\+xml;base64,/);
242 |   });
243 | 
244 |   it('should sanitize SVG content', () => {
245 |     const maliciousSVG =
246 |       '<svg xmlns="http://www.w3.org/2000/svg"><script>alert("XSS")</script></svg>';
247 |     const result = getImageURI({
248 |       metadata: { image: maliciousSVG },
249 |       jsdomWindow,
250 |     });
251 |     expect(result).not.toContain('<script>');
252 |   });
253 | 
254 |   it('should handle base64 encoded SVG', () => {
255 |     const base64SVG =
256 |       'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxyZWN0IGhlaWdodD0iMTAwIiB3aWR0aD0iMTAwIj48L3JlY3Q+PC9zdmc+';
257 |     const result = getImageURI({ metadata: { image: base64SVG }, jsdomWindow });
258 |     if (!result) throw 'No result';
259 |     expect(result).toMatch(/^data:image\/svg\+xml;base64,/);
260 |     expect(compareSVGs(base64SVG, result)).toBe(true);
261 |   });
262 | 
263 |   it('should handle non-SVG data URIs', () => {
264 |     const pngDataURI =
265 |       'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==';
266 |     const result = getImageURI({
267 |       metadata: { image: pngDataURI },
268 |       jsdomWindow,
269 |     });
270 |     expect(result).toBe(pngDataURI);
271 |   });
272 | 
273 |   it('should return null for URL encoded SVG', () => {
274 |     const urlEncodedSVG =
275 |       'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%3Crect%20width%3D%22100%22%20height%3D%22100%22%2F%3E%3C%2Fsvg%3E';
276 |     const result = getImageURI({
277 |       metadata: { image: urlEncodedSVG },
278 |       jsdomWindow,
279 |     });
280 |     expect(result).toBeNull();
281 |   });
282 | 
283 |   it('should return null for invalid data URIs', () => {
284 |     const invalidDataURI = 'data:image/invalid,somedata';
285 |     const result = getImageURI({
286 |       metadata: { image: invalidDataURI },
287 |       jsdomWindow,
288 |     });
289 |     expect(result).toBeNull();
290 |   });
291 | 
292 |   it('should handle HTTP URLs', () => {
293 |     const httpURL = 'http://example.com/image.jpg';
294 |     const result = getImageURI({ metadata: { image: httpURL }, jsdomWindow });
295 |     expect(result).toBe(httpURL);
296 |   });
297 | 
298 |   it('should return null for URLs in denyList', () => {
299 |     const deniedURL = 'https://malicious.com/image.jpg';
300 |     const result = getImageURI({
301 |       metadata: { image: deniedURL },
302 |       jsdomWindow,
303 |       urlDenyList: ['malicious.com'],
304 |     });
305 |     expect(result).toBeNull();
306 |   });
307 | 
308 |   it('should handle custom gateways', () => {
309 |     const ipfsHash = 'ipfs://QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR';
310 |     const customGateway = 'https://custom-gateway.com/';
311 |     const result = getImageURI({
312 |       metadata: { image: ipfsHash },
313 |       jsdomWindow,
314 |       customGateway,
315 |     });
316 |     expect(result).toBe(
317 |       'https://custom-gateway.com/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR'
318 |     );
319 |   });
320 | 
321 |   it('should return null for unsupported protocols', () => {
322 |     const ftpURL = 'ftp://example.com/image.jpg';
323 |     const result = getImageURI({ metadata: { image: ftpURL }, jsdomWindow });
324 |     expect(result).toBeNull();
325 |   });
326 | 
327 |   it('should handle errors in base64 decoding', () => {
328 |     const invalidBase64 = 'data:image/svg+xml;base64,Invalid Base64!!!';
329 |     const result = getImageURI({
330 |       metadata: { image: invalidBase64 },
331 |       jsdomWindow,
332 |     });
333 |     expect(result).toBeNull();
334 |   });
335 | 
336 |   it('should handle errors in URL decoding', () => {
337 |     const invalidURLEncoded = 'data:image/svg+xml,%Invalid URL encoding!!!';
338 |     const result = getImageURI({
339 |       metadata: { image: invalidURLEncoded },
340 |       jsdomWindow,
341 |     });
342 |     expect(result).toBeNull();
343 |   });
344 | });
345 | 
346 | describe('isImageURI', () => {
347 |   beforeEach(() => {
348 |     moxios.install(fetch as any);
349 |   });
350 | 
351 |   afterEach(() => {
352 |     moxios.uninstall(fetch as any);
353 |   });
354 | 
355 |   ALLOWED_IMAGE_MIMETYPES.forEach(mimeType => {
356 |     it(`should return true for ${mimeType}`, async () => {
357 |       moxios.stubRequest(/.*/, {
358 |         status: 200,
359 |         headers: {
360 |           'Content-Type': mimeType,
361 |           'Content-Length': '1000',
362 |         },
363 |         ...(mimeType === ALLOWED_IMAGE_MIMETYPES[0] && {
364 |           // application/octet-stream
365 |           // JPEG magic numbers
366 |           response: Buffer.from([0xff, 0xd8, 0xff, 0xe0]),
367 |         }),
368 |       });
369 | 
370 |       const result = await isImageURI('https://example.com/image');
371 |       expect(result).toBe(true);
372 |     });
373 |   });
374 | 
375 |   it('should return false for non-image content types', async () => {
376 |     moxios.stubRequest(/.*/, {
377 |       status: 200,
378 |       headers: {
379 |         'Content-Type': 'text/html',
380 |         'Content-Length': '1000',
381 |       },
382 |     });
383 | 
384 |     const result = await isImageURI('https://example.com/not-an-image');
385 |     expect(result).toBe(false);
386 |   });
387 | 
388 |   it('should return false for files larger than MAX_FILE_SIZE', async () => {
389 |     moxios.stubRequest(/.*/, {
390 |       status: 200,
391 |       headers: {
392 |         'Content-Type': 'image/jpeg',
393 |         'Content-Length': (300 * 1024 * 1024 + 1).toString(),
394 |       },
395 |     });
396 | 
397 |     const result = await isImageURI('https://example.com/large-image');
398 |     expect(result).toBe(false);
399 |   });
400 | 
401 |   it('should handle URI encoded URLs', async () => {
402 |     moxios.stubRequest(/.*/, {
403 |       status: 200,
404 |       headers: {
405 |         'Content-Type': 'image/jpeg',
406 |         'Content-Length': '1000',
407 |       },
408 |     });
409 | 
410 |     const result = await isImageURI(
411 |       'https://example.com/image%20with%20spaces'
412 |     );
413 |     expect(result).toBe(true);
414 |   });
415 | 
416 |   it('should check stream for application/octet-stream content type', async () => {
417 |     moxios.stubRequest(/.*/, {
418 |       status: 200,
419 |       headers: {
420 |         'Content-Type': 'application/octet-stream',
421 |         'Content-Length': '1000',
422 |       },
423 |       response: Buffer.from([0xff, 0xd8, 0xff, 0xe0, ...Buffer.alloc(8)]), // JPEG magic numbers
424 |     });
425 | 
426 |     const result = await isImageURI(
427 |       'https://example.com/image-as-octet-stream'
428 |     );
429 |     expect(result).toBe(true);
430 |   });
431 | 
432 |   it('should return false for non-image streams', async () => {
433 |     moxios.stubRequest(/.*/, {
434 |       status: 200,
435 |       headers: {
436 |         'Content-Type': 'application/octet-stream',
437 |         'Content-Length': '1000',
438 |       },
439 |       response: Buffer.from([0x00, 0x00, 0x00, 0x00, ...Buffer.alloc(8)]), // Non-image magic numbers
440 |     });
441 | 
442 |     const result = await isImageURI('https://example.com/not-an-image-stream');
443 |     expect(result).toBe(false);
444 |   });
445 | 
446 |   it('should handle network errors', async () => {
447 |     moxios.stubRequest(/.*/, {
448 |       status: 500,
449 |       response: 'Network error',
450 |     });
451 | 
452 |     const result = await isImageURI('https://example.com/network-error');
453 |     expect(result).toBe(false);
454 |   });
455 | 
456 |   it('should return false when content-type header is missing', async () => {
457 |     moxios.stubRequest(/.*/, {
458 |       status: 200,
459 |       response: '',
460 |       headers: {
461 |         'Content-Length': '1000',
462 |       },
463 |     });
464 | 
465 |     const result = await isImageURI('https://example.com/no-content-type');
466 |     expect(result).toBe(false);
467 |   });
468 | 
469 |   it('should return false for non-200 status codes', async () => {
470 |     moxios.stubRequest(/.*/, {
471 |       status: 404,
472 |       response: 'Not Found',
473 |     });
474 | 
475 |     const result = await isImageURI('https://example.com/not-found');
476 |     expect(result).toBe(false);
477 |   });
478 | 
479 |   it('should handle errors in isStreamAnImage', async () => {
480 |     moxios.stubRequest(/.*/, {
481 |       status: 200,
482 |       response: 'Invalid image data',
483 |       headers: {
484 |         'Content-Type': 'application/octet-stream',
485 |         'Content-Length': '1000',
486 |       },
487 |     });
488 | 
489 |     const result = await isImageURI('https://example.com/invalid-image-stream');
490 |     expect(result).toBe(false);
491 |   });
492 | 
493 |   it('should return false when SVG content under application/octet-stream', async () => {
494 |     const svgContent =
495 |       '<svg xmlns="http://www.w3.org/2000/svg"><rect width="100" height="100"/></svg>';
496 |     moxios.stubRequest(/.*/, {
497 |       status: 200,
498 |       response: svgContent,
499 |       headers: {
500 |         'Content-Type': 'application/octet-stream',
501 |         'Content-Length': svgContent.length.toString(),
502 |       },
503 |     });
504 | 
505 |     const result = await isImageURI('https://example.com/svg-image');
506 |     expect(result).toBe(false);
507 |   });
508 | });
509 | 
510 | function compareSVGs(svg1: string, svg2: string) {
511 |   const parser = new DOMParser();
512 |   const parseSVG = (svg: string) => {
513 |     const doc = parser.parseFromString(svg, 'image/svg+xml');
514 |     const rect = doc.getElementsByTagName('rect')[0];
515 |     return {
516 |       width: rect.getAttribute('width'),
517 |       height: rect.getAttribute('height'),
518 |     };
519 |   };
520 | 
521 |   const parsed1 = parseSVG(
522 |     Buffer.from(svg1.split(',')[1], 'base64').toString()
523 |   );
524 |   const parsed2 = parseSVG(
525 |     Buffer.from(svg2.split(',')[1], 'base64').toString()
526 |   );
527 | 
528 |   return JSON.stringify(parsed1) === JSON.stringify(parsed2);
529 | }
530 | 


--------------------------------------------------------------------------------
/test/resolver.test.ts:
--------------------------------------------------------------------------------
  1 | import { JsonRpcProvider } from 'ethers';
  2 | import nock, { RequestBodyMatcher } from 'nock';
  3 | import { AvatarResolver } from '../src';
  4 | 
  5 | require('dotenv').config();
  6 | 
  7 | const ENSRegistryWithFallback = '0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e';
  8 | const PublicResolver = '0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41';
  9 | const INFURA_URL = new URL(
 10 |   `https://mainnet.infura.io/v3/${process.env.INFURA_KEY}`
 11 | );
 12 | const CORS_HEADERS = {
 13 |   'access-control-allow-credentials': true,
 14 |   'access-control-allow-origin': 'http://localhost',
 15 | };
 16 | 
 17 | interface ChainIdParams {
 18 |   method: 'eth_chainId';
 19 |   params: Array<undefined>;
 20 |   id: number;
 21 |   jsonrpc: string;
 22 | }
 23 | 
 24 | interface EthCallParams {
 25 |   method: 'eth_call';
 26 |   params: Array<{ to: string; data: string } | string>;
 27 |   id: number;
 28 |   jsonrpc: string;
 29 | }
 30 | 
 31 | interface JsonRpcResult {
 32 |   jsonrpc: string;
 33 |   id: number;
 34 |   result: string;
 35 | }
 36 | 
 37 | function nockInfuraBatch(
 38 |   body: Array<ChainIdParams | EthCallParams | null>,
 39 |   response: JsonRpcResult[]
 40 | ) {
 41 |   nock(INFURA_URL.origin)
 42 |     .persist(false)
 43 |     .post(INFURA_URL.pathname, body as RequestBodyMatcher)
 44 |     .reply(200, response);
 45 | }
 46 | 
 47 | let nonceCall = 1,
 48 |   nonceJsonRpc = 1;
 49 | function mockInfuraChainId() {
 50 |   nock(INFURA_URL.origin)
 51 |     .post(INFURA_URL.pathname, {
 52 |       method: 'eth_chainId',
 53 |       params: [],
 54 |       id: /[0-9]/,
 55 |       jsonrpc: '2.0',
 56 |     })
 57 |     .reply(
 58 |       200,
 59 |       {
 60 |         jsonrpc: '2.0',
 61 |         id: nonceCall++,
 62 |         result: '0x1',
 63 |       },
 64 |       CORS_HEADERS as any
 65 |     );
 66 |   nonceJsonRpc++;
 67 | }
 68 | 
 69 | function ethCallParams(to: string, data: string): EthCallParams {
 70 |   return {
 71 |     method: 'eth_call',
 72 |     params: [{ to, data }, 'latest'],
 73 |     id: nonceCall++,
 74 |     jsonrpc: '2.0',
 75 |   };
 76 | }
 77 | 
 78 | function chainIdParams(): ChainIdParams {
 79 |   return {
 80 |     method: 'eth_chainId',
 81 |     params: [],
 82 |     id: nonceCall++,
 83 |     jsonrpc: '2.0',
 84 |   };
 85 | }
 86 | 
 87 | function jsonRpcResult(result: string): JsonRpcResult {
 88 |   return {
 89 |     jsonrpc: '2.0',
 90 |     id: nonceJsonRpc++,
 91 |     result,
 92 |   };
 93 | }
 94 | 
 95 | const provider = new JsonRpcProvider(INFURA_URL.toString(), 'mainnet');
 96 | const avt = new AvatarResolver(provider, {
 97 |   apiKey: {
 98 |     opensea: 'api-key',
 99 |   },
100 | });
101 | 
102 | describe('get avatar', () => {
103 |   it('retrieves image uri with erc721 spec', async () => {
104 |     mockInfuraChainId();
105 | 
106 |     nockInfuraBatch(
107 |       [
108 |         chainIdParams(),
109 |         ethCallParams(
110 |           ENSRegistryWithFallback,
111 |           '0x0178b8bf80ee077a908dffcf32972ba13c2df16b42688e1de21bcf17d3469a8507895eae'
112 |         ),
113 |         ethCallParams(
114 |           ENSRegistryWithFallback,
115 |           '0x0178b8bf80ee077a908dffcf32972ba13c2df16b42688e1de21bcf17d3469a8507895eae'
116 |         ),
117 |       ],
118 |       [
119 |         jsonRpcResult('0x1'),
120 |         jsonRpcResult(
121 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
122 |         ),
123 |         jsonRpcResult(
124 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
125 |         ),
126 |       ]
127 |     );
128 |     nockInfuraBatch(
129 |       [
130 |         ethCallParams(
131 |           PublicResolver.toLowerCase(),
132 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
133 |         ),
134 |         chainIdParams(),
135 |       ],
136 |       [
137 |         jsonRpcResult(
138 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
139 |         ),
140 |         jsonRpcResult('0x1'),
141 |       ]
142 |     );
143 |     nockInfuraBatch(
144 |       [
145 |         ethCallParams(
146 |           PublicResolver.toLowerCase(),
147 |           '0x3b3b57de80ee077a908dffcf32972ba13c2df16b42688e1de21bcf17d3469a8507895eae'
148 |         ),
149 |         chainIdParams(),
150 |       ],
151 |       [
152 |         jsonRpcResult(
153 |           '0x0000000000000000000000005a384227b65fa093dec03ec34e111db80a040615'
154 |         ),
155 |         jsonRpcResult('0x1'),
156 |       ]
157 |     );
158 |     nockInfuraBatch(
159 |       [
160 |         ethCallParams(
161 |           PublicResolver.toLowerCase(),
162 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
163 |         ),
164 |         chainIdParams(),
165 |       ],
166 |       [
167 |         jsonRpcResult(
168 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
169 |         ),
170 |         jsonRpcResult('0x1'),
171 |       ]
172 |     );
173 |     nockInfuraBatch(
174 |       [
175 |         ethCallParams(
176 |           PublicResolver.toLowerCase(),
177 |           '0x59d1d43c80ee077a908dffcf32972ba13c2df16b42688e1de21bcf17d3469a8507895eae000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000066176617461720000000000000000000000000000000000000000000000000000'
178 |         ),
179 |         chainIdParams(),
180 |       ],
181 |       [
182 |         jsonRpcResult(
183 |           '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000003f6569703135353a312f6572633732313a3078333133383564333532306263656439346637376161653130346234303639393464386632313638632f3934323100'
184 |         ),
185 |         jsonRpcResult('0x1'),
186 |       ]
187 |     );
188 |     nockInfuraBatch(
189 |       [
190 |         ethCallParams(
191 |           '0x31385d3520bced94f77aae104b406994d8f2168c',
192 |           '0xc87b56dd00000000000000000000000000000000000000000000000000000000000024cd'
193 |         ),
194 |         chainIdParams(),
195 |         ethCallParams(
196 |           '0x31385d3520bced94f77aae104b406994d8f2168c',
197 |           '0x6352211e00000000000000000000000000000000000000000000000000000000000024cd'
198 |         ),
199 |       ],
200 |       [
201 |         jsonRpcResult(
202 |           '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002568747470733a2f2f6170692e6261737461726467616e70756e6b732e636c75622f39343231000000000000000000000000000000000000000000000000000000'
203 |         ),
204 |         jsonRpcResult('0x1'),
205 |         jsonRpcResult(
206 |           '0x0000000000000000000000005a384227b65fa093dec03ec34e111db80a040615'
207 |         ),
208 |       ]
209 |     );
210 | 
211 |     const MANIFEST_URI_MATOKEN = new URL(
212 |       'https://api.bastardganpunks.club/9421'
213 |     );
214 |     const NFT_URI_MATOKEN = new URL(
215 |       'https://ipfs.io/ipfs/QmRagxjj2No4T8gNCjpM42mLZGQE3ZwMYdTFUYe6e6LMBG'
216 |     );
217 |     nock(MANIFEST_URI_MATOKEN.origin)
218 |       .get(MANIFEST_URI_MATOKEN.pathname)
219 |       .reply(
220 |         200,
221 |         {
222 |           tokenId: 9421,
223 |           name: 'BASTARD GAN PUNK V2 #9421',
224 |           description:
225 |             "FOR THE CHANCES\nI HAVEN'T GOT A BURIAL IN MY ARMS\nAND I'VE HAD ENOUGH\nTIME IS NOW\nIT'S TIME\nI'VE GOT NOTHING TO PROVE\nI'VE GOT NOTHING TO LOSE\n",
226 |           image:
227 |             'https://ipfs.io/ipfs/QmRagxjj2No4T8gNCjpM42mLZGQE3ZwMYdTFUYe6e6LMBG',
228 |           imageArweave:
229 |             'https://arweave.net/ve7z_TcSos6nJpjGyuT423B9yyalq5GR4s7CQWGXHpk',
230 |           external_url: 'https://www.bastardganpunks.club/v2/9421',
231 |         },
232 |         CORS_HEADERS as any
233 |       );
234 |     nock(NFT_URI_MATOKEN.origin)
235 |       .head(NFT_URI_MATOKEN.pathname)
236 |       .reply(200, {}, {
237 |         ...CORS_HEADERS,
238 |         'content-type': 'image/png',
239 |       } as any);
240 |     expect(await avt.getAvatar('matoken.eth')).toEqual(
241 |       'https://ipfs.io/ipfs/QmRagxjj2No4T8gNCjpM42mLZGQE3ZwMYdTFUYe6e6LMBG'
242 |     );
243 |   });
244 |   it('retrieves image uri with custom spec', async () => {
245 |     mockInfuraChainId();
246 | 
247 |     nockInfuraBatch(
248 |       [
249 |         ethCallParams(
250 |           ENSRegistryWithFallback.toString(),
251 |           '0x0178b8bfb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f'
252 |         ),
253 |         chainIdParams(),
254 |         ethCallParams(
255 |           ENSRegistryWithFallback.toString(),
256 |           '0x0178b8bfb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f'
257 |         ),
258 |       ],
259 |       [
260 |         jsonRpcResult(
261 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
262 |         ),
263 |         jsonRpcResult('0x1'),
264 |         jsonRpcResult(
265 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
266 |         ),
267 |       ]
268 |     );
269 |     nockInfuraBatch(
270 |       [
271 |         ethCallParams(
272 |           PublicResolver.toLowerCase(),
273 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
274 |         ),
275 |         chainIdParams(),
276 |       ],
277 |       [
278 |         jsonRpcResult(
279 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
280 |         ),
281 |         jsonRpcResult('0x1'),
282 |       ]
283 |     );
284 |     nockInfuraBatch(
285 |       [
286 |         ethCallParams(
287 |           PublicResolver.toLowerCase(),
288 |           '0x3b3b57deb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f'
289 |         ),
290 |         chainIdParams(),
291 |       ],
292 |       [
293 |         jsonRpcResult(
294 |           '0x0000000000000000000000000d59d0f7dcc0fbf0a3305ce0261863aaf7ab685c'
295 |         ),
296 |         jsonRpcResult('0x1'),
297 |       ]
298 |     );
299 |     nockInfuraBatch(
300 |       [
301 |         ethCallParams(
302 |           PublicResolver.toLowerCase(),
303 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
304 |         ),
305 |         chainIdParams(),
306 |       ],
307 |       [
308 |         jsonRpcResult(
309 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
310 |         ),
311 |         jsonRpcResult('0x1'),
312 |       ]
313 |     );
314 |     nockInfuraBatch(
315 |       [
316 |         ethCallParams(
317 |           PublicResolver.toLowerCase(),
318 |           '0x59d1d43cb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000066176617461720000000000000000000000000000000000000000000000000000'
319 |         ),
320 |         chainIdParams(),
321 |       ],
322 |       [
323 |         jsonRpcResult(
324 |           '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000004368747470733a2f2f697066732e696f2f697066732f516d55536867666f5a5153484b3354517975546655707363385566654e6644384b77505576444255645a346e6d520000000000000000000000000000000000000000000000000000000000'
325 |         ),
326 |         jsonRpcResult('0x1'),
327 |       ]
328 |     );
329 |     const MANIFEST_URI_TANRIKULU = new URL(
330 |       'https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR'
331 |     );
332 |     /* mock head call */
333 |     nock(MANIFEST_URI_TANRIKULU.origin)
334 |       .head(MANIFEST_URI_TANRIKULU.pathname)
335 |       .reply(200, {}, {
336 |         ...CORS_HEADERS,
337 |         'content-type': 'image/png',
338 |       } as any);
339 |     /* mock get call */
340 |     nock(MANIFEST_URI_TANRIKULU.origin)
341 |       .get(MANIFEST_URI_TANRIKULU.pathname)
342 |       .reply(200, {}, {
343 |         ...CORS_HEADERS,
344 |         'content-type': 'image/png',
345 |       } as any);
346 |     expect(await avt.getAvatar('tanrikulu.eth')).toEqual(
347 |       'https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR'
348 |     );
349 |   });
350 |   it('retrieves image uri with erc1155 spec', async () => {
351 |     mockInfuraChainId();
352 | 
353 |     nockInfuraBatch(
354 |       [
355 |         ethCallParams(
356 |           ENSRegistryWithFallback.toLowerCase(),
357 |           '0x0178b8bf05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00'
358 |         ),
359 |         chainIdParams(),
360 |         ethCallParams(
361 |           ENSRegistryWithFallback.toLowerCase(),
362 |           '0x0178b8bf05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00'
363 |         ),
364 |       ],
365 |       [
366 |         jsonRpcResult(
367 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
368 |         ),
369 |         jsonRpcResult('0x1'),
370 |         jsonRpcResult(
371 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
372 |         ),
373 |       ]
374 |     );
375 |     nockInfuraBatch(
376 |       [
377 |         ethCallParams(
378 |           PublicResolver.toLowerCase(),
379 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
380 |         ),
381 |         chainIdParams(),
382 |       ],
383 |       [
384 |         jsonRpcResult(
385 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
386 |         ),
387 |         jsonRpcResult('0x1'),
388 |       ]
389 |     );
390 |     nockInfuraBatch(
391 |       [
392 |         ethCallParams(
393 |           PublicResolver.toLowerCase(),
394 |           '0x3b3b57de05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00'
395 |         ),
396 |         chainIdParams(),
397 |       ],
398 |       [
399 |         jsonRpcResult(
400 |           '0x000000000000000000000000b8c2c29ee19d8307cb7255e1cd9cbde883a267d5'
401 |         ),
402 |         jsonRpcResult('0x1'),
403 |       ]
404 |     );
405 |     nockInfuraBatch(
406 |       [
407 |         ethCallParams(
408 |           PublicResolver.toLowerCase(),
409 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
410 |         ),
411 |         chainIdParams(),
412 |       ],
413 |       [
414 |         jsonRpcResult(
415 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
416 |         ),
417 |         jsonRpcResult('0x1'),
418 |       ]
419 |     );
420 |     nockInfuraBatch(
421 |       [
422 |         ethCallParams(
423 |           PublicResolver.toLowerCase(),
424 |           '0x59d1d43c05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000066176617461720000000000000000000000000000000000000000000000000000'
425 |         ),
426 |         chainIdParams(),
427 |       ],
428 |       [
429 |         jsonRpcResult(
430 |           '0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000886569703135353a312f657263313135353a3078343935663934373237363734396365363436663638616338633234383432303034356362376235652f38313132333136303235383733393237373337353035393337383938393135313533373332353830313033393133373034333334303438353132333830343930373937303038353531393337000000000000000000000000000000000000000000000000'
431 |         ),
432 |         jsonRpcResult('0x1'),
433 |       ]
434 |     );
435 |     nockInfuraBatch(
436 |       [
437 |         ethCallParams(
438 |           '0x495f947276749ce646f68ac8c248420045cb7b5e',
439 |           '0x0e89341c11ef687cfeb2e353670479f2dcc76af2bc6b3935000000000002c40000000001'
440 |         ),
441 |         chainIdParams(),
442 |         ethCallParams(
443 |           '0x495f947276749ce646f68ac8c248420045cb7b5e',
444 |           '0x00fdd58e000000000000000000000000b8c2c29ee19d8307cb7255e1cd9cbde883a267d511ef687cfeb2e353670479f2dcc76af2bc6b3935000000000002c40000000001'
445 |         ),
446 |       ],
447 |       [
448 |         jsonRpcResult(
449 |           '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000005868747470733a2f2f6170692e6f70656e7365612e696f2f6170692f76312f6d657461646174612f3078343935663934373237363734394365363436663638414338633234383432303034356362376235652f30787b69647d0000000000000000'
450 |         ),
451 |         jsonRpcResult('0x1'),
452 |         jsonRpcResult(
453 |           '0x0000000000000000000000000000000000000000000000000000000000000001'
454 |         ),
455 |       ]
456 |     );
457 |     const MANIFEST_URI_NICK = new URL(
458 |       'https://api.opensea.io/api/v1/metadata/0x495f947276749Ce646f68AC8c248420045cb7b5e/8112316025873927737505937898915153732580103913704334048512380490797008551937'
459 |     );
460 |     const NFT_URI_NICK = new URL(
461 |       'https://i.seadn.io/gae/hKHZTZSTmcznonu8I6xcVZio1IF76fq0XmcxnvUykC-FGuVJ75UPdLDlKJsfgVXH9wOSmkyHw0C39VAYtsGyxT7WNybjQ6s3fM3macE?w=500&auto=format'
462 |     );
463 |     nock(MANIFEST_URI_NICK.origin)
464 |       .options(MANIFEST_URI_NICK.pathname)
465 |       .reply(200, {}, {
466 |         ...CORS_HEADERS,
467 |         'access-control-allow-headers':
468 |           'accept, authorization, content-type, user-agent, x-csrftoken, x-requested-with, x-datadog-origin, x-datadog-parent-id, x-datadog-sampled, x-datadog-sampling-priority, x-datadog-trace-id, i196zqqsyk-a0, i196zqqsyk-a1, i196zqqsyk-a2, i196zqqsyk-a, i196zqqsyk-b, i196zqqsyk-c, i196zqqsyk-d, i196zqqsyk-f, i196zqqsyk-z, x-readme-api-explorer, x-api-key, x-build-id, x-signed-query, x-cache-skip, x-app-id, solana-client',
469 |         'access-control-allow-methods':
470 |           'DELETE, GET, OPTIONS, PATCH, POST, PUT',
471 |         'access-control-max-age': '86400',
472 |         'content-type': 'text/html; charset=utf-8',
473 |         'transfer-encoding': 'chunked',
474 |         vary: 'origin',
475 |         'x-content-type-options': 'nosniff',
476 |       } as any);
477 |     nock(NFT_URI_NICK.origin)
478 |       .head(NFT_URI_NICK.pathname + '?' + NFT_URI_NICK.searchParams)
479 |       .reply(
480 |         200,
481 |         {},
482 |         {
483 |           'accept-ranges': 'bytes',
484 |           'access-control-allow-origin': '*',
485 |           'access-control-expose-headers': '*',
486 |           'content-length': '7229',
487 |           'content-type': 'image/png',
488 |         }
489 |       );
490 |     nock(MANIFEST_URI_NICK.origin)
491 |       .get(MANIFEST_URI_NICK.pathname)
492 |       .reply(
493 |         200,
494 |         {
495 |           name: 'Nick Johnson',
496 |           description: null,
497 |           external_link: null,
498 |           image: NFT_URI_NICK.toString(),
499 |           animation_url: null,
500 |         },
501 |         CORS_HEADERS as any
502 |       );
503 |     expect(await avt.getAvatar('nick.eth')).toEqual(NFT_URI_NICK.toString());
504 |   });
505 | 
506 |   it('sets cache to 1 sec', async () => {
507 |     const avt = new AvatarResolver(provider, { cache: 1 });
508 |     expect(avt?.options?.cache).toEqual(1);
509 |   });
510 | 
511 |   // it('retrieves image uri with custom nested uri', async () => {
512 |   //   expect(await avt.getAvatar({ ens: 'testname.eth' })).toEqual(
513 |   //     ''
514 |   //   );
515 |   // });
516 | 
517 |   // on chain svg example
518 |   // it('retrieves image uri with custom nested uri', async () => {
519 |   //   expect(await avt.getAvatar({ ens: 'testname.eth' })).toMatch(/^(data:image\/svg\+xml;base64,).*$/);
520 |   // });
521 | });
522 | 
523 | describe('get banner/header', () => {
524 |   it('retrieves image uri with custom spec', async () => {
525 |     mockInfuraChainId();
526 | 
527 |     nockInfuraBatch(
528 |       [
529 |         ethCallParams(
530 |           ENSRegistryWithFallback.toString(),
531 |           '0x0178b8bfb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f'
532 |         ),
533 |         chainIdParams(),
534 |         ethCallParams(
535 |           ENSRegistryWithFallback.toString(),
536 |           '0x0178b8bfb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f'
537 |         ),
538 |       ],
539 |       [
540 |         jsonRpcResult(
541 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
542 |         ),
543 |         jsonRpcResult('0x1'),
544 |         jsonRpcResult(
545 |           '0x0000000000000000000000004976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41'
546 |         ),
547 |       ]
548 |     );
549 |     nockInfuraBatch(
550 |       [
551 |         ethCallParams(
552 |           PublicResolver.toLowerCase(),
553 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
554 |         ),
555 |         chainIdParams(),
556 |       ],
557 |       [
558 |         jsonRpcResult(
559 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
560 |         ),
561 |         jsonRpcResult('0x1'),
562 |       ]
563 |     );
564 |     nockInfuraBatch(
565 |       [
566 |         ethCallParams(
567 |           PublicResolver.toLowerCase(),
568 |           '0x3b3b57deb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f'
569 |         ),
570 |         chainIdParams(),
571 |       ],
572 |       [
573 |         jsonRpcResult(
574 |           '0x0000000000000000000000000d59d0f7dcc0fbf0a3305ce0261863aaf7ab685c'
575 |         ),
576 |         jsonRpcResult('0x1'),
577 |       ]
578 |     );
579 |     nockInfuraBatch(
580 |       [
581 |         ethCallParams(
582 |           PublicResolver.toLowerCase(),
583 |           '0x01ffc9a79061b92300000000000000000000000000000000000000000000000000000000'
584 |         ),
585 |         chainIdParams(),
586 |       ],
587 |       [
588 |         jsonRpcResult(
589 |           '0x0000000000000000000000000000000000000000000000000000000000000000'
590 |         ),
591 |         jsonRpcResult('0x1'),
592 |       ]
593 |     );
594 | 
595 |     nockInfuraBatch(
596 |       [
597 |         ethCallParams(
598 |           PublicResolver.toLowerCase(),
599 |           '0x59d1d43cb47a0edaf3c702800c923ca4c44a113d0d718cb1f42ecdce70c5fd05fa36a63f000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000066865616465720000000000000000000000000000000000000000000000000000'
600 |         ),
601 |         chainIdParams(),
602 |       ],
603 |       [
604 |         jsonRpcResult(
605 |           '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000004368747470733a2f2f697066732e696f2f697066732f516d55536867666f5a5153484b3354517975546655707363385566654e6644384b77505576444255645a346e6d520000000000000000000000000000000000000000000000000000000000'
606 |         ), // Encoded HEADER URI
607 |         jsonRpcResult('0x1'),
608 |       ]
609 |     );
610 | 
611 |     const HEADER_URI_TANRIKULU = new URL(
612 |       'https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR'
613 |     );
614 | 
615 |     /* mock head call */
616 |     nock(HEADER_URI_TANRIKULU.origin)
617 |       .head(HEADER_URI_TANRIKULU.pathname)
618 |       .reply(200, {}, {
619 |         ...CORS_HEADERS,
620 |         'content-type': 'image/png',
621 |       } as any);
622 |     /* mock get call */
623 |     nock(HEADER_URI_TANRIKULU.origin)
624 |       .get(HEADER_URI_TANRIKULU.pathname)
625 |       .reply(200, {}, {
626 |         ...CORS_HEADERS,
627 |         'content-type': 'image/png',
628 |       } as any);
629 |     expect(await avt.getHeader('tanrikulu.eth')).toEqual(
630 |       'https://ipfs.io/ipfs/QmUShgfoZQSHK3TQyuTfUpsc8UfeNfD8KwPUvDBUdZ4nmR'
631 |     );
632 |   });
633 | });
634 | 


--------------------------------------------------------------------------------