sneak/quak
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Compare commits

base: sneak/quak:next
Branches Tags
sneak/quak:main sneak/quak:next
..
compare: sneak/quak:b89254f1b067cb25b5c6987677a9c5ad1aeb73fe
Branches Tags
sneak/quak:next sneak/quak:main
1 Commits
next .. b89254f1b0
Author SHA1 Message Date
sneak b89254f1b0 Bring README and TODO.md in line with next after the milestone merge (closes #132)
check / check (push) Successful in 1m6s
Details 
Docs only. TODO.md's Next Step no longer says open issues wait on
`next`: no implementation work is open, and the cache design waits on
sneak's review. The README is corrected where the code contradicts it:
where SRP lives and how the login subkey is derived, when email OTP is
used, how the auth token is encoded, the download retry's temporary
files (two for a live photo), which CLI commands open a library, what
`--exif` records, which commands take `--json`, the ML data fetch
during `quak backup`, the default cache directory, and the `408`/`429`
retries.

Model: opus-5-5
 2026-09-29 02:00:23 +00:00
2 changed files with 75 additions and 123 deletions
Expand all files Collapse all files
README.md
+63 -83
View File
@@ -8,9 +8,9 @@ and downloads individual images while decrypting them on the way to disk.
quak also includes a resilient backup command that downloads every file in the quak also includes a resilient backup command that downloads every file in the
account into a deduplicated local directory tree, skipping files that already account into a deduplicated local directory tree, skipping files that already
exist on disk and continuing past individual download failures instead of exist on disk and continuing past individual download failures instead of
crashing. For each file it persists the basic metadata fields quak keeps (title, crashing. It decrypts and persists all three metadata layers (basic, private
file type, creation and modification time, latitude, longitude, content hash), magic, public magic) per file, including camera info, GPS coordinates, captions,
and the private and public magic metadata in full. A helper subcommand can and any face/keyword labels the Ente clients have added. A helper subcommand can
detect and regenerate missing thumbnails, encrypting and uploading them back to detect and regenerate missing thumbnails, encrypting and uploading them back to
the server. the server.
@@ -51,8 +51,7 @@ const client = await Client.login({
// Open a cache-backed library. On an empty cache this awaits one server // Open a cache-backed library. On an empty cache this awaits one server
// refresh; on an existing cache it returns immediately and refreshes in the // refresh; on an existing cache it returns immediately and refreshes in the
// background. Later refreshes start `refreshIntervalSeconds` (default 3) after // background every `refreshIntervalSeconds` (default 3).
// the previous one ends.
const lib = await Library.open({ client }); const lib = await Library.open({ client });
// Default reads answer synchronously from the local cache — no network. // Default reads answer synchronously from the local cache — no network.
@@ -63,7 +62,7 @@ for (const album of lib.albums.list()) {
} }
} }
// Fresh reads await a server round-trip, joining one already running. // Fresh reads await a server round-trip and answer with current state.
const { albums } = await lib.fresh(); const { albums } = await lib.fresh();
console.log(`${albums.list().length} albums as of now`); console.log(`${albums.list().length} albums as of now`);
@@ -85,7 +84,7 @@ enumeration/download calls) is exported too and documented under Design below.
This repository adheres to the This repository adheres to the
[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all) [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
standard: normalized scripts in `script/` are the entrypoints for the standard: normalized scripts in `script/` are the entrypoints for the
development workflow, and most Makefile targets are thin shims that call them. development workflow, and the Makefile targets are thin shims that call them.
The scripts are POSIX sh (not bash) so they run in minimal containers such as The scripts are POSIX sh (not bash) so they run in minimal containers such as
alpine. We provide: alpine. We provide:
@@ -171,19 +170,16 @@ local cache is reliable, and the UI is responsive on a five-year-old laptop.
All work on quak is test-driven. No exceptions. All work on quak is test-driven. No exceptions.
1. Every change starts on a feature branch off `next`, and its pull request 1. Every change starts on a feature branch off `main`.
targets `next`.
2. The first commit on the branch is the test suite for what is being added or 2. The first commit on the branch is the test suite for what is being added or
changed. Those tests must fail at that commit; the branch is red until the changed. Those tests must fail at that commit; the branch is red until the
implementation lands. implementation lands.
3. Subsequent commits add the implementation and any refactors needed to make 3. Subsequent commits add the implementation and any refactors needed to make
the tests pass. the tests pass.
4. A pull request can only be merged into `next` when `make check` is green. 4. A feature branch can only be merged into `main` when `make check` is green.
Once it has passed review, the repository manager squash-merges it into `main` is always green. CI runs `script/cibuild`, which builds the
`next`. Only sneak merges `next` into `main`. `main` and `next` are always `Dockerfile`: its `lint` and `test` phases, then the compile, so neither a
green. CI runs `script/cibuild`, which builds the `Dockerfile`: its `lint` red branch nor one that does not compile can pass CI.
and `test` phases, then the compile, so neither a red branch nor one that
does not compile can pass CI.
5. Tests are the canonical API documentation for this library. Every test file 5. Tests are the canonical API documentation for this library. Every test file
is commented thoroughly enough that a reader who has never seen quak can is commented thoroughly enough that a reader who has never seen quak can
learn how to use it from the tests alone. Comments explain why a behavior learn how to use it from the tests alone. Comments explain why a behavior
@@ -201,7 +197,7 @@ All work on quak is test-driven. No exceptions.
not the tests, and so not the full `make check`. This is deliberate so the not the tests, and so not the full `make check`. This is deliberate so the
TDD red-phase commit (failing tests, no implementation yet) can land. The TDD red-phase commit (failing tests, no implementation yet) can land. The
`test` phase is part of the image build, which is what CI executes via `test` phase is part of the image build, which is what CI executes via
`script/cibuild`, so a red branch still cannot reach `next`. `script/cibuild`, so a red branch still cannot reach `main`.
## Design ## Design
@@ -223,7 +219,7 @@ quak/
and search, request pools and search, request pools
backup.ts resilient full-account backup with dedup backup.ts resilient full-account backup with dedup
metadata-backup.ts metadata-backup.ts
backup-metadata: the metadata quak keeps, as JSON backup-metadata: all decrypted metadata as JSON
mldata-fetch.ts fetch + decrypt per-file ML data mldata-fetch.ts fetch + decrypt per-file ML data
filename.ts safe file names from server metadata filename.ts safe file names from server metadata
errors.ts error types shared across layers errors.ts error types shared across layers
@@ -255,8 +251,7 @@ the repository root rather than `src/`, because `bin/` is compiled too and
All cryptography is done by `libsodium-wrappers-sumo` (the "sumo" build is All cryptography is done by `libsodium-wrappers-sumo` (the "sumo" build is
required for `crypto_pwhash` / Argon2id), except the SRP handshake, which uses required for `crypto_pwhash` / Argon2id), except the SRP handshake, which uses
`fast-srp-hap`, and the MD5 checksum sent with a thumbnail upload, which uses `fast-srp-hap`. No hand-rolled crypto.
Node's built-in `node:crypto`. No hand-rolled crypto.
The key hierarchy, derived during login, is: The key hierarchy, derived during login, is:
@@ -267,12 +262,9 @@ The key hierarchy, derived during login, is:
3. SRP login: `crypto_kdf_derive_from_key` (BLAKE2b) derives a 32-byte subkey 3. SRP login: `crypto_kdf_derive_from_key` (BLAKE2b) derives a 32-byte subkey
from the KEK with subkey id 1 and context `loginctx`. Its first 16 bytes are from the KEK with subkey id 1 and context `loginctx`. Its first 16 bytes are
the SRP password. the SRP password.
4. When SRP completes, the server returns a blob of "key attributes" plus an 4. After SRP completes, or after the email OTP that replaces SRP when the
encrypted auth token, or first asks for a second factor. quak answers a TOTP account has email MFA on (`isEmailMFAEnabled`), the server returns a blob of
request with the code (`POST /users/two-factor/verify`), after which the "key attributes" plus an encrypted auth token.
server returns them, and cannot answer a passkey request. When the account
has email MFA on (`isEmailMFAEnabled`), an email OTP replaces SRP and the
server returns them after it.
5. `crypto_secretbox_open_easy` over the encrypted master key with the KEK 5. `crypto_secretbox_open_easy` over the encrypted master key with the KEK
yields the 32-byte master key. yields the 32-byte master key.
6. `crypto_secretbox_open_easy` over the encrypted secret key with the master 6. `crypto_secretbox_open_easy` over the encrypted secret key with the master
@@ -339,9 +331,8 @@ request is repeated only when repeating it could produce a different answer:
- Every other 4xx: not retried. A 404 in particular is an answer, and - Every other 4xx: not retried. A 404 in particular is an answer, and
`listMissingThumbnails` depends on getting it promptly and once. `listMissingThumbnails` depends on getting it promptly and once.
- Transport failures — a `fetch` rejection, `ECONNRESET`, `ETIMEDOUT`, a DNS or - Transport failures — a `fetch` rejection, `ECONNRESET`, `ETIMEDOUT`, a DNS or
TLS failure — and deadline aborts: retried. Node's `fetch` rejects with a TLS failure — and deadline aborts: retried. The errno is looked for in the
plain `TypeError`, so every `TypeError` is retried. The errno is looked for in error's `cause` chain, because that is where Node's `fetch` puts it.
the error's `cause` chain, because that is where Node's `fetch` puts it.
- A truncated download: retried. - A truncated download: retried.
- Anything else, including a secretstream authentication failure that is not - Anything else, including a secretstream authentication failure that is not
truncation: not retried. The default answer is no. For a backup tool, retrying truncation: not retried. The default answer is no. For a backup tool, retrying
@@ -410,10 +401,9 @@ and these endpoints have no Range support, so a retry starts the file over. The
atomic write is part of the retried unit: each attempt writes its own temporary atomic write is part of the retried unit: each attempt writes its own temporary
files, one for most files and two for a live photo (its image and its video), files, one for most files and two for a live photo (its image and its video),
and removes them if it fails. Only the attempt that completes renames anything and removes them if it fails. Only the attempt that completes renames anything
into place. The retry sits below `runBackup` and `runMetadataBackup`. into place. `runBackup` and `runMetadataBackup` are unchanged: the retry sits
`runBackup` logs, counts and steps over a file that still fails after its below them, and a file that fails after exhausting it is still logged, counted,
retries; `runMetadataBackup`, which downloads only with `--exif`, records the and stepped over.
error in that file's JSON as `imageMetadataError` and goes on.
One imprecision is deliberate and worth knowing about. When a body ends part-way One imprecision is deliberate and worth knowing about. When a body ends part-way
through a secretstream chunk, Poly1305 fails and carries no framing signal, so a through a secretstream chunk, Poly1305 fails and carries no framing signal, so a
@@ -437,11 +427,10 @@ base64-encoded keys) that the consumer can write to disk, a database, or
whatever else fits their use case. `Client.fromJSON(snapshot)` restores a whatever else fits their use case. `Client.fromJSON(snapshot)` restores a
working client from that snapshot without re-authenticating; it checks every working client from that snapshot without re-authenticating; it checks every
field and each key's length first, and throws an error naming the bad field. field and each key's length first, and throws an error naming the bad field.
`client.logout()` clears the token and zeroes the key buffers in place; after `client.logout()` clears the token and zeroes the key buffers in place; every
it, every other method on that client throws. It does not contact the server, so later call on that client throws. It does not contact the server, so the token
the token stays valid there and in any saved snapshot; stays valid there and in any saved snapshot; `await client.logoutOnServer()`
`await client.logoutOnServer()` first ends the session on the server first ends the session on the server (`POST /users/logout`).
(`POST /users/logout`).
The CLI stores the snapshot at the platform-appropriate data directory via The CLI stores the snapshot at the platform-appropriate data directory via
`env-paths`: `~/Library/Application Support/quak/session.json` on macOS, `env-paths`: `~/Library/Application Support/quak/session.json` on macOS,
@@ -449,8 +438,7 @@ The CLI stores the snapshot at the platform-appropriate data directory via
`0600`. The key material is stored in cleartext in the JSON; treat this file as `0600`. The key material is stored in cleartext in the JSON; treat this file as
you would treat the password itself. A missing file is reported as "not logged you would treat the password itself. A missing file is reported as "not logged
in"; a file that exists but is corrupt is reported as such, naming the bad in"; a file that exists but is corrupt is reported as such, naming the bad
field. Both exit with status 1, except that `quak logout` with no file says field. Both exit with status 1.
there is no session and exits 0.
`quak logout` ends the session on the server, so the token in `session.json` `quak logout` ends the session on the server, so the token in `session.json`
stops working even in a copy of the file, and then deletes the file. If the stops working even in a copy of the file, and then deletes the file. If the
@@ -473,7 +461,7 @@ quak files --collection <id> [--json] list files in a collec
quak get <fileID> [--out path] [--collection] download and decrypt a file quak get <fileID> [--out path] [--collection] download and decrypt a file
quak get-thumb <fileID> [--out] [--collection] download and decrypt a thumbnail quak get-thumb <fileID> [--out] [--collection] download and decrypt a thumbnail
quak backup <dir> [--json] full incremental backup quak backup <dir> [--json] full incremental backup
quak backup-metadata <dir> [--exif] dump the metadata quak keeps as JSON quak backup-metadata <dir> [--exif] dump all decrypted metadata as JSON
quak helper list-missing-thumbnails [--json] find files with missing thumbnails quak helper list-missing-thumbnails [--json] find files with missing thumbnails
quak helper fix-missing-thumbnails [--file ids] [--json] generate + upload missing thumbnails quak helper fix-missing-thumbnails [--file ids] [--json] generate + upload missing thumbnails
``` ```
@@ -500,13 +488,13 @@ its EXIF metadata and dimensions. `collections`, `files`, `backup`,
`--json` for machine-readable output. `--json` for machine-readable output.
`backup-metadata` fetches ML data in requests of up to 200 files. When a request `backup-metadata` fetches ML data in requests of up to 200 files. When a request
fails, the error is logged, each of its files is written with the reason in an still fails after its retries, the error is logged, each of its files is written
`mlDataError` field instead of `mlData`, and the dump goes on. The exit code is with the reason in an `mlDataError` field instead of `mlData`, and the dump goes
non-zero if any ML data request failed. on. The exit code is non-zero if any ML data request failed.
`helper fix-missing-thumbnails` regenerates thumbnails for JPEG images only, `helper fix-missing-thumbnails` regenerates thumbnails for baseline JPEG images
because the bundled decoder (`jpeg-js`) decodes only JPEG. A non-JPEG image only, because the bundled decoder (`jpeg-js`) decodes only JPEG. A non-JPEG
(PNG, HEIC) or a video is reported as `skipped` (unsupported format), kept image (PNG, HEIC) or a video is reported as `skipped` (unsupported format), kept
distinct from a `failed` repair, and does not affect the exit code; a genuine distinct from a `failed` repair, and does not affect the exit code; a genuine
failure still exits non-zero. The server accepts a new thumbnail only from the failure still exits non-zero. The server accepts a new thumbnail only from the
file's owner and only when it is no larger than the thumbnail size it records file's owner and only when it is no larger than the thumbnail size it records
@@ -525,9 +513,7 @@ the smallest does not.
originals/ originals/
<fileID>.<ext> actual file content (one per unique file, <fileID>.<ext> actual file content (one per unique file,
two for a live photo: see below) two for a live photo: see below)
<fileID>.json the file's basic metadata fields quak <fileID>.json all decrypted metadata for that file
keeps, and its private and public magic
metadata
<fileID>.livephoto.json which of a live photo's two files is which <fileID>.livephoto.json which of a live photo's two files is which
collections/ collections/
<name>/ <name>/
@@ -615,8 +601,7 @@ Future (desktop client, separate repo):
The library's primary surface is the cache-backed `Library`; the lower-level The library's primary surface is the cache-backed `Library`; the lower-level
`Client` sits underneath it and is covered by the Design sections above. The `Client` sits underneath it and is covered by the Design sections above. The
test suite is the canonical, executable documentation — `test/library/` and test suite is the canonical, executable documentation — `test/library/` and
`test/client/usage.test.ts` walk most operations, `test/cli/backup.test.ts` `test/client/usage.test.ts` walk every operation, and `yarn test` verifies them.
walks `lib.backup()`, and `yarn test` verifies them.
### Opening a library ### Opening a library
@@ -638,7 +623,7 @@ background, so an unreachable server does not block opening.
| `precacheThumbnails` | `true` | prefetch every thumbnail, newest first | | `precacheThumbnails` | `true` | prefetch every thumbnail, newest first |
| `precacheOriginals` | `true` | prefetch the favorites album and the latest-window originals | | `precacheOriginals` | `true` | prefetch the favorites album and the latest-window originals |
| `precacheOriginalsDays` | `7` | length in days of that latest window | | `precacheOriginalsDays` | `7` | length in days of that latest window |
| `cacheOriginalsMaxBytes` | 100 GiB | size limit on the originals cache; pinned originals can exceed it | | `cacheOriginalsMaxBytes` | 100 GiB | hard ceiling on the originals cache |
| `freeBelowBytes` | 50 GiB | free space to protect on the volume; the effective limit adapts down | | `freeBelowBytes` | 50 GiB | free space to protect on the volume; the effective limit adapts down |
| `isOriginalPinned` | none | extra predicate for originals that must never be evicted | | `isOriginalPinned` | none | extra predicate for originals that must never be evicted |
| `pools` | fresh `RequestPools` | the bounded request pools (sets concurrency) | | `pools` | fresh `RequestPools` | the bounded request pools (sets concurrency) |
@@ -660,21 +645,17 @@ can then be removed.
### Default reads vs. fresh reads ### Default reads vs. fresh reads
Default reads — `lib.albums`, `lib.photos`, `lib.timeline` — answer Default reads — `lib.albums`, `lib.photos`, `lib.timeline` — answer
synchronously from the copy held in RAM and never touch the network. A refresh synchronously from the last refreshed copy held in RAM and never touch the
changes that copy only once all its server requests have succeeded, and the network. The background timer refreshes that copy every
background timer starts the next refresh `refreshIntervalSeconds` after the `refreshIntervalSeconds`, so a default read is immediate but may be up to one
previous one ends. So a default read is immediate, but only as current as the interval stale.
last refresh whose requests all succeeded; right after opening an existing
cache, it is the copy on disk.
`await lib.fresh()` waits for a refresh to complete and persist, and returns the `await lib.fresh()` forces a refresh, waits for it to complete and persist, and
same `{ albums, photos, timeline }` namespaces, which then reflect a completed returns the same `{ albums, photos, timeline }` namespaces — now guaranteed to
server round-trip. When a refresh is already running, background or not, reflect a completed server round-trip. Concurrent `fresh()` calls coalesce onto
`fresh()` waits for that one, so its answer can come from requests made before one refresh, and a refresh that fails rejects the caller (default reads stay
the call; only when none is running does it start one. A refresh that fails silent and keep serving the last good copy). The CLI's read commands use fresh
rejects the caller (default reads stay silent and keep serving the last good reads (issue https://git.eeqj.de/sneak/quak/issues/75).
copy). The CLI's read commands use fresh reads (issue
https://git.eeqj.de/sneak/quak/issues/75).
### Read surface ### Read surface
@@ -691,8 +672,8 @@ https://git.eeqj.de/sneak/quak/issues/75).
`includeArchived`; hidden photos are always excluded. `includeArchived`; hidden photos are always excluded.
An `Album` exposes its record fields and `album.photos.list()` → `Photo[]` An `Album` exposes its record fields and `album.photos.list()` → `Photo[]`
(newest first). A `Photo` exposes its record fields other than `thumbnailPath` (newest first). A `Photo` exposes its record fields, `photo.record()` →
and `originalPath`, `photo.record()` → `PhotoRecord`, and two content methods: `PhotoRecord`, and two content methods:
- `await photo.original(opts?)` → `{ path, bytes, videoPath? }` — the - `await photo.original(opts?)` → `{ path, bytes, videoPath? }` — the
full-resolution file. For a live photo, `path` and `bytes` are its image's and full-resolution file. For a live photo, `path` and `bytes` are its image's and
@@ -741,16 +722,16 @@ photos newest first). `lib.subscribe({ onChange })` delivers a `LibraryChange`
`SimilarResult[]` (`{ fileID, score }`, cosine similarity, most similar first, `SimilarResult[]` (`{ fileID, score }`, cosine similarity, most similar first,
default limit 20). quak bundles no text encoder, so `searchByEmbedding` takes default limit 20). quak bundles no text encoder, so `searchByEmbedding` takes
a query vector the caller produced elsewhere. a query vector the caller produced elsewhere.
- `await lib.backup(opts?)` → `BackupResult`. It waits for a refresh as - `await lib.backup(opts?)` → `BackupResult`. It refreshes, fetches every
`fresh()` does, fetches every in-scope original not already in the backup in-scope original not already in the backup (and, with `includeThumbnails`,
(and, with `includeThumbnails`, thumbnails) through the content cache, and thumbnails) through the content cache, and rebuilds the on-disk backup tree
rebuilds the on-disk backup tree with a durable failure ledger. A fetched with a durable failure ledger. A fetched original is written straight into the
original is written straight into the backup's `originals/` and not into the backup's `originals/` and not into the cache, which then counts it as present;
cache, which then counts it as present; one the cache already held is copied one the cache already held is copied from there. `BackupOptions`:
from there. `BackupOptions`: `downloadDirectory` (falls back to the one `downloadDirectory` (falls back to the one `open()` was given),
`open()` was given), `includeOriginals` (default `true`), `includeThumbnails` `includeOriginals` (default `true`), `includeThumbnails` (default `false`),
(default `false`), `onlyAlbumNames`, and `onProgress`. See Backup layout above `onlyAlbumNames`, and `onProgress`. See Backup layout above for the tree it
for the tree it writes. writes.
### Request pools ### Request pools
@@ -842,15 +823,14 @@ documents:
`yarn.lock`. Never `git add -A`. Never force-push to main. `yarn.lock`. Never `git add -A`. Never force-push to main.
- **The "Development workflow" section above.** All changes go on feature - **The "Development workflow" section above.** All changes go on feature
branches off `next`, and every pull request targets `next`; only sneak merges branches. Tests are written first and committed in a failing state before the
`next` into `main`. Tests are written first and committed in a failing state implementation. Tests are the canonical API documentation and must be
before the implementation. Tests are the canonical API documentation and must commented thoroughly. `main` is always green.
be commented thoroughly. `main` and `next` are always green.
- **Required checks before every commit:** `make lint` must pass — that is - **Required checks before every commit:** `make lint` must pass — that is
eslint plus the prettier check, and it builds the `lint` phase of the eslint plus the prettier check, and it builds the `lint` phase of the
`Dockerfile`, so it needs docker. The pre-commit hook enforces exactly that. `Dockerfile`, so it needs docker. The pre-commit hook enforces exactly that.
`make check` (which also runs the tests) must pass before merging into `next`. `make check` (which also runs the tests) must pass before merging to `main`.
`make fmt-check` is available for a host-side formatting check on its own, but `make fmt-check` is available for a host-side formatting check on its own, but
it is not a separate requirement: `make lint` already covers it, and running it is not a separate requirement: `make lint` already covers it, and running
both would check formatting twice. Never invoke eslint or prettier directly; both would check formatting twice. Never invoke eslint or prettier directly;
TODO.md
+12 -40
View File
@@ -1,15 +1,12 @@
# Workflow # Workflow
- branch from `next` - branch (from `main`)
- do the work in Next Step - do the work in Next Step
- move Next Step to the top of Completed Steps - move Next Step to the top of Completed Steps
- move the top item of Future Steps into Next Step - move the top item of Future Steps into Next Step
- commit (`TODO.md` changes in the same commit as the work) - commit (`TODO.md` changes in the same commit as the work)
- merge to `main` if the branch is not protected, otherwise open a PR
- push - push
- open a pull request that targets `next`
- once the pull request has passed review, the repository manager squash-merges
it into `next`
- only sneak merges `next` into `main`
# Status # Status
@@ -25,44 +22,19 @@ declares one.
# Completed Steps # Completed Steps
- 2026-09-29: The "Workflow" list at the top of this file now says to branch
from `next` and open a pull request that targets `next`, that the repository
manager squash-merges a reviewed pull request into `next`, and that only sneak
merges `next` into `main`, as the README does (issue 137).
- 2026-09-29: The README's "Development workflow" and "For LLMs" sections now
say work branches from `next`, every pull request targets `next`, the
repository manager squash-merges reviewed pull requests into `next`, and only
sneak merges `next` into `main` (issue 135).
- 2026-09-29: Brought the README and this file in line with `next` after the - 2026-09-29: Brought the README and this file in line with `next` after the
milestone merge (issue 132). The Next Step says no implementation work is open milestone merge (issue 132). The Next Step says no implementation work is open
and the cache design (issue 36) waits on sneak's review. README corrections: and the cache design (issue 36) waits on sneak's review. README corrections:
the Getting Started comments say when the library refreshes; most, not all, `script/lint` and `script/test` have no host path, though `yarn test` does;
Makefile targets call a script; `script/lint` and `script/test` have no host the SRP handshake uses `fast-srp-hap`, outside `crypto/`; the SRP password is
path, though `yarn test` does; the SRP handshake uses `fast-srp-hap`, outside the first 16 bytes of a 32-byte subkey; email OTP replaces SRP when the
`crypto/`, and a thumbnail upload's MD5 uses `node:crypto`; the SRP password account has email MFA on; the auth token is sent as URL-safe base64 with
is the first 16 bytes of a 32-byte subkey; the key attributes and token come padding; each download attempt writes its own temporary files, two for a live
after SRP, after the TOTP code SRP may ask for, or after the email OTP that photo, and only the attempt that completes renames them into place; `login`,
replaces SRP when the account has email MFA on, and quak cannot answer a `whoami` and `logout` open no library; `--exif` records XMP and, for a JPEG,
passkey; the auth token is sent as URL-safe base64 with padding; every EXIF, and no IPTC; which commands take `--json`; `quak backup` still fetches
`TypeError` is retried; each download attempt writes its own temporary files, ML data; the default cache directory is the per-user one, not an XDG path on
two for a live photo, and only the attempt that completes renames them into macOS; and `408` and `429` are retried.
place; `runMetadataBackup` records a failed download in the file's JSON; a
second `client.logout()` does not throw; `quak logout` with no session exits
0, and names the cache directory only when it knows it; `login`, `whoami` and
`logout` open no library; `--exif` records XMP and, for a JPEG, EXIF, and no
IPTC; which commands take `--json`; a failed ML data request may not have been
retried; the thumbnail fixer is not limited to baseline JPEG; `quak backup`
still fetches ML data; a backup's JSON holds the basic metadata fields quak
keeps and the private and public magic metadata, not every decrypted field,
and the README no longer lists what the magic metadata holds; the default
cache directory is the per-user one, not an XDG path on macOS; pinned
originals can exceed `cacheOriginalsMaxBytes`; which tests cover which
operations; a default read is only as current as the last refresh whose
requests all succeeded; `fresh()` and `lib.backup()` join a refresh already
running; a `Photo` has no `thumbnailPath` or `originalPath`; and `408` and
`429` are retried.
- 2026-09-28: Tested the live-photo writer's fsyncs (issue 130). A test checks - 2026-09-28: Tested the live-photo writer's fsyncs (issue 130). A test checks
that the image's and the video's temp files are fsynced before either is that the image's and the video's temp files are fsynced before either is