@beechcms/core 0.7.0 → 0.8.1

package/dist/media/magic-bytes.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { SUPPORTED_FILE_TYPES, getFileTypeByMime, BLOCKED_IMAGE_MIME_TYPES, matchesFileSignature, } from './file-types.js';
+/**
+ * Iterates across supported binary definitions to find any matching file signature.
+ *
+ * @param bytes - The raw byte buffer to analyze.
+ * @returns The matching FileTypeDefinition if recognized, or undefined.
+ */
+function detectBinaryType(bytes) {
+    for (const def of Object.values(SUPPORTED_FILE_TYPES)) {
+        if (def.isBinary && matchesFileSignature(def, bytes)) {
+            return def;
+        }
+    }
+    return undefined;
+}
+/**
+ * Validates that an uploaded file's binary content matches its declared MIME type,
+ * protecting against MIME-spoofing, disguised executables, and blocked formats (e.g. SVG).
+ *
+ * @param buffer - The raw binary buffer (ArrayBuffer or Uint8Array).
+ * @param declaredMime - The client-declared MIME type string.
+ * @returns A MagicBytesValidationResult indicating validity and details.
+ */
+export function verifyMagicBytes(buffer, declaredMime) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    if (bytes.length < 2) {
+        return { valid: false, error: 'File buffer too small for signature inspection' };
+    }
+    const normalizedDeclared = declaredMime.split(';')[0].trim().toLowerCase();
+    // Unconditionally reject blocked MIME types (e.g. SVG)
+    if (BLOCKED_IMAGE_MIME_TYPES.includes(normalizedDeclared)) {
+        return {
+            valid: false,
+            error: `File type '${declaredMime}' is blocked for security reasons`,
+        };
+    }
+    const declaredDef = getFileTypeByMime(normalizedDeclared);
+    if (!declaredDef) {
+        return { valid: false, error: `Unrecognized file signature for declared MIME ${declaredMime}` };
+    }
+    // Non-binary types (e.g. text/plain, text/csv, text/markdown, application/json)
+    if (!declaredDef.isBinary) {
+        return { valid: true, detectedMime: declaredDef.primaryMime };
+    }
+    // If buffer is smaller than the minimum bytes needed for initial signature inspection (typically 4, or 2-3 for short signatures)
+    const minInspectionLength = Math.min(4, declaredDef.magicBytes?.length ?? 4);
+    if (bytes.length < minInspectionLength) {
+        return { valid: false, error: 'File buffer too small for signature inspection' };
+    }
+    // Binary types: verify signature against declared definition
+    if (matchesFileSignature(declaredDef, bytes)) {
+        return { valid: true, detectedMime: declaredDef.primaryMime };
+    }
+    // Signature mismatch: check if it matches another known binary signature
+    const detectedDef = detectBinaryType(bytes);
+    if (detectedDef) {
+        return {
+            valid: false,
+            detectedMime: detectedDef.primaryMime,
+            error: `Signature mismatch: file is ${detectedDef.extension.toUpperCase()} but declared as ${declaredMime}`,
+        };
+    }
+    return { valid: false, error: `Unrecognized file signature for declared MIME ${declaredMime}` };
+}

package/dist/media/media-transform.d.ts

