@lpdjs/firestore-repo-service 2.4.3 → 2.6.2-beta.0

package/dist/{types-5vgXdUM2.d.ts → types-BHZ-Gk-s.d.ts}

@@ -1,8 +1,8 @@
-import { c as AuthUser, A as AuthExtension } from './firebase-auth-D1APf9PA.js';
+import { c as AuthUser, A as AuthExtension } from './firebase-auth-Dpvrd8MP.js';
 import * as zod from 'zod';
 import { z } from 'zod';
 import { HttpsOptions } from 'firebase-functions/v2/https';
-import { a as HistoryConfigForModel, b as HistoryMethods } from './read-BSyLao3I.js';
+import { d as HistoryConfigForModel, i as HistoryMethods } from './read-CTWZjxyh.js';
 import { DocumentReference, Firestore, DocumentSnapshot, WhereFilterOp, Query, CollectionReference, WriteBatch, Transaction } from 'firebase-admin/firestore';
 
 /**
@@ -533,6 +533,58 @@ type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, an
     history?: HistoryMethods<T["type"], Parameters<T["documentRef"]>>;
 };
 
+/**
+ * Default security-headers middleware for the bundled HTTP servers.
+ *
+ * Addresses issues #12 (no security headers / clickjacking / cache leakage)
+ * and #13 (no CSP bounding the CDN origins loaded by the admin & login pages).
+ *
+ * The middleware is framework-agnostic: it only touches `res.setHeader`
+ * (present on Node's `ServerResponse` and the shims used by the admin/CRUD
+ * routers) and always calls `next()`.
+ */
+type AnyReq = any;
+type AnyRes = any;
+type Next = () => void | Promise<void>;
+/**
+ * Reasonable default Content-Security-Policy for the bundled **HTML** pages
+ * (admin UI + login). Allows the specific CDN origins the pages need and
+ * forbids framing entirely. `'unsafe-inline'`/`'unsafe-eval'` are required by
+ * the Tailwind browser build and the small inline bootstrap scripts.
+ */
+declare const DEFAULT_HTML_CSP: string;
+interface SecurityHeadersOptions {
+    /**
+     * Content-Security-Policy value. Pass a string to override, or `false` to
+     * omit the header entirely. Defaults to {@link DEFAULT_HTML_CSP} for HTML
+     * servers (admin/login) and is omitted for pure JSON APIs unless provided.
+     */
+    csp?: string | false;
+    /**
+     * `X-Frame-Options` value. Default `"DENY"`. Pass `false` to omit (e.g. when
+     * the app must be embedded in a trusted iframe — prefer a CSP
+     * `frame-ancestors` allowlist instead).
+     */
+    frameOptions?: string | false;
+    /** `Referrer-Policy` value. Default `"no-referrer"`. */
+    referrerPolicy?: string | false;
+    /**
+     * `Cache-Control` value. Default `"private, no-store"` to keep private data
+     * out of shared proxy caches. Pass `false` to leave caching to handlers.
+     */
+    cacheControl?: string | false;
+}
+/**
+ * Build a middleware that sets a baseline of security response headers.
+ *
+ * @example
+ * ```ts
+ * router.use(securityHeaders());                 // HTML-safe defaults
+ * router.use(securityHeaders({ csp: false }));   // JSON API (no CSP)
+ * ```
+ */
+declare function securityHeaders(opts?: SecurityHeadersOptions): (_req: AnyReq, res: AnyRes, next: Next) => Promise<void>;
+
 /**
  * Options to control OpenAPI 3.1 spec generation for the CRUD server.
  * Defined here (rather than in `./openapi`) to avoid a circular import:
@@ -577,8 +629,9 @@ type IsAny<T> = 0 extends 1 & T ? true : false;
  * - `"create"` — field is accepted in create requests / create form
  * - `"mutable"` — field is accepted in update requests / edit form
  * - `"filterable"` — field can be used in query filters / filter bar
+ * - `"orderable"` — field can be used in `orderBy` / sort
  */
