@starci/hfs 4.0.7 → 4.0.9

package/templates/fe/{skeleton/apps/__app__ → skeleton-lite/apps/web}/src/app/globals.css

@@ -2,5 +2,5 @@
 @import "@heroui/styles/css";
 @import "@starci/grammar/common.css";
 
-/* The grammar's renderers spell their layout in Tailwind utilities inside node_modules, which Tailwind never scans by default. */
+/* Grammar's renderers contain Tailwind utilities outside the app source tree. */
 @source "../../../../../node_modules/@starci/grammar/dist";

package/templates/fe/skeleton-lite/apps/web/src/app/health/live/route.ts

@@ -0,0 +1,5 @@
+/** Liveness is answered per request, never prerendered at build time. */
+export const dynamic = "force-dynamic"
+
+/** Process-local liveness; it never touches a dependency. */
+export const GET = (): Response => Response.json({ status: "ok", info: {}, error: {}, details: {} })

package/templates/fe/skeleton-lite/apps/web/src/components/blocks/SignInForm/component.tsx

@@ -0,0 +1,29 @@
+import { Button, Form, Input, SectionHeader, Text } from "@starci/grammar/common"
+
+/** Copy, state and action supplied by the connected sign-in block. */
+export interface SignInFormBaseProps {
+    readonly state: "ready" | "working" | "failed"
+    readonly props: {
+        readonly title: string
+        readonly emailLabel: string
+        readonly passwordLabel: string
+        readonly submitLabel: string
+        readonly failure?: string
+    }
+    readonly on: { readonly submit: (input: FormData) => void }
+}
+
+/** Draws the sign-in form without reading navigation, copy or database state. */
+export const SignInFormBase = (props: SignInFormBaseProps) => (
+    <>
+        <SectionHeader title={props.props.title} level={2} />
+        <Form label={props.props.title} isPending={props.state === "working"} onSubmit={props.on.submit}>
+            <Input id="sign-in-email" name="email" label={props.props.emailLabel} kind="email" isRequired />
+            <Input id="sign-in-password" name="password" label={props.props.passwordLabel} kind="password" isRequired />
+            {props.props.failure === undefined ? null : <Text live="assertive">{props.props.failure}</Text>}
+            <Button type="submit" variant="primary" isPending={props.state === "working"}>
+                {props.props.submitLabel}
+            </Button>
+        </Form>
+    </>
+)

package/templates/fe/skeleton-lite/apps/web/src/components/blocks/SignInForm/index.tsx

@@ -0,0 +1,41 @@
+"use client"
+
+import { useTranslations } from "next-intl"
+import { useState, useTransition } from "react"
+import { writeSignIn } from "@/modules/db/auth/write-sign-in"
+import { navigation } from "@/modules/i18n"
+import { SignInFormBase } from "./component"
+
+type SignInFailure = "refused" | "not-found" | "invalid" | "unavailable"
+
+/** The interactive sign-in form wired to the schema-checked Server Action. */
+export const SignInForm = () => {
+    const router = navigation.useRouter()
+    const t = useTranslations("app.signIn")
+    const [failure, setFailure] = useState<SignInFailure>()
+    const [pending, startTransition] = useTransition()
+    const submit = (input: FormData) => {
+        startTransition(async () => {
+            const outcome = await writeSignIn(input)
+            if (outcome.kind === "ok") {
+                setFailure(undefined)
+                router.refresh()
+                return
+            }
+            setFailure(outcome.kind)
+        })
+    }
+    return (
+        <SignInFormBase
+            state={pending ? "working" : failure === undefined ? "ready" : "failed"}
+            props={{
+                title: t("title"),
+                emailLabel: t("email"),
+                passwordLabel: t("password"),
+                submitLabel: pending ? t("working") : t("submit"),
+                failure: failure === undefined ? undefined : t(failure),
+            }}
+            on={{ submit }}
+        />
+    )
+}

package/templates/fe/skeleton-lite/apps/web/src/components/blocks/SignOutButton/component.tsx

