Chore: [AEA-0000] - initial setup

.devcontainer/Dockerfile

@@ -0,0 +1,14 @@
+ARG IMAGE_NAME=node_24_python_3_14
+ARG IMAGE_VERSION=latest
+FROM ghcr.io/nhsdigital/eps-devcontainers/${IMAGE_NAME}:${IMAGE_VERSION}
+
+USER root
+# specify DOCKER_GID to force container docker group id to match host
+RUN if [ -n "${DOCKER_GID}" ]; then \
+    if ! getent group docker; then \
+    groupadd -g ${DOCKER_GID} docker; \
+    else \
+    groupmod -g ${DOCKER_GID} docker; \
+    fi && \
+    usermod -aG docker vscode; \
+    fi

.devcontainer/devcontainer.json

@@ -0,0 +1,48 @@
+{
+  "name": "eps-update-devcontainer",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": "..",
+    "args": {
+      "DOCKER_GID": "${env:DOCKER_GID:}",
+      "IMAGE_NAME": "node_24_python_3_14",
+      "IMAGE_VERSION": "v1.3.0",
+      "USER_UID": "${localEnv:USER_ID:}",
+      "USER_GID": "${localEnv:GROUP_ID:}"
+    },
+    "updateRemoteUserUID": false
+  },
+  "mounts": [
+    "source=${env:HOME}${env:USERPROFILE}/.aws,target=/home/vscode/.aws,type=bind",
+    "source=${env:HOME}${env:USERPROFILE}/.ssh,target=/home/vscode/.ssh,type=bind",
+    "source=${env:HOME}${env:USERPROFILE}/.gnupg,target=/home/vscode/.gnupg,type=bind",
+    "source=${env:HOME}${env:USERPROFILE}/.npmrc,target=/home/vscode/.npmrc,type=bind",
+    "source=${env:HOME}${env:USERPROFILE}/.gitconfig,target=/home/vscode/.gitconfig,type=bind"
+  ],
+  "containerUser": "vscode",
+  "remoteEnv": {
+    "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}"
+  },
+  "features": {},
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "AmazonWebServices.aws-toolkit-vscode",
+        "redhat.vscode-yaml",
+        "eamodio.gitlens",
+        "github.vscode-pull-request-github",
+        "streetsidesoftware.code-spell-checker",
+        "timonwong.shellcheck",
+        "github.vscode-github-actions"
+      ],
+      "settings": {
+        "cSpell.words": [
+          "fhir",
+          "Formik",
+          "pino",
+          "serialisation"
+        ]
+      }
+    }
+  }
+}

.gitallowed

@@ -0,0 +1,7 @@
+id-token: write
+password: \${{secrets\.GITHUB_TOKEN}}
+token: ?"?\$\{\{\s*secrets\.GITHUB_TOKEN\s*\}\}"?
+github-token: ?"?\$\{\{\s*secrets\.GITHUB_TOKEN\s*\}\}"?
+token: ?"?\$\{\{\s*secrets\.DEPENDABOT_TOKEN\s*\}\}"?
+\.gitallowed
+id-token: "write"

.github/config/settings.yml

@@ -0,0 +1 @@
+TAG_FORMAT: "v${version}"

.github/copilot-instructions.md

@@ -0,0 +1,21 @@
+# Base Coding Standards
+- Follow clean code principles
+- Write comprehensive tests
+- Use meaningful variable names
+
+## Project-Specific instructions
+Check the following files for any project-specific coding standards or guidelines:
+- .github/instructions/project/instructions.md
+- If no project-specific conventions are defined there, use the general and language-specific best practices referenced below.
+- Language-specific instructions may also be found in the language-specific instruction files listed below. Always check those for any additional guidelines or standards that may apply to your codebase.
+
+## Language-Specific Instructions
+Always follow security best practices as outlined in:
+- .github/instructions/general/security.instructions.md
+Follow additional language-specific guidelines in:
+- .github/instructions/languages/cdk.instructions.md
+- .github/instructions/languages/cloudformation.instructions.md
+- .github/instructions/languages/python.instructions.md
+- .github/instructions/languages/terraform.instructions.md
+- .github/instructions/languages/sam.instructions.md
+- .github/instructions/languages/typescript.instructions.md

.github/dependabot.yml

