@odla-ai/chapter 0.46.0 → 0.47.0

package/README.md

@@ -1511,8 +1511,10 @@ These bite silently — a smoke test won't catch them:
 - **Bootstrap the first admin according to the selected auth source.** Chapter
   mode defaults to Clerk claims: set the first operator's Clerk
   `public_metadata.role` to `admin`. If that operator also needs the
-  read-only cross-site tier, add their lowercase email to `superAdmins` in odla
-  Studio. Hub mode defaults to table auth: add the first operator's lowercase
+  super-admin tier, prefer `auth: { superAdminSource: "odla" }` and grant their
+  app-scoped role on Database → Users in odla Studio. Existing sites retain the
+  legacy `superAdmins` table until they opt in. Hub mode defaults to table auth:
+  add the first operator's lowercase
   email to `admins` in Studio. Neither allowlist is ever written by a worker
   route or provisioning seed; that is deliberate, so the running app cannot
   grant itself admin. Confirm the result by signing in, not merely by inspecting

package/dist/{copy-context-GaxckY3T.d.ts → copy-context-20WFI5TI.d.ts}

@@ -458,7 +458,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.
  *
@@ -470,10 +470,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 {
@@ -483,6 +486,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

package/dist/index.cjs

@@ -1015,7 +1015,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;
@@ -1198,7 +1198,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];