@starci/hfs 4.9.11 → 4.10.1

package/templates/be/skeleton-lite/src/modules/integrations/passport/strategies/oauth-state.store.ts

@@ -0,0 +1,59 @@
+import { randomBytes, timingSafeEqual } from "node:crypto"
+import type { Request, Response } from "express"
+
+const COOKIE = "oauth_state"
+const MAX_AGE_MS = 600_000
+
+type Stored = { readonly state: string; readonly verifier: string }
+type StoreCallback = (error: Error | null, state?: string) => void
+type VerifyCallback = (error: Error | null, verifier?: string | false, state?: string) => void
+
+/** The response of the request a passport-oauth2 store is called with: passport keeps it on `req.res`. */
+const responseOf = (request: Request): Response | undefined => request.res
+
+/** The value of the state cookie in the request's Cookie header (no cookie middleware is installed). */
+const cookieOf = (request: Request): string | undefined =>
+    request.headers.cookie
+        ?.split(";")
+        .map((part) => part.trim())
+        .find((part) => part.startsWith(`${COOKIE}=`))
+        ?.slice(COOKIE.length + 1)
+
+const readStored = (request: Request): Stored | undefined => {
+    const raw = cookieOf(request)
+    if (raw === undefined) return undefined
+    const [state, verifier, extra] = raw.split(".")
+    return state && verifier && extra === undefined ? { state, verifier } : undefined
+}
+
+const sameText = (left: string, right: string): boolean => {
+    const a = Buffer.from(left)
+    const b = Buffer.from(right)
+    return a.length === b.length && timingSafeEqual(a, b)
+}
+
+/**
+ * The OAuth state and PKCE verifier store of the Google strategy without a server session: both live in one short-lived
+ * httpOnly, Secure, SameSite=Lax cookie scoped to the callback path, and the callback must present the same state.
+ */
+export class CookieStateStore {
+    constructor(private readonly callbackPath: string) {}
+
+    /** Stores a fresh state with the PKCE verifier and hands the state to the authorization redirect. */
+    store(request: Request, verifier: string, _state: unknown, _meta: unknown, callback: StoreCallback): void {
+        const state = randomBytes(24).toString("base64url")
+        responseOf(request)?.cookie(COOKIE, `${state}.${verifier}`, { httpOnly: true, secure: true, sameSite: "lax", path: this.callbackPath, maxAge: MAX_AGE_MS })
+        callback(null, state)
+    }
+
+    /** Answers the stored verifier only when the callback's state equals the stored one; the cookie is cleared either way. */
+    verify(request: Request, provided: string, callback: VerifyCallback): void {
+        const stored = readStored(request)
+        responseOf(request)?.clearCookie(COOKIE, { httpOnly: true, secure: true, sameSite: "lax", path: this.callbackPath })
+        if (stored === undefined || !sameText(stored.state, provided)) {
+            callback(null, false)
+            return
+        }
+        callback(null, stored.verifier, stored.state)
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { EntityManager } from "typeorm"
+
+/** The database functions this app may call, each listed with its reason in ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/
+
+/**
+ * Calls one database function TypeORM cannot express (a pg built-in or a SECURITY DEFINER function of a migration) with numbered
+ * parameters; the function name is an identifier the canon lint holds to the listed set, never a value.
+ */
+export const callDbFunction = async <T>(manager: EntityManager, name: string, args: ReadonlyArray<unknown>): Promise<ReadonlyArray<T>> => {
+    if (!IDENTIFIER.test(name)) throw new TypeError(`${name} is not a database function name`)
+    const placeholders = args.map((_, index) => `$${String(index + 1)}`).join(", ")
+    return manager.query<Array<T>>(`SELECT * FROM ${name}(${placeholders})`, [...args])
+}
+
+/** Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends. */
+export const advisoryXactLock = async (manager: EntityManager, key: string): Promise<void> => {
+    await manager.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key])
+}
+
+/** Sends one NOTIFY on `channel` with `payload`, delivered when the manager's transaction commits. */
+export const notify = async (manager: EntityManager, channel: string, payload: string): Promise<void> => {
+    await manager.query("SELECT pg_notify($1, $2)", [channel, payload])
+}

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

