@peers-app/peers-sdk 0.23.13 → 0.24.0

package/dist/device-pairing/types.js

@@ -1,36 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.devicePairingStateSchema = exports.devicePairingPhaseSchema = exports.signedPairingInstallationReceiptSchema = exports.pairingInstallationReceiptContentsSchema = exports.pairingCredentialEnvelopeSchema = exports.pairingCredentialContentsSchema = exports.signedPairingApprovalSchema = exports.pairingApprovalContentsSchema = exports.pairingDescriptionSchema = exports.pairingDevicePresentationSchema = exports.devicePairingTranscriptSchema = exports.devicePairingIceServersAckSchema = exports.devicePairingRoomReadyAckSchema = exports.devicePairingSignalingAckSchema = exports.devicePairingSignalingErrorCodeSchema = exports.devicePairingDeleteRoomRequestSchema = exports.devicePairingJoinRoomRequestSchema = exports.devicePairingCreateRoomRequestSchema = exports.pairingSignalSchema = exports.unsignedPairingSignalSchema = exports.pairingIceServerSchema = exports.pairingIceCandidateSchema = exports.pairingSessionDescriptionSchema = exports.devicePairingInvitationSchema = exports.pairingRoleSchema = exports.pairingEndpointNonceSchema = exports.pairingHashSchema = exports.pairingRoomSecretSchema = exports.pairingRoomIdSchema = void 0;
+exports.devicePairingStateSchema = exports.devicePairingPhaseSchema = exports.signedPairingInstallationReceiptSchema = exports.pairingInstallationReceiptContentsSchema = exports.pairingCredentialEnvelopeSchema = exports.pairingCredentialContentsSchema = exports.pairingConfirmationSchema = exports.pairingConfirmationContentsSchema = exports.pairingDevicePresentationSchema = exports.devicePairingTranscriptSchema = exports.devicePairingIceServersAckSchema = exports.devicePairingRoomReadyAckSchema = exports.devicePairingRoomCreatedAckSchema = exports.devicePairingSignalingAckSchema = exports.devicePairingSignalingErrorCodeSchema = exports.devicePairingDeleteRoomRequestSchema = exports.devicePairingJoinRoomRequestSchema = exports.devicePairingCreateRoomRequestSchema = exports.pairingSignalSchema = exports.authenticatedPairingSignalSchema = exports.unsignedPairingSignalSchema = exports.pairingPakeSignalSchema = exports.pairingIceServerSchema = exports.pairingIceCandidateSchema = exports.pairingTransportChoiceSchema = exports.pairingTransportOptionsSchema = exports.pairingWebSocketUrlSchema = exports.pairingTransportSchema = exports.pairingSessionDescriptionSchema = exports.pairingRendezvousSchema = exports.pairingServiceOriginSchema = exports.pairingRoleSchema = exports.pairingNameplateSchema = exports.pairingPakeShareSchema = exports.pairingEndpointNonceSchema = exports.pairingHashSchema = void 0;
 const zod_1 = require("zod");
 const devices_1 = require("../data/devices");
 const zod_types_1 = require("../types/zod-types");
 const constants_1 = require("./constants");
 const base64UrlSchema = zod_1.z.string().regex(/^[A-Za-z0-9_-]+$/);
-/** A random 128-bit pairing-room identifier encoded as unpadded base64url. */
-exports.pairingRoomIdSchema = base64UrlSchema.length(22);
-/** A random 256-bit pairing-room secret encoded as unpadded base64url. */
-exports.pairingRoomSecretSchema = base64UrlSchema.length(43);
-/** A SHA-256 value encoded as unpadded base64url. */
+/** A SHA-256 value or 256-bit key encoded as unpadded base64url. */
 exports.pairingHashSchema = base64UrlSchema.length(43);
 /** A random 256-bit endpoint nonce encoded as unpadded base64url. */
 exports.pairingEndpointNonceSchema = base64UrlSchema.length(43);
+/** A 32-byte X25519 PAKE public share encoded as unpadded base64url. */
+exports.pairingPakeShareSchema = base64UrlSchema.length(43);
+/** Small integer that names a signaling room; the first element of a pairing code. */
+exports.pairingNameplateSchema = zod_1.z.number().int().min(1).max(constants_1.DEVICE_PAIRING_MAX_NAMEPLATE);
 /** Source and destination roles in a two-party pairing room. */
 exports.pairingRoleSchema = zod_1.z.enum(["source", "destination"]);
