Bundle wire format
v1.

The on-disk shape every Attestix portability bundle speaks. Tamper-evident, deterministic, JCS-canonical, and identical byte-for-byte across the OSS Python exporter and the cloud TypeScript worker. Published 2026-05-28. v1 is frozen.

01 / Identifier

The canonical URI for this version of the spec is:

https://attestix.io/spec/bundle/v1

Every bundle produced by Attestix — Python core ≥ v0.4.0 via the attestix.portability.bundle_writer module, the TypeScript cloud worker, and both the attestix export and attestix import CLIs — emits this exact string as the attestix_bundle_format field in manifest.json. The URI is dereferenceable to this page so a verifier holding only the bundle on disk can find the spec.

02 / Wire format at a glance

03 / Manifest schema

Every bundle carries one manifest.json whose body is the JCS-canonical serialisation of the following object. Field order is irrelevant on the wire (the canonicaliser sorts keys); the table below lists fields in semantic order.

{
  "manifest_version": "1.0",
  "attestix_bundle_format": "https://attestix.io/spec/bundle/v1",
  "workspace": {
    "id": "<UUID or slug>",
    "slug": "<tenant slug>",
    "region": "<aws-style region or 'local'>",
    "data_residency": "<eu|uk|us|in|ap|self-host>"
  },
  "exported_at": "<RFC-3339 UTC, ms precision>",
  "exported_by": {
    "user_id": "<UUID|'local'|null>",
    "email": "<email|'self-host@local'|null>"
  },
  "tables": [
    { "name": "<table>", "format": "jsonl",
      "row_count": <int>, "bytes": <int>, "sha256": "<hex>" }
  ],
  "core_version": "attestix==<semver>",
  "schemas": { "db_migration_max": "<zero-padded migration number>" },
  "notes": [ "<free-form producer note>" ]
}

04 / Side-car: manifest.sha256

A plain-text file inside the tarball alongside manifest.json. It contains the lowercase hex SHA-256 of the JCS-canonical manifest body followed by a single trailing newline (65 bytes total). Critical for verifier round-trips: the consumer can recompute the hash and compare without first parsing the manifest, and producers can transport the digest separately without round-tripping the full body.

The sha is computed over the manifest as it was written — the manifest's own sha256 appears only inside per-table entries; there is no self-reference at the manifest root, so no field needs to be stripped before re-canonicalising.

# Producer side
canonical = canonicalize_json(manifest)            # JCS bytes
sha = sha256(canonical).hexdigest()                # 64 hex chars
write_member("manifest.json", canonical)
write_member("manifest.sha256", sha + "\n")

# Verifier side
canonical = canonicalize_json(json.loads(manifest_bytes))
assert sha256(canonical).hexdigest() == sidecar.strip()

05 / Per-table tables

Thirteen tables. Order in the manifest tables[] array and on-disk MUST match the order below — cloud and OSS producers agree on this byte-for-byte. Cloud-only tables are emitted as empty JSONL members by OSS producers so the bundle's member set stays symmetric across producers.

Per-row schema for each table mirrors the Postgres column names used by the cloud database — snake_cased, with Date values rendered as ISO-8601 UTC strings, bigint values rendered as strings (JCS rejects numeric overflow), Buffer and Uint8Array rendered as lowercase hex, and null preserved verbatim. See the row projectors in attestix.portability.bundle_writer for the authoritative shape.

06 / Verifier algorithm (reference)

Two reference implementations: Python in attestix.portability.bundle_reader (PyPI attestix) and TypeScript in attestix-js (today @vibetensor/attestix@0.2.0; unscoped attestix publish in flight). Both follow the same algorithm:

1. Open bundle.tar.gz; extract every member to memory (bundle cap: 256 MiB; per-member cap: 128 MiB).
2. Read manifest.json; parse as JSON object.
3. JCS-canonicalise the parsed manifest dict (sort_keys + tightest separators + ensure_ascii=False).
4. Compute SHA-256 of the canonical bytes; read manifest.sha256 side-car; refuse on mismatch.
5. For each entry in manifest.tables[]:
     read <entry.name>.jsonl from the bundle
     compute SHA-256 over the raw bytes (no normalisation — the writer
       already wrote JCS-canonical lines, so re-canonicalising would drift)
     compare to entry.sha256; refuse on mismatch
     count newline-terminated lines; compare to entry.row_count; refuse on mismatch
6. For audit_events specifically: walk the rows in stored order, verify
     row[i].prev_hash == row[i-1].chain_hash and recompute row[i].chain_hash
     from the JCS-canonical body; refuse on any chain break.
7. Compare manifest.schemas.db_migration_max to the verifier's
     SUPPORTED_DB_MIGRATION_MAX; raise BundleSchemaTooNewError if strictly newer.
8. If every check passes: bundle integrity verified.

07 / Compatibility and versioning

• v1 is frozen. No breaking changes will land within v1. A future v2 will be published at a new URI (e.g. /spec/bundle/v2) and producers will stamp the new URI in attestix_bundle_format.
• Forward compatibility. Producers MAY add fields to the manifest or new tables to tables[]; verifiers MUST ignore unknown manifest fields and MUST ignore unknown tables that are not referenced by a verification rule.
• Schema gating. The schemas.db_migration_max field carries the producer's database migration version. Consumers refuse bundles whose db_migration_max is strictly newer than the consumer's supported max — see BundleSchemaTooNewError in bundle_reader.py.
• v2 plans (non-binding). zstd compression in place of gzip; optional Parquet representation for audit_events for large tenants; manifest signed via the producer's DID using Ed25519Signature2020. In v1 the manifest is unsigned; integrity is by SHA-256 only.

