@derec-alliance/nodejs 0.0.1-alpha.8 → 0.0.1

package/README.md

@@ -318,6 +318,13 @@ for (const ev of events) {
 Errors surface as objects with a `code` field — `ALREADY_RESTORED`,
 `CONFLICT` (with `channel_ids`), `INVARIANT`, or `STORAGE`.
 
+> **Secret format:** the recoverable secret (the bytes helpers store and
+> recovery reconstructs) is `[version byte] · payload` — v1's payload is
+> **gzip (RFC 1952)** compressed **JSON**, with byte fields as **standard
+> base64 with padding (RFC 4648 §4)** and `u64` fields as decimal strings.
+> See the `derec-library` `protocol::types::secret` reference documentation
+> for the full field schema.
+
 ---
 
 ## Verification Flow

package/derec_library.d.ts

@@ -88,15 +88,42 @@ export class DeRecProtocolBuilder {
      */
     withThreshold(threshold: number): DeRecProtocolBuilder;
     /**
-     * Protocol-wide staleness boundary (seconds). Clamped to at least
-     * 1. Default: 300.
+     * Configure the four waiting periods in one call.
+     *
+     * Object shape — every field optional, and **absent means "keep the
+     * library default"**:
+     *
+     * ```text
+     * {
+     *   inbound_message_secs?: number,   // staleness / replay window
+     *   sharing_round_secs?:   number,
+     *   unpair_ack_secs?:      number,
+     *   expired_channels?:     { enabled: boolean, timeout_in_secs: number },
+     * }
+     * ```
+     *
+     * Values are forwarded verbatim; clamping and the meaning of a disabled
+     * `expired_channels` are library decisions, not this shim's. Not calling
+     * this leaves every default in force.
      */
-    withTimeout(timeout_in_secs: number): DeRecProtocolBuilder;
+    withTimeouts(timeouts: any): DeRecProtocolBuilder;
     withTransport(transport: any): DeRecProtocolBuilder;
     /**
      * `ack` is `"required"` (default) or `"not_required"`.
      */
     withUnpairAck(ack: string): DeRecProtocolBuilder;
+    /**
+     * Accept plaintext `http://` transport endpoints. **Development only.**
+     * Default `false`.
+     *
+     * With it `false`, plaintext is accepted only for an endpoint this
+     * device configured for *itself* that names loopback (`localhost`,
+     * `127.0.0.1`, `::1`) — so a local dev server needs no configuration.
+     * With it `true`, plaintext is accepted for any host on any path,
+     * including endpoints a peer supplies. That is what makes the LAN case
+     * work (a phone against a laptop), and why the name is blunt.
+     */
+    withUnsafeHttp(allow: boolean): DeRecProtocolBuilder;
     withUserSecretStore(store: any): DeRecProtocolBuilder;
 }
 
@@ -125,7 +152,7 @@ export class DeRecProtocolBuilder {
  * | `ShareConfirmed`   | `channel_id: string`, `version: number`                |
  * | `ShareVerified`    | `channel_id: string`, `version: number`                |
  * | `SecretsDiscovered`| `channel_id: string`, `secrets: SecretVersionEntry[]`  |
- * | `SecretRecovered`  | `secret: { helpers, secrets, replicas, owner_replica_id }` (same nested shape as `ReplicaSecretReceived.secret`) |
+ * | `SecretRecovered`  | `secret: { helpers, secrets, replicas }` (same nested shape as `ReplicaSecretReceived.secret`) |
  * | `NoOp`             | _(none)_                                               |
  *
  * `SecretVersionEntry = { secret_id: bigint, versions: { version: number, description: string }[] }`
@@ -170,7 +197,8 @@ export class DeRecProtocolWasm {
      * Feed any incoming wire bytes to the protocol.
      *
      * Returns an `Array` of plain JS event objects (see struct-level docs for shapes).
-     * All five flows (pairing, sharing, verification, discovery, recovery) are
+     * Every inbound flow — pairing, sharing, verification, discovery,
+     * recovery, unpairing, channel-info updates and the replica flows — is
      * handled through this single entry point.
      *
      * # Arguments
@@ -188,6 +216,20 @@ export class DeRecProtocolWasm {
      * * `memo` — Human-readable rejection reason.
      */
     reject(action_bytes: Uint8Array, status: number, memo: string): Promise<void>;
+    /**
+     * Remove `Pending` channels older than `older_than_secs`, along with
+     * their pairing keys.
+     *
+     * Independent of the configured cleanup policy — it sweeps at the
+     * threshold given, even when the policy is disabled. The age
+     * comparison is strict, so a channel created within the current
+     * second survives even `0`.
+     *
+     * # Returns
+     *
+     * An `Array` of removed channel ids as decimal strings.
+     */
+    removeExpiredChannels(older_than_secs: number): Promise<any>;
     /**
      * Rebuild this protocol's `secret_id` namespace from a recovered
      * `Secret`. Mirrors [`crate::protocol::DeRecProtocol::restore`] —
@@ -259,6 +301,18 @@ export class DeRecProtocolWasm {
      * dispatched requests. Same shape as `process()`.
      */
     start(flow_kind: number, params: any): Promise<any>;
+    /**
+     * Advance time-driven state without an inbound message.
+     *
+     * Timeouts are otherwise only evaluated by `process`, so a publish whose
+     * helpers all go quiet has nothing left to close it. Call this from a
+     * timer — `setInterval`, a service-worker alarm, a job runner — at an
+     * interval shorter than the configured timeout.
+     *
+     * Returns an `Array` of plain JS event objects, empty when nothing was
+     * in flight. Safe to call at any time.
+     */
+    tick(): Promise<any>;
     /**
      * Verify a fingerprint against the channel's locally-derived one. On
      * match, the channel transitions from `Pending` to `Paired`. Returns
@@ -369,7 +423,7 @@ export function recovery_response_recover(secret_id: bigint, version: number, re
 
 export function sharing_request_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
 
-export function sharing_request_produce(channel_id: bigint, version: number, secret_id: bigint, committed_share: any, keep_list: any, description: string, shared_key: Uint8Array, reply_to: any, replica_id: any): any;
+export function sharing_request_produce(channel_id: bigint, version: number, secret_id: bigint, committed_share: any, keep_list: any, description: string, shared_key: Uint8Array, reply_to: any): any;
 
 export function sharing_request_split(channels: any, secret_id: bigint, version: number, secret_data: Uint8Array, threshold: number): any;