@x12i/catalox 1.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,222 @@
+# `@x12i/catalox`
+
+Catalox is a **data-tier** package for managing **app-scoped catalogs** in Firebase **Firestore**, including:
+
+- **Catalog discovery** for an `appId` (what catalogs are available + access)
+- **First-class catalog descriptors** (capabilities, query metadata, identity metadata, field metadata)
+- **Native catalogs** (items stored in Firestore)
+- **Mapped catalogs** (items normalized from MongoDB or APIs)
+- **References + validation contracts** (standardized cross-catalog shapes)
+- **Seed/import/export + batch upsert** workflows for native catalogs
+
+Catalox **does not** own UI, workflow orchestration, remote execution, artifact blobs, or secret storage.
+
+## Install
+
+This repo is currently set up as a workspace package.
+
+- **Node**: `>=20`
+- **TypeScript**: builds to `dist/`
+
+`@x12i/helpers` is a **required dependency** (installed as `@x12i/helpers@^1.2.0`).
+
+## Configuration (real connections)
+
+Catalox is a library: you provide initialized clients + runtime env.
+
+### Firestore (Firebase Admin SDK)
+
+This implementation of Catalox expects a **Firebase Admin SDK** Firestore instance (`firebase-admin`).
+
+Important clarification:
+
+- **“Admin” here means privileged access to your Firebase/GCP project’s Firestore**, using a service account.
+- It is **not** “admin of the host machine / server OS”.
+- Admin SDK access typically **bypasses Firestore Security Rules** (rules are for client SDKs).
+
+Scoping:
+
+- You can scope the service account to **Firestore-related IAM roles** and to a specific **project**.
+- You generally cannot scope an Admin SDK credential to only certain collections/documents via IAM the way client rules work.
+
+To connect to a real Firebase project, initialize `firebase-admin` using `GOOGLE_APPLICATION_CREDENTIALS` (service account JSON) or your preferred Admin initialization strategy.
+
+Minimal example:
+
+```ts
+import { initializeApp, applicationDefault } from "firebase-admin/app";
+import { getFirestore } from "firebase-admin/firestore";
+
+initializeApp({ credential: applicationDefault() });
+const firestore = getFirestore();
+```
+
+### Mongo (mapped catalogs)
+
+For Mongo-mapped catalogs, provide:
+
+- `MONGO_URI` (or whatever you store in adapter config as `mongoUriEnvVar`)
+
+Example `.env` (do not commit secrets):
+
+```bash
+MONGO_URI=mongodb://127.0.0.1:27017
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+FIRESTORE_LIVE_TESTS=1
+```
+
+## Firestore data model (logical collections)
+
+Metadata:
+
+- `apps/{appId}`
+- `catalogs/{catalogId}`
+- `catalogBindings/{bindingId}` (many-to-many app↔catalog)
+- `catalogDefinitions/{catalogId}` (native vs mapped specifics)
+- `catalogAdapters/{adapterId}` (mongo/api adapter definitions)
+- `catalogMappings/{mappingId}` (field mapping specs)
+- `catalogDescriptors/{catalogId}` (**descriptor metadata** for generic consumption)
+- `catalogReferences/{referenceId}` (standardized reference records)
+
+Data:
+
+- `catalogData/{catalogId}/items/{itemId}` (native items)
+- `catalogSnapshots/{catalogId}/items/{itemId}` (mapped snapshot mode)
+
+## Core usage (generic from `appId`)
+
+### Create stores and `Catalox`
+
+```ts
+import { FirestoreStore } from "@x12i/catalox";
+import { AppStore, CatalogStore, BindingStore, DefinitionStore, MappingStore, DescriptorStore, ReferenceStore, NativeItemStore, SnapshotStore, AdapterStore } from "@x12i/catalox";
+import { AuthorizationService, Catalox } from "@x12i/catalox";
+
+// firebase-admin initialization is up to the consumer
+import { getFirestore } from "firebase-admin/firestore";
+
+const firestore = getFirestore();
+const store = new FirestoreStore({ firestore });
+
+const deps = {
+  apps: new AppStore(store),
+  catalogs: new CatalogStore(store),
+  bindings: new BindingStore(store),
+  definitions: new DefinitionStore(store),
+  mappings: new MappingStore(store),
+  descriptors: new DescriptorStore(store),
+  references: new ReferenceStore(store),
+  nativeItems: new NativeItemStore(store),
+  snapshots: new SnapshotStore(store),
+  adapters: new AdapterStore(store),
+  authz: new AuthorizationService(new BindingStore(store)),
+};
+
+const catalox = new Catalox(deps);
+```
+
+### What you need persisted for “generic consumption”
+
+To let consumers operate *purely* from `appId` with no hardcoded catalog registrations, Catalox relies on these being present in Firestore:
+
+- **Bindings**: `catalogBindings` determine which catalogs an app can see/use.
+- **Descriptors**: `catalogDescriptors/{catalogId}` provide capabilities, query metadata, identity metadata, and field metadata.
+
+### Discover catalogs for an app
+
+```ts
+const context = { appId: "myAppId" };
+const catalogs = await catalox.listAppCatalogs(context, { appId: "myAppId" });
+```
+
+### Get a catalog descriptor
+
+```ts
+const descriptor = await catalox.getCatalogDescriptor(context, "signals");
+```
+
+### Bootstrap (all descriptors accessible to an app)
+
+```ts
+const bootstrap = await catalox.getAppCatalogBootstrap(context, "myAppId");
+```
+
+### Common “generic client” flow (no hardcoded catalog logic)
+
+1) `listAppCatalogs(appId)` → get catalog list + access
+2) `getAppCatalogBootstrap(appId)` → get descriptors (capabilities/query/identity/fields)
+3) `listCatalogItems(catalogId, filter/sort)` → fetch normalized items
+4) `getCatalogItem(catalogId, itemId)` → fetch one item
+5) Optional: `getCatalogItemReferences(...)`, `validateCatalogItem(...)`
+
+## Native catalogs (seed/import/export + batch upsert)
+
+### Import/Export JSON (helpers)
+
+```ts
+const items = catalox.importCatalogItemsFromJson<Array<Record<string, unknown>>>(jsonString);
+const jsonOut = catalox.exportCatalogItemsToJson(items);
+```
+
+### Upsert one item (descriptor-driven identity)
+
+```ts
+await catalox.upsertNativeCatalogItem({ appId: "myAppId" }, "signals", {
+  categoryId: "core",
+  code: "S1",
+  title: "Example",
+  indexed: { categoryId: "core", code: "S1" }
+});
+```
+
+### Batch upsert
+
+```ts
+await catalox.batchUpsertNativeCatalogItems({ appId: "myAppId" }, "signals", items);
+```
+
+### List native items with equality filtering
+
+```ts
+const res = await catalox.listCatalogItems({ appId: "myAppId" }, "signals", {
+  filter: { categoryId: "core" }
+});
+```
+
+Filtering is performed on `indexed.<field>` in stored native records (payload remains in `data`).
+
+## References
+
+```ts
+const refs = await catalox.getCatalogItemReferences({ appId: "myAppId" }, "signals", "core:S1");
+```
+
+## Validation
+
+Catalog-level and item-level validation APIs exist with standardized contracts. (Item validation logic can be implemented by upstream domain rules while keeping the contract stable.)
+
+## Tests
+
+Unit tests (default):
+
+```bash
+npm test
+```
+
+Integration tests (live Firestore, no mocks/emulators):
+
+```bash
+npm run test:integration
+```
+
+Integration tests are **live-only** (no mocks, no emulators). They require:
+
+- `FIRESTORE_LIVE_TESTS=1`
+- `FIREBASE_SERVICE_ACCOUNT_PATH=...`
+- `FIREBASE_PROJECT_ID=...`
+
+## Boundaries (important)
+
+- **Secrets**: do not store secret material (API keys, cloud creds) in Catalox. Store only non-secret refs like `credentialsRef`.
+- **Artifacts**: store descriptor metadata and remote keys; artifact blobs live in external object storage.
+

