@atlastodo/shared 0.1.11-rc.7 → 0.1.11-rc.8

package/dist/index.d.ts

@@ -51,6 +51,7 @@ export * from "./stats.js";
 export * from "./pomodoro.js";
 export * from "./focus.js";
 export * from "./countdown.js";
+export * from "./vault.js";
 export * from "./swipe.js";
 export * from "./hotkeys.js";
 export * from "./avatarColor.js";

package/dist/index.js

@@ -20775,6 +20775,367 @@ function presetTarget(id, now, timeZone) {
       return makeInstant(p.year + 1, 0, 1, 0, 0, 0, timeZone);
   }
 }
+// src/vault.ts
+var VAULT_ITEM_TYPES = [
+  "login",
+  "note",
+  "card",
+  "identity",
+  "ssh_key",
+  "api_key"
+];
+var VAULT_FIELD_KINDS = ["text", "hidden", "totp", "email", "url", "phone"];
+var VAULT_SECRET_KINDS = ["hidden", "totp"];
+var VAULT_HISTORY_PER_FIELD = 5;
+
+class VaultError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "VaultError";
+  }
+}
+var CREATE_KEYS = ["type", "name", "fields", "urls", "notes", "tags", "folder", "favorite"];
+var PATCH_KEYS = [...CREATE_KEYS, "set_fields", "remove_fields"];
+var bad = (message) => new VaultError("bad_input", message);
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var int = (v) => typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : null;
+var strings = (v) => Array.isArray(v) ? v.filter((s) => typeof s === "string") : [];
+var has = (o, key) => Object.prototype.hasOwnProperty.call(o, key);
+var sameName = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
+var isSecret = (kind) => VAULT_SECRET_KINDS.includes(kind) || !VAULT_FIELD_KINDS.includes(kind);
+function jsonEqual(a, b) {
+  if (a === b)
+    return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => jsonEqual(x, b[i]));
+  }
+  if (isObject(a) && isObject(b)) {
+    const ka = Object.keys(a);
+    return ka.length === Object.keys(b).length && ka.every((k) => has(b, k) && jsonEqual(a[k], b[k]));
+  }
+  return false;
+}
+function cleanVaultTags(tags) {
+  const out = [];
+  for (const t of tags.map((t) => t.trim())) {
+    if (t && !out.some((o) => o.toLowerCase() === t.toLowerCase()))
+      out.push(t);
+  }
+  return out;
+}
+function cleanVaultUrls(urls) {
+  const out = [];
+  for (const u of urls.map((u) => u.trim()))
+    if (u && !out.includes(u))
+      out.push(u);
+  return out;
+}
+function readFields(v) {
+  if (!Array.isArray(v))
+    return [];
+  const out = [];
+  for (const f of v) {
+    if (!isObject(f) || typeof f.name !== "string" || typeof f.value !== "string")
+      continue;
+    out.push({ name: f.name, kind: typeof f.kind === "string" ? f.kind : "text", value: f.value });
+  }
+  return out;
+}
+function readHistory(v) {
+  if (!Array.isArray(v))
+    return [];
+  const out = [];
+  for (const h of v) {
+    if (!isObject(h) || typeof h.field !== "string" || typeof h.value !== "string")
+      continue;
+    out.push({ field: h.field, value: h.value, changed_at: int(h.changed_at) ?? 0 });
+  }
+  return out;
+}
+function toVaultItem(id, f) {
+  const text = (k) => typeof f[k] === "string" ? f[k] : "";
+  return {
+    id,
+    type: typeof f.type === "string" ? f.type : "login",
+    name: text("name"),
+    fields: readFields(f.fields),
+    urls: strings(f.urls),
+    notes: text("notes"),
+    tags: strings(f.tags),
+    folder: typeof f.folder === "string" ? f.folder : null,
+    favorite: typeof f.favorite === "boolean" ? f.favorite : false,
+    history: readHistory(f.history),
+    created_at: int(f.created_at) ?? 0,
+    updated_at: int(f.updated_at) ?? 0,
+    deleted_at: int(f.deleted_at)
+  };
+}
+function summarizeVaultItem(item) {
+  return {
+    id: item.id,
+    type: item.type,
+    name: item.name,
+    fields: item.fields.map((f) => ({ name: f.name, kind: f.kind })),
+    urls: [...item.urls],
+    tags: [...item.tags],
+    folder: item.folder,
+    favorite: item.favorite,
+    created_at: item.created_at,
+    updated_at: item.updated_at,
+    deleted_at: item.deleted_at
+  };
+}
+function checkKeys(input, allowed) {
+  const unknown = Object.keys(input).sort().find((k) => !allowed.includes(k));
+  if (unknown !== undefined)
+    throw bad(`${unknown} is not a vault item field`);
+}
+function checkType(v) {
+  if (typeof v === "string" && VAULT_ITEM_TYPES.includes(v))
+    return v;
+  throw bad(`type must be one of ${VAULT_ITEM_TYPES.join(", ")}`);
+}
+function checkName(v) {
+  if (typeof v !== "string")
+    throw bad("name must be a string");
+  const name = v.trim();
+  if (!name)
+    throw bad("a vault item needs a name");
+  return name;
+}
+function checkStrings(key, v) {
+  if (!Array.isArray(v) || !v.every((s) => typeof s === "string")) {
+    throw bad(`${key} must be a list of strings`);
+  }
+  return v;
+}
+function checkNotes(v) {
+  if (typeof v !== "string")
+    throw bad("notes must be a string");
+  return v;
+}
+function checkFolder(v) {
+  if (v === null)
+    return null;
+  if (typeof v === "string" && v.trim())
+    return v.trim();
+  throw bad("folder must be a folder id or null");
+}
+function checkFavorite(v) {
+  if (typeof v !== "boolean")
+    throw bad("favorite must be true or false");
+  return v;
+}
+function givenField(key, v) {
+  const shape = () => bad(`${key} must be a list of {name, kind, value} objects with string values`);
+  if (!isObject(v) || typeof v.name !== "string" || typeof v.value !== "string")
+    throw shape();
+  let kind = null;
+  if (v.kind !== undefined && v.kind !== null) {
+    if (typeof v.kind !== "string")
+      throw shape();
+    kind = v.kind;
+  }
+  const name = v.name.trim();
+  if (!name)
+    throw bad("a field needs a name");
+  if (kind !== null && !VAULT_FIELD_KINDS.includes(kind)) {
+    throw bad(`field kind must be one of ${VAULT_FIELD_KINDS.join(", ")}`);
+  }
+  return { name, kind, value: v.value };
+}
+function fieldValue(name, kind, value) {
+  if (kind !== "totp")
+    return value;
+  const t = value.trim();
+  if (t.slice(0, 10).replace(/[A-Z]/g, (c) => c.toLowerCase()) === "otpauth://")
+    return t;
+  const seed = t.replace(/\s/g, "").replace(/[a-z]/g, (c) => c.toUpperCase()).replace(/=+$/, "");
+  if (!seed || !/^[A-Z2-7]+$/.test(seed)) {
+    throw bad(`the totp field "${name}" needs an otpauth:// URI or a base32 secret`);
+  }
+  return seed;
+}
+function givenFields(v) {
+  if (!Array.isArray(v)) {
+    throw bad("fields must be a list of {name, kind, value} objects with string values");
+  }
+  const out = [];
+  for (const item of v) {
+    const g = givenField("fields", item);
+    const kind = g.kind ?? "text";
+    const value = fieldValue(g.name, kind, g.value);
+    if (out.some((f) => sameName(f.name, g.name))) {
+      throw bad(`two fields are named "${g.name.toLowerCase()}"`);
+    }
+    out.push({ name: g.name, kind, value });
+  }
+  return out;
+}
+var fieldJson = (f) => ({ name: f.name, kind: f.kind, value: f.value });
+var historyJson = (h) => ({
+  field: h.field,
+  value: h.value,
+  changed_at: h.changed_at
+});
+function newVaultItemFields(input, now) {
+  if (!isObject(input))
+    throw bad("a vault item is a JSON object");
+  checkKeys(input, CREATE_KEYS);
+  const type = has(input, "type") ? checkType(input.type) : "login";
+  if (!has(input, "name"))
+    throw bad("a vault item needs a name");
+  const name = checkName(input.name);
+  const fields = has(input, "fields") ? givenFields(input.fields) : [];
+  const urls = has(input, "urls") ? cleanVaultUrls(checkStrings("urls", input.urls)) : [];
+  const notes = has(input, "notes") ? checkNotes(input.notes) : "";
+  const tags = has(input, "tags") ? cleanVaultTags(checkStrings("tags", input.tags)) : [];
+  const folder = has(input, "folder") ? checkFolder(input.folder) : null;
+  const favorite = has(input, "favorite") ? checkFavorite(input.favorite) : false;
+  return {
+    type,
+    name,
+    fields: fields.map(fieldJson),
+    urls,
+    notes,
+    tags,
+    folder,
+    favorite,
+    history: [],
+    created_at: now,
+    updated_at: now
+  };
+}
+function patchedFields(current, set, remove) {
+  let fields = current.map((f) => ({ ...f }));
+  if (remove !== undefined) {
+    for (const name of checkStrings("remove_fields", remove)) {
+      const before = fields.length;
+      fields = fields.filter((f) => !sameName(f.name, name));
+      if (fields.length === before)
+        throw bad(`no field "${name.trim()}" to remove`);
+    }
+  }
+  if (set !== undefined) {
+    if (!Array.isArray(set)) {
+      throw bad("set_fields must be a list of {name, kind, value} objects with string values");
+    }
+    for (const item of set) {
+      const g = givenField("set_fields", item);
+      const existing = fields.find((f) => sameName(f.name, g.name));
+      if (existing) {
+        if (g.kind !== null)
+          existing.kind = g.kind;
+        existing.value = fieldValue(existing.name, existing.kind, g.value);
+      } else {
+        const kind = g.kind ?? "text";
+        fields.push({ name: g.name, kind, value: fieldValue(g.name, kind, g.value) });
+      }
+    }
+  }
+  return fields;
+}
+function nextHistory(history, before, after, now) {
+  const entries = before.filter((old) => isSecret(old.kind)).filter((old) => {
+    const next = after.find((f) => sameName(f.name, old.name));
+    return !next || next.value !== old.value;
+  }).map((old) => ({ field: old.name, value: old.value, changed_at: now }));
+  entries.push(...history);
+  const counts = new Map;
+  return entries.filter((e) => {
+    const key = e.field.trim().toLowerCase();
+    const n = (counts.get(key) ?? 0) + 1;
+    counts.set(key, n);
+    return n <= VAULT_HISTORY_PER_FIELD;
+  });
+}
+function vaultItemChanges(current, patch, now) {
+  if (!isObject(patch))
+    throw bad("a vault item change is a JSON object");
+  checkKeys(patch, PATCH_KEYS);
+  if (has(patch, "fields") && (has(patch, "set_fields") || has(patch, "remove_fields"))) {
+    throw bad("give fields (the whole list) or set_fields and remove_fields, not both");
+  }
+  const item = toVaultItem("", current);
+  const changes = {};
+  if (has(patch, "type")) {
+    const t = checkType(patch.type);
+    if (t !== item.type)
+      changes.type = t;
+  }
+  if (has(patch, "name")) {
+    const n = checkName(patch.name);
+    if (n !== item.name)
+      changes.name = n;
+  }
+  let fields = null;
+  if (has(patch, "fields"))
+    fields = givenFields(patch.fields);
+  else if (has(patch, "set_fields") || has(patch, "remove_fields")) {
+    fields = patchedFields(item.fields, patch.set_fields, patch.remove_fields);
+  }
+  if (fields) {
+    const list = fields;
+    const dup = list.find((f, i) => list.slice(0, i).some((g) => sameName(g.name, f.name)));
+    if (dup)
+      throw bad(`two fields are named "${dup.name.trim().toLowerCase()}"`);
+    if (!jsonEqual(list, item.fields)) {
+      const history = nextHistory(item.history, item.fields, list, now);
+      changes.fields = list.map(fieldJson);
+      if (!jsonEqual(history, item.history))
+        changes.history = history.map(historyJson);
+    }
+  }
+  if (has(patch, "urls")) {
+    const urls = cleanVaultUrls(checkStrings("urls", patch.urls));
+    if (!jsonEqual(urls, item.urls))
+      changes.urls = urls;
+  }
+  if (has(patch, "notes")) {
+    const notes = checkNotes(patch.notes);
+    if (notes !== item.notes)
+      changes.notes = notes;
+  }
+  if (has(patch, "tags")) {
+    const tags = cleanVaultTags(checkStrings("tags", patch.tags));
+    if (!jsonEqual(tags, item.tags))
+      changes.tags = tags;
+  }
+  if (has(patch, "folder")) {
+    const folder = checkFolder(patch.folder);
+    if (folder !== item.folder)
+      changes.folder = folder;
+  }
+  if (has(patch, "favorite")) {
+    const favorite = checkFavorite(patch.favorite);
+    if (favorite !== item.favorite)
+      changes.favorite = favorite;
+  }
+  if (Object.keys(changes).length > 0)
+    changes.updated_at = now;
+  return changes;
+}
+function resolveVaultItem(items, ref) {
+  const r = ref.trim();
+  const byId = items.find((i) => i.id === r);
+  if (byId)
+    return byId.id;
+  const named = items.filter((i) => i.deleted_at == null && sameName(i.name, r)).map((i) => i.id).sort();
+  if (named.length === 1)
+    return named[0];
+  if (named.length === 0)
+    throw new VaultError("unknown_vault_item", `no vault item "${r}"`);
+  throw new VaultError("ambiguous_vault_item", `"${r}" names ${named.length} vault items (${named.join(", ")}); use an id`);
+}
+function vaultItemField(item, name) {
+  const field = item.fields.find((f) => sameName(f.name, name));
+  if (field)
+    return field.value;
+  const hasFields = item.fields.length ? `it has: ${item.fields.map((f) => f.name).join(", ")}` : "it has none";
+  throw new VaultError("unknown_vault_field", `vault item "${item.name}" has no field "${name.trim()}" (${hasFields})`);
+}
 // src/swipe.ts
 var TASK_SWIPE_ACTIONS = [
   "complete",
@@ -21203,6 +21564,11 @@ export {
   TOAST_TTL_MS,
   TRASH_KINDS,
   TRASH_RETENTION_MS,
+  VAULT_FIELD_KINDS,
+  VAULT_HISTORY_PER_FIELD,
+  VAULT_ITEM_TYPES,
+  VAULT_SECRET_KINDS,
+  VaultError,
   accentVars,
   addDays,
   adoptBooked,
@@ -21224,6 +21590,8 @@ export {
   bundleFilename,
   clampOffset,
   classifySwipe,
+  cleanVaultTags,
+  cleanVaultUrls,
   columnCards,
   columnMoveManyWrites,
   columnMoveWrites,
@@ -21322,6 +21690,7 @@ export {
   moveSectionToProject,
   moveTask,
   moveTaskToProject,
+  newVaultItemFields,
   nextDue,
   nextOccurrence,
   nextOccurrenceCivil,
@@ -21374,6 +21743,7 @@ export {
   resolveTaskSwipe,
   resolveTheme,
   resolveTimeZone,
+  resolveVaultItem,
   resources,
   restoreEntity,
   restoreFromTrash,
@@ -21401,6 +21771,7 @@ export {
   strengthSeries,
   stripTrailingSlash,
   subtreeProgress,
+  summarizeVaultItem,
   sweepExpiredTrash,
   taskComparator,
   taskContextClosure,
@@ -21422,6 +21793,7 @@ export {
   toReminder,
   toSection,
   toTask,
+  toVaultItem,
   toastReducer,
   todayTasks,
   todoistProjectName,
@@ -21434,6 +21806,8 @@ export {
   upcomingTasks,
   updateRecurringTask,
   updateTask,
+  vaultItemChanges,
+  vaultItemField,
   visibleSections,
   visibleTasks,
   weekDays,

package/dist/vault.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Atlas Vault item rules (`vault.item`, manifests/vault.json), at parity with
+ * `crates/atlas-client/src/vault.rs` through `test-vectors/vault_item_vectors.json`. Every field of
+ * an item is end-to-end encrypted under the vault app key; these rules decide what a client
+ * writes. An item's stored fields:
+ * - `type`: one of {@link VAULT_ITEM_TYPES}; `name`: non-empty text.
+ * - `fields`: `{name, kind, value}[]`, names unique case-insensitively, `kind` one of
+ *   {@link VAULT_FIELD_KINDS}; `hidden` and `totp` values are secrets (a TOTP value is an
+ *   `otpauth://` URI or a base32 seed, stored upper-case without spaces or padding).
+ * - `urls`, `tags`: string lists; `notes`: text; `folder`: a `vault.folder` id or null;
+ *   `favorite`: a boolean.
+ * - `history`: earlier values of secret fields, `{field, value, changed_at}`, newest first, at most
+ *   {@link VAULT_HISTORY_PER_FIELD} per field name.
+ * - `created_at`, `updated_at`: unix ms; `deleted_at`: unix ms once in the trash, else null.
+ */
+export declare const VAULT_ITEM_TYPES: readonly ["login", "note", "card", "identity", "ssh_key", "api_key"];
+export declare const VAULT_FIELD_KINDS: readonly ["text", "hidden", "totp", "email", "url", "phone"];
+/** Secret field kinds; a kind this client does not know counts as secret too. */
+export declare const VAULT_SECRET_KINDS: readonly ["hidden", "totp"];
+export declare const VAULT_HISTORY_PER_FIELD = 5;
+export type VaultItemType = (typeof VAULT_ITEM_TYPES)[number];
+export interface VaultField {
+    name: string;
+    kind: string;
+    value: string;
+}
+export interface VaultHistoryEntry {
+    field: string;
+    value: string;
+    changed_at: number;
+}
+/** A vault item as integrations see it, secrets included. */
+export interface VaultItem {
+    id: string;
+    type: string;
+    name: string;
+    fields: VaultField[];
+    urls: string[];
+    notes: string;
+    tags: string[];
+    folder: string | null;
+    favorite: boolean;
+    history: VaultHistoryEntry[];
+    created_at: number;
+    updated_at: number;
+    deleted_at: number | null;
+}
+/** An item in a listing: everything but the field values, notes and history. */
+export interface VaultItemSummary {
+    id: string;
+    type: string;
+    name: string;
+    fields: {
+        name: string;
+        kind: string;
+    }[];
+    urls: string[];
+    tags: string[];
+    folder: string | null;
+    favorite: boolean;
+    created_at: number;
+    updated_at: number;
+    deleted_at: number | null;
+}
+/** A field as given: kind `text` when left out. */
+export interface VaultFieldInput {
+    name: string;
+    kind?: string;
+    value: string;
+}
+/** A new item. `folder` is a folder id (a client resolves names first). */
+export interface VaultItemInput {
+    type?: string;
+    name: string;
+    fields?: VaultFieldInput[];
+    urls?: string[];
+    notes?: string;
+    tags?: string[];
+    folder?: string | null;
+    favorite?: boolean;
+}
+/**
+ * A change: `fields` replaces the list; `set_fields` sets one field's value (and kind, when
+ * given) or appends it, `remove_fields` removes fields by name; `folder: null` clears it.
+ */
+export interface VaultItemPatch extends Partial<Omit<VaultItemInput, "fields">> {
+    fields?: VaultFieldInput[];
+    set_fields?: VaultFieldInput[];
+    remove_fields?: string[];
+}
+/** A rule refused the input; `code` is stable (`bad_input`, `unknown_vault_item`, …). */
+export declare class VaultError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Tags trimmed, without empty ones or repeats (case-insensitive), in order. */
+export declare function cleanVaultTags(tags: readonly string[]): string[];
+/** URLs trimmed, without empty ones or exact repeats, in order. */
+export declare function cleanVaultUrls(urls: readonly string[]): string[];
+/**
+ * Read an item's stored fields, tolerating values of the wrong shape (another client's): an
+ * unknown type or field kind is kept, anything malformed is dropped or defaulted.
+ */
+export declare function toVaultItem(id: string, f: Record<string, unknown>): VaultItem;
+/** The listing form of an item: no field values, notes or history. */
+export declare function summarizeVaultItem(item: VaultItem): VaultItemSummary;
+/** The stored fields of a new item from `input` at `now`; throws {@link VaultError}. */
+export declare function newVaultItemFields(input: unknown, now: number): Record<string, unknown>;
+/**
+ * The fields a patch writes to the item stored as `current` at `now` (empty when nothing changes;
+ * `updated_at` with any change); throws {@link VaultError}.
+ */
+export declare function vaultItemChanges(current: Record<string, unknown>, patch: unknown, now: number): Record<string, unknown>;
+/**
+ * The id `ref` names among `items`: an id, trashed or not, or a name (case-insensitive, trimmed)
+ * of exactly one item outside the trash; throws `unknown_vault_item` or `ambiguous_vault_item`.
+ */
+export declare function resolveVaultItem(items: readonly {
+    id: string;
+    name: string;
+    deleted_at: number | null;
+}[], ref: string): string;
+/** The value of the item's field named `name` (case-insensitive), exactly as stored. */
+export declare function vaultItemField(item: Pick<VaultItem, "name" | "fields">, name: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlastodo/shared",
-  "version": "0.1.11-rc.7",
+  "version": "0.1.11-rc.8",
   "description": "Atlas shared logic: the portable task rules, recurrence, quick add, filters, i18n and theme used by every Atlas client",
   "license": "AGPL-3.0-only",
   "homepage": "https://github.com/atlastodo/atlas/tree/main/packages/shared",
@@ -36,7 +36,8 @@
       "filter_vectors.json",
       "quick_add_vectors.json",
       "recurrence_vectors.json",
-      "task_rules_vectors.json"
+      "task_rules_vectors.json",
+      "vault_item_vectors.json"
     ]
   },
   "scripts": {
@@ -45,7 +46,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@atlastodo/client-core": "0.1.11-rc.7",
+    "@atlastodo/client-core": "0.1.11-rc.8",
     "@noble/hashes": "^2.4.0",
     "fflate": "^0.8.3"
   },

package/test-vectors/vault_item_vectors.json

@@ -0,0 +1,563 @@
+{
+  "_doc": "The Atlas Vault item rules (packages/shared/src/vault.ts, crates/atlas-client/src/vault.rs), asserted by both. Every value is a field of a `vault.item` entity, end-to-end encrypted (manifests/vault.json keeps none plaintext). `create`: `input` (the keys type, name, fields, urls, notes, tags, folder, favorite) at `now` gives the stored `fields`, or fails with `error` {code, message}. `update`: a stored `item` and a `patch` (the create keys, `folder: null` clears; or `set_fields`/`remove_fields` instead of `fields`) at `now` give the `changes` written (field → value; none when nothing changed), or an `error`. A changed or removed secret field (kind hidden or totp) leaves its old value in `history`, newest first, at most 5 per field name. `read`: raw stored `fields` (another client's, possibly malformed) read as `item` and listed as `summary` (no field values). `resolve`: a reference (id, or name case-insensitively among items outside the trash) among `items` gives an `id` or an `error`. `field`: one field's value by name, case-insensitively.",
+  "now": 1791972000000,
+  "create": [
+    {
+      "name": "a login with a username, password and TOTP seed",
+      "input": {
+        "type": "login",
+        "name": "  GitHub ",
+        "fields": [
+          { "name": "username", "value": "octo" },
+          { "name": "password", "kind": "hidden", "value": " pa ss " },
+          { "name": "totp", "kind": "totp", "value": "jbsw y3dp ehpk 3pxp==" }
+        ],
+        "urls": [" https://github.com ", "", "https://github.com", "https://github.com/login"],
+        "tags": ["work", " Work", "dev"],
+        "favorite": true
+      },
+      "fields": {
+        "type": "login",
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "password", "kind": "hidden", "value": " pa ss " },
+          { "name": "totp", "kind": "totp", "value": "JBSWY3DPEHPK3PXP" }
+        ],
+        "urls": ["https://github.com", "https://github.com/login"],
+        "notes": "",
+        "tags": ["work", "dev"],
+        "folder": null,
+        "favorite": true,
+        "history": [],
+        "created_at": 1791972000000,
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "the defaults: a login with nothing but a name",
+      "input": { "name": "Router" },
+      "fields": {
+        "type": "login",
+        "name": "Router",
+        "fields": [],
+        "urls": [],
+        "notes": "",
+        "tags": [],
+        "folder": null,
+        "favorite": false,
+        "history": [],
+        "created_at": 1791972000000,
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "an API key in a folder, with an otpauth URI kept as given",
+      "input": {
+        "type": "api_key",
+        "name": "Deploy key",
+        "fields": [
+          { "name": "key", "kind": "hidden", "value": "sk_live_123" },
+          {
+            "name": "2fa",
+            "kind": "totp",
+            "value": " otpauth://totp/Atlas:me?secret=JBSWY3DPEHPK3PXP&issuer=Atlas "
+          }
+        ],
+        "notes": "Rotate yearly.\n",
+        "folder": "0192f000-0000-7000-8000-00000000f001"
+      },
+      "fields": {
+        "type": "api_key",
+        "name": "Deploy key",
+        "fields": [
+          { "name": "key", "kind": "hidden", "value": "sk_live_123" },
+          {
+            "name": "2fa",
+            "kind": "totp",
+            "value": "otpauth://totp/Atlas:me?secret=JBSWY3DPEHPK3PXP&issuer=Atlas"
+          }
+        ],
+        "urls": [],
+        "notes": "Rotate yearly.\n",
+        "tags": [],
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "favorite": false,
+        "history": [],
+        "created_at": 1791972000000,
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "every type is accepted",
+      "input": { "type": "ssh_key", "name": "laptop", "fields": [{ "name": "private key", "kind": "hidden", "value": "-----BEGIN" }] },
+      "fields": {
+        "type": "ssh_key",
+        "name": "laptop",
+        "fields": [{ "name": "private key", "kind": "hidden", "value": "-----BEGIN" }],
+        "urls": [],
+        "notes": "",
+        "tags": [],
+        "folder": null,
+        "favorite": false,
+        "history": [],
+        "created_at": 1791972000000,
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "a name is required",
+      "input": { "type": "note", "name": "   ", "notes": "x" },
+      "error": { "code": "bad_input", "message": "a vault item needs a name" }
+    },
+    {
+      "name": "an unknown type",
+      "input": { "type": "wifi", "name": "Home" },
+      "error": {
+        "code": "bad_input",
+        "message": "type must be one of login, note, card, identity, ssh_key, api_key"
+      }
+    },
+    {
+      "name": "an unknown key, such as a typo",
+      "input": { "name": "x", "url": "https://example.com" },
+      "error": { "code": "bad_input", "message": "url is not a vault item field" }
+    },
+    {
+      "name": "two fields with one name, case-insensitively",
+      "input": {
+        "name": "x",
+        "fields": [
+          { "name": "Password", "kind": "hidden", "value": "a" },
+          { "name": "password ", "kind": "hidden", "value": "b" }
+        ]
+      },
+      "error": { "code": "bad_input", "message": "two fields are named \"password\"" }
+    },
+    {
+      "name": "a field without a name",
+      "input": { "name": "x", "fields": [{ "name": " ", "value": "a" }] },
+      "error": { "code": "bad_input", "message": "a field needs a name" }
+    },
+    {
+      "name": "an unknown field kind",
+      "input": { "name": "x", "fields": [{ "name": "pin", "kind": "secret", "value": "1234" }] },
+      "error": {
+        "code": "bad_input",
+        "message": "field kind must be one of text, hidden, totp, email, url, phone"
+      }
+    },
+    {
+      "name": "a field value that is not a string",
+      "input": { "name": "x", "fields": [{ "name": "pin", "kind": "hidden", "value": 1234 }] },
+      "error": {
+        "code": "bad_input",
+        "message": "fields must be a list of {name, kind, value} objects with string values"
+      }
+    },
+    {
+      "name": "a TOTP seed that is not base32",
+      "input": { "name": "x", "fields": [{ "name": "totp", "kind": "totp", "value": "not base32!" }] },
+      "error": {
+        "code": "bad_input",
+        "message": "the totp field \"totp\" needs an otpauth:// URI or a base32 secret"
+      }
+    },
+    {
+      "name": "a TOTP seed with a letter outside base32 (only ASCII is upper-cased)",
+      "input": { "name": "x", "fields": [{ "name": "totp", "kind": "totp", "value": "straße" }] },
+      "error": {
+        "code": "bad_input",
+        "message": "the totp field \"totp\" needs an otpauth:// URI or a base32 secret"
+      }
+    },
+    {
+      "name": "urls must be strings",
+      "input": { "name": "x", "urls": ["https://a.example", 7] },
+      "error": { "code": "bad_input", "message": "urls must be a list of strings" }
+    },
+    {
+      "name": "favorite must be a boolean",
+      "input": { "name": "x", "favorite": "yes" },
+      "error": { "code": "bad_input", "message": "favorite must be true or false" }
+    },
+    {
+      "name": "folder must be an id or null",
+      "input": { "name": "x", "folder": 3 },
+      "error": { "code": "bad_input", "message": "folder must be a folder id or null" }
+    },
+    {
+      "name": "set_fields is for updates",
+      "input": { "name": "x", "set_fields": [] },
+      "error": { "code": "bad_input", "message": "set_fields is not a vault item field" }
+    }
+  ],
+  "update": [
+    {
+      "name": "a new password keeps the old one in the history",
+      "item": {
+        "type": "login",
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "password", "kind": "hidden", "value": "old" }
+        ],
+        "urls": [],
+        "notes": "",
+        "tags": [],
+        "folder": null,
+        "favorite": false,
+        "history": [],
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": { "set_fields": [{ "name": "Password", "value": "new" }] },
+      "changes": {
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "password", "kind": "hidden", "value": "new" }
+        ],
+        "history": [{ "field": "password", "value": "old", "changed_at": 1791972000000 }],
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "a text field changes without history; a new field is appended as text",
+      "item": {
+        "type": "login",
+        "name": "GitHub",
+        "fields": [{ "name": "username", "kind": "text", "value": "octo" }],
+        "history": [],
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": {
+        "set_fields": [
+          { "name": "username", "value": "cat" },
+          { "name": "recovery email", "kind": "email", "value": "me@example.com" },
+          { "name": "note" , "value": "" }
+        ]
+      },
+      "changes": {
+        "fields": [
+          { "name": "username", "kind": "text", "value": "cat" },
+          { "name": "recovery email", "kind": "email", "value": "me@example.com" },
+          { "name": "note", "kind": "text", "value": "" }
+        ],
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "removing a secret field keeps it in the history, capped at 5 per field, newest first",
+      "item": {
+        "type": "api_key",
+        "name": "Deploy",
+        "fields": [
+          { "name": "key", "kind": "hidden", "value": "k6" },
+          { "name": "totp", "kind": "totp", "value": "JBSWY3DPEHPK3PXP" }
+        ],
+        "history": [
+          { "field": "key", "value": "k5", "changed_at": 1791500000005 },
+          { "field": "totp", "value": "OLDSEED", "changed_at": 1791500000004 },
+          { "field": "Key", "value": "k4", "changed_at": 1791500000004 },
+          { "field": "key", "value": "k3", "changed_at": 1791500000003 },
+          { "field": "key", "value": "k2", "changed_at": 1791500000002 },
+          { "field": "key", "value": "k1", "changed_at": 1791500000001 }
+        ],
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": { "remove_fields": ["KEY"] },
+      "changes": {
+        "fields": [{ "name": "totp", "kind": "totp", "value": "JBSWY3DPEHPK3PXP" }],
+        "history": [
+          { "field": "key", "value": "k6", "changed_at": 1791972000000 },
+          { "field": "key", "value": "k5", "changed_at": 1791500000005 },
+          { "field": "totp", "value": "OLDSEED", "changed_at": 1791500000004 },
+          { "field": "Key", "value": "k4", "changed_at": 1791500000004 },
+          { "field": "key", "value": "k3", "changed_at": 1791500000003 },
+          { "field": "key", "value": "k2", "changed_at": 1791500000002 }
+        ],
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "replacing the whole list records every secret that changed or went",
+      "item": {
+        "type": "card",
+        "name": "Visa",
+        "fields": [
+          { "name": "number", "kind": "hidden", "value": "4111" },
+          { "name": "cvv", "kind": "hidden", "value": "123" },
+          { "name": "holder", "kind": "text", "value": "A" }
+        ],
+        "history": [],
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": {
+        "name": " Visa debit ",
+        "fields": [
+          { "name": "Number", "kind": "hidden", "value": "4111" },
+          { "name": "holder", "value": "B" }
+        ],
+        "tags": ["Bank"],
+        "favorite": true,
+        "folder": "0192f000-0000-7000-8000-00000000f001"
+      },
+      "changes": {
+        "name": "Visa debit",
+        "fields": [
+          { "name": "Number", "kind": "hidden", "value": "4111" },
+          { "name": "holder", "kind": "text", "value": "B" }
+        ],
+        "tags": ["Bank"],
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "favorite": true,
+        "history": [{ "field": "cvv", "value": "123", "changed_at": 1791972000000 }],
+        "updated_at": 1791972000000
+      }
+    },
+    {
+      "name": "unchanged values write nothing",
+      "item": {
+        "type": "note",
+        "name": "Wi-Fi",
+        "notes": "pw on the router",
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "tags": ["home"],
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": {
+        "type": "note",
+        "name": "Wi-Fi ",
+        "notes": "pw on the router",
+        "tags": ["home", "HOME"],
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "fields": []
+      },
+      "changes": {}
+    },
+    {
+      "name": "folder null clears it; type and notes change",
+      "item": {
+        "type": "note",
+        "name": "Wi-Fi",
+        "notes": "old",
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": { "type": "login", "folder": null, "notes": "" },
+      "changes": { "type": "login", "notes": "", "folder": null, "updated_at": 1791972000000 }
+    },
+    {
+      "name": "removing a field that is not there",
+      "item": {
+        "type": "login",
+        "name": "x",
+        "fields": [],
+        "created_at": 1791000000000,
+        "updated_at": 1791000000000
+      },
+      "patch": { "remove_fields": ["password"] },
+      "error": { "code": "bad_input", "message": "no field \"password\" to remove" }
+    },
+    {
+      "name": "fields and set_fields together",
+      "item": { "type": "login", "name": "x", "created_at": 1791000000000, "updated_at": 1791000000000 },
+      "patch": { "fields": [], "set_fields": [{ "name": "a", "value": "b" }] },
+      "error": {
+        "code": "bad_input",
+        "message": "give fields (the whole list) or set_fields and remove_fields, not both"
+      }
+    },
+    {
+      "name": "a patch may not empty the name",
+      "item": { "type": "login", "name": "x", "created_at": 1791000000000, "updated_at": 1791000000000 },
+      "patch": { "name": "" },
+      "error": { "code": "bad_input", "message": "a vault item needs a name" }
+    }
+  ],
+  "read": [
+    {
+      "name": "a stored item reads as it was written, and its summary leaves the values out",
+      "fields": {
+        "type": "login",
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "password", "kind": "hidden", "value": "pw" }
+        ],
+        "urls": ["https://github.com"],
+        "notes": "n",
+        "tags": ["dev"],
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "favorite": true,
+        "history": [{ "field": "password", "value": "old", "changed_at": 5 }],
+        "created_at": 1,
+        "updated_at": 2
+      },
+      "item": {
+        "type": "login",
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "password", "kind": "hidden", "value": "pw" }
+        ],
+        "urls": ["https://github.com"],
+        "notes": "n",
+        "tags": ["dev"],
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "favorite": true,
+        "history": [{ "field": "password", "value": "old", "changed_at": 5 }],
+        "created_at": 1,
+        "updated_at": 2,
+        "deleted_at": null
+      },
+      "summary": {
+        "type": "login",
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text" },
+          { "name": "password", "kind": "hidden" }
+        ],
+        "urls": ["https://github.com"],
+        "tags": ["dev"],
+        "folder": "0192f000-0000-7000-8000-00000000f001",
+        "favorite": true,
+        "created_at": 1,
+        "updated_at": 2,
+        "deleted_at": null
+      }
+    },
+    {
+      "name": "malformed values read leniently: unknown kinds and types are kept, junk is dropped",
+      "fields": {
+        "type": 3,
+        "name": ["x"],
+        "fields": [
+          { "name": "pin", "kind": "passkey", "value": "1" },
+          { "name": "no value" },
+          "junk",
+          { "name": "plain", "value": "v" }
+        ],
+        "urls": ["https://a.example", 4],
+        "favorite": "yes",
+        "folder": 9,
+        "history": [{ "field": "pin", "value": "0", "changed_at": "x" }, { "value": "?" }],
+        "created_at": 7,
+        "deleted_at": 9
+      },
+      "item": {
+        "type": "login",
+        "name": "",
+        "fields": [
+          { "name": "pin", "kind": "passkey", "value": "1" },
+          { "name": "plain", "kind": "text", "value": "v" }
+        ],
+        "urls": ["https://a.example"],
+        "notes": "",
+        "tags": [],
+        "folder": null,
+        "favorite": false,
+        "history": [{ "field": "pin", "value": "0", "changed_at": 0 }],
+        "created_at": 7,
+        "updated_at": 0,
+        "deleted_at": 9
+      },
+      "summary": {
+        "type": "login",
+        "name": "",
+        "fields": [
+          { "name": "pin", "kind": "passkey" },
+          { "name": "plain", "kind": "text" }
+        ],
+        "urls": ["https://a.example"],
+        "tags": [],
+        "folder": null,
+        "favorite": false,
+        "created_at": 7,
+        "updated_at": 0,
+        "deleted_at": 9
+      }
+    }
+  ],
+  "resolve": [
+    {
+      "name": "by id, even in the trash",
+      "items": [
+        { "id": "0192f000-0000-7000-8000-000000000001", "name": "GitHub", "deleted_at": 5 },
+        { "id": "0192f000-0000-7000-8000-000000000002", "name": "AWS", "deleted_at": null }
+      ],
+      "ref": " 0192f000-0000-7000-8000-000000000001",
+      "id": "0192f000-0000-7000-8000-000000000001"
+    },
+    {
+      "name": "by name, case-insensitively, outside the trash",
+      "items": [
+        { "id": "0192f000-0000-7000-8000-000000000001", "name": "GitHub", "deleted_at": 5 },
+        { "id": "0192f000-0000-7000-8000-000000000003", "name": "github ", "deleted_at": null }
+      ],
+      "ref": "GITHUB",
+      "id": "0192f000-0000-7000-8000-000000000003"
+    },
+    {
+      "name": "an unknown reference",
+      "items": [{ "id": "0192f000-0000-7000-8000-000000000001", "name": "GitHub", "deleted_at": 5 }],
+      "ref": "GitHub",
+      "error": { "code": "unknown_vault_item", "message": "no vault item \"GitHub\"" }
+    },
+    {
+      "name": "a name two items share",
+      "items": [
+        { "id": "0192f000-0000-7000-8000-000000000009", "name": "AWS", "deleted_at": null },
+        { "id": "0192f000-0000-7000-8000-000000000002", "name": "aws", "deleted_at": null }
+      ],
+      "ref": "aws",
+      "error": {
+        "code": "ambiguous_vault_item",
+        "message": "\"aws\" names 2 vault items (0192f000-0000-7000-8000-000000000002, 0192f000-0000-7000-8000-000000000009); use an id"
+      }
+    }
+  ],
+  "field": [
+    {
+      "name": "a field by name, case-insensitively, value as stored",
+      "item": {
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "Password", "kind": "hidden", "value": " pw " }
+        ]
+      },
+      "field": "password",
+      "value": " pw "
+    },
+    {
+      "name": "a missing field names the ones there are",
+      "item": {
+        "name": "GitHub",
+        "fields": [
+          { "name": "username", "kind": "text", "value": "octo" },
+          { "name": "Password", "kind": "hidden", "value": "pw" }
+        ]
+      },
+      "field": "token",
+      "error": {
+        "code": "unknown_vault_field",
+        "message": "vault item \"GitHub\" has no field \"token\" (it has: username, Password)"
+      }
+    },
+    {
+      "name": "an item without fields",
+      "item": { "name": "Note" },
+      "field": "x",
+      "error": {
+        "code": "unknown_vault_field",
+        "message": "vault item \"Note\" has no field \"x\" (it has none)"
+      }
+    }
+  ]
+}