-/** Versioned invitation shared out-of-band from the signed-in source. */
-exports.devicePairingInvitationSchema = zod_1.z
+/** HTTP(S) origin of the signaling service without a path. */
+exports.pairingServiceOriginSchema = zod_1.z
+    .string()
+    .url()
+    .max(2048)
+    .refine((value) => {
+    const url = new URL(value);
+    return (url.protocol === "https:" || url.protocol === "http:") && url.origin === value;
+}, "Expected an HTTP(S) origin without a path");
+/** Established rendezvous shared by both endpoints once the room exists. */
+exports.pairingRendezvousSchema = zod_1.z
     .object({
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    roomId: exports.pairingRoomIdSchema,
-    roomSecret: exports.pairingRoomSecretSchema,
+    serviceOrigin: exports.pairingServiceOriginSchema,
+    nameplate: exports.pairingNameplateSchema,
     expiresAt: zod_1.z.number().int().positive(),
-    serviceOrigin: zod_1.z
-        .string()
-        .url()
-        .max(2048)
-        .refine((value) => {
-        const url = new URL(value);
-        return (url.protocol === "https:" || url.protocol === "http:") && url.origin === value;
-    }, "Expected an HTTP(S) origin without a path"),
 })
     .strict();
 /** WebRTC session description carried inside an authenticated signaling message. */
@@ -41,9 +42,56 @@ exports.pairingSessionDescriptionSchema = zod_1.z
         .string()
         .min(1)
         .max(64 * 1024),
+})
+    .strict();
+/** Data transports a pairing ceremony can negotiate after the PAKE. */
+exports.pairingTransportSchema = zod_1.z.enum(["wrtc", "ws"]);
+/** Socket.IO URL a destination hosts for the direct WebSocket transport. */
+exports.pairingWebSocketUrlSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine((value) => {
+    try {
+        const url = new URL(value);
+        return ["http:", "https:", "ws:", "wss:"].includes(url.protocol) && url.hostname.length > 0;
+    }
+    catch {
+        return false;
+    }
+}, "Expected an http(s) or ws(s) URL");
+/**
+ * Destination's transport options, sent right after both PAKE shares. `websocket.urls` are the
+ * Socket.IO origins the destination is listening on for a source that can reach them directly.
+ */
+exports.pairingTransportOptionsSchema = zod_1.z
+    .object({
     endpointNonce: exports.pairingEndpointNonceSchema,
+    webrtc: zod_1.z.boolean(),
+    websocket: zod_1.z
+        .object({
+        urls: zod_1.z.array(exports.pairingWebSocketUrlSchema).min(1).max(constants_1.DEVICE_PAIRING_MAX_WEBSOCKET_URLS),
+    })
+        .strict()
+        .optional(),
 })
     .strict();
