@starci/hfs 4.11.22 → 4.12.0

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

@@ -1,7 +1,8 @@
 import { Test } from "@nestjs/testing"
-import type { Response } from "express"
+import type { Request, Response } from "express"
 import { mock } from "@starci/jest-preset"
 import { clearRefreshCookie, newRefreshToken, refreshTokenHash, setRefreshCookie } from "./passport.cookie"
+import { CookieStateStore } from "./strategies/oauth-state.store"
 
 const COOKIE: unique symbol = Symbol("passport.cookie")
 
@@ -54,4 +55,50 @@ describe("refresh cookie", () => {
 
         expect(response.clearCookie).toHaveBeenCalledWith("refresh", { httpOnly: true, secure: true, sameSite: "strict", path: "/auth/refresh" })
     })
+
+    it("stays host-only: no Domain attribute is set or cleared when no cookie domain is configured", async () => {
+        const subject = await build()
+        const response = mock<Response>()
+
+        subject.setRefreshCookie(response, OPTIONS, "token-1")
+        subject.clearRefreshCookie(response, OPTIONS)
+
+        expect(response.cookie).toHaveBeenCalledWith("refresh", "token-1", expect.not.objectContaining({ domain: expect.anything() }))
+        expect(response.clearCookie).toHaveBeenCalledWith("refresh", expect.not.objectContaining({ domain: expect.anything() }))
+    })
+
+    it("sets the rotated token with Domain=<cookieDomain> so a sibling host can forward it", async () => {
+        const subject = await build()
+        const response = mock<Response>()
+
+        subject.setRefreshCookie(response, { ...OPTIONS, cookieDomain: "example.com" }, "token-1")
+
+        expect(response.cookie).toHaveBeenCalledWith("refresh", "token-1", { httpOnly: true, secure: true, sameSite: "strict", path: "/auth/refresh", domain: "example.com", maxAge: 600_000 })
+    })
+
+    it("clears the cookie with the same Domain it was set with, or the browser keeps it", async () => {
+        const subject = await build()
+        const response = mock<Response>()
+
+        subject.clearRefreshCookie(response, { ...OPTIONS, cookieDomain: "example.com" })
+
+        expect(response.clearCookie).toHaveBeenCalledWith("refresh", { httpOnly: true, secure: true, sameSite: "strict", path: "/auth/refresh", domain: "example.com" })
+    })
+})
+
+describe("oauth state cookie", () => {
+    const request = (response: Response): Request => ({ res: response, headers: {} }) as unknown as Request
+
+    it("is host-only without a cookie domain and carries Domain=<cookieDomain> with one, on set and on clear", () => {
+        const hostOnly = mock<Response>()
+        const shared = mock<Response>()
+
+        new CookieStateStore("/auth/google/callback").store(request(hostOnly), "verifier", undefined, undefined, () => undefined)
+        new CookieStateStore("/auth/google/callback", "example.com").store(request(shared), "verifier", undefined, undefined, () => undefined)
+        new CookieStateStore("/auth/google/callback", "example.com").verify(request(shared), "state", () => undefined)
+
+        expect(hostOnly.cookie).toHaveBeenCalledWith("oauth_state", expect.stringMatching(/^[A-Za-z0-9_-]{32}[.]verifier$/), expect.not.objectContaining({ domain: expect.anything() }))
+        expect(shared.cookie).toHaveBeenCalledWith("oauth_state", expect.stringMatching(/^[A-Za-z0-9_-]{32}[.]verifier$/), expect.objectContaining({ domain: "example.com" }))
+        expect(shared.clearCookie).toHaveBeenCalledWith("oauth_state", expect.objectContaining({ domain: "example.com" }))
+    })
 })

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

