@textrp/briij-js-sdk 41.0.0

package/src/models/beacon.ts

@@ -0,0 +1,213 @@
+/*
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { type MBeaconEventContent } from "../@types/beacon.ts";
+import {
+    type BeaconInfoState,
+    type BeaconLocationState,
+    parseBeaconContent,
+    parseBeaconInfoContent,
+} from "../content-helpers.ts";
+import { type BriijEvent } from "./event.ts";
+import { sortEventsByLatestContentTimestamp } from "../utils.ts";
+import { TypedEventEmitter } from "./typed-event-emitter.ts";
+
+export enum BeaconEvent {
+    New = "Beacon.new",
+    Update = "Beacon.update",
+    LivenessChange = "Beacon.LivenessChange",
+    Destroy = "Beacon.Destroy",
+    LocationUpdate = "Beacon.LocationUpdate",
+}
+
+export type BeaconEventHandlerMap = {
+    [BeaconEvent.Update]: (event: BriijEvent, beacon: Beacon) => void;
+    [BeaconEvent.LivenessChange]: (isLive: boolean, beacon: Beacon) => void;
+    [BeaconEvent.Destroy]: (beaconIdentifier: string) => void;
+    [BeaconEvent.LocationUpdate]: (locationState: BeaconLocationState) => void;
+};
+
+export const isTimestampInDuration = (startTimestamp: number, durationMs: number, timestamp: number): boolean =>
+    timestamp >= startTimestamp && startTimestamp + durationMs >= timestamp;
+
+// beacon info events are uniquely identified by
+// `<roomId>_<state_key>`
+export type BeaconIdentifier = string;
+export const getBeaconInfoIdentifier = (event: BriijEvent): BeaconIdentifier =>
+    `${event.getRoomId()}_${event.getStateKey()}`;
+
+// https://github.com/matrix-org/matrix-spec-proposals/pull/3672
+export class Beacon extends TypedEventEmitter<Exclude<BeaconEvent, BeaconEvent.New>, BeaconEventHandlerMap> {
+    public readonly roomId: string;
+    // beaconInfo is assigned by setBeaconInfo in the constructor
+    // ! to make tsc believe it is definitely assigned
+    private _beaconInfo!: BeaconInfoState;
+    private _isLive?: boolean;
+    private livenessWatchTimeout?: ReturnType<typeof setTimeout>;
+    private _latestLocationEvent?: BriijEvent;
+
+    public constructor(private rootEvent: BriijEvent) {
+        super();
+        this.roomId = this.rootEvent.getRoomId()!;
+        this.setBeaconInfo(this.rootEvent);
+    }
+
+    public get isLive(): boolean {
+        return !!this._isLive;
+    }
+
+    public get identifier(): BeaconIdentifier {
+        return getBeaconInfoIdentifier(this.rootEvent);
+    }
+
+    public get beaconInfoId(): string {
+        return this.rootEvent.getId()!;
+    }
+
+    public get beaconInfoOwner(): string {
+        return this.rootEvent.getStateKey()!;
+    }
+
+    public get beaconInfoEventType(): string {
+        return this.rootEvent.getType();
+    }
+
+    public get beaconInfo(): BeaconInfoState {
+        return this._beaconInfo;
+    }
+
+    public get latestLocationState(): BeaconLocationState | undefined {
+        return this._latestLocationEvent && parseBeaconContent(this._latestLocationEvent.getContent());
+    }
+
+    public get latestLocationEvent(): BriijEvent | undefined {
+        return this._latestLocationEvent;
+    }
+
+    public update(beaconInfoEvent: BriijEvent): void {
+        if (getBeaconInfoIdentifier(beaconInfoEvent) !== this.identifier) {
+            throw new Error("Invalid updating event");
+        }
+        // don't update beacon with an older event
+        if (beaconInfoEvent.getTs() < this.rootEvent.getTs()) {
+            return;
+        }
+        this.rootEvent = beaconInfoEvent;
+        this.setBeaconInfo(this.rootEvent);
+
+        this.emit(BeaconEvent.Update, beaconInfoEvent, this);
+        this.clearLatestLocation();
+    }
+
+    public destroy(): void {
+        if (this.livenessWatchTimeout) {
+            clearTimeout(this.livenessWatchTimeout);
+        }
+
+        this._isLive = false;
+        this.emit(BeaconEvent.Destroy, this.identifier);
+    }
+
+    /**
+     * Monitor liveness of a beacon
+     * Emits BeaconEvent.LivenessChange when beacon expires
+     */
+    public monitorLiveness(): void {
+        if (this.livenessWatchTimeout) {
+            clearTimeout(this.livenessWatchTimeout);
+        }
+
+        this.checkLiveness();
+        if (!this.beaconInfo) return;
+        if (this.isLive) {
+            const expiryInMs = this.beaconInfo.timestamp! + this.beaconInfo.timeout - Date.now();
+            if (expiryInMs > 1) {
+                this.livenessWatchTimeout = setTimeout(() => {
+                    this.monitorLiveness();
+                }, expiryInMs);
+            }
+        } else if (this.beaconInfo.timestamp! > Date.now()) {
+            // beacon start timestamp is in the future
+            // check liveness again then
+            this.livenessWatchTimeout = setTimeout(() => {
+                this.monitorLiveness();
+            }, this.beaconInfo.timestamp! - Date.now());
+        }
+    }
+
+    /**
+     * Process Beacon locations
+     * Emits BeaconEvent.LocationUpdate
+     */
+    public addLocations(beaconLocationEvents: BriijEvent[]): void {
+        // discard locations for beacons that are not live
+        if (!this.isLive) {
+            return;
+        }
+
+        const validLocationEvents = beaconLocationEvents.filter((event) => {
+            const content = event.getContent<MBeaconEventContent>();
+            const parsed = parseBeaconContent(content);
+            if (!parsed.uri || !parsed.timestamp) return false; // we won't be able to process these
+            const { timestamp } = parsed;
+            return (
+                this._beaconInfo.timestamp &&
+                // only include positions that were taken inside the beacon's live period
+                isTimestampInDuration(this._beaconInfo.timestamp, this._beaconInfo.timeout, timestamp) &&
+                // ignore positions older than our current latest location
+                (!this.latestLocationState || timestamp > this.latestLocationState.timestamp!)
+            );
+        });
+        const latestLocationEvent = validLocationEvents.sort(sortEventsByLatestContentTimestamp)?.[0];
+
+        if (latestLocationEvent) {
+            this._latestLocationEvent = latestLocationEvent;
+            this.emit(BeaconEvent.LocationUpdate, this.latestLocationState!);
+        }
+    }
+
+    private clearLatestLocation = (): void => {
+        this._latestLocationEvent = undefined;
+        this.emit(BeaconEvent.LocationUpdate, this.latestLocationState!);
+    };
+
+    private setBeaconInfo(event: BriijEvent): void {
+        this._beaconInfo = parseBeaconInfoContent(event.getContent());
+        this.checkLiveness();
+    }
+
+    private checkLiveness(): void {
+        const prevLiveness = this.isLive;
+
+        // element web sets a beacon's start timestamp to the senders local current time
+        // when Alice's system clock deviates slightly from Bob's a beacon Alice intended to be live
+        // may have a start timestamp in the future from Bob's POV
+        // handle this by adding 6min of leniency to the start timestamp when it is in the future
+        if (!this.beaconInfo) return;
+        const startTimestamp =
+            this.beaconInfo.timestamp! > Date.now()
+                ? this.beaconInfo.timestamp! - 360000 /* 6min */
+                : this.beaconInfo.timestamp;
+        this._isLive =
+            !!this._beaconInfo.live &&
+            !!startTimestamp &&
+            isTimestampInDuration(startTimestamp, this._beaconInfo.timeout, Date.now());
+
+        if (prevLiveness !== this.isLive) {
+            this.emit(BeaconEvent.LivenessChange, this.isLive, this);
+        }
+    }
+}

