feat(operator): invite operator → creates user in Authentik

New "Invite operator" button + modal on /operator-team. Replaces the
bounce-to-Authentik flow with an inline invite that creates the user via
the Authentik API and pre-populates our local User doc so they appear
immediately.

services/platform-api/src/integrations/authentik.client.ts:
  - findUserByEmail(): early-conflict check before we attempt the create
  - createUser(): POST /core/users/ with username = email, internal type,
    is_active, attached to the supplied group PKs
  - addUserToGroup(): kept for tenant-member invites later
  - recoveryLink(): tries POST /core/users/{pk}/recovery/, returns
    undefined when no recovery flow is configured on the Authentik brand
    (we soft-fail and the service falls back to setInitialPassword)
  - setInitialPassword(): POST /core/users/{pk}/set_password/. Returns 204
    No Content so we bypass request<T>'s JSON parser and call fetch
    directly with explicit ok check.

services/platform-api/src/users/users.service.ts:
  - inviteOperator(dto, actor) orchestrates: dedup by email →
    findOrCreate Authentik group → create user in group → pre-create
    local User doc with platformAdmin=true so the list reflects them
    immediately → try recovery link → fall back to temp password →
    record platform.user_invited audit event with handoff method.
  - Return type is { subject, userId, link? | tempPassword? } —
    exactly one credential mode set depending on Authentik config.
  - generateTempPassword(): 16-char with at least one upper/lower/digit/
    symbol, shuffled. Confusable chars (I/O/0/1/l) omitted.
  - Cached platform-admin group ID after first lookup.

services/platform-api/src/users/users.controller.ts:
  - POST /users/invite behind OperatorGuard. Calls the service with
    actor + IP from the JWT/request.

apps/operator:
  - server/api/users/invite.post.ts: standard platformApi proxy.
  - components/InviteOperatorModal.vue: 2-step form. Step 1: name +
    email with client-side validation. Step 2: shows whichever
    credential the backend returned — recovery link OR username+
    temp-password — with copy-to-clipboard buttons and a note about
    SMTP/recovery-flow follow-up paths.
  - pages/operator-team.vue: "Invite operator" replaces "Manage in
    Authentik" as the primary action; Authentik link demoted to
    secondary. Refreshes the list on @invited so the new user shows
    up without a manual reload.

Verified end-to-end against real Authentik:
  - Invite created user pk=7, uid=f22f2bb…, group=dezky-platform-admins,
    is_active=true, temp password set. Modal showed both fields with
    copy buttons; operator-team count went 1 → 2 immediately. Audit
    event recorded (platform.user_invited with handoff='temp-password').
  - Recovery link path is preferred but Authentik has no recovery flow
    configured on the default brand. AuthentikClient.recoveryLink()
    soft-fails on the "No recovery flow set." 400, returns undefined,
    and inviteOperator transparently falls back to set_password. Once
    a recovery flow is configured (Authentik admin → Flows), the link
    path becomes active and the temp-password path stops firing
    without any code changes.

Known follow-ups:
  - Configure Authentik recovery flow so the link path activates
    (one-time admin task, not in code)
  - Outbound SMTP wiring (Phase 5/6) → Authentik can email link/temp
    directly; modal stops showing the credential
  - Deactivate / remove operator from inside the app (currently still
    Authentik UI; defensible until proven needed)
  - Tenant-member invite — similar flow but adds to tenant group
    instead, exposed from /users (global users) or tenant detail

apps/operator/components/InviteOperatorModal.vue

