feat: RBAC Documentation Drafting (#332)

* chore: wip

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* Update 0005-flutter-app.md

* docs(docs): Use latest docs builders and fix concepts page

* docs(cips): Start drafting the CIPS for milestone 2

* docs(cips): More text for RBAC metadata draft

* docs(cips): WIP updates to draft cip for role registration

* docs(cips): define draft specification for a ULID cbor tag

* docs(cips): Further WIP edits to RBAC

* docs(cips): fix ulid spec binary encoding reference

* docs(cips): Add a tag to the epoch time.

* docs(cips): Add CBOR tag cip for ED25519-BIP32 Keys, Derivation paths and Signatures

* docs(cips): Properly define the field tags to use where known, and clean up Stake Address specification.

* docs(cips): Fix nonce so its reliable without needing blockchain data

* docs(cips): updates

* docs(docs): Add CDDL definition for POC x509 envelope metadata

* fix(vscode): update vscode extension recommendations

* docs(cips): rbac x509 envelope fix

* docs(cips): wip updates to high level docs

* docs(cips): Add overview of cardano transaction processign and data

* docs(cips): update cardano block to be complete for clarity

* docs(cips): fix layout engine

* docs(cips): wip cddl for envelope metadata

* docs(cips): Add cddl specs and diagrams for x509 rbac registration work

* docs(cips): Add full transaction/metadata relationship diagram

* refactor(cips): reorganize documentation ready for drafting descriptive prose about the formats and uses

* docs(cips): add cip draft for catalyst roles using the x509-rbac standard

* docs(cips): Add c509 cddl with restrictions and enhancements for plutus usage

* docs(cips): Metadata envelope specification draft complete

* Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/x509-role-registration-metadata/x509-roles.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/x509-envelope-metadata/x509-envelope.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* Update docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl

Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

* docs(cips): Fix time and algorithm comments

* build(frontend): Relax flutter/dart version requirements to last minor release

* docs(cips): wip

* fix(cips): rename draft x509 envelope CIP so its easier to identify

* docs(cips): WIP updates to x509 roles

* fix(cips): rename RBAC definition CIP draft so its easier to identify

* docs(cips): x509 certificate registration format fully defined

* docs(cips): Document the restricted plutus subset.

* docs(cips): Add document detailing how CIP-30 is used to sign the transaction

* fix(cips): remove trailing spaces

* fix(cips): Fix line lengths

* fix(cips): Correct spelling

* fix(cips): spelling

* fix(frontend): revert changes to flutter/dart versions

* fix(frontend): more flutter/dart version corrections

* fix(frontend): Revert flutter files to same as main branch

* fix(frontend): revert more flutter .yml files to those in main

* fix(cips): Fix links between files

* docs(cips): Add catalyst specific role registration documentation

* docs(spelling): fix spelling

---------

Co-authored-by: minikin <djminikin@gmail.com>
Co-authored-by: bkioshn <35752733+bkioshn@users.noreply.github.com>

.config/dictionaries/project.dic

@@ -25,6 +25,7 @@ cfbundle
 chromedriver
 chrono
 ciphertext
+CIPs
 COCOAPODS
 codegen
 codepoints
@@ -48,7 +49,6 @@ Edgedriver
 emurgo
 encryptor
 endfunction
-endfunction
 fetchval
 fmtchk
 fmtfix
@@ -86,6 +86,9 @@ lintfix
 localizable
 loguru
 mdlint
+metadatum
+metadatums
+metamap
 mgrybyk
 mithril
 mitigations
@@ -120,6 +123,8 @@ pubspec
 pytest
 rapidoc
 redoc
+Replayability
+repr
 reqwest
 rfwtxt
 ripgrep
@@ -140,6 +145,7 @@ slotno
 sqlfluff
 Stefano
 stevenj
+Subkey
 subosito
 SYSROOT
 tacho
@@ -156,13 +162,14 @@ Traceback
 TXNZD
 Typer
 unmanaged
-UTXO
 utxo
-Utxos
+UTXO
 utxos
+Utxos
 vite
 vitss
 vkey
+vkeywitness
 voteplan
 voteplans
 wallclock
@@ -176,6 +183,3 @@ xctest
 xctestrun
 xcworkspace
 yoroi
-cbor
-metamap
-repr

.vscode/extensions.json

@@ -15,6 +15,7 @@
         "rust-lang.rust-analyzer",
         "JScearcy.rust-doc-viewer",
         "serayuzgur.crates",
+        "anweiss.cddl-languageserver",
         "tintinweb.graphviz-interactive-preview",
         "terrastruct.d2"
     ]

