@hearthlog/tooling 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthlog/tooling",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "tsx": "^4.23.15",
-    "@hearthlog/contracts": "0.1.6"
+    "@hearthlog/contracts": "0.1.7"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

package/src/deploy/ensure-tenant.ts

@@ -108,6 +108,7 @@ import {
 import {
 	generateTenantWranglerConfigs,
 	moduleBindings,
+	serverDeclarations,
 	resolveFrontendWranglerTarget,
 } from "../tenants/wrangler-config.js";
 
@@ -694,7 +695,7 @@ async function ensureLedgerApp(
  * `LEDGER_ADMIN_TOKEN` environment variable is only the fallback when no Ledger was contacted (`--skip-ledger`).
  */
 export async function collectSecrets(
-	site: Pick<ResolvedSite, "id" | "admin" | "integrations">,
+	site: Pick<ResolvedSite, "id" | "admin" | "integrations"> & Partial<Pick<ResolvedSite, "features">>,
 	infrastructure: Pick<InfrastructureDefinition, "accessTeamDomain">,
 	ledgerToken: string | null,
 	accessAud: string | undefined,
@@ -718,10 +719,26 @@ export async function collectSecrets(
 	// The renderer's credential comes from the operator's environment; without one the renderer routes answer 503.
 	const rendererToken = process.env.INVOICE_RENDERER_TOKEN?.trim();
 	if (rendererToken) secrets.INVOICE_RENDERER_TOKEN = rendererToken;
-	Object.assign(secrets, extractionSecretsFromEnvironment());
+	Object.assign(secrets, extractionSecretsFromEnvironment(), moduleSecretsFromEnvironment(site.id, serverDeclarations(site.features ?? [])));
 	return secrets;
 }
 
+/** Site-scoped operator variables take precedence when provisioning several gateways. Values never enter generated files. */
+export function moduleSecretsFromEnvironment(
+    siteId: string,
+    servers: ReadonlyArray<{ secrets?: ReadonlyArray<{ name: string }> }>,
+    environment: Record<string, string | undefined> = process.env,
+): Record<string, string> {
+    const result: Record<string, string> = {};
+    const suffix = siteId.toUpperCase().replace(/-/g, '_');
+    for (const server of servers) for (const { name } of server.secrets ?? []) {
+        const value = environment[`${name}_${suffix}`]?.trim() || environment[name]?.trim();
+        if (!value) throw new TenantConfigError(`Site ${siteId}: supply ${name}_${suffix} (or ${name}) in the operator environment before setting module secrets`);
+        result[name] = value;
+    }
+    return result;
+}
+
 /**
  * Vertex AI credentials for AI invoice reading. Absent credentials are not a
  * failure: the feature answers 503 and the UI hides itself.

package/src/init/check-module.ts

@@ -43,6 +43,14 @@ export function assembleCheckSite(options: Required<Pick<CheckModuleOptions, "di
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, content, "utf8");
     }
+    // Required external module variables need harmless placeholders in this isolated build, not operator storage.
+    const configPath = join(options.work, "tenants.json");
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    for (const variable of loaded.manifest.server?.vars ?? []) {
+        if (variable.optional || config.infrastructure[variable.resource]) continue;
+        config.infrastructure[variable.resource] = /Endpoint$|Origin$/.test(variable.resource) ? 'https://storage.example.invalid' : /Region$/.test(variable.resource) ? 'us-east-1' : 'module-check-storage';
+    }
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
     const manifestPath = join(options.work, "package.json");
     const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { dependencies: Record<string, string> };
     manifest.dependencies[name] = `file:${directory}`;
@@ -82,6 +90,12 @@ export function testConfig(directory: string, work: string): string {
         { find: "$tenant/generated", replacement: join(work, ".generated", "sites", "st", "tenant.ts") },
         { find: /^\$app\/.*/ as unknown as string, replacement: join(work, "app-stub.mjs") },
     ];
+    // Test the same platform the composed site built, including unreleased --overrides, rather than the module's older dev dependency.
+    const sdk = join(work, "node_modules", "@hearthlog", "sdk");
+    const sdkManifest = JSON.parse(readFileSync(join(sdk, "package.json"), "utf8")) as { exports: Record<string, string> };
+    for (const [entry, file] of Object.entries(sdkManifest.exports)) {
+        if (entry.startsWith('./') && typeof file === 'string') alias.push({ find: `@hearthlog/sdk/${entry.slice(2)}`, replacement: join(sdk, file) });
+    }
     const stub = join(work, "node_modules", "@hearthlog", "cloudflare", "src", "testing", "cloudflare-workers.ts");
     if (existsSync(stub)) alias.push({ find: "cloudflare:workers", replacement: stub });
     const options = JSON.stringify({ root: directory, resolve: { alias } }, null, 2).replace('"find": {}', '"find": /^\\$app\\/.*/');

package/src/security/audit-push.ts

@@ -30,7 +30,7 @@ export interface PushFinding {
     detail: string;
 }
 
-const SAFE_NOREPLY = /^(?:noreply@github\.com|[0-9]*\+?[a-z0-9-]+@users\.noreply\.github\.com)$/i;
+const SAFE_NOREPLY = /^(?:noreply@github\.com|[0-9]*\+?[a-z0-9-]+(?:\[bot\])?@users\.noreply\.github\.com)$/i;
 
 /** Every file under the directory except `.git`, as relative paths. */
 export function listFiles(directory: string): string[] {

package/src/tenants/tenant-config.ts

@@ -54,6 +54,11 @@ export interface SiteTheme {
 }
 
 export interface SiteDefinition {
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    stashMediaProxy?: string;
+
     id: string;
     ledgerAppName?: string;
     admin?: boolean;
@@ -95,6 +100,12 @@ export interface InfrastructureDefinition {
     galleryPublicBucket: string;
     galleryPublicWorker: string;
     galleryPublicOrigin: string;
+    /** Private S3-compatible video storage, provisioned separately by the site operator. */
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    /** "1" streams playback through the gateway instead of redirecting to storage. */
+    stashMediaProxy?: string;
     /** The account's workers.dev subdomain, for example `example.workers.dev`; Worker URLs derive from it. */
     workersDevDomain: string;
     /** The invoice renderer's HTTPS origin; Invoices answers 503 without one. */
@@ -119,6 +130,13 @@ export interface InfrastructureDefinition {
 
 /** `tenants/<site>/deployment.json`: a site that runs on its own stack. */
 export interface SiteDeployment {
+    /** Private S3-compatible video storage, provisioned separately by the site operator. */
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    /** "1" streams playback through the gateway instead of redirecting to storage. */
+    stashMediaProxy?: string;
+
     schemaVersion: 1;
     /**
      * Prefix of every resource the site owns, starting with the site id, for
@@ -160,6 +178,11 @@ export interface TenantFile {
 }
 
 export interface ResolvedSite {
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    stashMediaProxy?: string;
+
     id: string;
     ledgerAppName: string;
     features: FeatureId[];
@@ -208,10 +231,12 @@ const SITE_KEYS = [
     "dynamicEntities",
     "theme",
     "hostname",
+    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
 ] as const satisfies readonly (keyof SiteDefinition)[];
 const DEPLOYMENT_KEYS = [
     "$schema", "schemaVersion", "resourcePrefix", "ledger", "accountId", "workersDevDomain", "authentication",
     "ledgerAdminEmail", "invoiceRendererOrigin", "kalApiOrigin", "accessSessionDuration", "accessGlobalSessionDuration",
+    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
 ] as const;
 const TENANT_FILE_KEYS = ["$schema", "schemaVersion", ...SITE_KEYS] as const;
 const WORKERS_DEV_PATTERN = /^[a-z0-9][a-z0-9-]*\.workers\.dev$/;
@@ -240,6 +265,7 @@ const INFRASTRUCTURE_KEYS = [
     "accessSessionDuration",
     "accessGlobalSessionDuration",
     "gallerySweeper",
+    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
     "accountId",
 ] as const satisfies readonly (keyof InfrastructureDefinition)[];
 
@@ -491,6 +517,7 @@ export function parseSiteDeployment(
         requireSessionDuration(`${label} ${key}`, duration);
         result[key] = duration;
     }
+    Object.assign(result, parseStashMediaConfiguration(deployment, label));
     if (options.standalone) {
         for (const key of ["workersDevDomain", "ledgerAdminEmail", "authentication"] as const) {
             if (result[key] === undefined) throw new TenantConfigError(`${label}: ${key} is required when there is no tenants.json`);
@@ -499,6 +526,22 @@ export function parseSiteDeployment(
     return result;
 }
 
+/** Validate optional media settings without requiring storage for sites that do not enable it. */
+export function parseStashMediaConfiguration(value: Partial<InfrastructureDefinition>, label: string): Partial<InfrastructureDefinition> {
+    const result: Partial<InfrastructureDefinition> = {};
+    for (const key of ['stashMediaEndpoint', 'stashMediaBucket', 'stashMediaRegion', 'stashMediaProxy'] as const) {
+        const text = value[key];
+        if (text === undefined) continue;
+        if (typeof text !== 'string' || !text.trim()) throw new TenantConfigError(`${label}.${key} must be a non-empty string`);
+        if (key === 'stashMediaEndpoint') requireHttpsOrigin(`${label}.${key}`, text);
+        if (key === 'stashMediaBucket' && !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(text)) throw new TenantConfigError(`${label}.${key} must be an S3 bucket name`);
+        if (key === 'stashMediaRegion' && !/^[a-z0-9-]+$/.test(text)) throw new TenantConfigError(`${label}.${key} must be an S3 region`);
+        if (key === 'stashMediaProxy' && !['0', '1'].includes(text)) throw new TenantConfigError(`${label}.${key} must be 0 or 1`);
+        result[key] = text;
+    }
+    return result;
+}
+
 function requireSessionDuration(label: string, duration: unknown): asserts duration is string {
     if (typeof duration !== "string" || !/^[1-9]\d*h$/.test(duration) || Number(duration.slice(0, -1)) > 720) {
         throw new TenantConfigError(`${label} must be whole hours between 1h and 720h`);
@@ -527,10 +570,10 @@ export function workersDevDomainFor(site: Pick<ResolvedSite, "deployment">, shar
  * every name from its resource prefix. Account-wide settings stay shared.
  */
 export function infrastructureFor(
-    site: Pick<ResolvedSite, "deployment">,
+    site: Pick<ResolvedSite, "deployment"> & Partial<Pick<ResolvedSite, "stashMediaEndpoint" | "stashMediaBucket" | "stashMediaRegion" | "stashMediaProxy">>,
     shared: InfrastructureDefinition,
 ): InfrastructureDefinition {
-    if (!site.deployment) return shared;
+    if (!site.deployment) return { ...shared, ...parseStashMediaConfiguration(site, "site") };
     const prefix = site.deployment.resourcePrefix;
     const origin = (worker: string) => `https://${worker}.${workersDevDomainFor(site, shared)}`;
     const names = {
@@ -547,6 +590,8 @@ export function infrastructureFor(
     return {
         ...shared,
         ...names,
+        ...parseStashMediaConfiguration(site.deployment, "site deployment"),
+        ...parseStashMediaConfiguration(site, "site"),
         workersDevDomain: workersDevDomainFor(site, shared),
         ...(site.deployment.authentication ? { accessTeamDomain: site.deployment.authentication.teamDomain } : {}),
         ...(site.deployment.ledgerAdminEmail ? { ledgerAdminEmail: site.deployment.ledgerAdminEmail } : {}),
@@ -670,6 +715,7 @@ export function resolveSite(
     return {
         id: site.id,
         ledgerAppName: site.ledgerAppName ?? site.id,
+        ...parseStashMediaConfiguration(site, label),
         features: [...features],
         ai: [...ai],
         integrations,
@@ -824,6 +870,7 @@ export function resolveInfrastructure(
         const duration = infrastructure[key];
         if (duration !== undefined) requireSessionDuration(`tenants.json infrastructure.${key}`, duration);
     }
+    parseStashMediaConfiguration(infrastructure, "tenants.json infrastructure");
     return infrastructure;
 }
 

package/src/tenants/tenant-schema.ts

@@ -78,6 +78,10 @@ export function buildTenantSchema(): Record<string, unknown> {
                     workersDevDomain: { type: "string", pattern: "^[a-z0-9][a-z0-9-]*\\.workers\\.dev$", description: "The account's workers.dev subdomain." },
                     invoiceRendererOrigin: httpsOrigin,
                     kalApiOrigin: httpsOrigin,
+                    stashMediaEndpoint: httpsOrigin,
+                    stashMediaBucket: nonEmptyString,
+                    stashMediaRegion: nonEmptyString,
+                    stashMediaProxy: { enum: ["0", "1"] },
                     ledgerAdminEmail: { type: "string", format: "email" },
                     accessTeamDomain: httpsOrigin,
                     accessSessionDuration: hours,
@@ -140,6 +144,10 @@ export function buildTenantSchema(): Record<string, unknown> {
                             },
                         },
                         hostname: { type: "string", format: "uri" },
+                        stashMediaEndpoint: httpsOrigin,
+                        stashMediaBucket: nonEmptyString,
+                        stashMediaRegion: nonEmptyString,
+                        stashMediaProxy: { enum: ["0", "1"] },
                     },
                 },
             },

package/src/vite/config.ts

@@ -21,6 +21,7 @@ import {
 	localLedgerGatewayPath,
 	localLedgerOriginGuardPlugin,
 	localReceivedInvoiceFilesPlugin,
+	localStashMediaPlugin,
 } from './dev-plugins.js';
 
 import { defineConfig, searchForWorkspaceRoot, type ProxyOptions, type UserConfig } from 'vite';
@@ -275,6 +276,7 @@ return defineConfig(({ command, mode }): UserConfig => {
                 localLedgerOriginGuardPlugin(Boolean(localLedgerCredential)),
                 localInvoicePdfGatewayFallbackPlugin(Boolean(invoiceRendererToken)),
                 localReceivedInvoiceFilesPlugin(),
+                localStashMediaPlugin(localLedgerCredential),
                 localInvoiceExtractionPlugin(),
                 localAiDecisionsPlugin(isE2E),
                 e2eLedgerStubPlugin(isE2E),

package/src/vite/dev-plugins.ts

@@ -336,3 +336,42 @@ export async function readJsonBody(request: import('node:http').IncomingMessage)
         return undefined;
     }
 }
+
+/** Real S3 signing against loopback MinIO; no production credentials or Access bypass reach a deployed build. */
+export function localStashMediaPlugin(credential?: import('../dev/local-development.js').LocalLedgerCredential): Plugin {
+    return {
+        name: 'local-stash-media',
+        configureServer(server) {
+            server.middlewares.use(async (incoming, outgoing, next) => {
+                if (!incoming.url?.startsWith('/api/stash-media/v1/')) return next();
+                const respond = (status: number, message: string) => { outgoing.statusCode = status; outgoing.setHeader('Content-Type', 'application/json'); outgoing.end(JSON.stringify({ error: message, code: 'local_media_unavailable' })); };
+                if (!localGatewayOriginAllowed(incoming.headers.origin, incoming.headers.host) || incoming.headers['sec-fetch-site'] === 'cross-site') return respond(403, 'Cross-origin local media requests are not allowed');
+                if (!credential) return respond(503, 'Start the local Ledger and run ledger:provision-local before uploading videos locally');
+                try {
+                    const [{ loadModules }, { loadTenantConfig }, { activeSiteId }] = await Promise.all([import('../compose/compose-modules.js'), import('../tenants/tenant-config.js'), import('../root.js')]);
+                    const config = await loadTenantConfig(), site = config.sites.find(site => site.id === activeSiteId());
+                    const module = loadModules().find(module => module.manifest.server?.routes?.includes('/api/stash-media/v1') && module.manifest.features.some(feature => site?.features.some(enabled => enabled === feature.id)));
+                    if (!module) return respond(404, 'Video media is not enabled for this site');
+                    const endpoint = new URL(process.env.STASH_MEDIA_DEV_ENDPOINT || 'http://127.0.0.1:9000');
+                    if (!['localhost', '127.0.0.1', '[::1]'].includes(endpoint.hostname)) return respond(503, 'Development media storage must use a loopback MinIO endpoint');
+                    const { handleStashMediaRequest } = await server.ssrLoadModule(`${module.directory}/src/server/media.ts`);
+                    const chunks: Buffer[] = []; let size = 0;
+                    for await (const chunk of incoming) { size += chunk.length; if (size > 1024 * 1024) return respond(413, 'Media control request is too large'); chunks.push(Buffer.from(chunk)); }
+                    const headers = new Headers();
+                    for (const [name, value] of Object.entries(incoming.headers)) if (typeof value === 'string') headers.set(name, value);
+                    const request = new Request(new URL(incoming.url, `http://${incoming.headers.host}`), { method: incoming.method, headers, ...(size ? { body: Buffer.concat(chunks) } : {}) });
+                    const env = {
+                        STASH_MEDIA_ENDPOINT: endpoint.origin, STASH_MEDIA_BUCKET: 'hearthlog-dev', STASH_MEDIA_REGION: 'us-east-1',
+                        STASH_MEDIA_KEY_ID: 'hearthlog-local', STASH_MEDIA_APP_KEY: 'hearthlog-local-only', LEDGER_AUTH_TOKEN: credential.token,
+                        LEDGER: { fetch: (request: Request) => { const url = new URL(request.url); return fetch(new URL(`${url.pathname}${url.search}`, credential.baseUrl), { method: request.method, headers: request.headers }); } },
+                    };
+                    const response: Response = await handleStashMediaRequest(request, env, async () => ({ email: 'local@example.invalid' }));
+                    outgoing.statusCode = response.status;
+                    response.headers.forEach((value, name) => outgoing.setHeader(name, value));
+                    if (response.body) for await (const chunk of response.body) outgoing.write(chunk);
+                    outgoing.end();
+                } catch { respond(503, 'Local video storage is unavailable. Check that MinIO and the local Ledger are running'); }
+            });
+        },
+    };
+}