From 60efd328e1fc83f70f9395c438baea7faa3eab8f Mon Sep 17 00:00:00 2001 From: Chris Swan <478926+cpswan@users.noreply.github.com> Date: Thu, 14 Dec 2023 16:49:11 +0000 Subject: [PATCH 1/3] docs: SDK ready for Beta release --- README.md | 2 +- pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d932a85..7385faa 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_python/badge)](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_python) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8104/badge)](https://www.bestpractices.dev/projects/8104) -# The atPlatform for Python developers - (Alpha Version) +# The atPlatform for Python developers - (Beta Version) This repo contains library, samples and examples for developers who wish to work with the atPlatform from Python code. diff --git a/pyproject.toml b/pyproject.toml index fa9d305..58960cf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "atsdk" -version = "0.0.4" +version = "0.1.0" description = "Python SDK for atPlatform" authors = ["Umang Shah ","Chris Swan "] maintainers = ["Chris Swan "] From f068f8be03d16950307ce56d46ac791634022968 Mon Sep 17 00:00:00 2001 From: Chris Swan <478926+cpswan@users.noreply.github.com> Date: Thu, 14 Dec 2023 17:09:11 +0000 Subject: [PATCH 2/3] docs: Markdown lints --- CONTRIBUTING.md | 47 +++++++++-------- README.md | 127 +++++++++++++++++++++++++++------------------ SECURITY.md | 82 ++++++++++++++--------------- code_of_conduct.md | 6 +-- 4 files changed, 146 insertions(+), 116 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb976a6..8ff942f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ - +

# Contributing guidelines @@ -8,38 +8,38 @@ for fixing issues or adding features. Thanks for your contribution! Please read our [code of conduct](code_of_conduct.md), which is based on [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](code_of_conduct.md) - For small changes, especially documentation, you can simply use the "Edit" button to update the Markdown file, and start the [pull request](https://help.github.com/articles/about-pull-requests/) process. Use the preview tab in GitHub to make sure that it is properly -formatted before committing. Please use conventional commits and follow the semantic PR format as documented -[here](https://github.com/atsign-foundation/.github/blob/trunk/atGitHub.md#semantic-prs). -A pull request will cause integration tests to run automatically, so please review -the results of the pipeline and correct any mistakes that are reported. +formatted before committing. Please use conventional commits and follow the +semantic PR format as documented +[here](https://github.com/atsign-foundation/.github/blob/trunk/atGitHub.md#semantic-prs) +. A pull request will cause integration tests to run automatically, so please +review the results of the pipeline and correct any mistakes that are reported. If you plan to contribute often or have a larger change to make, it is best to -setup an environment for contribution, which is what the rest of these guidelines -describe. The atsign-foundation GitHub organization's conventions and configurations are documented +setup an environment for contribution, which is what the rest of these +guidelines describe. The atsign-foundation GitHub organization's conventions +and configurations are documented [here](https://github.com/atsign-foundation/.github/blob/trunk/atGitHub.md). ## Development Environment Setup - ### Prerequisites -1. Download latest python from https://www.python.org/downloads/ +1. Download latest python from 2. Install required libraries using below command. - ``` + + ```sh pip install -r requirements.txt ``` - ### GitHub Repository Clone To prepare your dedicated GitHub repository: -1. Fork in GitHub https://github.com/atsign-foundation/at_python +1. Fork in GitHub 2. Clone *your forked repository* (e.g., `git clone git@github.com:yourname/at_python`) 3. Set your remotes as follows: @@ -61,7 +61,7 @@ To prepare your dedicated GitHub repository: The use of `upstream --push DISABLED` is to prevent those with `write` access to the main repository from accidentally pushing changes directly. - + ### Development Process 1. Fetch latest changes from main repository: @@ -89,15 +89,18 @@ To prepare your dedicated GitHub repository: git push ``` -1. How to run tests:
- Create `config.ini` file and add your atsigns to run testcases. The structure of the files is as follows: +1. How to run tests: + Create `config.ini` file and add your atsigns to run testcases. The + structure of the files is as follows: - ``` + ```sh [test_atsigns] atsign1 = atsign2 = ``` + Run all testcases using this command. + ``` sh python -m unittest discover -s test -p '*_test.py' -v ``` @@ -139,11 +142,11 @@ release to pub.dev * Where possible the issue associated with the bug should be closed by mutual consent with the reporter. This could be: - * The reporter closing the issue because they have found a workaround. - * The reporter closing the issue because they are satisfied with a fix - provided. - * A team member closes the issue after the reporter leaves a comment - indicating that they are happy for it to be closed. + * The reporter closing the issue because they have found a workaround. + * The reporter closing the issue because they are satisfied with a fix + provided. + * A team member closes the issue after the reporter leaves a comment + indicating that they are happy for it to be closed. * If the reporter does not respond within 14 calendar days then we must assume that they no longer have an interest in fixing the bug and work in progress can be closed out at the team’s discretion. diff --git a/README.md b/README.md index 7385faa..d742d61 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - +

[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_python/badge)](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_python) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8104/badge)](https://www.bestpractices.dev/projects/8104) @@ -9,20 +9,24 @@ This repo contains library, samples and examples for developers who wish to work with the atPlatform from Python code. ## Getting Started + ### 1. Installation -``` + +```shell pip install -r requirements.txt pip install . ``` - - ### 2. Setting up your `.atKeys` + To run the examples save .atKeys file in the '~/.atsign/keys/' directory. ### 3. Sending and Receiving Data + There are 3 ways in which data can be sent and received from at server. + 1. Using PublicKey + ```python from at_client import AtClient from at_client.common import AtSign @@ -43,10 +47,10 @@ There are 3 ways in which data can be sent and received from at server. # Deleting data response = atclient.delete(pk) print(response) - ``` 2. Using SelfKey + ```python from at_client import AtClient from at_client.common import AtSign @@ -67,10 +71,10 @@ There are 3 ways in which data can be sent and received from at server. # Deleting data response = atclient.delete(sk) print(response) - ``` 3. Using SharedKey + ```python from at_client import AtClient from at_client.common import AtSign @@ -93,63 +97,86 @@ There are 3 ways in which data can be sent and received from at server. # Deleting data response = bob_atclient.delete(sk) print(response) - ``` - ### CLI Tools -* **REPL** - you can use this to type atPlatform commands and see responses; but the best thing about the REPL currently is that it shows the data notifications as they are received. The REPL code has the essentials of what a 'receiving' client needs to do - i.e. - * create an AtClient (assigning a Queue object to its queue parameter) - * start two new threads - * one for the AtClient.start_monitor() task: receives data update/delete notification events (the event data contains the ciphertext) - * the other one calls handle_event() method, which will read the upcoming events in the queue and handle them: - * calling AtClient.handle_event() (to decrypt the notifications and introducing the result as a new event in the queue) - * reading the new event, which contains the decrypted result - * Instructions to run the REPL: - 1) Run repl.py and choose an atSign using option `1` - 2) Select option `2`. REPL will start and activate monitor mode automatically in a different thread. You can still send commands/verbs. You will start seeing your own notifications (from yourself to yourself) and heartbeat working (noop verb is sent from time to time as a keepalive) - 3) Use `at_talk` or any other tool to send notifications to your atSign from a different atSign. You should be able to see the complete notification, and the encrypted and decrypted value of it. - -* **REGISTER** - use this cli to register new free atsign. Uses onboarding cli to create atkey files. - * Use following command to run the REGISTER cli using email: - ```shell - python register.py -e - ``` - * Use following command to run the REGISTER cli using api-key: - ```shell - python register.py -k - ``` - -* **ONBOARDING** - use this cli to onboard a new atSign. Once onboarding is complete it creates the all-important keys file. Onboard is a subset of Register. - * Use following command to run the ONBOARDING cli: - ```shell - python onboarding.py -a -c - ``` + +* **REPL** - you can use this to type atPlatform commands and see responses; +but the best thing about the REPL currently is that it shows the data +notifications as they are received. The REPL code has the essentials of what +a 'receiving' client needs to do - i.e. + * create an AtClient (assigning a Queue object to its queue parameter) + * start two new threads + * one for the AtClient.start_monitor() task: receives data update/delete + notification events (the event data contains the ciphertext) + * the other one calls handle_event() method, which will read the + upcoming events in the queue and handle them: + * calling AtClient.handle_event() (to decrypt the notifications and + introducing the result as a new event in the queue) + * reading the new event, which contains the decrypted result + * Instructions to run the REPL: + 1) Run repl.py and choose an atSign using option `1` + 2) Select option `2`. REPL will start and activate monitor mode + automatically in a different thread. You can still send commands/verbs. + You will start seeing your own notifications (from yourself to yourself) + and heartbeat working (noop verb is sent from time to time as a keepalive) + 3) Use `at_talk` or any other tool to send notifications to your atSign + from a different atSign. You should be able to see the complete + notification, and the encrypted and decrypted value of it. + +* **REGISTER** - use this cli to register new free atsign. Uses onboarding +cli to create atkey files. + * Use following command to run the REGISTER cli using email: + + ```shell + python register.py -e + ``` + + * Use following command to run the REGISTER cli using api-key: + + ```shell + python register.py -k + ``` + +* **ONBOARDING** - use this cli to onboard a new atSign. Once onboarding +is complete it creates the all-important keys file. Onboard is a subset of +Register. + * Use following command to run the ONBOARDING cli: + + ```shell + python onboarding.py -a -c + ``` * **SHARE** - use this cli to share data between 2 atsigns. - * Use following command to run the SHARE cli: - ```shell - python share.py -a -o -k -s - ``` + * Use following command to run the SHARE cli: + + ```shell + python share.py -a -o -k -s + ``` * **GET** - use this cli to get shared data between 2 atsigns. - * Use following command to run the GET cli: - ```shell - python get.py -a -o -k - ``` + * Use following command to run the GET cli: + + ```shell + python get.py -a -o -k + ``` * **DELETE** - use this cli to delete any key shared between 2 atsigns. - * Use following command to run the DELETE cli: - ```shell - python delete.py -a -o -k - ``` + * Use following command to run the DELETE cli: + + ```shell + python delete.py -a -o -k + ``` ## Open source usage and contributions This is open source code, so feel free to use it as is, suggest changes or -enhancements or create your own version. See [CONTRIBUTING.md](./CONTRIBUTING.md) -for detailed guidance on how to setup tools, tests and make a pull request. +enhancements or create your own version. See +[CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidance on how to setup +tools, tests and make a pull request. ## Maintainers -This project is created and maintained by [Umang Shah](https://github.com/shahumang19) +This project was created by [Umang Shah](https://github.com/shahumang19) +and is maintained by [Chris Swan](https://github.com/cpswan) and +[Xavier Lin](https://github.com/xlin123) diff --git a/SECURITY.md b/SECURITY.md index 6f56d8a..06ed9cd 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,41 +1,41 @@ - - -# Atsign Foundation Open Source Security Policies and Procedures - -This document outlines security procedures and general policies for the -Atsign Foundation Open Source projects as found on -https://github.com/atsign-foundation. - - * [Reporting a Vulnerability](#reporting-a-vulnerability) - * [Disclosure Policy](#disclosure-policy) - -## Reporting a Vulnerability - -The Atsign Foundation team and community take all security vulnerabilities -seriously. Thank you for improving the security of our open source -software. We appreciate your efforts and responsible disclosure and will -make every effort to acknowledge your contributions. - -Report security vulnerabilities by emailing the Atsign security team at: - - security@atsign.com - -The lead maintainer will acknowledge your email within 24 hours, and will -send a more detailed response within 48 hours indicating the next steps in -handling your report. After the initial reply to your report, the security -team will endeavor to keep you informed of the progress towards a fix and -full announcement, and may ask for additional information or guidance. - -Please report security vulnerabilities in third-party modules to the person -or team maintaining the module. - -## Disclosure Policy - -When the security team receives a security bug report, they will assign it -to a primary handler. This person will coordinate the fix and release -process, involving the following steps: - - * Confirm the problem and determine the affected versions. - * Audit code to find any potential similar problems. - * Prepare fixes for all releases still under maintenance. These fixes - will be released as fast as possible to pub.dev where applicable. \ No newline at end of file +

+ +# Atsign Foundation Open Source Security Policies and Procedures + +This document outlines security procedures and general policies for the +Atsign Foundation Open Source projects as found on +. + +* [Reporting a Vulnerability](#reporting-a-vulnerability) +* [Disclosure Policy](#disclosure-policy) + +## Reporting a Vulnerability + +The Atsign Foundation team and community take all security vulnerabilities +seriously. Thank you for improving the security of our open source +software. We appreciate your efforts and responsible disclosure and will +make every effort to acknowledge your contributions. + +Report security vulnerabilities by emailing the Atsign security team at: + + security@atsign.com + +The lead maintainer will acknowledge your email within 24 hours, and will +send a more detailed response within 48 hours indicating the next steps in +handling your report. After the initial reply to your report, the security +team will endeavor to keep you informed of the progress towards a fix and +full announcement, and may ask for additional information or guidance. + +Please report security vulnerabilities in third-party modules to the person +or team maintaining the module. + +## Disclosure Policy + +When the security team receives a security bug report, they will assign it +to a primary handler. This person will coordinate the fix and release +process, involving the following steps: + +* Confirm the problem and determine the affected versions. +* Audit code to find any potential similar problems. +* Prepare fixes for all releases still under maintenance. These fixes + will be released as fast as possible to pub.dev where applicable. diff --git a/code_of_conduct.md b/code_of_conduct.md index 072d50a..9122094 100644 --- a/code_of_conduct.md +++ b/code_of_conduct.md @@ -1,4 +1,4 @@ - +

# The Atsign Foundation Code of Conduct @@ -123,11 +123,11 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. -Community Impact Guidelines were inspired by +Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC]. For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations]. [homepage]: https://www.contributor-covenant.org From a308ad26ba32785ec11e3da1aec526e9fc297f72 Mon Sep 17 00:00:00 2001 From: Chris Swan <478926+cpswan@users.noreply.github.com> Date: Thu, 14 Dec 2023 17:10:57 +0000 Subject: [PATCH 3/3] docs: Add PyPI install instructions --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index d742d61..36f1e37 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,14 @@ to work with the atPlatform from Python code. ### 1. Installation +This package can be installed from PyPI with: + +```sh +pip install atsdk +``` + +Alternatively clone this repo and from the repo root: + ```shell pip install -r requirements.txt pip install .