From 00b0f1b44bd4578c4d879b176e4599ea25ff7eb6 Mon Sep 17 00:00:00 2001 From: Srie Teja Date: Thu, 29 Jun 2023 19:00:45 +0530 Subject: [PATCH 1/4] refactor: rename old readme to changelog --- CHANGELOG.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f222ac7 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,66 @@ + + +[![gitHub license](https://img.shields.io/badge/license-BSD3-blue.svg)](./LICENSE) +[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_java/badge)](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_java) + +# The atPlatform for Java developers + +This repo contains libraries, tools, samples and examples for developers who wish +to work with the atPlatform from Java code. + +NB: As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally +be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0 + +### Contributions welcome! + +All of our software is open with intent. We welcome contributions - we want pull requests, and we want +to hear about issues. See also [CONTRIBUTING.md](CONTRIBUTING.md) + +## What's here / changelog +### Next ... +* Getting started guide - from nothing to end-to-end-encrypted chat session in < 5 minutes +* fluid client APIs for sharing data - e.g. share(value).with(atSign/s).as(keyName) +* extend client REPL so that you can call AtClient methods (e.g. the share() above) interactively + +### May 29 2022 +* Retry bug fixed in Register CLI +* Config yaml parameters restructured and backwards compatibility provided so as not to break existing usage. +* New parameter added to validateOtp method in RegisterUtil.java. The usage of this parameter is provided in + java docs of the respective method. + + +### May 18 2022 +* A new CLI tool Register has been introduced which can acquire a free atsign and register it to the provided email. +* Register CLI also handles calling the Onboard client with the cram secret which was received during the registration process. + +### May 03 2022 +* Better event distribution +* Improved Monitor's event generation +* Added 'userDefined' to the AtEventType enum, to allow the event bus to be used by application code +* Caches shared keys after first retrieval +* AtClientImpl listens for updateNotification events, decrypts the ciphertext on-the-fly, and publishes a decryptedUpdateNotification + which is more useful for application code +* Enhanced REPL to optionally listen to only decryptedUpdateNotification; added command-line flag to listen to both + +### Apr 29 2022 +* **at_client** : Initial implementation of Java client library for the atPlatform. README will come soon + but here's a very brief summary which will get you going if you already know the basics of the atPlatform + and have used the Dart/Flutter packages + * **Uses Maven** + * The Maven target you want is 'install' which will put things in the 'target' output directory + * The **CLI tools** will give you the best overview of how to use the library as a whole. There are five CLIs + in the initial commit: + * **Onboard** - generate keys for a new @-sign. If you already have a .keys file, you can reuse it. + Currently, the Java library expects keys for @alice to be in ./keys/@alice.keys + * **REPL** - you can use this to type @-protocol 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 + * add an event listener which + * receives data update/delete notification events (the event data contains the ciphertext) + * calls 'get' to decrypt + * **Share** - a simple 'sender' client - shares some data with another @-sign + * **Get** - gets data which was shared by another @-sign + * **Delete** - deletes data that this Atsign previously shared with another + * To run them, having done a mvn install + `java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.REPL` (or Onboard/Share/Get/Delete ) From 0622b71121dd98b9bb51df80fc33145195913bd9 Mon Sep 17 00:00:00 2001 From: Srie Teja Date: Thu, 29 Jun 2023 19:01:04 +0530 Subject: [PATCH 2/4] docs: create a new README --- README.md | 125 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 69 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index d02c486..770d0a6 100644 --- a/README.md +++ b/README.md @@ -8,59 +8,72 @@ This repo contains libraries, tools, samples and examples for developers who wish to work with the atPlatform from Java code. -NB: As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally -be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0 - -### Contributions welcome! - -All of our software is open with intent. We welcome contributions - we want pull requests, and we want -to hear about issues. See also [CONTRIBUTING.md](CONTRIBUTING.md) - -## What's here / changelog -### Next ... -* Getting started guide - from nothing to end-to-end-encrypted chat session in < 5 minutes -* fluid client APIs for sharing data - e.g. share(value).with(atSign/s).as(keyName) -* extend client REPL so that you can call AtClient methods (e.g. the share() above) interactively - -### May 29 2022 -* Retry bug fixed in Register CLI -* Config yaml parameters restructured and backwards compatibility provided so as not to break existing usage. -* New parameter added to validateOtp method in RegisterUtil.java. The usage of this parameter is provided in -java docs of the respective method. - - -### May 18 2022 -* A new CLI tool Register has been introduced which can acquire a free atsign and register it to the provided email. -* Register CLI also handles calling the Onboard client with the cram secret which was received during the registration process. - -### May 03 2022 -* Better event distribution -* Improved Monitor's event generation -* Added 'userDefined' to the AtEventType enum, to allow the event bus to be used by application code -* Caches shared keys after first retrieval -* AtClientImpl listens for updateNotification events, decrypts the ciphertext on-the-fly, and publishes a decryptedUpdateNotification -which is more useful for application code -* Enhanced REPL to optionally listen to only decryptedUpdateNotification; added command-line flag to listen to both - -### Apr 29 2022 -* **at_client** : Initial implementation of Java client library for the atPlatform. README will come soon -but here's a very brief summary which will get you going if you already know the basics of the atPlatform -and have used the Dart/Flutter packages - * **Uses Maven** - * The Maven target you want is 'install' which will put things in the 'target' output directory - * The **CLI tools** will give you the best overview of how to use the library as a whole. There are five CLIs - in the initial commit: - * **Onboard** - generate keys for a new @-sign. If you already have a .keys file, you can reuse it. - Currently, the Java library expects keys for @alice to be in ./keys/@alice.keys - * **REPL** - you can use this to type @-protocol 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 - * add an event listener which - * receives data update/delete notification events (the event data contains the ciphertext) - * calls 'get' to decrypt - * **Share** - a simple 'sender' client - shares some data with another @-sign - * **Get** - gets data which was shared by another @-sign - * **Delete** - deletes data that this Atsign previously shared with another - * To run them, having done a mvn install - `java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.REPL` (or Onboard/Share/Get/Delete/Register ) + +## Getting Started +#### Note: Java and Maven are Prerequisites to use at_java + +Clone the at_java repo from GItHub using + +```shell +git clone https://github.com/atsign-foundation/at_java.git +``` +Change directory into at_java/at_client + +```shell +cd at_client +``` + +Compile the package using maven with the following command + +```shell +mvn install +``` + +Now that the programs have been compiled, execute the following command to use at_java + +```shell +java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli. [required arguments] +``` + +### The different classes(functionalities) that at_java contains: +1) REPL +2) Share +3) Get +4) Delete +5) Register +6) Onboard + +#### Note: Each of these classes requires a different set of arguments, make sure to read the help text and provide necessary arguments +** Text about the remaining functionalities coming soon ** +### Register +A class that accepts command line arguments which are used to fetch a free atsign and register it to the email provided. +Further, this atsign can be activated using a verification code sent to the registered email. + +### Register with SUPER_API Key +Register* can also be used with a SUPER_API Key* that has privileges to preset and atsign with an activation code. +When using the SUPER_API Key to register an atsign, the following sequence of calls take place: +1) User provides at_java/Register with the SUPER_API Key passed as an argument +2) at_java calls the AtSign Registrar API* Endpoint(get-atsign) with the SUPER_API Key provided +3) The AtSign registrar API responds with an AtSign-ActivationKey pair +4) at_java now call the AtSign Registrar API* Endpoint(activate-atsign) with the AtSign-ActivationKey pair +5) The API responds with a json containing the CRAM_KEY* for the concerned atsign +6) This CRAM_KEY* can be used to activate the atsign further making it usable +7) at_java does the activation automatically for you and stores your atKeys* file at path '~/.atsign/keys' +8) Now the atsign is activated and the atKeys file can be used to authenticate and perform protected operation with/on the atSign. + +#### ** +1) Register: This is a class in at_java that has the functionality to call the necessary API, handle responses in order to fetch and register atsigns +2) AtSign Registrar API: An AtSign service that is responsible for handling atsign's server creation, registration, authentication, reset and deletion +3) SUPER_API Key: + - All calls to the AtSign Registrar API require an API_KEY. But the SUPER_API Key has some additional privileges. + - SUPER_API Keys have the privilege to preset an AtSign with an activation key so that this AtSign can be activated + without manually entering a verification code that is sent to the registered email + - All SUPER_API Keys have a name containing two elements [say pre and post], all the atsigns generated using this + API_Key will be of the following format: (pre)atsign(post). Now the atsign will be @preatsignpost. + This is done to separate atsigns generated using SUPER_API Keys to the atsigns that are generated through other methods. +4) CRAM_KEY: This is a authentication key that will be used for a one-time authentication to activate an atsign which allows for assigning random, secure non-symmetric keypairs which will be further stored in the users atKeys file. + * Note: CRAM_KEY will be deleted from the atsign server after an atKeys file has been generated, so only you have the keys to authenticate into your atsign +5) atKeys file: This will be a file generated during activation of an atsign that stores all the keys necessary for authenticating into atSign + * That would mean users have to keep this file in a secured location + * Users should keep this file safe, as there's only one copy of this file and losing it would mean the user would be unable to login to the atsign + * If lost, users can reset the atsign and get a new atKeys file. This would result in loss of all data stored in the atsign's server From 2d5eb5cc686c6fc8ee2f683e3dc81cd40327e622 Mon Sep 17 00:00:00 2001 From: Srie Teja Date: Fri, 27 Oct 2023 15:34:25 +0530 Subject: [PATCH 3/4] chore: resolve merge conflicts --- README.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 770d0a6..b32f4c5 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,28 @@ This repo contains libraries, tools, samples and examples for developers who wish to work with the atPlatform from Java code. +NB: As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally +be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0 + +# Maven Depdendency + +The Java SDK can be added to your project through a compiled JAR or by Maven! + +```xml + + + ossrh + https://s01.oss.sonatype.org/content/repositories/snapshots + + + + + io.github.atsign-foundation + at_client + 1.0-SNAPSHOT + + +``` ## Getting Started #### Note: Java and Maven are Prerequisites to use at_java @@ -48,9 +70,19 @@ java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli. ### Register A class that accepts command line arguments which are used to fetch a free atsign and register it to the email provided. Further, this atsign can be activated using a verification code sent to the registered email. +* To run use the following command +```shell +java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.Register -e email@email.com +``` ### Register with SUPER_API Key Register* can also be used with a SUPER_API Key* that has privileges to preset and atsign with an activation code. + +* To run use the following command +```shell +java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.Register -k +``` + When using the SUPER_API Key to register an atsign, the following sequence of calls take place: 1) User provides at_java/Register with the SUPER_API Key passed as an argument 2) at_java calls the AtSign Registrar API* Endpoint(get-atsign) with the SUPER_API Key provided @@ -61,7 +93,7 @@ When using the SUPER_API Key to register an atsign, the following sequence of ca 7) at_java does the activation automatically for you and stores your atKeys* file at path '~/.atsign/keys' 8) Now the atsign is activated and the atKeys file can be used to authenticate and perform protected operation with/on the atSign. -#### ** +### Things to know about at_platform 1) Register: This is a class in at_java that has the functionality to call the necessary API, handle responses in order to fetch and register atsigns 2) AtSign Registrar API: An AtSign service that is responsible for handling atsign's server creation, registration, authentication, reset and deletion 3) SUPER_API Key: @@ -71,9 +103,15 @@ When using the SUPER_API Key to register an atsign, the following sequence of ca - All SUPER_API Keys have a name containing two elements [say pre and post], all the atsigns generated using this API_Key will be of the following format: (pre)atsign(post). Now the atsign will be @preatsignpost. This is done to separate atsigns generated using SUPER_API Keys to the atsigns that are generated through other methods. -4) CRAM_KEY: This is a authentication key that will be used for a one-time authentication to activate an atsign which allows for assigning random, secure non-symmetric keypairs which will be further stored in the users atKeys file. +4) CRAM_KEY: This is an authentication key that will be used for a one-time authentication to activate an atsign which allows for assigning random, secure non-symmetric keypairs which will be further stored in the users atKeys file. * Note: CRAM_KEY will be deleted from the atsign server after an atKeys file has been generated, so only you have the keys to authenticate into your atsign 5) atKeys file: This will be a file generated during activation of an atsign that stores all the keys necessary for authenticating into atSign * That would mean users have to keep this file in a secured location - * Users should keep this file safe, as there's only one copy of this file and losing it would mean the user would be unable to login to the atsign + * Users should keep this file safe, as there's only one copy of this file and losing it would mean the user would be unable to log in to the atsign * If lost, users can reset the atsign and get a new atKeys file. This would result in loss of all data stored in the atsign's server + + +### Contributions welcome! + +All of our software is open with intent. We welcome contributions - we want pull requests, and we want +to hear about issues. See also [CONTRIBUTING.md](CONTRIBUTING.md) From 997777a3187fdf1bb013e5dd230da4c37eef3ca5 Mon Sep 17 00:00:00 2001 From: Srie Teja Date: Fri, 27 Oct 2023 15:38:39 +0530 Subject: [PATCH 4/4] docs: removed unnecessary element from CHANGELOG.md --- CHANGELOG.md | 24 ++++-------------------- README.md | 3 --- 2 files changed, 4 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f222ac7..5f136ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,21 +1,3 @@ - - -[![gitHub license](https://img.shields.io/badge/license-BSD3-blue.svg)](./LICENSE) -[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_java/badge)](https://api.securityscorecards.dev/projects/github.com/atsign-foundation/at_java) - -# The atPlatform for Java developers - -This repo contains libraries, tools, samples and examples for developers who wish -to work with the atPlatform from Java code. - -NB: As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally -be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0 - -### Contributions welcome! - -All of our software is open with intent. We welcome contributions - we want pull requests, and we want -to hear about issues. See also [CONTRIBUTING.md](CONTRIBUTING.md) - ## What's here / changelog ### Next ... * Getting started guide - from nothing to end-to-end-encrypted chat session in < 5 minutes @@ -62,5 +44,7 @@ to hear about issues. See also [CONTRIBUTING.md](CONTRIBUTING.md) * **Share** - a simple 'sender' client - shares some data with another @-sign * **Get** - gets data which was shared by another @-sign * **Delete** - deletes data that this Atsign previously shared with another - * To run them, having done a mvn install - `java -cp "target/at_client-1.0-SNAPSHOT.jar:target/lib/*" org.atsign.client.cli.REPL` (or Onboard/Share/Get/Delete ) + +#### Note: +As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally +be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0 diff --git a/README.md b/README.md index b32f4c5..d0c753e 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,6 @@ This repo contains libraries, tools, samples and examples for developers who wish to work with the atPlatform from Java code. -NB: As of May 3 2022, the Java client library can still be considered a 1.0.0-Beta version - i.e. there may occasionally -be breaking changes, based on feedback from users of the library, until we get to a final version 1.0.0 - # Maven Depdendency The Java SDK can be added to your project through a compiled JAR or by Maven!