@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/logging/transports/EmailLogTransport.d.ts

@@ -0,0 +1,18 @@
+import type { Mail } from '../../mail/index.js';
+import type { EmailLogOptions } from '../contracts/index.js';
+/**
+ * Sends each serialized error/fatal log through Mail once, in arrival order.
+ * Pending sends live in memory; flush/close drains them. Provider failures go to
+ * stderr without recursive logging, retry, cooldown, grouping or suppression of later records.
+ */
+export declare class EmailLogTransport {
+    #private;
+    readonly options: EmailLogOptions;
+    readonly mail: () => Mail;
+    /** Resolves Mail lazily so constructing an application logger does not initialize mail providers. */
+    constructor(options: EmailLogOptions, mail: () => Mail);
+    /** Accepts Pino JSON lines after serialization and configured field redaction. */
+    write(line: string): void;
+    /** Waits for all accepted sends, including records appended while a flush is in progress. */
+    flush(): Promise<void>;
+}

package/dist/logging/transports/EmailLogTransport.js

@@ -0,0 +1,47 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { formatLogEmail } from '../formatLogEmail.js';
+const deliveringEmail = new AsyncLocalStorage();
+/**
+ * Sends each serialized error/fatal log through Mail once, in arrival order.
+ * Pending sends live in memory; flush/close drains them. Provider failures go to
+ * stderr without recursive logging, retry, cooldown, grouping or suppression of later records.
+ */
+export class EmailLogTransport {
+    options;
+    mail;
+    #pending = Promise.resolve();
+    /** Resolves Mail lazily so constructing an application logger does not initialize mail providers. */
+    constructor(options, mail) {
+        this.options = options;
+        this.mail = mail;
+    }
+    /** Accepts Pino JSON lines after serialization and configured field redaction. */
+    write(line) {
+        if (deliveringEmail.getStore())
+            return;
+        try {
+            const record = JSON.parse(line);
+            const message = formatLogEmail(record, this.options);
+            this.#pending = this.#pending.then(() => deliveringEmail.run(true, async () => {
+                try {
+                    await this.mail().send(message);
+                }
+                catch {
+                    // Never include provider errors here: they can contain credentials or request bodies.
+                    process.stderr.write('[logging] Error email delivery failed; original record remains in configured log destinations.\n');
+                }
+            }));
+        }
+        catch {
+            process.stderr.write('[logging] Error email formatting failed; original record remains in configured log destinations.\n');
+        }
+    }
+    /** Waits for all accepted sends, including records appended while a flush is in progress. */
+    async flush() {
+        let pending;
+        do {
+            pending = this.#pending;
+            await pending;
+        } while (pending !== this.#pending);
+    }
+}

package/dist/mail/Mail.d.ts

