@sudobility/shapeshyft_service 1.0.0

package/CLAUDE.md

@@ -0,0 +1,35 @@
+# shapeshyft_service
+
+> **Git policy — never auto-commit or auto-push.** Run `git commit`, `git push`,
+> or publish only when the user explicitly asks in that turn.
+
+Shared backend for `shapeshyft_api` and `shaperouter_api`: Drizzle table
+factories, idempotent DDL, Hono routers, auth and rate-limit middleware.
+Stateless LLM work (adapters, prompts, media, provider catalog) lives in
+`@sudobility/shapeshyft_engine`.
+
+## The seam
+
+The service never knows where a provider API key lives. The app passes a
+`ProviderCredentialResolver`:
+
+- `bindEndpoint` — endpoint create/update; returns the `provider` and
+  `llmKeyId` to persist, or a `{ status, message }` failure.
+- `resolve` — invoke and prompt-preview time; returns `provider`, `apiKey`,
+  `endpointUrl`, `timeoutMs`, or a failure.
+
+Optional `InvokeHooks`: `beforeInvoke` (after rate limiting; return a Response to
+stop) and `afterInvoke` (inside the usage_analytics transaction).
+
+## Rules
+
+- No `process.env`. Add a field to `ShapeshyftServiceConfig` instead.
+- No reference to `llm_api_keys`. The binding column is `llm_key_id`, nullable,
+  no FK here; apps add their own FK.
+- Relative imports carry `.js`.
+- Handler error messages and status codes are part of two products' public APIs.
+
+## Tests
+
+    bun run test      # unit, no DB
+    TEST_DATABASE_URL=postgresql://localhost:5432/shapeshyft_test bun run test:db

package/README.md

@@ -0,0 +1,17 @@
+# @sudobility/shapeshyft_service
+
+Shared tables, routes and middleware for ShapeShyft-style structured-output APIs.
+
+```ts
+const service = createShapeshyftService({
+  db,
+  tables,
+  keyPrefixes: { user: "shyft_", entity: "shyftent" },
+  encryption,
+  auth,
+  email,
+  credentials, // ProviderCredentialResolver: where provider API keys come from
+});
+
+app.route("/api/v1", service.buildRoutes({ mountAdmin }));
+```

package/dist/context.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Service configuration and the context every router closes over
+ */
+import type { RateLimitsConfig } from "@sudobility/ratelimit_service";
+import { createLLMProvider } from "@sudobility/shapeshyft_engine";
+import type { AuthAdapter, EmailSender, InvokeHooks, Logger, ProviderCredentialResolver, ServiceDb } from "./contracts.js";
+import type { Encryption } from "./lib/encryption.js";
+import { type ProjectApiKeys } from "./lib/api-key.js";
+import { type UserApiKeys } from "./lib/user-api-key.js";
+import { type EntityApiKeyFormat } from "./lib/entity-api-key.js";
+import { type UserApiKeyCache } from "./lib/user-api-key-cache.js";
+import { type EntityAccess } from "./lib/entity-helpers.js";
+import { type SubscriptionAccess } from "./middleware/subscription.js";
+import { type RateLimiting } from "./middleware/rateLimit.js";
+import { type EndpointBindingShapes, type EndpointSchemas } from "./schemas/index.js";
+import type { ServiceTables } from "./schema/tables.js";
+export interface ShapeshyftServiceConfig {
+    db: ServiceDb;
+    tables: ServiceTables;
+    /** e.g. `{ user: "shyft_", entity: "shyftent" }` -- entity has no trailing underscore */
+    keyPrefixes: {
+        user: string;
+        entity: string;
+    };
+    encryption: Encryption;
+    auth: AuthAdapter;
+    email: EmailSender;
+    credentials: ProviderCredentialResolver;
+    /** Extra zod fields validated on endpoint create/update. */
+    endpointBinding?: EndpointBindingShapes;
+    hooks?: InvokeHooks;
+    /** Absent: subscription lookups and invoke rate limiting are skipped. */
+    revenueCatApiKey?: string;
+    rateLimits?: RateLimitsConfig;
+    entitlementDisplayNames?: Record<string, string>;
+    /** Default: `console`. */
+    logger?: Logger;
+    /** Default: the engine's `createLLMProvider`. Tests inject a fake. */
+    createProvider?: typeof createLLMProvider;
+}
+export interface ServiceContext {
+    db: ServiceDb;
+    tables: ServiceTables;
+    auth: AuthAdapter;
+    email: EmailSender;
+    credentials: ProviderCredentialResolver;
+    hooks: InvokeHooks;
+    logger: Logger;
+    createProvider: typeof createLLMProvider;
+    revenueCatApiKey: string | undefined;
+    encryption: Encryption;
+    projectApiKeys: ProjectApiKeys;
+    userApiKeys: UserApiKeys;
+    userApiKeyCache: UserApiKeyCache;
+    entityApiKeyFormat: EntityApiKeyFormat;
+    entityAccess: EntityAccess;
+    subscription: SubscriptionAccess;
+    rateLimiting: RateLimiting;
+    schemas: EndpointSchemas;
+}
+export declare function buildContext(config: ShapeshyftServiceConfig): ServiceContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,MAAM,EACN,0BAA0B,EAC1B,SAAS,EACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,yFAAyF;IACzF,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,EAAE,0BAA0B,CAAC;IACxC,4DAA4D;IAC5D,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,iBAAiB,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,EAAE,0BAA0B,CAAC;IACxC,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,iBAAiB,CAAC;IACzC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,UAAU,EAAE,UAAU,CAAC;IACvB,cAAc,EAAE,cAAc,CAAC;IAC/B,WAAW,EAAE,WAAW,CAAC;IACzB,eAAe,EAAE,eAAe,CAAC;IACjC,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,kBAAkB,CAAC;IACjC,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,uBAAuB,GAAG,cAAc,CA2C5E"}

