@portaidentity/server 1.7.0

package/dist/lib/bulk-operations.js

@@ -0,0 +1,201 @@
+/**
+ * Tenant-safe bulk status operations with ordered partial results.
+ *
+ * Whole-request validation completes before the first mutation. Each admitted item then owns one
+ * database transaction containing its lock, transition, update, and durable audit record. Domain
+ * rejections are isolated to that item. Dependency failures stop the operation and mark the
+ * current and remaining items as not attempted.
+ */
+import { randomUUID } from 'node:crypto';
+import { getPool } from './database.js';
+import { logger } from './logger.js';
+import { writeAuditLogInTransaction } from './audit-log.js';
+const ORGANIZATION_TRANSITIONS = Object.freeze({
+    activate: { from: ['suspended'], to: 'active' },
+    suspend: { from: ['active'], to: 'suspended' },
+    archive: { from: ['active', 'suspended'], to: 'archived' },
+});
+const USER_TRANSITIONS = Object.freeze({
+    activate: { from: ['inactive', 'suspended'], to: 'active' },
+    deactivate: { from: ['active'], to: 'inactive' },
+    suspend: { from: ['active'], to: 'suspended' },
+    lock: { from: ['active'], to: 'locked' },
+    unlock: { from: ['locked'], to: 'active' },
+});
+const MAXIMUM_ITEMS = 100;
+const MAXIMUM_REASON_CHARACTERS = 500;
+/** Validate every request-level invariant before opening an item transaction. */
+function requireValidInput(input) {
+    if (input.entityIds.length === 0)
+        return undefined;
+    if (input.entityIds.length > MAXIMUM_ITEMS) {
+        throw new Error('Bulk operations are limited to 100 items at a time');
+    }
+    if (new Set(input.entityIds).size !== input.entityIds.length) {
+        throw new Error('Bulk operations require unique entity identifiers');
+    }
+    if (input.reason !== undefined && input.reason.length > MAXIMUM_REASON_CHARACTERS) {
+        throw new Error('Bulk operation reason is limited to 500 characters');
+    }
+    if (input.entityType === 'user' && !input.organizationId) {
+        throw new Error('Organization scope is required for user bulk operations');
+    }
+    const transitions = input.entityType === 'organization' ? ORGANIZATION_TRANSITIONS : USER_TRANSITIONS;
+    const transition = transitions[input.action];
+    if (!transition) {
+        throw new Error(`Invalid action '${input.action}' for entity type '${input.entityType}'`);
+    }
+    return transition;
+}
+/** Roll back an open item transaction before returning a domain rejection. */
+async function rollback(client) {
+    await client.query('ROLLBACK');
+}
+/** Build the tenant-qualified row lock for the closed entity catalog. */
+async function lockCurrentStatus(client, input, id) {
+    if (input.entityType === 'user') {
+        const result = await client.query(`SELECT status FROM users
+       WHERE id = $1 AND organization_id = $2
+       FOR UPDATE`, [id, input.organizationId]);
+        return result.rows[0]?.status;
+    }
+    const result = await client.query('SELECT status FROM organizations WHERE id = $1 FOR UPDATE', [id]);
+    return result.rows[0]?.status;
+}
+/** Persist the status transition using only closed table and field choices. */
+async function updateStatus(client, input, id, nextStatus) {
+    if (input.entityType === 'user' &&
+        input.reason &&
+        (input.action === 'suspend' || input.action === 'lock')) {
+        await client.query(`UPDATE users
+       SET status = $1, updated_at = NOW(), suspension_reason = $2
+       WHERE id = $3 AND organization_id = $4`, [nextStatus, input.reason, id, input.organizationId]);
+        return;
+    }
+    if (input.entityType === 'user') {
+        await client.query(`UPDATE users SET status = $1, updated_at = NOW()
+       WHERE id = $2 AND organization_id = $3`, [nextStatus, id, input.organizationId]);
+        return;
+    }
+    await client.query('UPDATE organizations SET status = $1, updated_at = NOW() WHERE id = $2', [
+        nextStatus,
+        id,
+    ]);
+}
+/** Insert the per-item audit record through the same transaction as the mutation. */
+async function insertAudit(client, input, id, previousStatus, nextStatus) {
+    const organizationId = input.entityType === 'organization' ? id : input.organizationId;
+    const userId = input.entityType === 'user' ? id : null;
+    await writeAuditLogInTransaction(client, {
+        organizationId,
+        ...(userId === null ? {} : { userId }),
+        ...(input.actorId === undefined ? {} : { actorId: input.actorId }),
+        eventType: `admin.bulk.${input.entityType}.status_changed`,
+        eventCategory: 'admin',
+        metadata: { action: input.action, previousStatus, newStatus: nextStatus },
+    });
+}
+/** Create one concealed missing/foreign item result. */
+function concealedResult(id) {
+    return {
+        id,
+        success: false,
+        outcome: 'failed',
+        code: 'not_found_or_not_authorized',
+        error: 'Entity not found or not authorized',
+    };
+}
+/** Create one closed invalid-transition result. */
+function invalidTransitionResult(id, previousStatus) {
+    return {
+        id,
+        success: false,
+        outcome: 'failed',
+        code: 'invalid_transition',
+        error: 'Status transition not allowed',
+        previousStatus,
+    };
+}
+/** Create an explicit result for work skipped after dependency failure. */
+function notAttemptedResult(id) {
+    return {
+        id,
+        success: false,
+        outcome: 'not_attempted',
+        code: 'not_attempted',
+        error: 'Operation not attempted',
+    };
+}
+/**
+ * Execute an ordered partial-result bulk status operation.
+ *
+ * @param input - Fully validated entity, action, scope, and actor input.
+ * @returns Ordered item outcomes. A dependency stop includes one server correlation ID.
+ */
+export async function bulkStatusChange(input) {
+    const transition = requireValidInput(input);
+    if (!transition) {
+        return { total: 0, succeeded: 0, failed: 0, results: [] };
+    }
+    const pool = getPool();
+    const results = [];
+    let correlationId;
+    for (let index = 0; index < input.entityIds.length; index += 1) {
+        const id = input.entityIds[index];
+        let client;
+        try {
+            client = await pool.connect();
+            await client.query('BEGIN');
+            const previousStatus = await lockCurrentStatus(client, input, id);
+            if (previousStatus === undefined) {
+                await rollback(client);
+                results.push(concealedResult(id));
+                continue;
+            }
+            if (!transition.from.includes(previousStatus)) {
+                await rollback(client);
+                results.push(invalidTransitionResult(id, previousStatus));
+                continue;
+            }
+            await updateStatus(client, input, id, transition.to);
+            await insertAudit(client, input, id, previousStatus, transition.to);
+            await client.query('COMMIT');
+            results.push({
+                id,
+                success: true,
+                outcome: 'succeeded',
+                code: null,
+                previousStatus,
+                newStatus: transition.to,
+            });
+        }
+        catch {
+            if (client) {
+                try {
+                    await rollback(client);
+                }
+                catch {
+                    // The public result remains the same when rollback outcome is unknown.
+                }
+            }
+            correlationId = randomUUID();
+            logger.warn({ correlationId, entityType: input.entityType, action: input.action }, 'Bulk operation stopped after a dependency failure');
+            for (let pending = index; pending < input.entityIds.length; pending += 1) {
+                results.push(notAttemptedResult(input.entityIds[pending]));
+            }
+            break;
+        }
+        finally {
+            client?.release();
+        }
+    }
+    const succeeded = results.filter((result) => result.outcome === 'succeeded').length;
+    return {
+        total: input.entityIds.length,
+        succeeded,
+        failed: input.entityIds.length - succeeded,
+        results,
+        ...(correlationId ? { correlationId } : {}),
+    };
+}
+//# sourceMappingURL=bulk-operations.js.map

