Topolo Auth

Documentation Map

• Application hub
• Machine system JSON
• applications/auth
• reference/api/topolo-auth

What It Is

Central identity, personal workspace and household-membership authority, organization-scoped role catalog, service registry, service lifecycle/accessibility and surface-classification authority, API key authority, app-switcher catalog/preference authority, browser/headless Auth SDK owner, Flutter Auth SDK owner, principal metadata source for service-local identities, and billable org-seat authority across the platform.

Canonical documentation for Topolo Auth lives in `PlatformApplications/TopoloDocs`.

Use this repository for implementation only. Local product and operational docs have been retired in favor of the docs application.

API Reference

Coverage: curated

Source: PlatformApplications/TopoloAuth/src/controllers/auth.js

Source exists in repo: yes

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`, 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, 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, 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 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, 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, 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:

API key scopes

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

Deployments

Deployment environments: production

Routes: auth.stg.topolo.us, auth.topolo.app

Observability enabled: yes

Wrangler surfaces

• PlatformApplications/TopoloAuth/wrangler.toml -> topolo-auth-staging

Build and deploy commands

• build — PlatformApplications/TopoloAuth/package.json :: wrangler deploy --dry-run --outdir .wrangler/build
• deploy — PlatformApplications/TopoloAuth/package.json :: wrangler deploy
• deploy:staging — PlatformApplications/TopoloAuth/package.json :: wrangler deploy
• deploy:production — PlatformApplications/TopoloAuth/package.json :: wrangler deploy --env production
• deploy:dry-run — PlatformApplications/TopoloAuth/package.json :: wrangler deploy --dry-run --outdir .wrangler/build
• build — PlatformApplications/TopoloAuth/packages/topolo-auth-client/package.json :: tsup src/index.ts --format esm,cjs --dts

Failure Modes

No default failure-mode heuristics are currently flagged for this system.

Debugging Runbooks

Start with these entrypoints:

• PlatformApplications/TopoloAuth/wrangler.toml
• PlatformApplications/TopoloAuth/src/controllers/auth.js
• PlatformApplications/TopoloAuth/README.md
• PlatformApplications/TopoloAuth/package.json
• PlatformApplications/TopoloAuth/packages/topolo-auth-client/package.json

Change Log / Verification

Lifecycle: active

Last verified: 2026-04-29

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.