@velora-cms/server 0.11.0 → 0.12.1

package/dist/media/media-service.d.ts

@@ -1,14 +1,9 @@
+import type { Readable } from "node:stream";
 import type { Prisma, PrismaClient } from "@prisma/client";
-import type { MediaFile } from "@velora-cms/api-schemas";
+import type { MediaFile, MediaVisibility } from "@velora-cms/api-schemas";
 import type { Dialect } from "@velora-cms/prisma-variants";
-export interface MediaStorageConfig {
-    endpoint: string;
-    region: string;
-    accessKeyId: string;
-    secretAccessKey: string;
-    bucket: string;
-}
-export declare function mediaStorageConfigFromEnv(): MediaStorageConfig;
+import type { MediaStorage } from "./storage/types.js";
+export declare function resolveMediaStorage(env?: NodeJS.ProcessEnv): MediaStorage;
 export interface MediaUploadInput {
     filename: string;
     mimeType: string;
@@ -17,11 +12,10 @@ export interface MediaUploadInput {
 }
 export declare class MediaService {
     private readonly prisma;
-    private readonly config;
+    private readonly storage;
     private readonly dialect;
-    private readonly s3;
-    constructor(prisma: PrismaClient, config: MediaStorageConfig, dialect: Dialect);
-    ensureBucket(): Promise<void>;
+    constructor(prisma: PrismaClient, storage: MediaStorage, dialect: Dialect);
+    ensureReady(): Promise<void>;
     upload(input: MediaUploadInput): Promise<MediaFile>;
     getById(id: string): Promise<MediaFile | null>;
     list(options: {
@@ -29,8 +23,13 @@ export declare class MediaService {
         limit: number;
         search?: string;
     }): Promise<MediaFile[]>;
-    getDownloadUrl(id: string, expiresInSeconds?: number): Promise<string>;
+    getDownloadUrl(id: string): Promise<string>;
+    getStream(id: string): Promise<{
+        stream: Readable;
+        size?: number;
+    }>;
     delete(id: string): Promise<void>;
-    private canonicalUrl;
+    setVisibility(id: string, visibility: MediaVisibility): Promise<MediaFile>;
 }
 export declare function buildFilenameSearchFilter(search: string, dialect: Dialect): Prisma.StringFilter;
+export declare function sanitizeForKey(filename: string): string;

package/dist/media/media-service.js

@@ -1,24 +1,47 @@
 import { randomUUID } from "node:crypto";
-import { CreateBucketCommand, DeleteObjectCommand, GetObjectCommand, HeadBucketCommand, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
-import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
-// Defaults match the minio service in docker-compose.yml (same treatment as
-// POSTGRES_TEST_URL), so local dev works with zero required config. Point
-// these at real S3/R2 via .env — see .env.example.
-export function mediaStorageConfigFromEnv() {
-    return {
-        endpoint: process.env.S3_ENDPOINT ?? "http://localhost:9000",
-        region: process.env.S3_REGION ?? "us-east-1",
-        accessKeyId: process.env.S3_ACCESS_KEY_ID ?? "velora",
-        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY ?? "velora-secret",
-        bucket: process.env.S3_BUCKET ?? "velora-media",
-    };
+import { mintMediaToken } from "./media-tokens.js";
+import { LocalDiskStorage } from "./storage/local.js";
+import { S3Storage, s3ConfigFromEnv } from "./storage/s3.js";
+// Driver selection (S186c §1): MEDIA_STORAGE explicit wins; otherwise ANY
+// S3_* var being set means this deployment configured S3, so pick s3;
+// with nothing set at all, a fresh scaffold gets local disk. This is the
+// fix for the landmine where a stranger's first boot silently dialed the
+// dev-only MinIO default at localhost:9000 (previously baked into
+// S3-config defaults regardless of whether S3 was ever requested) — the
+// defaults in s3ConfigFromEnv now only apply once this function has
+// already decided s3 is the active driver.
+export function resolveMediaStorage(env = process.env) {
+    // LOW-8: an empty-string MEDIA_STORAGE (e.g. a stray `MEDIA_STORAGE=`
+    // line in .env) is "unset," not a third explicit value — same
+    // empty-means-unset convention hasAnyS3Var applies to the S3_* vars.
+    const explicit = env.MEDIA_STORAGE || undefined;
+    if (explicit !== undefined && explicit !== "local" && explicit !== "s3") {
+        throw new Error(`Unknown MEDIA_STORAGE "${explicit}" — expected "local" or "s3".`);
+    }
+    const driver = explicit ??
+        (hasAnyS3Var(env) ? "s3" : "local");
+    return driver === "s3"
+        ? new S3Storage(s3ConfigFromEnv(env))
+        : new LocalDiskStorage(env.MEDIA_DIR || "./media");
+}
+// LOW-8: empty string counts as unset for every S3_* var, same as
+// MEDIA_STORAGE above — otherwise a scaffold with a blank `S3_ENDPOINT=`
+// left over in .env would silently flip the driver to s3.
+function hasAnyS3Var(env) {
+    return (isSet(env.S3_ENDPOINT) ||
+        isSet(env.S3_BUCKET) ||
+        isSet(env.S3_ACCESS_KEY_ID) ||
+        isSet(env.S3_SECRET_ACCESS_KEY) ||
+        isSet(env.S3_REGION));
+}
+function isSet(value) {
+    return value !== undefined && value !== "";
 }
 export class MediaService {
     prisma;
-    config;
+    storage;
     dialect;
-    s3;
-    constructor(prisma, config, 
+    constructor(prisma, storage, 
     // Which Prisma provider the injected client is actually querying against
     // (postgresql | mysql | sqlite) — needed by list()'s search filter,
     // see buildFilenameSearchFilter below. Passed in rather than
@@ -27,40 +50,19 @@ export class MediaService {
     // the real app, a literal in tests).
     dialect) {
         this.prisma = prisma;
-        this.config = config;
+        this.storage = storage;
         this.dialect = dialect;
-        this.s3 = new S3Client({
-            endpoint: config.endpoint,
-            region: config.region,
-            credentials: {
-                accessKeyId: config.accessKeyId,
-                secretAccessKey: config.secretAccessKey,
-            },
-            // MinIO and R2 route by path, not by bucket subdomain — and a
-            // localhost endpoint can't do virtual-hosted buckets at all.
-            forcePathStyle: true,
-        });
     }
-    // Idempotent; safe to call on startup or from tests. Only creates the
-    // bucket when it doesn't exist yet.
-    async ensureBucket() {
-        try {
-            await this.s3.send(new HeadBucketCommand({ Bucket: this.config.bucket }));
-        }
-        catch {
-            await this.s3.send(new CreateBucketCommand({ Bucket: this.config.bucket }));
-        }
+    // Idempotent; safe to call on startup or from tests. Driver-aware: local
+    // disk mkdirs the media directory, s3 confirms/creates the bucket (and
+    // fails loudly if unreachable — see S3Storage.ensureReady).
+    async ensureReady() {
+        await this.storage.ensureReady();
     }
     async upload(input) {
         const id = randomUUID();
         const storageKey = `${id}/${sanitizeForKey(input.filename)}`;
-        await this.s3.send(new PutObjectCommand({
-            Bucket: this.config.bucket,
-            Key: storageKey,
-            Body: input.data,
-            ContentType: input.mimeType,
-            ContentLength: input.data.length,
-        }));
+        await this.storage.put(storageKey, input.data, input.mimeType);
         try {
             const row = await this.prisma.mediaFile.create({
                 data: {
@@ -69,7 +71,12 @@ export class MediaService {
                     mimeType: input.mimeType,
                     size: input.data.length,
                     storageKey,
-                    url: this.canonicalUrl(storageKey),
+                    // M5: url is COMPUTED from id+filename (see toMediaFile /
+                    // stableMediaPath below), never read back from this column —
+                    // the schema keeps a NOT NULL `url` this task (untouched), so
+                    // this write is inert filler, not a value anything trusts.
+                    // storageKey is the honest "what got written here" value.
+                    url: storageKey,
                     uploadedBy: input.uploadedBy,
                 },
             });
@@ -78,9 +85,7 @@ export class MediaService {
         catch (error) {
             // Metadata is the source of truth — don't leave an object around that
             // no metadata row points to.
-            await this.s3
-                .send(new DeleteObjectCommand({ Bucket: this.config.bucket, Key: storageKey }))
-                .catch(() => undefined);
+            await this.storage.delete(storageKey).catch(() => undefined);
             throw error;
         }
     }
@@ -102,28 +107,72 @@ export class MediaService {
         });
         return rows.map(toMediaFile);
     }
-    // Time-limited presigned GET — works against private buckets, which is
-    // why downloads go through this rather than the stored canonical url.
-    async getDownloadUrl(id, expiresInSeconds = 900) {
+    // The stable app path — NOT a time-limited presigned URL (S186c §1/§3).
+    // The old presigned-URL mechanism expired in 15 minutes even for public
+    // media, which silently broke embedded links.
+    //
+    // PUBLIC items: the same path forever for a given id+filename — the
+    // GET /media/:id/:filename route (media-public.ts) serves it straight
+    // from the driver, no auth required.
+    //
+    // PRIVATE items: that same path PLUS a freshly minted, short-lived
+    // `?token=` (media-tokens.ts's mintMediaToken, S186c §3) — a NEW token
+    // every call, so this value is for immediate use (an admin list/detail
+    // response rendering an `<img src>` right now), not for persisting or
+    // reusing across requests. The dedicated "Copy temporary link" mint
+    // (POST /api/media/:id/link, routes/media.ts) is the caller-facing way
+    // to get a link meant to be saved/shared.
+    async getDownloadUrl(id) {
+        const row = await this.prisma.mediaFile.findUnique({ where: { id } });
+        if (!row) {
+            throw new Error(`Media file not found: ${id}`);
+        }
+        const path = stableMediaPath(row.id, row.filename);
+        if (row.visibility === "private") {
+            const { token } = mintMediaToken(row.id);
+            return `${path}?token=${encodeURIComponent(token)}`;
+        }
+        return path;
+    }
+    // Streams the object's bytes straight from the active driver — used by
+    // the (future) /media/:id/:filename route and directly by tests that
+    // need to assert real content round-trips without going through HTTP.
+    async getStream(id) {
         const row = await this.prisma.mediaFile.findUnique({ where: { id } });
         if (!row) {
             throw new Error(`Media file not found: ${id}`);
         }
-        return getSignedUrl(this.s3, new GetObjectCommand({ Bucket: this.config.bucket, Key: row.storageKey }), { expiresIn: expiresInSeconds });
+        return this.storage.getStream(row.storageKey);
     }
     async delete(id) {
         const row = await this.prisma.mediaFile.findUnique({ where: { id } });
         if (!row) {
             throw new Error(`Media file not found: ${id}`);
         }
-        await this.s3.send(new DeleteObjectCommand({ Bucket: this.config.bucket, Key: row.storageKey }));
+        await this.storage.delete(row.storageKey);
         await this.prisma.mediaFile.delete({ where: { id } });
     }
-    canonicalUrl(storageKey) {
-        const encodedKey = storageKey.split("/").map(encodeURIComponent).join("/");
-        return `${this.config.endpoint.replace(/\/$/, "")}/${this.config.bucket}/${encodedKey}`;
+    // Flips the visibility flag (S186c §2) — updates the row only, never the
+    // storage key or the computed URL, in either driver. Throws the same
+    // "not found" shape as delete()/getDownloadUrl() above so routes/media.ts
+    // can turn it into a 404 with no existence oracle either way.
+    async setVisibility(id, visibility) {
+        const row = await this.prisma.mediaFile.findUnique({ where: { id } });
+        if (!row) {
+            throw new Error(`Media file not found: ${id}`);
+        }
+        const updated = await this.prisma.mediaFile.update({ where: { id }, data: { visibility } });
+        return toMediaFile(updated);
     }
 }
+// `/media/<id>/<filename>` — the stable app path from S186c §3, computed
+// from the row rather than stored, so it never has an absolute host/port/
+// endpoint baked in to go stale. filename is the ORIGINAL (unsanitized)
+// name, not the storage key's sanitized segment — the future route
+// verifies it against the stored filename rather than trusting it.
+function stableMediaPath(id, filename) {
+    return `/media/${encodeURIComponent(id)}/${encodeURIComponent(filename)}`;
+}
 // Case-insensitive filename search, built per the active Prisma provider's
 // verified capabilities (Session 131 walkthrough, task-4-report.md step 13
 // — SQLite 500'd here because `mode: "insensitive"` isn't a real argument
@@ -145,8 +194,10 @@ export function buildFilenameSearchFilter(search, dialect) {
     return dialect === "postgresql" ? { contains: search, mode: "insensitive" } : { contains: search };
 }
 // Original filename lives untouched in metadata; the object key only keeps
-// characters that are safe in S3 keys and URLs.
-function sanitizeForKey(filename) {
+// characters that are safe in S3 keys and URLs. Exported for routes/media.ts
+// (LOW-11) to reuse the exact same "does this collapse to something inert"
+// check the upload path itself uses, rather than re-deriving it.
+export function sanitizeForKey(filename) {
     return filename.replace(/[^A-Za-z0-9._-]/g, "_");
 }
 function toMediaFile(row) {
@@ -155,7 +206,18 @@ function toMediaFile(row) {
         filename: row.filename,
         mimeType: row.mimeType,
         size: row.size,
-        url: row.url,
+        // M5: computed, never read from row.url — old rows can carry a
+        // stale absolute value (a past presigned/S3 URL, a defaulted MinIO
+        // endpoint, etc.) that would otherwise leak straight into the API
+        // response. See stableMediaPath's doc comment.
+        url: stableMediaPath(row.id, row.filename),
+        // Prisma types this column as a plain string (schema.prisma has no
+        // native enum for it, matching the Role-enum-avoidance pattern
+        // elsewhere in this file's dialect notes) — the column is written
+        // exclusively through setVisibility/the Prisma default, both of which
+        // only ever store "public"/"private", so this cast reflects an
+        // invariant this module already enforces, not an unchecked read.
+        visibility: row.visibility,
         uploadedBy: row.uploadedBy,
         uploadedAt: row.uploadedAt.toISOString(),
     };

package/dist/media/media-tokens.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_MEDIA_LINK_TTL_SECONDS = 900;
+export declare function mintMediaToken(id: string, expiresInSeconds?: number, nowMs?: number): {
+    token: string;
+    expiresAt: string;
+};
+export declare function verifyMediaToken(id: string, token: string, nowMs?: number): boolean;

package/dist/media/media-tokens.js

@@ -0,0 +1,88 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+// Signed, short-lived media links (S186c §3) — the mechanism behind
+// "Copy temporary link" and the private branch of GET /media/:id/:filename.
+// Deliberately NOT a JWT and NOT the admin session (api-design.md: never
+// conflate a headless/short-lived token with a logged-in session) — same
+// shape as auth/preview-tokens.ts's mintPreviewToken/verifyPreviewToken,
+// applied to media ids instead of content ids:
+//
+//   base64url(JSON{id, exp}) + "." + base64url(hmacSignature)
+//
+// Exactly ONE dot, so a real two-dot JWT can never be mistaken for one
+// (and vice versa) — same defense-by-construction as preview tokens.
+//
+// The signing key is a fixed derivation of JWT_SECRET under its own label
+// ("velora-media-link", distinct from preview-tokens.ts's
+// "velora-preview-token") so a leaked media link can never be replayed as
+// a preview token or an admin JWT, and vice versa: three disjoint
+// keyspaces from one root secret. Derived fresh per call, never cached —
+// tests toggle JWT_SECRET across calls in the same run, and caching would
+// silently keep signing/verifying with a stale key.
+const DERIVATION_LABEL = "velora-media-link";
+// Default TTL (S186c §3: "short-lived ... default 15 min"). No env
+// override today — mintMediaToken's own `expiresInSeconds` parameter is
+// the extension point (the mint route always calls it with the default;
+// nothing currently needs a longer/shorter link).
+export const DEFAULT_MEDIA_LINK_TTL_SECONDS = 900;
+function derivedKey() {
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        throw new Error("JWT_SECRET must be set — see .env.example");
+    }
+    return createHmac("sha256", secret).update(DERIVATION_LABEL).digest();
+}
+function sign(payloadB64) {
+    return createHmac("sha256", derivedKey()).update(payloadB64).digest("base64url");
+}
+// nowMs defaults to Date.now() but is overridable — same reason
+// preview-tokens.ts exposes it: deterministic expiry tests with no fake
+// timers.
+export function mintMediaToken(id, expiresInSeconds = DEFAULT_MEDIA_LINK_TTL_SECONDS, nowMs = Date.now()) {
+    const exp = Math.floor(nowMs / 1000) + expiresInSeconds;
+    const payload = { id, exp };
+    const payloadB64 = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    const signatureB64 = sign(payloadB64);
+    return {
+        token: `${payloadB64}.${signatureB64}`,
+        expiresAt: new Date(exp * 1000).toISOString(),
+    };
+}
+// Returns false for EVERY failure mode — malformed shape, bad signature,
+// expired, a token minted for a DIFFERENT media id, JWT_SECRET missing —
+// with no distinction between them and never a thrown error. The media
+// route (media-public.ts) relies on this never throwing: a bad `?token=`
+// on an otherwise-valid request must fall through to the same 404 as a
+// missing token, not 500 the request. `id` is the id from the route's own
+// :id param — verifying it against the token's embedded id is what makes
+// a token minted for item A rejected outright when presented against
+// item B's URL (wrong-id), not just against a mismatched signature.
+export function verifyMediaToken(id, token, nowMs = Date.now()) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 2)
+            return false;
+        const [payloadB64, signatureB64] = parts;
+        if (!payloadB64 || !signatureB64)
+            return false;
+        const expectedSignatureB64 = sign(payloadB64);
+        const presented = Buffer.from(signatureB64, "base64url");
+        const expected = Buffer.from(expectedSignatureB64, "base64url");
+        // Length-check before timingSafeEqual: it throws on mismatched buffer
+        // lengths rather than returning false, and skipping this check would
+        // itself be a length side-channel.
+        if (presented.length !== expected.length || !timingSafeEqual(presented, expected)) {
+            return false;
+        }
+        const payload = JSON.parse(Buffer.from(payloadB64, "base64url").toString());
+        if (typeof payload?.id !== "string" || typeof payload?.exp !== "number")
+            return false;
+        if (payload.id !== id)
+            return false;
+        if (nowMs >= payload.exp * 1000)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/media/storage/local.d.ts

@@ -0,0 +1,16 @@
+import type { Readable } from "node:stream";
+import { type MediaStorage } from "./types.js";
+export declare class LocalDiskStorage implements MediaStorage {
+    readonly kind: "local";
+    private readonly rootDir;
+    constructor(dir: string);
+    ensureReady(): Promise<void>;
+    put(key: string, data: Buffer, _mimeType: string): Promise<void>;
+    getStream(key: string): Promise<{
+        stream: Readable;
+        size?: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    private pathFor;
+}

package/dist/media/storage/local.js

@@ -0,0 +1,99 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { assertValidStorageKey, MediaNotFoundError } from "./types.js";
+// Scaffold default (S186c §1) — files live under MEDIA_DIR, next to the
+// site's velora.db, so backing up the project folder backs up its media
+// too. No object storage required for a shared-host / single-VPS site.
+export class LocalDiskStorage {
+    kind = "local";
+    rootDir;
+    constructor(dir) {
+        // Resolved against cwd, same convention as .env / MEDIA_DIR itself —
+        // a relative MEDIA_DIR means "next to wherever the process was
+        // started," matching how the rest of the app resolves relative paths.
+        this.rootDir = resolve(process.cwd(), dir);
+    }
+    async ensureReady() {
+        await mkdir(this.rootDir, { recursive: true });
+    }
+    async put(key, data, _mimeType) {
+        const finalPath = this.pathFor(key);
+        const dir = dirname(finalPath);
+        await mkdir(dir, { recursive: true });
+        // Temp-file-then-rename: a reader calling getStream/exists mid-write
+        // only ever sees either nothing or the complete file, never a torn
+        // one. Same-directory rename is atomic on both POSIX and NTFS.
+        const tempPath = join(dir, `.tmp-${randomUUID()}`);
+        try {
+            await writeFile(tempPath, data);
+            await rename(tempPath, finalPath);
+        }
+        catch (error) {
+            await rm(tempPath, { force: true });
+            throw error;
+        }
+    }
+    async getStream(key) {
+        const path = this.pathFor(key);
+        let stats;
+        try {
+            stats = await stat(path);
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new MediaNotFoundError(key);
+            throw error;
+        }
+        // A directory sitting at this path (e.g. the key names a prefix that
+        // legitimately holds other objects) is not a readable object —
+        // treated the same as "missing" from a caller's point of view.
+        if (!stats.isFile())
+            throw new MediaNotFoundError(key);
+        return { stream: createReadStream(path), size: stats.size };
+    }
+    async delete(key) {
+        try {
+            await unlink(this.pathFor(key));
+        }
+        catch (error) {
+            // Idempotent, matching S3 DeleteObject's native "no error either
+            // way" behavior — see the MediaStorage interface doc comment.
+            if (!isNotFound(error))
+                throw error;
+        }
+    }
+    async exists(key) {
+        try {
+            const stats = await stat(this.pathFor(key));
+            // A directory is not "an object that exists" from a caller's point
+            // of view — same isFile() gate as getStream.
+            return stats.isFile();
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return false;
+            throw error;
+        }
+    }
+    pathFor(key) {
+        // Keys are always server-generated (`<uuid>/<sanitized-filename>`,
+        // see sanitizeForKey in media-service.ts), never a raw user-supplied
+        // path fragment — but this validates BEFORE resolve() ever runs, so a
+        // hostile/buggy key is rejected outright rather than relying on the
+        // containment check below to catch whatever `..` walking it produces.
+        assertValidStorageKey(key);
+        const path = resolve(this.rootDir, key);
+        // No equality allowance: a key that resolves to exactly rootDir
+        // itself (e.g. via a validated-but-empty tail) is still "outside" any
+        // single object this driver should ever address.
+        if (!path.startsWith(this.rootDir + sep)) {
+            throw new Error(`Refusing to resolve media key outside MEDIA_DIR: ${key}`);
+        }
+        return path;
+    }
+}
+function isNotFound(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}

package/dist/media/storage/s3.d.ts

@@ -0,0 +1,25 @@
+import type { Readable } from "node:stream";
+import { type MediaStorage } from "./types.js";
+export interface S3StorageConfig {
+    endpoint: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucket: string;
+    endpointWasDefaulted?: boolean;
+}
+export declare function s3ConfigFromEnv(env?: NodeJS.ProcessEnv): S3StorageConfig;
+export declare class S3Storage implements MediaStorage {
+    private readonly config;
+    readonly kind: "s3";
+    private readonly client;
+    constructor(config: S3StorageConfig);
+    ensureReady(): Promise<void>;
+    put(key: string, data: Buffer, mimeType: string): Promise<void>;
+    getStream(key: string): Promise<{
+        stream: Readable;
+        size?: number;
+    }>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}