Skip to content
Merged
2 changes: 1 addition & 1 deletion modules/shell/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Puts Kitokey's four steps in the user's hands: a tray, a global shortcut, notifi
## Internal conventions nobody could guess

- Every sentence the user reads is in `src/words.rs`, in each language the interface speaks — English and French, following the system's (the decider, 2026-10-13). They are the product's content: the one place where this repository holds another language than English. A sentence written anywhere else is a defect. They are written to the voice guide, [`docs/voice.md`](docs/voice.md): its principles, its lexicon, its templates and the comment each sentence carries.
- The Whisper models Settings offer are `registry/models.json`, built in (`src/registry.rs`, D40, ADR-0010): a model is added or removed there, never in the code. Each says what it is good for by a key whose sentence is in `src/words.rs`; a new key needs its sentence first. The shell's tests read the file: one that does not read, or names a host other than `registry::HOSTS`, fails them. Its first model stays this build's default (`model::DEFAULT`): a list read again that puts another first is refused, the default being what a transcript waits for and the tray fetches. Read again, a list is taken only signed by the decider's key (`registry::PUBLIC_KEY`, D56): once that key is built in, a change to the file is followed by their `minisign -Sm`, or the shell's tests refuse it. `registry/.gitattributes` keeps the file's bytes as signed, on Windows too.
- The Whisper models Settings offer are `registry/models.json`, built in (`src/registry.rs`, D40, ADR-0010): a model is added or removed there, never in the code. Each says what it is good for by a key whose sentence is in `src/words.rs`; a new key needs its sentence first. The shell's tests read the file: one that does not read, or names a host other than `registry::HOSTS`, fails them. Its first model stays this build's default (`model::DEFAULT`): a list read again that puts another first is refused, the default being what a transcript waits for and the tray fetches. Read again, a list is taken only signed by the decider's key (`registry::PUBLIC_KEY`, `28AD0E835D7AF31E`, D56). **A change to the file is signed by the decider**, in their own terminal — `minisign -Sm modules/shell/registry/models.json` —, and its `models.json.minisig` committed with it: an agent never holds, makes or asks for the private key, and never signs; until the decider's signature is there, the shell's tests refuse the change. `registry/.gitattributes` keeps the file's bytes as signed, on Windows too.
- Decided before any code (ADR-0002, cycle 01 *D1*): Tauri v2; under GNOME the global shortcut and the window's coming forward go through the desktop's portal, not the toolkit's plugin; the tray's menu holds the actions themselves, since it cannot bring a window forward there.

## Business invariants
Expand Down
4 changes: 2 additions & 2 deletions modules/shell/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -265,8 +265,8 @@ the Whisper models of [`registry/models.json`](registry/models.json), the list s
ADR-0010), and for the minutes `qwen3:8b` fetched by Ollama's own pull (`POST /api/pull`) —,
one fetch at a time. The Whisper models are read again from `main` only on *Mettre à jour la
liste (raw.githubusercontent.com)*, and offered then until Kitokey quits, only when the
decider's minisign key signed them (D56). Until that key is built in, no list is read again and
*Réglages* say it waits on it; a list that cannot be read, unsigned, signed by another key or changed since leaves the one offered, and says so; a model fetched joins those to choose, the choice staying the
decider's minisign key signed them (D56): its public key, `28AD0E835D7AF31E`, is built in
(`registry::PUBLIC_KEY`). A list that cannot be read, unsigned, signed by another key or changed since leaves the one offered, and says so; a model fetched joins those to choose, the choice staying the
user's. With no Ollama answering, the row says where to get it: Kitokey never installs it (D37). A model the settings name, and which is not
there, is said with where it was looked for: it is the user's own, never fetched.

Expand Down
2 changes: 2 additions & 0 deletions modules/shell/registry/kitokey-models.pub
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
untrusted comment: minisign public key 28AD0E835D7AF31E
RWQe83pdgw6tKGbfv/lHOXQkpVU+KJcfXp3KiOmb2JIVn9Lz0ojPkotS
4 changes: 4 additions & 0 deletions modules/shell/registry/models.json.minisig
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
untrusted comment: signature from minisign secret key
RUQe83pdgw6tKImxS0WO+2AtWJxhUZW8MwcdKJSoAfZ+6m8wvlJLg37hMFYt6jN3APScM0ql3hN5doGMauTQo4MJ3uPmhklIoAw=
trusted comment: timestamp:1794666686 file:models.json hashed
i8noTVJYzVjkIq8Lz3xIs0izQPgaMbaHj5evFVNUkc2YCQo5WOWM0QDSW1sE6t0LyxilorV6mLEVxSlecefaCA==
60 changes: 39 additions & 21 deletions modules/shell/scripts/e2e_window.py
Original file line number Diff line number Diff line change
Expand Up @@ -904,19 +904,23 @@ def copyfile(self, source, sink):


