@starci/hfs 5.0.8 → 5.2.0

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

@@ -1,88 +0,0 @@
-import { Test } from "@nestjs/testing"
-import { exportPKCS8, generateKeyPair, SignJWT } from "jose"
-import { Secret } from "@modules/platform/config"
-import { PassportErrorCode } from "./errors/passport.error"
-import { createTokenKit, tokenKit } from "./passport.tokens"
-
-const TOKENS: unique symbol = Symbol("passport.tokens")
-
-type SigningKey = Awaited<ReturnType<typeof generateKeyPair>>["privateKey"]
-
-const ISSUER = "https://api.example.test"
-const AUDIENCE = "app"
-
-const build = async () => {
-    const moduleRef = await Test.createTestingModule({
-        providers: [{ provide: TOKENS, useValue: { createTokenKit, tokenKit } }],
-    }).compile()
-    return moduleRef.get<{ createTokenKit: typeof createTokenKit; tokenKit: typeof tokenKit }>(TOKENS)
-}
-
-const keyPair = async () => {
-    const { privateKey } = await generateKeyPair("ES256", { extractable: true })
-    return { privateKey, options: { issuer: ISSUER, audience: AUDIENCE, privateKey: new Secret(await exportPKCS8(privateKey)), keyId: "k1", accessTtlSeconds: 60 } }
-}
-
-/** A token the kit's own key signs with the given claims, so only the claim checks can refuse it. */
-const ownSigned = (privateKey: SigningKey, claims: Record<string, unknown>, { subject = "user-1", expires = true } = {}) => {
-    const jwt = new SignJWT(claims).setProtectedHeader({ alg: "ES256", kid: "k1" }).setIssuer(ISSUER).setAudience(AUDIENCE).setIssuedAt()
-    if (subject !== "") jwt.setSubject(subject)
-    if (expires) jwt.setExpirationTime("60s")
-    return jwt.sign(privateKey)
-}
-
-describe("createTokenKit", () => {
-    it("verifies its own token with an email against its own key set and publishes only the public key", async () => {
-        const subject = await build()
-        const { options } = await keyPair()
-        const kit = await subject.createTokenKit(options)
-
-        expect(await kit.verify(await kit.issue({ id: "user-1", email: "a@example.test" }))).toEqual({ kind: "ok", value: { id: "user-1", role: "authenticated", email: "a@example.test" } })
-        expect(kit.jwks.keys).toHaveLength(1)
-        expect(kit.jwks.keys[0]).toMatchObject({ kid: "k1", alg: "ES256", use: "sig", kty: "EC", crv: "P-256" })
-        expect(kit.jwks.keys[0]).not.toHaveProperty("d")
-    })
-
-    it("issues a token without an email claim for a user who has none", async () => {
-        const subject = await build()
-        const { options } = await keyPair()
-        const kit = await subject.createTokenKit(options)
-
-        expect(await kit.verify(await kit.issue({ id: "user-2" }))).toEqual({ kind: "ok", value: { id: "user-2", role: "authenticated" } })
-    })
-
-    it("refuses a token another key signed, naming the failed signature", async () => {
-        const subject = await build()
-        const kit = await subject.createTokenKit((await keyPair()).options)
-        const other = await subject.createTokenKit((await keyPair()).options)
-
-        expect(await kit.verify(await other.issue({ id: "user-1" }))).toEqual({
-            kind: "refused",
-            code: PassportErrorCode.AccessTokenInvalid,
-            params: { cause: "JWSSignatureVerificationFailed: signature verification failed" },
-        })
-    })
-
-    it("refuses a correctly signed token whose subject, expiry or role is not the one it issues", async () => {
-        const subject = await build()
-        const { privateKey, options } = await keyPair()
-        const kit = await subject.createTokenKit(options)
-        const invalid = { kind: "refused", code: PassportErrorCode.AccessTokenInvalid }
-
-        expect(await kit.verify(await ownSigned(privateKey, { role: "authenticated" }, { subject: "" }))).toEqual(invalid)
-        expect(await kit.verify(await ownSigned(privateKey, { role: "authenticated" }, { expires: false }))).toEqual(invalid)
-        expect(await kit.verify(await ownSigned(privateKey, { role: "service_role" }))).toEqual(invalid)
-        expect(await kit.verify(await ownSigned(privateKey, { role: "authenticated", email: 7 }))).toEqual({ kind: "ok", value: { id: "user-1", role: "authenticated" } })
-    })
-})
-
-describe("tokenKit", () => {
-    it("signs, verifies and publishes through the one key import it starts", async () => {
-        const subject = await build()
-        const { options } = await keyPair()
-        const kit = subject.tokenKit(options)
-
-        expect(await kit.verify(await kit.issue({ id: "user-3", email: "c@example.test" }))).toEqual({ kind: "ok", value: { id: "user-3", role: "authenticated", email: "c@example.test" } })
-        expect((await kit.jwks()).keys.map((key) => key.kid)).toEqual(["k1"])
-    })
-})

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,37 +0,0 @@
-import { Injectable } 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
-}
-
-@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 PassportStrategy(Strategy, "google") {
-    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,36 +0,0 @@
-import { Injectable } 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>
-
-@Injectable()
-/** Email and password sign-in: bcrypt against the stored hash; a miss and a wrong password fail alike. */
-export class LocalStrategy extends PassportStrategy(Strategy, "local") {
-    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