Topolo Auth
Central identity, personal workspace and household-membership authority, organization-context selection authority for org-scoped service entry, organization-scoped role catalog, service registry, role-scoped default platform-service access policy, service lifecycle/accessibility and surface-classification authority, API key authority, app-switcher catalog/preference and platform shell-theme authority, browser/headless Auth SDK owner, Flutter Auth SDK owner, principal metadata source for service-local and agent identities, billable org-seat authority, and AI workforce credential/token authority across the platform.
Documentation Map
What It Is
Central identity, personal workspace and household-membership authority, organization-context selection authority for org-scoped service entry, organization-scoped role catalog, service registry, role-scoped default platform-service access policy, service lifecycle/accessibility and surface-classification authority, API key authority, app-switcher catalog/preference and platform shell-theme authority, browser/headless Auth SDK owner, Flutter Auth SDK owner, principal metadata source for service-local and agent identities, billable org-seat authority, and AI workforce credential/token authority across the platform.
Architecture
Owners: identity-platform
Source repos: apps/system/TopoloAuth, apps/system/TopoloAuth/packages/topolo-auth-client, apps/system/TopoloAuth/packages/topolo_auth_flutter
Dependencies: None registered
Repo shape
No repo surface entries were detected from the registered repo paths.
Runtime Surfaces
Hosts:
https://auth.topolo.app https://auth.stg.topolo.us No wrangler surface was discovered under the registered repo paths.
API Reference
Coverage: curated
Source: PlatformApplications/TopoloAuth/src/controllers/auth.js
Source exists in repo: no
Curated Topolo Auth reference supplements controller-backed route behavior, including personal workspace plus household membership and selected-household ownership, verified personal recovery email ownership through `user_email_addresses`, `/api/me/recovery-email`, and `/recovery-email/verify`, Admin-created organization owner activation through Auth `/password-reset` password setup before TopoloOne onboarding, explicit active-context resolution for only `personal` and `organization`, household and dependent management routes, `PUT /api/me/selected-household`, org-scoped role and bundle management, app-switcher service catalog/preference routes including user-level `preferences.theme` for shared shell dark/light persistence, service surface classification fields that distinguish launchable applications from API, runtime, and internal services, launcher `supported_contexts` metadata for workspace scopes only, launcher `household_capable` metadata for personal-profile family-aware apps, service-level `quick_links` and `command_palette.quick_links` persisted from Topolo Developers-owned app marketing metadata, included/free app-switcher install grants, normal first-party org-service grants for launcher-visible Topolo apps such as Spaces and Consent, plus Auth runtime role-scoped default platform-service access, first-party app onboarding completion through `organization_services.onboarding_completed_at`, per-user role walkthrough progress through `user_service_onboarding`, admin/owner-only app login while onboarding is pending, Auth billable-seat evaluation plus org billing preview and portal proxy routes, production Smart Placement for the D1-backed login and SSO hot path, first-party embedded password login restricted by browser Origin, return URL, and registered first-party service metadata, shared browser-client suppression of cookie-refresh probes on explicit first-party `/login` routes, shared first-party LoginPage password boundary-whitespace normalization, password reveal, Auth signup handoff, and failed-login submitted-length hints before credential submission, hosted Auth login/signup password reveal plus signup links that preserve return URL, service id, and response mode, public signup identity and personal-context creation that does not grant paid application entitlement except for the explicit Developers workspace grant path, Auth-hosted third-party OAuth browser consent that any signed-in Topolo identity can approve for a registered client while showing publisher, callback domain, requested scopes, and trust state, Auth audit events for third-party OAuth consent approvals and denials with actor, client, owner, callback-domain, scope, and trust-state context, edge-budget WebCrypto PBKDF2 password hashing with non-blocking rehash of older bcrypt/PBKDF2/SHA records and combined security/passkey reads, static-origin CORS handling that skips service-catalog hydration for first-party, isolated `*.stg.topolo.us`, and no-Origin requests while preserving dynamic third-party host checks, signed MFA challenges that avoid repeated password verification during TOTP, backup-code, or passkey completion, browser and registered-native SSO one-time exchange codes with single-pass authorize-time active user, org, and service-access validation plus service-scoped browser token issue and atomic code consumption, bearer-backed handoff-code creation that preserves the source token's active organization context through destination service token issuance, the production SSO callback-origin catalog and live metadata audit, the manifest-derived service permission, role-bundle, API-key scope, and organization-role permission catalog synced to production D1 on 2026-04-19, the planned TopoloP2P human/agent principal classes, grants, API-key scopes, and org policy inputs enforced by Auth while P2P owns action, ledger, and settlement state, staging-only synthetic load seeding through deterministic `syn_*` organizations, users, memberships, and org-service grants in `centralized-auth-staging`, staging-only TopoloSeed platform-admin bootstrap for the Auth `admin` organization and `srv_N2cf0CIg2CvT` seat assignment, the production MDM service catalog migration from legacy `svc_nodo_*` identifiers to canonical `svc_topolo_*` identifiers on 2026-04-23, the canonical `@topolo/auth-client` package without a legacy token-based `exchangeSSOToken` handoff helper, the canonical `topolo_auth_flutter` package with SDK-started callback state validation and Auth-hydrated startup restore, TopoloOne developer-application intake, the approved-app registration handoff consumed by Topolo Developers review and first-party scaffold provisioning, optional first-party launcher plus login/landing/app UI config upserts during that handoff, explicit ownerType/portfolio/audience/tenancy/surface metadata plus distribution metadata for developer-owned services so Topolo first-party platform/personal apps and third-party business/personal apps stay distinct in one registration pipeline while organization-internal apps are filtered out of Auth-backed launcher discovery and Developers-owned store discovery, built-in bindable-resource catalogs such as `developer_app:*` for approved Developers registrations, and the rule that third-party partner/customer/supplier sub-surfaces stay under the owning application service id instead of registering separate platform services. Auth remains the identity and authorization source of truth and should not own Topolo Developers draft, submission, store read-model, build-request, review persistence, TopoloP2P action rail, ledger, settlement state, or paid marketplace checkout.
This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.
Auth and Permissions
Depends on Topolo Auth: yes
Service IDs:
srv_mKShvFV4c8Z3 API key scopes
View machine credentials
Resource pattern: none
Create or revoke machine credentials
Resource pattern: none
View audit logs and security events
Resource pattern: none
View organization details
Resource pattern: none
Create and edit organizations
Resource pattern: none
View permission assignments
Resource pattern: none
Manage user permissions
Resource pattern: none
View service role bundles
Resource pattern: none
Manage service role bundles
Resource pattern: none
View registered services
Resource pattern: none
Manage service registrations
Resource pattern: none
View user sessions and access state
Resource pattern: none
Revoke or rotate user sessions
Resource pattern: none
Delete or suspend user accounts
Resource pattern: none
View user accounts and profiles
Resource pattern: none
Create and edit user accounts
Resource pattern: none
Service permissions
api_keys:read, api_keys:write, audit:read, organizations:read, organizations:write, permissions:read, permissions:write, roles:read, roles:write, services:read, services:write, sessions:read, sessions:write, users:delete, users:read, users:write
Data Ownership
No storage bindings were derived from wrangler configuration.
Queues / Cron / Workflows
Queue bindings:
No queue bindings were detected.
Cron triggers
No cron triggers were detected.
Workflow signals
No explicit queue/workflow script or cron signal was discovered.
Environment Variables and Bindings
Environment variables:
No environment variables were derived from wrangler configuration.
All wrangler bindings
No bindings were derived from wrangler configuration.
Deployments
Deployment environments: default only or not declared
Routes: workers.dev or Pages-only delivery
Observability enabled: no explicit setting found
Failure Modes
- No wrangler.toml surface was discovered under the registered repo paths.
- The registered contract source is missing: PlatformApplications/TopoloAuth/src/controllers/auth.js
- Neither OpenAPI nor README-derived interface detail was found.
Debugging Runbooks
Start with these entrypoints:
- PlatformApplications/TopoloAuth/src/controllers/auth.js
Change Log / Verification
Lifecycle: active
Last verified: 2026-05-14
Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.