@x12i/catalox-authix-bridge

Maps Authix token payloads to CataloxContext and enforces Catalox feature requirements on HTTP routes.

Part of the Catalox monorepo. Required for 6.0.0 public API.

Role

Authix is not login — your SaaS authenticates users; your backend issues Authix tokens. This package bridges those tokens into the engine's authorization model.

| Export | Purpose | |--------|---------| | mapAuthixToCataloxContext(payload) | Authix → CataloxContext | | CATALOX_FEATURES / CataloxFeatureId | Feature id registry | | requireCataloxFeature(payload, featureId) | Throw if feature missing | | hasCataloxFeature(payload, featureId) | Boolean check | | narrowScopeFromQuery(tokenScope, queryScope) | Scope narrowing rules |

Feature catalog

| Feature ID | Allows | |------------|--------| | catalox.discovery.read | List catalogs, bootstrap | | catalox.catalog.read | Catalog metadata read | | catalox.catalog.write | Descriptor / catalog mutations | | catalox.catalog.admin | Bind/unbind, lifecycle admin | | catalox.item.read | List/get items | | catalox.item.write | Upsert/patch/delete items | | catalox.item.search | Search / AI match | | catalox.operator.read | Inventory, export | | catalox.operator.super | superAdmin (service identities only) |

Usage

In-process (BFF)

import { createAuthixTokenVerifier } from "@x12i/authix-sdk";
import { mapAuthixToCataloxContext, requireCataloxFeature } from "@x12i/catalox-authix-bridge";
import { createCatalox } from "@x12i/catalox-engine";

const payload = await verifier.assertValid(token);
requireCataloxFeature(payload, "catalox.item.read");
const context = mapAuthixToCataloxContext(payload);
await catalox.listCatalogItemsWithOutcome(context, "skills");

HTTP (via @x12i/catalox-api)

catalox-service with CATALOX_AUTH_MODE=authix verifies tokens and route handlers call requireCataloxFeature before engine methods.

Mapping reference

| Authix | Catalox | |--------|---------| | appId | context.appId | | subject.identityId + identityType | userId, agentId, actor | | scope.accountIds | accountId, scope.accountIds | | scope.domainIds | domainId, scope.domainIds | | scope.custom | merged into item scope | | catalox.operator.super + service subject | superAdmin: true |

Token scope is the visibility ceiling; query scope may only narrow.

→ 6.0.0 README · authorization.md

Install & build

npm install @x12i/catalox-authix-bridge @x12i/catalox-contracts
npm run build -w @x12i/catalox-authix-bridge
npm test -w @x12i/catalox-authix-bridge

Depends on @x12i/authix-types.