@run402/functions 2.9.0 → 3.1.0

package/dist/auth/errors.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Structured errors thrown by the `auth.*` namespace.
+ *
+ * The platform error envelope (`R402_AUTH_*` codes) is the wire shape;
+ * these Error subclasses are how user code catches them in TypeScript.
+ *
+ * The docs say "do not catch auth errors" — the platform's response-shape
+ * decision (303 redirect for HTML, 401/403 envelope for JSON) already does
+ * the right thing. But framework code, middleware, and test harnesses
+ * occasionally need typed catches; that's what these classes are for.
+ */
+export type Run402AuthCode = "R402_AUTH_REQUIRED" | "R402_AUTH_INSUFFICIENT_ROLE" | "R402_AUTH_INSUFFICIENT_MEMBERSHIP" | "R402_AUTH_FRESHNESS_REQUIRED" | "R402_AUTH_PRERENDERED" | "R402_AUTH_FETCH_ABSOLUTE_URL" | "R402_AUTH_UNKNOWN_EXPORT" | "R402_AUTH_SESSION_BRIDGE_UNVERIFIED" | "R402_AUTH_IDENTITY_LINK_CONFLICT" | "R402_AUTH_UNKNOWN_IDENTITY" | "R402_AUTH_TENANT_SUFFIX_REQUIRED" | "R402_AUTH_RETURN_TO_INVALID" | "R402_AUTH_REDUNDANT_USER_FILTER" | "R402_AUTH_INVALID_CREDENTIALS" | "R402_AUTH_TENANT_SUBJECT_INVALID" | "R402_AUTH_UNTRUSTED_CONTEXT";
+export declare class Run402AuthError extends Error {
+    readonly code: Run402AuthCode;
+    readonly status: number;
+    readonly details: Record<string, unknown>;
+    readonly suggestedFix?: string;
+    readonly docs?: string;
+    constructor(opts: {
+        code: Run402AuthCode;
+        status: number;
+        message: string;
+        details?: Record<string, unknown>;
+        suggestedFix?: string;
+        docs?: string;
+    });
+}
+/** Subclass identifying the "anonymous on a protected route" case. The
+ *  middleware decides whether to surface this as a 303 (HTML) or a 401
+ *  envelope (JSON); user code never needs to make that choice. */
+export declare class AuthRequiredError extends Run402AuthError {
+    constructor(opts?: {
+        returnTo?: string;
+    });
+}
+export declare class InsufficientRoleError extends Run402AuthError {
+    readonly requiredRole: string;
+    constructor(requiredRole: string);
+}
+export declare class InsufficientMembershipError extends Run402AuthError {
+    readonly requiredMembership: string;
+    constructor(requiredMembership: string);
+}
+export declare class FreshnessRequiredError extends Run402AuthError {
+    readonly maxAge: string;
+    readonly amr: string[];
+    constructor(opts: {
+        maxAge: string;
+        amr: string[];
+        returnTo?: string;
+    });
+}
+export declare class FetchAbsoluteUrlError extends Run402AuthError {
+    constructor(opts: {
+        attempted: string;
+        reason: string;
+    });
+}
+export declare class PrerenderedError extends Run402AuthError {
+    constructor(opts: {
+        sdkFunction: string;
+    });
+}
+export declare class UnknownExportError extends Run402AuthError {
+    readonly attemptedName: string;
+    readonly canonicalName: string;
+    constructor(opts: {
+        attemptedName: string;
+        canonicalName: string;
+    });
+}
+export declare class SessionBridgeUnverifiedError extends Run402AuthError {
+    constructor(opts: {
+        reason: string;
+    });
+}
+export declare class IdentityLinkConflictError extends Run402AuthError {
+    constructor(opts: {
+        provider: string;
+        subject: string;
+    });
+}
+export declare class UnknownIdentityError extends Run402AuthError {
+    constructor(opts: {
+        provider: string;
+        subject: string;
+    });
+}
+/** The canonical "your own credential check failed" error. Thrown via the
+ *  `auth.invalidCredentials()` FUNCTION (not `new auth.InvalidCredentialsError()`)
+ *  per D9 — agents fumble the constructor+import; `throw auth.invalidCredentials()`
+ *  is one call and renders the canonical `R402_AUTH_INVALID_CREDENTIALS` envelope
+ *  (distinct from `R402_AUTH_MAGIC_LINK_INVALID`). */
+export declare class InvalidCredentialsError extends Run402AuthError {
+    constructor();
+}
+/** Rejects a tenant-assertion mint whose `user` lacks a stable `id` (e.g. a
+ *  bare email). The `fix` shows the required `{ tenant, user: { id, email, ... },
+ *  method }` shape. SDK-side fast-feedback twin of the gateway's
+ *  `R402_AUTH_TENANT_SUBJECT_INVALID` envelope. */
+export declare class TenantSubjectInvalidError extends Run402AuthError {
+    constructor(opts: {
+        reason: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts.map

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

package/dist/auth/errors.js

@@ -0,0 +1,205 @@
+/**
+ * Structured errors thrown by the `auth.*` namespace.
+ *
+ * The platform error envelope (`R402_AUTH_*` codes) is the wire shape;
+ * these Error subclasses are how user code catches them in TypeScript.
+ *
+ * The docs say "do not catch auth errors" — the platform's response-shape
+ * decision (303 redirect for HTML, 401/403 envelope for JSON) already does
+ * the right thing. But framework code, middleware, and test harnesses
+ * occasionally need typed catches; that's what these classes are for.
+ */
+export class Run402AuthError extends Error {
+    code;
+    status;
+    details;
+    suggestedFix;
+    docs;
+    constructor(opts) {
+        super(opts.message);
+        this.name = "Run402AuthError";
+        this.code = opts.code;
+        this.status = opts.status;
+        this.details = opts.details ?? {};
+        if (opts.suggestedFix)
+            this.suggestedFix = opts.suggestedFix;
+        if (opts.docs)
+            this.docs = opts.docs;
+    }
+}
+/** Subclass identifying the "anonymous on a protected route" case. The
+ *  middleware decides whether to surface this as a 303 (HTML) or a 401
+ *  envelope (JSON); user code never needs to make that choice. */
+export class AuthRequiredError extends Run402AuthError {
+    constructor(opts = {}) {
+        super({
+            code: "R402_AUTH_REQUIRED",
+            status: 401,
+            message: "Authentication required.",
+            details: opts.returnTo ? { returnTo: opts.returnTo } : {},
+            suggestedFix: "Use: const user = await auth.requireUser()",
+            docs: "https://run402.com/errors/#R402_AUTH_REQUIRED",
+        });
+        this.name = "AuthRequiredError";
+    }
+}
+export class InsufficientRoleError extends Run402AuthError {
+    requiredRole;
+    constructor(requiredRole) {
+        super({
+            code: "R402_AUTH_INSUFFICIENT_ROLE",
+            status: 403,
+            message: `Authenticated user lacks required role: ${requiredRole}.`,
+            details: { required_role: requiredRole },
+        });
+        this.name = "InsufficientRoleError";
+        this.requiredRole = requiredRole;
+    }
+}
+export class InsufficientMembershipError extends Run402AuthError {
+    requiredMembership;
+    constructor(requiredMembership) {
+        super({
+            code: "R402_AUTH_INSUFFICIENT_MEMBERSHIP",
+            status: 403,
+            message: `Authenticated user lacks required membership: ${requiredMembership}.`,
+            details: { required_membership: requiredMembership },
+        });
+        this.name = "InsufficientMembershipError";
+        this.requiredMembership = requiredMembership;
+    }
+}
+export class FreshnessRequiredError extends Run402AuthError {
+    maxAge;
+    amr;
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_FRESHNESS_REQUIRED",
+            status: 401,
+            message: `Fresh re-auth proof required within ${opts.maxAge} matching one of: ${opts.amr.join(", ")}.`,
+            details: { max_age: opts.maxAge, amr: opts.amr, returnTo: opts.returnTo ?? null },
+        });
+        this.name = "FreshnessRequiredError";
+        this.maxAge = opts.maxAge;
+        this.amr = opts.amr;
+    }
+}
+export class FetchAbsoluteUrlError extends Run402AuthError {
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_FETCH_ABSOLUTE_URL",
+            status: 500,
+            message: `auth.fetch refused URL "${opts.attempted}": ${opts.reason}`,
+            details: { attempted_url: opts.attempted, reason: opts.reason },
+            suggestedFix: "auth.fetch accepts only same-origin paths. Cross-origin calls belong in your own service module.",
+            docs: "https://run402.com/errors/#R402_AUTH_FETCH_ABSOLUTE_URL",
+        });
+        this.name = "FetchAbsoluteUrlError";
+    }
+}
+export class PrerenderedError extends Run402AuthError {
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_PRERENDERED",
+            status: 500,
+            message: `${opts.sdkFunction} cannot run in prerendered context.`,
+            details: { sdk_function: opts.sdkFunction },
+            suggestedFix: "Set `export const prerender = false` or use a server island.",
+            docs: "https://run402.com/errors/#R402_AUTH_PRERENDERED",
+        });
+        this.name = "PrerenderedError";
+    }
+}
+export class UnknownExportError extends Run402AuthError {
+    attemptedName;
+    canonicalName;
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_UNKNOWN_EXPORT",
+            status: 500,
+            message: `Unknown SDK export: ${opts.attemptedName}. Use ${opts.canonicalName} instead.`,
+            details: {
+                attempted_name: opts.attemptedName,
+                canonical_name: opts.canonicalName,
+                import_line: 'import { auth } from "@run402/functions"',
+            },
+            suggestedFix: `Use: ${opts.canonicalName}`,
+            docs: "https://run402.com/errors/#R402_AUTH_UNKNOWN_EXPORT",
+        });
+        this.name = "UnknownExportError";
+        this.attemptedName = opts.attemptedName;
+        this.canonicalName = opts.canonicalName;
+    }
+}
+export class SessionBridgeUnverifiedError extends Run402AuthError {
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_SESSION_BRIDGE_UNVERIFIED",
+            status: 401,
+            message: `Session bridge refused unverified proof: ${opts.reason}`,
+            details: { reason: opts.reason },
+            suggestedFix: "Pass a verifiable proof to auth.sessions.createResponseFromIdentity({provider, subject, proof, amr, createUser?}).",
+            docs: "https://run402.com/errors/#R402_AUTH_SESSION_BRIDGE_UNVERIFIED",
+        });
+        this.name = "SessionBridgeUnverifiedError";
+    }
+}
+export class IdentityLinkConflictError extends Run402AuthError {
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_IDENTITY_LINK_CONFLICT",
+            status: 409,
+            message: `Identity (${opts.provider}, ${opts.subject}) is already linked to another user.`,
+            details: { provider: opts.provider, subject: opts.subject },
+        });
+        this.name = "IdentityLinkConflictError";
+    }
+}
+export class UnknownIdentityError extends Run402AuthError {
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_UNKNOWN_IDENTITY",
+            status: 401,
+            message: `Identity (${opts.provider}, ${opts.subject}) not found.`,
+            details: { provider: opts.provider, subject: opts.subject },
+            suggestedFix: "Pass `createUser: true` to auth.sessions.createResponseFromIdentity if first-sign-in should create the user.",
+        });
+        this.name = "UnknownIdentityError";
+    }
+}
+/** The canonical "your own credential check failed" error. Thrown via the
+ *  `auth.invalidCredentials()` FUNCTION (not `new auth.InvalidCredentialsError()`)
+ *  per D9 — agents fumble the constructor+import; `throw auth.invalidCredentials()`
+ *  is one call and renders the canonical `R402_AUTH_INVALID_CREDENTIALS` envelope
+ *  (distinct from `R402_AUTH_MAGIC_LINK_INVALID`). */
+export class InvalidCredentialsError extends Run402AuthError {
+    constructor() {
+        super({
+            code: "R402_AUTH_INVALID_CREDENTIALS",
+            status: 401,
+            message: "Invalid credentials.",
+            details: {},
+            suggestedFix: 'After your own credential check fails, use: throw auth.invalidCredentials()',
+            docs: "https://run402.com/errors/#R402_AUTH_INVALID_CREDENTIALS",
+        });
+        this.name = "InvalidCredentialsError";
+    }
+}
+/** Rejects a tenant-assertion mint whose `user` lacks a stable `id` (e.g. a
+ *  bare email). The `fix` shows the required `{ tenant, user: { id, email, ... },
+ *  method }` shape. SDK-side fast-feedback twin of the gateway's
+ *  `R402_AUTH_TENANT_SUBJECT_INVALID` envelope. */
+export class TenantSubjectInvalidError extends Run402AuthError {
+    constructor(opts) {
+        super({
+            code: "R402_AUTH_TENANT_SUBJECT_INVALID",
+            status: 400,
+            message: `Tenant assertion subject invalid: ${opts.reason}`,
+            details: { reason: opts.reason },
+            suggestedFix: 'Pass a stable id: auth.sessions.createResponseFromTenantAssertion({ tenant, user: { id, email, emailVerified }, method: "password" })',
+            docs: "https://run402.com/errors/#R402_AUTH_TENANT_SUBJECT_INVALID",
+        });
+        this.name = "TenantSubjectInvalidError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/auth/errors.js.map

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

package/dist/auth/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `auth.*` — the sole server-side auth namespace.
+ *
+ * The single import line for any consumer:
+ *
+ *     import { auth } from "@run402/functions";
+ *
+ * Surface (deliberately small):
+ *
+ *     auth.user()                          → Actor | null
+ *     auth.requireUser()                   → Actor (throws / 303 otherwise)
+ *     auth.requireRole(role)               → { user, role }
+ *     auth.requireMembership(membership)   → { user, membership }
+ *     auth.requireFresh({ maxAge, amr? })  → void (throws / 303 otherwise)
+ *     auth.identities.link({ ... })        → void
+ *     auth.fetch(input, init?)             → Response (same-origin only)
+ *     auth.csrfToken()                     → string
+ *     auth.csrfField()                     → "<input type=hidden ...>"
+ *     auth.sessions.createResponseFromIdentity({ ... }) → Response
+ *     auth.sessions.createResponseFromTenantAssertion({ tenant, user, method }) → Response
+ *     auth.sessions.endResponse()          → Response
+ *     auth.invalidCredentials()            → InvalidCredentialsError (throw it)
+ *
+ * Behaviour notes baked into the helpers:
+ *   - Calling any helper taints the cache (the response now depends on
+ *     per-request actor state). The taint is monotonic — once set, the
+ *     SSR cache layer treats the response as non-cacheable until the
+ *     request completes.
+ *   - HTML-vs-JSON failure decisions are made by the gateway middleware
+ *     (303 redirect for HTML, 401/403 envelope for JSON). The SDK throws
+ *     a typed Error subclass; framework code OR the gateway translates.
+ *   - `requireRole` / `requireMembership` always read fresh server-side
+ *     grant data — no positive cache (matches D8 + the "instant revocation"
+ *     contract). For now we route via `getRole` which the gateway sets
+ *     at the routed-function envelope; once the v1.60 grants table lands,
+ *     gate helpers will JOIN against it inside the same request.
+ *   - `requireFresh` consults the per-method `amr_times` on the Actor —
+ *     a recent password proof does NOT satisfy `{amr: ["passkey"]}`.
+ *
+ * @see openspec/changes/auth-aware-ssr/specs/auth-sdk-namespace/spec.md
+ */
+import { InvalidCredentialsError } from "./errors.js";
+import type { Actor, CreateResponseFromIdentityOptions, CreateResponseFromTenantAssertionOptions, IdentityLinkOptions } from "./types.js";
+interface RequireFreshOptions {
+    /** Human-friendly window expression. Accepted forms: `"10m"`, `"1h"`,
+     *  `"5m30s"`, integer seconds (`"600"`). Anything that fails to parse
+     *  is treated as 0s (immediate freshness required). */
+    maxAge: string;
+    /** Names of AMR methods one of which must have been verified within
+     *  `maxAge`. When omitted, any flat `auth_time` proof within `maxAge`
+     *  satisfies. */
+    amr?: string[];
+}
+/** Header on the function's RETURNED Response that the gateway's routed-invoke
+ *  post-processor materializes into a host-bound `Set-Cookie` — AFTER it
+ *  checks the INVOKED function's declared `auth.sessionMint` capability
+ *  (server-side; service-key presence is NOT sufficient). The gateway always
+ *  strips this header before the client sees it. Kept in sync with the
+ *  gateway constant of the same name. */
+export declare const MINT_DIRECTIVE_HEADER = "x-run402-mint-directive";
+interface AuthNamespace {
+    user(): Promise<Actor | null>;
+    requireUser(): Promise<Actor>;
+    requireRole<const R extends string>(role: R): Promise<{
+        user: Actor;
+        role: R;
+    }>;
+    requireMembership<const M extends string>(membership: M): Promise<{
+        user: Actor;
+        membership: M;
+    }>;
+    requireFresh(opts: RequireFreshOptions): Promise<void>;
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    csrfToken(): string;
+    csrfField(): string;
+    /** Canonical invalid-credentials failure for the tenant-owned credential
+     *  case. A function (not a constructor): `throw auth.invalidCredentials()`. */
+    invalidCredentials(): InvalidCredentialsError;
+    identities: {
+        link(opts: IdentityLinkOptions): Promise<void>;
+    };
+    sessions: {
+        createResponseFromIdentity(opts: CreateResponseFromIdentityOptions): Promise<Response>;
+        createResponseFromTenantAssertion(opts: CreateResponseFromTenantAssertionOptions): Promise<Response>;
+        endResponse(): Promise<Response>;
+    };
+}
+/** Hallucinated-name proxy. Property access for a name not in
+ *  `baseAuth` throws `R402_AUTH_UNKNOWN_EXPORT` with the canonical
+ *  replacement. Hot-path access (existing keys) returns the actual
+ *  helper — proxy overhead is one Reflect.has + Reflect.get. */
+export declare const auth: AuthNamespace;
+/** Throwing-sentinel exports for the top hallucinated *bare* names.
+ *  ESM `import { getUser } from "@run402/functions"` can be intercepted
+ *  only by a real export — so we ship these as exported throwing
+ *  functions. They're marked `@deprecated` in the type JSDoc; the SDK
+ *  proxy + lint registry + `run402 doctor` scan all flag the import
+ *  before runtime if the user is running the tooling.
+ *
+ *  Excluded from public docs and AGENTS.md per the spec.
+ */
+/** @deprecated Use `auth.user()` or `auth.requireUser()`. */
+export declare function getSession(): never;
+/** @deprecated Use `auth.user()`. */
+export declare function currentUser(): never;
+/** @deprecated Use `auth.user()`. */
+export declare function getCurrentUser(): never;
+/** @deprecated Use `auth.user()`. */
+export declare function getServerSession(): never;
+export type { Actor, IdentityProof, TenantUser, CreateResponseFromTenantAssertionOptions, } from "./types.js";
+export { AuthRequiredError, InsufficientRoleError, InsufficientMembershipError, FreshnessRequiredError, FetchAbsoluteUrlError, PrerenderedError, UnknownExportError, SessionBridgeUnverifiedError, IdentityLinkConflictError, UnknownIdentityError, InvalidCredentialsError, TenantSubjectInvalidError, Run402AuthError, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAUH,OAAO,EAML,uBAAuB,EAIxB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,KAAK,EACL,iCAAiC,EACjC,wCAAwC,EACxC,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAsJpB,UAAU,mBAAmB;IAC3B;;2DAEuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;qBAEiB;IACjB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AA8JD;;;;;yCAKyC;AACzC,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AA2K/D,UAAU,aAAa;IACrB,IAAI,IAAI,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IAC9B,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,WAAW,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAChF,iBAAiB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EACtC,UAAU,EAAE,CAAC,GACZ,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,UAAU,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAC3C,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,SAAS,IAAI,MAAM,CAAC;IACpB,SAAS,IAAI,MAAM,CAAC;IACpB;mFAC+E;IAC/E,kBAAkB,IAAI,uBAAuB,CAAC;IAC9C,UAAU,EAAE;QACV,IAAI,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KAChD,CAAC;IACF,QAAQ,EAAE;QACR,0BAA0B,CAAC,IAAI,EAAE,iCAAiC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvF,iCAAiC,CAC/B,IAAI,EAAE,wCAAwC,GAC7C,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrB,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;KAClC,CAAC;CACH;AAoDD;;;gEAGgE;AAChE,eAAO,MAAM,IAAI,EAAE,aAiBjB,CAAC;AAEH;;;;;;;;GAQG;AAEH,6DAA6D;AAC7D,wBAAgB,UAAU,IAAI,KAAK,CAElC;AAED,qCAAqC;AACrC,wBAAgB,WAAW,IAAI,KAAK,CAEnC;AAED,qCAAqC;AACrC,wBAAgB,cAAc,IAAI,KAAK,CAEtC;AAED,qCAAqC;AACrC,wBAAgB,gBAAgB,IAAI,KAAK,CAKxC;AA8BD,YAAY,EACV,KAAK,EACL,aAAa,EACb,UAAU,EACV,wCAAwC,GACzC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,2BAA2B,EAC3B,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,yBAAyB,EACzB,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,GAChB,MAAM,aAAa,CAAC"}