Migration V13 to V14

Migration V13 to V14

V13 and V14 are intentionally different formats and should be migrated explicitly rather than through heuristic interpretation.

Compatibility boundary

V13 browser packages:

SECURE-BROWSER-V13
.spk13

V14 server packages:

SECURE-PKG-V14
.spkg14

They are not interchangeable.

Main cryptographic difference

V13

• browser-side Web Crypto
• PBKDF2-HMAC-SHA-256
• 1,500,000 iterations
• AES-256-GCM
• browser streaming/chunk model

V14

• server-side Sodium
• Argon2id13
• XChaCha20-Poly1305-IETF
• secretstream XChaCha20-Poly1305
• random 256-bit package root key
• explicit credential/recovery key slots
• authenticated header binding
• blob SHA-256 inventory
• package Merkle root

No implicit conversion

The V14 reader does not attempt to treat a V13 package as a V14 package.

This is deliberate.

A format parser that guesses which security profile the caller intended can become a downgrade or confusion boundary.

Recommended operational migration

1. Keep the V13 browser client available for existing .spk13 packages.
2. Create all new server-side encrypted packages as V14.
3. Preserve V13 artifacts as legacy input during the migration period.
4. Store V14 recovery keys independently from their packages.
5. Introduce any V13-to-V14 conversion path as a dedicated, testable feature.
6. Require security review for the conversion reader/exporter before making it the default workflow.

What a future migration tool should guarantee

A future conversion tool should explicitly verify:

• source format identity
• source package integrity
• source credential validity
• complete source inventory
• source Merkle/integrity state
• output V14 format identity
• output package root key creation
• output key-slot construction
• output manifest integrity
• output restore equivalence

The result should be a fresh V14 package, not a V13 package with renamed metadata.

Why re-encryption is expected

The cryptographic profiles are different. A trustworthy migration therefore needs to:

V13 ciphertext
   -> authenticated V13 restore/decrypt
   -> plaintext staging
   -> fresh V14 encryption
   -> V14 verification

The conversion operation should not simply transplant V13 ciphertext into V14 structures.

Migration and recovery keys

A V14 recovery key is a new credential generated for the V14 package. A V13 recovery mechanism should not be copied into the V14 header unless the future migration design explicitly defines and authenticates such a relationship.

Legacy retention

The active source tree keeps superseded generation material under:

archive/secure-package-legacy.zip

This archive is historical material, not part of the active application surface.