@gryt/crypto 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,14 @@
-# @gryt/crypto
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Gryt-chat/client/main/public/logo.svg" width="80" alt="Gryt logo" />
+  <h1>@gryt/crypto</h1>
+  <p>Message encryption for <a href="https://gryt.chat">Gryt</a>.<br />Key derivation, key bindings, sealed envelopes, pinning, and the code two people compare out of band.</p>
+</div>
 
-Message encryption for [Gryt](https://gryt.chat): key derivation, key bindings,
-sealed envelopes, pinning, and the code two people compare out of band.
+<br />
+
+```sh
+npm install @gryt/crypto
+```
 
 Used by the desktop client and the mobile app. They run this, not two ports of
 it — two implementations of one envelope is a pair of clients that send each
@@ -20,8 +27,8 @@ either way.
 - **`conversation-encryption`** — every member has a usable key, or nobody gets
   it sealed.
 - **`comparison-code`** — sixty digits two people read to each other.
-- **`attachments`** — a key per file, bound to its id, with the key inside the
-  sealed message.
+- **`attachments`** — a key per file, bound so one file’s bytes cannot be served
+  as another’s, with the key inside the sealed message.
 
 ## Importing it
 
@@ -72,6 +79,20 @@ what a client installs. `check-crypto-vectors.mjs` holds bytes produced before
 the WebCrypto-to-noble conversion and nothing regenerates them — a change that
 quietly altered the envelope would leave every message already sent unreadable.
 
-## Licence
+## Issues
+
+Please report bugs and request features in the
+[main Gryt repository](https://github.com/Gryt-chat/gryt/issues).
+
+## Sponsors
+
+What sponsoring pays for, the tiers, and everyone who has sponsored:
+[gryt.chat/sponsors](https://gryt.chat/sponsors). To sponsor:
+[GitHub Sponsors](https://github.com/sponsors/Gryt-chat).
+
+The list itself lives in the [Gryt README](https://github.com/Gryt-chat/gryt#sponsors),
+in one place rather than ten, so it cannot fall out of step across repositories.
+
+## License
 
-AGPL-3.0-only.
+[AGPL-3.0](https://github.com/Gryt-chat/gryt/blob/main/LICENSE) — Part of [Gryt](https://github.com/Gryt-chat/gryt)

package/dist/attachments.d.ts

@@ -8,6 +8,23 @@ export declare const SEALED_ATTACHMENT_TYPE = "gryt-sealed-attachment";
  * needed.
  */
 export interface SealedAttachmentKey {
+    /**
+     * What the ciphertext is bound to. Generated here, not supplied.
+     *
+     * It used to be the file id, and that could not work: the server assigns the
+     * id, and it assigns it in the response to the upload — by which point the
+     * bytes have already been encrypted and sent. A caller would have had to
+     * choose the id and talk the server into using it, which means a
+     * client-chosen primary key and a uniqueness problem that is the server's to
+     * lose.
+     *
+     * A random value chosen here does the same job. The point of binding was
+     * never the id itself: it is that a server serving one file's bytes under
+     * another's name produces something that does not open. Bound to a value the
+     * sender picked and wrote into the encrypted metadata, a swap still fails,
+     * and nobody has to agree on an id first.
+     */
+    id: string;
     /** The file's own key, base64url. */
     key: string;
     /** Its nonce, base64url. */
@@ -24,16 +41,14 @@ export interface SealedAttachmentKey {
 /**
  * Encrypt a file, ready to upload.
  *
- * The id has to be decided before the bytes are sealed, because it is what they
- * are bound to. Callers generate one rather than taking the server's: an id
- * chosen after the upload would mean either re-encrypting or leaving the bytes
- * unbound, and a server that assigns the id could then assign the same one
- * twice.
+ * Nothing has to be agreed with the server first. The value the ciphertext is
+ * bound to is generated here and returned in `meta`, so a caller can encrypt,
+ * upload, take whatever id the server hands back, and file the metadata under
+ * it — see {@link SealedAttachmentKey.id}.
  */
-export declare function sealAttachment({ bytes, conversationId, fileId, name, mime, width, height, }: {
+export declare function sealAttachment({ bytes, conversationId, name, mime, width, height, }: {
     bytes: Uint8Array;
     conversationId: string;
-    fileId: string;
     name?: string;
     mime?: string;
     width?: number;
@@ -49,9 +64,8 @@ export declare function sealAttachment({ bytes, conversationId, fileId, name, mi
  * message, where a member who joined later legitimately has no key — so a
  * caller should say the file is broken rather than draw an empty one.
  */
-export declare function openAttachment({ ciphertext, conversationId, fileId, meta, }: {
+export declare function openAttachment({ ciphertext, conversationId, meta, }: {
     ciphertext: Uint8Array;
     conversationId: string;
-    fileId: string;
     meta: SealedAttachmentKey;
 }): Uint8Array<ArrayBuffer>;

package/dist/attachments.js

@@ -40,6 +40,14 @@ import { base64Url, base64UrlDecode } from "./base64.js";
  */
 const IV_BYTES = 12;
 const FILE_KEY_BYTES = 32;
+/**
+ * Enough that two attachments never collide, and no more.
+ *
+ * This is not a secret and not a key. It exists so that one file's ciphertext
+ * does not open under another's metadata, so all it has to be is unique among
+ * the attachments a person sends.
+ */
+const BINDING_ID_BYTES = 16;
 export const SEALED_ATTACHMENT_TYPE = "gryt-sealed-attachment";
 function randomBytes(length) {
     const bytes = new Uint8Array(length);
@@ -49,34 +57,36 @@ function randomBytes(length) {
 /**
  * What the ciphertext is bound to.
  *
- * The file id goes in, so the bytes stored under one id cannot be served back
- * under another and still open. A server that swapped two members' uploads
- * would otherwise produce files that decrypt perfectly and are the wrong ones —
- * and since the reader never saw the original, nothing would look wrong.
+ * The sender's own id for this attachment goes in, so bytes stored under one
+ * cannot be served back under another and still open. A server that swapped two
+ * members' uploads would otherwise produce files that decrypt perfectly and are
+ * the wrong ones — and since the reader never saw the original, nothing would
+ * look wrong.
  *
  * The conversation goes in for the reason `message-keys.ts` gives: the same
  * pair talking in two places must not be able to have a file replayed between
  * them.
  */
-function fileContext(conversationId, fileId) {
-    return new TextEncoder().encode(`${SEALED_ATTACHMENT_TYPE}/v1/${conversationId}/${fileId}`);
+function fileContext(conversationId, id) {
+    return new TextEncoder().encode(`${SEALED_ATTACHMENT_TYPE}/v1/${conversationId}/${id}`);
 }
 /**
  * Encrypt a file, ready to upload.
  *
- * The id has to be decided before the bytes are sealed, because it is what they
- * are bound to. Callers generate one rather than taking the server's: an id
- * chosen after the upload would mean either re-encrypting or leaving the bytes
- * unbound, and a server that assigns the id could then assign the same one
- * twice.
+ * Nothing has to be agreed with the server first. The value the ciphertext is
+ * bound to is generated here and returned in `meta`, so a caller can encrypt,
+ * upload, take whatever id the server hands back, and file the metadata under
+ * it — see {@link SealedAttachmentKey.id}.
  */
-export function sealAttachment({ bytes, conversationId, fileId, name, mime, width, height, }) {
+export function sealAttachment({ bytes, conversationId, name, mime, width, height, }) {
+    const id = base64Url(randomBytes(BINDING_ID_BYTES));
     const key = randomBytes(FILE_KEY_BYTES);
     const iv = randomBytes(IV_BYTES);
-    const ciphertext = gcm(key, iv, fileContext(conversationId, fileId)).encrypt(bytes);
+    const ciphertext = gcm(key, iv, fileContext(conversationId, id)).encrypt(bytes);
     return {
         ciphertext: ciphertext,
         meta: {
+            id,
             key: base64Url(key),
             iv: base64Url(iv),
             size: bytes.length,
@@ -94,6 +104,6 @@ export function sealAttachment({ bytes, conversationId, fileId, name, mime, widt
  * message, where a member who joined later legitimately has no key — so a
  * caller should say the file is broken rather than draw an empty one.
  */
-export function openAttachment({ ciphertext, conversationId, fileId, meta, }) {
-    return gcm(base64UrlDecode(meta.key), base64UrlDecode(meta.iv), fileContext(conversationId, fileId)).decrypt(ciphertext);
+export function openAttachment({ ciphertext, conversationId, meta, }) {
+    return gcm(base64UrlDecode(meta.key), base64UrlDecode(meta.iv), fileContext(conversationId, meta.id)).decrypt(ciphertext);
 }

package/dist/index.d.ts

@@ -33,6 +33,7 @@
  * setting.
  */
 export * from "./attachments.js";
+export * from "./base64.js";
 export * from "./comparison-code.js";
 export * from "./conversation-encryption.js";
 export * from "./dm-key-binding.js";

package/dist/index.js

@@ -33,6 +33,10 @@
  * setting.
  */
 export * from "./attachments.js";
+// Exported because both apps carry their own copy of exactly this, and one of
+// the two is the `btoa` version this file was written to replace. They cannot
+// drop theirs while it is package-internal.
+export * from "./base64.js";
 export * from "./comparison-code.js";
 export * from "./conversation-encryption.js";
 export * from "./dm-key-binding.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/crypto",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Message encryption for Gryt: key derivation, key bindings, sealed envelopes, pinning and comparison codes. Shared by the desktop client and the mobile app.",
   "license": "AGPL-3.0-only",
   "repository": {