{"service":"auth-onamerica","version":"2.0.0","mesh_role":"Fleet Authorization Service for all MHS ventures on *.onamerica.org","base_url":"https://auth-onamerica.ron-helms.workers.dev","ticket":"CH-2026-0402-HASCOM-001","identity_model":{"description":"One email, one person, many ventures. Universal identity with sovereign MHS ID.","mhs_id_format":"MHS-{seq}.{variant}-{suffix} (e.g. MHS-00001.A-CAPT)","tables":{"onamerica_users":"Universal identity — id, mhs_id, email, name, phone","onamerica_tenants":"Venture registry — id, code, name, industry_id, domain","onamerica_industries":"Hierarchical taxonomy — id, code, name, parent_industry_id","onamerica_user_tenants":"M:N membership — user_id, tenant_id, role, tier, verification_status","onamerica_sessions":"Device + venture sessions","onamerica_ops_log":"Universal audit trail","magic_tokens":"Ephemeral 8-digit consent codes (15-min TTL, single-use)"}},"consent_model":{"principle":"Maximum automation between consent gates. Every gate is explicit human affirmation.","gates":["Gate 0: Email entry (identity declaration)","Gate 1: 8-digit code entry (consent to authenticate — code from email, typed into requesting portal)","Gate 2: Biometric opt-in (consent to provision device — first login per device)","Gate 2': Biometric scan (reauthorization — instant access on provisioned devices)"],"token_security":{"generation":"crypto.getRandomValues() — 8-digit random per request","lifecycle":"Single-use. Prior tokens invalidated on new request. Burns after 5 failed attempts.","expiry":"15-minute TTL from creation","transport":"HTTPS only. Code travels via email (MTA relay). User types code into HTTPS page."}},"endpoints":[{"method":"POST","path":"/api/auth/magic-link","description":"Send 8-digit consent code to email","body":"{ email, venture? }","response":"{ sent, token, name }","auth":false},{"method":"GET","path":"/api/auth/token-status/:token","description":"Poll for consent confirmation","response":"{ consumed, player: { id, mhsId, name, email, role, tenants[] } }","auth":false},{"method":"GET","path":"/api/auth/verify-token/:token","description":"One-time code verification (flips 0→1)","response":"HTML auto-close page","auth":false},{"method":"POST","path":"/api/auth/code","description":"Checkin code login (venture-specific)","body":"{ code, venture? }","response":"{ success, player }","auth":false},{"method":"GET","path":"/api/auth/role/:email","description":"Resolve role for venture context","response":"{ email, role, tier, verified, tenants[] }","auth":false},{"method":"GET","path":"/api/auth/staff","description":"List staff for venture","response":"{ staff[] }","auth":false,"note":"Venture resolved from Origin/X-Venture header"},{"method":"GET","path":"/api/auth/mhs-id/:email","description":"Look up MHS ID","response":"{ mhs_id, seq, name, email }","auth":false},{"method":"PUT","path":"/api/auth/mhs-id/suffix","description":"Self-service MHS ID suffix change","body":"{ email, suffix }","response":"{ mhs_id }","auth":true},{"method":"GET","path":"/api/verify/:id/confirm?by=email","description":"Trust chain: confirm","auth":false},{"method":"GET","path":"/api/verify/:id/followup?by=email","description":"Trust chain: follow up","auth":false},{"method":"GET","path":"/api/verify/:id/deny?by=email","description":"Trust chain: deny","auth":false},{"method":"GET","path":"/api/verifications/pending","description":"List pending verifications","auth":false},{"method":"GET","path":"/.well-known/fleet-auth.json","description":"This spec (machine-readable)","auth":false}],"venture_context":{"resolution_order":["1. Explicit \"venture\" field in request body","2. X-Venture header","3. Origin header domain matching (golflink.onamerica.org → golflink)","4. Default: golflink"],"registered_ventures":[{"code":"golflink","domain":"golflink.onamerica.org","customer":"Vets Whole In One","product_domain":"golflink.cc","industry":"veterans"},{"code":"pad","domain":"weyland.onamerica.org","customer":"Precision Auto Doors","product_domain":"weyland.onamerica.org","industry":"doors"},{"code":"mhs","domain":"helmcorp.cc","customer":null,"product_domain":"helmcorp.cc","industry":"technology"}],"industries":[{"code":"construction","name":"Construction","parent":null},{"code":"doors","name":"Door Hardware","parent":"ind_construction"},{"code":"electrical","name":"Electrical","parent":"ind_construction"},{"code":"mechanical","name":"Mechanical","parent":"ind_construction"},{"code":"nonprofit","name":"Nonprofit Organizations","parent":null},{"code":"technology","name":"Technology","parent":null},{"code":"veterans","name":"Veteran Services","parent":"ind_nonprofit"}]},"joining":{"description":"How to onboard a new venture or service into the fleet auth mesh.","steps":["1. Register your venture: INSERT INTO onamerica_tenants (id, code, name, industry_id, domain) VALUES (...)","2. Point your login page to POST /api/auth/magic-link with {email, venture: \"your_code\"}","3. Show 8-digit code input. Poll GET /api/auth/token-status/:token every 3s.","4. On consumed=true, store the player object (includes mhsId + tenants array).","5. For venture-scoped API calls, exchange fleet identity for your venture JWT via your own /api/auth/fleet-exchange endpoint.","6. Optional: POST /api/auth/invite to let admins invite team members by email."],"venture_worker_contract":{"description":"Your venture worker must implement these routes to integrate with fleet auth:","routes":["POST /api/auth/fleet-exchange — accept fleet JWT, create/match local user, return venture-scoped JWT + tenant list","GET /api/user/tenants — return tenants for authenticated user (populates workspace switcher)","GET/POST/DELETE /api/tenants/:id/members — team management"]},"consent_constraints":{"rule":"Every cross-system operation requires consent from both parties. Fleet auth publishes identity. Your service subscribes to it. Neither stores the other's credentials.","token_chain":"Fleet JWT → Venture JWT → API calls. Each hop is a consent boundary.","guest_access":"Pre-consented view-only tokens bypass fleet auth. Your service issues these directly."},"compliance":{"encryption":"All D1 data encrypted at rest (Cloudflare platform). WebAuthn keys never leave device.","soc2":"Auditable consent chain in onamerica_ops_log. Every auth event logged.","gdpr":"Explicit consent at every gate. Right to deletion cascades through all tables. Data minimization enforced."}},"existing_fleet_services":[{"service":"auth-onamerica","url":"https://auth-onamerica.ron-helms.workers.dev","role":"Authentication, consent exchange, MHS ID, trust chain"},{"service":"comms-onamerica","url":"https://comms-onamerica.ron-helms.workers.dev","role":"Email, SMS, follow-up delivery"},{"service":"events-onamerica","url":"https://events-onamerica.ron-helms.workers.dev","role":"Event lifecycle, phase machine, registration"},{"service":"profiles-onamerica","url":"https://profiles-onamerica.ron-helms.workers.dev","role":"Cross-venture identity, profile management"},{"service":"auth-onamerica-biometric","url":"https://auth-onamerica-biometric.ron-helms.workers.dev","role":"Biometric registration + assertion (WebAuthn/FIDO2)"},{"service":"golflink-onamerica-api","url":"https://golflink-onamerica-api.ron-helms.workers.dev","role":"Golf-specific: pairings, grading, scoring (venture backend)"},{"service":"golflink-onamerica-live","url":"https://golflink-onamerica-live.ron-helms.workers.dev","role":"Golf real-time: WebSocket events (venture channel)"},{"service":"golflink-onamerica-mail","url":"https://golflink-onamerica-mail.ron-helms.workers.dev","role":"Golf email relay (migrating to fleet comms)"}]}