@unwanted/matrix-sdk-mini 34.12.0-1

package/lib/common-crypto/CryptoBackend.d.ts

@@ -0,0 +1,240 @@
+import type { IDeviceLists, IToDeviceEvent } from "../sync-accumulator.ts";
+import { IClearEvent, MatrixEvent } from "../models/event.ts";
+import { Room } from "../models/room.ts";
+import { CryptoApi, DecryptionFailureCode, ImportRoomKeysOpts } from "../crypto-api/index.ts";
+import { CrossSigningInfo, UserTrustLevel } from "../crypto/CrossSigning.ts";
+import { IEncryptedEventInfo } from "../crypto/api.ts";
+import { KeyBackupInfo, KeyBackupSession } from "../crypto-api/keybackup.ts";
+import { IMegolmSessionData } from "../@types/crypto.ts";
+/**
+ * Common interface for the crypto implementations
+ *
+ * @internal
+ */
+export interface CryptoBackend extends SyncCryptoCallbacks, CryptoApi {
+    /**
+     * Whether sendMessage in a room with unknown and unverified devices
+     * should throw an error and not send the message. This has 'Global' for
+     * symmetry with setGlobalBlacklistUnverifiedDevices but there is currently
+     * no room-level equivalent for this setting.
+     *
+     * @remarks This has no effect in Rust Crypto; it exists only for the sake of
+     * the accessors in MatrixClient.
+     */
+    globalErrorOnUnknownDevices: boolean;
+    /**
+     * Shut down any background processes related to crypto
+     */
+    stop(): void;
+    /**
+     * Get the verification level for a given user
+     *
+     * @param userId - user to be checked
+     *
+     * @deprecated Superceded by {@link CryptoApi#getUserVerificationStatus}.
+     */
+    checkUserTrust(userId: string): UserTrustLevel;
+    /**
+     * Encrypt an event according to the configuration of the room.
+     *
+     * @param event -  event to be sent
+     *
+     * @param room - destination room.
+     *
+     * @returns Promise which resolves when the event has been
+     *     encrypted, or null if nothing was needed
+     */
+    encryptEvent(event: MatrixEvent, room: Room): Promise<void>;
+    /**
+     * Decrypt a received event
+     *
+     * @returns a promise which resolves once we have finished decrypting.
+     * Rejects with an error if there is a problem decrypting the event.
+     */
+    decryptEvent(event: MatrixEvent): Promise<EventDecryptionResult>;
+    /**
+     * Get information about the encryption of an event
+     *
+     * @param event - event to be checked
+     */
+    getEventEncryptionInfo(event: MatrixEvent): IEncryptedEventInfo;
+    /**
+     * Get the cross signing information for a given user.
+     *
+     * The cross-signing API is currently UNSTABLE and may change without notice.
+     *
+     * @param userId - the user ID to get the cross-signing info for.
+     *
+     * @returns the cross signing information for the user.
+     * @deprecated Prefer {@link CryptoApi#userHasCrossSigningKeys}
+     */
+    getStoredCrossSigningForUser(userId: string): CrossSigningInfo | null;
+    /**
+     * Check the cross signing trust of the current user
+     *
+     * @param opts - Options object.
+     *
+     * @deprecated Unneeded for the new crypto
+     */
+    checkOwnCrossSigningTrust(opts?: CheckOwnCrossSigningTrustOpts): Promise<void>;
+    /**
+     * Get a backup decryptor capable of decrypting megolm session data encrypted with the given backup information.
+     * @param backupInfo - The backup information
+     * @param privKey - The private decryption key.
+     */
+    getBackupDecryptor(backupInfo: KeyBackupInfo, privKey: ArrayLike<number>): Promise<BackupDecryptor>;
+    /**
+     * Import a list of room keys restored from backup
+     *
+     * @param keys - a list of session export objects
+     * @param backupVersion - the version of the backup these keys came from.
+     * @param opts - options object
+     * @returns a promise which resolves once the keys have been imported
+     */
+    importBackedUpRoomKeys(keys: IMegolmSessionData[], backupVersion: string, opts?: ImportRoomKeysOpts): Promise<void>;
+}
+/** The methods which crypto implementations should expose to the Sync api
+ *
+ * @internal
+ */
+export interface SyncCryptoCallbacks {
+    /**
+     * Called by the /sync loop whenever there are incoming to-device messages.
+     *
+     * The implementation may preprocess the received messages (eg, decrypt them) and return an
+     * updated list of messages for dispatch to the rest of the system.
+     *
+     * Note that, unlike {@link ClientEvent.ToDeviceEvent} events, this is called on the raw to-device
+     * messages, rather than the results of any decryption attempts.
+     *
+     * @param events - the received to-device messages
+     * @returns A list of preprocessed to-device messages.
+     */
+    preprocessToDeviceMessages(events: IToDeviceEvent[]): Promise<IToDeviceEvent[]>;
+    /**
+     * Called by the /sync loop when one time key counts and unused fallback key details are received.
+     *
+     * @param oneTimeKeysCounts - the received one time key counts
+     * @param unusedFallbackKeys - the received unused fallback keys
+     */
+    processKeyCounts(oneTimeKeysCounts?: Record<string, number>, unusedFallbackKeys?: string[]): Promise<void>;
+    /**
+     * Handle the notification from /sync that device lists have
+     * been changed.
+     *
+     * @param deviceLists - device_lists field from /sync
+     */
+    processDeviceLists(deviceLists: IDeviceLists): Promise<void>;
+    /**
+     * Called by the /sync loop whenever an m.room.encryption event is received.
+     *
+     * This is called before RoomStateEvents are emitted for any of the events in the /sync
+     * response (even if the other events technically happened first). This works around a problem
+     * if the client uses a RoomStateEvent (typically a membership event) as a trigger to send a message
+     * in a new room (or one where encryption has been newly enabled): that would otherwise leave the
+     * crypto layer confused because it expects crypto to be set up, but it has not yet been.
+     *
+     * @param room - in which the event was received
+     * @param event - encryption event to be processed
+     */
+    onCryptoEvent(room: Room, event: MatrixEvent): Promise<void>;
+    /**
+     * Called by the /sync loop after each /sync response is processed.
+     *
+     * Used to complete batch processing, or to initiate background processes
+     *
+     * @param syncState - information about the completed sync.
+     */
+    onSyncCompleted(syncState: OnSyncCompletedData): void;
+}
+/**
+ * @internal
+ */
+export interface OnSyncCompletedData {
+    /**
+     * The 'next_batch' result from /sync, which will become the 'since' token for the next call to /sync.
+     */
+    nextSyncToken?: string;
+    /**
+     * True if we are working our way through a backlog of events after connecting.
+     */
+    catchingUp?: boolean;
+}
+/**
+ * Options object for {@link CryptoBackend#checkOwnCrossSigningTrust}.
+ */
+export interface CheckOwnCrossSigningTrustOpts {
+    allowPrivateKeyRequests?: boolean;
+}
+/**
+ * The result of a (successful) call to {@link CryptoBackend.decryptEvent}
+ */
+export interface EventDecryptionResult {
+    /**
+     * The plaintext payload for the event (typically containing <tt>type</tt> and <tt>content</tt> fields).
+     */
+    clearEvent: IClearEvent;
+    /**
+     * List of curve25519 keys involved in telling us about the senderCurve25519Key and claimedEd25519Key.
+     * See {@link MatrixEvent#getForwardingCurve25519KeyChain}.
+     */
+    forwardingCurve25519KeyChain?: string[];
+    /**
+     * Key owned by the sender of this event.  See {@link MatrixEvent#getSenderKey}.
+     */
+    senderCurve25519Key?: string;
+    /**
+     * ed25519 key claimed by the sender of this event. See {@link MatrixEvent#getClaimedEd25519Key}.
+     */
+    claimedEd25519Key?: string;
+    /**
+     * Whether the keys for this event have been received via an unauthenticated source (eg via key forwards, or
+     * restored from backup)
+     */
+    untrusted?: boolean;
+}
+/**
+ * Responsible for decrypting megolm session data retrieved from a remote backup.
+ * The result of {@link CryptoBackend#getBackupDecryptor}.
+ */
+export interface BackupDecryptor {
+    /**
+     * Whether keys retrieved from this backup can be trusted.
+     *
+     * Depending on the backup algorithm, keys retrieved from the backup can be trusted or not.
+     * If false, keys retrieved from the backup  must be considered unsafe (authenticity cannot be guaranteed).
+     * It could be by design (deniability) or for some technical reason (eg asymmetric encryption).
+     */
+    readonly sourceTrusted: boolean;
+    /**
+     *
+     * Decrypt megolm session data retrieved from backup.
+     *
+     * @param ciphertexts - a Record of sessionId to session data.
+     *
+     * @returns An array of decrypted `IMegolmSessionData`
+     */
+    decryptSessions(ciphertexts: Record<string, KeyBackupSession>): Promise<IMegolmSessionData[]>;
+    /**
+     * Free any resources held by this decryptor.
+     *
+     * Should be called once the decryptor is no longer needed.
+     */
+    free(): void;
+}
+/**
+ * Exception thrown when decryption fails
+ *
+ * @param code - Reason code for the failure.
+ *
+ * @param msg - user-visible message describing the problem
+ *
+ * @param details - key/value pairs reported in the logs but not shown
+ *   to the user.
+ */
+export declare class DecryptionError extends Error {
+    readonly code: DecryptionFailureCode;
+    readonly detailedString: string;
+    constructor(code: DecryptionFailureCode, msg: string, details?: Record<string, string | Error>);
+}
+//# sourceMappingURL=CryptoBackend.d.ts.map