@@ -0,0 +1,301 @@
+<script setup lang="ts">
+// Operator-only modal that creates a new platform admin in Authentik and
+// surfaces the recovery link for the operator to share manually. Once
+// outbound SMTP is wired, Authentik can email the link directly and we'll
+// drop the "share manually" affordance from this modal.
+
+interface InviteResult {
+  subject: string
+  userId: string
+  // Exactly one is set — recovery link when Authentik has a recovery flow,
+  // temp password as a fallback when it doesn't.
+  link?: string
+  tempPassword?: string
+}
+
+const props = defineProps<{ open: boolean }>()
+const emit = defineEmits<{ close: []; invited: [InviteResult] }>()
+
+const name = ref('')
+const email = ref('')
+const busy = ref(false)
+const error = ref<string | null>(null)
+const result = ref<InviteResult | null>(null)
+const copied = ref(false)
+
+// Reset state every time the modal opens so previous results don't linger.
+watch(
+  () => props.open,
+  (v) => {
+    if (v) {
+      name.value = ''
+      email.value = ''
+      busy.value = false
+      error.value = null
+      result.value = null
+      copied.value = false
+    }
+  },
+)
+
+onMounted(() => {
+  const onKey = (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && props.open && !busy.value) emit('close')
+  }
+  document.addEventListener('keydown', onKey)
+  onBeforeUnmount(() => document.removeEventListener('keydown', onKey))
+})
+
+const canSubmit = computed(() => {
+  return (
+    !busy.value &&
+    name.value.trim().length >= 2 &&
+    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value.trim())
+  )
+})
+
+async function submit() {
+  if (!canSubmit.value) return
+  busy.value = true
+  error.value = null
+  try {
+    result.value = await $fetch<InviteResult>('/api/users/invite', {
+      method: 'POST',
+      body: { name: name.value.trim(), email: email.value.trim() },
+    })
+    emit('invited', result.value)
+  } catch (e) {
+    const err = e as { data?: { data?: { message?: string }; message?: string; statusMessage?: string } }
+    error.value =
+      err.data?.data?.message ||
+      err.data?.message ||
+      err.data?.statusMessage ||
+      'Invite failed'
+  } finally {
+    busy.value = false
+  }
+}
+
+async function copyToClipboard(value: string) {
+  try {
+    await navigator.clipboard.writeText(value)
+    copied.value = true
+    setTimeout(() => (copied.value = false), 2000)
+  } catch {
+    // Some browsers reject clipboard in non-secure contexts. Fall back to
+    // user manually selecting the text in the readonly input below.
+  }
+}
+
+function done() {
+  emit('close')
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div v-if="open" class="backdrop" @click="!busy && emit('close')">
+      <div class="modal" role="dialog" aria-label="Invite operator" @click.stop>
+        <header>
+          <div>
+            <Eyebrow>Platform</Eyebrow>
+            <h2>Invite operator</h2>
+          </div>
+          <button class="x" type="button" aria-label="Close" :disabled="busy" @click="emit('close')">
+            <UiIcon name="x" :size="12" />
+          </button>
+        </header>
+
+        <!-- Step 1: collect details -->
+        <div v-if="!result" class="body">
+          <section>
+            <label class="label">Name</label>
+            <input v-model="name" type="text" placeholder="Anne Baslund" :disabled="busy" />
+          </section>
+          <section>
+            <label class="label">Email</label>
+            <input v-model="email" type="email" placeholder="anne@dezky.com" :disabled="busy" />
+          </section>
+
+          <div class="note">
+            <UiIcon name="shield" :size="13" />
+            <Mono dim>
+              Adds the user to the <strong>dezky-platform-admins</strong> Authentik group.
+              They'll receive a single-use recovery link to set their password + enroll MFA.
+            </Mono>
+          </div>
+
+          <p v-if="error" class="err">{{ error }}</p>
+        </div>
+
+        <!-- Step 2: show the credential to share -->
+        <div v-else class="body result">
+          <Badge tone="ok" dot>invited</Badge>
+
+          <!-- Preferred path: Authentik issued a recovery link -->
+          <template v-if="result.link">
+            <p class="success">
+              {{ name }} (<Mono>{{ email }}</Mono>) was added to the
+              <Mono>dezky-platform-admins</Mono> group. Share the link below — it's
+              single-use and they'll set their own password + MFA.
+            </p>
+            <div class="cred-row">
+              <input :value="result.link" readonly @focus="($event.target as HTMLInputElement).select()" />
+              <UiButton variant="secondary" @click="copyToClipboard(result.link!)">
+                {{ copied ? 'Copied' : 'Copy' }}
+              </UiButton>
+            </div>
+          </template>
+
+          <!-- Fallback path: no recovery flow configured in Authentik, share temp password -->
+          <template v-else-if="result.tempPassword">
+            <p class="success">
+              {{ name }} (<Mono>{{ email }}</Mono>) was added to the
+              <Mono>dezky-platform-admins</Mono> group. Authentik doesn't have a
+              recovery flow configured yet, so we set a temporary password —
+              share it with them out-of-band, they'll be prompted to change it
+              on first login.
+            </p>
+            <section>
+              <label class="label">Username / email</label>
+              <div class="cred-row">
+                <input :value="email" readonly @focus="($event.target as HTMLInputElement).select()" />
+                <UiButton variant="secondary" @click="copyToClipboard(email)">
+                  Copy
+                </UiButton>
+              </div>
+            </section>
+            <section>
+              <label class="label">Temporary password</label>
+              <div class="cred-row">
+                <input :value="result.tempPassword" readonly @focus="($event.target as HTMLInputElement).select()" />
+                <UiButton variant="secondary" @click="copyToClipboard(result.tempPassword!)">
+                  {{ copied ? 'Copied' : 'Copy' }}
+                </UiButton>
+              </div>
+            </section>
+            <Mono dim>
+              // configure a recovery flow in Authentik (Flows → recovery) to
+              switch this to a self-service link · once SMTP is wired the
+              credential gets emailed automatically
+            </Mono>
+          </template>
+        </div>
+
+        <footer v-if="!result">
+          <UiButton variant="ghost" :disabled="busy" @click="emit('close')">Cancel</UiButton>
+          <UiButton variant="primary" :disabled="!canSubmit" @click="submit">
+            {{ busy ? 'Inviting…' : 'Send invite' }}
+          </UiButton>
+        </footer>
+        <footer v-else>
+          <UiButton variant="primary" @click="done">Done</UiButton>
+        </footer>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+.backdrop {
+  position: fixed; inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+  display: flex; align-items: center; justify-content: center;
+  padding: 24px;
+  z-index: 180;
+}
+.modal {
+  width: 100%; max-width: 520px;
+  background: var(--elevated);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  box-shadow: 0 24px 80px rgba(0, 0, 0, 0.5);
+  display: flex; flex-direction: column;
+  overflow: hidden;
+}
+header {
+  padding: 16px 20px;
+  display: flex; justify-content: space-between; align-items: flex-start;
+  border-bottom: 1px solid var(--border);
+}
+h2 { margin: 4px 0 0 0; font-family: var(--font-display); font-weight: 600; font-size: 18px; }
+.x {
+  width: 26px; height: 26px;
+  border: 0; border-radius: 6px; background: transparent;
+  color: var(--text-mute); cursor: pointer;
+  display: inline-flex; align-items: center; justify-content: center;
+}
+.x:hover:not(:disabled) { background: var(--surface); color: var(--text); }
+.x:disabled { opacity: 0.4; cursor: not-allowed; }
+
+.body {
+  padding: 16px 20px;
+  display: flex; flex-direction: column; gap: 14px;
+}
+section { display: flex; flex-direction: column; gap: 6px; }
+.label {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--text-mute);
+  font-weight: 500;
+}
+input {
+  height: 34px;
+  padding: 0 12px;
+  background: var(--input-bg);
+  border: 1px solid var(--border);
+  color: var(--text);
+  border-radius: 6px;
+  font-family: inherit;
+  font-size: 13px;
+  outline: 0;
+}
+input:focus { border-color: var(--border-hi); }
+input:disabled { opacity: 0.6; }
+
+.note {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 12px 14px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  color: var(--text-mute);
+}
+.note strong { color: var(--text); font-family: var(--font-mono); font-weight: 600; }
+
+.err {
+  margin: 0;
+  padding: 10px 12px;
+  background: rgba(240, 88, 88, 0.08);
+  border: 1px solid rgba(240, 88, 88, 0.24);
+  color: var(--bad);
+  border-radius: 6px;
+  font-size: 12px;
+}
+
+.result .success {
+  margin: 4px 0 0 0;
+  font-size: 13px;
+  color: var(--text-dim);
+  line-height: 1.55;
+}
+.cred-row { display: flex; gap: 8px; align-items: center; }
+.cred-row input {
+  flex: 1;
+  font-family: var(--font-mono);
+  font-size: 11px;
+}
+
+footer {
+  padding: 12px 20px;
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  border-top: 1px solid var(--border);
+  background: var(--surface);
+}
+</style>

