@seda-protocol/auth-core

Shared seda-auth domain types, API contracts, and Privy authentication helpers for React applications.

Entry points

• @seda-protocol/auth-core exports domain types and service API contracts.
• @seda-protocol/auth-core/client exports the consumer HTTP client.
• @seda-protocol/auth-core/auth-ui exports reusable Privy authentication helpers for React applications.

Install the peer dependencies required by the entry points your application uses:

• @seda-protocol/auth-core: effect and @effect/platform.
• @seda-protocol/auth-core/client: effect.
• @seda-protocol/auth-core/auth-ui: @privy-io/react-auth, react and react-dom (peer dependency of @privy-io/react-auth).

Client

@seda-protocol/auth-core/client provides:

• makeSedaAuthClient for exchanging Privy identity tokens for SEDA access or admin tokens;
• verifySedaAccessToken for Effect-based local access-token verification;
• verifyAdminAccessToken for Effect-based local admin-token verification;
• requireSedaAuth for extracting and verifying a Bearer token from an HTTP request; and
• typed exchange and verification errors.

Consumer APIs verify SEDA JWTs locally with the configured issuer, expected app, and SEDA-AUTH JWKS URL. They do not need to call SEDA-AUTH for every request.

Auth UI

import {
	SedaAuthPrivyProvider,
	useSedaAuth,
} from "@seda-protocol/auth-core/auth-ui";
import { availableSedaApps, makeSedaAuthClient } from "@seda-protocol/auth-core/client";

const authClient = makeSedaAuthClient({ baseUrl: "https://auth.example.com" });

const exchangeToken = (privyIdentityToken: string) =>
	authClient.exchangeIdentityToken({
		app: availableSedaApps.FAST_USER_DASHBOARD,
		privyIdentityToken,
	});

const loadMe = (accessToken: string) => {
	return getMe(accessToken);
};

const classifyError = (error: unknown) => {
	if (error instanceof ApiError && error.status === 401) {
		return "login-again" as const;
	}

	if (error instanceof ApiError && error.status === 403) {
		return "denied" as const;
	}

	return "error" as const;
};

function Dashboard() {
	const session = useSedaAuth({
		loadMe,
		classifyError,
		exchangeToken,
	});

	switch (session.status) {
		case "loading":
			return <p>Loading...</p>;

		case "unauthenticated":
			return <button onClick={session.login}>Log in</button>;

		case "login-again":
			return <button onClick={session.login}>Log in again</button>;

		case "denied":
			return (
				<>
					<p>You do not have access to this application.</p>
					<button onClick={session.logout}>Log out</button>
				</>
			);

		case "error":
			return <p>Unable to load your session.</p>;

		case "authorized":
			return (
				<>
					<p>{session.me.user.email}</p>
					<button onClick={session.logout}>Log out</button>
				</>
			);
	}
}

export function App() {
	return (
		<SedaAuthPrivyProvider appId={privyAppId}>
			<Dashboard />
		</SedaAuthPrivyProvider>
	);
}

For local development without Privy, render SedaAuthDevProvider instead of SedaAuthPrivyProvider and point it at a SEDA-AUTH service running with SEDA_AUTH_DEV_IDENTITIES=true:

import { SedaAuthDevProvider, useSedaAuth } from "@seda-protocol/auth-core/auth-ui";

export function App() {
	return (
		<SedaAuthDevProvider authBaseUrl="http://localhost:3000">
			<Dashboard />
		</SedaAuthDevProvider>
	);
}

useSedaAuth, exchangeToken, and loadMe stay the same. Entering an email that is not already in the local database creates that user. The dev provider stores the local identity token in localStorage so the session can refresh. The Privy provider does not.

useSedaAuth exposes authentication actions and a discriminated session state with the following statuses:

• loading
• unauthenticated
• authorized
• denied
• login-again
• error

Consumers provide exchangeToken, which exchanges the current Privy identity token for a short-lived SEDA JWT, loadMe, which loads the authenticated SEDA user, and classifyError, which maps application-specific request errors to session states.