+/** Source's transport choice; `url` is the destination URL it connected to for `ws`. */
+exports.pairingTransportChoiceSchema = zod_1.z.discriminatedUnion("selected", [
+    zod_1.z
+        .object({
+        endpointNonce: exports.pairingEndpointNonceSchema,
+        selected: zod_1.z.literal("wrtc"),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        endpointNonce: exports.pairingEndpointNonceSchema,
+        selected: zod_1.z.literal("ws"),
+        url: exports.pairingWebSocketUrlSchema,
+    })
+        .strict(),
+]);
 /** ICE candidate carried inside an authenticated signaling message. */
 exports.pairingIceCandidateSchema = zod_1.z
     .object({
@@ -70,84 +118,99 @@ exports.pairingIceServerSchema = zod_1.z
     (value.username !== undefined && value.credential !== undefined), "TURN username and credential must be supplied together");
 const pairingSignalBase = {
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    roomId: exports.pairingRoomIdSchema,
+    nameplate: exports.pairingNameplateSchema,
     senderRole: exports.pairingRoleSchema,
     sequence: zod_1.z.number().int().positive(),
 };
-/** Unsigned offer, answer, or ICE message before its signaling MAC is attached. */
+/** PAKE share exchanged before any key exists; it is not MACed and carries no secrets. */
+exports.pairingPakeSignalSchema = zod_1.z
+    .object({
+    ...pairingSignalBase,
+    kind: zod_1.z.literal("pake"),
+    payload: zod_1.z.object({ share: exports.pairingPakeShareSchema }).strict(),
+})
+    .strict();
+const unsignedTransportOptionsSignal = zod_1.z
+    .object({
+    ...pairingSignalBase,
+    kind: zod_1.z.literal("transport-options"),
+    payload: exports.pairingTransportOptionsSchema,
+})
+    .strict();
+const unsignedTransportChoiceSignal = zod_1.z
+    .object({
+    ...pairingSignalBase,
+    kind: zod_1.z.literal("transport-choice"),
+    payload: exports.pairingTransportChoiceSchema,
+})
+    .strict();
+const unsignedOfferSignal = zod_1.z
+    .object({
+    ...pairingSignalBase,
+    kind: zod_1.z.literal("offer"),
+    payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
+})
+    .strict();
+const unsignedAnswerSignal = zod_1.z
+    .object({
+    ...pairingSignalBase,
+    kind: zod_1.z.literal("answer"),
+    payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
+})
+    .strict();
+const unsignedCandidateSignal = zod_1.z
+    .object({
+    ...pairingSignalBase,
+    kind: zod_1.z.literal("candidate"),
+    payload: exports.pairingIceCandidateSchema,
+})
+    .strict();
+/**
+ * Unsigned transport, offer, answer, or ICE message before its signaling MAC is attached.
+ *
+ * Order after both PAKE shares: destination `transport-options`, source `transport-choice`, then
+ * (WebRTC only) source `offer`, destination `answer`, and `candidate`s from either role.
+ */
 exports.unsignedPairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
-    zod_1.z
-        .object({
-        ...pairingSignalBase,
-        kind: zod_1.z.literal("offer"),
-        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
-    })
-        .strict(),
-    zod_1.z
-        .object({
-        ...pairingSignalBase,
-        kind: zod_1.z.literal("answer"),
-        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
-    })
-        .strict(),
-    zod_1.z
-        .object({
-        ...pairingSignalBase,
-        kind: zod_1.z.literal("candidate"),
-        payload: exports.pairingIceCandidateSchema,
-    })
-        .strict(),
+    unsignedTransportOptionsSignal,
+    unsignedTransportChoiceSignal,
+    unsignedOfferSignal,
+    unsignedAnswerSignal,
+    unsignedCandidateSignal,
 ]);
-/** HMAC-authenticated offer, answer, or ICE signaling message. */
-exports.pairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
-    zod_1.z
-        .object({
-        ...pairingSignalBase,
-        kind: zod_1.z.literal("offer"),
-        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("offer") }).strict(),
-        mac: exports.pairingHashSchema,
-    })
-        .strict(),
-    zod_1.z
-        .object({
-        ...pairingSignalBase,
-        kind: zod_1.z.literal("answer"),
-        payload: exports.pairingSessionDescriptionSchema.extend({ type: zod_1.z.literal("answer") }).strict(),
-        mac: exports.pairingHashSchema,
-    })
-        .strict(),
-    zod_1.z
-        .object({
-        ...pairingSignalBase,
-        kind: zod_1.z.literal("candidate"),
-        payload: exports.pairingIceCandidateSchema,
-        mac: exports.pairingHashSchema,
-    })
-        .strict(),
+const macField = { mac: exports.pairingHashSchema };
+/** HMAC-authenticated transport, offer, answer, or ICE signaling message. */
+exports.authenticatedPairingSignalSchema = zod_1.z.discriminatedUnion("kind", [
+    unsignedTransportOptionsSignal.extend(macField).strict(),
+    unsignedTransportChoiceSignal.extend(macField).strict(),
+    unsignedOfferSignal.extend(macField).strict(),
+    unsignedAnswerSignal.extend(macField).strict(),
+    unsignedCandidateSignal.extend(macField).strict(),
+]);
+/** Any signaling message relayed by peers-services: the PAKE share or an authenticated signal. */
+exports.pairingSignalSchema = zod_1.z.union([
+    exports.pairingPakeSignalSchema,
+    exports.authenticatedPairingSignalSchema,
 ]);
