@selvajs/platform 0.14.3-beta.0 → 0.15.0-beta.2

package/src/storage/assetClasses.ts

@@ -1,134 +0,0 @@
-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

@@ -1,26 +0,0 @@
-/**
- * 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

@@ -1,82 +0,0 @@
-/**
- * Shared image-transcoding helper for `IStorageProvider` implementations.
- * Cover images are normalized to WebP at upload time (capped at 1200px,
- * quality 85) so storage/bandwidth stays predictable and the viewer path
- * is uniform.
- *
- * `sharp` is loaded via a dynamic import so the platform package has no
- * hard runtime dependency on it — install it in providers that need
- * transcoding (optional peer dependency).
- */
-
-export const IMAGE_MAX_WIDTH = 1200;
-export const IMAGE_WEBP_QUALITY = 85;
-
-export interface TranscodeResult {
-	data: Uint8Array;
-	contentType: string;
-	/** Possibly-rewritten path (non-webp inputs become `.webp`). */
-	path: string;
-}
-
-/** 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|svg)$/i.test(storagePath);
-}
-
-/**
- * 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|svg)$/i, '.webp');
-}
-
-/**
- * If the input is an image, transcode to WebP (capped + re-encoded) and
- * return rewritten bytes/content-type/path. Non-images pass through, so
- * providers can call this unconditionally before `put`.
- *
- * Throws if `sharp` isn't installed — that's a config error, not a fallback.
- */
-export async function transcodeImageIfNeeded(
-	data: Uint8Array,
-	contentType: string | undefined,
-	storagePath: string
-): Promise<TranscodeResult> {
-	if (!isImageUpload(contentType, storagePath)) {
-		return { data, contentType: contentType ?? 'application/octet-stream', path: storagePath };
-	}
-
-	const sharp = await loadSharp();
-	const compressed = await sharp(Buffer.from(data))
-		.resize({ width: IMAGE_MAX_WIDTH, withoutEnlargement: true })
-		.webp({ quality: IMAGE_WEBP_QUALITY })
-		.toBuffer();
-
-	return {
-		data: new Uint8Array(compressed),
-		contentType: 'image/webp',
-		path: toWebpPath(storagePath)
-	};
-}
-
-type SharpFn = typeof import('sharp');
-let cachedSharp: SharpFn | null = null;
-
-async function loadSharp(): Promise<SharpFn> {
-	if (cachedSharp) return cachedSharp;
-	try {
-		const mod = (await import('sharp')) as unknown as { default: SharpFn };
-		cachedSharp = mod.default ?? (mod as unknown as SharpFn);
-		return cachedSharp;
-	} catch (err) {
-		throw new Error(
-			'Image transcoding requires `sharp` to be installed. Add it as a dependency in your provider package.',
-			{ cause: err as Error }
-		);
-	}
-}

package/src/storage/index.ts

