@derec-alliance/react-native 0.0.1

package/lib/protocol.js

@@ -0,0 +1,514 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 DeRec Alliance. All rights reserved.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeRecProtocol = exports.DeRecProtocolBuilder = void 0;
+exports.protocolDiscriminant = protocolDiscriminant;
+exports.buildProtectSecretParams = buildProtectSecretParams;
+exports.buildRestoreParams = buildRestoreParams;
+const codec_1 = require("./codec");
+const native_1 = require("./native");
+const primitives_1 = require("./primitives");
+const types_1 = require("./types");
+/**
+ * Event fields carrying `Vec<u8>`.
+ *
+ * `serde_json` writes them as arrays of decimal byte values, while
+ * {@link DeRecEvent} declares them `Uint8Array` — the shape
+ * `@derec-alliance/nodejs` produces, where `serde-wasm-bindgen` makes the
+ * conversion natively. Without the conversion below the declared type is a
+ * lie, and the first thing an application does with `ActionRequired.action` is
+ * hand it back to `accept()`, where the native layer reads `.buffer` off it
+ * and finds nothing.
+ *
+ * Unlike the message codec in `./messages`, ids are deliberately left alone:
+ * every id on an event is declared as a decimal `string`, not a `bigint`.
+ */
+const EVENT_BYTE_FIELDS = new Set([
+    'action',
+    'shared_key',
+    'committed_share',
+    'id',
+    'data',
+]);
+function reviveEventBytes(value) {
+    if (Array.isArray(value)) {
+        return value.map(reviveEventBytes);
+    }
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    const out = {};
+    for (const [key, field] of Object.entries(value)) {
+        out[key] =
+            EVENT_BYTE_FIELDS.has(key) && Array.isArray(field)
+                ? Uint8Array.from(field)
+                : reviveEventBytes(field);
+    }
+    return out;
+}
+function decodeEvents(buffer) {
+    return reviveEventBytes((0, codec_1.jsonFromBytes)(buffer));
+}
+/**
+ * Maps a transport protocol name to the `derec_proto::Protocol` discriminant.
+ * `bindings/test_fixture/enums.json` — the shared enum fixture every other
+ * numeric mapping in this SDK is read from — does not carry this enum (it
+ * only covers the Rust-internal serde enums listed under its `"enums"` key);
+ * the transport `Protocol` enum lives in `protobufs/transportprotocol.proto`
+ * instead, where only `HTTPS = 0` is currently defined.
+ */
+function protocolDiscriminant(protocol) {
+    switch (protocol.toLowerCase()) {
+        case 'https':
+            return 0;
+        default:
+            throw new Error(`DeRec: unknown transport protocol "${protocol}"`);
+    }
+}
+function encodeTarget(target) {
+    if (target === null) {
+        return null;
+    }
+    if (Array.isArray(target)) {
+        return target.map((id) => id.toString());
+    }
+    return target.toString();
+}
+/**
+ * `ProtectSecretParamsJson` (`library/src/interop/ffi/protocol/flow.rs`): every
+ * `UserSecret.id`/`.data` byte array travels as a bare JSON array of decimal
+ * byte values, matching `UserSecretJson`'s plain `Vec<u8>` fields — no
+ * base64, no wrapping.
+ *
+ * Exported so it can be golden-tested against
+ * `bindings/test_fixture/wire_golden.json` without a native module.
+ */
+function buildProtectSecretParams(params) {
+    const out = {
+        secrets: params.secrets.map((secret) => ({
+            id: Array.from(secret.id),
+            name: secret.name,
+            data: Array.from(secret.data),
+        })),
+    };
+    if (params.description !== undefined) {
+        out.description = params.description;
+    }
+    return out;
+}
+function communicationInfoOrOmit(info) {
+    return info !== undefined && Object.keys(info).length > 0 ? info : undefined;
+}
+/**
+ * `RestoreParamsJson` (`library/src/interop/ffi/protocol/handle/flow.rs`). Mirrors
+ * `SecretWire`'s own shape: `channel_id`/`replica_id` are the decimal `u64`
+ * strings the `SecretRecovered` event already carries, forwarded verbatim;
+ * `communication_info` is omitted per-entry (not sent as `{}`) whenever a
+ * helper or replica member has none, matching the Go SDK's `omitempty` and
+ * the shared golden fixture byte-for-byte; `replicas` is omitted entirely
+ * when the recovered secret has no replica group.
+ *
+ * Exported so it can be golden-tested against
+ * `bindings/test_fixture/wire_golden.json` without a native module.
+ */
+function buildRestoreParams(recoveredSecret, version) {
+    const recovered = {
+        helpers: recoveredSecret.helpers.map((helper) => {
+            const out = {
+                channel_id: helper.channel_id,
+                transport_uri: helper.transport_uri,
+                shared_key: Array.from(helper.shared_key),
+            };
+            const info = communicationInfoOrOmit(helper.communication_info);
+            if (info !== undefined) {
+                out.communication_info = info;
+            }
+            return out;
+        }),
+        secrets: recoveredSecret.secrets.map((secret) => ({
+            id: Array.from(secret.id),
+            name: secret.name,
+            data: Array.from(secret.data),
+        })),
+    };
+    if (recoveredSecret.replicas !== undefined) {
+        recovered.replicas = {
+            channel_id: recoveredSecret.replicas.channel_id,
+            members: recoveredSecret.replicas.members.map((member) => {
+                const out = {
+                    replica_id: member.replica_id,
+                    transport_uri: member.transport_uri,
+                    role: member.role,
+                };
+                const info = communicationInfoOrOmit(member.communication_info);
+                if (info !== undefined) {
+                    out.communication_info = info;
+                }
+                return out;
+            }),
+            shared_key: Array.from(recoveredSecret.replicas.shared_key),
+        };
+    }
+    return { version, recovered_secret: recovered };
+}
+/**
+ * `PairingParamsJson.contact` (`library/src/interop/ffi/protocol/flow.rs`) is a
+ * `Vec<u8>` of proto-encoded `ContactMessage` bytes, so the typed contact the
+ * caller holds is re-encoded through the library's own codec on the way in.
+ * Encoding in Rust also means the contact is structurally validated before
+ * the pairing flow ever sees it.
+ */
+function contactToByteArray(contact) {
+    return Array.from(primitives_1.primitives.pairing.request.encode_contact(contact));
+}
+function buildStartParams(flowKind, params) {
+    switch (flowKind) {
+        case types_1.FlowKind.Pairing: {
+            const p = params;
+            const out = {
+                kind: p.kind,
+                contact: contactToByteArray(p.contact),
+            };
+            if (p.peerCommunicationInfo !== undefined) {
+                out.peer_communication_info = p.peerCommunicationInfo;
+            }
+            return (0, codec_1.jsonToBytes)(out);
+        }
+        case types_1.FlowKind.Discovery: {
+            const p = (params ?? {});
+            const out = {};
+            if (p.target !== undefined) {
+                out.target = encodeTarget(p.target);
+            }
+            return (0, codec_1.jsonToBytes)(out);
+        }
+        case types_1.FlowKind.ProtectSecret:
+            return (0, codec_1.jsonToBytes)(buildProtectSecretParams(params));
+        case types_1.FlowKind.VerifyShares: {
+            const p = params;
+            const out = {
+                secret_id: p.secretId.toString(),
+                version: p.version,
+            };
+            if (p.target !== undefined) {
+                out.target = encodeTarget(p.target);
+            }
+            return (0, codec_1.jsonToBytes)(out);
+        }
+        case types_1.FlowKind.RecoverSecret: {
+            const p = params;
+            return (0, codec_1.jsonToBytes)({ secret_id: p.secretId.toString(), version: p.version });
+        }
+        case types_1.FlowKind.Unpair: {
+            const p = params;
+            const out = { channel_id: p.channel_id };
+            if (p.memo !== undefined) {
+                out.memo = p.memo;
+            }
+            return (0, codec_1.jsonToBytes)(out);
+        }
+        case types_1.FlowKind.UpdateChannelInfo: {
+            const p = (params ?? {});
+            const out = {};
+            if (p.target !== undefined) {
+                out.target = encodeTarget(p.target);
+            }
+            if (p.communication_info !== undefined) {
+                out.communication_info = p.communication_info;
+            }
+            if (p.transport_protocol !== undefined) {
+                out.transport_protocol = p.transport_protocol;
+            }
+            return (0, codec_1.jsonToBytes)(out);
+        }
+        case types_1.FlowKind.SyncCheck:
+            // No parameters: the group and this device's own version both come
+            // from the stores.
+            return (0, codec_1.jsonToBytes)({});
+        case types_1.FlowKind.RemoveReplica: {
+            const p = params;
+            const out = { replica_id: p.replica_id };
+            if (p.memo !== undefined) {
+                out.memo = p.memo;
+            }
+            return (0, codec_1.jsonToBytes)(out);
+        }
+        default: {
+            const exhaustive = flowKind;
+            throw new Error(`DeRec: unknown FlowKind ${exhaustive}`);
+        }
+    }
+}
+function toBigInt(id) {
+    return typeof id === 'bigint' ? id : BigInt(id);
+}
+/**
+ * Builder for {@link DeRecProtocol}, mirroring `@derec-alliance/nodejs`'s
+ * `DeRecProtocolBuilder` method-for-method. The config JSON shape is dictated
+ * by the Rust `ProtocolConfig` struct (`library/src/interop/ffi/protocol/handle/mod.rs`);
+ * every field here writes exactly the `snake_case` key that struct expects.
+ *
+ * Every value the caller supplies is forwarded verbatim — defaults, clamping
+ * and the meaning of a disabled cleanup policy are library decisions.
+ * `threshold`, `keep_versions_count`, `auto_respond_on_failure`,
+ * `unpair_ack`, `auto_reply_to` and `auto_accept` are omitted entirely from
+ * the emitted config unless their setter was called: `ProtocolConfig` has a
+ * `#[serde(default = "...")]` on each of them, reading the same constants
+ * `DeRecProtocolBuilder::new` uses, so an absent key resolves to the
+ * library's own default rather than one frozen into this shim.
+ */
+class DeRecProtocolBuilder {
+    constructor(secretId) {
+        this.config = {};
+        this.stores = {};
+        this.secretIdValue = BigInt(secretId);
+    }
+    withChannelStore(store) {
+        this.stores.channelStore = store;
+        return this;
+    }
+    withShareStore(store) {
+        this.stores.shareStore = store;
+        return this;
+    }
+    withSecretStore(store) {
+        this.stores.secretStore = store;
+        return this;
+    }
+    withUserSecretStore(store) {
+        this.stores.userSecretStore = store;
+        return this;
+    }
+    withStateStore(store) {
+        this.stores.stateStore = store;
+        return this;
+    }
+    withTransport(transport) {
+        this.stores.transport = transport;
+        return this;
+    }
+    withOwnTransport(endpoint) {
+        this.config.own_transport_uri = endpoint.uri;
+        this.config.own_transport_protocol = protocolDiscriminant(endpoint.protocol);
+        return this;
+    }
+    /** Default: 3. */
+    withThreshold(threshold) {
+        this.config.threshold = threshold;
+        return this;
+    }
+    /** Default: 3. */
+    withKeepVersionsCount(count) {
+        this.config.keep_versions_count = count;
+        return this;
+    }
+    /**
+     * Every field is optional; not calling this at all leaves all four at the
+     * library's defaults — `timeouts` is genuinely absent from the JSON in
+     * that case, not filled in with a synthesized object. Values are forwarded
+     * verbatim; `Timeouts`'s field names already match `TimeoutsConfig`'s
+     * `snake_case` keys one for one.
+     */
+    withTimeouts(timeouts) {
+        this.config.timeouts = { ...timeouts };
+        return this;
+    }
+    /** Default: false. */
+    withUnsafeHttp(allow) {
+        this.config.unsafe_http = allow;
+        return this;
+    }
+    /**
+     * Default: empty. `derec_protocol_new`'s own `communication_info` argument
+     * is a pre-encoded `CommunicationInfo` protobuf message, and this SDK has
+     * no encoder for that message — the C ABI exposes one only for
+     * `ContactMessage`. Hand-rolling one here would be SDK-side protocol logic
+     * with no test coverage — exactly what this codebase's "Rust decides, the
+     * SDK only marshals" rule forbids. Instead,
+     * `build()` constructs the protocol with an empty `communication_info`
+     * (a legitimate, always-accepted value — see `decode_communication_info`
+     * in `library/src/interop/ffi/protocol/handle/mod.rs`, which treats a zero-length
+     * buffer as "no entries") and then calls the already-bound
+     * {@link DeRecProtocol.setCommunicationInfo}, which takes the same map as
+     * plain JSON (`derec_protocol_set_communication_info` in
+     * `library/src/interop/ffi/protocol/handle/config.rs`). That setter is queued on
+     * the protocol's serial worker before `build()` returns, so it is ordered
+     * ahead of every call the caller can subsequently make.
+     */
+    withCommunicationInfo(info) {
+        this.communicationInfo = info;
+        return this;
+    }
+    /** Default: false. */
+    withAutoRespondOnFailure(enabled) {
+        this.config.auto_respond_on_failure = enabled;
+        return this;
+    }
+    /** Default: "required". */
+    withUnpairAck(ack) {
+        if (ack === 'required') {
+            this.config.unpair_ack = 0;
+        }
+        else if (ack === 'not_required') {
+            this.config.unpair_ack = 1;
+        }
+        else {
+            throw new Error(`DeRec: unknown unpair ack "${ack}"`);
+        }
+        return this;
+    }
+    /** Default: false. */
+    withAutoReplyTo(enabled) {
+        this.config.auto_reply_to = enabled;
+        return this;
+    }
+    /** Default: empty policy (every flow off). */
+    withAutoAccept(policy) {
+        this.config.auto_accept = {
+            pairing: policy.pairing ?? false,
+            pre_pair: policy.prePair ?? false,
+            store_share: policy.storeShare ?? false,
+            verify_share: policy.verifyShare ?? false,
+            discovery: policy.discovery ?? false,
+            get_share: policy.getShare ?? false,
+            unpair: policy.unpair ?? false,
+            update_channel_info: policy.updateChannelInfo ?? false,
+        };
+        return this;
+    }
+    /** Default: unset. */
+    withReplicaId(replicaId) {
+        this.config.replica_id = BigInt(replicaId).toString();
+        return this;
+    }
+    build() {
+        const config = {
+            secret_id: this.secretIdValue.toString(),
+            replica_id: null,
+            own_transport_uri: '',
+            own_transport_protocol: 0,
+            ...this.config,
+        };
+        const host = (0, native_1.getNative)().protocol_new(JSON.stringify(config), new Uint8Array(0), this.stores);
+        const protocol = DeRecProtocol.fromHost(host);
+        if (this.communicationInfo !== undefined) {
+            // `setCommunicationInfo` is asynchronous, but `build()` stays
+            // synchronous: the guarantee callers need is not that the map has been
+            // applied by the time `build()` returns, it is that no flow can run
+            // before it. Posting it here puts it on the protocol's serial worker
+            // queue ahead of anything the caller has had the chance to start, so
+            // every subsequent call observes it. Left unhandled deliberately — a
+            // failure reaches the runtime's unhandled-rejection reporting rather
+            // than being silently discarded, and `build()` has no synchronous
+            // channel to raise it on.
+            void protocol.setCommunicationInfo(this.communicationInfo);
+        }
+        return protocol;
+    }
+}
+exports.DeRecProtocolBuilder = DeRecProtocolBuilder;
+/**
+ * Thin wrapper around the `ProtocolHost` JSI host object, mirroring
+ * `@derec-alliance/nodejs`'s `DeRecProtocol` — same methods, and the same
+ * sync/async split except for `setCommunicationInfo` and `setOwnTransport`,
+ * which return a `Promise` here (see their own doc comments for why);
+ * `secretId` is synchronous and everything else returns a `Promise`. Every method encodes its
+ * arguments into the wire shape the host function expects and decodes its
+ * result back into the typed value declared here; no protocol decision is
+ * made in this class.
+ */
+class DeRecProtocol {
+    /** Use {@link DeRecProtocolBuilder} to construct instances. */
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * @internal Constructs an instance from a native `ProtocolHost`. Not part
+     * of the public surface — {@link DeRecProtocolBuilder.build} is the only
+     * caller. Exists because the constructor is `private` (matching
+     * `@derec-alliance/nodejs`'s `index.d.ts`), and a private constructor is
+     * only callable from within this class's own body, not from
+     * `DeRecProtocolBuilder`.
+     */
+    static fromHost(host) {
+        return new DeRecProtocol(host);
+    }
+    secretId() {
+        return this.host.secretId();
+    }
+    /**
+     * Returns a `Promise`, where `@derec-alliance/nodejs` declares this
+     * `void`. The native setter takes the same handle mutex a running flow
+     * holds across its store callbacks, so calling it on the JavaScript thread
+     * would block that thread until the flow released the mutex — which it
+     * cannot do while it is waiting on the JavaScript thread. The binding
+     * therefore queues the setter onto the same serial worker every flow runs
+     * on, which orders it after any call already in flight. The nodejs SDK is
+     * WASM and single-threaded, so it has no such hazard.
+     *
+     * Callers that ignore the result behave exactly as before, so this stays
+     * source-compatible with nodejs-shaped code; awaiting it additionally
+     * surfaces a failure that would otherwise be swallowed.
+     */
+    setCommunicationInfo(info) {
+        return this.host.setCommunicationInfo((0, codec_1.jsonToBytes)(info));
+    }
+    /** Returns a `Promise` for the same reason {@link setCommunicationInfo} does. */
+    setOwnTransport(uri, protocol) {
+        return this.host.setOwnTransport(uri, protocolDiscriminant(protocol));
+    }
+    /**
+     * Decodes the `contact_wire_bytes` `derec_protocol_create_contact`
+     * produces into a typed `ContactMessage`, so an application can read the
+     * contact's `nonce`, `transport_protocol` and mode without a protobuf
+     * codec of its own. Feed the returned object straight back into
+     * `start(FlowKind.Pairing, { contact })`, which re-encodes it.
+     */
+    async createContact(channelId, contactMode, nonce) {
+        const hasChannelId = channelId !== null && channelId !== undefined ? 1 : 0;
+        const hasNonce = nonce !== null && nonce !== undefined ? 1 : 0;
+        const buffer = (await this.host.createContact(hasChannelId, toBigInt(channelId ?? 0), contactMode, hasNonce, toBigInt(nonce ?? 0)));
+        return primitives_1.primitives.pairing.request.decode_contact(new Uint8Array(buffer));
+    }
+    async start(flowKind, params) {
+        const paramsBytes = buildStartParams(flowKind, params);
+        const buffer = (await this.host.start(flowKind, paramsBytes));
+        return decodeEvents(buffer);
+    }
+    async process(message) {
+        const buffer = (await this.host.process(message));
+        return decodeEvents(buffer);
+    }
+    async tick() {
+        const buffer = (await this.host.tick());
+        return decodeEvents(buffer);
+    }
+    async accept(actionBytes) {
+        const buffer = (await this.host.accept(actionBytes));
+        return decodeEvents(buffer);
+    }
+    async reject(actionBytes, status, memo) {
+        await this.host.reject(actionBytes, status, memo);
+    }
+    async getFingerprint(channelId) {
+        return (await this.host.getFingerprint(toBigInt(channelId)));
+    }
+    async verifyFingerprint(channelId, fingerprint) {
+        return (await this.host.verifyFingerprint(toBigInt(channelId), fingerprint));
+    }
+    async removeExpiredChannels(olderThanSecs) {
+        const buffer = (await this.host.removeExpiredChannels(olderThanSecs));
+        return (0, codec_1.jsonFromBytes)(buffer);
+    }
+    async restore(recoveredSecret, version) {
+        const params = buildRestoreParams(recoveredSecret, version);
+        const buffer = (await this.host.restore((0, codec_1.jsonToBytes)(params)));
+        return decodeEvents(buffer);
+    }
+    /** Release the native handle. Safe to call more than once. */
+    free() {
+        this.host.free();
+    }
+}
+exports.DeRecProtocol = DeRecProtocol;