path: root/source/storage/Record.mc

// Author:  cirakg & claude ai
// Summary: The stored byte format of one entry: readable TLV header plus a SealedBox with the sensitive fields.
//
// Record format, version 1 (one ByteArray under the key "e.<id>"):
//
//     v (1 byte, = 1) | kr (1 byte) | hlen (2 bytes, big-endian) | header (hlen bytes) | box
//
//     kr     = 0: sealed with the device key, 1: sealed with the locked master key
//     header = Codec TLV of the header fields (tags 1-13), readable without a key
//     box    = SealedBox of the Codec TLV of the sensitive fields (tags 20-28)
//     aad    = UTF-8 id || v || kr || hlen || header
//
// Because the aad holds the ID and the whole header, the box's MAC covers
// them: changing the HOTP counter, the locked flag or a name, or copying a
// record under another ID, makes open() fail (README 7.3). Reading only the
// header (for the list) doesn't check the MAC; the header is not secret and
// the device key, which would be needed to forge it, is stored next to it
// anyway (README 7.4).
//
// With "Encrypt names" the name, account and group move from the header
// into the box (tags 26-28).
//
// Decoding never throws: malformed input gives null and the vault reports
// the entry as damaged.

import Toybox.Lang;

module Record {

    const VERSION = 1;
    const KEY_DEVICE = 0;
    const KEY_MASTER = 1;
    const PREFIX_BYTES = 4;
    // Application.Storage allows 8 KB per value; stay clearly below it.
    const MAX_BYTES = 8000;

    // Header tags.
    const H_ID = 1;
    const H_KIND = 2;
    const H_TYPE = 3;
    const H_NAME = 4;
    const H_ACCOUNT = 5;
    const H_GROUP = 6;
    const H_LOCKED = 7;
    const H_SOURCE = 8;
    const H_FAVORITE = 9;
    const H_COUNTER = 10;
    const H_CREATED = 11;
    const H_NAMES_ENCRYPTED = 12;
    const H_FINGERPRINT = 13;

    // Sensitive tags (inside the box).
    const S_ALGORITHM = 20;
    const S_DIGITS = 21;
    const S_PERIOD = 22;
    const S_SECRET = 23;
    const S_PAYLOAD = 24;
    const S_OPTIONS = 25;
    const S_NAME = 26;
    const S_ACCOUNT = 27;
    const S_GROUP = 28;

    // Seal an entry into record bytes. keyRef is KEY_DEVICE or KEY_MASTER and
    // must match `keys`. The plaintext TLV is wiped before returning.
    function seal(entry as Entry, keyRef as Number, keys as SealedBox.Keys) as ByteArray {
        return sealWith(entry, keyRef, keys, null);
    }

    // As seal(), but the plaintext TLV goes to `wiper` when given: wiping a
    // large code's contents is a step of its own (the watchdog).
    function sealWith(entry as Entry, keyRef as Number, keys as SealedBox.Keys, wiper as Jobs.Wiper?) as ByteArray {
        var header = encodeHeader(entry);
        var record = [VERSION, keyRef, (header.size() >> 8) & 0xFF, header.size() & 0xFF]b;
        record.addAll(header);
        var plain = encodeSecret(entry);
        var leftovers = wiper != null ? [] as Array<ByteArray> : null;
        var box = SealedBox.sealKeep(keys, aad(entry.id, record), plain, leftovers);
        if (wiper != null) {
            wiper.add(plain);
            wiper.addAll(leftovers as Array<ByteArray>);
        } else {
            Bytes.wipe(plain);
        }
        record.addAll(box);
        return record;
    }

    // The key reference (KEY_DEVICE or KEY_MASTER), or null when the bytes
    // aren't a version-1 record.
    function keyRef(record as ByteArray) as Number? {
        var headerEnd = headerEnd(record);
        if (headerEnd == null) {
            return null;
        }
        return record[1];
    }

