Janady13/missionmatch / internal/modules/auth/dto.go

1// Package auth is the first party authentication and accounts module. It produces a verified 2// (org_id, user_id, role) from an opaque server side session and feeds that, and only that, into the 3// tenant resolver, replacing the dev X-Org-ID header. The cryptographic primitives live in 4// internal/platform/security; this package wires them to the database (through the SECURITY DEFINER 5// functions in migration 0009) and to HTTP. 6package auth 7 8import ( 9 "github.com/missionworkforce/missionmatch/internal/platform/audit" 10 "github.com/missionworkforce/missionmatch/internal/platform/orgsettings" 11 "github.com/missionworkforce/missionmatch/internal/platform/security" 12 "github.com/missionworkforce/missionmatch/internal/platform/tenant" 13) 14 15// Cookie names. The session cookie uses the __Host- prefix, which a browser only accepts when the 16// cookie is Secure, Path=/, and has no Domain, so it cannot be planted by a sibling subdomain. The 17// prefix and the Secure attribute must agree: a __Host- cookie without Secure is silently dropped by 18// the browser. So the name is chosen to match the Secure flag (the secure name in production, a plain 19// name only for plain http local dev). Production config requires CookieSecure true. 20const ( 21 SessionCookie = "__Host-mm_session" 22 CSRFCookie = "__Host-mm_csrf" 23 CSRFHeader = "X-CSRF-Token" 24 sessionCookieInsecure = "mm_session" 25 csrfCookieInsecure = "mm_csrf" 26) 27 28// Deps is everything the service needs, assembled in cmd/api from config. Keys never have defaults; 29// they come from the secrets file through config. 30type Deps struct { 31 DB *tenant.DB 32 Audit *audit.Writer 33 Hasher *security.Hasher 34 Tagger *security.Tagger 35 TOTP security.TOTP 36 TOTPKEKs map[int][]byte // key_version to AES 256 key, for decrypt 37 TOTPKEKActive int // version new secrets are sealed under 38 TOTPIssuer string 39 IdleSeconds int 40 AbsoluteSeconds int 41 PendingSeconds int 42 InviteSeconds int 43 CookieSecure bool 44 MFADisabled bool // pilot only: when true, login and invite accept mint an active session with no TOTP step. The zero value (false) keeps MFA mandatory, so a Deps built without setting it is secure by default. 45 // OperatorMFADisabled stands down the operator only second factor of amendment 6 decision 1. Like 46 // MFADisabled the ZERO VALUE keeps the rule ON, so a Deps built without setting it is secure by default 47 // and every test that does not mention it proves the amendment's behaviour rather than the exception. 48 // Config refuses it in a production MM_ENV. 49 OperatorMFADisabled bool 50 // Settings resolves the organization's own mail configuration so an invitation can be delivered from the 51 // customer's address rather than handed to an administrator to forward. NIL IS A SUPPORTED STATE and 52 // means the pilot behaviour: the one time link is returned in the response and a human delivers it. 53 Settings *orgsettings.Store 54 // AppBaseURL is the public address of the web application, used to build the activation link in an 55 // invitation. Empty means no link is built and the raw code is sent with an instruction instead, because 56 // a guessed hostname in a credential bearing email is worse than none. 57 AppBaseURL string 58} 59 60// LoginInput is a password login attempt. 61type LoginInput struct { 62 Email string `json:"email"` 63 Password string `json:"password"` 64} 65 66// LoginResult tells the SPA whether to show the enroll or the verify step. Token is set as the 67// session cookie by the handler, never returned in the body. When MFARequired is false the issued 68// session is already active, so the SPA skips the MFA step and goes straight to the app. 69type LoginResult struct { 70 Token string `json:"-"` 71 MFAEnrolled bool `json:"mfa_enrolled"` 72 MFARequired bool `json:"mfa_required"` 73} 74 75// CodeInput carries a submitted six digit TOTP code or a recovery code. 76type CodeInput struct { 77 Code string `json:"code"` 78} 79 80// EnrollResult returns the provisioning material shown once during enrollment. 81type EnrollResult struct { 82 OTPAuthURI string `json:"otpauth_uri"` 83 Secret string `json:"secret"` 84} 85 86// ActivateResult returns the recovery codes shown exactly once on activation. Token is the new active 87// session cookie. 88type ActivateResult struct { 89 Token string `json:"-"` 90 RecoveryCodes []string `json:"recovery_codes"` 91} 92 93// TokenResult is a bare new session token for the handler to set as a cookie. 94type TokenResult struct { 95 Token string `json:"-"` 96} 97 98// InviteInput is an owner or admin inviting a user into their org. 99type InviteInput struct { 100 Email string `json:"email"` 101 FullName string `json:"full_name"` 102 Role string `json:"role"` 103 // Tools is the product set the new account starts with. Carried on the invite so creating an account 104 // and granting its access are ONE operation: entitlement fails closed, so an account created without 105 // this would exist but see nothing, and the operator would have to notice and fix it in a second step. 106 // Bounded by the same rule as a later change: the inviter may only confer tools they hold themselves. 107 Tools []string `json:"tools"` 108} 109 110// InviteResult returns the one time activation link token for manual delivery at pilot. 111type InviteResult struct { 112 // Token is the one time activation link, and it is EMPTY when Delivered is true. Once the credential has 113 // reached the invited person by mail there is no reason for a second copy to exist in an administrator's 114 // browser. 115 Token string `json:"token,omitempty"` 116 UserID string `json:"user_id"` 117 // Delivered reports that the organization's own mail server accepted the message. 118 Delivered bool `json:"delivered"` 119 // DeliveredTo echoes the address it went to, so the administrator can see it reached the right person. 120 DeliveredTo string `json:"delivered_to,omitempty"` 121 // DeliveryNote explains why the link came back instead of being mailed. It is present only when delivery 122 // did not happen, and it is guidance for the administrator, never an error: the invitation succeeded 123 // either way. 124 DeliveryNote string `json:"delivery_note,omitempty"` 125} 126 127// AcceptInput redeems an invite or activation link and sets the password. 128type AcceptInput struct { 129 Token string `json:"token"` 130 Password string `json:"password"` 131} 132 133// ChangePasswordInput changes the authenticated user's password. 134type ChangePasswordInput struct { 135 OldPassword string `json:"old_password"` 136 NewPassword string `json:"new_password"` 137} 138 139// RoleChangeInput sets a target user's role. 140type RoleChangeInput struct { 141 Role string `json:"role"` 142} 143 144// StatusChangeInput enables or disables a target user. 145type StatusChangeInput struct { 146 Status string `json:"status"` 147} 148 149// SessionInfo is the SPA view of the current session. No secrets. 150type SessionInfo struct { 151 UserID string `json:"user_id"` 152 OrgID string `json:"org_id"` 153 Role string `json:"role"` 154 MFAEnrolled bool `json:"mfa_enrolled"` 155 // Capabilities is the caller's resolved permission list, computed from the same matrix the server 156 // enforces. It exists so the interface stops gating on role name comparisons, which duplicate the 157 // matrix in TypeScript where it drifts, and cannot express a permission that does not map cleanly 158 // onto one role. 159 // 160 // The server remains the only authority. This list decides what is OFFERED, never what is allowed, 161 // and every endpoint keeps its own gate. 162 Capabilities []string `json:"capabilities"` 163 164 // Tools is the caller's granted product set: which of missionMATCH, screenMATCH, slateMATCH, and 165 // recruitMATCH exist for them at all. Separate from Capabilities because role answers what a person 166 // may DO and this answers what they may SEE, and the two vary independently between clients. 167 // 168 // Like Capabilities this decides what is OFFERED, never what is allowed: each tool's route group 169 // carries its own server side gate, so a hidden tool is refused at the API even if the interface is 170 // bypassed entirely. 171 Tools []string `json:"tools"` 172 173 // OrgTools is what the ORGANIZATION is entitled to, which is a different question from what this 174 // caller holds, and amendment 6 decision 13 needs both to say WHY a control is disabled: the tenant 175 // never bought the product, or the actor personally does not hold it. Sending it from the server means 176 // the two reasons are computed from one source rather than guessed in TypeScript. 177 // 178 // There is no organization level product entitlement table yet (the open design point recorded in the 179 // ledger), so today every tenant is entitled to all four and this carries the full vocabulary. When the 180 // Phase 5A operator console lands the per tool entitlement, only this value narrows and no client 181 // changes, which is the whole reason it is a field rather than a constant in the bundle. 182 OrgTools []string `json:"org_tools"` 183 184 // The caller's own identity, so the profile screen renders current values without a second endpoint and 185 // so a name change propagates everywhere the identity renders on the next session read. Amendment 6 186 // decision 4 and acceptance item 36. 187 FullName string `json:"full_name"` 188 Title string `json:"title"` 189 Phone string `json:"phone"` 190} 191 192// UserSummary is one row of the org user list. No secrets. 193type UserSummary struct { 194 ID string `json:"id"` 195 Email string `json:"email"` 196 FullName string `json:"full_name"` 197 Role string `json:"role"` 198 Status string `json:"status"` 199 MFAEnrolled bool `json:"mfa_enrolled"` 200 // Tools is this user's granted product set, so the People screen can show and edit what they SEE 201 // alongside what they may do. Always present, empty rather than null, so the client can iterate. 202 Tools []string `json:"tools"` 203 // LastLoginAt was the other half of a two part defect. The column was never written, and it was also 204 // never returned, so fixing only the write would have left the People screen still showing "never 205 // signed in" for everyone and the fix would have looked like it failed. 206 LastLoginAt *string `json:"last_login_at,omitempty"` 207} 208 209// ToolsChangeInput replaces a user's tool entitlement. The field is the COMPLETE intended set, not a 210// delta: the result is exactly these tools, so one request can express "these and no others" and a client 211// that has drifted from the server cannot re grant something it believed was already absent. 212type ToolsChangeInput struct { 213 Tools []string `json:"tools"` 214} 215