@db3.ai/app 0.1.0-beta.1

package/src/storage/mime.ts

@@ -0,0 +1,30 @@
+import { extname } from 'node:path';
+
+const mimeTypes: Record<string, string> = {
+	'.avif': 'image/avif',
+	'.css': 'text/css',
+	'.csv': 'text/csv',
+	'.gif': 'image/gif',
+	'.html': 'text/html',
+	'.jpeg': 'image/jpeg',
+	'.jpg': 'image/jpeg',
+	'.js': 'text/javascript',
+	'.json': 'application/json',
+	'.md': 'text/markdown',
+	'.pdf': 'application/pdf',
+	'.png': 'image/png',
+	'.svg': 'image/svg+xml',
+	'.txt': 'text/plain',
+	'.webp': 'image/webp',
+	'.xml': 'application/xml',
+};
+
+/**
+ * Returns a best-effort MIME type from a file path.
+ *
+ * @param path - File path or storage path with an extension.
+ * @returns MIME type for known extensions, or application/octet-stream.
+ */
+export function mimeTypeFromPath(path: string): string {
+	return mimeTypes[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}

package/src/storage/path.ts

@@ -0,0 +1,76 @@
+import { isAbsolute, resolve, sep } from 'node:path';
+import { posix } from 'node:path';
+
+/**
+ * Normalizes a caller-provided storage path into a safe relative path.
+ *
+ * @param path - User or application supplied storage path.
+ * @returns Normalized relative storage path using forward slashes.
+ */
+export function normalizeStoragePath(path: string): string {
+	if (typeof path !== 'string') {
+		throw new Error('Storage path must be a string.');
+	}
+
+	if (path.includes('\0')) {
+		throw new Error('Storage path cannot contain null bytes.');
+	}
+
+	const input = path.trim().replace(/\\/g, '/');
+
+	if (!input) {
+		throw new Error('Storage path cannot be empty.');
+	}
+
+	if (input.startsWith('/') || isAbsolute(input)) {
+		throw new Error(`Storage path "${path}" must be relative.`);
+	}
+
+	if (/^[A-Za-z]:\//.test(input)) {
+		throw new Error(`Storage path "${path}" must be relative.`);
+	}
+
+	const normalized = posix.normalize(input);
+
+	if (normalized === '.' || normalized === '..' || normalized.startsWith('../')) {
+		throw new Error(`Storage path "${path}" cannot leave the storage disk root.`);
+	}
+
+	return normalized;
+}
+
+/**
+ * Normalizes a storage directory path while allowing the disk root.
+ *
+ * @param path - User or application supplied directory path.
+ * @returns Normalized relative directory path, or an empty string for the root.
+ */
+export function normalizeStorageDirectoryPath(path = ''): string {
+	if (typeof path !== 'string') {
+		throw new Error('Storage path must be a string.');
+	}
+
+	const input = path.trim().replace(/\\/g, '/');
+
+	if (input === '' || input === '.') return '';
+
+	return normalizeStoragePath(input);
+}
+
+/**
+ * Resolves a normalized storage path against a local disk root.
+ *
+ * @param root - Absolute or process-relative disk root.
+ * @param path - Storage path to resolve.
+ * @returns Absolute filesystem path inside the disk root.
+ */
+export function resolveLocalStoragePath(root: string, path: string): string {
+	const normalizedRoot = resolve(root);
+	const resolved = resolve(normalizedRoot, normalizeStoragePath(path));
+
+	if (resolved !== normalizedRoot && !resolved.startsWith(`${normalizedRoot}${sep}`)) {
+		throw new Error(`Storage path "${path}" cannot leave the storage disk root.`);
+	}
+
+	return resolved;
+}

package/src/storage/types.ts

@@ -0,0 +1,251 @@
+import type { Readable } from 'node:stream';
+
+import type { StorageListing, StorageListOptions } from './contracts';
+
+export type StorageVisibility = 'public' | 'private';
+
+export type StorageContents = string | Buffer | Uint8Array | ArrayBuffer;
+
+export interface StoragePutOptions {
+	visibility?: StorageVisibility;
+	mimeType?: string;
+}
+
+export interface StorageFileStat {
+	path: string;
+	size: number;
+	lastModified: Date;
+}
+
+/**
+ * Runtime interface implemented by configured storage disks.
+ */
+export interface StorageDisk {
+	readonly name: string;
+
+	/**
+	 * Writes file contents to a path on this disk.
+	 *
+	 * Alias for put(), useful for command-line and REPL usage.
+	 *
+	 * @param path - Relative storage path to write.
+	 * @param contents - Bytes or text content to persist.
+	 * @param options - Optional write metadata.
+	 * @returns Promise that resolves once the file is written.
+	 */
+	write(path: string, contents: StorageContents, options?: StoragePutOptions): Promise<void>;
+
+	/**
+	 * Writes file contents to a path on this disk.
+	 *
+	 * @param path - Relative storage path to write.
+	 * @param contents - Bytes or text content to persist.
+	 * @param options - Optional write metadata.
+	 * @returns Promise that resolves once the file is written.
+	 */
+	put(path: string, contents: StorageContents, options?: StoragePutOptions): Promise<void>;
+
+	/**
+	 * Writes streamed file contents to a path on this disk.
+	 *
+	 * @param path - Relative storage path to write.
+	 * @param stream - Readable stream containing file bytes.
+	 * @param options - Optional write metadata.
+	 * @returns Promise that resolves once the stream is written.
+	 */
+	writeStream(path: string, stream: Readable, options?: StoragePutOptions): Promise<void>;
+
+	/**
+	 * Lists files and directories beneath a path on this disk.
+	 *
+	 * @param path - Relative directory path, or an empty string for the disk root.
+	 * @param options - Directory traversal options.
+	 * @returns Lazy provider-neutral directory listing.
+	 */
+	list(path?: string, options?: StorageListOptions): StorageListing;
+
+	/**
+	 * Reads file contents as bytes from this disk.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @returns Stored file contents.
+	 */
+	get(path: string): Promise<Buffer>;
+
+	/**
+	 * Reads file contents into a string from this disk.
+	 *
+	 * Matches Flystorage's readToString() API.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @returns Stored text content.
+	 */
+	readToString(path: string): Promise<string>;
+
+	/**
+	 * Reads file contents into a Buffer from this disk.
+	 *
+	 * Matches Flystorage's readToBuffer() API.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @returns Stored file contents.
+	 */
+	readToBuffer(path: string): Promise<Buffer>;
+
+	/**
+	 * Reads file contents into a Uint8Array from this disk.
+	 *
+	 * Matches Flystorage's readToUint8Array() API.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @returns Stored file contents.
+	 */
+	readToUint8Array(path: string): Promise<Uint8Array>;
+
+	/**
+	 * Reads file contents as a stream from this disk.
+	 *
+	 * Matches Flystorage's read() API.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @returns Readable stream for the stored file.
+	 */
+	read(path: string): Promise<Readable>;
+
+	/**
+	 * Reads file contents as a stream from this disk.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @returns Readable stream for the stored file.
+	 */
+	readStream(path: string): Promise<Readable>;
+
+	/**
+	 * Reads file contents as text from this disk.
+	 *
+	 * @param path - Relative storage path to read.
+	 * @param encoding - Text encoding used to decode the file.
+	 * @returns Stored text content.
+	 */
+	getText(path: string, encoding?: BufferEncoding): Promise<string>;
+
+	/**
+	 * Returns true when a file exists at the given path.
+	 *
+	 * @param path - Relative storage path to inspect.
+	 * @returns True when the file exists.
+	 */
+	exists(path: string): Promise<boolean>;
+
+	/**
+	 * Returns true when a file does not exist at the given path.
+	 *
+	 * @param path - Relative storage path to inspect.
+	 * @returns True when the file is missing.
+	 */
+	missing(path: string): Promise<boolean>;
+
+	/**
+	 * Deletes a file from this disk.
+	 *
+	 * @param path - Relative storage path to delete.
+	 * @returns True when a file was deleted.
+	 */
+	delete(path: string): Promise<boolean>;
+
+	/**
+	 * Copies a file between two paths on this disk.
+	 *
+	 * @param from - Existing relative storage path.
+	 * @param to - New relative storage path.
+	 * @returns Promise that resolves once the copy is complete.
+	 */
+	copy(from: string, to: string): Promise<void>;
+
+	/**
+	 * Moves a file between two paths on this disk.
+	 *
+	 * @param from - Existing relative storage path.
+	 * @param to - New relative storage path.
+	 * @returns Promise that resolves once the move is complete.
+	 */
+	move(from: string, to: string): Promise<void>;
+
+	/**
+	 * Returns file size in bytes.
+	 *
+	 * @param path - Relative storage path to inspect.
+	 * @returns File size in bytes.
+	 */
+	size(path: string): Promise<number>;
+
+	/**
+	 * Returns the last modification time for a file.
+	 *
+	 * @param path - Relative storage path to inspect.
+	 * @returns File modification date.
+	 */
+	lastModified(path: string): Promise<Date>;
+
+	/**
+	 * Returns a best-effort MIME type for a file path.
+	 *
+	 * @param path - Relative storage path to inspect.
+	 * @returns MIME type for the file extension.
+	 */
+	mimeType(path: string): Promise<string>;
+
+	/**
+	 * Returns a public URL for a path when the disk supports URLs.
+	 *
+	 * @param path - Relative storage path to expose.
+	 * @returns Public URL.
+	 */
+	url(path: string): Promise<string>;
+
+	/**
+	 * Returns an absolute filesystem path when the disk is local.
+	 *
+	 * @param path - Relative storage path to resolve.
+	 * @returns Absolute filesystem path.
+	 */
+	path(path: string): string;
+}
+
+export interface LocalStorageDiskConfig {
+	driver: 'local';
+	root?: string;
+	url?: string;
+	visibility?: StorageVisibility;
+}
+
+export interface S3StorageDiskConfig {
+	driver: 's3';
+	bucket: string;
+	region?: string;
+	endpoint?: string;
+	prefix?: string;
+	url?: string;
+	forcePathStyle?: boolean;
+	accessKeyId?: string;
+	secretAccessKey?: string;
+	sessionToken?: string;
+	key?: string;
+	secret?: string;
+	visibility?: StorageVisibility;
+}
+
+export interface CustomStorageDiskConfig {
+	driver: string;
+	[key: string]: unknown;
+}
+
+export type StorageDiskConfig = LocalStorageDiskConfig | S3StorageDiskConfig | CustomStorageDiskConfig;
+
+export type StorageDiskFactory = (name: string, config: StorageDiskConfig) => StorageDisk;
+
+export interface StorageOptions {
+	default?: string;
+	disks?: Record<string, StorageDiskConfig | StorageDisk>;
+	drivers?: Record<string, StorageDiskFactory>;
+}

package/src/url/README.md

@@ -0,0 +1,41 @@
+# Application URLs
+
+## Runnable links and tests
+
+Copy the installed package's `src/url/examples/` into `examples/`, then run
+`npx tsx examples/runApplicationLinks.ts`. No SQL or network is needed. The lab
+checks base/subpath resolution, invalid configuration, an application-owned
+same-origin redirect guard and recovery. Copy the exact
+`tests/examples/runApplicationLinks.test.ts` into `tests/url/` to extend it.
+`to()` follows standard URL resolution and permits absolute references; it is
+not an open-redirect or remote-fetch protection mechanism.
+
+`app().url` is the framework-owned source for the canonical browser-facing
+application URL. It is deliberately separate from a concrete server such as
+Fastify so URL generation also works in queue workers, schedulers, console
+commands, and server-side rendering processes.
+
+Configure a deployed application with `APP_URL` or an explicit `baseUrl`. Apps
+with a separate frontend development server can pass its configured local port:
+
+```ts
+const application = new App({
+	url: {
+		localPort: 8888,
+	},
+});
+
+application.url.baseUrl;
+// http://localhost:8888
+
+application.url.to('/api/oauth/callback');
+// http://localhost:8888/api/oauth/callback
+```
+
+Application code should use this service instead of reading request host
+headers or reconstructing origins from environment variables. Request headers
+are untrusted and a concrete HTTP server may not exist in background processes.
+
+Future SSR request URLs should be carried by `app().requestContext`; they must
+not mutate the canonical URL used for OAuth callbacks, email links, billing
+returns, publishing, and background jobs.

package/src/url/UrlGenerator.ts

@@ -0,0 +1,72 @@
+import type * as url from './contracts';
+
+/**
+ * Canonical application URL generator.
+ *
+ * The generator is intentionally independent of a concrete server adapter and
+ * the current request. API, queue, scheduler, console, and future SSR runtimes
+ * can therefore share one trusted application origin. Request-specific SSR
+ * state belongs to the request context and must not replace this canonical URL.
+ *
+ * @example
+ * const callback = app().url.to('/api/integrations/provider/callback');
+ */
+export class UrlGenerator {
+	/** Normalized browser-facing application URL without a trailing slash. */
+	readonly baseUrl: string;
+
+	/**
+	 * Creates the canonical application URL generator.
+	 *
+	 * @param options - Public deployment URL or local browser port configuration.
+	 */
+	constructor(options: url.UrlGeneratorOptions = {}) {
+		this.baseUrl = resolveBaseUrl(options);
+	}
+
+	/**
+	 * Builds an absolute application URL from a path or relative reference.
+	 *
+	 * @param path - Application path or relative URL to resolve.
+	 * @returns Absolute browser-facing application URL.
+	 *
+	 * @example
+	 * app().url.to('/auth/reset-password');
+	 */
+	to(path: string): string {
+		return new URL(path, `${this.baseUrl}/`).toString();
+	}
+}
+
+/**
+ * Resolves and validates the one canonical application base URL.
+ *
+ * @param options - Explicit public URL or local browser port configuration.
+ * @returns Normalized HTTP(S) application base URL without a trailing slash.
+ */
+function resolveBaseUrl(options: url.UrlGeneratorOptions): string {
+	const configured = options.baseUrl
+		|| process.env.APP_URL
+		|| process.env.PUBLIC_APP_URL;
+
+	if (configured) {
+		const normalized = configured.trim().replace(/\/+$/, '');
+		const parsed = new URL(normalized);
+
+		if (!['http:', 'https:'].includes(parsed.protocol)) {
+			throw new Error('Application base URL must use http or https.');
+		}
+
+		return normalized;
+	}
+
+	if (options.localPort !== undefined) {
+		if (!Number.isInteger(options.localPort) || options.localPort < 1 || options.localPort > 65_535) {
+			throw new Error('Application local port must be an integer between 1 and 65535.');
+		}
+
+		return `http://localhost:${options.localPort}`;
+	}
+
+	throw new Error('Application base URL is not configured. Set APP_URL or provide a local port.');
+}

package/src/url/contracts/UrlGeneratorOptions.ts

@@ -0,0 +1,14 @@
+/**
+ * Canonical application URL configuration.
+ *
+ * The explicit public URL is authoritative in deployed environments. A local
+ * port can provide a browser-facing development origin without duplicating a
+ * complete application URL alongside the frontend server configuration.
+ */
+export interface UrlGeneratorOptions {
+	/** Public application base URL, such as `https://example.com`. */
+	baseUrl?: string;
+
+	/** Browser-facing localhost port used when no public base URL is configured. */
+	localPort?: number;
+}

package/src/url/contracts/index.ts

@@ -0,0 +1 @@
+export * from './UrlGeneratorOptions';

package/src/url/examples/runApplicationLinks.ts

@@ -0,0 +1,33 @@
+import { pathToFileURL } from 'node:url';
+import { App } from '@db3.ai/app/server';
+import { UrlGenerator } from '@db3.ai/app/url';
+
+/**
+ * Builds a link from an app-owned path, rejecting another origin.
+ *
+ * This is an example redirect policy, not a method supplied by UrlGenerator.
+ * @param url - Trusted application URL generator.
+ * @param path - Root-relative path to resolve.
+ * @returns Same-origin absolute URL.
+ */
+export function applicationLink(url: UrlGenerator, path: string): string {
+	if (!path.startsWith('/') || path.startsWith('//')) throw new Error('Use a root-relative application path.');
+	const resolved = url.to(path);
+	if (new URL(resolved).origin !== new URL(url.baseUrl).origin) throw new Error('Link must remain on the application origin.');
+	return resolved;
+}
+
+/** Exercises canonical links, subpath resolution, invalid configuration and repair. */
+export async function runApplicationLinks() {
+	const application = new App({ url: { baseUrl: 'https://notes.example.test/workspace/' } });
+	try {
+		const url = application.url;
+		let invalidBaseRejected = false;
+		try { new UrlGenerator({ baseUrl: 'file:///private/notes' }); } catch { invalidBaseRejected = true; }
+		let externalRejected = false;
+		try { applicationLink(url, '//outside.example.test/'); } catch { externalRejected = true; }
+		return { base: url.baseUrl, relative: url.to('notes/one'), root: applicationLink(url, '/notes/one'), externalRejected, invalidBaseRejected, repaired: new UrlGenerator({ baseUrl: 'https://notes.example.test' }).to('/sign-in') };
+	} finally { await application.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runApplicationLinks(), null, 2));

package/src/url/index.ts

@@ -0,0 +1,2 @@
+export * from './contracts';
+export * from './UrlGenerator';