@odla-ai/auth-clerk

⚠️ Early access — pre-1.0. Agents work from bounded runbooks; humans approve credentials, production changes, releases, and merges. APIs and exact package availability can change. Review the documented guarantees and limitations; this software is MIT-licensed and provided without warranty.

Clerk end-user auth as a themed, config-driven odla capability — not a bag of components you re-wire per app.

It wraps vanilla @clerk/clerk-js (no @clerk/clerk-react), so it runs on Preact via preact/compat exactly as cleanly as on React 18/19. Authored against the react API using only the compat-safe subset (hooks + plain JSX); the same build runs on both.

What's in the box

• <ClerkGate> — provider (replaces <ClerkProvider>). Loads Clerk once, provides it via context.
• useClerkAuth() — { isLoaded, isSignedIn, user, session, getToken, signOut }, reactive via useSyncExternalStore.
• <SignedIn> / <SignedOut> — conditional render (blank until loaded, so no signed-out flash).
• <SignIn> / <UserButton> — mount Clerk's widgets imperatively; write them like components.
• clerkAppearanceFromTokens() — maps odla-ui --ui-* design tokens into a Clerk appearance, including accent/on-accent, both surfaces, text/input, border/ring, status colors, radius, font, and card shadow. It supplies both current and legacy Clerk variable aliases so every widget matches the theme.
• clerkIntegration — the integration descriptor (settings, secrets, data-sync contract, provisioning steps) as data.

Usage

import { ClerkGate, SignedIn, SignedOut, useClerkAuth, SignIn, clerkAppearanceFromTokens } from "@odla-ai/auth-clerk";

// The host app loads @odla-ai/ui tokens (for theming) and supplies the
// publishable key (e.g. fetched from /registry/config).
<ClerkGate publishableKey={key} afterSignOutUrl="/" appearance={clerkAppearanceFromTokens()}>
  <SignedOut><SignIn routing="hash" /></SignedOut>
  <SignedIn>{/* app */}</SignedIn>
</ClerkGate>

Under Preact, alias react/react-dom → preact/compat in your bundler (see the dashboard's vite.config.ts).

The capability, not just the UI

Turning Clerk "on" for an app is a registry setting (auth[env].publishableKey), not a code flag — this package renders against that config. What settings and secrets it needs, what the CLI provisions, and what data syncs to Clerk ($users: id, email, userType, allowedIds) all live in clerkIntegration.

Dependency advisory boundary

As of 2026-07-10, a production npm audit reports one unresolved moderate advisory as 12 package nodes: @clerk/clerk-js → Clerk's Solana wallet adapters → @solana/web3.js → jayson → uuid (GHSA-w5hq-g745-h8pq). The installed Clerk 5 line and current Clerk 6.25.2 both include that wallet stack; current @solana/web3.js 1.98.4 still uses jayson 4.3.0, which declares uuid ^8.3.2. There is no compatible clean upstream upgrade today.

The advisory affects uuid v3/v5/v6 when a caller supplies a buffer. jayson 4.3.0 imports and calls uuid.v4() without a buffer. odla's capability only loads Clerk's normal sign-in/user widgets, session JWT access, and sign-out; its provisioning does not enable or initialize a Solana wallet strategy. We found no executable path to the affected functions in that configuration. That is a reachability assessment, not a remediation or proof of safety. Reassess before enabling Clerk Web3 wallet sign-in.

Do not force uuid 11 through an npm override: it is outside jayson's declared range, can break consumers, and a root override would not protect downstream installs of this package. odla CI runs npm run check:audit, allows only this exact moderate advisory chain, and fails on any other moderate, high, or critical production advisory while we track an upstream-compatible fix.

MIT licensed. Early access — use at your own risk.