@teamscala/service-boot 0.23.516 → 0.23.518

package/src/resolve-brand-favicon.test.ts

@@ -0,0 +1,63 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./resolve-brand-favicon declares 2 runtime export(s) and 5 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mock } from "bun:test";
+const __realAssetProxy = await import("./asset-proxy");
+let __probeCalls = 0;
+let __probeBehaviour: "ok" | "notok" | "throw" = "ok";
+mock.module("./asset-proxy", () => ({ ...__realAssetProxy, handleAssetProxy: async () => { __probeCalls++; if (__probeBehaviour === "throw") throw new Error("asset store unreachable"); return new Response(null, { status: __probeBehaviour === "ok" ? 200 : 404 }); } }));
+
+const mod = await import("./resolve-brand-favicon");
+
+const { resolveBrandFaviconPath } = mod;
+
+describe("resolve-brand-favicon exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"resolveBrandFaviconPath",
+			"warmBrandFaviconCache",
+		]);
+	});
+	it("resolveBrandFaviconPath is a function", () => {
+		expect(typeof mod["resolveBrandFaviconPath"]).toBe("function");
+	});
+	it("warmBrandFaviconCache is a function", () => {
+		expect(typeof mod["warmBrandFaviconCache"]).toBe("function");
+	});
+	it("no brand org resolves null without probing the asset store", async () => {
+		__probeCalls = 0;
+		const got = await resolveBrandFaviconPath(undefined);
+		expect(got).toBeNull();
+		expect(__probeCalls).toBe(0);
+	});
+	it("a reachable favicon resolves the encoded convention path and caches it", async () => {
+		__probeBehaviour = "ok"; __probeCalls = 0;
+		const got = await resolveBrandFaviconPath("brand-org-probe-1");
+		expect(got).toBe("/api/assets/brand-org-probe-1%2Flogos%2Ffavicon.png");
+		expect(__probeCalls).toBe(1);
+	});
+	it("the second resolution for the same org serves from cache", async () => {
+		__probeCalls = 0;
+		const got = await resolveBrandFaviconPath("brand-org-probe-1");
+		expect(got).toBe("/api/assets/brand-org-probe-1%2Flogos%2Ffavicon.png");
+		expect(__probeCalls).toBe(0);
+	});
+	it("a missing favicon at the convention key resolves null", async () => {
+		__probeBehaviour = "notok"; __probeCalls = 0;
+		const got = await resolveBrandFaviconPath("brand-org-probe-2");
+		expect(got).toBeNull();
+	});
+	it("an asset-store failure degrades to the generic fallback (null), never a throw", async () => {
+		__probeBehaviour = "throw"; __probeCalls = 0;
+		const got = await resolveBrandFaviconPath("brand-org-probe-3");
+		expect(got).toBeNull();
+	});
+});

package/src/resolve-theme-mode.test.ts

@@ -0,0 +1,51 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./resolve-theme-mode declares 1 runtime export(s) + 1 type(s) and 5 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+
+const mod = await import("./resolve-theme-mode");
+
+const { resolveThemeMode } = mod;
+
+describe("resolve-theme-mode exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"resolveThemeMode",
+		]);
+	});
+	it("resolveThemeMode is a function", () => {
+		expect(typeof mod["resolveThemeMode"]).toBe("function");
+	});
+	it("the ?theme= URL override wins and marks the render embedded", async () => {
+		const got = resolveThemeMode({ url: "https://x.local/p?theme=dark" });
+		expect(got.theme).toBe("dark");
+		expect(got.embedded).toBe(true);
+	});
+	it("an explicit override behaves exactly like the URL form", async () => {
+		const got = resolveThemeMode({ override: "dark" });
+		expect(got.theme).toBe("dark");
+		expect(got.embedded).toBe(true);
+	});
+	it("a non-light/dark override is not an override", async () => {
+		const got = resolveThemeMode({ override: "purple", candidates: ["dark"] });
+		expect(got.theme).toBe("dark");
+		expect(got.embedded).toBe(false);
+	});
+	it("candidates are consulted in priority order", async () => {
+		const got = resolveThemeMode({ candidates: [null, "light", "dark"] });
+		expect(got.theme).toBe("light");
+		expect(got.embedded).toBe(false);
+	});
+	it("nothing resolvable lands on light, never a crash", async () => {
+		const got = resolveThemeMode({});
+		expect(got.theme).toBe("light");
+		expect(got.embedded).toBe(false);
+	});
+});