package/dist/adapters/api/api-adapter.d.ts

@@ -0,0 +1,22 @@
+import type { ApiCatalogAdapterConfig } from "../../contracts/adapters.js";
+import type { CatalogQueryOptions } from "../../contracts/catalogs.js";
+import type { CataloxContext } from "../../contracts/context.js";
+import type { CatalogId } from "../../contracts/ids.js";
+import type { UnifiedCatalogItem } from "../../contracts/items.js";
+import type { CatalogFieldMappingSpec, MappingExecutionOptions } from "../../contracts/mappings.js";
+export type ApiAdapterRuntime = {
+    fetchImpl?: typeof fetch;
+};
+export declare class ApiCatalogAdapter {
+    private readonly runtime;
+    constructor(runtime?: ApiAdapterRuntime);
+    listItems(context: CataloxContext, catalogId: CatalogId, config: ApiCatalogAdapterConfig, mapping: {
+        responseMapping: CatalogFieldMappingSpec[];
+        options?: MappingExecutionOptions;
+    }, options?: CatalogQueryOptions): Promise<{
+        items: UnifiedCatalogItem[];
+        nextCursor?: string;
+        issues?: import("../../contracts/mappings.js").CatalogMappingIssue[];
+    }>;
+}
+//# sourceMappingURL=api-adapter.d.ts.map