apps/operator/pages/operator-team.vue

@@ -7,6 +7,8 @@ const { data: users, pending, refresh } = await useFetch<PlatformUser[]>('/api/u
 
 const operators = computed(() => (users.value ?? []).filter((u) => u.platformAdmin))
 
+const inviteOpen = ref(false)
+
 function lastSeen(u: PlatformUser) {
   if (!u.lastLoginAt) return '—'
   const diff = Date.now() - new Date(u.lastLoginAt).getTime()
@@ -18,6 +20,13 @@ function lastSeen(u: PlatformUser) {
   const d = Math.floor(h / 24)
   return `${d} d ago`
 }
+
+async function onInvited() {
+  // Refresh the list so the newly-invited operator shows up immediately —
+  // platform-api pre-creates the local User doc, so they appear with
+  // platformAdmin=true even before their first login.
+  await refresh()
+}
 </script>
 
 <template>
@@ -33,14 +42,20 @@ function lastSeen(u: PlatformUser) {
           Refresh
         </UiButton>
         <a href="https://auth.dezky.local/if/admin/" target="_blank" rel="noopener" class="link">
-          <UiButton variant="primary">
+          <UiButton variant="secondary">
             <template #leading><UiIcon name="external" :size="13" /></template>
             Manage in Authentik
           </UiButton>
         </a>
+        <UiButton variant="primary" @click="inviteOpen = true">
+          <template #leading><UiIcon name="plus" :size="13" /></template>
+          Invite operator
+        </UiButton>
       </template>
     </PageHeader>
 
+    <InviteOperatorModal :open="inviteOpen" @close="inviteOpen = false" @invited="onInvited" />
+
     <div class="stage">
       <Card :pad="0">
         <table v-if="operators.length">

apps/operator/server/api/users/invite.post.ts

@@ -0,0 +1,6 @@
+import { platformApi } from '~~/server/utils/platform-api'
+
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event)
+  return platformApi(event, '/users/invite', { method: 'POST', body })
+})

