@starci/hfs 5.0.8 → 5.2.0

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.kit.ts

@@ -0,0 +1,26 @@
+import { AuthPrincipalVerifier, AuthTokens } from "@starci/auth/server"
+import { ok, refused } from "@modules/platform/primitives"
+import { PassportErrorCode } from "./errors/passport.error"
+import type { PassportOptions, VerifyAccessToken } from "./passport.options"
+
+/** The signer of the app's own access tokens (it also serves the JWKS) and the verifier `domain/identity` turns into a principal. */
+export interface PassportKit {
+    /** Signs access tokens and publishes every key of the set. */
+    readonly tokens: AuthTokens
+    /** Verifies one bearer token against the app's own key set. */
+    readonly verify: VerifyAccessToken
+}
+
+/**
+ * Builds the kit from the typed options. The key set is imported on the first use, so a bad key fails the first verification
+ * instead of hiding behind a default; the package verifies against its own key set only, never a remote one.
+ */
+export const passportKit = (options: PassportOptions): PassportKit => {
+    const tokens = new AuthTokens(options)
+    const verifier = new AuthPrincipalVerifier(tokens)
+    const verify: VerifyAccessToken = async (token) => {
+        const verified = await verifier.verify(token)
+        return verified.kind === "ok" ? ok(verified.value) : refused(PassportErrorCode.AccessTokenInvalid)
+    }
+    return { tokens, verify }
+}

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.options.ts

@@ -1,68 +1,39 @@
-import type { Secret } from "@modules/platform/config"
+import type { AuthOptions } from "@starci/auth/server"
 import type { Outcome } from "@modules/platform/primitives"
 import type { PassportErrorCode } from "./errors/passport.error"
 
+/**
+ * The typed settings of the sign-in, parsed once at boot by `passport.config.ts` and handed to @starci/auth: the signing keys
+ * (the first with a private key signs; every key verifies and is published as the JWKS), the access and refresh lifetimes, the
+ * Google client, the refresh cookie and the sign-in budget. The stores the package needs (sessions, accounts, rate counter)
+ * are not settings: `domain/identity` provides them.
+ */
+export type PassportOptions = Pick<
+    AuthOptions,
+    | "issuer"
+    | "audience"
+    | "keys"
+    | "accessTtlSeconds"
+    | "refreshTtlSeconds"
+    | "reuseGraceMs"
+    | "bcryptCost"
+    | "returnOrigin"
+    | "google"
+    | "cookie"
+    | "budget"
+>
+
 /** The claims admitted from one of the app's own access tokens after every cryptographic and semantic check. */
 export interface OwnPrincipal {
     /** The user identifier from the verified `sub` claim (a row of auth.users). */
     readonly id: string
     /** The verified email claim when the user has one. */
     readonly email?: string
+    /** The device session the token belongs to, when the token names one. */
+    readonly sessionId?: string
     /** The role every access token the app issues carries; any other role is refused. */
     readonly role: "authenticated"
 }
 
 /** Verifies one bearer token against the app's own key set and returns only claims that passed every check. */
 export type VerifyAccessToken = (token: string) => Promise<Outcome<OwnPrincipal, PassportErrorCode>>
-
-/** Issues one short-lived access token for a signed-in user. */
-export type IssueAccessToken = (user: { readonly id: string; readonly email?: string }) => Promise<string>
-
-/** Google OAuth 2.0 client configuration (authorization code with state and PKCE). */
-export interface GoogleOptions {
-    /** The OAuth client id. */
-    readonly clientId: string
-    /** The OAuth client secret. */
-    readonly clientSecret: Secret
-    /** The absolute callback URL of the back end's Google callback door. */
-    readonly callbackUrl: string
-}
-
-/** The app's own asymmetric access tokens and the JWKS that publishes their public key. */
-export interface TokenOptions {
-    /** The issuer (`iss`), the app's public API origin. */
-    readonly issuer: string
-    /** The audience (`aud`) every token names. */
-    readonly audience: string
-    /** The ES256 private key in PKCS#8 PEM; its public half is served as the JWKS. */
-    readonly privateKey: Secret
-    /** The key id (`kid`) of the signing key. */
-    readonly keyId: string
-    /** The access-token lifetime in seconds. */
-    readonly accessTtlSeconds: number
-}
-
-/** The rotating refresh token: an opaque value held only in an httpOnly, Secure, SameSite=Strict cookie. */
-export interface RefreshCookieOptions {
-    /** The cookie name. */
-    readonly name: string
-    /** The path the browser sends the cookie to: the refresh door only. */
-    readonly path: string
-    /** The refresh-token lifetime in seconds. */
-    readonly ttlSeconds: number
-    /**
-     * The bare registrable domain every cookie passport sets and clears carries as `Domain` (`example.com`, no scheme,
-     * no port), so a web app on another subdomain can forward the cookie to this API. Unset keeps the cookies host-only.
-     */
-    readonly cookieDomain?: string | undefined
-}
-
-/** The passport integration configuration parsed once at API boot. */
-export interface PassportOptions {
-    /** Google OAuth 2.0. */
-    readonly google: GoogleOptions
-    /** The app's own access tokens. */
-    readonly tokens: TokenOptions
-    /** The refresh cookie. */
-    readonly refresh: RefreshCookieOptions
-}

