feat(cat-voices): expose collaborators in metadata (#3750)

* Add collaborators to DocumentDataMetadata and add mapper

* update DTO

* fix: failing tests

* fix: spelling

Author: damian-molinski

catalyst_voices/packages/internal/catalyst_voices_models/lib/src/document/data/document_data_metadata.dart

@@ -27,10 +27,16 @@ final class DocumentDataMetadata extends Equatable {
   /// A reference to a section of a document.
   final String? section;
 
+  /// A list of allowed Collaborators on the next subsequent version of a document.
+  final List<CatalystId>? collaborators;
+
   /// A list of referenced parameters like brand, category or campaign.
   final DocumentParameters parameters;
 
-  /// List of authors represented by CatalystId
+  /// List of authors represented by CatalystId.
+  ///
+  /// Note. This list just represents who signed this version
+  /// Note. Can change from version to version when [collaborators] are non empty.
   final List<CatalystId>? authors;
 
   /// The default constructor for the [DocumentDataMetadata].
@@ -42,6 +48,7 @@ final class DocumentDataMetadata extends Equatable {
     this.template,
     this.reply,
     this.section,
+    this.collaborators,
     this.parameters = const DocumentParameters(),
     this.authors,
   }) : assert(
@@ -80,6 +87,7 @@ final class DocumentDataMetadata extends Equatable {
     required SignedDocumentRef template,
     required DocumentParameters parameters,
     required List<CatalystId> authors,
+    List<CatalystId>? collaborators,
   }) {
     return DocumentDataMetadata(
       type: DocumentType.proposalDocument,
@@ -88,6 +96,7 @@ final class DocumentDataMetadata extends Equatable {
       template: template,
       parameters: parameters,
       authors: authors,
+      collaborators: collaborators,
     );
   }
 
@@ -134,10 +143,14 @@ final class DocumentDataMetadata extends Equatable {
     template,
     reply,
     section,
+    collaborators,
     parameters,
     authors,
   ];
 
+  /// Who signed this document version. Can change from version to version.
+  List<CatalystId>? get signers => authors;
+
   String get version => selfRef.version!;
 
   DocumentDataMetadata copyWith({
@@ -148,6 +161,7 @@ final class DocumentDataMetadata extends Equatable {
     Optional<SignedDocumentRef>? template,
     Optional<SignedDocumentRef>? reply,
     Optional<String>? section,
+    Optional<List<CatalystId>>? collaborators,
     DocumentParameters? parameters,
     Optional<List<CatalystId>>? authors,
   }) {
@@ -159,6 +173,7 @@ final class DocumentDataMetadata extends Equatable {
       template: template.dataOr(this.template),
       reply: reply.dataOr(this.reply),
       section: section.dataOr(this.section),
+      collaborators: collaborators.dataOr(this.collaborators),
       parameters: parameters ?? this.parameters,
       authors: authors.dataOr(this.authors),
     );

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/dto/document/document_data_dto.dart

@@ -92,6 +92,7 @@ final class DocumentDataMetadataDto {
   final DocumentRefDto? template;
   final DocumentRefDto? reply;
   final String? section;
+  final List<String>? collaborators;
   final List<DocumentRefDto> parameters;
   final List<String>? authors;
 
@@ -103,6 +104,7 @@ final class DocumentDataMetadataDto {
     this.template,
     this.reply,
     this.section,
+    this.collaborators,
     this.parameters = const [],
     this.authors,
   });
@@ -125,6 +127,7 @@ final class DocumentDataMetadataDto {
         template: data.template?.toDto(),
         reply: data.reply?.toDto(),
         section: data.section,
+        collaborators: data.collaborators?.map((e) => e.toString()).toList(),
         parameters: data.parameters.set.map((e) => e.toDto()).toList(),
         authors: data.authors?.map((e) => e.toString()).toList(),
       );
@@ -140,6 +143,7 @@ final class DocumentDataMetadataDto {
       template: template?.toModel().toSignedDocumentRef(),
       reply: reply?.toModel().toSignedDocumentRef(),
       section: section,
+      collaborators: collaborators?.map((e) => CatalystId.fromUri(e.getUri())).toList(),
       parameters: DocumentParameters(
         parameters.map((e) => e.toModel().toSignedDocumentRef()).toSet(),
       ),

catalyst_voices/packages/internal/catalyst_voices_repositories/lib/src/signed_document/signed_document_manager_impl.dart

@@ -1,11 +1,10 @@
-import 'dart:convert';
 import 'dart:typed_data';
 
 import 'package:catalyst_compression/catalyst_compression.dart';
 import 'package:catalyst_cose/catalyst_cose.dart';
 import 'package:catalyst_voices_models/catalyst_voices_models.dart';
-import 'package:catalyst_voices_repositories/src/document/exception/document_exception.dart';
 import 'package:catalyst_voices_repositories/src/signed_document/signed_document_manager.dart';
+import 'package:catalyst_voices_repositories/src/signed_document/signed_document_mapper.dart';
 import 'package:cbor/cbor.dart';
 import 'package:equatable/equatable.dart';
 
@@ -21,28 +20,10 @@ final class SignedDocumentManagerImpl implements SignedDocumentManager {
   @override
   Future<SignedDocument> parseDocument(Uint8List bytes) async {
     final coseSign = CoseSign.fromCbor(cbor.decode(bytes));
-    final signers = _CatalystIdListExt.fromCose(
-      coseSign.signatures.map((e) => e.protectedHeaders.kid).nonNulls.toList().cast(),
-    );
-
-    final metadata = _DocumentMetadataExt.fromCose(
-      protectedHeaders: coseSign.protectedHeaders,
-      unprotectedHeaders: coseSign.unprotectedHeaders,
-      signers: signers,
-    );
 
-    final payloadBytes = await _brotliDecompressPayload(coseSign);
-    final payload = SignedDocumentPayload.fromBytes(
-      payloadBytes,
-      contentType: metadata.contentType,
-    );
+    final rawPayload = await _decompressPayload(coseSign);
 
-    return _CoseSignedDocument(
-      coseSign: coseSign,
-      payload: payload,
-      metadata: metadata,
-      signers: signers,
-    );
+    return _CoseSignedDocument.fromCose(coseSign, rawPayload: rawPayload);
   }
 
   @override
@@ -52,11 +33,11 @@ final class SignedDocumentManagerImpl implements SignedDocumentManager {
     required CatalystId catalystId,
     required CatalystPrivateKey privateKey,
   }) async {
-    final compressedPayload = await _brotliCompressPayload(document.toBytes());
+    final compressedPayload = await _compressPayload(document.toBytes());
 
     final coseSign = await CoseSign.sign(
-      protectedHeaders: metadata.asCoseProtectedHeaders,
-      unprotectedHeaders: metadata.asCoseUnprotectedHeaders,
+      protectedHeaders: SignedDocumentMapper.buildCoseProtectedHeaders(metadata),
+      unprotectedHeaders: const CoseHeaders.unprotected(),
       payload: compressedPayload,
       signers: [_CatalystSigner(catalystId, privateKey)],
     );
@@ -69,12 +50,12 @@ final class SignedDocumentManagerImpl implements SignedDocumentManager {
     );
   }
 
-  Future<Uint8List> _brotliCompressPayload(Uint8List payload) async {
+  Future<Uint8List> _compressPayload(Uint8List payload) async {
     final compressed = await brotli.compress(payload);
     return Uint8List.fromList(compressed);
   }
 
-  Future<Uint8List> _brotliDecompressPayload(CoseSign coseSign) async {
+  Future<Uint8List> _decompressPayload(CoseSign coseSign) async {
     if (coseSign.protectedHeaders.contentEncoding == CoseHttpContentEncoding.brotli) {
       final decompressed = await brotli.decompress(coseSign.payload);
       return Uint8List.fromList(decompressed);
@@ -149,6 +130,34 @@ final class _CoseSignedDocument with EquatableMixin implements SignedDocument {
     required this.signers,
   }) : _coseSign = coseSign;
 
+  factory _CoseSignedDocument.fromCose(
+    CoseSign coseSign, {
+    required Uint8List rawPayload,
+  }) {
+    final signers = coseSign.signatures
+        .map((e) => e.protectedHeaders.kid)
+        .nonNulls
+        .cast<CatalystIdKid>()
+        .toList();
+
+    final metadata = SignedDocumentMapper.buildMetadata(
+      protectedHeaders: coseSign.protectedHeaders,
+      unprotectedHeaders: coseSign.unprotectedHeaders,
+      signers: signers,
+    );
+    final payload = SignedDocumentPayload.fromBytes(
+      rawPayload,
+      contentType: metadata.contentType,
+    );
+
+    return _CoseSignedDocument(
+      coseSign: coseSign,
+      payload: payload,
+      metadata: metadata,
+      signers: metadata.signers ?? [],
+    );
+  }
+
   @override
   List<Object?> get props => [_coseSign, payload, metadata, signers];
 
@@ -163,148 +172,3 @@ final class _CoseSignedDocument with EquatableMixin implements SignedDocument {
     return _coseSign.verify(verifier: _CatalystVerifier(catalystId));
   }
 }
-
-extension _CatalystIdExt on CatalystId {
-  static CatalystId? fromCose(CatalystIdKid kid) {
-    final string = utf8.decode(kid.bytes);
-    final uri = Uri.tryParse(string);
-    if (uri == null) return null;
-
-    return CatalystId.fromUri(uri);
-  }
-}
-
-extension _CatalystIdListExt on List<CatalystId> {
-  static List<CatalystId> fromCose(List<CatalystIdKid> list) {
-    return list.map(_CatalystIdExt.fromCose).nonNulls.toList();
-  }
-}
-
-extension _DocumentMetadataExt on DocumentDataMetadata {
-  CoseHeaders get asCoseProtectedHeaders {
-    final id = this.id;
-    final version = this.version;
-    final ref = this.ref;
-    final template = this.template;
-    final reply = this.reply;
-    final section = this.section;
-
-    return CoseHeaders.protected(
-      mediaType: contentType.asCose,
-      contentEncoding: CoseHttpContentEncoding.brotli,
-      type: CoseDocumentType(type.uuid.asUuidV4),
-      id: CoseDocumentId(id.asUuidV7),
-      ver: CoseDocumentVer(version.asUuidV7),
-      ref: ref == null ? null : [ref].asCose,
-      template: template == null ? null : [template].asCose,
-      reply: reply == null ? null : [reply].asCose,
-      section: section == null ? null : CoseSectionRef(CoseJsonPointer(section)),
-      parameters: parameters.set.toList().asCose,
-    );
-  }
-
-  CoseHeaders get asCoseUnprotectedHeaders {
-    return const CoseHeaders.unprotected();
-  }
-
-  static DocumentDataMetadata fromCose({
-    required CoseHeaders protectedHeaders,
-    required CoseHeaders unprotectedHeaders,
-    required List<CatalystId> signers,
-  }) {
-    final type = protectedHeaders.type?.value.format();
-    final id = protectedHeaders.id?.value?.format();
-    final ver = protectedHeaders.ver?.value?.format();
-    final ref = protectedHeaders.ref;
-    final template = protectedHeaders.template;
-    final reply = protectedHeaders.reply;
-    final parameters = protectedHeaders.parameters;
-
-    final malformedReasons = <String>[];
-    if (id == null) {
-      malformedReasons.add('id is missing');
-    }
-    if (ver == null) {
-      malformedReasons.add('version is missing');
-    }
-
-    if (malformedReasons.isNotEmpty) {
-      throw DocumentMetadataMalformedException(reasons: malformedReasons);
-    }
-
-    return DocumentDataMetadata(
-      contentType: _SignedDocumentContentTypeExt.fromCose(protectedHeaders.mediaType),
-      type: type == null ? DocumentType.unknown : DocumentType.fromJson(type),
-      selfRef: SignedDocumentRef(id: id!, version: ver),
-      ref: ref == null ? null : _DocumentRefsExt.fromCose(ref).firstOrNull,
-      template: template == null ? null : _DocumentRefsExt.fromCose(template).firstOrNull,
-      reply: reply == null ? null : _DocumentRefsExt.fromCose(reply).firstOrNull,
-      section: protectedHeaders.section?.value.text,
-      parameters: parameters == null
-          ? const DocumentParameters()
-          : DocumentParameters(_DocumentRefsExt.fromCose(parameters).toSet()),
-      authors: signers,
-    );
-  }
-}
-
-extension _DocumentRefExt on DocumentRef {
-  CoseDocumentRef get asCose => CoseDocumentRef.optional(
-    documentId: id.asUuidV7,
-    documentVer: (version ?? id).asUuidV7,
-    documentLocator: CoseDocumentLocator.fallback(),
-  );
-
-  static SignedDocumentRef fromCose(CoseDocumentRef cose) {
-    return SignedDocumentRef(
-      id: cose.documentId.format(),
-      version: cose.documentVer.format(),
-    );
-  }
-}
-
-extension _DocumentRefsExt on List<DocumentRef> {
-  CoseDocumentRefs get asCose => CoseDocumentRefs(map((e) => e.asCose).toList());
-
-  static List<SignedDocumentRef> fromCose(CoseDocumentRefs cose) {
-    return cose.refs.map(_DocumentRefExt.fromCose).toList();
-  }
-}
-
-extension _SignedDocumentContentTypeExt on DocumentContentType {
-  /// Maps the [DocumentContentType] into COSE representation.
-  CoseMediaType? get asCose {
-    switch (this) {
-      case DocumentContentType.json:
-        return CoseMediaType.json;
-      case DocumentContentType.unknown:
-        return null;
-    }
-  }
-
-  static DocumentContentType fromCose(CoseMediaType? mediaType) {
-    switch (mediaType) {
-      case CoseMediaType.json:
-        return DocumentContentType.json;
-      case CoseMediaType.cbor:
-      case CoseMediaType.cddl:
-      case CoseMediaType.schemaJson:
-      case CoseMediaType.css:
-      case CoseMediaType.cssHandlebars:
-      case CoseMediaType.html:
-      case CoseMediaType.htmlHandlebars:
-      case CoseMediaType.markdown:
-      case CoseMediaType.markdownHandlebars:
-      case CoseMediaType.plain:
-      case CoseMediaType.plainHandlebars:
-      case null:
-        return DocumentContentType.unknown;
-    }
-  }
-}
-
-extension _UuidExt on String {
-  CoseUuidV4 get asUuidV4 => CoseUuidV4.fromString(this);
-
-  CoseUuidV7 get asUuidV7 => CoseUuidV7.fromString(this);
-}