Update credential storage

README.md

@@ -634,14 +634,10 @@ This will be specific to your application.
 
 #### `storage_id`
 This is the output of `$credential->getStorageId()`.
-It MAY be combined as a primary key (e.g. having only an `id` field, and populating it with `->getStorageId()`).
+It MAY be used as a primary key (e.g. having only an `id` field, and populating it with `->getStorageId()`).
 The value will always be plain ASCII.
 
-This field SHOULD support text of at least 255 bytes (commonly `varchar(255)`).
-
-> [!NOTE]
-> The underlying WebAuthn spec makes no formal guarantee about the maximum length of a Credential's id.
-> This recommendation is based on observations and testing during library development.
+The raw value is [at most 1,023 bytes](https://www.w3.org/TR/webauthn-3/#credential-id), and is exported as Base64URL, so storage should support **at least `1,364` characters**.
 
 This field SHOULD have a `UNIQUE` index.
 If during storage the unique constraint is violated AND it's associated with a different user,
@@ -653,8 +649,9 @@ See https://www.w3.org/TR/webauthn-2/#sctn-registering-a-new-credential section
 This is the output of `Firehed\WebAuthn\Codecs\Credential::encode($credential)`.
 When retreived from the database for use during authentication, it should be unserialized with the complementing `->decode()` method on the same class.
 
-This field SHOULD support storing at least 2KiB, and it's RECOMMENDED to support storing at least 64KiB (commonly `TEXT` or `varchar(65535)`).
+This field SHOULD support storing at least 4KiB, and it's RECOMMENDED to support storing at least 64KiB (commonly `TEXT` or `varchar(65535)`).
 The value will always be plain ASCII.
+To reduce the stored size, you MAY pass `storeRegistrationData: false` to the codec's constructor; be aware that doing so will eliminate the ability to re-validate credentials in the future.
 
 This format IS COVERED by semantic versioning.
 

src/ArrayBufferResponseParser.php

@@ -81,6 +81,7 @@ public function parseCreateResponse(array $response): Responses\AttestationInter
         ));
 
         return new CreateResponse(
+            type: Enums\PublicKeyCredentialType::from($response['type']),
             id: BinaryString::fromBytes($response['rawId']),
             ao: new Attestations\AttestationObject(BinaryString::fromBytes($response['attestationObject'])),
             clientDataJson: BinaryString::fromBytes($response['clientDataJSON']),

src/Attestations/AttestationObjectInterface.php

@@ -16,5 +16,7 @@ interface AttestationObjectInterface
 {
     public function getAuthenticatorData(): AuthenticatorData;
 
+    public function getCbor(): BinaryString;
+
     public function verify(BinaryString $clientDataHash): VerificationResult;
 }

src/Codecs/Credential.php

@@ -4,10 +4,14 @@
 
 namespace Firehed\WebAuthn\Codecs;
 
+use Firehed\WebAuthn\Attestations\AttestationObject;
 use Firehed\WebAuthn\BinaryString;
 use Firehed\WebAuthn\COSEKey;
 use Firehed\WebAuthn\CredentialInterface;
 use Firehed\WebAuthn\CredentialV1;
+use Firehed\WebAuthn\CredentialV2;
+use Firehed\WebAuthn\Enums;
+use UnhandledMatchError;
 
 /**
  * This codec is responsible for serializing a CredentialInterface object to
@@ -37,6 +41,8 @@
  *
  * The format spec is for internal use only.
  *
+ * All integer formats are big-endian.
+ *
  * Format spec:
  *
  * A CredentialObj shall be encoded to a string.
@@ -45,10 +51,10 @@
  * [ version ] [ version-specific data ]
  *
  * version shall be a single byte.
- * The highest bit (big-endian) shall be 0.
- * A high bit of 1 is reserve for future use, and if encountered, an error
+ * The highest bit shall be 0.
+ * A high bit of 1 is reserved for future use, and if encountered, an error
  * should be thrown.
- * The lowest seven bits shall be interpreted as a big-endian7-bit integer.
+ * The lowest seven bits shall be interpreted as a 7-bit integer (i.e. 00-7F).
  *
  * The remainder of the string is a variable-length value that is specific to
  * the version.
@@ -57,19 +63,44 @@
  */
 class Credential
 {
+    private const TRANPSORT_FLAGS = [
+        0 => Enums\AuthenticatorTransport::Ble,
+        1 => Enums\AuthenticatorTransport::Hybrid,
+        2 => Enums\AuthenticatorTransport::Internal,
+        3 => Enums\AuthenticatorTransport::Nfc,
+        4 => Enums\AuthenticatorTransport::SmartCard,
+        5 => Enums\AuthenticatorTransport::Usb,
+    ];
+
+    private const PACK_UINT8 = 'C';
+    private const PACK_UINT16 = 'n';
+    private const PACK_UINT32 = 'N';
+
+    public function __construct(
+        private readonly bool $storeRegistrationData = true,
+    ) {
+    }
+
+    public function encode(CredentialInterface $credential): string
+    {
+        return match (true) {
+            $credential instanceof CredentialV1 => $this->encodeV1($credential),
+            default => $this->encodeV2($credential),
+        };
+    }
     /**
      * Version 1:
      *
      * [ id length ] [ id ] [ coseKeyLength ] [ coseKeyCbor ] [ signCount ]
      *
-     * id legnth is a big-endian unsigned short (16bit)
+     * id legnth is an unsigned short (16bit)
      * id is a string of variable length [id length]
-     * coseKeyLength is a big-endian unsigned long (32bit)
+     * coseKeyLength is an unsigned long (32bit)
      * coseKeyCbor is a string of variable legnth [coseKeyCbor]
-     * signCount is a big-endian unsigned long (32bit)
+     * signCount is an unsigned long (32bit)
      *
      */
-    public function encode(CredentialInterface $credential): string
+    private function encodeV1(CredentialInterface $credential): string
     {
         $version = 1;
 
@@ -78,21 +109,148 @@ public function encode(CredentialInterface $credential): string
 
         $versionSpecificFormat = sprintf(
             '%s%s%s%s%s',
-            pack('n', strlen($rawId)),
+            pack(self::PACK_UINT16, strlen($rawId)),
             $rawId,
-            pack('N', strlen($rawCbor)),
+            pack(self::PACK_UINT32, strlen($rawCbor)),
             $rawCbor,
-            pack('N', $credential->getSignCount()),
+            pack(self::PACK_UINT32, $credential->getSignCount()),
         );
 
         // append a checksum (crc32?) that import can validate?
         // e.g. assert(crc32(substr(data, 1, -4)) === substr(data, -4))
 
-        $binary = pack('C', $version) . $versionSpecificFormat;
+        $binary = pack(self::PACK_UINT8, $version) . $versionSpecificFormat;
 
         return base64_encode($binary);
     }
 
+    /**
+     * Version 2:
+     *
+     * [ flags ] [ idLength ] [ id ] [ signCount ] [ coseKeyLength ] [ coseKey
+     * ] [ transports ] [ attestationData ]
+     * Flags: 1 byte where bit 0 is the least significant bit
+     *   0: UV is initialized
+     *   1: Backup Eligible
+     *   2: Backup State
+     *   3: Transports included
+     *   4: Attestation Data included
+     *   5-7: RFU
+     *
+     * Transports: if [flags] has bit 3 set, the next byte tracks supported
+     * authenticator transports. If flags bit 3 is not set, the transports byte
+     * will be skipped.
+     *   0-5: see TRANSPORT_FLAGS
+     *   6: Reserved for Future Use (RFU1)
+     *   7: Reserved for Future Use (RFU2)
+     *
+     * Attestation Data: if [flags] has bit 4 set, a tuple follows:
+     * - aoLength (u32)
+     * - cdjLength (u32)
+     * - aoData - string of length `aoLength`
+     * - clientDataJSON - string of legnth `cdjLength`
+     *
+     * Note: this has CBOR and JSON inside of a packed format, which is a bit
+     * strange. A v3 of this codec may use a pure-CBOR representation which
+     * should be marginally more efficient.
+     *
+     * This capures all of the recommended Credential Record data as of
+     * WebAuthn Level 3 (except `type` which only has one value).
+     *
+     * @link https://www.w3.org/TR/webauthn-3/#credential-record
+     */
+    private function encodeV2(CredentialInterface $credential): string
+    {
+        // if ($credential->type !== Enums\PublicKeyCredentialType::PublicKey) {
+        // block this for now. May use flags bits to differentiate.
+        // }
+        $version = 2;
+
+        $flags = 0;
+        if ($credential->isUvInitialized()) {
+            $flags |= (1 << 0);
+        }
+        if ($credential->isBackupEligible()) {
+            $flags |= (1 << 1);
+        }
+        if ($credential->isBackedUp()) {
+            $flags |= (1 << 2);
+        }
+
+        $transportFlags = self::getTransportFlags($credential->getTransports());
+        if ($transportFlags !== 0) {
+            $flags |= (1 << 3);
+        }
+
+        $attestationData = $credential->getAttestationData();
+        if ($attestationData !== null && $this->storeRegistrationData) {
+            $flags |= (1 << 4);
+            [$ao, $aCDJ] = $attestationData;
+            $aoData = $ao->getCbor();
+            $aoLength = $aoData->getLength();
+            $cdjLenth = $aCDJ->getLength();
+
+            $attestation = sprintf(
+                '%s%s%s%s',
+                pack(self::PACK_UINT32, $aoLength),
+                pack(self::PACK_UINT32, $cdjLenth),
+                $aoData->unwrap(),
+                $aCDJ->unwrap(),
+            );
+        } else {
+            $attestation = '';
+        }
+
+        $rawId = $credential->getId()->unwrap();
+        $rawCbor = $credential->getCoseCbor()->unwrap();
+        $signCount = $credential->getSignCount();
+
+        assert($flags >= 0x00 && $flags <= 0xFF); // @phpstan-ignore-line
+        $versionSpecificFormat = sprintf(
+            '%s%s%s%s%s%s%s%s',
+            pack(self::PACK_UINT8, $flags),
+            pack(self::PACK_UINT16, strlen($rawId)),
+            $rawId,
+            pack(self::PACK_UINT32, $credential->getSignCount()),
+            pack(self::PACK_UINT32, strlen($rawCbor)),
+            $rawCbor,
+            $transportFlags > 0 ? pack(self::PACK_UINT8, $transportFlags) : '',
+            $attestation,
+        );
+
+        $binary = pack(self::PACK_UINT8, $version) . $versionSpecificFormat;
+
+        return base64_encode($binary);
+    }
+
+    /**
+     * @param Enums\AuthenticatorTransport[] $transports
+     */
+    private static function getTransportFlags(array $transports): int
+    {
+        $flags = 0;
+        foreach ($transports as $transport) {
+            $bit = array_search($transport, self::TRANPSORT_FLAGS, true);
+            $flags |= (1 << $bit);
+        }
+        return $flags;
+    }
+
+    /**
+     * @return Enums\AuthenticatorTransport[]
+     */
+    private static function parseTransportFlags(int $flags): array
+    {
+        $transports = [];
+        for ($bit = 0; $bit <= 5; $bit++) {
+            $value = 1 << $bit;
+            if (($flags & $value) === $value) {
+                $transports[] = self::TRANPSORT_FLAGS[$bit];
+            }
+        }
+        return $transports;
+    }
+
     public function decode(string $encoded): CredentialInterface
     {
         $binary = base64_decode($encoded, true);
@@ -102,9 +260,15 @@ public function decode(string $encoded): CredentialInterface
 
         $version = $bytes->readUint8();
         assert(($version & 0x80) === 0, 'High bit in version must not be set');
-        // match -> decodeV1 ?
-        assert($version === 1);
+        return match ($version) {
+            1 => $this->decodeV1($bytes),
+            2 => $this->decodeV2($bytes),
+            default => throw new UnhandledMatchError('Unsupported version'),
+        };
+    }
 
+    private function decodeV1(BinaryString $bytes): CredentialInterface
+    {
         $idLength = $bytes->readUint16();
         $id = $bytes->read($idLength);
 
@@ -114,9 +278,62 @@ public function decode(string $encoded): CredentialInterface
         $signCount = $bytes->readUint32();
 
         return new CredentialV1(
-            new BinaryString($id),
-            new COSEKey(new BinaryString($cbor)),
-            $signCount,
+            id: new BinaryString($id),
+            coseKey: new COSEKey(new BinaryString($cbor)),
+            signCount: $signCount,
+        );
+    }
+
+    private function decodeV2(BinaryString $bytes): CredentialInterface
+    {
+        $flags = $bytes->readUint8();
+
+        $idLength = $bytes->readUint16();
+        $id = $bytes->read($idLength);
+
+        $signCount = $bytes->readUint32();
+
+        $cborLength = $bytes->readUint32();
+        $cbor = $bytes->read($cborLength);
+
+        // 0x01: UV
+        $UV = ($flags & 0x01) === 0x01;
+        // 0x02: BE
+        $BE = ($flags & 0x02) === 0x02;
+        // 0x04: BS
+        $BS = ($flags & 0x04) === 0x04;
+
+        // 0x08: transports included
+        if (($flags & 0x08) === 0x08) {
+            $transportFlags = $bytes->readUint8();
+            $transports = self::parseTransportFlags($transportFlags);
+        } else {
+            $transports = [];
+        }
+
+        // 0x10: attData
+        $AT = ($flags & 0x10) === 0x10;
+        if ($AT) {
+            $aoLength = $bytes->readUint32();
+            $cdjLength = $bytes->readUint32();
+            $rawAo = $bytes->read($aoLength);
+            $cdj = new BinaryString($bytes->read($cdjLength));
+            $ao = new AttestationObject(new BinaryString($rawAo));
+            $attestation = [$ao, $cdj];
+        } else {
+            $attestation = null;
+        }
+
+        return new CredentialV2(
+            type: Enums\PublicKeyCredentialType::PublicKey,
+            id: new BinaryString($id),
+            transports: $transports,
+            signCount: $signCount,
+            isUvInitialized: $UV,
+            isBackupEligible: $BE,
+            isBackedUp: $BS,
+            coseKey: new COSEKey(new BinaryString($cbor)),
+            attestation: $attestation,
         );
     }
 }

src/CreateResponse.php

@@ -22,6 +22,7 @@ class CreateResponse implements Responses\AttestationInterface
      * @param Enums\AuthenticatorTransport[] $transports
      */
     public function __construct(
+        private Enums\PublicKeyCredentialType $type,
         private BinaryString $id,
         private Attestations\AttestationObjectInterface $ao,
         private BinaryString $clientDataJson,
@@ -158,13 +159,19 @@ public function verify(
         // (done in client code?)
 
         // 7.1.27
-        // associate credential with new user
-        // done in client code
+        // Create and store credential and associate with user. Storage to be
+        // done in consuming code.
         $data = $authData->getAttestedCredentialData();
-        $credential = new CredentialV1(
-            id: $this->id,
+        $credential = new CredentialV2(
+            type: $this->type,
+            id: $this->id, // data->id?
             signCount: $authData->getSignCount(),
             coseKey: $data->coseKey,
+            isUvInitialized: $authData->isUserVerified(),
+            transports: $this->transports,
+            isBackupEligible: $authData->isBackupEligible(),
+            isBackedUp: $authData->isBackedUp(),
+            attestation: [$this->ao, $this->clientDataJson],
         );
 
         // This is not part of the official procedure, but serves as a general