FederalFile

FederalFile is a production-oriented, U.S.-only individual income-tax preparation platform. The active implementation target is an explicitly selected TY2025 federal vertical slice. It cannot transmit a live federal or state return.

Prerequisites

• Node.js 24.16.0
• pnpm 11.11.0 through Corepack
• Docker Engine with Compose v2

Setup

corepack enable
corepack prepare pnpm@11.11.0 --activate
pnpm install --frozen-lockfile
pnpm dev:env
docker compose up -d
DATABASE_URL=postgres://federalfile:local-development-only@127.0.0.1:5432/federalfile pnpm --filter @federalfile/database migrate
pnpm verify:official-form:ty2025
pnpm dev

Open http://localhost:3000. Local service credentials in compose.yaml are development-only. Never reuse them outside local development.

pnpm verify:official-form:ty2025 downloads the public finalized TY2025 Form 1040 from the IRS, refuses it unless its SHA-256 matches the approved source manifest, stores it only in the ignored local cache, and exercises the official review renderer. The resulting application download is watermarked and non-production; it is not a filed return.

The one-shot minio-init service creates private, anonymous-access-disabled federalfile-quarantine-local and federalfile-artifacts-local buckets. The document API fails closed when storage is unavailable, and uploaded objects remain quarantined until content validation and malware scanning succeed. Rendered tax artifacts are application-envelope-encrypted before they enter the separate artifact bucket.

The document worker requires separate least-privilege runtime credentials for DATABASE_URL, REDIS_URL, OBJECT_STORAGE_*, and CLAMAV_*. Scanner engine and signature versions are required configuration and are recorded with scan results. Jobs retry three times with lease-safe exponential backoff; stale scan claims may be recovered without allowing an earlier worker to overwrite the new result. Exhausted jobs remain in BullMQ's failed set for operational review, while the document remains processing_failed and cannot be extracted or treated as authoritative.

The local stack also runs an ephemeral, single-node Vault Transit development service at http://127.0.0.1:8200. vault-init creates four context-specific keys and a restricted synthetic application token. To exercise Transit-backed field encryption locally, set:

NUXT_FIELD_ENCRYPTION_PROVIDER=vault-transit
NUXT_VAULT_ADDRESS=http://127.0.0.1:8200
NUXT_VAULT_TOKEN=federalfile-local-transit-only
NUXT_VAULT_TRANSIT_MOUNT=transit
NUXT_VAULT_TRANSIT_KEY_PREFIX=federalfile
NUXT_VAULT_ALLOW_INSECURE_LOCALHOST_FOR_DEVELOPMENT=true

Then restart pnpm dev. Confirm initialization with docker compose ps --all vault vault-init, then exercise a real wrap, decrypt, rotation, rewrap, and denied key-administration request with:

pnpm verify:kms

This service uses fixed development credentials and plaintext loopback HTTP. It is not a production KMS, is not an HA design, and supplies no compliance or FIPS claim. See docs/adr/0010-self-hosted-kms-boundary.md before considering production self-hosting.

The local stack includes Keycloak at http://localhost:8080. Sign in to FederalFile with the synthetic local account:

• Username: synthetic-taxpayer
• Password: FederalFile-Local-Only-2025!

pnpm dev:env creates a mode-0600 .env with unique local encryption, identity-index, and CSRF secrets and refuses to overwrite an existing file. The committed Keycloak realm and HTTP exception are development-only. The OIDC adapter accepts insecure HTTP only when explicitly enabled, only for loopback hosts, and never when NODE_ENV=production.

Taxpayer dates of birth and taxpayer identification numbers are envelope-encrypted before persistence. The repository's static key-encryption-key provider is restricted to local development and refuses to run in production. A Vault Transit adapter is available, but any production KMS topology, custody model, and rotation procedures still require formal review and approval.

The Keycloak administration console is available at http://localhost:8080/admin with local-only credentials admin / local-development-only. These credentials and the synthetic taxpayer must never be reused or enabled outside local development.

After the app is running, verify the complete synthetic Single-return workflow—including calculation, consent, step-up, immutable mock signature, duplicate-submission prevention, and deterministic acknowledgment—with:

pnpm verify:mock-filing

This command creates synthetic local records and never contacts a government agency.

Required verification

pnpm lint
pnpm typecheck
pnpm test
PLAYWRIGHT_BROWSERS_PATH=.playwright-browsers pnpm exec playwright install chromium
pnpm test:e2e
pnpm build

If host browser installation is restricted, use the pinned test runner after pnpm build:

docker build -f infra/docker/e2e.Dockerfile -t federalfile-e2e .
docker run --rm --init --ipc=host --network host -v "$PWD:/work" federalfile-e2e

Safety boundary

• Tax years are explicit; the calendar year is never used to select rules.
• Authoritative tax values will come only from deterministic, versioned rule packs.
• Tests and seeds use synthetic identities only.
• Authenticated tax data must never be stored in browser storage or emitted to telemetry.
• MockEFileAdapter will be the only enabled filing adapter until evidence-backed production gates are satisfied.

See architecture, support matrix, and go-live gates.

Current implementation progress is tracked in the milestone checklist.