@3sln/trove 0.0.7 → 0.0.9

package/packages/core/src/encryption/exposure.js

@@ -0,0 +1,101 @@
+// What encryption does not protect you from, said plainly and per collection.
+//
+// Encryption here defends the BUCKET. Anything that indexes a file sees it in the clear,
+// because indexing is by definition reading the contents — the server decrypts before
+// handing bytes to an indexer, and that is the whole reason full search still works on an
+// encrypted collection. So a badge saying "encrypted" is true and, on its own, misleading.
+//
+// The disclosure that matters is therefore not about encryption at all. It is: which things
+// read your files, which of them are third-party code, and where that code is allowed to
+// send what it reads. A built-in indexer runs in this drive and talks to nobody. A plugin
+// indexer might be pointed at an external API, and the manifest already says which one.
+//
+// Read off the manifest rather than written as prose. A sentence in a settings page drifts
+// from what a plugin is actually permitted the moment either changes; a list derived from
+// the declaration it is enforced against cannot. If it says a plugin may reach one host,
+// that is because the plugin may reach exactly that host.
+
+/**
+ * @typedef {object} IndexerExposure
+ * @property {string} id
+ * @property {string} name
+ * @property {'built-in'|'plugin'} source
+ * @property {string|null} pluginId
+ * @property {string[]} endpoints  where this one may send what it reads; empty means nowhere
+ */
+
+/**
+ * Who reads the files in this collection, and where it can send them.
+ *
+ * @param {object} deps
+ * @param {Array<{id: string, displayName?: string}>} deps.indexers  what will run
+ * @param {Array<object>} [deps.plugins]  installed plugin records, with manifests
+ * @param {(manifest: object) => string[]} [deps.endpointsOf]  how to read declared egress
+ * @param {object|null} [deps.encryption]  the collection's encryption config
+ */
+export function describeExposure({ indexers = [], plugins = [], endpointsOf = null, encryption = null } = {}) {
+  // Defaulting this to `() => []` would have every plugin report "reaches nowhere" whenever
+  // a caller forgot to wire it — an affirmative safety claim made with no evidence, which
+  // is the same mistake as calling an unresolved plugin built-in. No reader means unknown.
+  const readEndpoints = typeof endpointsOf === 'function' ? endpointsOf : null;
+  // A plugin indexer's id is a contribution URI — `trove+contrib:<domain>/<name>/<what>` —
+  // so the plugin it belongs to is derivable from the id rather than tracked separately.
+  const byId = new Map();
+  for (const p of plugins) {
+    const id = p.id || p.manifest?.name;
+    if (id) byId.set(id, p);
+  }
+
+  const rows = indexers.map((i) => {
+    // Whether something is a plugin is decided by its ID, not by whether we managed to find
+    // its install record. An indexer whose plugin we cannot resolve is still third-party
+    // code, and calling it built-in would be the most dangerous mislabel available here.
+    const contributed = String(i.id || '').startsWith('trove+contrib:');
+    const owner = contributed ? pluginOf(i.id, byId) : null;
+    return {
+      id: i.id,
+      name: i.displayName || i.id,
+      source: contributed ? 'plugin' : 'built-in',
+      pluginId: owner ? (owner.id || owner.manifest?.name || null) : null,
+      // `[]` is an affirmative claim that this reaches nowhere. Without a manifest we
+      // cannot make it, so an unresolved plugin gets `null` — unknown — and is counted
+      // among the things that might send data out rather than among the things that cannot.
+      endpoints: owner && readEndpoints ? [...new Set(readEndpoints(owner.manifest) || [])] : (contributed ? null : []),
+    };
+  });
+
+  const reachOut = rows.filter((r) => r.endpoints === null || r.endpoints.length);
+  const unknown = rows.filter((r) => r.endpoints === null);
+  return {
+    encrypted: !!encryption?.enabled,
+    // Said explicitly, because "encrypted" without a scope is the thing people
+    // over-read. This is what the encryption is and is not.
+    protects: encryption?.enabled
+      ? 'Files are encrypted before they reach the storage provider, so the bucket holds ciphertext. '
+        + 'It is not end-to-end: this drive holds the key, and anything that indexes a file reads it in the clear.'
+      : null,
+    indexers: rows,
+    // The single fact someone should be able to see without reading a list.
+    anyEgress: reachOut.length > 0,
+    egressSummary: reachOut.length
+      ? `${reachOut.length} of ${rows.length} indexers may send file contents outside this drive.`
+        + (unknown.length
+          ? ` ${unknown.length} could not be checked, because the plugin that provides it is not installed here.`
+          : '')
+      : rows.length
+        ? 'No indexer on this collection may send file contents anywhere.'
+        : 'Nothing indexes this collection.',
+  };
+}
+
+/** Which installed plugin an indexer id belongs to, if any. */
+function pluginOf(indexerId, byId) {
+  const id = String(indexerId || '');
+  if (!id.startsWith('trove+contrib:')) return null;
+  // `trove+contrib:<domain>/<name>/<contribution>` — the plugin is domain/name.
+  const path = id.slice('trove+contrib:'.length);
+  const parts = path.split('/');
+  if (parts.length < 2) return null;
+  const owner = `${parts[0]}/${parts[1]}`;
+  return byId.get(owner) || byId.get(parts[1]) || null;
+}

