@dereekb/dbx-cli 13.11.17 → 13.12.0

package/src/lib/mcp-scan/registry/archetypes.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Model archetype catalog.
+ *
+ * Canonical metadata for the 17 Firestore-model archetypes plus 3 field-level
+ * add-ons that the `dbx_model_archetype_*` tool cluster recommends, looks up,
+ * and filters peers by. Pure data — no imports, no state — so it can be
+ * consumed from tools, resources, and tests without bootstrap overhead.
+ *
+ * Each archetype carries its `slug`, the implied
+ * {@link FirestoreCollectionKind}, a short narrative description, a structured
+ * "answer template" (`expected`) used by the recommender's scoring algorithm,
+ * and the discrete axis values that further refine the slug.
+ *
+ * The recommender's scoring algorithm walks {@link MODEL_ARCHETYPES} once per
+ * call and never mutates the array, so the entire table is frozen at
+ * compile-time through `readonly` types. New archetypes are added by appending
+ * a {@link ModelArchetypeInfo} entry — the tool cluster picks it up
+ * automatically.
+ */
+import type { FirestoreCollectionKind } from './firebase-models.js';
+/**
+ * First-class sync-mode taxonomy attached to every model archetype. Mirrors the
+ * vocabulary documented in the planning doc (`§3 Sync-Mode Vocabulary`) so the
+ * recommender's questionnaire, the catalog UI, and the heuristic extractor all
+ * use one set of values.
+ *
+ * - `always-in-sync` – source of truth or updated synchronously alongside its dependency.
+ * - `trigger-eventual` – patched by an `onWrite` / `onCreate` Firestore trigger.
+ * - `flag-eventual` – source carries a `@dbxModelVariableSyncFlag` boolean flag walked by a scheduler.
+ * - `scheduled-rebuild` – periodic full/partial rebuild on a cron; no per-source flag.
+ * - `append-only` – never updated after creation; new docs supersede old.
+ * - `pull-on-demand` – read by code when needed; nothing watches it.
+ * - `external-bidirectional` – webhook patches in, scheduled reconciler patches out.
+ */
+export type ModelArchetypeSyncMode = 'always-in-sync' | 'trigger-eventual' | 'flag-eventual' | 'scheduled-rebuild' | 'append-only' | 'pull-on-demand' | 'external-bidirectional';
+/**
+ * Every recognised sync-mode in declaration order. Exported so resources can
+ * surface a stable list (`dbx://model-archetype/by-sync-mode/{mode}`) without
+ * re-deriving it from {@link MODEL_ARCHETYPES}.
+ */
+export declare const MODEL_ARCHETYPE_SYNC_MODES: readonly ModelArchetypeSyncMode[];
+/**
+ * Discrete values for the `docIdSource` questionnaire field. Used both by the
+ * recommender (top-tier discriminator, weight 3) and by the `denormalised-aggregate`
+ * archetype's `keying` axis. Keep in sync with the canonical schema in
+ * the planning doc (`§4.1`).
+ */
+export type ModelArchetypeDocIdSource = 'auto' | 'parent-id' | 'user-uid' | 'external-vendor-id' | 'geo-key' | 'bucket-code' | 'composite-flat-key' | 'numeric-short-id' | 'fixed';
+/**
+ * Discrete values for the `parentRelation` questionnaire field. Captures both
+ * the structural parent (one / many parents, no parent) AND the meta-parent
+ * cases the recommender uses to disambiguate user-keyed, external-id-keyed,
+ * geo-key roots.
+ */
+export type ModelArchetypeParentRelation = 'none' | 'one-parent' | 'many-parents' | 'user-uid' | 'external-vendor-id' | 'region-key' | 'district-key' | 'composite-key';
+/**
+ * Discrete values for the `userRelation` questionnaire field. Independent of
+ * {@link ModelArchetypeDocIdSource}: a model can have `uid-is-doc-id` AND a
+ * field reference (`references-user-key`) in tandem.
+ */
+export type ModelArchetypeUserRelation = 'none' | 'owned-by-uid' | 'uid-is-doc-id' | 'references-user-key' | 'external-vendor-id-is-doc-id';
+/**
+ * Discrete values for the `mutability` questionnaire field. The `append-only`
+ * case lives on `syncMode`, not here — once a doc is created it can still be
+ * `mutable` or `immutable` across its lifetime independently.
+ */
+export type ModelArchetypeMutability = 'mutable' | 'immutable';
+/**
+ * Every recognised archetype slug. Axis values (e.g.
+ * `single-item-sub.subPurpose`, `denormalised-aggregate.keying`) further refine
+ * a slug rather than introducing separate slugs.
+ */
+export type ModelArchetypeSlug = 'root-entity' | 'sub-collection-entity' | 'single-item-sub' | 'user-keyed-entity-root' | 'user-keyed-index-root' | 'external-id-keyed-entity-root' | 'group-root' | 'group-member' | 'composite-key-root' | 'denormalised-aggregate' | 'root-singleton-aggregate' | 'external-mirror' | 'audit-log' | 'lifecycle-item' | 'reference-registry' | 'model-tree-node' | 'system-state-singleton' | 'storagefile-purpose' | 'notification-template' | 'notification-task' | 'state-machine-item' | 'embedded-sub-objects' | 'active-vs-archive-split';
+/**
+ * Field-level add-on slugs that never appear as the primary archetype answer —
+ * always returned alongside a "real" archetype on the recommender's "Field-level
+ * add-ons" list.
+ */
+export declare const MODEL_ARCHETYPE_ADDON_SLUGS: readonly ModelArchetypeSlug[];
+/**
+ * Discrete values for `single-item-sub.subPurpose`. Captures why this 1:1
+ * subcollection exists — sensitive split, permission table, parent config,
+ * parent state, denormalised summary, member-count summary.
+ */
+export type ModelArchetypeSingleItemSubPurpose = 'private' | 'permission' | 'config' | 'state' | 'summary' | 'member-summary';
+/**
+ * Discrete values for `denormalised-aggregate.keying`. Combined with
+ * `syncMode`, these distinguish parent-keyed digests, bucketed temporal
+ * summaries, composite-keyed indexes, and short-id subcollection summaries.
+ */
+export type ModelArchetypeDenormalisedAggregateKeying = 'parent-id' | 'bucket-code' | 'composite-flat-key' | 'numeric-short-id';
+/**
+ * Canonical answer template for one archetype. Each field is the *expected*
+ * value the recommender looks for on a matching questionnaire; the scoring
+ * algorithm sums weighted matches across these dimensions.
+ *
+ * Each property is optional because not every archetype constrains every
+ * dimension — `root-entity` allows any `userRelation`, so its template omits
+ * the field rather than forcing one value. Unset answers contribute zero to
+ * the score on either side (see `§5.2 Scoring algorithm`).
+ */
+export interface ModelArchetypeExpectedAnswers {
+    readonly docIdSource?: readonly ModelArchetypeDocIdSource[];
+    readonly parentRelation?: readonly ModelArchetypeParentRelation[];
+    readonly userRelation?: readonly ModelArchetypeUserRelation[];
+    readonly syncMode?: readonly ModelArchetypeSyncMode[];
+    readonly isDenormalization?: boolean;
+    readonly isExternalMirror?: boolean;
+    readonly isEventLog?: boolean;
+    readonly hasInheritance?: boolean;
+    readonly isSiblingAggregate?: boolean;
+    readonly isSubsystemSingleton?: boolean;
+    readonly involvesFileUpload?: boolean;
+    readonly sendsMessageToUser?: boolean;
+    readonly isMultiCheckpointWorkflow?: boolean;
+    readonly hasLifecycleStates?: boolean;
+    readonly hasSensitiveFields?: boolean;
+    readonly needsFineGrainedPermissions?: boolean;
+    readonly hasArchiveCounterpart?: boolean;
+    readonly mutability?: readonly ModelArchetypeMutability[];
+    readonly instancesPerParent?: readonly ('one' | 'many')[];
+    readonly aggregatesFromNonEmpty?: boolean;
+    readonly isGroupRoot?: boolean;
+    readonly isTreeNode?: boolean;
+}
+/**
+ * Catalog entry for one archetype. Shared by the recommender, lookup, search,
+ * resource, and heuristic extractor so they all read from one source of truth.
+ */
+export interface ModelArchetypeInfo {
+    readonly slug: ModelArchetypeSlug;
+    /**
+     * Family the archetype belongs to (`'standalone-entity'`, `'user-external-root'`, …).
+     * Surfaced in the catalog group headers and `_lookup` output so users can see
+     * sibling archetypes alongside the matched one.
+     */
+    readonly family: string;
+    /**
+     * Implied {@link FirestoreCollectionKind}. Some archetypes (e.g.
+     * `denormalised-aggregate`) accept more than one kind depending on axis
+     * values — the dominant kind is listed here and the alternative is recorded
+     * in `description`. The recommender's "Shape" block prints whichever value
+     * the questionnaire actually implies; this field is used by
+     * `dbx://model-archetype/by-collection-kind/{kind}` to filter the catalog.
+     */
+    readonly collectionKind: FirestoreCollectionKind;
+    /**
+     * First-paragraph narrative description, also printed by `_lookup`.
+     */
+    readonly description: string;
+    /**
+     * One-line guidance for "when to pick this" — appears in the catalog and
+     * single-entry views.
+     */
+    readonly whenToUse: string;
+    /**
+     * Optional extension-cluster name when this archetype hooks into one of the
+     * `_m` model-extension clusters (`storagefile_m`, `notification_m`,
+     * `system_m`). Absent for plain archetypes.
+     */
+    readonly extensionCluster?: 'storagefile_m' | 'notification_m' | 'system_m';
+    /**
+     * Canonical answer template the scorer compares each questionnaire against.
+     */
+    readonly expected: ModelArchetypeExpectedAnswers;
+    /**
+     * Axis name → allowed values. The recommender returns the resolved axis on
+     * its output; `_search` accepts an axes filter on these names.
+     */
+    readonly axes: {
+        readonly [axisName: string]: readonly string[];
+    };
+    /**
+     * Implementation pointers — skill names, sync-flag conventions, peer-search
+     * notes. Surfaced verbatim on the recommender's "Implementation pointers"
+     * bullet list.
+     */
+    readonly implementationPointers: readonly string[];
+    /**
+     * Optional comment shown alongside the slug — used to capture the
+     * "is/isn't" disambiguation hints (`external-id-keyed-entity-root` vs.
+     * `external-mirror`, `root-singleton-aggregate` vs.
+     * `system-state-singleton`, …).
+     */
+    readonly disambiguation?: string;
+}
+/**
+ * Full ordered catalog of every archetype. Order follows the planning doc's
+ * §2 grouping (standalone-entity → user/external roots → group → aggregate
+ * families → mirror/log/registry → framework → add-ons) so the catalog renders
+ * predictably.
+ */
+export declare const MODEL_ARCHETYPES: readonly ModelArchetypeInfo[];
+/**
+ * Resolves a slug to its archetype entry. Returns `undefined` for unknown
+ * slugs.
+ *
+ * @param slug - Archetype slug (`'root-entity'`, `'denormalised-aggregate'`, …)
+ * @returns The matching catalog entry, or `undefined` when no archetype uses the slug.
+ */
+export declare function getModelArchetypeBySlug(slug: ModelArchetypeSlug): ModelArchetypeInfo | undefined;
+/**
+ * Resolves a slug (case-insensitive) to its archetype entry. The canonical
+ * entry point for lookup tools.
+ *
+ * @param slug - Archetype slug.
+ * @returns The matching catalog entry, or `undefined` when no archetype uses the slug.
+ */
+export declare function resolveModelArchetype(slug: string): {
+    readonly archetype: ModelArchetypeInfo;
+} | undefined;
+/**
+ * Returns every catalog entry whose `expected.syncMode` includes the given
+ * sync mode. Useful for browsing by sync semantics
+ * (`dbx://model-archetype/by-sync-mode/{mode}`).
+ *
+ * @param mode - Sync mode to filter by.
+ * @returns Matching archetypes in declaration order.
+ */
+export declare function getModelArchetypesBySyncMode(mode: ModelArchetypeSyncMode): readonly ModelArchetypeInfo[];
+/**
+ * Returns every catalog entry whose implied `collectionKind` matches.
+ *
+ * @param kind - {@link FirestoreCollectionKind} to filter by.
+ * @returns Matching archetypes in declaration order.
+ */
+export declare function getModelArchetypesByCollectionKind(kind: FirestoreCollectionKind): readonly ModelArchetypeInfo[];
+/**
+ * Returns every catalog entry whose `axes[axisName]` includes the given value.
+ *
+ * @param axisName - Axis to filter on (e.g. `'subPurpose'`, `'keying'`)
+ * @param axisValue - The value to filter by.
+ * @returns Matching archetypes in declaration order.
+ */
+export declare function getModelArchetypesByAxisValue(axisName: string, axisValue: string): readonly ModelArchetypeInfo[];