def list_refreshed(now: dt.datetime) -> None:
"""W. The list of models is read again only signed by the decider's key: until it is built in, none is (D40, D56)."""
print("W. Settings: no list of models read again until the decider's key is built in, and it is said (D40, D56)")
# When registry::PUBLIC_KEY is set, this scenario changes: the button is back, its host shown,
# and an unsigned list served here is refused. The signed path is the shell's tests'
# (tests/registry_fetch.rs), with a key of their own: no window can hold a key a test made.
asked = []
"""W. The list of models is read again only signed by the decider's key, built in (D40, D56)."""
print("W. Settings: a list of models read again is taken only signed by the decider's key; refused, it is said (D40, D56)")
# Served here: the list on main, with the decider's signature of it (registry/models.json.minisig),
# none, or the list changed after it was signed. A key a test made is the shell's tests' only
# (tests/registry_fetch.rs): no window holds one.
registry = Path(__file__).parent.parent / "registry"
shipped, signature = (registry / "models.json").read_bytes(), (registry / "models.json.minisig").read_bytes()
asked, serving = [], {"list": shipped, "signature": signature}

class List(http.server.BaseHTTPRequestHandler):
def do_GET(self):
asked.append(self.path)
self.send_response(404)
self.send_header("Content-Length", "0")
body = serving["signature"] if self.path.endswith(".minisig") else serving["list"]
self.send_response(404 if body is None else 200)
self.send_header("Content-Length", str(len(body or b"")))
self.end_headers()
self.wfile.write(body or b"")

def log_message(self, *_):
pass
Expand All @@ -931,21 +935,35 @@ def log_message(self, *_):
window.env.update(KITOKEY_REGISTRY=f"http://{at}/models.json")
with window as browser:
browser.find_element(By.ID, "settings-link").click()
waits = wait_for(browser, lambda b: "attend la clé qui la signe" in b.execute_script(said), 10)
check("Settings say the list waits on the key that signs it, and the models stay offered",
waits and "restent proposés" in browser.execute_script(said)
and browser.find_elements(By.CSS_SELECTOR, '[data-offered="ggml-small-q8_0.bin"]'),
browser.execute_script(said))
check("no button offers to read it again", not browser.find_elements(By.ID, "offered-refresh"))
# Asked all the same, it is refused, and logged so, with nothing asked of anyone.
browser.execute_script("window.__TAURI__.core.invoke('registry_refresh').then(() => { window.listRead = 'read'; }, () => { window.listRead = 'refused'; })")
answered = wait_for(browser, lambda b: b.execute_script("return window.listRead || ''"), 10)
check("asked all the same, it is refused, and nothing crosses the network",
answered and browser.execute_script("return window.listRead") == "refused" and asked == [],
(browser.execute_script("return window.listRead"), asked))
button = wait_for(browser, lambda b: b.find_elements(By.ID, "offered-refresh"), 10)
check("the key built in: a button offers to read the list again, its host shown, nothing said of a key awaited",
button and at in browser.find_element(By.ID, "offered-refresh").text and "attend la clé" not in browser.execute_script(said)
and asked == [], (browser.execute_script(said), asked))

def read_again(what: str, list_: bytes, signature: bytes | None) -> str:
"""The list served as `what` says, the button pressed: what the page says after it."""
serving.update(list=list_, signature=signature)
asked.clear()
browser.find_element(By.ID, "offered-refresh").click()
wait_for(browser, lambda b: b.execute_script(said) or len(asked) == 2 and b.find_elements(By.ID, "offered-refresh")
and b.find_element(By.ID, "offered-refresh").is_enabled(), 10)
time.sleep(0.5)
return browser.execute_script(said)

