Plaid Link — Frontend Systems Design

Problem Framing

Plaid Link is a client-side widget that a customer (an app that wants bank data) embeds. The end user's bank credentials never touch the customer's page or the customer's servers. That credential isolation is the entire product.

Rendering choice: a single-page app rendered inside an iframe modal, not a multi-page app. MPA page reloads would destroy in-memory flow state and look broken inside a modal. The one twist: the OAuth step forces a real full-page redirect out to the bank and back, so the SPA must rehydrate cleanly after a redirect. That survival requirement is the same thing as idempotency and is the heart of the problem.

Non-goals (state deliberately): SEO does not matter (widget is not indexed content), and initial load perf is not a focus (small surface). Calling these out shows deliberate scoping.

RRequirements

Functional clarifying questions

• Auth model. Modern banks use OAuth redirect — the user authenticates on the bank's own page and we never see credentials. Legacy is credential-based (user types bank username/password into the widget). Confirm we design the OAuth flow, note we would gracefully support both.
• Do we host the bank auth page (no — in OAuth the bank does) or hand off via redirect/popup?
• New link vs update/reconnect mode (re-auth an existing item).
• Institution search and selection in-widget; roughly how many institutions.

Non-functional clarifying questions

• Accessibility. A modal needs a focus trap, ESC to close, ARIA roles, screen reader support. Call this out early.
• Security and isolation (iframe, postMessage origin checks, CSRF state). DEEP DIVE Flag that you will return here.
• Devices. Mobile changes redirect vs popup — popups are unreliable on mobile, so OAuth uses full redirect there.
• i18n and per-customer theming/branding.
• Resilience. Network drops mid-flow, back button, refresh, double-clicks.

The questions above resolve to the committed scope below. State this out loud — "so I'm building this, not that" — before moving to architecture.

AArchitecture

• Host page loads a small JS SDK (a script the customer includes).
• SDK exposes create / open and injects an iframe pointing at the Widget SPA, served from our own origin. The iframe is what enforces isolation — the customer's page cannot read inside it.
• postMessage bridge between iframe and host for lifecycle events (ready, success, exit, event).
• Our backend talks to the bank's OAuth server.
• Customer backend creates the link_token and later exchanges the public_token. It does not talk to the widget directly — it talks to our backend.

Diagram A — Architecture & trust boundaries

flowchart TB
    subgraph Browser["User Browser (one tab)"]
        Host["Host Page<br/>app.customer.com"]
        SDK["JS SDK loader"]
        subgraph Iframe["iframe — Widget SPA<br/>link.provider.com"]
            Widget["Widget UI + FlowState"]
        end
        Host -->|includes| SDK
        SDK -->|injects| Iframe
        Iframe <-->|"postMessage<br/>(origin-checked)"| Host
    end
    OurBackend["Provider (Plaid) Backend"]
    CustBackend["Customer Backend"]
    Bank["Bank OAuth Server"]
    Widget -->|"HTTPS / fetch"| OurBackend
    Host -->|"public_token via onSuccess"| CustBackend
    CustBackend -->|"server-to-server exchange"| OurBackend
    OurBackend <-->|"OAuth"| Bank
    Widget -.->|"full-page redirect"| Bank
    classDef secret fill:#ffe0e0,stroke:#c00;
    classDef safe fill:#e0f0ff,stroke:#06c;
    class OurBackend,CustBackend,Bank secret;
    class Host,SDK,Widget safe;

DData Model / Core Entities

FlowState (enum) — the anti-optimistic-advance mechanism

Corrected order: CONSENT comes first — the user consents to the data-sharing terms before picking a bank. There are two consent moments: (1) up-front consent to Plaid's data use, in-widget, and (2) authorization at the bank during OAuth, on the bank's page. Model the first as CONSENT; the second is part of the OAuth leg itself.

CONSENT → SELECT_INSTITUTION → OAUTH_REDIRECT → OAUTH_RETURN → ACCOUNT_SELECT → SUCCESS, plus ERROR. Belongs to the widget, mirrored on the server — the server copy is authoritative.

Diagram B — FlowState machine (corrected order)

stateDiagram-v2
    [*] --> CONSENT
    CONSENT --> SELECT_INSTITUTION: agrees to data-use terms
    SELECT_INSTITUTION --> OAUTH_REDIRECT: bank chosen
    OAUTH_REDIRECT --> OAUTH_RETURN: user authorizes at bank<br/>(bank-side consent + account grant)
    OAUTH_RETURN --> ACCOUNT_SELECT: server confirms grant
    ACCOUNT_SELECT --> SUCCESS: selection persisted,<br/>public_token issued
    SUCCESS --> [*]
    CONSENT --> ERROR
    SELECT_INSTITUTION --> ERROR
    OAUTH_REDIRECT --> ERROR: state mismatch / expired
    OAUTH_RETURN --> ERROR
    ACCOUNT_SELECT --> ERROR
    ERROR --> [*]
    note right of OAUTH_RETURN
        SPA reloaded from scratch here.
        Read oauth_state_id from URL,
        link_token from sessionStorage,
        then GET /link/session/:id.
        Server reports the real step.
    end note

