@x12i/catalox 3.4.5 → 3.5.0

package/dist/src/catalox/catalox.js

@@ -1,5 +1,5 @@
 import { compactCatalogFilter } from "../contracts/catalogs.js";
-import { CatalogAccessDeniedError, CatalogAdapterError, CatalogNotFoundError } from "../contracts/errors.js";
+import { CatalogAccessDeniedError, CatalogAdapterError, CatalogBindingError, CatalogNotFoundError, } from "../contracts/errors.js";
 import { validateMappingSpec } from "../mapping/validate-mapping.js";
 import { executeMapping } from "../mapping/execute-mapping.js";
 import { ApiCatalogAdapter } from "../adapters/api/api-adapter.js";
@@ -110,8 +110,41 @@ export class Catalox {
             if (active.length)
                 return { storeId, appIds: active };
         }
+        if (!context.appId) {
+            throw new CatalogBindingError({
+                reason: "missing_appId",
+                message: "App id is required unless storeId/appIds are provided.",
+            });
+        }
         return { ...(storeId ? { storeId } : {}), appIds: [context.appId] };
     }
+    async resolveAppIdForCatalogAccess(params) {
+        const { context, catalogId, required } = params;
+        if (context.appId)
+            return context.appId;
+        // Super-admin callers may omit appId; access is still evaluated with explicit elevation.
+        if (context.superAdmin)
+            return "_super";
+        // CatalogId-first: infer appId via active bindings if there is exactly one viable binding.
+        const bindings = await this.deps.bindings.listByCatalog(catalogId);
+        const active = bindings.filter((b) => b.status === "active");
+        const viable = active.filter((b) => {
+            if (required === "read")
+                return Boolean(b.access.canRead);
+            if (required === "write")
+                return Boolean(b.access.canWrite);
+            return Boolean(b.access.canAdmin);
+        });
+        const distinctApps = [...new Set(viable.map((b) => String(b.appId)))];
+        if (distinctApps.length === 1)
+            return viable[0].appId;
+        throw new CatalogBindingError({
+            reason: "cannot_resolve_appId_for_catalog",
+            catalogId: String(catalogId),
+            required,
+            matchingAppIds: distinctApps,
+        });
+    }
     readPath(obj, path) {
         if (!path)
             return undefined;
@@ -162,7 +195,12 @@ export class Catalox {
         }
         if (source.type === "catalog") {
             // Enforce authz: safest default is to require binding (unless god-mode).
-            await this.deps.authz.requireBindingAccess(params.context, params.context.appId, source.catalogId, "read");
+            const appId = await this.resolveAppIdForCatalogAccess({
+                context: params.context,
+                catalogId: source.catalogId,
+                required: "read",
+            });
+            await this.deps.authz.requireBindingAccess(params.context, appId, source.catalogId, "read");
             const filterEq = resolveFilterBy(source.filterBy, params.currentItemData, (o, p) => this.readPath(o, p));
             const sort = source.sortBy
                 ? { [source.sortBy.field]: source.sortBy.direction === "asc" ? 1 : -1 }
@@ -421,6 +459,9 @@ export class Catalox {
     }
     async listAppCatalogs(context, input) {
         const appId = input?.appId ?? context.appId;
+        if (!appId) {
+            throw new CatalogBindingError({ reason: "missing_appId", message: "listAppCatalogs requires an appId." });
+        }
         const bindings = await this.deps.bindings.listByApp(appId);
         const catalogs = await this.deps.catalogs.listAll();
         const byId = new Map(catalogs.map((c) => [c.catalogId, c]));
@@ -547,12 +588,14 @@ export class Catalox {
         return findCatalogsByAiHelper({ query: input.query, catalogs: all, input });
     }
     async getCatalogDescriptor(context, catalogId) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const rec = await this.deps.descriptors.get(catalogId);
         return rec?.descriptor ?? null;
     }
     async getCatalogRendererSnippet(context, catalogId, role, mode) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         if (!this.deps.rendererSnippets) {
             throw new Error("rendererSnippets dependency is not configured");
         }
@@ -560,6 +603,9 @@ export class Catalox {
     }
     async getAppCatalogBootstrap(context, appId) {
         const resolved = appId ?? context.appId;
+        if (!resolved) {
+            throw new CatalogBindingError({ reason: "missing_appId", message: "getAppCatalogBootstrap requires an appId." });
+        }
         const entries = await this.listAppCatalogs(context, { appId: resolved });
         const descriptors = [];
         for (const e of entries) {
@@ -582,7 +628,9 @@ export class Catalox {
         return out;
     }
     async listCatalogItems(context, catalogId, options) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const appCtx = context.appId ? context : { ...context, appId };
         const catalog = await this.deps.catalogs.get(catalogId);
         if (!catalog)
             throw new CatalogNotFoundError({ catalogId });
@@ -619,7 +667,7 @@ export class Catalox {
             else {
                 physical = await this.fetchScopedPhysicalRows(catalogId, rawScope, baseListOpts);
             }
-            const merged = mergeNativePhysicalRows(physical, descRec.descriptor.identity, String(context.appId), wantsSuperList);
+            const merged = mergeNativePhysicalRows(physical, descRec.descriptor.identity, String(appId), wantsSuperList);
             const off = listQueryOptions?.offset ?? 0;
             const lim = listQueryOptions?.limit ?? 100;
             const sliced = merged.slice(off, off + lim);
@@ -652,7 +700,7 @@ export class Catalox {
             const adapterConfig = await this.deps.adapters.get(def.adapterId);
             if (!adapterConfig)
                 throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
-            const result = await this.deps.mongoAdapter.listItems(context, catalogId, adapterConfig, { mapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
+            const result = await this.deps.mongoAdapter.listItems(appCtx, catalogId, adapterConfig, { mapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
             return result.issues?.length
                 ? { listOutcome: "ok", items: result.items, issues: result.issues }
                 : { listOutcome: "ok", items: result.items };
@@ -663,7 +711,7 @@ export class Catalox {
             const adapterConfig = await this.deps.adapters.get(def.adapterId);
             if (!adapterConfig)
                 throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
-            const result = await this.deps.apiAdapter.listItems(context, catalogId, adapterConfig, { responseMapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
+            const result = await this.deps.apiAdapter.listItems(appCtx, catalogId, adapterConfig, { responseMapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
             return {
                 listOutcome: "ok",
                 items: result.items,
@@ -697,7 +745,8 @@ export class Catalox {
         }
     }
     async getCatalogItem(context, catalogId, itemId, options) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const catalog = await this.deps.catalogs.get(catalogId);
         if (!catalog)
             throw new CatalogNotFoundError({ catalogId });
@@ -713,7 +762,7 @@ export class Catalox {
                 const base = {
                     itemId: rec.itemId,
                     catalogId: rec.catalogId,
-                    appId: context.appId,
+                    appId,
                     sourceMode: "native",
                     sourceType: "firebase",
                     data: rec.data,
@@ -738,7 +787,7 @@ export class Catalox {
             const filtered = scope?.accountId || scope?.groupId || scope?.userId || scope?.channelId || scope?.visitorId || scope?.domainId || scope?.agentId
                 ? filterPhysicalForTenantFetch(rows, scope)
                 : rows.filter((r) => isGlobalPhysicalRow(r));
-            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(context.appId), false);
+            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(appId), false);
             const hit = merged.find((m) => m.itemId === itemId) ?? merged[0];
             if (!hit)
                 return { outcome: "not_found" };
@@ -784,18 +833,23 @@ export class Catalox {
         return { isValid: true, issues: [] };
     }
     async getCatalogItemReferences(context, catalogId, itemId) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const refs = await this.deps.references.listByItem(catalogId, itemId);
         return refs;
     }
     async listCatalogReferences(context, catalogId) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const refs = await this.deps.references.listByCatalog(catalogId);
         return refs;
     }
     // Spec methods below are stubs for now; filled in by later todos.
     async getApp(_context, appId) {
-        return appId ? this.deps.apps.get(appId) : this.deps.apps.get(_context.appId);
+        const resolved = appId ?? _context.appId;
+        if (!resolved)
+            throw new CatalogBindingError({ reason: "missing_appId" });
+        return this.deps.apps.get(resolved);
     }
     async createCatalog(_context, _input) {
         const now = new Date().toISOString();
@@ -1004,7 +1058,8 @@ export class Catalox {
         return { query: input.query, hits, noMatch: Boolean(res.noMatch) };
     }
     async createCatalogItemByAi(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const descRec = await this.deps.descriptors.get(catalogId);
         if (!descRec)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
@@ -1056,7 +1111,8 @@ export class Catalox {
         return out;
     }
     async modifyCatalogItemByAi(context, catalogId, itemId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const descRec = await this.deps.descriptors.get(catalogId);
         if (!descRec)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
@@ -1146,7 +1202,7 @@ export class Catalox {
     async bindAppToStore(context, input) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        if (!context.superAdmin && input.appId !== context.appId) {
+        if (!context.superAdmin && (!context.appId || input.appId !== context.appId)) {
             throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.storeAppBindings.findByStoreApp(input.storeId, input.appId);
@@ -1170,7 +1226,7 @@ export class Catalox {
     async unbindAppFromStore(context, storeId, appId) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        if (!context.superAdmin && appId !== context.appId) {
+        if (!context.superAdmin && (!context.appId || appId !== context.appId)) {
             throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.storeAppBindings.findByStoreApp(storeId, appId);
@@ -1192,10 +1248,15 @@ export class Catalox {
         if (context.superAdmin)
             return records;
         // non-god: only reveal memberships that include the caller's own appId
-        return records.filter((r) => r.appId === context.appId);
+        return context.appId ? records.filter((r) => r.appId === context.appId) : [];
     }
     async ensureCatalog(context, catalog) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalog.catalogId, "admin");
+        const appId = await this.resolveAppIdForCatalogAccess({
+            context,
+            catalogId: catalog.catalogId,
+            required: "admin",
+        });
+        await this.deps.authz.requireBindingAccess(context, appId, catalog.catalogId, "admin");
         const existing = await this.deps.catalogs.get(catalog.catalogId);
         const now = new Date().toISOString();
         if (existing)
@@ -1211,7 +1272,7 @@ export class Catalox {
     }
     async ensureBinding(context, input) {
         // only super-admin apps can provision cross-app bindings.
-        if (!context.superAdmin && input.appId !== context.appId) {
+        if (!context.superAdmin && (!context.appId || input.appId !== context.appId)) {
             throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.bindings.findByAppCatalog(input.appId, input.catalogId);
@@ -1236,7 +1297,8 @@ export class Catalox {
         return this.upsertNativeCatalogItem(_context, _catalogId, _input);
     }
     async updateNativeCatalogItem(_context, _catalogId, _itemId, _patch, _options) {
-        await this.deps.authz.requireBindingAccess(_context, _context.appId, _catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context: _context, catalogId: _catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(_context, appId, _catalogId, "write");
         let existing = null;
         if (_options?.storageDocId) {
             existing = await this.deps.nativeItems.get(_catalogId, _options.storageDocId);
@@ -1292,7 +1354,7 @@ export class Catalox {
         const out = {
             itemId: nextRec.itemId,
             catalogId: _catalogId,
-            appId: _context.appId,
+            appId,
             sourceMode: "native",
             sourceType: "firebase",
             data: mergedData,
@@ -1302,7 +1364,8 @@ export class Catalox {
         return this.decorateItem(_catalogId, out);
     }
     async deleteNativeCatalogItem(_context, _catalogId, _itemId, _options) {
-        await this.deps.authz.requireBindingAccess(_context, _context.appId, _catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context: _context, catalogId: _catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(_context, appId, _catalogId, "write");
         let docId = _options?.storageDocId;
         if (!docId) {
             let rows = await this.deps.nativeItems.findByLogicalItemId(_catalogId, _itemId);
@@ -1333,7 +1396,8 @@ export class Catalox {
         if (!context.superAdmin) {
             throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
         }
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const fromDoc = input.fromStorageDocId ??
             encodeNativeItemStorageDocId(String(itemId), normalizeStoredScope(input.fromScope ?? { kind: "global" }));
         const rec = await this.deps.nativeItems.get(catalogId, fromDoc);
@@ -1362,7 +1426,8 @@ export class Catalox {
         });
     }
     async upsertNativeCatalogItem(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
@@ -1381,7 +1446,7 @@ export class Catalox {
             itemId: logicalItemId,
             catalogId,
             ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
-            appScopedOwnerId: context.appId,
+            appScopedOwnerId: appId,
             ...(indexed != null ? { indexed } : {}),
             data,
             version: (existing?.version ?? 0) + 1,
@@ -1402,7 +1467,7 @@ export class Catalox {
         return {
             itemId: logicalItemId,
             catalogId,
-            appId: context.appId,
+            appId,
             sourceMode: "native",
             sourceType: "firebase",
             data,
@@ -1411,7 +1476,8 @@ export class Catalox {
         };
     }
     async batchUpsertNativeCatalogItems(context, catalogId, items) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
@@ -1432,7 +1498,7 @@ export class Catalox {
                 itemId: logicalItemId,
                 catalogId,
                 ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
-                appScopedOwnerId: context.appId,
+                appScopedOwnerId: appId,
                 ...(indexed != null ? { indexed } : {}),
                 data: stripped.data,
                 createdAt: now,
@@ -1803,7 +1869,8 @@ export class Catalox {
         });
     }
     async listCatalogItemHistory(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const rh = this.deps.recordHistory;
         if (!rh)
             return { events: [] };
@@ -1816,7 +1883,8 @@ export class Catalox {
         const row = await rh.store.get(eventId);
         if (!row)
             return null;
-        await this.deps.authz.requireBindingAccess(context, context.appId, row.catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, row.catalogId, "read");
         const payload = await readRecordHistoryEventPayload(rh, row);
         return { index: row, payload };
     }
@@ -1827,7 +1895,8 @@ export class Catalox {
         const row = await rh.store.get(eventId);
         if (!row)
             throw new Error(`catalogItemHistory event not found: ${eventId}`);
-        await this.deps.authz.requireBindingAccess(context, context.appId, row.catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, row.catalogId, "write");
         const payload = await readRecordHistoryEventPayload(rh, row);
         const rec = input.mode === "before" ? payload.before ?? undefined : payload.after ?? undefined;
         if (!rec)
@@ -1847,7 +1916,7 @@ export class Catalox {
         return this.decorateItem(row.catalogId, {
             itemId: rec.itemId,
             catalogId: row.catalogId,
-            appId: context.appId,
+            appId,
             sourceMode: "native",
             sourceType: "firebase",
             data: liveAfter.data,
@@ -1856,7 +1925,8 @@ export class Catalox {
         });
     }
     async replayCatalogToPointInTime(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const rh = this.deps.recordHistory;
         if (!rh)
             throw new Error("recordHistory is not configured on Catalox");
@@ -1908,8 +1978,9 @@ export class Catalox {
         return { upserted, deleted };
     }
     async deleteCatalog(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "admin");
-        return runDeleteCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, context, catalogId, input);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "admin" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "admin");
+        return runDeleteCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, { ...context, appId }, catalogId, input);
     }
     async restoreDeletedCatalog(context, input) {
         if (!context.superAdmin) {
@@ -1926,8 +1997,9 @@ export class Catalox {
         return runRestoreDeletedCatalog(this.catalogLifecycleDeps(), rh, input);
     }
     async renameCatalog(context, fromCatalogId, toCatalogId, input = {}) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, fromCatalogId, "admin");
-        return runRenameCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, context, fromCatalogId, toCatalogId, input);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: fromCatalogId, required: "admin" });
+        await this.deps.authz.requireBindingAccess(context, appId, fromCatalogId, "admin");
+        return runRenameCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, { ...context, appId }, fromCatalogId, toCatalogId, input);
     }
     /**
      * Fix {@link CataloxContext} for subsequent calls so embedders omit it on each method (no globals).