> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pensionsportal.ie/llms.txt
> Use this file to discover all available pages before exploring further.

# Secure Development Lifecycle (SDLC)

> How PensionsPortal.ie builds, tests, and deploys code securely — from branch to production.

Security is integrated into every stage of the development process, not bolted on at the end. This page describes the controls applied from code authorship through to production deployment.

## Development Workflow

<Steps>
  <Step title="Feature branch">
    All work occurs on feature branches. No direct commits to `main`. Branch naming convention follows the issue tracker reference.
  </Step>

  <Step title="Local quality gates">
    Developers run `npm run lint` (ESLint) and `npm test` (Vitest) before pushing. ESLint is configured with `eslint-config-next` for Next.js-aware rules.
  </Step>

  <Step title="Pull request">
    PRs require at least one reviewer approval. The CI pipeline must pass before merge is permitted.
  </Step>

  <Step title="CI pipeline">
    GitHub Actions runs type-checking, linting, unit tests, and security tests on every PR. See CI section below.
  </Step>

  <Step title="Deployment">
    Merges to `main` trigger an automatic Vercel production deployment. Preview deployments are created for every PR.
  </Step>
</Steps>

## CI Pipeline

The CI pipeline enforces the following gates on every pull request:

| Gate             | Tool                          | Failure blocks merge? |
| ---------------- | ----------------------------- | --------------------- |
| Type checking    | `tsc --noEmit`                | ✅                     |
| Linting          | ESLint (`eslint-config-next`) | ✅                     |
| Unit tests       | Vitest                        | ✅                     |
| Security tests   | Vitest (security suite)       | ✅                     |
| E2E tests        | Playwright                    | ✅                     |
| Dependency audit | `npm audit`                   | Configured per policy |

<Note>
  ESLint runs as a **dedicated CI step** and is skipped during `next build` (configured in `next.config.ts`) to avoid duplicate work and keep build times predictable.
</Note>

## Testing Strategy

### Unit Tests (Vitest)

Located in `src/tests/`. Cover:

* **Domain logic** — FSM state machine transitions for `Scheme` and `Member` entities
* **Change proposal** — proposal creation, approval, rejection, expiry logic
* **Security regression** — `src/tests/api/security.test.ts` verifies that API routes never leak connection strings, stack traces, or environment variable names in error responses

### Security Tests

The security test suite (`src/tests/api/security.test.ts`) specifically tests:

* DB health endpoint does not expose PostgreSQL connection strings in 503 responses
* Ready endpoint does not enumerate missing environment variable names
* API routes return clean error messages without stack traces or `node_modules` paths

### E2E Tests (Playwright)

Playwright tests cover critical user journeys including health endpoint availability. Configuration in `playwright.config.ts`.

## Code Review Standards

Every PR is reviewed for:

* **Authentication and authorisation** — does the new route check `session` and scope by `brokerId`?
* **Sensitive data handling** — is PPS data handled via the encrypted field? Is it excluded from logs?
* **Audit logging** — do material changes write to `audit_logs`?
* **Error handling** — do catch blocks return sanitised messages, not raw errors?

## Dependency Management

* `package-lock.json` is committed and pinned
* `npm audit` is run in CI to detect known vulnerabilities
* Dependabot (or equivalent) is configured for automated dependency update PRs

See [Vulnerability Management](/security/vulnerability-management) for the full dependency scanning policy.

## Secrets in Code

Secrets must never be committed to the repository. The `.env.example` file contains placeholder values only. Real secrets are managed via Vercel environment variables. See [Secrets Management](/security/secrets-management).

A `git-secrets` or equivalent pre-commit hook is recommended for all developers to prevent accidental secret commits.