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

# Checksums

> Answer md5sum and sha256sum from a stored hash.

Checksums lets a VFS answer hash commands from a hash its service already
stores, without reading the file.
[Built-in VFSs](https://docs.mirage.strukto.ai/home/integration/overview.md#checksums) lists which VFSs support
it.

## VFS and Checksums Integration

A VFS overrides `checksum` when its service stores hashes. It returns `None`
(TypeScript: `null`) when it has no stored hash, and Mirage reads and hashes
the file instead. The example extends `NotesVFS` from
[Adding a New VFS](https://docs.mirage.strukto.ai/home/setup/vfs/new.md#write-one), mounted at `/notes`.

### `checksum`

The stored hash of one file.

**Commands:** `md5sum`, `md5`, `sha1sum`, `sha224sum`, `sha256sum`,
`sha384sum`, `sha512sum` and `b2sum`. With `-c`, which checks the hashes
listed in a file, they read the files without asking.

**path** `PathSpec` *required*

The file, on this mount.

**algorithm** `str` *required*

The hash to return: `md5`, `sha1`, `sha224`, `sha256`, `sha384`, `sha512`, `blake2b`, or `blake2b-N` for BLAKE2b at N bits.

**Examples:**

| Command | `path` | `algorithm` |
| - | - | - |
| `md5sum /notes/hello.txt` | `/notes/hello.txt` | `md5` |
| `sha256sum /notes/hello.txt` | `/notes/hello.txt` | `sha256` |
| `b2sum /notes/hello.txt` | `/notes/hello.txt` | `blake2b` |
| `b2sum -l 256 /notes/hello.txt` | `/notes/hello.txt` | `blake2b-256` |

**returns** `str | None`

| Return | What happens |
| - | - |
| The lowercase hex hash of exactly the bytes a read returns | The command prints it, and the file is not read. |
| `None` | The file is read and hashed. |

> [tab] Python
>
> ```python theme={null}
> import hashlib
>
> from mirage import PathSpec
>
> from notes import NotesVFS
>
>
> class HashedNotesVFS(NotesVFS):
>     async def checksum(self, path: PathSpec, algorithm: str) -> str | None:
>         if algorithm != "md5":
>             return None
>         return hashlib.md5(self.page(path).encode()).hexdigest()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { createHash } from 'node:crypto'
> import type { PathSpec } from '@struktoai/mirage-node'
> import { NotesVFS } from './notes.ts'
>
> export class HashedNotesVFS extends NotesVFS {
>   override async checksum(path: PathSpec, algorithm: string): Promise<string | null> {
>     if (algorithm !== 'md5') return null
>     return createHash('md5').update(this.page(path)).digest('hex')
>   }
> }
> ```

A real service returns the hash it stores. This example computes MD5 and
leaves the others to Mirage, so `md5sum /notes/hello.txt` reads nothing, and
`sha256sum /notes/hello.txt` still reads the page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.