@@ -12,6 +12,8 @@ export interface MailMessage {
     html?: string;
     /** Extra message headers; File and Resend preserve them, Mailgun currently does not. */
     headers?: Record<string, string>;
+    /** Stable request identity for provider retries. Resend deduplicates identical requests for 24 hours; other built-in transports ignore this value. */
+    idempotencyKey?: string;
 }
 /** Transport input with a default sender resolved and recipients normalized to an array. */
 export interface ResolvedMailMessage extends Omit<MailMessage, 'from' | 'to'> {

package/dist/mail/Mail.js

@@ -18,6 +18,9 @@ export class Mail {
     }
     /** Resolves the sender and recipient list without changing application content. */
     resolveMessage(message) {
+        if (message.idempotencyKey !== undefined && !/^[\x21-\x7e]{1,256}$/.test(message.idempotencyKey)) {
+            throw new Error('Mail idempotencyKey must contain 1 to 256 printable non-space ASCII characters.');
+        }
         const to = Array.isArray(message.to) ? message.to : [message.to];
         if (to.length === 0) {
             throw new Error('Mail requires at least one recipient.');

package/dist/mail/MailDeliveryError.d.ts

@@ -0,0 +1,9 @@
+/** Structured provider refusal; consumers decide retry policy without parsing diagnostic messages. */
+export declare class MailDeliveryError extends Error {
+    readonly provider: string;
+    readonly status: number;
+    readonly code: string | null;
+    readonly retryAt: Date | null;
+    /** Creates a refusal retaining the provider code, HTTP status and optional validated retry time. */
+    constructor(message: string, provider: string, status: number, code: string | null, retryAt?: Date | null);
+}

package/dist/mail/MailDeliveryError.js

@@ -0,0 +1,16 @@
+/** Structured provider refusal; consumers decide retry policy without parsing diagnostic messages. */
+export class MailDeliveryError extends Error {
+    provider;
+    status;
+    code;
+    retryAt;
+    /** Creates a refusal retaining the provider code, HTTP status and optional validated retry time. */
+    constructor(message, provider, status, code, retryAt = null) {
+        super(message);
+        this.provider = provider;
+        this.status = status;
+        this.code = code;
+        this.retryAt = retryAt;
+        this.name = 'MailDeliveryError';
+    }
+}

package/dist/mail/index.d.ts

@@ -2,3 +2,4 @@ export * from './Mail.js';
 export * from './transports/FileMailTransport.js';
 export * from './transports/MailgunTransport.js';
 export * from './transports/ResendTransport.js';
+export * from './MailDeliveryError.js';

package/dist/mail/index.js

@@ -2,3 +2,4 @@ export * from './Mail.js';
 export * from './transports/FileMailTransport.js';
 export * from './transports/MailgunTransport.js';
 export * from './transports/ResendTransport.js';
+export * from './MailDeliveryError.js';

package/dist/mail/transports/MailgunTransport.js

@@ -35,6 +35,8 @@ export class MailgunTransport {
         }
         const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
             method: 'POST',
+            signal: AbortSignal.timeout(15000),
+            redirect: 'error',
             headers: {
                 authorization: `Basic ${Buffer.from(`api:${this.apiKey}`).toString('base64')}`,
             },

package/dist/mail/transports/ResendTransport.d.ts

@@ -7,8 +7,9 @@ export interface ResendTransportOptions {
  * Resend API transport.
  */
 export declare class ResendTransport implements MailTransport {
-    private readonly apiKey;
-    private readonly baseUrl;
+    #private;
+    /** Creates a bounded Resend transport; credentials remain private to this instance. */
     constructor(options: ResendTransportOptions);
+    /** Sends one message, forwarding a stable retry identity as an API header rather than an email header. */
     send(message: ResolvedMailMessage): Promise<MailDelivery>;
 }

package/dist/mail/transports/ResendTransport.js

@@ -1,20 +1,17 @@
-import { formatMailAddress, mailAddressEmail, } from '../Mail.js';
-class ResendTransportError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ResendTransportError';
-    }
-}
+import { MailDeliveryError } from '../MailDeliveryError.js';
+import { formatMailAddress, mailAddressEmail } from '../Mail.js';
 /**
  * Resend API transport.
  */
 export class ResendTransport {
-    apiKey;
-    baseUrl;
+    #apiKey;
+    #baseUrl;
+    /** Creates a bounded Resend transport; credentials remain private to this instance. */
     constructor(options) {
-        this.apiKey = options.apiKey;
-        this.baseUrl = (options.baseUrl || 'https://api.resend.com').replace(/\/+$/, '');
+        this.#apiKey = options.apiKey;
+        this.#baseUrl = (options.baseUrl || 'https://api.resend.com').replace(/\/+$/, '');
     }
+    /** Sends one message, forwarding a stable retry identity as an API header rather than an email header. */
     async send(message) {
         const payload = {
             from: formatMailAddress(message.from),
@@ -30,11 +27,14 @@ export class ResendTransport {
         if (message.headers) {
             payload.headers = message.headers;
         }
-        const response = await fetch(`${this.baseUrl}/emails`, {
+        const response = await fetch(`${this.#baseUrl}/emails`, {
             method: 'POST',
+            signal: AbortSignal.timeout(15000),
+            redirect: 'error',
             headers: {
-                authorization: `Bearer ${this.apiKey}`,
+                authorization: `Bearer ${this.#apiKey}`,
                 'content-type': 'application/json',
+                ...(message.idempotencyKey ? { 'Idempotency-Key': message.idempotencyKey } : {}),
             },
             body: JSON.stringify(payload),
         });
@@ -43,7 +43,8 @@ export class ResendTransport {
             const detail = typeof result?.message === 'string'
                 ? result.message
                 : response.statusText;
-            throw new ResendTransportError(`Resend rejected the message: ${detail}`);
+            const code = typeof result?.name === 'string' && /^[a-z_]{1,100}$/.test(result.name) ? result.name : null;
+            throw new MailDeliveryError(`Resend rejected the message: ${detail}`, 'resend', response.status, code, retryTime(response.headers.get('retry-after')));
         }
         return {
             id: typeof result?.id === 'string' ? result.id : '',
@@ -53,3 +54,10 @@ export class ResendTransport {
         };
     }
 }
+/** Parses standard Retry-After seconds or HTTP dates, ignoring malformed, overflowing and past values. */
+function retryTime(value) {
+    if (!value)
+        return null;
+    const milliseconds = /^\d+$/.test(value) ? Date.now() + Number(value) * 1000 : Date.parse(value);
+    return Number.isFinite(milliseconds) && milliseconds > Date.now() && milliseconds <= 8640000000000000 ? new Date(milliseconds) : null;
+}

package/dist/media/MediaManager.d.ts

@@ -26,6 +26,7 @@ export declare class MediaManager {
     constructor(storage: Storage, options?: MediaOptions, imageProcessor?: ImageProcessor);
     /**
      * Finds or creates the media library for an application-owned scope.
+     * Concurrent creators reuse the winning row without overwriting its defaults.
      *
      * @param input - Scope identity and defaults for a new library.
      * @returns Existing or newly-created media library.
@@ -111,14 +112,15 @@ export declare class MediaManager {
      */
     deleteFile(fileOrId: MediaFile | string): Promise<void>;
     /**
-     * Finds or creates the root browser item for a library.
+     * Finds or creates the root browser item for a library, including concurrent writers.
      *
      * @param libraryOrId - Media library row or id.
      * @returns Root browser item for the library.
      */
     rootFor(libraryOrId: MediaLibraryInput): Promise<MediaItem>;
     /**
-     * Finds or creates a slash-prefixed browser folder path.
+     * Finds or creates a slash-prefixed browser folder path. Concurrent creators
+     * reuse the winning directory without replacing its metadata.
      *
      * @param input - Library and folder path to ensure.
      * @returns Folder item for the requested path, or the root for `/`.

package/dist/media/MediaManager.js

@@ -1,4 +1,4 @@
-import { mimeTypeFromPath } from '../storage/mime.js';
+import { mimeTypeFromPath } from '../storage/mimeTypeFromPath.js';
 import { normalizeStoragePath } from '../storage/path.js';
 import { MEDIA_FILE_VISIBILITY, MEDIA_ITEM_TYPE, MEDIA_LIBRARY_DEFAULT_KEY } from './constants.js';
 import { ImageReconstructionError, ImageVariantRenderer, SharpImageProcessor } from './image/index.js';
@@ -38,6 +38,7 @@ export class MediaManager {
     }
     /**
      * Finds or creates the media library for an application-owned scope.
+     * Concurrent creators reuse the winning row without overwriting its defaults.
      *
      * @param input - Scope identity and defaults for a new library.
      * @returns Existing or newly-created media library.
@@ -72,8 +73,18 @@ export class MediaManager {
             pathPrefix: input.pathPrefix ?? null,
             meta: input.meta ?? null,
         });
-        await library.save();
-        return library;
+        try {
+            await library.save();
+            return library;
+        }
+        catch (error) {
+            if (!isUniqueConstraintError(error) && !isRetriableTransactionConflict(error))
+                throw error;
+            const raced = await MediaLibrary.where({ scopeType, scopeId, key }).first();
+            if (!raced)
+                throw error;
+            return raced;
+        }
     }
     /**
      * Loads one media library by id.
@@ -181,7 +192,7 @@ export class MediaManager {
         await file.delete();
     }
     /**
-     * Finds or creates the root browser item for a library.
+     * Finds or creates the root browser item for a library, including concurrent writers.
      *
      * @param libraryOrId - Media library row or id.
      * @returns Root browser item for the library.
@@ -204,11 +215,22 @@ export class MediaManager {
             path: '/',
             meta: null,
         });
-        await root.save();
-        return root;
+        try {
+            await root.save();
+            return root;
+        }
+        catch (error) {
+            if (!isUniqueConstraintError(error) && !isRetriableTransactionConflict(error))
+                throw error;
+            const raced = await MediaItem.where({ library, path: '/', type: MEDIA_ITEM_TYPE.root }).first();
+            if (!raced)
+                throw error;
+            return raced;
+        }
     }
     /**
-     * Finds or creates a slash-prefixed browser folder path.
+     * Finds or creates a slash-prefixed browser folder path. Concurrent creators
+     * reuse the winning directory without replacing its metadata.
      *
      * @param input - Library and folder path to ensure.
      * @returns Folder item for the requested path, or the root for `/`.
@@ -249,7 +271,17 @@ export class MediaManager {
                     path: currentPath,
                     meta: currentPath === path ? input.meta ?? null : null,
                 });
-                await folder.save();
+                try {
+                    await folder.save();
+                }
+                catch (error) {
+                    if (!isUniqueConstraintError(error) && !isRetriableTransactionConflict(error))
+                        throw error;
+                    const raced = await MediaItem.where({ library, path: currentPath, type: MEDIA_ITEM_TYPE.directory }).first();
+                    if (!raced)
+                        throw error;
+                    folder = raced;
+                }
             }
             parent = folder;
         }

package/dist/network/BlockedUrlError.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Raised when an outbound request targets a URL the network guard refuses.
+ *
+ * The message is safe to show to the user who supplied the URL: it names the
+ * rule that failed without revealing resolved internal addresses. Callers
+ * typically catch it to turn a blocked crawl, webhook or preview into a
+ * validation error instead of a server failure.
+ */
+export declare class BlockedUrlError extends Error {
+    /**
+     * Creates a blocked-URL error with a public explanation.
+     *
+     * @param message - Caller-safe reason the URL was refused.
+     */
+    constructor(message?: string);
+}

package/dist/network/BlockedUrlError.js

@@ -0,0 +1,19 @@
+/**
+ * Raised when an outbound request targets a URL the network guard refuses.
+ *
+ * The message is safe to show to the user who supplied the URL: it names the
+ * rule that failed without revealing resolved internal addresses. Callers
+ * typically catch it to turn a blocked crawl, webhook or preview into a
+ * validation error instead of a server failure.
+ */
+export class BlockedUrlError extends Error {
+    /**
+     * Creates a blocked-URL error with a public explanation.
+     *
+     * @param message - Caller-safe reason the URL was refused.
+     */
+    constructor(message = 'This URL is not allowed.') {
+        super(message);
+        this.name = 'BlockedUrlError';
+    }
+}

package/dist/network/assertPublicUrl.d.ts

@@ -0,0 +1,22 @@
+import type * as network from './contracts/index.js';
+/**
+ * Validates that a URL is an HTTP(S) address on the public internet.
+ *
+ * This is a pre-flight check that gives users a clear error before any
+ * connection is attempted. It is not sufficient on its own: DNS can return a
+ * different address when the request connects (DNS rebinding). Send requests
+ * through {@link guardedFetch}, or pass {@link publicAddressLookup} to the HTTP
+ * client, so the connected address is checked as well.
+ *
+ * @param rawUrl - Absolute URL supplied by a user, crawler or redirect.
+ * @param options - Destination policy; private hosts are refused by default.
+ * @throws {BlockedUrlError} When the URL is malformed, not HTTP(S), or reaches
+ * a private, local or reserved address.
+ *
+ * @example
+ * await assertPublicUrl('https://example.com/feed.xml');
+ * await assertPublicUrl('http://169.254.169.254/'); // throws BlockedUrlError
+ */
+export declare function assertPublicUrl(rawUrl: string, options?: network.PublicUrlOptions): Promise<void>;
+/** Public explanation used for every private, local or reserved destination. */
+export declare const PRIVATE_DESTINATION_MESSAGE = "Private, local, or reserved URLs are not allowed.";

package/dist/network/assertPublicUrl.js

@@ -0,0 +1,67 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { BlockedUrlError } from './BlockedUrlError.js';
+import { isPrivateHostname, isPrivateIpAddress, normalizedUrlHostname } from './privateNetworkAddresses.js';
+/**
+ * Validates that a URL is an HTTP(S) address on the public internet.
+ *
+ * This is a pre-flight check that gives users a clear error before any
+ * connection is attempted. It is not sufficient on its own: DNS can return a
+ * different address when the request connects (DNS rebinding). Send requests
+ * through {@link guardedFetch}, or pass {@link publicAddressLookup} to the HTTP
+ * client, so the connected address is checked as well.
+ *
+ * @param rawUrl - Absolute URL supplied by a user, crawler or redirect.
+ * @param options - Destination policy; private hosts are refused by default.
+ * @throws {BlockedUrlError} When the URL is malformed, not HTTP(S), or reaches
+ * a private, local or reserved address.
+ *
+ * @example
+ * await assertPublicUrl('https://example.com/feed.xml');
+ * await assertPublicUrl('http://169.254.169.254/'); // throws BlockedUrlError
+ */
+export async function assertPublicUrl(rawUrl, options = {}) {
+    const hostname = publicUrlHostname(rawUrl, options);
+    if (hostname === null || isIP(hostname))
+        return;
+    let addresses;
+    try {
+        addresses = await lookup(hostname, { all: true, verbatim: true });
+    }
+    catch {
+        throw new BlockedUrlError('Unable to resolve the URL hostname.');
+    }
+    if (addresses.length === 0 || addresses.some(entry => isPrivateIpAddress(entry.address))) {
+        throw new BlockedUrlError(PRIVATE_DESTINATION_MESSAGE);
+    }
+}
+/** Public explanation used for every private, local or reserved destination. */
+export const PRIVATE_DESTINATION_MESSAGE = 'Private, local, or reserved URLs are not allowed.';
+/**
+ * Performs the synchronous part of URL validation.
+ *
+ * @param rawUrl - Absolute URL to validate.
+ * @param options - Destination policy.
+ * @returns Normalized hostname still requiring DNS validation, or null when no
+ * further checks are needed because private destinations are allowed.
+ * @throws {BlockedUrlError} When the URL fails a synchronous rule.
+ */
+function publicUrlHostname(rawUrl, options) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new BlockedUrlError('The URL is not valid.');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new BlockedUrlError('Only http and https URLs are allowed.');
+    }
+    if (options.allowPrivate)
+        return null;
+    const hostname = normalizedUrlHostname(parsed.hostname);
+    if (isPrivateHostname(hostname) || (isIP(hostname) && isPrivateIpAddress(hostname))) {
+        throw new BlockedUrlError(PRIVATE_DESTINATION_MESSAGE);
+    }
+    return hostname;
+}

package/dist/network/contracts/GuardedFetch.d.ts

@@ -0,0 +1,35 @@
+import type { PublicUrlOptions } from './PublicUrlOptions.js';
+/**
+ * Options for one guarded outbound HTTP request.
+ *
+ * `init` is passed to `fetch` unchanged except that redirects are always
+ * handled by the guard and the connection dispatcher is always replaced with
+ * one that re-validates the addresses DNS returns at connect time.
+ */
+export interface GuardedFetchOptions extends PublicUrlOptions {
+    /** Standard fetch options such as method, headers, body and abort signal. */
+    init?: RequestInit;
+    /**
+     * Maximum redirects followed before the request fails with `BlockedUrlError`.
+     *
+     * Every redirect target is validated as a new destination. Defaults to 4.
+     */
+    maxRedirects?: number;
+    /**
+     * How redirects are handled.
+     *
+     * `follow` (default) validates and follows each hop. `manual` returns the
+     * first 3xx response unchanged so a caller such as a browser can follow it
+     * through its own guarded request path.
+     */
+    redirect?: 'follow' | 'manual';
+}
+/**
+ * Response returned by a guarded outbound request.
+ */
+export interface GuardedFetchResult {
+    /** Final response after any followed redirects. */
+    response: Response;
+    /** Absolute URL that produced `response`, after followed redirects. */
+    finalUrl: string;
+}

package/dist/network/contracts/GuardedFetch.js

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

package/dist/network/contracts/PublicUrlOptions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Destination policy shared by every outbound network guard.
+ *
+ * Applications decide the policy (for example from their environment) and pass
+ * it to each guarded operation. The guard itself never reads environment
+ * variables, so a request handler cannot widen the policy through input.
+ */
+export interface PublicUrlOptions {
+    /**
+     * Allows private, loopback and reserved destinations.
+     *
+     * Intended for interactive local development, where integrations are often
+     * tested against `localhost` receivers. Production code should leave this
+     * unset so user-supplied URLs can only reach public internet hosts.
+     */
+    allowPrivate?: boolean;
+}

package/dist/network/contracts/PublicUrlOptions.js

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

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

@@ -0,0 +1,2 @@
+export * from './GuardedFetch.js';
+export * from './PublicUrlOptions.js';

package/dist/network/contracts/index.js

@@ -0,0 +1,2 @@
+export * from './GuardedFetch.js';
+export * from './PublicUrlOptions.js';

package/dist/network/guardedFetch.d.ts

@@ -0,0 +1,29 @@
+import type * as network from './contracts/index.js';
+/**
+ * Fetches a user-supplied URL without allowing it to reach private networks.
+ *
+ * Each hop is validated before it is requested, and the connection itself uses
+ * {@link publicAddressLookup}, so the address DNS returns at connect time is
+ * the address that was checked. Redirects are followed manually: every target
+ * is validated, `303` (and `301`/`302` after `POST`) switch to `GET` without a
+ * body as `fetch` does, and credentials (`Authorization`, `Cookie`) are removed
+ * when a redirect leaves the original origin.
+ *
+ * `allowPrivate` permits private destinations without weakening TLS certificate
+ * verification. Local HTTPS receivers must present a certificate trusted by Node.
+ *
+ * The request is sent with the runtime's global `fetch`, so test doubles that
+ * replace `globalThis.fetch` continue to work.
+ *
+ * @param rawUrl - Absolute HTTP(S) URL to request.
+ * @param options - Fetch init, redirect handling and destination policy.
+ * @returns Final response and the URL that produced it.
+ * @throws {BlockedUrlError} When any hop targets a refused destination or the
+ * redirect limit is exceeded.
+ *
+ * @example
+ * const { response, finalUrl } = await guardedFetch('https://example.com/', {
+ * 	init: { headers: { accept: 'text/html' }, signal: AbortSignal.timeout(10_000) },
+ * });
+ */
+export declare function guardedFetch(rawUrl: string, options?: network.GuardedFetchOptions): Promise<network.GuardedFetchResult>;