@starci/hfs 5.1.0 → 5.2.0

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

@@ -1,69 +0,0 @@
-import { createLocalJWKSet, exportJWK, importPKCS8, jwtVerify, SignJWT } from "jose"
-import type { JSONWebKeySet } from "jose"
-import { ok, refused } from "@modules/platform/primitives"
-import { PassportErrorCode } from "./errors/passport.error"
-import type { IssueAccessToken, OwnPrincipal, TokenOptions, VerifyAccessToken } from "./passport.options"
-
-const ALGORITHM = "ES256"
-const ROLE = "authenticated"
-
-/** The app's own token kit: the signer, the verifier over its own key set, and the public JWKS the API serves. */
-export interface TokenKit {
-    /** Signs one access token. */
-    readonly issue: IssueAccessToken
-    /** Verifies one access token against the app's own keys. */
-    readonly verify: VerifyAccessToken
-    /** The public key set served at `/.well-known/jwks.json`. */
-    readonly jwks: JSONWebKeySet
-}
-
-/** Builds the token kit from the ES256 private key; the verifier checks the app's own key set, never a remote one. */
-export const createTokenKit = async (options: TokenOptions): Promise<TokenKit> => {
-    const privateKey = await importPKCS8(options.privateKey.reveal(), ALGORITHM, { extractable: true })
-    const { d: _private, ...publicJwk } = await exportJWK(privateKey)
-    const jwks: JSONWebKeySet = { keys: [{ ...publicJwk, kid: options.keyId, alg: ALGORITHM, use: "sig" }] }
-    const keys = createLocalJWKSet(jwks)
-    const issue: IssueAccessToken = (user) =>
-        new SignJWT({ role: ROLE, ...(user.email === undefined ? {} : { email: user.email }) })
-            .setProtectedHeader({ alg: ALGORITHM, kid: options.keyId })
-            .setSubject(user.id)
-            .setIssuer(options.issuer)
-            .setAudience(options.audience)
-            .setIssuedAt()
-            .setExpirationTime(`${String(options.accessTtlSeconds)}s`)
-            .sign(privateKey)
-    const verify: VerifyAccessToken = async (token) => {
-        try {
-            const { payload } = await jwtVerify(token, keys, {
-                algorithms: ["ES256"],
-                audience: options.audience,
-                issuer: options.issuer,
-            })
-            if (typeof payload.sub !== "string" || typeof payload.exp !== "number" || payload.role !== ROLE) {
-                return refused(PassportErrorCode.AccessTokenInvalid)
-            }
-            const principal: OwnPrincipal = {
-                id: payload.sub,
-                role: ROLE,
-                ...(typeof payload.email === "string" ? { email: payload.email } : {}),
-            }
-            return ok(principal)
-        } catch (cause) {
-            return refused(PassportErrorCode.AccessTokenInvalid, { cause: String(cause) })
-        }
-    }
-    return { issue, verify, jwks }
-}
-
-/**
- * The token kit of a composition root that registers synchronously: each call awaits the one key import started here, so a
- * bad key fails the first verification instead of hiding behind a default.
- */
-export const tokenKit = (options: TokenOptions): { readonly issue: IssueAccessToken; readonly verify: VerifyAccessToken; readonly jwks: () => Promise<JSONWebKeySet> } => {
-    const kit = createTokenKit(options)
-    return {
-        issue: async (user) => (await kit).issue(user),
-        verify: async (token) => (await kit).verify(token),
-        jwks: async () => (await kit).jwks,
-    }
-}

package/templates/be/skeleton-lite/src/modules/integrations/passport/strategies/google.strategy.ts