-/** Request from the source to create a bounded signaling room. */
+/** Request from the destination to create a bounded signaling room and receive a nameplate. */
 exports.devicePairingCreateRoomRequestSchema = zod_1.z
     .object({
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    roomId: exports.pairingRoomIdSchema,
     expiresAt: zod_1.z.number().int().positive(),
-    roomAccessTokenHash: exports.pairingHashSchema,
 })
     .strict();
-/** Request from the destination to occupy the second room slot. */
+/** Request from the source to occupy the room named by the typed or scanned nameplate. */
 exports.devicePairingJoinRoomRequestSchema = zod_1.z
     .object({
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    roomId: exports.pairingRoomIdSchema,
-    roomAccessToken: exports.pairingHashSchema,
+    nameplate: exports.pairingNameplateSchema,
 })
     .strict();
-/** Request from the source to tear down its signaling room. */
+/** Request from the creating destination socket to tear down its signaling room. */
 exports.devicePairingDeleteRoomRequestSchema = zod_1.z
     .object({
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    roomId: exports.pairingRoomIdSchema,
-    roomAccessToken: exports.pairingHashSchema,
+    nameplate: exports.pairingNameplateSchema,
 })
     .strict();
 /** Public signaling-service error codes that do not echo attacker input. */
@@ -172,7 +235,18 @@ exports.devicePairingSignalingAckSchema = zod_1.z.discriminatedUnion("ok", [
     zod_1.z.object({ ok: zod_1.z.literal(true) }).strict(),
     devicePairingSignalingFailureSchema,
 ]);
-/** Acknowledgement proving room creation/join and its service-authoritative expiry. */
+/** Acknowledgement returned to the destination with its allocated nameplate and expiry. */
+exports.devicePairingRoomCreatedAckSchema = zod_1.z.discriminatedUnion("ok", [
+    zod_1.z
+        .object({
+        ok: zod_1.z.literal(true),
+        nameplate: exports.pairingNameplateSchema,
+        expiresAt: zod_1.z.number().int().positive(),
+    })
+        .strict(),
+    devicePairingSignalingFailureSchema,
+]);
+/** Acknowledgement proving a room join and its service-authoritative expiry. */
 exports.devicePairingRoomReadyAckSchema = zod_1.z.discriminatedUnion("ok", [
     zod_1.z
         .object({
@@ -192,17 +266,24 @@ exports.devicePairingIceServersAckSchema = zod_1.z.discriminatedUnion("ok", [
         .strict(),
     devicePairingSignalingFailureSchema,
 ]);
-/** Canonical transcript input derived independently by both endpoints. */
+/**
+ * Canonical transcript input derived independently by both endpoints.
+ *
+ * `transportBinding` pins the negotiated data channel: for `wrtc` it is the sorted SHA-256 DTLS
+ * fingerprints of the offer and answer (`offer|answer`); for `ws` it is the destination URL the
+ * source connected to, exactly as advertised in the MACed transport options.
+ */
 exports.devicePairingTranscriptSchema = zod_1.z
     .object({
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    roomId: exports.pairingRoomIdSchema,
+    serviceOrigin: exports.pairingServiceOriginSchema,
+    nameplate: exports.pairingNameplateSchema,
     sourceIdentity: devices_1.deviceInfoSchema,
     destinationIdentity: devices_1.deviceInfoSchema,
     sourceEndpointNonce: exports.pairingEndpointNonceSchema,
     destinationEndpointNonce: exports.pairingEndpointNonceSchema,
-    offerFingerprint: zod_1.z.string().min(1).max(256),
-    answerFingerprint: zod_1.z.string().min(1).max(256),
+    transport: exports.pairingTransportSchema,
+    transportBinding: zod_1.z.string().min(1).max(4096),
 })
     .strict();
 /** Renderer-safe presentation of the remote endpoint. */
@@ -213,32 +294,22 @@ exports.pairingDevicePresentationSchema = zod_1.z
     deviceType: zod_1.z.string().max(64).optional(),
 })
     .strict();
-/** Payload exchanged by `pairing.describe` after the normal Connection handshake. */
-exports.pairingDescriptionSchema = zod_1.z
+/** Unauthenticated contents of a `pairing.confirm` message. */
+exports.pairingConfirmationContentsSchema = zod_1.z
     .object({
     version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
+    role: exports.pairingRoleSchema,
     transcriptHash: exports.pairingHashSchema,
     device: devices_1.deviceInfoSchema,
     presentation: exports.pairingDevicePresentationSchema,
 })
     .strict();
-/** Contents of a signed, single-use user approval. */
-exports.pairingApprovalContentsSchema = zod_1.z
-    .object({
-    version: zod_1.z.literal(constants_1.DEVICE_PAIRING_PROTOCOL_VERSION),
-    approvalId: exports.pairingEndpointNonceSchema,
-    transcriptHash: exports.pairingHashSchema,
-    role: exports.pairingRoleSchema,
-    expiresAt: zod_1.z.number().int().positive(),
-})
-    .strict();
-/** Signed approval bound to one transcript and endpoint identity. */
-exports.signedPairingApprovalSchema = zod_1.z
-    .object({
-    contents: exports.pairingApprovalContentsSchema,
-    signature: base64UrlSchema.length(86),
-    publicKey: base64UrlSchema.length(43),
-})
+/**
+ * Payload exchanged by `pairing.confirm` after the Connection handshake. The MAC uses the
+ * PAKE-derived confirmation key, proving the peer knew the code and saw the same transcript.
+ */
+exports.pairingConfirmationSchema = exports.pairingConfirmationContentsSchema
+    .extend({ mac: exports.pairingHashSchema })
     .strict();
 /** Account credentials encrypted directly to the temporary destination identity. */
 exports.pairingCredentialContentsSchema = zod_1.z
@@ -250,7 +321,7 @@ exports.pairingCredentialContentsSchema = zod_1.z
     secretKey: base64UrlSchema.length(86),
 })
     .strict();
