Passport — Enriched Identity, Branding & Permissions

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 (when passport.includeBranding: true)
  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'
    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[]
}

// req.user IS the Passport — already populated by Janus or your middleware
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 vault lookup. No Koko call. It's already in the token.

import { useEffect, useState } from 'react'

const BIO_ID_URL = process.env.NEXT_PUBLIC_BIO_ID_URL || 'https://bio.insureco.io'

export function usePassport(token: string | null) {
  const [passport, setPassport] = useState<Passport | null>(null)

  useEffect(() => {
    if (!token) return

    const ws = new WebSocket(`${BIO_ID_URL.replace(/^http/, 'ws')}/passport?token=${token}`)

    ws.onmessage = (e) => {
      const { type, passport } = JSON.parse(e.data)
      if (type === 'identity' || type === 'passport_updated') setPassport(passport)
      if (type === 'revoked') setPassport(null)
    }

    ws.onclose = () => setPassport(null)
    return () => ws.close()
  }, [token])

  return passport
}

import WebSocket from 'ws'

const BIO_ID_URL = process.env.BIO_ID_URL || 'https://bio.insureco.io'

export function connectPassport(token: string, onIdentity: (passport: Passport) => void) {
  const ws = new WebSocket(`${BIO_ID_URL.replace(/^http/, 'ws')}/passport?token=${token}`)

  ws.on('message', (raw) => {
    const { type, passport } = JSON.parse(raw.toString())
    if (type === 'identity' || type === 'passport_updated') onIdentity(passport)
    if (type === 'revoked') process.exit(0)
  })

  return () => ws.close()
}

wss://bio.insureco.io/passport?token=<access_token>

spec:
  auth:
    mode: sso

spec:
  auth:
    mode: sso
    passport:
      includeBranding: true

spec:
  auth:
    mode: sso
    passport:
      includeBranding: true
      headless: true
      allowedOrigins:
        - https://yourapp.com

const bio = BioAuth.fromEnv()

// Signup — server-to-server, no redirect
const tokens = await bio.embed.signup({
  email, password, firstName,
  orgSlug: 'acme-agency',  // optional — omit to auto-create org
})

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

// Magic link (you send the email yourself)
const { magicToken } = await bio.embed.createMagicLink({ email })

// Verify magic token
const tokens = await bio.embed.verify({ token: magicToken })

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

Any mode → user signs up → Bio-ID auto-creates personal org (slug from name)
→ Passport minted with new org → user lands in service

Admin: POST /api/v2/orgs/:orgSlug/invites { email, role, modules }
→ Bio-ID stores invite, sends email (or returns inviteUrl for headless)
→ User clicks link → signup (if new) or login (if existing)
→ Attached to inviting org with specified role
→ Passport minted with inviting org as primary

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

// Create user directly in an org (requires org:manage scope)
const tokens = await bio.embed.signup({
  email: '[email protected]',
  password: tempPassword,
  firstName: 'New',
  orgSlug: 'acme-agency',
  role: 'agent',
})

GET  /v1/branding/:orgSlug                    → 0 gas, public
PATCH /v1/entities/:iecHash/branding          → 2 gas, auth required

import { VaultClient } from '@insureco/bio-vault'
const vault = VaultClient.fromEnv()

const branding = await vault.getBranding('acme-agency')