@@ -0,0 +1,17 @@
+import { Button, Text } from "@starci/grammar/common"
+
+/** Copy, state and action supplied by the connected sign-out block. */
+export interface SignOutButtonBaseProps {
+    readonly props: { readonly label: string; readonly pending: boolean; readonly failure?: string }
+    readonly on: { readonly press: () => void }
+}
+
+/** Draws the sign-out control without reading navigation, copy or database state. */
+export const SignOutButtonBase = (props: SignOutButtonBaseProps) => (
+    <>
+        <Button variant="secondary" isPending={props.props.pending} onPress={props.on.press}>
+            {props.props.label}
+        </Button>
+        {props.props.failure === undefined ? null : <Text live="assertive">{props.props.failure}</Text>}
+    </>
+)

package/templates/fe/skeleton-lite/apps/web/src/components/blocks/SignOutButton/index.tsx

@@ -0,0 +1,38 @@
+"use client"
+
+import { useTranslations } from "next-intl"
+import { useState, useTransition } from "react"
+import { writeSignOut } from "@/modules/db/auth/write-sign-out"
+import { navigation } from "@/modules/i18n"
+import { SignOutButtonBase } from "./component"
+
+type SignOutFailure = "refused" | "not-found" | "invalid" | "unavailable"
+
+/** The connected control that ends the current browser session. */
+export const SignOutButton = () => {
+    const router = navigation.useRouter()
+    const t = useTranslations("app.signOut")
+    const [failure, setFailure] = useState<SignOutFailure>()
+    const [pending, startTransition] = useTransition()
+    const signOut = () => {
+        startTransition(async () => {
+            const outcome = await writeSignOut()
+            if (outcome.kind !== "ok") {
+                setFailure(outcome.kind)
+                return
+            }
+            setFailure(undefined)
+            router.refresh()
+        })
+    }
+    return (
+        <SignOutButtonBase
+            props={{
+                label: pending ? t("working") : t("submit"),
+                pending,
+                failure: failure === undefined ? undefined : t(failure),
+            }}
+            on={{ press: signOut }}
+        />
+    )
+}

package/templates/fe/skeleton-lite/apps/web/src/components/composites/ErrorNotice/index.tsx

@@ -0,0 +1,13 @@
+import { Alert } from "@starci/grammar/common"
+
+/** The words of a recoverable failure and its one recovery action. */
+type ErrorNoticeProps = {
+    readonly title: string
+    readonly retryLabel: string
+    readonly onRetry: () => void
+}
+
+/** A recoverable failure shown as an assertive banner. */
+export const ErrorNotice = (props: ErrorNoticeProps) => (
+    <Alert title={props.title} tone="negative" action={{ label: props.retryLabel, onAction: props.onRetry }} />
+)

package/templates/fe/skeleton-lite/apps/web/src/components/composites/GlobalErrorNotice/index.tsx

@@ -0,0 +1,24 @@
+import { Alert, GrammarRoot } from "@starci/grammar/common"
+
+/** The document language, failure words and recovery action. */
+type GlobalErrorNoticeProps = {
+    readonly lang: string
+    readonly title: string
+    readonly retryLabel: string
+    readonly onRetry: () => void
+}
+
+/** The last-resort failure replaces the layout and therefore draws the document itself. */
+export const GlobalErrorNotice = (props: GlobalErrorNoticeProps) => (
+    <html lang={props.lang}>
+        <body>
+            <GrammarRoot>
+                <Alert
+                    title={props.title}
+                    tone="negative"
+                    action={{ label: props.retryLabel, onAction: props.onRetry }}
+                />
+            </GrammarRoot>
+        </body>
+    </html>
+)

package/templates/fe/skeleton-lite/apps/web/src/components/composites/LoadingNotice/index.tsx

@@ -0,0 +1,7 @@
+import { Spinner } from "@starci/grammar/common"
+
+/** The word a wait announces. */
+type LoadingNoticeProps = { readonly label: string }
+
+/** A wait shown as one announced spinner. */
+export const LoadingNotice = (props: LoadingNoticeProps) => <Spinner label={props.label} />

package/templates/fe/skeleton-lite/apps/web/src/components/composites/NotFoundNotice/index.tsx

@@ -0,0 +1,18 @@
+import { Heading, TextAction } from "@starci/grammar/common"
+
+/** The words of a missing page and the way home. */
+type NotFoundNoticeProps = {
+    readonly title: string
+    readonly homeLabel: string
+    readonly homeHref: string
+}
+
+/** A missing page with one destination back to the app's front door. */
+export const NotFoundNotice = (props: NotFoundNoticeProps) => (
+    <>
+        <Heading level={1}>{props.title}</Heading>
+        <TextAction appearance="inline" href={props.homeHref}>
+            {props.homeLabel}
+        </TextAction>
+    </>
+)

