@odla-ai/chapter 0.46.0 → 0.47.0

package/dist/index.d.cts

@@ -604,7 +604,7 @@ interface ChapterScheduling {
  *
  * - `"claim"` reads a role ladder from a JWT claim (the member-site model:
  *   `provisional → member → admin`). Admin is the last (highest) rung; the
- *   read-only `superAdmins` tier sits above it.
+ *   Studio-managed super-admin tier sits above it.
  * - `"table"` gates on the deny-all `admins` allowlist (the hub model):
  *   a binary "email is an admin or isn't", set only in odla Studio.
  *
@@ -616,10 +616,13 @@ interface ChapterAuth {
     /** Role ladder low→high, for `source: "claim"`. The last entry is admin.
      *  Default `["provisional", "member", "admin"]`. */
     ladder?: readonly string[];
-    /** Provision the read-only `superAdmins` tier table — the only tier that may
-     *  create/modify admins, and (like every namespace) deny-all + written only in
-     *  odla Studio. Default: `true` for `"claim"`, `false` for `"table"`. */
+    /** Enable the Studio-managed super-admin tier — the only tier that may
+     *  create/modify admins. Default: `true` for `"claim"`, `false` for `"table"`. */
     superAdmins?: boolean;
+    /** Authority behind the super-admin tier. `"table"` preserves the legacy
+     * app allowlist; `"odla"` reads protected `$users.role`. Default `"table"`
+     * for backward compatibility. */
+    superAdminSource?: "table" | "odla";
 }
 /** The fully-resolved auth policy (defaults applied) carried on the {@link Chapter}. */
 interface ResolvedAuth {
@@ -629,6 +632,7 @@ interface ResolvedAuth {
     /** The highest ladder rung (last entry) — the "admin" gate. */
     adminRole: string;
     superAdmins: boolean;
+    superAdminSource: "none" | "table" | "odla";
 }
 /** The application status pipeline. Which statuses exist, and the subsets a site
  *  allows a call to be booked from / an application approved from. Defaults to
@@ -1199,8 +1203,9 @@ declare function createChapterIntegration(chapter: Chapter, options?: ChapterInt
  *
  * Operational tables (`applications`/`groups`/`meetings`/`emailLog`) are added in
  * `chapter` mode only. The auth tables follow {@link ResolvedAuth}: `source:
- * "table"` adds the `admins` allowlist (hub/BNF); `superAdmins` adds the
- * read-only super-admin tier (default on for the `"claim"` ladder). A `"claim"`
+ * "table"` adds the `admins` allowlist (hub/BNF); `superAdminSource: "table"`
+ * adds the legacy read-only super-admin tier (the backward-compatible default).
+ * `superAdminSource: "odla"` uses reserved `$users` and adds no app namespace. A `"claim"`
  * chapter therefore emits the reference namespace set — `applications`,
  * `groups`, `meetings`, `emailLog`, `stripeEventReceipts`, `superAdmins` — with
  * no `admins` table. */
@@ -1563,6 +1568,8 @@ declare function buildGroupSeed(config: ChapterConfig): Record<string, unknown>;
  * Apply defaults + validate the auth config into a {@link ResolvedAuth}. Defaults
  * by mode: `chapter` → the `provisional/member/admin` claim ladder with the
  * `superAdmins` tier; `hub` → the `admins` allowlist table with no super tier.
+ * Existing sites retain the legacy `superAdmins` table unless they explicitly
+ * select protected odla user roles.
  * Throws at import on a bad policy.
  */
 declare function resolveAuth(mode: ChapterMode, auth: ChapterAuth | undefined): ResolvedAuth;
@@ -1572,7 +1579,7 @@ declare function roleFromClaim(payload: Record<string, unknown>, auth: ResolvedA
 /** Does a role meet the admin bar (the highest ladder rung)? */
 declare function isAdminRole(role: string, auth: ResolvedAuth): boolean;
 /** Inputs to the role-change guard — resolved by the caller (route) from the
- *  identity provider + the read-only `superAdmins` table. */
+ *  identity provider + the configured Studio-managed super-admin authority. */
 interface RoleChangeContext {
     actorId: string;
     actorIsSuper: boolean;
@@ -1596,8 +1603,8 @@ type GuardResult = {
  * none re-derives it. Denies: an out-of-ladder role; changing your own role;
  * touching a super-admin unless you are one; and (when a `superAdmins` tier
  * exists) creating or altering an admin unless you are a super-admin. Note the
- * super-admin tier itself is never writable here — it lives in the read-only
- * `superAdmins` table, set only in odla Studio.
+ * super-admin tier itself is never writable here — it is set only in odla
+ * Studio, either as a protected `$users.role` or in the legacy allowlist.
  */
 declare function canChangeRole(ctx: RoleChangeContext): GuardResult;
 /** Structural view of odla-db's tenant-vault read, so chapter takes no runtime

package/dist/index.d.ts

@@ -604,7 +604,7 @@ interface ChapterScheduling {
  *
  * - `"claim"` reads a role ladder from a JWT claim (the member-site model:
  *   `provisional → member → admin`). Admin is the last (highest) rung; the
- *   read-only `superAdmins` tier sits above it.
+ *   Studio-managed super-admin tier sits above it.
  * - `"table"` gates on the deny-all `admins` allowlist (the hub model):
  *   a binary "email is an admin or isn't", set only in odla Studio.
  *
@@ -616,10 +616,13 @@ interface ChapterAuth {
     /** Role ladder low→high, for `source: "claim"`. The last entry is admin.
      *  Default `["provisional", "member", "admin"]`. */
     ladder?: readonly string[];
-    /** Provision the read-only `superAdmins` tier table — the only tier that may
-     *  create/modify admins, and (like every namespace) deny-all + written only in
-     *  odla Studio. Default: `true` for `"claim"`, `false` for `"table"`. */
+    /** Enable the Studio-managed super-admin tier — the only tier that may
+     *  create/modify admins. Default: `true` for `"claim"`, `false` for `"table"`. */
     superAdmins?: boolean;
+    /** Authority behind the super-admin tier. `"table"` preserves the legacy
+     * app allowlist; `"odla"` reads protected `$users.role`. Default `"table"`
+     * for backward compatibility. */
+    superAdminSource?: "table" | "odla";
 }
 /** The fully-resolved auth policy (defaults applied) carried on the {@link Chapter}. */
 interface ResolvedAuth {
@@ -629,6 +632,7 @@ interface ResolvedAuth {
     /** The highest ladder rung (last entry) — the "admin" gate. */
     adminRole: string;
     superAdmins: boolean;
+    superAdminSource: "none" | "table" | "odla";
 }
 /** The application status pipeline. Which statuses exist, and the subsets a site
  *  allows a call to be booked from / an application approved from. Defaults to
@@ -1199,8 +1203,9 @@ declare function createChapterIntegration(chapter: Chapter, options?: ChapterInt
  *
  * Operational tables (`applications`/`groups`/`meetings`/`emailLog`) are added in
  * `chapter` mode only. The auth tables follow {@link ResolvedAuth}: `source:
- * "table"` adds the `admins` allowlist (hub/BNF); `superAdmins` adds the
- * read-only super-admin tier (default on for the `"claim"` ladder). A `"claim"`
+ * "table"` adds the `admins` allowlist (hub/BNF); `superAdminSource: "table"`
+ * adds the legacy read-only super-admin tier (the backward-compatible default).
+ * `superAdminSource: "odla"` uses reserved `$users` and adds no app namespace. A `"claim"`
  * chapter therefore emits the reference namespace set — `applications`,
  * `groups`, `meetings`, `emailLog`, `stripeEventReceipts`, `superAdmins` — with
  * no `admins` table. */
@@ -1563,6 +1568,8 @@ declare function buildGroupSeed(config: ChapterConfig): Record<string, unknown>;
  * Apply defaults + validate the auth config into a {@link ResolvedAuth}. Defaults
  * by mode: `chapter` → the `provisional/member/admin` claim ladder with the
  * `superAdmins` tier; `hub` → the `admins` allowlist table with no super tier.
+ * Existing sites retain the legacy `superAdmins` table unless they explicitly
+ * select protected odla user roles.
  * Throws at import on a bad policy.
  */
 declare function resolveAuth(mode: ChapterMode, auth: ChapterAuth | undefined): ResolvedAuth;
@@ -1572,7 +1579,7 @@ declare function roleFromClaim(payload: Record<string, unknown>, auth: ResolvedA
 /** Does a role meet the admin bar (the highest ladder rung)? */
 declare function isAdminRole(role: string, auth: ResolvedAuth): boolean;
 /** Inputs to the role-change guard — resolved by the caller (route) from the
- *  identity provider + the read-only `superAdmins` table. */
+ *  identity provider + the configured Studio-managed super-admin authority. */
 interface RoleChangeContext {
     actorId: string;
     actorIsSuper: boolean;
@@ -1596,8 +1603,8 @@ type GuardResult = {
  * none re-derives it. Denies: an out-of-ladder role; changing your own role;
  * touching a super-admin unless you are one; and (when a `superAdmins` tier
  * exists) creating or altering an admin unless you are a super-admin. Note the
- * super-admin tier itself is never writable here — it lives in the read-only
- * `superAdmins` table, set only in odla Studio.
+ * super-admin tier itself is never writable here — it is set only in odla
+ * Studio, either as a protected `$users.role` or in the legacy allowlist.
  */
 declare function canChangeRole(ctx: RoleChangeContext): GuardResult;
 /** Structural view of odla-db's tenant-vault read, so chapter takes no runtime

package/dist/index.js

@@ -801,7 +801,7 @@ function chapterDb(mode, auth, includeNetworkNotes = false, application = resolv
     }
   }
   if (auth.source === "table") entities.admins = admins;
-  if (auth.superAdmins) entities.superAdmins = superAdmins;
+  if (auth.superAdminSource === "table") entities.superAdmins = superAdmins;
   if (includeNetworkNotes) entities.networkNotes = networkNotes;
   if (includeBuilderLibrary) {
     entities.builderLibraryControls = builderLibraryControls;
@@ -984,7 +984,12 @@ function resolveAuth(mode, auth) {
   }
   const adminRole = ladder[ladder.length - 1];
   const superAdmins2 = a.superAdmins ?? source === "claim";
-  return { source, claim, ladder, adminRole, superAdmins: superAdmins2 };
+  const configuredSuperSource = a.superAdminSource ?? "table";
+  if (configuredSuperSource !== "table" && configuredSuperSource !== "odla") {
+    throw new Error(`defineChapter.auth.superAdminSource: must be "table" or "odla" \u2014 got ${JSON.stringify(a.superAdminSource)}`);
+  }
+  const superAdminSource = superAdmins2 ? configuredSuperSource : "none";
+  return { source, claim, ladder, adminRole, superAdmins: superAdmins2, superAdminSource };
 }
 function roleFromClaim(payload, auth) {
   const raw2 = payload[auth.claim];