Pre release 0.0.1

Author: satiracode

README.md

@@ -1,77 +1,24 @@
-# BitKeeper
-*Threshold Signing Vault*
+# TKeeper
 
-## Running the application
-To run an app in HTTP mode simply run:
+**TKeeper** is a threshold signature service that provides a simple REST API for distributed signing using **GG20 (Threshold ECDSA)** and **FROST (Threshold Schnorr)** protocols. The service abstracts the complexity of multiparty computation: to sign a message, a client just needs to send a single HTTP request.
 
-```bash
-java -jar <runner>.jar
-```
+It is suitable for custody systems, MPC-based wallets, and backend services that require distributed key management and signing without exposing private keys to any single participant.
 
-To enabld **CLI** mode, run:
+We avoid using high-level abstractions such as `BigInteger` for handling sensitive data. All arithmetic operations on secret shares and cryptographic material are performed through low-level bindings over **libgmp**, allowing precise memory control and zeroing. For highly sensitive values (such as private key shares), **SecretBox** from **libsodium** is used for encryption in memory. The memory encryption key is generated every time application is started. For local persistent storage, TKeeper uses **RocksDB**, with all secret data encrypted with your **seal** key before being written to disk.
 
-```bash
-java -Dquarkus.profile=cli -jar <runner>.jar 
-```
+---
 
-#### NOTE
-DON'T CHANGE `%cli` PROFILE CONFIG! HTTP SERVER SHOULD NOT BE ENABLED IN THIS MODE
+## Requirements
 
-## Configuration
-Configuration example:
+TKeeper depends on several native libraries for cryptographic operations. Make sure the following are installed on the system:
 
-```yaml
-"%cli":
-  quarkus:
-    http:
-      insecure-requests: disabled
-      host-enabled: false
-      ssl-port: -1
+- [libsodium](https://github.com/jedisct1/libsodium) – used for secure memory handling and Ed25519 point ops
+- [libgmp](https://gmplib.org/) – used for arbitrary-precision arithmetic
+- [libsecp256k1](https://github.com/bitcoin-core/secp256k1) – used for Secp256k1 point ops
 
-keeper:
-  idx: ${KEEPER_SERVICE_IDX}
-  threshold: ${KEEPER_SERVICE_THRESHOLD}
-  parallelism: ${KEEPER_SERVICE_PARALLELISM:4}
-  database-path: ${KEEPER_DATABASE_PATH}
-  session:
-    gg20:
-      expire: 15m
-    frost:
-      expire: 5m
-  private-key: ${KEEPER_PRIVATE_KEY}
-  peers:
-    - idx: 1
-      public-url: 'https://keeper1.example.com'
-      public-key: 'NOOP'
-```
+Make sure these libraries are available in your environment and linked correctly.
+___
 