package/src/lib/mcp-scan/registry/auth-builtin.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Curated baseline auth entries shipped with dbx-components-mcp.
+ *
+ * The auth catalog has two layers:
+ *
+ *   1. **Built-in (this file)** — `@dereekb/util` role consts, the
+ *      `@dereekb/firebase` storage-upload claim, and the five `model.*`
+ *      OIDC scopes from `@dereekb/firebase-server`. These are catalog
+ *      entries every dbx-components workspace inherits regardless of
+ *      which apps it ships.
+ *
+ *   2. **Downstream-loaded** — entries extracted from a downstream
+ *      app's `claims.ts` file at server-startup time. The
+ *      {@link loadAuthRegistry} loader walks `components/*-firebase`
+ *      and `apps/*` for files tagged with `@dbxAuthClaimsApp`,
+ *      `@dbxAuthClaimsService`, `@dbxAuthClaim`, and `@dbxAuthRoleTag`,
+ *      then merges the extracted entries with the layer-1 built-ins.
+ *
+ * The {@link WORKSPACE_AUTH_CLAIMS} / {@link WORKSPACE_AUTH_APPS}
+ * constants below mirror the workspace's demo claims module verbatim so
+ * tests can drive the auth tools without spinning up the loader. The
+ * production server bootstrap does NOT consume them — it goes through
+ * {@link loadAuthRegistry} to extract the same entries from disk.
+ */
+import type { AuthAppInfo, AuthClaimInfo, AuthRoleInfo, AuthScopeInfo } from './auth-runtime.js';
+/**
+ * Roles defined by `@dereekb/util` plus the `uploads` role contributed by
+ * `@dereekb/firebase`. Tags reflect the catalog convention used by
+ * downstream apps:
+ *
+ *   - `system`     — built-in role from a `@dereekb/*` package
+ *   - `auth`       — fundamental auth-state role
+ *   - `privileged` — admin / staff-level role
+ *   - `verified-user` — applies to vetted onboarded users
+ *   - `uploads`    — role gating storage uploads
+ */
+export declare const BUILTIN_AUTH_ROLES: readonly AuthRoleInfo[];
+/**
+ * Library-level custom claims. Today this is just the `fr` upload-restriction
+ * claim from `@dereekb/firebase`; downstream apps mix it into their own
+ * `*ApiAuthClaims` interfaces.
+ */
+export declare const BUILTIN_AUTH_CLAIMS: readonly AuthClaimInfo[];
+/**
+ * The five callModel CRUD scopes enforced by
+ * {@link oidcCallModelScopePreAssert}. App-specific scopes live in the
+ * downstream catalog layer.
+ */
+export declare const BUILTIN_AUTH_SCOPES: readonly AuthScopeInfo[];
+/**
+ * Workspace-level claim catalog (currently just the demo). Apps that live
+ * outside this workspace contribute their own entries through the
+ * downstream loader.
+ */
+export declare const WORKSPACE_AUTH_CLAIMS: readonly AuthClaimInfo[];
+/**
+ * Workspace-level app catalog (currently just demo-api).
+ */
+export declare const WORKSPACE_AUTH_APPS: readonly AuthAppInfo[];