package/dist/lib/bulk-operations.js.map

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

package/dist/lib/cursor.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Cursor-based pagination utility.
+ *
+ * Provides opaque cursor encoding and decoding for keyset pagination.
+ * Cursors encode the sort value and entity ID of the last item in a
+ * result set, enabling efficient "next page" queries using:
+ *
+ *   WHERE (sort_column, id) > ($cursor_sort, $cursor_id)
+ *
+ * Cursors are base64url-encoded JSON strings — opaque to API consumers
+ * but decodable by the server. Invalid or tampered cursors are safely
+ * rejected (returns null from decodeCursor).
+ *
+ * @module lib/cursor
+ */
+/**
+ * Internal cursor payload — the data encoded inside an opaque cursor string.
+ *
+ * @property s - Sort field value at the cursor position (string, number, or null for NULLs)
+ * @property i - Entity ID at the cursor position (UUID) — ensures stable ordering for ties
+ */
+export interface CursorPayload {
+    /** Sort field value at the cursor position */
+    s: string | number | null;
+    /** Entity ID (UUID) — tie-breaker for stable ordering */
+    i: string;
+}
+/**
+ * Options for cursor-based pagination.
+ *
+ * When `cursor` is provided, keyset pagination is used.
+ * When `page` is provided (without cursor), offset pagination is used.
+ * When neither is provided, defaults to offset pagination page 1.
+ */
+export interface CursorPaginationOptions {
+    /** Opaque cursor string from a previous response */
+    cursor?: string;
+    /** Maximum items per page (default 25, max 100) */
+    limit?: number;
+    /** Sort column (must be whitelisted per-entity) */
+    sortBy?: string;
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Result shape for cursor-paginated queries.
+ *
+ * Includes the data array, navigation cursors, and a hasMore flag.
+ * `nextCursor` is null when there are no more results.
+ * `previousCursor` is the cursor of the first item (for potential reverse navigation).
+ */
+export interface CursorPaginatedResult<T> {
+    /** The page of results */
+    data: T[];
+    /** Cursor to fetch the next page — null if no more results */
+    nextCursor: string | null;
+    /** Cursor of the first item in this page — null if the page is empty */
+    previousCursor: string | null;
+    /** Whether there are more results after this page */
+    hasMore: boolean;
+}
+/**
+ * Encode a cursor from the last item in a result set.
+ *
+ * Produces an opaque base64url string safe for URL query parameters.
+ * The cursor encodes the sort value and entity ID, which together
+ * define the exact position in the ordered result set.
+ *
+ * @param sortValue - The sort field value of the item (string, number, or null)
+ * @param id - The entity UUID of the item
+ * @returns Opaque cursor string
+ *
+ * @example
+ * const cursor = encodeCursor('2026-01-15T10:00:00Z', 'abc-123');
+ * // → 'eyJzIjoiMjAyNi0wMS0xNVQxMDowMDowMFoiLCJpIjoiYWJjLTEyMyJ9'
+ */
+export declare function encodeCursor(sortValue: string | number | null, id: string): string;
+/**
+ * Decode an opaque cursor string back to a CursorPayload.
+ *
+ * Returns null if the cursor is invalid — malformed base64, invalid JSON,
+ * missing fields, or wrong types. This ensures tampered or corrupted
+ * cursors are safely rejected without throwing exceptions.
+ *
+ * @param cursor - The opaque cursor string to decode
+ * @returns Decoded payload, or null if invalid
+ *
+ * @example
+ * const payload = decodeCursor('eyJzIjoiMjAyNi0wMS0xNVQxMDowMDowMFoiLCJpIjoiYWJjLTEyMyJ9');
+ * // → { s: '2026-01-15T10:00:00Z', i: 'abc-123' }
+ *
+ * const invalid = decodeCursor('not-a-cursor');
+ * // → null
+ */
+export declare function decodeCursor(cursor: string): CursorPayload | null;
+/**
+ * Build a CursorPaginatedResult from a query result set.
+ *
+ * The caller should query for `limit + 1` rows. If the extra row exists,
+ * `hasMore` is true and the extra row is stripped from the result.
+ * Cursors are generated using the provided sort value extractor function.
+ *
+ * @param rows - Raw query rows (may include the extra hasMore row)
+ * @param limit - The requested page size
+ * @param getSortValue - Function to extract the sort value from a row
+ * @param getId - Function to extract the entity ID from a row
+ * @returns CursorPaginatedResult with cursors and hasMore flag
+ */
+export declare function buildCursorResult<T>(rows: T[], limit: number, getSortValue: (row: T) => string | number | null, getId: (row: T) => string): CursorPaginatedResult<T>;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/lib/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/lib/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1B,yDAAyD;IACzD,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,0BAA0B;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAKlF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAoCjE;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,IAAI,EAAE,CAAC,EAAE,EACT,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GAAG,IAAI,EAChD,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GACxB,qBAAqB,CAAC,CAAC,CAAC,CAa1B"}

package/dist/lib/cursor.js

@@ -0,0 +1,115 @@
+/**
+ * Cursor-based pagination utility.
+ *
+ * Provides opaque cursor encoding and decoding for keyset pagination.
+ * Cursors encode the sort value and entity ID of the last item in a
+ * result set, enabling efficient "next page" queries using:
+ *
+ *   WHERE (sort_column, id) > ($cursor_sort, $cursor_id)
+ *
+ * Cursors are base64url-encoded JSON strings — opaque to API consumers
+ * but decodable by the server. Invalid or tampered cursors are safely
+ * rejected (returns null from decodeCursor).
+ *
+ * @module lib/cursor
+ */
+// ============================================================================
+// Encoding / Decoding
+// ============================================================================
+/**
+ * Encode a cursor from the last item in a result set.
+ *
+ * Produces an opaque base64url string safe for URL query parameters.
+ * The cursor encodes the sort value and entity ID, which together
+ * define the exact position in the ordered result set.
+ *
+ * @param sortValue - The sort field value of the item (string, number, or null)
+ * @param id - The entity UUID of the item
+ * @returns Opaque cursor string
+ *
+ * @example
+ * const cursor = encodeCursor('2026-01-15T10:00:00Z', 'abc-123');
+ * // → 'eyJzIjoiMjAyNi0wMS0xNVQxMDowMDowMFoiLCJpIjoiYWJjLTEyMyJ9'
+ */
+export function encodeCursor(sortValue, id) {
+    const payload = { s: sortValue, i: id };
+    const json = JSON.stringify(payload);
+    // Use base64url encoding (no padding) for URL safety
+    return Buffer.from(json, 'utf-8').toString('base64url');
+}
+/**
+ * Decode an opaque cursor string back to a CursorPayload.
+ *
+ * Returns null if the cursor is invalid — malformed base64, invalid JSON,
+ * missing fields, or wrong types. This ensures tampered or corrupted
+ * cursors are safely rejected without throwing exceptions.
+ *
+ * @param cursor - The opaque cursor string to decode
+ * @returns Decoded payload, or null if invalid
+ *
+ * @example
+ * const payload = decodeCursor('eyJzIjoiMjAyNi0wMS0xNVQxMDowMDowMFoiLCJpIjoiYWJjLTEyMyJ9');
+ * // → { s: '2026-01-15T10:00:00Z', i: 'abc-123' }
+ *
+ * const invalid = decodeCursor('not-a-cursor');
+ * // → null
+ */
+export function decodeCursor(cursor) {
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf-8');
+        const parsed = JSON.parse(json);
+        // Validate shape: must be an object with 's' and 'i' fields
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            !('s' in parsed) ||
+            !('i' in parsed)) {
+            return null;
+        }
+        const obj = parsed;
+        // Validate 'i' is a non-empty string (entity ID)
+        if (typeof obj.i !== 'string' || obj.i.length === 0) {
+            return null;
+        }
+        // Validate 's' is string, number, or null (sort value)
+        const sortType = typeof obj.s;
+        if (obj.s !== null && sortType !== 'string' && sortType !== 'number') {
+            return null;
+        }
+        return {
+            s: obj.s,
+            i: obj.i,
+        };
+    }
+    catch {
+        // JSON parse error, base64 decode error, etc.
+        return null;
+    }
+}
+// ============================================================================
+// Result Builder
+// ============================================================================
+/**
+ * Build a CursorPaginatedResult from a query result set.
+ *
+ * The caller should query for `limit + 1` rows. If the extra row exists,
+ * `hasMore` is true and the extra row is stripped from the result.
+ * Cursors are generated using the provided sort value extractor function.
+ *
+ * @param rows - Raw query rows (may include the extra hasMore row)
+ * @param limit - The requested page size
+ * @param getSortValue - Function to extract the sort value from a row
+ * @param getId - Function to extract the entity ID from a row
+ * @returns CursorPaginatedResult with cursors and hasMore flag
+ */
+export function buildCursorResult(rows, limit, getSortValue, getId) {
+    const hasMore = rows.length > limit;
+    const data = hasMore ? rows.slice(0, limit) : rows;
+    const nextCursor = hasMore && data.length > 0
+        ? encodeCursor(getSortValue(data[data.length - 1]), getId(data[data.length - 1]))
+        : null;
+    const previousCursor = data.length > 0
+        ? encodeCursor(getSortValue(data[0]), getId(data[0]))
+        : null;
+    return { data, nextCursor, previousCursor, hasMore };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/lib/cursor.js.map

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

package/dist/lib/data-export.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Bounded administrative data export.
+ *
+ * Every query selects an explicit public field list, reads one row beyond the public limit, and
+ * writes a content-free audit record in the same repeatable-read transaction. CSV output is
+ * neutralized before quoting so spreadsheet applications cannot execute imported formulas.
+ */
+/** Closed serialization formats accepted by the export service. */
+export type ExportFormat = 'json' | 'csv';
+/** Closed entity catalog accepted by the export service. */
+export type ExportEntityType = 'users' | 'organizations' | 'clients' | 'roles' | 'audit';
+/** Maximum number of rows returned by one export. */
+export declare const MAXIMUM_EXPORT_ROWS = 10000;
+/** Input for one authorized administrative export. */
+export interface ExportOptions {
+    /** Entity catalog to serialize. */
+    entityType: ExportEntityType;
+    /** Public output representation. */
+    format: ExportFormat;
+    /** Exact tenant scope for tenant-owned data. */
+    organizationId?: string;
+    /** Exact application relationship required for role data. */
+    applicationId?: string;
+    /** Inclusive audit-window start. */
+    startDate?: Date;
+    /** Inclusive audit-window end. */
+    endDate?: Date;
+    /** Authenticated administrator recorded without export content. */
+    actorId?: string;
+}
+/** Serialized export admitted after scope, bound, and audit checks. */
+export interface ExportResult {
+    /** Complete serialized document. */
+    data: string;
+    /** Public response media type. */
+    contentType: string;
+    /** Attachment filename without user-controlled input. */
+    filename: string;
+    /** Exact number of exported rows. */
+    rowCount: number;
+}
+/** Stable public export failures. */
+export type ExportFailureCode = 'export_scope_required' | 'export_invalid_range' | 'export_too_large' | 'export_failed';
+/** Minimal export failure which never retains query or row diagnostics. */
+export declare class ExportOperationError extends Error {
+    /** Stable public failure discriminator. */
+    readonly code: ExportFailureCode;
+    /** Recommended HTTP status. */
+    readonly status: 400 | 413 | 503;
+    /**
+     * Create a closed export failure.
+     *
+     * @param code - Stable public failure discriminator.
+     * @param status - Recommended route status.
+     */
+    constructor(code: ExportFailureCode, status: 400 | 413 | 503);
+}
+/**
+ * Export one authorized entity set through a bounded repeatable-read transaction.
+ *
+ * @param options - Exact entity, representation, scope, and actor.
+ * @returns Complete serialized export and exact row count.
+ * @throws ExportOperationError when scope is incomplete, the bound is exceeded, or persistence
+ * fails.
+ */
+export declare function exportData(options: ExportOptions): Promise<ExportResult>;
+//# sourceMappingURL=data-export.d.ts.map

package/dist/lib/data-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-export.d.ts","sourceRoot":"","sources":["../../src/lib/data-export.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC;AAE1C,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAEzF,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,oCAAoC;IACpC,MAAM,EAAE,YAAY,CAAC;IACrB,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,kCAAkC;IAClC,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,MAAM,iBAAiB,GAC3B,uBAAuB,GAAG,sBAAsB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE1F,2EAA2E;AAC3E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,2CAA2C;IAC3C,SAAgB,IAAI,EAAE,iBAAiB,CAAC;IAExC,+BAA+B;IAC/B,SAAgB,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAExC;;;;;OAKG;IACH,YAAmB,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,EAKlE;CACF;AAqMD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAgD9E"}