Rename quack to quak
German for 'quack', matching the Ente (German for 'duck') naming. All references updated: package name, CLI binary, X-Client-Package header, test descriptions, temp dir prefixes, README, Makefile docker tag.
This commit is contained in:
60
README.md
60
README.md
@@ -1,6 +1,6 @@
|
||||
# quack
|
||||
# quak
|
||||
|
||||
quack is a WTFPL-licensed TypeScript client library and CLI by
|
||||
quak is a WTFPL-licensed TypeScript client library and CLI by
|
||||
[@sneak](https://sneak.berlin) for the [Ente](https://ente.io) end-to-end
|
||||
encrypted photo hosting service. It logs in, enumerates collections and files,
|
||||
and downloads individual images while decrypting them on the way to disk.
|
||||
@@ -8,29 +8,29 @@ and downloads individual images while decrypting them on the way to disk.
|
||||
## Getting Started
|
||||
|
||||
```bash
|
||||
git clone https://git.eeqj.de/sneak/quack.git
|
||||
cd quack
|
||||
git clone https://git.eeqj.de/sneak/quak.git
|
||||
cd quak
|
||||
yarn install
|
||||
yarn build
|
||||
|
||||
# Log in (prompts for email, password, and OTP/TOTP if required).
|
||||
# Stores an encrypted session under $XDG_CONFIG_HOME/quack/.
|
||||
yarn quack login
|
||||
# Stores an encrypted session under $XDG_CONFIG_HOME/quak/.
|
||||
yarn quak login
|
||||
|
||||
# List the user's collections (albums).
|
||||
yarn quack collections
|
||||
yarn quak collections
|
||||
|
||||
# List files in a collection.
|
||||
yarn quack files --collection 12345
|
||||
yarn quak files --collection 12345
|
||||
|
||||
# Download and decrypt a single file to ./out/.
|
||||
yarn quack get 67890 --out ./out/
|
||||
yarn quak get 67890 --out ./out/
|
||||
```
|
||||
|
||||
For library use:
|
||||
|
||||
```ts
|
||||
import { Client } from "quack";
|
||||
import { Client } from "quak";
|
||||
|
||||
const client = await Client.fromSavedSession();
|
||||
for (const c of await client.listCollections()) {
|
||||
@@ -49,7 +49,7 @@ Flutter app fails to sync reliably. The web app is heavy. The desktop app is the
|
||||
web app inside a slow Electron wrapper. The Go CLI is the closest thing to a
|
||||
usable tool, but it is awkward to integrate from anything that is not a shell.
|
||||
|
||||
quack is the first step in fixing that. This repo ships a small, correct,
|
||||
quak is the first step in fixing that. This repo ships a small, correct,
|
||||
well-tested implementation of Ente's cryptographic protocol and its read-only
|
||||
API surface, plus a CLI that proves the library is enough to do real work
|
||||
without a UI.
|
||||
@@ -67,7 +67,7 @@ requires the protocol layer to be correct first.
|
||||
|
||||
## Development workflow
|
||||
|
||||
All work on quack is test-driven. No exceptions.
|
||||
All work on quak is test-driven. No exceptions.
|
||||
|
||||
1. Every change starts on a feature branch off `main`.
|
||||
2. The first commit on the branch is the test suite for what is being added or
|
||||
@@ -79,7 +79,7 @@ All work on quack is test-driven. No exceptions.
|
||||
`main` is always green. The Dockerfile runs `make check`, so a red branch
|
||||
cannot pass CI.
|
||||
5. Tests are the canonical API documentation for this library. Every test file
|
||||
is commented thoroughly enough that a reader who has never seen quack 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
|
||||
matters, not just what the assertion checks.
|
||||
6. Test fixtures (cryptographic vectors, recorded HTTP responses, sample files)
|
||||
@@ -98,13 +98,13 @@ All work on quack is test-driven. No exceptions.
|
||||
|
||||
## Design
|
||||
|
||||
quack is a TypeScript library with a thin CLI wrapper. The library does the
|
||||
work; the CLI is for humans.
|
||||
quak is a TypeScript library with a thin CLI wrapper. The library does the work;
|
||||
the CLI is for humans.
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
quack/
|
||||
quak/
|
||||
src/
|
||||
crypto/ libsodium primitives (boxes, secretstreams, KDF, SRP)
|
||||
api/ HTTP client + typed endpoint wrappers
|
||||
@@ -114,7 +114,7 @@ quack/
|
||||
client.ts high-level Client class assembled from the above
|
||||
index.ts public library exports
|
||||
bin/
|
||||
quack.ts CLI entrypoint (commander.js)
|
||||
quak.ts CLI entrypoint (commander.js)
|
||||
test/ unit + integration tests (vitest)
|
||||
Makefile
|
||||
Dockerfile
|
||||
@@ -169,7 +169,7 @@ A custom API endpoint is configurable for self-hosted servers via the
|
||||
Required request headers on every authenticated call:
|
||||
|
||||
- `X-Auth-Token`: the decrypted auth token from login.
|
||||
- `X-Client-Package`: identifies the client. quack uses `berlin.sneak.quack`.
|
||||
- `X-Client-Package`: identifies the client. quak uses `berlin.sneak.quak`.
|
||||
|
||||
Endpoints used:
|
||||
|
||||
@@ -187,8 +187,8 @@ Endpoints used:
|
||||
|
||||
### Session persistence
|
||||
|
||||
After login, quack writes an encrypted session blob to
|
||||
`$XDG_CONFIG_HOME/quack/session.json` (default `~/.config/quack/session.json`)
|
||||
After login, quak writes an encrypted session blob to
|
||||
`$XDG_CONFIG_HOME/quak/session.json` (default `~/.config/quak/session.json`)
|
||||
containing the auth token, the user's master key, the user's secret key, and the
|
||||
user's email. The session file is itself encrypted with a key derived from a
|
||||
per-machine random value stored in the OS keychain when available, falling back
|
||||
@@ -197,14 +197,14 @@ secret key are never written to disk in cleartext.
|
||||
|
||||
### CLI surface
|
||||
|
||||
- `quack login`: interactive login, writes session.
|
||||
- `quack logout`: deletes the session.
|
||||
- `quack whoami`: prints the logged-in email.
|
||||
- `quack collections`: list collections (id, name, type, file count).
|
||||
- `quack files --collection <id>`: list files in a collection (id, name, type,
|
||||
- `quak login`: interactive login, writes session.
|
||||
- `quak logout`: deletes the session.
|
||||
- `quak whoami`: prints the logged-in email.
|
||||
- `quak collections`: list collections (id, name, type, file count).
|
||||
- `quak files --collection <id>`: list files in a collection (id, name, type,
|
||||
creation time, size).
|
||||
- `quack get <fileID> --out <dir>`: download and decrypt a file.
|
||||
- `quack get-thumb <fileID> --out <dir>`: download and decrypt a thumbnail.
|
||||
- `quak get <fileID> --out <dir>`: download and decrypt a file.
|
||||
- `quak get-thumb <fileID> --out <dir>`: download and decrypt a thumbnail.
|
||||
|
||||
All commands accept `--json` for machine-readable output.
|
||||
|
||||
@@ -438,7 +438,7 @@ export interface ApiClientOptions {
|
||||
thumbsOrigin?: string; // default https://thumbnails.ente.io
|
||||
authToken?: string;
|
||||
fetch?: typeof fetch; // injectable for tests
|
||||
userAgent?: string; // default "quack/<version>"
|
||||
userAgent?: string; // default "quak/<version>"
|
||||
}
|
||||
|
||||
export class ApiError extends Error {
|
||||
@@ -481,8 +481,8 @@ export interface Session {
|
||||
}
|
||||
|
||||
export interface SessionStoreOptions {
|
||||
path?: string; // default $XDG_CONFIG_HOME/quack/session.json
|
||||
keychainService?: string; // default "berlin.sneak.quack"
|
||||
path?: string; // default $XDG_CONFIG_HOME/quak/session.json
|
||||
keychainService?: string; // default "berlin.sneak.quak"
|
||||
}
|
||||
|
||||
export class SessionStore {
|
||||
|
||||
Reference in New Issue
Block a user