@odla-ai/chapter 0.47.10 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/chapter",
-  "version": "0.47.10",
+  "version": "0.48.0",
   "description": "A leader/follower foundation for branded membership sites: shared CRM, admin, auth, payments, booking, and explicit record delivery from one defineChapter config.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/chapter",
@@ -79,15 +79,15 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@odla-ai/crm": ">=0.9.2 <0.10.0",
+    "@odla-ai/crm": ">=0.10.0 <0.11.0",
     "@odla-ai/promotion": "0.1.0",
-    "@odla-ai/stripe": ">=0.1.0 <1.0.0",
+    "@odla-ai/stripe": ">=0.1.1 <1.0.0",
     "jose": "^6.2.3"
   },
   "peerDependencies": {
-    "@odla-ai/auth-clerk": ">=0.4.1 <1.0.0",
+    "@odla-ai/auth-clerk": ">=0.5.0 <1.0.0",
     "@odla-ai/calendar": ">=0.2.0 <1.0.0",
-    "@odla-ai/db": ">=0.9.0 <1.0.0",
+    "@odla-ai/db": ">=0.14.0 <1.0.0",
     "@odla-ai/ui": ">=0.20.0 <1.0.0",
     "preact": ">=10.29.7 <11"
   },

package/runbooks/adopt-existing.md

@@ -531,7 +531,10 @@ leader and follower are different websites and use different Clerk
 applications, publishable keys, issuers, roles, and local session tokens. A
 Clerk JWT never authenticates a cross-site delivery.
 
-Chapter claim mode requires session claims for both email and role; hub table
+Prefer explicit `auth: { source: "clerk", superAdminSource: "odla" }` for
+backend-only authorization. It resolves `private_metadata.role` from Clerk on
+each check and never falls back to public metadata or a session role claim.
+Legacy claim mode requires session claims for both email and role; hub table
 mode uses lowercase `admins` rows. Prove signed-out, allowed, forbidden,
 provisional, member, admin, super-admin, malformed, expired, wrong-issuer,
 sign-out, and return-target behavior. If the site's verifier intentionally
@@ -541,17 +544,50 @@ fixtures. If it never enforced those claims, mark those two cases `n/a` only
 after the full matrix is recorded; do not call their absence an auth success or
 use it to skip the remaining authorization tests.
 
-When Chapter needs server-side account/role operations, set the named
-app-readable `clerk_secret_key` through:
+When Chapter needs server-side account/role operations, use the existing
+environment-scoped reserved credential (Chapter reads its effective
+`clerk_secret_key` alias):
 
 ```sh
-npx odla-ai secrets set clerk_secret_key --env dev --stdin
+npx odla-ai secrets set-clerk-key --env dev --stdin
 ```
 
-Do not substitute `secrets set-clerk-key`; it writes the platform-reserved
-`$clerk_secret`, which Chapter cannot read under the named key. The generic
-command does not validate Clerk instance prefixes: independently confirm dev
-uses `sk_test_`. Never put `sk_live_` in dev.
+Do not create a second secret pair. Confirm the selected instance and dev
+`sk_test_` status without printing the secret; never put `sk_live_` in dev.
+
+#### Coordinated dev private-role cutover
+
+1. Resolve every active runtime sharing the app's dev Clerk instance from odla.
+   All developer sandboxes are authoritative; do not infer the inventory from
+   one checkout or change a peer's deployment without authority.
+2. Have the human grant an existing operator's exact Clerk subject the protected
+   app-scoped role through odla Studio → Database → Users. Confirm an active,
+   nondeleted `$users` row. Never copy a legacy `superAdmins` row, email match,
+   or Clerk metadata value into a protected grant. Keep its ordinary Clerk
+   admin role separate. Do not switch live auth with no protected operator.
+3. Stage compatible private-role readers AND writers in every runtime. Pause
+   role-changing approval/refund/seat/admin operations everywhere during
+   migration; do not leave a legacy writer racing a private writer.
+4. Backend-read all Clerk users and run `planPrivateRoleMigration` with the exact
+   dev inventory, reviewed runtime versions/readiness, and existing protected
+   subject IDs. Resolve malformed/unknown/conflicting roles before proceeding.
+   The helper is dry-run only; a ready result is not a remote lock or write grant.
+5. For each reviewed change, re-read and compare both role fields immediately
+   before the metadata PATCH. If either changed, stop and regenerate the plan.
+   Merge the approved role into `private_metadata.role`, removing only the old
+   public role key; preserve unrelated metadata. Re-read to verify each result.
+   Keep writers paused throughout; regenerate the plan on interrupted resume.
+6. Switch all participating runtimes to the private configuration together and
+   verify admin/member access, denied stale/public-only admin claims, exact-ID
+   protected authority, and same-session promotion/revocation. Remove the unused
+   public role session claim only after every relying runtime is migrated.
+   Exercise approval, refund, seat, and admin role changes against the same
+   private field before resuming normal writes.
+7. Do not roll back only the Worker to a public-role reader after metadata has
+   migrated. Keep writes paused and review a coordinated recovery using fresh
+   provider state. Never replay a stale role snapshot or automatically recreate
+   public privileges. Old allowlist rows may remain stored but have no authority
+   in protected mode; deleting them is not required for this cutover.
 
 Chapter now reserves `public_metadata` for the small authorization role and
 stores its `applicationId`/allowlisted profile snapshot in backend-only