Passport, Branding & Auth Modes — Full Architecture

interface Passport {
  // Identity
  bioId: string                  // unique user ID (immutable)
  email: string
  firstName: string
  lastName: string
  displayName: string
  avatar?: string
  userType: string               // 'user' | 'service' | 'admin'
  roles: string[]                // roles in primary org

  // Primary org
  orgSlug: string
  orgId: string                  // ORG-xxx format
  orgName: string

  // All org memberships (multi-org users)
  orgs: {
    orgSlug: string
    orgId: string
    orgName: string
    roles: string[]
    modules: string[]
  }[]

  // Aggregated modules across all orgs
  modules: string[]

  // Branding — loaded from vault at mint time
  branding: {
    displayName: string          // org display name for UI chrome
    tagline?: string
    logoUrl?: string             // primary logo (SVG or PNG)
    logoMarkUrl?: string         // icon/mark for small surfaces
    primaryColor: string         // hex — defaults to '#0F172A' (platform dark)
    secondaryColor?: string      // hex
    websiteUrl?: string
    verified: boolean            // platform verified this entity
    whiteLabelApproved: boolean  // approved for custom domain + hideEcoBranding
  }

  // Permissions — resolved from Koko at mint time
  permissions: {
    scopes: string[]             // e.g. ['raterspot:rate', 'docman:read']
  }

  // Vault link
  iecHash?: string               // entity's chain address (if vault entity exists)

  // Session metadata
  issuedAt: string
  connectedServices: string[]
}

// In any route handler — the Passport IS req.user
const { orgSlug, branding, permissions } = req.user

// Brand the page
document.title = branding.displayName
headerLogo.src = branding.logoUrl
root.style.setProperty('--primary', branding.primaryColor)

// Check permission
if (permissions.scopes.includes('raterspot:rate')) {
  showRatingPanel()
}

// No extra API calls. No vault lookup. No Koko call.

User clicks "Sign in with Bio-ID"
→ Redirect to bio.tawa.pro/oauth/authorize
→ Bio-ID consent screen (InsurEco logo, platform colors)
→ Passport returned to service via callback

spec:
  auth:
    mode: sso