@@ -21,7 +21,7 @@ const ENTITY_MANAGER_TOKENS: ReadonlyMap<string, EntityManagerToken> = new Map<s
 ])
 
 @Module({})
-/** Opens each named Supabase PostgreSQL connection and exposes its shared EntityManager without entities or migrations. */
+/** Opens each named PostgreSQL connection with the entities the composition root hands it, and exposes its shared EntityManager; no migrations. */
 export class DatabaseModule extends ConfigurableModuleClass {
     /** Registers the capability once per app with the connections it opens. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
@@ -53,6 +53,7 @@ export class DatabaseModule extends ConfigurableModuleClass {
                         type: "postgres",
                         url: connection.url.reveal(),
                         ...schemaOption(connection.schema),
+                        entities: [...options.entities],
                         synchronize: false,
                         retryAttempts: 2,
                     }),

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

@@ -4,8 +4,8 @@ import type { Secret } from "@modules/platform/config"
 export interface DatabaseConnectionConfig {
     /** The logical connection name declared in `hfs.json`. */
     readonly name: string
-    /** The Supabase PostgreSQL provider; schema changes remain under `supabase/migrations`. */
-    readonly provider: "supabase"
+    /** The PostgreSQL provider; schema changes remain under `db/migrations`. */
+    readonly provider: "postgres"
     /** The dedicated least-privilege application role's connection URL. */
     readonly url: Secret
 }