    // The header fields only (no key needed, MAC not checked), or null when
    // malformed. The returned entry has no secret or payload.
    function decodeHeader(record as ByteArray) as Entry? {
        var end = headerEnd(record);
        if (end == null) {
            return null;
        }
        var map = Codec.decode(record.slice(PREFIX_BYTES, end));
        if (map == null) {
            return null;
        }
        var f = new Fields(map);
        var entry = new Entry();
        entry.id = f.text(H_ID, true);
        entry.kind = f.number(H_KIND, Entry.KIND_OTP, Entry.KIND_CODE, true);
        entry.type = f.number(H_TYPE, 0, Entry.MAX_SYMBOLOGY, true);
        entry.name = f.text(H_NAME, false);
        entry.account = f.text(H_ACCOUNT, false);
        entry.group = f.text(H_GROUP, false);
        entry.locked = f.flag(H_LOCKED);
        entry.source = f.number(H_SOURCE, Entry.SOURCE_MANUAL, Entry.SOURCE_IMPORT, false);
        entry.favorite = f.flag(H_FAVORITE);
        entry.counter = f.long(H_COUNTER);
        entry.created = f.long(H_CREATED);
        entry.namesEncrypted = f.flag(H_NAMES_ENCRYPTED);
        entry.fingerprint = f.bytes(H_FINGERPRINT);
        if (!f.ok || !Entry.isValidId(entry.id) || entry.counter < 0) {
            return null;
        }
        return entry;
    }

    // The full entry, or null when the record is malformed, sealed with other
    // keys, stored under another ID, or changed in any way. The decrypted
    // TLV is wiped; the caller must call entry.wipeSecrets() when done.
    function open(record as ByteArray, id as String, keys as SealedBox.Keys) as Entry? {
        return openWith(record, id, keys, null);
    }

    // As open(), but the decrypted TLV goes to `wiper` when given.
    function openWith(record as ByteArray, id as String, keys as SealedBox.Keys, wiper as Jobs.Wiper?) as Entry? {
        var entry = decodeHeader(record);
        var end = headerEnd(record);
        if (entry == null || end == null || !entry.id.equals(id)) {
            return null;
        }
        var leftovers = wiper != null ? [] as Array<ByteArray> : null;
        var plain = SealedBox.openKeep(keys, aad(id, record.slice(0, end)), record.slice(end, record.size()), leftovers);
        if (wiper != null) {
            wiper.addAll(leftovers as Array<ByteArray>);
        }
        if (plain == null) {
            return null;
        }
        var map = Codec.decode(plain);
        if (wiper != null) {
            wiper.add(plain);
        } else {
            Bytes.wipe(plain);
        }
        if (map == null) {
            return null;
        }
        var f = new Fields(map);
        if (entry.kind == Entry.KIND_OTP) {
            entry.algorithm = f.number(S_ALGORITHM, Hashes.SHA1, Hashes.SHA512, true);
            entry.digits = f.number(S_DIGITS, 0, 255, true);
            entry.period = f.number(S_PERIOD, 0, 65535, true);
            entry.secret = f.bytes(S_SECRET);
        } else {
            entry.payload = f.bytes(S_PAYLOAD);
            entry.options = f.number(S_OPTIONS, 0, 0x7FFFFFFF, true);
        }
        if (entry.namesEncrypted) {
            entry.name = f.text(S_NAME, false);
            entry.account = f.text(S_ACCOUNT, false);
            entry.group = f.text(S_GROUP, false);
        }
        if (!f.ok || entry.validate() != null) {
            entry.wipeSecrets();
            return null;
        }
        return entry;
    }

