> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens 컬렉션

`tokens`에는 일회용 토큰이 저장됩니다. 누군가 비밀번호를 설정할 수 있게 하는 링크 속 비밀 값입니다. 문서 하나가 토큰 하나입니다. Mongoose 모델은 없으며, web은 `services/web/app/src/Features/Security/OneTimeTokenHandler.mjs`를 통해 네이티브 드라이버로 컬렉션에 씁니다.

#### 필드

| 필드 | 타입 | 의미 | 출처 |
| - | - | - | - |
| `_id` | ObjectId | 문서 id. | `OneTimeTokenHandler.mjs:40` |
| `use` | String | 토큰의 용도. 아래 [용도](#uses)를 참조하세요. 모든 조회가 이 값으로 필터링합니다. | `OneTimeTokenHandler.mjs:41` |
| `token` | String | 링크 속 비밀 값: 무작위 32바이트를 16진수 64자로 나타내며 그대로 저장합니다. | `OneTimeTokenHandler.mjs:38,42` |
| `data` | Object | 토큰이 나타내는 내용으로, 토큰을 사용할 때 반환됩니다. | `OneTimeTokenHandler.mjs:43` |
| `data.user_id` | String | 사용자 id. 모든 호출자가 문자열로 기록합니다. | `services/web/app/src/Features/PasswordReset/PasswordResetHandler.mjs:27`, `services/web/app/src/Features/User/UserRegistrationHandler.mjs:117`, `services/web/modules/admin-tools/app/src/AdminUserManager.mjs:79` |
| `data.email` | String | 토큰을 만들 때의 사용자 이메일. 비밀번호 재설정은 이 기본 이메일로 사용자를 찾습니다(`PasswordResetHandler.mjs:66-70`). | `data.user_id`와 동일 |
| `createdAt` | Date | 생성 시각. TTL 인덱스가 90일 뒤 토큰을 삭제합니다. | `OneTimeTokenHandler.mjs:36,44` |
| `expiresAt` | Date | `createdAt`에 `expiresIn`초를 더한 값: 기본 1시간, 활성화 링크는 1주. 이후 조회는 토큰을 무시합니다. | `OneTimeTokenHandler.mjs:35-37,45` |
| `peekCount` | Number | 사용되지 않은 채 조회된 횟수. `peekValueFromToken`마다 1씩 늘며, 4(`MAX_PEEKS`)가 되면 토큰이 더 이상 작동하지 않습니다. | `OneTimeTokenHandler.mjs:8-31,107` |
| `usedAt` | Date | 토큰이 사용되거나 취소된 시각. 이 값이 있는 토큰은 조회에서 무시됩니다. | `OneTimeTokenHandler.mjs:51-104` |

#### 용도

| `use` | 기능 | 만료 | 코드 |
| - | - | - | - |
| `password` | "비밀번호를 잊으셨나요" 페이지에서 보내는 비밀번호 재설정 이메일 | 1시간 | `PasswordResetHandler.mjs:14-42` |
| `password` | 활성화 링크: 무작위 비밀번호로 계정을 만든 뒤 비밀번호를 설정하는 링크를 보냅니다. 공개 가입(`services/web/modules/login-register/app/src/RegisterController.mjs:65`), `user-activate`의 관리자 등록 페이지(`services/web/modules/user-activate/app/src/UserActivateController.mjs:27-30`), `create-user` 스크립트(`services/web/modules/server-ce-scripts/scripts/create-user.mjs:21`)에서 사용합니다 | 1주 | `UserRegistrationHandler.mjs:97-130` |
| `password` | 관리자 패널(모듈 `admin-tools`)에서 보내는 활성화 또는 비밀번호 재설정 링크 | 1주(활성화), 1시간(재설정) | `AdminUserManager.mjs:76-103,196-206` |
| `email_confirmation` | 이메일 확인 링크. 읽기만 합니다: 이제 확인 과정에서 6자리 코드를 보내므로 이 저장소에서 이런 토큰을 만드는 곳은 없습니다(`services/web/app/src/Features/User/UserEmailsConfirmationHandler.mjs:15-35`) | | `UserEmailsConfirmationHandler.mjs:12,37-66` |

#### 쓰는 코드

| 코드 | 역할 |
| - | - |
| `OneTimeTokenHandler.mjs:34-49` (`getNewToken`) | 토큰을 삽입합니다. 호출자: `PasswordResetHandler.mjs:28`, `UserRegistrationHandler.mjs:115-119`, `AdminUserManager.mjs:77-81`. |
| `OneTimeTokenHandler.mjs:8-32` (`peekValueFromToken`) | 유효한 토큰의 `data`를 반환하고 `peekCount`에 1을 더합니다. 비밀번호 재설정 페이지를 열 때(`services/web/app/src/Features/PasswordReset/PasswordResetController.mjs:195-208`), 새 비밀번호를 설정할 때 다시(`PasswordResetHandler.mjs:94-96`), 그리고 이메일 확인(`UserEmailsConfirmationHandler.mjs:38-41`)에서 사용합니다. |
| `OneTimeTokenHandler.mjs:75-88` (`expireToken`) | 토큰 하나에 `usedAt`을 설정합니다: 새 비밀번호를 설정한 후(`PasswordResetHandler.mjs:44-48,119`) 또는 이메일을 확인한 후(`UserEmailsConfirmationHandler.mjs:65`). |
| `OneTimeTokenHandler.mjs:90-104` (`expireAllTokensForUser`) | 사용자가 설정에서 비밀번호를 바꾸거나(`services/web/app/src/Features/User/UserController.mjs:146-149`) 관리자가 관리자 패널에서 설정할 때(`AdminUserManager.mjs:479-488`), 그 사용자의 열린 `password` 토큰 모두에 `usedAt`을 설정합니다. |

#### 읽는 코드

| 코드 | 역할 |
| - | - |
| `PasswordResetHandler.mjs:50-70,94-119` | 재설정 또는 활성화 토큰으로 사용자를 찾은 뒤 비밀번호를 설정합니다. `user-activate`의 활성화 페이지는 토큰을 이 양식에 넘기기만 합니다. |
| `UserEmailsConfirmationHandler.mjs:37-66` | 로그인한 사용자의 `email_confirmation` 토큰으로 이메일을 확인합니다. |
| `AdminUserManager.mjs:213-223` (module `admin-tools`) | 관리자 패널에 활성화 링크를 다시 표시하기 위해 사용자의 열린 활성화 토큰을 찾습니다. `db.tokens`를 직접 읽습니다. |

#### 인덱스

| 이름 | 키 | 옵션 | 마이그레이션 |
| - | - | - | - |
| `token_1_use_1` | `{ token: 1, use: 1 }` | 고유 | `20190912145031_create_tokens_indexes.mjs` |
| `createdAt_1` | `{ createdAt: 1 }` | TTL, `expireAfterSeconds: 7776000`(90일) | `20210407085118_token-expiry-with-ttl-index.mjs` |
| `data.user_id_1` | `{ "data.user_id": 1 }` | | `20231113173237_tokens_user_id_index.mjs` |

마이그레이션은 `tools/migrations/`에 있습니다.

#### 참고

* 사용했거나 만료된 토큰은 바로 삭제되지 않습니다. TTL 인덱스가 `createdAt` 90일 뒤 제거할 때까지 `usedAt` 또는 지난 `expiresAt`과 함께 남아 있습니다.
* `OneTimeTokenHandler`에는 `getValueFromTokenAndExpire`(`OneTimeTokenHandler.mjs:51-73`)도 있지만 이를 호출하는 곳은 없습니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.