@clerk/expo-biometrics 0.0.1

package/ios/Tests/BiometricCredentialContractTests.swift

@@ -0,0 +1,286 @@
+import CryptoKit
+import Foundation
+import Security
+import XCTest
+@testable import ClerkExpoBiometrics
+
+/// Mirrors clerk-ios `BiometricCredentialStorageContractTests` (contract version 1) with the same vectors and fixture.
+final class BiometricCredentialContractTests: XCTestCase {
+  private let fixtureLocalKeyId = "tdlk_0123456789abcdef0123456789abcdef"
+
+  // MARK: - Secure Enclave key
+
+  func testPrivateKeyQueryUsesContractApplicationTagWithoutAccessGroup() {
+    let query = BiometricKeyManager.privateKeyQuery(localKeyId: fixtureLocalKeyId)
+
+    XCTAssertEqual(query[kSecClass as String] as? String, kSecClassKey as String)
+    XCTAssertEqual(query[kSecAttrKeyClass as String] as? String, kSecAttrKeyClassPrivate as String)
+    XCTAssertEqual(query[kSecAttrKeyType as String] as? String, kSecAttrKeyTypeECSECPrimeRandom as String)
+    XCTAssertEqual(
+      query[kSecAttrApplicationTag as String] as? Data,
+      Data("dev.clerk.trusted_device.tdlk_0123456789abcdef0123456789abcdef".utf8)
+    )
+    XCTAssertNil(query[kSecAttrAccessGroup as String])
+    XCTAssertNil(query[kSecAttrLabel as String])
+    XCTAssertNil(query[kSecAttrApplicationLabel as String])
+    XCTAssertEqual(query.count, 4)
+  }
+
+  func testPrivateKeyAttributesMatchContract() throws {
+    let attributes = BiometricKeyManager.privateKeyAttributes(
+      localKeyId: fixtureLocalKeyId,
+      accessControl: try BiometricKeyManager.accessControl(policy: .biometryCurrentSet)
+    )
+
+    XCTAssertEqual(attributes[kSecAttrKeyType as String] as? String, kSecAttrKeyTypeECSECPrimeRandom as String)
+    XCTAssertEqual(attributes[kSecAttrKeySizeInBits as String] as? Int, 256)
+    XCTAssertEqual(attributes[kSecAttrTokenID as String] as? String, kSecAttrTokenIDSecureEnclave as String)
+    XCTAssertNil(attributes[kSecAttrAccessGroup as String])
+    XCTAssertEqual(attributes.count, 4)
+
+    let privateKeyAttributes = try XCTUnwrap(attributes[kSecPrivateKeyAttrs as String] as? [String: Any])
+    XCTAssertEqual(privateKeyAttributes[kSecAttrIsPermanent as String] as? Bool, true)
+    XCTAssertEqual(
+      privateKeyAttributes[kSecAttrApplicationTag as String] as? Data,
+      Data("dev.clerk.trusted_device.tdlk_0123456789abcdef0123456789abcdef".utf8)
+    )
+    XCTAssertNotNil(privateKeyAttributes[kSecAttrAccessControl as String])
+    XCTAssertNil(privateKeyAttributes[kSecAttrAccessGroup as String])
+    XCTAssertEqual(privateKeyAttributes.count, 3)
+  }
+
+  func testPolicyRawValuesAndAccessControlFlagsMatchContract() throws {
+    XCTAssertEqual(BiometricCredentialPolicy.biometryCurrentSet.rawValue, "biometry_current_set")
+    XCTAssertEqual(BiometricCredentialPolicy.biometryAny.rawValue, "biometry_any")
+    XCTAssertEqual(BiometricCredentialPolicy.biometryOrDevicePasscode.rawValue, "biometry_or_device_passcode")
+
+    XCTAssertEqual(BiometricKeyManager.accessControlFlags(for: .biometryCurrentSet), [.privateKeyUsage, .biometryCurrentSet])
+    XCTAssertEqual(BiometricKeyManager.accessControlFlags(for: .biometryAny), [.privateKeyUsage, .biometryAny])
+    XCTAssertEqual(BiometricKeyManager.accessControlFlags(for: .biometryOrDevicePasscode), [.privateKeyUsage, .userPresence])
+
+    for policy in BiometricCredentialPolicy.allCases {
+      XCTAssertNoThrow(try BiometricKeyManager.accessControl(policy: policy))
+    }
+  }
+
+  func testLocalKeyIdFormat() {
+    let localKeyId = BiometricCredentialCoding.makeLocalKeyId()
+
+    XCTAssertTrue(localKeyId.hasPrefix("tdlk_"))
+    let suffix = localKeyId.dropFirst("tdlk_".count)
+    XCTAssertEqual(suffix.count, 32)
+    XCTAssertTrue(suffix.allSatisfy { "0123456789abcdef".contains($0) })
+    XCTAssertNotEqual(localKeyId, BiometricCredentialCoding.makeLocalKeyId())
+  }
+
+  // MARK: - Signing and public key
+
+  func testPublicKeyJWKMatchesContractFormat() throws {
+    var representation = Data([0x04])
+    representation.append(Data(repeating: 0x01, count: 32))
+    representation.append(Data(repeating: 0x02, count: 32))
+
+    XCTAssertEqual(
+      try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: representation),
+      #"{"kty":"EC","crv":"P-256","x":"AQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQE","y":"AgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgI","alg":"ES256"}"#
+    )
+  }
+
+  func testPublicKeyJWKRejectsCompressedOrShortKeys() {
+    XCTAssertThrowsError(try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: Data([0x02] + Array(repeating: 1, count: 32))))
+    XCTAssertThrowsError(try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: Data([0x05] + Array(repeating: 1, count: 64))))
+  }
+
+  func testSignatureIsRawRAndSEncodedAsUnpaddedBase64URL() throws {
+    let rComponent: [UInt8] = [0x00, 0x80] + Array(repeating: 0xAA, count: 31)
+    let sComponent: [UInt8] = Array(repeating: 0x11, count: 31)
+    let der = Data([0x30, 0x44, 0x02, UInt8(rComponent.count)] + rComponent + [0x02, UInt8(sComponent.count)] + sComponent)
+
+    let raw = try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: der)
+
+    XCTAssertEqual(raw.count, 64)
+    XCTAssertEqual(
+      BiometricCredentialCoding.base64URLEncodedString(raw),
+      "gKqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqoAEREREREREREREREREREREREREREREREREREREREREQ"
+    )
+  }
+
+  func testRawSignatureRejectsMalformedDER() {
+    let valid: [UInt8] = [0x30, 0x06, 0x02, 0x01, 0x01, 0x02, 0x01, 0x02]
+    XCTAssertNoThrow(try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: Data(valid)))
+
+    let malformed: [[UInt8]] = [
+      [],
+      [0x31] + valid.dropFirst(),
+      [0x30, 0x07] + valid.dropFirst(2),
+      valid + [0x00],
+      [0x30, 0x06, 0x02, 0x01, 0x81, 0x02, 0x01, 0x02],
+      [0x30, 0x06, 0x02, 0x00, 0x02, 0x02, 0x01, 0x02],
+      [0x30, 0x25, 0x02, 0x21, 0x01] + Array(repeating: 0x01, count: 32) + [0x02, 0x01, 0x02],
+    ]
+    for bytes in malformed {
+      XCTAssertThrowsError(try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: Data(bytes)), "\(bytes)") { error in
+        XCTAssertEqual((error as? BiometricsError)?.code, .signingFailed)
+      }
+    }
+  }
+
+  func testSecuritySignatureConvertsToVerifiableRawSignature() throws {
+    var error: Unmanaged<CFError>?
+    let attributes: [String: Any] = [
+      kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+      kSecAttrKeySizeInBits as String: 256,
+    ]
+    let privateKey = try XCTUnwrap(SecKeyCreateRandomKey(attributes as CFDictionary, &error))
+    let publicKey = try XCTUnwrap(SecKeyCopyPublicKey(privateKey))
+    let publicKeyData = try XCTUnwrap(SecKeyCopyExternalRepresentation(publicKey, &error) as Data?)
+    let clientData = #"{"challenge":"abc","nonce":"é"}"#
+
+    for _ in 0 ..< 32 {
+      let der = try XCTUnwrap(SecKeyCreateSignature(
+        privateKey,
+        .ecdsaSignatureMessageX962SHA256,
+        Data(clientData.utf8) as CFData,
+        &error
+      ) as Data?)
+      let raw = try BiometricCredentialCoding.rawES256Signature(fromDEREncoded: der)
+
+      XCTAssertEqual(raw.count, 64)
+      let signature = try P256.Signing.ECDSASignature(rawRepresentation: raw)
+      let verifyingKey = try P256.Signing.PublicKey(x963Representation: publicKeyData)
+      XCTAssertTrue(verifyingKey.isValidSignature(signature, for: Data(clientData.utf8)))
+    }
+
+    let jwk = try BiometricCredentialCoding.publicKeyJWK(fromX963Representation: publicKeyData)
+    let decoded = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(jwk.utf8)) as? [String: String])
+    XCTAssertEqual(decoded["x"], BiometricCredentialCoding.base64URLEncodedString(publicKeyData[1 ..< 33]))
+    XCTAssertEqual(decoded["y"], BiometricCredentialCoding.base64URLEncodedString(publicKeyData[33 ..< 65]))
+    XCTAssertFalse(jwk.contains("="))
+  }
+
+  // MARK: - Metadata Keychain item
+
+  func testMetadataItemQueryMatchesContract() {
+    let query = KeychainMetadataStorage(service: "com.clerk.example").baseQuery()
+
+    XCTAssertEqual(query[kSecClass as String] as? String, kSecClassGenericPassword as String)
+    XCTAssertEqual(query[kSecAttrService as String] as? String, "com.clerk.example")
+    XCTAssertEqual(query[kSecAttrAccount as String] as? String, "trustedDeviceCredentials")
+    XCTAssertNil(query[kSecAttrAccessGroup as String])
+    XCTAssertEqual(query.count, 3)
+  }
+
+  func testMetadataServicePrefersNonEmptyClerkKeychainService() {
+    XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: "com.example.shared", bundleIdentifier: "com.example.app"), "com.example.shared")
+    XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: "", bundleIdentifier: "com.example.app"), "com.example.app")
+    XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: nil, bundleIdentifier: "com.example.app"), "com.example.app")
+    XCTAssertEqual(BiometricCredentialCoding.metadataService(infoDictionaryService: nil, bundleIdentifier: nil), "")
+  }
+
+  func testV1FixtureDecodesToExpectedRecords() throws {
+    let records = try BiometricCredentialRecordList.decode(Self.fixtureData())
+
+    XCTAssertEqual(records.compactMap(BiometricCredentialRecord.init(jsonObject:)), Self.fixtureRecords)
+  }
+
+  func testExpectedRecordsEncodeToV1Fixture() throws {
+    var records: [[String: Any]] = []
+    for record in Self.fixtureRecords {
+      records = BiometricCredentialRecordList.saving(record, into: records).records
+    }
+
+    let stored = try XCTUnwrap(BiometricCredentialRecordList.encode(records))
+    let storedJSON = try JSONSerialization.jsonObject(with: stored) as? NSArray
+    let fixtureJSON = try JSONSerialization.jsonObject(with: Self.fixtureData()) as? NSArray
+    XCTAssertNotNil(storedJSON)
+    XCTAssertEqual(storedJSON, fixtureJSON)
+  }
+
+  func testRecordFieldNamesAndIntegerMilliseconds() throws {
+    let data = try XCTUnwrap(BiometricCredentialRecordList.encode(Self.fixtureRecords.prefix(2).map(\.jsonObject)))
+    let records = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [[String: Any]])
+
+    XCTAssertEqual(Set(records[0].keys), ["id", "localKeyId", "userId", "appIdentifier", "identifierHint", "policy", "createdAt", "updatedAt"])
+    XCTAssertEqual(Set(records[1].keys), ["id", "localKeyId", "userId", "appIdentifier", "policy", "createdAt", "updatedAt"])
+    XCTAssertEqual((records[0]["createdAt"] as? NSNumber)?.int64Value, 1_714_000_000_500)
+    XCTAssertTrue(String(decoding: data, as: UTF8.self).contains(#""createdAt":1714000000500"#))
+  }
+
+  func testReadersIgnoreUnknownFieldsAndNormalizeIdentifierHints() throws {
+    let json = """
+    [{"id":"tdc_future","localKeyId":"tdlk_future","userId":"user_1","appIdentifier":"com.clerk.example",\
+    "identifierHint":"  User@Example.COM ","policy":"biometry_any","createdAt":1714000000000.25,\
+    "updatedAt":1714000000000,"futureField":{"nested":true}}]
+    """
+    let listed = BiometricCredentialRecordList.listable(try BiometricCredentialRecordList.decode(Data(json.utf8)))
+
+    XCTAssertEqual(listed.count, 1)
+    XCTAssertEqual(listed[0]["identifierHint"] as? String, "user@example.com")
+    XCTAssertEqual(listed[0]["futureField"] as? [String: Bool], ["nested": true])
+    XCTAssertEqual((listed[0]["createdAt"] as? NSNumber)?.doubleValue, 1_714_000_000_000.25)
+  }
+
+  func testIdentifierHintHashMatchesAndroidContractVector() {
+    XCTAssertEqual(
+      BiometricCredentialCoding.identifierHintSHA256("  User@Example.COM\n"),
+      "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514"
+    )
+    XCTAssertNil(BiometricCredentialCoding.identifierHintSHA256(" \n\t"))
+    XCTAssertNil(BiometricCredentialCoding.identifierHintSHA256(nil))
+  }
+
+  func testInstallationMarkerKeyMatchesContractFormat() {
+    XCTAssertEqual(
+      BiometricCredentialCoding.installationMarkerKey(service: "com.clerk.example", accessGroup: nil, appIdentifier: "com.clerk.example"),
+      "com.clerk.trusted-device-installation-marker.s17:com.clerk.example.n.s17:com.clerk.example"
+    )
+    XCTAssertEqual(
+      BiometricCredentialCoding.installationMarkerKey(service: "com.clerk.é", accessGroup: "TEAMID.com.clerk.shared", appIdentifier: "com.clerk.example"),
+      "com.clerk.trusted-device-installation-marker.s12:com.clerk.é.s23:TEAMID.com.clerk.shared.s17:com.clerk.example"
+    )
+    XCTAssertEqual(
+      BiometricCredentialCoding.installationMarkerKey(service: "com.clerk.example", accessGroup: "", appIdentifier: "com.clerk.example"),
+      "com.clerk.trusted-device-installation-marker.s17:com.clerk.example.s0:.s17:com.clerk.example"
+    )
+  }
+
+  static let fixtureRecords: [BiometricCredentialRecord] = [
+    BiometricCredentialRecord(
+      id: "tdc_contract_current_set",
+      localKeyId: "tdlk_0123456789abcdef0123456789abcdef",
+      userId: "user_contract_1",
+      appIdentifier: "com.clerk.example",
+      identifierHint: "user@example.com",
+      policy: .biometryCurrentSet,
+      createdAt: 1_714_000_000_500,
+      updatedAt: 1_714_000_001_500
+    ),
+    BiometricCredentialRecord(
+      id: "tdc_contract_any",
+      localKeyId: "tdlk_fedcba9876543210fedcba9876543210",
+      userId: "user_contract_2",
+      appIdentifier: "com.clerk.example",
+      identifierHint: nil,
+      policy: .biometryAny,
+      createdAt: 1_714_000_002_000,
+      updatedAt: 1_714_000_003_000
+    ),
+    BiometricCredentialRecord(
+      id: "tdc_contract_passcode",
+      localKeyId: "tdlk_00000000000000000000000000000000",
+      userId: "user_contract_1",
+      appIdentifier: "com.clerk.other",
+      identifierHint: "+15555550100",
+      policy: .biometryOrDevicePasscode,
+      createdAt: 1_714_000_004_000,
+      updatedAt: 1_714_000_004_000
+    ),
+  ]
+
+  static func fixtureData() throws -> Data {
+    let url = try XCTUnwrap(
+      Bundle(for: BiometricCredentialContractTests.self).url(forResource: "BiometricCredentialStorageContractV1", withExtension: "json")
+    )
+    return try Data(contentsOf: url)
+  }
+}