package/src/resolvers/fetch-org-brand.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./fetch-org-brand declares 1 runtime export(s) and 4 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+
+const mod = await import("./fetch-org-brand");
+
+const { fetchOrgBrandWithFallback } = mod;
+
+describe("fetch-org-brand (page-org-first wrapper) exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"fetchOrgBrandWithFallback",
+		]);
+	});
+	it("fetchOrgBrandWithFallback is a function", () => {
+		expect(typeof mod["fetchOrgBrandWithFallback"]).toBe("function");
+	});
+	it("a page org with a brand row renders THAT brand, no fallback consulted", async () => {
+		const client = { organisation_profile: { findFirst: async ({ select, where }) => (where.id === "org-branded" ? { company_name: "Launcha", brand_primary_color: "#123456" } : null) } };
+		const got = await fetchOrgBrandWithFallback({ input: { orgId: "org-branded" }, client, params: {} } as never);
+		expect(got).not.toBeNull();
+		expect((got as { companyName: string }).companyName).toBe("Launcha");
+	});
+	it("a page org with no brand falls back to the website owning-org", async () => {
+		const client = { organisation_profile: { findFirst: async ({ where }) => (where.id === "org-fallback" ? { company_name: "Website Owner" } : null) } };
+		const got = await fetchOrgBrandWithFallback({ input: { orgId: "org-page", fallbackOrgId: "org-fallback" }, client, params: {} } as never);
+		expect((got as { companyName: string }).companyName).toBe("Website Owner");
+	});
+	it("a fallback identical to the page org is not consulted twice", async () => {
+		let calls = 0; const client = { organisation_profile: { findFirst: async () => { calls++; return null; } } };
+		const got = await fetchOrgBrandWithFallback({ input: { orgId: "org-x", fallbackOrgId: "org-x" }, client, params: {} } as never);
+		expect(got).toBeNull();
+		expect(calls).toBe(2);
+	});
+	it("no orgId anywhere resolves null and names it", async () => {
+		const client = { organisation_profile: { findFirst: async () => { throw new Error("must not be called"); } } };
+		const got = await fetchOrgBrandWithFallback({ input: {}, client, params: {} } as never);
+		expect(got).toBeNull();
+	});
+});

package/src/resolvers/website-by-host-map.test.ts

@@ -0,0 +1,63 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./website-by-host-map declares 1 runtime export(s) and 7 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+
+const mod = await import("./website-by-host-map");
+
+const { resolveWebsiteByHostMap } = mod;
+
+describe("website-by-host-map exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"resolveWebsiteByHostMap",
+		]);
+	});
+	it("resolveWebsiteByHostMap is a function", () => {
+		expect(typeof mod["resolveWebsiteByHostMap"]).toBe("function");
+	});
+	it("no host or no hosts_map resolves null without a query", async () => {
+		let queried = 0; const client = { builda_websites: { findFirst: async () => { queried++; return null; } } };
+		const got = await resolveWebsiteByHostMap({ input: {}, client, params: {} } as never);
+		expect(got).toBeNull();
+		expect(queried).toBe(0);
+	});
+	it("a mapped host resolves ITS website with the entry body_path", async () => {
+		const client = { builda_websites: { findFirst: async ({ where }) => (where.slug === "site-launcha" ? { id: "w1", slug: "site-launcha", name: "Launcha" } : null) } };
+		const got = await resolveWebsiteByHostMap({ input: { host: "launcha.example", hosts_map: { "launcha.example": { website: "site-launcha", body_path: "/p" } } }, client, params: {} } as never);
+		expect(got).not.toBeNull();
+		expect((got as { slug: string }).slug).toBe("site-launcha");
+		expect((got as { body_path: string }).body_path).toBe("/p");
+	});
+	it("an unmapped host falls to default_website and :path follows the request path", async () => {
+		const client = { builda_websites: { findFirst: async ({ where }) => (where.slug === "site-default" ? { id: "w2", slug: "site-default" } : null) } };
+		const got = await resolveWebsiteByHostMap({ input: { host: "other.example", hosts_map: {}, default_website: "site-default", default_body_path: ":path" }, client, params: { path: "/join" } } as never);
+		expect((got as { body_path: string }).body_path).toBe("/join");
+	});
+	it("an unknown slug in the map resolves null (the lookup is the validation)", async () => {
+		const client = { builda_websites: { findFirst: async () => null } };
+		const got = await resolveWebsiteByHostMap({ input: { host: "x.example", hosts_map: { "x.example": { website: "nope" } } }, client, params: {} } as never);
+		expect(got).toBeNull();
+	});
+	it("a mapped host whose client carries no builda_websites is a MISS, not a TypeError (the sign.scala.business 500)", async () => {
+		const client = { other_model: {} };
+		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client, params: {} } as never);
+		expect(got).toBeNull();
+	});
+	it("an undefined client on a mapped host is a MISS, never a throw", async () => {
+		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client: undefined, params: {} } as never);
+		expect(got).toBeNull();
+	});
+	it("a bound accessor with no findFirst is a MISS, never a throw", async () => {
+		const client = { builda_websites: {} };
+		const got = await resolveWebsiteByHostMap({ input: { host: "sign.scala.business", hosts_map: { "sign.scala.business": { website: "site-sign" } } }, client, params: {} } as never);
+		expect(got).toBeNull();
+	});
+});

