@reflagged/shell 1.2.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,11 +1,12 @@
 {
   "name": "@reflagged/shell",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Shared app shell for Reflagged services — OIDC auth, SSO, app switcher",
   "type": "module",
   "sideEffects": false,
   "files": [
     "src",
+    "!src/**/*.test.ts",
     "tsconfig.json",
     "README.md"
   ],
@@ -29,28 +30,30 @@
     "./components/ServiceIcon": "./src/components/ServiceIcon.tsx"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
     "jose": "^5.10.0",
     "oauth4webapi": "^3.6.0"
   },
   "peerDependencies": {
+    "lucide-react": ">=0.400.0",
     "next": "^15.4.0",
     "payload": "^3.79.0",
     "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "lucide-react": ">=0.400.0"
+    "react-dom": "^19.2.0"
   },
   "devDependencies": {
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
+    "lucide-react": "^0.500.0",
     "next": "^15.4.0",
     "payload": "^3.79.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "typescript": "^5.7.0",
-    "lucide-react": "^0.500.0"
+    "vitest": "^3.2.0"
   },
   "peerDependenciesMeta": {
     "lucide-react": {

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

@@ -5,46 +5,123 @@ import { loadAppConfig } from '../../config'
 import { OIDC_COOKIE } from './oidc-config'
 import { verifySessionCookie } from './oidc-cookie'
 
-export const nextauthStrategy: AuthStrategy = {
-  name: 'rflgd-oidc',
-  authenticate: async ({ payload, headers }) => {
-    const secret = process.env.AUTH_SECRET
-    if (!secret) return { user: null }
-
-    const cookieHeader = headers.get('cookie') ?? ''
-    const cookieStart = `${OIDC_COOKIE}=`
-    const segment = cookieHeader
-      .split(';')
-      .map((c) => c.trim())
-      .find((c) => c.startsWith(cookieStart))
-    if (!segment) return { user: null }
-
-    const token = segment.slice(cookieStart.length)
-    const session = await verifySessionCookie(secret, token)
-    if (!session?.email) return { user: null }
-
-    const existing = await payload.find({
-      collection: 'users',
-      where: { email: { equals: session.email } },
-      limit: 1,
-      overrideAccess: true,
-    })
-
-    let user = existing.docs[0]
-    if (!user) {
-      const config = loadAppConfig()
-      const isFirst = (await payload.count({ collection: 'users', overrideAccess: true })).totalDocs === 0
-      user = await payload.create({
+/** What the platform knows about a person signing in for the first time. */
+export type NewUserContext = {
+  /**
+   * 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
+  email: string
+  /** True when this account is the first in the instance. */
+  isFirstUser: boolean
+}
+
+/** Maps the platform's view of a person onto one of this app's own roles. */
+export type RoleForNewUser = (ctx: NewUserContext) => string
+
+/**
+ * The role a newly created account receives.
+ *
+ * Without a callback this is exactly what it always was: the first account
+ * administers, everyone after it gets RFLGD_DEFAULT_USER_ROLE. With a
+ * callback the decision belongs entirely to the app, `isFirstUser` included —
+ * which is why it is in the context. An app that forgets that branch can end
+ * up with an instance that has no administrator.
+ *
+ * The return value is not checked. Which roles exist is the app's knowledge;
+ * an unknown value is rejected by Payload against the field configuration and
+ * the account is not created. That is the same path on which this package's
+ * own default 'user' once locked instances out.
+ */
+export function resolveNewUserRole(
+  ctx: NewUserContext,
+  roleForNewUser?: RoleForNewUser,
+): string {
+  if (roleForNewUser) return roleForNewUser(ctx)
+  return ctx.isFirstUser ? 'admin' : loadAppConfig().defaultRole
+}
+
+/**
+ * Payload auth strategy for the platform's single sign-on.
+ *
+ * Creates an account on first sign-in when none exists for the address. The
+ * role it gets is `resolveNewUserRole`'s decision — see there.
+ */
+export function createOidcStrategy(options?: {
+  roleForNewUser?: RoleForNewUser
+}): AuthStrategy {
+  return {
+    name: 'rflgd-oidc',
+    authenticate: async ({ payload, headers }) => {
+      const secret = process.env.AUTH_SECRET
+      if (!secret) return { user: null }
+
+      const cookieHeader = headers.get('cookie') ?? ''
+      const cookieStart = `${OIDC_COOKIE}=`
+      const segment = cookieHeader
+        .split(';')
+        .map((c) => c.trim())
+        .find((c) => c.startsWith(cookieStart))
+      if (!segment) return { user: null }
+
+      const token = segment.slice(cookieStart.length)
+      const session = await verifySessionCookie(secret, token)
+      if (!session?.email) return { user: null }
+
+      const existing = await payload.find({
         collection: 'users',
-        data: {
-          email: session.email,
-          password: randomBytes(32).toString('hex'),
-          role: isFirst ? 'admin' : config.defaultRole,
-        },
+        where: { email: { equals: session.email } },
+        limit: 1,
         overrideAccess: true,
       })
-    }
 
-    return { user: { ...user, collection: 'users' } }
-  },
+      let user = existing.docs[0]
+      if (!user) {
+        const isFirstUser =
+          (await payload.count({ collection: 'users', overrideAccess: true })).totalDocs === 0
+        const role = resolveNewUserRole(
+          {
+            orgRole: session.orgRole ?? null,
+            platformRole: session.platformRole ?? null,
+            email: session.email,
+            isFirstUser,
+          },
+          options?.roleForNewUser,
+        )
+        user = await payload.create({
+          collection: 'users',
+          data: {
+            email: session.email,
+            password: randomBytes(32).toString('hex'),
+            // `role` comes from the environment or the app and is therefore a
+            // `string`. The host application narrows `users.role` to the
+            // options of its own collection — this package cannot know that
+            // type. The value is checked by Payload against the field
+            // configuration on write; an unknown one is rejected there.
+            role: role as never,
+          },
+          overrideAccess: true,
+        })
+      }
+
+      return { user: { ...user, collection: 'users' } }
+    },
+  }
 }
+
+/**
+ * The strategy without options — the export every consumer used before this
+ * package learned about role translation. Kept so nothing has to change.
+ */
+export const nextauthStrategy: AuthStrategy = createOidcStrategy()