@selvajs/platform 0.14.2 → 0.14.3-beta.0

package/src/storage/assetClasses.ts

@@ -0,0 +1,134 @@
+import { ALL_ORG_ASSET_KINDS } from '../organizations/schemas.js';
+import { COVER_IMAGE_EXTENSIONS } from '../definitions/types.js';
+
+/**
+ * How a stored asset is allowed to be read. This is a property of the asset
+ * *class* (its path prefix), never of the individual file — so a logo and a
+ * pricing sheet differ only in which class they belong to, and adding a new
+ * asset type is one entry in {@link ASSET_CLASSES} rather than a new route.
+ *
+ * - `public`  — anyone, including logged-out visitors. Served with no auth via
+ *   a CDN/public bucket (Supabase) or a shape-gated proxy branch (local). Used
+ *   for branding (logo, favicon) that appears on viewer headers and login pages.
+ * - `org`     — members of the owning org only. The route resolves the orgId
+ *   from the path and runs an org-membership check. Used for org-private docs
+ *   (e.g. pricing sheets) once they exist.
+ * - `project` — members of the owning project only. The route resolves the
+ *   definition guid → its project and runs the project-view check. Used for
+ *   definition cover images and other per-definition blobs.
+ */
+export type AssetVisibility = 'public' | 'org' | 'project';
+
+/**
+ * What scope id the route must authorize against. `none` for public assets
+ * (no scope to check); `org`/`project` carry the id extracted from the path.
+ */
+export type AssetScope = 'none' | 'org' | 'project';
+
+export interface AssetClass {
+	/** Stable identifier — for logging and tests, not user-facing. */
+	readonly id: string;
+	readonly visibility: AssetVisibility;
+	readonly scope: AssetScope;
+	/**
+	 * Anchored matcher for this class's storage paths. Capture group 1 (when
+	 * present) is the scope id (orgId or guid) the route authorizes against.
+	 */
+	readonly pattern: RegExp;
+}
+
+export interface AssetMatch {
+	readonly class: AssetClass;
+	/** The scope id from the path, or null for `scope: 'none'` classes. */
+	readonly scopeId: string | null;
+}
+
+// Org branding kinds (logo, favicon, …) are the public set. Built from the
+// schema enum so adding a kind there extends this pattern automatically.
+const BRANDING_KINDS = ALL_ORG_ASSET_KINDS.join('|');
+
+// Cover extensions are derived from the canonical `COVER_IMAGE_EXTENSIONS`
+// (definitions/types.ts) — strip the leading dot and escape so adding a new
+// cover format there propagates here instead of silently 404ing legit covers.
+const COVER_EXTS = COVER_IMAGE_EXTENSIONS.map((ext) =>
+	ext.replace(/^\./, '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+).join('|');
+
+// Reusable segment alphabets. `SAFE_SEGMENT` mirrors the `assertSafeKey`
+// alphabet in the path helpers (traversal/empty segments are rejected
+// separately by `hasUnsafeSegment`); `GUID` is the canonical definition guid
+// shape — kept in sync with `UUID_REGEX` in definitions/schemas.ts.
+const SAFE_SEGMENT = String.raw`[A-Za-z0-9._-]+`;
+const GUID = String.raw`[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`;
+
+/**
+ * The closed registry of servable asset classes. Order matters only for
+ * readability — patterns are mutually exclusive by prefix. Anything that
+ * matches no class is unservable (the route 404s), which keeps the proxy
+ * default-deny: a new blob type is opt-in by adding an entry here.
+ */
+export const ASSET_CLASSES: readonly AssetClass[] = [
+	{
+		id: 'org-branding',
+		visibility: 'public',
+		scope: 'none',
+		pattern: new RegExp(
+			String.raw`^orgs\/(${SAFE_SEGMENT})\/branding\/(?:${BRANDING_KINDS})\.webp$`
+		)
+	},
+	{
+		id: 'org-private',
+		visibility: 'org',
+		scope: 'org',
+		pattern: new RegExp(String.raw`^orgs\/(${SAFE_SEGMENT})\/private\/${SAFE_SEGMENT}$`)
+	},
+	{
+		id: 'definition-cover',
+		visibility: 'project',
+		scope: 'project',
+		pattern: new RegExp(String.raw`^definitions\/(${GUID})\/cover\.(?:${COVER_EXTS})$`, 'i')
+	}
+];
+
+/**
+ * Reject any path that contains a traversal, empty, or backslash segment
+ * *before* it can match a class. The class patterns use a permissive segment
+ * alphabet (`[A-Za-z0-9._-]+`) so dotted ids and filenames work, but that
+ * alphabet also admits a bare `.` or `..` *as a whole segment* — which would
+ * let `orgs/../branding/logo.webp` classify as public branding with `..`
+ * captured as the orgId. This mirrors `assertSafeKey` in the path builders:
+ * the registry is the read-side gate, those are the write-side gate, and both
+ * forbid the same segments so a path that can't be *written* can't be *read*.
+ */
+function hasUnsafeSegment(storagePath: string): boolean {
+	if (storagePath.includes('\\')) return true;
+	for (const segment of storagePath.split('/')) {
+		if (segment === '' || segment === '.' || segment === '..') return true;
+	}
+	return false;
+}
+
+/**
+ * Classify a storage path into its asset class and scope id, or null when no
+ * class matches (or the path is unsafe). Callers — `getPublicUrl` (to pick CDN
+ * vs proxy) and the serving route (to pick the auth check) — consult this so
+ * URL generation and authorization never drift apart.
+ *
+ * For `org-branding` the orgId is captured as group 1 but the class is public,
+ * so `scopeId` is reported as the captured id only when the class actually
+ * authorizes against it (`scope !== 'none'`); public classes report null.
+ */
+export function classifyAssetPath(storagePath: string): AssetMatch | null {
+	if (hasUnsafeSegment(storagePath)) return null;
+	for (const cls of ASSET_CLASSES) {
+		const m = cls.pattern.exec(storagePath);
+		if (!m) continue;
+		return { class: cls, scopeId: cls.scope === 'none' ? null : (m[1] ?? null) };
+	}
+	return null;
+}
+
+/** True when the path belongs to a `public` asset class (CDN-servable, no auth). */
+export function isPublicAssetPath(storagePath: string): boolean {
+	return classifyAssetPath(storagePath)?.class.visibility === 'public';
+}

package/src/storage/cacheBust.ts

@@ -0,0 +1,26 @@
+/**
+ * Append a cache-busting token to a stored-asset URL.
+ *
+ * Mutable blobs are overwritten **in place** (`IStorageProvider.put` is upsert),
+ * so a re-upload keeps the same storage path — and therefore the same public
+ * URL. A browser/CDN that cached the old bytes under that URL keeps serving them
+ * until the TTL expires, which reads as "the replace didn't work". Appending a
+ * token that changes only when the content changes gives each new version a
+ * distinct URL (forcing a refetch) while letting unchanged assets stay cached.
+ *
+ * Generic over asset kind: the caller supplies the token from whatever it has
+ * that tracks the blob's version — a content hash, the owning record's
+ * `updatedAt`, a version counter. The serving route ignores the query string
+ * (SvelteKit's `[...path]` param never includes it), so this is purely a
+ * client-cache key and needs no route support.
+ *
+ * Empty/whitespace tokens are dropped (returns the URL unchanged) so a missing
+ * token degrades to "no cache-bust" rather than `?v=`.
+ */
+export function withCacheBust(url: string, token: string | number | undefined | null): string {
+	if (token === undefined || token === null) return url;
+	const value = String(token).trim();
+	if (value === '') return url;
+	const sep = url.includes('?') ? '&' : '?';
+	return `${url}${sep}v=${encodeURIComponent(value)}`;
+}

package/src/storage/image.ts

@@ -22,12 +22,17 @@ export interface TranscodeResult {
 /** True if the input looks like an image to process — by content type or path extension. */
 export function isImageUpload(contentType: string | undefined, storagePath: string): boolean {
 	if (contentType?.startsWith('image/')) return true;
-	return /\.(webp|png|jpe?g|gif|bmp|tif?f)$/i.test(storagePath);
+	return /\.(webp|png|jpe?g|gif|bmp|tif?f|svg)$/i.test(storagePath);
 }
 
-/** Rewrite a path's extension to `.webp`. Unchanged if not a recognized image extension. */
+/**
+ * Rewrite a path's extension to `.webp`. Unchanged if not a recognized image
+ * extension. SVG is included: every upload (including SVG) is rasterized to
+ * WebP, so a `.svg` input is stored as `.webp` — no vector blob is ever
+ * persisted, which keeps the served bytes XSS-free without a sanitizer.
+ */
 export function toWebpPath(storagePath: string): string {
-	return storagePath.replace(/\.(png|jpe?g|gif|bmp|tif?f)$/i, '.webp');
+	return storagePath.replace(/\.(png|jpe?g|gif|bmp|tif?f|svg)$/i, '.webp');
 }
 
 /**

package/src/storage/index.ts

@@ -7,3 +7,6 @@ export {
 	transcodeImageIfNeeded
 } from './image.js';
 export type { TranscodeResult } from './image.js';
+export { ASSET_CLASSES, classifyAssetPath, isPublicAssetPath } from './assetClasses.js';
+export type { AssetVisibility, AssetScope, AssetClass, AssetMatch } from './assetClasses.js';
+export { withCacheBust } from './cacheBust.js';

package/src/testing/suites/definitionStoreSuite.ts

@@ -522,6 +522,51 @@ export function runDefinitionStoreConformance(opts: DefinitionStoreConformanceOp
 			expect(byProject.items.map((r) => r.guid)).not.toContain(guid);
 		});
 
+		it('deleteByProject soft-deletes every definition in the project, leaving others', async () => {
+			const store = await createStore();
+			const scope = await scopeFor();
+			// Two published definitions in the target project, one in another —
+			// the cascade must tombstone the target project's and leave the rest.
+			const a = makeUuid();
+			const b = makeUuid();
+			const other = makeUuid();
+			await store.create(
+				ctx(scope.ownerId),
+				record(scope, { guid: a, projectId: scope.projectId, status: 'published' })
+			);
+			await store.create(
+				ctx(scope.ownerId),
+				record(scope, { guid: b, projectId: scope.projectId, status: 'published' })
+			);
+			await store.create(
+				ctx(scope.ownerId),
+				record(scope, { guid: other, projectId: scope.secondaryProjectId, status: 'published' })
+			);
+
+			await store.deleteByProject(ctx(scope.ownerId), scope.projectId);
+
+			// Both target-project definitions gone from every read path…
+			expect(await store.get(ctx(scope.ownerId), a)).toBeNull();
+			expect(await store.get(ctx(scope.ownerId), b)).toBeNull();
+			const targetList = await store.listByProject(ctx(scope.ownerId), scope.projectId, {
+				limit: 500
+			});
+			expect(targetList.items).toHaveLength(0);
+			const all = await store.list(ctx(scope.ownerId), { limit: 500 });
+			expect(all.items.map((r) => r.guid)).not.toContain(a);
+			expect(all.items.map((r) => r.guid)).not.toContain(b);
+			// …but the other project's definition survives.
+			expect(await store.get(ctx(scope.ownerId), other)).not.toBeNull();
+		});
+
+		it('deleteByProject is a no-op when the project has no definitions', async () => {
+			const store = await createStore();
+			const scope = await scopeFor();
+			await expect(
+				store.deleteByProject(ctx(scope.ownerId), scope.secondaryProjectId)
+			).resolves.toBeUndefined();
+		});
+
 		it('listPublic returns published records, not pending', async () => {
 			const store = await createStore();
 			const scope = await scopeFor();

package/src/testing/suites/orgStoreSuite.ts

@@ -132,6 +132,23 @@ export function runOrgStoreConformance(opts: OrgStoreConformanceOptions): void {
 				expect(got?.slug).toBe('new-slug');
 			});
 
+			it('updateOrg sets and clears branding assets', async () => {
+				const store = await createStore();
+				const u1 = await seed();
+				const orgId = makeUuid();
+				await store.createOrg(ctx(u1), org(u1, { id: orgId, slug: 'asset-org' }));
+
+				// Set the logo asset.
+				await store.updateOrg(ctx(u1), orgId, { assets: { logo: '/api/files/orgs/x/logo.webp' } });
+				expect((await store.getOrg(ctx(u1), orgId))?.assets?.logo).toBe(
+					'/api/files/orgs/x/logo.webp'
+				);
+
+				// Replace the whole map (drops logo) — the store persists what it's given.
+				await store.updateOrg(ctx(u1), orgId, { assets: {} });
+				expect((await store.getOrg(ctx(u1), orgId))?.assets?.logo ?? null).toBeNull();
+			});
+
 			it('deleteOrg removes the organization', async () => {
 				const store = await createStore();
 				const u1 = await seed();

package/src/testing/suites/storageProviderSuite.ts

@@ -171,5 +171,26 @@ export function runStorageProviderConformance(opts: StorageProviderConformanceOp
 			expect(atWebp?.slice(0, 4)).toEqual(bytes('RIFF'));
 			expect(atWebp?.slice(8, 12)).toEqual(bytes('WEBP'));
 		});
+
+		it('rasterizes svg input to webp — no vector blob is ever stored', async () => {
+			const storage = await createStorage();
+			// A minimal SVG carrying a <script> — the exact XSS payload the
+			// rasterize-everything policy is meant to neutralize.
+			const svg =
+				'<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10">' +
+				'<script>alert(1)</script><rect width="10" height="10" fill="red"/></svg>';
+			const svgBytes = new TextEncoder().encode(svg);
+			await storage.put('orgs/x/logo.webp', svgBytes, 'image/svg+xml');
+
+			// The stored blob is a WebP raster, NOT the original SVG bytes — so the
+			// served file can't execute script. (The path is already .webp because
+			// orgPaths.asset fixes it; the content is what matters here.)
+			const stored = await storage.get('orgs/x/logo.webp');
+			expect(stored).toBeTruthy();
+			expect(stored?.slice(0, 4)).toEqual(bytes('RIFF'));
+			expect(stored?.slice(8, 12)).toEqual(bytes('WEBP'));
+			// Defense-in-depth assertion: the script tag is gone from the bytes.
+			expect(new TextDecoder().decode(stored!)).not.toContain('script');
+		});
 	});
 }