authkit-api 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/LICENSE +21 -0
  3. package/README.md +125 -2
  4. package/bin/cli.js +8 -0
  5. package/package.json +76 -4
  6. package/src/constants.js +29 -0
  7. package/src/generator.js +142 -0
  8. package/src/index.js +99 -0
  9. package/src/prompts.js +59 -0
  10. package/src/utils/fs.js +36 -0
  11. package/src/utils/logger.js +8 -0
  12. package/src/utils/packageJson.js +16 -0
  13. package/src/utils/validateProjectName.js +19 -0
  14. package/templates/base/Dockerfile +22 -0
  15. package/templates/base/README.md +108 -0
  16. package/templates/base/_dockerignore +16 -0
  17. package/templates/base/_env.example +25 -0
  18. package/templates/base/_gitignore +5 -0
  19. package/templates/base/_husky/pre-commit +1 -0
  20. package/templates/base/_prettierignore +5 -0
  21. package/templates/base/_prettierrc +1 -0
  22. package/templates/base/package.json +62 -0
  23. package/templates/base/scripts/docker-entrypoint.sh +9 -0
  24. package/templates/base/scripts/generate-postman.ts +102 -0
  25. package/templates/base/scripts/seed-admin.ts +62 -0
  26. package/templates/base/src/app.ts +46 -0
  27. package/templates/base/src/config/env.schema.ts +85 -0
  28. package/templates/base/src/config/env.ts +15 -0
  29. package/templates/base/src/config/logger.ts +20 -0
  30. package/templates/base/src/constants/examples.ts +3 -0
  31. package/templates/base/src/constants/roles.ts +4 -0
  32. package/templates/base/src/constants/user.rules.ts +16 -0
  33. package/templates/base/src/docs/openapi.registry.ts +90 -0
  34. package/templates/base/src/docs/openapi.ts +36 -0
  35. package/templates/base/src/docs/paths/auth.paths.ts +88 -0
  36. package/templates/base/src/docs/paths/user.paths.ts +88 -0
  37. package/templates/base/src/middlewares/authenticate.ts +20 -0
  38. package/templates/base/src/middlewares/authorize.ts +13 -0
  39. package/templates/base/src/middlewares/errorHandler.ts +52 -0
  40. package/templates/base/src/middlewares/notFound.ts +6 -0
  41. package/templates/base/src/middlewares/rateLimiter.ts +20 -0
  42. package/templates/base/src/middlewares/validate.ts +39 -0
  43. package/templates/base/src/modules/auth/auth.controller.ts +45 -0
  44. package/templates/base/src/modules/auth/auth.cookie.ts +22 -0
  45. package/templates/base/src/modules/auth/auth.routes.ts +12 -0
  46. package/templates/base/src/modules/auth/auth.service.ts +81 -0
  47. package/templates/base/src/modules/auth/auth.validation.ts +44 -0
  48. package/templates/base/src/modules/user/user.controller.ts +24 -0
  49. package/templates/base/src/modules/user/user.routes.ts +22 -0
  50. package/templates/base/src/modules/user/user.service.ts +57 -0
  51. package/templates/base/src/modules/user/user.validation.ts +27 -0
  52. package/templates/base/src/routes/docs.routes.ts +16 -0
  53. package/templates/base/src/routes/health.routes.ts +17 -0
  54. package/templates/base/src/routes/index.ts +13 -0
  55. package/templates/base/src/server.ts +51 -0
  56. package/templates/base/src/types/express.d.ts +14 -0
  57. package/templates/base/src/utils/ApiError.ts +35 -0
  58. package/templates/base/src/utils/apiResponse.ts +24 -0
  59. package/templates/base/src/utils/password.ts +14 -0
  60. package/templates/base/src/utils/token.ts +60 -0
  61. package/templates/base/src/utils/zod.ts +5 -0
  62. package/templates/base/tests/app.test.ts +67 -0
  63. package/templates/base/tests/auth.test.ts +194 -0
  64. package/templates/base/tests/authenticate.test.ts +61 -0
  65. package/templates/base/tests/docs.test.ts +127 -0
  66. package/templates/base/tests/env.test.ts +96 -0
  67. package/templates/base/tests/health.test.ts +21 -0
  68. package/templates/base/tests/helpers/auth.helper.ts +49 -0
  69. package/templates/base/tests/password.test.ts +18 -0
  70. package/templates/base/tests/postman.test.ts +32 -0
  71. package/templates/base/tests/rateLimiter.test.ts +27 -0
  72. package/templates/base/tests/seedAdmin.test.ts +42 -0
  73. package/templates/base/tests/token.test.ts +69 -0
  74. package/templates/base/tests/trustProxy.test.ts +24 -0
  75. package/templates/base/tests/user.repository.test.ts +211 -0
  76. package/templates/base/tests/user.test.ts +145 -0
  77. package/templates/base/tests/validate.test.ts +42 -0
  78. package/templates/base/tests/validation.test.ts +62 -0
  79. package/templates/base/vitest.config.ts +16 -0
  80. package/templates/databases/mongodb/README.part.md +23 -0
  81. package/templates/databases/mongodb/_github/workflows/ci.yml +29 -0
  82. package/templates/databases/mongodb/docker-compose.yml +30 -0
  83. package/templates/databases/mongodb/env.part +2 -0
  84. package/templates/databases/mongodb/package.part.json +4 -0
  85. package/templates/databases/mongodb/src/database/connection.ts +46 -0
  86. package/templates/databases/mongodb/src/database/env.schema.ts +3 -0
  87. package/templates/databases/mongodb/src/database/id.schema.ts +3 -0
  88. package/templates/databases/mongodb/src/database/models/refreshToken.model.ts +24 -0
  89. package/templates/databases/mongodb/src/database/models/user.model.ts +52 -0
  90. package/templates/databases/mongodb/src/modules/user/user.repository.ts +91 -0
  91. package/templates/databases/mongodb/tests/globalSetup.ts +13 -0
  92. package/templates/databases/mongodb/tests/setup.ts +17 -0
  93. package/templates/databases/postgres/README.part.md +31 -0
  94. package/templates/databases/postgres/_github/workflows/ci.yml +46 -0
  95. package/templates/databases/postgres/docker-compose.yml +34 -0
  96. package/templates/databases/postgres/env.part +2 -0
  97. package/templates/databases/postgres/package.part.json +15 -0
  98. package/templates/databases/postgres/prisma/migrations/20261030073256_init/migration.sql +39 -0
  99. package/templates/databases/postgres/prisma/migrations/migration_lock.toml +3 -0
  100. package/templates/databases/postgres/prisma/schema.prisma +39 -0
  101. package/templates/databases/postgres/prisma.config.ts +14 -0
  102. package/templates/databases/postgres/src/database/connection.ts +72 -0
  103. package/templates/databases/postgres/src/database/env.schema.ts +3 -0
  104. package/templates/databases/postgres/src/database/id.schema.ts +3 -0
  105. package/templates/databases/postgres/src/database/prisma.ts +9 -0
  106. package/templates/databases/postgres/src/modules/user/user.repository.ts +111 -0
  107. package/templates/databases/postgres/tests/connection.test.ts +19 -0
  108. package/templates/databases/postgres/tests/globalSetup.ts +66 -0
  109. package/templates/databases/postgres/tests/prismaSchema.test.ts +27 -0
  110. package/templates/databases/postgres/tests/setup.ts +15 -0
  111. package/templates/languages/js/eslint.config.js +23 -0
  112. package/templates/languages/ts/eslint.config.js +30 -0
  113. package/templates/languages/ts/package.part.json +21 -0
  114. package/templates/languages/ts/tsconfig.json +15 -0
  115. package/templates-js/base/Dockerfile +22 -0
  116. package/templates-js/base/README.md +108 -0
  117. package/templates-js/base/_dockerignore +16 -0
  118. package/templates-js/base/_env.example +25 -0
  119. package/templates-js/base/_gitignore +5 -0
  120. package/templates-js/base/_husky/pre-commit +1 -0
  121. package/templates-js/base/_prettierignore +5 -0
  122. package/templates-js/base/_prettierrc +1 -0
  123. package/templates-js/base/package.json +62 -0
  124. package/templates-js/base/scripts/docker-entrypoint.sh +9 -0
  125. package/templates-js/base/scripts/generate-postman.js +70 -0
  126. package/templates-js/base/scripts/seed-admin.js +61 -0
  127. package/templates-js/base/src/app.js +46 -0
  128. package/templates-js/base/src/config/env.js +15 -0
  129. package/templates-js/base/src/config/env.schema.js +85 -0
  130. package/templates-js/base/src/config/logger.js +20 -0
  131. package/templates-js/base/src/constants/examples.js +3 -0
  132. package/templates-js/base/src/constants/roles.js +2 -0
  133. package/templates-js/base/src/constants/user.rules.js +16 -0
  134. package/templates-js/base/src/docs/openapi.js +26 -0
  135. package/templates-js/base/src/docs/openapi.registry.js +81 -0
  136. package/templates-js/base/src/docs/paths/auth.paths.js +87 -0
  137. package/templates-js/base/src/docs/paths/user.paths.js +87 -0
  138. package/templates-js/base/src/middlewares/authenticate.js +19 -0
  139. package/templates-js/base/src/middlewares/authorize.js +11 -0
  140. package/templates-js/base/src/middlewares/errorHandler.js +35 -0
  141. package/templates-js/base/src/middlewares/notFound.js +5 -0
  142. package/templates-js/base/src/middlewares/rateLimiter.js +20 -0
  143. package/templates-js/base/src/middlewares/validate.js +31 -0
  144. package/templates-js/base/src/modules/auth/auth.controller.js +40 -0
  145. package/templates-js/base/src/modules/auth/auth.cookie.js +21 -0
  146. package/templates-js/base/src/modules/auth/auth.routes.js +12 -0
  147. package/templates-js/base/src/modules/auth/auth.service.js +79 -0
  148. package/templates-js/base/src/modules/auth/auth.validation.js +41 -0
  149. package/templates-js/base/src/modules/user/user.controller.js +21 -0
  150. package/templates-js/base/src/modules/user/user.routes.js +22 -0
  151. package/templates-js/base/src/modules/user/user.service.js +19 -0
  152. package/templates-js/base/src/modules/user/user.validation.js +24 -0
  153. package/templates-js/base/src/routes/docs.routes.js +16 -0
  154. package/templates-js/base/src/routes/health.routes.js +17 -0
  155. package/templates-js/base/src/routes/index.js +13 -0
  156. package/templates-js/base/src/server.js +50 -0
  157. package/templates-js/base/src/utils/ApiError.js +32 -0
  158. package/templates-js/base/src/utils/apiResponse.js +8 -0
  159. package/templates-js/base/src/utils/password.js +14 -0
  160. package/templates-js/base/src/utils/token.js +46 -0
  161. package/templates-js/base/src/utils/zod.js +5 -0
  162. package/templates-js/base/tests/app.test.js +67 -0
  163. package/templates-js/base/tests/auth.test.js +185 -0
  164. package/templates-js/base/tests/authenticate.test.js +61 -0
  165. package/templates-js/base/tests/docs.test.js +115 -0
  166. package/templates-js/base/tests/env.test.js +94 -0
  167. package/templates-js/base/tests/health.test.js +21 -0
  168. package/templates-js/base/tests/helpers/auth.helper.js +41 -0
  169. package/templates-js/base/tests/password.test.js +18 -0
  170. package/templates-js/base/tests/postman.test.js +31 -0
  171. package/templates-js/base/tests/rateLimiter.test.js +27 -0
  172. package/templates-js/base/tests/seedAdmin.test.js +42 -0
  173. package/templates-js/base/tests/token.test.js +69 -0
  174. package/templates-js/base/tests/trustProxy.test.js +24 -0
  175. package/templates-js/base/tests/user.repository.test.js +210 -0
  176. package/templates-js/base/tests/user.test.js +144 -0
  177. package/templates-js/base/tests/validate.test.js +35 -0
  178. package/templates-js/base/tests/validation.test.js +61 -0
  179. package/templates-js/base/vitest.config.js +16 -0
  180. package/templates-js/databases/mongodb/README.part.md +23 -0
  181. package/templates-js/databases/mongodb/_github/workflows/ci.yml +29 -0
  182. package/templates-js/databases/mongodb/docker-compose.yml +30 -0
  183. package/templates-js/databases/mongodb/env.part +2 -0
  184. package/templates-js/databases/mongodb/package.part.json +4 -0
  185. package/templates-js/databases/mongodb/src/database/connection.js +39 -0
  186. package/templates-js/databases/mongodb/src/database/env.schema.js +3 -0
  187. package/templates-js/databases/mongodb/src/database/id.schema.js +3 -0
  188. package/templates-js/databases/mongodb/src/database/models/refreshToken.model.js +15 -0
  189. package/templates-js/databases/mongodb/src/database/models/user.model.js +41 -0
  190. package/templates-js/databases/mongodb/src/modules/user/user.repository.js +68 -0
  191. package/templates-js/databases/mongodb/tests/globalSetup.js +13 -0
  192. package/templates-js/databases/mongodb/tests/setup.js +17 -0
  193. package/templates-js/databases/postgres/README.part.md +31 -0
  194. package/templates-js/databases/postgres/_github/workflows/ci.yml +46 -0
  195. package/templates-js/databases/postgres/docker-compose.yml +34 -0
  196. package/templates-js/databases/postgres/env.part +2 -0
  197. package/templates-js/databases/postgres/package.part.json +15 -0
  198. package/templates-js/databases/postgres/prisma/migrations/20261030073256_init/migration.sql +39 -0
  199. package/templates-js/databases/postgres/prisma/migrations/migration_lock.toml +3 -0
  200. package/templates-js/databases/postgres/prisma/schema.prisma +39 -0
  201. package/templates-js/databases/postgres/prisma.config.js +14 -0
  202. package/templates-js/databases/postgres/src/database/connection.js +61 -0
  203. package/templates-js/databases/postgres/src/database/env.schema.js +3 -0
  204. package/templates-js/databases/postgres/src/database/id.schema.js +3 -0
  205. package/templates-js/databases/postgres/src/database/prisma.js +9 -0
  206. package/templates-js/databases/postgres/src/modules/user/user.repository.js +88 -0
  207. package/templates-js/databases/postgres/tests/connection.test.js +17 -0
  208. package/templates-js/databases/postgres/tests/globalSetup.js +60 -0
  209. package/templates-js/databases/postgres/tests/prismaSchema.test.js +27 -0
  210. package/templates-js/databases/postgres/tests/setup.js +15 -0