User clicks "Sign in"
→ Redirect to auth.acmeagency.com/oauth/authorize
  (CNAME → bio.tawa.pro; Acme's logo, colors; no "Powered by InsurEco")
→ Passport returned to service via callback
→ JWT iss = auth.acmeagency.com (Custom Issuer mode)

spec:
  auth:
    mode: sso
    passport:
      branding: true           # bundle vault branding into Passport

User fills out YOUR signup/login form
→ Your backend POSTs to bio.tawa.pro/api/embed/signup
→ Bio-ID returns tokens + Passport
→ Your backend sets cookies
→ User never knows Bio-ID exists

spec:
  auth:
    mode: sso
    passport:
      branding: true
      headless: true           # enables embed API for this client
      allowedOrigins:          # browser SDK callers (optional)
        - https://yourapp.com

import { BioAuth } from '@insureco/bio'

const bio = BioAuth.fromEnv()

// Signup — returns tokens + full Passport
const { access_token, refresh_token, user } = await bio.embed.signup({
  email: req.body.email,
  password: req.body.password,
  firstName: req.body.firstName,
  orgSlug: req.body.orgSlug,   // optional — omit to auto-create org
})

// Login
const tokens = await bio.embed.login({
  email: req.body.email,
  password: req.body.password,
})

// Magic link (you send the email yourself)
const { magicToken } = await bio.embed.createMagicLink({
  email: req.body.email,
})
// → Send magicToken via your own email/SMS system
// → User clicks link → your verify route calls bio.embed.verify({ token })

// Refresh
const tokens = await bio.embed.refresh({ refreshToken })

interface VaultBranding {
  // Public display — self-serve after claiming
  displayName: string            // shown on all surfaces (registry pages, headers)
  tagline?: string               // "Colorado's largest commercial agency"
  logoUrl?: string               // primary logo — SVG or PNG, hosted on vault CDN
  logoMarkUrl?: string           // icon/mark for small surfaces (32x32 avatars)
  primaryColor: string           // hex — buttons, links, accents
  secondaryColor?: string        // hex
  websiteUrl?: string
  phone?: string
  email?: string

  // White-label auth surface — requires whiteLabelApproved
  customDomain?: string          // auth.acmeagency.com (CNAME → bio.tawa.pro)
  hideEcoBranding: boolean       // remove "Powered by InsurEco" footer
  emailFromName?: string         // "Acme Insurance" — magic link sender name
  customCss?: string             // injected into consent page, max 10KB

  // Platform approval state
  verified: boolean              // platform confirmed this entity is real
  whiteLabelApproved: boolean    // approved for customDomain + hideEcoBranding + customCss
}

GET  /v1/branding/:orgSlug                    → 0 gas, public
GET  /v1/entities/:iecHash/branding           → 0 gas, public
PATCH /v1/entities/:iecHash/branding          → 2 gas, auth required (owner or admin)

{
  "displayName": "Acme Insurance Agency",
  "tagline": "Colorado commercial specialists",
  "logoUrl": "https://vault.ins.bio/assets/acme-agency/logo.svg",
  "logoMarkUrl": null,
  "primaryColor": "#E63946",
  "secondaryColor": "#1D3557",
  "websiteUrl": "https://acmeinsurance.com",
  "phone": "+17205550100",
  "email": "[email protected]",
  "customDomain": null,
  "hideEcoBranding": false,
  "emailFromName": null,
  "customCss": null,
  "verified": true,
  "whiteLabelApproved": false
}

import { VaultClient } from '@insureco/bio-vault'

const vault = VaultClient.fromEnv()

// By orgSlug — most common (you have it from the JWT)
const branding = await vault.getBranding('acme-agency')

// By iecHash — for public entity pages
const branding = await vault.getBrandingByHash('0x1a2b3c...')

Branded / White-Label:
  → User clicks "Sign up" on consent screen
  → Bio-ID creates user + auto-creates personal org (slug from name)
  → Passport minted with new org
  → Redirect back to service

Headless:
  → User fills your signup form
  → bio.embed.signup({ email, password, firstName })
  → Bio-ID creates user + auto-creates personal org
  → Tokens returned → your backend sets session

Admin creates invite:
  POST /api/v2/orgs/:orgSlug/invites
  { email, role, modules }
  → Bio-ID stores invite, sends email via relay (or returns inviteUrl for headless)

User clicks invite link:
  → Link format: https://{service}/join?invite=TOKEN
  → If user exists: attach to org with specified role
  → If user is new: signup form, then attach to org
  → Passport minted with inviting org as primary

Headless invite acceptance:
  const tokens = await bio.embed.signup({
    email,
    password,
    firstName,
    inviteToken: 'TOKEN',   // resolves to org + role
  })

// Your backend creates the user in the right org directly
const tokens = await bio.embed.signup({
  email: '[email protected]',
  password: tempPassword,
  firstName: 'New',
  lastName: 'Agent',
  orgSlug: 'acme-agency',     // user is created IN this org
  role: 'agent',               // with this role
})
// → User belongs to acme-agency immediately, no invite needed

Admin opens Console → Org Settings → Members → "Add Member"
  → Enters email, selects role, selects modules
  → Bio-ID creates invite record
  → Email sent via relay (branded with org's vault branding)
  → User clicks link → signup or login → lands in org
  → Admin sees new member in member list immediately (passport_updated event)

spec:
  auth:
    mode: sso

spec:
  auth:
    mode: sso
    passport:
      branding: true             # bundle org's vault branding into Passport
      scopes: [raterspot:rate]   # service needs these scopes resolved in Passport

spec:
  auth:
    mode: sso
    passport:
      branding: true
      headless: true
      allowedOrigins:
        - https://myapp.tawa.pro
        - https://staging.myapp.tawa.pro

{
  "serviceName": "my-service",
  "passportConfig": {
    "branding": true,
    "scopes": ["raterspot:rate"],
    "headless": true,
    "allowedOrigins": ["https://myapp.tawa.pro"]
  }
}

Passport Configuration
──────────────────────
Auth Mode:     SSO
Branding:      ✓ Enabled — org branding bundled into every token
Headless:      ✓ Enabled — embed API active
Scopes:        raterspot:rate, docman:read
Allowed Origins: https://myapp.tawa.pro

Passport Preview (for acme-agency)
──────────────────────────────────
{
  bioId: "USR-example",
  orgSlug: "acme-agency",
  branding: {
    displayName: "Acme Insurance Agency",
    logoUrl: "https://vault.ins.bio/assets/...",
    primaryColor: "#E63946",
    verified: true,
    whiteLabelApproved: false
  },
  permissions: {
    scopes: ["raterspot:rate"]
  }
}

Branding
────────
Display Name:  Acme Insurance Agency
Logo:          [uploaded] ✓
Primary Color: #E63946
Tagline:       Colorado commercial specialists

White-Label Status
──────────────────
Verified:              ✓
White-Label Approved:  ✗ (Request Approval)
Custom Domain:         — (set after approval)

1. User authenticates (any mode — PKCE, headless, magic link)
2. Bio-ID loads user record (bioId, email, orgs, roles)
3. Bio-ID checks the OAuth client's passportConfig (from Koko cache, 60s TTL)
4. If passportConfig.branding == true:
   → Fetch vault.ins.bio/v1/branding/{orgSlug} (cached 5min)
   → Bundle into passport.branding
5. If passportConfig.scopes is non-empty:
   → Resolve scopes from Koko for this service + user's org
   → Bundle into passport.permissions.scopes
6. If vault entity exists for orgSlug:
   → Include iecHash in passport
7. Sign JWT with RS256 private key
8. Return token + publish on Passport socket

sequenceDiagram
    participant User
    participant Service
    participant BioID
    participant Koko
    participant Vault

    User->>Service: Login request
    Service->>BioID: OAuth / Embed API
    BioID->>BioID: Load user record
    BioID->>Koko: Get passportConfig for service
    Koko-->>BioID: { branding: true, scopes: [...] }
    BioID->>Vault: GET /v1/branding/{orgSlug}
    Vault-->>BioID: { logoUrl, primaryColor, ... }
    BioID->>BioID: Assemble Passport
    BioID->>BioID: Sign RS256 JWT
    BioID-->>Service: Token (contains full Passport)
    BioID-->>User: Passport pushed on socket