-/** Signed-and-boxed credential envelope sent over the WebRTC Connection. */
+/** Signed-and-boxed credential envelope sent over the pairing Connection. */
 exports.pairingCredentialEnvelopeSchema = zod_1.z
     .object({
     contents: base64UrlSchema.min(1).max(4096),
@@ -275,12 +346,19 @@ exports.signedPairingInstallationReceiptSchema = zod_1.z
     publicKey: base64UrlSchema.length(43),
 })
     .strict();
-/** Renderer-visible phases of the short-lived pairing ceremony. */
+/**
+ * Renderer-visible phases of the short-lived pairing ceremony.
+ *
+ * - `showing-code`: destination is displaying its code and waiting for a source to join.
+ * - `connecting`: room joined; transport negotiation and the Connection handshake are in progress.
+ * - `authenticating`: PAKE-derived confirmations are being exchanged.
+ * - `waiting-for-approval`: source must tap Approve; destination waits for it.
+ */
 exports.devicePairingPhaseSchema = zod_1.z.enum([
     "idle",
-    "inviting",
+    "showing-code",
     "connecting",
-    "comparing",
+    "authenticating",
     "waiting-for-approval",
     "transferring",
     "complete",
@@ -295,10 +373,10 @@ exports.devicePairingStateSchema = zod_1.z
     phase: exports.devicePairingPhaseSchema,
     expiresAt: zod_1.z.number().int().positive().optional(),
     remoteDevice: exports.pairingDevicePresentationSchema.optional(),
-    sas: zod_1.z
-        .string()
-        .regex(/^\d{6}$/)
-        .optional(),
+    /** Destination only: the code to show as text and QR while `showing-code`. */
+    code: zod_1.z.string().max(128).optional(),
+    /** Non-fatal message shown alongside the current phase (e.g. why a code was rotated). */
+    notice: zod_1.z.string().max(256).optional(),
     error: zod_1.z.string().max(256).optional(),
 })
     .strict();

package/dist/index.d.ts

@@ -15,8 +15,8 @@ export * from "./device/socket-io-binary-peer";
 export * from "./device/tx-encoding";
 export * from "./device-pairing";
 export * from "./events";
-export * from "./group-invite";
 export * from "./hlc";
+export * from "./invites";
 export * from "./keys";
 export * from "./logging";
 export * from "./mentions";