package/templates/be/skeleton-lite/src/modules/integrations/passport/passport.registration.ts

@@ -0,0 +1,31 @@
+import { AuthModule } from "@starci/auth/server"
+import type { AccountDirectory, RateCounter, SessionStore } from "@starci/auth/server"
+import type { DynamicModule } from "@nestjs/common"
+import { CLOCK } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { IDS } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import { PASSPORT_ACCOUNTS, PASSPORT_AUTHENTICATOR, PASSPORT_RATE_COUNTER, PASSPORT_SESSION_STORE } from "./passport.decorators"
+import type { PassportOptions } from "./passport.options"
+
+/** Whether the app root registers the sign-in package globally: the root decides, never the module. */
+export interface PassportRegistration {
+    /** True when every module of the app may inject what the package provides, without importing it. */
+    readonly isGlobal: boolean
+}
+
+/** The sign-in package as a Nest module: the typed options, the clock and ids of the app, and the stores the identity domain provides. */
+export const passportModule = (options: PassportOptions, registration: PassportRegistration): DynamicModule =>
+    AuthModule.registerAsync({
+        isGlobal: registration.isGlobal,
+        authenticator: PASSPORT_AUTHENTICATOR,
+        inject: [PASSPORT_SESSION_STORE, PASSPORT_ACCOUNTS, PASSPORT_RATE_COUNTER, CLOCK, IDS],
+        useFactory: (sessions: SessionStore, accounts: AccountDirectory, rate: RateCounter, clock: Clock, ids: Ids) => ({
+            ...options,
+            sessions,
+            accounts,
+            rate,
+            clock,
+            ids,
+        }),
+    })

package/templates/be/skeleton-lite/src/modules/platform/cqrs/index.ts

@@ -1,4 +1,4 @@
 export type { Principal, PublicExecuteParams } from "./cqrs.contracts"
-export { InjectQueryBus } from "./cqrs.decorators"
+export { InjectCommandBus, InjectQueryBus } from "./cqrs.decorators"
 export { ICQRSHandler } from "./cqrs.handler"
 export { CqrsModule } from "./cqrs.module"

package/templates/be/skeleton-lite/src/modules/platform/database/database.port.ts

@@ -5,7 +5,7 @@ import type { DatabaseOptions } from "./database.options"
 import { PRIMARY_CONNECTION } from "./primary.connection"
 
 /** The primary pool's override token for infrastructure fixtures; TypeORM tokens stay owned by this capability. */
-export const PRIMARY_DATA_SOURCE = getDataSourceToken(PRIMARY_CONNECTION)
+export const PRIMARY_DATA_SOURCE: ReturnType<typeof getDataSourceToken> = getDataSourceToken(PRIMARY_CONNECTION)
 
 /** Token of the options of the database capability. */
 export const DATABASE_OPTIONS: unique symbol = Symbol("platform.database.options")

package/templates/be/skeleton-lite/src/modules/platform/database/entities.ts

@@ -1,3 +1,4 @@
+import { identityEntities } from "@modules/domain/identity"
 import { httpSecurityEntities } from "@modules/platform/http-security"
 import type { EntityClass } from "./database.options"
 
@@ -7,4 +8,4 @@ import type { EntityClass } from "./database.options"
  * file, from the deep path `@modules/platform/database/entities`; DatabaseModule and the database barrel never do, since the
  * capability barrels import the database capability back.
  */