package/lib/common-crypto/CryptoBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CryptoBackend.d.ts","sourceRoot":"","sources":["../../src/common-crypto/CryptoBackend.ts"],"names":[],"mappings":"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"}

package/lib/common-crypto/CryptoBackend.js

@@ -0,0 +1,73 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+/*
+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.
+*/
+
+/**
+ * Common interface for the crypto implementations
+ *
+ * @internal
+ */
+
+/** The methods which crypto implementations should expose to the Sync api
+ *
+ * @internal
+ */
+
+/**
+ * @internal
+ */
+
+/**
+ * Options object for {@link CryptoBackend#checkOwnCrossSigningTrust}.
+ */
+
+/**
+ * The result of a (successful) call to {@link CryptoBackend.decryptEvent}
+ */
+
+/**
+ * Responsible for decrypting megolm session data retrieved from a remote backup.
+ * The result of {@link CryptoBackend#getBackupDecryptor}.
+ */
+
+/**
+ * Exception thrown when decryption fails
+ *
+ * @param code - Reason code for the failure.
+ *
+ * @param msg - user-visible message describing the problem
+ *
+ * @param details - key/value pairs reported in the logs but not shown
+ *   to the user.
+ */
+export class DecryptionError extends Error {
+  constructor(code, msg, details) {
+    super(msg);
+    this.code = code;
+    _defineProperty(this, "detailedString", void 0);
+    this.name = "DecryptionError";
+    this.detailedString = detailedStringForDecryptionError(this, details);
+  }
+}
+function detailedStringForDecryptionError(err, details) {
+  var result = err.name + "[msg: " + err.message;
+  if (details) {
+    result += ", " + Object.keys(details).map(k => k + ": " + details[k]).join(", ");
+  }
+  result += "]";
+  return result;
+}
+//# sourceMappingURL=CryptoBackend.js.map

