@db3.ai/app 0.1.0-beta.1

package/src/security/Security.ts

@@ -0,0 +1,346 @@
+import { Buffer } from 'node:buffer';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { app } from '../server/appContext';
+import type * as security from './contracts';
+import { SecurityError } from './SecurityError';
+
+const DEFAULT_CIPHER: security.SecurityCipher = 'aes-256-gcm';
+const ENCRYPTION_KEY_BYTES = 32;
+const INITIALIZATION_VECTOR_BYTES = 12;
+const AUTHENTICATION_TAG_BYTES = 16;
+const PAYLOAD_FORMAT = 'security';
+const PAYLOAD_VERSION = '1';
+
+/**
+ * Central application service for versioned authenticated encryption.
+ *
+ * The service owns key resolution, cipher policy, payload framing, and JSON
+ * serialization so fields and application services do not implement their own
+ * cryptographic formats.
+ *
+ * @example
+ * const encrypted = app().security.encryptJson({
+ * 	token: 'provider-secret',
+ * });
+ * const decrypted = app().security.decryptJson<{ token: string }>(encrypted);
+ */
+export class Security {
+	/**
+	 * Central key source and encryption policy.
+	 */
+	readonly #options: security.SecurityOptions;
+
+	/**
+	 * Validated key pinned for this service lifetime.
+	 */
+	readonly #encryptionKey: Buffer;
+
+	/**
+	 * Creates the application security service from the active app config.
+	 */
+	constructor() {
+		const options = app().config.get<security.SecurityOptions>('security', {});
+
+		this.#options = {
+			...options,
+			key: Buffer.isBuffer(options.key)
+				? Buffer.from(options.key)
+				: options.key,
+		};
+		this.#encryptionKey = this.#validateKey(this.#options.key);
+	}
+
+	/**
+	 * Generates a new base64-formatted 256-bit application key.
+	 *
+	 * @returns Value suitable for an `APP_KEY` environment variable.
+	 */
+	static generateKey(): string {
+		return `base64:${randomBytes(ENCRYPTION_KEY_BYTES).toString('base64')}`;
+	}
+
+	/**
+	 * Encrypts bytes or text with authenticated encryption.
+	 *
+	 * @param value - Plaintext bytes or UTF-8 text.
+	 * @param options - Optional additional authenticated ownership context.
+	 * @returns Versioned encrypted payload safe for text storage.
+	 */
+	encrypt(
+		value: string | Buffer,
+		options: security.SecurityPayloadOptions = {},
+	): string {
+		const cipherName = this.#cipher();
+		const iv = randomBytes(INITIALIZATION_VECTOR_BYTES);
+		const cipher = createCipheriv(cipherName, this.#key(), iv);
+
+		cipher.setAAD(additionalAuthenticatedData(options));
+
+		const ciphertext = Buffer.concat([
+			cipher.update(bufferValue(value)),
+			cipher.final(),
+		]);
+		const authenticationTag = cipher.getAuthTag();
+
+		return [
+			PAYLOAD_FORMAT,
+			PAYLOAD_VERSION,
+			cipherName,
+			iv.toString('base64url'),
+			authenticationTag.toString('base64url'),
+			ciphertext.toString('base64url'),
+		].join(':');
+	}
+
+	/**
+	 * Decrypts and authenticates a versioned security payload.
+	 *
+	 * @param payload - Encrypted payload created by {@link encrypt}.
+	 * @param options - Additional authenticated data supplied during encryption.
+	 * @returns Decrypted plaintext bytes.
+	 */
+	decrypt(
+		payload: string,
+		options: security.SecurityPayloadOptions = {},
+	): Buffer {
+		const parsed = parsePayload(payload);
+		const configuredCipher = this.#cipher();
+
+		if (parsed.cipher !== configuredCipher) {
+			throw new SecurityError(
+				`Encrypted payload uses unsupported cipher "${parsed.cipher}".`,
+			);
+		}
+
+		try {
+			const decipher = createDecipheriv(
+				configuredCipher,
+				this.#key(),
+				parsed.initializationVector,
+			);
+
+			decipher.setAAD(additionalAuthenticatedData(options));
+			decipher.setAuthTag(parsed.authenticationTag);
+
+			return Buffer.concat([
+				decipher.update(parsed.ciphertext),
+				decipher.final(),
+			]);
+		} catch (error) {
+			if (error instanceof SecurityError) throw error;
+
+			throw new SecurityError(
+				'Encrypted payload could not be decrypted. Verify the application key and payload integrity.',
+				{ cause: error },
+			);
+		}
+	}
+
+	/**
+	 * Serializes and encrypts a JSON-compatible value.
+	 *
+	 * @param value - JSON-compatible value to protect.
+	 * @param options - Optional additional authenticated ownership context.
+	 * @returns Versioned encrypted payload safe for text storage.
+	 */
+	encryptJson<TValue>(
+		value: TValue,
+		options: security.SecurityPayloadOptions = {},
+	): string {
+		let serialized: string;
+
+		try {
+			const json = JSON.stringify(value);
+
+			if (json === undefined) {
+				throw new TypeError('Value is not JSON serializable.');
+			}
+
+			serialized = json;
+		} catch (error) {
+			throw new SecurityError(
+				'Security value could not be serialized as JSON.',
+				{ cause: error },
+			);
+		}
+
+		return this.encrypt(serialized, options);
+	}
+
+	/**
+	 * Decrypts and parses a JSON-compatible value.
+	 *
+	 * @param payload - Encrypted JSON payload created by {@link encryptJson}.
+	 * @param options - Additional authenticated data supplied during encryption.
+	 * @returns Decrypted and parsed JSON value.
+	 */
+	decryptJson<TValue>(
+		payload: string,
+		options: security.SecurityPayloadOptions = {},
+	): TValue {
+		const plaintext = this.decrypt(payload, options).toString('utf8');
+
+		try {
+			return JSON.parse(plaintext) as TValue;
+		} catch (error) {
+			throw new SecurityError(
+				'Decrypted security payload does not contain valid JSON.',
+				{ cause: error },
+			);
+		}
+	}
+
+	/**
+	 * Resolves and validates the configured encryption cipher.
+	 *
+	 * @returns Supported authenticated encryption cipher.
+	 */
+	#cipher(): security.SecurityCipher {
+		const cipher = this.#options.cipher ?? DEFAULT_CIPHER;
+
+		if (cipher !== DEFAULT_CIPHER) {
+			throw new SecurityError(`Unsupported security cipher "${String(cipher)}".`);
+		}
+
+		return cipher;
+	}
+
+	/**
+	 * Resolves and validates the central 256-bit application key.
+	 *
+	 * @returns Raw AES-256 key bytes.
+	 */
+	#key(): Buffer {
+		return this.#encryptionKey;
+	}
+
+	/**
+	 * Validates configured key material and returns detached raw bytes.
+	 *
+	 * @param input - Raw or encoded application key.
+	 * @returns Validated AES-256 key bytes.
+	 */
+	#validateKey(input: string | Buffer | undefined): Buffer {
+		if (
+			input === undefined
+			|| (typeof input === 'string' && input.trim() === '')
+			|| (Buffer.isBuffer(input) && input.length === 0)
+		) {
+			throw new SecurityError(
+				'Application security requires a configured 32-byte key.',
+			);
+		}
+
+		const key = securityKeyBuffer(input);
+
+		if (key.length !== ENCRYPTION_KEY_BYTES) {
+			throw new SecurityError(
+				'Application security key must contain exactly 32 bytes.',
+			);
+		}
+
+		return key;
+	}
+}
+
+/**
+ * Parsed authenticated encryption payload.
+ */
+interface ParsedSecurityPayload {
+	/** Cipher recorded by the payload format. */
+	cipher: string;
+
+	/** Random initialization vector used for this payload. */
+	initializationVector: Buffer;
+
+	/** GCM authentication tag protecting ciphertext and caller context. */
+	authenticationTag: Buffer;
+
+	/** Encrypted plaintext bytes. */
+	ciphertext: Buffer;
+}
+
+/**
+ * Parses and validates the non-secret structure of an encrypted payload.
+ *
+ * @param payload - Versioned encrypted payload.
+ * @returns Validated cipher and binary payload components.
+ */
+function parsePayload(payload: string): ParsedSecurityPayload {
+	const parts = payload.split(':');
+	const [format, version, cipher, encodedIv, encodedTag, encodedCiphertext] = parts;
+
+	if (
+		parts.length !== 6
+		|| format !== PAYLOAD_FORMAT
+		|| version !== PAYLOAD_VERSION
+		|| !cipher
+		|| !encodedIv
+		|| !encodedTag
+		|| encodedCiphertext === undefined
+	) {
+		throw new SecurityError('Encrypted payload has an unsupported or malformed format.');
+	}
+
+	const initializationVector = Buffer.from(encodedIv, 'base64url');
+	const authenticationTag = Buffer.from(encodedTag, 'base64url');
+	const ciphertext = Buffer.from(encodedCiphertext, 'base64url');
+
+	if (
+		initializationVector.length !== INITIALIZATION_VECTOR_BYTES
+		|| authenticationTag.length !== AUTHENTICATION_TAG_BYTES
+	) {
+		throw new SecurityError('Encrypted payload has an unsupported or malformed format.');
+	}
+
+	return {
+		cipher,
+		initializationVector,
+		authenticationTag,
+		ciphertext,
+	};
+}
+
+/**
+ * Converts configured key input into raw bytes.
+ *
+ * @param input - Raw, UTF-8, or `base64:`-prefixed key material.
+ * @returns Raw encryption key bytes.
+ */
+function securityKeyBuffer(input: string | Buffer): Buffer {
+	if (Buffer.isBuffer(input)) return Buffer.from(input);
+
+	const value = input.trim();
+
+	return value.startsWith('base64:')
+		? Buffer.from(value.slice('base64:'.length), 'base64')
+		: Buffer.from(value, 'utf8');
+}
+
+/**
+ * Converts text or byte input into a detached buffer.
+ *
+ * @param value - Text or bytes supplied by the caller.
+ * @returns Plaintext buffer.
+ */
+function bufferValue(value: string | Buffer): Buffer {
+	return Buffer.isBuffer(value)
+		? Buffer.from(value)
+		: Buffer.from(value, 'utf8');
+}
+
+/**
+ * Resolves additional authenticated data into bytes.
+ *
+ * @param options - Caller-provided authenticated context.
+ * @returns Context bytes, or an empty buffer.
+ */
+function additionalAuthenticatedData(
+	options: security.SecurityPayloadOptions,
+): Buffer {
+	const value = options.additionalAuthenticatedData;
+
+	if (value === undefined) return Buffer.alloc(0);
+
+	return bufferValue(value);
+}