@@ -1,12 +0,0 @@
-export type { IStorageProvider } from './interface.js';
-export {
-	IMAGE_MAX_WIDTH,
-	IMAGE_WEBP_QUALITY,
-	isImageUpload,
-	toWebpPath,
-	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/storage/interface.ts

@@ -1,27 +0,0 @@
-/**
- * Generic path-based blob storage. Implement with: local filesystem, S3,
- * Supabase Storage, Azure Blob, etc.
- *
- * **Authorization is the caller's responsibility.** Methods do NOT take a
- * `RequestContext` — the path itself names the resource, and constructing it
- * requires already-authorized scope. Routes/services MUST authorize against
- * `@selvajs/platform/access` BEFORE constructing the path.
- */
-export interface IStorageProvider {
-	/** Returns null if the path does not exist. */
-	get(path: string): Promise<Uint8Array | null>;
-
-	put(path: string, data: Uint8Array, contentType?: string): Promise<void>;
-
-	/** No-op if the path does not exist. */
-	delete(path: string): Promise<void>;
-
-	/** Delete every file whose path starts with `prefix`. */
-	deletePrefix(prefix: string): Promise<void>;
-
-	/**
-	 * Public URL for a stored file. Local: a relative API path; S3/CDN: a
-	 * full or signed URL.
-	 */
-	getPublicUrl(path: string): string;
-}

package/src/testing/index.ts

@@ -1,47 +0,0 @@
-export { runAuthProviderConformance } from './suites/authProviderSuite.js';
-export type { AuthProviderConformanceOptions } from './suites/authProviderSuite.js';
-
-export { runEmailLinkAuthConformance } from './suites/emailLinkAuthSuite.js';
-export type { EmailLinkAuthConformanceOptions } from './suites/emailLinkAuthSuite.js';
-
-export { runDefinitionStoreConformance } from './suites/definitionStoreSuite.js';
-export type { DefinitionStoreConformanceOptions } from './suites/definitionStoreSuite.js';
-
-export { runOrgStoreConformance } from './suites/orgStoreSuite.js';
-export type { OrgStoreConformanceOptions } from './suites/orgStoreSuite.js';
-
-export { runProjectStoreConformance } from './suites/projectStoreSuite.js';
-export type { ProjectStoreConformanceOptions } from './suites/projectStoreSuite.js';
-
-export { runStorageProviderConformance } from './suites/storageProviderSuite.js';
-export type { StorageProviderConformanceOptions } from './suites/storageProviderSuite.js';
-
-export { runUserProfileStoreConformance } from './suites/userProfileStoreSuite.js';
-export type { UserProfileStoreConformanceOptions } from './suites/userProfileStoreSuite.js';
-
-export { runInviteStoreConformance } from './suites/inviteStoreSuite.js';
-export type { InviteStoreConformanceOptions, InviteTestScope } from './suites/inviteStoreSuite.js';
-
-export { runComputeServerStoreConformance } from './suites/computeServerStoreSuite.js';
-export type { ComputeServerStoreConformanceOptions } from './suites/computeServerStoreSuite.js';
-
-export { runShareLinkStoreConformance } from './suites/shareLinkStoreSuite.js';
-export type {
-	ShareLinkStoreConformanceOptions,
-	ShareLinkTestScope
-} from './suites/shareLinkStoreSuite.js';
-
-export { runEventSinkConformance, RecordingEventSink } from './suites/eventSinkSuite.js';
-export type { EventSinkConformanceOptions } from './suites/eventSinkSuite.js';
-
-export { runSolveMetricSinkConformance } from './suites/solveMetricSinkSuite.js';
-export type {
-	SolveMetricSinkConformanceOptions,
-	RecordedSolveMetric
-} from './suites/solveMetricSinkSuite.js';
-
-export { runPlatformPermissionStoreConformance } from './suites/platformPermissionStoreSuite.js';
-export type { PlatformPermissionStoreConformanceOptions } from './suites/platformPermissionStoreSuite.js';
-
-export { runPlatformProjectGrantStoreConformance } from './suites/platformProjectGrantStoreSuite.js';
-export type { PlatformProjectGrantStoreConformanceOptions } from './suites/platformProjectGrantStoreSuite.js';

package/src/testing/suites/authProviderSuite.ts

@@ -1,207 +0,0 @@
-// Conformance suite for IAuthProvider: token round-trips, identity, password auth, admin management.
-
-import { describe, it, expect } from 'vitest';
-import type { IAuthProvider } from '../../auth/index.js';
-import { makeUuid } from './helpers.js';
-
-export interface AuthProviderConformanceOptions {
-	/** Name to show in test output (e.g. "LocalAuthProvider"). */
-	name: string;
-	/**
-	 * Factory returning a fresh provider configured with a known password.
-	 * `adminPassword` must work with `passwordAuth.verifyLogin(adminEmail, adminPassword)`
-	 * for password-capable providers. The factory is responsible for seeding
-	 * the admin user (e.g. via `createUserWithPassword`) before returning.
-	 *
-	 * `adminEmail` defaults to `''` for legacy reasons; new providers should
-	 * always return the seeded admin's email.
-	 */
-	createProvider: () =>
-		| Promise<{ provider: IAuthProvider; adminPassword: string; adminEmail?: string }>
-		| { provider: IAuthProvider; adminPassword: string; adminEmail?: string };
-	/**
-	 * Set to true when the provider is wired with a backend so that
-	 * createUser / listUsers / updateUserPlatformPermissions / deleteUser tests run.
-	 * When false those methods are expected to return null / 'not_supported'.
-	 */
-	userManagement?: boolean;
-}
-
-export function runAuthProviderConformance(opts: AuthProviderConformanceOptions): void {
-	const { name, createProvider, userManagement = false } = opts;
-
-	describe(`IAuthProvider conformance: ${name}`, () => {
-		// Token round-trips
-		it('verifyLogin returns a session token that verifyToken accepts', async () => {
-			const { provider, adminPassword, adminEmail = '' } = await createProvider();
-			const result = await provider.passwordAuth!.verifyLogin(adminEmail, adminPassword);
-			expect(result.kind).toBe('success');
-			if (result.kind !== 'success') return;
-			const verified = await provider.verifyToken(result.sessionToken);
-			expect(verified?.id).toBe(result.user.id);
-		});
-
-		it('verifyToken returns null for a garbage token', async () => {
-			const { provider } = await createProvider();
-			const result = await provider.verifyToken('not-a-valid-token');
-			expect(result).toBeNull();
-		});
-
-		it('verifyToken returns null for an empty string', async () => {
-			const { provider } = await createProvider();
-			const result = await provider.verifyToken('');
-			expect(result).toBeNull();
-		});
-
-		// Password auth (only runs when passwordAuth is present)
-		it('verifyLogin returns success with correct password', async () => {
-			const { provider, adminPassword, adminEmail = '' } = await createProvider();
-			if (!provider.passwordAuth) return;
-			const result = await provider.passwordAuth.verifyLogin(adminEmail, adminPassword);
-			expect(result.kind).toBe('success');
-			if (result.kind !== 'success') return;
-			// Identity-only — platform permissions live on IPlatformPermissionStore now.
-			expect(result.user.id).toBeTruthy();
-			expect(typeof result.sessionToken).toBe('string');
-			expect(result.sessionToken.length).toBeGreaterThan(0);
-		});
-
-		it('verifyLogin returns failed for wrong password', async () => {
-			const { provider, adminEmail = '' } = await createProvider();
-			if (!provider.passwordAuth) return;
-			const result = await provider.passwordAuth.verifyLogin(adminEmail, 'wrong-password-xyz');
-			expect(result.kind).toBe('failed');
-		});
-
-		// getUser
-		it('getUser returns null for unknown id', async () => {
-			const { provider } = await createProvider();
-			// Valid UUID shape but not an actual user — stricter backends (Postgres
-			// uuid columns) reject non-UUID ids outright, so we never send those.
-			const result = await provider.getUser(makeUuid());
-			expect(result).toBeNull();
-		});
-
-		// ============================================================================
-		// User management (opt-in)
-		// ============================================================================
-
-		if (userManagement) {
-			it('passwordAuth.createUserWithPassword + getUser returns the created user', async () => {
-				const { provider } = await createProvider();
-				const email = `test-${makeUuid()}@example.com`;
-				const created = await provider.passwordAuth!.createUserWithPassword(email, 'password1234');
-				expect(created).toBeTruthy();
-				const fetched = await provider.getUser(created.id);
-				expect(fetched?.id).toBe(created.id);
-				expect(fetched?.email).toBe(email);
-			});
-
-			it('createUserWithPassword allows login with the new credentials', async () => {
-				const { provider } = await createProvider();
-				const email = `login-${makeUuid()}@example.com`;
-				await provider.passwordAuth!.createUserWithPassword(email, 'secret9999');
-				const result = await provider.passwordAuth!.verifyLogin(email, 'secret9999');
-				expect(result.kind).toBe('success');
-				if (result.kind !== 'success') return;
-				expect(result.user.email).toBe(email);
-			});
-
-			it('listUsers returns created users', async () => {
-				const { provider } = await createProvider();
-				const a = `a-${makeUuid()}@example.com`;
-				const b = `b-${makeUuid()}@example.com`;
-				await provider.passwordAuth!.createUserWithPassword(a, 'pass12345678');
-				await provider.passwordAuth!.createUserWithPassword(b, 'pass12345678');
-				const page = await provider.listUsers({ limit: 200 });
-				expect(page).toBeTruthy();
-				const emails = page!.items.map((u) => u.email);
-				expect(emails).toContain(a);
-				expect(emails).toContain(b);
-			});
-
-			it('deleteUser removes the user', async () => {
-				const { provider } = await createProvider();
-				const email = `del-${makeUuid()}@example.com`;
-				const created = await provider.passwordAuth!.createUserWithPassword(email, 'pass12345678');
-				const result = await provider.deleteUser(created.id);
-				expect(result).toBe('ok');
-				const fetched = await provider.getUser(created.id);
-				expect(fetched).toBeNull();
-			});
-
-			it('deleteUser returns not_found for unknown user', async () => {
-				const { provider } = await createProvider();
-				const result = await provider.deleteUser(makeUuid());
-				expect(result).toBe('not_found');
-			});
-
-			// Note: the §2 sole-`instance_admin` invariant is no longer enforced
-			// by IAuthProvider — it lives on IPlatformPermissionStore now and
-			// callers consult `countInstanceAdminsExcluding` before destructive
-			// ops. Auth-side delete/disable just deletes the identity and
-			// trusts the caller. See `runPlatformPermissionStoreConformance`
-			// for the invariant tests.
-
-			it('createUserWithPassword returns an identity record without profile fields', async () => {
-				const { provider } = await createProvider();
-				const user = await provider.passwordAuth!.createUserWithPassword(
-					`new-${makeUuid()}@example.com`,
-					'pass12345678'
-				);
-				// Profile state (starred, recentRuns, displayName) lives on
-				// IUserProfileStore. Platform permissions live on
-				// IPlatformPermissionStore. AuthUser is identity-only.
-				expect(
-					(user as unknown as { starredDefinitions?: unknown }).starredDefinitions
-				).toBeUndefined();
-				expect((user as unknown as { recentRuns?: unknown }).recentRuns).toBeUndefined();
-				expect((user as unknown as { displayName?: unknown }).displayName).toBeUndefined();
-				expect(
-					(user as unknown as { platformPermissions?: unknown }).platformPermissions
-				).toBeUndefined();
-			});
-
-			it('disableUser disables a user', async () => {
-				const { provider } = await createProvider();
-				const created = await provider.passwordAuth!.createUserWithPassword(
-					`disable-${makeUuid()}@example.com`,
-					'pass12345678'
-				);
-				const result = await provider.disableUser(created.id);
-				expect(result).toBe('ok');
-				const fetched = await provider.getUser(created.id);
-				expect(fetched?.disabled).toBe(true);
-			});
-
-			it('disableUser returns not_found for unknown user', async () => {
-				const { provider } = await createProvider();
-				const result = await provider.disableUser(makeUuid());
-				expect(result).toBe('not_found');
-			});
-		} else {
-			it('listUsers returns null when user management is not supported', async () => {
-				const { provider } = await createProvider();
-				const result = await provider.listUsers();
-				expect(result).toBeNull();
-			});
-
-			it('createUser (allowlist) is undefined when user management is not supported', async () => {
-				const { provider } = await createProvider();
-				expect(provider.createUser).toBeUndefined();
-			});
-
-			it('deleteUser returns not_supported', async () => {
-				const { provider } = await createProvider();
-				const result = await provider.deleteUser(makeUuid());
-				expect(result).toBe('not_supported');
-			});
-
-			it('disableUser returns not_supported', async () => {
-				const { provider } = await createProvider();
-				const result = await provider.disableUser(makeUuid());
-				expect(result).toBe('not_supported');
-			});
-		}
-	});
-}