package/lib/common-crypto/CryptoBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CryptoBackend.js","names":["DecryptionError","Error","constructor","code","msg","details","_defineProperty","name","detailedString","detailedStringForDecryptionError","err","result","message","Object","keys","map","k","join"],"sources":["../../src/common-crypto/CryptoBackend.ts"],"sourcesContent":["/*\nCopyright 2022 The Matrix.org Foundation C.I.C.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n*/\n\nimport type { IDeviceLists, IToDeviceEvent } from \"../sync-accumulator.ts\";\nimport { IClearEvent, MatrixEvent } from \"../models/event.ts\";\nimport { Room } from \"../models/room.ts\";\nimport { CryptoApi, DecryptionFailureCode, ImportRoomKeysOpts } from \"../crypto-api/index.ts\";\nimport { CrossSigningInfo, UserTrustLevel } from \"../crypto/CrossSigning.ts\";\nimport { IEncryptedEventInfo } from \"../crypto/api.ts\";\nimport { KeyBackupInfo, KeyBackupSession } from \"../crypto-api/keybackup.ts\";\nimport { IMegolmSessionData } from \"../@types/crypto.ts\";\n\n/**\n * Common interface for the crypto implementations\n *\n * @internal\n */\nexport interface CryptoBackend extends SyncCryptoCallbacks, CryptoApi {\n    /**\n     * Whether sendMessage in a room with unknown and unverified devices\n     * should throw an error and not send the message. This has 'Global' for\n     * symmetry with setGlobalBlacklistUnverifiedDevices but there is currently\n     * no room-level equivalent for this setting.\n     *\n     * @remarks This has no effect in Rust Crypto; it exists only for the sake of\n     * the accessors in MatrixClient.\n     */\n    globalErrorOnUnknownDevices: boolean;\n\n    /**\n     * Shut down any background processes related to crypto\n     */\n    stop(): void;\n\n    /**\n     * Get the verification level for a given user\n     *\n     * @param userId - user to be checked\n     *\n     * @deprecated Superceded by {@link CryptoApi#getUserVerificationStatus}.\n     */\n    checkUserTrust(userId: string): UserTrustLevel;\n\n    /**\n     * Encrypt an event according to the configuration of the room.\n     *\n     * @param event -  event to be sent\n     *\n     * @param room - destination room.\n     *\n     * @returns Promise which resolves when the event has been\n     *     encrypted, or null if nothing was needed\n     */\n    encryptEvent(event: MatrixEvent, room: Room): Promise<void>;\n\n    /**\n     * Decrypt a received event\n     *\n     * @returns a promise which resolves once we have finished decrypting.\n     * Rejects with an error if there is a problem decrypting the event.\n     */\n    decryptEvent(event: MatrixEvent): Promise<EventDecryptionResult>;\n\n    /**\n     * Get information about the encryption of an event\n     *\n     * @param event - event to be checked\n     */\n    getEventEncryptionInfo(event: MatrixEvent): IEncryptedEventInfo;\n\n    /**\n     * Get the cross signing information for a given user.\n     *\n     * The cross-signing API is currently UNSTABLE and may change without notice.\n     *\n     * @param userId - the user ID to get the cross-signing info for.\n     *\n     * @returns the cross signing information for the user.\n     * @deprecated Prefer {@link CryptoApi#userHasCrossSigningKeys}\n     */\n    getStoredCrossSigningForUser(userId: string): CrossSigningInfo | null;\n\n    /**\n     * Check the cross signing trust of the current user\n     *\n     * @param opts - Options object.\n     *\n     * @deprecated Unneeded for the new crypto\n     */\n    checkOwnCrossSigningTrust(opts?: CheckOwnCrossSigningTrustOpts): Promise<void>;\n\n    /**\n     * Get a backup decryptor capable of decrypting megolm session data encrypted with the given backup information.\n     * @param backupInfo - The backup information\n     * @param privKey - The private decryption key.\n     */\n    getBackupDecryptor(backupInfo: KeyBackupInfo, privKey: ArrayLike<number>): Promise<BackupDecryptor>;\n\n    /**\n     * Import a list of room keys restored from backup\n     *\n     * @param keys - a list of session export objects\n     * @param backupVersion - the version of the backup these keys came from.\n     * @param opts - options object\n     * @returns a promise which resolves once the keys have been imported\n     */\n    importBackedUpRoomKeys(keys: IMegolmSessionData[], backupVersion: string, opts?: ImportRoomKeysOpts): Promise<void>;\n}\n\n/** The methods which crypto implementations should expose to the Sync api\n *\n * @internal\n */\nexport interface SyncCryptoCallbacks {\n    /**\n     * Called by the /sync loop whenever there are incoming to-device messages.\n     *\n     * The implementation may preprocess the received messages (eg, decrypt them) and return an\n     * updated list of messages for dispatch to the rest of the system.\n     *\n     * Note that, unlike {@link ClientEvent.ToDeviceEvent} events, this is called on the raw to-device\n     * messages, rather than the results of any decryption attempts.\n     *\n     * @param events - the received to-device messages\n     * @returns A list of preprocessed to-device messages.\n     */\n    preprocessToDeviceMessages(events: IToDeviceEvent[]): Promise<IToDeviceEvent[]>;\n\n    /**\n     * Called by the /sync loop when one time key counts and unused fallback key details are received.\n     *\n     * @param oneTimeKeysCounts - the received one time key counts\n     * @param unusedFallbackKeys - the received unused fallback keys\n     */\n    processKeyCounts(oneTimeKeysCounts?: Record<string, number>, unusedFallbackKeys?: string[]): Promise<void>;\n\n    /**\n     * Handle the notification from /sync that device lists have\n     * been changed.\n     *\n     * @param deviceLists - device_lists field from /sync\n     */\n    processDeviceLists(deviceLists: IDeviceLists): Promise<void>;\n\n    /**\n     * Called by the /sync loop whenever an m.room.encryption event is received.\n     *\n     * This is called before RoomStateEvents are emitted for any of the events in the /sync\n     * response (even if the other events technically happened first). This works around a problem\n     * if the client uses a RoomStateEvent (typically a membership event) as a trigger to send a message\n     * in a new room (or one where encryption has been newly enabled): that would otherwise leave the\n     * crypto layer confused because it expects crypto to be set up, but it has not yet been.\n     *\n     * @param room - in which the event was received\n     * @param event - encryption event to be processed\n     */\n    onCryptoEvent(room: Room, event: MatrixEvent): Promise<void>;\n\n    /**\n     * Called by the /sync loop after each /sync response is processed.\n     *\n     * Used to complete batch processing, or to initiate background processes\n     *\n     * @param syncState - information about the completed sync.\n     */\n    onSyncCompleted(syncState: OnSyncCompletedData): void;\n}\n\n/**\n * @internal\n */\nexport interface OnSyncCompletedData {\n    /**\n     * The 'next_batch' result from /sync, which will become the 'since' token for the next call to /sync.\n     */\n    nextSyncToken?: string;\n\n    /**\n     * True if we are working our way through a backlog of events after connecting.\n     */\n    catchingUp?: boolean;\n}\n\n/**\n * Options object for {@link CryptoBackend#checkOwnCrossSigningTrust}.\n */\nexport interface CheckOwnCrossSigningTrustOpts {\n    allowPrivateKeyRequests?: boolean;\n}\n\n/**\n * The result of a (successful) call to {@link CryptoBackend.decryptEvent}\n */\nexport interface EventDecryptionResult {\n    /**\n     * The plaintext payload for the event (typically containing <tt>type</tt> and <tt>content</tt> fields).\n     */\n    clearEvent: IClearEvent;\n    /**\n     * List of curve25519 keys involved in telling us about the senderCurve25519Key and claimedEd25519Key.\n     * See {@link MatrixEvent#getForwardingCurve25519KeyChain}.\n     */\n    forwardingCurve25519KeyChain?: string[];\n    /**\n     * Key owned by the sender of this event.  See {@link MatrixEvent#getSenderKey}.\n     */\n    senderCurve25519Key?: string;\n    /**\n     * ed25519 key claimed by the sender of this event. See {@link MatrixEvent#getClaimedEd25519Key}.\n     */\n    claimedEd25519Key?: string;\n    /**\n     * Whether the keys for this event have been received via an unauthenticated source (eg via key forwards, or\n     * restored from backup)\n     */\n    untrusted?: boolean;\n}\n\n/**\n * Responsible for decrypting megolm session data retrieved from a remote backup.\n * The result of {@link CryptoBackend#getBackupDecryptor}.\n */\nexport interface BackupDecryptor {\n    /**\n     * Whether keys retrieved from this backup can be trusted.\n     *\n     * Depending on the backup algorithm, keys retrieved from the backup can be trusted or not.\n     * If false, keys retrieved from the backup  must be considered unsafe (authenticity cannot be guaranteed).\n     * It could be by design (deniability) or for some technical reason (eg asymmetric encryption).\n     */\n    readonly sourceTrusted: boolean;\n\n    /**\n     *\n     * Decrypt megolm session data retrieved from backup.\n     *\n     * @param ciphertexts - a Record of sessionId to session data.\n     *\n     * @returns An array of decrypted `IMegolmSessionData`\n     */\n    decryptSessions(ciphertexts: Record<string, KeyBackupSession>): Promise<IMegolmSessionData[]>;\n\n    /**\n     * Free any resources held by this decryptor.\n     *\n     * Should be called once the decryptor is no longer needed.\n     */\n    free(): void;\n}\n\n/**\n * Exception thrown when decryption fails\n *\n * @param code - Reason code for the failure.\n *\n * @param msg - user-visible message describing the problem\n *\n * @param details - key/value pairs reported in the logs but not shown\n *   to the user.\n */\nexport class DecryptionError extends Error {\n    public readonly detailedString: string;\n\n    public constructor(\n        public readonly code: DecryptionFailureCode,\n        msg: string,\n        details?: Record<string, string | Error>,\n    ) {\n        super(msg);\n        this.name = \"DecryptionError\";\n        this.detailedString = detailedStringForDecryptionError(this, details);\n    }\n}\n\nfunction detailedStringForDecryptionError(err: DecryptionError, details?: Record<string, string | Error>): string {\n    let result = err.name + \"[msg: \" + err.message;\n\n    if (details) {\n        result +=\n            \", \" +\n            Object.keys(details)\n                .map((k) => k + \": \" + details[k])\n                .join(\", \");\n    }\n\n    result += \"]\";\n\n    return result;\n}\n"],"mappings":";AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAWA;AACA;AACA;AACA;AACA;;AA6FA;AACA;AACA;AACA;;AAwDA;AACA;AACA;;AAaA;AACA;AACA;;AAKA;AACA;AACA;;AA0BA;AACA;AACA;AACA;;AA6BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,eAAe,SAASC,KAAK,CAAC;EAGhCC,WAAWA,CACEC,IAA2B,EAC3CC,GAAW,EACXC,OAAwC,EAC1C;IACE,KAAK,CAACD,GAAG,CAAC;IAAC,KAJKD,IAA2B,GAA3BA,IAA2B;IAAAG,eAAA;IAK3C,IAAI,CAACC,IAAI,GAAG,iBAAiB;IAC7B,IAAI,CAACC,cAAc,GAAGC,gCAAgC,CAAC,IAAI,EAAEJ,OAAO,CAAC;EACzE;AACJ;AAEA,SAASI,gCAAgCA,CAACC,GAAoB,EAAEL,OAAwC,EAAU;EAC9G,IAAIM,MAAM,GAAGD,GAAG,CAACH,IAAI,GAAG,QAAQ,GAAGG,GAAG,CAACE,OAAO;EAE9C,IAAIP,OAAO,EAAE;IACTM,MAAM,IACF,IAAI,GACJE,MAAM,CAACC,IAAI,CAACT,OAAO,CAAC,CACfU,GAAG,CAAEC,CAAC,IAAKA,CAAC,GAAG,IAAI,GAAGX,OAAO,CAACW,CAAC,CAAC,CAAC,CACjCC,IAAI,CAAC,IAAI,CAAC;EACvB;EAEAN,MAAM,IAAI,GAAG;EAEb,OAAOA,MAAM;AACjB","ignoreList":[]}