@@ -0,0 +1,88 @@
+import type { ImageOutputMime, ImageTransformSpec, MediaDimensions } from './image-transformer.js';
+/** Default ceiling, in pixels, on either side of a derived variant. Covers native 32:9 ultrawide panels. */
+export declare const DEFAULT_MEDIA_MAX_DIMENSION = 5120;
+/** MEDIA_MAX_DIMENSION may lower the ceiling freely but raise it only this far. */
+export declare const ABSOLUTE_MAX_MEDIA_DIMENSION = 8192;
+export type MediaOutputFormat = 'original' | 'webp' | 'jpeg';
+export type MediaQuality = 'low' | 'medium' | 'high';
+export declare const MEDIA_OUTPUT_FORMATS: readonly MediaOutputFormat[];
+export declare const MEDIA_QUALITIES: readonly MediaQuality[];
+export declare const DEFAULT_MEDIA_FORMAT: MediaOutputFormat;
+export declare const DEFAULT_MEDIA_QUALITY: MediaQuality;
+/** Encoder quality per enum value. `medium` ≈ 82 per the brief. */
+export declare const MEDIA_QUALITY_VALUES: Readonly<Record<MediaQuality, number>>;
+export type MediaPreset = {
+    readonly kind: 'crop';
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly kind: 'scale';
+    readonly width: number;
+};
+export type MediaPresetCatalog = ReadonlyMap<string, MediaPreset>;
+export declare const DEFAULT_MEDIA_SCALE_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560, 3840, 5120];
+export declare const DEFAULT_MEDIA_PRESETS: Readonly<Record<string, MediaPreset>>;
+/** Raster sources the transform path accepts. Everything else — SVG, PDF, video, AVIF, BMP, ICO — is refused. */
+export declare const TRANSFORMABLE_MEDIA_MIME_TYPES: readonly ImageOutputMime[];
+/** Parameters of the discarded free-form contract. Their presence is an error, never ignored. */
+export declare const FORBIDDEN_MEDIA_TRANSFORM_PARAMS: readonly string[];
+export type MediaTransformErrorCode = 'media_param_forbidden' | 'media_param_duplicated' | 'media_preset_required' | 'media_format_invalid' | 'media_quality_invalid' | 'media_preset_unknown' | 'media_not_transformable' | 'media_dimension_exceeded';
+export interface MediaTransformRequest {
+    readonly preset: string;
+    readonly format: MediaOutputFormat;
+    readonly quality: MediaQuality;
+}
+export type MediaTransformQuery = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'invalid';
+    readonly code: MediaTransformErrorCode;
+} | {
+    readonly kind: 'transform';
+    readonly request: MediaTransformRequest;
+};
+/** Thrown by buildMediaPresetCatalog on any malformed MEDIA_PRESETS entry. Fail closed, never fall back. */
+export declare class MediaPresetCatalogError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * Classifies a media query string. Pure: does not consult the catalog (that is env-dependent and
+ * resolved by the caller), so an unknown-but-well-formed preset name returns `transform`.
+ */
+export declare function parseMediaTransformQuery(params: URLSearchParams): MediaTransformQuery;
+/**
+ * Canonical query for a request: fixed order preset → format → quality, defaults omitted.
+ * `@beechcms/client` emits exactly this string; the server recomputes it and never trusts the client's.
+ */
+export declare function canonicalMediaTransformQuery(request: MediaTransformRequest): string;
+/**
+ * Builds the active catalog: DEFAULT_MEDIA_PRESETS merged by name with `overrides`
+ * (the parsed MEDIA_PRESETS JSON). An override value of `null` removes a preset.
+ * Defaults larger than `maxDimension` are dropped (they could only ever 400); an operator-supplied
+ * preset larger than `maxDimension` is an error.
+ *
+ * @throws {MediaPresetCatalogError} on any malformed override.
+ */
+export declare function buildMediaPresetCatalog(overrides: unknown, maxDimension: number): MediaPresetCatalog;
+export declare function isTransformableMime(mime: string | null | undefined): boolean;
+/**
+ * Output dimensions of a scale preset (`fit=scale-down`: never upscales). Returns `null` when either
+ * side would exceed `maxDimension` — the pathological-aspect-ratio guard of brief §4. Never truncates.
+ */
+export declare function deriveScaleOutput(presetWidth: number, source: MediaDimensions, maxDimension: number): MediaDimensions | null;
+/** Identity of a preset's *definition*, so redefining a name never reuses an old variant. */
+export declare function mediaPresetSignature(preset: MediaPreset): string;
+/** Precondition: `isTransformableMime(sourceMime)` is true. */
+export declare function buildImageTransformSpec(preset: MediaPreset, request: MediaTransformRequest, sourceMime: string): ImageTransformSpec;
+/**
+ * Strong ETag of a variant: source identity (key + size — keys are never overwritten) plus the
+ * canonical request plus the preset definition. Format: `"mv1-<32 hex>"`.
+ */
+export declare function computeMediaVariantEtag(source: {
+    readonly key: string;
+    readonly size: number;
+}, request: MediaTransformRequest, preset: MediaPreset): Promise<string>;
+/** RFC 9110 §13.1.2: `*` matches; otherwise weak comparison against a comma-separated list. */
+export declare function ifNoneMatchMatches(header: string | null | undefined, etag: string | null | undefined): boolean;
+//# sourceMappingURL=media-transform.d.ts.map