@@ -11,11 +11,16 @@ export const newRefreshToken = (): { readonly token: string; readonly hash: stri
 /** The sha256 a refresh token is stored and looked up by; the token itself is never stored. */
 export const refreshTokenHash = (token: string): string => createHash("sha256").update(token).digest("hex")
 
+/** `Domain=<cookieDomain>` when the app configured one; absent (host-only) otherwise. Setting and clearing must agree on it. */
+export const domainAttribute = (cookieDomain: string | undefined): Pick<CookieOptions, "domain"> =>
+    cookieDomain === undefined ? {} : { domain: cookieDomain }
+
 const attributes = (options: RefreshCookieOptions): CookieOptions => ({
     httpOnly: true,
     secure: true,
     sameSite: "strict",
     path: options.path,
+    ...domainAttribute(options.cookieDomain),
 })
 
 /** Sets the rotated refresh token: httpOnly, Secure, SameSite=Strict and sent to the refresh door only. */

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

@@ -50,6 +50,11 @@ export interface RefreshCookieOptions {
     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. */

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

@@ -25,7 +25,7 @@ export class GoogleStrategy extends PassportStrategy(Strategy, "google") {
             scope: ["openid", "email"],
             pkce: true,
             state: true,
-            store: new CookieStateStore(new URL(options.google.callbackUrl).pathname),
+            store: new CookieStateStore(new URL(options.google.callbackUrl).pathname, options.refresh.cookieDomain),
         })
     }
 

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

@@ -1,5 +1,6 @@
 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
@@ -37,19 +38,22 @@ const sameText = (left: string, right: string): boolean => {
  * 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) {}
+    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 })
+        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 })
+        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

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

@@ -20,6 +20,12 @@ const ENTITY_MANAGER_TOKENS: ReadonlyMap<string, EntityManagerToken> = new Map<s
     [PRIMARY_CONNECTION, PRIMARY_ENTITY_MANAGER],
 ])
 