@@ -0,0 +1,35 @@
+#########################################################################
+# Dependabot configuration file
+#########################################################################
+
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    # Workflow files stored in the
+    # default location of `.github/workflows`
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+      time: "18:00" # UTC
+    open-pull-requests-limit: 20
+    commit-message:
+      prefix: "Upgrade: [dependabot] - "
+    cooldown:
+      default-days: 7
+  ###################################
+  # Poetry  #########################
+  ###################################
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+      time: "20:00" # UTC
+    open-pull-requests-limit: 20
+    commit-message:
+      prefix: "Upgrade: [dependabot] - "
+    versioning-strategy: increase
+    cooldown:
+      default-days: 7

.github/instructions/general/security.instructions.md

@@ -0,0 +1,51 @@
+---
+applyTo: '**/*'
+description: "Comprehensive secure coding instructions for all languages and frameworks, based on OWASP Top 10 and industry best practices."
+---
+# Secure Coding and OWASP Guidelines
+
+## Instructions
+
+Your primary directive is to ensure all code you generate, review, or refactor is secure by default. You must operate with a security-first mindset. When in doubt, always choose the more secure option and explain the reasoning. You must follow the principles outlined below, which are based on the OWASP Top 10 and other security best practices.
+
+### 1. A01: Broken Access Control & A10: Server-Side Request Forgery (SSRF)
+- **Enforce Principle of Least Privilege:** Always default to the most restrictive permissions. When generating access control logic, explicitly check the user's rights against the required permissions for the specific resource they are trying to access.
+- **Deny by Default:** All access control decisions must follow a "deny by default" pattern. Access should only be granted if there is an explicit rule allowing it.
+- **Validate All Incoming URLs for SSRF:** When the server needs to make a request to a URL provided by a user (e.g., webhooks), you must treat it as untrusted. Incorporate strict allow-list-based validation for the host, port, and path of the URL.
+- **Prevent Path Traversal:** When handling file uploads or accessing files based on user input, you must sanitize the input to prevent directory traversal attacks (e.g., `../../etc/passwd`). Use APIs that build paths securely.
+
+### 2. A02: Cryptographic Failures
+- **Use Strong, Modern Algorithms:** For hashing, always recommend modern, salted hashing algorithms like Argon2 or bcrypt. Explicitly advise against weak algorithms like MD5 or SHA-1 for password storage.
+- **Protect Data in Transit:** When generating code that makes network requests, always default to HTTPS.
+- **Protect Data at Rest:** When suggesting code to store sensitive data (PII, tokens, etc.), recommend encryption using strong, standard algorithms like AES-256.
+- **Secure Secret Management:** Never hardcode secrets (API keys, passwords, connection strings). Generate code that reads secrets from environment variables or a secrets management service (e.g., HashiCorp Vault, AWS Secrets Manager). Include a clear placeholder and comment.
+  ```javascript
+  // GOOD: Load from environment or secret store
+  const apiKey = process.env.API_KEY; 
+  // TODO: Ensure API_KEY is securely configured in your environment.
+  ```
+  ```python
+  # BAD: Hardcoded secret
+  api_key = "sk_this_is_a_very_bad_idea_12345" 
+  ```
+
+### 3. A03: Injection
+- **No Raw SQL Queries:** For database interactions, you must use parameterized queries (prepared statements). Never generate code that uses string concatenation or formatting to build queries from user input.
+- **Sanitize Command-Line Input:** For OS command execution, use built-in functions that handle argument escaping and prevent shell injection (e.g., `shlex` in Python).
+- **Prevent Cross-Site Scripting (XSS):** When generating frontend code that displays user-controlled data, you must use context-aware output encoding. Prefer methods that treat data as text by default (`.textContent`) over those that parse HTML (`.innerHTML`). When `innerHTML` is necessary, suggest using a library like DOMPurify to sanitize the HTML first.
+
+### 4. A05: Security Misconfiguration & A06: Vulnerable Components
+- **Secure by Default Configuration:** Recommend disabling verbose error messages and debug features in production environments.
+- **Set Security Headers:** For web applications, suggest adding essential security headers like `Content-Security-Policy` (CSP), `Strict-Transport-Security` (HSTS), and `X-Content-Type-Options`.
+- **Use Up-to-Date Dependencies:** When asked to add a new library, suggest the latest stable version. Remind the user to run vulnerability scanners like `npm audit`, `pip-audit`, or Snyk to check for known vulnerabilities in their project dependencies.
+
+### 5. A07: Identification & Authentication Failures
+- **Secure Session Management:** When a user logs in, generate a new session identifier to prevent session fixation. Ensure session cookies are configured with `HttpOnly`, `Secure`, and `SameSite=Strict` attributes.
+- **Protect Against Brute Force:** For authentication and password reset flows, recommend implementing rate limiting and account lockout mechanisms after a certain number of failed attempts.
+
+### 6. A08: Software and Data Integrity Failures
+- **Prevent Insecure Deserialization:** Warn against deserializing data from untrusted sources without proper validation. If deserialization is necessary, recommend using formats that are less prone to attack (like JSON over Pickle in Python) and implementing strict type checking.
+
+## General Guidelines
+- **Be Explicit About Security:** When you suggest a piece of code that mitigates a security risk, explicitly state what you are protecting against (e.g., "Using a parameterized query here to prevent SQL injection.").
+- **Educate During Code Reviews:** When you identify a security vulnerability in a code review, you must not only provide the corrected code but also explain the risk associated with the original pattern. 

