{"schemaVersion":1,"id":"https://lucioduran.com/decisions/scoped-remote-image-patterns","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns","title":"Scoped Remote Image Patterns over Generic CDN Proxy","description":"The portfolio displays images from multiple origins: profile photos and social cards from statics.lucioduran.com, dynamic content images from api.lucioduran.com","language":"en","datePublished":"2024-05-20","dateModified":null,"contentFormat":"text/markdown","content":"ADR-016acceptedMay 20, 2024\n\n# Scoped Remote Image Patterns over Generic CDN Proxy\n\n## Context\n\nThe portfolio displays images from multiple origins: profile photos and social cards from statics.lucioduran.com, dynamic content images from api.lucioduran.com, and the main domain lucioduran.com for statically hosted assets. Next.js Image component provides automatic optimization (WebP/AVIF conversion, responsive sizing, lazy loading) but requires explicit configuration of allowed remote image sources via remotePatterns in next.config.js. The configuration choice is between a permissive approach (allowing any hostname via a wildcard pattern) and a restrictive approach (explicitly listing each allowed origin). A wildcard pattern simplifies configuration but creates an open proxy, any external image URL processed through Next.js Image becomes an attack vector for SSRF (Server-Side Request Forgery), where an attacker could force the server to fetch internal network resources. For a publicly deployed site on Vercel, this could expose Vercel's internal infrastructure to probing.\n\n## Decision\n\nConfigure next.config.js remotePatterns with exactly three explicitly listed hostnames, all under the lucioduran.com domain: statics.lucioduran.com (static assets CDN), api.lucioduran.com (dynamic content images), and lucioduran.com (root domain assets). Each entry specifies protocol: 'https', no HTTP sources allowed. No wildcard patterns, no catch-all rules, no third-party hostnames. Images from any other origin must be downloaded and self-hosted before they can be optimized through Next.js Image. This creates a closed system where every image URL processed by the optimization pipeline is from a controlled, first-party origin.\n\n## Consequences\n\nPositive: The image optimization endpoint cannot be used as an SSRF proxy, only three known, controlled hostnames are processable. HTTPS-only enforcement prevents accidental mixed-content serving. The explicit listing serves as documentation of the site's image infrastructure, a new developer can immediately see which origins serve images. All three origins share a common root domain (lucioduran.com), making SSL certificate management consistent. The constraint forces discipline: every image must be hosted on owned infrastructure, preventing dependency on third-party image services that could change URLs or go offline. Negative: Adding a new image source (e.g., a profile photo from a third-party service, screenshots from external tools) requires a next.config.js change and redeploy. If a content entry references an image on an unlisted domain, the Next.js Image component falls back to an unoptimized img tag or errors, depending on configuration. The three-origin limitation means all images must be uploaded to owned infrastructure first, adding a manual step to the content authoring workflow.\n\n## Calibrated Uncertainty\n\n## Predictions at Decision Time\n\nExpected the three-origin restriction to cover all current and near-future image sources. Predicted the manual upload step (images to owned infrastructure) would add negligible friction because image changes are infrequent. Assumed no third-party image sources would be needed.\n\n## Measured Outcomes\n\nThe three-origin restriction has covered 100% of image needs for 20+ months. No third-party image source has been required. The manual upload step is negligible as predicted, images change approximately once per quarter. The ~60% size reduction from WebP optimization is consistent across all image types (profile photos, social cards, content images). The unexpected benefit: having all images on owned infrastructure means zero risk of broken images from third-party URL changes or service discontinuations, a problem that has affected previous projects with images hotlinked from external services.\n\n## Unknowns at Decision Time\n\nDid not know whether future content types would require images from external origins (e.g., GitHub avatar URLs, certification badge images from third-party issuers). So far they haven't, all images are self-hosted. Also unknown: whether Vercel's image optimization pricing would change for free tier users. Currently unlimited, but usage-based pricing could make aggressive image optimization costly at scale.\n\n## Reversibility Classification\n\nTwo-Way Door\n\nAdding new origins to remotePatterns is a single line addition to next.config.js. Switching to a wildcard pattern (hostname: '\\*\\*') is a one-line change. Removing Image optimization entirely and using standard img tags requires replacing Next.js Image imports across components. Estimated effort for any pattern change: 5 minutes plus redeploy.\n\n## Strongest Counter-Argument\n\nThe SSRF risk for a static portfolio site on Vercel is theoretical, there are no internal network resources to probe, and Vercel's infrastructure is not vulnerable to SSRF via image optimization endpoints. A wildcard pattern would simplify the workflow for adding new image sources and eliminate the manual upload step. For a single-developer project with full control over content, the security posture is arguably over-restrictive. The counter-counter: the restrictive pattern is not just about SSRF, it's about infrastructure ownership. Depending on external image hosts creates a silent availability risk that is harder to diagnose than a build failure.\n\n## Technical Context\n\nStack\n\n- Next.js Image\n- next.config.js remotePatterns\n- WebP/AVIF\n- Vercel Image Optimization\n\nAllowed Origins\n\n3\n\nProtocol Restriction\n\nHTTPS only\n\nWildcard Patterns\n\n0\n\nAvg Image Size Reduction\n\n~60% (WebP vs PNG)\n\nConstraints\n\n- No wildcard hostname patterns\n- HTTPS only\n- All origins must be first-party controlled\n\n## Related Decisions\n\n- [ADR-015accepted\n\n  Critical Rendering Path Optimization Strategy](<https://lucioduran.com/decisions/critical-rendering-path-optimization>)\n- [ADR-017accepted\n\n  Defense-in-Depth HTTP Security Headers](<https://lucioduran.com/decisions/defense-in-depth-security-headers>)\n\n[Back to Decisions](<https://lucioduran.com/decisions>)","headings":[{"level":1,"text":"Scoped Remote Image Patterns over Generic CDN Proxy","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#title"},{"level":2,"text":"Context","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-context"},{"level":2,"text":"Decision","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-decision"},{"level":2,"text":"Consequences","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-consequences"},{"level":2,"text":"Calibrated Uncertainty","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-uncertainty"},{"level":2,"text":"Predictions at Decision Time","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-predictions"},{"level":2,"text":"Measured Outcomes","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-outcomes"},{"level":2,"text":"Unknowns at Decision Time","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-unknowns"},{"level":2,"text":"Reversibility Classification","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-reversibility"},{"level":2,"text":"Strongest Counter-Argument","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-counterArgument"},{"level":2,"text":"Technical Context","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-techContext"},{"level":2,"text":"Related Decisions","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-relatedDecisions"}],"sections":[{"heading":"Scoped Remote Image Patterns over Generic CDN Proxy","level":1,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns","content":"ADR-016acceptedMay 20, 2024"},{"heading":"Scoped Remote Image Patterns over Generic CDN Proxy","level":1,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#title","content":""},{"heading":"Context","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-context","content":"The portfolio displays images from multiple origins: profile photos and social cards from statics.lucioduran.com, dynamic content images from api.lucioduran.com, and the main domain lucioduran.com for statically hosted assets. Next.js Image component provides automatic optimization (WebP/AVIF conversion, responsive sizing, lazy loading) but requires explicit configuration of allowed remote image sources via remotePatterns in next.config.js. The configuration choice is between a permissive approach (allowing any hostname via a wildcard pattern) and a restrictive approach (explicitly listing each allowed origin). A wildcard pattern simplifies configuration but creates an open proxy, any external image URL processed through Next.js Image becomes an attack vector for SSRF (Server-Side Request Forgery), where an attacker could force the server to fetch internal network resources. For a publicly deployed site on Vercel, this could expose Vercel's internal infrastructure to probing."},{"heading":"Decision","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-decision","content":"Configure next.config.js remotePatterns with exactly three explicitly listed hostnames, all under the lucioduran.com domain: statics.lucioduran.com (static assets CDN), api.lucioduran.com (dynamic content images), and lucioduran.com (root domain assets). Each entry specifies protocol: 'https', no HTTP sources allowed. No wildcard patterns, no catch-all rules, no third-party hostnames. Images from any other origin must be downloaded and self-hosted before they can be optimized through Next.js Image. This creates a closed system where every image URL processed by the optimization pipeline is from a controlled, first-party origin."},{"heading":"Consequences","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-consequences","content":"Positive: The image optimization endpoint cannot be used as an SSRF proxy, only three known, controlled hostnames are processable. HTTPS-only enforcement prevents accidental mixed-content serving. The explicit listing serves as documentation of the site's image infrastructure, a new developer can immediately see which origins serve images. All three origins share a common root domain (lucioduran.com), making SSL certificate management consistent. The constraint forces discipline: every image must be hosted on owned infrastructure, preventing dependency on third-party image services that could change URLs or go offline. Negative: Adding a new image source (e.g., a profile photo from a third-party service, screenshots from external tools) requires a next.config.js change and redeploy. If a content entry references an image on an unlisted domain, the Next.js Image component falls back to an unoptimized img tag or errors, depending on configuration. The three-origin limitation means all images must be uploaded to owned infrastructure first, adding a manual step to the content authoring workflow."},{"heading":"Calibrated Uncertainty","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-uncertainty","content":""},{"heading":"Predictions at Decision Time","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-predictions","content":"Expected the three-origin restriction to cover all current and near-future image sources. Predicted the manual upload step (images to owned infrastructure) would add negligible friction because image changes are infrequent. Assumed no third-party image sources would be needed."},{"heading":"Measured Outcomes","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-outcomes","content":"The three-origin restriction has covered 100% of image needs for 20+ months. No third-party image source has been required. The manual upload step is negligible as predicted, images change approximately once per quarter. The ~60% size reduction from WebP optimization is consistent across all image types (profile photos, social cards, content images). The unexpected benefit: having all images on owned infrastructure means zero risk of broken images from third-party URL changes or service discontinuations, a problem that has affected previous projects with images hotlinked from external services."},{"heading":"Unknowns at Decision Time","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-unknowns","content":"Did not know whether future content types would require images from external origins (e.g., GitHub avatar URLs, certification badge images from third-party issuers). So far they haven't, all images are self-hosted. Also unknown: whether Vercel's image optimization pricing would change for free tier users. Currently unlimited, but usage-based pricing could make aggressive image optimization costly at scale."},{"heading":"Reversibility Classification","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-reversibility","content":"Two-Way Door\n\nAdding new origins to remotePatterns is a single line addition to next.config.js. Switching to a wildcard pattern (hostname: '\\*\\*') is a one-line change. Removing Image optimization entirely and using standard img tags requires replacing Next.js Image imports across components. Estimated effort for any pattern change: 5 minutes plus redeploy."},{"heading":"Strongest Counter-Argument","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-counterArgument","content":"The SSRF risk for a static portfolio site on Vercel is theoretical, there are no internal network resources to probe, and Vercel's infrastructure is not vulnerable to SSRF via image optimization endpoints. A wildcard pattern would simplify the workflow for adding new image sources and eliminate the manual upload step. For a single-developer project with full control over content, the security posture is arguably over-restrictive. The counter-counter: the restrictive pattern is not just about SSRF, it's about infrastructure ownership. Depending on external image hosts creates a silent availability risk that is harder to diagnose than a build failure."},{"heading":"Technical Context","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-techContext","content":"Stack\n\n- Next.js Image\n- next.config.js remotePatterns\n- WebP/AVIF\n- Vercel Image Optimization\n\nAllowed Origins\n\n3\n\nProtocol Restriction\n\nHTTPS only\n\nWildcard Patterns\n\n0\n\nAvg Image Size Reduction\n\n~60% (WebP vs PNG)\n\nConstraints\n\n- No wildcard hostname patterns\n- HTTPS only\n- All origins must be first-party controlled"},{"heading":"Related Decisions","level":2,"url":"https://lucioduran.com/decisions/scoped-remote-image-patterns#decisionDetail-relatedDecisions","content":"- [ADR-015accepted\n\n  Critical Rendering Path Optimization Strategy](<https://lucioduran.com/decisions/critical-rendering-path-optimization>)\n- [ADR-017accepted\n\n  Defense-in-Depth HTTP Security Headers](<https://lucioduran.com/decisions/defense-in-depth-security-headers>)\n\n[Back to Decisions](<https://lucioduran.com/decisions>)"}],"links":[{"text":"ADR-015acceptedCritical Rendering Path Optimization Strategy","url":"https://lucioduran.com/decisions/critical-rendering-path-optimization"},{"text":"ADR-017acceptedDefense-in-Depth HTTP Security Headers","url":"https://lucioduran.com/decisions/defense-in-depth-security-headers"},{"text":"Back to Decisions","url":"https://lucioduran.com/decisions"}],"structuredData":[{"@context":"https://schema.org","@graph":[{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com/"},{"@type":"WebSite","@id":"https://lucioduran.com/#website","url":"https://lucioduran.com/","name":"Lucio Durán","inLanguage":["en","es"],"publisher":{"@id":"https://lucioduran.com/#person"}},{"@type":"WebPage","@id":"https://lucioduran.com/decisions/scoped-remote-image-patterns#page","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns","name":"ADR-016: Scoped Remote Image Patterns over Generic CDN Proxy | Lucio Durán","description":"The portfolio displays images from multiple origins: profile photos and social cards from statics.lucioduran.com, dynamic content images from api.lucioduran.com","inLanguage":"en","author":{"@id":"https://lucioduran.com/#person"},"publisher":{"@id":"https://lucioduran.com/#person"},"isPartOf":{"@id":"https://lucioduran.com/#website"},"isAccessibleForFree":true,"datePublished":"2024-05-20","mainEntity":{"@id":"https://lucioduran.com/decisions/scoped-remote-image-patterns#article"},"breadcrumb":{"@id":"https://lucioduran.com/decisions/scoped-remote-image-patterns#breadcrumb"}},{"@type":"TechArticle","url":"https://lucioduran.com/decisions/scoped-remote-image-patterns","name":"ADR-016: Scoped Remote Image Patterns over Generic CDN Proxy","headline":"Scoped Remote Image Patterns over Generic CDN Proxy","datePublished":"2024-05-20","author":{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com/"},"isPartOf":{"@id":"https://lucioduran.com/#website"},"inLanguage":"en","about":"Software Architecture Decision Record","proficiencyLevel":"Expert","dependencies":"Next.js Image, next.config.js remotePatterns, WebP/AVIF, Vercel Image Optimization","@id":"https://lucioduran.com/decisions/scoped-remote-image-patterns#article","publisher":{"@id":"https://lucioduran.com/#person"},"mainEntityOfPage":{"@id":"https://lucioduran.com/decisions/scoped-remote-image-patterns#page"},"isAccessibleForFree":true},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://lucioduran.com/"},{"@type":"ListItem","position":2,"name":"Architecture Decisions","item":"https://lucioduran.com/decisions"},{"@type":"ListItem","position":3,"name":"Scoped Remote Image Patterns over Generic CDN Proxy","item":"https://lucioduran.com/decisions/scoped-remote-image-patterns"}],"@id":"https://lucioduran.com/decisions/scoped-remote-image-patterns#breadcrumb"}]}],"contentHash":"7ed149ce18654ebf09a2aa29f4de7adee8f12b6d6fabb7b646acd6e6593a6d1e","provenance":{"method":"Deterministic serialization of the server-rendered main element","source":"https://lucioduran.com/decisions/scoped-remote-image-patterns","hashAlgorithm":"sha256","hashScope":"JSON document fields before contentHash and provenance","sourceHTMLBytes":44744,"contentBytes":6050}}
