White Label Proxy Server

Documentation Index

Fetch the complete documentation index at: https://docs.y.uno/llms.txt

Use this file to discover all available pages before exploring further.

​

Why this server exists

​

How it works

┌──────────────────┐      ┌──────────────────────┐      ┌────────────────────┐
│  Partner page    │────▶ │  white-label-proxy   │────▶ │ Yuno upstreams     │
│  (browser)       │      │  (Express :9090)     │      │  - sdk-web.*.y.uno │
│                  │ ◀────│                      │ ◀────│  - sdk-3ds.*.y.uno │
│ <script src=     │      │  Routes by path:     │      │  - sdk-web-card.*  │
│  localhost:9090/ │      │   /v1/*  → BACKEND   │      │  - api[-env].y.uno │
│  v1.7/main.js>   │      │   /v<n>/pages → CARD │      │                    │
└──────────────────┘      │   /challenge → 3DS   │      └────────────────────┘
                          │   else       → SDK   │
                          └──────────────────────┘

1. The browser only ever talks to the proxy origin. No *.y.uno request originates from the page itself — otherwise the SDK is not really being tested against a foreign host.
2. All upstream domains are reachable from the proxy. SDK assets, the card-form micro-app, the 3DS micro-app, the REST API, and the WebSocket service are all separate hostnames that must each be configurable.
3. CORS is owned by the proxy, not the upstream. Upstream CORS would respond with api.y.uno origins; the proxy strips those and writes its own, echoing the caller.

​

Architecture

• express — routing and middleware for HTTP.
• node-fetch — outbound HTTP to upstreams, for streaming bodies and header control.
• http-proxy — WebSocket upgrades, because Express middleware never sees Upgrade requests.

​

Request lifecycle

1. CORS middleware runs first. It echoes the caller’s Origin, handles OPTIONS preflight, and sets Access-Control-Allow-Credentials: true. The proxy is the CORS authority.
2. Local routes match before anything else: /, /static/*, /whitelabel-info. These never touch an upstream.
3. Backend pass-through matches /v1/* and /v2/* (the Yuno REST surface used by the SDK) and forwards via node-fetch to BACKEND_URL. Hop-by-hop headers are stripped; access-control-* headers from the upstream are dropped so they cannot override the proxy’s own CORS.
4. SDK asset catch-all matches every remaining GET/HEAD. A small dispatcher picks the right upstream based on path:
   • 3DS micro-app paths (/challenge.html, /redirect.html, /session-id.html, and /assets/(challenge|redirect|session-id|validate-url)*) → SDK_3DS_UPSTREAM.
   • Card micro-app paths (/v<semver>/pages/*, /v<semver>/assets/*) → SDK_CARD_UPSTREAM.
   • Everything else → SDK_UPSTREAM.
5. WebSocket upgrades are handled on the underlying http.Server, not Express. /checkout-websocket-notification-ms/ws/* → BACKEND_WS_URL; everything else follows the same SDK / card / 3DS split as HTTP.

​

Version normalization

• Partner pages may hardcode a version that the upstream no longer publishes.
• The “current” version drifts over time.

​

SDK_MAIN_JS — pinning the SDK version

1. Template injection. The proxy serves pages/index.html with the literal __SDK_MAIN_JS__ placeholder replaced by this path. A partner page can write <script src="__SDK_MAIN_JS__"> and get e.g. /v1.9.0/main.js.
2. Version normalization target. The proxy parses the /v<x>/ segment out of SDK_MAIN_JS and rewrites any incoming /v<other>/main.js (and adjacent /v<other>/*.js, /v<other>/*.css) request to that same version. So if SDK_MAIN_JS=/v1.9.0/main.js, a request for /v1.5.0/main.js is silently fetched as /v1.9.0/main.js from SDK_UPSTREAM.

​

Resolution order at boot

1. process.env.SDK_MAIN_JS                          (if set, used as-is, no upstream call)
2. <SDK_UPSTREAM>/versions.json → latest.version    (auto-detect, 5s timeout)
3. /v1.7/main.js                                    (hard-coded fallback)

​

Format

SDK_MAIN_JS=/v<semver>/main.js

​

Common use cases

SDK_MAIN_JS=/v1.9.0/main.js npm start

SDK_MAIN_JS=/v1.9.0/main.js npm start

SDK_MAIN_JS=/v1.7.4/main.js npm start

​

Gotchas

• Card and 3DS upstreams are not affected. SDK_MAIN_JS only pins the main SDK bundle’s version. The card micro-app (/v<x>/pages/*) and the 3DS micro-app keep their own version segments.
• Setting it disables auto-detection. If a newer SDK version is published upstream, you keep loading the pinned version until you change the env var and restart.
• Restart required. The value is read once at boot. No hot reload.
• Mismatch with upstream is silent. Pinning to a version the upstream does not publish results in a 404 for /v<your-pin>/main.js. Check the network tab to spot it.
• No query strings or hash. Path only.

​

Building a server like this

​

1. Bootstrap the project

mkdir my-proxy && cd my-proxy
npm init -y
npm install express http-proxy node-fetch@2 dotenv

​

2. Define your upstream map

​

3. Set up CORS as the proxy’s responsibility

app.use((req, res, next) => {
  const origin = req.headers.origin
  if (origin) {
    res.set('access-control-allow-origin', origin)
    res.set('access-control-allow-credentials', 'true')
    res.set('vary', 'origin')
  } else {
    res.set('access-control-allow-origin', '*')
  }
  res.set('access-control-allow-methods', req.headers['access-control-request-method'] || 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS')
  res.set('access-control-allow-headers', req.headers['access-control-request-headers'] || '*')
  res.set('access-control-expose-headers', '*')
  res.set('access-control-max-age', '86400')
  if (req.method === 'OPTIONS') return res.status(204).end()
  next()
})

​

4. Filter hop-by-hop headers in both directions

const HOP_BY_HOP = new Set([
  'host', 'connection', 'keep-alive',
  'proxy-authenticate', 'proxy-authorization',
  'te', 'trailer', 'transfer-encoding', 'upgrade',
  'content-length', // node-fetch sets this itself
])

​

5. Forward the API surface

app.all('/v1/*', forwardToBackend)
app.all('/v2/*', forwardToBackend)

async function forwardToBackend(req, res) {
  const targetUrl = `${BACKEND_URL}${req.originalUrl}`
  const headers = pickRequestHeaders(req) // filters HOP_BY_HOP
  const init = { method: req.method, headers }
  if (req.method !== 'GET' && req.method !== 'HEAD') {
    // express.json() consumed the original body; re-serialize it.
    init.body = req.body && Object.keys(req.body).length ? JSON.stringify(req.body) : undefined
    if (init.body && !headers['content-type']) headers['content-type'] = 'application/json'
  }
  const upstream = await fetch(targetUrl, init)
  res.status(upstream.status)
  for (const [k, v] of upstream.headers.entries()) {
    const lk = k.toLowerCase()
    if (HOP_BY_HOP.has(lk)) continue
    if (lk.startsWith('access-control-')) continue   // proxy owns CORS
    res.set(k, v)
  }
  res.send(await upstream.text())
}

​

6. Catch-all proxy for SDK assets

app.use((req, res, next) => {
  if (req.method !== 'GET' && req.method !== 'HEAD') return next()
  proxyToUpstream(req, res, next)
})

async function proxyToUpstream(req, res, next) {
  const upstreamBase = pickSdkUpstream(req.path)   // returns one of three URLs
  const targetUrl = `${upstreamBase}${normalizePath(req.originalUrl)}`
  const upstream = await fetch(targetUrl, { redirect: 'follow', headers: { /* accept, user-agent */ } })
  if (upstream.status === 404) return next()
  res.status(upstream.status)
  for (const h of ['content-type', 'cache-control', 'etag', 'last-modified']) {
    const v = upstream.headers.get(h)
    if (v) res.set(h, v)
  }
  upstream.body.pipe(res)   // stream — don't buffer, assets can be big
}