package/dist/adapters/api/api-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/api/api-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAGpG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,CAAC;AAYF,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,iBAAsB;IAEtD,SAAS,CACb,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE;QAAE,eAAe,EAAE,uBAAuB,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,uBAAuB,CAAA;KAAE,EAC1F,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC;QAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,6BAA6B,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAC;CAgDvI"}

package/dist/adapters/api/api-adapter.js

@@ -0,0 +1,60 @@
+import { executeMapping } from "../../mapping/execute-mapping.js";
+function deepGetFallback(obj, path) {
+    const parts = path.split(".").map((p) => p.trim()).filter(Boolean);
+    let cur = obj;
+    for (const p of parts) {
+        if (cur == null)
+            return undefined;
+        cur = cur[p];
+    }
+    return cur;
+}
+export class ApiCatalogAdapter {
+    runtime;
+    constructor(runtime = {}) {
+        this.runtime = runtime;
+    }
+    async listItems(context, catalogId, config, mapping, options) {
+        const fetchImpl = this.runtime.fetchImpl ?? fetch;
+        if (!config.endpoint)
+            throw new Error("API adapter missing endpoint.");
+        const url = new URL(config.endpoint);
+        if (options?.limit != null)
+            url.searchParams.set("limit", String(options.limit));
+        if (options?.offset != null)
+            url.searchParams.set("offset", String(options.offset));
+        const res = await fetchImpl(url.toString(), { method: config.method ?? "GET" });
+        if (!res.ok)
+            throw new Error(`API request failed: ${res.status}`);
+        const body = (await res.json());
+        const itemsPath = config.pagination?.itemsPath;
+        const rawItems = itemsPath ? deepGetFallback(body, itemsPath) : body;
+        const arr = Array.isArray(rawItems) ? rawItems : [];
+        const out = [];
+        const issues = [];
+        for (const row of arr) {
+            const source = row;
+            const mapped = executeMapping(source, mapping.responseMapping, mapping.options);
+            if (mapped.issues)
+                issues.push(...mapped.issues);
+            const itemId = config.itemIdSourcePath ? deepGetFallback(source, config.itemIdSourcePath) : undefined;
+            out.push({
+                itemId: itemId != null ? String(itemId) : JSON.stringify(source),
+                catalogId,
+                appId: context.appId,
+                sourceMode: "mapped",
+                sourceType: "api",
+                sourceRef: { endpoint: config.endpoint },
+                data: mapped.data,
+            });
+        }
+        const nextCursorPath = config.pagination?.nextCursorPath;
+        const nextCursor = nextCursorPath ? deepGetFallback(body, nextCursorPath) : undefined;
+        return {
+            items: out,
+            ...(typeof nextCursor === "string" ? { nextCursor } : {}),
+            ...(issues.length ? { issues } : {}),
+        };
+    }
+}
+//# sourceMappingURL=api-adapter.js.map

package/dist/adapters/api/api-adapter.js.map

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

package/dist/adapters/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./api-adapter.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/api/index.js

@@ -0,0 +1,2 @@
+export * from "./api-adapter.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/adapters/mongo/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./mongo-adapter.js";
+export * from "./resolve-db.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/mongo/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/mongo/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/adapters/mongo/index.js

