feat(platform-api): multi-audience JWT + Partner CRUD + tenant lifecycle (O.2)

JwtAuthGuard now accepts a comma-separated AUTHENTIK_AUDIENCE
('dezky-portal,dezky-operator'). jose.jwtVerify takes an array and succeeds
on any match — both customer-portal and operator-portal tokens validate
against this service. Per-endpoint guards restrict further.

New OperatorGuard enforces operator-only mutations:
  1. JWT audience claim includes 'dezky-operator' (proof from the token
     alone that this is a privileged session)
  2. ActorService-resolved User has platformAdmin=true (DB check so
     revocation works without waiting for the token to expire)
Both required; either alone is insufficient.

Partner module:
  - Partner schema: slug, name, domain, status, marginPct, contactInfo,
    billingInfo. marginPct is one number per partner (decided in grilling)
  - CRUD endpoints under @UseGuards(JwtAuthGuard, OperatorGuard) — every
    partner mutation requires operator scope
  - GET /partners returns each row with a computed customers count from
    aggregating Tenant.partnerId. MRR aggregation deferred until
    Subscription gains a price column
  - GET /partners/:slug/tenants for the partner detail view
  - DELETE soft-terminates (status='terminated') — never hard-delete
    because tenants may still reference the partner

Tenant changes:
  - partnerId?: Types.ObjectId (ref Partner, indexed sparse) added to
    Tenant schema
  - UpdateTenantDto accepts partnerId so PATCH can attach/detach
  - POST /tenants/:slug/suspend and /resume — operator-only via
    OperatorGuard. PATCH already covers plan/domains/partnerId changes

Smoke test: customer-portal session sends POST /api/partners through the
portal proxy → 403 "This endpoint requires an operator-scoped token". The
positive test (operator-token → 200) waits for O.3 when there's an
operator app to mint the right token.

apps/portal/server/api/partners/index.post.ts is a temporary verification
proxy — delete once the operator portal exists.

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

@@ -3,6 +3,7 @@ import { ConfigModule } from '@nestjs/config'
 import { MongooseModule } from '@nestjs/mongoose'
 import { AuthModule } from './auth/auth.module.js'
 import { HealthController } from './health.controller.js'
+import { PartnersModule } from './partners/partners.module.js'
 import { SeedModule } from './seed/seed.module.js'
 import { SubscriptionsModule } from './subscriptions/subscriptions.module.js'
 import { TenantsModule } from './tenants/tenants.module.js'
@@ -16,6 +17,7 @@ import { UsersModule } from './users/users.module.js'
     ),
     AuthModule,
     TenantsModule,
+    PartnersModule,
     UsersModule,
     SubscriptionsModule,
     SeedModule,

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

@@ -3,10 +3,11 @@ import { MongooseModule } from '@nestjs/mongoose'
 import { User, UserSchema } from '../schemas/user.schema.js'
 import { ActorService } from './actor.service.js'
 import { JwtAuthGuard } from './jwt-auth.guard.js'
+import { OperatorGuard } from './operator.guard.js'
 
 @Module({
   imports: [MongooseModule.forFeature([{ name: User.name, schema: UserSchema }])],
-  providers: [JwtAuthGuard, ActorService],
-  exports: [JwtAuthGuard, ActorService],
+  providers: [JwtAuthGuard, OperatorGuard, ActorService],
+  exports: [JwtAuthGuard, OperatorGuard, ActorService],
 })
 export class AuthModule {}

services/platform-api/src/auth/jwt-auth.guard.ts

