HMRC Business Tax Account (BTA) + VAT Demonstrator

A mock front-end application demonstrating how HMRC could use Verifiable Credentials to digitise VAT registration. This project simulates the HMRC Business Tax Account experience to showcase the journey of requesting and receiving a "Digital VAT ID" (Verifiable Credential).

Note: This is a purely demonstrative simulation using GOV.UK patterns. It is not connected to real HMRC systems and is for research and demonstration purposes only.

Purpose

The primary goal is to demonstrate the user journey for a business to:

1. View their VAT status on a simulated HMRC dashboard.
2. Request a Verifiable Credential (Digital VAT ID).
3. Connect a digital wallet to receive the credential.

Features

• HMRC Look & Feel: Built using govuk-frontend and hmrc-frontend to match official design patterns.
• Simulated BTA Landing Page: Displays a realistic-looking business tax summary.
• VAT Dashboard: Shows fictitious VAT return statuses and periods.
• Credential Issuance Flow:
  • Generates Out-of-Band (OOB) invitations for connection.
  • Displays QR codes for wallet interaction.
  • Simulates the issuance of a digital credential upon connection.
• Demo-first state management: Issuance sessions are stored in-memory (no file/database persistence). Restarting the service clears any active sessions.

Tech Stack

• Runtime: Node.js (v20+)
• Server: Express.js
• Templating: Nunjucks
• Frontend Frameworks:
  • GOV.UK Frontend
  • HMRC Frontend

Prerequisites

• Node.js (version 20 or higher)
• npm (usually included with Node.js)
• A running instance of veritable-cloudagent (for full credential issuance functionality)

Configuration

The application can be configured using environment variables:

Variable	Default	Description
PORT	3000	The port the web server listens on.
HMRC_AGENT_URL	http://hmrc-agent:3000	The URL of the Verifiable Cloud Agent API.
ISSUER_DID	-	Required. The DID of the Issuer (used for W3C credential signatures).
COMPANY_DID	-	Required. The DID of the Subject/Holder (used for W3C credential issuance).
SESSION_TTL_MS	-	Optional. If set to a positive integer, issuance sessions older than this (ms) will be expired/cleaned up.

Session storage

This demonstrator keeps the “Digital VAT ID” issuance session state in-memory (see src/data/db.js). Sessions persist for as long as the web process/container is running, but are cleared on restart. It does not write a database.json file.

Getting Started

1. Clone the repository:

   git clone <repository-url>
   cd veritable-hmrc-mock

2. Install dependencies:

   npm install

3. Run the application:

   • Development mode (with auto-restart):

     npm run dev

   • Production mode:

     npm start

4. Access the application: Open your browser and navigate to http://localhost:3000 (or the port specified in the console output).

User Journey

1. Landing Page: The user starts at the simulated Business Tax Account home page.
2. VAT Overview: Navigate to the VAT section to view details.
3. Request Digital ID: Select the option to request a digital proof of VAT registration.
4. Wallet Connection:
   • The application presents a QR code and connection link.
   • The user scans this with their digital wallet app.
   • Once connected, the mock server interacts with a cloud agent (simulated or real, depending on configuration) to issue the credential.

For a detailed technical flow and sequence diagram, please refer to docs/flow.md.

Project Structure

• src/server.js: Main application entry point and Express configuration.
• src/routes/: Express route definitions (index.js, vat.js).
• src/views/: Nunjucks templates using GOV.UK/HMRC macros.
• src/data/: Mock data and scenario configurations.
• plan/: Planning and documentation files.
• docs/: Additional documentation, including the Technical Flow.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.