-type FieldRole = "create" | "mutable" | "filterable";
+type FieldRole = "create" | "mutable" | "filterable" | "orderable";
 /**
  * Field paths on the model, **excluding** auto-managed system keys.
  * Falls back to `string` when `TRepo` is unresolved (`any`) so that plain
@@ -627,6 +680,10 @@ interface CrudRepoConfig<TRepo extends ConfiguredRepository<any> = ConfiguredRep
      * - `"create"` — field is accepted in create requests
      * - `"mutable"` — field is accepted in update requests (PUT/PATCH)
      * - `"filterable"` — field can be used in query filters
+     * - `"orderable"` — field can be used in `orderBy` / sort. When no field
+     *   declares `"orderable"`, the `"filterable"` set is reused so existing
+     *   configs keep sorting on their filterable fields (fail-closed: fields
+     *   that are neither filterable nor orderable cannot be sorted on).
      *
      * If `fieldsConfig` is omitted, all non-system schema fields are allowed
      * for all roles, and all fields (including system keys) are filterable.
@@ -764,6 +821,8 @@ interface CrudRepoEntry {
     pageSize: number;
     /** Resolved from fieldsConfig: fields with role "filterable" */
     filterableFields?: string[];
+    /** Resolved from fieldsConfig: fields with role "orderable" (falls back to filterableFields) */
+    orderableFields?: string[];
     /** Resolved from fieldsConfig: fields with role "mutable" */
     mutableFields?: string[];
     /** Resolved from fieldsConfig: fields with role "create" */
@@ -832,6 +891,14 @@ interface CrudServerOptions<TRepos extends Record<string, ConfiguredRepository<a
     };
     /** Whether to parse JSON bodies. Default: true. */
     parseBody?: boolean;
+    /**
+     * Baseline security response headers (X-Frame-Options, nosniff,
+     * Referrer-Policy, Cache-Control, optional CSP). Enabled by default; for
+     * this JSON API the CSP is omitted unless you provide one (so the bundled
+     * `/__docs` UI keeps working). Pass an options object to customise or
+     * `false` to disable (issue #12).
+     */
+    securityHeaders?: SecurityHeadersOptions | false;
     /**
      * Authentication guard executed before every request.
      * - Pass an {@link AuthExtension} (e.g. result of `firebaseAuth({...})`) to
@@ -970,4 +1037,4 @@ interface QueryRequestBody {
     })[];
 }
 
-export { type ApiResponse as A, type BasicAuthConfig as B, type ConfiguredRepository as C, type ExtractDocumentRefSignature as E, type FieldRole as F, type GetOptions as G, type IncludeConfigTyped as I, type ListResponseData as L, type Middleware as M, type OpenAPISpecOptions as O, type PaginationOptions as P, type QueryRequestBody as Q, type RepoFieldPath as R, type UserFieldPath as U, type WhereClause as W, type CrudServerOptions as a, type CrudRepoConfig as b, type CrudRepoEntry as c, type CrudRepoRegistry as d, type RepoRelationKeys as e, type RepositoryConfig as f, type FieldPath as g, type QueryOptions as h, type RelationConfig as i, type ExtractUpdateSignature as j, type GetResult as k, type RelationalKeys as l, createPaginationIterator as m, executePaginatedQuery as n, type PaginationResult as o, type GenerateGetMethods as p, type GenerateQueryMethods as q, type PaginationWithIncludeOptionsTyped as r, type PopulateOptionsTyped as s };
+export { type ApiResponse as A, type BasicAuthConfig as B, type ConfiguredRepository as C, DEFAULT_HTML_CSP as D, type ExtractDocumentRefSignature as E, type FieldRole as F, type GetOptions as G, type IncludeConfigTyped as I, type ListResponseData as L, type Middleware as M, type OpenAPISpecOptions as O, type PaginationOptions as P, type QueryRequestBody as Q, type RepoFieldPath as R, type SecurityHeadersOptions as S, type UserFieldPath as U, type WhereClause as W, type CrudServerOptions as a, type CrudRepoConfig as b, type CrudRepoEntry as c, type CrudRepoRegistry as d, type RepoRelationKeys as e, type RepositoryConfig as f, type FieldPath as g, type QueryOptions as h, type RelationConfig as i, type ExtractUpdateSignature as j, type GetResult as k, type RelationalKeys as l, createPaginationIterator as m, executePaginatedQuery as n, type PaginationResult as o, type GenerateGetMethods as p, type GenerateQueryMethods as q, type PaginationWithIncludeOptionsTyped as r, securityHeaders as s, type PopulateOptionsTyped as t };

package/dist/{types-ChzVPw4k.d.ts → types-FLGn8CAI.d.ts}

@@ -1,4 +1,4 @@
-import { A as AuthExtension } from './firebase-auth-D1APf9PA.js';
+import { A as AuthExtension } from './firebase-auth-Dpvrd8MP.js';
 import { onDocumentCreated, onDocumentUpdated, onDocumentDeleted } from 'firebase-functions/v2/firestore';
 import { onRequest, HttpsOptions } from 'firebase-functions/v2/https';
 import { onMessagePublished, PubSubOptions } from 'firebase-functions/v2/pubsub';
@@ -77,6 +77,14 @@ interface SyncEvent {
      * versions; the worker treats `undefined` as "always apply".
      */
     version?: number;
