diff --git a/CHANGELOG.md b/CHANGELOG.md index 555f5eec1d03abe34e5311292e8e7f35a3c98521..83a3809eb796844a1cabaa3d8b3c337887762e9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ # Revision history for tahoe-capabilities -## 0.1.0.0 -- YYYY-mm-dd +## 0.1.0.0 -- 2023-08-15 * First version. Released on an unsuspecting world. +* Add the `ConfidentialShowable` type class for stringifying secrets. diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..95731801eda4732fbe275c4d312f0a14ea2f4d88 --- /dev/null +++ b/README.md @@ -0,0 +1,28 @@ +# Tahoe-Capabilities + +## What is it? + +Tahoe-LAFS LIT, CHK, SDMF, and MDMF capabilities offer varying functionality for interacting with encrypted data. +This library provides abstractions for functionality common to all of these capability types. + +All responsibility for implementing these abstractions is left to the capability-specific libraries. + +### What is the current state? + +* The `ConfidentialShowable` type class provides a uniform way for losslessly converting a capability to a string. + +### What is planned? + +Sufficient abstraction so that general encoding, decoding, upload, and download functions could be implemented independent of the specific capability type in use. + +## Why does it exist? + +Each specific Tahoe-LAFS capability type supports certain operations and offers certain security properties. +At a high level, +an application will often want to select among the available capability types to satisfy its particular security and/or privacy requirements. +A lower level exists encompassing such details of a capability type as which hash function is used or the size or alignment of certain fields. +Applications should typically not be required to make choices at this lower level. +By using a set of operations that abstract over these details, +application code can be kept simpler and more general-purpose. +By allowing some centralization of the choice of which concrete capability type to use, +applications can also be made more secure over time at a lower maintenance cost. diff --git a/flake.nix b/flake.nix index b97bb3e0df73427c618811e9518e7c660801cb6e..021ed188267173b5823c8d17e1f7dd070699f6c9 100644 --- a/flake.nix +++ b/flake.nix @@ -42,12 +42,30 @@ runtimeInputs = with pkgs; [pkg-config haskell.compiler.${ghcVersion} cabal-install]; text = '' + set -ex cabal update hackage.haskell.org - cabal build all - cabal run tests + cabal build --enable-tests + runtests=$(cabal list-bin --enable-tests tahoe-capabilities-test) + eval "$runtests" ''; } }/bin/cabal-build-and-test"; }; + apps.release = { + type = "app"; + program = "${ + pkgs.writeShellApplication { + name = "release"; + runtimeInputs = with pkgs; [cabal-install]; + text = '' + set -x + sdist=$(cabal sdist | tail -n 1) + haddocks=$(cabal haddock --haddock-for-hackage | tail -n 1) + cabal upload "$sdist" + cabal upload --documentation "$haddocks" + ''; + } + }/bin/release"; + }; }); } diff --git a/tahoe-capabilities.cabal b/tahoe-capabilities.cabal index 7af4ce996db837f9c34c694b74752d9ae73e9edc..0aff665faa3c5173620285a60fb4bccd83c2699a 100644 --- a/tahoe-capabilities.cabal +++ b/tahoe-capabilities.cabal @@ -18,20 +18,26 @@ name: tahoe-capabilities -- See the Haskell package versioning policy (PVP) for standards -- guiding when and how versions should be incremented. -- https://pvp.haskell.org --- PVP summary: +-+------- breaking API changes --- | | +----- non-breaking API additions --- | | | +--- code changes with no API change +-- PVP summary: +-+------- breaking API changes +-- | | +----- non-breaking API additions +-- | | | +--- code changes with no API change version: 0.1.0.0 -- A short (one-line) description of the package. --- synopsis: +synopsis: Abstractions related to Tahoe-LAFS "capabilities". -- A longer description of the package. --- description: +description: + Tahoe-LAFS LIT, CHK, SDMF, and MDMF capabilities offer varying functionality + for interacting with encrypted data. This library provides abstractions for + functionality common to all of these capability types. -- URL for the project homepage or repository. homepage: - https://whetstone.private/storage/PrivateStorage/tahoe-capabilities + https://whetstone.private.storage/PrivateStorage/tahoe-capabilities + +bug-reports: + https://whetstone.private.storage/PrivateStorage/tahoe-capabilities/-/issues -- The license under which the package is released. license: LGPL-3.0-or-later @@ -43,19 +49,26 @@ license-file: LICENSE author: Jean-Paul Calderone -- An email address to which users can send suggestions, bug reports, and patches. -maintainer: jean-paul@private.storage +maintainer: exarkun@twistedmatrix.com -- A copyright notice. --- copyright: +copyright: 2023 The Authors category: Codec build-type: Simple -- Extra doc files to be distributed with the package, such as a CHANGELOG or a README. -extra-doc-files: CHANGELOG.md +extra-doc-files: + CHANGELOG.md + README.md -- Extra source files to be distributed with the package, such as examples, or a tutorial module. -- extra-source-files: +source-repository head + type: git + location: + gitlab@whetstone.private.storage:privatestorage/tahoe-capabilities.git + common warnings ghc-options: -Wall @@ -76,8 +89,8 @@ library -- Other library packages from which modules are imported. build-depends: - , base - , text + , base >=4.7 && <5 + , text >=1.2.3.1 && <1.3 -- Directories containing source files. hs-source-dirs: src @@ -109,5 +122,5 @@ test-suite tahoe-capabilities-test -- Test dependencies. build-depends: - , base + , base >=4.7 && <5 , tahoe-capabilities