Scanned File Checksums

Overview

To ensure the integrity and safety of files stored in Firebase Storage, each file is scanned for malware and assigned a checksum. This checksum, stored in the file’s Firebase Storage metadata, allows the system to validate that the file has not been tampered with before it is downloaded. A status metadata field also indicates whether the file was marked as safe (clean) during its scan.

Validation is handled via a Cloud Function (verifyFileChecksum) which compares the stored checksum to a freshly calculated one prior to any file download.

Features

1. Checksum Creation and Storage

Checksums are created using a SHA-256 hash of the file content.

  • createChecksum: Computes a hash from file content
  • Checksums are stored within file custom metadata

This metadata is the source of truth for integrity checks.

2. Cloud Function: verifyFileChecksum

A callable function that performs checksum validation. When called, it:

  1. Fetches the file
  2. Validates that:
    • The file’s customMetadata.status === 'clean'
  3. Downloads the file
  4. Computes the SHA-256 checksum
  5. Compares it to the stored metadata checksum

It returns:

{ 
    valid: boolean, 
    isFileClean: boolean, 
    metadata: object, - null if no checksum
    message?: string - present only if there’s an error or mismatch
}

3. Frontend Integration

All frontend repositories with download functionality (e.g. Apply, Admin, Assessments) should integrate this validation step before permitting a file to be downloaded.

ALL Downloads should call verifyFileChecksum before allowing download

This will block the download if:

  • The checksum is missing or doesn’t match
  • The file is not marked as clean

*A feature flag controls whether checksums are enforced.*

Found under /settings/candidateSettings/checksums/enabled = Bool [true/false]

This allows for:

  • A safe rollout across environments
  • Uploads to continue while legacy files are backfilled with checksums disabling of checksums if an issue arrises

Usage

Uploading Files

When a file is uploaded: It is scanned for malware If clean, a SHA-256 checksum is generated The checksum and status are stored in file metadata

Validating Files (Pre-download)

Before download:

The frontend calls the verifyFileChecksum function with the file path

If validation fails, the download is blocked

Handling Errors

If:

Metadata is missing

Checksum is absent or mismatched

The file is not marked as clean
→ the frontend should gracefully handle the error and prevent the file from being downloaded

API Reference Callable Function: verifyFileChecksum

Request:

{ filePath: string }

Response:

{ valid: boolean, isFileClean: boolean, metadata: object, message?: string // e.g. ‘Checksum mismatch’ or error reason }