​

7. Handle WebSocket upgrades on the http.Server

const wsProxy = httpProxy.createProxyServer({ changeOrigin: true, ws: true })
const server = app.listen(PORT)
server.on('upgrade', (req, socket, head) => {
  const target = pickWsTarget(req.url)   // BACKEND_WS_URL or SDK_UPSTREAM
  wsProxy.ws(req, socket, head, { target })
})

​

8. Wire up environment variables

• SDK services follow <service>[.<env>].y.uno — sdk-web.y.uno, sdk-web.staging.y.uno, sdk-web.dev.y.uno.
• API surface uses api[-<env>].y.uno — api.y.uno, api-staging.y.uno, api-dev.y.uno. Note the hyphen, not a dot.
• The WebSocket service has no api- prefix — <env>.y.uno directly (y.uno, staging.y.uno, dev.y.uno).

​

9. Ship a minimal landing page

​

Pitfalls and edge cases

• Route order matters. The SDK catch-all is registered last. Anything you app.use after it never runs.
• CORS authority must be the proxy. Letting upstream access-control-* headers through means credentialed cross-origin requests randomly fail when the upstream’s allow-list does not include localhost.
• Hop-by-hop headers are bidirectional. Strip them on both legs. content-length is the one that bites.
• Body consumption is a one-shot. Once express.json() parses a request, the underlying stream is drained. Re-serialize from req.body if you need to forward a POST.
• Streaming, not buffering, for assets. upstream.body.pipe(res) keeps memory flat even for multi-MB bundles.
• Version normalization is SDK_UPSTREAM-only. Card and 3DS micro-apps have their own version segments — rewriting them breaks the upstream URL.
• WebSocket auth is whatever headers http-proxy sees. Do not strip cookie or authorization from WS upgrades.
• .env is gitignored. Always keep .env.example in sync — it is the spec for anyone cloning the repo.

​

Verification checklist

1. Network tab — no requests to any *.y.uno host originate from the merchant page. All traffic is to the proxy origin.
2. window.SdkPayments is defined; window.Yuno is either undefined or a legacy alias.
3. sdk-payments-ready event fires on document after the SDK boots.
4. No yuno-* DOM tokens in the rendered output, except for the trust-mark allow-list (yuno-badge, secure-by-yuno, yuno-typography-provider, yuno-c2p, yuno-redirect, yuno-debug, data-yuno-session-id).

​

Reference implementation

​

See also

• White Label (Web SDK) — the SDK-side overrides this harness verifies.
• yuno-payments/yuno-sdk-web/tree/main/white-label-proxy-server — full source.
• RFC 7230 §6.1 — Connection-specific headers
• http-proxy WebSocket docs