package/src/models/compare-event-ordering.ts

@@ -0,0 +1,139 @@
+/*
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { type BriijEvent } from "./event.ts";
+import { type Room } from "./room.ts";
+import { inMainTimelineForReceipt, threadIdForReceipt } from "../client.ts";
+
+/**
+ * Determine the order of two events in a room.
+ *
+ * In principle this should use the same order as the server, but in practice
+ * this is difficult for events that were not received over the Sync API. See
+ * MSC4033 for details.
+ *
+ * This implementation leans on the order of events within their timelines, and
+ * falls back to comparing event timestamps when they are in different
+ * timelines.
+ *
+ * See https://github.com/matrix-org/matrix-js-sdk/issues/3325 for where we are
+ * tracking the work to fix this.
+ *
+ * @param room - the room we are looking in
+ * @param leftEventId - the id of the first event
+ * @param rightEventId - the id of the second event
+
+ * @returns -1 if left \< right, 1 if left \> right, 0 if left == right, null if
+ *          we can't tell (because we can't find the events).
+ */
+export function compareEventOrdering(room: Room, leftEventId: string, rightEventId: string): number | null {
+    const leftEvent = room.findEventById(leftEventId);
+    const rightEvent = room.findEventById(rightEventId);
+
+    if (!leftEvent || !rightEvent) {
+        // Without the events themselves, we can't find their thread or
+        // timeline, or guess based on timestamp, so we just don't know.
+        return null;
+    }
+
+    // Check whether the events are in the main timeline
+    const isLeftEventInMainTimeline = inMainTimelineForReceipt(leftEvent);
+    const isRightEventInMainTimeline = inMainTimelineForReceipt(rightEvent);
+
+    if (isLeftEventInMainTimeline && isRightEventInMainTimeline) {
+        return compareEventsInMainTimeline(room, leftEventId, rightEventId, leftEvent, rightEvent);
+    } else {
+        // At least one event is not in the timeline, so we can't use the room's
+        // unfiltered timeline set.
+        return compareEventsInThreads(leftEventId, rightEventId, leftEvent, rightEvent);
+    }
+}
+
+function compareEventsInMainTimeline(
+    room: Room,
+    leftEventId: string,
+    rightEventId: string,
+    leftEvent: BriijEvent,
+    rightEvent: BriijEvent,
+): number | null {
+    // Get the timeline set that contains all the events.
+    const timelineSet = room.getUnfilteredTimelineSet();
+
+    // If they are in the same timeline, compareEventOrdering does what we need
+    const compareSameTimeline = timelineSet.compareEventOrdering(leftEventId, rightEventId);
+    if (compareSameTimeline !== null) {
+        return compareSameTimeline;
+    }
+
+    // Find which timeline each event is in. Refuse to provide an ordering if we
+    // can't find either of the events.
+
+    const leftTimeline = timelineSet.getTimelineForEvent(leftEventId);
+    if (leftTimeline === timelineSet.getLiveTimeline()) {
+        // The left event is part of the live timeline, so it must be after the
+        // right event (since they are not in the same timeline or we would have
+        // returned after compareEventOrdering.
+        return 1;
+    }
+
+    const rightTimeline = timelineSet.getTimelineForEvent(rightEventId);
+    if (rightTimeline === timelineSet.getLiveTimeline()) {
+        // The right event is part of the live timeline, so it must be after the
+        // left event.
+        return -1;
+    }
+
+    // They are in older timeline sets (because they were fetched by paging up).
+    return guessOrderBasedOnTimestamp(leftEvent, rightEvent);
+}
+
+function compareEventsInThreads(
+    leftEventId: string,
+    rightEventId: string,
+    leftEvent: BriijEvent,
+    rightEvent: BriijEvent,
+): number | null {
+    const leftEventThreadId = threadIdForReceipt(leftEvent);
+    const rightEventThreadId = threadIdForReceipt(rightEvent);
+
+    const leftThread = leftEvent.getThread();
+
+    if (leftThread && leftEventThreadId === rightEventThreadId) {
+        // They are in the same thread, so we can ask the thread's timeline to
+        // figure it out for us
+        return leftThread.timelineSet.compareEventOrdering(leftEventId, rightEventId);
+    } else {
+        return guessOrderBasedOnTimestamp(leftEvent, rightEvent);
+    }
+}
+
+/**
+ * Guess the order of events based on server timestamp. This is not good, but
+ * difficult to avoid without MSC4033.
+ *
+ * See https://github.com/matrix-org/matrix-js-sdk/issues/3325
+ */
+function guessOrderBasedOnTimestamp(leftEvent: BriijEvent, rightEvent: BriijEvent): number {
+    const leftTs = leftEvent.getTs();
+    const rightTs = rightEvent.getTs();
+    if (leftTs < rightTs) {
+        return -1;
+    } else if (leftTs > rightTs) {
+        return 1;
+    } else {
+        return 0;
+    }
+}