cspell.json

@@ -175,5 +175,6 @@
         "web-components.min.js",
         "**/generated/**",
         "utilities/catalyst_voices_remote_widgets/example/**/**",
+        "**/*.svg"
     ]
 }

docs/src/architecture/08_concepts/.pages

@@ -0,0 +1 @@
+title: Concepts

docs/src/catalyst-standards/cbor_tags/ulid.md

@@ -0,0 +1,32 @@
+# ULIDs for CBOR
+
+This document specifies a tag for ULIDs in Concise Binary Object Representation (CBOR) [1].
+
+    Tag: 32780
+    Data item: byte string
+    Semantics: Binary ULID (https://github.com/ulid/spec/tree/master)
+    Point of contact: Steven Johnson <steven.johnson@iohk.io>
+    Description of semantics: 
+    https://github.com/input-output-hk/catalyst-voices/tree/main/docs/src/catalyst-standards/cbor_tags/ulid.md
+
+## Semantics
+
+Tag 32780 can be applied to a byte string (major type 2) to indicate that the byte string
+is a binary [ULID] as specified by the [ULID Binary Layout].
+
+## References
+
+<!-- markdownlint-disable max-one-sentence-per-line -->
+<!-- cspell: words Bormann -->
+[1] [C. Bormann, and P. Hoffman. "Concise Binary Object Representation (CBOR)". RFC 8949, October 2020.][RFC 8949]
+<!-- markdownlint-enable max-one-sentence-per-line -->
+
+[2] [Universally Unique Lexicographically Sortable Identifier][ULID]
+
+## Author
+
+Steven Johnson <steven.johnson@iohk.io>
+
+[RFC 8949]: https://datatracker.ietf.org/doc/html/rfc8949
+[ULID]: https://github.com/ulid/spec/blob/master/README.md
+[ULID Binary Layout]: https://github.com/ulid/spec/tree/master#binary-layout-and-byte-order

docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/c509-cert-plutus-restricted.cddl

@@ -0,0 +1,86 @@
+; This c509 Certificate format is based upon:
+; https://datatracker.ietf.org/doc/draft-ietf-cose-cbor-encoded-cert/09/
+; And is restricted/customized to better enable compatibility with Plutus scripts
+; that would consume them, without loosing necessary features of x509
+; Not all x509 features are supported and some fields have different semantics to improve
+; certificate size and ability to be processed by Plutus Scripts.
+
+; cspell: words reencoded, biguint 
+
+C509CertificatePlutusRestrictedSubset = [ TBSCertificate, issuerSignatureValue: ed25519Signature, ]
+
+; The elements of the following group are used in a CBOR Sequence:
+TBSCertificate = (
+	c509CertificateType: &c509CertificateTypeValues, ; Always 0
+	certificateSerialNumber: CertificateSerialNumber, ; Can be ignored/set to 0 or used as intended.
+	issuer: Name, ; This could be an on-chain reference to the issuer cert, what would be the best way?  Transaction hash/cert hash?
+	validityNotBefore: Time, ; c509 uses UTC
+	validityNotAfter: Time, ; c509 uses UTC
+	subject: Name, ; Reference to on-chain keys related to this certificate
+	subjectPublicKeyAlgorithm: AlgorithmIdentifier, ; Must be int(12) = Ed25519
+	subjectPublicKey: subjectPublicKey, ; Ed25519 public key
+	extensions: Extensions, ; No extensions are currently supported must be set to []
+	issuerSignatureAlgorithm: AlgorithmIdentifier, ; Must be int(12) = Ed25519
+)
+
+; 0 = Native CBOR Certificate type
+; 1 = reencoded-der-cert -  Not supported in this restricted version of the format.
+c509CertificateTypeValues = ( native-cbor: 0,
+	; reencoded-der: 1 ; Not supported in this restricted encoding format
+)
+
+CertificateSerialNumber = biguint
+
+Name = [ * RelativeDistinguishedName ]
+	/ text
+	/ bytes
+
+RelativeDistinguishedName = Attribute / [ 2* Attribute ]
+
+Attribute = (
+	( attributeType: int, attributeValue: text )
+	// ( attributeType: oid, attributeValue: bytes )
+	// ( attributeType: pen, attributeValue: bytes )
+	// CardanoPublicKey
+)
+
+subjectPublicKey = bytes .size (32..32); Ed25519 public key stored in bytes, adjust size of this if other key types are supported.  
+
+; This is a completely custom Attribute for the RelativeDistinguishedName which is only for use with Plutus scripts.
+; attributeType = The type of Cardano key we associate with this certificate.
+; proof = Does the transaction require proof that the key is owned by the transaction signer?
+; attributeValue = The Cardano public key hash of the attribute type
+
+CardanoPublicKey = ( attributeType: &cardanoKeyTypes proof: bool, attributeValue: bytes .size (28..28) )
+
+cardanoKeyTypes = (
+	paymentKeyHash: 0,
+	stakeKeyHash: 1,
+	drepVerificationKeyHash: 2,
+	ccColdVerificationKeyHash: 3,
+	ccHotVerificationKeyHash: 4,
+)
+
+; Plutus will need to convert the Unix epoch timestamp to the nearest slot number
+; validityNotBefore rounds up to the next Slot after that time.
+; validityNotAfter rounds down to the next Slot before that time.
+Time = ( ~time / null )
+
+ed25519Signature = bstr .size 64; Ed25519 signature must be tagged to identify their type.
+
+
+; Currently ONLY AlgorithmIdentifier int(12) - Ed25519 is supported.
+; oid and [ algorithm: oid, parameters: bytes ] are not supported by Plutus.
+AlgorithmIdentifier = (int
+	/ ~oid
+	/ [ algorithm: ~oid, parameters: bytes ])
+
+; Extensions are not currently supported by plutus and should be set to []
+; Any extensions present in the certificate will be ignored by plutus scripts.
+Extensions = [ * Extension ] / int
+
+Extension = (
+	( extensionID: int, extensionValue: any )
+	// ( extensionID: ~oid, ? critical: true, extensionValue: bytes )
+	// ( extensionID: pen, ? critical: true, extensionValue: bytes )
+)

docs/src/catalyst-standards/draft-cips/c509-plutus-restricted-certificate/cip-509C.md

@@ -0,0 +1,57 @@
+---
+CIP: /?
+Title: Restricted format for C509 compatibility with Plutus
+Category: MetaData
+Status: Proposed
+Authors:
+    - Steven Johnson<steven.johnson@iohk.io>
+Implementors: []
+Discussions:
+    - https://github.com/cardano-foundation/cips/pulls/?
+Created: 2023-10-24
+License: CC-BY-4.0
+---
+
+## Abstract
+
+Plutus can access metadatums that encode C509 certificates.
+This specification documents the restricted feature set of those certificates.
+
+## Motivation: why is this CIP necessary?
+
+In order to keep complexity low, this specification details a set of restriction
+on-top of a standard C509 certificate definition.
+These restrictions help plutus support the important features of
+x509 certificates in smart contracts on-chain.
+
+They also help reduce the amount of data stored on-chain.
+
+## Specification
+
+See [c509-cert-plutus-restricted.cddl](./c509-cert-plutus-restricted.cddl).
+This is the formal specification which describes the requirements of on-chain x509 certificates.
+ust include a CDDL schema in it's specification.-->
+
+## Rationale: how does this CIP achieve its goals?
+
+By clearly defining the feature set that plutus scripts can accept from C509 certificates it is easier for
+script writers and certificate creators to produce interoperable certificates.
+
+## Path to Active
+
+This draft CIP requires extensive collaboration with multiple parties in order to arrive at a
+correct and viable specification.
+
+It has been kept deliberately terse in order for that process to be as open and collaborative as possible.
+
+### Acceptance Criteria
+
+* General community consensus on the minimum standard needs to be agreed.
+
+### Implementation Plan
+
+## Copyright
+
+This CIP is licensed under [CC-BY-4.0]
+
+Code samples and reference material are licensed under [Apache 2.0]