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