proto: land F2 — download.provideAuth (1.2.0)
The last contract gap blocking an M1 definition-of-done item: CORE's "401
handled" has no return path without it, and B2a's sibling F2 was accepted in
proto-answers-m1.md but never actually landed.
download.provideAuth {taskId, username, password, save?} -> {ok}, exactly as
proposed there. Privileged and Unix-socket-only: a credential-bearing method
must never be reachable from the browser, which is the other half of the
promise event.auth.required's own description already makes ("never back
through this event, never into a log"). It answers the challenge; it does not
itself resume the task -- the daemon retries with the credential attached and
the ordinary event.task.state reports the task leaving retry_wait, the same
as any other state change.
save only tells the daemon whether to persist the credential in the Secret
Service for next time, or use it for this attempt alone -- it never touches
SQLite or a log either way, in keeping with CLAUDE.md's secrets rule.
Three fixtures: the success path, -32010 for a task that no longer exists
(credentials submitted for it are simply discarded), and -32003 confirming
the extension has no path to this method under any transport.
mockd gets a real handler rather than falling through to the generic fixture
responder: it validates the taskId exists (so the -32010 fixture is
replayable) and actually transitions the task out of retry_wait.
Minor bump, 1.1.0 -> 1.2.0: additive method, no existing type touched.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
Claude Sonnet 5
+11
-10
@@ -3,14 +3,14 @@
|
||||
**This directory is the interface between every lane.** Owner: agent **PROTO**.
|
||||
Nobody else commits here. Everybody else *generates from* here.
|
||||
|
||||
> ## Status: **v1.0.0 — FROZEN** (2026-09-09)
|
||||
> ## Status: **v1.2.0** (frozen at v1.0.0 on 2026-09-09; minor bumps since)
|
||||
>
|
||||
> **v1.0.0** froze 38 methods, 9 events, 26 named types. **v1.1.0** (current) is a minor
|
||||
> bump on top of it: `bufferBytes` bounds widened to 64 KiB - 16 MiB across all four
|
||||
> locations, two new settings keys (`connection.maxTotalBufferBytes`,
|
||||
> `connection.maxActiveSegments`), and `TaskDetail.effectiveBufferBytes` — see
|
||||
> `docs/adr/0012-buffer-and-segment-budget.md`. See also `docs/adr/0005-...` for the
|
||||
> versioning rule and `docs/adr/0010-...` for the failure taxonomy and segment ranges.
|
||||
> **v1.0.0** froze 38 methods, 9 events, 26 named types. **v1.1.0** widened `bufferBytes`
|
||||
> bounds, added `connection.maxTotalBufferBytes` / `connection.maxActiveSegments`, and
|
||||
> `TaskDetail.effectiveBufferBytes` (`docs/adr/0012-...`). **v1.2.0** (current) adds
|
||||
> `download.provideAuth` — F2's credential return path for a paused 401/407, UDS-only
|
||||
> and privileged. See also `docs/adr/0005-...` for the versioning rule and
|
||||
> `docs/adr/0010-...` for the failure taxonomy and segment ranges.
|
||||
>
|
||||
> Lane requests are answered in writing: `contracts/proto-answers-m1.md` responds to
|
||||
> `core/docs/proto-requests-m1.md` point by point.
|
||||
@@ -30,7 +30,7 @@ Nobody else commits here. Everybody else *generates from* here.
|
||||
|
||||
```
|
||||
contracts/
|
||||
├── VERSION # protocol semver — frozen at 1.0.0
|
||||
├── VERSION # protocol semver — v1.2.0, minor-bumped from the v1.0.0 freeze
|
||||
├── openrpc.json # human-readable API doc (generated from schema/)
|
||||
├── schema/
|
||||
│ ├── envelope.schema.json # JSON-RPC 2.0 envelope + our error codes
|
||||
@@ -76,7 +76,7 @@ on rather than as prose a reader has to honour:
|
||||
| `x-errors` | the error codes this method is documented to return |
|
||||
| `x-wsRestrictions` | extra limits when the call arrives from the extension |
|
||||
|
||||
19 of the 38 methods are privileged: everything that reconfigures the daemon, destroys user
|
||||
20 of the 39 methods are privileged: everything that reconfigures the daemon, destroys user
|
||||
data, or names an arbitrary destination path. The extension may *request* a download; it
|
||||
may not choose where the bytes land.
|
||||
|
||||
@@ -93,7 +93,7 @@ All four carry **the same JSON-RPC 2.0 payloads**. The framing differences stop
|
||||
transport layer; no method behaves differently depending on how it arrived — except that
|
||||
methods marked `"privileged": true` in the schema are refused over the WebSocket transport.
|
||||
|
||||
## Method surface (v1.0.0 target — expand only via PR)
|
||||
## Method surface (v1.2.0 — expand only via PR)
|
||||
|
||||
### Session
|
||||
| Method | Params → Result |
|
||||
@@ -114,6 +114,7 @@ methods marked `"privileged": true` in the schema are refused over the WebSocket
|
||||
| `download.remove` | `{taskIds[], deleteFile:bool}` → `{removed[]}` |
|
||||
| `download.update` | `{taskId, patch:{filename?, saveDir?, categoryId?, queueId?, description?, segments?, bufferBytes?}}` → `TaskSummary` |
|
||||
| `download.refreshUrl` | `{taskId, url, headers?}` → `{ok}` *(IDM's "Refresh Download Address")* |
|
||||
| `download.provideAuth` | `{taskId, username, password, save?}` → `{ok}` — answers `event.auth.required`. UDS only; privileged. Credentials go to the Secret Service, never SQLite, never logs |
|
||||
|
||||
### Organisation
|
||||
`category.list` · `category.upsert` · `category.remove` · `queue.list` · `queue.upsert` ·
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
1.1.0
|
||||
1.2.0
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"name": "download.provideAuth \u2014 answer a 401 challenge and remember it",
|
||||
"description": "The task was sitting in retry_wait after event.auth.required. This does not restart the transfer itself: the daemon retries with the credential attached and the task's state.transition to connecting/downloading happens on its own, reported the normal way through event.task.state.",
|
||||
"transport": "uds",
|
||||
"request": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": 80,
|
||||
"method": "download.provideAuth",
|
||||
"params": {
|
||||
"taskId": "$taskId",
|
||||
"username": "svc-releases",
|
||||
"password": "hunter2-not-a-real-password",
|
||||
"save": true
|
||||
}
|
||||
},
|
||||
"response": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": 80,
|
||||
"result": {
|
||||
"ok": true
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"the password never appears in a log line, ever, on either side of this call",
|
||||
"save true stores the credential in the Secret Service keyed by host and realm, not in SQLite",
|
||||
"the task itself is not touched synchronously by this call \u2014 it moves out of retry_wait when the daemon's own retry succeeds, reported via event.task.state",
|
||||
"this method is refused with -32003 over the WebSocket transport"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"name": "download.provideAuth \u2014 the task no longer exists",
|
||||
"description": "The ordinary stale-client case: the user typed credentials into a dialog for a task that was removed in the meantime.",
|
||||
"transport": "uds",
|
||||
"request": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": 81,
|
||||
"method": "download.provideAuth",
|
||||
"params": {
|
||||
"taskId": "00000000-0000-4000-8000-000000000000",
|
||||
"username": "x",
|
||||
"password": "y"
|
||||
}
|
||||
},
|
||||
"response": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": 81,
|
||||
"error": {
|
||||
"code": -32010,
|
||||
"message": "no such task",
|
||||
"data": {
|
||||
"taskId": "00000000-0000-4000-8000-000000000000"
|
||||
}
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"credentials submitted for a task that no longer exists are discarded, never persisted anywhere"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"name": "download.provideAuth \u2014 refused over the WebSocket transport",
|
||||
"description": "The other half of event.auth.required's own promise: a credential-bearing method must never be reachable from the browser.",
|
||||
"transport": "ws",
|
||||
"request": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": 82,
|
||||
"method": "download.provideAuth",
|
||||
"params": {
|
||||
"taskId": "$taskId",
|
||||
"username": "x",
|
||||
"password": "y"
|
||||
}
|
||||
},
|
||||
"response": {
|
||||
"jsonrpc": "2.0",
|
||||
"id": 82,
|
||||
"error": {
|
||||
"code": -32003,
|
||||
"message": "method is not permitted on this transport"
|
||||
}
|
||||
},
|
||||
"assertions": [
|
||||
"the extension has no path to this method under any circumstance"
|
||||
]
|
||||
}
|
||||
+74
-1
@@ -2,7 +2,7 @@
|
||||
"openrpc": "1.2.6",
|
||||
"info": {
|
||||
"title": "Velox Download Manager",
|
||||
"version": "1.1.0",
|
||||
"version": "1.2.0",
|
||||
"description": "The wire contract between veloxd and every client: the Qt GUI, the CLI, the native-messaging host and the Firefox extension. One JSON-RPC 2.0 payload set over four framings; only the framing differs.\n\nGENERATED from contracts/schema/ by contracts/codegen/gen_openrpc.py. Do not edit by hand.",
|
||||
"license": {
|
||||
"name": "See repository LICENSE"
|
||||
@@ -1031,6 +1031,79 @@
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "download.provideAuth",
|
||||
"summary": "Answer an event.",
|
||||
"description": "Answer an event.auth.required challenge. The task sits in retry_wait until this arrives; on success the daemon retries with the credentials attached and the task resumes on its own \u2014 this method does not itself start the transfer. Privileged and Unix-socket-only: a credential-bearing method must never be reachable from the browser, which is exactly the boundary event.auth.required's own description draws ('never back through this event, never into a log') \u2014 this is the other half of that promise. Credentials are handed to the Secret Service, never to SQLite and never logged; save only tells the daemon whether to persist them there for next time, or use them for this attempt alone.",
|
||||
"paramStructure": "by-name",
|
||||
"params": [
|
||||
{
|
||||
"name": "taskId",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"format": "uuid"
|
||||
},
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "username",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"maxLength": 256
|
||||
},
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "password",
|
||||
"schema": {
|
||||
"type": "string",
|
||||
"maxLength": 1024
|
||||
},
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "save",
|
||||
"schema": {
|
||||
"type": [
|
||||
"boolean",
|
||||
"null"
|
||||
],
|
||||
"description": "true persists the credential in the Secret Service, keyed by host and realm, for future downloads from the same site. false or null uses it for this task's retry only. Never affects SQLite or the daemon's logs either way."
|
||||
},
|
||||
"description": "true persists the credential in the Secret Service, keyed by host and realm, for future downloads from the same site. false or null uses it for this task's retry only. Never affects SQLite or the daemon's logs either way."
|
||||
}
|
||||
],
|
||||
"result": {
|
||||
"name": "download.provideAuthResult",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"ok"
|
||||
],
|
||||
"properties": {
|
||||
"ok": {
|
||||
"type": "boolean"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"x-privileged": true,
|
||||
"x-transports": [
|
||||
"uds"
|
||||
],
|
||||
"x-deadlineMs": 5000,
|
||||
"errors": [
|
||||
{
|
||||
"code": -32003,
|
||||
"message": "Method is privileged and was called over a transport that may not use it."
|
||||
},
|
||||
{
|
||||
"code": -32010,
|
||||
"message": "No task with that id."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "download.refreshUrl",
|
||||
"summary": "IDM's 'Refresh Download Address'.",
|
||||
|
||||
@@ -100,7 +100,7 @@ Agreed with your ranking: these are minor under rule 4 and land as small PRs to
|
||||
| # | Item | Verdict | Shape |
|
||||
|---|---|---|---|
|
||||
| **B2a** | readable effective buffer size | **landed in 1.1.0** | `TaskDetail.effectiveBufferBytes` (placed on `TaskDetail`, not `TaskSummary` — `bufferBytes` itself was already `TaskDetail`-only, so the pair stays together). See `docs/adr/0012-buffer-and-segment-budget.md`, which also lands B4's bounds and the two new settings keys in the same PR. |
|
||||
| **F2** | credential return path for 401/407 | **accepted as proposed** | `download.provideAuth {taskId, username, password, save?}` → `{ok}`. Unix socket only, privileged: a credential-bearing method must never be reachable from the browser. Secrets go to the Secret Service; `save` only tells DAEMON whether to persist. |
|
||||
| **F2** | credential return path for 401/407 | **landed in 1.2.0** | `download.provideAuth {taskId, username, password, save?}` → `{ok}`, exactly as proposed: Unix socket only, privileged. It answers the challenge; it does not itself resume the task — the daemon retries with the credential attached and the usual `event.task.state` reports the task leaving `retry_wait`. |
|
||||
| **F1** | "needs user decision" carrier | **the simple option** | `state: paused` + `event.notify` is the intended carrier for M1: CORE reports `server_file_changed`, DAEMON pauses and notifies, GUI offers restart. A dedicated `event.task.decision` + `download.decide` is a real design with a state machine attached, and it should not be invented in a hurry — raise it again in M3 if the notify path proves too thin. A string comparison on `error.code` covers the engine side either way, which is now a `TaskErrorCode` comparison rather than a magic number. |
|
||||
| **F3** | `checksum` string format | **already frozen, differently** | `download.add {checksum}` is **not** a string. It is a `Checksum` object: `{algorithm: "md5"\|"sha1"\|"sha256"\|"sha512", value: "<hex>"}`, with `value` patterned `^[0-9a-fA-F]{32,128}$`. Parse your `"<algo>:<hex>"` form at the CLI or GUI edge, not on the wire. Note `sha512` is accepted by the contract even though the appendix lists MD5/SHA-256 — reject it in the engine if you do not implement it, rather than the contract forbidding it. |
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://velox.dev/schema/methods/download.provideAuth.schema.json",
|
||||
"title": "download.provideAuth",
|
||||
"description": "Answer an event.auth.required challenge. The task sits in retry_wait until this arrives; on success the daemon retries with the credentials attached and the task resumes on its own — this method does not itself start the transfer. Privileged and Unix-socket-only: a credential-bearing method must never be reachable from the browser, which is exactly the boundary event.auth.required's own description draws ('never back through this event, never into a log') — this is the other half of that promise. Credentials are handed to the Secret Service, never to SQLite and never logged; save only tells the daemon whether to persist them there for next time, or use them for this attempt alone.",
|
||||
"x-privileged": true,
|
||||
"x-transports": ["uds"],
|
||||
"x-deadlineMs": 5000,
|
||||
"x-errors": [-32003, -32010],
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"params": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["taskId", "username", "password"],
|
||||
"properties": {
|
||||
"taskId": { "type": "string", "format": "uuid" },
|
||||
"username": { "type": "string", "maxLength": 256 },
|
||||
"password": { "type": "string", "maxLength": 1024 },
|
||||
"save": {
|
||||
"type": ["boolean", "null"],
|
||||
"description": "true persists the credential in the Secret Service, keyed by host and realm, for future downloads from the same site. false or null uses it for this task's retry only. Never affects SQLite or the daemon's logs either way."
|
||||
}
|
||||
}
|
||||
},
|
||||
"result": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["ok"],
|
||||
"properties": {
|
||||
"ok": { "type": "boolean" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_cpp.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_cpp.py
|
||||
@@ -4369,6 +4369,78 @@ template <> Result<DownloadProbeResult> parse<DownloadProbeResult>(const nlohman
|
||||
return out;
|
||||
}
|
||||
|
||||
void to_json(nlohmann::json& j, const DownloadProvideAuthParams& v) {
|
||||
j = nlohmann::json::object();
|
||||
j["taskId"] = v.taskId;
|
||||
j["username"] = v.username;
|
||||
j["password"] = v.password;
|
||||
if (v.save.has_value()) j["save"] = *v.save;
|
||||
}
|
||||
|
||||
template <> Result<DownloadProvideAuthParams> parse<DownloadProvideAuthParams>(const nlohmann::json& j, std::string_view path) {
|
||||
if (!j.is_object()) return std::unexpected(ParseError{std::string(path), "expected an object"});
|
||||
DownloadProvideAuthParams out;
|
||||
{
|
||||
const std::string fp = join(path, "taskId");
|
||||
const auto it = j.find("taskId");
|
||||
if (it == j.end() || it->is_null())
|
||||
return std::unexpected(ParseError{fp, "required field is missing"});
|
||||
if (!(*it).is_string()) return std::unexpected(ParseError{std::string(fp), "expected a string"});
|
||||
auto val = (*it).get<std::string>();
|
||||
out.taskId = std::move(val);
|
||||
}
|
||||
{
|
||||
const std::string fp = join(path, "username");
|
||||
const auto it = j.find("username");
|
||||
if (it == j.end() || it->is_null())
|
||||
return std::unexpected(ParseError{fp, "required field is missing"});
|
||||
if (!(*it).is_string()) return std::unexpected(ParseError{std::string(fp), "expected a string"});
|
||||
auto val = (*it).get<std::string>();
|
||||
if (val.size() > 256u) return std::unexpected(ParseError{std::string(fp), "value is longer than 256 characters"});
|
||||
out.username = std::move(val);
|
||||
}
|
||||
{
|
||||
const std::string fp = join(path, "password");
|
||||
const auto it = j.find("password");
|
||||
if (it == j.end() || it->is_null())
|
||||
return std::unexpected(ParseError{fp, "required field is missing"});
|
||||
if (!(*it).is_string()) return std::unexpected(ParseError{std::string(fp), "expected a string"});
|
||||
auto val = (*it).get<std::string>();
|
||||
if (val.size() > 1024u) return std::unexpected(ParseError{std::string(fp), "value is longer than 1024 characters"});
|
||||
out.password = std::move(val);
|
||||
}
|
||||
{
|
||||
const std::string fp = join(path, "save");
|
||||
const auto it = j.find("save");
|
||||
if (it != j.end() && !it->is_null()) {
|
||||
if (!(*it).is_boolean()) return std::unexpected(ParseError{std::string(fp), "expected a boolean"});
|
||||
auto val = (*it).get<bool>();
|
||||
out.save = std::move(val);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
void to_json(nlohmann::json& j, const DownloadProvideAuthResult& v) {
|
||||
j = nlohmann::json::object();
|
||||
j["ok"] = v.ok;
|
||||
}
|
||||
|
||||
template <> Result<DownloadProvideAuthResult> parse<DownloadProvideAuthResult>(const nlohmann::json& j, std::string_view path) {
|
||||
if (!j.is_object()) return std::unexpected(ParseError{std::string(path), "expected an object"});
|
||||
DownloadProvideAuthResult out;
|
||||
{
|
||||
const std::string fp = join(path, "ok");
|
||||
const auto it = j.find("ok");
|
||||
if (it == j.end() || it->is_null())
|
||||
return std::unexpected(ParseError{fp, "required field is missing"});
|
||||
if (!(*it).is_boolean()) return std::unexpected(ParseError{std::string(fp), "expected a boolean"});
|
||||
auto val = (*it).get<bool>();
|
||||
out.ok = std::move(val);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
void to_json(nlohmann::json& j, const DownloadRefreshUrlParams& v) {
|
||||
j = nlohmann::json::object();
|
||||
j["taskId"] = v.taskId;
|
||||
@@ -6895,6 +6967,7 @@ std::string_view to_string(Method m) noexcept {
|
||||
case Method::DownloadList: return "download.list";
|
||||
case Method::DownloadPause: return "download.pause";
|
||||
case Method::DownloadProbe: return "download.probe";
|
||||
case Method::DownloadProvideAuth: return "download.provideAuth";
|
||||
case Method::DownloadRefreshUrl: return "download.refreshUrl";
|
||||
case Method::DownloadRemove: return "download.remove";
|
||||
case Method::DownloadResume: return "download.resume";
|
||||
@@ -6938,6 +7011,7 @@ std::optional<Method> method_from_string(std::string_view s) noexcept {
|
||||
if (s == "download.list") return Method::DownloadList;
|
||||
if (s == "download.pause") return Method::DownloadPause;
|
||||
if (s == "download.probe") return Method::DownloadProbe;
|
||||
if (s == "download.provideAuth") return Method::DownloadProvideAuth;
|
||||
if (s == "download.refreshUrl") return Method::DownloadRefreshUrl;
|
||||
if (s == "download.remove") return Method::DownloadRemove;
|
||||
if (s == "download.resume") return Method::DownloadResume;
|
||||
@@ -6981,6 +7055,7 @@ bool is_privileged(Method m) noexcept {
|
||||
case Method::DownloadList: return false;
|
||||
case Method::DownloadPause: return false;
|
||||
case Method::DownloadProbe: return false;
|
||||
case Method::DownloadProvideAuth: return true;
|
||||
case Method::DownloadRefreshUrl: return false;
|
||||
case Method::DownloadRemove: return true;
|
||||
case Method::DownloadResume: return false;
|
||||
@@ -7025,6 +7100,7 @@ bool is_allowed_on(Method m, Transport t) noexcept {
|
||||
case Method::DownloadList: return t == Transport::Uds ? true : true;
|
||||
case Method::DownloadPause: return t == Transport::Uds ? true : true;
|
||||
case Method::DownloadProbe: return t == Transport::Uds ? true : true;
|
||||
case Method::DownloadProvideAuth: return t == Transport::Uds ? true : false;
|
||||
case Method::DownloadRefreshUrl: return t == Transport::Uds ? true : true;
|
||||
case Method::DownloadRemove: return t == Transport::Uds ? true : false;
|
||||
case Method::DownloadResume: return t == Transport::Uds ? true : true;
|
||||
@@ -7069,6 +7145,7 @@ std::int32_t deadline_ms(Method m) noexcept {
|
||||
case Method::DownloadList: return 5000;
|
||||
case Method::DownloadPause: return 5000;
|
||||
case Method::DownloadProbe: return 30000;
|
||||
case Method::DownloadProvideAuth: return 5000;
|
||||
case Method::DownloadRefreshUrl: return 30000;
|
||||
case Method::DownloadRemove: return 10000;
|
||||
case Method::DownloadResume: return 5000;
|
||||
@@ -7305,6 +7382,18 @@ nlohmann::json dispatch(Dispatcher& handler, Transport transport, const nlohmann
|
||||
nlohmann::json out = *r;
|
||||
return make_result(id, std::move(out));
|
||||
}
|
||||
case Method::DownloadProvideAuth: {
|
||||
auto p = parse<DownloadProvideAuthParams>(params, "params");
|
||||
if (!p)
|
||||
return make_error(id, ErrorCode::InvalidParams, p.error().message,
|
||||
nlohmann::json{{"path", p.error().path}});
|
||||
auto r = handler.on_download_provideAuth(*p);
|
||||
if (!r)
|
||||
return make_error(id, ErrorCode::InternalError, r.error().message,
|
||||
nlohmann::json{{"path", r.error().path}});
|
||||
nlohmann::json out = *r;
|
||||
return make_result(id, std::move(out));
|
||||
}
|
||||
case Method::DownloadRefreshUrl: {
|
||||
auto p = parse<DownloadRefreshUrlParams>(params, "params");
|
||||
if (!p)
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_cpp.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_cpp.py
|
||||
@@ -27,7 +27,7 @@
|
||||
// docs/adr/0009-generated-protocol-library.md.
|
||||
namespace velox::proto {
|
||||
|
||||
inline constexpr std::string_view kProtocolVersion = "1.1.0";
|
||||
inline constexpr std::string_view kProtocolVersion = "1.2.0";
|
||||
|
||||
/// Why a payload could not be turned into a typed value. `path` is a JSON Pointer
|
||||
/// into the offending document, so a conformance failure names the exact field.
|
||||
@@ -1004,6 +1004,20 @@ struct DownloadProbeResult {
|
||||
std::optional<bool> requiresAuth{};
|
||||
};
|
||||
|
||||
struct DownloadProvideAuthParams {
|
||||
std::string taskId{};
|
||||
std::string username{};
|
||||
std::string password{};
|
||||
/// true persists the credential in the Secret Service, keyed by host and realm, for future
|
||||
/// downloads from the same site. false or null uses it for this task's retry only. Never
|
||||
/// affects SQLite or the daemon's logs either way.
|
||||
std::optional<bool> save{};
|
||||
};
|
||||
|
||||
struct DownloadProvideAuthResult {
|
||||
bool ok{};
|
||||
};
|
||||
|
||||
struct DownloadRefreshUrlParams {
|
||||
std::string taskId{};
|
||||
std::string url{};
|
||||
@@ -1454,6 +1468,8 @@ void to_json(nlohmann::json& j, const DownloadListResult& v);
|
||||
void to_json(nlohmann::json& j, const DownloadPauseParams& v);
|
||||
void to_json(nlohmann::json& j, const DownloadProbeParams& v);
|
||||
void to_json(nlohmann::json& j, const DownloadProbeResult& v);
|
||||
void to_json(nlohmann::json& j, const DownloadProvideAuthParams& v);
|
||||
void to_json(nlohmann::json& j, const DownloadProvideAuthResult& v);
|
||||
void to_json(nlohmann::json& j, const DownloadRefreshUrlParams& v);
|
||||
void to_json(nlohmann::json& j, const DownloadRefreshUrlResult& v);
|
||||
void to_json(nlohmann::json& j, const DownloadRemoveParams& v);
|
||||
@@ -1599,6 +1615,8 @@ template <> Result<DownloadListResult> parse<DownloadListResult>(const nlohmann:
|
||||
template <> Result<DownloadPauseParams> parse<DownloadPauseParams>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadProbeParams> parse<DownloadProbeParams>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadProbeResult> parse<DownloadProbeResult>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadProvideAuthParams> parse<DownloadProvideAuthParams>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadProvideAuthResult> parse<DownloadProvideAuthResult>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadRefreshUrlParams> parse<DownloadRefreshUrlParams>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadRefreshUrlResult> parse<DownloadRefreshUrlResult>(const nlohmann::json& j, std::string_view path);
|
||||
template <> Result<DownloadRemoveParams> parse<DownloadRemoveParams>(const nlohmann::json& j, std::string_view path);
|
||||
@@ -1686,6 +1704,7 @@ enum class Method {
|
||||
DownloadList, // download.list
|
||||
DownloadPause, // download.pause
|
||||
DownloadProbe, // download.probe
|
||||
DownloadProvideAuth, // download.provideAuth
|
||||
DownloadRefreshUrl, // download.refreshUrl
|
||||
DownloadRemove, // download.remove
|
||||
DownloadResume, // download.resume
|
||||
@@ -1714,7 +1733,7 @@ enum class Method {
|
||||
SettingsSet, // settings.set
|
||||
};
|
||||
|
||||
inline constexpr std::size_t kMethodCount = 38;
|
||||
inline constexpr std::size_t kMethodCount = 39;
|
||||
|
||||
std::string_view to_string(Method m) noexcept;
|
||||
std::optional<Method> method_from_string(std::string_view s) noexcept;
|
||||
@@ -1819,6 +1838,16 @@ public:
|
||||
/// lands.
|
||||
virtual Result<DownloadProbeResult> on_download_probe(const DownloadProbeParams& params) = 0;
|
||||
|
||||
/// Answer an event.auth.required challenge. The task sits in retry_wait until this arrives; on
|
||||
/// success the daemon retries with the credentials attached and the task resumes on its own —
|
||||
/// this method does not itself start the transfer. Privileged and Unix-socket-only: a
|
||||
/// credential-bearing method must never be reachable from the browser, which is exactly the
|
||||
/// boundary event.auth.required's own description draws ('never back through this event, never
|
||||
/// into a log') — this is the other half of that promise. Credentials are handed to the Secret
|
||||
/// Service, never to SQLite and never logged; save only tells the daemon whether to persist
|
||||
/// them there for next time, or use them for this attempt alone.
|
||||
virtual Result<DownloadProvideAuthResult> on_download_provideAuth(const DownloadProvideAuthParams& params) = 0;
|
||||
|
||||
/// IDM's 'Refresh Download Address'. Point an existing task at a freshly-issued URL when a
|
||||
/// signed link has expired, keeping every byte already on disk. The daemon re-probes and
|
||||
/// compares size and validator: if they still match, the transfer resumes from where it
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_ts.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_ts.py
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_ts.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_ts.py
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_ts.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_ts.py
|
||||
@@ -33,6 +33,8 @@ import type {
|
||||
DownloadPauseParams,
|
||||
DownloadProbeParams,
|
||||
DownloadProbeResult,
|
||||
DownloadProvideAuthParams,
|
||||
DownloadProvideAuthResult,
|
||||
DownloadRefreshUrlParams,
|
||||
DownloadRefreshUrlResult,
|
||||
DownloadRemoveParams,
|
||||
@@ -159,6 +161,17 @@ export interface MethodMap {
|
||||
* when this lands.
|
||||
*/
|
||||
"download.probe": { params: DownloadProbeParams; result: DownloadProbeResult };
|
||||
/**
|
||||
* Answer an event.auth.required challenge. The task sits in retry_wait until this arrives;
|
||||
* on success the daemon retries with the credentials attached and the task resumes on its
|
||||
* own — this method does not itself start the transfer. Privileged and Unix-socket-only: a
|
||||
* credential-bearing method must never be reachable from the browser, which is exactly the
|
||||
* boundary event.auth.required's own description draws ('never back through this event,
|
||||
* never into a log') — this is the other half of that promise. Credentials are handed to
|
||||
* the Secret Service, never to SQLite and never logged; save only tells the daemon whether
|
||||
* to persist them there for next time, or use them for this attempt alone.
|
||||
*/
|
||||
"download.provideAuth": { params: DownloadProvideAuthParams; result: DownloadProvideAuthResult };
|
||||
/**
|
||||
* IDM's 'Refresh Download Address'. Point an existing task at a freshly-issued URL when a
|
||||
* signed link has expired, keeping every byte already on disk. The daemon re-probes and
|
||||
@@ -346,6 +359,7 @@ export const METHODS: { readonly [M in MethodName]: MethodMeta } = {
|
||||
"download.list": { privileged: false, transports: ['uds', 'ws'], deadlineMs: 5000, errors: [] },
|
||||
"download.pause": { privileged: false, transports: ['uds', 'ws'], deadlineMs: 5000, errors: [-32010] },
|
||||
"download.probe": { privileged: false, transports: ['uds', 'ws'], deadlineMs: 30000, errors: [-32013] },
|
||||
"download.provideAuth": { privileged: true, transports: ['uds'], deadlineMs: 5000, errors: [-32003, -32010] },
|
||||
"download.refreshUrl": { privileged: false, transports: ['uds', 'ws'], deadlineMs: 30000, errors: [-32010, -32013] },
|
||||
"download.remove": { privileged: true, transports: ['uds'], deadlineMs: 10000, errors: [-32003, -32010] },
|
||||
"download.resume": { privileged: false, transports: ['uds', 'ws'], deadlineMs: 5000, errors: [-32010] },
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_ts.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_ts.py
|
||||
@@ -11,7 +11,7 @@
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
export const PROTOCOL_VERSION = "1.1.0";
|
||||
export const PROTOCOL_VERSION = "1.2.0";
|
||||
|
||||
/**
|
||||
* Every error code the daemon may return. Adding one is a minor bump; changing the meaning
|
||||
@@ -978,6 +978,22 @@ export interface DownloadProbeResult {
|
||||
requiresAuth?: boolean;
|
||||
}
|
||||
|
||||
export interface DownloadProvideAuthParams {
|
||||
taskId: string;
|
||||
username: string;
|
||||
password: string;
|
||||
/**
|
||||
* true persists the credential in the Secret Service, keyed by host and realm, for future
|
||||
* downloads from the same site. false or null uses it for this task's retry only. Never
|
||||
* affects SQLite or the daemon's logs either way.
|
||||
*/
|
||||
save?: boolean | null;
|
||||
}
|
||||
|
||||
export interface DownloadProvideAuthResult {
|
||||
ok: boolean;
|
||||
}
|
||||
|
||||
export interface DownloadRefreshUrlParams {
|
||||
taskId: string;
|
||||
url: string;
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_ts.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_ts.py
|
||||
@@ -46,6 +46,8 @@ import type {
|
||||
DownloadPauseParams,
|
||||
DownloadProbeParams,
|
||||
DownloadProbeResult,
|
||||
DownloadProvideAuthParams,
|
||||
DownloadProvideAuthResult,
|
||||
DownloadRefreshUrlParams,
|
||||
DownloadRefreshUrlResult,
|
||||
DownloadRemoveParams,
|
||||
@@ -1233,6 +1235,32 @@ export function validateDownloadProbeResult(v: unknown, path = ''): Validated<Do
|
||||
return { ok: true, value: out as unknown as DownloadProbeResult };
|
||||
}
|
||||
|
||||
/** Validate an untrusted value as DownloadProvideAuthParams. */
|
||||
export function validateDownloadProvideAuthParams(v: unknown, path = ''): Validated<DownloadProvideAuthParams> {
|
||||
if (!isPlainObject(v)) return fail(path, 'expected an object');
|
||||
const out: Record<string, unknown> = {};
|
||||
let r: Validated<null>;
|
||||
r = req(v, "taskId", path, vString, out);
|
||||
if (!r.ok) return r;
|
||||
r = req(v, "username", path, vLimited(vString, { maxLength: 256 }), out);
|
||||
if (!r.ok) return r;
|
||||
r = req(v, "password", path, vLimited(vString, { maxLength: 1024 }), out);
|
||||
if (!r.ok) return r;
|
||||
r = opt(v, "save", path, vBoolean, out);
|
||||
if (!r.ok) return r;
|
||||
return { ok: true, value: out as unknown as DownloadProvideAuthParams };
|
||||
}
|
||||
|
||||
/** Validate an untrusted value as DownloadProvideAuthResult. */
|
||||
export function validateDownloadProvideAuthResult(v: unknown, path = ''): Validated<DownloadProvideAuthResult> {
|
||||
if (!isPlainObject(v)) return fail(path, 'expected an object');
|
||||
const out: Record<string, unknown> = {};
|
||||
let r: Validated<null>;
|
||||
r = req(v, "ok", path, vBoolean, out);
|
||||
if (!r.ok) return r;
|
||||
return { ok: true, value: out as unknown as DownloadProvideAuthResult };
|
||||
}
|
||||
|
||||
/** Validate an untrusted value as DownloadRefreshUrlParams. */
|
||||
export function validateDownloadRefreshUrlParams(v: unknown, path = ''): Validated<DownloadRefreshUrlParams> {
|
||||
if (!isPlainObject(v)) return fail(path, 'expected an object');
|
||||
@@ -2058,6 +2086,7 @@ const PARAMS_VALIDATORS: { [M in MethodName]: Validator<MethodMap[M]['params']>
|
||||
"download.list": validateDownloadListParams,
|
||||
"download.pause": validateDownloadPauseParams,
|
||||
"download.probe": validateDownloadProbeParams,
|
||||
"download.provideAuth": validateDownloadProvideAuthParams,
|
||||
"download.refreshUrl": validateDownloadRefreshUrlParams,
|
||||
"download.remove": validateDownloadRemoveParams,
|
||||
"download.resume": validateDownloadResumeParams,
|
||||
@@ -2099,6 +2128,7 @@ const RESULT_VALIDATORS: { [M in MethodName]: Validator<MethodMap[M]['result']>
|
||||
"download.list": validateDownloadListResult,
|
||||
"download.pause": validateBulkTaskResult,
|
||||
"download.probe": validateDownloadProbeResult,
|
||||
"download.provideAuth": validateDownloadProvideAuthResult,
|
||||
"download.refreshUrl": validateDownloadRefreshUrlResult,
|
||||
"download.remove": validateDownloadRemoveResult,
|
||||
"download.resume": validateBulkTaskResult,
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
//
|
||||
// Source: contracts/schema/**
|
||||
// Generator: contracts/codegen/gen_cpp.py
|
||||
// Contract: v1.1.0
|
||||
// Contract: v1.2.0
|
||||
//
|
||||
// Hand-editing this file is a merge blocker. Fix the schema and regenerate:
|
||||
// python3 contracts/codegen/gen_cpp.py
|
||||
@@ -87,6 +87,11 @@ public:
|
||||
return golden<proto::DownloadProbeResult>("download.probe");
|
||||
}
|
||||
|
||||
proto::Result<proto::DownloadProvideAuthResult> on_download_provideAuth(const proto::DownloadProvideAuthParams& params) override {
|
||||
(void)params;
|
||||
return golden<proto::DownloadProvideAuthResult>("download.provideAuth");
|
||||
}
|
||||
|
||||
proto::Result<proto::DownloadRefreshUrlResult> on_download_refreshUrl(const proto::DownloadRefreshUrlParams& params) override {
|
||||
(void)params;
|
||||
return golden<proto::DownloadRefreshUrlResult>("download.refreshUrl");
|
||||
|
||||
@@ -218,6 +218,15 @@ export class Dispatcher {
|
||||
return { updated, failed };
|
||||
}
|
||||
|
||||
case 'download.provideAuth': {
|
||||
const task = state.tasks.get(String(params['taskId']));
|
||||
if (!task) return notFound(String(params['taskId']));
|
||||
// A real transition, not just a canned {ok:true}: the task was parked in
|
||||
// retry_wait by an auth challenge, and answering it is what lets it resume.
|
||||
state.transition(task.taskId, 'connecting');
|
||||
return { ok: true };
|
||||
}
|
||||
|
||||
case 'download.remove': {
|
||||
const removed: string[] = [];
|
||||
const failed: Json[] = [];
|
||||
|
||||
Reference in New Issue
Block a user