package/templates/fe/skeleton-lite/apps/web/src/components/composites/SiteShell/classNames.ts

@@ -0,0 +1,4 @@
+/** The shell's frame: a full-height column on the theme's page colours. */
+export const siteShellClassNames = {
+    frame: "flex min-h-screen flex-col bg-background text-foreground",
+} as const

package/templates/fe/skeleton-lite/apps/web/src/components/composites/SiteShell/index.tsx

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react"
+import { GrammarRoot, PageContainer, TextAction, TopBar, WorkspaceShell } from "@starci/grammar/common"
+import { siteShellClassNames } from "./classNames"
+
+/** What the app chrome hands the shell. */
+type SiteShellProps = {
+    readonly brand: string
+    readonly homeHref: string
+    readonly children: ReactNode
+}
+
+/** The app chrome: grammar boundary, wordmark header and routed body. */
+{{> fe/common/site-shell.tsx.partial}}

package/templates/fe/skeleton-lite/apps/web/src/features/layouts/AppLayout/index.tsx

@@ -0,0 +1,31 @@
+import type { Metadata } from "next"
+import { getTranslations } from "next-intl/server"
+import type { ReactNode } from "react"
+import { SiteShell } from "@/components/composites/SiteShell"
+import { siteUrl } from "@/modules/config"
+import { APP_ROUTES } from "@/modules/routes"
+
+type AppLayoutProps = {
+    readonly locale: string
+    readonly content: ReactNode
+}
+
+/** The document title and absolute metadata base for the requested locale. */
+export const appLayoutMetadata = async (locale: string): Promise<Metadata> => {
+    const t = await getTranslations({ locale, namespace: "app" })
+    return { title: t("title"), metadataBase: new URL(siteUrl()) }
+}
+
+/** The server-resolved app chrome around the routed body. */
+export const AppLayout = async (props: AppLayoutProps) => {
+    const t = await getTranslations("app.shell")
+    return (
+        <html lang={props.locale}>
+            <body>
+                <SiteShell brand={t("brand")} homeHref={APP_ROUTES.home}>
+                    {props.content}
+                </SiteShell>
+            </body>
+        </html>
+    )
+}

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppErrorPage/component.tsx

@@ -0,0 +1,12 @@
+import { ErrorNotice } from "@/components/composites/ErrorNotice"
+
+/** Props for the pure error page. */
+export type AppErrorPageBaseProps = {
+    readonly props: { readonly title: string; readonly retryLabel: string }
+    readonly on: { readonly retry: () => void }
+}
+
+/** Draws the locale segment's recoverable failure. */
+export const AppErrorPageBase = (props: AppErrorPageBaseProps) => (
+    <ErrorNotice title={props.props.title} retryLabel={props.props.retryLabel} onRetry={props.on.retry} />
+)

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppErrorPage/index.tsx

@@ -0,0 +1,10 @@
+import { useTranslations } from "next-intl"
+import { AppErrorPageBase } from "./component"
+
+type AppErrorPageProps = { readonly onRetry: () => void }
+
+/** A render failure with the segment retry. */
+export const AppErrorPage = (props: AppErrorPageProps) => {
+    const t = useTranslations("app.errors.page")
+    return <AppErrorPageBase props={{ title: t("title"), retryLabel: t("retry") }} on={{ retry: props.onRetry }} />
+}

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppGlobalErrorPage/index.tsx

@@ -0,0 +1,15 @@
+import { GlobalErrorNotice } from "@/components/composites/GlobalErrorNotice"
+import { DEFAULT_LOCALE } from "@/modules/i18n"
+import messages from "@/modules/i18n/messages/vi.json"
+
+type AppGlobalErrorPageProps = { readonly onRetry: () => void }
+
+/** The provider-free last-resort boundary reads the default catalog directly. */
+export const AppGlobalErrorPage = (props: AppGlobalErrorPageProps) => (
+    <GlobalErrorNotice
+        lang={DEFAULT_LOCALE}
+        title={messages.app.errors.global.title}
+        retryLabel={messages.app.errors.global.retry}
+        onRetry={props.onRetry}
+    />
+)

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/component.tsx