package/src/resolvers/website-by-host-map.ts

@@ -30,9 +30,21 @@ export async function resolveWebsiteByHostMap({ input, client, params }: Resolve
 	if (!websiteSlug) return null;
 	const rawBodyPath = entry?.body_path ?? (input.default_body_path as string | undefined) ?? ":path";
 	const bodyPath = rawBodyPath === ":path" ? ((params.path as string) || "/") : rawBodyPath;
-	const website = await (client as never as {
-		builda_websites: { findFirst: (args: Record<string, unknown>) => Promise<BrandWebsite | null> };
-	}).builda_websites.findFirst({
+	// A host-map entry whose client is not bound is a MISS, not a crash.
+	// scala-sign (public catch-all, no builda_websites in its per-service
+	// scope) still receives hosts_map resolver inputs, so this arm used to
+	// reach an unbound client and escape as a TypeError: sign.scala.business
+	// answered 500 on its own host (measured 2026-09-29, stack
+	// resolveWebsiteByHostMap) while 127.0.0.1 answered 200 — only the
+	// mapped host crashed. Null lets the service's catch-all answer, and
+	// an unmapped host and an unbound client are both misses
+	// (unrecognised-input-must-refuse-never-degrade).
+	const siteClient = (client as
+		| { builda_websites?: { findFirst?: (args: Record<string, unknown>) => Promise<BrandWebsite | null> } }
+		| undefined
+		| null)?.builda_websites;
+	if (!siteClient?.findFirst) return null;
+	const website = await siteClient.findFirst({
 		where: { slug: websiteSlug },
 		select: {
 			id: true,

package/src/run-boot-hook-list.test.ts

@@ -0,0 +1,47 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./run-boot-hook-list declares 1 runtime export(s) and 4 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+
+const mod = await import("./run-boot-hook-list");
+
+const { runBootHookList } = mod;
+
+describe("run-boot-hook-list exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"runBootHookList",
+		]);
+	});
+	it("runBootHookList is a function", () => {
+		expect(typeof mod["runBootHookList"]).toBe("function");
+	});
+	it("declared hooks run in declared order, registered-but-undeclared run after", async () => {
+		const ran: string[] = []; const hooks = new Map([["late", async () => { ran.push("late"); }], ["second", async () => { ran.push("second"); }], ["first", async () => { ran.push("first"); }]]);
+		const config = { boot_hooks: [{ slug: "first" }, { slug: "second" }] };
+		await runBootHookList(config as never, { bootHooks: hooks } as never, "svc-hl");
+		expect(ran).toEqual(["first", "second", "late"]);
+	});
+	it("a declared hook with no registered handler is a boot-fatal, not a silent skip", async () => {
+		const config = { boot_hooks: [{ slug: "ghost" }] };
+		const call = () => runBootHookList(config as never, { bootHooks: new Map() } as never, "svc-hl");
+		expect(call).toThrow(/ghost/);
+	});
+	it("a throwing hook is fatal and NAMES the hook", async () => {
+		const hooks = new Map([["boom", async () => { throw new Error("disk gone"); }]]);
+		const config = { boot_hooks: [{ slug: "boom" }] };
+		const call = () => runBootHookList(config as never, { bootHooks: hooks } as never, "svc-hl");
+		expect(call).toThrow(/boom/);
+	});
+	it("no hooks and no registrations resolves without work", async () => {
+		const got = await runBootHookList({} as never, { bootHooks: new Map() } as never, "svc-hl");
+		expect(got).toBeUndefined();
+	});
+});

package/src/run-boot-hooks.test.ts

@@ -0,0 +1,56 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./run-boot-hooks declares 1 runtime export(s) + 2 type(s) and 5 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mock } from "bun:test";
+const __hookCalls: string[] = [];
+mock.module("stub-boot-hook", () => ({ default: async (ctx: { serviceSlug: string }) => { __hookCalls.push(ctx.serviceSlug); } }));
+mock.module("stub-boot-hook-no-default", () => ({ named: async () => {} }));
+
+const mod = await import("./run-boot-hooks");
+
+const { runBootHooks } = mod;
+
+describe("run-boot-hooks exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"runBootHooks",
+		]);
+	});
+	it("runBootHooks is a function", () => {
+		expect(typeof mod["runBootHooks"]).toBe("function");
+	});
+	it("no declared hooks resolves an empty ran", async () => {
+		const got = await runBootHooks("svc-bh", {} as never);
+		expect(got.ran).toEqual([]);
+	});
+	it("each hook dynamic-imports its handler_slug and receives the boot context", async () => {
+		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "the-hook", handler_slug: "stub-boot-hook" }] } as never);
+		expect(got.ran).toEqual(["the-hook"]);
+		expect(__hookCalls).toEqual(["svc-bh"]);
+	});
+	it("hooks run in ascending order, defaulting to 100", async () => {
+		const order: string[] = [];
+		mock.module("stub-hook-a", () => ({ default: async () => { order.push("a-200"); } }));
+		mock.module("stub-hook-b", () => ({ default: async () => { order.push("b-50"); } }));
+		mock.module("stub-hook-c", () => ({ default: async () => { order.push("c-default"); } }));
+		const got = await runBootHooks("svc-bh", { boot_hooks: [{ slug: "a", handler_slug: "stub-hook-a", order: 200 }, { slug: "b", handler_slug: "stub-hook-b", order: 50 }, { slug: "c", handler_slug: "stub-hook-c" }] } as never);
+		expect(got.ran).toEqual(["b", "c", "a"]);
+		expect(order).toEqual(["b-50", "c-default", "a-200"]);
+	});
+	it("a module with no default export is boot-fatal", async () => {
+		const call = () => runBootHooks("svc-bh", { boot_hooks: [{ slug: "nope", handler_slug: "stub-boot-hook-no-default" }] } as never);
+		expect(call).toThrow(/no default export/);
+	});
+	it("an unimportable handler is boot-fatal and names the specifier", async () => {
+		const call = () => runBootHooks("svc-bh", { boot_hooks: [{ slug: "gone", handler_slug: "stub-hook-does-not-exist" }] } as never);
+		expect(call).toThrow(/stub-hook-does-not-exist/);
+	});
+});

