@atlastodo/client-core 0.1.11-rc.8 → 0.1.11-rc.9

package/dist/fieldPolicy.d.ts

@@ -18,6 +18,8 @@ export interface TokenPolicy {
     max_lifetime_days: number | null;
     /** Whether a token may write when its creator does not say. */
     write_by_default: boolean;
+    /** A token including the app may include no other app (the server refuses the mix). */
+    exclusive: boolean;
 }
 /** A bundled app manifest: its id, version, the entity kinds it syncs and its token policy. */
 export interface AppManifest {
@@ -39,7 +41,8 @@ export declare const BUNDLED_MANIFESTS: readonly AppManifest[];
 /**
  * The policy of a token for all of `apps` (bundled ids), the strictest of theirs as the server
  * takes it: an expiry required if any requires one, the shortest lifetime, and read-only by
- * default if any is. A client making a token reads it to ask for an expiry and write access.
+ * default if any is, and exclusive if any is. A client making a token reads it to ask for an expiry
+ * and write access, and to offer an exclusive app's token on its own.
  */
 export declare function tokenPolicyFor(apps: readonly string[]): TokenPolicy;
 /** The bundled app owning the kind with this wire name, if any. */

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * from "./trust.js";
 export * from "./store.js";
 export * from "./opLogFile.js";
 export * from "./persistence.js";
+export * from "./sealedPersistence.js";
 export * from "./attachments.js";
 export * from "./indexeddb.js";
 export * from "./expo-sqlite.js";

package/dist/index.js

@@ -1478,10 +1478,10 @@ var todo_default = {
 };
 // ../../manifests/vault.json
 var vault_default = {
-  _doc: "The Atlas Vault app manifest: a password manager, end-to-end encrypted, held to a stricter threat model than todo. Its kinds are namespaced `vault.<kind>`. Vault v1 is personal: the server never fans its ops out to another account and reads none of their fields, so every field value is encrypted (no plaintext_fields), including the item type, its folder and its timestamps. `vault.item` is one item (login, note, card, identity, ssh_key, api_key: name, typed fields, urls, notes, tags, folder, favorite, secret field history), `vault.folder` one folder, `vault.preference` one of the app's settings. `api_tokens` is the policy for API tokens that include the app, which the server enforces: an expiry is required, at most `max_lifetime_days` after creation, and a token is read-only unless its creator opts in to writes. Bump `version` whenever the kinds, their plaintext fields or the token policy change.",
+  _doc: "The Atlas Vault app manifest: a password manager, end-to-end encrypted, held to a stricter threat model than todo. Its kinds are namespaced `vault.<kind>`. Vault v1 is personal: the server never fans its ops out to another account and reads none of their fields, so every field value is encrypted (no plaintext_fields), including the item type, its folder and its timestamps. `vault.item` is one item (login, note, card, identity, ssh_key, api_key: name, typed fields, urls, notes, tags, folder, favorite, secret field history), `vault.folder` one folder, `vault.preference` one of the app's settings. `api_tokens` is the policy for API tokens that include the app, which the server enforces: an expiry is required, at most `max_lifetime_days` after creation, a token is read-only unless its creator opts in to writes, and it is for the vault alone (`exclusive`: no other app's key travels with a vault secret). Bump `version` whenever the kinds, their plaintext fields or the token policy change.",
   app: "vault",
   name: "Atlas Vault",
-  version: 1,
+  version: 2,
   kinds: {
     "vault.item": { plaintext_fields: [] },
     "vault.folder": { plaintext_fields: [] },
@@ -1490,7 +1490,8 @@ var vault_default = {
   api_tokens: {
     expiry_required: true,
     max_lifetime_days: 365,
-    write_by_default: false
+    write_by_default: false,
+    exclusive: true
   }
 };
 
@@ -1504,7 +1505,8 @@ function tokenPolicyFor(apps) {
   const policy = {
     expiry_required: false,
     max_lifetime_days: null,
-    write_by_default: true
+    write_by_default: true,
+    exclusive: false
   };
   for (const app of apps) {
     const p = BUNDLED_MANIFESTS.find((m) => m.app === app)?.api_tokens;
@@ -1517,6 +1519,8 @@ function tokenPolicyFor(apps) {
     }
     if (p.write_by_default === false)
       policy.write_by_default = false;
+    if (p.exclusive)
+      policy.exclusive = true;
   }
   return policy;
 }
@@ -4699,8 +4703,110 @@ function rowToOp(r) {
     value: r.value_json === null ? undefined : JSON.parse(r.value_json)
   };
 }
-// src/attachments.ts
+// src/sealedPersistence.ts
+import { hkdf as hkdf7 } from "@noble/hashes/hkdf.js";
 import { sha256 as sha2568 } from "@noble/hashes/sha2.js";
+var LOCAL_STORE_KEY_ID = "local-v1";
+var SCOPE = { kind: "personal" };
+function deriveLocalStoreKey(appKey, userId) {
+  if (appKey.length !== 32)
+    throw new Error("the app key must be 32 bytes");
+  return hkdf7(sha2568, appKey, utf8ToBytes(userId), utf8ToBytes("atlas-local-store-v1"), 32);
+}
+
+class SealedStoreError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SealedStoreError";
+  }
+}
+function seal(key, entity, entityId, field, value) {
+  return encryptField(key, LOCAL_STORE_KEY_ID, SCOPE, { entity, entityId, field }, value);
+}
+function open(key, entity, entityId, field, stored) {
+  if (!isFieldEnvelopeV2(stored) || stored.kid !== LOCAL_STORE_KEY_ID) {
+    throw new SealedStoreError(`a stored value of ${entity}.${field} is not sealed`);
+  }
+  try {
+    return decryptField(key, SCOPE, { entity, entityId, field }, stored);
+  } catch {
+    throw new SealedStoreError(`a stored value of ${entity}.${field} does not open with this key`);
+  }
+}
+function sealOp(key, op) {
+  if (op.op !== "set")
+    return op;
+  return { ...op, value: seal(key, op.entity, op.entityId, op.field, op.value) };
+}
+function openOp(key, op) {
+  if (op.op !== "set")
+    return op;
+  return { ...op, value: open(key, op.entity, op.entityId, op.field, op.value) };
+}
+function sealRepairs(key, repairs) {
+  return repairs.map((r) => ({ ...r, value: seal(key, r.entity, r.entityId, r.field, r.value) }));
+}
+function openRepairs(key, repairs) {
+  return repairs.map((r) => ({ ...r, value: open(key, r.entity, r.entityId, r.field, r.value) }));
+}
+function sealPersistence(inner, key) {
+  if (key.length !== 32)
+    throw new Error("the local store key must be 32 bytes");
+  const sealed = {
+    load: async () => (await inner.load()).map((p) => ({ ...p, op: openOp(key, p.op) })),
+    append: (op, synced) => inner.append(sealOp(key, op), synced),
+    markSynced: (opIds) => inner.markSynced(opIds),
+    getCursor: () => inner.getCursor(),
+    setCursor: (cursor) => inner.setCursor(cursor)
+  };
+  if (inner.appendBatch) {
+    const appendBatch = inner.appendBatch.bind(inner);
+    sealed.appendBatch = (ops, synced) => appendBatch(ops.map((op) => sealOp(key, op)), synced);
+  }
+  if (inner.getBootstrap) {
+    const getBootstrap = inner.getBootstrap.bind(inner);
+    sealed.getBootstrap = async () => {
+      const progress = await getBootstrap();
+      if (!progress?.repairs)
+        return progress;
+      return { ...progress, repairs: openRepairs(key, progress.repairs) };
+    };
+  }
+  if (inner.setBootstrap) {
+    const setBootstrap = inner.setBootstrap.bind(inner);
+    sealed.setBootstrap = (progress, page) => setBootstrap(progress && progress.repairs ? { ...progress, repairs: sealRepairs(key, progress.repairs) } : progress, page ? { ...page, repairs: sealRepairs(key, page.repairs) } : page);
+  }
+  if (inner.commitSyncBatch) {
+    const commit = inner.commitSyncBatch.bind(inner);
+    sealed.commitSyncBatch = (ops, cursor) => commit(ops.map((op) => sealOp(key, op)), cursor);
+  }
+  if (inner.restamp) {
+    const restamp = inner.restamp.bind(inner);
+    sealed.restamp = (ops) => restamp(ops.map((op) => sealOp(key, op)));
+  }
+  const passThrough = [
+    "clear",
+    "clearSynced",
+    "compact",
+    "deleteOps",
+    "close",
+    "loadAttachmentQueue",
+    "putAttachmentUpload",
+    "deleteAttachmentUpload",
+    "listAttachmentQueue",
+    "loadAttachmentCiphertext",
+    "updateAttachmentUpload"
+  ];
+  for (const name of passThrough) {
+    const fn = inner[name];
+    if (typeof fn === "function") {
+      sealed[name] = fn.bind(inner);
+    }
+  }
+  return sealed;
+}
+// src/attachments.ts
+import { sha256 as sha2569 } from "@noble/hashes/sha2.js";
 var DEFAULT_MAX_BLOB_BYTES = 25 * 1024 * 1024;
 function maxAttachmentBytes(maxBlobBytes = DEFAULT_MAX_BLOB_BYTES) {
   return maxPlainSize(maxBlobBytes);
@@ -4718,7 +4824,7 @@ function generateAek() {
   return randomBytes(32);
 }
 function sha256Hex(bytes) {
-  return bytesToHex(sha2568(bytes));
+  return bytesToHex(sha2569(bytes));
 }
 function bytesSource(bytes) {
   return {
@@ -4777,8 +4883,8 @@ async function sealSource(aek, source, opts = {}) {
   const expected = sealedBlobSize(total);
   const sink = opts.asBlob ? new BlobSink : new BufferSink(expected);
   const sealer = new BlobSealer(aek);
-  const blobHash = sha2568.create();
-  const plainHash = sha2568.create();
+  const blobHash = sha2569.create();
+  const plainHash = sha2569.create();
   let size = 0;
   const emit = (bytes) => {
     blobHash.update(bytes);
@@ -4841,7 +4947,7 @@ class PlainCollector {
   out;
   parts = [];
   length = 0;
-  hash = sha2568.create();
+  hash = sha2569.create();
   constructor(blobSize) {
     this.out = blobSize !== null && blobSize <= MAX_PREALLOCATION ? new Uint8Array(blobSize) : null;
   }
@@ -4919,7 +5025,7 @@ async function fetchBlob(transport, sha, aek, plainSha) {
   const download = body instanceof Uint8Array ? { size: body.length, chunks: [body] } : body;
   const opener = new BlobOpener(aek);
   const plain = new PlainCollector(download.size);
-  const received = sha2568.create();
+  const received = sha2569.create();
   for await (const piece of download.chunks) {
     received.update(piece);
     for (const chunk of opener.push(piece))
@@ -6690,6 +6796,7 @@ export {
   Keyring,
   LEGACY_DISCOVERY,
   LEGACY_KDF,
+  LOCAL_STORE_KEY_ID,
   LocalStore,
   MAX_CLOCK_DRIFT_MS,
   MAX_COUNTER,
@@ -6716,6 +6823,7 @@ export {
   SNAPSHOT_PAGE_KEYS,
   SYNC_APPS_HEADER,
   SYNC_PROTOCOL,
+  SealedStoreError,
   ServerIncompatibleError,
   SqlitePersistence,
   SyncClient,
@@ -6765,6 +6873,7 @@ export {
   deriveApiTokenKeys,
   deriveAuthAndMek,
   deriveAuthAndMekAsync,
+  deriveLocalStoreKey,
   derivePasskeySlotKey,
   deriveRecoveryAuthKeypair,
   deriveRecoveryKey,
@@ -6866,6 +6975,7 @@ export {
   sameKeyScope,
   sealDelivery,
   sealKey,
+  sealPersistence,
   sealRootKey,
   sealSource,
   sealedBlobSize,

package/dist/sealedPersistence.d.ts

@@ -0,0 +1,39 @@
+import type { Persistence } from "./persistence.js";
+/**
+ * A {@link Persistence} that keeps every op's value encrypted at rest.
+ *
+ * The local op log holds what the store merged: values already decrypted from the wire. For most
+ * apps that is the device's own business, but a client that locks (a password manager) must not
+ * leave its data readable on disk while it is locked. `sealPersistence(inner, key)` wraps any
+ * backend (IndexedDB, SQLite, memory) so that each `set` op's value, and each bootstrap repair's,
+ * is stored as a field envelope under `key` instead; loading opens them again. Everything else
+ * (op ids, entities, entity ids, field names, clocks, the cursor) is stored as before: the same
+ * metadata the server sees.
+ *
+ * The envelope is the wire's v2 field envelope (AES-256-GCM, padded, associated data naming the
+ * entity, field and scope) with its own key id ({@link LOCAL_STORE_KEY_ID}), so a value sealed
+ * here can neither be opened at another field nor pass for a wire envelope. Use a key of its own
+ * ({@link deriveLocalStoreKey}), not the app key itself.
+ *
+ * Every stored value must be sealed: a backend written without the wrapper, or under another key,
+ * fails to load with {@link SealedStoreError} rather than half-load (start over with `clear()`).
+ * Attachment queue rows pass through unchanged (their blob is already ciphertext; their metadata
+ * is not sealed): a client that needs them sealed must not queue attachments through this.
+ */
+/** The key id of a value sealed at rest; never one the wire uses. */
+export declare const LOCAL_STORE_KEY_ID = "local-v1";
+/**
+ * The at-rest key for a user's local store, derived from an app key the client holds only while
+ * unlocked (HKDF-SHA256, salted with the user id, info `atlas-local-store-v1`).
+ */
+export declare function deriveLocalStoreKey(appKey: Uint8Array, userId: string): Uint8Array;
+/** A stored value that does not open under this key (another key, tampering, or never sealed). */
+export declare class SealedStoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * `inner` with every value sealed under `key` (32 bytes). The wrapper offers exactly the optional
+ * methods `inner` does, so a store's behaviour (batching, restamping, bootstrap resume) is the
+ * inner backend's. Keep a reference to `key` only while the client is unlocked.
+ */
+export declare function sealPersistence(inner: Persistence, key: Uint8Array): Persistence;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlastodo/client-core",
-  "version": "0.1.11-rc.8",
+  "version": "0.1.11-rc.9",
   "description": "Atlas core client: hybrid logical clocks, the op log and per-field LWW merge, end-to-end encryption, the local store and the sync client",
   "license": "AGPL-3.0-only",
   "homepage": "https://github.com/atlastodo/atlas/tree/main/packages/client-core",

package/test-vectors/field_policy_vectors.json

@@ -1,5 +1,5 @@
 {
-  "_doc": "What the bundled app manifests (manifests/*.json) decide, asserted by packages/client-core/src/fieldPolicy.test.ts and crates/atlas-client (field_policy.rs). `fields`: whether a value of `entity`.`field` leaves the device end-to-end encrypted (`encrypted`); a kind no manifest names, and any field a manifest does not list, is encrypted. Todo keeps only the ids the server routes and checks access by in plaintext; journal and vault keep nothing, so the server sees no vault item's type, name, folder, URL, timestamp or secret. `token_policies`: the API token policy of a token for `apps`, the strictest of their manifests' `api_tokens` (`max_lifetime_days` null is no limit).",
+  "_doc": "What the bundled app manifests (manifests/*.json) decide, asserted by packages/client-core/src/fieldPolicy.test.ts and crates/atlas-client (field_policy.rs). `fields`: whether a value of `entity`.`field` leaves the device end-to-end encrypted (`encrypted`); a kind no manifest names, and any field a manifest does not list, is encrypted. Todo keeps only the ids the server routes and checks access by in plaintext; journal and vault keep nothing, so the server sees no vault item's type, name, folder, URL, timestamp or secret. `token_policies`: the API token policy of a token for `apps`, the strictest of their manifests' `api_tokens` (`max_lifetime_days` null is no limit; `exclusive`: the server refuses a token naming such an app with any other).",
   "fields": [
     { "entity": "task", "field": "title", "encrypted": true },
     { "entity": "task", "field": "project_id", "encrypted": false },
@@ -34,19 +34,19 @@
   "token_policies": [
     {
       "apps": ["todo"],
-      "policy": { "expiry_required": false, "max_lifetime_days": null, "write_by_default": true }
+      "policy": { "expiry_required": false, "max_lifetime_days": null, "write_by_default": true, "exclusive": false }
     },
     {
       "apps": ["journal"],
-      "policy": { "expiry_required": false, "max_lifetime_days": null, "write_by_default": true }
+      "policy": { "expiry_required": false, "max_lifetime_days": null, "write_by_default": true, "exclusive": false }
     },
     {
       "apps": ["vault"],
-      "policy": { "expiry_required": true, "max_lifetime_days": 365, "write_by_default": false }
+      "policy": { "expiry_required": true, "max_lifetime_days": 365, "write_by_default": false, "exclusive": true }
     },
     {
       "apps": ["todo", "journal", "vault"],
-      "policy": { "expiry_required": true, "max_lifetime_days": 365, "write_by_default": false }
+      "policy": { "expiry_required": true, "max_lifetime_days": 365, "write_by_default": false, "exclusive": true }
     }
   ]
 }