glow.ts 1.2.1 → 1.3.1

package/dist/index.d.ts

@@ -221,27 +221,69 @@ export declare class Mailbox {
     /**
      * Sends a free-form object to a guest we already have in our keyring. Set `encrypt` to `false` to
      * send a plaintext message. Returns a token that can be used with `messageStatus` command to check
-     * the status of the message
+     * the status of the message.
+     *
+     * WARNING: a plaintext message (`encrypt = false`) has no confidentiality and no authenticity:
+     * on receipt it is indistinguishable from a message forged by the relay. `download` never
+     * returns it as an authenticated `message`: it is classified as `ZaxMessageKind.unverified` if
+     * the recipient already has the sender's key in their keyring, or as `ZaxMessageKind.plain` if
+     * they do not. Only use plaintext for bootstrap flows where the recipient does not have the
+     * sender's key yet, and never trust its content
      */
     upload(url: string, guestKey: string, message: string, encrypt?: boolean): Promise<Base64>;
     /**
      * Downloads all messages from a relay, decrypts them with a relay key,
-     * and then parses each message to find out if it's a text message, file message,
-     * or if it can't be decrypted because HPK is missing in the keyring.
-     * Returns an array of mixed messages
+     * and then parses each message to find out if it's an authenticated text message (`message`),
+     * a file message (`file`), a message from a sender whose HPK is missing in the keyring
+     * (`plain`), or a message claiming to be from a known sender whose payload failed
+     * authenticated decryption (`unverified`). Returns an array of mixed messages.
+     *
+     * A single malformed message — text or file — never rejects the batch: when its sender
+     * is in the keyring it is returned as `unverified` alongside the messages that did parse
+     * (an unknown sender's payload is returned as `plain` in any case), and the same applies
+     * to a message with an unknown `kind`, which an untrusted relay may set to an arbitrary value
      */
     download(url: string): Promise<ZaxParsedMessage[]>;
+    /**
+     * Classifies a single raw relay message by sender and `kind`
+     */
+    private parseMessage;
     /**
      * Marks a raw Zax message as one that can't be decrypted,
      * because sender's HPK is not found in the keyring
      */
     private parsePlainMessage;
     /**
-     * Decrypts a message that represents uploaded file metadata
+     * Marks a raw Zax message claiming to be from a known sender as one that failed
+     * authentication, passing the relay-supplied payload through untouched
+     */
+    private markUnverified;
+    /**
+     * Decrypts a message that represents uploaded file metadata. A payload that can not be
+     * authenticated (a garbage envelope, a forged ciphertext, or malformed metadata)
+     * is returned as `ZaxMessageKind.unverified` with the raw relay-supplied bytes.
+     *
+     * Unlike text messages, file metadata is always encrypted on upload (`startFileUpload`
+     * has no plaintext option), so an `unverified` file message always indicates forgery,
+     * tampering, or corruption — never a legitimate plaintext upload. Authenticated metadata
+     * is returned as a `file` whatever fields it carries, see `isFileMetadata`
      */
     private parseFileMessage;
+    private static readonly fileMetadataFieldTypes;
+    /**
+     * Runtime check of decrypted file metadata: `JSON.parse` alone accepts any JSON value
+     * (`null`, `42`, `[]`), so require a JSON object. No field is mandatory: which ones a sender
+     * includes is its own contract with the recipient (a client may send nothing but `orig_size`
+     * and the `skey` added by `startFileUpload`), and a missing field says nothing about
+     * authenticity — the payload already passed authenticated decryption. A field that is present
+     * must have its declared type, so that `ReceivedFileMetadata` holds for every `file` message
+     */
+    private static isFileMetadata;
     /**
-     * Attempts to decrypt a regular encrypted Zax message. Returns plain message if it was sent encrypted
+     * Attempts authenticated decryption of a regular Zax message. A payload that can not be
+     * authenticated with the sender's key (a plaintext upload, a forged message, or a tampered
+     * ciphertext — indistinguishable cases on receipt) is returned as `ZaxMessageKind.unverified`
+     * with the raw relay-supplied bytes, so that the application can decide whether to trust it
      */
     private parseTextMessage;
     /**
@@ -265,7 +307,8 @@ export declare class Mailbox {
      */
     startFileUpload(url: string, guest: string, rawMetadata: FileUploadMetadata): Promise<StartFileUploadResponse>;
     /**
-     * Encrypts the file chunk symmetrically and transfers it to a relay
+     * Encrypts the file chunk symmetrically and transfers it to a relay.
+     * The chunk must not exceed `max_chunk_size` returned by `startFileUpload`.
      */
     uploadFileChunk(url: string, uploadID: string, chunk: Uint8Array, part: number, totalParts: number, skey: Uint8Array): Promise<UploadFileChunkResponse>;
     /**
@@ -275,9 +318,10 @@ export declare class Mailbox {
      */
     getFileStatus(url: string, uploadID: string): Promise<FileStatusResponse>;
     /**
-     * Fetches the file metadata by uploadID, which was declared by the uploader
+     * Fetches the file metadata by uploadID, which was declared by the uploader,
+     * or `undefined` when the mailbox holds no `file` message with that uploadID
      */
-    getFileMetadata(url: string, uploadID: string): Promise<FileUploadMetadata>;
+    getFileMetadata(url: string, uploadID: string): Promise<ReceivedFileMetadata | undefined>;
     /**
      * Downloads a binary chunk of a file from a relay by a given uploadID. The total number of chunks
      * can be retrieved via a `getFileStatus` request
@@ -316,7 +360,9 @@ export declare class Mailbox {
     encodeMessage(guest: string, message: string): Promise<EncryptedMessage>;
     /**
      * Decodes a ciphertext from a guest key already in our keyring with this nonce
-     * @returns null if failed to decode
+     * @returns null if the payload could not be authenticated and decrypted with this guest's key.
+     * A `null` carries no information about why: the payload may have been sent as plaintext,
+     * forged, or tampered with — these cases can not be told apart on the receiving side
      */
     decodeMessage(guest: string, nonce: Base64, ctext: Base64): Promise<string | null>;
     /**
@@ -380,6 +426,14 @@ export declare interface NaClDriver {
     from_hex(data: string): Promise<Uint8Array>;
 }
 
+/**
+ * File metadata as it arrives in a `file` message. A sender may include only the fields its
+ * recipient needs, so none of them is guaranteed, but a field that is present has the type
+ * declared in `FileUploadMetadata`: `Mailbox.download` returns metadata that breaks this as
+ * `unverified` instead of a `file`. Fields outside `FileUploadMetadata` pass through untyped
+ */
+export declare type ReceivedFileMetadata = Partial<FileUploadMetadata>;
+
 /**
  * Low-level operations with Zax relay
  */
@@ -517,7 +571,7 @@ export declare class Utils {
 }
 
 export declare interface ZaxFileMessage {
-    data: FileUploadMetadata;
+    data: ReceivedFileMetadata;
     time: number;
     senderTag: string;
     uploadID: string;
@@ -528,10 +582,11 @@ export declare interface ZaxFileMessage {
 export declare enum ZaxMessageKind {
     message = "message",
     file = "file",
-    plain = "plain"
+    plain = "plain",
+    unverified = "unverified"
 }
 
-export declare type ZaxParsedMessage = ZaxPlainMessage | ZaxFileMessage | ZaxTextMessage;
+export declare type ZaxParsedMessage = ZaxPlainMessage | ZaxFileMessage | ZaxTextMessage | ZaxUnverifiedMessage;
 
 export declare interface ZaxPlainMessage {
     data: string;
@@ -553,4 +608,29 @@ export declare interface ZaxTextMessage {
     kind: ZaxMessageKind.message;
 }
 
+/**
+ * A message that claims to come from a known guest (the relay-supplied sender HPK
+ * matched a keyring entry), but whose payload could NOT be authenticated with that
+ * guest's key. This happens both when the sender deliberately uploaded plaintext
+ * (`upload` with `encrypt = false`) and when the ciphertext was forged or tampered
+ * with in transit or by the relay — the two cases are indistinguishable on receipt.
+ * The claimed `senderTag` is therefore unproven: never treat `data` as authentic
+ * unless the application has its own reason to trust unauthenticated content
+ * on this channel.
+ */
+export declare interface ZaxUnverifiedMessage {
+    /**
+     * Raw payload exactly as supplied by the relay, not authenticated or decrypted
+     */
+    data: string;
+    time: number;
+    /**
+     * Tag of the keyring guest the message claims to be from. NOT verified
+     */
+    senderTag: string;
+    from: Base64;
+    nonce: Base64;
+    kind: ZaxMessageKind.unverified;
+}
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glow.ts",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "displayName": "Glow.ts",
   "description": "Client library for interacting with Zax Cryptographic Relay Servers",
   "keywords": [
@@ -52,7 +52,7 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@jest/types": "30.4.1",
-    "@microsoft/api-extractor": "^7.57.7",
+    "@microsoft/api-extractor": "7.59.1",
     "@types/jest": "30.0.0",
     "@types/node": "24.5.2",
     "eslint": "10.6.0",