package/packages/core/src/encryption/keys.js

@@ -0,0 +1,88 @@
+// The key a collection's objects are encrypted with, and the fingerprint that names it.
+//
+// The threat model is the STORAGE HOST, and only that: the bucket holds ciphertext, so a
+// leaked bucket credential, a public-bucket misconfiguration, or a storage vendor who is
+// not the compute vendor learns sizes and timestamps and no content. The server holds the
+// key — it has to, in order to hand it to a client and to decrypt for an indexer — so this
+// is explicitly not end-to-end and does not pretend to be.
+//
+// Which is why the key is GENERATED rather than derived from something a user types.
+// A passphrase would buy nothing here: the server knows the key either way, so there is no
+// protection to gain from the user holding it, and every cost still applies — a slow KDF
+// on every unlock, a prompt in front of every collection, a key that can be forgotten and
+// then cannot be reset by anyone, and a re-encryption of everything whenever someone
+// changes their password. A random 256-bit key has none of that and is stronger than any
+// passphrase a person would choose.
+//
+// Access to the key is therefore an ACCESS-CONTROL question, not a knowledge one: whoever
+// may read the collection may have the key, because they may already read its contents.
+//
+// If this ever becomes end-to-end, the change is confined to where the key comes from and
+// who is allowed it. The envelope, the fingerprint, and every stored object are unchanged.
+
+import { TroveError } from '../errors.js';
+
+const enc = new TextEncoder();
+
+export const KEY_BYTES = 32; // AES-256
+export const FINGERPRINT_BYTES = 16;
+
+/** A new collection key. Random, because there is nothing to derive it from. */
+export function generateDataKey() {
+  return crypto.getRandomValues(new Uint8Array(KEY_BYTES));
+}
+
+/**
+ * The public name of a key.
+ *
+ * Stamped into every object and recorded on the collection, so an object can be matched to
+ * a key by whoever holds it — which is what makes a sideloaded object identifiable and
+ * what lets a key rotation tell what it has already converted.
+ *
+ * Derived through HKDF rather than being a plain hash of the key. With a random 256-bit key
+ * there is nothing to guess, so this is no longer load-bearing against an offline attack;
+ * it stays because a fingerprint should be a value derived FOR this purpose, and a bare
+ * `SHA-256(key)` is a value that might mean something somewhere else. The label makes it
+ * unambiguously this and nothing else.
+ *
+ * @param {Uint8Array} dataKey
+ * @returns {Promise<Uint8Array>} 16 bytes — far past collision risk for "which key is this"
+ */
+export async function fingerprint(dataKey) {
+  if (!(dataKey instanceof Uint8Array) || dataKey.length !== KEY_BYTES) {
+    throw TroveError.invalid('A data key must be 32 bytes');
+  }
+  const base = await crypto.subtle.importKey('raw', dataKey, 'HKDF', false, ['deriveBits']);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: enc.encode('trove-key-id') },
+    base,
+    FINGERPRINT_BYTES * 8,
+  );
+  return new Uint8Array(bits);
+}
+
+/** Bytes as lowercase hex — how a key and a fingerprint are written down. */
+export function toHex(b) {
+  return [...b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}
+
+export function fromHex(hex) {
+  if (typeof hex !== 'string' || !hex.length || hex.length % 2 || /[^0-9a-f]/i.test(hex)) {
+    throw TroveError.invalid('Not hex');
+  }
+  return new Uint8Array(hex.match(/../g).map((h) => parseInt(h, 16)));
+}
+
+/** Kept as the name the rest of the code already uses for a fingerprint in hex. */
+export const fingerprintHex = toHex;
+
+/**
+ * A fresh key and what the collection records about it.
+ *
+ * The key is returned separately from the config because they go to different places: the
+ * config is what any reader may see, and the key is what the server keeps.
+ */
+export async function newCollectionKey() {
+  const dataKey = generateDataKey();
+  return { dataKey, config: { fingerprint: toHex(await fingerprint(dataKey)) } };
+}

package/packages/core/src/encryption/policy.js

@@ -0,0 +1,112 @@
+// Which items in a collection get encrypted, and what the collection tells a client
+// about its key.
+//
+// Encryption is per collection and selective within it, because "encrypt everything" is
+// not always what someone wants and the cost is not free: an encrypted object cannot be
+// served straight from the bucket to something that does not hold the key, and the storage
+// host can no longer deduplicate it. So a collection says which extensions and which media
+// types are sensitive, and the rest is stored as it always was.
+//
+// The rules are matched at UPLOAD time and the answer is recorded in the object itself —
+// the envelope header — rather than re-derived later. Rules change; an object that was
+// encrypted must stay readable as an encrypted object regardless of what the collection
+// says today, and one that was not must not suddenly be interpreted as one.
+
+import { TroveError } from '../errors.js';
+
+/**
+ * What a collection stores about its encryption.
+ *
+ * The fingerprint is safe to show anyone who may see the collection: it names the key
+ * without being it. The key itself is never part of this — it reaches a client through a
+ * transfer plan, which is authorized per operation.
+ *
+ * @typedef {object} EncryptionConfig
+ * @property {boolean} enabled
+ * @property {string} fingerprint hex — which key this collection's objects are sealed with
+ * @property {{extensions: string[], mimeTypes: string[], all: boolean}} rules
+ */
+
+const normList = (v) => (Array.isArray(v) ? v : [])
+  .map((s) => String(s || '').trim().toLowerCase())
+  .filter(Boolean);
+
+/** An extension without its dot, so ".PDF", "PDF" and "pdf" are one rule. */
+const normExt = (e) => e.replace(/^\./, '');
+
+/**
+ * Validate and normalise what a caller asked for, against the key the server holds.
+ *
+ * The fingerprint is a separate argument rather than a field of `input` because the two
+ * come from different places and only one of them is the caller's to decide: rules are
+ * asked for, the key is minted. A collection recorded as encrypted with no fingerprint is
+ * one whose objects could never be matched to a key, so it is refused rather than repaired.
+ *
+ * @param {object|null} input   what the caller asked for: `{ enabled, rules }`
+ * @param {string} [fingerprint] hex, from the collection's key
+ */
+export function normalizeEncryption(input, fingerprint) {
+  if (!input || input.enabled === false) return null;
+  const fp = fingerprint ?? input.fingerprint;
+  if (!fp) throw TroveError.invalid('An encrypted collection needs a key fingerprint');
+  if (!/^[0-9a-f]{32}$/.test(String(fp))) {
+    throw TroveError.invalid('Not a key fingerprint');
+  }
+  const r = input.rules || {};
+  const out = {
+    enabled: true,
+    fingerprint: String(fp),
+    rules: {
+      all: !!r.all,
+      extensions: [...new Set(normList(r.extensions).map(normExt))],
+      mimeTypes: [...new Set(normList(r.mimeTypes))],
+    },
+  };
+  if (!out.rules.all && !out.rules.extensions.length && !out.rules.mimeTypes.length) {
+    // Enabling encryption and matching nothing is almost certainly a mistake, and a silent
+    // one: every upload would be stored in the clear on a collection labelled encrypted.
+    throw TroveError.invalid(
+      'This collection is set to encrypt, but no file would match. Choose "all files", or name some extensions or media types.',
+    );
+  }
+  return out;
+}
+
+/**
+ * Should this item be encrypted?
+ *
+ * A media type match is by full type or by its leading part, so `image` covers
+ * `image/png` without listing every format — which is how someone actually thinks about
+ * "encrypt my photos".
+ */
+export function shouldEncrypt(encryption, { name = '', contentType = '' } = {}) {
+  if (!encryption?.enabled) return false;
+  const { rules } = encryption;
+  if (rules.all) return true;
+
+  const ext = normExt((String(name).match(/\.[^./\\]+$/) || [''])[0].toLowerCase());
+  if (ext && rules.extensions.includes(ext)) return true;
+
+  const type = String(contentType || '').toLowerCase().split(';')[0].trim();
+  if (!type) return false;
+  if (rules.mimeTypes.includes(type)) return true;
+  const [top] = type.split('/');
+  return !!top && rules.mimeTypes.includes(top);
+}
+
+/**
+ * What a client is told about a collection's encryption.
+ *
+ * Enough to know that objects here are sealed and which key seals them; never the key.
+ * There is no "locked" state and nothing to prompt for — a client that may read the
+ * collection is handed the key with the transfer plan, because being allowed to read the
+ * contents and being allowed to decrypt them are the same permission.
+ */
+export function describeEncryption(encryption) {
+  if (!encryption?.enabled) return null;
+  return {
+    enabled: true,
+    fingerprint: encryption.fingerprint,
+    rules: { ...encryption.rules },
+  };
+}