merge: 'implement-basic-functionality' into 'main'

Implement basic functionality

See merge request namib-master/libraries/dart_dcaf!2

Author: falko17

.gitignore

@@ -0,0 +1,12 @@
+# Files and directories created by pub.
+.dart_tool/
+.packages
+
+# Conventional directory for build outputs.
+build/
+
+# Omit committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock
+
+.idea

.gitlab-ci.yml

@@ -0,0 +1,67 @@
+# https://hub.docker.com/_/dart
+image: dart:beta
+
+variables:
+  PUB_VARS: "--platform vm --timeout 30s --concurrency=6 --test-randomize-ordering-seed=random --reporter=json"
+
+# Cache downloaded dependencies and plugins between builds.
+# To keep cache across branches add 'key: "$CI_JOB_NAME"'
+cache:
+  paths:
+    - .pub-cache/global_packages
+
+before_script:
+  - export PATH="$PATH":"~/.pub-cache/bin"
+  - pub get --no-precompile
+  - pub global activate junitreport
+  - pub global activate coverage
+  - pub global activate -sgit https://github.com/Workiva/lsif_indexer
+  - apt -qq update
+  - apt -qq install -y lcov python3 python3-distutils # unfortunately necessary to convert lcov reports to cobertura
+  - curl -o lcov_cobertura.py https://raw.githubusercontent.com/eriwen/lcov-to-cobertura-xml/master/lcov_cobertura/lcov_cobertura.py
+
+style_check:
+  stage: test
+  script:
+    - dart format -o none --set-exit-if-changed .
+
+lint:
+  stage: test
+  script:
+    - dart analyze .
+
+test:
+  stage: test
+  script:
+    - pub run test $PUB_VARS --coverage=./coverage > report.jsonl
+    - pub global run junitreport:tojunit --input report.jsonl --output report.xml
+    - pub global run coverage:format_coverage --packages=.packages --report-on=lib --lcov -o ./coverage/lcov.info -i ./coverage
+    - python3 lcov_cobertura.py ./coverage/lcov.info -o ./coverage.xml
+    - genhtml coverage/lcov.info
+  coverage: '/lines\.*: \d+\.\d+\%/'
+  artifacts:
+    when: always
+    reports:
+      junit:
+        - report.xml
+      cobertura:
+        - coverage.xml
+
+code_quality:
+  stage: test
+  script:
+    - dart run dart_code_metrics:metrics analyze lib -r gitlab > quality.json
+  artifacts:
+    when: always
+    reports:
+      codequality:
+        - quality.json
+
+code_navigation:
+  stage: test
+  allow_failure: true
+  script:
+    - pub global run lsif_indexer -o dump.lsif
+  artifacts:
+    reports:
+      lsif: dump.lsif

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0-pre --- 2022-04-27
+- CBOR de-/serializable model of the ACE-OAuth framework has been added:
+    - Binary-, text-encoded and [AIF](https://datatracker.ietf.org/doc/html/draft-ietf-ace-aif)-scopes
+      - A variant of the AIF format specific to [libdcaf](https://gitlab.informatik.uni-bremen.de/DCAF/dcaf) is also supported
+    - Access token requests and responses
+    - Authorization server request creation hints
+    - Error responses
+    - Various smaller types (`CoseKey`, `GrantType`, `ProofOfPossessionKey`, `TokenType`...)
+    - Use `serialize()` or `fromSerialized()` to serialize and deserialize these types.
+- Pre-release because we depend on the Dart Beta SDK (2.17.0).

CODEOWNERS

@@ -3,4 +3,4 @@
 # https://docs.gitlab.com/ee/user/project/code_owners.html
 
 [Maintainers]
-# * [ENTER USERNAME HERE AND UNCOMMENT]
+* @falko1

LICENSE

@@ -0,0 +1 @@
+LICENSE-MIT

LICENSE-MIT

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 The NAMIB Project Developers
+Copyright (c) 2022 The NAMIB Project Developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,20 +1,98 @@
-# [PROJECT NAME HERE]
+# dart_dcaf
 
-[PROJECT SHORT DESCRIPTION HERE]
+[![pub.dev](https://img.shields.io/pub/v/dcaf?style=for-the-badge)](https://pub.dev/packages/dcaf)
 
-## **IMPORTANT NOTES CONCERNING THE TEMPLATE**
+An implementation of the [ACE-OAuth] framework in Dart.
 
-After creating the repository, perform the steps detailed in [the current version of the Git workflow document](https://hackmd.informatik.uni-bremen.de/s/w8tkKT_SZ).
+This library implements the ACE-OAuth
+(Authentication and Authorization for Constrained Environments
+using the OAuth 2.0 Framework) framework as defined in
+[`draft-ietf-ace-oauth-authz-46`](https://www.ietf.org/archive/id/draft-ietf-ace-oauth-authz-46.html).
+Its main feature is CBOR-(de-)serializable data models such as `AccessTokenRequest`.
 
-The most important steps that need to be performed are:
-1. Set at least one maintainer **in the CODEOWNERS file**, **at the end of this README document** and **in the GitLab project member settings (under "Project information")**.
-2. Check that the **push rules**, the **merge approval and merge request settings** as well as the **protected branch settings** match the ones detailed in the Git workflow document.
-3. Check that the License suggested in this template (Apache 2.0/MIT dual license) is actually the one you want for this project.
-4. Enable/disable GitLab project features as needed (Settings->General)
-4. Update this README file, adding a short repository description and other relevant information (like build instructions) and removing this part of the document.
-5. **Rewrite/Replace** the initial commit so that the first commit includes all the changes you have made (as well as other things the repository should inlcude in the first commit) and **force push** the initial commit (you might have to disable the branch protection temporarily for this).
+## Features
+- CBOR de-/serializable model of the ACE-OAuth framework:
+  - Binary-, text-encoded and [AIF](https://datatracker.ietf.org/doc/html/draft-ietf-ace-aif)-scopes
+    - A variant of the AIF format specific to [libdcaf](https://gitlab.informatik.uni-bremen.de/DCAF/dcaf) is also supported
+    - *Note that dynamic REST methods in AIF currently don't (de)serialize correctly on the Web platform!*
+  - Access token requests and responses
+  - Authorization server request creation hints
+  - Error responses
+  - Various smaller types (`CoseKey`, `GrantType`, `ProofOfPossessionKey`, `TokenType`...)
+  - Use `serialize()` or `fromSerialized()` to serialize and deserialize these types.
 
-If there are any questions or suggestions you can contact the Git workflow group (@s_edhnm5, @falko1, @hdamer) via Mattermost.
+> Note that actually transmitting the serialized values (e.g. via CoAP)
+is *out of scope* for this library.
+
+## Getting started
+
+**Note that this package is currently in pre-release, mainly because we depend
+on Dart 2.17.0, which is still in Beta at the time of writing.**
+
+All you need to do to get started is to add this package to your `pubspec.yaml`.
+You can then import it using `import 'package:dcaf/dcaf.dart`.
+
+## Usage
+
+As mentioned, the main feature of this library is ACE-OAuth data models.
+
+[For example](https://www.ietf.org/archive/id/draft-ietf-ace-oauth-authz-46.html#figure-7),
+say you (the client) want to request an access token from an
+Authorization Server. For this, you'd need to create an `AccessTokenRequest`, 
+which has to include at least a `clientId`. We'll also specify an audience,
+a scope (using `TextScope`---note that `BinaryScope`s or `AifScope`s would also work), 
+as well as a `ProofOfPossessionKey`
+(the key the access token should be bound to) in the `reqCnf` field.
+
+Creating, serializing and then de-serializing such
+a structure would look like this:
+```dart
+final request = AccessTokenRequest(
+    clientId: "myclient",
+    audience: "valve242",
+    scope: TextScope("read"),
+    reqCnf: KeyId([0xDC, 0xAF]));
+final List<int> serialized = request.serialize();
+assert(AccessTokenRequest.fromSerialized(serialized) == request);
+```
+
+Its CBOR representation (using CBOR diagnostic notation) would look like this:
+```text
+{
+  "client_id" : "myclient",
+  "audience" : "valve424",
+  "scope" : "read",
+  "req_cnf" : {
+    "kid" : h'dcaf'
+  }
+}
+```
+(Note that abbreviations aren't used here,
+so keep in mind that the labels are really integers instead of strings.)
+
+## Additional information
+
+This library is heavily based on [`dcaf-rs`](https://crates.io/crates/dcaf),
+a similar implementation of the ACE-OAuth framework in Rust, which is
+intended for all actors in the ACE-OAuth protocol flow
+(e.g. Authorization Servers too). In contrast, this library is mainly
+intended for the "Client", hence missing some features present in `dcaf-rs`.
+Whenever I update `dcaf-rs`, I will try to add the new functionality to 
+this library as well (if applicable).
+
+The name DCAF was chosen because eventually, it's planned for this
+library to support functionality from the [Delegated CoAP Authentication and
+Authorization Framework (DCAF)](https://dcaf.science/)
+specified in [`draft-gerdes-ace-dcaf-authorize`](https://datatracker.ietf.org/doc/html/draft-gerdes-ace-dcaf-authorize-04)
+(which was specified prior to ACE-OAuth and inspired many design
+choices in it)---specifically, it's planned to support using a CAM
+(Client Authorization Manager)
+instead of just a SAM (Server Authorization Manager),
+as is done in ACE-OAuth.
+Compatibility with the existing [DCAF implementation in C](https://gitlab.informatik.uni-bremen.de/DCAF/dcaf)
+(which we'll call `libdcaf` to disambiguate from `dcaf` referring
+to this library) is also an additional design goal, though the primary
+objective is still to support ACE-OAuth.
 
 ## License
 
@@ -37,6 +115,9 @@ dual licensed as above, without any additional terms or conditions.
 
 This project is currently maintained by the following developers:
 
-|    Name    |     Email Address    |                GitHub Username               |
-|:----------:|:--------------------:|:--------------------------------------------:|
-| [MAINTAINER NAME] | [MAINTAINER UNIVERSITY EMAIL] | [[GITHUB_USERNAME]]([GITHUB_PROFILE_URL]) |
+|      Name      |    Email Address     |            GitHub Username            |
+|:--------------:|:--------------------:|:-------------------------------------:|
+| Falko Galperin | [email protected] | [falko17](https://github.com/falko17) |
+
+
+[ACE-OAuth]: https://www.ietf.org/archive/id/draft-ietf-ace-oauth-authz-46.html

analysis_options.yaml

@@ -0,0 +1,111 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+
+include: package:lints/recommended.yaml
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options
+
+analyzer:
+  exclude:
+    - "**/*.g.dart"
+    - "**/*.freezed.dart"
+  strong-mode:
+    implicit-casts: false
+    implicit-dynamic: false
+  errors:
+    invalid_annotation_target: ignore  # for freezed
+    missing_required_param: warning
+    missing_return: warning
+    package_api_docs: warning
+    public_member_api_docs: warning
+    prefer_interpolation_to_compose_strings: warning
+    unnecessary_lambdas: warning
+    avoid_catches_without_on_clauses: warning
+    avoid_catching_errors: warning
+    prefer_mixin: warning
+    use_setters_to_change_properties: warning
+    avoid_setters_without_getters: warning
+    type_annotate_public_apis: warning
+    always_declare_return_types: warning
+    avoid_void_async: warning
+    only_throw_errors: warning
+    prefer_final_locals: warning
+    prefer_null_aware_method_calls: warning
+    unawaited_futures: warning
+    depend_on_referenced_packages: warning
+    flutter_style_todos: info
+    deprecated_member_use_from_same_package: info
+    todo: ignore
+
+# Rules in addition to recommended set
+linter:
+  rules:
+    - directives_ordering
+    - package_api_docs
+    - public_member_api_docs
+    - comment_references
+    - prefer_interpolation_to_compose_strings
+    - unnecessary_lambdas
+    - lines_longer_than_80_chars
+    - avoid_catches_without_on_clauses  # no pokémon exception handling (at least only catch Exception)
+    - avoid_catching_errors
+    - use_to_and_as_if_applicable  # this rule may cause false positives, if so, just disable it
+    - prefer_mixin
+    - use_setters_to_change_properties
+    - avoid_setters_without_getters  # use a method instead
+    - avoid_returning_this  # use cascades instead
+    - type_annotate_public_apis
+    - avoid_types_on_closure_parameters
+    - avoid_positional_boolean_parameters
+    - avoid_dynamic_calls
+    - avoid_returning_null_for_future
+    - avoid_slow_async_io
+    - cancel_subscriptions
+    - close_sinks
+    - always_declare_return_types
+    - avoid_void_async
+    - cascade_invocations
+    - eol_at_end_of_file
+    - flutter_style_todos
+    - leading_newlines_in_multiline_strings
+    - only_throw_errors
+    - prefer_final_locals
+    - prefer_null_aware_method_calls
+    - unawaited_futures
+    - unnecessary_null_aware_assignments
+    - use_if_null_to_convert_nulls_to_bools
+    - use_is_even_rather_than_modulo
+    - depend_on_referenced_packages
+
+
+dart_code_metrics:
+  anti-patterns:
+    - long-method
+    - long-parameter-list
+  metrics:
+    cyclomatic-complexity: 20
+    maximum-nesting-level: 5
+    number-of-parameters: 4
+    source-lines-of-code: 50
+  metrics-exclude:
+    - test/**
+  rules:
+    - avoid-nested-conditional-expressions:
+        - acceptable-level: 2
+    - avoid-throw-in-catch-block # throwWithStackTrace should be used instead
+    - avoid-unnecessary-type-casts
+    - no-boolean-literal-compare
+    - no-empty-block
+    - no-equal-then-else
+    - no-magic-number:
+        - allowed: [3.14, -1, 0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 100]
+    - prefer-correct-type-name