@@ -1,41 +0,0 @@
-import { Injectable } from "@nestjs/common"
-import type { Type } from "@nestjs/common"
-import { PassportStrategy } from "@nestjs/passport"
-import { Strategy } from "passport-google-oauth20"
-import type { Profile } from "passport-google-oauth20"
-import { InjectPassportOptions } from "../passport.decorators"
-import type { PassportOptions } from "../passport.options"
-import { CookieStateStore } from "./oauth-state.store"
-
-/** The Google identity a callback proves: the provider subject and the verified email when Google states one. */
-export interface GoogleIdentity {
-    /** Google's stable subject id (auth.identities.provider_id). */
-    readonly providerId: string
-    /** The verified email, when present. */
-    readonly email?: string
-}
-
-/** The Passport strategy base of the google scheme, typed as the class the strategy extends. */
-const GoogleStrategyBase: Type<object> = PassportStrategy(Strategy, "google")
-
-@Injectable()
-/** Google OAuth 2.0 (authorization code with state and PKCE): it proves the Google identity and never signs the user in itself. */
-export class GoogleStrategy extends GoogleStrategyBase {
-    constructor(@InjectPassportOptions() options: PassportOptions) {
-        super({
-            clientID: options.google.clientId,
-            clientSecret: options.google.clientSecret.reveal(),
-            callbackURL: options.google.callbackUrl,
-            scope: ["openid", "email"],
-            pkce: true,
-            state: true,
-            store: new CookieStateStore(new URL(options.google.callbackUrl).pathname, options.refresh.cookieDomain),
-        })
-    }
-
-    /** The identity of the callback; the identity domain links it to a user and issues the session. */
-    validate(_accessToken: string, _refreshToken: string, profile: Profile): GoogleIdentity {
-        const email = profile.emails?.find((entry) => entry.verified)?.value
-        return { providerId: profile.id, ...(email === undefined ? {} : { email }) }
-    }
-}

package/templates/be/skeleton-lite/src/modules/integrations/passport/strategies/local.strategy.ts

@@ -1,40 +0,0 @@
-import { Injectable } from "@nestjs/common"
-import type { Type } from "@nestjs/common"
-import { PassportStrategy } from "@nestjs/passport"
-import { Strategy } from "passport-local"
-import { PassportError, PassportErrorCode } from "../errors/passport.error"
-import { InjectPasswordAccounts } from "../passport.decorators"
-import { verifyPassword } from "../passport.password"
-
-/** The account a password sign-in proves. */
-export interface PasswordAccount {
-    /** The user id (auth.users.id). */
-    readonly id: string
-    /** The account email. */
-    readonly email: string
-    /** The stored bcrypt hash (auth.users.encrypted_password), null for an account without a password. */
-    readonly passwordHash: string | null
-}
-
-/** The lookup the identity domain provides: the account of one email, or undefined. */
-export type FindPasswordAccount = (email: string) => Promise<PasswordAccount | undefined>
-
-/** The Passport strategy base of the local scheme, typed as the class the strategy extends. */
-const LocalStrategyBase: Type<object> = PassportStrategy(Strategy, "local")
-
-@Injectable()
-/** Email and password sign-in: bcrypt against the stored hash; a miss and a wrong password fail alike. */
-export class LocalStrategy extends LocalStrategyBase {
-    constructor(@InjectPasswordAccounts() private readonly findAccount: FindPasswordAccount) {
-        super({ usernameField: "email", passwordField: "password" })
-    }
-
-    /** The proven account; every refusal is the same error so an email's existence never leaks. */
-    async validate(email: string, password: string): Promise<{ readonly id: string; readonly email: string }> {
-        const account = await this.findAccount(email.trim().toLowerCase())
-        if (!(await verifyPassword(password, account?.passwordHash ?? null)) || account === undefined) {
-            throw new PassportError({ code: PassportErrorCode.CredentialsRefused })
-        }
-        return { id: account.id, email: account.email }
-    }
-}

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

@@ -1,63 +0,0 @@
-import { randomBytes, timingSafeEqual } from "node:crypto"
-import type { Request, Response } from "express"
-import { domainAttribute } from "../passport.cookie"
-
-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,
-        private readonly cookieDomain?: 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, ...domainAttribute(this.cookieDomain) })
-        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, ...domainAttribute(this.cookieDomain) })
-        if (stored === undefined || !sameText(stored.state, provided)) {
-            callback(null, false)
-            return
-        }
-        callback(null, stored.verifier, stored.state)
-    }
-}

package/templates/fe/skeleton/packages/__project__-ui/src/frames/SiteShell/classNames.ts

@@ -1,4 +0,0 @@
-/** The shell's frame: a full-height column; colours come from Grammar's root. */
-export const siteShellClassNames = {
-    frame: "flex min-h-screen flex-col",
-} as const

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

@@ -1,30 +0,0 @@
-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,50 +0,0 @@
-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"
-
-const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> => typeof value === "object" && value !== null
-
-/** 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 }) } }
-}
-
-/** 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

@@ -1,31 +0,0 @@
-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/components/frames/SiteShell/classNames.ts

@@ -1,4 +0,0 @@
-/** The shell's frame: a full-height column; colours come from Grammar's root. */
-export const siteShellClassNames = {
-    frame: "flex min-h-screen flex-col",
-} as const