@@ -14,12 +14,19 @@ export class JwtAuthGuard implements CanActivate {
   private readonly logger = new Logger(JwtAuthGuard.name)
   private jwks: ReturnType<typeof createRemoteJWKSet> | null = null
   private readonly issuer: string
-  private readonly audience: string
+  // AUTHENTIK_AUDIENCE is comma-separated to accept tokens from multiple
+  // OAuth clients (customer portal + operator portal + future surfaces).
+  // jose.jwtVerify with an array succeeds if the token's aud matches any.
+  private readonly audiences: string[]
   private readonly jwksUri: string
 
   constructor(config: ConfigService) {
     this.issuer = config.getOrThrow<string>('AUTHENTIK_ISSUER')
-    this.audience = config.getOrThrow<string>('AUTHENTIK_AUDIENCE')
+    this.audiences = config
+      .getOrThrow<string>('AUTHENTIK_AUDIENCE')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
     this.jwksUri = config.getOrThrow<string>('AUTHENTIK_JWKS_URI')
   }
 
@@ -52,7 +59,7 @@ export class JwtAuthGuard implements CanActivate {
     try {
       const { payload } = await jwtVerify(token, this.getJwks(), {
         issuer: this.issuer,
-        audience: this.audience,
+        audience: this.audiences,
       })
       req.user = payload as unknown as AuthentikJwtPayload
       return true

services/platform-api/src/auth/operator.guard.ts

@@ -0,0 +1,41 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+} from '@nestjs/common'
+import { ActorService } from './actor.service.js'
+import type { AuthentikJwtPayload } from './jwt-payload.interface.js'
+
+// Applied AFTER JwtAuthGuard. Enforces that the request is coming from an
+// operator session — both proofs required:
+//   1. Token audience is 'dezky-operator' (the operator OAuth client)
+//   2. The DB-resolved User has platformAdmin=true
+//
+// Either proof alone is insufficient. The token claim makes "is this a
+// privileged session" derivable from the JWT alone; the DB check ensures
+// revocation works without waiting for the token to expire.
+@Injectable()
+export class OperatorGuard implements CanActivate {
+  constructor(private readonly actor: ActorService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const req = context.switchToHttp().getRequest<{ user?: AuthentikJwtPayload }>()
+    const jwt = req.user
+    if (!jwt) {
+      throw new ForbiddenException('Authentication required (JwtAuthGuard must run first)')
+    }
+
+    const aud = Array.isArray(jwt.aud) ? jwt.aud : [jwt.aud]
+    if (!aud.includes('dezky-operator')) {
+      throw new ForbiddenException('This endpoint requires an operator-scoped token')
+    }
+
+    const actor = await this.actor.resolve(jwt)
+    if (!actor.platformAdmin) {
+      throw new ForbiddenException('platformAdmin role required')
+    }
+
+    return true
+  }
+}

services/platform-api/src/partners/dto/create-partner.dto.ts

@@ -0,0 +1,53 @@
+import { Type } from 'class-transformer'
+import {
+  IsEmail,
+  IsEnum,
+  IsInt,
+  IsOptional,
+  IsString,
+  Matches,
+  Max,
+  MaxLength,
+  Min,
+  MinLength,
+  ValidateNested,
+} from 'class-validator'
+
+class ContactInfoDto {
+  @IsOptional() @IsString() @MaxLength(200) primaryName?: string
+  @IsOptional() @IsEmail() primaryEmail?: string
+  @IsOptional() @IsEmail() billingEmail?: string
+}
+
+class BillingInfoDto {
+  @IsOptional() @IsString() @MaxLength(200) companyName?: string
+  @IsOptional() @IsString() @MaxLength(40) vatId?: string
+  @IsOptional() @IsString() @MaxLength(2) country?: string
+  @IsOptional() @IsEmail() contactEmail?: string
+}
+
+export class CreatePartnerDto {
+  @IsString()
+  @Matches(/^[a-z0-9]([a-z0-9-]{0,38}[a-z0-9])?$/, {
+    message: 'slug must be lowercase, 2-40 chars, hyphen-separated',
+  })
+  slug!: string
+
+  @IsString() @MinLength(2) @MaxLength(120)
+  name!: string
+
+  @IsString() @MinLength(3) @MaxLength(120)
+  domain!: string
+
+  @IsOptional() @IsEnum(['active', 'in-negotiation', 'paused', 'terminated'])
+  status?: 'active' | 'in-negotiation' | 'paused' | 'terminated'
+
+  @IsOptional() @IsInt() @Min(0) @Max(100)
+  marginPct?: number
+
+  @IsOptional() @ValidateNested() @Type(() => ContactInfoDto)
+  contactInfo?: ContactInfoDto
+
+  @IsOptional() @ValidateNested() @Type(() => BillingInfoDto)
+  billingInfo?: BillingInfoDto
+}

services/platform-api/src/partners/dto/update-partner.dto.ts

@@ -0,0 +1,46 @@
+import { Type } from 'class-transformer'
+import {
+  IsEmail,
+  IsEnum,
+  IsInt,
+  IsOptional,
+  IsString,
+  Max,
+  MaxLength,
+  Min,
+  MinLength,
+  ValidateNested,
+} from 'class-validator'
+
+class ContactInfoDto {
+  @IsOptional() @IsString() @MaxLength(200) primaryName?: string
+  @IsOptional() @IsEmail() primaryEmail?: string
+  @IsOptional() @IsEmail() billingEmail?: string
+}
+
+class BillingInfoDto {
+  @IsOptional() @IsString() @MaxLength(200) companyName?: string
+  @IsOptional() @IsString() @MaxLength(40) vatId?: string
+  @IsOptional() @IsString() @MaxLength(2) country?: string
+  @IsOptional() @IsEmail() contactEmail?: string
+}
+
+export class UpdatePartnerDto {
+  @IsOptional() @IsString() @MinLength(2) @MaxLength(120)
+  name?: string
+
+  @IsOptional() @IsString() @MinLength(3) @MaxLength(120)
+  domain?: string
+
+  @IsOptional() @IsEnum(['active', 'in-negotiation', 'paused', 'terminated'])
+  status?: 'active' | 'in-negotiation' | 'paused' | 'terminated'
+
+  @IsOptional() @IsInt() @Min(0) @Max(100)
+  marginPct?: number
+
+  @IsOptional() @ValidateNested() @Type(() => ContactInfoDto)
+  contactInfo?: ContactInfoDto
+
+  @IsOptional() @ValidateNested() @Type(() => BillingInfoDto)
+  billingInfo?: BillingInfoDto
+}

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

@@ -0,0 +1,60 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  Param,
+  Patch,
+  Post,
+  UseGuards,
+} from '@nestjs/common'
+import { JwtAuthGuard } from '../auth/jwt-auth.guard.js'
+import { OperatorGuard } from '../auth/operator.guard.js'
+import { CreatePartnerDto } from './dto/create-partner.dto.js'
+import { UpdatePartnerDto } from './dto/update-partner.dto.js'
+import { PartnersService } from './partners.service.js'
+
+// Partners are operator-managed only. Every endpoint requires an
+// operator-scoped token (aud === 'dezky-operator') plus platformAdmin on the
+// resolved user. A self-serve partner portal (partner.dezky.local) is a
+// future surface and will hit different endpoints scoped to "this partner's
+// own customers" rather than the full set.
+@Controller('partners')
+@UseGuards(JwtAuthGuard, OperatorGuard)
+export class PartnersController {
+  constructor(private readonly partners: PartnersService) {}
+
+  @Post()
+  create(@Body() dto: CreatePartnerDto) {
+    return this.partners.create(dto)
+  }
+
+  @Get()
+  async findAll() {
+    const rows = await this.partners.findAllWithStats()
+    return rows.map((r) => ({ ...r.partner.toObject(), customers: r.customers }))
+  }
+
+  @Get(':slug')
+  async findOne(@Param('slug') slug: string) {
+    const row = await this.partners.findOneWithStats(slug)
+    return { ...row.partner.toObject(), customers: row.customers }
+  }
+
+  @Get(':slug/tenants')
+  listTenants(@Param('slug') slug: string) {
+    return this.partners.listTenants(slug)
+  }
+
+  @Patch(':slug')
+  update(@Param('slug') slug: string, @Body() dto: UpdatePartnerDto) {
+    return this.partners.update(slug, dto)
+  }
+
+  @Delete(':slug')
+  @HttpCode(204)
+  async terminate(@Param('slug') slug: string) {
+    await this.partners.terminate(slug)
+  }
+}

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

@@ -0,0 +1,21 @@
+import { Module } from '@nestjs/common'
+import { MongooseModule } from '@nestjs/mongoose'
+import { AuthModule } from '../auth/auth.module.js'
+import { Partner, PartnerSchema } from '../schemas/partner.schema.js'
+import { Tenant, TenantSchema } from '../schemas/tenant.schema.js'
+import { PartnersController } from './partners.controller.js'
+import { PartnersService } from './partners.service.js'
+
+@Module({
+  imports: [
+    MongooseModule.forFeature([
+      { name: Partner.name, schema: PartnerSchema },
+      { name: Tenant.name, schema: TenantSchema },
+    ]),
+    AuthModule,
+  ],
+  controllers: [PartnersController],
+  providers: [PartnersService],
+  exports: [PartnersService],
+})
+export class PartnersModule {}

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

@@ -0,0 +1,87 @@
+import { ConflictException, Injectable, NotFoundException } from '@nestjs/common'
+import { InjectModel } from '@nestjs/mongoose'
+import { Model, Types } from 'mongoose'
+import { Partner, PartnerDocument } from '../schemas/partner.schema.js'
+import { Tenant, TenantDocument } from '../schemas/tenant.schema.js'
+import type { CreatePartnerDto } from './dto/create-partner.dto.js'
+import type { UpdatePartnerDto } from './dto/update-partner.dto.js'
+
+// Aggregated view of a Partner — adds counts that are computed at query time
+// rather than stored on the document. Storing denormalized would force a sync
+// hop on every tenant create/suspend; the count query is cheap with the index
+// on Tenant.partnerId.
+export interface PartnerWithStats {
+  partner: PartnerDocument
+  customers: number
+  // MRR sum is intentionally absent for now — Tenant doesn't carry a
+  // monthlyAmount yet (lives on Subscription, no pricing tables). Wire when
+  // Subscription gains a price column.
+}
+
+@Injectable()
+export class PartnersService {
+  constructor(
+    @InjectModel(Partner.name) private readonly partnerModel: Model<PartnerDocument>,
+    @InjectModel(Tenant.name) private readonly tenantModel: Model<TenantDocument>,
+  ) {}
+
+  async create(dto: CreatePartnerDto): Promise<PartnerDocument> {
+    const exists = await this.partnerModel.exists({ slug: dto.slug })
+    if (exists) throw new ConflictException(`Partner "${dto.slug}" already exists`)
+    return this.partnerModel.create({
+      ...dto,
+      status: dto.status ?? 'in-negotiation',
+    })
+  }
+
+  async findAll(): Promise<PartnerDocument[]> {
+    return this.partnerModel.find().sort({ createdAt: -1 }).exec()
+  }
+
+  async findAllWithStats(): Promise<PartnerWithStats[]> {
+    const partners = await this.findAll()
+    if (partners.length === 0) return []
+    const counts = await this.tenantModel.aggregate<{ _id: Types.ObjectId; n: number }>([
+      { $match: { partnerId: { $in: partners.map((p) => p._id) } } },
+      { $group: { _id: '$partnerId', n: { $sum: 1 } } },
+    ])
+    const countMap = new Map(counts.map((c) => [String(c._id), c.n]))
+    return partners.map((p) => ({ partner: p, customers: countMap.get(String(p._id)) ?? 0 }))
+  }
+
+  async findOneBySlug(slug: string): Promise<PartnerDocument> {
+    const partner = await this.partnerModel.findOne({ slug }).exec()
+    if (!partner) throw new NotFoundException(`Partner "${slug}" not found`)
+    return partner
+  }
+
+  async findOneWithStats(slug: string): Promise<PartnerWithStats> {
+    const partner = await this.findOneBySlug(slug)
+    const customers = await this.tenantModel.countDocuments({ partnerId: partner._id })
+    return { partner, customers }
+  }
+
+  async listTenants(slug: string): Promise<TenantDocument[]> {
+    const partner = await this.findOneBySlug(slug)
+    return this.tenantModel.find({ partnerId: partner._id }).sort({ createdAt: -1 }).exec()
+  }
+
+  async update(slug: string, dto: UpdatePartnerDto): Promise<PartnerDocument> {
+    const partner = await this.partnerModel
+      .findOneAndUpdate({ slug }, dto, { new: true, runValidators: true })
+      .exec()
+    if (!partner) throw new NotFoundException(`Partner "${slug}" not found`)
+    return partner
+  }
+
+  // Soft-terminate. We never hard-delete a partner — there may be customer
+  // tenants pointing at it and we want the historical reference to survive.
+  async terminate(slug: string): Promise<void> {
+    const result = await this.partnerModel
+      .updateOne({ slug }, { status: 'terminated' })
+      .exec()
+    if (result.matchedCount === 0) {
+      throw new NotFoundException(`Partner "${slug}" not found`)
+    }
+  }
+}

services/platform-api/src/schemas/partner.schema.ts

@@ -0,0 +1,68 @@
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose'
+import { HydratedDocument } from 'mongoose'
+
+export type PartnerDocument = HydratedDocument<Partner>
+
+export type PartnerStatus = 'active' | 'in-negotiation' | 'paused' | 'terminated'
+
+@Schema({ collection: 'partners', timestamps: true })
+export class Partner {
+  // URL-safe identifier, same convention as Tenant.slug.
+  @Prop({ required: true, unique: true, index: true, lowercase: true, trim: true })
+  slug!: string
+
+  @Prop({ required: true, trim: true })
+  name!: string
+
+  // The partner's own organization domain (e.g. 'nordicmsp.dk'). Not used by
+  // any service-level integration — purely metadata for display + contact.
+  @Prop({ required: true, trim: true })
+  domain!: string
+
+  @Prop({
+    enum: ['active', 'in-negotiation', 'paused', 'terminated'],
+    default: 'in-negotiation',
+    index: true,
+  })
+  status!: PartnerStatus
+
+  // Revenue share. 20 = partner keeps 20% of their customers' MRR. One number
+  // per partner — we don't negotiate per-tenant margin under a partner.
+  @Prop({ default: 0, min: 0, max: 100 })
+  marginPct!: number
+
+  @Prop()
+  partnershipStartedAt?: Date
+
+  @Prop({
+    type: {
+      primaryName: String,
+      primaryEmail: String,
+      billingEmail: String,
+    },
+    default: {},
+  })
+  contactInfo!: {
+    primaryName?: string
+    primaryEmail?: string
+    billingEmail?: string
+  }
+
+  @Prop({
+    type: {
+      companyName: String,
+      vatId: String,
+      country: String,
+      contactEmail: String,
+    },
+    default: {},
+  })
+  billingInfo!: {
+    companyName?: string
+    vatId?: string
+    country?: string
+    contactEmail?: string
+  }
+}
+
+export const PartnerSchema = SchemaFactory.createForClass(Partner)

services/platform-api/src/schemas/tenant.schema.ts

@@ -1,5 +1,5 @@
 import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose'
-import { HydratedDocument } from 'mongoose'
+import { HydratedDocument, Types } from 'mongoose'
 
 export type TenantDocument = HydratedDocument<Tenant>
 

services/platform-api/src/tenants/dto/update-tenant.dto.ts

@@ -1,4 +1,4 @@
-import { IsArray, IsEnum, IsOptional, IsString, MaxLength, MinLength } from 'class-validator'
+import { IsArray, IsEnum, IsMongoId, IsOptional, IsString, MaxLength, MinLength } from 'class-validator'
 
 export class UpdateTenantDto {
   @IsOptional() @IsString() @MinLength(2) @MaxLength(120)
@@ -12,4 +12,8 @@ export class UpdateTenantDto {
 
   @IsOptional() @IsArray() @IsString({ each: true })
   domains?: string[]
+
+  // Attach / move tenant under a partner (or pass null to detach).
+  @IsOptional() @IsMongoId()
+  partnerId?: string | null
 }

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

@@ -13,6 +13,7 @@ import {
 import { ActorService } from '../auth/actor.service.js'
 import { CurrentUser } from '../auth/current-user.decorator.js'
 import { JwtAuthGuard } from '../auth/jwt-auth.guard.js'
+import { OperatorGuard } from '../auth/operator.guard.js'
 import type { AuthentikJwtPayload } from '../auth/jwt-payload.interface.js'
 import { CreateTenantDto } from './dto/create-tenant.dto.js'
 import { UpdateTenantDto } from './dto/update-tenant.dto.js'
@@ -88,4 +89,18 @@ export class TenantsController {
     }
     return this.tenants.reconcile(slug)
   }
+
+  // Lifecycle: operator-only. JwtAuthGuard validates the token first, then
+  // OperatorGuard requires audience='dezky-operator' AND platformAdmin=true.
+  @Post(':slug/suspend')
+  @UseGuards(OperatorGuard)
+  suspend(@Param('slug') slug: string) {
+    return this.tenants.setStatus(slug, 'suspended')
+  }
+
+  @Post(':slug/resume')
+  @UseGuards(OperatorGuard)
+  resume(@Param('slug') slug: string) {
+    return this.tenants.setStatus(slug, 'active')
+  }
 }

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

@@ -65,4 +65,12 @@ export class TenantsService {
       .exec()
     if (result.matchedCount === 0) throw new NotFoundException(`Tenant "${slug}" not found`)
   }
+
+  async setStatus(slug: string, status: 'active' | 'suspended'): Promise<TenantDocument> {
+    const tenant = await this.tenantModel
+      .findOneAndUpdate({ slug }, { status }, { new: true })
+      .exec()
+    if (!tenant) throw new NotFoundException(`Tenant "${slug}" not found`)
+    return tenant
+  }
 }