-export const PRIMARY_ENTITIES: ReadonlyArray<EntityClass> = [...httpSecurityEntities]
+export const PRIMARY_ENTITIES: ReadonlyArray<EntityClass> = [...httpSecurityEntities, ...identityEntities]

package/templates/be/skeleton-lite/src/modules/platform/http-security/index.ts

@@ -6,7 +6,7 @@ export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard, ServerToServer } from "./origin.guard"
 export { httpSecurityEntities } from "./persistence/entities"
-export { RateLimitGuard } from "./rate-limit.guard"
+export { RateLimit, RateLimitGuard, RateTier } from "./rate-limit.guard"
 export { applyHttpSecurity } from "./edge-security.service"
 export { ReadinessService } from "./readiness.service"
 export { InjectReadiness } from "./readiness.decorators"

package/templates/be/skeleton-lite/src/modules/platform/http-security/persistence/entities/index.ts

@@ -1,4 +1,4 @@
 import { RateWindowEntity } from "./rate-window.entity"
 
 /** The entities of the http-security capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const httpSecurityEntities = [RateWindowEntity]
+export const httpSecurityEntities: ReadonlyArray<typeof RateWindowEntity> = [RateWindowEntity]

package/templates/be/skeleton-lite/src/tests/fixtures/builders/api.builder.ts

@@ -4,8 +4,14 @@ import { ACCESS_TOKEN_VERIFIER } from "@modules/domain/identity"
 import { OWN_TOKEN_VERIFIER } from "@modules/integrations/passport"
 import { OBJECT_STORAGE } from "@modules/integrations/object-storage"
 
+/** What a wiring proof hands the compiled root: public options and the infrastructure doubles. */
+export interface WiringProof {
+    readonly options: Readonly<Record<string, unknown>>
+    readonly overrides: ReadonlyArray<{ readonly token: unknown; readonly value: unknown }>
+}
+
 /** Compiles the real API root with public configuration and explicit infrastructure doubles. */