Other entities

• Institution: id, name, logo, oauth_supported, products.
• Tokens: link_token (init, short-lived), public_token (result, short-lived, exchanged server-side). access_token is server-only and does not belong in any frontend entity.

IInterfaces

SDK surface for the customer

• PlaidLink.create({ token: link_token, onSuccess, onExit, onEvent })
• handler.open() / handler.exit()
• onSuccess(public_token, metadata), onExit(error, metadata), onEvent(eventName, metadata)

iframe ↔ host over postMessage

Every message validated against an origin allowlist, both directions. postMessage is browser-to-browser (two frames in one tab), not browser-to-backend.

Backend REST (idempotent by design)

Put an Idempotency-Key (client-generated per action) on the mutating POSTs so retries and double-clicks collapse to one effect. The server dedupes.

Diagram C — Token flow & the server-to-server exchange

sequenceDiagram
    participant U as User Browser
    participant W as Widget (iframe)
    participant CB as Customer Backend
    participant PB as Provider Backend
    participant Bank as Bank
    CB->>PB: create link_token (with secret creds)
    PB-->>CB: link_token (short-lived)
    CB-->>U: link_token
    U->>W: open widget with link_token
    W->>Bank: OAuth redirect (with oauth_state_id)
    Bank-->>W: callback (echoes oauth_state_id)
    W->>PB: finalize (oauth_state_id validated)
    PB-->>W: session ok, public_token
    W-->>U: onSuccess(public_token)
    Note over U,CB: public_token sent up to customer backend
    U->>CB: public_token
    rect rgb(255,224,224)
    CB->>PB: exchange public_token + secret creds (server-to-server)
    PB-->>CB: access_token + item_id
    end
    Note over CB: access_token stored server-side,<br/>NEVER returned to browser
    CB-->>U: "linked, ok"

OOptimizations / Deep Dives

1. OAuth redirect and rehydration CORE PROBLEM

When the user goes to the bank and comes back, the SPA reloads from scratch (amnesia). The problem on return: which session does this browser belong to? Two independent recovery paths, so one failing doesn't kill you:

1. sessionStorage breadcrumb. Before redirecting, persist the session handle (link_token). Works when the redirect returns in the same tab.
2. The oauth_state_id in the callback URL. The bank echoes it back; the server can look up which session issued it. Works even in a new tab with empty sessionStorage.

The client never validates the state — it is a courier, not a judge. A client-side "state I sent vs state I got back" check proves nothing (an attacker controls the client). The server generated the state, stored it in the LinkSession, and does the only comparison that counts. The client's jobs: before redirect, save the session handle and navigate to the bank URL the server built (state already inside); on return, read state + code from the URL and forward them to the server. Then GET /link/session/:id and render whatever current_step the server reports. Never trust a client flag that says "I was on step 4."

The return leg: one guarded write, one safe read

1. SPA reloads with amnesia. Read oauth_state_id from the URL, session handle from sessionStorage.
2. POST /oauth/callback with oauth_state_id + auth code. Server validates state (CSRF), checks single-use (replay), exchanges with the bank, burns the state, advances the session. The one write.
3. GET /link/session/:id to read the now-current step and render. Safe to repeat.

Why both? They answer different questions. The GET answers "where am I, what should I render" — read-only, refresh five times, nothing breaks. The POST answers "actually finalize this grant, exactly once" — a real state change with an outside effect (token exchange with the bank), guarded by the single-use nonce and the Idempotency-Key. Burning a nonce is a side effect, and side effects do not belong on a GET (a refresh or prefetch would blow up the session).

Diagram D — OAuth return: guarded POST vs safe GET