package/lib/common-crypto/key-passphrase.d.ts

@@ -0,0 +1,14 @@
+interface IAuthData {
+    private_key_salt?: string;
+    private_key_iterations?: number;
+    private_key_bits?: number;
+}
+/**
+ * Derive a backup key from a passphrase using the salt and iterations from the auth data.
+ * @param authData - The auth data containing the salt and iterations
+ * @param passphrase - The passphrase to derive the key from
+ * @deprecated Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/shared via 4S.
+ */
+export declare function keyFromAuthData(authData: IAuthData, passphrase: string): Promise<Uint8Array>;
+export {};
+//# sourceMappingURL=key-passphrase.d.ts.map

package/lib/common-crypto/key-passphrase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-passphrase.d.ts","sourceRoot":"","sources":["../../src/common-crypto/key-passphrase.ts"],"names":[],"mappings":"AAmBA,UAAU,SAAS;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAW5F"}

package/lib/common-crypto/key-passphrase.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2024 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 { deriveRecoveryKeyFromPassphrase } from "../crypto-api/index.js";
+
+/* eslint-disable camelcase */
+
+/**
+ * Derive a backup key from a passphrase using the salt and iterations from the auth data.
+ * @param authData - The auth data containing the salt and iterations
+ * @param passphrase - The passphrase to derive the key from
+ * @deprecated Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/shared via 4S.
+ */
+export function keyFromAuthData(authData, passphrase) {
+  if (!authData.private_key_salt || !authData.private_key_iterations) {
+    throw new Error("Salt and/or iterations not found: " + "this backup cannot be restored with a passphrase");
+  }
+  return deriveRecoveryKeyFromPassphrase(passphrase, authData.private_key_salt, authData.private_key_iterations, authData.private_key_bits);
+}
+//# sourceMappingURL=key-passphrase.js.map

