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" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user