@db3.ai/app 0.1.0-beta.1

package/dist/scheduler/index.d.ts

@@ -0,0 +1,9 @@
+export * from './contracts/index.js';
+export * from './console.js';
+export * from './Scheduler.js';
+export * from './ScheduledCall.js';
+export * from './ScheduledEvent.js';
+export * from './ScheduledJob.js';
+export * from './ScheduledOccurrence.js';
+export * from './ScheduledOccurrenceRecorder.js';
+export * from './SchedulerWorker.js';

package/dist/scheduler/index.js

@@ -0,0 +1,9 @@
+export * from './contracts/index.js';
+export * from './console.js';
+export * from './Scheduler.js';
+export * from './ScheduledCall.js';
+export * from './ScheduledEvent.js';
+export * from './ScheduledJob.js';
+export * from './ScheduledOccurrence.js';
+export * from './ScheduledOccurrenceRecorder.js';
+export * from './SchedulerWorker.js';

package/dist/scheduler/scheduleTime.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Validates and normalizes one daily wall-clock time.
+ *
+ * @param value - Candidate time in 24-hour HH:mm form.
+ * @returns Validated time.
+ */
+export declare function normalizeDailyTime(value: string): string;
+/**
+ * Validates one IANA timezone using the platform Intl implementation.
+ *
+ * @param value - Candidate IANA timezone.
+ * @returns Validated timezone.
+ */
+export declare function normalizeScheduleTimezone(value: string): string;
+/**
+ * Returns whether a UTC instant matches one daily local schedule.
+ *
+ * @param instant - UTC instant being evaluated.
+ * @param time - Local HH:mm schedule time.
+ * @param timezone - IANA timezone used for local interpretation.
+ * @returns True when the local hour and minute match.
+ */
+export declare function dailyScheduleIsDue(instant: Date, time: string, timezone: string): boolean;
+/**
+ * Floors an instant to its canonical UTC minute.
+ *
+ * @param instant - Instant to normalize.
+ * @returns New Date at second and millisecond zero.
+ */
+export declare function utcMinute(instant: Date): Date;

package/dist/scheduler/scheduleTime.js

@@ -0,0 +1,64 @@
+const DAILY_TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/;
+/**
+ * Validates and normalizes one daily wall-clock time.
+ *
+ * @param value - Candidate time in 24-hour HH:mm form.
+ * @returns Validated time.
+ */
+export function normalizeDailyTime(value) {
+    const normalized = value.trim();
+    if (!DAILY_TIME_PATTERN.test(normalized)) {
+        throw new Error(`Invalid daily schedule time "${value}". Use HH:mm in 24-hour time.`);
+    }
+    return normalized;
+}
+/**
+ * Validates one IANA timezone using the platform Intl implementation.
+ *
+ * @param value - Candidate IANA timezone.
+ * @returns Validated timezone.
+ */
+export function normalizeScheduleTimezone(value) {
+    const normalized = value.trim();
+    try {
+        new Intl.DateTimeFormat('en-GB', {
+            timeZone: normalized,
+        }).format(new Date(0));
+    }
+    catch {
+        throw new Error(`Invalid scheduler timezone "${value}". Use an IANA timezone name.`);
+    }
+    return normalized;
+}
+/**
+ * Returns whether a UTC instant matches one daily local schedule.
+ *
+ * @param instant - UTC instant being evaluated.
+ * @param time - Local HH:mm schedule time.
+ * @param timezone - IANA timezone used for local interpretation.
+ * @returns True when the local hour and minute match.
+ */
+export function dailyScheduleIsDue(instant, time, timezone) {
+    const parts = new Intl.DateTimeFormat('en-GB', {
+        timeZone: timezone,
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(instant);
+    const hour = parts.find(part => part.type === 'hour')?.value;
+    const minute = parts.find(part => part.type === 'minute')?.value;
+    return `${hour}:${minute}` === time;
+}
+/**
+ * Floors an instant to its canonical UTC minute.
+ *
+ * @param instant - Instant to normalize.
+ * @returns New Date at second and millisecond zero.
+ */
+export function utcMinute(instant) {
+    const time = instant.getTime();
+    if (!Number.isFinite(time)) {
+        throw new Error('Scheduler requires a valid evaluation date.');
+    }
+    return new Date(Math.floor(time / 60_000) * 60_000);
+}

package/dist/security/Security.d.ts

@@ -0,0 +1,60 @@
+import { Buffer } from 'node:buffer';
+import type * as security from './contracts/index.js';
+/**
+ * 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 declare class Security {
+    #private;
+    /**
+     * Creates the application security service from the active app config.
+     */
+    constructor();
+    /**
+     * Generates a new base64-formatted 256-bit application key.
+     *
+     * @returns Value suitable for an `APP_KEY` environment variable.
+     */
+    static generateKey(): string;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}

package/dist/security/Security.js

@@ -0,0 +1,252 @@
+import { Buffer } from 'node:buffer';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { app } from '../server/appContext.js';
+import { SecurityError } from './SecurityError.js';
+const DEFAULT_CIPHER = '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.
+     */
+    #options;
+    /**
+     * Validated key pinned for this service lifetime.
+     */
+    #encryptionKey;
+    /**
+     * Creates the application security service from the active app config.
+     */
+    constructor() {
+        const options = app().config.get('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() {
+        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, options = {}) {
+        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, options = {}) {
+        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(value, options = {}) {
+        let serialized;
+        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(payload, options = {}) {
+        const plaintext = this.decrypt(payload, options).toString('utf8');
+        try {
+            return JSON.parse(plaintext);
+        }
+        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() {
+        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() {
+        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) {
+        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;
+    }
+}
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    const value = options.additionalAuthenticatedData;
+    if (value === undefined)
+        return Buffer.alloc(0);
+    return bufferValue(value);
+}

package/dist/security/SecurityError.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Error raised when the application security service cannot safely complete an
+ * encryption, decryption, or key operation.
+ */
+export declare 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);
+}

package/dist/security/SecurityError.js

@@ -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, options) {
+        super(message, options);
+        this.name = 'SecurityError';
+    }
+}