services/platform-api/src/integrations/authentik.client.ts

@@ -86,6 +86,109 @@ export class AuthentikClient {
     if (since) params.set('created__gt', since.toISOString())
     return this.request<AuthentikEventPage>(`/events/events/?${params}`)
   }
+
+  // Look up a user by email. Returns undefined if not found. Used by the
+  // invite flow so we can give a friendly conflict error instead of letting
+  // Authentik 400.
+  async findUserByEmail(email: string): Promise<AuthentikUser | undefined> {
+    const res = await this.request<{ results: AuthentikUser[] }>(
+      `/core/users/?email=${encodeURIComponent(email)}`,
+    )
+    return res.results[0]
+  }
+
+  // Create a user. Authentik's `uid` field becomes the JWT `sub` claim once
+  // they log in — this is the same value our User.authentikSubjectId is keyed
+  // on. We set type='internal' (real human user, not service account) and
+  // is_active=true so the recovery link they receive lets them set a password.
+  async createUser(input: {
+    username: string
+    email: string
+    name: string
+    attributes?: Record<string, unknown>
+    groupPks?: string[]
+  }): Promise<AuthentikUser> {
+    const created = await this.request<AuthentikUser>('/core/users/', {
+      method: 'POST',
+      body: JSON.stringify({
+        username: input.username,
+        email: input.email,
+        name: input.name,
+        type: 'internal',
+        is_active: true,
+        path: 'users',
+        groups: input.groupPks ?? [],
+        attributes: input.attributes ?? {},
+      }),
+    })
+    this.logger.log(`Created Authentik user ${input.email} (pk=${created.pk}, uid=${created.uid})`)
+    return created
+  }
+
+  // Add an existing user to a group by ID. Idempotent — adding twice is a
+  // no-op on Authentik's side.
+  async addUserToGroup(userPk: number, groupId: string): Promise<void> {
+    await this.request(`/core/groups/${groupId}/add_user/`, {
+      method: 'POST',
+      body: JSON.stringify({ pk: userPk }),
+    })
+    this.logger.log(`Added user ${userPk} to Authentik group ${groupId}`)
+  }
+
+  // Generate a single-use recovery link the new user clicks to set their
+  // password + enroll MFA. Requires a "recovery flow" configured on the
+  // Authentik brand — if not set, returns undefined so callers can fall
+  // back to setInitialPassword.
+  async recoveryLink(userPk: number): Promise<string | undefined> {
+    try {
+      const res = await this.request<{ link: string }>(
+        `/core/users/${userPk}/recovery/`,
+        { method: 'POST' },
+      )
+      return res.link
+    } catch (err) {
+      // Authentik returns 400 with "No recovery flow set." when the brand has
+      // no recovery flow wired. Treat as soft-fail; caller fallback path
+      // sets an initial password instead.
+      if (err instanceof Error && err.message.includes('recovery flow')) {
+        this.logger.warn('Authentik recovery link unavailable — no recovery flow configured')
+        return undefined
+      }
+      throw err
+    }
+  }
+
+  // Direct set_password — used when no recovery flow is configured. The
+  // operator hands the temp password to the new user out-of-band; the user
+  // changes it after first login via Authentik's password-change flow.
+  // Authentik returns 204 No Content (empty body) on success, so we skip
+  // request<T>()'s JSON parser and call fetch directly.
+  async setInitialPassword(userPk: number, password: string): Promise<void> {
+    const res = await fetch(`${this.base}/core/users/${userPk}/set_password/`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.token}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify({ password }),
+    })
+    if (!res.ok) {
+      const body = await res.text().catch(() => '')
+      throw new Error(`Authentik set_password ${userPk} → ${res.status}: ${body.slice(0, 200)}`)
+    }
+    this.logger.log(`Set initial password for Authentik user ${userPk}`)
+  }
+}
+
+export interface AuthentikUser {
+  pk: number
+  uid: string  // becomes JWT `sub` on first login
+  username: string
+  email: string
+  name?: string
+  is_active: boolean
+  groups?: string[]
 }
 
 // Shape returned by /events/events/. Only the fields we read; Authentik

