@starci/hfs 5.1.0 → 5.2.0

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

@@ -1,24 +1,46 @@
 import type { EnvSource } from "@modules/platform/config"
 import type { PassportOptions } from "./passport.options"
 
-/** Reads the passport configuration with no credential or localhost defaults; secrets read `<KEY>_FILE` first. */
+const ACCESS_TTL_SECONDS = 900
+const REFRESH_TTL_SECONDS = 2_592_000
+const BCRYPT_COST = 10
+const LOGIN_ATTEMPTS = 10
+const RESET_ATTEMPTS = 5
+const ATTEMPT_WINDOW_MS = 900_000
+
+/** The Google client, or null when the deployment declares none (the Google door is then unavailable). */
+const readGoogle = (env: EnvSource): PassportOptions["google"] =>
+    env.has("GOOGLE_CLIENT_ID")
+        ? {
+              clientId: env.string("GOOGLE_CLIENT_ID"),
+              clientSecret: env.secret("GOOGLE_CLIENT_SECRET"),
+              callbackUrl: env.url("GOOGLE_CALLBACK_URL"),
+          }
+        : null
+
+/** The key set: the signing key, and the previous public key while its access tokens are still valid (a rotation). */
+const readKeys = (env: EnvSource): PassportOptions["keys"] => {
+    const previous = env.optional("AUTH_JWT_PREVIOUS_PUBLIC_KEY")
+    return [
+        { privateKey: env.secret("AUTH_JWT_PRIVATE_KEY"), keyId: env.optional("AUTH_JWT_KEY_ID") },
+        ...(previous === undefined ? [] : [{ publicKey: previous, keyId: env.optional("AUTH_JWT_PREVIOUS_KEY_ID") }]),
+    ]
+}
+
+/** Reads the sign-in configuration with no credential or localhost defaults; secrets read `<KEY>_FILE` first. */
 export const parsePassportConfig = (env: EnvSource): PassportOptions => ({
-    google: {
-        clientId: env.string("GOOGLE_CLIENT_ID"),
-        clientSecret: env.secret("GOOGLE_CLIENT_SECRET"),
-        callbackUrl: env.url("GOOGLE_CALLBACK_URL"),
-    },
-    tokens: {
-        issuer: env.url("AUTH_JWT_ISSUER"),
-        audience: env.string("AUTH_JWT_AUDIENCE"),
-        privateKey: env.secret("AUTH_JWT_PRIVATE_KEY"),
-        keyId: env.string("AUTH_JWT_KEY_ID"),
-        accessTtlSeconds: env.int("AUTH_ACCESS_TTL_SECONDS", 900),
-    },
-    refresh: {
-        name: "refresh_token",
-        path: "/auth/refresh",
-        ttlSeconds: env.int("AUTH_REFRESH_TTL_SECONDS", 2_592_000),
-        cookieDomain: env.optionalDomain("AUTH_COOKIE_DOMAIN"),
+    issuer: env.url("AUTH_JWT_ISSUER"),
+    audience: env.optional("AUTH_JWT_AUDIENCE"),
+    keys: readKeys(env),
+    accessTtlSeconds: env.int("AUTH_ACCESS_TTL_SECONDS", ACCESS_TTL_SECONDS),
+    refreshTtlSeconds: env.int("AUTH_REFRESH_TTL_SECONDS", REFRESH_TTL_SECONDS),
+    bcryptCost: env.int("AUTH_BCRYPT_COST", BCRYPT_COST),
+    returnOrigin: new URL(env.url("AUTH_WEB_ORIGIN")).origin,
+    google: readGoogle(env),
+    cookie: { name: "refresh_token", domain: env.optionalDomain("AUTH_COOKIE_DOMAIN") },
+    budget: {
+        loginAttempts: env.int("AUTH_LOGIN_ATTEMPTS", LOGIN_ATTEMPTS),
+        resetAttempts: env.int("AUTH_RESET_ATTEMPTS", RESET_ATTEMPTS),
+        windowMs: env.duration("AUTH_ATTEMPT_WINDOW", ATTEMPT_WINDOW_MS),
     },
 })

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

@@ -1,14 +1,20 @@
+import { AUTH_DOORS_SERVICE, AUTH_PASSWORDS, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET } from "@starci/auth/server"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { PassportOptions, VerifyAccessToken } from "./passport.options"
-import type { FindPasswordAccount } from "./strategies/local.strategy"
 
 /** Token of the passport options. */
 export const PASSPORT_OPTIONS: unique symbol = Symbol("integrations.passport.options")
 /** Token of the verifier of the app's own access tokens. */
 export const OWN_TOKEN_VERIFIER: unique symbol = Symbol("integrations.passport.own-token-verifier")
-/** Token of the password-account lookup the identity domain provides. */
-export const PASSWORD_ACCOUNTS: unique symbol = Symbol("integrations.passport.password-accounts")
+/** Token of the session store the identity domain implements over the package's tables. */
+export const PASSPORT_SESSION_STORE: unique symbol = Symbol("integrations.passport.session-store")
+/** Token of the account directory the identity domain implements over the user table. */
+export const PASSPORT_ACCOUNTS: unique symbol = Symbol("integrations.passport.accounts")
+/** Token of the rate counter the identity domain implements over its attempts table. */
+export const PASSPORT_RATE_COUNTER: unique symbol = Symbol("integrations.passport.rate-counter")
+/** Token of the sign-in decisions (password and Google) the identity domain makes. */
+export const PASSPORT_AUTHENTICATOR: unique symbol = Symbol("integrations.passport.authenticator")
 
 /** Injects the passport options. Parameter type: PassportOptions. */
 export const InjectPassportOptions = (): TypedParameterDecorator<PassportOptions> => injector<PassportOptions>(PASSPORT_OPTIONS)
@@ -17,6 +23,12 @@ export const InjectPassportOptions = (): TypedParameterDecorator<PassportOptions
 export const InjectOwnTokenVerifier = (): TypedParameterDecorator<VerifyAccessToken> =>
     injector<VerifyAccessToken>(OWN_TOKEN_VERIFIER)
 
-/** Injects the password-account lookup. Parameter type: FindPasswordAccount. */
-export const InjectPasswordAccounts = (): TypedParameterDecorator<FindPasswordAccount> =>
-    injector<FindPasswordAccount>(PASSWORD_ACCOUNTS)
+/** Token of the sign-in doors. */
+export const PASSPORT_DOORS: typeof AUTH_DOORS_SERVICE = AUTH_DOORS_SERVICE
+/** Token of the rotating sessions. */
+export const PASSPORT_SESSIONS: typeof AUTH_SESSIONS = AUTH_SESSIONS
+/** Token of the password hasher. */
+export const PASSPORT_PASSWORDS: typeof AUTH_PASSWORDS = AUTH_PASSWORDS
+/** Token of the failures-only sign-in budget. */
+export const PASSPORT_SIGN_IN_BUDGET: typeof AUTH_SIGN_IN_BUDGET = AUTH_SIGN_IN_BUDGET
+

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

@@ -0,0 +1,73 @@
+import { Test } from "@nestjs/testing"
+import { AUTH_ERROR_CODES, AUTH_ERROR_KINDS } from "@starci/auth/contracts"
+import { generateTestKeyPair } from "@starci/auth/testing"
+import { PASSPORT_ERROR_KINDS, PassportErrorCode } from "./errors/passport.error"
+import { passportKit } from "./passport.kit"
+import type { PassportOptions } from "./passport.options"
+
+const KIT: unique symbol = Symbol("passport.kit")
+
+const FAR_FUTURE = 32_503_680_000_000
+const LONG_AGO = 0
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [{ provide: KIT, useValue: { passportKit } }] }).compile()
+    return moduleRef.get<{ passportKit: typeof passportKit }>(KIT).passportKit
+}
+
+const optionsFor = (keys: PassportOptions["keys"]): PassportOptions => ({
+    issuer: "https://api.example.test",
+    audience: undefined,
+    keys,
+    accessTtlSeconds: 60,
+    refreshTtlSeconds: 3600,
+    reuseGraceMs: undefined,
+    bcryptCost: 4,
+    returnOrigin: "https://app.example.test",
+    google: null,
+    cookie: { name: "refresh_token" },
+    budget: { loginAttempts: 10, resetAttempts: 5, windowMs: 900_000 },
+})
+
+describe("PassportErrorCode", () => {
+    it("names every PASSPORT wire code of @starci/auth with the same kind", () => {
+        const wire = Object.values(AUTH_ERROR_CODES).filter((code) => code.startsWith("PASSPORT_"))
+
+        expect(Object.values(PassportErrorCode).sort()).toEqual(wire.sort())
+        for (const code of Object.values(PassportErrorCode)) expect(PASSPORT_ERROR_KINDS[code]).toBe(AUTH_ERROR_KINDS[code])
+    })
+})
+
+describe("passportKit", () => {
+    it("verifies a token its own signer issued and builds the principal from it", async () => {
+        const create = await build()
+        const kit = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey, keyId: "k1" }]))
+        const { token } = await kit.tokens.sign({ sub: "user-1", email: "a@example.test", sessionId: "s-1" }, new Date(FAR_FUTURE))
+
+        expect(await kit.verify(token)).toEqual({ kind: "ok", value: { id: "user-1", role: "authenticated", sessionId: "s-1", email: "a@example.test" } })
+        expect((await kit.tokens.jwks()).keys).toHaveLength(1)
+    })
+
+    it("refuses an expired token, a token of another key and a token that is no token", async () => {
+        const create = await build()
+        const kit = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey }]))
+        const stranger = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey }]))
+        const expired = await kit.tokens.sign({ sub: "user-1", sessionId: "s-1" }, new Date(LONG_AGO))
+        const foreign = await stranger.tokens.sign({ sub: "user-1", sessionId: "s-1" }, new Date(FAR_FUTURE))
+
+        for (const token of [expired.token, foreign.token, "not-a-token"]) {
+            expect(await kit.verify(token)).toEqual({ kind: "refused", code: PassportErrorCode.AccessTokenInvalid })
+        }
+    })
+
+    it("keeps verifying the token of a retired key while its public key stays in the set", async () => {
+        const create = await build()
+        const retired = generateTestKeyPair()
+        const before = create(optionsFor([{ privateKey: retired.privateKey, keyId: "old" }]))
+        const { token } = await before.tokens.sign({ sub: "user-1", sessionId: "s-1" }, new Date(FAR_FUTURE))
+        const after = create(optionsFor([{ privateKey: generateTestKeyPair().privateKey, keyId: "new" }, { publicKey: retired.publicKey, keyId: "old" }]))
+
+        expect((await after.verify(token)).kind).toBe("ok")
+        expect((await after.tokens.jwks()).keys.map((key) => key["kid"])).toEqual(["new", "old"])
+    })
+})

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/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/tests/fixtures/builders/api.builder.ts