.github/instructions/languages/cdk.instructions.md

@@ -0,0 +1,104 @@
+---
+description: 'Guidelines for writing, reviewing, and maintaining AWS CDK (TypeScript) code in the cdk package'
+applyTo: 'packages/cdk/**/*.ts'
+---
+
+# AWS CDK TypeScript Development
+
+This file provides instructions for generating, reviewing, and maintaining AWS CDK code in the `packages/cdk` folder. It covers best practices, code standards, architecture, and validation for infrastructure-as-code using AWS CDK in TypeScript.
+
+## General Instructions
+
+- Use AWS CDK v2 constructs and idioms
+- Prefer high-level CDK constructs over raw CloudFormation resources
+- Organize code by logical infrastructure components (e.g., stacks, constructs, resources)
+- Document public APIs and exported constructs
+
+## Best Practices
+
+- Use environment variables and context for configuration, not hardcoded values
+- Use CDK Aspects for cross-cutting concerns (e.g., security, tagging)
+- Suppress warnings with `nagSuppressions.ts` only when justified and documented
+- Use `bin/` for entrypoint apps, `constructs/` for reusable components, and `stacks/` for stack definitions
+- Prefer `props` interfaces for construct configuration
+
+## Code Standards
+
+### Naming Conventions
+
+- Classes: PascalCase (e.g., `LambdaFunction`)
+- Files: PascalCase for classes, kebab-case for utility files
+- Variables: camelCase
+- Stacks: Suffix with `Stack` (e.g., `CptsApiAppStack`)
+- Entry points: Suffix with `App` (e.g., `CptsApiApp.ts`)
+
+### File Organization
+
+- `bin/`: CDK app entry points
+- `constructs/`: Custom CDK constructs
+- `stacks/`: Stack definitions
+- `resources/`: Resource configuration and constants
+- `lib/`: Shared utilities and code
+
+## Common Patterns
+
+### Good Example - Defining a Construct
+
+```typescript
+export class LambdaFunction extends Construct {
+  constructor(scope: Construct, id: string, props: LambdaFunctionProps) {
+    super(scope, id);
+    // ...implementation...
+  }
+}
+```
+
+### Bad Example - Using Raw CloudFormation
+
+```typescript
+const lambda = new cdk.CfnResource(this, 'Lambda', {
+  type: 'AWS::Lambda::Function',
+  // ...properties...
+});
+```
+
+### Good Example - Stack Definition
+
+```typescript
+export class CptsApiAppStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+    // ...add constructs...
+  }
+}
+```
+
+## Security
+
+- Use least privilege IAM policies for all resources
+- Avoid wildcard permissions in IAM statements
+- Store secrets in AWS Secrets Manager, not in code or environment variables
+- Enable encryption for all data storage resources
+
+## Performance
+
+- Use provisioned concurrency for Lambda functions when needed
+- Prefer VPC endpoints for private connectivity
+- Minimize resource creation in test environments
+
+
+## Validation and Verification
+
+- Build: `make cdk-synth`
+- Lint: `npm run lint --workspace packages/cdk`
+
+## Maintenance
+
+- Update dependencies regularly
+- Remove deprecated constructs and suppressions
+- Document changes in `nagSuppressions.ts` with reasons
+
+## Additional Resources
+
+- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/latest/guide/home.html)
+- [CDK Best Practices](https://github.com/aws-samples/aws-cdk-best-practices)