+    /**
+     * DLQ retry bookkeeping. Set by the worker when an event is re-published to
+     * the dead-letter topic after a flush failure. Used to cap retries of a
+     * poison message (see issue #09). Absent on first-time events.
+     */
+    attempts?: number;
+    /** Epoch millis of the first flush failure for this event (DLQ only). */
+    firstFailedAt?: number;
 }
 /**
  * Abstract SQL adapter that the sync worker calls.
@@ -240,6 +248,12 @@ interface SyncWorkerConfig<M = Record<string, any>> {
     autoMigrate?: boolean;
     /** PubSub topic prefix (default: "firestore-sync") */
     topicPrefix?: string;
+    /**
+     * Maximum number of times an event may be re-published to the dead-letter
+     * topic before it is dropped (poison-message cap). Default: 5. Set to 0 to
+     * disable the cap (events are re-published indefinitely). See issue #09.
+     */
+    maxDlqAttempts?: number;
     /**
      * Cloud Functions v2 options forwarded to `onMessagePublished()` for every
      * worker handler. Use to tune `concurrency`, `maxInstances`, `minInstances`,

package/dist/{types-BtdC0Qhu.d.cts → types-GvexCqrq.d.cts}

@@ -1,8 +1,8 @@
-import { c as AuthUser, A as AuthExtension } from './firebase-auth-D1APf9PA.cjs';
+import { c as AuthUser, A as AuthExtension } from './firebase-auth-Dpvrd8MP.cjs';
 import * as zod from 'zod';
 import { z } from 'zod';
 import { HttpsOptions } from 'firebase-functions/v2/https';
-import { a as HistoryConfigForModel, b as HistoryMethods } from './read-BSyLao3I.cjs';
+import { d as HistoryConfigForModel, i as HistoryMethods } from './read-CTWZjxyh.cjs';
 import { DocumentReference, Firestore, DocumentSnapshot, WhereFilterOp, Query, CollectionReference, WriteBatch, Transaction } from 'firebase-admin/firestore';
 
 /**
@@ -533,6 +533,58 @@ type ConfiguredRepository<T extends RepositoryConfig<any, any, any, any, any, an
     history?: HistoryMethods<T["type"], Parameters<T["documentRef"]>>;
 };
 
+/**
+ * Default security-headers middleware for the bundled HTTP servers.
+ *
+ * Addresses issues #12 (no security headers / clickjacking / cache leakage)
+ * and #13 (no CSP bounding the CDN origins loaded by the admin & login pages).
+ *
+ * The middleware is framework-agnostic: it only touches `res.setHeader`
+ * (present on Node's `ServerResponse` and the shims used by the admin/CRUD
+ * routers) and always calls `next()`.
+ */
+type AnyReq = any;
+type AnyRes = any;
+type Next = () => void | Promise<void>;
+/**
+ * Reasonable default Content-Security-Policy for the bundled **HTML** pages
+ * (admin UI + login). Allows the specific CDN origins the pages need and
+ * forbids framing entirely. `'unsafe-inline'`/`'unsafe-eval'` are required by
+ * the Tailwind browser build and the small inline bootstrap scripts.
+ */
+declare const DEFAULT_HTML_CSP: string;
+interface SecurityHeadersOptions {
+    /**
+     * Content-Security-Policy value. Pass a string to override, or `false` to
+     * omit the header entirely. Defaults to {@link DEFAULT_HTML_CSP} for HTML
+     * servers (admin/login) and is omitted for pure JSON APIs unless provided.
+     */
+    csp?: string | false;
+    /**
+     * `X-Frame-Options` value. Default `"DENY"`. Pass `false` to omit (e.g. when
+     * the app must be embedded in a trusted iframe — prefer a CSP
+     * `frame-ancestors` allowlist instead).
+     */
+    frameOptions?: string | false;
+    /** `Referrer-Policy` value. Default `"no-referrer"`. */
+    referrerPolicy?: string | false;
+    /**
+     * `Cache-Control` value. Default `"private, no-store"` to keep private data
+     * out of shared proxy caches. Pass `false` to leave caching to handlers.
+     */
+    cacheControl?: string | false;
+}
+/**
+ * Build a middleware that sets a baseline of security response headers.
+ *
+ * @example
+ * ```ts
+ * router.use(securityHeaders());                 // HTML-safe defaults
+ * router.use(securityHeaders({ csp: false }));   // JSON API (no CSP)
+ * ```
+ */
+declare function securityHeaders(opts?: SecurityHeadersOptions): (_req: AnyReq, res: AnyRes, next: Next) => Promise<void>;
+
 /**
  * Options to control OpenAPI 3.1 spec generation for the CRUD server.
  * Defined here (rather than in `./openapi`) to avoid a circular import:
@@ -577,8 +629,9 @@ type IsAny<T> = 0 extends 1 & T ? true : false;
  * - `"create"` — field is accepted in create requests / create form
  * - `"mutable"` — field is accepted in update requests / edit form
  * - `"filterable"` — field can be used in query filters / filter bar
+ * - `"orderable"` — field can be used in `orderBy` / sort
  */
