From 358e5153e592a93368dd1637e79d3316e9262d48 Mon Sep 17 00:00:00 2001 From: Magic_RB Date: Thu, 21 Apr 2022 22:58:12 +0200 Subject: [PATCH 1/2] [#74] Add proper README and project description Signed-off-by: Magic_RB --- README.md | 218 ++++++++++++++++++++++++++++- coffer.cabal | 1 + docs/cli-backends-configuration.md | 28 ++++ lib/CLI/Parser.hs | 7 +- logo.png | Bin 0 -> 890 bytes logo.png.license | 3 + package.yaml | 2 +- 7 files changed, 255 insertions(+), 4 deletions(-) create mode 100644 docs/cli-backends-configuration.md create mode 100644 logo.png create mode 100644 logo.png.license diff --git a/README.md b/README.md index 60a0f2fe..eb086cb8 100644 --- a/README.md +++ b/README.md @@ -4,4 +4,220 @@ - SPDX-License-Identifier: MPL-2.0 --> -# coffer +# Coffer + +![coffer-logo](./logo.png "Coffer logo") + +Coffer is multi-backend password store with multiple frontends. It reaches out to [Vault](https://www.vaultproject.io/), [pass](https://www.passwordstore.org/) and others to store your most precious secrets. + +## Installation + +??? from releases? + +## Usage + +### CLI + +The CLI is built from a multitude of commands, a quick list can be found below: + +``` +Available commands: + view View entries under the specified path, optionally + returning only the specified field for each entry + create Create a new entry at the specified path + set-field Set a field on the entry at the specified path + delete-field Delete a field from the entry at the specified path + find Find and list entries, optionally filtering + rename Rename an entry or directory + copy Copy an entry or directory + delete Delete an entry or directory + tag Add or remove tags from an entry +``` + +#### Configuration + +First you must configure coffer and tell it how to reach your preferred backend(s). The way you do this depends on which frontend you want to use, please refer to *frontends* for a list. As an example, here is a `config.toml` taken in by the CLI frontend: + +```toml +main_backend = "vault-local" + +[[backend]] +type = "vault-kv" +name = "vault-local" +address = "localhost:8200" +mount = "secret" +token = "" +``` + +The configuration consists of a single `main_backend` key and N `[[backend]]` sections. Each one must at least have the `type` key and the `name` key. The rest depends on each backend, to see a comprehensive list, refer to [backends](./docs/cli-backends-configuration.md). + +The coffer CLI will look for its configuration file in the following order: +1. A file passed to the tool using the `-c/--config` argument +2. A file passed to the tool using the `COFFER_CONFIG` environment variable +3. `config.toml` file in the current working directory. + +### Web API + +Coffer also has a Web API. Currently, it runs on `localhost:8081`. In the future we could configure this but at this moment we can't. + +You can run server in the following ways: +1. Cabal +```shell +$ cabal run coffer-server +``` +2. Stack +```shell +$ stack run coffer-server +``` + +Documentation for Web API endpoints and their return types could be generated via `servant-openapi3`. (TODO: write something about docs generation after [#114](https://github.com/serokell/coffer/issues/114) is resolved). + +#### Configuration +(TODO: write something here after [#95](https://github.com/serokell/coffer/issues/95) is resolved). At this moment we configure Web API via HTTP header (we are passing `VaultToken`, but it's not used anywhere). + +Examples: +1. Creating new entry +```shell +$ curl -s -D /dev/stderr \ + -H 'token: root' \ + 'localhost:8081/api/v1/content/create?path=/ex1' \ + -X POST \ + -H 'Content-Type: application/json' \ + -d '{ "fields": { "some-field": { "contents": "hi", "visibility": "public" } }, "tags": ["tag"] }' | jq + +HTTP/1.1 200 OK +Transfer-Encoding: chunked +Date: Tue, 31 May 2022 13:00:28 GMT +Server: Warp/3.3.18 +Content-Type: application/json;charset=utf-8 + +{ + "path": "/ex1", + "dateModified": "2022-05-31T13:00:28.267250327Z", + "masterField": null, + "fields": { + "some-field": { + "dateModified": "2022-05-31T13:00:28.267250327Z", + "visibility": "public", + "contents": "hi" + } + }, + "tags": [ + "tag" + ] +} + +``` +2. View all entries +```shell +$ curl -s -D /dev/stderr \ + -H 'token: root' \ + 'localhost:8081/api/v1/content/view?path=/' \ + -X GET \ + -H 'Content-Type: application/json' | jq + +HTTP/1.1 200 OK +Transfer-Encoding: chunked +Date: Tue, 31 May 2022 13:05:31 GMT +Server: Warp/3.3.18 +Content-Type: application/json;charset=utf-8 + +{ + "entries": [ + { + "path": "/ex1", + "dateModified": "2022-05-31T13:04:05.827650358Z", + "masterField": null, + "fields": {}, + "tags": [] + }, + { + "path": "/ex2", + "dateModified": "2022-05-31T13:04:24.259142027Z", + "masterField": null, + "fields": { + "example": { + "dateModified": "2022-05-31T13:04:24.259142027Z", + "visibility": "public", + "contents": "some contents" + } + }, + "tags": [] + }, + { + "path": "/ex3", + "dateModified": "2022-05-31T13:04:08.178256852Z", + "masterField": null, + "fields": {}, + "tags": [] + } + ], + "subdirs": {} +} +``` + +## Development + +### Nix + +This is the preffered way, install Nix according to the [Nix download page](https://nixos.org/download.html "nix download"). Then execute: + +```shell +$ nix develop --extra-experimental-features 'nix-command flakes' +``` + +You're now ready to develop coffer, using the exact same version (down to a single bit) of GHC, Cabal and all the other required tooling. To actually perform a build run: + +```shell +$ cabal build +``` + +To run coffer while developing run: + +```shell +$ cabal run coffer -- <&args> +``` + +A language server is also available, to use it, either start your IDE from a `nix shell`, or setup `direnv` for your IDE. To install `direnv` itself, take a look [here](https://direnv.net/ "direnv site"). + +### System Packages + +If you don't want to install Nix or can't, then you can try to install the required packages from your distro's package manager. This is not recommended, supported or tested. A complete, but maybe incorrect list, which may need translation to your package manager's naming convention, can be found below: + +``` +ghc +cabal +haskell-language-server (optional) +stack +stylish-haskell +zlib +``` + +## Testing + +### `Golden` Tests +Before you run `golden` tests you need to obtain a `coffer` executable. You can get it in two ways: +1. Cabal +```shell +$ cabal install +``` +2. Stack +```shell +$ stack install +``` +These commands would build the project and add a symblink for a `coffer` executable. + +Now you can run `golden` tests with next command: +```shell +$ make bats +``` + +### Haskell Tests +These test suites are easier to run than `golden` tests. You can run all tests with this command: +```shell +$ make test +``` +Also we have a special task in `Makefile` which runs only `server-integration` test suite (this test suite is included in `test` task). +```shell +$ make server-integration +``` \ No newline at end of file diff --git a/coffer.cabal b/coffer.cabal index bf98a591..e491e561 100644 --- a/coffer.cabal +++ b/coffer.cabal @@ -6,6 +6,7 @@ cabal-version: 1.12 name: coffer version: 0.1.0.0 +description: A multi-backend, multi-frontend password manager, reaching out to Vault, pass among others. category: Command Line Tools homepage: https://github.com/serokell/coffer/ author: Serokell diff --git a/docs/cli-backends-configuration.md b/docs/cli-backends-configuration.md new file mode 100644 index 00000000..46084b8f --- /dev/null +++ b/docs/cli-backends-configuration.md @@ -0,0 +1,28 @@ + + +# Coffer CLI Backends Configuration + +## Vault + +### Backend configuration file example +```toml +type = "vault-kv" # type for 'vault' backend +address = "localhost:8200" # required +mount = "secret" # required +token = "" # required +``` + +### How to run +First of all, you need to install `vault` from its [official site](https://www.vaultproject.io/). Then you can start server with the next command: +```shell +$ vault server -dev +``` +Also you can specify token and address where it would be launched (default `localhost:8200`) +```shell +-dev-root-token-id= +-dev-listen-address= +``` \ No newline at end of file diff --git a/lib/CLI/Parser.hs b/lib/CLI/Parser.hs index 2d6ed1b3..e0c5b1dc 100644 --- a/lib/CLI/Parser.hs +++ b/lib/CLI/Parser.hs @@ -33,8 +33,11 @@ parserInfo :: ParserInfo Options parserInfo = info (parser <**> helper) $ fullDesc - <> progDesc "TODO: coffer description goes here" - <> header "TODO: coffer description goes here" + <> progDesc (unlines [ "Coffer CLI is just one frontend of the coffer project." + , "Coffer, the project, is a multi-backend, multi-frontend password manager." + , "It reaches out to multiple backends, allowing you to manage multiple password stores af it were one. From anywhere!" + ]) + <> header "multi-backend, multi-frontend password manager - CLI frontend" parser :: Parser Options parser = Options diff --git a/logo.png b/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..095eefa1e7916ab3d5b79c285d7b2edbb083d59d GIT binary patch literal 890 zcmV-=1BLvFP)j5rXF<2QceH-6(k9#Fl&d7kHOQ2_XQ0Gi{HuMLwOfPiYp1p?fD zTL}bIJ1#lb^X&EjJaJ|RAYg^#I{~qku`7UpUIS+sHxmfxb)FdW6+l3*^KJ2&QL0=E zMx0+o*XcRpZ^2WNv(mHedGhhBvWu^k&Hyj+o1GHfcBVys1|z(=p4bc3$K5QYILcTE z(0@7*qo9p|-~y0c!CB5_=mVO0#Srs=7~Q0IUSUOO`$P1G9{p0Yrt$#O&x)08uHgv1)&205PNbLv7K3 z*nlb^W|qC^DL_MMT|n?a@qn1!cDn!|i4m_zq9ACX^Z+rt8Ttl*Mm;JZSdnxooTA&K zLJ5wH*IxuL=tqxH05~Wko+QgBO7IZ?Lbtc4@_PTTsQWdS0gb|u$TKaU-Il<-N!#L`1EjspDdX)W?fdMWAT7ZoY?KN-8X&avzEl9w2`neL zqfdK+Er?ce!!tY&rlb(N?+AJQ1HK?>2fH3mwuLhw|E7yDU|HVXN19?fK|D)~ztj!3cn5Z-y*=F*=VX z$~1~w3Ap|CdQwvIy+$J%xm;<@lU@F{b<+Em4)u=6epR-Mm_v?-*Y|GVtgPHLA!Qwp z*%5rr2EaMfL3=}0)pmcaV1Oi4v>fm$?;KL{M%&}cnO?)lU4i+UXzxD$0l+3O)E&`* QkpKVy07*qoM6N<$g1Ok5X#fBK literal 0 HcmV?d00001 diff --git a/logo.png.license b/logo.png.license new file mode 100644 index 00000000..838dd5c2 --- /dev/null +++ b/logo.png.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2022 Serokell + +SPDX-License-Identifier: MPL-2.0 diff --git a/package.yaml b/package.yaml index 67c1d63e..ec57d884 100644 --- a/package.yaml +++ b/package.yaml @@ -5,7 +5,7 @@ name: coffer version: 0.1.0.0 #synopsis: -#description: +description: A multi-backend, multi-frontend password manager, reaching out to Vault, pass among others. homepage: https://github.com/serokell/coffer/ license: BSD3 author: Serokell From 642021d4c9c64dfdb3650931b8a31202547504aa Mon Sep 17 00:00:00 2001 From: Leonid Vasilev Date: Mon, 6 Jun 2022 12:34:40 +0300 Subject: [PATCH 2/2] [#74] Add `stack` to `flake.nix` Problem: if we setup development environment with `nix flakes`, then we wouldn't get `stack` installed. But it is needed for some scripts. Solution: add `stack` to `flake.nix`. --- flake.nix | 1 + 1 file changed, 1 insertion(+) diff --git a/flake.nix b/flake.nix index 478ff0f1..e11b13a5 100644 --- a/flake.nix +++ b/flake.nix @@ -27,6 +27,7 @@ cabal-install haskell-language-server haskellPackages.implicit-hie + stack ]; buildInputs = with pkgs; [ zlib