@ibgib/node-gib 0.0.14 → 0.0.17

package/dist/identity/sso/custodian-auth-helpers.d.mts

@@ -0,0 +1,45 @@
+import { CustodianRequirements } from './sso-types.mjs';
+/**
+ * Derives a deterministic single-turn authorization code using the server's private KDF secret
+ * and the JSON-stringified `custodianReqs` (excluding `authCode` itself) as salt.
+ *
+ * @param custodianReqsOmitAuthCode The custodian requirements object omitting the `authCode` property.
+ * @param serverSecret The server's private KDF secret (`SSO_SERVER_KDF_SECRET`).
+ */
+export declare function deriveCustodianAuthCode({ custodianReqsOmitAuthCode, serverSecret, }: {
+    custodianReqsOmitAuthCode: Omit<CustodianRequirements, 'authCode'>;
+    serverSecret: string;
+}): Promise<string>;
+/**
+ * Generates a full `CustodianRequirements` object containing single-turn nonce,
+ * expiration timestamp, permitted verbs, and derived auth code.
+ *
+ * @param primaryTjpAddr Primary identity keystone TJP address (`ib^gib`).
+ * @param ttlMs Time-to-live duration in milliseconds. Defaults to 15 minutes.
+ * @param allowedVerbs Permitted keystone verbs. Defaults to `['sync', 'connect']`.
+ * @param serverSecret The server's private KDF secret (`SSO_SERVER_KDF_SECRET`).
+ */
+export declare function generateCustodianRequirements({ primaryTjpAddr, ttlMs, allowedVerbs, serverSecret, }: {
+    primaryTjpAddr: string;
+    ttlMs?: number;
+    allowedVerbs?: string[];
+    serverSecret: string;
+}): Promise<CustodianRequirements>;
+/**
+ * Computes the deterministic index hash (`authCustodianIndex`) over the full `CustodianRequirements` object
+ * used for atomic file reservation tracking on the server filesystem.
+ */
+export declare function getAuthCustodianIndex({ custodianReqs, }: {
+    custodianReqs: CustodianRequirements;
+}): Promise<string>;
+/**
+ * Cryptographically verifies a `CustodianRequirements` object against expiration and server KDF authCode match.
+ */
+export declare function verifyCustodianRequirements({ custodianReqs, serverSecret, }: {
+    custodianReqs: CustodianRequirements;
+    serverSecret: string;
+}): Promise<{
+    valid: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=custodian-auth-helpers.d.mts.map

package/dist/identity/sso/custodian-auth-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custodian-auth-helpers.d.mts","sourceRoot":"","sources":["../../../src/identity/sso/custodian-auth-helpers.mts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,EAC1C,yBAAyB,EACzB,YAAY,GACf,EAAE;IACC,yBAAyB,EAAE,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,CAAC;IACnE,YAAY,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CAAC,EAChD,cAAc,EACd,KAAsB,EACtB,YAA0D,EAC1D,YAAY,GACf,EAAE;IACC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAiCjC;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,EACxC,aAAa,GAChB,EAAE;IACC,aAAa,EAAE,qBAAqB,CAAC;CACxC,GAAG,OAAO,CAAC,MAAM,CAAC,CAKlB;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAAC,EAC9C,aAAa,EACb,YAAY,GACf,EAAE;IACC,aAAa,EAAE,qBAAqB,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB9C"}

package/dist/identity/sso/custodian-auth-helpers.mjs

@@ -0,0 +1,108 @@
+import { getUUID, hash, HashAlgorithm, extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { kdf_recursiveSaltWrap } from '@ibgib/core-gib/dist/keystone/kdf/kdf-helpers.mjs';
+import { KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+/**
+ * Derives a deterministic single-turn authorization code using the server's private KDF secret
+ * and the JSON-stringified `custodianReqs` (excluding `authCode` itself) as salt.
+ *
+ * @param custodianReqsOmitAuthCode The custodian requirements object omitting the `authCode` property.
+ * @param serverSecret The server's private KDF secret (`SSO_SERVER_KDF_SECRET`).
+ */
+export async function deriveCustodianAuthCode({ custodianReqsOmitAuthCode, serverSecret, }) {
+    const lc = `[${deriveCustodianAuthCode.name}]`;
+    try {
+        if (!serverSecret) {
+            throw new Error('serverSecret required for custodian auth code derivation (E: a1b2c3d4e5f67890123456789abcdef0)');
+        }
+        const salt = await hash({
+            s: JSON.stringify(custodianReqsOmitAuthCode),
+            algorithm: HashAlgorithm.sha_512
+        });
+        return await kdf_recursiveSaltWrap({
+            masterSecret: serverSecret,
+            salt,
+            rounds: 1000,
+            algorithm: HashAlgorithm.sha_512
+        });
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+/**
+ * Generates a full `CustodianRequirements` object containing single-turn nonce,
+ * expiration timestamp, permitted verbs, and derived auth code.
+ *
+ * @param primaryTjpAddr Primary identity keystone TJP address (`ib^gib`).
+ * @param ttlMs Time-to-live duration in milliseconds. Defaults to 15 minutes.
+ * @param allowedVerbs Permitted keystone verbs. Defaults to `['sync', 'connect']`.
+ * @param serverSecret The server's private KDF secret (`SSO_SERVER_KDF_SECRET`).
+ */
+export async function generateCustodianRequirements({ primaryTjpAddr, ttlMs = 15 * 60 * 1000, allowedVerbs = [KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT], serverSecret, }) {
+    const lc = `[${generateCustodianRequirements.name}]`;
+    try {
+        if (!primaryTjpAddr) {
+            throw new Error('primaryTjpAddr is required to generate custodian requirements (E: b2c3d4e5f67890123456789abcdef01)');
+        }
+        if (!serverSecret) {
+            throw new Error('serverSecret is required to generate custodian requirements (E: c3d4e5f67890123456789abcdef012)');
+        }
+        const nonce = await getUUID();
+        const expiresAt = Date.now() + ttlMs;
+        const custodianReqsOmitAuthCode = {
+            primaryTjpAddr,
+            nonce,
+            expiresAt,
+            allowedVerbs,
+        };
+        const authCode = await deriveCustodianAuthCode({
+            custodianReqsOmitAuthCode,
+            serverSecret
+        });
+        return {
+            ...custodianReqsOmitAuthCode,
+            authCode
+        };
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+/**
+ * Computes the deterministic index hash (`authCustodianIndex`) over the full `CustodianRequirements` object
+ * used for atomic file reservation tracking on the server filesystem.
+ */
+export async function getAuthCustodianIndex({ custodianReqs, }) {
+    return await hash({
+        s: JSON.stringify(custodianReqs),
+        algorithm: HashAlgorithm.sha_256
+    });
+}
+/**
+ * Cryptographically verifies a `CustodianRequirements` object against expiration and server KDF authCode match.
+ */
+export async function verifyCustodianRequirements({ custodianReqs, serverSecret, }) {
+    try {
+        if (!custodianReqs || !custodianReqs.authCode || !custodianReqs.nonce || !custodianReqs.expiresAt || !custodianReqs.primaryTjpAddr) {
+            return { valid: false, error: 'Malformed custodian requirements structure. (E: d4e5f67890123456789abcdef0123)' };
+        }
+        if (Date.now() > custodianReqs.expiresAt) {
+            return { valid: false, error: 'Custodian requirements have expired. (E: e5f67890123456789abcdef01234)' };
+        }
+        const { authCode, ...custodianReqsOmitAuthCode } = custodianReqs;
+        const expectedAuthCode = await deriveCustodianAuthCode({
+            custodianReqsOmitAuthCode,
+            serverSecret
+        });
+        if (authCode !== expectedAuthCode) {
+            return { valid: false, error: 'Cryptographic authCode mismatch. Requirement payload tampered or invalid. (E: f67890123456789abcdef012345)' };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        return { valid: false, error: `Verification failed: ${extractErrorMsg(error)} (E: 7890123456789abcdef0123456)` };
+    }
+}
+//# sourceMappingURL=custodian-auth-helpers.mjs.map

package/dist/identity/sso/custodian-auth-helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"custodian-auth-helpers.mjs","sourceRoot":"","sources":["../../../src/identity/sso/custodian-auth-helpers.mts"],"names":[],"mappings":"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"}

package/dist/identity/sso/sso-config-helper.d.mts

@@ -0,0 +1,7 @@
+import { SsoServerConfig } from './sso-types.mjs';
+/**
+ * Loads the SSO configuration from environment variables.
+ * Parses active OAuth2 providers dynamically based on their environment keys.
+ */
+export declare function loadSsoServerConfig(): SsoServerConfig;
+//# sourceMappingURL=sso-config-helper.d.mts.map

package/dist/identity/sso/sso-config-helper.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-config-helper.d.mts","sourceRoot":"","sources":["../../../src/identity/sso/sso-config-helper.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA0C,MAAM,iBAAiB,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,CA6CrD"}

package/dist/identity/sso/sso-config-helper.mjs

@@ -0,0 +1,42 @@
+/**
+ * Loads the SSO configuration from environment variables.
+ * Parses active OAuth2 providers dynamically based on their environment keys.
+ */
+export function loadSsoServerConfig() {
+    const ssoServerKdfSecret = process.env.SSO_SERVER_KDF_SECRET;
+    const sessionSecret = process.env.SESSION_SECRET;
+    if (!ssoServerKdfSecret) {
+        throw new Error(`SSO_SERVER_KDF_SECRET is missing from environment. (E: 840899ab4fdfd23e89cfae1889cfae12)`);
+    }
+    if (!sessionSecret) {
+        throw new Error(`SESSION_SECRET is missing from environment. (E: bfa899ab4fdfd23e89cfae23)`);
+    }
+    const providers = {};
+    // Load Google Provider if configured
+    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+        providers.google = {
+            providerId: 'google',
+            clientId: process.env.GOOGLE_CLIENT_ID,
+            clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+            tokenUrl: 'https://oauth2.googleapis.com/token',
+            userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+            jwksUrl: 'https://www.googleapis.com/oauth2/v3/certs'
+        };
+    }
+    // Load GitHub Provider if configured
+    if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+        providers.github = {
+            providerId: 'github',
+            clientId: process.env.GITHUB_CLIENT_ID,
+            clientSecret: process.env.GITHUB_CLIENT_SECRET,
+            tokenUrl: 'https://github.com/login/oauth/access_token',
+            userInfoUrl: 'https://api.github.com/user'
+        };
+    }
+    return {
+        ssoServerKdfSecret,
+        sessionSecret,
+        providers
+    };
+}
+//# sourceMappingURL=sso-config-helper.mjs.map

package/dist/identity/sso/sso-config-helper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-config-helper.mjs","sourceRoot":"","sources":["../../../src/identity/sso/sso-config-helper.mts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IAC/B,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAC7D,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAEjD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACX,0FAA0F,CAC7F,CAAC;IACN,CAAC;IACD,IAAI,CAAC,aAAa,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACX,2EAA2E,CAC9E,CAAC;IACN,CAAC;IAED,MAAM,SAAS,GAA4D,EAAE,CAAC;IAE9E,qCAAqC;IACrC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACnE,SAAS,CAAC,MAAM,GAAG;YACf,UAAU,EAAE,QAAQ;YACpB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;YACtC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;YAC9C,QAAQ,EAAE,qCAAqC;YAC/C,WAAW,EAAE,kDAAkD;YAC/D,OAAO,EAAE,4CAA4C;SACxD,CAAC;IACN,CAAC;IAED,qCAAqC;IACrC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;QACnE,SAAS,CAAC,MAAM,GAAG;YACf,UAAU,EAAE,QAAQ;YACpB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;YACtC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;YAC9C,QAAQ,EAAE,6CAA6C;YACvD,WAAW,EAAE,6BAA6B;SAC7C,CAAC;IACN,CAAC;IAED,OAAO;QACH,kBAAkB;QAClB,aAAa;QACb,SAAS;KACZ,CAAC;AACN,CAAC"}

package/dist/identity/sso/sso-custodian-service.d.mts

@@ -0,0 +1,139 @@
+import { KeystoneChallengePool } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { SsoServerConfig, SsoProviderId, OAuthUserInfo, SsoProviderServerConfig, SsoProviderClientConfig } from './sso-types.mjs';
+/**
+ * Server-side service for token exchange, JWT validation, and user profile normalization.
+ */
+export declare class SsoCustodianService {
+    private config;
+    private lc;
+    private jwksCache;
+    private jwksTtlMs;
+    /**
+     * @param config The server's global SSO configuration.
+     *   - Visibility: Private (Contains high-entropy secrets like `ssoServerKdfSecret` and `sessionSecret`).
+     *   - Generator: Server (Bootstrapped from node environment variables on server initialization).
+     */
+    constructor(config: SsoServerConfig);
+    /**
+     * Exchanges an authorization code for an OAuth2 token and retrieves normalized user info.
+     *
+     * @param providerId The string identifier of the OAuth provider (e.g. 'google' or 'github').
+     *   - Visibility: Public (Non-sensitive metadata string).
+     *   - Generator: Client (Sent from browser UI selection).
+     *
+     * @param code The temporary authorization code returned by the OAuth provider.
+     *   - Visibility: Private (Confidential short-lived bearer credential. Must be kept private).
+     *   - Generator: Provider (Created by provider's OAuth page and sent to client redirect URI).
+     *
+     * @param redirectUri The redirect URI registered in the provider portal.
+     *   - Visibility: Public (Configuration URL).
+     *   - Generator: Client/Server (Derived from environmental configuration and sent by client).
+     */
+    getOAuthUserInfo(providerId: SsoProviderId, code: string, redirectUri: string): Promise<OAuthUserInfo>;
+    /**
+     * Directly validates a Google ID Token (JWT) locally and returns normalized user info.
+     * Useful for client-side authentication handshakes.
+     *
+     * @param idToken The raw base64-encoded signed JSON Web Token (JWT) ID token returned by Google.
+     *   - Visibility: Private (Sensitive bearer credential containing signature and claims. Must be kept private).
+     *   - Generator: Provider (Generated and signed cryptographically by Google authentication servers).
+     */
+    verifyAndNormalizeGoogleToken(idToken: string): Promise<OAuthUserInfo>;
+    /**
+     * Internal: Exchange authorization code for access token / ID token.
+     *
+     * @param providerConfig Server configuration settings for the specific provider.
+     *   - Visibility: Private (Contains provider client secrets. Must stay server-side).
+     *   - Generator: Server (Configured from node environment variables).
+     *
+     * @param code The temporary authorization code to exchange.
+     *   - Visibility: Private (Short-lived credential. Must be kept private).
+     *   - Generator: Provider (Via OAuth flow).
+     *
+     * @param redirectUri The redirect URI registered for the exchange.
+     *   - Visibility: Public (Configuration URL).
+     *   - Generator: Client/Server (From app configuration).
+     */
+    private exchangeCodeForTokens;
+    /**
+     * Internal: Fetch GitHub user profile and normalize.
+     *
+     * @param providerConfig Server configuration settings for GitHub.
+     *   - Visibility: Private (Contains GitHub client secret).
+     *   - Generator: Server (From environment config).
+     *
+     * @param accessToken The active OAuth2 access token to authorize the API call.
+     *   - Visibility: Private (Bearer token. Must be kept private).
+     *   - Generator: Provider (GitHub token endpoint).
+     */
+    private fetchAndNormalizeGithubUser;
+    /**
+     * Internal: Decodes and cryptographically verifies a JWT signature using JWKS public keys.
+     *
+     * @param token The raw base64-encoded JWT token to verify.
+     *   - Visibility: Private (Sensitive token. Must be kept private).
+     *   - Generator: Provider (Google / OIDC server).
+     *
+     * @param providerConfig The target provider server settings containing `jwksUrl`.
+     *   - Visibility: Private (Contains secrets).
+     *   - Generator: Server (From environment config).
+     */
+    verifyJwt(token: string, providerConfig: SsoProviderServerConfig): Promise<any>;
+    /**
+     * Internal: Retrieves JWKS keys from cache or fetches them from the provider's jwksUrl.
+     *
+     * @param providerConfig The provider config containing the target `jwksUrl`.
+     *   - Visibility: Private (Contains client secrets).
+     *   - Generator: Server (From environment config).
+     */
+    private getJwksKeys;
+    /**
+     * Derives a server-delegate master secret deterministically using the server's private KDF secret,
+     * the providerKey, and the user's public nonce.
+     *
+     * @param providerKey The unique key identifying the provider and user sub ID (e.g. `google:123...`).
+     *   - Visibility: Public (Identifier saved on parent's delegate claim, safe for log/ledger storage).
+     *   - Generator: Provider/Server (Derived by mapping provider user sub ID after authentication).
+     *
+     * @param userNonce The public, high-entropy nonce generated by the client to salt the KDF derivation.
+     *   - Visibility: Public (Salt value stored on parent's delegate claim, safe for ledger storage).
+     *   - Generator: Client (Generated offline on user's device).
+     */
+    deriveServerDelegateSecret(providerKey: string, userNonce: string): Promise<string>;
+    /**
+     * Creates a public custodian challenge pool (custodian-manage) derived deterministically
+     * from the server's private KDF secret, providerKey, and userNonce.
+     *
+     * @param providerKey The unique key identifying the provider and user sub ID (e.g. `google:123...`).
+     *   - Visibility: Public (Mapped identifier, safe for ledger).
+     *   - Generator: Provider/Server (Derived after successful token exchange).
+     *
+     * @param userNonce The public, high-entropy nonce.
+     *   - Visibility: Public (Derivation salt, safe for ledger).
+     *   - Generator: Client (Generated on user's device).
+     */
+    createCustodianChallengePool({ providerId, providerKey, userNonce, keystoneAddr, metaspace, space, }: {
+        providerId: string;
+        providerKey: string;
+        userNonce: string;
+        keystoneAddr: string;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneChallengePool>;
+    /**
+     * Maps private server configuration to safe public client configurations.
+     *
+     * @param hostUrl The root URL host address of the server (e.g. `https://space-gib.localhost` or `https://ibgib.space`).
+     *   - Visibility: Public (Non-sensitive hostname configuration).
+     *   - Generator: Server (Extracted from the HTTP request context headers/protocol).
+     */
+    getSsoClientConfigs(hostUrl: string): SsoProviderClientConfig[];
+    /**
+     * Revokes an active OAuth access or refresh token with the provider.
+     * Keeps token revocation logic DRY and centralized.
+     */
+    revokeToken(providerId: SsoProviderId, token: string): Promise<void>;
+}
+//# sourceMappingURL=sso-custodian-service.d.mts.map

package/dist/identity/sso/sso-custodian-service.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sso-custodian-service.d.mts","sourceRoot":"","sources":["../../../src/identity/sso/sso-custodian-service.mts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAsB,MAAM,kDAAkD,CAAC;AAI7G,OAAO,EAAE,gBAAgB,EAAE,MAAM,kEAAkE,CAAC;AACpG,OAAO,EAAE,aAAa,EAAE,MAAM,sDAAsD,CAAC;AAErF,OAAO,EACH,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,uBAAuB,EACtE,uBAAuB,EAC1B,MAAM,iBAAiB,CAAC;AAgBzB;;GAEG;AACH,qBAAa,mBAAmB;IAYhB,OAAO,CAAC,MAAM;IAX1B,OAAO,CAAC,EAAE,CAAmC;IAG7C,OAAO,CAAC,SAAS,CAAwE;IACzF,OAAO,CAAC,SAAS,CAAuB;IAExC;;;;OAIG;IACH,YAAoB,MAAM,EAAE,eAAe,EAAK;IAEhD;;;;;;;;;;;;;;OAcG;IACG,gBAAgB,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA4B3G;IAED;;;;;;;OAOG;IACG,6BAA6B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAmC3E;IAED;;;;;;;;;;;;;;OAcG;YACW,qBAAqB;IAoCnC;;;;;;;;;;OAUG;YACW,2BAA2B;IA4DzC;;;;;;;;;;OAUG;IACU,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,CAqD3F;IAED;;;;;;OAMG;YACW,WAAW;IA8BzB;;;;;;;;;;;OAWG;IACG,0BAA0B,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWxF;IAED;;;;;;;;;;;OAWG;IACG,4BAA4B,CAAC,EAC/B,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,SAAS,EACT,KAAK,GACR,EAAE;QACC,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,gBAAgB,CAAC;QAC5B,KAAK,EAAE,aAAa,CAAC;KACxB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAuEjC;IAED;;;;;;OAMG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,EAAE,CAwB9D;IAED;;;OAGG;IACG,WAAW,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzE;CACJ"}