for what, list_, signature_ in [("unsigned", shipped, None),
("changed after the decider signed it", shipped.replace(b'"version": 1', b'"version": 1', 1), signature),
("its signature none", shipped, b"<html>")]:
refusal = read_again(what, list_, signature_)
check(f"a list {what}: refused, said, the models shipped still offered",
"n’a pas pu être mise à jour" in refusal and "restent proposés" in refusal
and asked == ["/models.json", "/models.json.minisig"]
and browser.find_elements(By.CSS_SELECTOR, '[data-offered="ggml-small-q8_0.bin"]'), (refusal, asked))
taken = read_again("the decider's", shipped, signature)
check("the list the decider signed: taken, nothing said against it, its models offered",
"n’a pas pu" not in taken and asked == ["/models.json", "/models.json.minisig"]
and browser.find_elements(By.CSS_SELECTOR, '[data-offered="ggml-small-q8_0.bin"]'), (taken, asked))
server.shutdown()


def speech_offered(now: dt.datetime) -> None:
"""X. On a Mac, Apple's SpeechAnalyzer is offered among who hears, its model fetched on the click (D42)."""
print("X. Settings: Apple's SpeechAnalyzer offered where this Mac offers it, its model fetched on the click (D42)")
Expand Down
14 changes: 9 additions & 5 deletions modules/shell/src/registry.rs
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@ pub const SHIPPED: &str = include_str!("../registry/models.json");
/// Where the list is read again from, on the user's gesture: the file on `main`.
pub const ADDRESS: &str = "https://raw.githubusercontent.com/NapkinStack/wholeheard/main/modules/shell/registry/models.json";

/// The decider's public key, as `minisign -G` writes it on the second line of its `.pub` file.
/// None until they give it (cycle 05, *Dependency with a date*): no list is read again, Settings
/// say so, and so does the check of the list in the repository.
pub const PUBLIC_KEY: Option<&str> = None;
/// The decider's public key, as `minisign -G` writes it on the second line of its `.pub` file:
/// `minisign public key 28AD0E835D7AF31E`, made in their own terminal (D56). Its private key is in
/// no repository and no session: a list is signed by the decider alone (`AGENTS.md`).
pub const PUBLIC_KEY: Option<&str> = Some("RWQe83pdgw6tKGbfv/lHOXQkpVU+KJcfXp3KiOmb2JIVn9Lz0ojPkotS");

/// What no list is read again without, said to the logs and to whoever reads the check.
const WAITS: &str = "the list is not read again: it waits on the decider's key";
Expand Down Expand Up @@ -99,13 +99,17 @@ fn answered(agent: &ureq::Agent, address: &str, limit: usize) -> Result<String,
Ok(text)
}

/// minisign's legacy form — the list signed whole, not its hash — is refused: `minisign -S` writes
/// the pre-hashed form, and `minisign-verify` takes the other only when it is asked to (D56).
const LEGACY_ALLOWED: bool = false;

/// Whether `signature` is `key`'s over the bytes of `list`. minisign's pre-hashed signature only,
/// what `minisign -S` writes: the legacy form is refused.
pub fn verify(list: &str, signature: &str, key: &str) -> Result<(), String> {
let key = minisign_verify::PublicKey::from_base64(key).map_err(|error| format!("the key built in does not read ({error})"))?;
let signature =
minisign_verify::Signature::decode(signature).map_err(|error| format!("the list's signature does not read ({error})"))?;
key.verify(list.as_bytes(), &signature, false)
key.verify(list.as_bytes(), &signature, LEGACY_ALLOWED)
.map_err(|error| format!("the list's signature does not verify ({error})"))
}

Expand Down
71 changes: 71 additions & 0 deletions modules/shell/tests/registry_fetch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -221,3 +221,74 @@ fn the_list_in_the_repository_verifies_or_waits_on_the_key_and_the_check_says_wh
// Straight to the error stream: what the test harness captures would not be seen when it passes.
writeln!(std::io::stderr(), "registry/models.json: {said}").unwrap();
}

// Under the key built in (D56): the decider's, made in their own terminal — its private key in no
// repository and no session. The lists here are signed by a test's key, or are the list on `main`
// with the signature the decider made of it, `registry/models.json.minisig`.