-type FieldRole = "create" | "mutable" | "filterable";
+type FieldRole = "create" | "mutable" | "filterable" | "orderable";
 /**
  * Field paths on the model, **excluding** auto-managed system keys.
  * Falls back to `string` when `TRepo` is unresolved (`any`) so that plain
@@ -627,6 +680,10 @@ interface CrudRepoConfig<TRepo extends ConfiguredRepository<any> = ConfiguredRep
      * - `"create"` — field is accepted in create requests
      * - `"mutable"` — field is accepted in update requests (PUT/PATCH)
      * - `"filterable"` — field can be used in query filters
+     * - `"orderable"` — field can be used in `orderBy` / sort. When no field
+     *   declares `"orderable"`, the `"filterable"` set is reused so existing
+     *   configs keep sorting on their filterable fields (fail-closed: fields
+     *   that are neither filterable nor orderable cannot be sorted on).
      *
      * If `fieldsConfig` is omitted, all non-system schema fields are allowed
      * for all roles, and all fields (including system keys) are filterable.
@@ -764,6 +821,8 @@ interface CrudRepoEntry {
     pageSize: number;
     /** Resolved from fieldsConfig: fields with role "filterable" */
     filterableFields?: string[];
+    /** Resolved from fieldsConfig: fields with role "orderable" (falls back to filterableFields) */
+    orderableFields?: string[];
     /** Resolved from fieldsConfig: fields with role "mutable" */
     mutableFields?: string[];
     /** Resolved from fieldsConfig: fields with role "create" */
@@ -832,6 +891,14 @@ interface CrudServerOptions<TRepos extends Record<string, ConfiguredRepository<a
     };
     /** Whether to parse JSON bodies. Default: true. */
     parseBody?: boolean;