package/src/models/device.ts

@@ -0,0 +1,85 @@
+/*
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/** State of the verification of the device. */
+export enum DeviceVerification {
+    Blocked = -1,
+    Unverified = 0,
+    Verified = 1,
+}
+
+/** A map from user ID to device ID to Device */
+export type DeviceMap = Map<string, Map<string, Device>>;
+
+type DeviceParameters = Pick<Device, "deviceId" | "userId" | "algorithms" | "keys"> & Partial<Device>;
+
+/**
+ *  Information on a user's device, as returned by {@link crypto-api!CryptoApi.getUserDeviceInfo}.
+ */
+export class Device {
+    /** id of the device */
+    public readonly deviceId: string;
+
+    /** id of the user that owns the device */
+    public readonly userId: string;
+
+    /** list of algorithms supported by this device */
+    public readonly algorithms: string[];
+
+    /** a map from `<key type>:<id> -> <base64-encoded key>` */
+    public readonly keys: Map<string, string>;
+
+    /** whether the device has been verified/blocked by the user */
+    public readonly verified: DeviceVerification;
+
+    /** a map `<userId, map<algorithm:device_id, signature>>` */
+    public readonly signatures: Map<string, Map<string, string>>;
+
+    /** display name of the device */
+    public readonly displayName?: string;
+
+    /** whether the device is a dehydrated device */
+    public readonly dehydrated: boolean = false;
+
+    public constructor(opts: DeviceParameters) {
+        this.deviceId = opts.deviceId;
+        this.userId = opts.userId;
+        this.algorithms = opts.algorithms;
+        this.keys = opts.keys;
+        this.verified = opts.verified || DeviceVerification.Unverified;
+        this.signatures = opts.signatures || new Map();
+        this.displayName = opts.displayName;
+        this.dehydrated = !!opts.dehydrated;
+    }
+
+    /**
+     * Get the fingerprint for this device (ie, the Ed25519 key)
+     *
+     * @returns base64-encoded fingerprint of this device
+     */
+    public getFingerprint(): string | undefined {
+        return this.keys.get(`ed25519:${this.deviceId}`);
+    }
+
+    /**
+     * Get the identity key for this device (ie, the Curve25519 key)
+     *
+     * @returns base64-encoded identity key of this device
+     */
+    public getIdentityKey(): string | undefined {
+        return this.keys.get(`curve25519:${this.deviceId}`);
+    }
+}

