mirror of
https://github.com/zkldi/Tachi.git
synced 2026-09-28 09:58:11 +03:00
zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
284 lines
7.0 KiB
Markdown
284 lines
7.0 KiB
Markdown
# Internal Authentication
|
|
|
|
These endpoints relate to internal authentication methods. Read the warning below.
|
|
|
|
!!! danger
|
|
This is **NOT** for external use. You should **NEVER**
|
|
be requesting a username and password from a user.
|
|
|
|
Furthermore, interacting with this programmatically
|
|
is near-impossible because you need to complete a CAPTCHA.
|
|
|
|
Nevertheless, This is documented for completeness' sake.
|
|
|
|
!!! warning
|
|
All of these endpoints are aggressively rate limited. If you fire a bot at this, you will probably get
|
|
your IP blacklisted. Don't do that.
|
|
|
|
---
|
|
|
|
## Login with username and password.
|
|
|
|
`POST /api/v1/auth/login`
|
|
|
|
Logs a user in and returns a session cookie.
|
|
|
|
### Parameters
|
|
|
|
| Property | Type | Description |
|
|
| :---------: | :----: | :---------------------------------------------------------------------------------------: |
|
|
| `username` | String | The user's username. This is compared case-insensitively. |
|
|
| `!password` | String | The user's password. |
|
|
| `captcha` | String | Information about the captcha filled out by the user. We use a Google ReCaptcha instance. |
|
|
|
|
!!! info
|
|
The `!` prefix is special in that anything with it is assumed to be private and is **always**
|
|
ignored by our request logger.
|
|
|
|
Without it, we would log passwords!
|
|
|
|
### Response
|
|
|
|
| Property | Type | Description |
|
|
| :------: | :-----: | :--------------------------------------: |
|
|
| `userID` | Integer | The ID of the user you authenticated as. |
|
|
|
|
| HTTP Header | Description |
|
|
| :----------: | :--------------------------------------------------: |
|
|
| `Set-Cookie` | Contains a session cookie for future authentication. |
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
|
|
```
|
|
POST /api/v1/auth/login
|
|
```
|
|
|
|
```json
|
|
{
|
|
"username": "zkldi",
|
|
"!password": "my_password",
|
|
"captcha": "herebedragons"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"userID": 1
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Register a new account.
|
|
|
|
`POST /api/v1/auth/register`
|
|
|
|
### Parameters
|
|
|
|
| Property | Type | Description |
|
|
| :----------------------------: | :------------------------------------: | :------------------------------------------------------------------------------------------------------------------: |
|
|
| `username` | String | A string between 3 and 20 characters. The first character must be A-Z, _ or -. The other 19 may be A-Z, 0-9, _ or -. |
|
|
| `!password` | String | An 8 character or longer string. |
|
|
| `!email` | String | Valid email. The `!` prefix keeps this field out of server request logs. |
|
|
| `inviteCode` (Kamaitachi Only) | String (Undefined/Unused on Bokutachi) | If on Kamaitachi, this is the user's invitation code. |
|
|
| `captcha` | String | |
|
|
|
|
### Response
|
|
|
|
| Property | Type | Description |
|
|
| :------: | :-----------------------------------: | :-------------------------------------: |
|
|
| `<body>` | [UserDocument](../../schemas/user.md) | The newly-created user's User Document. |
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
|
|
```
|
|
POST /api/v1/auth/register
|
|
```
|
|
|
|
```json
|
|
{
|
|
"username": "newGuy",
|
|
"!password": "my_password",
|
|
"captcha": "herebedragons",
|
|
"!email": "test@example.com"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"id": 2,
|
|
"username": "newGuy",
|
|
"usernameLowercase": "newguy",
|
|
"socialMedia": {
|
|
"discord": null,
|
|
"twitter": null,
|
|
"github": null,
|
|
"steam": null,
|
|
"youtube": null,
|
|
"twitch": null
|
|
},
|
|
"joinDate": 1639628634978,
|
|
"lastSeen": 1639628634978,
|
|
"about": "I'm a fairly nondescript person.",
|
|
"status": null,
|
|
"customPfpLocation": null,
|
|
"customBannerLocation": null,
|
|
"clan": null,
|
|
"badges": [],
|
|
"authLevel": 1
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Verify an email from the code that was sent to it.
|
|
|
|
`POST /api/v1/auth/verify-email`
|
|
|
|
### Parameters
|
|
|
|
| Property | Type | Description |
|
|
| :------: | :----: | :------------------------------------------: |
|
|
| `code` | String | The Code that was sent to the users mailbox. |
|
|
|
|
### Response
|
|
|
|
Empty Object
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
|
|
```
|
|
{
|
|
"code": "abcdef1234567890"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
Empty Object.
|
|
|
|
---
|
|
|
|
## Resend a verification email to the requesting user's email address.
|
|
|
|
`POST /api/v1/auth/resend-verify-email`
|
|
|
|
**Requires Self-Key Level Auth**
|
|
|
|
### Parameters
|
|
|
|
None, This endpoint reads the requesting user from their session.
|
|
|
|
### Response
|
|
|
|
Empty object.
|
|
|
|
### Example
|
|
|
|
N/A
|
|
|
|
---
|
|
|
|
## Log Out.
|
|
|
|
`POST /api/v1/auth/logout`
|
|
|
|
Destroys the current session associated with this cookie.
|
|
|
|
### Parameters
|
|
|
|
None.
|
|
|
|
### Response
|
|
|
|
Empty Object.
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
|
|
```
|
|
POST /api/v1/auth/logout
|
|
```
|
|
|
|
#### Response
|
|
|
|
Nothing.
|
|
|
|
---
|
|
|
|
## Create a password reset code and send it to the provided email.
|
|
|
|
`POST /api/v1/auth/forgot-password`
|
|
|
|
!!! note
|
|
This endpoint sends the password reset code pretty-printed to the email, and is **NOT**
|
|
returned as part of the HTTP request.
|
|
|
|
### Parameters
|
|
|
|
| Property | Type | Description |
|
|
| :------: | :----: | :-------------------------------------------------------------------------------------------------------------: |
|
|
| `!email` | String | A user's email. If the email does not correspond to any accounts, 202 is returned anyway as a security measure. Request logs omit this field. |
|
|
|
|
### Response
|
|
|
|
Empty Object. The endpoint immediately returns 202 to avoid giving away information about registered emails.
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
|
|
```js
|
|
{
|
|
"!email": "zkldiv@gmail.com"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
Although the request body returns nothing, `zkldiv@gmail.com` will have recieved an email with
|
|
a URL containing the password reset code.
|
|
|
|
---
|
|
|
|
## Reset a user's password with a password reset code.
|
|
|
|
`POST /api/v1/auth/reset-password`
|
|
|
|
### Parameters
|
|
|
|
| Property | Type | Description |
|
|
| :---------: | :----: | :----------------------------------------------------------------: |
|
|
| `code` | String | A password reset code. This is provided in a password reset email. |
|
|
| `!password` | String | The password to change to. |
|
|
|
|
### Response
|
|
|
|
Empty Object.
|
|
|
|
### Example
|
|
|
|
#### Request
|
|
|
|
```js
|
|
{
|
|
"code": "1234567890abcdef",
|
|
"!password": "zkldi_so_cool",
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
|
|
Empty Object.
|