+    /**
+     * Baseline security response headers (X-Frame-Options, nosniff,
+     * Referrer-Policy, Cache-Control, optional CSP). Enabled by default; for
+     * this JSON API the CSP is omitted unless you provide one (so the bundled
+     * `/__docs` UI keeps working). Pass an options object to customise or
+     * `false` to disable (issue #12).
+     */
+    securityHeaders?: SecurityHeadersOptions | false;
     /**
      * Authentication guard executed before every request.
      * - Pass an {@link AuthExtension} (e.g. result of `firebaseAuth({...})`) to
@@ -970,4 +1037,4 @@ interface QueryRequestBody {
     })[];
 }
 
-export { type ApiResponse as A, type BasicAuthConfig as B, type ConfiguredRepository as C, type ExtractDocumentRefSignature as E, type FieldRole as F, type GetOptions as G, type IncludeConfigTyped as I, type ListResponseData as L, type Middleware as M, type OpenAPISpecOptions as O, type PaginationOptions as P, type QueryRequestBody as Q, type RepoFieldPath as R, type UserFieldPath as U, type WhereClause as W, type CrudServerOptions as a, type CrudRepoConfig as b, type CrudRepoEntry as c, type CrudRepoRegistry as d, type RepoRelationKeys as e, type RepositoryConfig as f, type FieldPath as g, type QueryOptions as h, type RelationConfig as i, type ExtractUpdateSignature as j, type GetResult as k, type RelationalKeys as l, createPaginationIterator as m, executePaginatedQuery as n, type PaginationResult as o, type GenerateGetMethods as p, type GenerateQueryMethods as q, type PaginationWithIncludeOptionsTyped as r, type PopulateOptionsTyped as s };
+export { type ApiResponse as A, type BasicAuthConfig as B, type ConfiguredRepository as C, DEFAULT_HTML_CSP as D, type ExtractDocumentRefSignature as E, type FieldRole as F, type GetOptions as G, type IncludeConfigTyped as I, type ListResponseData as L, type Middleware as M, type OpenAPISpecOptions as O, type PaginationOptions as P, type QueryRequestBody as Q, type RepoFieldPath as R, type SecurityHeadersOptions as S, type UserFieldPath as U, type WhereClause as W, type CrudServerOptions as a, type CrudRepoConfig as b, type CrudRepoEntry as c, type CrudRepoRegistry as d, type RepoRelationKeys as e, type RepositoryConfig as f, type FieldPath as g, type QueryOptions as h, type RelationConfig as i, type ExtractUpdateSignature as j, type GetResult as k, type RelationalKeys as l, createPaginationIterator as m, executePaginatedQuery as n, type PaginationResult as o, type GenerateGetMethods as p, type GenerateQueryMethods as q, type PaginationWithIncludeOptionsTyped as r, securityHeaders as s, type PopulateOptionsTyped as t };

package/dist/{types-BgIGWlR1.d.cts → types-wcX7xfdo.d.cts}

@@ -1,4 +1,4 @@
-import { A as AuthExtension } from './firebase-auth-D1APf9PA.cjs';
+import { A as AuthExtension } from './firebase-auth-Dpvrd8MP.cjs';
 import { onDocumentCreated, onDocumentUpdated, onDocumentDeleted } from 'firebase-functions/v2/firestore';
 import { onRequest, HttpsOptions } from 'firebase-functions/v2/https';
 import { onMessagePublished, PubSubOptions } from 'firebase-functions/v2/pubsub';
@@ -77,6 +77,14 @@ interface SyncEvent {
      * versions; the worker treats `undefined` as "always apply".
      */
     version?: number;
+    /**
+     * DLQ retry bookkeeping. Set by the worker when an event is re-published to
+     * the dead-letter topic after a flush failure. Used to cap retries of a
+     * poison message (see issue #09). Absent on first-time events.
+     */
+    attempts?: number;
+    /** Epoch millis of the first flush failure for this event (DLQ only). */
+    firstFailedAt?: number;
 }
 /**
  * Abstract SQL adapter that the sync worker calls.
@@ -240,6 +248,12 @@ interface SyncWorkerConfig<M = Record<string, any>> {
     autoMigrate?: boolean;
     /** PubSub topic prefix (default: "firestore-sync") */
     topicPrefix?: string;
+    /**
+     * Maximum number of times an event may be re-published to the dead-letter
+     * topic before it is dropped (poison-message cap). Default: 5. Set to 0 to
+     * disable the cap (events are re-published indefinitely). See issue #09.
+     */
+    maxDlqAttempts?: number;
     /**
      * Cloud Functions v2 options forwarded to `onMessagePublished()` for every
      * worker handler. Use to tune `concurrency`, `maxInstances`, `minInstances`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lpdjs/firestore-repo-service",
-  "version": "2.4.3",
+  "version": "2.6.2-beta.0",
   "workspaces": [
     "test/functions"
   ],
@@ -135,7 +135,7 @@
     "LICENSE"
   ],
   "bin": {
-    "frs-hono": "./dist/servers/hono/cli.js"
+    "frs": "./dist/servers/hono/cli.js"
   },
   "authors": [
     {