LATCH Document Package Format (.latchdoc)
1. Status
LATCH Document Package Format, specification version 2.0 (draft).
- Change controller: CoDynamics Lab Corporation
- Contact: mike@codynamicslab.com
- Last updated: November 10, 2026
Version 2.0 is the published target format. The current LATCH release writes version 1 files, described in Section 13.
2. Purpose
A .latchdoc file is a document package. It carries one or more documents together with everything derived from them:
- the original files
- the extracted text, and a map from text positions to pages
- extracted entities (names, dates, docket numbers, record numbers, and similar)
- optional precomputed data for AI models
- optional audit records
The package is encrypted, signed by the device that created it, and lists a SHA-256 digest for every file inside it. A recipient can confirm that nothing was changed, and can rebuild any model-specific data from the sealed source.
The companion format for sending a search result is the .latch finding package, specified at /docs/formats/latch. Both formats share the same envelope (Sections 4 to 7).
3. Identification
| Item | Value |
|---|---|
| Media type | application/vnd.codynamicslab.latchdoc |
| File extension | .latchdoc |
| Magic number | 4C 41 54 43 48 32 00 00 ("LATCH2" followed by two null bytes) at offset 0 |
| Package type (header field) | "latchdoc" |
| macOS UTI | com.codynamicslab.latchdoc |
.latchdoc and .latch files share a magic number. Readers tell them apart by the package_type field in the cleartext header.
4. File layout
All integers are little-endian.
| Offset | Size | Field |
|---|---|---|
| 0 | 8 bytes | Magic number |
| 8 | 4 bytes | header_len (unsigned 32-bit) |
| 12 | header_len bytes |
Header, UTF-8 JSON |
| next | 16 bytes | Salt |
| next | 12 bytes | Nonce |
| next | variable | Ciphertext |
| last | 16 bytes | AES-256-GCM authentication tag |
The GCM associated data is magic || header_len || header bytes, so the cleartext header is authenticated together with the ciphertext.
5. Header
The header is a JSON object.
| Field | Description |
|---|---|
package_type |
"latchdoc" |
spec_version |
"2.0" |
package_id |
Lowercase hex SHA-256 of the plaintext (the zstd-compressed tar, before encryption) |
created_at |
RFC 3339 UTC timestamp |
created_by_device |
Ed25519 public key id of the device that created the package |
kdf |
{"alg": "argon2id", "m": <KiB>, "t": <iterations>, "p": <parallelism>}, or {"alg": "none", "key_id": "<id>"} when a raw organization key is used |
signature |
Base64 Ed25519 signature (Section 7) |
The header never contains document content or file names. Readers must ignore unknown header fields. Readers must reject a package whose spec_version has an unknown major version.
6. Key derivation
When kdf.alg is argon2id, the 32-byte AES key is derived with Argon2id from the passphrase and the 16-byte salt, using the parameters in the header. Recommended minimums: m = 65536 (64 MiB), t = 3, p = 1.
When kdf.alg is none, the key is a 32-byte organization key identified by key_id and shared out of band.
The key must never default to a license token or any other value the user did not choose.
7. Signature
The signature is Ed25519 over the RFC 8785 (JCS) canonical JSON of the header with the signature field removed. Because package_id is part of the signed header, the signature also covers the full archive contents.
8. Plaintext archive
The plaintext is a POSIX tar archive (pax format) compressed with Zstandard (RFC 8878).
| Member | Required | Contents |
|---|---|---|
manifest.json |
Yes | Every member: path, size, full-file SHA-256, role |
documents.json |
Yes | Document ids, original file names, SHA-256 of original and of extracted text |
source/<sha256> |
Yes | Original files, named by their SHA-256 |
text/<sha256>.txt |
Yes | Extracted UTF-8 text, named by its SHA-256 |
offsets/<sha256>.json |
Yes | Map from text character ranges to page numbers and page coordinates |
entities/<sha256>.json |
No | Extracted entities with their positions |
payloads/<kind>/... |
No | Optional precomputed data (Section 9) |
audit/ |
No | Audit entries and chain proof |
8.1 manifest.json
{
"spec_version": "2.0",
"package_type": "latchdoc",
"members": [
{ "path": "documents.json", "size": 2210, "sha256": "5a7e...", "role": "documents" },
{ "path": "source/c3b8...", "size": 1843302, "sha256": "c3b8...", "role": "source" },
{ "path": "text/4f1c....txt", "size": 61204, "sha256": "4f1c...", "role": "text" }
]
}
8.2 documents.json
{
"documents": [
{
"doc_id": "d_0001",
"original_name": "Henderson_Lease_Amendment_3.pdf",
"original_sha256": "c3b8...",
"text_sha256": "4f1c...",
"media_type": "application/pdf",
"extractor": "docling 2.x",
"ocr": { "used": true, "mean_page_confidence": 0.94, "low_confidence_pages": [7] }
}
]
}
8.3 offsets/<sha256>.json
Offsets are Unicode code point positions in the extracted text.
{
"text_sha256": "4f1c...",
"ranges": [
{ "start": 0, "end": 3120, "page": 1, "boxes": [[72.0, 90.5, 540.0, 702.0]] },
{ "start": 3120, "end": 6410, "page": 2, "boxes": [[72.0, 88.0, 540.0, 700.4]] }
]
}
8.4 entities/<sha256>.json
{
"text_sha256": "4f1c...",
"entities": [
{ "type": "person", "text": "John A. Smith", "normalized": "smith, john a", "start": 18234, "end": 18247 },
{ "type": "docket", "text": "2:24-cv-01187", "normalized": "2:24-cv-01187", "start": 912, "end": 925 }
]
}
9. Payload kinds
Payloads are optional precomputed data stored under payloads/<kind>/.
| Payload kind | Model-bound | Exact | Purpose |
|---|---|---|---|
structured-text |
No | Yes | Layout-aware text any reader or model can use |
embeddings/<model> |
Yes | Not applicable | Skip re-embedding on import |
kv-exact/<model-id> |
Yes | Yes | Precomputed attention cache for a named model |
cdlac-memory/<tuple-id> |
Yes | No (lossy) | Compressed memory for a named model tuple |
Readers must ignore payload kinds they do not recognize. Any model-bound payload can be dropped and rebuilt from source/ and text/, so a package stays readable after the model changes.
10. Reader verification
To verify a .latchdoc file:
- Check the magic number and that
header_lenis within a sane limit (recommended maximum 64 KiB). - Parse the header and confirm
package_typeis"latchdoc". - Derive the key, decrypt, and verify the GCM tag.
- Verify the Ed25519 signature against the creating device's public key.
- Check that the SHA-256 of the decrypted plaintext equals
package_id. - Decompress with limits on total size and member count, and apply the path safety rules in Section 12.
- Check that every member is listed in
manifest.jsonand that its SHA-256 matches. - Check that each original file and each extracted text file hashes to the SHA-256 listed for it in
documents.json.
Reject the package if any step fails.
11. Relationship to .latch
.latchdoc |
.latch |
|
|---|---|---|
| Carries source documents | Yes | No |
| Carries extracted text | Yes | No |
| Carries verbatim quotes | No | Yes, short quotes only |
| Typical size | Large | Small |
| Typical use | Archive or transfer a document set | Send a finding to a partner, co-counsel, expert, or referring physician |
A .latchdoc provides the extracted text a recipient needs to verify every quote in a matching .latch file fully offline.
12. Security considerations
-
Active content. The format itself defines no executable or active content. However, a package carries original source documents (for example PDF or Office files), and those files may contain active content such as scripts or macros from their original authors. Readers must not execute or render anything inside a package automatically. Original files should be opened only in applications that apply their normal protections for that file type. Extracted text may also contain instructions aimed at AI models that later read it, so systems that pass package text to a language model should treat it as untrusted data, not as instructions.
-
Privacy and integrity. Packages can contain confidential material such as legal or medical documents, so they need both privacy and integrity protection.
-
Services provided by the format. The archive is encrypted with AES-256-GCM. The key is derived from a passphrase or organization key using Argon2id. The GCM tag authenticates the ciphertext and the cleartext header. Each package is signed with Ed25519 by the device that created it. The manifest lists a SHA-256 digest for every file, and readers must check the tag, the signature, and every digest before using any content. The cleartext header holds only format metadata, never document content. Anyone with the passphrase or key can read the contents, so keys must be protected and shared separately from the file.
-
Use of existing formats. The header and the manifest files are JSON, and the security considerations of RFC 8259, Section 12 apply. Readers should limit header size, reject duplicate keys and malformed input, and treat all fields as untrusted until the signature and GCM tag have been verified. The format does not use JSON extensibility to carry executable content. Unknown fields and unknown payload kinds must be ignored, not interpreted.
4a. Compression. The archive is compressed with Zstandard, and the security considerations of RFC 8878, Section 7 apply. Readers should enforce limits on decompressed size and file count to protect against decompression bombs, and should check sizes listed in the manifest before extracting.
4b. Container format. The decrypted payload is a tar archive. Readers must reject absolute paths,
..path segments, symbolic links, hard links, and device files, so that extraction cannot write outside the target directory or overwrite existing files. Readers must reject any archive member not listed in the signed manifest, and any member whose SHA-256 digest does not match the manifest. -
Links. The format does not include links that must be fetched to interpret it. All source documents, extracted text, and metadata are contained in the package itself, and references between files inside the package use SHA-256 digests, not URLs. Readers must not fetch remote resources while processing a package.
Additional note. Some optional payloads contain model-specific data (for example embeddings or attention caches). That data can reveal information about the source text, so it is protected by the same encryption as the documents.
13. Legacy version 1 files
The current LATCH release writes .latchdoc files using the version 1 layout:
- Magic
LATCH1\0\0(8 bytes), salt (16 bytes), nonce (12 bytes), ciphertext, GCM tag (16 bytes). The GCM associated data is empty. - Key from PBKDF2-HMAC-SHA256 with 600,000 iterations. If no passphrase is given, version 1 derives the key from the instance license token. If no license token is configured either, version 1 writes an unencrypted tar.gz file with no magic number.
- tar.gz payload containing
manifest.json(schema version 1.0, with aruntime_compatibility_id),documents.json, per-document compressed memory caches undercache/(memory.safetensorsandmetadata.json), and verbatim source text undertext/. - The version 1 manifest lists no per-file digests. Integrity rests on the GCM tag. The
runtime_compatibility_ididentifies the model files with a sampled digest that hashes only the file size plus the first and last 64 KB of each file.
Version 1 is superseded by this specification. Readers may support version 1 for import. A reader can tell the versions apart by the magic number. Unencrypted version 1 files begin with the gzip signature 1F 8B.
14. Media type registration
Type name: application
Subtype name: vnd.codynamicslab.latchdoc
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: binary
Security considerations: See Section 12 of the published specification.
Interoperability considerations: Files begin with the 8-byte magic
number "LATCH2" followed by two null bytes, then a 4-byte
little-endian header length and a UTF-8 JSON header. The header
carries a spec_version field. Readers must reject files with an
unknown major version and must ignore unknown header fields and
unknown payload kinds. Model-specific payloads are optional and can
be rebuilt from the source documents in the package. Version 1 files
use the magic number "LATCH1" and are a different, legacy layout.
Published specification: https://www.codynamicslab.com/docs/formats/latchdoc
Applications that use this media type: CoDynamics Lab document
software, including the LATCH document appliance and its
verification tools.
Fragment identifier considerations: N/A
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): 4C 41 54 43 48 32 00 00 at offset 0
File extension(s): .latchdoc
Macintosh file type code(s): N/A
Person & email address to contact for further information:
mike@codynamicslab.com
Intended usage: COMMON
Restrictions on usage: None
Author: CoDynamics Lab Corporation
Change controller: CoDynamics Lab Corporation
15. Changelog
- 2.0 (draft), November 10, 2026: Initial public specification.