461 lines
19 KiB
JavaScript
461 lines
19 KiB
JavaScript
/*!
|
||
* Sitemap
|
||
* Copyright(c) 2011 Eugene Kalinin
|
||
* MIT Licensed
|
||
*/
|
||
import { InvalidPathError, InvalidURLError, InvalidLimitError, InvalidPublicBasePathError, InvalidXSLUrlError, ChangeFreqInvalidError, InvalidAttrValue, InvalidNewsAccessValue, InvalidNewsFormat, InvalidVideoDescription, InvalidVideoDuration, InvalidVideoFormat, InvalidVideoRating, NoURLError, NoConfigError, PriorityInvalidError, InvalidVideoTitle, InvalidVideoViewCount, InvalidVideoTagCount, InvalidVideoCategory, InvalidVideoFamilyFriendly, InvalidVideoYesNo, InvalidLinkHreflang, InvalidVideoRestriction, InvalidVideoRestrictionRelationship, InvalidVideoPriceType, InvalidVideoResolution, InvalidVideoPriceCurrency, } from './errors.js';
|
||
import { ErrorLevel, EnumChangefreq, EnumYesNo, EnumAllowDeny, } from './types.js';
|
||
import { LIMITS } from './constants.js';
|
||
import { defaultLogger, loggingErrorHandler } from './logger.js';
|
||
import { isAbsolute } from 'node:path';
|
||
/**
|
||
* Validator regular expressions for various sitemap fields
|
||
*/
|
||
const allowDeny = /^(?:allow|deny)$/;
|
||
export const validators = {
|
||
'price:currency': /^[A-Z]{3}$/,
|
||
'price:type': /^(?:rent|purchase|RENT|PURCHASE)$/,
|
||
'price:resolution': /^(?:HD|hd|sd|SD)$/,
|
||
'platform:relationship': allowDeny,
|
||
'restriction:relationship': allowDeny,
|
||
restriction: /^([A-Z]{2}( +[A-Z]{2})*)?$/,
|
||
platform: /^((web|mobile|tv)( (web|mobile|tv))*)?$/,
|
||
// Language codes: zh-cn, zh-tw, or ISO 639 2-3 letter codes
|
||
language: /^(zh-cn|zh-tw|[a-z]{2,3})$/,
|
||
genres: /^(PressRelease|Satire|Blog|OpEd|Opinion|UserGenerated)(, *(PressRelease|Satire|Blog|OpEd|Opinion|UserGenerated))*$/,
|
||
stock_tickers: /^(\w+:\w+(, *\w+:\w+){0,4})?$/,
|
||
};
|
||
/**
|
||
* Type guard to check if a string is a valid price type
|
||
*/
|
||
export function isPriceType(pt) {
|
||
return validators['price:type'].test(pt);
|
||
}
|
||
/**
|
||
* Type guard to check if a string is a valid resolution
|
||
*/
|
||
export function isResolution(res) {
|
||
return validators['price:resolution'].test(res);
|
||
}
|
||
/**
|
||
* Type guard to check if a string is a valid changefreq value
|
||
*/
|
||
const CHANGEFREQ = Object.values(EnumChangefreq);
|
||
export function isValidChangeFreq(freq) {
|
||
return CHANGEFREQ.includes(freq);
|
||
}
|
||
/**
|
||
* Type guard to check if a string is a valid yes/no value
|
||
*/
|
||
export function isValidYesNo(yn) {
|
||
return /^(?:YES|NO|[Yy]es|[Nn]o)$/.test(yn);
|
||
}
|
||
/**
|
||
* Checks that a priority is a finite number within sitemaps.org bounds (0–1)
|
||
*/
|
||
export function isValidPriority(priority) {
|
||
return (typeof priority === 'number' &&
|
||
Number.isFinite(priority) &&
|
||
priority >= LIMITS.MIN_PRIORITY &&
|
||
priority <= LIMITS.MAX_PRIORITY);
|
||
}
|
||
/**
|
||
* Checks that a video duration is a finite number of seconds within Google's
|
||
* video sitemap bounds (0–28800)
|
||
*/
|
||
export function isValidVideoDuration(duration) {
|
||
return (isFinite(duration) &&
|
||
duration >= LIMITS.MIN_VIDEO_DURATION &&
|
||
duration <= LIMITS.MAX_VIDEO_DURATION);
|
||
}
|
||
/**
|
||
* Checks that a video rating is a finite number within Google's video sitemap
|
||
* bounds (0–5)
|
||
*/
|
||
export function isValidVideoRating(rating) {
|
||
return (isFinite(rating) &&
|
||
rating >= LIMITS.MIN_VIDEO_RATING &&
|
||
rating <= LIMITS.MAX_VIDEO_RATING);
|
||
}
|
||
/**
|
||
* Checks that a video view count is a finite, non-negative number
|
||
*/
|
||
export function isValidVideoViewCount(count) {
|
||
return isFinite(count) && count >= LIMITS.MIN_VIDEO_VIEW_COUNT;
|
||
}
|
||
/**
|
||
* Checks that a date string is in ISO 8601 / W3C format
|
||
*/
|
||
export function isValidISODate(date) {
|
||
return LIMITS.ISO_DATE_REGEX.test(date);
|
||
}
|
||
/**
|
||
* Returns an alternate link's language (`lang`, else `hreflang`), or
|
||
* `undefined` when neither is a non-empty string. Validation reports such a
|
||
* link, and the writer drops it.
|
||
*/
|
||
export function getLinkHreflang(link) {
|
||
const hreflang = link.lang || link.hreflang;
|
||
return typeof hreflang === 'string' && hreflang !== '' ? hreflang : undefined;
|
||
}
|
||
/**
|
||
* Type guard to check if a string is a valid allow/deny value
|
||
*/
|
||
export function isAllowDeny(ad) {
|
||
return allowDeny.test(ad);
|
||
}
|
||
/**
|
||
* Validates that a URL is well-formed and meets security requirements
|
||
*
|
||
* Security: This function enforces that URLs use safe protocols (http/https),
|
||
* are within reasonable length limits (2048 chars per sitemaps.org spec),
|
||
* and can be properly parsed. This prevents protocol injection attacks and
|
||
* ensures compliance with sitemap specifications.
|
||
*
|
||
* @param url - The URL to validate
|
||
* @param paramName - The parameter name for error messages
|
||
* @throws {InvalidURLError} If the URL is invalid (a subclass of InvalidHostnameError)
|
||
*/
|
||
export function validateURL(url, paramName) {
|
||
if (!url || typeof url !== 'string') {
|
||
throw new InvalidURLError(url, `${paramName} must be a non-empty string`);
|
||
}
|
||
if (url.length > LIMITS.MAX_URL_LENGTH) {
|
||
throw new InvalidURLError(url, `${paramName} exceeds maximum length of ${LIMITS.MAX_URL_LENGTH} characters`);
|
||
}
|
||
if (!LIMITS.URL_PROTOCOL_REGEX.test(url)) {
|
||
throw new InvalidURLError(url, `${paramName} must use http:// or https:// protocol`);
|
||
}
|
||
// Validate URL can be parsed
|
||
try {
|
||
new URL(url);
|
||
}
|
||
catch (err) {
|
||
throw new InvalidURLError(url, `${paramName} is not a valid URL: ${err instanceof Error ? err.message : String(err)}`);
|
||
}
|
||
}
|
||
/**
|
||
* Runs validateURL and returns its error message instead of throwing, for
|
||
* parsers that report invalid values and keep going.
|
||
*
|
||
* @returns The validation error message, or undefined if the URL is valid
|
||
*/
|
||
export function getURLError(url, paramName) {
|
||
try {
|
||
validateURL(url, paramName);
|
||
return undefined;
|
||
}
|
||
catch (error) {
|
||
return error instanceof Error ? error.message : String(error);
|
||
}
|
||
}
|
||
/**
|
||
* Validates that a path doesn't contain path traversal sequences
|
||
*
|
||
* Security: This function prevents path traversal attacks by detecting
|
||
* any occurrence of '..' in the path, whether it appears as '../', '/..',
|
||
* or standalone. This prevents attackers from accessing files outside
|
||
* the intended directory structure.
|
||
*
|
||
* @param path - The path to validate
|
||
* @param paramName - The parameter name for error messages
|
||
* @throws {InvalidPathError} If the path contains traversal sequences
|
||
*/
|
||
export function validatePath(path, paramName) {
|
||
if (!path || typeof path !== 'string') {
|
||
throw new InvalidPathError(path, `${paramName} must be a non-empty string`);
|
||
}
|
||
// Reject absolute paths to prevent arbitrary write location when caller input
|
||
// reaches destinationDir (BB-04)
|
||
if (isAbsolute(path)) {
|
||
throw new InvalidPathError(path, `${paramName} must be a relative path (absolute paths are not allowed)`);
|
||
}
|
||
// Check for path traversal sequences - must check before and after normalization
|
||
// to catch both Windows-style (\) and Unix-style (/) separators
|
||
if (path.includes('..')) {
|
||
throw new InvalidPathError(path, `${paramName} contains path traversal sequence (..)`);
|
||
}
|
||
// Additional check after normalization to catch encoded or obfuscated attempts
|
||
const normalizedPath = path.replace(/\\/g, '/');
|
||
const pathComponents = normalizedPath.split('/').filter((p) => p.length > 0);
|
||
if (pathComponents.includes('..')) {
|
||
throw new InvalidPathError(path, `${paramName} contains path traversal sequence (..)`);
|
||
}
|
||
// Check for null bytes (security issue in some contexts)
|
||
if (path.includes('\0')) {
|
||
throw new InvalidPathError(path, `${paramName} contains null byte character`);
|
||
}
|
||
}
|
||
/**
|
||
* Validates that a public base path is safe for URL construction
|
||
*
|
||
* Security: This function prevents path traversal attacks and validates
|
||
* that the path is safe for use in URL construction within sitemap indexes.
|
||
* It checks for '..' sequences, null bytes, and invalid whitespace that
|
||
* could be used to manipulate URL structure or inject malicious content.
|
||
*
|
||
* @param publicBasePath - The public base path to validate
|
||
* @throws {InvalidPublicBasePathError} If the path is invalid
|
||
*/
|
||
export function validatePublicBasePath(publicBasePath) {
|
||
if (!publicBasePath || typeof publicBasePath !== 'string') {
|
||
throw new InvalidPublicBasePathError(publicBasePath, 'must be a non-empty string');
|
||
}
|
||
// Check for path traversal - check the raw string first
|
||
if (publicBasePath.includes('..')) {
|
||
throw new InvalidPublicBasePathError(publicBasePath, 'contains path traversal sequence (..)');
|
||
}
|
||
// Additional check for path components after normalization
|
||
const normalizedPath = publicBasePath.replace(/\\/g, '/');
|
||
const pathComponents = normalizedPath.split('/').filter((p) => p.length > 0);
|
||
if (pathComponents.includes('..')) {
|
||
throw new InvalidPublicBasePathError(publicBasePath, 'contains path traversal sequence (..)');
|
||
}
|
||
// Check for null bytes
|
||
if (publicBasePath.includes('\0')) {
|
||
throw new InvalidPublicBasePathError(publicBasePath, 'contains null byte character');
|
||
}
|
||
// Check for potentially dangerous characters that could break URL construction
|
||
if (/[\r\n\t]/.test(publicBasePath)) {
|
||
throw new InvalidPublicBasePathError(publicBasePath, 'contains invalid whitespace characters');
|
||
}
|
||
}
|
||
/**
|
||
* Validates that a limit is within acceptable range per sitemaps.org spec
|
||
*
|
||
* Security: This function enforces sitemap size limits (1-50,000 URLs per
|
||
* sitemap) as specified by sitemaps.org. This prevents resource exhaustion
|
||
* attacks and ensures compliance with search engine requirements.
|
||
*
|
||
* @param limit - The limit to validate
|
||
* @throws {InvalidLimitError} If the limit is out of range
|
||
*/
|
||
export function validateLimit(limit) {
|
||
if (typeof limit !== 'number' ||
|
||
!Number.isFinite(limit) ||
|
||
Number.isNaN(limit)) {
|
||
throw new InvalidLimitError(limit);
|
||
}
|
||
if (limit < LIMITS.MIN_SITEMAP_ITEM_LIMIT ||
|
||
limit > LIMITS.MAX_SITEMAP_ITEM_LIMIT) {
|
||
throw new InvalidLimitError(limit);
|
||
}
|
||
// Ensure it's an integer
|
||
if (!Number.isInteger(limit)) {
|
||
throw new InvalidLimitError(limit);
|
||
}
|
||
}
|
||
/**
|
||
* Whether `n` is a valid parser entry cap: a non-negative integer, or
|
||
* `Infinity` for no cap. Unlike validateLimit, 0 and values above the
|
||
* sitemaps.org limit are allowed.
|
||
*/
|
||
export function isValidMaxEntries(n) {
|
||
return n === Infinity || (Number.isInteger(n) && n >= 0);
|
||
}
|
||
/**
|
||
* Validates that an XSL URL is safe and well-formed
|
||
*
|
||
* Security: This function validates XSL stylesheet URLs to prevent
|
||
* injection attacks. It blocks dangerous protocols and content patterns
|
||
* that could be used for XSS or other attacks. The validation uses
|
||
* case-insensitive matching to catch obfuscated attacks.
|
||
*
|
||
* @param xslUrl - The XSL URL to validate
|
||
* @throws {InvalidXSLUrlError} If the URL is invalid
|
||
*/
|
||
export function validateXSLUrl(xslUrl) {
|
||
if (!xslUrl || typeof xslUrl !== 'string') {
|
||
throw new InvalidXSLUrlError(xslUrl, 'must be a non-empty string');
|
||
}
|
||
if (xslUrl.length > LIMITS.MAX_URL_LENGTH) {
|
||
throw new InvalidXSLUrlError(xslUrl, `exceeds maximum length of ${LIMITS.MAX_URL_LENGTH} characters`);
|
||
}
|
||
if (!LIMITS.URL_PROTOCOL_REGEX.test(xslUrl)) {
|
||
throw new InvalidXSLUrlError(xslUrl, 'must use http:// or https:// protocol');
|
||
}
|
||
// Validate URL can be parsed
|
||
try {
|
||
new URL(xslUrl);
|
||
}
|
||
catch (err) {
|
||
throw new InvalidXSLUrlError(xslUrl, `is not a valid URL: ${err instanceof Error ? err.message : String(err)}`);
|
||
}
|
||
// Check for potentially dangerous content (case-insensitive)
|
||
const lowerUrl = xslUrl.toLowerCase();
|
||
// Block dangerous HTML/script content
|
||
if (lowerUrl.includes('<script')) {
|
||
throw new InvalidXSLUrlError(xslUrl, 'contains potentially malicious content (<script tag)');
|
||
}
|
||
// Block dangerous protocols (already checked http/https above, but double-check for encoded variants)
|
||
const dangerousProtocols = [
|
||
'javascript:',
|
||
'data:',
|
||
'vbscript:',
|
||
'file:',
|
||
'about:',
|
||
];
|
||
for (const protocol of dangerousProtocols) {
|
||
if (lowerUrl.includes(protocol)) {
|
||
throw new InvalidXSLUrlError(xslUrl, `contains dangerous protocol: ${protocol}`);
|
||
}
|
||
}
|
||
// Check for URL-encoded variants of dangerous patterns
|
||
// %3C = '<', %3E = '>', %3A = ':'
|
||
const encodedPatterns = [
|
||
'%3cscript', // <script
|
||
'%3c%73%63%72%69%70%74', // <script (fully encoded)
|
||
'javascript%3a', // javascript:
|
||
'data%3a', // data:
|
||
];
|
||
for (const pattern of encodedPatterns) {
|
||
if (lowerUrl.includes(pattern)) {
|
||
throw new InvalidXSLUrlError(xslUrl, 'contains URL-encoded malicious content');
|
||
}
|
||
}
|
||
// Reject unencoded XML special characters — these must be percent-encoded in
|
||
// valid URLs and could break out of XML attribute context if left raw.
|
||
if (xslUrl.includes('"') || xslUrl.includes('<') || xslUrl.includes('>')) {
|
||
throw new InvalidXSLUrlError(xslUrl, 'contains unencoded XML special characters (" < >); percent-encode them in the URL');
|
||
}
|
||
}
|
||
/**
|
||
* Internal helper to validate fields against their validators
|
||
*/
|
||
function validate(subject, url, level, errorHandler) {
|
||
Object.keys(subject).forEach((key) => {
|
||
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
|
||
// @ts-ignore
|
||
const val = subject[key];
|
||
if (validators[key] && !validators[key].test(val)) {
|
||
errorHandler(new InvalidAttrValue(key, val, validators[key], url), level);
|
||
}
|
||
});
|
||
}
|
||
// Default for direct validateSMIOptions() calls: warn through the console
|
||
const handleError = loggingErrorHandler(defaultLogger);
|
||
/**
|
||
* Verifies all data passed in will comply with sitemap spec.
|
||
* @param conf Options to validate
|
||
* @param level logging level
|
||
* @param errorHandler error handling func
|
||
*/
|
||
export function validateSMIOptions(conf, level = ErrorLevel.WARN, errorHandler = handleError) {
|
||
if (!conf) {
|
||
throw new NoConfigError();
|
||
}
|
||
if (level === ErrorLevel.SILENT) {
|
||
return conf;
|
||
}
|
||
const { url, changefreq, priority, news, video } = conf;
|
||
if (!url) {
|
||
errorHandler(new NoURLError(), level);
|
||
}
|
||
if (changefreq) {
|
||
if (!isValidChangeFreq(changefreq)) {
|
||
errorHandler(new ChangeFreqInvalidError(url, changefreq), level);
|
||
}
|
||
}
|
||
if (priority !== undefined && priority !== null) {
|
||
if (!isValidPriority(priority)) {
|
||
errorHandler(new PriorityInvalidError(url, priority), level);
|
||
}
|
||
}
|
||
if (Array.isArray(conf.links)) {
|
||
conf.links.forEach((link) => {
|
||
if (getLinkHreflang(link) === undefined) {
|
||
errorHandler(new InvalidLinkHreflang(url, link.url, link.lang || link.hreflang), level);
|
||
}
|
||
});
|
||
}
|
||
if (news) {
|
||
if (news.access &&
|
||
news.access !== 'Registration' &&
|
||
news.access !== 'Subscription') {
|
||
errorHandler(new InvalidNewsAccessValue(url, news.access), level);
|
||
}
|
||
if (!news.publication ||
|
||
!news.publication.name ||
|
||
!news.publication.language ||
|
||
!news.publication_date ||
|
||
!news.title) {
|
||
errorHandler(new InvalidNewsFormat(url), level);
|
||
}
|
||
validate(news, url, level, errorHandler);
|
||
validate(news.publication, url, level, errorHandler);
|
||
}
|
||
if (video) {
|
||
video.forEach((vid) => {
|
||
if (vid.duration !== undefined) {
|
||
if (!isValidVideoDuration(vid.duration)) {
|
||
errorHandler(new InvalidVideoDuration(url, vid.duration), level);
|
||
}
|
||
}
|
||
if (vid.rating !== undefined && !isValidVideoRating(vid.rating)) {
|
||
errorHandler(new InvalidVideoRating(url, vid.title, vid.rating), level);
|
||
}
|
||
if (typeof vid !== 'object' ||
|
||
!vid.thumbnail_loc ||
|
||
!vid.title ||
|
||
!vid.description) {
|
||
// has to be an object and include required categories https://support.google.com/webmasters/answer/80471?hl=en&ref_topic=4581190
|
||
errorHandler(new InvalidVideoFormat(url), level);
|
||
}
|
||
if (vid.title.length > 100) {
|
||
errorHandler(new InvalidVideoTitle(url, vid.title.length), level);
|
||
}
|
||
if (vid.description.length > 2048) {
|
||
errorHandler(new InvalidVideoDescription(url, vid.description.length), level);
|
||
}
|
||
if (vid.view_count !== undefined &&
|
||
!isValidVideoViewCount(vid.view_count)) {
|
||
errorHandler(new InvalidVideoViewCount(url, vid.view_count), level);
|
||
}
|
||
if (vid.tag.length > 32) {
|
||
errorHandler(new InvalidVideoTagCount(url, vid.tag.length), level);
|
||
}
|
||
if (vid.category !== undefined && vid.category?.length > 256) {
|
||
errorHandler(new InvalidVideoCategory(url, vid.category.length), level);
|
||
}
|
||
if (vid.family_friendly !== undefined &&
|
||
!isValidYesNo(vid.family_friendly)) {
|
||
errorHandler(new InvalidVideoFamilyFriendly(url, vid.family_friendly), level);
|
||
}
|
||
for (const field of [
|
||
'requires_subscription',
|
||
'live',
|
||
'player_loc:allow_embed',
|
||
]) {
|
||
const value = vid[field];
|
||
if (value !== undefined && !isValidYesNo(value)) {
|
||
errorHandler(new InvalidVideoYesNo(url, field, value), level);
|
||
}
|
||
}
|
||
if (vid.restriction) {
|
||
if (!validators.restriction.test(vid.restriction)) {
|
||
errorHandler(new InvalidVideoRestriction(url, vid.restriction), level);
|
||
}
|
||
if (!vid['restriction:relationship'] ||
|
||
!isAllowDeny(vid['restriction:relationship'])) {
|
||
errorHandler(new InvalidVideoRestrictionRelationship(url, vid['restriction:relationship']), level);
|
||
}
|
||
}
|
||
// TODO price element should be unbounded
|
||
if ((vid.price === '' && vid['price:type'] === undefined) ||
|
||
(vid['price:type'] !== undefined && !isPriceType(vid['price:type']))) {
|
||
errorHandler(new InvalidVideoPriceType(url, vid['price:type'], vid.price), level);
|
||
}
|
||
if (vid['price:resolution'] !== undefined &&
|
||
!isResolution(vid['price:resolution'])) {
|
||
errorHandler(new InvalidVideoResolution(url, vid['price:resolution']), level);
|
||
}
|
||
if (vid['price:currency'] !== undefined &&
|
||
!validators['price:currency'].test(vid['price:currency'])) {
|
||
errorHandler(new InvalidVideoPriceCurrency(url, vid['price:currency']), level);
|
||
}
|
||
validate(vid, url, level, errorHandler);
|
||
});
|
||
}
|
||
return conf;
|
||
}
|