services/platform-api/src/users/dto/invite-operator.dto.ts

@@ -0,0 +1,13 @@
+import { IsEmail, IsString, MaxLength, MinLength } from 'class-validator'
+
+// Operator-only: invite a new platform admin. Body is just identity — group
+// membership is implicit (we add them to the dezky-platform-admins Authentik
+// group). Tenant-member invites land later via a different endpoint with
+// tenantSlug + role fields.
+export class InviteOperatorDto {
+  @IsString() @MinLength(2) @MaxLength(120)
+  name!: string
+
+  @IsEmail() @MaxLength(254)
+  email!: string
+}

services/platform-api/src/users/users.controller.ts

@@ -17,7 +17,9 @@ import { clientIp } from '../auth/client-ip.js'
 import { CurrentUser } from '../auth/current-user.decorator.js'
 import { JwtAuthGuard } from '../auth/jwt-auth.guard.js'
 import type { AuthentikJwtPayload } from '../auth/jwt-payload.interface.js'
+import { OperatorGuard } from '../auth/operator.guard.js'
 import { CreateUserDto } from './dto/create-user.dto.js'
+import { InviteOperatorDto } from './dto/invite-operator.dto.js'
 import { UpdateUserDto } from './dto/update-user.dto.js'
 import { UsersService } from './users.service.js'
 
@@ -63,6 +65,25 @@ export class UsersController {
     return this.users.create(dto)
   }
 
