handleOGProxy – Once UI

The handleOGProxy function is a server-side utility that proxies external images through your server. This is essential for displaying Open Graph images from external sources without CORS restrictions.

Features

Proxies images from external URLs
Preserves original content type
Configurable cache control headers
Custom user agent support
Validates URLs to block SSRF (private IPs, localhost, non-HTTPS)
Optional domain allowlist via allowedDomains
Requires Node.js runtime (uses DNS resolution for hostname validation)
Handles errors gracefully

Basic usage

Create an API route that uses the utility:

app/api/og/proxy/route.ts

import { NextRequest } from 'next/server';
import { handleOGProxy } from '@once-ui-system/core/server';

export const runtime = 'nodejs';

export async function GET(request: NextRequest) {
return handleOGProxy(request);
}

Then use the proxy in your client:

Component.tsx

const imageUrl = 'https://external-site.com/image.jpg';
const proxiedUrl = `/api/og/proxy?url=${encodeURIComponent(imageUrl)}`;

<img src={proxiedUrl} alt="External image" />

With options

Customize cache duration and user agent:

app/api/og/proxy/route.ts

import { NextRequest } from 'next/server';
import { handleOGProxy } from '@once-ui-system/core/server';

export async function GET(request: NextRequest) {
return handleOGProxy(request, {
  userAgent: 'Mozilla/5.0 (compatible; ImageProxy/1.0)',
  cacheMaxAge: 86400,
  allowedDomains: ['example.com', 'once-ui.com'],
});
}

Why use a proxy?

External images often have CORS restrictions that prevent direct usage in web applications. By proxying images through your server:

Bypass CORS: Your server fetches the image and serves it from your domain
Caching: Reduce external requests with configurable cache headers
Privacy: Hide the original image URL from client-side code
Reliability: Handle external failures gracefully

API Reference

Prop	Type	Default
request	Request	—
options	OGProxyOptions	—
options.userAgent User agent string for the fetch request.	string	'Mozilla/5.0 (compatible; OG-Proxy/1.0)'
options.cacheMaxAge Cache duration in seconds (1 hour).	number	3600
options.allowedDomains When set, only these domains (and their subdomains) are permitted.	string[]	—

Response

The function returns the image binary data with appropriate headers:

Response headers

// Response headers
{
'Content-Type': 'image/jpeg',  // Original content type
'Cache-Control': 'public, max-age=3600'
}

Error handling

The function returns appropriate error responses:

400: Missing URL parameter or URL failed validation (blocked domain, private IP, etc.)
500: Failed to fetch the image
Original status: If the external server returns an error, that status is forwarded

Error response

{
"error": "Failed to fetch image: 404"
}

Use with useOgData hook

The useOgData hook automatically uses the proxy for external images:

Component.tsx

import { useOgData } from '@once-ui-system/core';

function MyComponent() {
const { ogData, loading } = useOgData(
  'https://example.com',
  '/api/og/fetch',
  '/api/og/proxy'  // Custom proxy endpoint
);

return (
  <div>
    {ogData?.image && (
      <img src={ogData.image} alt={ogData.title} />
    )}
  </div>
);
}

Security considerations

Both handleOGFetch and handleOGProxy validate URLs server-side before fetching:

Only HTTPS URLs are allowed
Private IPs, localhost, and link-local addresses are blocked
Embedded credentials in URLs are rejected
Redirect chains are followed and re-validated (up to 3 redirects)

Use allowedDomains to restrict fetching to trusted hosts in production:

Domain allowlist

return handleOGProxy(request, {
allowedDomains: ['example.com', 'cdn.example.com'],
});

Consider also adding rate limiting at the route level to prevent abuse.