@@ -0,0 +1,14 @@
+import { Heading, Text } from "@starci/grammar/common"
+
+/** Props for the signed-in home page. */
+export type AppHomePageBaseProps = {
+    readonly props: { readonly title: string; readonly principal: string }
+}
+
+/** Draws the signed-in front door. */
+export const AppHomePageBase = (props: AppHomePageBaseProps) => (
+    <>
+        <Heading level={1}>{props.props.title}</Heading>
+        <Text>{props.props.principal}</Text>
+    </>
+)

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/index.tsx

@@ -0,0 +1,30 @@
+import type { Metadata } from "next"
+import { getTranslations } from "next-intl/server"
+import { SignInForm } from "@/components/blocks/SignInForm"
+import { SignOutButton } from "@/components/blocks/SignOutButton"
+import { readSession } from "@/modules/db"
+import { AppHomePageBase } from "./component"
+
+/** The document title of the home page. */
+export const appHomeMetadata = async (): Promise<Metadata> => {
+    const t = await getTranslations("app.home")
+    return { title: t("title") }
+}
+
+/** The front door: sign-in for an anonymous request, otherwise the verified principal. */
+export const AppHomePage = async () => {
+    const session = await readSession()
+    if (session.kind !== "ok") return <SignInForm />
+    const t = await getTranslations("app.home")
+    return (
+        <>
+            <AppHomePageBase
+                props={{
+                    title: t("title"),
+                    principal: session.value.email ?? t("signedIn"),
+                }}
+            />
+            <SignOutButton />
+        </>
+    )
+}

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppLoadingPage/index.tsx

@@ -0,0 +1,8 @@
+import { getTranslations } from "next-intl/server"
+import { LoadingNotice } from "@/components/composites/LoadingNotice"
+
+/** Shown while a route resolves. */
+export const AppLoadingPage = async () => {
+    const t = await getTranslations("app.loading")
+    return <LoadingNotice label={t("message")} />
+}

package/templates/fe/skeleton-lite/apps/web/src/features/pages/AppNotFoundPage/index.tsx