+  // Operator-only: invite a new platform admin. Creates the user in Authentik,
+  // adds them to the dezky-platform-admins group, returns a recovery link the
+  // operator shares manually. Once outbound SMTP is wired, Authentik can
+  // email the link directly and the response link is mostly informational.
+  @Post('invite')
+  @UseGuards(OperatorGuard)
+  async invite(
+    @Body() dto: InviteOperatorDto,
+    @CurrentUser() jwt: AuthentikJwtPayload,
+    @Req() req: Parameters<typeof clientIp>[0],
+  ) {
+    const actor = await this.actor.resolve(jwt)
+    return this.users.inviteOperator(dto, {
+      userId: String(actor._id),
+      email: actor.email,
+      ip: clientIp(req),
+    })
+  }
+
   @Get()
   async findAll(@CurrentUser() jwt: AuthentikJwtPayload) {
     const actor = await this.actor.resolve(jwt)

services/platform-api/src/users/users.module.ts

@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common'
 import { MongooseModule } from '@nestjs/mongoose'
 import { AuditModule } from '../audit/audit.module.js'
 import { AuthModule } from '../auth/auth.module.js'
+import { IntegrationsModule } from '../integrations/integrations.module.js'
 import { Tenant, TenantSchema } from '../schemas/tenant.schema.js'
 import { User, UserSchema } from '../schemas/user.schema.js'
 import { TenantsModule } from '../tenants/tenants.module.js'
@@ -16,6 +17,7 @@ import { UsersService } from './users.service.js'
     ]),
     AuthModule,
     AuditModule,
+    IntegrationsModule,
     TenantsModule,
   ],
   controllers: [UsersController],

services/platform-api/src/users/users.service.ts

