@reflagged/shell 1.3.0 → 1.3.1

package/README.md

@@ -46,9 +46,39 @@ import { loadAppConfig } from '@reflagged/shell/config'
 import { OIDC_COOKIE, loadOidcEnv } from '@reflagged/shell/auth/oidc-config'
 import { verifySessionCookie } from '@reflagged/shell/auth/oidc-cookie'
 import { refreshAccessToken } from '@reflagged/shell/auth/oidc-refresh'
-import { nextauthStrategy } from '@reflagged/shell/auth/nextauth-strategy'
+import { nextauthStrategy, createOidcStrategy } from '@reflagged/shell/auth/nextauth-strategy'
 ```
 
+### Mapping the platform's role onto your own (`roleForNewUser`)
+
+`nextauthStrategy` is `createOidcStrategy()` with no options — the role a
+newly created account gets is `RFLGD_DEFAULT_USER_ROLE` (or `admin` for the
+very first account). Call `createOidcStrategy` directly to decide that role
+yourself from the platform's view of the person, using the workspace role
+the platform put in the session:
+
+```ts
+import { createOidcStrategy, type NewUserContext } from '@reflagged/shell/auth/nextauth-strategy'
+
+function roleForNewUser({ orgRole, isFirstUser }: NewUserContext): string {
+  if (isFirstUser) return 'admin'
+  // org_role is three-valued, not two: 'owner' | 'admin' | 'member' when a
+  // membership row exists (both 'owner' and 'admin' administer the
+  // workspace), or a *platform* role — 'superadmin' | 'reflagged_admin' |
+  // 'tenant_admin' | 'member' — when it does not. Check for 'owner' as well
+  // as 'admin': the person who books an instance is always created as
+  // 'owner', never 'admin'.
+  return orgRole === 'owner' || orgRole === 'admin' ? 'workspace-admin' : 'member'
+}
+
+export const oidcStrategy = createOidcStrategy({ roleForNewUser })
+```
+
+This callback runs only when an account is created, never on later
+sign-ins — see `NewUserContext`'s doc comments in
+`src/lib/auth/nextauth-strategy.ts` for the full contract, including the
+`isFirstUser` branch and the `null` case for standalone operation.
+
 ### Per-app route files + middleware
 
 Each app keeps thin wrappers that re-export the handlers:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reflagged/shell",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Shared app shell for Reflagged services — OIDC auth, SSO, app switcher",
   "type": "module",
   "sideEffects": false,

package/src/lib/auth/nextauth-strategy.ts

@@ -7,7 +7,18 @@ import { verifySessionCookie } from './oidc-cookie'
 
 /** What the platform knows about a person signing in for the first time. */
 export type NewUserContext = {
-  /** Role in the current workspace ('admin' | 'member'), null without claims. */
+  /**
+   * Role in the current workspace, when a membership row exists for it:
+   * 'owner' | 'admin' | 'member'. When no membership row exists, the
+   * platform substitutes a *platform* role instead — 'superadmin' |
+   * 'reflagged_admin' | 'tenant_admin' | 'member' — a second, unrelated
+   * vocabulary in the same field (rflgd-base `src/lib/oidc/provider.ts:163`,
+   * `org_role: orgRole ?? userRole ?? null`). Only `null` without any claims
+   * at all. Callers that special-case 'admin' should check 'owner' too —
+   * rflgd-base always creates the booking person's membership with
+   * 'owner', never 'admin' (`src/lib/access/service-access.ts:20` treats
+   * both as equally privileged).
+   */
   orgRole: string | null
   /** Role on the platform itself, null without claims. */
   platformRole: string | null