/// The decider's key, as its `.pub` names it: `minisign public key 28AD0E835D7AF31E`.
const DECIDERS_KEY_ID: &str = "28AD0E835D7AF31E";

/// The signature the decider made of the list in the repository.
fn deciders_signature() -> String {
std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/registry/models.json.minisig"))
.expect("registry/models.json.minisig, the decider's signature of the list")
}

#[test]
fn the_key_built_in_is_the_deciders() {
let key = registry::PUBLIC_KEY.expect("a key built in");
let key = minisign::PublicKey::from_base64(key).unwrap();
// minisign shows a key's number as its eight bytes read little-endian.
let id: String = key.keynum().iter().rev().map(|byte| format!("{byte:02X}")).collect();
assert_eq!(id, DECIDERS_KEY_ID);
}

#[test]
fn under_the_key_built_in_a_list_signed_by_another_key_changed_after_it_was_signed_or_unsigned_is_refused() {
let list = registry::SHIPPED.to_owned();
let refused = [
("signed by another key", signed_by(&test_key(), list.clone())),
(
"changed after the decider signed it",
served_with(
200,
list.replacen("\"version\": 1", "\"version\": 1", 1),
"",
Some(deciders_signature()),
),
),
("unsigned", served_with(200, list.clone(), "", None)),
];
for (what, served) in refused {
let why = registry::fetch(&served.address, registry::PUBLIC_KEY).expect_err(what);
assert!(why.contains("signature") && !why.contains("waits"), "{what}: {why}");
assert_eq!(*served.asked.lock().unwrap(), ["/models.json", "/models.json.minisig"], "{what}");
}
}

#[test]
fn under_the_key_built_in_the_list_the_decider_signed_is_taken() {
let served = served_with(200, registry::SHIPPED.to_owned(), "", Some(deciders_signature()));
let listed = registry::fetch(&served.address, registry::PUBLIC_KEY).unwrap();
assert_eq!(listed, registry::shipped());
}

/// A key made for this test, outside it (openssl's Ed25519, the boxes as minisign writes them):
/// `minisign` the crate writes the pre-hashed form only. Its private key was not kept.
const FIXED_KEY: &str = "RWQBI0VniavN7wWzl40CApIQMFl5I82eP9r51HLn0+S12rpml2YUEJMN";
/// What that key signed, both ways.
const FIXED_LIST: &str = "A list signed by a key made for this test.\n";
/// Its signature in minisign's pre-hashed form, `ED`: what `minisign -S` writes.
const PREHASHED: &str = "untrusted comment: signature from minisign secret key\nRUQBI0VniavN7wrzXTMs5fdRG6KVz+5THLiu+a8cBCxN3Z4DuDpIiu2Cuw6V6r3uIeRW5H2FQ8B7Md7iETvI1lBzIvFSaYz98gs=\ntrusted comment: timestamp:1794666686\tfile:models.json\thashed\njSaui6oed+w24Xpc7qoBDxGb4ESZQFH+G1ZlPTqlNFx0oGA4rwdySDORy0ZpX4bGnpIEqTcPo1qHunqdHT7GAg==\n";
/// The same bytes signed in the legacy form, `Ed`: the list itself, not its hash.
const LEGACY: &str = "untrusted comment: signature from minisign secret key\nRWQBI0VniavN77JORcfb0/qk/S+eZJButt7IBOw0QkA5tgFZ6PaeIDWMDMQx9jpkVazHbKuJl/LBc6SjE2HJrM8V5/wcGoAWZgo=\ntrusted comment: timestamp:1794666686\tfile:models.json\thashed\ns6BDg+gP07KNfUzg51q7MJUZRhiw6Jt2I5D/UARqlcYKY/Z/aty8y7kYp9vXkt8Ezy0bjBGe/WWugAD6UjjkBA==\n";

#[test]
fn a_list_signed_in_minisigns_legacy_form_is_refused() {
// The same key and bytes, pre-hashed: verified — the refusal below is the form's alone.
assert_eq!(registry::verify(FIXED_LIST, PREHASHED, FIXED_KEY), Ok(()));
let why = registry::verify(FIXED_LIST, LEGACY, FIXED_KEY).unwrap_err();
assert!(why.contains("signature"), "{why}");
assert!(registry::in_the_repository(FIXED_LIST, Some(LEGACY), Some(FIXED_KEY)).is_err());
}
Loading