package/src/security/SecurityError.ts

@@ -0,0 +1,16 @@
+/**
+ * Error raised when the application security service cannot safely complete an
+ * encryption, decryption, or key operation.
+ */
+export class SecurityError extends Error {
+	/**
+	 * Creates a security error with a message that must not contain protected data.
+	 *
+	 * @param message - User-safe explanation of the security failure.
+	 * @param options - Optional error cause retained for server-side diagnostics.
+	 */
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = 'SecurityError';
+	}
+}

package/src/security/contracts/SecurityOptions.ts

@@ -0,0 +1,20 @@
+import type { Buffer } from 'node:buffer';
+
+/**
+ * Authenticated encryption ciphers supported by the framework security service.
+ */
+export type SecurityCipher = 'aes-256-gcm';
+
+/**
+ * Central application security configuration.
+ */
+export interface SecurityOptions {
+	/**
+	 * Application encryption key as 32 raw bytes, a 32-byte UTF-8 string, or a
+	 * `base64:`-prefixed value.
+	 */
+	key?: string | Buffer;
+
+	/** Authenticated encryption cipher used for new payloads. */
+	cipher?: SecurityCipher;
+}

package/src/security/contracts/SecurityPayload.ts

@@ -0,0 +1,14 @@
+import type { Buffer } from 'node:buffer';
+
+/**
+ * Per-operation options for authenticated encryption and decryption.
+ */
+export interface SecurityPayloadOptions {
+	/**
+	 * Optional context authenticated with the payload but not stored inside it.
+	 *
+	 * Callers can use this to bind ciphertext to a model field, tenant, or other
+	 * stable ownership boundary.
+	 */
+	additionalAuthenticatedData?: string | Buffer;
+}