package/lib/common-crypto/key-passphrase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-passphrase.js","names":["deriveRecoveryKeyFromPassphrase","keyFromAuthData","authData","passphrase","private_key_salt","private_key_iterations","Error","private_key_bits"],"sources":["../../src/common-crypto/key-passphrase.ts"],"sourcesContent":["/*\n * Copyright 2024 The Matrix.org Foundation C.I.C.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { deriveRecoveryKeyFromPassphrase } from \"../crypto-api/index.ts\";\n\n/* eslint-disable camelcase */\ninterface IAuthData {\n    private_key_salt?: string;\n    private_key_iterations?: number;\n    private_key_bits?: number;\n}\n\n/**\n * Derive a backup key from a passphrase using the salt and iterations from the auth data.\n * @param authData - The auth data containing the salt and iterations\n * @param passphrase - The passphrase to derive the key from\n * @deprecated Deriving a backup key from a passphrase is not part of the matrix spec. Instead, a random key is generated and stored/shared via 4S.\n */\nexport function keyFromAuthData(authData: IAuthData, passphrase: string): Promise<Uint8Array> {\n    if (!authData.private_key_salt || !authData.private_key_iterations) {\n        throw new Error(\"Salt and/or iterations not found: \" + \"this backup cannot be restored with a passphrase\");\n    }\n\n    return deriveRecoveryKeyFromPassphrase(\n        passphrase,\n        authData.private_key_salt,\n        authData.private_key_iterations,\n        authData.private_key_bits,\n    );\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,+BAA+B,QAAQ,wBAAwB;;AAExE;;AAOA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,eAAeA,CAACC,QAAmB,EAAEC,UAAkB,EAAuB;EAC1F,IAAI,CAACD,QAAQ,CAACE,gBAAgB,IAAI,CAACF,QAAQ,CAACG,sBAAsB,EAAE;IAChE,MAAM,IAAIC,KAAK,CAAC,oCAAoC,GAAG,kDAAkD,CAAC;EAC9G;EAEA,OAAON,+BAA+B,CAClCG,UAAU,EACVD,QAAQ,CAACE,gBAAgB,EACzBF,QAAQ,CAACG,sBAAsB,EAC/BH,QAAQ,CAACK,gBACb,CAAC;AACL","ignoreList":[]}

package/lib/content-helpers.d.ts

@@ -0,0 +1,90 @@
+import { MBeaconEventContent, MBeaconInfoContent, MBeaconInfoEventContent } from "./@types/beacon.ts";
+import { LocationAssetType, LocationEventWireContent, MLocationEventContent, MLocationContent, LegacyLocationEventContent } from "./@types/location.ts";
+import { MRoomTopicEventContent } from "./@types/topic.ts";
+import { RoomMessageEventContent } from "./@types/events.ts";
+/**
+ * Generates the content for a HTML Message event
+ * @param body - the plaintext body of the message
+ * @param htmlBody - the HTML representation of the message
+ * @returns
+ */
+export declare function makeHtmlMessage(body: string, htmlBody: string): RoomMessageEventContent;
+/**
+ * Generates the content for a HTML Notice event
+ * @param body - the plaintext body of the notice
+ * @param htmlBody - the HTML representation of the notice
+ * @returns
+ */
+export declare function makeHtmlNotice(body: string, htmlBody: string): RoomMessageEventContent;
+/**
+ * Generates the content for a HTML Emote event
+ * @param body - the plaintext body of the emote
+ * @param htmlBody - the HTML representation of the emote
+ * @returns
+ */
+export declare function makeHtmlEmote(body: string, htmlBody: string): RoomMessageEventContent;
+/**
+ * Generates the content for a Plaintext Message event
+ * @param body - the plaintext body of the emote
+ * @returns
+ */
+export declare function makeTextMessage(body: string): RoomMessageEventContent;
+/**
+ * Generates the content for a Plaintext Notice event
+ * @param body - the plaintext body of the notice
+ * @returns
+ */
+export declare function makeNotice(body: string): RoomMessageEventContent;
+/**
+ * Generates the content for a Plaintext Emote event
+ * @param body - the plaintext body of the emote
+ * @returns
+ */
+export declare function makeEmoteMessage(body: string): RoomMessageEventContent;
+/** Location content helpers */
+export declare const getTextForLocationEvent: (uri: string | undefined, assetType: LocationAssetType, timestamp?: number, description?: string | null) => string;
+/**
+ * Generates the content for a Location event
+ * @param uri - a geo:// uri for the location
+ * @param timestamp - the timestamp when the location was correct (milliseconds since the UNIX epoch)
+ * @param description - the (optional) label for this location on the map
+ * @param assetType - the (optional) asset type of this location e.g. "m.self"
+ * @param text - optional. A text for the location
+ */
+export declare const makeLocationContent: (text?: string, uri?: string, timestamp?: number, description?: string | null, assetType?: LocationAssetType) => LegacyLocationEventContent & MLocationEventContent;
+/**
+ * Parse location event content and transform to
+ * a backwards compatible modern m.location event format
+ */
+export declare const parseLocationEvent: (wireEventContent: LocationEventWireContent) => MLocationEventContent;
+/**
+ * Topic event helpers
+ */
+export type MakeTopicContent = (topic: string, htmlTopic?: string) => MRoomTopicEventContent;
+export declare const makeTopicContent: MakeTopicContent;
+export type TopicState = {
+    text: string;
+    html?: string;
+};
+export declare const parseTopicContent: (content: MRoomTopicEventContent) => TopicState;
+/**
+ * Beacon event helpers
+ */
+export type MakeBeaconInfoContent = (timeout: number, isLive?: boolean, description?: string, assetType?: LocationAssetType, timestamp?: number) => MBeaconInfoEventContent;
+export declare const makeBeaconInfoContent: MakeBeaconInfoContent;
+export type BeaconInfoState = MBeaconInfoContent & {
+    assetType?: LocationAssetType;
+    timestamp?: number;
+};
+/**
+ * Flatten beacon info event content
+ */
+export declare const parseBeaconInfoContent: (content: MBeaconInfoEventContent) => BeaconInfoState;
+export type MakeBeaconContent = (uri: string, timestamp: number, beaconInfoEventId: string, description?: string) => MBeaconEventContent;
+export declare const makeBeaconContent: MakeBeaconContent;
+export type BeaconLocationState = Omit<MLocationContent, "uri"> & {
+    uri?: string;
+    timestamp?: number;
+};
+export declare const parseBeaconContent: (content: MBeaconEventContent) => BeaconLocationState;
+//# sourceMappingURL=content-helpers.d.ts.map

package/lib/content-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.d.ts","sourceRoot":"","sources":["../src/content-helpers.ts"],"names":[],"mappings":"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"}