mercadodevida/work/artifacts/F-006/implementer.md

done -> work/artifacts/F-006/implementer.md

F-006 — Users: profile, addresses, RBAC (Build)

Agent: implementer Stage: build Feature: F-006

Scope delivered

Profile + address management with owner-or-admin authorization, on top of the F-005 identity foundation. No new npm dependencies were added.

Files

Migrations (immutable; new migrations only)

• project/migrations/003_identity_roles.js — adds identity_users.role (customer | admin, default customer, NOT NULL) + index.
• project/migrations/004_users.js — users_profiles (PK user_id FK → identity_users, display_name, phone, timestamps) and users_addresses (id uuid PK, user_id FK ON DELETE CASCADE, address fields, is_default, timestamps, user_id index).

Shared auth contract

• project/src/shared/auth.ts — Role, CurrentUser, Authenticate, requireRole, requireOwnerOrAdmin. Shared (not module-owned) so both identity and users use one authorization vocabulary without cross-module imports.

Identity additions

• project/src/modules/identity/infrastructure/session-authenticator.ts — resolves the session cookie into CurrentUser from the DB (expiry + revocation enforced in SQL). Exported through the module index so the composition root can inject it.
• Role added to User, PgUserRepository (SELECT/RETURNING role), and the register/login responses.

Users module (hexagonal)

• domain/profile.ts, domain/address.ts, domain/ports.ts
• application/profile-use-cases.ts, application/address-use-cases.ts
• infrastructure/pg-profile-repository.ts, infrastructure/pg-address-repository.ts
• api/users.routes.ts — registers the endpoints below.
• index.ts — public API.

Composition root

• project/src/app/build-app.ts — registers @fastify/cookie once at root (cross-module infrastructure), wires identity routes, builds the Authenticate from identity and injects it into the users routes.

Tests

• project/src/shared/tests/auth.test.ts (unit)
• project/src/app/tests/users.itest.ts (integration)
• project/src/infrastructure/db/tests/migrations.itest.ts — full rollback now asserts users_addresses, users_profiles, identity and baseline all drop.

Endpoints

Method	Path	Auth
GET	/users	admin only
GET	/users/:id	owner or admin
PATCH	/users/:id	owner or admin
GET	/users/:id/addresses	owner or admin
POST	/users/:id/addresses	owner or admin
PATCH	/users/:id/addresses/:addressId	owner or admin
DELETE	/users/:id/addresses/:addressId	owner or admin

Authorization runs BEFORE existence checks: a non-owner gets 403 regardless of whether the target resource exists. Address operations are additionally scoped by user_id in SQL, so a caller cannot touch another user's address even with a valid id.

Verification

• npm run lint, npm run lint:boundaries, npm run typecheck, npm run build: clean.
• npm test: 52 passed, 22 skipped (integration skipped without TEST_DATABASE_URL).
• npm run test:integration: 22 passed against real PostgreSQL 16.
• ./scripts/verify.sh: green.
• Live smoke (PORT=3995): register/login 201/200; PATCH own profile 200; GET own 200; cross-user GET 403; GET /users as customer 403; after promotion GET /users as admin 200; address CRUD 201/204; cross-user address 403; no-cookie GET 401. Smoke data removed afterwards.

Deviations from TESTS.md (documented, not silent)

• The planned users/tests/ownership.test.ts was merged into shared/tests/auth.test.ts, because the owner-or-admin decision lives in the shared contract (shared/auth.ts), not in the users module. Coverage is equivalent.
• @fastify/cookie registration moved from identity's route scope to the app root. Fastify encapsulation meant the request.cookies decorator was not visible in the users scope (caused 500s); cookies are now cross-module infrastructure registered once at the composition root.

Notes for gates

• Reviewer: check the SQL column whitelist in pg-profile-repository.upsert and pg-address-repository.update (only hardcoded columns; values always parameterized), and that every users route calls authenticate then requireOwnerOrAdmin before touching data.
• Security: session resolution is DB-backed (revocation + expiry in SQL); role is read from identity_users per request, so promotion/demotion is reflected immediately without trusting the client.
• QA: integration suite exercises every acceptance criterion (AC1–AC4) plus the F-005 logout regression.