package/src/security/contracts/index.ts

@@ -0,0 +1,2 @@
+export * from './SecurityOptions';
+export * from './SecurityPayload';

package/src/security/ensureAppKey.ts

@@ -0,0 +1,82 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'dotenv';
+import { Security } from './Security';
+import { SecurityError } from './SecurityError';
+
+/**
+ * Returns the conventional `APP_KEY`, generating it in `.env` when missing.
+ *
+ * Applications should normally call this from their security config after
+ * checking the environment. Existing non-empty values are preserved so invalid
+ * keys fail normal security validation instead of being silently replaced.
+ *
+ * @returns Existing or newly generated application key.
+ * @throws {SecurityError} When `.env` cannot be read or updated.
+ *
+ * @example
+ * export default defineConfig({
+ * 	key: env.string('APP_KEY') || ensureAppKey(),
+ * });
+ */
+export function ensureAppKey(): string {
+	const environmentKey = process.env.APP_KEY?.trim();
+
+	if (environmentKey) return environmentKey;
+
+	const environmentFile = resolve(process.cwd(), '.env');
+
+	try {
+		let content = '';
+
+		try {
+			content = readFileSync(environmentFile, 'utf8');
+		} catch (error) {
+			if (
+				typeof error !== 'object'
+				|| error === null
+				|| !('code' in error)
+				|| error.code !== 'ENOENT'
+			) {
+				throw error;
+			}
+		}
+
+		const fileKey = parse(content).APP_KEY?.trim();
+
+		if (fileKey) {
+			process.env.APP_KEY = fileKey;
+			return fileKey;
+		}
+
+		const generatedKey = Security.generateKey();
+		const keyLine = `APP_KEY=${generatedKey}`;
+		const existingKeyLine = /^(?:export\s+)?APP_KEY\s*=.*$/m;
+		let updatedContent: string;
+
+		if (existingKeyLine.test(content)) {
+			updatedContent = content.replace(existingKeyLine, keyLine);
+		} else {
+			const separator = content.length > 0 && !content.endsWith('\n')
+				? '\n'
+				: '';
+
+			updatedContent = `${content}${separator}${keyLine}\n`;
+		}
+
+		writeFileSync(environmentFile, updatedContent, {
+			encoding: 'utf8',
+			mode: 0o600,
+		});
+		process.env.APP_KEY = generatedKey;
+
+		return generatedKey;
+	} catch (error) {
+		if (error instanceof SecurityError) throw error;
+
+		throw new SecurityError(
+			'Application security could not persist APP_KEY to ".env".',
+			{ cause: error },
+		);
+	}
+}