@@ -0,0 +1,9 @@
+import { getTranslations } from "next-intl/server"
+import { NotFoundNotice } from "@/components/composites/NotFoundNotice"
+import { APP_ROUTES } from "@/modules/routes"
+
+/** Shown when a route does not exist. */
+export const AppNotFoundPage = async () => {
+    const t = await getTranslations("app.notFound")
+    return <NotFoundNotice title={t("title")} homeLabel={t("home")} homeHref={APP_ROUTES.home} />
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/brand/brand.css

@@ -0,0 +1,20 @@
+/* The lite scaffold's neutral brand layer; replace these values through the brand workflow. */
+:root,
+.light,
+.dark {
+    --starci-core-accent: #0d9488;
+    --accent: var(--starci-core-accent);
+    --accent-foreground: #051817;
+    --font-sans: ui-sans-serif, system-ui, sans-serif;
+}
+
+:root,
+.light {
+    --info-soft: #ccf3ef;
+    --info-soft-foreground: #0b5c54;
+}
+
+.dark {
+    --info-soft: #0d3b37;
+    --info-soft-foreground: #7fe0d4;
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/brand/index.ts

@@ -0,0 +1,2 @@
+/** Loads the app-owned brand tokens after the Grammar stylesheet. */
+import "./brand.css"

package/templates/fe/skeleton-lite/apps/web/src/modules/config/index.ts

@@ -0,0 +1,20 @@
+/** The only process-environment reader in the web app. */
+const required = (name: string, value: string | undefined): string => {
+    if (value === undefined || value === "") throw new Error(`${name} is not set`)
+    return value
+}
+
+/** The public origin used for metadata and same-origin redirects. */
+export const siteUrl = (): string => required("NEXT_PUBLIC_SITE_URL", process.env.NEXT_PUBLIC_SITE_URL)
+/** The public Supabase project origin. */
+export const supabaseUrl = (): string => required("NEXT_PUBLIC_SUPABASE_URL", process.env.NEXT_PUBLIC_SUPABASE_URL)
+/** The public anonymous key; RLS remains the authority for every request. */
+export const supabaseAnonKey = (): string =>
+    required("NEXT_PUBLIC_SUPABASE_ANON_KEY", process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY)
+
+/** Security attributes applied whenever the app writes a Supabase session cookie. */
+export const sessionCookieOptions = {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+} as const

package/templates/fe/skeleton-lite/apps/web/src/modules/db/auth/read-session.ts

@@ -0,0 +1,25 @@
+import "server-only"
+
+import type { NextRequest, NextResponse } from "next/server"
+import { getPrincipal, principalFromClaims } from "../principal"
+import type { Principal } from "../principal"
+import { createRequestDbClient, createServerDbClient } from "../server"
+import { toOutcome } from "../outcome"
+import type { DbOutcome } from "../outcome"
+
+/** Reads the verified principal of the current server request. */
+export const readSession = (): Promise<DbOutcome<Principal>> => getPrincipal()
+
+/** Exchanges the one-time PKCE code and lets the server client write the resulting cookies. */
+export const exchangeAuthCode = async (code: string) => {
+    const client = await createServerDbClient()
+    return toOutcome(await client.auth.exchangeCodeForSession(code))
+}
+
+/** Refreshes proxy cookies through `getClaims()` and returns the verified principal outcome. */
+export const refreshSession = async (request: NextRequest, response: NextResponse): Promise<DbOutcome<Principal>> => {
+    const client = createRequestDbClient(request, response)
+    const claims = toOutcome(await client.auth.getClaims())
+    if (claims.kind !== "ok") return claims
+    return principalFromClaims(claims.value.claims)
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/db/auth/write-sign-in.ts

@@ -0,0 +1,25 @@
+"use server"
+import "server-only"
+
+import { getPrincipal } from "../principal"
+import { createServerDbClient } from "../server"
+import { dbFailure, dbOk, toOutcome } from "../outcome"
+import type { DbOutcome } from "../outcome"
+import { signInInputSchema } from "../validation/validation.mapper"
+
+/** Result exposed to the client boundary after sign-in. */
+export interface SignInResult {
+    readonly userId: string
+}
+
+/** Schema-checks credentials, signs in through the server client and returns a typed outcome. */
+export const writeSignIn = async (input: FormData): Promise<DbOutcome<SignInResult>> => {
+    const principal = await getPrincipal()
+    if (principal.kind === "ok") return dbOk({ userId: principal.value.id })
+    const parsed = signInInputSchema.safeParse(input)
+    if (!parsed.success) return dbFailure("invalid", "sign-in-input")
+    const client = await createServerDbClient()
+    const signedIn = toOutcome(await client.auth.signInWithPassword(parsed.data))
+    if (signedIn.kind !== "ok") return signedIn
+    return signedIn.value.user === null ? dbFailure("refused", "user") : dbOk({ userId: signedIn.value.user.id })
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/db/auth/write-sign-out.ts

@@ -0,0 +1,17 @@
+"use server"
+import "server-only"
+
+import { getPrincipal } from "../principal"
+import { createServerDbClient } from "../server"
+import { dbFailure, dbOk } from "../outcome"
+import type { DbOutcome } from "../outcome"
+
+/** Ends the cookie-backed Supabase session, including an already-anonymous one. */
+export const writeSignOut = async (): Promise<DbOutcome<true>> => {
+    const principal = await getPrincipal()
+    void principal
+    const client = await createServerDbClient()
+    const result = await client.auth.signOut()
+    if (result.error === null) return dbOk(true)
+    return dbFailure(result.error.status === 401 ? "refused" : "unavailable", result.error.code ?? "sign-out")
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/db/browser.ts

@@ -0,0 +1,14 @@
+import { createBrowserClient } from "@supabase/ssr"
+import type { SupabaseClient } from "@supabase/supabase-js"
+import type { Database } from "../../../../../../supabase/types/database.types"
+import { supabaseAnonKey, supabaseUrl } from "@/modules/config"
+
+/** Creates the typed public client used only by client-side auth lifecycle hooks. */
+const createBrowserDbClient = (): SupabaseClient<Database> =>
+    createBrowserClient<Database>(supabaseUrl(), supabaseAnonKey())
+
+/** Owns the browser Auth subscription and exposes only its lifecycle to client hooks. */
+export const subscribeToAuthRefresh = (refresh: () => void): (() => void) => {
+    const listener = createBrowserDbClient().auth.onAuthStateChange(refresh)
+    return () => listener.data.subscription.unsubscribe()
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/db/index.ts

@@ -0,0 +1,3 @@
+import "server-only"
+
+export { exchangeAuthCode, readSession, refreshSession } from "./auth/read-session"

package/templates/fe/skeleton-lite/apps/web/src/modules/db/outcome.ts

@@ -0,0 +1,59 @@
+/** Failure kinds exposed by the database boundary. */
+export type DbFailureKind = "refused" | "not-found" | "invalid" | "unavailable"
+
+/** A successful database or Auth operation. */
+export interface DbOk<T> {
+    readonly kind: "ok"
+    readonly value: T
+}
+
+/** An expected database or Auth failure. */
+export interface DbFailure {
+    readonly kind: DbFailureKind
+    readonly code: string
+}
+
+/** The app's one result vocabulary, owned by the lite database transport. */
+export type DbOutcome<T> = DbOk<T> | DbFailure
+
+/** The structural part of a Supabase error this boundary interprets. */
+interface SupabaseFailure {
+    readonly code?: string
+    readonly status?: number
+    readonly message: string
+}
+
+/** The common structural pair returned by Supabase data and Auth calls. */
+export interface SupabaseResult {
+    readonly data: unknown
+    readonly error: SupabaseFailure | null
+}
+
+/** The non-null data carried by one concrete SDK result. */
+export type SupabaseData<T extends SupabaseResult> = NonNullable<T["data"]>
+
+/** Wraps a value as a successful outcome. */
+export const dbOk = <T>(value: T): DbOk<T> => ({ kind: "ok", value })
+/** Builds a refusal without throwing across a Server Action boundary. */
+export const dbFailure = (kind: DbFailureKind, code: string): DbFailure => ({ kind, code })
+
+const hasSignal = (error: SupabaseFailure, signals: ReadonlyArray<string>): boolean => {
+    const values = [error.code, error.status === undefined ? undefined : String(error.status)]
+    return values.some((value) => value !== undefined && signals.includes(value))
+}
+
+const hasData = <T>(value: T): value is NonNullable<T> => value !== null && value !== undefined
+
+/** Maps Supabase's data/error pair into the app's closed outcome vocabulary. */
+export const toOutcome = <T extends SupabaseResult>(result: T): DbOutcome<SupabaseData<T>> => {
+    if (result.error === null) {
+        return hasData(result.data) ? dbOk(result.data) : dbFailure("not-found", "empty")
+    }
+    const code = result.error.code ?? String(result.error.status ?? "transport")
+    if (hasSignal(result.error, ["42501", "PGRST301", "401", "403", "invalid_credentials"])) {
+        return dbFailure("refused", code)
+    }
+    if (hasSignal(result.error, ["PGRST116"])) return dbFailure("not-found", code)
+    if (result.error.code?.startsWith("23") === true) return dbFailure("invalid", code)
+    return dbFailure("unavailable", code)
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/db/principal.ts

@@ -0,0 +1,29 @@
+import "server-only"
+
+import { cache } from "react"
+import { createServerDbClient } from "./server"
+import { dbFailure, dbOk, toOutcome } from "./outcome"
+import type { DbOutcome } from "./outcome"
+
+/** The trusted caller claims exposed to server readers and writers. */
+export interface Principal {
+    readonly id: string
+    readonly email?: string
+}
+
+/** Keeps only the claims a consumer may trust after `getClaims()` verified the token. */
+export const principalFromClaims = (claims: Readonly<Record<string, unknown>>): DbOutcome<Principal> => {
+    if (typeof claims.sub !== "string") return dbFailure("refused", "claims")
+    return dbOk({
+        id: claims.sub,
+        ...(typeof claims.email === "string" ? { email: claims.email } : {}),
+    })
+}
+
+/** Verifies and memoizes the current request principal. */
+export const getPrincipal = cache(async (): Promise<DbOutcome<Principal>> => {
+    const client = await createServerDbClient()
+    const claims = toOutcome(await client.auth.getClaims())
+    if (claims.kind !== "ok") return claims
+    return principalFromClaims(claims.value.claims)
+})