08 / Security model

Recommended deployment. Pair every bundle export with a signed BundleExportedCredential (W3C VC) issued at export time that attests to the bundle's SHA-256. The credential provides producer authenticity that the v1 wire format does not, without bloating the manifest with signature material.

09 / Example

The bytes below are extracted verbatim from the deterministic test fixture at tests/fixtures/bundles/sample-v1.tar.gz in the attestix repo. The bundle is 2,768 bytes on disk and contains 15 tar members (13 table JSONLs + manifest + sha side-car).

manifest.json (verbatim, JCS-canonical, 2,367 bytes)

{"attestix_bundle_format":"https://attestix.io/spec/bundle/v1","core_version":"attestix==0.4.0rc2","exported_at":"2026-05-28T12:00:00.000Z","exported_by":{"email":"operator@fixture.attestix.io","user_id":"22222222-2222-4222-8222-222222222222"},"manifest_version":"1.0","notes":["format=jsonl","fixture=oss-roundtrip"],"schemas":{"db_migration_max":"0010"},"tables":[{"bytes":2004,"format":"jsonl","name":"identities","row_count":2,"sha256":"8e0fba149ead951d8412a8634cb7d29fa7f9c2749929d7dee0d83e561e7d992f"},{"bytes":0,"format":"jsonl","name":"key_references","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"bytes":586,"format":"jsonl","name":"credentials","row_count":1,"sha256":"450e860134d4a00fdcbc66d76469fcbbea82181ae6f7740db042fb7d863d8575"},{"bytes":0,"format":"jsonl","name":"credential_schemas","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"bytes":0,"format":"jsonl","name":"memberships","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"bytes":0,"format":"jsonl","name":"team_invites","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"bytes":0,"format":"jsonl","name":"subscriptions","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"bytes":651,"format":"jsonl","name":"compliance_profiles","row_count":1,"sha256":"b58f382b75d0804e695fbe7e4708cf09326ca1f73498ca6504ec53fe7a8ae0fd"},{"bytes":383,"format":"jsonl","name":"conformity_assessments","row_count":1,"sha256":"e98f58b40249c985f05b8fb2203c8129b03184201b1059e3766b0d8d6bc9455e"},{"bytes":0,"format":"jsonl","name":"agent_dependencies","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},{"bytes":1999,"format":"jsonl","name":"audit_events","row_count":3,"sha256":"e3a185627ed4cd67781cd64011f3ca20d6d942751a1f0665c37d1823b498b316"},{"bytes":798,"format":"jsonl","name":"anchors","row_count":1,"sha256":"58d9dc30f6151c89a2cb8f0ef85b16cb8e4d6521faa33d884447a522f7adc034"},{"bytes":0,"format":"jsonl","name":"webhook_endpoints","row_count":0,"sha256":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}],"workspace":{"data_residency":"eu","id":"11111111-1111-4111-8111-111111111111","region":"eu-west-1","slug":"fixture-tenant"}}

manifest.sha256 (verbatim, 65 bytes including trailing newline)

b52c2baa896c82991f0c86afb6b771f4ab192d25dc153b463eb125183cf737c9

credentials.jsonl (one row; full W3C VC envelope; 586 bytes)

{"credential":{"credentialStatus":{"id":"urn:uuid:cred-fixture-0001#status","revocation_reason":null,"revoked":false,"revoked_at":null,"type":"RevocationList2021Status"},"credentialSubject":{"id":"attestix:fixture0000000001","role":"Fixture Subject"},"expirationDate":"2027-05-01T10:00:00Z","id":"urn:uuid:cred-fixture-0001","issuanceDate":"2026-05-01T10:00:00Z","issuer":{"id":"did:key:fixture-issuer","name":"Fixture Issuer"},"type":["VerifiableCredential","AgentIdentityCredential"]},"id":"cccccccc-cccc-4ccc-8ccc-cccccccccc01","workspace_id":"11111111-1111-4111-8111-111111111111"}

audit_events.jsonl (first row of a 3-row hash chain)

{"action":"identity.create","actor":"user:operator@fixture.attestix.io","anchor_id":null,"chain_hash":"5d1034b220c98c5a839df512fef2dff46e34e86df7dfb2d288a96528c0dfac88","change_digest":"d36b020fbbdb0baacea68cd168bcad261b3d283b8eb69554f3d31eb193947fd2","created_at":"2026-05-01T10:00:01Z","event_id":"evt:fixture000000","id":"99999999-9999-4999-8999-999999999900","occurred_at":"2026-05-01T10:00:00+00:00","occurred_at_month":"2026-05-01","prev_hash":"0000000000000000000000000000000000000000000000000000000000000000","retention_days":7,"target_collection":"identities","target_id":"attestix:fixture0000000001","workspace_id":"11111111-1111-4111-8111-111111111111"}

The first row's prev_hash is the genesis sentinel (64 zero bytes). Each subsequent row's prev_hash equals the previous row's chain_hash; each row's own chain_hash is computed over the JCS-canonical row body using the canonicaliser documented above.

10 / Test vectors

The deterministic fixture above is regenerated by tests/fixtures/bundles/generate_sample_bundle.py. Anyone building a third-party verifier can run the generator, byte-compare against the committed fixture, then assert their verifier accepts the clean bundle and rejects each of the three tamper variants the generator can produce (manifest body mutation, table body mutation, and schema-too-new bump).

The round-trip suite at tests/portability/ exercises every code path on this page against the fixture and is part of the 481-test CI matrix.

11 / Versions index