@@ -0,0 +1,3 @@
+export * from "./mongo-adapter.js";
+export * from "./resolve-db.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/mongo/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/mongo/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/adapters/mongo/mongo-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { MongoCatalogAdapterConfig } from "../../contracts/adapters.js";
+import type { CatalogQueryOptions } from "../../contracts/catalogs.js";
+import type { CataloxContext } from "../../contracts/context.js";
+import type { CatalogId } from "../../contracts/ids.js";
+import type { UnifiedCatalogItem } from "../../contracts/items.js";
+import type { MappingExecutionOptions } from "../../contracts/mappings.js";
+export type MongoAdapterRuntime = {
+    mongoUri: string;
+};
+export declare class MongoCatalogAdapter {
+    private readonly runtime;
+    constructor(runtime: MongoAdapterRuntime);
+    listItems(context: CataloxContext, catalogId: CatalogId, config: MongoCatalogAdapterConfig, mapping: {
+        mapping: import("../../contracts/mappings.js").CatalogFieldMappingSpec[];
+        options?: MappingExecutionOptions;
+    }, options?: CatalogQueryOptions): Promise<{
+        items: UnifiedCatalogItem[];
+        issues?: import("../../contracts/mappings.js").CatalogMappingIssue[];
+    }>;
+}
+//# sourceMappingURL=mongo-adapter.d.ts.map

package/dist/adapters/mongo/mongo-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/mongo/mongo-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAI3E,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,mBAAmB;IAEnD,SAAS,CACb,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,yBAAyB,EACjC,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,6BAA6B,EAAE,uBAAuB,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,uBAAuB,CAAA;KAAE,EACxH,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC;QAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,6BAA6B,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAC;CAyDlH"}

package/dist/adapters/mongo/mongo-adapter.js

@@ -0,0 +1,57 @@
+import { MongoClient } from "mongodb";
+import { executeMapping } from "../../mapping/execute-mapping.js";
+import { resolveMongoDbName } from "./resolve-db.js";
+export class MongoCatalogAdapter {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async listItems(context, catalogId, config, mapping, options) {
+        const client = new MongoClient(this.runtime.mongoUri);
+        await client.connect();
+        try {
+            const dbName = config.databaseResolution.kind === "lookup"
+                ? resolveMongoDbName(context.appId, { kind: "appId-direct" })
+                : resolveMongoDbName(context.appId, config.databaseResolution);
+            const db = client.db(dbName);
+            const coll = db.collection(config.collection);
+            const filter = {
+                ...(config.queryDefaults?.filter ?? {}),
+                ...(options?.filter ?? {}),
+            };
+            const sort = (options?.sort ?? config.queryDefaults?.sort ?? {});
+            const limit = options?.limit ?? 100;
+            const skip = options?.offset ?? 0;
+            const cursor = coll.find(filter).sort(sort).skip(skip).limit(limit);
+            const docs = (await cursor.toArray());
+            const items = [];
+            const issues = [];
+            for (const doc of docs) {
+                const source = doc;
+                const mapped = executeMapping(source, mapping.mapping, mapping.options);
+                if (mapped.issues)
+                    issues.push(...mapped.issues);
+                const itemId = (config.idSourcePath ? source?.[config.idSourcePath] : undefined) ??
+                    String(doc._id);
+                items.push({
+                    itemId: String(itemId),
+                    catalogId,
+                    appId: context.appId,
+                    sourceMode: "mapped",
+                    sourceType: "mongo",
+                    sourceRef: {
+                        database: dbName,
+                        collection: config.collection,
+                        sourceRecordId: String(doc._id),
+                    },
+                    data: mapped.data,
+                });
+            }
+            return issues.length ? { items, issues } : { items };
+        }
+        finally {
+            await client.close();
+        }
+    }
+}
+//# sourceMappingURL=mongo-adapter.js.map

package/dist/adapters/mongo/mongo-adapter.js.map

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

package/dist/adapters/mongo/resolve-db.d.ts

@@ -0,0 +1,4 @@
+import type { AppId } from "../../contracts/ids.js";
+import type { MongoDatabaseResolution } from "../../contracts/adapters.js";
+export declare function resolveMongoDbName(appId: AppId, resolution: MongoDatabaseResolution): string;
+//# sourceMappingURL=resolve-db.d.ts.map

package/dist/adapters/mongo/resolve-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-db.d.ts","sourceRoot":"","sources":["../../../src/adapters/mongo/resolve-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAE3E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,uBAAuB,GAAG,MAAM,CAO5F"}

package/dist/adapters/mongo/resolve-db.js