package/src/lib/mcp-scan/registry/auth-runtime.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Auth runtime registry wrapper.
+ *
+ * Catalogs three related domains used to gate access in dbx-components apps:
+ *
+ *   - **roles**  — `AuthRole` strings used by the role-set permission model.
+ *     The well-known constants in `@dereekb/util` (admin, onboarded, tos,
+ *     user) are bundled by default; downstream apps can register additional
+ *     roles via tagged JSDoc on their own role consts or claims interfaces.
+ *
+ *   - **claims** — JWT custom-claim keys (e.g. `a`, `o`, `fr`) plus the role
+ *     mapping each one performs through {@link authRoleClaimsService}. Each
+ *     entry knows which `*ApiAuthClaims` interface declares it and which
+ *     app it belongs to.
+ *
+ *   - **scopes** — OAuth/OIDC scope names (`model.read`, `model.write`, …)
+ *     surfaced through the OIDC bridge, plus the source location where each
+ *     scope is enforced (e.g. `oidcCallModelScopePreAssert`).
+ *
+ *   - **apps**   — one entry per downstream app (demo-api, hellosubs-api).
+ *     Bundles the claims interface name, the claims-service constant name,
+ *     and the set of claim keys / scopes the app accepts.
+ *
+ * The registry is loaded once at server startup and passed into the tool
+ * factories. Tests can construct a registry from any entry array via
+ * {@link createAuthRegistryFromEntries} to drive the tools without touching
+ * disk.
+ */
+/**
+ * Whether an entry is a built-in `@dereekb/*` definition (`'system'`) or
+ * was contributed by a downstream app's catalog (`'app'`). Used by the
+ * lookup tools to label provenance and by the catalog to filter.
+ */
+export type AuthEntrySource = 'system' | 'app';
+/**
+ * One AuthRole entry.
+ */
+export interface AuthRoleInfo {
+    /**
+     * The string value of the role as it appears in an `AuthRoleSet`
+     * (`'admin'`, `'onboarded'`, `'uploads'`).
+     */
+    readonly role: string;
+    /**
+     * TypeScript constant name when the role originates from an exported
+     * const (e.g. `'AUTH_ADMIN_ROLE'`). Optional for app-defined roles
+     * declared inline.
+     */
+    readonly constName?: string;
+    /**
+     * Origin of the entry — `'system'` for `@dereekb/*` built-ins, `'app'`
+     * for catalog entries contributed by a downstream app.
+     */
+    readonly source: AuthEntrySource;
+    /**
+     * Workspace-relative path to the file that declares the role (or the
+     * mapping that introduces it).
+     */
+    readonly sourcePath: string;
+    /**
+     * 1-based line number of the role declaration. Optional — included
+     * when the extractor / hand-curated entry knows the line.
+     */
+    readonly sourceLine?: number;
+    /**
+     * One-line description.
+     */
+    readonly description: string;
+    /**
+     * Free-form catalog tags (e.g. `'privileged'`, `'verified-user'`).
+     * Tags come from `@dbxAuthRoleTag` JSDoc on the claim that maps to the
+     * role, or from the curated entry. Used by `dbx_auth_role_lookup` to
+     * filter.
+     */
+    readonly tags: readonly string[];
+}
+/**
+ * Role-mapping payload nested inside an {@link AuthClaimInfo}. Mirrors the
+ * shape of {@link AuthRoleClaimsFactoryConfigEntry} after normalisation —
+ * inverse vs forward, the resolved role list, and any non-default claim
+ * value.
+ */
+export interface AuthClaimRoleMappingInfo {
+    /**
+     * Roles set (or revoked, when `inverse` is true) by the claim.
+     */
+    readonly roles: readonly string[];
+    /**
+     * Whether the mapping is an inverse claim (claim presence revokes roles
+     * instead of granting them).
+     */
+    readonly inverse: boolean;
+    /**
+     * For inverse mappings, the SetIncludesMode controlling when the claim
+     * value is set during encoding.
+     */
+    readonly inverseMode?: 'any' | 'all';
+    /**
+     * Override claim value when set. `undefined` means the default
+     * ({@link DEFAULT_AUTH_ROLE_CLAIMS_CLAIM_VALUE}) is used.
+     */
+    readonly claimValue?: string | number | boolean;
+    /**
+     * Custom encode/decode entry — used by claims that don't fit the
+     * `roles` shape and supply functions instead. The presence of this
+     * field signals callers that the role list is approximate.
+     */
+    readonly customEncodeDecode: boolean;
+}
+/**
+ * One auth-claim entry.
+ */
+export interface AuthClaimInfo {
+    /**
+     * Claim key as it appears on the JWT custom-claims object (`'a'`,
+     * `'o'`, `'fr'`).
+     */
+    readonly key: string;
+    /**
+     * TypeScript-ish summary of the claim value type (e.g. `'1'`,
+     * `'StorageFileUploadUserRestriction'`).
+     */
+    readonly type: string;
+    /**
+     * One-line description of the claim's meaning.
+     */
+    readonly description: string;
+    /**
+     * Slug of the app that owns the claim (e.g. `'demo-api'`). `undefined`
+     * for shared library claims (e.g. `fr` from `@dereekb/firebase`).
+     */
+    readonly app?: string;
+    /**
+     * Name of the TypeScript interface that declares the claim
+     * (e.g. `'DemoApiAuthClaims'`, `'StorageFileUploadUserClaims'`).
+     */
+    readonly interfaceName?: string;
+    /**
+     * Workspace-relative path to the file declaring the claim.
+     */
+    readonly sourcePath: string;
+    /**
+     * 1-based line number of the claim's property declaration. Optional.
+     */
+    readonly sourceLine?: number;
+    /**
+     * Origin of the entry. App-owned claims are `'app'`; library claims
+     * (e.g. `fr`) are `'system'`.
+     */
+    readonly source: AuthEntrySource;
+    /**
+     * Role-mapping payload. Always present — every catalogued claim maps
+     * to at least one role (or revokes one for inverse claims).
+     */
+    readonly mapping: AuthClaimRoleMappingInfo;
+    /**
+     * Free-form catalog tags pulled from `@dbxAuthRoleTag` JSDoc on the
+     * claim's property declaration.
+     */
+    readonly tags: readonly string[];
+}
+/**
+ * Where a scope is enforced. Multiple entries are allowed when a scope is
+ * checked in more than one place (e.g. `model.read` is enforced by the
+ * callModel preAssert and by per-app middleware).
+ */
+export interface AuthScopeEnforcementInfo {
+    readonly path: string;
+    readonly line?: number;
+    /**
+     * One-line description of the gate (e.g. `'oidcCallModelScopePreAssert'`).
+     */
+    readonly description: string;
+}
+/**
+ * One OIDC scope entry.
+ */
+export interface AuthScopeInfo {
+    /**
+     * Full scope name (`'model.read'`, `'demo'`).
+     */
+    readonly scope: string;
+    /**
+     * Conventional prefix shared by a family of scopes
+     * (e.g. `'model.'` for the callModel CRUD scopes).
+     */
+    readonly prefix?: string;
+    /**
+     * Logical CRUD verb associated with the scope. `undefined` for app-
+     * specific or non-CRUD scopes.
+     */
+    readonly callType?: string;
+    /**
+     * One-line description.
+     */
+    readonly description: string;
+    /**
+     * Source files that declare or enforce the scope.
+     */
+    readonly enforcedAt: readonly AuthScopeEnforcementInfo[];
+    /**
+     * Error code thrown when the gate rejects a request. Optional.
+     */
+    readonly errorCode?: string;
+    /**
+     * Origin of the entry.
+     */
+    readonly source: AuthEntrySource;
+    /**
+     * Workspace-relative path to the file that defines the scope constant
+     * or scope catalog. Optional for app-defined scopes that don't have a
+     * single canonical declaration.
+     */
+    readonly sourcePath?: string;
+    /**
+     * 1-based line number of the scope declaration. Optional.
+     */
+    readonly sourceLine?: number;
+    /**
+     * Apps that surface this scope to callers (subset of the claim catalog
+     * apps). Empty for system scopes that aren't tied to a specific app.
+     */
+    readonly apps: readonly string[];
+}
+/**
+ * One per downstream app catalogued by the registry.
+ */
+export interface AuthAppInfo {
+    /**
+     * App slug — typically the Nx project name (`'demo-api'`).
+     */
+    readonly app: string;
+    /**
+     * `*ApiAuthClaims`-style interface name declared by the app
+     * (e.g. `'DemoApiAuthClaims'`).
+     */
+    readonly claimsInterfaceName: string;
+    /**
+     * Constant exported by the app's `claims.ts` for the
+     * {@link authRoleClaimsService} return value (e.g. `'DEMO_AUTH_CLAIMS_SERVICE'`).
+     */
+    readonly serviceConstName?: string;
+    /**
+     * Workspace-relative path to the app's `claims.ts` (or equivalent).
+     */
+    readonly sourcePath: string;
+    /**
+     * Claim keys catalogued for the app.
+     */
+    readonly claimKeys: readonly string[];
+    /**
+     * OIDC scope names accepted by the app, in registry order.
+     */
+    readonly scopes: readonly string[];
+    /**
+     * Optional one-line summary of what the app's auth surface gates.
+     */
+    readonly description?: string;
+}
+/**
+ * Domain-friendly read API over the merged auth catalog.
+ */
+export interface AuthRegistry {
+    readonly roles: readonly AuthRoleInfo[];
+    readonly claims: readonly AuthClaimInfo[];
+    readonly scopes: readonly AuthScopeInfo[];
+    readonly apps: readonly AuthAppInfo[];
+    readonly loadedSources: readonly string[];
+    /**
+     * Returns the role entry whose `role` string or `constName` matches
+     * `key` (case-insensitive). Returns `undefined` when no entry matches.
+     */
+    findRole(key: string): AuthRoleInfo | undefined;
+    /**
+     * Returns every role tagged with the given tag (case-insensitive).
+     */
+    findRolesByTag(tag: string): readonly AuthRoleInfo[];
+    /**
+     * Returns the claim entry whose `key` matches `key` exactly. When
+     * `app` is supplied the lookup is scoped to that app; otherwise the
+     * first match in registry order wins.
+     */
+    findClaim(key: string, app?: string): AuthClaimInfo | undefined;
+    /**
+     * Returns every claim catalogued for the given app (case-insensitive).
+     */
+    findClaimsByApp(app: string): readonly AuthClaimInfo[];
+    /**
+     * Returns every claim whose `interfaceName` matches `interfaceName`
+     * (case-insensitive). Useful when callers know the type name but not
+     * the app slug.
+     */
+    findClaimsByInterface(interfaceName: string): readonly AuthClaimInfo[];
+    /**
+     * Returns the scope entry whose `scope` matches exactly. Case-sensitive
+     * because OIDC scope names are case-sensitive.
+     */
+    findScope(scope: string): AuthScopeInfo | undefined;
+    /**
+     * Returns the app entry whose slug matches `app` exactly
+     * (case-insensitive).
+     */
+    findApp(app: string): AuthAppInfo | undefined;
+    /**
+     * Returns the app entry whose `claimsInterfaceName` matches
+     * (case-insensitive).
+     */
+    findAppByInterface(interfaceName: string): AuthAppInfo | undefined;
+    /**
+     * Returns every role that is set (or revoked) by at least one claim.
+     * Combined with the claim catalog this lets `dbx_auth_role_lookup`
+     * answer "which claims set this role?".
+     */
+    findClaimsForRole(role: string): readonly AuthClaimInfo[];
+}
+/**
+ * Input to {@link createAuthRegistryFromEntries}. Every field is optional
+ * to make registry composition easy in tests.
+ */
+export interface CreateAuthRegistryFromEntriesInput {
+    readonly roles?: readonly AuthRoleInfo[];
+    readonly claims?: readonly AuthClaimInfo[];
+    readonly scopes?: readonly AuthScopeInfo[];
+    readonly apps?: readonly AuthAppInfo[];
+    readonly loadedSources?: readonly string[];
+}
+/**
+ * Builds an {@link AuthRegistry} from raw entry arrays. The constructed
+ * registry indexes by every accessor's primary key so all lookups are O(1)
+ * after construction.
+ *
+ * @param input - The entry arrays plus the source labels to advertise.
+ * @returns A fully-indexed registry suitable for tools and resources.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createAuthRegistryFromEntries(input?: CreateAuthRegistryFromEntriesInput): AuthRegistry;
+/**
+ * Empty registry used when no auth catalog has been loaded. Tools wired
+ * against this registry behave as if the catalog loaded successfully with
+ * zero entries.
+ */
+export declare const EMPTY_AUTH_REGISTRY: AuthRegistry;