-### Definitions
-- `idx` - index of the current keeper in the network
-- `threshold` - threshold defined during shamir secret sharing
-- `parallelism` - number of parallel threads for keeper while broadcasts
-- `database-path` - path to the database file (!file)
-- `session` - session settings
-  - `gg20` - settings for GG20 session
-    - `expire` - expiration time of the session
-  - `frost` - settings for FROST session
-    - `expire` - expiration time of the session
-- `private-key` - Ed25519 private key of the keeper
-- `peers` - list of peers in the network
-  - `idx` - index of the peer
-  - `public-url` - public URL of the peer
-  - `public-key` - Ed25519 public key of the peer
-
-## CLI commands
-
-### Storing private key share
-```bash
-store <publicKeyId> <privateKeyShare> <relatedFullPublicKey>
-```
-
-### Deleting key share
-```bash
-delete <publicKeyId>
-```
-
-**NOTE**:
-All key share data should be specified in **Base64**
+## Documentation
+See [docs](docs) for detailed documentation on, or visit [docs.exploit.org/tkeeper](https://docs.exploit.org/tkeeper) for
+user-friendly documentation.

build.gradle

@@ -37,13 +37,13 @@ dependencies {
 
     implementation 'com.fasterxml.jackson.module:jackson-module-kotlin:2.18.3'
 
-    implementation 'org.exploit.tss:gg20:0.0.1-patch1'
-    implementation 'org.exploit.tss:frost:0.0.1-patch1'
+    implementation 'org.exploit.tss:gg20:0.0.2.4'
+    implementation 'org.exploit.tss:frost:0.0.2.4'
 
-    implementation 'org.exploit.tss:ed25519:0.0.1-patch1'
-    implementation 'org.exploit.tss:secp256k1:0.0.1-patch1'
+    implementation 'org.exploit.tss:ed25519:0.0.2.4'
+    implementation 'org.exploit.tss:secp256k1:0.0.2.4'
 
-    implementation 'org.exploit.tss:core:0.0.1-patch1'
+    implementation 'org.exploit.tss:core:0.0.2.4'
 
     implementation 'com.nimbusds:nimbus-jose-jwt:10.2'
 
@@ -61,7 +61,7 @@ dependencies {
 }
 
 group 'org.exploit'
-version '1.0-SNAPSHOT'
+version '0.0.1-SNAPSHOT'
 
 java {
     sourceCompatibility = JavaVersion.VERSION_17

docs/API.md

@@ -0,0 +1,164 @@
+# TKeeper API
+
+This document describes all public REST endpoints exposed by TKeeper.  
+Each endpoint enforces permission checks (see [auth.md](auth.md)) and assumes that the node is unsealed and ready, unless stated otherwise.
+
+---
+
+## Base Path
+
+```
+/v1/keeper
+```
+
+---
+
+## 1. System Control
+
+### `POST /system/init`
+
+Initializes TKeeper with the peer ID, threshold, and total number of nodes.
+
+- See: [init.md](init.md)
+
+### `PUT /system/unseal`
+
+Submits one or more Shamir shares to reconstruct the local key share (manual unseal).  
+Returns unsealing progress.
+
+- See: [seal.md](seal.md)
+
+### `PUT /system/seal`
+
+Seals the local key share, removing it from memory.  
+Used to force the node back into a locked state.
+
+- Permissions: `tkeeper.system.seal`
+
+### `GET /system/status`
+
+Returns current sealing status.
+
+```json
+{
+  "sealedBy": "shamir | aws | google",
+  "state": "UNINITIALIZED | SEALED | UNSEALED",
+  "progress": {
+    "threshold": 3,
+    "total": 5,
+    "progress": 2,
+    "ready": false
+  }
+}
+```
+
+---
+
+## 2. Key Generation
+
+### `POST /dkg/generate`
+
+Triggers distributed key generation (or key share refreshing).
+
+- Request body: see [keygen.md](keygen.md)
+- Supports:
+    - `overwrite: true` (requires `tkeeper.dkg.generate.overwrite`)
+    - `refresh: true` for share refreshing
+- Requires all peers to be online
+
+---
+
+## 3. Signatures
+
+### `POST /sign`
+
+Performs threshold signing using the specified key and MPC scheme.
+
+- Supports:
+    - `GG20` (1 operation max)
+    - `FROST` (multiple operations allowed)
+- See: [sign.md](sign.md)
+
+### `POST /sign/verify`
+
+Verifies a signature against a public key.
+
+- See: [sign.md](sign.md)
+
+---
+
+## 4. Public Interface
+
+### `GET /publicKey?keyId=...`
+
+Returns the public key for the given key ID.
+
+```json
+{
+  "data64": "base64-encoded public key"
+}
+```
+
+- Requires: `tkeeper.key.{keyId}.public`
+
+### `GET /peerId`
+
+Returns the current node’s `peerId`.
+
+```json
+{
+  "serviceId": 2,
+  "result": 2
+}
+```
+
+### `GET /ping`
+
+Returns basic readiness status:
+
+```json
+{
+  "ready": true
+}
+```
+
+- `true`: node is initialized and unsealed
+
+---
+
+## 5. Integrity
+
+### `POST /integrity/regen`
+
+Regenerates the internal integrity key used to authenticate internal peer-to-peer messages.  
+Used for re-keying or recovery.
+
+- Permission: `tkeeper.integrity.regen`
+
+---
+
+## 6. Storage (Trusted Dealer)
+
+### `POST /storage/store`
+
+Injects a full private key into the system. The current node acts as a **trusted dealer**, splits the key into Shamir shares, and distributes them to all online peers.
+
+- All nodes must be online during this operation
+- Each peer receives and stores only its own share
+- See: [store.md](store.md)
+- Permission: `tkeeper.storage.write`
+
+### `DELETE /storage/delete?keyId=...`
+
+Deletes the distributed key from **all peers**. The initiating node contacts every participant and removes the stored share.
+
+- All nodes must be online
+- If any peer is unreachable, the operation fails
+- Permission: `tkeeper.storage.delete`
+
+---
+
+## Permissions Overview
+
+Each endpoint requires a specific permission token.  
+For the full list and structure, refer to [auth.md](auth.md).