@@ -20,4 +20,6 @@ export interface DatabaseConnectionOptions extends DatabaseConnectionConfig {
 export interface DatabaseOptions {
     /** The connections this app opens; one per physical database. */
     readonly connections: ReadonlyArray<DatabaseConnectionOptions>
+    /** The TypeORM entities the connections map: PRIMARY_ENTITIES of `@modules/platform/database/entities`, passed by the app's composition root only. */
+    readonly entities: ReadonlyArray<Function>
 }

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

@@ -1,4 +1,4 @@
-import type { EntityManager } from "typeorm"
+import type { EntityManager, EntityTarget, ObjectLiteral } from "typeorm"
 import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
 
 declare const sqlTextBrand: unique symbol
@@ -35,15 +35,28 @@ function assertSqlIdent(_value: string): asserts _value is SqlIdent {
 
 type NotFoundFactory = (id: string) => never
 
-/** Requires the row selected by an id-and-owner statement and lets the capability own its typed not-found error of that id. */
-export const requireOwnedRow = async <T>(
+/** The id an owned read answers. */
+interface OwnedId {
+    readonly id: string
+}
+
+/**
+ * Requires the row of `entity` with this id and owner (its `id` and `owner_id` columns) and lets the capability own its
+ * typed not-found error of that id; absent and denied rows share it. The read is the entity's query builder with named
+ * parameters, so the capability writes no SQL (R334).
+ */
+export const requireOwnedEntity = async (
     entityManager: EntityManager,
-    statement: SqlText,
+    entity: EntityTarget<ObjectLiteral>,
     id: string,
     ownerId: string,
     notFound: NotFoundFactory,
-): Promise<T> => {
-    const row = (await entityManager.query<Array<T>>(statement, [id, ownerId]))[0]
+): Promise<OwnedId> => {
+    const row = await entityManager
+        .createQueryBuilder(entity, "owned")
+        .select("owned.id", "id")
+        .where("owned.id = :id AND owned.owner_id = :ownerId", { id, ownerId })
+        .getRawOne<OwnedId>()
     if (row === undefined) return notFound(id)
     return row
 }

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

@@ -0,0 +1,7 @@
+/**
+ * The entity list of the primary connection: each capability's `<c>Entities` array (its `persistence/entities/index.ts`), by
+ * name, no glob (the entity registry, slot be.platform.database.entities). Only app composition and the test world import this
+ * 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<Function> = []

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

@@ -1,4 +1,5 @@
 export { DatabaseModule } from "./database.module"
+export { advisoryXactLock, callDbFunction, notify } from "./database.functions"
 export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"

package/templates/be/skeleton-lite/src/modules/platform/database/migration-runner.service.ts

@@ -12,7 +12,7 @@ const runDbPush = (): Promise<void> =>
     })
 
 @Injectable()
-/** The lite migration runner delegates the Supabase schema authority to the managed db:push wrapper. */
+/** The lite migration runner delegates the db/migrations schema authority to the managed db:push wrapper. */
 export class MigrationRunnerService {
     /** Runs the managed wrapper and propagates a CLI or migration failure. */
     async run(): Promise<void> {

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

@@ -2,10 +2,10 @@ import type { EnvSource } from "@modules/platform/config"
 import type { DatabaseConnectionOptions } from "./database.options"
 import { PRIMARY_CONNECTION } from "./primary.connection"
 
-/** Reads the least-privilege Supabase PostgreSQL connection with no default. */
+/** Reads the least-privilege PostgreSQL connection with no default. */
 export const parsePrimaryDatabaseConfig = (env: EnvSource): DatabaseConnectionOptions => ({
     name: PRIMARY_CONNECTION,
-    provider: "supabase",
+    provider: "postgres",
     url: env.secret("PRIMARY_DB_URL"),
     schema: env.string("PRIMARY_DB_SCHEMA"),
 })

package/templates/be/skeleton-lite/src/modules/platform/database/seed-runner.service.ts

@@ -4,7 +4,7 @@ import type { EntityManager } from "typeorm"
 import type { SqlText } from "./database.sql"
 import { InjectPrimaryEntityManager } from "./primary.decorators"
 
-const SEED_FILE = "supabase/seed.sql"
+const SEED_FILE = "db/seed.sql"
 
 function assertSeedText(_text: string): asserts _text is SqlText {
     // The brand is compile-time only; this function's caller reads the tracked seed file verbatim.
@@ -16,7 +16,7 @@ const seedText = (text: string): SqlText => {
 }
 
 @Injectable()
-/** Executes the one tracked Supabase seed through the shared least-privilege EntityManager. */
+/** Executes the one tracked seed through the shared least-privilege EntityManager. */
 export class SeedRunnerService {
     constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
 

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

@@ -1,7 +1,8 @@
 import { Secret } from "@modules/platform/config"
 import { PRIMARY_DATA_SOURCE } from "@modules/platform/database"
 import { ACCESS_TOKEN_VERIFIER } from "@modules/domain/identity"
-import { SUPABASE_ACCESS_TOKEN_VERIFIER, SUPABASE_ADMIN_CLIENT } from "@modules/integrations/supabase"
+import { OWN_TOKEN_VERIFIER } from "@modules/integrations/passport"
+import { OBJECT_STORAGE } from "@modules/integrations/object-storage"
 
 /** Compiles the real API root with public configuration and explicit infrastructure doubles. */
 export const buildWiringProof = () => ({
@@ -14,16 +15,28 @@ export const buildWiringProof = () => ({
         },
         database: {
             name: "primary",
-            provider: "supabase",
+            provider: "postgres",
             url: new Secret("postgresql://app_be@127.0.0.1:5432/postgres"),
             schema: "public",
         },
-        supabase: { url: "https://fixture.supabase.co", serviceRoleKey: new Secret("fixture-only") },
+        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 },
+        },
+        objectStorage: {
+            endpoint: "https://storage.fixture.example",
+            region: "us-east-1",
+            bucket: "fixture",
+            accessKeyId: new Secret("fixture-only"),
+            secretAccessKey: new Secret("fixture-only"),
+            presignTtlSeconds: 300,
+        },
     },
     overrides: [
         { token: PRIMARY_DATA_SOURCE, value: { manager: {} } },
-        { token: SUPABASE_ADMIN_CLIENT, value: { auth: {}, storage: {} } },
-        { token: SUPABASE_ACCESS_TOKEN_VERIFIER, value: () => ({ ok: false }) },
+        { token: OBJECT_STORAGE, value: {} },
+        { token: OWN_TOKEN_VERIFIER, value: () => ({ ok: false }) },
         { token: ACCESS_TOKEN_VERIFIER, value: () => ({ ok: false }) },
     ],
 })

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

@@ -7,7 +7,7 @@ export const buildWiringProof = () => ({
     options: {
         connections: [{
             name: PRIMARY_CONNECTION,
-            provider: "supabase",
+            provider: "postgres",
             url: new Secret("postgresql://app_be@127.0.0.1:5432/postgres"),
             schema: "public",
         }],

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

@@ -0,0 +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]

package/templates/be/table/entity.ts.tpl

@@ -0,0 +1,21 @@
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+
+/** One row of public.{{table}}, mapped from its creating migration in db/migrations; edit it beside every migration that changes the table. */
+@Entity({ schema: "public", name: "{{table}}" })
+export class {{Singular}}Entity {
+    /** The row id. */
+    @PrimaryGeneratedColumn("uuid", { name: "id" })
+    id!: string
+
+    /** The owning user (auth.users.id). */
+    @Column({ name: "owner_id", type: "uuid" })
+    ownerId!: string
+
+    /** When the row was created; the database sets it. */
+    @Column({ name: "created_at", type: "timestamptz", insert: false, update: false })
+    createdAt!: Date
+
+    /** When the row last changed; the database trigger sets it. */
+    @Column({ name: "updated_at", type: "timestamptz", insert: false, update: false })
+    updatedAt!: Date
+}

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

@@ -1,2 +1,3 @@
 export { {{upper}}_ERROR_KINDS } from "./errors/{{name}}.error"
 export { {{Name}}Module } from "./{{name}}.module"
+export { {{nameCamel}}Entities } from "./persistence/entities/index"

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

@@ -4,7 +4,7 @@ import { ConfigurableModuleClass, OPTIONS_TYPE } from "./{{name}}.module-definit
 import { {{Name}}Service } from "./{{name}}.service"
 
 @Module({})
-/** The {{name}} capability over the primary Supabase PostgreSQL connection. */
+/** The {{name}} capability over the primary PostgreSQL connection. */
 export class {{Name}}Module extends ConfigurableModuleClass {
     /** Registers the capability once in the API app. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {

package/templates/be/table/service.api.ts.tpl

@@ -1,36 +1,35 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { InjectPrimaryEntityManager, requireOwnedRow } from "@modules/platform/database"
+import { InjectPrimaryEntityManager, requireOwnedEntity } from "@modules/platform/database"
 import { {{Name}}Error, {{Name}}ErrorCode } from "./errors/{{name}}.error"
-import type { {{Name}}Row } from "./persistence/{{name}}.rows"
-import { FIND_{{upper}}, INSERT_{{upper}} } from "./persistence/{{name}}.sql"
+import { {{Singular}}Entity } from "./persistence/entities/{{name}}.entity"
 
 /** What the capability answers for one row: its id. */
-type {{Name}}Result = Pick<{{Name}}Row, "id">
+type {{Name}}Result = Pick<{{Singular}}Entity, "id">
 
 /** Throws the typed not-found error of one id: absent and denied rows share it. */
 const notFound = (id: string): never => {
     throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotFound, params: { id } })
 }
 
-/** The row an insert answered; an insert that answered none throws the typed not-created error. */
-const createdRow = ([row]: ReadonlyArray<{{Name}}Result>): {{Name}}Result => {
-    if (row === undefined) throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotCreated })
-    return row
+/** The id of the row an insert saved; a save that answered none throws the typed not-created error. */
+const createdRow = (row: {{Singular}}Entity): {{Name}}Result => {
+    if (!row.id) throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotCreated })
+    return { id: row.id }
 }
 
 @Injectable()
-/** The {{name}} rows reached only through the shared primary EntityManager. */
+/** The {{name}} rows reached only through the {{Singular}}Entity on the shared primary EntityManager. */
 export class {{Name}}Service {
     constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
 
     /** Answers one row owned by the authenticated principal; absent and denied rows share one typed not-found result. */
     {{nameCamel}}(principalId: string, id: string): Promise<{{Name}}Result> {
-        return requireOwnedRow<{{Name}}Result>(this.entityManager, FIND_{{upper}}, id, principalId, notFound)
+        return requireOwnedEntity(this.entityManager, {{Singular}}Entity, id, principalId, notFound)
     }
 
     /** Creates one row owned by the authenticated principal and answers its id. */
     create{{Singular}}(principalId: string): Promise<{{Name}}Result> {
-        return this.entityManager.query<Array<{{Name}}Result>>(INSERT_{{upper}}, [principalId]).then(createdRow)
+        return this.entityManager.save({{Singular}}Entity, { ownerId: principalId }).then(createdRow)
     }
 }

package/templates/be/table/service.ts.tpl

@@ -1,12 +1,11 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { InjectPrimaryEntityManager, requireOwnedRow } from "@modules/platform/database"
+import { InjectPrimaryEntityManager, requireOwnedEntity } from "@modules/platform/database"
 import { {{Name}}Error, {{Name}}ErrorCode } from "./errors/{{name}}.error"
-import type { {{Name}}Row } from "./persistence/{{name}}.rows"
-import { FIND_{{upper}} } from "./persistence/{{name}}.sql"
+import { {{Singular}}Entity } from "./persistence/entities/{{name}}.entity"
 
 /** What the capability answers for one row: its id. */
-type {{Name}}Result = Pick<{{Name}}Row, "id">
+type {{Name}}Result = Pick<{{Singular}}Entity, "id">
 
 /** Throws the typed not-found error of one id: absent and denied rows share it. */
 const notFound = (id: string): never => {
@@ -14,12 +13,12 @@ const notFound = (id: string): never => {
 }
 
 @Injectable()
-/** The {{name}} rows reached only through the shared primary EntityManager. */
+/** The {{name}} rows reached only through the {{Singular}}Entity on the shared primary EntityManager. */
 export class {{Name}}Service {
     constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
 
     /** Answers one row owned by the authenticated principal; absent and denied rows share one typed not-found result. */
     {{nameCamel}}(principalId: string, id: string): Promise<{{Name}}Result> {
-        return requireOwnedRow<{{Name}}Result>(this.entityManager, FIND_{{upper}}, id, principalId, notFound)
+        return requireOwnedEntity(this.entityManager, {{Singular}}Entity, id, principalId, notFound)
     }
 }

package/templates/fe/skeleton-lite/apps/__app__/src/modules/auth/auth-door.ts

@@ -0,0 +1,30 @@
+import axios from "axios"
+import { apiUrl } from "@/modules/config"
+
+/** What one auth door answered: its status and its body, unread (the client narrows it). */
+export interface DoorAnswer {
+    readonly status: number
+    readonly body: unknown
+}
+
+/** The auth doors of the app's own back end; the refresh token rides in their httpOnly cookie, never in a body. */
+export type AuthDoor = "sign-in" | "sign-up" | "refresh" | "sign-out" | "password-reset" | "resend-verification"
+
+const TIMEOUT_MS = 10_000
+
+/**
+ * The one auth door of the front end: a POST to `<api>/auth/<door>` with the cookies attached. A network failure answers
+ * status 0, so the client maps it to "unavailable" instead of throwing.
+ */
+export const callAuthDoor = async (door: AuthDoor, body?: Readonly<Record<string, string>>): Promise<DoorAnswer> => {
+    try {
+        const response = await axios.post<unknown>(`${apiUrl()}/auth/${door}`, body, {
+            withCredentials: true,
+            validateStatus: () => true,
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        })
+        return { status: response.status, body: response.data }
+    } catch {
+        return { status: 0, body: undefined }
+    }
+}

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

@@ -1,18 +1,50 @@
-import { createClient } from "@supabase/supabase-js"
-import type { Session, SupabaseClient } from "@supabase/supabase-js"
-import { supabaseAnonKey, supabaseUrl } from "@/modules/config"
+import { callAuthDoor } from "./auth-door"
+import type { DoorAnswer } from "./auth-door"
 import type { AuthClient, AuthFailure, AuthSession } from "./contracts"
+import { heldSession, heldToken, hold, listen } from "./token-store"
 
-let authentication: SupabaseClient["auth"] | undefined
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> => typeof value === "object" && value !== null
 
-/**
- * The one Supabase client of the front end, used for Supabase Auth only (the PKCE flow runs in the browser: a returning
- * redirect's code is exchanged by `detectSessionInUrl`, no route handler). It never calls `.from()`, `.rpc()` or storage:
- * data goes through modules/api to the back end, which verifies the access token.
- */
-const authOf = (): SupabaseClient["auth"] =>
-    (authentication ??= createClient(supabaseUrl(), supabaseAnonKey(), {
-        auth: { flowType: "pkce", detectSessionInUrl: true, persistSession: true, autoRefreshToken: true },
-    }).auth)
+/** The token and session an auth door issued, narrowed from its unread body; undefined when the body is not one. */
+const issuedOf = (body: unknown): { readonly token: string; readonly session: AuthSession } | undefined => {
+    if (!isRecord(body) || typeof body.accessToken !== "string" || !isRecord(body.user) || typeof body.user.id !== "string") return undefined
+    const email = typeof body.user.email === "string" ? body.user.email : undefined
+    return { token: body.accessToken, session: { userId: body.user.id, ...(email === undefined ? {} : { email }) } }
+}
 
-// {{> fe/auth/supabase-client.ts.tpl}}
+/** The failure kind of a door's status: refused credentials, rejected input, or the API unavailable. */
+const kindOf = (status: number): string => {
+    if (status === 400 || status === 401 || status === 403) return "refused"
+    return status === 422 ? "invalid" : "unavailable"
+}
+
+const failureOf = (answer: DoorAnswer): AuthFailure => ({ code: `AUTH_${String(answer.status)}`, kind: kindOf(answer.status), message: "" })
+
+const ok = (answer: DoorAnswer): boolean => answer.status >= 200 && answer.status < 300
+
+/** Rotates the refresh cookie and holds the new access token; signs out when the API refuses the cookie. */
+const refresh = async (): Promise<string | undefined> => {
+    const answer = await callAuthDoor("refresh")
+    hold(ok(answer) ? issuedOf(answer.body) : undefined)
+    return heldToken()
+}
+
+/** The lite session issuer's client: the app's own auth doors through `auth-door.ts`, the token in `token-store.ts`. */
+export const authClient: AuthClient = {
+    session: async () => heldSession() ?? ((await refresh()) === undefined ? undefined : heldSession()),
+    accessToken: async () => heldToken() ?? refresh(),
+    refreshAccessToken: refresh,
+    signInWithPassword: async (email, password) => {
+        const answer = await callAuthDoor("sign-in", { email, password })
+        const issued = ok(answer) ? issuedOf(answer.body) : undefined
+        if (issued === undefined) return failureOf(answer)
+        hold(issued)
+        return undefined
+    },
+    signOut: async () => {
+        const answer = await callAuthDoor("sign-out")
+        hold(undefined)
+        return ok(answer) ? undefined : failureOf(answer)
+    },
+    onChange: listen,
+}

package/templates/fe/skeleton-lite/apps/__app__/src/modules/auth/token-store.ts

@@ -0,0 +1,31 @@
+import type { AuthSession } from "./contracts"
+
+/** The signed-in reader and the access token, in memory only; the refresh token never reaches the browser's script. */
+interface Held {
+    readonly token: string
+    readonly session: AuthSession
+}
+
+let held: Held | undefined
+const listeners = new Set<(session: AuthSession | undefined) => void>()
+
+/** The held access token, or undefined when signed out. */
+export const heldToken = (): string | undefined => held?.token
+
+/** The held session, or undefined when signed out. */
+export const heldSession = (): AuthSession | undefined => held?.session
+
+/** Replaces the held token and session (undefined signs out) and tells every listener. */
+export const hold = (next: Held | undefined): void => {
+    held = next
+    for (const listener of listeners) listener(held?.session)
+}
+
+/** Subscribes to session changes; the listener hears the current session first. */
+export const listen = (listener: (session: AuthSession | undefined) => void): (() => void) => {
+    listeners.add(listener)
+    listener(held?.session)
+    return () => {
+        listeners.delete(listener)
+    }
+}

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

@@ -6,8 +6,5 @@ const required = (name: string, value: string | undefined): string => {
 
 /** The public origin used for metadata. */
 export const siteUrl = (): string => required("NEXT_PUBLIC_SITE_URL", process.env.NEXT_PUBLIC_SITE_URL)
-/** The public Supabase project origin, read by modules/auth only. */
-export const supabaseUrl = (): string => required("NEXT_PUBLIC_SUPABASE_URL", process.env.NEXT_PUBLIC_SUPABASE_URL)
-/** The public anonymous key of Supabase Auth; the back end verifies every access token it is sent. */
-export const supabaseAnonKey = (): string =>
-    required("NEXT_PUBLIC_SUPABASE_ANON_KEY", process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY)
+/** The public origin of the API whose auth doors modules/auth calls; the browser holds no credential of its own. */
+export const apiUrl = (): string => required("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL)