Skip to content

Commit 9bcfcf1

Browse files
Merge pull request #27 from muhammadali-imran/main
v1.0.6 and v1.0.3
2 parents 02bb482 + bae4672 commit 9bcfcf1

44 files changed

Lines changed: 616 additions & 74 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎backend/README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,9 @@ mounted outside production.
9292
## Operational rules
9393

9494
- Authentication uses an HTTP-only `signpak_token` cookie. Email verification is
95-
required before login; password reset invalidates existing sessions.
95+
followed by consent acceptance before a new account is activated and signed
96+
in. Existing contributors must accept the current consent version before
97+
submitting; password reset invalidates existing sessions.
9698
- `CLIENT_ORIGIN` controls credentialed CORS and the check for browser
9799
state-changing requests that carry an `Origin` header.
98100
- The global, auth, contact, and upload rate limits can be disabled with
@@ -106,9 +108,10 @@ mounted outside production.
106108
- Reference and demo-video uploads accept browser-reported `width` and `height`
107109
in pixels, each from 0 to 16,384. Zero represents unknown dimensions; these
108110
values are metadata for responsive playback, not server-side media probes.
109-
- `SUBMISSION_COOLDOWN_MS` defaults to 30 seconds per contributor/video pair.
110-
Atomic claiming prevents simultaneous duplicate submissions; failed processing
111-
releases the claim.
111+
- `SUBMISSION_COOLDOWN_MS` defaults to 30 seconds per contributor/video pair,
112+
starting when the server accepts an upload for processing. Atomic claiming
113+
prevents simultaneous duplicate submissions; failed processing releases the
114+
claim.
112115
- Contact delivery uses Web3Forms. A signed-in account can send from its own
113116
email; quotas are one per account per UTC day and 25 per UTC day globally by
114117
default. Abusive attempts can temporarily restrict a device or IP.
@@ -124,7 +127,7 @@ npm test
124127
The command runs Node's built-in test runner serially across every
125128
`tests/*.test.js` file. The API suites use MongoDB Memory Server unless
126129
`MONGODB_URI_TEST` is supplied. That configured database is dropped by the tests,
127-
so use only a disposable database. Provider delivery is stubbed. The 57 cases and
130+
so use only a disposable database. Provider delivery is stubbed. The 60 cases and
128131
their test types are documented in [docs/TEST-CASES.md](docs/TEST-CASES.md).
129132

130133
## Current limitation

‎backend/docs/API.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,14 @@ and `/api-docs.json` in all environments. Swagger UI is disabled in production.
88

99
## Authentication and cookies
1010

11-
Successful login and email verification set an HTTP-only `signpak_token` cookie.
12-
Signup creates an unverified account and sends a six-digit verification code; the
13-
account must be verified before login. Browser clients must send requests with
11+
Successful login and consent acceptance set an HTTP-only `signpak_token` cookie.
12+
Signup creates a pending, unverified record and sends a six-digit verification
13+
code. A valid code returns a short-lived consent token but does not establish a
14+
session or activate the account. `POST /auth/consent` accepts the current notice,
15+
activates the account, stores the consent version and timestamp, and starts the
16+
session. `POST /auth/decline-consent` discards the pending signup. Existing
17+
contributors without current consent are redirected to the notice and cannot
18+
submit recordings until they accept. Browser clients must send requests with
1419
credentials.
1520

1621
`GET /auth/session` returns the current user or `null` for a visitor. `POST
@@ -57,14 +62,17 @@ All paths below are relative to `/api/v1`.
5762
| GET | `/health` | Public | Report API uptime and database connectivity; returns `503` while the database is unavailable. |
5863
| POST | `/auth/signup` | Public | Create an unverified contributor and send an email code. |
5964
| POST | `/auth/login` | Public | Authenticate and set the session cookie. |
60-
| POST | `/auth/verify-email` | Public | Verify an email code and establish a session. |
65+
| POST | `/auth/verify-email` | Public | Verify an email code and return a short-lived consent token. |
66+
| POST | `/auth/consent` | Public | Accept the current consent notice, activate a pending signup, and start a session. |
67+
| POST | `/auth/decline-consent` | Public | Discard a pending signup after consent is declined. |
6168
| POST | `/auth/resend-verification` | Public | Request another verification code. |
6269
| POST | `/auth/forgot-password` | Public | Request a password-reset code. |
6370
| POST | `/auth/reset-password` | Public | Reset a password and invalidate older sessions. |
6471
| POST | `/auth/logout` | Public | Clear the session cookie. |
6572
| GET | `/auth/session` | Public | Return the current user or `null`. |
6673
| GET | `/users/me` | Authenticated user | Read the signed-in user's profile. |
6774
| PATCH | `/users/me` | Authenticated user | Update supported profile connections. |
75+
| POST | `/users/me/consent` | Authenticated user | Accept the current notice for an existing account. |
6876
| GET | `/categories` | Public | List categories. |
6977
| POST | `/categories` | Admin | Create a category. |
7078
| PATCH | `/categories/:id` | Admin | Update a category. |
@@ -162,8 +170,10 @@ administrator can recover by removing a restriction.
162170
- Deleting a category unassigns videos rather than deleting them. Deleting a
163171
reference video keeps submissions associated with that video on record.
164172
- A contributor may submit the same video again after the
165-
`SUBMISSION_COOLDOWN_MS` cooldown (default 30 seconds). Concurrent submissions
166-
for the same account/video pair are atomically limited.
173+
`SUBMISSION_COOLDOWN_MS` cooldown (default 30 seconds), measured from when the
174+
server starts processing the upload request. The submission response includes
175+
`cooldownStartedAt` so the client countdown uses the same timestamp. Concurrent
176+
submissions for the same account/video pair are atomically limited.
167177

168178
For the detailed OpenAPI schemas and examples, use the raw OpenAPI document or
169179
the development Swagger UI.

‎backend/docs/TEST-CASES.md‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
# Backend test cases
22

3-
The backend suite uses Node's built-in test runner. It currently contains **57 test
4-
cases** across twelve test files. Each named API test suite has its own `.test.js`
3+
The backend suite uses Node's built-in test runner. It currently contains **60 test
4+
cases** across thirteen test files. Each named API test suite has its own `.test.js`
55
file and starts with a fresh test database and account fixtures:
66

77
| Test file | Cases | Main test type |
88
| --- | ---: | --- |
99
| `tests/api-basics.test.js` | 5 | HTTP integration tests |
1010
| `tests/api-demo-video.test.js` | 1 | HTTP integration tests |
1111
| `tests/api-auth.test.js` | 8 | HTTP integration tests |
12+
| `tests/api-consent.test.js` | 3 | HTTP integration tests |
1213
| `tests/api-profile-connections.test.js` | 1 | HTTP integration tests |
1314
| `tests/api-categories.test.js` | 2 | HTTP integration tests |
1415
| `tests/api-videos.test.js` | 6 | HTTP integration tests |
@@ -62,10 +63,10 @@ their respective test file. Each API case below is an HTTP integration test.
6263

6364
7. **signup validates every field** — Checks required signup fields, password
6465
confirmation, and minimum password length.
65-
8. **signup sets an httpOnly cookie and never leaks the hash or accepts a role** —
66-
Checks that signup does not create a session before verification, ignores a
67-
submitted admin role, verifies email, sets secure cookie attributes, and does
68-
not expose the password hash.
66+
8. **signup only creates an account after consent and never leaks the hash or
67+
accepts a role** — Checks that signup and email verification do not create a
68+
session, ignores a submitted admin role, activates the account after consent,
69+
sets secure cookie attributes, and does not expose the password hash.
6970
9. **password reset codes are one-time and replace the old password** — Checks the
7071
generic reset-request response, invalid-code handling, password replacement,
7172
code reuse rejection, and invalidation of the old session.
@@ -228,6 +229,15 @@ routes. The cases are separated by the behavior under test.
228229
Checks cleanup of the stored video when the subsequent poster save fails.
229230
57. **video create removes video and poster if the database write fails** —
230231
Checks cleanup of both stored files when database record creation fails.
232+
58. **creates the account only after consent and records the acceptance time** —
233+
Checks that verification alone cannot log in, current consent activates the
234+
account, the acceptance time and version are stored, and consent tokens
235+
cannot be replayed.
236+
59. **declining consent discards the unfinished signup** — Checks the pending
237+
account is removed and its email can be used for a new signup.
238+
60. **legacy accounts without consent cannot submit until they accept** — Checks
239+
that older accounts are blocked from submitting until they accept the current
240+
notice.
231241

232242
## Running the suite
233243

‎backend/package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎backend/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "backend",
3-
"version": "1.0.2",
3+
"version": "1.0.3",
44
"description": "SignPakCommons API: Express, Node.js and MongoDB",
55
"main": "server.js",
66
"scripts": {

‎backend/src/config/constants.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,7 @@ export const VIDEO_STATUS_LIST = Object.values(VIDEO_STATUS)
1010

1111
export const POSTER_MAX_BYTES = 2 * 1024 * 1024
1212
export const MAX_RECORDING_SECONDS = 600
13+
// Bump when the consent notice text changes materially; contributors are then asked to accept it again.
14+
export const CONSENT_VERSION = '2026-10'
1315
// Client-reported durations are rounded, so allow a little slack when checking trim ranges.
1416
export const TRIM_TOLERANCE_SECONDS = 0.5

‎backend/src/controllers/authController.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,23 @@ export const authController = {
1515
ok(res, user)
1616
}),
1717

18+
// A valid code does not log anyone in: it returns a short-lived consent token for the next step.
1819
verifyEmail: asyncHandler(async (req, res) => {
19-
const { user, token } = await authService.verifyEmail(req.body)
20+
ok(res, await authService.verifyEmail(req.body))
21+
}),
22+
23+
acceptConsent: asyncHandler(async (req, res) => {
24+
const { user, token } = await authService.completeSignup(req.body)
2025
await authService.recordDevice(user, req.get('X-Device-ID'))
2126
setAuthCookie(res, token)
2227
ok(res, user)
2328
}),
2429

30+
declineConsent: asyncHandler(async (req, res) => {
31+
await authService.declineSignup(req.body)
32+
noContent(res)
33+
}),
34+
2535
resendVerification: asyncHandler(async (req, res) => {
2636
await authService.resendVerification(req.body.email)
2737
ok(res, { message: 'If the account needs verification, a code will be sent.' })

‎backend/src/controllers/userController.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { noContent, ok } from '../utils/response.js'
55
export const userController = {
66
me: (req, res) => ok(res, req.user),
77
updateMe: asyncHandler(async (req, res) => ok(res, await userService.updateConnections(req.user, req.body.connections))),
8+
acceptConsent: asyncHandler(async (req, res) => ok(res, await userService.acceptConsent(req.user, req.body.version))),
89
list: asyncHandler(async (req, res) => ok(res, await userService.listAll())),
910
updateStatus: asyncHandler(async (req, res) => ok(res, await userService.updateStatus(req.params.id, req.user, req.body))),
1011
remove: asyncHandler(async (req, res) => { await userService.remove(req.params.id, req.user); noContent(res) }),

‎backend/src/docs/openapi.js‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,11 @@ export const openapi = {
141141
role: { type: 'string', enum: ['user', 'admin'] },
142142
status: { type: 'string', enum: ['active', 'suspended'] },
143143
statusReason: { type: 'string' },
144+
consent: {
145+
type: 'object',
146+
description: 'When the contributor accepted the consent notice (null until they do).',
147+
properties: { acceptedAt: { type: 'string', format: 'date-time', nullable: true }, version: { type: 'string', nullable: true } },
148+
},
144149
connections: {
145150
type: 'object',
146151
properties: {
@@ -254,6 +259,7 @@ export const openapi = {
254259
mirrored: { type: 'boolean' },
255260
duration: { type: 'number' },
256261
submittedAt: { type: 'string', format: 'date-time' },
262+
cooldownStartedAt: { type: 'string', format: 'date-time', description: 'When the server accepted the upload for processing and claimed the per-video cooldown.' },
257263
size: { type: 'integer' },
258264
mimeType: { type: 'string', enum: ['video/mp4', 'video/webm', 'video/quicktime'] },
259265
archivePath: { type: 'string', nullable: true, description: 'Included for admins only.' },
@@ -347,9 +353,27 @@ export const openapi = {
347353
'/auth/verify-email': {
348354
post: {
349355
tags: ['Auth'],
350-
summary: 'Verify an email code and establish a session',
356+
summary: 'Verify an email code',
357+
description: 'A valid code does not create the account or log anyone in. It returns a short-lived consentToken to use with POST /auth/consent.',
351358
requestBody: { required: true, content: { 'application/json': { schema: ref('VerifyEmailInput') } } },
352-
responses: { 200: jsonResponse('Verified and logged in', ref('User')), ...authErrors },
359+
responses: { 200: jsonResponse('Code accepted', { type: 'object', properties: { consentToken: { type: 'string' } } }), ...authErrors },
360+
},
361+
},
362+
'/auth/consent': {
363+
post: {
364+
tags: ['Auth'],
365+
summary: 'Accept the consent notice, create the account and log in',
366+
description: 'Activates the account, stores the acceptance date, time and notice version, and sets the session cookie.',
367+
requestBody: { required: true, content: { 'application/json': { schema: { type: 'object', required: ['consentToken', 'accepted', 'version'], properties: { consentToken: { type: 'string' }, accepted: { type: 'boolean', enum: [true] }, version: { type: 'string' } } } } } },
368+
responses: { 200: jsonResponse('Account created and logged in', ref('User')), ...authErrors, 409: errorResponse },
369+
},
370+
},
371+
'/auth/decline-consent': {
372+
post: {
373+
tags: ['Auth'],
374+
summary: 'Decline the consent notice and discard the unfinished sign-up',
375+
requestBody: { required: true, content: { 'application/json': { schema: { type: 'object', required: ['consentToken'], properties: { consentToken: { type: 'string' } } } } } },
376+
responses: { 204: { description: 'Sign-up discarded' }, ...authErrors },
353377
},
354378
},
355379
'/auth/resend-verification': {
@@ -402,6 +426,16 @@ export const openapi = {
402426
responses: { 200: jsonResponse('Updated user', ref('User')), 401: errorResponse, 422: errorResponse },
403427
},
404428
},
429+
'/users/me/consent': {
430+
post: {
431+
tags: ['Users'],
432+
summary: 'Accept the consent notice',
433+
description: 'Records the acceptance date and time and the notice version. Submissions are refused with CONSENT_REQUIRED until this is done.',
434+
security: userSecurity,
435+
requestBody: { required: true, content: { 'application/json': { schema: { type: 'object', required: ['accepted', 'version'], properties: { accepted: { type: 'boolean', enum: [true] }, version: { type: 'string' } } } } } },
436+
responses: { 200: jsonResponse('Updated user', ref('User')), 401: errorResponse, 409: errorResponse, 422: errorResponse },
437+
},
438+
},
405439
'/categories': {
406440
get: {
407441
tags: ['Categories'],

‎backend/src/middlewares/validators/authSchemas.js‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,13 @@ export const resetPasswordSchema = z.object({
3030
password: z.string({ error: 'Create a password.' }).min(8, 'Use at least 8 characters.').max(72, 'Use 72 characters or fewer.'),
3131
confirmPassword: z.string(),
3232
}).refine((data) => data.confirmPassword === data.password, { path: ['confirmPassword'], message: 'Passwords do not match.' })
33+
34+
export const consentSchema = z.object({
35+
consentToken: z.string({ error: 'This sign-up step has expired. Verify your email again.' }).min(10).max(2000),
36+
accepted: z.literal(true, { error: 'You must accept the consent notice to create your account.' }),
37+
version: z.string({ error: 'Missing consent version.' }).min(1).max(40),
38+
})
39+
40+
export const declineConsentSchema = z.object({
41+
consentToken: z.string({ error: 'This sign-up step has expired.' }).min(10).max(2000),
42+
})

0 commit comments

Comments
 (0)