-export const buildWiringProof = () => ({
+export const buildWiringProof = (): WiringProof => ({
     options: {
         server: { port: 3000 },
         httpSecurity: {
@@ -21,9 +27,16 @@ export const buildWiringProof = () => ({
             schema: "public",
         },
         passport: {
-            google: { clientId: "fixture", clientSecret: new Secret("fixture-only"), callbackUrl: "https://api.fixture.example/auth/google/callback" },
-            tokens: { issuer: "https://api.fixture.example", audience: "fixture", privateKey: new Secret("fixture-only"), keyId: "k1", accessTtlSeconds: 900 },
-            refresh: { name: "refresh_token", path: "/auth/refresh", ttlSeconds: 2592000 },
+            issuer: "https://api.fixture.example",
+            audience: "fixture",
+            keys: [{ privateKey: new Secret("fixture-only"), keyId: "k1" }],
+            accessTtlSeconds: 900,
+            refreshTtlSeconds: 2592000,
+            bcryptCost: 4,
+            returnOrigin: "https://app.fixture.example",
+            google: null,
+            cookie: { name: "refresh_token" },
+            budget: { loginAttempts: 10, resetAttempts: 5, windowMs: 900000 },
         },
         objectStorage: {
             endpoint: "https://storage.fixture.example",
@@ -31,7 +44,7 @@ export const buildWiringProof = () => ({
             bucket: "fixture",
             accessKeyId: new Secret("fixture-only"),
             secretAccessKey: new Secret("fixture-only"),
-            presignTtlSeconds: 300,
+            defaultExpiresIn: 300,
         },
     },
     overrides: [

package/templates/be/skeleton-lite/src/tests/fixtures/builders/cli.builder.ts

@@ -2,8 +2,14 @@ import { getDataSourceToken } from "@nestjs/typeorm"
 import { Secret } from "@modules/platform/config"
 import { PRIMARY_CONNECTION } from "@modules/platform/database"
 
+/** What a wiring proof hands the compiled root: public options and the infrastructure doubles. */
+export interface WiringProof {
+    readonly options: Readonly<Record<string, unknown>>
+    readonly overrides: ReadonlyArray<{ readonly token: unknown; readonly value: unknown }>
+}
+
 /** Public fixture options and the database double for compiling the real CLI AppModule without network access. */
-export const buildWiringProof = () => ({
+export const buildWiringProof = (): WiringProof => ({
     options: {
         connections: [{
             name: PRIMARY_CONNECTION,

package/templates/be/table/api/feature.module-definition.ts.tpl

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { {{Name}}ApiOptions } from "./{{name}}.options"
 
+const built = new ConfigurableModuleBuilder<{{Name}}ApiOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<{{Name}}ApiOptions, "register", "create", {}>
+
 /** The configurable-module base of the {{name}} module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<{{Name}}ApiOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/table/api/graphql.module-definition.ts.tpl

@@ -1,6 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { {{Name}}GraphqlOptions } from "./{{name}}-graphql.options"
 
+const built = new ConfigurableModuleBuilder<{{Name}}GraphqlOptions>().setClassMethodName("register").build()
+type Host = ConfigurableModuleHost<{{Name}}GraphqlOptions, "register", "create", {}>
+
 /** The configurable-module base of the {{name}}-graphql module. */
-export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
-    new ConfigurableModuleBuilder<{{Name}}GraphqlOptions>().setClassMethodName("register").build()
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The injection token of the registered options. */
+export const MODULE_OPTIONS_TOKEN: Host["MODULE_OPTIONS_TOKEN"] = built.MODULE_OPTIONS_TOKEN
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/table/entities.index.ts.tpl

@@ -1,4 +1,4 @@
 import { {{Singular}}Entity } from "./{{name}}.entity"
 
 /** The entities of the {{name}} capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const {{nameCamel}}Entities = [{{Singular}}Entity]
+export const {{nameCamel}}Entities: ReadonlyArray<typeof {{Singular}}Entity> = [{{Singular}}Entity]

package/templates/be/table/module-definition.ts.tpl

@@ -1,7 +1,12 @@
-import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { ConfigurableModuleBuilder, type ConfigurableModuleHost } from "@nestjs/common"
 import type { {{Name}}Options } from "./{{name}}.options"
 
-/** The configurable-module base of the {{name}} capability. */
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<{{Name}}Options>()
+const built = new ConfigurableModuleBuilder<{{Name}}Options>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()
+type Host = ConfigurableModuleHost<{{Name}}Options, "register", "create", { isGlobal: boolean }>
+
+/** The configurable-module base of the {{name}} capability. */
+export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass
+/** The options of a synchronous registration, for the register signature. */
+export const OPTIONS_TYPE: Host["OPTIONS_TYPE"] = built.OPTIONS_TYPE

package/templates/be/test-world/e2e/serves-once-migrated.e2e-spec.ts.tpl

@@ -10,23 +10,23 @@ describe("system-health: the {{app}} app serves once its database is migrated (e
     const world = useTestWorld({ apps: ["{{app}}"] })
 
     it("answers liveness and readiness over the migrated {{connection}} database", async () => {
-        const live = await world.apps{{appAccess}}.api.get("/health/live")
-        const ready = await world.apps{{appAccess}}.api.get("/health/ready")
+        const live = await world.apps{{appAccess}}?.api.get("/health/live")
+        const ready = await world.apps{{appAccess}}?.api.get("/health/ready")
         const applied = await appliedMigrations(world.db{{connectionAccess}}, {{migrationsConst}})
 
-        expect(live.status).toBe(200)
-        expect(ready.status).toBe(200)
-        expect(ready.body).toEqual({ ok: true })
+        expect(live?.status).toBe(200)
+        expect(ready?.status).toBe(200)
+        expect(ready?.body).toEqual({ ok: true })
         expect(applied.length).toBeGreaterThan(0)
     })
 
     it("answers 503 on readiness while the database is cut, and liveness stays up", async () => {
         await world.interruptDatabase(async () => {
-            const ready = await world.apps{{appAccess}}.api.get("/health/ready")
-            const live = await world.apps{{appAccess}}.api.get("/health/live")
+            const ready = await world.apps{{appAccess}}?.api.get("/health/ready")
+            const live = await world.apps{{appAccess}}?.api.get("/health/live")
 
-            expect(ready.status).toBe(503)
-            expect(live.status).toBe(200)
+            expect(ready?.status).toBe(503)
+            expect(live?.status).toBe(200)
         })
     })
 })

package/templates/be/test-world/fixtures/migrations.sql.ts.tpl

@@ -7,8 +7,9 @@ export interface AppliedMigrationRow {
     readonly name: string
 }
 {{migrationQueries}}
-/** Reads the ledger of one connection with one of the queries above. */
+/** Reads the ledger of one connection with one of the queries above; a connection the world did not wire fails the spec. */
 export const appliedMigrations = (
-    manager: EntityManager,
+    manager: EntityManager | undefined,
     query: ReturnType<typeof sql>,
-): Promise<ReadonlyArray<AppliedMigrationRow>> => manager.query(query)
+): Promise<ReadonlyArray<AppliedMigrationRow>> =>
+    manager === undefined ? Promise.reject(new Error("The test world wired no such connection")) : manager.query(query)

package/templates/be/test-world/world/test-world.config.ts.tpl

@@ -5,10 +5,11 @@
  */
 import { applyCorrelation } from "@modules/platform/logging"
 import { defineTestWorld } from "@starci/test-world"
+import type { TestWorldApi } from "@starci/test-world"
 {{appModuleImports}}
 import { {{optionsImports}} } from "./test-apps.options"
 
-export const { useTestWorld, useSandbox } = defineTestWorld({
+const world: TestWorldApi = defineTestWorld({
     stack: ".starcistacks/dev",
     stacks: {
         postgresql: { connections: [{{connectionDeclarations}}] },
@@ -19,3 +20,9 @@ export const { useTestWorld, useSandbox } = defineTestWorld({
     migrate: { module: migrateCli, options: cliOptionsOf },
     modules: { base: platformBase },
 })
+
+/** Registers the hooks that boot and close the world around a spec and answers its handle; call it inside `describe`. */
+export const useTestWorld: TestWorldApi["useTestWorld"] = world.useTestWorld
+
+/** The contract layer: the real integration client against a provider sandbox, in a `contract-spec`. */
+export const useSandbox: TestWorldApi["useSandbox"] = world.useSandbox

package/templates/fe/auth-lite/apps/web/src/modules/auth/client.ts

@@ -0,0 +1,26 @@
+// Managed by starci app sync (slot fe.modules.auth.client); do not edit: run "npx starci app sync --execute".
+import { createAuthClient } from "@starci/auth/client"
+import { apiUrl } from "@/modules/config"
+import type { AuthClient, AuthFailure, AuthSession } from "./contracts"
+
+/** The one instance of the front end: the doors of the app's own back end, the access token in its memory, one shared refresh. */
+const auth = createAuthClient({ apiOrigin: () => apiUrl() })
+
+const sessionOf = (user: { readonly id: string; readonly email: string } | null): AuthSession | undefined =>
+    user === null ? undefined : { userId: user.id, ...(user.email === "" ? {} : { email: user.email }) }
+
+/** The lite session issuer's client: `@starci/auth/client` behind the interface every edition shares. */
+export const authClient: AuthClient = {
+    session: async () => sessionOf(await auth.user()),
+    accessToken: () => auth.accessToken(),
+    refreshAccessToken: () => auth.renew(),
+    signInWithPassword: async (email, password): Promise<AuthFailure | undefined> => {
+        const outcome = await auth.signIn({ email, password })
+        return outcome.success ? undefined : { code: outcome.error, kind: outcome.message, message: "" }
+    },
+    signOut: async () => {
+        await auth.signOut()
+        return undefined
+    },
+    onChange: (listener) => auth.subscribe(() => listener(sessionOf(auth.getSnapshot().user))),
+}

package/templates/fe/common/app-layout.tsx.partial

@@ -1,4 +1,4 @@
-export const AppLayout = async (props: AppLayoutProps) => {
+export const AppLayout = async (props: AppLayoutProps): Promise<ReactElement> => {
     const t = await getTranslations("app.shell")
     return (
         <SiteShell brand={t("brand")} homeHref={APP_ROUTES.home}>

package/templates/fe/common/site-shell.tsx.partial

@@ -1,10 +1,10 @@
 export const SiteShell = (props: SiteShellProps) => (
-    <GrammarRoot className={siteShellClassNames.frame}>
+    <GrammarRoot>
         <WorkspaceShell
             viewport="flow"
             primaryLabel={props.brand}
-            header={<TopBar brand={<TextAction href={props.homeHref}>{props.brand}</TextAction>} />}
-            primary={<PageContainer measure="reading">{props.children}</PageContainer>}
+            header={<TopBar brand={<Link href={props.homeHref}>{props.brand}</Link>} />}
+            primary={props.children}
         />
     </GrammarRoot>
 )

package/templates/fe/skeleton/apps/__app__/src/components/providers/AppProviders/index.tsx

@@ -1,11 +1,15 @@
 "use client"
 
 import { ToastProvider } from "@heroui/react"
+import { viewerCacheKey, viewerSwrConfig } from "@starci/next-data"
+import type { ViewerId } from "@starci/next-data"
 import { ThemeProvider } from "next-themes"
 import type { ReactNode } from "react"
-import { SWRConfig } from "swr"
+import { SWRConfig, useSWRConfig } from "swr"
+import { useViewerId } from "@/hooks/auth"
 import { useAuthSessionEffect } from "@/hooks/effects"
 import { SwrSideEffects } from "@/hooks/swr"
+import { viewerCache } from "@/modules/viewer-cache"
 import { ReduxProvider } from "@/redux"
 
 /** What the app providers wrap: the routed tree. */
@@ -25,25 +29,44 @@ const SWR_DEFAULTS = {
 } as const
 
 /** The app-wide session effect: modules/auth's session kept in redux. Renders nothing. */
-const AuthSessionEffect = () => {
+const AuthSessionEffect = (): null => {
     useAuthSessionEffect()
     return null
 }
 
+/** Points the writes of viewerCache at the SWR cache around it. Renders nothing. */
+const ViewerCacheBinding = (): null => {
+    viewerCache.bind(useSWRConfig().mutate)
+    return null
+}
+
+/**
+ * Each viewer gets their own SWR cache (FE-BOUNDARY-3): a change of person remounts the config on a fresh Map, and
+ * `viewerSwrConfig` lists pollingRestart so a read whose refreshInterval stopped at 0 polls again for newer data.
+ */
+const renderViewerScope = (viewerId: ViewerId, children: ReactNode): ReactNode => (
+    <SWRConfig key={viewerCacheKey(viewerId)} value={viewerSwrConfig(SWR_DEFAULTS)}>
+        <ViewerCacheBinding />
+        <SwrSideEffects />
+        {children}
+        <ToastProvider />
+    </SWRConfig>
+)
+
+/** The SWR config of the viewer on screen around the routed tree. */
+const ViewerSwrScope = (props: AppProvidersProps): ReactNode => renderViewerScope(useViewerId(), props.children)
+
 /**
  * The one client provider stack the locale layout mounts, outer to inner: the theme (light and dark through the `.light` /
- * `.dark` class the grammar and the brand layer read, the system theme by default), the redux store, the SWR defaults, the
- * app-wide effects and the HeroUI toast region modules/toast writes to. Each part is composed here, in its one owner.
+ * `.dark` class the grammar and the brand layer read, the system theme by default), the redux store, the session effect, the
+ * SWR config keyed by the viewer, the app-wide effects and the HeroUI toast region modules/toast writes to. Each part is
+ * composed here, in its one owner.
  */
 export const AppProviders = (props: AppProvidersProps) => (
     <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
         <ReduxProvider>
-            <SWRConfig value={SWR_DEFAULTS}>
-                <AuthSessionEffect />
-                <SwrSideEffects />
-                {props.children}
-                <ToastProvider />
-            </SWRConfig>
+            <AuthSessionEffect />
+            <ViewerSwrScope>{props.children}</ViewerSwrScope>
         </ReduxProvider>
     </ThemeProvider>
 )

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/index.ts

@@ -2,3 +2,4 @@ export { useSession } from "./useSession"
 export { useSignIn } from "./useSignIn"
 export type { SignInFailure } from "./useSignIn"
 export { useSignOut } from "./useSignOut"
+export { useViewerId } from "./useViewerId"

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSession.ts

@@ -2,9 +2,10 @@
 
 import { useDebugValue } from "react"
 import { useAppSelector } from "@/redux"
+import type { SessionState } from "@/redux"
 
 /** The reader's session as the app shares it (redux, kept by the auth session effect): unknown, signed in or signed out. */
-export const useSession = () => {
+export const useSession = (): SessionState => {
     const session = useAppSelector((state) => state.session)
     useDebugValue(session.status)
     return session

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignIn.ts

@@ -12,18 +12,26 @@ const FAILURES: readonly SignInFailure[] = ["refused", "invalid", "unavailable"]
 /** The failure of a sign-in's failure kind. */
 const failureOf = (kind: string): SignInFailure => FAILURES.find((each) => each === kind) ?? "unavailable"
 
+/** What the sign-in hook answers: whether a request runs, why the last one failed, the sign-in itself and `reject`. */
+export interface SignIn {
+    readonly failure: SignInFailure | undefined
+    readonly pending: boolean
+    readonly signIn: (email: string, password: string) => void
+    readonly reject: () => void
+}
+
 /**
  * Signs the reader in with an email and a password through modules/auth: whether a request runs, why the last one failed,
  * the sign-in itself and `reject` for input the form could not read. A success needs no state here: the session effect
  * moves the reader to signed in.
  */
-export const useSignIn = () => {
+export const useSignIn = (): SignIn => {
     const [failure, setFailure] = useState<SignInFailure>()
     const [pending, startTransition] = useTransition()
-    const signIn = (email: string, password: string) =>
+    const signIn = (email: string, password: string): void =>
         startTransition(async () => {
             const failed = await authClient.signInWithPassword(email, password)
             setFailure(failed === undefined ? undefined : failureOf(failed.kind))
         })
-    return { failure, pending, signIn, reject: () => setFailure("invalid") }
+    return { failure, pending, signIn, reject: (): void => setFailure("invalid") }
 }

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignOut.ts

@@ -11,14 +11,20 @@ const responseOf = (failure: AuthFailure | undefined) =>
         ? { success: true as const, data: null }
         : { success: false as const, error: failure.code, kind: failure.kind, message: failure.message }
 
+/** What the sign-out hook answers: whether the request runs and the sign-out itself. */
+export interface SignOut {
+    readonly pending: boolean
+    readonly signOut: () => void
+}
+
 /**
  * Ends the reader's session through modules/auth: whether the request runs and the sign-out itself. A failure is reported by
  * modules/toast; a success needs no toast, the session effect moves the reader to signed out.
  */
-export const useSignOut = () => {
+export const useSignOut = (): SignOut => {
     const withToast = useGraphQLWithToast()
     const [pending, startTransition] = useTransition()
-    const signOut = () =>
+    const signOut = (): void =>
         startTransition(async () => {
             await withToast(async () => responseOf(await authClient.signOut()), { showSuccessToast: false })
         })

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useViewerId.ts

@@ -0,0 +1,11 @@
+"use client"
+
+import type { ViewerId } from "@starci/next-data"
+import { useAppSelector } from "@/redux"
+
+/** The person the session belongs to: undefined until modules/auth answers, null when signed out (the viewer of @starci/next-data). */
+export const useViewerId = (): ViewerId => {
+    const session = useAppSelector((state) => state.session)
+    if (session.status === "unknown") return undefined
+    return session.session?.userId ?? null
+}

package/templates/fe/skeleton/apps/__app__/src/hooks/zustand/appGuide/store.ts

@@ -1,6 +1,7 @@
 "use client"
 
 import { create } from "zustand"
+import type { StoreApi, UseBoundStore } from "zustand"
 
 /** The home guide's local UI state; it carries no session or server data. */
 type AppGuideState = {
@@ -9,7 +10,7 @@ type AppGuideState = {
 }
 
 /** One feature-local store, shared by the guide trigger and its controlled dialog. */
-export const useAppGuideStore = create<AppGuideState>()((set) => ({
+export const useAppGuideStore: UseBoundStore<StoreApi<AppGuideState>> = create<AppGuideState>()((set) => ({
     isOpen: false,
     setOpen: (isOpen) => set({ isOpen }),
 }))

package/templates/fe/skeleton/apps/__app__/src/modules/toast/hooks.ts

@@ -23,7 +23,7 @@ const useToastMessages = (): ToastMessages => {
 }
 
 /** A localized runGraphQLWithToast: every GraphQL write reports its outcome through it. */
-export const useGraphQLWithToast = () => {
+export const useGraphQLWithToast = (): (<T>(action: () => Promise<GraphQLResponse<T>>, options?: RunWithToastOptions) => Promise<GraphQLResponse<T>>) => {
     const messages = useToastMessages()
     return useCallback(
         <T>(action: () => Promise<GraphQLResponse<T>>, options?: RunWithToastOptions) =>