@@ -1,19 +1,34 @@
-import { ConflictException, Injectable, NotFoundException } from '@nestjs/common'
+import { ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
 import { InjectModel } from '@nestjs/mongoose'
 import { Model, Types } from 'mongoose'
 import { AuditService, type AuditActor } from '../audit/audit.service.js'
+import { AuthentikClient } from '../integrations/authentik.client.js'
 import { Tenant, TenantDocument } from '../schemas/tenant.schema.js'
 import { User, UserDocument } from '../schemas/user.schema.js'
 import type { CreateUserDto } from './dto/create-user.dto.js'
+import type { InviteOperatorDto } from './dto/invite-operator.dto.js'
 import type { UpdateUserDto } from './dto/update-user.dto.js'
 
 @Injectable()
 export class UsersService {
+  private readonly logger = new Logger(UsersService.name)
+  private readonly platformAdminGroup: string
+  // Cached after first successful lookup. The dezky-platform-admins group is
+  // created once during Authentik bootstrap and never moves; no need to look
+  // it up every invite.
+  private platformAdminGroupId: string | null = null
+
   constructor(
     @InjectModel(User.name) private readonly userModel: Model<UserDocument>,
     @InjectModel(Tenant.name) private readonly tenantModel: Model<TenantDocument>,
     private readonly audit: AuditService,
-  ) {}
+    private readonly authentik: AuthentikClient,
+    config: ConfigService,
+  ) {
+    this.platformAdminGroup =
+      config.get<string>('PLATFORM_ADMIN_BOOTSTRAP_GROUP') ?? 'dezky-platform-admins'
+  }
 
   async create(dto: CreateUserDto): Promise<UserDocument> {
     const exists = await this.userModel.exists({ authentikSubjectId: dto.authentikSubjectId })
@@ -106,4 +121,136 @@ export class UsersService {
     const tenants = await this.tenantModel.find({ slug: { $in: slugs } }, { _id: 1 }).exec()
     return tenants.map((t) => t._id)
   }
+
+  // Invite a new platform admin. Creates the user in Authentik, adds them to
+  // the dezky-platform-admins group, pre-creates the local User doc so they
+  // appear in the operator-team list immediately, and returns whichever
+  // credential-handoff path Authentik supports for our brand:
+  //   - `link`  — single-use recovery URL (preferred; requires a recovery
+  //               flow configured in Authentik. User clicks → sets password
+  //               + enrolls MFA themselves.)
+  //   - `tempPassword` — random 16-char password we set on the user. Used
+  //                      when no recovery flow exists; operator hands this
+  //                      to the new user out-of-band and they change it on
+  //                      first login via Authentik's password-change flow.
+  // On their first login, upsertFromAuthentik() patches lastLoginAt +
+  // reconciles group state from the JWT — no further work needed.
+  //
+  // Email delivery is the operator's job for now (we return the credential);
+  // when outbound SMTP is wired (Phase 5/6), Authentik can email directly.
+  async inviteOperator(
+    dto: InviteOperatorDto,
+    actor?: AuditActor,
+  ): Promise<{
+    subject: string
+    userId: string
+    link?: string
+    tempPassword?: string
+  }> {
+    // Prevent duplicate by email — Authentik will 400 but its error message
+    // isn't friendly. Check up front for a clean conflict.
+    const existing = await this.authentik.findUserByEmail(dto.email)
+    if (existing) {
+      throw new ConflictException(
+        `User with email ${dto.email} already exists in Authentik (uid=${existing.uid})`,
+      )
+    }
+
+    const groupPk = await this.resolvePlatformAdminGroupId()
+    const username = dto.email  // Authentik convention — keep email + username aligned
+
+    const created = await this.authentik.createUser({
+      username,
+      email: dto.email,
+      name: dto.name,
+      groupPks: [groupPk],
+      attributes: { invitedBy: actor?.email, invitedAt: new Date().toISOString() },
+    })
+
+    // Pre-create the local User doc so the operator-team list reflects the
+    // invite immediately. On their first login /users/me will upsert and
+    // reconcile lastLoginAt + platformAdmin from the JWT.
+    await this.userModel
+      .findOneAndUpdate(
+        { authentikSubjectId: created.uid },
+        {
+          $set: {
+            email: dto.email,
+            name: dto.name,
+            platformAdmin: true,
+          },
+          $setOnInsert: { role: 'admin', active: true, tenantIds: [] },
+        },
+        { upsert: true, new: true, runValidators: true },
+      )
+      .exec()
+
+    // Try the preferred recovery-link path first. If Authentik has no
+    // recovery flow configured (returns undefined), fall back to setting a
+    // generated temp password.
+    let link: string | undefined
+    let tempPassword: string | undefined
+    link = await this.authentik.recoveryLink(created.pk)
+    if (!link) {
+      tempPassword = generateTempPassword()
+      await this.authentik.setInitialPassword(created.pk, tempPassword)
+    }
+
+    void this.audit.record(
+      {
+        action: 'platform.user_invited',
+        resourceType: 'user',
+        resourceId: created.uid,
+        resourceName: dto.email,
+        metadata: {
+          role: 'platform-admin',
+          name: dto.name,
+          handoff: link ? 'recovery-link' : 'temp-password',
+        },
+      },
+      actor,
+    )
+
+    return { subject: created.uid, userId: String(created.pk), link, tempPassword }
+  }
+
+  // Resolve + cache the dezky-platform-admins group ID. The group is created
+  // by Authentik bootstrap so it's reliably present; ensureGroup is
+  // idempotent so the worst case is a no-op extra API call on cold start.
+  private async resolvePlatformAdminGroupId(): Promise<string> {
+    if (this.platformAdminGroupId) return this.platformAdminGroupId
+    const group = await this.authentik.ensureGroup(this.platformAdminGroup, {
+      role: 'platform-admin',
+    })
+    this.platformAdminGroupId = group.pk
+    return group.pk
+  }
+}
+
+// Generates a 16-character random password with mixed character classes.
+// Authentik's default password policy requires length + complexity; this
+// generator clears every reasonable policy. The new user changes it on
+// first login.
+function generateTempPassword(): string {
+  const upper = 'ABCDEFGHJKLMNPQRSTUVWXYZ'  // omit I + O (visually confusable)
+  const lower = 'abcdefghijkmnpqrstuvwxyz' // omit l (confusable with 1)
+  const digit = '23456789'                  // omit 0 + 1
+  const symbol = '!@#$%&*+-='
+  const all = upper + lower + digit + symbol
+
+  // Pick at least one from each class; fill the rest from `all`; shuffle.
+  const out: string[] = [
+    upper[Math.floor(Math.random() * upper.length)],
+    lower[Math.floor(Math.random() * lower.length)],
+    digit[Math.floor(Math.random() * digit.length)],
+    symbol[Math.floor(Math.random() * symbol.length)],
+  ]
+  while (out.length < 16) {
+    out.push(all[Math.floor(Math.random() * all.length)])
+  }
+  for (let i = out.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    ;[out[i], out[j]] = [out[j], out[i]]
+  }
+  return out.join('')
 }