package/ios/Tests/BiometricCredentialStoreTests.swift

@@ -0,0 +1,323 @@
+import Foundation
+import Security
+import XCTest
+@testable import ClerkExpoBiometrics
+
+final class BiometricCredentialStoreTests: XCTestCase {
+  private final class InMemoryStorage: BiometricCredentialMetadataStorage {
+    var data: Data?
+    var writes = 0
+    var deletes = 0
+
+    func read() throws -> Data? { data }
+    func write(_ data: Data) throws {
+      writes += 1
+      self.data = data
+    }
+
+    func delete() throws {
+      deletes += 1
+      data = nil
+    }
+
+    func records() throws -> [[String: Any]] {
+      try BiometricCredentialRecordList.decode(data)
+    }
+
+    func ids() throws -> [String?] {
+      try records().map { $0["id"] as? String }
+    }
+  }
+
+  private var storage: InMemoryStorage!
+  private var userDefaults: UserDefaults!
+  private var suiteName: String!
+  private var deletedKeys: [String] = []
+  private var failingKeys: Set<String> = []
+
+  override func setUp() {
+    super.setUp()
+    storage = InMemoryStorage()
+    suiteName = "ClerkExpoBiometricsTests.\(UUID().uuidString)"
+    userDefaults = UserDefaults(suiteName: suiteName)
+    deletedKeys = []
+    failingKeys = []
+  }
+
+  override func tearDown() {
+    userDefaults.removePersistentDomain(forName: suiteName)
+    super.tearDown()
+  }
+
+  private func makeStore(appIdentifier: String? = "com.clerk.example") -> BiometricCredentialStore {
+    BiometricCredentialStore(
+      storage: storage,
+      deleteKey: { [unowned self] localKeyId in
+        if failingKeys.contains(localKeyId) {
+          throw BiometricsError(.storageFailed, "delete failed")
+        }
+        deletedKeys.append(localKeyId)
+      },
+      userDefaults: userDefaults,
+      service: "com.clerk.example",
+      appIdentifier: appIdentifier
+    )
+  }
+
+  private let markerKey = "com.clerk.trusted-device-installation-marker.s17:com.clerk.example.n.s17:com.clerk.example"
+
+  private func setMarker() {
+    userDefaults.set(true, forKey: markerKey)
+  }
+
+  private func record(
+    id: String,
+    localKeyId: String? = nil,
+    userId: String = "user_1",
+    appIdentifier: String = "com.clerk.example",
+    identifierHint: String? = nil
+  ) -> BiometricCredentialRecord {
+    BiometricCredentialRecord(
+      id: id,
+      localKeyId: localKeyId ?? "tdlk_\(id)",
+      userId: userId,
+      appIdentifier: appIdentifier,
+      identifierHint: identifierHint,
+      policy: .biometryCurrentSet,
+      createdAt: 1_714_000_000_000,
+      updatedAt: 1_714_000_000_000
+    )
+  }
+
+  // MARK: - Reinstall marker
+
+  func testMissingMarkerWipesOnlyThisAppsRecordsAndKeysThenSetsMarker() throws {
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+    let store = makeStore()
+
+    XCTAssertEqual(store.installationMarkerKey, markerKey)
+    XCTAssertTrue(try store.ensureInstallationMarker())
+
+    XCTAssertEqual(deletedKeys, ["tdlk_0123456789abcdef0123456789abcdef", "tdlk_fedcba9876543210fedcba9876543210"])
+    XCTAssertEqual(try storage.ids(), ["tdc_contract_passcode"])
+    XCTAssertEqual(userDefaults.object(forKey: markerKey) as? Bool, true)
+    XCTAssertEqual(UserDefaults.standard.object(forKey: markerKey) as? Bool, nil)
+  }
+
+  func testMarkerIsIdempotent() throws {
+    let store = makeStore()
+
+    XCTAssertTrue(try store.ensureInstallationMarker())
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+    XCTAssertFalse(try store.ensureInstallationMarker())
+
+    XCTAssertEqual(deletedKeys, [])
+    XCTAssertEqual(try storage.records().count, 3)
+  }
+
+  func testMarkerIsNotSetWhenAKeyCannotBeDeleted() throws {
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+    failingKeys = ["tdlk_fedcba9876543210fedcba9876543210"]
+    let store = makeStore()
+
+    XCTAssertThrowsError(try store.ensureInstallationMarker())
+
+    XCTAssertEqual(try storage.ids(), ["tdc_contract_any", "tdc_contract_passcode"])
+    XCTAssertNil(userDefaults.object(forKey: markerKey))
+
+    failingKeys = []
+    XCTAssertTrue(try store.ensureInstallationMarker())
+    XCTAssertEqual(try storage.ids(), ["tdc_contract_passcode"])
+  }
+
+  func testMarkerWipesMalformedRecordsForThisApp() throws {
+    storage.data = Data(#"[{"appIdentifier":"com.clerk.example","localKeyId":"tdlk_bad"},{"appIdentifier":"com.clerk.example"}]"#.utf8)
+
+    XCTAssertTrue(try makeStore().ensureInstallationMarker())
+
+    XCTAssertEqual(deletedKeys, ["tdlk_bad"])
+    XCTAssertNil(storage.data)
+    XCTAssertEqual(storage.deletes, 1)
+  }
+
+  func testMarkerIsNotSetWhenMetadataIsNotAnArray() {
+    storage.data = Data(#"{"id":"tdc_1"}"#.utf8)
+
+    XCTAssertThrowsError(try makeStore().ensureInstallationMarker()) { error in
+      XCTAssertEqual((error as? BiometricsError)?.code, .storageFailed)
+    }
+    XCTAssertNil(userDefaults.object(forKey: markerKey))
+  }
+
+  func testMissingAppIdentifierSkipsTheMarker() throws {
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+
+    XCTAssertFalse(try makeStore(appIdentifier: nil).ensureInstallationMarker())
+    XCTAssertEqual(try storage.records().count, 3)
+  }
+
+  func testStoreOperationsApplyTheMarkerFirst() throws {
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+    let store = makeStore()
+
+    let listed = try JSONSerialization.jsonObject(with: Data(store.listRecordsJSON().utf8)) as? [[String: Any]]
+
+    XCTAssertEqual(listed?.map { $0["id"] as? String }, ["tdc_contract_passcode"])
+    XCTAssertEqual(userDefaults.object(forKey: markerKey) as? Bool, true)
+  }
+
+  // MARK: - List
+
+  func testListReturnsWellFormedRecordsForEveryAppWithUnknownFields() throws {
+    setMarker()
+    storage.data = Data("""
+    [{"id":"tdc_1","localKeyId":"tdlk_1","userId":"user_1","appIdentifier":"com.clerk.example","identifierHint":" A@B.co ",\
+    "policy":"biometry_any","createdAt":1714000000000,"updatedAt":1714000000001,"futureField":[1,true,null]},\
+    {"id":"tdc_2","localKeyId":"tdlk_2","userId":"user_2","appIdentifier":"com.clerk.other","identifierHint":"  ",\
+    "policy":"biometry_current_set","createdAt":1714000000000,"updatedAt":1714000000000},\
+    {"id":"tdc_bad_policy","localKeyId":"tdlk_3","userId":"user_1","appIdentifier":"com.clerk.example",\
+    "policy":"face","createdAt":1,"updatedAt":1},\
+    {"id":"tdc_bool_date","localKeyId":"tdlk_4","userId":"user_1","appIdentifier":"com.clerk.example",\
+    "policy":"biometry_any","createdAt":true,"updatedAt":1},\
+    {"id":"tdc_missing","userId":"user_1","appIdentifier":"com.clerk.example","policy":"biometry_any","createdAt":1,"updatedAt":1},\
+    {"id":"tdc_hint_number","localKeyId":"tdlk_5","userId":"user_1","appIdentifier":"com.clerk.example",\
+    "identifierHint":5,"policy":"biometry_any","createdAt":1,"updatedAt":1},\
+    {"id":"tdc_null_hint","localKeyId":"tdlk_6","userId":"user_1","appIdentifier":"com.clerk.example",\
+    "identifierHint":null,"policy":"biometry_or_device_passcode","createdAt":1,"updatedAt":1}]
+    """.utf8)
+
+    let json = try makeStore().listRecordsJSON()
+    let listed = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [[String: Any]])
+
+    XCTAssertEqual(listed.map { $0["id"] as? String }, ["tdc_1", "tdc_2", "tdc_null_hint"])
+    XCTAssertEqual(listed[0]["identifierHint"] as? String, "a@b.co")
+    XCTAssertNil(listed[1]["identifierHint"])
+    XCTAssertNil(listed[2]["identifierHint"])
+    XCTAssertEqual(listed[0]["identifierHintSha256"] as? String, "80305c9bb1bb2480e03894350e0a8a366dcbdeb302e69e0817aa0743abd77054")
+    XCTAssertTrue(listed[1]["identifierHintSha256"] is NSNull)
+    XCTAssertTrue(listed[2]["identifierHintSha256"] is NSNull)
+    XCTAssertTrue(json.contains(#""futureField":[1,true,null]"#))
+    XCTAssertTrue(json.contains(#""updatedAt":1714000000001"#))
+  }
+
+  func testListIsEmptyWithoutAnItem() throws {
+    setMarker()
+    XCTAssertEqual(try makeStore().listRecordsJSON(), "[]")
+  }
+
+  // MARK: - Save
+
+  func testSaveAddsRecordAndPreservesOtherAppsAndUnknownFields() throws {
+    setMarker()
+    storage.data = Data("""
+    [{"id":"tdc_other","localKeyId":"tdlk_other","userId":"user_1","appIdentifier":"com.clerk.other",\
+    "policy":"biometry_any","createdAt":1714000000000,"updatedAt":1714000000000,"futureField":"kept"},\
+    {"id":"tdc_same","localKeyId":"tdlk_same","userId":"user_2","appIdentifier":"com.clerk.example",\
+    "policy":"biometry_any","createdAt":1714000000000,"updatedAt":1714000000000,"futureField":"also kept"}]
+    """.utf8)
+
+    try makeStore().save(record(id: "tdc_new", identifierHint: " New@Example.com"), removeOtherRecordsForApp: false)
+
+    let records = try storage.records()
+    XCTAssertEqual(records.map { $0["id"] as? String }, ["tdc_other", "tdc_same", "tdc_new"])
+    XCTAssertEqual(records[0]["futureField"] as? String, "kept")
+    XCTAssertEqual(records[1]["futureField"] as? String, "also kept")
+    XCTAssertEqual(records[2]["identifierHint"] as? String, "new@example.com")
+    XCTAssertEqual(deletedKeys, [])
+  }
+
+  func testSaveReplacesSameIdAndDeletesItsOldKey() throws {
+    setMarker()
+    let store = makeStore()
+    try store.save(record(id: "tdc_1", localKeyId: "tdlk_old"), removeOtherRecordsForApp: false)
+
+    try store.save(record(id: "tdc_1", localKeyId: "tdlk_new"), removeOtherRecordsForApp: false)
+
+    let records = try storage.records()
+    XCTAssertEqual(records.count, 1)
+    XCTAssertEqual(records[0]["localKeyId"] as? String, "tdlk_new")
+    XCTAssertEqual(deletedKeys, ["tdlk_old"])
+  }
+
+  func testSaveDropsMalformedRecordsForTheSameAppOnly() throws {
+    setMarker()
+    storage.data = Data("""
+    [{"id":"tdc_bad","appIdentifier":"com.clerk.example"},{"id":"tdc_bad_other","appIdentifier":"com.clerk.other"}]
+    """.utf8)
+
+    try makeStore().save(record(id: "tdc_1"), removeOtherRecordsForApp: false)
+
+    XCTAssertEqual(try storage.ids(), ["tdc_bad_other", "tdc_1"])
+    XCTAssertEqual(deletedKeys, [])
+  }
+
+  func testSaveRemovingOtherRecordsDeletesThisAppsOtherRecordsAndKeys() throws {
+    setMarker()
+    let store = makeStore()
+    try store.save(record(id: "tdc_a", userId: "user_1"), removeOtherRecordsForApp: false)
+    try store.save(record(id: "tdc_b", userId: "user_2"), removeOtherRecordsForApp: false)
+    try store.save(record(id: "tdc_other_app", appIdentifier: "com.clerk.other"), removeOtherRecordsForApp: false)
+    failingKeys = ["tdlk_tdc_b"]
+
+    try store.save(record(id: "tdc_new"), removeOtherRecordsForApp: true)
+
+    XCTAssertEqual(deletedKeys, ["tdlk_tdc_a"])
+    XCTAssertEqual(try storage.ids(), ["tdc_b", "tdc_other_app", "tdc_new"])
+  }
+
+  func testSaveAppliesTheMarkerBeforeWriting() throws {
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+
+    try makeStore().save(record(id: "tdc_new"), removeOtherRecordsForApp: false)
+
+    XCTAssertEqual(try storage.ids(), ["tdc_contract_passcode", "tdc_new"])
+    XCTAssertEqual(userDefaults.object(forKey: markerKey) as? Bool, true)
+  }
+
+  func testSaveFailsWithoutWritingWhenTheMarkerCannotBeSet() throws {
+    storage.data = try BiometricCredentialContractTests.fixtureData()
+    failingKeys = ["tdlk_0123456789abcdef0123456789abcdef"]
+
+    XCTAssertThrowsError(try makeStore().save(record(id: "tdc_new"), removeOtherRecordsForApp: false))
+
+    XCTAssertFalse(try storage.ids().contains("tdc_new"))
+  }
+
+  // MARK: - Delete
+
+  func testDeleteRecordsDeletesKeyThenRecordsAndDropsTheItemWhenEmpty() throws {
+    setMarker()
+    let store = makeStore()
+    try store.save(record(id: "tdc_1", localKeyId: "tdlk_1"), removeOtherRecordsForApp: false)
+
+    try store.deleteRecords(localKeyId: "tdlk_1")
+
+    XCTAssertEqual(deletedKeys, ["tdlk_1"])
+    XCTAssertNil(storage.data)
+    XCTAssertEqual(storage.deletes, 1)
+  }
+
+  func testDeleteRecordsKeepsRecordsWhenTheKeyCannotBeDeleted() throws {
+    setMarker()
+    let store = makeStore()
+    try store.save(record(id: "tdc_1", localKeyId: "tdlk_1"), removeOtherRecordsForApp: false)
+    failingKeys = ["tdlk_1"]
+
+    XCTAssertThrowsError(try store.deleteRecords(localKeyId: "tdlk_1"))
+
+    XCTAssertEqual(try storage.ids(), ["tdc_1"])
+  }
+
+  func testDeleteRecordsPreservesUnknownFieldsOnOtherRecords() throws {
+    setMarker()
+    storage.data = Data("""
+    [{"id":"tdc_1","localKeyId":"tdlk_1","futureField":"kept"},{"id":"tdc_2","localKeyId":"tdlk_2"}]
+    """.utf8)
+
+    try makeStore().deleteRecords(localKeyId: "tdlk_2")
+
+    let records = try storage.records()
+    XCTAssertEqual(records.count, 1)
+    XCTAssertEqual(records[0]["futureField"] as? String, "kept")
+  }
+}