package/src/security/examples/runSecretRoundTrip.ts

@@ -0,0 +1,42 @@
+import { Buffer } from 'node:buffer';
+import { pathToFileURL } from 'node:url';
+import { Security, SecurityError } from '@db3.ai/app/security';
+import { App } from '@db3.ai/app/server';
+
+/**
+ * Encrypts an ephemeral example secret and proves rejection of altered context/data.
+ *
+ * Keys are generated only for this disposable lab. No dotenv file is changed and
+ * no key, plaintext or ciphertext is returned. Persistent apps must retain one key.
+ *
+ * @returns Non-sensitive round-trip and integrity-check outcomes.
+ */
+export async function runSecretRoundTrip() {
+	const application = new App({ config: { security: { key: Security.generateKey() } }, dbOptions: { syncColumns: false } });
+	try {
+		const security = application.security;
+		const context = { additionalAuthenticatedData: 'notes:ada:integration' };
+		const secret = { token: 'example-secret-not-for-output' };
+		const payload = security.encryptJson(secret, context);
+		const second = security.encryptJson(secret, context);
+		const decrypted = security.decryptJson<typeof secret>(payload, context);
+		const parts = payload.split(':');
+		const encryptedBytes = Buffer.from(parts[5]!, 'base64url');
+		encryptedBytes[0] = encryptedBytes[0]! ^ 1;
+		parts[5] = encryptedBytes.toString('base64url');
+		return {
+			roundTrip: decrypted.token === secret.token,
+			randomized: payload !== second,
+			contextRejected: rejectsSecurity(() => security.decryptJson(payload, { additionalAuthenticatedData: 'notes:grace:integration' })),
+			tamperingRejected: rejectsSecurity(() => security.decryptJson(parts.join(':'), context)),
+			nonJsonRejected: rejectsSecurity(() => security.encryptJson(undefined)),
+		};
+	} finally { await application.close(); }
+}
+
+/** Returns true only for the expected safe framework security error. */
+function rejectsSecurity(operation: () => unknown): boolean {
+	try { operation(); return false; } catch (error) { if (error instanceof SecurityError) return true; throw error; }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) console.log(JSON.stringify(await runSecretRoundTrip(), null, 2));

package/src/security/index.ts

@@ -0,0 +1,4 @@
+export * from './contracts';
+export * from './ensureAppKey';
+export * from './Security';
+export * from './SecurityError';

package/src/serialization/README.md