@@ -0,0 +1,10 @@
+export function resolveMongoDbName(appId, resolution) {
+    if (resolution.kind === "appId-direct")
+        return String(appId);
+    if (resolution.kind === "template") {
+        return String(resolution.template).replaceAll("{appId}", String(appId));
+    }
+    // lookup mode requires an external lookup (Firestore) and is handled at a higher layer.
+    return String(appId);
+}
+//# sourceMappingURL=resolve-db.js.map

package/dist/adapters/mongo/resolve-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-db.js","sourceRoot":"","sources":["../../../src/adapters/mongo/resolve-db.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,kBAAkB,CAAC,KAAY,EAAE,UAAmC;IAClF,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7D,IAAI,UAAU,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,wFAAwF;IACxF,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/bindings/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC"}

package/dist/bindings/index.js

@@ -0,0 +1,3 @@
+// Binding helpers will live here.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/bindings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,OAAO,EAAE,CAAC"}

package/dist/catalox/authorization.d.ts

@@ -0,0 +1,11 @@
+import type { AppId, CatalogId } from "../contracts/ids.js";
+import type { CataloxContext } from "../contracts/context.js";
+import type { CatalogBindingRecord } from "../contracts/bindings.js";
+import { BindingStore } from "../firebase/binding-store.js";
+export type RequiredAccess = "read" | "write" | "admin";
+export declare class AuthorizationService {
+    private readonly bindings;
+    constructor(bindings: BindingStore);
+    requireBindingAccess(context: CataloxContext, appId: AppId, catalogId: CatalogId, required: RequiredAccess): Promise<CatalogBindingRecord>;
+}
+//# sourceMappingURL=authorization.d.ts.map

package/dist/catalox/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../src/catalox/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAExD,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,YAAY;IAE7C,oBAAoB,CACxB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,oBAAoB,CAAC;CAiCjC"}

package/dist/catalox/authorization.js

@@ -0,0 +1,37 @@
+import { CatalogAccessDeniedError } from "../contracts/errors.js";
+import { BindingStore } from "../firebase/binding-store.js";
+export class AuthorizationService {
+    bindings;
+    constructor(bindings) {
+        this.bindings = bindings;
+    }
+    async requireBindingAccess(context, appId, catalogId, required) {
+        if (context.isGodMode) {
+            // God-mode policy: bypass binding for read/admin checks if needed.
+            // We still return a synthetic binding for uniformity.
+            return {
+                bindingId: `${String(appId)}:${String(catalogId)}`,
+                appId,
+                catalogId,
+                access: { canRead: true, canWrite: true, canAdmin: true },
+                status: "active",
+                createdAt: new Date(0).toISOString(),
+                updatedAt: new Date(0).toISOString(),
+            };
+        }
+        const binding = await this.bindings.findByAppCatalog(appId, catalogId);
+        if (!binding || binding.status !== "active") {
+            throw new CatalogAccessDeniedError({ appId, catalogId, reason: "binding_not_found_or_inactive" });
+        }
+        const ok = required === "read"
+            ? Boolean(binding.access.canRead)
+            : required === "write"
+                ? Boolean(binding.access.canWrite)
+                : Boolean(binding.access.canAdmin);
+        if (!ok) {
+            throw new CatalogAccessDeniedError({ appId, catalogId, required });
+        }
+        return binding;
+    }
+}
+//# sourceMappingURL=authorization.js.map

package/dist/catalox/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../../src/catalox/authorization.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAI5D,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,QAAsB;QAAtB,aAAQ,GAAR,QAAQ,CAAc;IAAG,CAAC;IAEvD,KAAK,CAAC,oBAAoB,CACxB,OAAuB,EACvB,KAAY,EACZ,SAAoB,EACpB,QAAwB;QAExB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,mEAAmE;YACnE,sDAAsD;YACtD,OAAO;gBACL,SAAS,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE;gBAClD,KAAK;gBACL,SAAS;gBACT,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACzD,MAAM,EAAE,QAAQ;gBAChB,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;gBACpC,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;aACrC,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC5C,MAAM,IAAI,wBAAwB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC,CAAC;QACpG,CAAC;QAED,MAAM,EAAE,GACN,QAAQ,KAAK,MAAM;YACjB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;YACjC,CAAC,CAAC,QAAQ,KAAK,OAAO;gBACpB,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;gBAClC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEzC,IAAI,CAAC,EAAE,EAAE,CAAC;YACR,MAAM,IAAI,wBAAwB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrE,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}