LATCH Document Package Format (.latchdoc)

1. Status

LATCH Document Package Format, specification version 2.0 (draft).

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 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:

  1. Check the magic number and that header_len is within a sane limit (recommended maximum 64 KiB).
  2. Parse the header and confirm package_type is "latchdoc".
  3. Derive the key, decrypt, and verify the GCM tag.
  4. Verify the Ed25519 signature against the creating device's public key.
  5. Check that the SHA-256 of the decrypted plaintext equals package_id.
  6. Decompress with limits on total size and member count, and apply the path safety rules in Section 12.
  7. Check that every member is listed in manifest.json and that its SHA-256 matches.
  8. 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

  1. 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.

  2. Privacy and integrity. Packages can contain confidential material such as legal or medical documents, so they need both privacy and integrity protection.

  3. 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.

  4. 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.

  5. 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:

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