@@ -39,7 +39,6 @@ export * from "./types/workflow";
 export * from "./types/workflow-logger";
 export * from "./types/workflow-run-context";
 export * from "./types/zod-types";
-export * from "./user-connect";
 export * from "./users.query";
 export * from "./utils";
 export * from "./workflow-log-formatter";

package/dist/index.js

@@ -36,8 +36,8 @@ __exportStar(require("./device/socket-io-binary-peer"), exports);
 __exportStar(require("./device/tx-encoding"), exports);
 __exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
-__exportStar(require("./group-invite"), exports);
 __exportStar(require("./hlc"), exports);
+__exportStar(require("./invites"), exports);
 __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);
 __exportStar(require("./mentions"), exports);
@@ -60,7 +60,6 @@ __exportStar(require("./types/workflow"), exports);
 __exportStar(require("./types/workflow-logger"), exports);
 __exportStar(require("./types/workflow-run-context"), exports);
 __exportStar(require("./types/zod-types"), exports);
-__exportStar(require("./user-connect"), exports);
 __exportStar(require("./users.query"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./workflow-log-formatter"), exports);

package/dist/invites/data-box-schema.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** Encrypted box as produced by `boxDataWithKeys`. */
+export declare const dataBoxSchema: z.ZodObject<{
+    contents: z.ZodString;
+    nonce: z.ZodString;
+    fromPublicKey: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    nonce: string;
+    contents: string;
+    fromPublicKey: string;
+}, {
+    nonce: string;
+    contents: string;
+    fromPublicKey: string;
+}>;

package/dist/invites/data-box-schema.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataBoxSchema = void 0;
+const zod_1 = require("zod");
+/** Encrypted box as produced by `boxDataWithKeys`. */
+exports.dataBoxSchema = zod_1.z
+    .object({
+    contents: zod_1.z.string().min(1),
+    nonce: zod_1.z.string().min(1),
+    fromPublicKey: zod_1.z
+        .string()
+        .regex(/^[A-Za-z0-9_-]+$/)
+        .length(43),
+})
+    .strict();

package/dist/invites/group-approval.d.ts

@@ -0,0 +1,43 @@
+import type { UserContext } from "../context/user-context";
+import { GroupMemberRole } from "../data";
+import { type IPublicPrivateKeys } from "../keys";
+import type { GroupApproval } from "./invite-messages";
+import type { InviteIdentity } from "./invite-token";
+/** Inputs for building a {@link GroupApproval} on the approving member's device. */
+export interface BuildGroupApprovalInput {
+    groupId: string;
+    joiner: InviteIdentity;
+    role: GroupMemberRole;
+    /** Nonce of the token or direct invite this approval answers. */
+    inviteNonce?: string;
+    /** The approving user's keys; the group secret is read and boxed with these. */
+    approverKeys: IPublicPrivateKeys;
+    approverDeviceId: string;
+}
+/**
+ * Builds the approval payload for a joiner: signs their membership row, gathers Admin+
+ * seed rows plus the approver's own Users/Devices records, and boxes the group secret to
+ * the joiner's box key.
+ *
+ * The approver must hold Admin+ in the group. The membership row is signed and saved in
+ * the approver's group context here; it syncs to the joiner when they connect and is also
+ * carried in the payload so the joiner can seed their copy immediately.
+ *
+ * @throws when the group is unknown, the approver is not Admin+, or the secret is unavailable
+ */
+export declare function buildGroupApproval(userContext: UserContext, input: BuildGroupApprovalInput): Promise<GroupApproval>;
+/** Result of importing an approval on the joiner's device. */
+export interface ImportGroupApprovalResult {
+    groupId: string;
+    approverUserId: string;
+    approverDeviceId: string;
+}
+/**
+ * Imports a {@link GroupApproval} on the joiner's device: records the group, seeds the group
+ * context with the signed rows, saves the approver as a contact, and stores the unboxed
+ * group secret in the personal context after validating it against the group's keys.
+ *
+ * Personal `Groups` is added only when missing so a local leave stays authoritative.
+ * `Devices` rows for the approver are left to the caller (device layer).
+ */
+export declare function importGroupApproval(userContext: UserContext, approval: GroupApproval, joinerKeys: IPublicPrivateKeys): Promise<ImportGroupApprovalResult>;