sequenceDiagram
    participant Bank
    participant U as User Browser (SPA)
    participant PB as Link Server
    Note over Bank,U: OAuth done, bank redirects back
    Bank-->>U: redirect to redirect_uri?state=oauth_state_id&code=auth_code
    Note over U: SPA reloaded, has amnesia.<br/>Read oauth_state_id from URL,<br/>session handle from sessionStorage
    rect rgb(255,224,224)
    Note over U,PB: WRITE — finalize exactly once
    U->>PB: POST /link/oauth/callback<br/>(oauth_state_id, code, Idempotency-Key)
    PB->>PB: state issued for live session? not yet used?
    alt valid + unused
        PB->>Bank: exchange auth_code (server-to-server)
        Bank-->>PB: grant
        PB->>PB: burn oauth_state_id, advance step
        PB-->>U: ok, new step
    else forged / replayed
        PB-->>U: reject
    end
    end
    rect rgb(224,240,255)
    Note over U,PB: READ — safe to repeat on refresh
    U->>PB: GET /link/session/:id
    PB-->>U: current_step (authoritative) -> render
    end

2. Not optimistically advancing

The UI shows a step only after the server confirms the transition. Do not render "success" until the token exchange / session finalize returns ok. Model it as a state machine where illegal transitions are rejected, so a stale message or duplicated redirect cannot jump forward.

3. Idempotency

• Reuse of oauth_state_id is rejected — single-use, like a nonce.
• Mutating calls carry an Idempotency-Key so a refresh or double redirect does not create two links. The server dedupes.
• OAuth retry: mint a fresh oauth_state_id and overwrite the session's field. Validation rule "incoming state must match the session's current active state AND be unused" means the old value is invalidated for free. Known race: if the first attempt's callback is in flight when the user retries, the legit first callback gets rejected — rare and acceptable, the user completes the retry. Stricter option: keep a short list of issued-but-unused states, burn each on use. Invariant either way: at most one link is created, because whichever callback finalizes first advances the FlowState, and any other callback finds the session already advanced and is rejected or deduped.

4. Security THREE SEPARATE BOUNDARIES

• Boundary 1 — iframe isolation. Widget iframe served from our origin (link.plaid.com), host page on customer origin (app.customer.com). Same-origin policy blocks the frames from reading each other's JS/DOM — that block is what stops the customer's page from scraping credentials.
• Boundary 2 — postMessage channel. Sending: name the exact target origin, never '*' — targetWindow.postMessage(data, 'https://app.customer.com'). Receiving: check event.origin against the allowlist before trusting any message; drop silently otherwise. Origin allowlist trust chain: customer pre-registers domains at onboarding → that config gates link_token creation → the link_token seeds the per-session allowlist the iframe enforces. Origin = scheme + host + port; exact string match, never substring includes (naive includes('customer.com') passes evil-customer.com.attacker.com).
• Boundary 3 — CSRF on the OAuth redirect. Server generates a random, unguessable, session-bound oauth_state_id before redirecting; bank echoes it back; server checks it matches a value it issued for a live session and is unused. Forged callbacks fail the match; replayed callbacks fail single-use.

Diagram E — Security surfaces (postMessage origin check + CSRF state)

sequenceDiagram
    participant Evil as Malicious Page
    participant Host as Host Page
    participant W as Widget (iframe)
    participant PB as Provider Backend
    participant Bank as Bank
    Note over Host,W: Surface 1 — postMessage channel
    W->>Host: postMessage(SUCCESS, targetOrigin=app.customer.com)
    Evil-->>W: postMessage(fake OPEN)
    W->>W: check event.origin against allowlist
    Note right of W: origin not allowed -> drop silently
    Note over W,Bank: Surface 2 — OAuth redirect / CSRF
    PB->>PB: generate random oauth_state_id (session-bound, single-use)
    W->>Bank: authorize?state=oauth_state_id
    Bank-->>W: callback?state=oauth_state_id
    W->>PB: /oauth/callback (state)
    PB->>PB: state issued for live session? not used yet?
    alt valid + unused
        PB-->>W: finalize ok (mark state used)
    else forged / replayed
        PB-->>W: reject
    end

5. Edge cases & resilience

6. Abuse prevention

• Rate limiting. Per link_token, per session, per IP, and per customer: cap session creations, institution searches, and OAuth attempts. A single session should never need more than a handful of finalize attempts — throttle and then kill the session.
• Device signals. Bind the session loosely to device fingerprint / user agent at creation; a finalize arriving from a wildly different device or geo than the session start is a signal to step up or reject. (Loose binding — IP can legitimately change across the bank redirect, especially on mobile.)
• Anomaly detection. Server-side monitoring on nonce failures: spikes in state-mismatch rejections (someone probing forged callbacks), replay attempts, or enumeration of session ids. Alert and auto-block origins/customers showing abuse patterns. Failed event.origin checks in the widget can be beaconed as telemetry.
• Blast-radius containment (already in the design). Everything the client holds is short-lived and scoped, so stolen values age out fast; the allowlist stops embedding on unauthorized origins.

Further Notes — Confusions Resolved