package/src/scala-tools-currency-watchdog.test.ts

@@ -0,0 +1,43 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./scala-tools-currency-watchdog declares 1 runtime export(s) and 2 declared behaviour vector(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mock } from "bun:test";
+const __watchdogs: { name: string; options: Record<string, unknown>; started: boolean }[] = [];
+const __captureCreateWatchdog = (name: string, options: Record<string, unknown>) => { const handle = { name, options, started: false, start() { this.started = true; }, stop() {} }; __watchdogs.push(handle); return handle; };
+mock.module("@teamscala/watchdog/create-watchdog", () => ({ createWatchdog: __captureCreateWatchdog }));
+
+const mod = await import("./scala-tools-currency-watchdog");
+
+const { startScalaToolsCurrencyWatchdog } = mod;
+
+describe("scala-tools-currency-watchdog exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"startScalaToolsCurrencyWatchdog",
+		]);
+	});
+	it("startScalaToolsCurrencyWatchdog is a function", () => {
+		expect(typeof mod["startScalaToolsCurrencyWatchdog"]).toBe("function");
+	});
+	it("starts the currency watchdog with the poll contract and no run-on-start", async () => {
+		__watchdogs.length = 0;
+		startScalaToolsCurrencyWatchdog();
+		expect(__watchdogs.length).toBe(1);
+		expect(__watchdogs[0].name).toBe("scala-sentinel:scala-tools-currency");
+		expect(__watchdogs[0].options.intervalMs).toBe(120_000);
+		expect(__watchdogs[0].options.runOnStart).toBe(false);
+		expect(__watchdogs[0].started).toBe(true);
+	});
+	it("a second start does not create a second watchdog", async () => {
+		startScalaToolsCurrencyWatchdog();
+		expect(__watchdogs.length).toBe(1);
+	});
+});