package/src/models/event-context.ts

@@ -0,0 +1,110 @@
+/*
+Copyright 2015 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { type BriijEvent } from "./event.ts";
+import { Direction } from "./event-timeline.ts";
+
+export class EventContext {
+    private timeline: BriijEvent[];
+    private ourEventIndex = 0;
+    private paginateTokens: Record<Direction, string | null> = {
+        [Direction.Backward]: null,
+        [Direction.Forward]: null,
+    };
+
+    /**
+     * Construct a new EventContext
+     *
+     * An eventcontext is used for circumstances such as search results, when we
+     * have a particular event of interest, and a bunch of events before and after
+     * it.
+     *
+     * It also stores pagination tokens for going backwards and forwards in the
+     * timeline.
+     *
+     * @param ourEvent - the event at the centre of this context
+     */
+    public constructor(public readonly ourEvent: BriijEvent) {
+        this.timeline = [ourEvent];
+    }
+
+    /**
+     * Get the main event of interest
+     *
+     * This is a convenience function for getTimeline()[getOurEventIndex()].
+     *
+     * @returns The event at the centre of this context.
+     */
+    public getEvent(): BriijEvent {
+        return this.timeline[this.ourEventIndex];
+    }
+
+    /**
+     * Get the list of events in this context
+     *
+     * @returns An array of BriijEvents
+     */
+    public getTimeline(): BriijEvent[] {
+        return this.timeline;
+    }
+
+    /**
+     * Get the index in the timeline of our event
+     */
+    public getOurEventIndex(): number {
+        return this.ourEventIndex;
+    }
+
+    /**
+     * Get a pagination token.
+     *
+     * @param backwards -   true to get the pagination token for going
+     */
+    public getPaginateToken(backwards = false): string | null {
+        return this.paginateTokens[backwards ? Direction.Backward : Direction.Forward];
+    }
+
+    /**
+     * Set a pagination token.
+     *
+     * Generally this will be used only by the matrix js sdk.
+     *
+     * @param token -        pagination token
+     * @param backwards -   true to set the pagination token for going
+     *                                   backwards in time
+     */
+    public setPaginateToken(token?: string, backwards = false): void {
+        this.paginateTokens[backwards ? Direction.Backward : Direction.Forward] = token ?? null;
+    }
+
+    /**
+     * Add more events to the timeline
+     *
+     * @param events -      new events, in timeline order
+     * @param atStart -   true to insert new events at the start
+     */
+    public addEvents(events: BriijEvent[], atStart = false): void {
+        // TODO: should we share logic with Room.addEventsToTimeline?
+        // Should Room even use EventContext?
+
+        if (atStart) {
+            this.timeline = events.concat(this.timeline);
+            this.ourEventIndex += events.length;
+        } else {
+            this.timeline = this.timeline.concat(events);
+        }
+    }
+}

package/src/models/event-status.ts

@@ -0,0 +1,39 @@
+/*
+Copyright 2015 - 2022 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * Enum for event statuses.
+ * @readonly
+ */
+export enum EventStatus {
+    /** The event was not sent and will no longer be retried. */
+    NOT_SENT = "not_sent",
+
+    /** The message is being encrypted */
+    ENCRYPTING = "encrypting",
+
+    /** The event is in the process of being sent. */
+    SENDING = "sending",
+
+    /** The event is in a queue waiting to be sent. */
+    QUEUED = "queued",
+
+    /** The event has been sent to the server, but we have not yet received the echo. */
+    SENT = "sent",
+
+    /** The event was cancelled before it was successfully sent. */
+    CANCELLED = "cancelled",
+}