@@ -27,9 +27,16 @@ export const buildWiringProof = (): WiringProof => ({
             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",
@@ -37,7 +44,7 @@ export const buildWiringProof = (): WiringProof => ({
             bucket: "fixture",
             accessKeyId: new Secret("fixture-only"),
             secretAccessKey: new Secret("fixture-only"),
-            presignTtlSeconds: 300,
+            defaultExpiresIn: 300,
         },
     },
     overrides: [

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

@@ -1,6 +1,5 @@
 import type { EntityManager } from "typeorm"
 import { sql } from "@modules/platform/database"
-import type { SqlText } from "@modules/platform/database"
 
 /** One row of a connection's migration ledger: the name of a migration the cli migrate step applied. */
 export interface AppliedMigrationRow {
@@ -8,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/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/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/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/modules/toast/toast.tsx

@@ -21,15 +21,18 @@ const INDICATOR: Record<"success" | "danger" | "warning" | "info", ReactNode> =
 /** The app's toast: HeroUI's, with the four status methods wrapped. */
 type AppToast = typeof heroToast
 
-/** The app's toast: HeroUI's imperative toast with the status indicator injected; the region is mounted by the providers. */
-export const toast: AppToast = {
-    ...heroToast,
-    success: (message: ReactNode, options?: StatusToastOptions) =>
-        heroToast.success(message, { indicator: INDICATOR.success, ...options }),
-    danger: (message: ReactNode, options?: StatusToastOptions) =>
-        heroToast.danger(message, { indicator: INDICATOR.danger, ...options }),
-    warning: (message: ReactNode, options?: StatusToastOptions) =>
-        heroToast.warning(message, { indicator: INDICATOR.warning, ...options }),
-    info: (message: ReactNode, options?: StatusToastOptions) =>
-        heroToast.info(message, { indicator: INDICATOR.info, ...options }),
-}
+/** The app's toast: HeroUI's imperative toast, callable as it is, with the four status methods wrapped to inject the status indicator; the region is mounted by the providers. */
+export const toast: AppToast = Object.assign(
+    (message: ReactNode, options?: Parameters<typeof heroToast>[1]) => heroToast(message, options),
+    heroToast,
+    {
+        success: (message: ReactNode, options?: StatusToastOptions) =>
+            heroToast.success(message, { indicator: INDICATOR.success, ...options }),
+        danger: (message: ReactNode, options?: StatusToastOptions) =>
+            heroToast.danger(message, { indicator: INDICATOR.danger, ...options }),
+        warning: (message: ReactNode, options?: StatusToastOptions) =>
+            heroToast.warning(message, { indicator: INDICATOR.warning, ...options }),
+        info: (message: ReactNode, options?: StatusToastOptions) =>
+            heroToast.info(message, { indicator: INDICATOR.info, ...options }),
+    },
+)

package/templates/fe/skeleton/apps/__app__/src/modules/viewer-cache/index.ts

@@ -0,0 +1,5 @@
+import { createViewerCache } from "@starci/next-data"
+import type { ViewerCache } from "@starci/next-data"
+
+/** The writes to the cache of the viewer on screen: the one instance of the app, bound by the client providers. */
+export const viewerCache: ViewerCache = createViewerCache()

package/templates/fe/skeleton/apps/__app__/src/redux/slices/session.ts

@@ -9,7 +9,7 @@ export interface SessionState {
 }
 
 /** The reducers of the session slice. */
-interface SessionReducers {
+type SessionReducers = {
     sessionChanged: CaseReducer<SessionState, PayloadAction<AuthSession | undefined>>
 }
 

package/templates/fe/skeleton/packages/__project__-i18n/src/index.ts

@@ -53,7 +53,7 @@ export interface AppI18n {
  * module: a client component reads the default locale from `./routing`.
  */
 export const createAppI18n = (app: string, loadMessages: LoadMessages): AppI18n => ({
-    navigation: createNavigation(routing),
+    navigation: createNavigation<ProductRouting["locales"], "as-needed">(routing),
     /**
      * The locale is the `[locale]` route param read through `next/root-params` (`experimental.rootParams` in the app's next.config.ts,
      * FE-I18N-1), never the deprecated `requestLocale`. An unrecognised locale resolves to the default before the loader runs, so a