package/dist/media/media-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-transform.d.ts","sourceRoot":"","sources":["../../src/media/media-transform.ts"],"names":[],"mappings":"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"}

package/dist/media/media-transform.js

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { sha256hex } from '../engine/privacy/policies.js';
+import { canonicalizeMime } from './file-types.js';
+/** Default ceiling, in pixels, on either side of a derived variant. Covers native 32:9 ultrawide panels. */
+export const DEFAULT_MEDIA_MAX_DIMENSION = 5120;
+/** MEDIA_MAX_DIMENSION may lower the ceiling freely but raise it only this far. */
+export const ABSOLUTE_MAX_MEDIA_DIMENSION = 8192;
+export const MEDIA_OUTPUT_FORMATS = ['original', 'webp', 'jpeg'];
+export const MEDIA_QUALITIES = ['low', 'medium', 'high'];
+export const DEFAULT_MEDIA_FORMAT = 'original';
+export const DEFAULT_MEDIA_QUALITY = 'medium';
+/** Encoder quality per enum value. `medium` ≈ 82 per the brief. */
+export const MEDIA_QUALITY_VALUES = Object.freeze({ low: 60, medium: 82, high: 92 });
+export const DEFAULT_MEDIA_SCALE_WIDTHS = [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560, 3840, 5120];
+export const DEFAULT_MEDIA_PRESETS = Object.freeze({
+    thumbnail: { kind: 'crop', width: 200, height: 200 },
+    avatar: { kind: 'crop', width: 128, height: 128 },
+    card: { kind: 'crop', width: 400, height: 300 },
+    'og-image': { kind: 'crop', width: 1200, height: 630 },
+    hero: { kind: 'crop', width: 1920, height: 800 },
+    ...Object.fromEntries(DEFAULT_MEDIA_SCALE_WIDTHS.map((width) => [`w-${width}`, { kind: 'scale', width }])),
+});
+/** Raster sources the transform path accepts. Everything else — SVG, PDF, video, AVIF, BMP, ICO — is refused. */
+export const TRANSFORMABLE_MEDIA_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+/** Parameters of the discarded free-form contract. Their presence is an error, never ignored. */
+export const FORBIDDEN_MEDIA_TRANSFORM_PARAMS = ['w', 'h', 'width', 'height', 'fit', 'q'];
+/** Thrown by buildMediaPresetCatalog on any malformed MEDIA_PRESETS entry. Fail closed, never fall back. */
+export class MediaPresetCatalogError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid media preset catalog: ${reason}`);
+        this.reason = reason;
+        this.name = 'MediaPresetCatalogError';
+    }
+}
+const PRESET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const SCALE_NAME_PATTERN = /^w-([1-9]\d*)$/;
+const invalid = (code) => ({ kind: 'invalid', code });
+/**
+ * Classifies a media query string. Pure: does not consult the catalog (that is env-dependent and
+ * resolved by the caller), so an unknown-but-well-formed preset name returns `transform`.
+ */
+export function parseMediaTransformQuery(params) {
+    if (FORBIDDEN_MEDIA_TRANSFORM_PARAMS.some((name) => params.has(name)))
+        return invalid('media_param_forbidden');
+    const presets = params.getAll('preset');
+    const formats = params.getAll('format');
+    const qualities = params.getAll('quality');
+    if (presets.length > 1 || formats.length > 1 || qualities.length > 1)
+        return invalid('media_param_duplicated');
+    if (presets.length === 0 && formats.length === 0 && qualities.length === 0)
+        return { kind: 'none' };
+    const preset = presets[0];
+    if (!preset)
+        return invalid('media_preset_required');
+    const format = formats[0] ?? DEFAULT_MEDIA_FORMAT;
+    if (!MEDIA_OUTPUT_FORMATS.includes(format))
+        return invalid('media_format_invalid');
+    const quality = qualities[0] ?? DEFAULT_MEDIA_QUALITY;
+    if (!MEDIA_QUALITIES.includes(quality))
+        return invalid('media_quality_invalid');
+    if (!PRESET_NAME_PATTERN.test(preset))
+        return invalid('media_preset_unknown');
+    return { kind: 'transform', request: { preset, format: format, quality: quality } };
+}
+/**
+ * Canonical query for a request: fixed order preset → format → quality, defaults omitted.
+ * `@beechcms/client` emits exactly this string; the server recomputes it and never trusts the client's.
+ */
+export function canonicalMediaTransformQuery(request) {
+    let query = `preset=${encodeURIComponent(request.preset)}`;
+    if (request.format !== DEFAULT_MEDIA_FORMAT)
+        query += `&format=${request.format}`;
+    if (request.quality !== DEFAULT_MEDIA_QUALITY)
+        query += `&quality=${request.quality}`;
+    return query;
+}
+function isPositiveIntegerAtMost(value, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= max;
+}
+function parsePresetEntry(name, value, maxDimension) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new MediaPresetCatalogError(`preset "${name}" must be an object or null`);
+    }
+    const entry = value;
+    const scaleMatch = SCALE_NAME_PATTERN.exec(name);
+    if (entry.kind === 'crop') {
+        if (Object.keys(entry).some((field) => !['kind', 'width', 'height'].includes(field))) {
+            throw new MediaPresetCatalogError(`preset "${name}" has unknown fields`);
+        }
+        if (scaleMatch)
+            throw new MediaPresetCatalogError(`"${name}" is reserved for scale presets`);
+        if (!isPositiveIntegerAtMost(entry.width, maxDimension) || !isPositiveIntegerAtMost(entry.height, maxDimension)) {
+            throw new MediaPresetCatalogError(`preset "${name}" needs integer width/height in 1..${maxDimension}`);
+        }
+        return { kind: 'crop', width: entry.width, height: entry.height };
+    }
+    if (entry.kind === 'scale') {
+        if (Object.keys(entry).some((field) => !['kind', 'width'].includes(field))) {
+            throw new MediaPresetCatalogError(`preset "${name}" has unknown fields (scale presets never take a height)`);
+        }
+        if (!isPositiveIntegerAtMost(entry.width, maxDimension)) {
+            throw new MediaPresetCatalogError(`preset "${name}" needs an integer width in 1..${maxDimension}`);
+        }
+        if (name !== `w-${entry.width}`)
+            throw new MediaPresetCatalogError(`scale preset "${name}" must be named "w-${entry.width}"`);
+        return { kind: 'scale', width: entry.width };
+    }
+    throw new MediaPresetCatalogError(`preset "${name}" has kind other than "crop" | "scale"`);
+}
+/**
+ * Builds the active catalog: DEFAULT_MEDIA_PRESETS merged by name with `overrides`
+ * (the parsed MEDIA_PRESETS JSON). An override value of `null` removes a preset.
+ * Defaults larger than `maxDimension` are dropped (they could only ever 400); an operator-supplied
+ * preset larger than `maxDimension` is an error.
+ *
+ * @throws {MediaPresetCatalogError} on any malformed override.
+ */
+export function buildMediaPresetCatalog(overrides, maxDimension) {
+    const catalog = new Map();
+    for (const [name, preset] of Object.entries(DEFAULT_MEDIA_PRESETS)) {
+        const largest = preset.kind === 'crop' ? Math.max(preset.width, preset.height) : preset.width;
+        if (largest <= maxDimension)
+            catalog.set(name, preset);
+    }
+    if (overrides === undefined)
+        return catalog;
+    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+        throw new MediaPresetCatalogError('MEDIA_PRESETS must be a JSON object keyed by preset name');
+    }
+    for (const [name, value] of Object.entries(overrides)) {
+        if (!PRESET_NAME_PATTERN.test(name))
+            throw new MediaPresetCatalogError(`"${name}" is not a valid preset name`);
+        if (value === null) {
+            catalog.delete(name);
+            continue;
+        }
+        catalog.set(name, parsePresetEntry(name, value, maxDimension));
+    }
+    return catalog;
+}
+export function isTransformableMime(mime) {
+    if (!mime)
+        return false;
+    return TRANSFORMABLE_MEDIA_MIME_TYPES.includes(canonicalizeMime(mime));
+}
+/**
+ * Output dimensions of a scale preset (`fit=scale-down`: never upscales). Returns `null` when either
+ * side would exceed `maxDimension` — the pathological-aspect-ratio guard of brief §4. Never truncates.
+ */
+export function deriveScaleOutput(presetWidth, source, maxDimension) {
+    if (source.width <= 0 || source.height <= 0)
+        return null;
+    const output = source.width <= presetWidth
+        ? { width: source.width, height: source.height }
+        : { width: presetWidth, height: Math.max(1, Math.round((source.height * presetWidth) / source.width)) };
+    return output.width > maxDimension || output.height > maxDimension ? null : output;
+}
+/** Identity of a preset's *definition*, so redefining a name never reuses an old variant. */
+export function mediaPresetSignature(preset) {
+    return preset.kind === 'crop' ? `crop:${preset.width}x${preset.height}` : `scale:${preset.width}`;
+}
+/** Precondition: `isTransformableMime(sourceMime)` is true. */
+export function buildImageTransformSpec(preset, request, sourceMime) {
+    const outputMime = request.format === 'webp'
+        ? 'image/webp'
+        : request.format === 'jpeg'
+            ? 'image/jpeg'
+            : canonicalizeMime(sourceMime);
+    const quality = MEDIA_QUALITY_VALUES[request.quality];
+    return preset.kind === 'crop'
+        ? { width: preset.width, height: preset.height, fit: 'cover', outputMime, quality }
+        : { width: preset.width, fit: 'scale-down', outputMime, quality };
+}
+/**
+ * Strong ETag of a variant: source identity (key + size — keys are never overwritten) plus the
+ * canonical request plus the preset definition. Format: `"mv1-<32 hex>"`.
+ */
+export async function computeMediaVariantEtag(source, request, preset) {
+    const digest = await sha256hex(`${source.key}\n${source.size}\n${canonicalMediaTransformQuery(request)}\n${mediaPresetSignature(preset)}`);
+    return `"mv1-${digest.slice(0, 32)}"`;
+}
+/** RFC 9110 §13.1.2: `*` matches; otherwise weak comparison against a comma-separated list. */
+export function ifNoneMatchMatches(header, etag) {
+    if (!header || !etag)
+        return false;
+    const target = etag.replace(/^W\//, '');
+    return header.split(',').some((candidate) => {
+        const trimmed = candidate.trim();
+        return trimmed === '*' || trimmed.replace(/^W\//, '') === target;
+    });
+}

package/dist/media.repository.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MediaRepository - Interface for tracking media assets in the database.
+ */
+export interface MediaObject {
+    key: string;
+    filename: string;
+    mime_type: string;
+    size_bytes: number;
+    uploaded_by: string;
+    created_at: number;
+}
+export interface MediaRepository {
+    /**
+     * Tracks a new file upload in the database.
+     */
+    trackUpload(media: Omit<MediaObject, 'created_at'>): Promise<void>;
+    /**
+     * Retrieves tracking info for a file by its key.
+     */
+    getByKey(key: string): Promise<MediaObject | null>;
+    /**
+     * Removes tracking info for a file.
+     */
+    untrack(key: string): Promise<void>;
+    /**
+     * Lists all tracked media with pagination.
+     */
+    list(options: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: MediaObject[];
+        total: number;
+    }>;
+    /**
+     * Gets the total number of tracked media objects.
+     */
+    count(): Promise<number>;
+}
+/**
+ * SystemStatsRepository - Interface for managing global system metrics.
+ */
+export interface SystemStatsRepository {
+    /**
+     * Increments the total storage counter.
+     */
+    incrementStorage(bytes: number): Promise<void>;
+    /**
+     * Decrements the total storage counter.
+     */
+    decrementStorage(bytes: number): Promise<void>;
+    /**
+     * Sets a specific value for a storage stat (e.g. after a full sync).
+     */
+    setStorage(bytes: number): Promise<void>;
+    /**
+     * Gets the current total storage usage in bytes.
+     */
+    getStorageUsage(): Promise<number>;
+}
+//# sourceMappingURL=media.repository.d.ts.map

package/dist/media.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.repository.d.ts","sourceRoot":"","sources":["../src/media.repository.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnG;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC"}

package/dist/media.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/notifications/notification-service.d.ts

@@ -13,9 +13,9 @@ export declare const createNotificationSchema: z.ZodObject<{
     title: z.ZodString;
     message: z.ZodString;
     type: z.ZodOptional<z.ZodEnum<{
-        success: "success";
         error: "error";
         info: "info";
+        success: "success";
         warning: "warning";
     }>>;
 }, z.core.$strip>;

package/dist/oauth/authorization-code.repository.d.ts

@@ -0,0 +1,33 @@
+import type { OAuthScope } from './scopes.js';
+export interface NewAuthorizationCode {
+    /** SHA-256 hex hash of the code. The plaintext code is never persisted. */
+    codeHash: string;
+    clientId: string;
+    userId: string;
+    scope: OAuthScope[];
+    redirectUri: string;
+    codeChallenge: string;
+    /** Always 'S256'; the column CHECK constraint rejects anything else. */
+    codeChallengeMethod: 'S256';
+    expiresAt: number;
+}
+export interface AuthorizationCodeRecord extends NewAuthorizationCode {
+    createdAt: number;
+    consumedAt: number | null;
+}
+export interface IOAuthAuthorizationCodeRepository {
+    /** Persists a new single-use authorization code. Hash only, never plaintext. */
+    save(record: NewAuthorizationCode): Promise<void>;
+    /**
+     * Returns the code regardless of its consumed state, provided it is unexpired.
+     * Callers MUST inspect `consumedAt`: a non-null value means replay, which
+     * requires cascade revocation via IOAuthTokenRepository.revokeByAuthorizationCode.
+     */
+    findByHash(codeHash: string, nowTimestamp: number): Promise<AuthorizationCodeRecord | null>;
+    /**
+     * Atomically marks the code consumed. Returns true only for the first caller;
+     * every subsequent call returns false, which is the replay signal.
+     */
+    consumeByHash(codeHash: string, nowTimestamp: number): Promise<boolean>;
+}
+//# sourceMappingURL=authorization-code.repository.d.ts.map

package/dist/oauth/authorization-code.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-code.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/authorization-code.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjD;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;IAE3F;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxE"}

package/dist/oauth/authorization-code.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/oauth/client.repository.d.ts

@@ -0,0 +1,17 @@
+import type { OAuthScope } from './scopes.js';
+export interface OAuthClientRecord {
+    clientId: string;
+    name: string;
+    /** Registered redirect URIs. Loopback entries are matched ignoring the port. */
+    redirectUris: string[];
+    allowedScopes: OAuthScope[];
+    /** True for clients that cannot hold a secret (native/CLI). PKCE is required regardless. */
+    isPublic: boolean;
+    createdAt: number;
+    disabledAt: number | null;
+}
+export interface IOAuthClientRepository {
+    /** Returns the client, or null when unknown or disabled. */
+    findActiveById(clientId: string): Promise<OAuthClientRecord | null>;
+}
+//# sourceMappingURL=client.repository.d.ts.map

package/dist/oauth/client.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/client.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,aAAa,EAAE,UAAU,EAAE,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;CACpE"}

package/dist/oauth/client.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/oauth/consent.repository.d.ts

@@ -0,0 +1,25 @@
+import type { OAuthScope } from './scopes.js';
+export interface ConsentRecord {
+    id: string;
+    clientId: string;
+    userId: string;
+    /** Cumulative set of scopes the user has approved for this client. */
+    scopes: OAuthScope[];
+    createdAt: number;
+    updatedAt: number;
+    revokedAt: number | null;
+}
+export interface IOAuthConsentRepository {
+    /** Returns the live consent for the pair, or null when absent or revoked. */
+    findActive(clientId: string, userId: string): Promise<ConsentRecord | null>;
+    /**
+     * Records consent for the pair, unioning `scopes` into any existing live grant
+     * and reviving a previously revoked row. Idempotent for an unchanged scope set.
+     */
+    grant(id: string, clientId: string, userId: string, scopes: readonly OAuthScope[], nowTimestamp: number): Promise<void>;
+    /** Revokes the consent. False when there was nothing live to revoke. */
+    revoke(clientId: string, userId: string, nowTimestamp: number): Promise<boolean>;
+    /** Lists all live consents for a user, newest first. */
+    listForUser(userId: string): Promise<ConsentRecord[]>;
+}
+//# sourceMappingURL=consent.repository.d.ts.map

package/dist/oauth/consent.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/consent.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAE3E;;;OAGG;IACH,KAAK,CACH,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhF,wDAAwD;IACxD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;CACtD"}

package/dist/oauth/consent.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PKCE (RFC 7636) verification. `S256` only — `plain` is rejected unconditionally,
+ * per OAuth 2.1, so no weak fallback configuration can ever exist.
+ */
+/** The only accepted code challenge method. */
+export declare const PKCE_CHALLENGE_METHOD: 'S256';
+export type PkceChallengeMethod = typeof PKCE_CHALLENGE_METHOD;
+/** Minimum / maximum code_verifier length, RFC 7636 §4.1. */
+export declare const PKCE_VERIFIER_MIN_LENGTH = 43;
+export declare const PKCE_VERIFIER_MAX_LENGTH = 128;
+/** Validates the code_verifier character set and length. */
+export declare function isValidCodeVerifier(verifier: string): boolean;
+/** Computes BASE64URL(SHA256(ASCII(verifier))). */
+export declare function deriveCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Verifies a code_verifier against a stored code_challenge.
+ * Returns false — never throws — on any malformed input, unsupported method, or
+ * mismatch, so callers cannot distinguish failure modes from the return value.
+ */
+export declare function verifyPkceChallenge(verifier: string, challenge: string, method: string): Promise<boolean>;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/oauth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,EAAG,MAAe,CAAA;AAEpD,MAAM,MAAM,mBAAmB,GAAG,OAAO,qBAAqB,CAAA;AAE9D,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAI3C,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM7D;AAQD,mDAAmD;AACnD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3E;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/oauth/pkce.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * PKCE (RFC 7636) verification. `S256` only — `plain` is rejected unconditionally,
+ * per OAuth 2.1, so no weak fallback configuration can ever exist.
+ */
+/** The only accepted code challenge method. */
+export const PKCE_CHALLENGE_METHOD = 'S256';
+/** Minimum / maximum code_verifier length, RFC 7636 §4.1. */
+export const PKCE_VERIFIER_MIN_LENGTH = 43;
+export const PKCE_VERIFIER_MAX_LENGTH = 128;
+const VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]+$/;
+/** Validates the code_verifier character set and length. */
+export function isValidCodeVerifier(verifier) {
+    return (verifier.length >= PKCE_VERIFIER_MIN_LENGTH &&
+        verifier.length <= PKCE_VERIFIER_MAX_LENGTH &&
+        VERIFIER_PATTERN.test(verifier));
+}
+/** Base64url-encodes bytes without padding, per RFC 7636 §A. */
+function base64UrlEncode(bytes) {
+    const binary = String.fromCharCode(...new Uint8Array(bytes));
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Computes BASE64URL(SHA256(ASCII(verifier))). */
+export async function deriveCodeChallenge(verifier) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64UrlEncode(digest);
+}
+/**
+ * Verifies a code_verifier against a stored code_challenge.
+ * Returns false — never throws — on any malformed input, unsupported method, or
+ * mismatch, so callers cannot distinguish failure modes from the return value.
+ */
+export async function verifyPkceChallenge(verifier, challenge, method) {
+    if (method !== PKCE_CHALLENGE_METHOD)
+        return false;
+    if (!isValidCodeVerifier(verifier))
+        return false;
+    const derived = await deriveCodeChallenge(verifier);
+    if (derived.length !== challenge.length)
+        return false;
+    let mismatch = 0;
+    for (let index = 0; index < derived.length; index += 1) {
+        mismatch |= derived.charCodeAt(index) ^ challenge.charCodeAt(index);
+    }
+    return mismatch === 0;
+}