@derec-alliance/nodejs 0.0.1-alpha.10

package/derec_library.d.ts

@@ -0,0 +1,466 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Fluent builder for [`DeRecProtocolWasm`]. Mirrors the Rust
+ * [`crate::protocol::DeRecProtocolBuilder`] and the dotnet
+ * `DeRecProtocolBuilder` method-for-method so a developer who already
+ * knows one SDK can move between them without reaching for reference
+ * docs.
+ *
+ * Required setters: `withChannelStore`, `withShareStore`,
+ * `withSecretStore`, `withTransport`, `withOwnTransport`. Calling
+ * `build()` without all five throws.
+ *
+ * All optional setters carry the defaults documented on the Rust
+ * builder.
+ */
+export class DeRecProtocolBuilder {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Finalize the configuration. Throws if any of the required
+     * setters was not called.
+     */
+    build(): DeRecProtocolWasm;
+    /**
+     * `secretId` is a JS `bigint` or `number`. Identifies the single
+     * secret this protocol instance manages; apps that juggle multiple
+     * secrets instantiate one protocol per id.
+     */
+    constructor(secret_id: any);
+    /**
+     * Per-flow auto-accept policy.
+     *
+     * `policy` shape (all fields optional, default `false`):
+     * `{ pairing, prePair, storeShare, verifyShare, discovery, getShare, unpair, updateChannelInfo }`.
+     *
+     * When a field is `true`, `process()` internally accepts the
+     * matching incoming request and emits an `AutoAccepted` event in
+     * place of `ActionRequired`. See the Rust-side
+     * `AutoAcceptPolicy` rustdoc for the per-flow trade-offs.
+     * Default: every field `false`.
+     */
+    withAutoAccept(policy: any): DeRecProtocolBuilder;
+    /**
+     * Whether outbound requests stamp `replyTo = ownTransport`.
+     * Default: false.
+     */
+    withAutoReplyTo(enabled: boolean): DeRecProtocolBuilder;
+    /**
+     * Whether the protocol auto-replies on failed inbound processing.
+     * Default: false.
+     */
+    withAutoRespondOnFailure(enabled: boolean): DeRecProtocolBuilder;
+    withChannelStore(store: any): DeRecProtocolBuilder;
+    /**
+     * `info` shape: `Record<string, string>`. Default: empty.
+     */
+    withCommunicationInfo(info: any): DeRecProtocolBuilder;
+    /**
+     * Number of recent versions each helper must retain. Default: 3.
+     */
+    withKeepVersionsCount(count: number): DeRecProtocolBuilder;
+    /**
+     * `endpoint` shape: `{ uri: string, protocol: string }`.
+     * `protocol` must be `"https"` (the only protocol supported today).
+     */
+    withOwnTransport(endpoint: any): DeRecProtocolBuilder;
+    /**
+     * Declare the local node's acceptable parameter range for pair
+     * negotiation. `range` is a JS object whose keys mirror the
+     * `ParameterRange` proto (`minShareSize`, `maxShareSize`,
+     * `minTimeBetweenVerifications`, ...). Each field is `i64` —
+     * accept either a number or a `BigInt` on the JS side. Default:
+     * unset (no constraints advertised, every peer range accepted).
+     */
+    withParameterRange(range: any): DeRecProtocolBuilder;
+    /**
+     * `id` is a JS `bigint` or `number`. Default: unset.
+     */
+    withReplicaId(id: any): DeRecProtocolBuilder;
+    withSecretStore(store: any): DeRecProtocolBuilder;
+    withShareStore(store: any): DeRecProtocolBuilder;
+    withStateStore(store: any): DeRecProtocolBuilder;
+    /**
+     * Minimum number of shares required to reconstruct the secret.
+     * Default: 3.
+     */
+    withThreshold(threshold: number): DeRecProtocolBuilder;
+    /**
+     * 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.
+     */
+    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;
+}
+
+/**
+ * Higher-level DeRec protocol orchestrator for TypeScript/JavaScript consumers.
+ *
+ * Wraps [`DeRecProtocol`](crate::protocol::DeRecProtocol) with JS-side store
+ * and transport adapters so that a TypeScript application can drive all five
+ * protocol flows without routing raw bytes manually.
+ *
+ * # Stores
+ *
+ * Pass four JS objects that implement the interfaces documented on each
+ * parameter.  All store methods must return `Promise`s — synchronous
+ * implementations can wrap their result with `Promise.resolve(...)`.
+ *
+ * # Events
+ *
+ * [`process`](DeRecProtocolWasm::process) returns an `Array` of plain JS
+ * objects, each with a `type` discriminant field:
+ *
+ * | `type`             | Additional fields                                      |
+ * |--------------------|--------------------------------------------------------|
+ * | `PairingCompleted`  | `channel_id: string`, `pairing_channel_id: string`, `kind: number` |
+ * | `ShareStored`      | `channel_id: string`, `version: number`                |
+ * | `ShareConfirmed`   | `channel_id: string`, `version: number`                |
+ * | `ShareVerified`    | `channel_id: string`, `version: number`                |
+ * | `SecretsDiscovered`| `channel_id: string`, `secrets: SecretVersionEntry[]`  |
+ * | `SecretRecovered`  | `secret: { helpers, secrets, replicas }` (same nested shape as `ReplicaSecretReceived.secret`) |
+ * | `NoOp`             | _(none)_                                               |
+ *
+ * `SecretVersionEntry = { secret_id: bigint, versions: { version: number, description: string }[] }`
+ */
+export class DeRecProtocolWasm {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Accept a pending action from an `ActionRequired` event.
+     *
+     * # Arguments
+     *
+     * * `action_bytes` — Opaque `Uint8Array` from the `action` field of an `ActionRequired` event.
+     *
+     * # Returns
+     *
+     * An `Array` of event objects (same format as `process()`).
+     */
+    accept(action_bytes: Uint8Array): Promise<any>;
+    /**
+     * Single entry point for all three contact modes (`InlineKeys`,
+     * `HashedKeys`, `NoKeys`).
+     *
+     * * `channel_id` — `null`/`undefined` lets the library mint a
+     *   random id; otherwise `bigint` / `number` is used verbatim.
+     * * `contact_mode` — `0` (InlineKeys), `1` (HashedKeys), `2` (NoKeys).
+     * * `nonce` — `null`/`undefined` lets the library generate a fresh
+     *   random `u64`; otherwise the supplied `bigint`/`number` is used.
+     *   Required for `NoKeys` where callers typically pick a small
+     *   human-typable value.
+     */
+    createContact(channel_id: any, contact_mode: number, nonce: any): Promise<any>;
+    /**
+     * Derive the human-readable fingerprint for a paired channel. Both
+     * sides of a replica pair derive the same fingerprint from the
+     * shared key, enabling out-of-band confirmation before the channel
+     * transitions from `Pending` to `Paired`.
+     */
+    getFingerprint(channel_id: any): Promise<string>;
+    /**
+     * Feed any incoming wire bytes to the protocol.
+     *
+     * Returns an `Array` of plain JS event objects (see struct-level docs for shapes).
+     * Every inbound flow — pairing, sharing, verification, discovery,
+     * recovery, unpairing, channel-info updates and the replica flows — is
+     * handled through this single entry point.
+     *
+     * # Arguments
+     *
+     * * `message` — Raw wire bytes of an incoming `DeRecMessage`.
+     */
+    process(message: Uint8Array): Promise<any>;
+    /**
+     * Reject a pending action from an `ActionRequired` event.
+     *
+     * # Arguments
+     *
+     * * `action_bytes` — Opaque `Uint8Array` from the `action` field of an `ActionRequired` event.
+     * * `status` — Numeric status code from `StatusEnum` (e.g. 2 for FAIL, 10 for REJECTED).
+     * * `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`] —
+     * see that method for the full contract.
+     *
+     * `recoveredSecret` is the typed `Secret` object carried by the
+     * `SecretRecovered` event; pass it verbatim.
+     *
+     * Errors surface as structured JS errors with a `code` field:
+     *
+     * | code               | meaning                                                          |
+     * |--------------------|------------------------------------------------------------------|
+     * | `ALREADY_RESTORED` | A user-secret snapshot already exists for this `secret_id`.      |
+     * | `CONFLICT`         | Channels live at canonical helper / replica ids. The error       |
+     * |                    | carries `channel_ids: string[]` listing the collisions.          |
+     * | `INVARIANT`        | The recovered `Secret` is internally inconsistent.               |
+     * | `STORAGE`          | A store I/O call failed mid-restore.                             |
+     */
+    restore(recovered_secret: any, version: number): Promise<any>;
+    /**
+     * Generate an out-of-band contact message (QR code payload, deep link, …).
+     *
+     * Returns a plain JS `ContactMessage` object. The `channel_id` field identifies
+     * the pairing session and will match the `channel_id` in the eventual
+     * `PairingCompleted` event — read it directly from the returned object.
+     *
+     * The caller is responsible for serializing the contact for out-of-band
+     * delivery (QR code, deep link, etc.). The peer passes the deserialized object
+     * to [`start`](Self::start) with `FlowKind::Pairing`.
+     *
+     * # Arguments
+     *
+     * * `channel_id` — Optional `BigInt` channel identifier. Pass `null` or
+     *   `undefined` to have the library generate a random one.
+     * * `contact_mode` — `0` for `InlineKeys` (keys embedded directly), `1`
+     *   for `HashedKeys` (contact carries only a SHA-384 binding hash; the
+     *   scanner fetches keys via a `PrePair` round-trip). `HashedKeys`
+     *   requires the protocol's `own_transport` to be ephemeral.
+     * The secret identifier this protocol instance is bound to.
+     */
+    secretId(): bigint;
+    /**
+     * Replace this node's local communication info. Does not contact peers —
+     * follow up with a `start(UpdateChannelInfo, ...)` to propagate.
+     */
+    setCommunicationInfo(info: any): void;
+    /**
+     * Replace this node's local transport endpoint. See
+     * `setCommunicationInfo` for the matching update-propagation flow.
+     * IMPORTANT: keep the old endpoint operational during the changeover —
+     * see the Rust docs on `set_own_transport` for the discipline.
+     */
+    setOwnTransport(uri: string, protocol: string): void;
+    /**
+     * Unified entry point for initiating any protocol flow.
+     *
+     * # Arguments
+     *
+     * * `flow_kind` — Flow discriminant:
+     *   - `0` = Pairing (params: `{ kind: number, contact: ContactMessage, name?: string }`)
+     *   - `1` = Discovery (params: `{ target: BigInt | BigInt[] | null }`)
+     *   - `2` = ProtectSecret (params: `{ secrets: UserSecret[], description?: string }`)
+     *   - `3` = VerifyShares (params: `{ version: number, target: BigInt | BigInt[] | null }`)
+     *   - `4` = RecoverSecret (params: `{ secretId: Uint8Array, version: number }`)
+     *
+     * # Returns
+     *
+     * An `Array` of `*Started` / `*Failed` events describing the
+     * 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
+     * `true` when the fingerprint matches and the channel is confirmed,
+     * `false` otherwise.
+     */
+    verifyFingerprint(channel_id: any, fingerprint: string): Promise<boolean>;
+}
+
+export function discovery_request_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function discovery_request_produce(channel_id: bigint, shared_key: Uint8Array, reply_to: any): any;
+
+export function discovery_response_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function discovery_response_process(response: any): any;
+
+export function discovery_response_produce(channel_id: bigint, secret_list: any, shared_key: Uint8Array): any;
+
+/**
+ * Overwrite `trace_id` on a primitive-produced envelope and return the
+ * re-encoded bytes. The outer envelope is plaintext, so this does no
+ * crypto work.
+ *
+ * Useful for consumers driving the protocol through primitives directly
+ * (the orchestrator-level `DeRecProtocol` already handles trace_id
+ * end-to-end on its own).
+ */
+export function envelope_apply_trace_id(envelope_bytes: Uint8Array, trace_id: bigint): Uint8Array;
+
+/**
+ * Read `trace_id` off an inbound envelope without touching the encrypted
+ * inner payload. Returns `0` when the sender didn't set one — the protobuf
+ * default is indistinguishable from an explicit zero.
+ */
+export function envelope_read_trace_id(envelope_bytes: Uint8Array): bigint;
+
+/**
+ * Structurally validate a JS-side [`ContactMessage`]. Throws on any
+ * mode/field inconsistency (unknown `contact_mode`, mode/field mismatch,
+ * wrong binding-hash length).
+ */
+export function pairing_contact_message_validate(contact_message: any): void;
+
+export function pairing_request_create_contact(channel_id: bigint, contact_mode: number, transport_protocol: any, nonce: any): any;
+
+/**
+ * Decodes a proto-encoded [`ContactMessage`]. Structurally validates the
+ * decoded value before returning it to application code so consumers can
+ * trust the mode/field invariants documented on the wire format.
+ */
+export function pairing_request_decode_contact(bytes: Uint8Array): any;
+
+/**
+ * Encodes a [`ContactMessage`] to proto wire bytes. Structurally validates
+ * the input first so a locally-constructed contact that violates the
+ * mode/field invariant is rejected at the boundary rather than silently
+ * serialized.
+ */
+export function pairing_request_encode_contact(contact_message: any): Uint8Array;
+
+export function pairing_request_extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): any;
+
+/**
+ * Initiator-side: decode an inbound plaintext `PrePairRequest` envelope.
+ */
+export function pairing_request_extract_pre_pair(envelope_bytes: Uint8Array): any;
+
+export function pairing_request_produce(kind: number, transport_protocol: any, contact_message: any, communication_info: any, parameter_range: any): any;
+
+/**
+ * Scanner-side: build the plaintext `PrePairRequest` envelope for a
+ * `HASHED_KEYS` contact.
+ */
+export function pairing_request_produce_pre_pair(transport_protocol: any, contact_message: any): any;
+
+export function pairing_response_extract(envelope_bytes: Uint8Array, secret_key: Uint8Array): any;
+
+/**
+ * Scanner-side: decode the inbound plaintext `PrePairResponse` envelope.
+ */
+export function pairing_response_extract_pre_pair(envelope_bytes: Uint8Array): any;
+
+export function pairing_response_process(contact_message: any, response: any, secret_key: Uint8Array): any;
+
+/**
+ * Scanner-side: validate the `PrePairResponse` against the contact's
+ * SHA-384 binding hash. Returns the validated keys + nonce on match.
+ */
+export function pairing_response_process_pre_pair(contact_message: any, response: any): any;
+
+export function pairing_response_produce(channel_id: bigint, request: any, secret_key: Uint8Array, communication_info: any, parameter_range: any): any;
+
+/**
+ * Contact-creator side: publish the actual public keys back to the scanner.
+ */
+export function pairing_response_produce_pre_pair(channel_id: bigint, request: any, secret_key: Uint8Array): any;
+
+export function recovery_request_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function recovery_request_produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to: any): any;
+
+export function recovery_response_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function recovery_response_produce(channel_id: bigint, request: any, stored_share_request: any, shared_key: Uint8Array): any;
+
+export function recovery_response_recover(secret_id: bigint, version: number, responses: any): any;
+
+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): any;
+
+export function sharing_request_split(channels: any, secret_id: bigint, version: number, secret_data: Uint8Array, threshold: number): any;
+
+export function sharing_response_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function sharing_response_process(version: number, response: any): void;
+
+export function sharing_response_produce(channel_id: bigint, request: any, shared_key: Uint8Array): any;
+
+export function unpairing_request_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function unpairing_request_produce(channel_id: bigint, memo: string, shared_key: Uint8Array, reply_to: any): any;
+
+export function unpairing_response_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function unpairing_response_process(response: any): any;
+
+export function unpairing_response_produce(channel_id: bigint, shared_key: Uint8Array): any;
+
+export function verification_request_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+export function verification_request_produce(channel_id: bigint, secret_id: bigint, version: number, shared_key: Uint8Array, reply_to: any): any;
+
+export function verification_response_extract(envelope_bytes: Uint8Array, shared_key: Uint8Array): any;
+
+/**
+ * Verify a `VerifyShareResponseMessage` against the originating
+ * `VerifyShareRequestMessage` and the expected share content.
+ *
+ * `request` must be the request the **owner** previously produced for
+ * this challenge (kept by the caller in a per-`channel_id` pending-
+ * verification map). The primitive rejects any response whose
+ * `(nonce, secret_id, version)` triple doesn't match — that's the
+ * anti-replay gate.
+ */
+export function verification_response_process(request: any, response: any, share_content: Uint8Array): boolean;
+
+export function verification_response_produce(channel_id: bigint, request: any, shared_key: Uint8Array, share_content: Uint8Array): any;
+
+export function wasm_start(): void;