    // Header TLV, in tag order. Names are left out when they are encrypted.
    function encodeHeader(entry as Entry) as ByteArray {
        var w = new Codec.Writer();
        w.addText(H_ID, entry.id);
        w.addInt(H_KIND, entry.kind);
        w.addInt(H_TYPE, entry.type);
        if (!entry.namesEncrypted) {
            w.addText(H_NAME, entry.name);
            w.addText(H_ACCOUNT, entry.account);
            w.addText(H_GROUP, entry.group);
        }
        w.addBool(H_LOCKED, entry.locked);
        w.addInt(H_SOURCE, entry.source);
        w.addBool(H_FAVORITE, entry.favorite);
        w.addInt(H_COUNTER, entry.counter);
        w.addInt(H_CREATED, entry.created);
        w.addBool(H_NAMES_ENCRYPTED, entry.namesEncrypted);
        var fingerprint = entry.fingerprint;
        if (fingerprint != null) {
            w.addBytes(H_FINGERPRINT, fingerprint);
        }
        return w.bytes;
    }

    // Sensitive TLV, in tag order. The caller wipes the result.
    function encodeSecret(entry as Entry) as ByteArray {
        var w = new Codec.Writer();
        if (entry.kind == Entry.KIND_OTP) {
            w.addInt(S_ALGORITHM, entry.algorithm);
            w.addInt(S_DIGITS, entry.digits);
            w.addInt(S_PERIOD, entry.period);
            w.addBytes(S_SECRET, entry.secret as ByteArray);
        } else {
            w.addBytes(S_PAYLOAD, entry.payload as ByteArray);
            w.addInt(S_OPTIONS, entry.options);
        }
        if (entry.namesEncrypted) {
            w.addText(S_NAME, entry.name);
            w.addText(S_ACCOUNT, entry.account);
            w.addText(S_GROUP, entry.group);
        }
        return w.bytes;
    }

    // The authenticated data: the ID and every byte before the box.
    function aad(id as String, prefixAndHeader as ByteArray) as ByteArray {
        var out = Bytes.fromUtf8(id);
        out.addAll(prefixAndHeader);
        return out;
    }

    // Index just past the header, or null when the prefix is invalid.
    function headerEnd(record as ByteArray) as Number? {
        if (record.size() < PREFIX_BYTES + SealedBox.MIN_SIZE || record[0] != VERSION
                || (record[1] != KEY_DEVICE && record[1] != KEY_MASTER)) {
            return null;
        }
        var end = PREFIX_BYTES + ((record[2] << 8) | record[3]);
        if (end + SealedBox.MIN_SIZE > record.size()) {
            return null;
        }
        return end;
    }

    // Typed access to decoded TLV fields. A missing required field or a
    // field of the wrong type or range clears `ok` and returns a default,
    // so decoding reads straight through and checks `ok` once at the end.
    class Fields {
        var ok as Boolean = true;
        private var _map as Dictionary<Number, ByteArray or String or Long or Boolean>;

        function initialize(map as Dictionary<Number, ByteArray or String or Long or Boolean>) {
            _map = map;
        }

        function text(tag as Number, required as Boolean) as String {
            var v = _map[tag];
            if (v instanceof String) {
                return v;
            }
            if (v != null || required) {
                ok = false;
            }
            return "";
        }

        function number(tag as Number, min as Number, max as Number, required as Boolean) as Number {
            var v = _map[tag];
            if (v instanceof Long && v >= min && v <= max) {
                return v.toNumber();
            }
            if (v != null || required) {
                ok = false;
            }
            return min;
        }

        function long(tag as Number) as Long {
            var v = _map[tag];
            if (v instanceof Long) {
                return v;
            }
            if (v != null) {
                ok = false;
            }
            return 0l;
        }

        function flag(tag as Number) as Boolean {
            var v = _map[tag];
            if (v instanceof Boolean) {
                return v;
            }
            if (v != null) {
                ok = false;
            }
            return false;
        }

        function bytes(tag as Number) as ByteArray? {
            var v = _map[tag];
            if (v instanceof ByteArray) {
                return v;
            }
            if (v != null) {
                ok = false;
            }
            return null;
        }
    }
}