Sunbeam Passport client

Drop Sunbeam Passport into an app with OAuth 2.1 + PKCE and a first-party button that looks like it belongs to the handoff.

pnpm add @sunbeam-za/passport

Register the app as a public OAuth client, including its exact callback URL.

Server apps: two small routes

createPassportServer() owns the short-lived HttpOnly PKCE transaction, state validation, one-time cleanup, and safe callback headers. Your app only chooses where its finished session lives:

// lib/passport.ts
import { createPassportServer } from "@sunbeam-za/passport/server";

export const passport = createPassportServer({
  clientId: process.env.SUNBEAM_CLIENT_ID!,
  redirectUri: "https://app.example.com/auth/callback",
});

// auth/start
import { passport } from "./lib/passport";

export const GET = () => passport.start();

// auth/callback
import { passport } from "./lib/passport";

export const GET = (request: Request) =>
  passport.complete(request, {
    async onSuccess(tokens) {
      await saveSession(tokens); // Prefer encrypted, HttpOnly cookies.
      return Response.redirect(new URL("/", request.url));
    },
    onError(error) {
      return Response.redirect(
        new URL(`/sign-in?error=${encodeURIComponent(error.code)}`, request.url),
      );
    },
  });

Use the branded link anywhere in the app. It works without client-side JavaScript:

import { PassportLink } from "@sunbeam-za/passport/react";
import "@sunbeam-za/passport/style.css";

<PassportLink href="/auth/start" />

Browser apps

For a browser-owned flow, add the client and button:

"use client";

import { createPassportClient } from "@sunbeam-za/passport";
import { PassportButton } from "@sunbeam-za/passport/react";
import "@sunbeam-za/passport/style.css";

const passport = createPassportClient({
  clientId: process.env.NEXT_PUBLIC_SUNBEAM_CLIENT_ID!,
  redirectUri: process.env.NEXT_PUBLIC_SUNBEAM_REDIRECT_URI!,
});

export function SignIn() {
  return <PassportButton client={passport} />;
}

authorize() creates a fresh PKCE verifier and state, keeps the short-lived transaction in sessionStorage, then sends the browser to Passport. On the callback page:

const tokens = await passport.handleCallback();
const profile = await passport.userInfo(tokens.access_token);

The client returns tokens but deliberately does not persist them. Put them in the session boundary that fits your application; server-rendered apps should prefer secure, HttpOnly cookies.

For browser callbacks, set a Referrer-Policy: no-referrer response header and avoid third-party resources on the callback page. handleCallback() validates the callback route and transaction state, consumes state once, and removes OAuth parameters from browser history before exchanging the code.

Buttons

Every control uses the canonical “Continue with [Sunbeam mark] Passport” prompt. Three appearances and sizes are included:

<PassportButton client={passport} />
<PassportButton client={passport} appearance="light" />
<PassportButton client={passport} appearance="sun" size="large" />

If your server owns the OAuth transaction, use the same branded surface with its prepared authorization URL:

import { PassportLink } from "@sunbeam-za/passport/react";

<PassportLink href={authorizationUrl} />

PassportButton and PassportLink accept normal button or anchor props, respect prefers-reduced-motion, and can be extended with className. Custom children replace the standard prompt while retaining the Passport mark. The following custom properties are available:

.my-passport-button {
  --sb-passport-bg: #111009;
  --sb-passport-ink: #f7f1de;
  --sb-passport-border: rgba(255, 236, 190, 0.2);
  --sb-passport-hover: #17140c;
}

Low-level server control

If a framework needs to own its transaction storage, use the same primitives underneath createPassportServer():

const passport = createPassportClient({ clientId, redirectUri });
const request = await passport.authorizationRequest();

// Save request.state and request.codeVerifier in a short-lived server session.
redirect(request.url);

At the callback, compare the returned state to the saved state before calling:

const tokens = await passport.exchangeCode({
  code,
  codeVerifier: savedCodeVerifier,
});

The default Passport gateway is https://passport.sunbeamdream.com. Set passportUrl for local development or preview deployments.

Core API

• authorizationRequest() creates a URL, state, and PKCE verifier for a server-owned flow.
• createPassportServer() wraps that flow in a private transaction cookie and gives server apps start() and complete() route primitives.
• authorize() starts a browser-owned flow.
• handleCallback() validates browser state and exchanges the code.
• exchangeCode() exchanges a code in a server-owned flow.
• refresh() rotates a refresh token.
• userInfo() reads the approved OIDC profile.

The default scopes are openid email profile. Pass scopes when creating the client or starting an authorization to request less.