package/dist/security/contracts/SecurityOptions.d.ts

@@ -0,0 +1,17 @@
+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/dist/security/contracts/SecurityOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/security/contracts/SecurityPayload.d.ts

@@ -0,0 +1,13 @@
+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/dist/security/contracts/SecurityPayload.js

@@ -0,0 +1 @@
+export {};

package/dist/security/contracts/index.d.ts

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

package/dist/security/contracts/index.js

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

package/dist/security/ensureAppKey.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function ensureAppKey(): string;

package/dist/security/ensureAppKey.js

@@ -0,0 +1,69 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse } from 'dotenv';
+import { Security } from './Security.js';
+import { SecurityError } from './SecurityError.js';
+/**
+ * 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() {
+    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;
+        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/dist/security/index.d.ts

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

package/dist/security/index.js

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

package/dist/serialization/Serializable.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Constructor-backed object that exposes its complete durable state.
+ *
+ * The returned state must contain only JSON values and registered
+ * ActiveRecord instances. Deserialization passes the restored state back to
+ * the registered class constructor.
+ *
+ * @template TState - Complete state accepted by the concrete class constructor.
+ */
+export interface Serializable<TState = unknown> {
+    /**
+     * Returns the complete state needed to reconstruct this object.
+     *
+     * @returns Constructor state containing JSON values and registered records.
+     */
+    toJSON(): TState;
+}

package/dist/serialization/Serializable.js

@@ -0,0 +1 @@
+export {};

package/dist/serialization/SerializationError.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Serializer operation that rejected a runtime or durable value.
+ */
+export type SerializationOperation = 'serialize' | 'deserialize';
+/**
+ * Stable failure categories exposed by SerializationError.
+ */
+export type SerializationErrorCode = 'unsupported_type' | 'invalid_value' | 'circular_reference' | 'unregistered_class' | 'unregistered_model' | 'unsaved_active_record' | 'dirty_active_record' | 'trashed_active_record' | 'active_record_not_found' | 'active_record_restore_failed' | 'invalid_payload' | 'unsupported_version' | 'class_construction_failed';
+/**
+ * Structured details used to create a safe serializer failure.
+ */
+export interface SerializationErrorOptions {
+    /** Operation that raised the failure. */
+    operation: SerializationOperation;
+    /** Stable machine-readable failure category. */
+    code: SerializationErrorCode;
+    /** JSONPath-like location of the rejected value. */
+    path: string;
+    /** Safe explanation that does not stringify the rejected value. */
+    message: string;
+    /** Lower-level error retained for diagnostics. */
+    cause?: unknown;
+}
+/**
+ * Error raised when runtime state cannot be serialized or restored losslessly.
+ */
+export declare class SerializationError extends Error {
+    /** Operation that raised this error. */
+    readonly operation: SerializationOperation;
+    /** Stable machine-readable failure category. */
+    readonly code: SerializationErrorCode;
+    /** JSONPath-like location of the rejected value. */
+    readonly path: string;
+    /**
+     * Creates one path-aware serializer failure.
+     *
+     * @param options - Safe structured failure details.
+     */
+    constructor(options: SerializationErrorOptions);
+}