@tempoxyz/id 0.0.0-stage → 0.0.1

package/dist/internal/Authorize.js

@@ -0,0 +1,330 @@
+/**
+ * Authorization requests that carry a key authorization. A first-party web app's page authorizes
+ * headlessly, within the headless ceiling. Any other app authorizes through a redirect, whose
+ * `/authorize` query carries the key to the approval page.
+ * @module
+ */
+import { Base64 } from 'ox';
+import { z } from 'zod';
+import * as Apps from './Apps.js';
+import * as ErrorResponse from './ErrorResponse.js';
+import * as KeyAuthorization from './KeyAuthorization.js';
+import * as Validation from './Validation.js';
+/** A headless request came from an origin that its redirect URI does not allow. */
+export class InvalidOriginError extends ErrorResponse.define('invalid_origin') {
+    name = 'Authorize.InvalidOriginError';
+}
+/** The request names no registered app or redirect URI, or the app may not authorize headlessly. */
+export class RejectedError extends ErrorResponse.define('rejected') {
+    name = 'Authorize.RejectedError';
+    constructor(options = {}) {
+        super({
+            error_description: options.description ??
+                "Authorization request rejected. Check `client_id`, `redirect_uri`, and `scope` against the app's registration.",
+        });
+    }
+}
+/** Zod schemas for headless authorization requests and their responses. */
+export var schema;
+(function (schema) {
+    /** The tokens that a public app receives. */
+    schema.tokens = z
+        .object({
+        access_token: z.string().meta({
+            description: "The access token, a JWT that Tempo ID signs. APIs verify it against Tempo ID's JSON Web Key Set.",
+            examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyIn0.c2lnbmF0dXJl'],
+        }),
+        expires_in: z.number().meta({
+            description: 'Seconds until the access token expires.',
+            examples: [300],
+        }),
+        id_token: z
+            .string()
+            .optional()
+            .meta({
+            description: 'The OIDC ID token, a JWT about the user. Absent when the request did not ask for the `openid` scope.',
+            examples: ['eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJhcHAifQ.c2lnbmF0dXJl'],
+        }),
+        refresh_token: z
+            .string()
+            .optional()
+            .meta({
+            description: 'The refresh token, which the app redeems at `/oauth2/token` for new tokens. Absent without the `offline_access` scope.',
+            examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+        }),
+        token_type: z.string().meta({
+            description: 'The type of the access token (RFC 6749 §7.1).',
+            examples: ['Bearer'],
+        }),
+    })
+        .meta({ description: 'OAuth tokens for a public app.', id: 'Tokens' });
+    /** A message whose EIP-191 hash becomes a key authorization's witness. */
+    schema.challenge = z
+        .string()
+        .min(1)
+        .max(1024)
+        .optional()
+        .meta({
+        description: "A message, such as a sign-in challenge from the app's backend, whose EIP-191 hash becomes the key authorization's `witness` (TIP-1053). Requires `key_authorization`, and the app's `tempo-id:sign` scope.",
+        examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
+    });
+    /** An app's headless authorization request. */
+    schema.request = z
+        .object({
+        challenge: schema.challenge,
+        client_id: z
+            .string()
+            .min(1)
+            .max(255)
+            .meta({
+            description: "The app's client ID.",
+            examples: ['Qk3vT9xZbLmN2pRw8YcHjF6sDaE4uGtK'],
+        }),
+        code_challenge: z
+            .string()
+            .regex(/^[\w-]{43}$/)
+            .optional()
+            .meta({
+            description: "The S256 PKCE challenge of a verifier that the app's backend holds (RFC 7636). With one, the app receives a code, and without one, a public app receives tokens.",
+            examples: ['E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'],
+        }),
+        key_authorization: KeyAuthorization.schema.request,
+        // Schemes that run script or read files are refused.
+        redirect_uri: z
+            .url({
+            protocol: /^(?!(?:blob|data|file|javascript|vbscript)$)[a-z][a-z\d+.-]*$/,
+        })
+            .meta({
+            description: 'A registered redirect URI of a web app, whose origin the page calls from.',
+            examples: ['https://app.example.com/callback'],
+        }),
+        scope: z
+            .string()
+            .regex(/^[\w:.-]+( [\w:.-]+)*$/)
+            .max(256)
+            .optional()
+            .meta({
+            description: 'Space-separated OAuth scopes. Defaults to `openid`.',
+            examples: ['openid email offline_access'],
+        }),
+        skip_upgrade: z
+            .boolean()
+            .optional()
+            .meta({
+            description: "Whether a wallet.tempo passkey's account that waits for its upgrade on the key's chain, where accounts are configurable, signs the key as the passkey's own account, in place of `upgrade_required`. It applies when a passkey signs in the same request, through a sign-in with key signature or `passkey`. The response then holds `upgrade_available`. The key stops working on that chain once the account upgrades, unless `POST /v1/account/upgrade` registers it first. Defaults to `false`.",
+            examples: [true],
+        }),
+        state: z
+            .string()
+            .min(1)
+            .max(256)
+            .optional()
+            .meta({
+            description: 'An opaque value that the response returns unchanged, to bind it to the request (RFC 6749 §4.1.1).',
+            examples: ['af0ifjsldkj'],
+        }),
+    })
+        .refine((request) => !request.challenge || request.key_authorization, {
+        message: 'A challenge requires `key_authorization`, whose witness binds it',
+        path: ['challenge'],
+    })
+        // The key carries the challenge as its witness, so the owner's signature binds it.
+        .transform((request) => request.key_authorization
+        ? {
+            ...request,
+            key_authorization: KeyAuthorization.bind(request.key_authorization, { challenge: request.challenge }),
+        }
+        : request)
+        .meta({
+        description: "An app's headless authorization request.",
+        id: 'AuthorizationRequest',
+    });
+    /** The key of a redirect's `/authorize` query, with its `challenge` bound as the witness. */
+    schema.redirect = z
+        .object({ challenge: schema.challenge, key_authorization: KeyAuthorization.schema.request })
+        .refine((request) => !request.challenge || request.key_authorization, {
+        message: 'A challenge requires `key_authorization`, whose witness binds it',
+        path: ['challenge'],
+    })
+        .transform((request) => request.key_authorization
+        ? KeyAuthorization.bind(request.key_authorization, {
+            challenge: request.challenge,
+        })
+        : undefined);
+    /** What a headless authorization returns: a code or tokens, with any signed key. */
+    schema.response = z
+        .object({
+        account: KeyAuthorization.schema.account.optional(),
+        code: z
+            .string()
+            .optional()
+            .meta({
+            description: "The authorization code, when the request sent a `code_challenge`. The app's backend redeems it at `/oauth2/token`.",
+            examples: ['Vb7mQ2xLkP9sTzR4'],
+        }),
+        key_authorization: KeyAuthorization.schema.rpc.optional(),
+        state: z
+            .string()
+            .optional()
+            .meta({
+            description: "The request's `state`, unchanged. Absent when the request sent none.",
+            examples: ['af0ifjsldkj'],
+        }),
+        tokens: schema.tokens.optional().meta({
+            description: 'The tokens, when the request sent no `code_challenge`.',
+        }),
+        upgrade_available: z.literal(true).optional().meta({
+            description: "Present when `skip_upgrade` signed the key as a wallet.tempo passkey's own account, whose upgrade waits on the key's chain. `POST /v1/account/upgrade` with the key registers it and upgrades the account.",
+        }),
+    })
+        .meta({
+        description: 'An authorization: a code or tokens, with the signed key authorization when the request asks for one.',
+        id: 'Authorization',
+    });
+})(schema || (schema = {}));
+/**
+ * Returns why Tempo ID refuses a headless `request`, or `undefined`. The request must meet each rule:
+ *
+ * - The app is a registered first-party web app, and its page calls from the redirect URI's origin.
+ * - A key comes from an app without a client secret, and fits the headless ceiling. A challenge
+ *   needs `tempo-id:sign`.
+ */
+export function check(request, options) {
+    const { app, origin } = options;
+    if (!app || !app.redirectUris.includes(request.redirect_uri))
+        return new RejectedError();
+    // A public app proves nothing about its caller, so a program that impersonates it receives what
+    // the response carries. Only first-party apps authorize headlessly. A third-party app's code goes
+    // to its redirect URI, after the user approves the request.
+    if (!app.firstParty)
+        return new RejectedError({
+            description: 'Headless authorization refused: the app is not a first-party app. Send the user to `/oauth2/authorize`, and receive the code at the redirect URI.',
+        });
+    // A native app's request proves no app, since any program can send one, with or without its
+    // redirect URI's `Origin`. Its code goes to its redirect URI, through an authentication sheet.
+    if (app.type === 'native')
+        return new RejectedError({
+            description: "Headless authorization refused: a native app's request does not prove which app sends it. Open `/oauth2/authorize` in an authentication sheet, and receive the code at the redirect URI.",
+        });
+    // A browser sets `Origin` itself, so a page calls from its redirect URI's origin.
+    const redirectUri = new URL(request.redirect_uri);
+    if (origin !== redirectUri.origin)
+        return new InvalidOriginError({
+            error_description: `Invalid \`Origin\`: ${origin ?? 'none'}. Requests for this redirect URI must come from ${redirectUri.origin}.`,
+            field: 'Origin',
+            meta: { expected: redirectUri.origin, ...(origin ? { origin } : {}) },
+        });
+    const key = request.key_authorization;
+    if (!key)
+        return undefined;
+    // A confidential app proves itself only with its secret, which a page never holds, and the code
+    // redemption that checks it returns no key.
+    if (app.secret)
+        return new RejectedError({
+            description: 'Key authorization refused: the app holds a client secret, which a headless request does not prove. Authorize the key through a redirect or the device grant.',
+        });
+    return (KeyAuthorization.checkHeadless(key, { sign: app.sign }) ??
+        KeyAuthorization.checkChallenge({ app, clientId: request.client_id, key }));
+}
+(function (check) {
+    /** The refusals `check` returns. Its return type admits no other. */
+    check.errors = [
+        ...KeyAuthorization.checkHeadless.errors,
+        ...KeyAuthorization.checkChallenge.errors,
+        InvalidOriginError,
+        RejectedError,
+    ];
+})(check || (check = {}));
+/**
+ * Returns why Tempo ID refuses `key` in a redirect's authorization request, or `undefined`. The
+ * approval page shows the key, so the headless ceiling does not apply. The request needs a PKCE
+ * challenge, whose verifier receives the key.
+ */
+export function checkKey(options) {
+    const { app, clientId, codeChallenge, key, query } = options;
+    if (!codeChallenge)
+        return new RejectedError({
+            description: 'Key authorization refused: the request names no `code_challenge`, whose verifier receives the key. Send an S256 `code_challenge`.',
+        });
+    // `key` already holds the defaults, so the check reads the key as the query carries it.
+    const explicit = Apps.thirdParty(clientId)
+        ? KeyAuthorization.checkExplicit(decode(query.get('key_authorization') ?? ''))
+        : undefined;
+    return (explicit ??
+        KeyAuthorization.check(key) ??
+        KeyAuthorization.checkChallenge({ app, clientId, key }));
+}
+(function (checkKey) {
+    /** The refusals `checkKey` returns. Its return type admits no other. */
+    checkKey.errors = [
+        ...KeyAuthorization.check.errors,
+        ...KeyAuthorization.checkExplicit.errors,
+        ...KeyAuthorization.checkChallenge.errors,
+        RejectedError,
+    ];
+})(checkKey || (checkKey = {}));
+/**
+ * Returns the key of a redirect's `query`, with its `challenge` bound as the witness, or `undefined`
+ * without one. Returns `Validation.InvalidFieldError` for an invalid key or a repeated parameter, so
+ * a page cannot show one value and approve another.
+ */
+export function fromQuery(query) {
+    const repeated = keyParameters.find((name) => query.getAll(name).length > 1);
+    if (repeated)
+        return new Validation.InvalidFieldError({
+            issues: [
+                {
+                    message: 'Repeated parameter. Send it once',
+                    path: [repeated],
+                },
+            ],
+        });
+    const encoded = query.get('key_authorization');
+    const parsed = schema.redirect.safeParse({
+        challenge: query.get('challenge') ?? undefined,
+        key_authorization: encoded === null ? undefined : decode(encoded),
+    });
+    if (!parsed.success)
+        return new Validation.InvalidFieldError({ issues: parsed.error.issues });
+    return parsed.data;
+}
+/**
+ * Returns `parameters` with `consent` added to `prompt` when they carry `key_authorization`, so the
+ * approval page shows the key. A first-party app's key without an expiry gains the default, so
+ * approval signs the expiry that the page shows.
+ */
+export function prepare(parameters) {
+    if (!parameters.has('key_authorization'))
+        return parameters;
+    const prepared = new URLSearchParams(parameters);
+    const prompt = new Set((prepared.get('prompt') ?? '').split(' ').filter(Boolean));
+    prompt.add('consent');
+    prepared.set('prompt', [...prompt].join(' '));
+    // A repeated key stays as it is, so the page refuses it.
+    const [encoded, ...rest] = prepared.getAll('key_authorization');
+    const key = encoded && !rest.length ? decode(encoded) : undefined;
+    if (!Apps.thirdParty(prepared.get('client_id') ?? '') &&
+        typeof key === 'object' &&
+        key !== null &&
+        !Array.isArray(key) &&
+        !('expiry' in key))
+        prepared.set('key_authorization', Base64.fromString(JSON.stringify({
+            ...key,
+            expiry: Math.floor(Date.now() / 1000) + KeyAuthorization.lifetime,
+        }), base64url));
+    return prepared;
+}
+/** Unpadded URL-safe Base64, as the client encodes `key_authorization`. */
+const base64url = { pad: false, url: true };
+/** The query parameters that carry a redirect's key. */
+const keyParameters = ['challenge', 'key_authorization'];
+/** Decodes base64url JSON, or returns `null`, which fails validation. */
+function decode(value) {
+    try {
+        return JSON.parse(Base64.toString(value));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=Authorize.js.map

package/dist/internal/Authorize.js.map

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

package/dist/internal/Cache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * An isolate's cache of configuration reads, such as an app's realms. It holds no user data, and a
+ * change that another process writes applies within its TTL.
+ * @module
+ */
+import type * as Timing from './Timing.js';
+/** A cache that {@link create} returns. */
+export type Cache = ReturnType<typeof create>;
+/**
+ * Creates a cache whose entries expire `ttl` milliseconds after their load settles. It stores only
+ * settled values, since another request cannot wait on a load's I/O. Keys can come from requests,
+ * so it holds at most `max` entries, and no key over 256 characters.
+ */
+export declare function create(options: create.Options): {
+    /**
+     * Returns the value of `key`, and loads it with `load` without a live entry. A rejected load, or
+     * a value that `keep` rejects, stores no entry.
+     */
+    get<value>(load: () => Promise<value>, key: Key, options?: read.Options<value>): Promise<value>;
+};
+export declare namespace create {
+    type Options = {
+        /** The most entries that the cache holds. Defaults to 1,000. */
+        max?: number | undefined;
+        /** Milliseconds that each entry lives. 0 turns the cache off. */
+        ttl: number;
+    };
+}
+/**
+ * Returns the value of `key` from the request's cache, as {@link create}'s `get` does. Without a
+ * cache on `c`, such as in the CLI, it calls `load`.
+ *
+ * ```ts
+ * Cache.read(c, () => Realm.forApp(db, { clientId }), ['realm.forApp', clientId])
+ * ```
+ */
+export declare function read<value>(c: read.Context, load: () => Promise<value>, key: Key, options?: read.Options<value>): Promise<value>;
+export declare namespace read {
+    /** A context with the request's timing, and its cache once `IsolateCache.middleware` ran. */
+    type Context = Timing.measure.Context & {
+        /** The request's variables. */
+        var: {
+            /** The isolate's cache. Absent, each read loads. */
+            cache?: Cache | undefined;
+        };
+    };
+    type Options<value> = {
+        /** Whether to store a loaded value. Defaults to storing every value. */
+        keep?: ((value: value) => boolean) | undefined;
+        /** A shorter lifetime for this entry, in milliseconds. Defaults to the cache's own. */
+        ttl?: number | undefined;
+    };
+}
+/** An entry's key: the read's name, unique across modules, then each input to the read. */
+export type Key = readonly [name: string, ...inputs: readonly string[]];
+//# sourceMappingURL=Cache.d.ts.map

package/dist/internal/Cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../src/internal/Cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAE1C,2CAA2C;AAC3C,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAA;AAE7C;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO;IAO1C;;;OAGG;IACG,GAAG,CAAC,KAAK,QACP,MAAM,OAAO,CAAC,KAAK,CAAC,OACrB,GAAG,YACC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAC3B,OAAO,CAAC,KAAK,CAAC;EA+BpB;AAED,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,KAAK,OAAO,GAAG;QACb,gEAAgE;QAChE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;QACxB,iEAAiE;QACjE,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAC9B,CAAC,EAAE,IAAI,CAAC,OAAO,EACf,IAAI,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,EAC1B,GAAG,EAAE,GAAG,EACR,OAAO,GAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAM,GAChC,OAAO,CAAC,KAAK,CAAC,CAIhB;AAED,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,6FAA6F;IAC7F,KAAK,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,GAAG;QACtC,+BAA+B;QAC/B,GAAG,EAAE;YACH,oDAAoD;YACpD,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;SAC1B,CAAA;KACF,CAAA;IAED,KAAK,OAAO,CAAC,KAAK,IAAI;QACpB,wEAAwE;QACxE,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,GAAG,SAAS,CAAA;QAC9C,uFAAuF;QACvF,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KACzB,CAAA;CACF;AAED,2FAA2F;AAC3F,MAAM,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA"}

package/dist/internal/Cache.js

@@ -0,0 +1,65 @@
+/**
+ * Creates a cache whose entries expire `ttl` milliseconds after their load settles. It stores only
+ * settled values, since another request cannot wait on a load's I/O. Keys can come from requests,
+ * so it holds at most `max` entries, and no key over 256 characters.
+ */
+export function create(options) {
+    const { max = 1_000, ttl } = options;
+    const entries = new Map();
+    // Each load takes the next number, so a load that settles late never replaces a newer one's value.
+    let loads = 0;
+    return {
+        /**
+         * Returns the value of `key`, and loads it with `load` without a live entry. A rejected load, or
+         * a value that `keep` rejects, stores no entry.
+         */
+        async get(load, key, options = {}) {
+            const { keep = () => true } = options;
+            const lifetime = Math.min(options.ttl ?? ttl, ttl);
+            // JSON keeps each part apart, whatever characters it holds.
+            const name = JSON.stringify(key);
+            if (lifetime <= 0 || name.length > 256)
+                return await load();
+            const cached = entries.get(name);
+            // `Date.now()` advances at I/O, so it reads the time of the request's latest I/O.
+            if (cached && cached.expires > Date.now())
+                return cached.value;
+            const number = ++loads;
+            const value = await load();
+            if (!keep(value))
+                return value;
+            const current = entries.get(name);
+            if (current && current.load > number)
+                return value;
+            const now = Date.now();
+            entries.delete(name);
+            if (entries.size >= max)
+                for (const [other, entry] of entries)
+                    if (entry.expires <= now)
+                        entries.delete(other);
+            if (entries.size >= max) {
+                // A `Map` iterates in insertion order, so its first key is the oldest entry.
+                const oldest = entries.keys().next().value;
+                if (oldest !== undefined)
+                    entries.delete(oldest);
+            }
+            entries.set(name, { expires: now + lifetime, load: number, value });
+            return value;
+        },
+    };
+}
+/**
+ * Returns the value of `key` from the request's cache, as {@link create}'s `get` does. Without a
+ * cache on `c`, such as in the CLI, it calls `load`.
+ *
+ * ```ts
+ * Cache.read(c, () => Realm.forApp(db, { clientId }), ['realm.forApp', clientId])
+ * ```
+ */
+export async function read(c, load, key, options = {}) {
+    const cache = c.var.cache;
+    if (!cache)
+        return await load();
+    return await cache.get(load, key, options);
+}
+//# sourceMappingURL=Cache.js.map

package/dist/internal/Cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.js","sourceRoot":"","sources":["../../src/internal/Cache.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,OAAuB;IAC5C,MAAM,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,OAAO,CAAA;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAA;IACxC,mGAAmG;IACnG,IAAI,KAAK,GAAG,CAAC,CAAA;IAEb,OAAO;QACL;;;WAGG;QACH,KAAK,CAAC,GAAG,CACP,IAA0B,EAC1B,GAAQ,EACR,OAAO,GAAwB,EAAE;YAEjC,MAAM,EAAE,IAAI,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,OAAO,CAAA;YACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,CAAA;YAClD,4DAA4D;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;YAChC,IAAI,QAAQ,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,GAAG;gBAAE,OAAO,MAAM,IAAI,EAAE,CAAA;YAE3D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YAChC,kFAAkF;YAClF,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE;gBAAE,OAAO,MAAM,CAAC,KAAc,CAAA;YAEvE,MAAM,MAAM,GAAG,EAAE,KAAK,CAAA;YACtB,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAA;YAC1B,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YACjC,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,MAAM;gBAAE,OAAO,KAAK,CAAA;YAElD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YACtB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACpB,IAAI,OAAO,CAAC,IAAI,IAAI,GAAG;gBACrB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,OAAO;oBAClC,IAAI,KAAK,CAAC,OAAO,IAAI,GAAG;wBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACnD,IAAI,OAAO,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;gBACxB,6EAA6E;gBAC7E,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAA;gBAC1C,IAAI,MAAM,KAAK,SAAS;oBAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAClD,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,GAAG,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;YACnE,OAAO,KAAK,CAAA;QACd,CAAC;KACF,CAAA;AACH,CAAC;AAWD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,CAAe,EACf,IAA0B,EAC1B,GAAQ,EACR,OAAO,GAAwB,EAAE;IAEjC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAA;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,MAAM,IAAI,EAAE,CAAA;IAC/B,OAAO,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;AAC5C,CAAC"}