From 250780f4abb61f2a573035c02fce21f61c5089ae Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:46:53 +0100 Subject: [PATCH 1/7] test(api): an API key must not choose the export folder or an export's destination --- tests/export-access.test.ts | 169 ++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 tests/export-access.test.ts diff --git a/tests/export-access.test.ts b/tests/export-access.test.ts new file mode 100644 index 00000000..d6991406 --- /dev/null +++ b/tests/export-access.test.ts @@ -0,0 +1,169 @@ +/** + * Where finished calls are exported is the user's own choice on this computer: `export.dir` and + * the `to` of `POST /calls/{id}/export` are taken from the app's own token on the desktop app's + * loopback listener (`akou config set export.dir`, `akou export --to`) and from the desktop + * window, never from an `ak_` key, the network listener, the window's page in a browser or server + * mode. Each refused door is checked at the route, with the CLI's own path as the control. + */ + +import { describe, expect, test } from "bun:test"; +import { APP_IDENTITY, type Identity } from "../src/main/api/access.ts"; +import type { Mode } from "../src/main/api/http.ts"; +import { type ApiApp, buildRouter } from "../src/main/api/server.ts"; +import { + buildSettings, + type LoadedConfig, + patchConfig, + resolvePaths, + type SettingKey, + type SettingValue, +} from "../src/main/config/schema.ts"; + +/** An admin `ak_` key: what the network listener and server mode's keys resolve to. */ +const ADMIN_KEY: Identity = { id: "k_admin", name: "laptop", scopes: ["admin"], callbackHosts: [] }; + +interface Caller { + identity?: Identity | null; + browser?: boolean; + mode?: Mode; +} + +/** One `PATCH /v1/config` through the route, on a config file held in memory. */ +async function patch(who: Caller, body: Record, start = {}) { + const paths = resolvePaths({ AKOU_HOME: "/t" }); + let file: Partial> = { ...start }; + const loaded = (): LoadedConfig => ({ ...buildSettings(paths, file, {}), file }); + const app = { + mode: () => who.mode ?? "app", + config: loaded, + saveConfig: async (change: (f: typeof file) => typeof file) => { + file = change(file); + return loaded(); + }, + } as unknown as ApiApp; + const router = buildRouter(who.mode ?? "app"); + const url = new URL("http://127.0.0.1/v1/config"); + const m = router.match("PATCH", "/config"); + if ("status" in m) throw new Error("no config route"); + const req = new Request(url.href, { method: "PATCH", body: JSON.stringify(body) }); + const res = await m.handler({ + req, + url, + params: m.params, + app, + by: "agent:test", + identity: who.identity, + browser: who.browser, + }); + return { status: res.status, body: (await res.json()) as Record, file }; +} + +/** One `POST /v1/calls/c1/export` through the route; answers the folders the export was given. */ +async function exportTo(who: Caller, body: Record) { + const asked: (string | undefined)[] = []; + const app = { + mode: () => who.mode ?? "app", + manager: { resolve: (ref: string) => ({ ok: true, id: ref }) }, + exportCall: async (_id: string, o: { to?: string }) => { + asked.push(o.to); + return { ok: true, path: "/x.md", written: true, draft: null }; + }, + } as unknown as ApiApp; + const url = new URL("http://127.0.0.1/v1/calls/c1/export"); + const m = buildRouter("app").match("POST", "/calls/c1/export"); + if ("status" in m) throw new Error("no export route"); + const req = new Request(url.href, { method: "POST", body: JSON.stringify(body) }); + const res = await m.handler({ + req, + url, + params: m.params, + app, + by: "agent:test", + identity: who.identity, + browser: who.browser, + }); + return { status: res.status, body: (await res.json()) as Record, asked }; +} + +const DIR = { "export.dir": "/exports" }; +const SHARE = { "export.dir": "\\\\host.example\\drop" }; + +describe("[EXP-1] The export folder set by an API key", () => { + test("an admin ak_ key's PATCH of export.dir is 400 and the file keeps the user's folder", async () => { + const r = await patch({ identity: ADMIN_KEY }, SHARE, DIR); + expect(r.status).toBe(400); + expect(r.body.error).toBe("bad_setting"); + expect(String(r.body.message)).toContain("export.dir"); + expect(r.file).toEqual(DIR); + }); + + test("the app's own token in server mode is refused too", async () => { + const r = await patch({ identity: APP_IDENTITY, mode: "server" }, SHARE, DIR); + expect(r.status).toBe(400); + expect(r.file).toEqual(DIR); + }); + + test("the window's page in a browser is refused, as for the window-only keys", async () => { + const r = await patch({ browser: true }, SHARE, DIR); + expect(r.status).toBe(400); + expect(r.file).toEqual(DIR); + }); + + test("positive control: `akou config set export.dir` (the app token on loopback) and the desktop window still set it", async () => { + const cli = await patch({ identity: APP_IDENTITY }, { "export.dir": "/notes" }, DIR); + expect(cli.status).toBe(200); + expect(cli.file).toEqual({ "export.dir": "/notes" }); + const window = await patch({}, { "export.dir": "/notes" }, DIR); + expect(window.status).toBe(200); + expect(window.file).toEqual({ "export.dir": "/notes" }); + }); + + test("positive control: the same key still writes a setting that sends nothing anywhere", async () => { + const r = await patch({ identity: ADMIN_KEY }, { "asr.threads": 4 }); + expect(r.status).toBe(200); + expect(r.file).toEqual({ "asr.threads": 4 }); + }); + + test("patchConfig takes export.dir only from the user on this computer", () => { + const paths = resolvePaths({ AKOU_HOME: "/t" }); + expect(patchConfig({}, SHARE, paths)).toMatchObject({ ok: false }); + expect(patchConfig({}, SHARE, paths, { local: true })).toMatchObject({ ok: true, file: SHARE }); + expect(patchConfig({}, SHARE, paths, { inProcess: true })).toMatchObject({ + ok: true, + file: SHARE, + }); + }); +}); + +describe("[EXP-2] An export folder named by an API key", () => { + test("an admin ak_ key's `to` is 400 and nothing is exported", async () => { + const r = await exportTo({ identity: ADMIN_KEY }, { to: "\\\\host.example\\drop" }); + expect(r.status).toBe(400); + expect(r.body.error).toBe("bad_field"); + expect(r.asked).toEqual([]); + const posix = await exportTo({ identity: ADMIN_KEY }, { to: "/net/host.example/drop" }); + expect(posix.status).toBe(400); + expect(posix.asked).toEqual([]); + }); + + test("the window's page in a browser cannot name one either", async () => { + const r = await exportTo({ browser: true }, { to: "/elsewhere" }); + expect(r.status).toBe(400); + expect(r.asked).toEqual([]); + }); + + test("positive control: `akou export --to` (the app token on loopback) and the desktop window still name one", async () => { + const cli = await exportTo({ identity: APP_IDENTITY }, { to: "/elsewhere" }); + expect(cli.status).toBe(200); + expect(cli.asked).toEqual(["/elsewhere"]); + const window = await exportTo({}, { to: "/elsewhere" }); + expect(window.status).toBe(200); + expect(window.asked).toEqual(["/elsewhere"]); + }); + + test("positive control: the key still exports into the folder the user set", async () => { + const r = await exportTo({ identity: ADMIN_KEY }, {}); + expect(r.status).toBe(200); + expect(r.asked).toEqual([undefined]); + }); +}); From a1065fbb2fdc51e8d5f6fe4ab5e30face547380a Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:48:05 +0100 Subject: [PATCH 2/7] fix(security): keep the export folder the user's choice, never an API key's export.dir and the export's `to` decide where every finished call's transcript and audio are written, yet an admin key could set them over the API, from another machine, and point them at a share it controls. Both are now taken only from the user on this computer: the app's own token on the desktop app's loopback listener (akou config set, akou export --to) and the desktop window. An ak_ key, the window's page in a browser and server mode get 400. --- docs/DESIGN.md | 2 +- docs/TRAPS.md | 2 ++ docs/api/openapi.json | 2 +- docs/configuration.md | 2 +- src/main/api/caller.ts | 18 +++++++++++++++++- src/main/api/routes/handoff.ts | 13 +++++++++++-- src/main/api/routes/settings.ts | 3 ++- src/main/config/schema.ts | 22 +++++++++++++++++++--- 8 files changed, 54 insertions(+), 10 deletions(-) diff --git a/docs/DESIGN.md b/docs/DESIGN.md index d818ba10..703ac12e 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -637,7 +637,7 @@ Exit codes: 0 ok, 3 nothing live, 64 usage, 65 a vocabulary term fails validatio | `GET /vocab` · `POST /vocab` · `DELETE /vocab/{term}` · `POST /vocab/{approve,reject,suggest,check,import}` | The vocabulary files | | `POST /calls/{id}/enhance` `{template}` · `GET …/enhance/context?template=` · `PUT …/enhanced` `{markdown, coversSeq}` | Enhancement, with or without a provider | | `GET /calls/{id}/audio/{part}` | Range requests | -| `POST /calls/{id}/export` `{to?}` · `POST /calls/{id}/hooks` `{stage?}` · `POST /calls/{id}/finalize` | Hand-off, re-run. `to` is an absolute folder in place of `export.dir`; `409 export_not_configured` when neither is set, `409 not_ended` on a live call. `hooks` waits for the hooks and answers each run | +| `POST /calls/{id}/export` `{to?}` · `POST /calls/{id}/hooks` `{stage?}` · `POST /calls/{id}/finalize` | Hand-off, re-run. `to` is an absolute folder in place of `export.dir`, taken like `export.dir` only from akou on this computer (the app's token on loopback, or the window), never from an `ak_` key or in server mode; `409 export_not_configured` when neither is set, `409 not_ended` on a live call. `hooks` waits for the hooks and answers each run | | `POST /import/hark-viewer` `{dirs[], workspace?}` | Imports predecessor call folders (absolute paths); `422 not_imported` with the reasons when none could be | | `POST /share` · `DELETE /share` · `GET /share` | Sharing | | `GET /templates` · `GET /templates/{name}` · `GET /config` · `PATCH /config` | Settings | diff --git a/docs/TRAPS.md b/docs/TRAPS.md index 80e4de0a..522ef772 100644 --- a/docs/TRAPS.md +++ b/docs/TRAPS.md @@ -139,6 +139,8 @@ Every number here comes from our vocabulary measurements: a synthetic TTS set an - **A provider command set over the API** [decision] (M2). Given `provider.command`, a program akou runs with the user's question, a `PATCH /config` or the settings pane must refuse to set it: like the harness path it is set in the config file only, or any key holder could make akou run a program of their choice. Test: `tests/ask-agent.test.ts`, with a control that sets the file-only key from the file. - **A window-only setting set through the browser page** [known bug] (M2). Given a session on the page server (the window in a browser, opened with `POST /v1/window`, which the API token alone can ask for, or in server mode with an admin key), a `PATCH /config` of a key only the desktop window may set (`provider.baseUrl`, `network.*`, `dictation.remote.url`) must get 400 `bad_setting` and leave the file as it was. The page server runs its requests through the same bridge as the desktop window, with no identity, so it was taken for the window. Test: `tests/window.test.ts`, with the desktop window's bridge setting the same key as the positive control. - **The models folder set over the API** [known bug] (M2). Given `asr.modelsDir`, the folder akou runs the pinned llama-server and CrispASR builds from (`//bin`), a `PATCH /config` from an HTTP client must refuse it, as for `asr.llamaServer`: otherwise an admin key could point it at a share it controls and have akou run its program. The desktop window and the file still set it; server mode sets it in the file or with `AKOU_MODELS_DIR`. Test: `tests/config.test.ts`, with `asr.threads` still written over HTTP as the positive control. +- **The export folder set by an API key** [EXP-1] (M2). Given `export.dir`, where every finished call's Markdown, event log and (with `export.audio: copy`) audio are written, an admin `ak_` key could set it with `PATCH /config` to a share it chose (`\\host\share` on Windows, `/net/` on macOS), and every later call went there, even after the key was revoked. A `PATCH /config` of it must get 400 `bad_setting` and leave the file as it was when it comes from an `ak_` key (the network listener takes nothing else), the window's page in a browser, or server mode. The app's own token on the desktop app's loopback listener (`akou config set export.dir`) and the desktop window still set it. Test: `tests/export-access.test.ts`, each refused door, with the CLI path, the window and a key writing `asr.threads` as the positive controls. +- **An export folder named by an API key** [EXP-2] (M2). Given `POST /calls/{id}/export {to}`, the same callers must be refused a `to` (400 `bad_field`, nothing exported), as for `export.dir`: on Windows a UNC `to` also sends the user's NTLM hash to that host. `akou export --to DIR` (the app's token on loopback) and the window still name one, and a key's export without `to` still goes into `export.dir`. Test: `tests/export-access.test.ts`, with those three as the positive controls. - **The remotes shown to a caller with no key** [known bug] (M2). Given a server with `server.remotes`, `GET /v1/server` needs no key, so behind a public proxy anyone can call it. Without a key it must list no remotes: their addresses, versions and states map the private network behind the proxy. A caller with any key still sees them. Test: `tests/remote-dispatch.e2e.test.ts`, with the same request carrying a key as the positive control. - **A key edit that wipes an unreadable keys file** [SV-K2] (M2). Given a `keys.json` that does not parse or holds no key list, a process that started on it (the CLI always does) read no keys, and its next `keys create`, `revoke` or `update` wrote only the new list over the file: every other key was gone, and remotes and agents got 401. An edit must be refused (409 `keys_file_invalid` over HTTP) and leave the file as it is. A missing file is a first key, not a refusal. Test: `tests/keys-file.test.ts`, a broken file and a file with no key list (refused, byte for byte the same), `akou keys revoke` on a broken file (`bad_key`, exit 64, the file untouched), with a valid file that keeps its key when another is made as the positive control. - **Token file readable by others** [T4.45] (M1). Given a fresh install, the token file must be mode 0600 (or a user-only ACL on Windows) and created atomically. Test: stat after `akou doctor`. diff --git a/docs/api/openapi.json b/docs/api/openapi.json index cd7fbb83..d587f478 100644 --- a/docs/api/openapi.json +++ b/docs/api/openapi.json @@ -6499,7 +6499,7 @@ "tags": [ "calls" ], - "description": "Export an ended call as Markdown with frontmatter into the export folder, or into the absolute folder `to` names. Answers the file written, and whether it went beside a copy the user edited.", + "description": "Export an ended call as Markdown with frontmatter into the export folder, or into the absolute folder `to` names; `to` is taken only from akou on this computer (the app's token or the window), never from an API key. Answers the file written, and whether it went beside a copy the user edited.", "parameters": [ { "name": "id", diff --git a/docs/configuration.md b/docs/configuration.md index 07b430c3..a43222ac 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -187,7 +187,7 @@ The tables below are generated from the settings registry in [src/main/config/sc | Key | Default | What it does | |---|---|---| -| `export.dir` | `""` | Folder finished calls are exported into, one subfolder per workspace: Markdown with frontmatter, the event log and the audio. Empty: no export until you set it. | +| `export.dir` | `""` | Folder finished calls are exported into, one subfolder per workspace: Markdown with frontmatter, the event log and the audio. Empty: no export until you set it. Set in the window, the file or with `akou config set` on this computer; an API key cannot set it, since it decides where your transcripts are written. | | `export.audio` | `"link"` | How the export carries the audio: a link to the call's file, a copy, or nothing. | ### hooks diff --git a/src/main/api/caller.ts b/src/main/api/caller.ts index 0164eae1..b6899616 100644 --- a/src/main/api/caller.ts +++ b/src/main/api/caller.ts @@ -4,7 +4,7 @@ */ import { APP_IDENTITY, callbackAllowed, type Identity } from "./access.ts"; -import { HttpError } from "./http.ts"; +import { HttpError, type Mode } from "./http.ts"; /** `POST /v1/jobs` with a callback the key may not name: 422 `callback_not_allowed`. */ export function requireCallbackAllowed(identity: Identity, url: string): void { @@ -29,3 +29,19 @@ export function caller(c: { identity?: Identity | null }): Identity { } return c.identity; } + +/** + * Is the caller the user on this computer: the desktop window in process, or the app's own token, + * which the desktop app takes only on its loopback listener? Never an `ak_` key (the network + * listener takes nothing else), the window's page in a browser, or server mode. For what decides + * where transcripts are written: `export.dir` and the export's `to`. + */ +export function isLocalUser(c: { + identity?: Identity | null; + browser?: boolean; + app: { mode?(): Mode }; +}): boolean { + if ((c.app.mode?.() ?? "app") !== "app") return false; + if (c.identity === undefined) return c.browser !== true; + return c.identity === APP_IDENTITY; +} diff --git a/src/main/api/routes/handoff.ts b/src/main/api/routes/handoff.ts index fb0cace4..4bda6008 100644 --- a/src/main/api/routes/handoff.ts +++ b/src/main/api/routes/handoff.ts @@ -2,7 +2,7 @@ * The hand-off and the import (docs/DESIGN.md sections 6.1, 6.2 and 8.2). * * - `POST /calls/{id}/export {to?}`: exports a finished call into `export.dir`, or into the - * absolute folder `to` names. `last` is accepted. Answers the file, whether anything was written, + * absolute folder `to` names (akou on this computer only, never an API key). `last` is accepted. Answers the file, whether anything was written, * and whether it went beside a file the user edited. * - `POST /calls/{id}/hooks {stage?}`: runs the hooks again (`akou hooks run`), waiting for them. * Without `stage`, every stage the call has reached. The export and the webhook are not re-run. @@ -11,6 +11,7 @@ import { isAbsolute } from "node:path"; import { HOOK_STAGES, type HookStage } from "../../config/schema.ts"; +import { isLocalUser } from "../caller.ts"; import { errorsOf } from "../errors.ts"; import { HttpError, json, outcome, type Router } from "../http.ts"; import type { ApiApp } from "../server.ts"; @@ -22,7 +23,7 @@ export function handoffRoutes(r: Router): void { "/calls/:id/export", { id: "calls.export", - doc: "Export an ended call as Markdown with frontmatter into the export folder, or into the absolute folder `to` names. Answers the file written, and whether it went beside a copy the user edited.", + doc: "Export an ended call as Markdown with frontmatter into the export folder, or into the absolute folder `to` names; `to` is taken only from akou on this computer (the app's token or the window), never from an API key. Answers the file written, and whether it went beside a copy the user edited.", access: "admin", modes: ["app"], params: { id: CALL_ID }, @@ -37,6 +38,14 @@ export function handoffRoutes(r: Router): void { if (b.to !== undefined && !isAbsolute(b.to)) { throw new HttpError(400, "bad_field", "`to` must be an absolute folder"); } + // Where a transcript is written is the user's choice, as `export.dir` is: never a key's. + if (b.to !== undefined && !isLocalUser(c)) { + throw new HttpError( + 400, + "bad_field", + "`to` is taken only from akou on this computer; an API key exports into export.dir", + ); + } const id = callId(c, { allowLast: true }); // The export waits behind the call's earlier hand-off work, hooks included. c.timeout?.(0); diff --git a/src/main/api/routes/settings.ts b/src/main/api/routes/settings.ts index eb207faf..2694e6fe 100644 --- a/src/main/api/routes/settings.ts +++ b/src/main/api/routes/settings.ts @@ -20,6 +20,7 @@ import { } from "../../config/schema.ts"; import { STORED_SECRETS } from "../../config/secrets.ts"; import { fillPreset, type Preset, usesSpeaker } from "../../notes/presets.ts"; +import { isLocalUser } from "../caller.ts"; import { errorsOf } from "../errors.ts"; import { HttpError, json, OPEN_BODY, type Router } from "../http.ts"; import type { ApiApp } from "../server.ts"; @@ -110,7 +111,7 @@ export function settingsRoutes(r: Router): void { ); // Made from the file as the save before it left it: saves run one at a time. const change = (current: typeof cfg.file) => { - const res = patchConfig(current, body, cfg.paths, { inProcess }); + const res = patchConfig(current, body, cfg.paths, { inProcess, local: isLocalUser(c) }); if (!res.ok) throw new HttpError(400, "bad_setting", res.errors.join("; "), { errors: res.errors }); return res.file; diff --git a/src/main/config/schema.ts b/src/main/config/schema.ts index 81754ce0..47a22761 100644 --- a/src/main/config/schema.ts +++ b/src/main/config/schema.ts @@ -123,6 +123,14 @@ export interface SettingSpec { * where their audio goes (`dictation.remote.url`). */ windowWritable?: boolean; + /** + * False for a setting that decides where transcripts are written (`export.dir`): over the API + * only the user on this computer sets it, with the app's own token on the desktop app's loopback + * listener (`akou config set`) or in the desktop window. An `ak_` key, the network listener, the + * window's page in a browser and server mode are refused, so a key cannot send every later call + * to a folder or share it chose. + */ + keyWritable?: boolean; /** A secret (an API key): never shown by `GET /config`, `config show` or `status`. */ secret?: boolean; /** A rule the type cannot say: the error, or null when the value is good. */ @@ -701,7 +709,8 @@ export const SETTINGS = { "export.dir": { type: "string", default: "", - doc: "Folder finished calls are exported into, one subfolder per workspace: Markdown with frontmatter, the event log and the audio. Empty: no export until you set it.", + keyWritable: false, + doc: "Folder finished calls are exported into, one subfolder per workspace: Markdown with frontmatter, the event log and the audio. Empty: no export until you set it. Set in the window, the file or with `akou config set` on this computer; an API key cannot set it, since it decides where your transcripts are written.", }, "export.audio": { type: "string", @@ -1472,13 +1481,14 @@ export function loadConfig( /** * Validates a `PATCH /config` body: `{key: value}` to set, `{key: null}` to go back to the default. * Returns the new file contents, or every error at once. Settings that name a program are refused; - * a `windowWritable` one is taken only `inProcess`, from the desktop window. + * a `windowWritable` one is taken only `inProcess`, from the desktop window; a `keyWritable: false` + * one only in process or from the `local` user (the app's own token on the desktop app's loopback). */ export function patchConfig( current: Partial>, patch: Record, paths: Paths, - o: { inProcess?: boolean } = {}, + o: { inProcess?: boolean; local?: boolean } = {}, ): { ok: true; file: Partial> } | { ok: false; errors: string[] } { const next = { ...current }; const errors: string[] = []; @@ -1494,6 +1504,12 @@ export function patchConfig( errors.push(`${key}: set it in config.json; it is not writable over the API`); continue; } + if (spec?.keyWritable === false && !(o.inProcess || o.local)) { + errors.push( + `${key}: set it in the akou window, config.json or with \`akou config set\` on this computer; an API key cannot set it`, + ); + continue; + } if (value === null) { if (!isSettingKey(key)) errors.push(`${key}: unknown setting`); else delete next[key]; From 16692d108e4c0361170432cf8c057e2a419234cd Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:48:57 +0100 Subject: [PATCH 3/7] test(api): read a route's refusal as the server answers it --- tests/export-access.test.ts | 52 +++++++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 19 deletions(-) diff --git a/tests/export-access.test.ts b/tests/export-access.test.ts index d6991406..1568efb1 100644 --- a/tests/export-access.test.ts +++ b/tests/export-access.test.ts @@ -8,7 +8,7 @@ import { describe, expect, test } from "bun:test"; import { APP_IDENTITY, type Identity } from "../src/main/api/access.ts"; -import type { Mode } from "../src/main/api/http.ts"; +import { errorResponse, HttpError, type Mode } from "../src/main/api/http.ts"; import { type ApiApp, buildRouter } from "../src/main/api/server.ts"; import { buildSettings, @@ -22,6 +22,16 @@ import { /** An admin `ak_` key: what the network listener and server mode's keys resolve to. */ const ADMIN_KEY: Identity = { id: "k_admin", name: "laptop", scopes: ["admin"], callbackHosts: [] }; +/** A handler's answer, with a thrown refusal turned into its response as the server does. */ +async function answer(run: () => Promise | Response): Promise { + try { + return await run(); + } catch (err) { + if (err instanceof HttpError) return errorResponse(err); + throw err; + } +} + interface Caller { identity?: Identity | null; browser?: boolean; @@ -46,15 +56,17 @@ async function patch(who: Caller, body: Record, start = {}) { const m = router.match("PATCH", "/config"); if ("status" in m) throw new Error("no config route"); const req = new Request(url.href, { method: "PATCH", body: JSON.stringify(body) }); - const res = await m.handler({ - req, - url, - params: m.params, - app, - by: "agent:test", - identity: who.identity, - browser: who.browser, - }); + const res = await answer(() => + m.handler({ + req, + url, + params: m.params, + app, + by: "agent:test", + identity: who.identity, + browser: who.browser, + }), + ); return { status: res.status, body: (await res.json()) as Record, file }; } @@ -73,15 +85,17 @@ async function exportTo(who: Caller, body: Record) { const m = buildRouter("app").match("POST", "/calls/c1/export"); if ("status" in m) throw new Error("no export route"); const req = new Request(url.href, { method: "POST", body: JSON.stringify(body) }); - const res = await m.handler({ - req, - url, - params: m.params, - app, - by: "agent:test", - identity: who.identity, - browser: who.browser, - }); + const res = await answer(() => + m.handler({ + req, + url, + params: m.params, + app, + by: "agent:test", + identity: who.identity, + browser: who.browser, + }), + ); return { status: res.status, body: (await res.json()) as Record, asked }; } From 3173c55d85601758502008c85d900500fd80001e Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:55:12 +0100 Subject: [PATCH 4/7] test(api): an API key must not choose the recordings folder --- tests/export-access.test.ts | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/tests/export-access.test.ts b/tests/export-access.test.ts index 1568efb1..b92722c8 100644 --- a/tests/export-access.test.ts +++ b/tests/export-access.test.ts @@ -111,6 +111,19 @@ describe("[EXP-1] The export folder set by an API key", () => { expect(r.file).toEqual(DIR); }); + test("an admin ak_ key's PATCH of recordings.root is 400 too: every later call is recorded there", async () => { + const ROOT = { "recordings.root": "/calls" }; + const r = await patch({ identity: ADMIN_KEY }, { "recordings.root": "\\\\host.example\\drop" }, ROOT); + expect(r.status).toBe(400); + expect(r.body.error).toBe("bad_setting"); + expect(String(r.body.message)).toContain("recordings.root"); + expect(r.file).toEqual(ROOT); + // Positive control: `akou config set recordings.root` (the app token on loopback) still sets it. + const cli = await patch({ identity: APP_IDENTITY }, { "recordings.root": "/notes" }, ROOT); + expect(cli.status).toBe(200); + expect(cli.file).toEqual({ "recordings.root": "/notes" }); + }); + test("the app's own token in server mode is refused too", async () => { const r = await patch({ identity: APP_IDENTITY, mode: "server" }, SHARE, DIR); expect(r.status).toBe(400); From 8e062e949de5fafe382e6b1f8fb1df16f21caa86 Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 10:56:30 +0100 Subject: [PATCH 5/7] fix(security): keep the recordings folder the user's choice, never an API key's --- docs/TRAPS.md | 2 +- docs/configuration.md | 2 +- src/main/config/schema.ts | 13 +++++++------ tests/export-access.test.ts | 3 ++- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/TRAPS.md b/docs/TRAPS.md index 522ef772..ce20143e 100644 --- a/docs/TRAPS.md +++ b/docs/TRAPS.md @@ -139,7 +139,7 @@ Every number here comes from our vocabulary measurements: a synthetic TTS set an - **A provider command set over the API** [decision] (M2). Given `provider.command`, a program akou runs with the user's question, a `PATCH /config` or the settings pane must refuse to set it: like the harness path it is set in the config file only, or any key holder could make akou run a program of their choice. Test: `tests/ask-agent.test.ts`, with a control that sets the file-only key from the file. - **A window-only setting set through the browser page** [known bug] (M2). Given a session on the page server (the window in a browser, opened with `POST /v1/window`, which the API token alone can ask for, or in server mode with an admin key), a `PATCH /config` of a key only the desktop window may set (`provider.baseUrl`, `network.*`, `dictation.remote.url`) must get 400 `bad_setting` and leave the file as it was. The page server runs its requests through the same bridge as the desktop window, with no identity, so it was taken for the window. Test: `tests/window.test.ts`, with the desktop window's bridge setting the same key as the positive control. - **The models folder set over the API** [known bug] (M2). Given `asr.modelsDir`, the folder akou runs the pinned llama-server and CrispASR builds from (`//bin`), a `PATCH /config` from an HTTP client must refuse it, as for `asr.llamaServer`: otherwise an admin key could point it at a share it controls and have akou run its program. The desktop window and the file still set it; server mode sets it in the file or with `AKOU_MODELS_DIR`. Test: `tests/config.test.ts`, with `asr.threads` still written over HTTP as the positive control. -- **The export folder set by an API key** [EXP-1] (M2). Given `export.dir`, where every finished call's Markdown, event log and (with `export.audio: copy`) audio are written, an admin `ak_` key could set it with `PATCH /config` to a share it chose (`\\host\share` on Windows, `/net/` on macOS), and every later call went there, even after the key was revoked. A `PATCH /config` of it must get 400 `bad_setting` and leave the file as it was when it comes from an `ak_` key (the network listener takes nothing else), the window's page in a browser, or server mode. The app's own token on the desktop app's loopback listener (`akou config set export.dir`) and the desktop window still set it. Test: `tests/export-access.test.ts`, each refused door, with the CLI path, the window and a key writing `asr.threads` as the positive controls. +- **The export folder set by an API key** [EXP-1] (M2). Given `export.dir`, where every finished call's Markdown, event log and (with `export.audio: copy`) audio are written, an admin `ak_` key could set it with `PATCH /config` to a share it chose (`\\host\share` on Windows, `/net/` on macOS), and every later call went there, even after the key was revoked. The same holds for `recordings.root`, where every later call is recorded. A `PATCH /config` of either must get 400 `bad_setting` and leave the file as it was when it comes from an `ak_` key (the network listener takes nothing else), the window's page in a browser, or server mode. The app's own token on the desktop app's loopback listener (`akou config set export.dir`) and the desktop window still set it. Test: `tests/export-access.test.ts`, each refused door, with the CLI path, the window and a key writing `asr.threads` as the positive controls. - **An export folder named by an API key** [EXP-2] (M2). Given `POST /calls/{id}/export {to}`, the same callers must be refused a `to` (400 `bad_field`, nothing exported), as for `export.dir`: on Windows a UNC `to` also sends the user's NTLM hash to that host. `akou export --to DIR` (the app's token on loopback) and the window still name one, and a key's export without `to` still goes into `export.dir`. Test: `tests/export-access.test.ts`, with those three as the positive controls. - **The remotes shown to a caller with no key** [known bug] (M2). Given a server with `server.remotes`, `GET /v1/server` needs no key, so behind a public proxy anyone can call it. Without a key it must list no remotes: their addresses, versions and states map the private network behind the proxy. A caller with any key still sees them. Test: `tests/remote-dispatch.e2e.test.ts`, with the same request carrying a key as the positive control. - **A key edit that wipes an unreadable keys file** [SV-K2] (M2). Given a `keys.json` that does not parse or holds no key list, a process that started on it (the CLI always does) read no keys, and its next `keys create`, `revoke` or `update` wrote only the new list over the file: every other key was gone, and remotes and agents got 401. An edit must be refused (409 `keys_file_invalid` over HTTP) and leave the file as it is. A missing file is a first key, not a refusal. Test: `tests/keys-file.test.ts`, a broken file and a file with no key list (refused, byte for byte the same), `akou keys revoke` on a broken file (`bad_key`, exit 64, the file untouched), with a valid file that keeps its key when another is made as the positive control. diff --git a/docs/configuration.md b/docs/configuration.md index a43222ac..adae0a06 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,7 +40,7 @@ The tables below are generated from the settings registry in [src/main/config/sc | Key | Default | What it does | |---|---|---| -| `recordings.root` | `"~/Recordings/akou"` | Folder that holds a subfolder per workspace, each holding one folder per call. Applies at the next start; calls already recorded stay in the old folder until you move them. | +| `recordings.root` | `"~/Recordings/akou"` | Folder that holds a subfolder per workspace, each holding one folder per call. Applies at the next start; calls already recorded stay in the old folder until you move them. Set in the window, the file or with `akou config set` on this computer; an API key cannot set it, since it decides where your calls are recorded. | ### user diff --git a/src/main/config/schema.ts b/src/main/config/schema.ts index 47a22761..8423751f 100644 --- a/src/main/config/schema.ts +++ b/src/main/config/schema.ts @@ -124,11 +124,11 @@ export interface SettingSpec { */ windowWritable?: boolean; /** - * False for a setting that decides where transcripts are written (`export.dir`): over the API - * only the user on this computer sets it, with the app's own token on the desktop app's loopback - * listener (`akou config set`) or in the desktop window. An `ak_` key, the network listener, the - * window's page in a browser and server mode are refused, so a key cannot send every later call - * to a folder or share it chose. + * False for a setting that decides where calls or transcripts are written (`recordings.root`, + * `export.dir`): over the API only the user on this computer sets it, with the app's own token + * on the desktop app's loopback listener (`akou config set`) or in the desktop window. An `ak_` + * key, the network listener, the window's page in a browser and server mode are refused, so a + * key cannot send every later call to a folder or share it chose. */ keyWritable?: boolean; /** A secret (an API key): never shown by `GET /config`, `config show` or `status`. */ @@ -162,7 +162,8 @@ export const SETTINGS = { type: "string", min: 1, default: join(home, "Recordings", "akou"), - doc: "Folder that holds a subfolder per workspace, each holding one folder per call. Applies at the next start; calls already recorded stay in the old folder until you move them.", + keyWritable: false, + doc: "Folder that holds a subfolder per workspace, each holding one folder per call. Applies at the next start; calls already recorded stay in the old folder until you move them. Set in the window, the file or with `akou config set` on this computer; an API key cannot set it, since it decides where your calls are recorded.", }, "user.name": { type: "string", diff --git a/tests/export-access.test.ts b/tests/export-access.test.ts index b92722c8..366ace62 100644 --- a/tests/export-access.test.ts +++ b/tests/export-access.test.ts @@ -113,7 +113,8 @@ describe("[EXP-1] The export folder set by an API key", () => { test("an admin ak_ key's PATCH of recordings.root is 400 too: every later call is recorded there", async () => { const ROOT = { "recordings.root": "/calls" }; - const r = await patch({ identity: ADMIN_KEY }, { "recordings.root": "\\\\host.example\\drop" }, ROOT); + const SHARED = { "recordings.root": "\\\\host.example\\drop" }; + const r = await patch({ identity: ADMIN_KEY }, SHARED, ROOT); expect(r.status).toBe(400); expect(r.body.error).toBe("bad_setting"); expect(String(r.body.message)).toContain("recordings.root"); From 0bd4890f2e6ee5bdb06b6d090032b9cf61145f8a Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:49:54 +0100 Subject: [PATCH 6/7] test(api): the window's page in the app's own browser sets where calls go --- tests/export-access.test.ts | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/tests/export-access.test.ts b/tests/export-access.test.ts index 366ace62..1a39cf0e 100644 --- a/tests/export-access.test.ts +++ b/tests/export-access.test.ts @@ -1,9 +1,10 @@ /** * Where finished calls are exported is the user's own choice on this computer: `export.dir` and * the `to` of `POST /calls/{id}/export` are taken from the app's own token on the desktop app's - * loopback listener (`akou config set export.dir`, `akou export --to`) and from the desktop - * window, never from an `ak_` key, the network listener, the window's page in a browser or server - * mode. Each refused door is checked at the route, with the CLI's own path as the control. + * loopback listener (`akou config set export.dir`, `akou export --to`) and from the window (the + * desktop window, or its page in a browser on the app's loopback page server, where the headless + * app runs its first-run setup), never from an `ak_` key, the network listener or server mode. + * Each refused door is checked at the route, with the CLI's own path as the control. */ import { describe, expect, test } from "bun:test"; @@ -131,10 +132,22 @@ describe("[EXP-1] The export folder set by an API key", () => { expect(r.file).toEqual(DIR); }); - test("the window's page in a browser is refused, as for the window-only keys", async () => { - const r = await patch({ browser: true }, SHARE, DIR); + test("the window's page in a browser in server mode is refused: it is opened with the admin password or a key", async () => { + const r = await patch({ browser: true, mode: "server" }, SHARE, DIR); expect(r.status).toBe(400); expect(r.file).toEqual(DIR); + const root = await patch({ browser: true, mode: "server" }, { "recordings.root": "/calls" }); + expect(root.status).toBe(400); + expect(root.file).toEqual({}); + }); + + test("the window's page in a browser in the app sets both: the headless app's first-run setup picks where calls go", async () => { + const root = await patch({ browser: true }, { "recordings.root": "/home/me/Calls" }); + expect(root.status).toBe(200); + expect(root.file).toEqual({ "recordings.root": "/home/me/Calls" }); + const dir = await patch({ browser: true }, { "export.dir": "/notes" }, DIR); + expect(dir.status).toBe(200); + expect(dir.file).toEqual({ "export.dir": "/notes" }); }); test("positive control: `akou config set export.dir` (the app token on loopback) and the desktop window still set it", async () => { @@ -174,12 +187,18 @@ describe("[EXP-2] An export folder named by an API key", () => { expect(posix.asked).toEqual([]); }); - test("the window's page in a browser cannot name one either", async () => { - const r = await exportTo({ browser: true }, { to: "/elsewhere" }); + test("the window's page in a browser in server mode cannot name one either", async () => { + const r = await exportTo({ browser: true, mode: "server" }, { to: "/elsewhere" }); expect(r.status).toBe(400); expect(r.asked).toEqual([]); }); + test("the window's page in a browser in the app names one, as the desktop window does", async () => { + const r = await exportTo({ browser: true }, { to: "/elsewhere" }); + expect(r.status).toBe(200); + expect(r.asked).toEqual(["/elsewhere"]); + }); + test("positive control: `akou export --to` (the app token on loopback) and the desktop window still name one", async () => { const cli = await exportTo({ identity: APP_IDENTITY }, { to: "/elsewhere" }); expect(cli.status).toBe(200); From 3cb2b63ed7db27d79c38eef1de34afd253e43518 Mon Sep 17 00:00:00 2001 From: GeiserX <9169332+GeiserX@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:49:57 +0100 Subject: [PATCH 7/7] fix(security): let the headless window's first-run setup choose the recordings folder --- docs/TRAPS.md | 4 ++-- src/main/api/caller.ts | 19 ++++++++----------- src/main/config/schema.ts | 10 ++++++---- 3 files changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/TRAPS.md b/docs/TRAPS.md index ce20143e..cc6c65c8 100644 --- a/docs/TRAPS.md +++ b/docs/TRAPS.md @@ -139,8 +139,8 @@ Every number here comes from our vocabulary measurements: a synthetic TTS set an - **A provider command set over the API** [decision] (M2). Given `provider.command`, a program akou runs with the user's question, a `PATCH /config` or the settings pane must refuse to set it: like the harness path it is set in the config file only, or any key holder could make akou run a program of their choice. Test: `tests/ask-agent.test.ts`, with a control that sets the file-only key from the file. - **A window-only setting set through the browser page** [known bug] (M2). Given a session on the page server (the window in a browser, opened with `POST /v1/window`, which the API token alone can ask for, or in server mode with an admin key), a `PATCH /config` of a key only the desktop window may set (`provider.baseUrl`, `network.*`, `dictation.remote.url`) must get 400 `bad_setting` and leave the file as it was. The page server runs its requests through the same bridge as the desktop window, with no identity, so it was taken for the window. Test: `tests/window.test.ts`, with the desktop window's bridge setting the same key as the positive control. - **The models folder set over the API** [known bug] (M2). Given `asr.modelsDir`, the folder akou runs the pinned llama-server and CrispASR builds from (`//bin`), a `PATCH /config` from an HTTP client must refuse it, as for `asr.llamaServer`: otherwise an admin key could point it at a share it controls and have akou run its program. The desktop window and the file still set it; server mode sets it in the file or with `AKOU_MODELS_DIR`. Test: `tests/config.test.ts`, with `asr.threads` still written over HTTP as the positive control. -- **The export folder set by an API key** [EXP-1] (M2). Given `export.dir`, where every finished call's Markdown, event log and (with `export.audio: copy`) audio are written, an admin `ak_` key could set it with `PATCH /config` to a share it chose (`\\host\share` on Windows, `/net/` on macOS), and every later call went there, even after the key was revoked. The same holds for `recordings.root`, where every later call is recorded. A `PATCH /config` of either must get 400 `bad_setting` and leave the file as it was when it comes from an `ak_` key (the network listener takes nothing else), the window's page in a browser, or server mode. The app's own token on the desktop app's loopback listener (`akou config set export.dir`) and the desktop window still set it. Test: `tests/export-access.test.ts`, each refused door, with the CLI path, the window and a key writing `asr.threads` as the positive controls. -- **An export folder named by an API key** [EXP-2] (M2). Given `POST /calls/{id}/export {to}`, the same callers must be refused a `to` (400 `bad_field`, nothing exported), as for `export.dir`: on Windows a UNC `to` also sends the user's NTLM hash to that host. `akou export --to DIR` (the app's token on loopback) and the window still name one, and a key's export without `to` still goes into `export.dir`. Test: `tests/export-access.test.ts`, with those three as the positive controls. +- **The export folder set by an API key** [EXP-1] (M2). Given `export.dir`, where every finished call's Markdown, event log and (with `export.audio: copy`) audio are written, an admin `ak_` key could set it with `PATCH /config` to a share it chose (`\\host\share` on Windows, `/net/` on macOS), and every later call went there, even after the key was revoked. The same holds for `recordings.root`, where every later call is recorded. A `PATCH /config` of either must get 400 `bad_setting` and leave the file as it was when it comes from an `ak_` key (the network listener takes nothing else) or server mode, its page in a browser included. The app's own token on the desktop app's loopback listener (`akou config set export.dir`) and the window still set it: the desktop window, and its page in a browser on the app's loopback page server, where the headless app runs its first-run setup (the setup's Where calls go step writes `recordings.root`). Test: `tests/export-access.test.ts`, each refused door, with the CLI path, the window, the window's page in a browser and a key writing `asr.threads` as the positive controls. +- **An export folder named by an API key** [EXP-2] (M2). Given `POST /calls/{id}/export {to}`, the same callers must be refused a `to` (400 `bad_field`, nothing exported), as for `export.dir`: on Windows a UNC `to` also sends the user's NTLM hash to that host. `akou export --to DIR` (the app's token on loopback) and the window, in a browser too, still name one, and a key's export without `to` still goes into `export.dir`. Test: `tests/export-access.test.ts`, with those three as the positive controls. - **The remotes shown to a caller with no key** [known bug] (M2). Given a server with `server.remotes`, `GET /v1/server` needs no key, so behind a public proxy anyone can call it. Without a key it must list no remotes: their addresses, versions and states map the private network behind the proxy. A caller with any key still sees them. Test: `tests/remote-dispatch.e2e.test.ts`, with the same request carrying a key as the positive control. - **A key edit that wipes an unreadable keys file** [SV-K2] (M2). Given a `keys.json` that does not parse or holds no key list, a process that started on it (the CLI always does) read no keys, and its next `keys create`, `revoke` or `update` wrote only the new list over the file: every other key was gone, and remotes and agents got 401. An edit must be refused (409 `keys_file_invalid` over HTTP) and leave the file as it is. A missing file is a first key, not a refusal. Test: `tests/keys-file.test.ts`, a broken file and a file with no key list (refused, byte for byte the same), `akou keys revoke` on a broken file (`bad_key`, exit 64, the file untouched), with a valid file that keeps its key when another is made as the positive control. - **Token file readable by others** [T4.45] (M1). Given a fresh install, the token file must be mode 0600 (or a user-only ACL on Windows) and created atomically. Test: stat after `akou doctor`. diff --git a/src/main/api/caller.ts b/src/main/api/caller.ts index b6899616..5df5b5b4 100644 --- a/src/main/api/caller.ts +++ b/src/main/api/caller.ts @@ -31,17 +31,14 @@ export function caller(c: { identity?: Identity | null }): Identity { } /** - * Is the caller the user on this computer: the desktop window in process, or the app's own token, - * which the desktop app takes only on its loopback listener? Never an `ak_` key (the network - * listener takes nothing else), the window's page in a browser, or server mode. For what decides - * where transcripts are written: `export.dir` and the export's `to`. + * Is the caller the user on this computer: the window in process (the desktop window, or its page + * in a browser on the app's own loopback page server, which is how the headless app shows its + * window and runs its first-run setup), or the app's own token, which the desktop app takes only + * on its loopback listener? Never an `ak_` key (the network listener takes nothing else), or + * server mode, whose page is opened with the admin password or a key. For what decides where calls + * and transcripts are written: `recordings.root`, `export.dir` and the export's `to`. */ -export function isLocalUser(c: { - identity?: Identity | null; - browser?: boolean; - app: { mode?(): Mode }; -}): boolean { +export function isLocalUser(c: { identity?: Identity | null; app: { mode?(): Mode } }): boolean { if ((c.app.mode?.() ?? "app") !== "app") return false; - if (c.identity === undefined) return c.browser !== true; - return c.identity === APP_IDENTITY; + return c.identity === undefined || c.identity === APP_IDENTITY; } diff --git a/src/main/config/schema.ts b/src/main/config/schema.ts index 8423751f..b701152b 100644 --- a/src/main/config/schema.ts +++ b/src/main/config/schema.ts @@ -126,9 +126,10 @@ export interface SettingSpec { /** * False for a setting that decides where calls or transcripts are written (`recordings.root`, * `export.dir`): over the API only the user on this computer sets it, with the app's own token - * on the desktop app's loopback listener (`akou config set`) or in the desktop window. An `ak_` - * key, the network listener, the window's page in a browser and server mode are refused, so a - * key cannot send every later call to a folder or share it chose. + * on the desktop app's loopback listener (`akou config set`) or in the window (the desktop + * window, or its page in a browser on the app's loopback page server). An `ak_` key, the network + * listener and server mode are refused, so a key cannot send every later call to a folder or + * share it chose. */ keyWritable?: boolean; /** A secret (an API key): never shown by `GET /config`, `config show` or `status`. */ @@ -1483,7 +1484,8 @@ export function loadConfig( * Validates a `PATCH /config` body: `{key: value}` to set, `{key: null}` to go back to the default. * Returns the new file contents, or every error at once. Settings that name a program are refused; * a `windowWritable` one is taken only `inProcess`, from the desktop window; a `keyWritable: false` - * one only in process or from the `local` user (the app's own token on the desktop app's loopback). + * one only in process or from the `local` user (the app's own token on the desktop app's loopback, + * or the window's page in a browser on the app's loopback page server). */ export function patchConfig( current: Partial>,