package/dist/context.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Service configuration and the context every router closes over
+ */
+import { createLLMProvider } from "@sudobility/shapeshyft_engine";
+import { createProjectApiKeys } from "./lib/api-key.js";
+import { createUserApiKeys } from "./lib/user-api-key.js";
+import { createEntityApiKeyFormat, } from "./lib/entity-api-key.js";
+import { createUserApiKeyCache, } from "./lib/user-api-key-cache.js";
+import { createEntityAccess } from "./lib/entity-helpers.js";
+import { createSubscriptionAccess, } from "./middleware/subscription.js";
+import { createRateLimiting, DEFAULT_ENTITLEMENT_DISPLAY_NAMES, DEFAULT_RATE_LIMITS_CONFIG, } from "./middleware/rateLimit.js";
+import { createEndpointSchemas, } from "./schemas/index.js";
+export function buildContext(config) {
+    const logger = config.logger ?? console;
+    const userApiKeys = createUserApiKeys({
+        prefix: config.keyPrefixes.user,
+        encryption: config.encryption,
+    });
+    return {
+        db: config.db,
+        tables: config.tables,
+        auth: config.auth,
+        email: config.email,
+        credentials: config.credentials,
+        hooks: config.hooks ?? {},
+        logger,
+        createProvider: config.createProvider ?? createLLMProvider,
+        revenueCatApiKey: config.revenueCatApiKey,
+        encryption: config.encryption,
+        projectApiKeys: createProjectApiKeys(config.encryption),
+        userApiKeys,
+        userApiKeyCache: createUserApiKeyCache({
+            db: config.db,
+            tables: config.tables,
+            hashUserApiKey: userApiKeys.hashUserApiKey,
+            logger,
+        }),
+        entityApiKeyFormat: createEntityApiKeyFormat(config.keyPrefixes.entity),
+        entityAccess: createEntityAccess({
+            db: config.db,
+            tables: config.tables,
+            entityKeyPrefix: config.keyPrefixes.entity,
+        }),
+        subscription: createSubscriptionAccess(config.revenueCatApiKey),
+        rateLimiting: createRateLimiting({
+            db: config.db,
+            rateLimitCounters: config.tables.rateLimitCounters,
+            revenueCatApiKey: config.revenueCatApiKey,
+            rateLimitsConfig: config.rateLimits ?? DEFAULT_RATE_LIMITS_CONFIG,
+            entitlementDisplayNames: config.entitlementDisplayNames ?? DEFAULT_ENTITLEMENT_DISPLAY_NAMES,
+        }),
+        schemas: createEndpointSchemas(config.endpointBinding),
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAUlE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAoB,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EACL,wBAAwB,GAEzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,qBAAqB,GAEtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAqB,MAAM,yBAAyB,CAAC;AAChF,OAAO,EACL,wBAAwB,GAEzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,kBAAkB,EAClB,iCAAiC,EACjC,0BAA0B,GAE3B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,qBAAqB,GAGtB,MAAM,oBAAoB,CAAC;AA8C5B,MAAM,UAAU,YAAY,CAAC,MAA+B;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC;IACxC,MAAM,WAAW,GAAG,iBAAiB,CAAC;QACpC,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;QACzB,MAAM;QACN,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,iBAAiB;QAC1D,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,cAAc,EAAE,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC;QACvD,WAAW;QACX,eAAe,EAAE,qBAAqB,CAAC;YACrC,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,cAAc,EAAE,WAAW,CAAC,cAAc;YAC1C,MAAM;SACP,CAAC;QACF,kBAAkB,EAAE,wBAAwB,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;QACvE,YAAY,EAAE,kBAAkB,CAAC;YAC/B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,eAAe,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM;SAC3C,CAAC;QACF,YAAY,EAAE,wBAAwB,CAAC,MAAM,CAAC,gBAAgB,CAAC;QAC/D,YAAY,EAAE,kBAAkB,CAAC;YAC/B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC,iBAAiB;YAClD,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,gBAAgB,EAAE,MAAM,CAAC,UAAU,IAAI,0BAA0B;YACjE,uBAAuB,EACrB,MAAM,CAAC,uBAAuB,IAAI,iCAAiC;SACtE,CAAC;QACF,OAAO,EAAE,qBAAqB,CAAC,MAAM,CAAC,eAAe,CAAC;KACvD,CAAC;AACJ,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview What an app supplies to shapeshyft_service
+ * @description The provider-credential seam, invoke hooks, and the adapters that
+ * replace module-level singletons (auth, email, logging).
+ */
+import type { Context } from "hono";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { DecodedIdToken } from "firebase-admin/auth";
+import type { getUserInfo, isAnonymousUser, isSiteAdmin } from "@sudobility/auth_service";
+import type { EndpointBase, LlmProvider } from "@sudobility/shapeshyft_engine/types";
+import type { ServiceTables } from "./schema/tables.js";
+/** The Drizzle database the app connects. Tables are passed separately. */
+export type ServiceDb = PostgresJsDatabase<any>;
+/** The `tx` handed to a `db.transaction` callback. */
+export type DbTransaction = Parameters<Parameters<ServiceDb["transaction"]>[0]>[0];
+export type EndpointRow = ServiceTables["endpoints"]["$inferSelect"];
+export type EntityRow = ServiceTables["entities"]["$inferSelect"];
+export type ProjectRow = ServiceTables["projects"]["$inferSelect"];
+/** An endpoint as the service's routes return it. */
+export interface EndpointRecord extends EndpointBase {
+    llm_key_id: string | null;
+    provider: LlmProvider | null;
+}
+/** A refusal. `message` is returned to the caller verbatim as `errorResponse(message)`. */
+export interface ResolverFailure {
+    ok: false;
+    status: 400 | 404 | 500 | 503;
+    message: string;
+}
+/** What to persist on an endpoint for its provider binding. */
+export interface EndpointBinding {
+    ok: true;
+    provider: LlmProvider;
+    /** ShapeShyft: the LlmApiKey UUID. Products without per-entity keys: null. */
+    llmKeyId: string | null;
+}
+/** A live credential for one call. `provider` is authoritative for the call. */
+export interface ResolvedCredential {
+    ok: true;
+    provider: LlmProvider;
+    apiKey?: string;
+    endpointUrl?: string;
+    timeoutMs?: number;
+}
+export interface ProviderCredentialResolver {
+    /**
+     * Endpoint create (no `current`) or update (`current` set). `body` is the
+     * validated request body, including the app's `endpointBinding` fields.
+     */
+    bindEndpoint(ctx: {
+        entityId: string;
+        body: Record<string, unknown>;
+        current?: EndpointRow;
+    }): Promise<EndpointBinding | ResolverFailure>;
+    /** Invoke and prompt-preview time. */
+    resolve(ctx: {
+        entityId: string;
+        endpoint: EndpointRow;
+    }): Promise<ResolvedCredential | ResolverFailure>;
+}
+export interface InvokeHooks {
+    /**
+     * After rate limiting, before the provider call. Return a Response to stop
+     * the request with it (e.g. 402 insufficient credit). Not run for /prompt.
+     */
+    beforeInvoke?(ctx: {
+        c: Context;
+        entity: EntityRow;
+        project: ProjectRow;
+        endpoint: EndpointRow;
+        provider: LlmProvider;
+    }): Promise<Response | void>;
+    /**
+     * After a successful provider call, inside the transaction that inserts the
+     * usage_analytics row. Throwing rolls that row back and fails the request 500.
+     */
+    afterInvoke?(ctx: {
+        tx: DbTransaction;
+        entity: EntityRow;
+        endpoint: EndpointRow;
+        usageAnalyticsId: string;
+        provider: LlmProvider;
+        model: string;
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+        };
+        providerCostMicroCents: bigint;
+    }): Promise<void>;
+}
+/** Auth functions the app initialises (auth_service is process-global). */
+export interface AuthAdapter {
+    verifyIdToken(token: string): Promise<DecodedIdToken>;
+    isSiteAdmin: typeof isSiteAdmin;
+    isAnonymousUser: typeof isAnonymousUser;
+    getUserInfo: typeof getUserInfo;
+}
+export interface EmailSender {
+    sendInvitationEmail(params: {
+        recipientEmail: string;
+        entityName: string;
+    }): Promise<void>;
+}
+/** `console` satisfies this; it is the default. */
+export interface Logger {
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

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

package/dist/contracts.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview What an app supplies to shapeshyft_service
+ * @description The provider-credential seam, invoke hooks, and the adapters that
+ * replace module-level singletons (auth, email, logging).
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview @sudobility/shapeshyft_service
+ * @description Tables, routes and middleware shared by ShapeShyft and
+ * ShapeRouter. Provider credentials come from the app via
+ * ProviderCredentialResolver; billing seams via InvokeHooks.
+ */
+export { createShapeshyftService, type BuildRoutesOptions, type ShapeshyftService, } from "./service.js";
+export { buildContext, type ServiceContext, type ShapeshyftServiceConfig, } from "./context.js";
+export type { AuthAdapter, DbTransaction, EmailSender, EndpointBinding, EndpointRecord, EndpointRow, EntityRow, InvokeHooks, Logger, ProjectRow, ProviderCredentialResolver, ResolvedCredential, ResolverFailure, ServiceDb, } from "./contracts.js";
+export { createServiceTables, LLM_PROVIDER_VALUES, type ServiceTables, } from "./schema/tables.js";
+export { initServiceTables } from "./schema/init.js";
+export { createEncryption, generateEncryptionKey, type Encryption, } from "./lib/encryption.js";
+export { toMicroCents } from "./lib/money.js";
+export { getActor, getPermissionErrorStatus, userActor, ENTITY_API_KEY_PERMISSIONS, type EntityAccess, type EntityActor, type EntityPermissionResult, } from "./lib/entity-helpers.js";
+export { DEFAULT_RATE_LIMITS_CONFIG, DEFAULT_ENTITLEMENT_DISPLAY_NAMES, } from "./middleware/rateLimit.js";
+export * from "./schemas/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,cAAc,EACd,WAAW,EACX,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,eAAe,EACf,SAAS,GACV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,KAAK,UAAU,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,QAAQ,EACR,wBAAwB,EACxB,SAAS,EACT,0BAA0B,EAC1B,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,0BAA0B,EAC1B,iCAAiC,GAClC,MAAM,2BAA2B,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview @sudobility/shapeshyft_service
+ * @description Tables, routes and middleware shared by ShapeShyft and
+ * ShapeRouter. Provider credentials come from the app via
+ * ProviderCredentialResolver; billing seams via InvokeHooks.
+ */
+export { createShapeshyftService, } from "./service.js";
+export { buildContext, } from "./context.js";
+export { createServiceTables, LLM_PROVIDER_VALUES, } from "./schema/tables.js";
+export { initServiceTables } from "./schema/init.js";
+export { createEncryption, generateEncryptionKey, } from "./lib/encryption.js";
+export { toMicroCents } from "./lib/money.js";
+export { getActor, getPermissionErrorStatus, userActor, ENTITY_API_KEY_PERMISSIONS, } from "./lib/entity-helpers.js";
+export { DEFAULT_RATE_LIMITS_CONFIG, DEFAULT_ENTITLEMENT_DISPLAY_NAMES, } from "./middleware/rateLimit.js";
+export * from "./schemas/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,uBAAuB,GAGxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,YAAY,GAGb,MAAM,cAAc,CAAC;AAiBtB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,gBAAgB,EAChB,qBAAqB,GAEtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,QAAQ,EACR,wBAAwB,EACxB,SAAS,EACT,0BAA0B,GAI3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,0BAA0B,EAC1B,iCAAiC,GAClC,MAAM,2BAA2B,CAAC;AACnC,cAAc,oBAAoB,CAAC"}

package/dist/lib/api-key.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Project API key management
+ * @description Generates, encrypts, decrypts, and validates project API keys.
+ * Keys use the format `sk_live_<base64url-random>` and are validated
+ * using timing-safe comparison to prevent timing attacks.
+ */
+import type { Encryption } from "./encryption.js";
+export declare function createProjectApiKeys(encryption: Encryption): {
+    generateProjectApiKey: () => {
+        key: string;
+        prefix: string;
+    };
+    encryptProjectApiKey: (key: string) => {
+        encrypted: string;
+        iv: string;
+    };
+    decryptProjectApiKey: (encrypted: string, iv: string) => string;
+    validateProjectApiKey: (providedKey: string, encryptedKey: string, iv: string) => boolean;
+    isValidApiKeyFormat: (key: string) => boolean;
+};
+export type ProjectApiKeys = ReturnType<typeof createProjectApiKeys>;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/lib/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../../src/lib/api-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQlD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU;iCAQvB;QAChC,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;KAChB;gCAoBkC,MAAM,KAAG;QAC1C,SAAS,EAAE,MAAM,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;KACZ;sCAUwC,MAAM,MAAM,MAAM,KAAG,MAAM;yCAarD,MAAM,gBACL,MAAM,MAChB,MAAM,KACT,OAAO;+BAuBwB,MAAM,KAAG,OAAO;EAWnD;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/lib/api-key.js

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Project API key management
+ * @description Generates, encrypts, decrypts, and validates project API keys.
+ * Keys use the format `sk_live_<base64url-random>` and are validated
+ * using timing-safe comparison to prevent timing attacks.
+ */
+import { randomBytes, timingSafeEqual } from "crypto";
+// API Key prefix for identification
+const API_KEY_PREFIX = "sk_live_";
+// Random bytes of entropy (32 bytes = 256 bits)
+const KEY_BYTES_LENGTH = 32;
+export function createProjectApiKeys(encryption) {
+    const { encryptApiKey, decryptApiKey } = encryption;
+    /**
+     * Generate a new API key with prefix
+     * Format: sk_live_<base64url-encoded-random-bytes>
+     * @returns Object with full key and prefix for display
+     */
+    function generateProjectApiKey() {
+        const randomPart = randomBytes(KEY_BYTES_LENGTH)
+            .toString("base64url")
+            .replace(/[=]/g, ""); // Remove padding
+        const fullKey = `${API_KEY_PREFIX}${randomPart}`;
+        // Prefix shows first 12 characters (sk_live_ + first 4 random chars)
+        const prefix = fullKey.substring(0, 12);
+        return {
+            key: fullKey,
+            prefix,
+        };
+    }
+    /**
+     * Encrypt a project API key for storage
+     * @param key The plain text API key
+     * @returns Object with encrypted value and IV
+     */
+    function encryptProjectApiKey(key) {
+        return encryptApiKey(key);
+    }
+    /**
+     * Decrypt a stored project API key
+     * @param encrypted The encrypted API key (hex string)
+     * @param iv The initialization vector (hex string)
+     * @returns The decrypted plain text API key
+     */
+    function decryptProjectApiKey(encrypted, iv) {
+        return decryptApiKey(encrypted, iv);
+    }
+    /**
+     * Validate a provided API key against an encrypted stored key
+     * Uses timing-safe comparison to prevent timing attacks
+     * @param providedKey The API key provided by the caller
+     * @param encryptedKey The encrypted stored API key
+     * @param iv The IV used for encryption
+     * @returns true if keys match, false otherwise
+     */
+    function validateProjectApiKey(providedKey, encryptedKey, iv) {
+        try {
+            const storedKey = decryptProjectApiKey(encryptedKey, iv);
+            // Use timing-safe comparison
+            const providedBuffer = Buffer.from(providedKey, "utf8");
+            const storedBuffer = Buffer.from(storedKey, "utf8");
+            if (providedBuffer.length !== storedBuffer.length) {
+                return false;
+            }
+            return timingSafeEqual(providedBuffer, storedBuffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if a string looks like a valid API key format
+     * @param key The string to check
+     * @returns true if format is valid
+     */
+    function isValidApiKeyFormat(key) {
+        return key.startsWith(API_KEY_PREFIX) && key.length > API_KEY_PREFIX.length;
+    }
+    return {
+        generateProjectApiKey,
+        encryptProjectApiKey,
+        decryptProjectApiKey,
+        validateProjectApiKey,
+        isValidApiKeyFormat,
+    };
+}
+//# sourceMappingURL=api-key.js.map

package/dist/lib/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../../src/lib/api-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAGtD,oCAAoC;AACpC,MAAM,cAAc,GAAG,UAAU,CAAC;AAElC,gDAAgD;AAChD,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B,MAAM,UAAU,oBAAoB,CAAC,UAAsB;IACzD,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,GAAG,UAAU,CAAC;IAEpD;;;;OAIG;IACH,SAAS,qBAAqB;QAI5B,MAAM,UAAU,GAAG,WAAW,CAAC,gBAAgB,CAAC;aAC7C,QAAQ,CAAC,WAAW,CAAC;aACrB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,iBAAiB;QAEzC,MAAM,OAAO,GAAG,GAAG,cAAc,GAAG,UAAU,EAAE,CAAC;QACjD,qEAAqE;QACrE,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAExC,OAAO;YACL,GAAG,EAAE,OAAO;YACZ,MAAM;SACP,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,SAAS,oBAAoB,CAAC,GAAW;QAIvC,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACH,SAAS,oBAAoB,CAAC,SAAiB,EAAE,EAAU;QACzD,OAAO,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,qBAAqB,CAC5B,WAAmB,EACnB,YAAoB,EACpB,EAAU;QAEV,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,oBAAoB,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;YAEzD,6BAA6B;YAC7B,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YACxD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAEpD,IAAI,cAAc,CAAC,MAAM,KAAK,YAAY,CAAC,MAAM,EAAE,CAAC;gBAClD,OAAO,KAAK,CAAC;YACf,CAAC;YAED,OAAO,eAAe,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;QACvD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS,mBAAmB,CAAC,GAAW;QACtC,OAAO,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;IAC9E,CAAC;IAED,OAAO;QACL,qBAAqB;QACrB,oBAAoB;QACpB,oBAAoB;QACpB,qBAAqB;QACrB,mBAAmB;KACpB,CAAC;AACJ,CAAC"}

package/dist/lib/encryption.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview AES-256-CBC encryption for credentials at rest
+ * @description The key is read through a getter on every call, so an app that
+ * starts without ENCRYPTION_KEY fails on first use -- the behaviour
+ * shapeshyft_api had when this read the environment directly.
+ */
+export interface Encryption {
+    /** Encrypt plain text; returns hex ciphertext and hex IV. */
+    encryptApiKey(plainText: string): {
+        encrypted: string;
+        iv: string;
+    };
+    /** Decrypt hex ciphertext with its hex IV. */
+    decryptApiKey(encrypted: string, ivHex: string): string;
+}
+/**
+ * @param getKeyHex Returns the 64-hex-character (32-byte) key. Called per operation.
+ */
+export declare function createEncryption(getKeyHex: () => string): Encryption;
+/** A new random key suitable for ENCRYPTION_KEY. */
+export declare function generateEncryptionKey(): string;
+//# sourceMappingURL=encryption.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/lib/encryption.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,8CAA8C;IAC9C,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,MAAM,GAAG,UAAU,CA4BpE;AAED,oDAAoD;AACpD,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C"}

package/dist/lib/encryption.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview AES-256-CBC encryption for credentials at rest
+ * @description The key is read through a getter on every call, so an app that
+ * starts without ENCRYPTION_KEY fails on first use -- the behaviour
+ * shapeshyft_api had when this read the environment directly.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "crypto";
+const ALGORITHM = "aes-256-cbc";
+const IV_LENGTH = 16; // AES block size
+/**
+ * @param getKeyHex Returns the 64-hex-character (32-byte) key. Called per operation.
+ */
+export function createEncryption(getKeyHex) {
+    function key() {
+        const keyHex = getKeyHex();
+        if (keyHex.length !== 64) {
+            throw new Error("ENCRYPTION_KEY must be 64 hex characters (32 bytes)");
+        }
+        return Buffer.from(keyHex, "hex");
+    }
+    return {
+        encryptApiKey(plainText) {
+            const iv = randomBytes(IV_LENGTH);
+            const cipher = createCipheriv(ALGORITHM, key(), iv);
+            let encrypted = cipher.update(plainText, "utf8", "hex");
+            encrypted += cipher.final("hex");
+            return { encrypted, iv: iv.toString("hex") };
+        },
+        decryptApiKey(encrypted, ivHex) {
+            const decipher = createDecipheriv(ALGORITHM, key(), Buffer.from(ivHex, "hex"));
+            let decrypted = decipher.update(encrypted, "hex", "utf8");
+            decrypted += decipher.final("utf8");
+            return decrypted;
+        },
+    };
+}
+/** A new random key suitable for ENCRYPTION_KEY. */
+export function generateEncryptionKey() {
+    return randomBytes(32).toString("hex");
+}
+//# sourceMappingURL=encryption.js.map

package/dist/lib/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/lib/encryption.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAEvE,MAAM,SAAS,GAAG,aAAa,CAAC;AAChC,MAAM,SAAS,GAAG,EAAE,CAAC,CAAC,iBAAiB;AASvC;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAuB;IACtD,SAAS,GAAG;QACV,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,OAAO;QACL,aAAa,CAAC,SAAS;YACrB,MAAM,EAAE,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;YAClC,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;YACpD,IAAI,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;YACxD,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACjC,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,CAAC;QACD,aAAa,CAAC,SAAS,EAAE,KAAK;YAC5B,MAAM,QAAQ,GAAG,gBAAgB,CAC/B,SAAS,EACT,GAAG,EAAE,EACL,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAC1B,CAAC;YACF,IAAI,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;YAC1D,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpC,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,qBAAqB;IACnC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC"}

package/dist/lib/entity-api-key.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Entity API key header conventions
+ * @description An entity key (`<prefix>_...`) authenticates a caller as the
+ * *entity* rather than as a person: CI jobs, deployment scripts, and MCP clients
+ * that must keep working when the member who created them leaves. Storage,
+ * generation, and verification live in `@sudobility/entity_service`; this
+ * module owns only the product's prefix and the header rules.
+ *
+ * Three other credentials exist and must not be confused with this one:
+ *   - personal key (user prefix), authenticates a *user* (see user-api-key.ts)
+ *   - `sk_live_...`  project key, authenticates callers of an AI endpoint
+ *   - Firebase token browser session credential
+ */
+export declare function createEntityApiKeyFormat(prefix: string): {
+    prefix: string;
+    prefixWithSeparator: string;
+    isEntityApiKeyFormat: (value: string) => boolean;
+    extractEntityApiKeyFromHeaders: (getHeader: (name: string) => string | undefined) => string | null;
+};
+export type EntityApiKeyFormat = ReturnType<typeof createEntityApiKeyFormat>;
+//# sourceMappingURL=entity-api-key.d.ts.map

package/dist/lib/entity-api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-api-key.d.ts","sourceRoot":"","sources":["../../src/lib/entity-api-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM;;;kCAOhB,MAAM,KAAG,OAAO;gDAkBxC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,KAC9C,MAAM,GAAG,IAAI;EAqBjB;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/lib/entity-api-key.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Entity API key header conventions
+ * @description An entity key (`<prefix>_...`) authenticates a caller as the
+ * *entity* rather than as a person: CI jobs, deployment scripts, and MCP clients
+ * that must keep working when the member who created them leaves. Storage,
+ * generation, and verification live in `@sudobility/entity_service`; this
+ * module owns only the product's prefix and the header rules.
+ *
+ * Three other credentials exist and must not be confused with this one:
+ *   - personal key (user prefix), authenticates a *user* (see user-api-key.ts)
+ *   - `sk_live_...`  project key, authenticates callers of an AI endpoint
+ *   - Firebase token browser session credential
+ */
+export function createEntityApiKeyFormat(prefix) {
+    const prefixWithSeparator = `${prefix}_`;
+    /**
+     * Check whether a string looks like an entity API key for this product.
+     * Used to route an incoming credential to entity auth instead of user auth.
+     */
+    function isEntityApiKeyFormat(value) {
+        return (value.startsWith(prefixWithSeparator) &&
+            value.length > prefixWithSeparator.length);
+    }
+    /**
+     * Extract an entity API key from request headers.
+     *
+     * Accepts `X-API-Key: <prefix>_...` (preferred, unambiguous) and
+     * `Authorization: Bearer <prefix>_...`. Anything without the prefix is left
+     * alone so it can be tried as a personal key or a Firebase ID token instead.
+     *
+     * @param getHeader Reads a request header by name, case-insensitively
+     * @returns The key, or null when the request carries none
+     */
+    function extractEntityApiKeyFromHeaders(getHeader) {
+        const headerKey = getHeader("X-API-Key");
+        if (headerKey && isEntityApiKeyFormat(headerKey))
+            return headerKey;
+        const authHeader = getHeader("Authorization");
+        if (authHeader) {
+            const [type, token] = authHeader.split(" ");
+            if (type === "Bearer" && token && isEntityApiKeyFormat(token)) {
+                return token;
+            }
+        }
+        return null;
+    }
+    return {
+        prefix,
+        prefixWithSeparator,
+        isEntityApiKeyFormat,
+        extractEntityApiKeyFromHeaders,
+    };
+}
+//# sourceMappingURL=entity-api-key.js.map

package/dist/lib/entity-api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-api-key.js","sourceRoot":"","sources":["../../src/lib/entity-api-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,MAAM,mBAAmB,GAAG,GAAG,MAAM,GAAG,CAAC;IAEzC;;;OAGG;IACH,SAAS,oBAAoB,CAAC,KAAa;QACzC,OAAO,CACL,KAAK,CAAC,UAAU,CAAC,mBAAmB,CAAC;YACrC,KAAK,CAAC,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAC1C,CAAC;IACJ,CAAC;IAED;;;;;;;;;OASG;IACH,SAAS,8BAA8B,CACrC,SAA+C;QAE/C,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;QACzC,IAAI,SAAS,IAAI,oBAAoB,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAEnE,MAAM,UAAU,GAAG,SAAS,CAAC,eAAe,CAAC,CAAC;QAC9C,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC5C,IAAI,IAAI,KAAK,QAAQ,IAAI,KAAK,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9D,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,MAAM;QACN,mBAAmB;QACnB,oBAAoB;QACpB,8BAA8B;KAC/B,CAAC;AACJ,CAAC"}