mindoodb 0.0.84 → 0.0.86

package/dist/server/peer/types.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Types for server-to-server (peer) replication and the cluster admin surface.
+ *
+ * Two auth classes, two route prefixes — the split is load-bearing:
+ *
+ * - `/system/peer/*` is the **server-to-server protocol**. Callers authenticate
+ *   with a server identity listed in `trusted-servers.json`. Only servers speak
+ *   it.
+ * - `/system/cluster/*` is the **admin surface**. Callers authenticate with a
+ *   system-admin JWT and pass the {@link CapabilityMatcher}. Only humans and
+ *   UIs speak it.
+ *
+ * No endpoint accepts both, so a peer can never administer and an admin can
+ * never write as a peer.
+ */
+/**
+ * Which way entries flow to a peer.
+ *
+ * Mirrors Haven's client-side `SyncDirectionPreference` so operators meet one
+ * vocabulary. `pull` is the backup/archive node (never writes to the peer),
+ * `push` the DMZ head (never reads back), `disabled` keeps the trust entry for
+ * inbound authentication but opens no outbound session.
+ */
+export type PeerSyncDirection = "bidirectional" | "push" | "pull" | "disabled";
+/**
+ * Mesh shape.
+ *
+ * A `spoke` opens sessions only to `hub` peers, never to another spoke, which
+ * turns the full mesh into a spanning tree. Because the entry set is a CRDT
+ * both converge; the tree just avoids the O(N^2) sessions of a large mesh.
+ * `peer` (the default) is fully meshed and is the right answer for two or three
+ * nodes — duplicate pushes are acknowledged idempotently by the receiver's
+ * duplicate path, so the redundancy is cheap.
+ */
+export type PeerRole = "peer" | "hub" | "spoke";
+/**
+ * How eagerly attachment blobs follow their documents.
+ *
+ * Attachments are usually the bulk of the bytes and live in a separate store,
+ * which makes this the biggest bandwidth lever. `lazy` still transfers them but
+ * only after every document store is done; `never` skips the attachment store
+ * entirely (an edge node that only needs text).
+ */
+export type PeerAttachmentMode = "eager" | "lazy" | "never";
+/** Peer settings resolved against their defaults. */
+export interface PeerSettings {
+    direction: PeerSyncDirection;
+    role: PeerRole;
+    attachments: PeerAttachmentMode;
+}
+export declare const DEFAULT_PEER_SETTINGS: PeerSettings;
+export declare function isPeerSyncDirection(value: unknown): value is PeerSyncDirection;
+export declare function isPeerRole(value: unknown): value is PeerRole;
+export declare function isPeerAttachmentMode(value: unknown): value is PeerAttachmentMode;
+/** Fill in defaults for any peer field the operator left unset. */
+export declare function normalizePeerSettings(raw: {
+    direction?: unknown;
+    role?: unknown;
+    attachments?: unknown;
+}): PeerSettings;
+/**
+ * Should this node open an outbound session to that peer?
+ *
+ * Spoke-to-spoke is the only pairing we suppress: both sides would otherwise
+ * dial each other even though the hub already carries their traffic.
+ */
+export declare function shouldOpenSessionTo(local: PeerRole, remote: PeerRole): boolean;
+/** May we send local entries to this peer? */
+export declare function directionAllowsPush(direction: PeerSyncDirection): boolean;
+/** May we take the peer's entries? */
+export declare function directionAllowsPull(direction: PeerSyncDirection): boolean;
+/**
+ * Order the databases of one tenant for replication.
+ *
+ * `directory` first, then `userdirectory`, then everything else alphabetically.
+ * This is not cosmetic. A peer validates every pushed entry against its own
+ * directory (`validatePublicSigningKey`), and an unknown author key is a
+ * **per-entry rejection**, not a batch failure. Push an application database
+ * before the peer has the author's grant and those entries are refused; with
+ * the client's cursor semantics they would then be skipped forever, leaving the
+ * two servers silently divergent.
+ *
+ * The same ordering also shrinks the transient window in which a purged
+ * document or a revoked `decryptionKeyId` makes the peer answer `ACCESS_DENIED`
+ * for a whole batch: both denylists are derived from the directory (purge
+ * requests live there and are executed by `executePendingPurges` after every
+ * directory push), so they converge as soon as the directory has arrived.
+ */
+export declare function orderDatabasesForReplication(dbIds: Iterable<string>): string[];
+/** True for the two system databases that must replicate before app data. */
+export declare function isTrustBearingDatabase(dbId: string): boolean;
+/** Live state of the outbound session to one peer. */
+export type ClusterSessionState = "connected" | "connecting" | "backoff" | "disabled" | "paused" | "unreachable";
+/**
+ * Health rollup, computed on the server so every console agrees on the
+ * thresholds instead of inventing its own.
+ */
+export type ClusterHealth = "ok" | "degraded" | "stalled" | "down";
+/**
+ * Why a peer is not `ok`. Typed so a UI can colour-code and explain without
+ * parsing prose.
+ *
+ * `entries-awaiting-directory-trust` is the one that matters most: it means the
+ * peer rejected entries because it does not yet trust their author, the cursor
+ * was held, and a retry is pending. Left unattended it is the visible precursor
+ * of two servers drifting apart.
+ */
+export type ClusterHealthReason = "entries-awaiting-directory-trust" | "access-denied-backoff" | "events-disconnected" | "intersection-stale" | "lag-above-threshold" | "peer-auth-failed" | "peer-unreachable" | "no-url-configured" | "session-disabled" | "session-paused";
+/** Typed error class beside the free-text `lastError`. */
+export type ClusterErrorClass = "auth" | "network" | "access-denied" | "protocol" | "internal";
+/**
+ * Bucket a replication failure so the console can react without parsing the
+ * message.
+ *
+ * The distinction that matters operationally is `access-denied` versus the
+ * rest: it is the peer *deliberately* refusing a batch (a purged document, a
+ * revoked key) and it resolves itself once the directory has replicated, so it
+ * warrants a backoff and not an alert. Everything else is either a
+ * misconfiguration (`auth`) or a genuine outage (`network`).
+ */
+/**
+ * Strip document and entry identifiers out of a message before it reaches the
+ * cluster status read-model.
+ *
+ * Rejection messages name the offending entry, and an entry id starts with the
+ * document id. The cluster console is a system-admin surface, and a system
+ * admin is not supposed to learn which documents a tenant holds — that is the
+ * same admin-blindness the encryption enforces, and it would be odd to hand it
+ * back through an error string. The classified reason plus the counts are what
+ * an operator can act on anyway.
+ */
+export declare function redactEntryIds(message: string): string;
+export declare function classifyPeerError(error: unknown): ClusterErrorClass;
+/** Per-tenant slice of a peer's replication state. */
+export interface ClusterTenantStatus {
+    tenantId: string;
+    /** Databases mirrored with this peer, in replication order. */
+    databases: string[];
+    lastSyncAt: string | null;
+    /** Entries the peer still owes us or we owe the peer, by head comparison. */
+    lag: number;
+    /** Entries rejected and queued for retry (see `entries-awaiting-directory-trust`). */
+    retryQueueDepth: number;
+    rejectedEntries: number;
+    health: ClusterHealth;
+    reasons: ClusterHealthReason[];
+}
+/** One peer as this node sees it. */
+export interface ClusterPeerStatus {
+    name: string;
+    url: string | null;
+    direction: PeerSyncDirection;
+    role: PeerRole;
+    attachments: PeerAttachmentMode;
+    state: ClusterSessionState;
+    health: ClusterHealth;
+    reasons: ClusterHealthReason[];
+    /** Tenants both sides hold, from the last Bloom intersection. */
+    sharedTenants: number;
+    lastIntersectionAt: string | null;
+    lastSyncAt: string | null;
+    eventsConnected: boolean;
+    lag: number;
+    retryQueueDepth: number;
+    rejectedEntries: number;
+    transferredEntries: number;
+    transferredBytes: number;
+    lastError: string | null;
+    lastErrorClass: ClusterErrorClass | null;
+    lastErrorAt: string | null;
+}
+/** Summary answer of `GET /system/cluster/status`. */
+export interface ClusterStatusResponse {
+    server: string | null;
+    health: ClusterHealth;
+    reasons: ClusterHealthReason[];
+    autoSyncEnabled: boolean;
+    generatedAt: string;
+    peers: ClusterPeerStatus[];
+}
+/** Drill-down answer of `GET /system/cluster/status/tenants/:tenantId`. */
+export interface ClusterTenantStatusResponse {
+    tenantId: string;
+    generatedAt: string;
+    peers: Array<{
+        name: string;
+        tenant: ClusterTenantStatus | null;
+    }>;
+}
+/** One entry of `GET /system/cluster/topology`. */
+export interface ClusterTopologyPeer {
+    name: string;
+    url: string | null;
+    direction: PeerSyncDirection;
+    role: PeerRole;
+    attachments: PeerAttachmentMode;
+    sessionActive: boolean;
+}
+export interface ClusterTopologyResponse {
+    /**
+     * This node's own identity and role. The console starts here and then polls
+     * every peer directly — no node answers on behalf of another (fan-out).
+     */
+    server: {
+        name: string | null;
+        role: PeerRole;
+    };
+    peers: ClusterTopologyPeer[];
+}
+export type ClusterJobState = "queued" | "running" | "succeeded" | "failed";
+export type ClusterJobKind = "sync" | "retry-rejected" | "refresh-intersection" | "pause" | "resume";
+export interface ClusterJobScope {
+    peer?: string;
+    tenantId?: string;
+    dbId?: string;
+}
+export interface ClusterJob {
+    id: string;
+    kind: ClusterJobKind;
+    scope: ClusterJobScope;
+    state: ClusterJobState;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+    /** Coarse progress counters; never carries document identity. */
+    progress: {
+        total: number;
+        completed: number;
+    };
+    result: ClusterJobResult | null;
+    error: string | null;
+    errorClass: ClusterErrorClass | null;
+    /** System-admin principal that requested the job. */
+    requestedBy: string;
+}
+export interface ClusterJobResult {
+    transferredEntries: number;
+    transferredBytes: number;
+    /** Count only — the entry ids would leak document identity to the console. */
+    rejectedEntries: number;
+    tenantsProcessed: number;
+    databasesProcessed: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/server/peer/types.d.ts.map

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

package/dist/server/peer/types.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Types for server-to-server (peer) replication and the cluster admin surface.
+ *
+ * Two auth classes, two route prefixes — the split is load-bearing:
+ *
+ * - `/system/peer/*` is the **server-to-server protocol**. Callers authenticate
+ *   with a server identity listed in `trusted-servers.json`. Only servers speak
+ *   it.
+ * - `/system/cluster/*` is the **admin surface**. Callers authenticate with a
+ *   system-admin JWT and pass the {@link CapabilityMatcher}. Only humans and
+ *   UIs speak it.
+ *
+ * No endpoint accepts both, so a peer can never administer and an admin can
+ * never write as a peer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PEER_SETTINGS = void 0;
+exports.isPeerSyncDirection = isPeerSyncDirection;
+exports.isPeerRole = isPeerRole;
+exports.isPeerAttachmentMode = isPeerAttachmentMode;
+exports.normalizePeerSettings = normalizePeerSettings;
+exports.shouldOpenSessionTo = shouldOpenSessionTo;
+exports.directionAllowsPush = directionAllowsPush;
+exports.directionAllowsPull = directionAllowsPull;
+exports.orderDatabasesForReplication = orderDatabasesForReplication;
+exports.isTrustBearingDatabase = isTrustBearingDatabase;
+exports.redactEntryIds = redactEntryIds;
+exports.classifyPeerError = classifyPeerError;
+const types_1 = require("../../core/types");
+exports.DEFAULT_PEER_SETTINGS = {
+    direction: "bidirectional",
+    role: "peer",
+    attachments: "eager",
+};
+function isPeerSyncDirection(value) {
+    return (value === "bidirectional" || value === "push" || value === "pull" || value === "disabled");
+}
+function isPeerRole(value) {
+    return value === "peer" || value === "hub" || value === "spoke";
+}
+function isPeerAttachmentMode(value) {
+    return value === "eager" || value === "lazy" || value === "never";
+}
+/** Fill in defaults for any peer field the operator left unset. */
+function normalizePeerSettings(raw) {
+    return {
+        direction: isPeerSyncDirection(raw.direction)
+            ? raw.direction
+            : exports.DEFAULT_PEER_SETTINGS.direction,
+        role: isPeerRole(raw.role) ? raw.role : exports.DEFAULT_PEER_SETTINGS.role,
+        attachments: isPeerAttachmentMode(raw.attachments)
+            ? raw.attachments
+            : exports.DEFAULT_PEER_SETTINGS.attachments,
+    };
+}
+/**
+ * Should this node open an outbound session to that peer?
+ *
+ * Spoke-to-spoke is the only pairing we suppress: both sides would otherwise
+ * dial each other even though the hub already carries their traffic.
+ */
+function shouldOpenSessionTo(local, remote) {
+    return !(local === "spoke" && remote === "spoke");
+}
+/** May we send local entries to this peer? */
+function directionAllowsPush(direction) {
+    return direction === "bidirectional" || direction === "push";
+}
+/** May we take the peer's entries? */
+function directionAllowsPull(direction) {
+    return direction === "bidirectional" || direction === "pull";
+}
+// =========================================================================
+// Replication ordering (convergence invariant 1)
+// =========================================================================
+/**
+ * Order the databases of one tenant for replication.
+ *
+ * `directory` first, then `userdirectory`, then everything else alphabetically.
+ * This is not cosmetic. A peer validates every pushed entry against its own
+ * directory (`validatePublicSigningKey`), and an unknown author key is a
+ * **per-entry rejection**, not a batch failure. Push an application database
+ * before the peer has the author's grant and those entries are refused; with
+ * the client's cursor semantics they would then be skipped forever, leaving the
+ * two servers silently divergent.
+ *
+ * The same ordering also shrinks the transient window in which a purged
+ * document or a revoked `decryptionKeyId` makes the peer answer `ACCESS_DENIED`
+ * for a whole batch: both denylists are derived from the directory (purge
+ * requests live there and are executed by `executePendingPurges` after every
+ * directory push), so they converge as soon as the directory has arrived.
+ */
+function orderDatabasesForReplication(dbIds) {
+    const rest = [];
+    let hasDirectory = false;
+    let hasUserDirectory = false;
+    for (const dbId of dbIds) {
+        if (dbId === types_1.DIRECTORY_DB_ID) {
+            hasDirectory = true;
+        }
+        else if (dbId === types_1.USER_DIRECTORY_DB_ID) {
+            hasUserDirectory = true;
+        }
+        else {
+            rest.push(dbId);
+        }
+    }
+    rest.sort((left, right) => left.localeCompare(right));
+    const ordered = [];
+    if (hasDirectory)
+        ordered.push(types_1.DIRECTORY_DB_ID);
+    if (hasUserDirectory)
+        ordered.push(types_1.USER_DIRECTORY_DB_ID);
+    return ordered.concat(rest);
+}
+/** True for the two system databases that must replicate before app data. */
+function isTrustBearingDatabase(dbId) {
+    return dbId === types_1.DIRECTORY_DB_ID || dbId === types_1.USER_DIRECTORY_DB_ID;
+}
+/**
+ * Bucket a replication failure so the console can react without parsing the
+ * message.
+ *
+ * The distinction that matters operationally is `access-denied` versus the
+ * rest: it is the peer *deliberately* refusing a batch (a purged document, a
+ * revoked key) and it resolves itself once the directory has replicated, so it
+ * warrants a backoff and not an alert. Everything else is either a
+ * misconfiguration (`auth`) or a genuine outage (`network`).
+ */
+/**
+ * Strip document and entry identifiers out of a message before it reaches the
+ * cluster status read-model.
+ *
+ * Rejection messages name the offending entry, and an entry id starts with the
+ * document id. The cluster console is a system-admin surface, and a system
+ * admin is not supposed to learn which documents a tenant holds — that is the
+ * same admin-blindness the encryption enforces, and it would be odd to hand it
+ * back through an error string. The classified reason plus the counts are what
+ * an operator can act on anyway.
+ */
+function redactEntryIds(message) {
+    return message.replace(/[0-9a-f]{16,}/gi, "<redacted>");
+}
+function classifyPeerError(error) {
+    const type = error?.type;
+    switch (type) {
+        case "ACCESS_DENIED":
+        // Every 403 reaches the client as USER_REVOKED, whatever the server meant
+        // by it. For a peer that is unambiguous: it holds no user identity, so a
+        // 403 can only mean the target refuses these particular entries — a purged
+        // document, a revoked decryption key. That is a backoff, not a
+        // misconfigured trust relationship.
+        case "USER_REVOKED":
+            return "access-denied";
+        case "INVALID_TOKEN":
+        case "INVALID_SIGNATURE":
+        case "CHALLENGE_EXPIRED":
+            return "auth";
+        case "NETWORK_ERROR":
+        case "RATE_LIMITED":
+            return "network";
+        case "PAYLOAD_TOO_LARGE":
+        case "SERVER_ERROR":
+            return "protocol";
+        default:
+            break;
+    }
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    if (message.includes("access_denied") || message.includes("access denied")) {
+        return "access-denied";
+    }
+    if (message.includes("401") ||
+        message.includes("403") ||
+        message.includes("authentication") ||
+        message.includes("token")) {
+        return "auth";
+    }
+    if (message.includes("fetch failed") ||
+        message.includes("econnrefused") ||
+        message.includes("enotfound") ||
+        message.includes("etimedout") ||
+        message.includes("socket") ||
+        message.includes("network")) {
+        return "network";
+    }
+    return "internal";
+}
+//# sourceMappingURL=types.js.map

package/dist/server/peer/types.js.map

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

package/dist/server/rateLimits.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Rate-limit resolution shared by the server's limiter tiers.
+ *
+ * Kept out of {@link MindooDBServer} so the interaction between the global net
+ * and the per-route tiers is testable on its own: it is the part that is easy
+ * to get wrong, and getting it wrong is silent — a global cap below a tier cap
+ * simply replaces that tier, and the tier's configuration stops meaning
+ * anything.
+ */
+import type { ServerRateLimitsConfig } from "./types";
+export interface ResolvedRateLimit {
+    windowMs: number;
+    max: number;
+}
+export interface ResolvedGlobalRateLimit extends ResolvedRateLimit {
+    /** Requests the tiers may spend inside the global window, plus headroom. */
+    tierFloor: number;
+    /** True when the resolved max rejects traffic a tier would still allow. */
+    shadowsTiers: boolean;
+}
+/**
+ * Resolve the global limiter against the tiers it is supposed to back up.
+ *
+ * Without an explicit `rateLimits.global`, the ceiling is derived from the
+ * tiers so the net catches only traffic no tier claims. An explicit value is
+ * honoured — an operator may want a hard cap — but reported as shadowing so
+ * the caller can say so at startup instead of leaving it to be discovered as
+ * mysterious 429s.
+ */
+export declare function resolveGlobalRateLimit(configured: ServerRateLimitsConfig["global"], tiers: {
+    sync: ResolvedRateLimit;
+    auth: ResolvedRateLimit;
+    defaultWindowMs: number;
+    headroom: number;
+}): ResolvedGlobalRateLimit;
+/**
+ * Bucket key for the sync tier.
+ *
+ * The principal is what makes this usable behind a NAT or a CDN: keyed on the
+ * address alone, one client opening several databases spends everyone else's
+ * budget. The address stays in the key so that callers we could not
+ * authenticate still get separated per source rather than sharing one
+ * "anonymous" bucket.
+ */
+export declare function buildSyncRateLimitKey(tenantId: string | undefined, principal: string | undefined, ip: string | undefined): string;
+/**
+ * Rate-limit defaults. Auth and sync have separate tiers because a single
+ * challenge/authenticate handshake is two requests; with multiple tenants,
+ * store kinds, and token renewals the auth budget exhausts quickly if set
+ * too low. These can be overridden in config.json under `rateLimits.auth`
+ * and `rateLimits.sync`.
+ */
+export declare const DEFAULT_AUTH_RATE_LIMIT_WINDOW_MS = 60000;
+export declare const DEFAULT_AUTH_RATE_LIMIT_MAX = 120;
+export declare const DEFAULT_SYNC_RATE_LIMIT_WINDOW_MS = 60000;
+/**
+ * Sync is keyed per authenticated principal, and a client legitimately opens
+ * several databases at once: a host like Teacher's Desk reads six, and a cold
+ * pass over one of them costs a few hundred batched requests. A budget sized
+ * for a single database turns that normal open into a throttled one.
+ */
+export declare const DEFAULT_SYNC_RATE_LIMIT_MAX = 3000;
+/**
+ * The global limiter is a coarse net for unauthenticated floods and unknown
+ * routes; the per-tier limiters are the real budgets. It runs first, so a
+ * global max below a tier max silently replaces that tier — the sync budget
+ * was unreachable while this was a hardcoded 500. The default is therefore
+ * derived from the tiers, and an override that would shadow one is honoured
+ * but flagged at startup rather than quietly applied.
+ */
+export declare const DEFAULT_GLOBAL_RATE_LIMIT_WINDOW_MS = 60000;
+export declare const GLOBAL_RATE_LIMIT_TIER_HEADROOM = 500;
+/**
+ * Timestamping gets its own budget rather than sharing the sync one. Sync is
+ * chatty and high-volume; sealing a document is a deliberate, rare user action.
+ * Sharing a bucket would let ordinary sync traffic starve the seal endpoint, and
+ * a runaway seal loop degrade sync.
+ *
+ * The daily cap matters more than the burst cap: proxying collapses every user
+ * onto the server's IP, so one tenant can exhaust an upstream's per-IP allowance
+ * (open-tsa.eu publishes 60/minute) and lock out everyone else on this server.
+ */
+export declare const DEFAULT_TIMESTAMP_RATE_LIMIT_WINDOW_MS = 60000;
+export declare const DEFAULT_TIMESTAMP_RATE_LIMIT_MAX = 10;
+export declare const DEFAULT_TIMESTAMP_DAILY_LIMIT_MAX = 500;
+export declare const TIMESTAMP_DAILY_WINDOW_MS: number;
+/** `/system/*` admin routes: aggressive per-IP throttle. */
+export declare const DEFAULT_SYSTEM_RATE_LIMIT_WINDOW_MS = 60000;
+export declare const DEFAULT_SYSTEM_RATE_LIMIT_MAX = 30;
+/** Device discovery scans every local tenant per request. */
+export declare const DEVICE_DISCOVERY_RATE_LIMIT: ResolvedRateLimit;
+/** Server-to-server peer routes; replication must not crawl. */
+export declare const PEER_RATE_LIMIT: ResolvedRateLimit;
+/** Every limiter tier of a server, resolved against `config.json`. */
+export interface ServerRateLimitPolicy {
+    global: ResolvedGlobalRateLimit;
+    auth: ResolvedRateLimit;
+    sync: ResolvedRateLimit;
+    timestamp: ResolvedRateLimit & {
+        dailyMax: number;
+    };
+    system: ResolvedRateLimit;
+    device: ResolvedRateLimit;
+    peer: ResolvedRateLimit;
+}
+export declare function resolveServerRateLimits(rateLimits: ServerRateLimitsConfig | undefined): ServerRateLimitPolicy;
+/**
+ * Composite key for the auth tier. Challenge requests include the username so
+ * that brute-forcing one account doesn't block legitimate users on the same
+ * IP. Authenticate requests omit username because the challenge token is
+ * already scoped to a single principal.
+ */
+export declare function buildAuthRateLimitKey(scope: "system" | "tenant", phase: "challenge" | "authenticate", tenantId: string | undefined, clientIp: string, body: {
+    username?: unknown;
+    signingPublicKey?: unknown;
+} | undefined): string;
+/** Bucket key of the timestamp tiers: tenant + principal + IP. */
+export declare function buildTimestampRateLimitKey(tier: "burst" | "daily", tenantId: string | undefined, principal: string | undefined, clientIp: string): string;
+//# sourceMappingURL=rateLimits.d.ts.map

package/dist/server/rateLimits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimits.d.ts","sourceRoot":"","sources":["../../src/server/rateLimits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EAC5C,KAAK,EAAE;IACL,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,iBAAiB,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,uBAAuB,CAiBzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,EAAE,EAAE,MAAM,GAAG,SAAS,GACrB,MAAM,CAER;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,QAAS,CAAC;AACxD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,iCAAiC,QAAS,CAAC;AACxD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAC1D,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD;;;;;;;;;GASG;AACH,eAAO,MAAM,sCAAsC,QAAS,CAAC;AAC7D,eAAO,MAAM,gCAAgC,KAAK,CAAC;AACnD,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD,eAAO,MAAM,yBAAyB,QAAsB,CAAC;AAE7D,4DAA4D;AAC5D,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAC1D,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,2BAA2B,EAAE,iBAAiD,CAAC;AAE5F,gEAAgE;AAChE,eAAO,MAAM,eAAe,EAAE,iBAAkD,CAAC;AAEjF,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,uBAAuB,CAAC;IAChC,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,iBAAiB,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,sBAAsB,GAAG,SAAS,GAC7C,qBAAqB,CA+BvB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,QAAQ,GAAG,QAAQ,EAC1B,KAAK,EAAE,WAAW,GAAG,cAAc,EACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,GACnE,MAAM,CAgBR;AAED,kEAAkE;AAClE,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,OAAO,GAAG,OAAO,EACvB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,MAAM,CAER"}