@@ -0,0 +1,69 @@
1
+ import jwt from 'jsonwebtoken';
2
+ import { afterEach, describe, expect, it, vi } from 'vitest';
3
+ import { env } from '../src/config/env.js';
4
+ import {
5
+ hashToken,
6
+ signAccessToken,
7
+ signRefreshToken,
8
+ verifyAccessToken,
9
+ verifyRefreshToken,
10
+ } from '../src/utils/token.js';
11
+
12
+ const expect401 = (fn) => {
13
+ try {
14
+ fn();
15
+ } catch (err) {
16
+ expect(err.statusCode).toBe(401);
17
+ return;
18
+ }
19
+ throw new Error('expected a 401 ApiError');
20
+ };
21
+
22
+ afterEach(() => vi.useRealTimers());
23
+
24
+ describe('tokens', () => {
25
+ it('round-trips an access token', () => {
26
+ const token = signAccessToken({ userId: 'u1', role: 'user' });
27
+ expect(verifyAccessToken(token)).toEqual({ userId: 'u1', role: 'user' });
28
+ });
29
+ it('round-trips a refresh token and returns expiresAt from exp', () => {
30
+ const { token, expiresAt } = signRefreshToken({ userId: 'u1' });
31
+ expect(verifyRefreshToken(token)).toEqual({ userId: 'u1' });
32
+ const days = (expiresAt.getTime() - Date.now()) / 86_400_000;
33
+ expect(days).toBeGreaterThan(6.9);
34
+ expect(days).toBeLessThan(7.1);
35
+ });
36
+ it('rejects a refresh token as access token and vice versa', () => {
37
+ const access = signAccessToken({ userId: 'u1', role: 'user' });
38
+ const { token: refresh } = signRefreshToken({ userId: 'u1' });
39
+ expect401(() => verifyAccessToken(refresh));
40
+ expect401(() => verifyRefreshToken(access));
41
+ });
42
+ it('rejects a tampered token', () => {
43
+ const token = signAccessToken({ userId: 'u1', role: 'user' });
44
+ const [header, payload, signature] = token.split('.');
45
+ const forged = JSON.parse(Buffer.from(payload, 'base64url').toString());
46
+ forged.sub = 'u2';
47
+ const tampered = `${header}.${Buffer.from(JSON.stringify(forged)).toString('base64url')}.${signature}`;
48
+ expect401(() => verifyAccessToken(tampered));
49
+ });
50
+ it('rejects a refresh-typed token signed with the access secret', () => {
51
+ const token = jwt.sign({ sub: 'u1', role: 'user', type: 'refresh' }, env.JWT_ACCESS_SECRET);
52
+ expect401(() => verifyAccessToken(token));
53
+ });
54
+ it('rejects garbage', () => {
55
+ expect401(() => verifyAccessToken('garbage'));
56
+ });
57
+ it('rejects an expired token', () => {
58
+ vi.useFakeTimers();
59
+ vi.setSystemTime(new Date('2030-01-01T00:00:00Z'));
60
+ const token = signAccessToken({ userId: 'u1', role: 'user' });
61
+ vi.setSystemTime(new Date('2030-01-01T00:16:00Z'));
62
+ expect401(() => verifyAccessToken(token));
63
+ });
64
+ it('hashToken is deterministic sha-256 hex', () => {
65
+ expect(hashToken('a')).toBe(hashToken('a'));
66
+ expect(hashToken('a')).toHaveLength(64);
67
+ expect(hashToken('a')).not.toBe(hashToken('b'));
68
+ });
69
+ });
@@ -0,0 +1,24 @@
1
+ import express from 'express';
2
+ import request from 'supertest';
3
+ import { describe, expect, it, vi } from 'vitest';
4
+
5
+ vi.mock('../src/config/env.js', async (importOriginal) => {
6
+ const { env } = await importOriginal();
7
+ return { env: { ...env, TRUST_PROXY: 1 } };
8
+ });
9
+
10
+ const { createApp } = await import('../src/app.js');
11
+
12
+ describe('TRUST_PROXY', () => {
13
+ it('sets Express trust proxy, so req.ip comes from X-Forwarded-For', async () => {
14
+ const app = createApp();
15
+ expect(app.get('trust proxy')).toBe(1);
16
+
17
+ // req.ip is what the rate limiter keys on.
18
+ const probe = express();
19
+ probe.set('trust proxy', app.get('trust proxy'));
20
+ probe.get('/ip', (req, res) => res.json({ ip: req.ip }));
21
+ const res = await request(probe).get('/ip').set('X-Forwarded-For', '1.2.3.4');
22
+ expect(res.body.ip).toBe('1.2.3.4');
23
+ });
24
+ });
@@ -0,0 +1,210 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import { mapDatabaseError } from '../src/database/connection.js';
3
+ import * as userRepository from '../src/modules/user/user.repository.js';
4
+ import { hashPassword } from '../src/utils/password.js';
5
+
6
+ let counter = 0;
7
+ const uniqueEmail = () => `user${(counter += 1)}-${Date.now()}@example.com`;
8
+
9
+ async function createUser(overrides = {}) {
10
+ return userRepository.create({
11
+ name: 'Test User',
12
+ email: uniqueEmail(),
13
+ password: await hashPassword('Password123'),
14
+ ...overrides,
15
+ });
16
+ }
17
+
18
+ const inOneHour = () => new Date(Date.now() + 60 * 60 * 1000);
19
+
20
+ describe('user repository', () => {
21
+ describe('create and find', () => {
22
+ it('returns a public user without internal fields', async () => {
23
+ const user = await userRepository.create({
24
+ name: 'Ada Lovelace',
25
+ email: 'Ada.Lovelace@Example.com',
26
+ password: await hashPassword('Password123'),
27
+ });
28
+
29
+ expect(user).toMatchObject({
30
+ name: 'Ada Lovelace',
31
+ email: 'ada.lovelace@example.com',
32
+ role: 'user',
33
+ });
34
+ expect(typeof user.id).toBe('string');
35
+ expect(user.createdAt).toBeInstanceOf(Date);
36
+ expect(user.updatedAt).toBeInstanceOf(Date);
37
+ expect(Object.keys(user).sort()).toEqual(
38
+ ['createdAt', 'email', 'id', 'name', 'role', 'updatedAt'].sort(),
39
+ );
40
+ });
41
+
42
+ it('findById returns the created user', async () => {
43
+ const created = await createUser();
44
+
45
+ expect(await userRepository.findById(created.id)).toEqual(created);
46
+ });
47
+
48
+ it('findByEmail hides the password unless asked for it', async () => {
49
+ const created = await createUser();
50
+
51
+ const plain = await userRepository.findByEmail(created.email);
52
+ expect(plain).toEqual(created);
53
+ expect(plain).not.toHaveProperty('password');
54
+
55
+ const withPassword = await userRepository.findByEmail(created.email, {
56
+ withPassword: true,
57
+ });
58
+ expect(withPassword.password).toMatch(/^\$argon2/);
59
+ expect(withPassword.id).toBe(created.id);
60
+ expect(withPassword).not.toHaveProperty('_id');
61
+ });
62
+
63
+ it('findByEmail returns null for an unknown email', async () => {
64
+ expect(await userRepository.findByEmail('nobody@example.com')).toBeNull();
65
+ });
66
+ });
67
+
68
+ describe('duplicate emails', () => {
69
+ it('rejects a second create with the same email and maps it to 409', async () => {
70
+ const email = uniqueEmail();
71
+ await createUser({ email });
72
+
73
+ const error = await createUser({ email }).catch((err) => err);
74
+
75
+ expect(error).toBeInstanceOf(Error);
76
+ expect(mapDatabaseError(error)).toMatchObject({
77
+ statusCode: 409,
78
+ message: 'Email is already registered',
79
+ });
80
+ });
81
+
82
+ it('lets exactly one of two simultaneous creates win; the other maps to 409', async () => {
83
+ const email = uniqueEmail();
84
+ const password = await hashPassword('Password123');
85
+
86
+ const results = await Promise.allSettled([
87
+ userRepository.create({ name: 'Racer One', email, password }),
88
+ userRepository.create({ name: 'Racer Two', email, password }),
89
+ ]);
90
+
91
+ const fulfilled = results.filter((r) => r.status === 'fulfilled');
92
+ const rejected = results.filter((r) => r.status === 'rejected');
93
+ expect(fulfilled).toHaveLength(1);
94
+ expect(rejected).toHaveLength(1);
95
+ expect(mapDatabaseError(rejected[0].reason)).toMatchObject({ statusCode: 409 });
96
+ });
97
+ });
98
+
99
+ describe('findMany', () => {
100
+ it('paginates, newest first, and reports the total', async () => {
101
+ const first = await createUser();
102
+ await new Promise((resolve) => setTimeout(resolve, 5));
103
+ const second = await createUser();
104
+ await new Promise((resolve) => setTimeout(resolve, 5));
105
+ const third = await createUser();
106
+
107
+ const page1 = await userRepository.findMany({ page: 1, limit: 1 });
108
+ const page2 = await userRepository.findMany({ page: 2, limit: 1 });
109
+
110
+ expect(page1.total).toBe(3);
111
+ expect(page1.users.map((u) => u.id)).toEqual([third.id]);
112
+ expect(page2.total).toBe(3);
113
+ expect(page2.users.map((u) => u.id)).toEqual([second.id]);
114
+ expect(page2.users[0]).not.toHaveProperty('password');
115
+ expect(first.id).not.toBe(second.id);
116
+ });
117
+ });
118
+
119
+ describe('updateRole', () => {
120
+ it('changes the role and returns the public user', async () => {
121
+ const created = await createUser();
122
+
123
+ const updated = await userRepository.updateRole(created.id, 'admin');
124
+
125
+ expect(updated).toMatchObject({ id: created.id, role: 'admin' });
126
+ expect(updated).not.toHaveProperty('password');
127
+ expect((await userRepository.findById(created.id)).role).toBe('admin');
128
+ });
129
+ });
130
+
131
+ describe('deleteById', () => {
132
+ it('deletes the user and their refresh tokens, and is false the second time', async () => {
133
+ const user = await createUser();
134
+ await userRepository.saveRefreshToken({
135
+ userId: user.id,
136
+ tokenHash: `hash-${user.id}`,
137
+ expiresAt: inOneHour(),
138
+ });
139
+
140
+ expect(await userRepository.deleteById(user.id)).toBe(true);
141
+ expect(await userRepository.findById(user.id)).toBeNull();
142
+ expect(await userRepository.findRefreshToken(`hash-${user.id}`)).toBeNull();
143
+ expect(await userRepository.deleteById(user.id)).toBe(false);
144
+ });
145
+ });
146
+
147
+ describe('refresh tokens', () => {
148
+ it('saves, finds, and revokes a token', async () => {
149
+ const user = await createUser();
150
+ const tokenHash = `hash-a-${user.id}`;
151
+ const expiresAt = inOneHour();
152
+
153
+ await userRepository.saveRefreshToken({ userId: user.id, tokenHash, expiresAt });
154
+
155
+ const found = await userRepository.findRefreshToken(tokenHash);
156
+ expect(found).toEqual({ userId: user.id, expiresAt, revokedAt: null });
157
+
158
+ expect(await userRepository.revokeRefreshToken(tokenHash)).toBe(true);
159
+ expect(await userRepository.revokeRefreshToken(tokenHash)).toBe(false);
160
+
161
+ const revoked = await userRepository.findRefreshToken(tokenHash);
162
+ expect(revoked.revokedAt).toBeInstanceOf(Date);
163
+ });
164
+
165
+ it('returns null for an unknown token', async () => {
166
+ expect(await userRepository.findRefreshToken('missing')).toBeNull();
167
+ });
168
+
169
+ it('revokeAllRefreshTokens revokes every token of that user only', async () => {
170
+ const user = await createUser();
171
+ const other = await createUser();
172
+ for (const name of ['one', 'two']) {
173
+ await userRepository.saveRefreshToken({
174
+ userId: user.id,
175
+ tokenHash: `hash-${name}-${user.id}`,
176
+ expiresAt: inOneHour(),
177
+ });
178
+ }
179
+ await userRepository.saveRefreshToken({
180
+ userId: other.id,
181
+ tokenHash: `hash-other-${other.id}`,
182
+ expiresAt: inOneHour(),
183
+ });
184
+
185
+ await userRepository.revokeAllRefreshTokens(user.id);
186
+
187
+ for (const name of ['one', 'two']) {
188
+ const token = await userRepository.findRefreshToken(`hash-${name}-${user.id}`);
189
+ expect(token.revokedAt).toBeInstanceOf(Date);
190
+ }
191
+ const untouched = await userRepository.findRefreshToken(`hash-other-${other.id}`);
192
+ expect(untouched.revokedAt).toBeNull();
193
+ });
194
+
195
+ it('maps a duplicate token hash to a generic 409', async () => {
196
+ const user = await createUser();
197
+ const tokenHash = `hash-dup-${user.id}`;
198
+ const save = () =>
199
+ userRepository.saveRefreshToken({ userId: user.id, tokenHash, expiresAt: inOneHour() });
200
+ await save();
201
+
202
+ const error = await save().catch((err) => err);
203
+
204
+ expect(mapDatabaseError(error)).toMatchObject({
205
+ statusCode: 409,
206
+ message: 'Resource already exists',
207
+ });
208
+ });
209
+ });
210
+ });
@@ -0,0 +1,144 @@
1
+ import request from 'supertest';
2
+ import { describe, expect, it } from 'vitest';
3
+ import { createApp } from '../src/app.js';
4
+ import * as userRepository from '../src/modules/user/user.repository.js';
5
+ import { createAdmin, createUser, loginAs } from './helpers/auth.helper.js';
6
+
7
+ const app = createApp();
8
+
9
+ // Every response in this file must be free of password data.
10
+ function expectNoPassword(res) {
11
+ expect(JSON.stringify(res.body)).not.toContain('"password"');
12
+ return res;
13
+ }
14
+
15
+ const api = (method, path, token) => {
16
+ const req = request(app)[method](`/api/v1/users${path}`);
17
+ return (token ? req.set('Authorization', `Bearer ${token}`) : req).then(expectNoPassword);
18
+ };
19
+
20
+ // A valid id (for either database) that no longer exists.
21
+ async function unknownId() {
22
+ const { user } = await createUser();
23
+ await userRepository.deleteById(user.id);
24
+ return user.id;
25
+ }
26
+
27
+ async function login(factory = createUser) {
28
+ const { user, password } = await factory();
29
+ const session = await loginAs(app, { email: user.email, password });
30
+ return { user, token: session.accessToken };
31
+ }
32
+
33
+ describe('GET /users/me', () => {
34
+ it('returns the logged in profile', async () => {
35
+ const { user, token } = await login();
36
+ const res = await api('get', '/me', token);
37
+ expect(res.status).toBe(200);
38
+ expect(res.body.data.user.email).toBe(user.email);
39
+ });
40
+
41
+ it('requires authentication', async () => {
42
+ expect((await api('get', '/me')).status).toBe(401);
43
+ });
44
+ });
45
+
46
+ describe('GET /users', () => {
47
+ it('is forbidden for a normal user', async () => {
48
+ const { token } = await login();
49
+ const res = await api('get', '', token);
50
+ expect(res.status).toBe(403);
51
+ expect(res.body.message).toBe('You do not have permission to perform this action');
52
+ });
53
+
54
+ it('lists users with pagination meta for an admin', async () => {
55
+ const { token } = await login(createAdmin);
56
+ await createUser();
57
+ const res = await api('get', '', token);
58
+ expect(res.status).toBe(200);
59
+ expect(res.body.data.users).toHaveLength(2);
60
+ expect(res.body.meta).toEqual({ page: 1, limit: 20, total: 2, totalPages: 1 });
61
+ });
62
+
63
+ it('pages through results', async () => {
64
+ const { token } = await login(createAdmin);
65
+ await createUser();
66
+ await createUser();
67
+ const first = await api('get', '?limit=1&page=1', token);
68
+ const second = await api('get', '?limit=1&page=2', token);
69
+ expect(second.status).toBe(200);
70
+ expect(second.body.data.users).toHaveLength(1);
71
+ expect(second.body.data.users[0].id).not.toBe(first.body.data.users[0].id);
72
+ expect(second.body.meta).toEqual({ page: 2, limit: 1, total: 3, totalPages: 3 });
73
+ });
74
+
75
+ it('returns an empty page past the end and keeps the total', async () => {
76
+ const { token } = await login(createAdmin);
77
+ await createUser();
78
+ const res = await api('get', '?page=999', token);
79
+ expect(res.status).toBe(200);
80
+ expect(res.body.data.users).toEqual([]);
81
+ expect(res.body.meta).toMatchObject({ page: 999, total: 2 });
82
+ });
83
+
84
+ it('rejects a limit above the maximum', async () => {
85
+ const { token } = await login(createAdmin);
86
+ expect((await api('get', '?limit=500', token)).status).toBe(400);
87
+ });
88
+ });
89
+
90
+ describe('GET /users/:id', () => {
91
+ it('returns a user for an admin', async () => {
92
+ const { token } = await login(createAdmin);
93
+ const { user } = await createUser();
94
+ const res = await api('get', `/${user.id}`, token);
95
+ expect(res.status).toBe(200);
96
+ expect(res.body.data.user.id).toBe(user.id);
97
+ });
98
+
99
+ it('is forbidden for a normal user', async () => {
100
+ const { user, token } = await login();
101
+ expect((await api('get', `/${user.id}`, token)).status).toBe(403);
102
+ });
103
+
104
+ it('returns 404 for an unknown id', async () => {
105
+ const { token } = await login(createAdmin);
106
+ const res = await api('get', `/${await unknownId()}`, token);
107
+ expect(res.status).toBe(404);
108
+ expect(res.body.message).toBe('User not found');
109
+ });
110
+
111
+ it('returns 400 for a malformed id', async () => {
112
+ const { token } = await login(createAdmin);
113
+ expect((await api('get', '/abc', token)).status).toBe(400);
114
+ });
115
+ });
116
+
117
+ describe('DELETE /users/:id', () => {
118
+ it('deletes a user and locks them out', async () => {
119
+ const admin = await login(createAdmin);
120
+ const target = await login();
121
+ const res = await api('delete', `/${target.user.id}`, admin.token);
122
+ expect(res.status).toBe(204);
123
+ expect((await api('get', `/${target.user.id}`, admin.token)).status).toBe(404);
124
+ expect((await api('get', '/me', target.token)).status).toBe(401);
125
+ });
126
+
127
+ it('refuses to delete yourself', async () => {
128
+ const admin = await login(createAdmin);
129
+ const res = await api('delete', `/${admin.user.id}`, admin.token);
130
+ expect(res.status).toBe(400);
131
+ expect(res.body.message).toBe('You cannot delete your own account');
132
+ });
133
+
134
+ it('is forbidden for a normal user', async () => {
135
+ const { token } = await login();
136
+ const { user } = await createUser();
137
+ expect((await api('delete', `/${user.id}`, token)).status).toBe(403);
138
+ });
139
+
140
+ it('returns 404 for an unknown id', async () => {
141
+ const { token } = await login(createAdmin);
142
+ expect((await api('delete', `/${await unknownId()}`, token)).status).toBe(404);
143
+ });
144
+ });
@@ -0,0 +1,35 @@
1
+ import { describe, expect, it, vi } from 'vitest';
2
+ import { validate } from '../src/middlewares/validate.js';
3
+ import { registerSchema } from '../src/modules/auth/auth.validation.js';
4
+ import { listUsersSchema } from '../src/modules/user/user.validation.js';
5
+
6
+ const run = (schema, req) => {
7
+ const next = vi.fn();
8
+ validate(schema)(req, {}, next);
9
+ return next;
10
+ };
11
+
12
+ describe('validate middleware', () => {
13
+ it('sets req.validated and calls next() on success', () => {
14
+ const req = { body: undefined, params: {}, query: { page: '3' } };
15
+ const next = run(listUsersSchema, req);
16
+ expect(next).toHaveBeenCalledWith();
17
+ expect(req.validated.query).toEqual({ page: 3, limit: 20 });
18
+ });
19
+ it('maps issues to field errors', () => {
20
+ const req = { body: { name: 'N', email: 'bad', password: 'Passw0rd' }, params: {}, query: {} };
21
+ const err = run(registerSchema, req).mock.calls[0][0];
22
+ expect(err.statusCode).toBe(400);
23
+ expect(err.message).toBe('Validation failed');
24
+ expect(err.errors.map((e) => e.field)).toEqual(expect.arrayContaining(['name', 'email']));
25
+ });
26
+ it('emits one entry per unrecognized key', () => {
27
+ const req = {
28
+ body: { name: 'Nitish', email: 'a@b.com', password: 'Passw0rd', role: 'admin' },
29
+ params: {},
30
+ query: {},
31
+ };
32
+ const err = run(registerSchema, req).mock.calls[0][0];
33
+ expect(err.errors[0]).toEqual({ field: 'role', message: 'Unrecognized field "role"' });
34
+ });
35
+ });
@@ -0,0 +1,61 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import { registerSchema, loginSchema } from '../src/modules/auth/auth.validation.js';
3
+ import { listUsersSchema, userIdParamSchema } from '../src/modules/user/user.validation.js';
4
+
5
+ const valid = { name: 'Nitish', email: ' Foo@X.com ', password: 'Passw0rd' };
6
+ const register = (body) => registerSchema.safeParse({ body, params: {}, query: {} });
7
+ const list = (query) => listUsersSchema.safeParse({ body: {}, params: {}, query });
8
+ const fields = (r) => r.error.issues.map((i) => i.path.slice(1).join('.'));
9
+
10
+ describe('registerSchema', () => {
11
+ it('accepts valid input and normalises the email', () => {
12
+ const r = register(valid);
13
+ expect(r.success).toBe(true);
14
+ expect(r.data.body.email).toBe('foo@x.com');
15
+ });
16
+ it('rejects a weak password on field password', () => {
17
+ const r = register({ ...valid, password: 'password' });
18
+ expect(r.success).toBe(false);
19
+ expect(fields(r)).toContain('password');
20
+ });
21
+ it('rejects too short and too long names', () => {
22
+ expect(register({ ...valid, name: 'N' }).success).toBe(false);
23
+ expect(register({ ...valid, name: 'a'.repeat(51) }).success).toBe(false);
24
+ });
25
+ it('rejects unknown keys such as role', () => {
26
+ const r = register({ ...valid, role: 'admin' });
27
+ expect(r.success).toBe(false);
28
+ expect(r.error.issues[0].code).toBe('unrecognized_keys');
29
+ });
30
+ it('works without params and query', () => {
31
+ expect(registerSchema.safeParse({ body: valid }).success).toBe(true);
32
+ });
33
+ });
34
+
35
+ describe('loginSchema', () => {
36
+ it('only requires a non-empty password', () => {
37
+ const r = loginSchema.safeParse({ body: { email: 'a@b.com', password: 'x' } });
38
+ expect(r.success).toBe(true);
39
+ expect(loginSchema.safeParse({ body: { email: 'a@b.com', password: '' } }).success).toBe(false);
40
+ });
41
+ });
42
+
43
+ describe('listUsersSchema', () => {
44
+ it('coerces page and limit', () => {
45
+ expect(list({ page: '2', limit: '10' }).data.query).toEqual({ page: 2, limit: 10 });
46
+ });
47
+ it('applies defaults', () => {
48
+ expect(list({}).data.query).toEqual({ page: 1, limit: 20 });
49
+ });
50
+ it('rejects bad values', () => {
51
+ expect(list({ limit: '101' }).success).toBe(false);
52
+ expect(list({ limit: 'abc' }).success).toBe(false);
53
+ expect(list({ page: '0' }).success).toBe(false);
54
+ });
55
+ });
56
+
57
+ describe('userIdParamSchema', () => {
58
+ it('rejects an invalid id', () => {
59
+ expect(userIdParamSchema.safeParse({ params: { id: 'nope' } }).success).toBe(false);
60
+ });
61
+ });
@@ -0,0 +1,16 @@
1
+ import { defineConfig } from 'vitest/config';
2
+
3
+ export default defineConfig({
4
+ test: {
5
+ env: {
6
+ NODE_ENV: 'test',
7
+ JWT_ACCESS_SECRET: 'test-access-secret-at-least-32-characters',
8
+ JWT_REFRESH_SECRET: 'test-refresh-secret-at-least-32-characters',
9
+ AUTH_RATE_LIMIT_MAX: '1000',
10
+ },
11
+ globalSetup: ['./tests/globalSetup.js'],
12
+ setupFiles: ['./tests/setup.js'],
13
+ // Database tests share one database, so test files run one at a time.
14
+ fileParallelism: false,
15
+ },
16
+ });
@@ -0,0 +1,23 @@
1
+ ## Quick start
2
+
3
+ ```bash
4
+ cd {{projectName}}
5
+ cp .env.example .env
6
+ npm install
7
+ docker compose up -d --wait db
8
+ npm run dev
9
+ ```
10
+
11
+ The API is on <http://localhost:3000>. `docker compose up -d --wait db` starts a MongoDB at the default `MONGODB_URI` (or point it at your own). `npm test` needs nothing installed: it uses an in-memory MongoDB.
12
+
13
+ ## Database
14
+
15
+ MongoDB with Mongoose.
16
+
17
+ | Variable | Meaning |
18
+ | ------------- | --------------------------------- |
19
+ | `MONGODB_URI` | Connection string of your MongoDB |
20
+
21
+ **Docker port.** The compose database is published on host port `27017`. If you already run MongoDB there, pick another port: `MONGO_PORT=27018 npm run docker:up`.
22
+
23
+ **Adding a user field.** Add it to the schema in `src/database/models/user.model.js` and to `create` in `src/modules/user/user.repository.js`. Mongoose adds the field to responses automatically.
@@ -0,0 +1,29 @@
1
+ name: CI
2
+
3
+ on: [push, pull_request]
4
+
5
+ jobs:
6
+ test:
7
+ runs-on: ubuntu-latest
8
+ steps:
9
+ - uses: actions/checkout@v7
10
+ - uses: actions/setup-node@v7
11
+ with:
12
+ node-version: 24
13
+ cache: npm
14
+ - run: npm ci
15
+ - run: npm run lint
16
+ - run: npm run format:check
17
+ - run: npm test
18
+
19
+ docker:
20
+ needs: test
21
+ runs-on: ubuntu-latest
22
+ steps:
23
+ - uses: actions/checkout@v7
24
+ - uses: docker/setup-buildx-action@v4
25
+ - uses: docker/build-push-action@v7
26
+ with:
27
+ context: .
28
+ push: false
29
+ tags: app:ci
@@ -0,0 +1,30 @@
1
+ name: '{{projectName}}'
2
+
3
+ services:
4
+ app:
5
+ build: .
6
+ env_file: .env
7
+ environment:
8
+ NODE_ENV: production
9
+ PORT: 3000
10
+ MONGODB_URI: mongodb://db:27017/{{databaseName}}
11
+ depends_on:
12
+ db:
13
+ condition: service_healthy
14
+ ports:
15
+ - '${PORT:-3000}:3000'
16
+
17
+ db:
18
+ image: mongo:8
19
+ ports:
20
+ - '${MONGO_PORT:-27017}:27017'
21
+ volumes:
22
+ - mongodata:/data/db
23
+ healthcheck:
24
+ test: ['CMD', 'mongosh', '--quiet', '--eval', "db.adminCommand('ping').ok"]
25
+ interval: 5s
26
+ timeout: 5s
27
+ retries: 10
28
+
29
+ volumes:
30
+ mongodata:
@@ -0,0 +1,2 @@
1
+ # --- database ---
2
+ MONGODB_URI=mongodb://localhost:27017/{{databaseName}}
@@ -0,0 +1,4 @@
1
+ {
2
+ "dependencies": { "mongoose": "^9.11.4" },
3
+ "devDependencies": { "mongodb-memory-server": "^11.3.0" }
4
+ }