package/src/scala-tools-currency-watchdog.ts

@@ -186,8 +186,3 @@ export function startScalaToolsCurrencyWatchdog(): void {
 	});
 	watchdog.start();
 }
-
-export function stopScalaToolsCurrencyWatchdog(): void {
-	watchdog?.stop();
-	watchdog = null;
-}

package/src/transfers/presigned-upload.ts

@@ -0,0 +1,165 @@
+/**
+ * @system service-boot
+ * @status handwritten — none derivable: searched the api_route row (fn-transfers-presigned-upload) which declares path/handler_config/input but not a body, the codegen outputs (host-bus-handler-contracts emits wiring + suites FROM rows, never procedure bodies), reference/package-catalog.md (object-storage signs a key; it carries no upload-policy primitive: no size/type/dir-scheme package to install), and the retired mount attach-transfers-upload.ts (the policy's origin, not a derivation target) — nothing generates a policy-checking procedure body.
+ * @edit edit directly
+ *
+ * The fn.transfers.presignedUpload procedure body (api_route
+ * `fn-transfers-presigned-upload`, authed: input + context). It replaces the
+ * FormData POST /api/transfers/upload mount for every UI caller: the browser
+ * asks for a SIGNED PUT URL for one key, uploads the bytes straight to the
+ * store, and persists the SERVABLE key — so the file never crosses the
+ * service and the call is one JSON request instead of a multipart body.
+ *
+ * The policy the mount carried lives here, and is the SAME policy: the
+ * MAX_FILE_SIZE / ALLOWED_TYPES refusals (with their 413/415 statuses intact
+ * through the ORPC codes below), the USER-scoped key scheme
+ * (`users/<userId>/<dir>/<dir-singular>-<ts>.<ext>`), the unknown-dir
+ * fallback to `uploads`, and the servable value returned as `url` with
+ * `thumbUrl` mirroring it (the stored value is the servable value —
+ * single-logo-pathway, so display code reads the column with no rewriting).
+ * The key is derived from `context.user.id`, never from input: a caller
+ * cannot mint a URL under another user's prefix.
+ *
+ * HONEST RESIDUAL: the size refusal reads the DECLARED fileSize, because the
+ * bytes no longer pass through here — the store enforces the signature's type
+ * and expiry, not a byte count. The mount's Content-Length check was equally
+ * a declared-value check (an attacker sent the bytes either way); what
+ * changes is that a lying client is now bounded by the URL's TTL instead of a
+ * boot-level body limit. A real byte bound belongs to the bucket, not to this
+ * handler.
+ */
+import { getAppLogger } from "@teamscala/logger/app-loggers";
+import { getPresignedUrl } from "@teamscala/object-storage/create/presigned-url";
+import { ServiceError } from "@teamscala/os/errors/service-error";
+
+const MAX_FILE_SIZE = 25 * 1024 * 1024; // 25MB — the mount's bound, unchanged
+const ALLOWED_TYPES = new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp",
+	"image/svg+xml",
+	"application/pdf",
+	"video/mp4",
+	"video/webm",
+	"text/csv",
+	"text/plain",
+]);
+// `dir` → S3 key sub-directory. Unknown/absent → "uploads" (the mount's
+// TYPE_DIR semantics: cloud-drive and any future dir land under uploads until
+// a directory is declared here).
+const TYPE_DIR: Record<string, string> = {
+	avatars: "avatars",
+	logos: "logos",
+	uploads: "uploads",
+};
+
+// The window the browser has to PUT after the URL is minted. Short by design:
+// the URL is requested and used in the same breath, and a shorter TTL bounds
+// what a leaked URL is worth.
+const PRESIGN_EXPIRES_IN_SECONDS = 900;
+
+export interface PresignedUploadInput {
+	fileName: string;
+	fileType?: string;
+	fileSize: number;
+	dir?: string;
+}
+
+export interface PresignedUploadResult {
+	/** The signed URL the bytes are PUT to. */
+	uploadUrl: string;
+	/** The store key the bytes land on. */
+	key: string;
+	/** The SERVABLE value to persist — /api/assets/<key>. */
+	url: string;
+	/** Mirrors url (see the upload system's single-pathway note). */
+	thumbUrl: string;
+	/** When uploadUrl stops working, ISO 8601. */
+	expiresAt: string;
+}
+
+interface PresignedUploadContext {
+	user?: { id?: string };
+}
+
+function extOf(filename: string, fallback = "bin"): string {
+	const m = filename.match(/\.([a-z0-9]+)$/i);
+	return (m?.[1] ?? fallback).toLowerCase();
+}
+
+export async function presignedUpload(
+	input: PresignedUploadInput,
+	context: PresignedUploadContext,
+): Promise<PresignedUploadResult> {
+	const userId = context?.user?.id;
+	if (!userId) {
+		throw new ServiceError({
+			code: "UNAUTHORIZED",
+			message: "Authentication required",
+			service: "transfers-presigned-upload",
+		});
+	}
+
+	if (!input?.fileName || input.fileName.length === 0) {
+		throw new ServiceError({
+			code: "BAD_REQUEST",
+			message: "'fileName' is required",
+			service: "transfers-presigned-upload",
+		});
+	}
+	if (!(input.fileSize > 0)) {
+		throw new ServiceError({
+			code: "BAD_REQUEST",
+			message: "empty file",
+			service: "transfers-presigned-upload",
+		});
+	}
+	if (input.fileSize > MAX_FILE_SIZE) {
+		throw new ServiceError({
+			code: "PAYLOAD_TOO_LARGE",
+			message: "file too large (max 25MB)",
+			service: "transfers-presigned-upload",
+		});
+	}
+	// An ABSENT type is allowed (the mount only checked a type it was given);
+	// a PRESENT one must be on the allowlist.
+	if (input.fileType && !ALLOWED_TYPES.has(input.fileType)) {
+		throw new ServiceError({
+			code: "UNSUPPORTED_MEDIA_TYPE",
+			message: `file type '${input.fileType}' not allowed`,
+			service: "transfers-presigned-upload",
+		});
+	}
+
+	const dir = TYPE_DIR[input.dir ?? "uploads"] ?? "uploads";
+	const ext = extOf(input.fileName);
+	const key = `users/${userId}/${dir}/${dir.slice(0, -1)}-${Date.now()}.${ext}`;
+
+	const signed = await getPresignedUrl({
+		key,
+		operation: "put",
+		expiresIn: PRESIGN_EXPIRES_IN_SECONDS,
+		...(input.fileType ? { contentType: input.fileType } : {}),
+	});
+	if (!signed.success || !signed.url) {
+		getAppLogger().error("transfers-presigned-upload", {
+			error: signed.error,
+			key,
+		});
+		throw new ServiceError({
+			code: "INTERNAL_SERVER_ERROR",
+			message: signed.error ?? "could not sign an upload URL",
+			service: "transfers-presigned-upload",
+		});
+	}
+
+	const storedUrl = `/api/assets/${key}`;
+	return {
+		uploadUrl: signed.url,
+		key,
+		url: storedUrl,
+		thumbUrl: storedUrl,
+		expiresAt: (signed.expiresAt ?? new Date(Date.now() + PRESIGN_EXPIRES_IN_SECONDS * 1000)).toISOString(),
+	};
+}

package/src/two-phase-minimal-app.test.ts

@@ -0,0 +1,24 @@
+/**
+ * @status generated — ts-api-smoke template (scala-test-suites
+ * templates/ts_api_smoke.pkl @1.3.0) over the exports map of @teamscala/service-boot.
+ * ./two-phase-minimal-app declares 1 runtime export(s) + 1 type(s);
+ * this suite asserts the import resolves, the runtime surface matches
+ * exactly, and every export carries its declared kind. Regenerate from
+ * inputs/bun-server-service-boot/api_smoke.json (scala-test-suites) — hand edits are
+ * overwritten.
+ */
+
+import { describe, expect, it } from "bun:test";
+
+const mod = await import("./two-phase-minimal-app");
+
+describe("two-phase-minimal-app exports-map smoke", () => {
+	it("the runtime export set is exactly the declared surface", () => {
+		expect(Object.keys(mod).sort()).toEqual([
+			"buildMinimalApp",
+		]);
+	});
+	it("buildMinimalApp is a function", () => {
+		expect(typeof mod["buildMinimalApp"]).toBe("function");
+	});
+});