@@ -0,0 +1,169 @@
+# Serialization
+
+## Runnable scalar-state example
+
+Copy `src/serialization/examples/` from the installed package into `examples/`
+and run `npx tsx examples/runExportSerialization.ts`. The registered request
+crosses a real JSON boundary, initializes private state, rejects a missing
+worker registration and invalid state, then recovers. It requires no SQL.
+The website includes `tests/examples/runExportSerialization.test.ts` as an
+exact consumer-copyable test. Model-reference behavior remains covered by the
+separate service SQL tests, not this scalar-identity example.
+
+The framework serializer reconstructs one registered root class from durable
+constructor state. It produces a versioned JSON-safe envelope and restores that
+object inside a bootstrapped application process.
+
+The service is available through `app().serializer`. Its application-scoped
+allowlist is available through `app().serializer.registry`.
+
+## Application configuration
+
+Register root classes and ActiveRecord models with explicit stable names:
+
+```ts
+import type { SerializerOptions } from '@db3.ai/app/serialization';
+
+const serializer: SerializerOptions = {
+	classes: {
+		'report.request': ReportRequest,
+	},
+	models: {
+		'app.user': User,
+		'app.website': Website,
+	},
+};
+
+new App({
+	serializer,
+});
+```
+
+The same entries can be registered during application boot:
+
+```ts
+app().serializer.registry.registerClass('report.request', ReportRequest);
+app().serializer.registry.registerModel('app.website', Website);
+```
+
+Registration is idempotent for the same name and constructor. Reusing a name
+or constructor for a different entry throws. The names are durable wire
+contracts, so stored payloads must be migrated or discarded before a name
+changes.
+
+Every producer and worker process must install the same registrations during
+boot. A process-local registration performed only while dispatching cannot make
+the constructor available to another queue worker.
+
+## Root constructor contract
+
+A registered root class implements `Serializable<TState>`. Its `toJSON()`
+method returns the complete state accepted by its one-argument constructor:
+
+```ts
+import type { Serializable } from '@db3.ai/app/serialization';
+
+interface ReportRequestState {
+	website: Website;
+	options: {
+		includeDrafts: boolean;
+	};
+}
+
+class ReportRequest implements Serializable<ReportRequestState> {
+	/**
+	 * Creates a report request from its complete runtime state.
+	 *
+	 * @param state - State used for both direct and restored construction.
+	 */
+	constructor(readonly state: ReportRequestState) {}
+
+	/**
+	 * Returns the state needed to call this constructor again.
+	 *
+	 * @returns Complete report request constructor state.
+	 */
+	toJSON(): ReportRequestState {
+		return this.state;
+	}
+}
+```
+
+Serialization resolves the instance's exact registered prototype and invokes
+that prototype's `toJSON()` exactly once. It does not inspect arbitrary root
+properties or invoke `toJSON()` on nested values.
+
+Deserialization validates the entire envelope, restores nested ActiveRecord
+references, and then calls `new RegisteredClass(state)`. Normal constructor
+validation therefore runs in both direct and restored execution, and private
+fields are initialized normally.
+
+## Constructor state
+
+Constructor state supports ordinary JSON values:
+
+- `null`, strings, booleans, and finite numbers;
+- dense arrays; and
+- plain objects through their normal enumerable string properties.
+
+Registered ActiveRecord instances are the only non-JSON values supported
+inside that state. Nested application classes, `undefined`, `bigint`, `Date`,
+functions, maps, sets, custom object prototypes, sparse arrays, invalid
+numbers, and cycles throw a path-aware `SerializationError`. As with ordinary
+JSON, symbol and non-enumerable properties are outside the serialized shape,
+and enumerable getters are read. Repeated non-cyclic plain objects are copied
+and do not preserve object identity.
+
+The `$platform` object key is reserved for framework reference markers. Convert
+optional or specialist runtime values to an intentional JSON representation in
+the root class's `toJSON()` result.
+
+## ActiveRecord references
+
+A registered, clean, persisted ActiveRecord is stored as a model key and
+logical primary key rather than as an attribute snapshot:
+
+```json
+{
+	"$platform": "active-record",
+	"model": "app.website",
+	"id": "01J..."
+}
+```
+
+Serialization rejects a record that is unregistered, unsaved, dirty, missing a
+supported string or safe-integer primary key, or already soft deleted. Dirty
+checks include in-place changes to structured field values.
+
+Deserialization resolves the registered model and calls `findOrFail()` through
+the active application database. The restored object therefore contains the
+current stored row, not a stale attribute snapshot. Repeated references to the
+same model and primary key share one lookup and restored instance. Errors
+distinguish a missing row from another database restoration failure.
+
+If a missing record should be a valid no-op for a workflow, store its scalar id
+as ordinary constructor state and perform that optional lookup in the workflow.
+
+## Envelope and validation
+
+The wire shape is explicit and versioned:
+
+```json
+{
+	"format": "platform.serialized-object",
+	"version": 1,
+	"name": "report.request",
+	"state": {}
+}
+```
+
+The complete envelope is validated before any database query or root
+constructor call.
+
+Use a real JSON boundary when verifying durable values:
+
+```ts
+const payload = app().serializer.serialize(value);
+const durablePayload = JSON.parse(JSON.stringify(payload));
+const restored = await app().serializer.deserialize(durablePayload);
+```