+/**
+ * How long a connection waits for its database at boot: 10 attempts 3 s apart (about 30 s), so an app that starts beside the db
+ * service of its stack outlives the database's own start instead of exiting and rolling the release back.
+ */
+const CONNECT_RETRY = { retryAttempts: 10, retryDelay: 3000 } as const
+
 @Module({})
 /** 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 {
@@ -55,7 +61,7 @@ export class DatabaseModule extends ConfigurableModuleClass {
                         ...schemaOption(connection.schema),
                         entities: [...options.entities],
                         synchronize: false,
-                        retryAttempts: 2,
+                        ...CONNECT_RETRY,
                     }),
                 ),
             ],

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

@@ -1,21 +1,10 @@
-import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+import { UuidAbstractEntity } from "@modules/platform/database"
+import { Column, Entity } 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
-
+/** One row of public.{{table}}, mapped from its creating migration in db/migrations; edit it beside every migration that changes the table. Its id, created_at and updated_at come from UuidAbstractEntity. */
+export class {{Singular}}Entity extends UuidAbstractEntity {
     /** 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/upgrade/check.d.mts

@@ -0,0 +1,9 @@
+import type { SlotManifest } from "../sync/index.mjs";
+/** Runs the normal check when the requested edition is the declared one; any other edition is a usage refusal. `normal` is the CLI's ordinary check closure. */
+export declare function checkEdition<T>({ repoRoot, edition, normal, manifest }: {
+    repoRoot: string;
+    edition: string | undefined;
+    normal: () => T | Promise<T>;
+    manifest?: SlotManifest;
+    [seam: string]: unknown;
+}): Promise<T>;

package/upgrade/check.mjs

@@ -3,14 +3,14 @@
 import { loadSlotManifest } from "../runtime/scripts/hfs/slots.mjs";
 import { loadHfs } from "../sync/index.mjs";
 import { UpgradeError } from "./index.mjs";
-
 /** Runs the normal check when the requested edition is the declared one; any other edition is a usage refusal. `normal` is the CLI's ordinary check closure. */
 export async function checkEdition({ repoRoot, edition, normal, manifest = loadSlotManifest() }) {
-  if (edition === undefined) return normal();
-  if (!["full", "lite"].includes(edition))
-    throw new UpgradeError("HFS_EDITION_INVALID", `--edition is ${JSON.stringify(edition)}; expected full or lite`);
-  const actual = loadHfs(repoRoot, manifest).edition ?? "full";
-  if (edition !== actual)
-    throw new UpgradeError("HFS_EDITION_INVALID", `hfs.json edition is ${actual}; editions are fixed at scaffold, so check judges only the declared edition`);
-  return normal();
+    if (edition === undefined)
+        return normal();
+    if (!["full", "lite"].includes(edition))
+        throw new UpgradeError("HFS_EDITION_INVALID", `--edition is ${JSON.stringify(edition)}; expected full or lite`);
+    const actual = loadHfs(repoRoot, manifest).edition ?? "full";
+    if (edition !== actual)
+        throw new UpgradeError("HFS_EDITION_INVALID", `hfs.json edition is ${actual}; editions are fixed at scaffold, so check judges only the declared edition`);
+    return normal();
 }

package/upgrade/file-state.d.mts

@@ -0,0 +1,6 @@
+/** The files an upgrade touched, by absolute path: their prior bytes, or null when the file did not exist. */
+export type Snapshot = Map<string, Buffer | null>;
+export declare function remember(snapshot: Snapshot, target: string): void;
+export declare function ensureParent(root: string, target: string, directories: string[]): void;
+export declare function writeFile(root: string, file: string, content: string, snapshot: Snapshot, directories: string[]): void;
+export declare function restore(snapshot: Snapshot, directories: readonly string[]): void;

package/upgrade/file-state.mjs

@@ -1,53 +1,45 @@
 // Snapshots and rollback for the additive completion of a full app.
 import fs from "node:fs";
 import path from "node:path";
-
 export function remember(snapshot, target) {
-  if (snapshot.has(target)) return;
-  snapshot.set(
-    target,
-    fs.existsSync(target) && fs.statSync(target).isFile()
-      ? fs.readFileSync(target)
-      : null,
-  );
+    if (snapshot.has(target))
+        return;
+    snapshot.set(target, fs.existsSync(target) && fs.statSync(target).isFile()
+        ? fs.readFileSync(target)
+        : null);
 }
-
 export function ensureParent(root, target, directories) {
-  const missing = [];
-  for (
-    let at = path.dirname(target);
-    at.startsWith(root) && at !== root && !fs.existsSync(at);
-    at = path.dirname(at)
-  )
-    missing.push(at);
-  for (const directory of missing.reverse()) {
-    fs.mkdirSync(directory);
-    directories.push(directory);
-  }
+    const missing = [];
+    for (let at = path.dirname(target); at.startsWith(root) && at !== root && !fs.existsSync(at); at = path.dirname(at))
+        missing.push(at);
+    for (const directory of missing.reverse()) {
+        fs.mkdirSync(directory);
+        directories.push(directory);
+    }
 }
-
 export function writeFile(root, file, content, snapshot, directories) {
-  const target = path.join(root, ...file.split("/"));
-  remember(snapshot, target);
-  ensureParent(root, target, directories);
-  fs.writeFileSync(target, content);
+    const target = path.join(root, ...file.split("/"));
+    remember(snapshot, target);
+    ensureParent(root, target, directories);
+    fs.writeFileSync(target, content);
 }
-
 export function restore(snapshot, directories) {
-  for (const [target, content] of [...snapshot.entries()].reverse()) {
-    if (content === null) {
-      if (fs.existsSync(target) && fs.statSync(target).isFile())
-        fs.unlinkSync(target);
-    } else {
-      fs.mkdirSync(path.dirname(target), { recursive: true });
-      fs.writeFileSync(target, content);
+    for (const [target, content] of [...snapshot.entries()].reverse()) {
+        if (content === null) {
+            if (fs.existsSync(target) && fs.statSync(target).isFile())
+                fs.unlinkSync(target);
+        }
+        else {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, content);
+        }
     }
-  }
-  for (const directory of [...directories].reverse()) {
-    try {
-      fs.rmdirSync(directory);
-    } catch {
-      /* It is non-empty or already absent: preserve it. */
+    for (const directory of [...directories].reverse()) {
+        try {
+            fs.rmdirSync(directory);
+        }
+        catch {
+            /* It is non-empty or already absent: preserve it. */
+        }
     }
-  }
 }

package/upgrade/index.d.mts

@@ -0,0 +1,13 @@
+export declare class UpgradeError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+/** The arguments of `starci app upgrade`: --execute (without it the run is a dry one: `plan`), and --repo from the CLI entry; --edition is refused (editions are fixed at scaffold). */
+export declare function upgradeArguments(argv: readonly string[]): {
+    root: string;
+    plan: boolean;
+};
+/** CLI adapter kept outside the CLI entry so that verb wiring remains one line. */
+export declare function upgradeMain(argv: string[], { stdout }?: {
+    stdout?: (text: string) => unknown;
+}): Promise<number>;