add swagger.yaml
This commit is contained in:
Bob Molitor
+626
@@ -0,0 +1,626 @@
|
|||||||
|
openapi: 3.1.0
|
||||||
|
info:
|
||||||
|
title: Trusted AI Auth API
|
||||||
|
version: '1.0.0'
|
||||||
|
description: >
|
||||||
|
Authentication and session-management endpoints required to reach the protected analyst UI
|
||||||
|
(dashboard, transaction review, company search, and company transactions).
|
||||||
|
servers:
|
||||||
|
- url: https://trusted-ai.local
|
||||||
|
description: Local development (composer run dev)
|
||||||
|
- url: https://api.trusted-ai.example.com
|
||||||
|
description: Production
|
||||||
|
tags:
|
||||||
|
- name: Auth
|
||||||
|
description: Credential, session, and verification endpoints.
|
||||||
|
- name: TwoFactor
|
||||||
|
description: Manage the analyst’s Time-based One Time Password (TOTP) second factor.
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
sessionCookie:
|
||||||
|
type: apiKey
|
||||||
|
in: cookie
|
||||||
|
name: laravel_session
|
||||||
|
description: Issued after login/two-factor completion; required for all protected routes.
|
||||||
|
xsrfToken:
|
||||||
|
type: apiKey
|
||||||
|
in: header
|
||||||
|
name: X-XSRF-TOKEN
|
||||||
|
description: CSRF token minted via `/sanctum/csrf-cookie` (or HTML meta); required by state-changing requests.
|
||||||
|
schemas:
|
||||||
|
AuthUser:
|
||||||
|
type: object
|
||||||
|
required: [id, name, email, emailVerified]
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: integer
|
||||||
|
format: int64
|
||||||
|
example: 143
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
example: Alex Analyst
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
example: analyst@example.com
|
||||||
|
emailVerified:
|
||||||
|
type: boolean
|
||||||
|
description: Indicates whether the analyst passes the `verified` middleware.
|
||||||
|
example: true
|
||||||
|
emailVerifiedAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
nullable: true
|
||||||
|
example: '2024-03-18T08:31:12Z'
|
||||||
|
roles:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example: [analyst]
|
||||||
|
createdAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
updatedAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
LoginResponse:
|
||||||
|
type: object
|
||||||
|
required: [user, twoFactorRequired]
|
||||||
|
properties:
|
||||||
|
user:
|
||||||
|
$ref: '#/components/schemas/AuthUser'
|
||||||
|
twoFactorRequired:
|
||||||
|
type: boolean
|
||||||
|
description: True when the next step is `/two-factor-challenge`.
|
||||||
|
example: false
|
||||||
|
TwoFactorPending:
|
||||||
|
type: object
|
||||||
|
required: [twoFactorRequired]
|
||||||
|
properties:
|
||||||
|
twoFactorRequired:
|
||||||
|
type: boolean
|
||||||
|
const: true
|
||||||
|
challengeToken:
|
||||||
|
type: string
|
||||||
|
description: Echo of the `login.id` stored server-side; clients must keep the accompanying session cookie.
|
||||||
|
example: 9b6c11f7-527a-4dc9-9c2b-8923e7c7a418
|
||||||
|
remember:
|
||||||
|
type: boolean
|
||||||
|
description: Remember-me preference preserved through the challenge.
|
||||||
|
example: true
|
||||||
|
TwoFactorSuccess:
|
||||||
|
type: object
|
||||||
|
required: [user]
|
||||||
|
properties:
|
||||||
|
user:
|
||||||
|
$ref: '#/components/schemas/AuthUser'
|
||||||
|
ValidationError:
|
||||||
|
type: object
|
||||||
|
required: [message, errors]
|
||||||
|
properties:
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
example: The given data was invalid.
|
||||||
|
errors:
|
||||||
|
type: object
|
||||||
|
additionalProperties:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example:
|
||||||
|
email:
|
||||||
|
- These credentials do not match our records.
|
||||||
|
MessageResponse:
|
||||||
|
type: object
|
||||||
|
required: [message]
|
||||||
|
properties:
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
example: If an account exists, a reset link has been sent.
|
||||||
|
TooManyRequestsError:
|
||||||
|
type: object
|
||||||
|
required: [message, retryAfterSeconds]
|
||||||
|
properties:
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
example: Too many login attempts. Try again in 48 seconds.
|
||||||
|
retryAfterSeconds:
|
||||||
|
type: integer
|
||||||
|
example: 48
|
||||||
|
RecoveryCodes:
|
||||||
|
type: object
|
||||||
|
required: [codes]
|
||||||
|
properties:
|
||||||
|
codes:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example: [JQ7L-9PKM, ZG28-5TQF]
|
||||||
|
QrCodeSvg:
|
||||||
|
type: object
|
||||||
|
required: [svg]
|
||||||
|
properties:
|
||||||
|
svg:
|
||||||
|
type: string
|
||||||
|
format: byte
|
||||||
|
description: Base64-encoded SVG markup for authenticator enrollment.
|
||||||
|
SecretKey:
|
||||||
|
type: object
|
||||||
|
required: [secret]
|
||||||
|
properties:
|
||||||
|
secret:
|
||||||
|
type: string
|
||||||
|
description: Plain-text TOTP secret for manual entry.
|
||||||
|
example: NB2W45DFOIZA====
|
||||||
|
paths:
|
||||||
|
/auth/session:
|
||||||
|
get:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Fetch the authenticated analyst
|
||||||
|
description: >
|
||||||
|
Confirms session status and email verification before loading guarded UI routes.
|
||||||
|
security:
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Active, verified session.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/AuthUser'
|
||||||
|
'401':
|
||||||
|
description: Missing or expired session cookie.
|
||||||
|
'403':
|
||||||
|
description: Analyst authenticated but email remains unverified.
|
||||||
|
/login:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Authenticate an analyst
|
||||||
|
description: >
|
||||||
|
Validates credentials and issues a new session cookie, matching the login Volt component.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [email, password]
|
||||||
|
properties:
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
example: analyst@example.com
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
example: correct-horse-battery-staple
|
||||||
|
remember:
|
||||||
|
type: boolean
|
||||||
|
default: false
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Login successful; analyst may navigate to protected pages.
|
||||||
|
headers:
|
||||||
|
Set-Cookie:
|
||||||
|
description: Refreshed `laravel_session` cookie.
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/LoginResponse'
|
||||||
|
'202':
|
||||||
|
description: Second factor required before granting access.
|
||||||
|
headers:
|
||||||
|
Set-Cookie:
|
||||||
|
description: Session cookie plus `login.id`/`login.remember` context.
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/TwoFactorPending'
|
||||||
|
'422':
|
||||||
|
description: Validation failed (bad credentials, throttled).
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
'429':
|
||||||
|
description: Too many attempts; obey lockout timings.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/TooManyRequestsError'
|
||||||
|
/two-factor-challenge:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Confirm the TOTP or recovery code
|
||||||
|
description: >
|
||||||
|
Completes the pending session when two-factor authentication is enabled.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
oneOf:
|
||||||
|
- required: [code]
|
||||||
|
properties:
|
||||||
|
code:
|
||||||
|
type: string
|
||||||
|
pattern: '^\d{6}$'
|
||||||
|
description: 6-digit TOTP value.
|
||||||
|
- required: [recovery_code]
|
||||||
|
properties:
|
||||||
|
recovery_code:
|
||||||
|
type: string
|
||||||
|
description: Emergency recovery code.
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Two-factor validated; session promoted to fully authenticated.
|
||||||
|
headers:
|
||||||
|
Set-Cookie:
|
||||||
|
description: Session cookie extended per remember-me preference.
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/TwoFactorSuccess'
|
||||||
|
'422':
|
||||||
|
description: Invalid TOTP or recovery code.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
'429':
|
||||||
|
description: Too many challenge attempts (Fortify `two-factor` limiter).
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/TooManyRequestsError'
|
||||||
|
/logout:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Terminate the active session
|
||||||
|
description: >
|
||||||
|
Logs the analyst out and invalidates the session cookie.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Logout succeeded; client should discard session cookies.
|
||||||
|
'401':
|
||||||
|
description: Analyst was not logged in.
|
||||||
|
/register:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Register a new analyst
|
||||||
|
description: >
|
||||||
|
Creates an account and authenticates immediately, matching the register Volt component.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [name, email, password, password_confirmation]
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
example: Jamie Investigator
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
password_confirmation:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: Account created; dashboard can load.
|
||||||
|
headers:
|
||||||
|
Set-Cookie:
|
||||||
|
description: Session cookie for the new account.
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/LoginResponse'
|
||||||
|
'422':
|
||||||
|
description: Validation errors (duplicate email, weak password, mismatch).
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
/forgot-password:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Send password reset link
|
||||||
|
description: >
|
||||||
|
Sends the reset email while obscuring account existence.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [email]
|
||||||
|
properties:
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
responses:
|
||||||
|
'202':
|
||||||
|
description: Reset notification dispatched if the account exists.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MessageResponse'
|
||||||
|
'422':
|
||||||
|
description: Email field invalid.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
/reset-password:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Reset password with token
|
||||||
|
description: >
|
||||||
|
Applies a valid reset token and forces the analyst to log in again.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [token, email, password, password_confirmation]
|
||||||
|
properties:
|
||||||
|
token:
|
||||||
|
type: string
|
||||||
|
description: Token from the password reset email.
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
password_confirmation:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Password updated; analyst should be redirected to `/login`.
|
||||||
|
'422':
|
||||||
|
description: Invalid token or password validation failure.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
/user/confirm-password:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Confirm password for sensitive operations
|
||||||
|
description: >
|
||||||
|
Required before enabling/disabling 2FA when the `password.confirm` middleware is active.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [password]
|
||||||
|
properties:
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
format: password
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Password confirmed for the next 900 seconds.
|
||||||
|
'422':
|
||||||
|
description: Wrong password submitted.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
/email/verification-notification:
|
||||||
|
post:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Resend email verification link
|
||||||
|
description: >
|
||||||
|
Needed because dashboard and investigation routes require the `verified` middleware.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'202':
|
||||||
|
description: Verification email dispatched (throttled at 6/hour).
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MessageResponse'
|
||||||
|
'429':
|
||||||
|
description: Throttle limit exceeded.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/TooManyRequestsError'
|
||||||
|
/email/verify/{id}/{hash}:
|
||||||
|
get:
|
||||||
|
tags: [Auth]
|
||||||
|
summary: Mark email address as verified
|
||||||
|
description: >
|
||||||
|
Consumes the signed verification link and redirects to the front end.
|
||||||
|
parameters:
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
- name: hash
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
- name: signature
|
||||||
|
in: query
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
- name: expires
|
||||||
|
in: query
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: integer
|
||||||
|
responses:
|
||||||
|
'302':
|
||||||
|
description: Redirect to `/dashboard?verified=1` (default).
|
||||||
|
headers:
|
||||||
|
Location:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
'403':
|
||||||
|
description: Link expired or signature mismatch.
|
||||||
|
/user/two-factor-authentication:
|
||||||
|
post:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: Start enrolling two-factor authentication
|
||||||
|
description: >
|
||||||
|
Generates the TOTP secret and makes QR/manual data available.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Enrollment started; fetch QR/secret next.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/MessageResponse'
|
||||||
|
example:
|
||||||
|
message: Two-factor authentication seed generated.
|
||||||
|
'423':
|
||||||
|
description: Password confirmation required.
|
||||||
|
'429':
|
||||||
|
description: Too many enable attempts.
|
||||||
|
delete:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: Disable two-factor authentication
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Two-factor disabled and secrets cleared.
|
||||||
|
'423':
|
||||||
|
description: Password confirmation required.
|
||||||
|
/user/confirmed-two-factor-authentication:
|
||||||
|
post:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: Confirm two-factor setup
|
||||||
|
description: >
|
||||||
|
Completes enrollment by verifying a TOTP code.
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
required: [code]
|
||||||
|
properties:
|
||||||
|
code:
|
||||||
|
type: string
|
||||||
|
pattern: '^\d{6}$'
|
||||||
|
description: 6-digit TOTP code.
|
||||||
|
responses:
|
||||||
|
'204':
|
||||||
|
description: Two-factor authentication confirmed.
|
||||||
|
'422':
|
||||||
|
description: Invalid confirmation code.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ValidationError'
|
||||||
|
/user/two-factor-qr-code:
|
||||||
|
get:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: Retrieve QR code SVG
|
||||||
|
description: >
|
||||||
|
Supplies the SVG rendered in the settings modal during enrollment.
|
||||||
|
security:
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: SVG payload for authenticator scanning.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/QrCodeSvg'
|
||||||
|
'404':
|
||||||
|
description: Two-factor enrollment not in progress.
|
||||||
|
/user/two-factor-secret-key:
|
||||||
|
get:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: Retrieve manual setup key
|
||||||
|
description: >
|
||||||
|
Provides the fallback alphanumeric key shown alongside the QR code.
|
||||||
|
security:
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Secret key for manual entry.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/SecretKey'
|
||||||
|
/user/two-factor-recovery-codes:
|
||||||
|
get:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: List recovery codes
|
||||||
|
security:
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Recovery codes ready for display or download.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/RecoveryCodes'
|
||||||
|
post:
|
||||||
|
tags: [TwoFactor]
|
||||||
|
summary: Regenerate recovery codes
|
||||||
|
security:
|
||||||
|
- xsrfToken: []
|
||||||
|
- sessionCookie: []
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: New recovery codes generated and returned.
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/RecoveryCodes'
|
||||||
|
'423':
|
||||||
|
description: Password confirmation required.
|
||||||
Reference in New Issue
Block a user