Skip to content

Commit 0cfed55

Browse files
Require consent before applying Requesty deep links (#2408)
* fix(auth): require consent before applying Requesty deep links <!-- coderabbit-ai-generated:v1 --> * fix(requesty): redact credentials in URL logs and localize consent dialog * docs(tla): add Requesty consent and URL redaction specs * fix(requesty): stop logging deep link URLs and show the real host * test(requesty): tighten consent tests and add dialog host spec --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Elliott de Launay <edelauna@gmail.com>
1 parent d112b7f commit 0cfed55

31 files changed

Lines changed: 528 additions & 39 deletions

‎docs/architecture/tla/AGENTS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# AGENTS.md (TLA+ specs)
2+
3+
This file applies to every file in this folder.
4+
It tells an agent how to write and check a TLA+ spec for a change in this repo.
5+
6+
## Policy
7+
8+
1. This policy is a trial. A maintainer decides when it ends. While it runs, write a spec for each change you implement.
9+
2. The goal is a knowledge base of how the repo works. Cost is not a reason to skip a spec.
10+
3. Record the cost and the findings in the spec header. A maintainer uses them to cut scope later.
11+
4. This policy is a choice. It is not a claim that specs find more bugs than tests or reviews.
12+
13+
## Stance
14+
15+
1. Before you write a spec, write down what you expect it to find. After the run, write what it found.
16+
2. Write the first version of each invariant before you read the review comments or the fix. Add later invariants through the review ratchet.
17+
3. Report a null result. A spec that finds nothing new is data, not a failure.
18+
4. Do not tune a spec until it finds a bug you already know.
19+
5. A spec checks the model, not the code. Do not say a spec proves the code correct.
20+
21+
## What to model
22+
23+
Write the unit tests and do the review as usual. The spec does not replace them.
24+
25+
| Change kind | The spec models |
26+
| -------------------------------------------- | -------------------------------------------------------------------- |
27+
| Order of events, async work, state over time | The actions and every order of them |
28+
| A value that enters a function | The input domain. Make the parser or callee an oracle. |
29+
| A setting or a config value | Each reader of the value and its default |
30+
| None of these | The source and the sink. Ask what a bad value can do at each source. |
31+
32+
## Terms
33+
34+
| Term | Meaning |
35+
| -------------- | ------------------------------------------------------------------------------------- |
36+
| TLC | The TLA+ model checker. It tries every state and checks each invariant. |
37+
| oracle | A function the spec does not define. TLC tries every result. Example: `parses`. |
38+
| replay | Run a counterexample on the real code. It shows if the counterexample is real. |
39+
| sabotage check | Remove a guard on purpose. The invariant must fail. If not, the invariant is vacuous. |
40+
| vacuous | True in all states because of the model, not because of the code. |
41+
| gate | The check an agent runs by hand on each commit. No script or CI step runs it yet. |
42+
43+
## Procedure
44+
45+
1. Search this folder for a spec of the same subsystem. If one exists, extend it.
46+
2. Write each failure that the change must prevent as one sentence.
47+
3. Write each invariant as the opposite of one failure.
48+
4. Mark the source and the sink in the code. Name the functions and events. Do not use line numbers. They go stale.
49+
5. Model only the source and the sink. Make every other part an oracle. Do not copy a parser.
50+
6. Limit the input domain to values that look real. If TLC finds an input that no user can send, add a rule to remove it.
51+
7. Run TLC on the unfixed code. If the code has no known bug, run the sabotage check. The invariant must fail.
52+
8. Replay each counterexample on the real code. Keep the counterexamples that leak. Record the false alarms.
53+
9. Run TLC on the fixed code. The invariant must hold.
54+
10. Write a property test from the same invariant sentence. Run it on the real code.
55+
11. Simplify the spec. Use the questions below.
56+
12. Run each TLC config and the property test by hand on each fix commit. Write the result in the spec header.
57+
58+
## Review ratchet
59+
60+
A review finding is a failure that someone saw in this repo. Use each finding to grow the spec.
61+
62+
1. After each review round, read each finding.
63+
2. If the spec can express the failure, add an invariant or an input rule. Cite the PR and the thread in a comment.
64+
3. If the first version of the spec already covered the finding, write "covered" in the header.
65+
4. If the spec cannot express the finding, write "gap" in the header and say why.
66+
5. Run each TLC config on the next fix commit.
67+
68+
Count the "covered", "added" and "gap" results in the header. Count the findings about the spec files too. A maintainer uses the counts to decide scope.
69+
70+
## Simplify questions
71+
72+
1. Is a variable always equal to a function of other variables? If yes, derive it. Do not store it.
73+
2. Do two actions have the same effect? If yes, merge them.
74+
3. Does a new variable multiply the state count? If yes, remove it or prove it is needed.
75+
4. Do two parts of the code or of this folder repeat the same rule? If yes, keep the rule in one place.
76+
77+
## File layout
78+
79+
1. Name each spec after its subsystem. Example: `UrlRedaction.tla`.
80+
2. Name the config that must pass `Spec.cfg`. Name each other config `Spec.Variant.cfg`, for example a sabotage run that must fail.
81+
3. Keep every module in this folder. TLC finds the modules there.
82+
4. Put shared operators in `Common.tla`. Extract an operator when a second spec needs it, not before.
83+
5. Use `EXTENDS` to split one spec. Use `INSTANCE` for a module that other specs reuse.
84+
6. Put model-checking settings in an `MC` module. Keep the spec free of them.
85+
7. Keep each spec under 300 lines. If a spec is longer, split it by subsystem.
86+
8. Start each spec with a comment. Name the functions, the failure, the invariant, the cost and the findings.
87+
88+
Sources: [module structure](https://learning.tlapl.us/intro/module-structure/) and [MC file advice](https://discuss.tlapl.us/msg06726.html).
89+
90+
## Run TLC
91+
92+
1. Download `tla2tools.jar` to a folder outside the repo. Do not commit it.
93+
2. Run: `java -XX:+UseParallelGC -cp <jar> tlc2.TLC -metadir <folder outside the repo> -config Spec.Variant.cfg Spec.tla`. Without `-metadir`, TLC writes a `states` folder here.
94+
3. If the system can end, add `CHECK_DEADLOCK FALSE` to the config. Without it, TLC reports the end as a deadlock.
95+
4. Pick the smallest constants that show the interaction. Two links are enough for interleaving.
96+
97+
## Rules for this folder
98+
99+
1. Write prose and comments in ASD-STE100. Keep each comment to one or two lines.
100+
2. The repo has TypeScript model checks. Run `pnpm lifecycle:model-check` for lifecycle code. Read `docs/architecture/task-lifecycle-model.md` first. Do not replace these checks with a spec.
101+
3. Follow the root `AGENTS.md` for tests and lint.
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
SPECIFICATION Spec
2+
CHECK_DEADLOCK FALSE
3+
CONSTANT Links = {l1, l2}
4+
INVARIANTS TypeOK NoInstallWithoutConsent
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---- MODULE RequestyConsent ----
2+
\* Models the consent gate in src/activate/handleUri.ts, case "/requesty".
3+
\* Install = the call to upsertProviderProfile in handleRequestyCallback.
4+
\* Failure: a provider profile is written without the user approving the dialog.
5+
\* Invariant: NoInstallWithoutConsent.
6+
\* Result, 2 links: holds in 25 states. Without the approval guard, TLC fails in 2 states.
7+
\* Not modeled: the visible provider instance. Dialog text is in RequestyDialogHost.tla.
8+
\* Cost: TLC runs in under 1 second. Agent time is not measured.
9+
\* Review: 0 covered, 0 added, 2 gap (the log leak is in UrlRedaction.tla, the host spoof in RequestyDialogHost.tla).
10+
11+
CONSTANT Links \* the deep links that can arrive
12+
13+
VARIABLES open, answer, installed
14+
15+
vars == <<open, answer, installed>>
16+
17+
TypeOK ==
18+
/\ open \subseteq Links
19+
/\ answer \in [Links -> {"none", "approve", "dismiss"}]
20+
/\ installed \subseteq Links
21+
22+
Init ==
23+
/\ open = {}
24+
/\ answer = [l \in Links |-> "none"]
25+
/\ installed = {}
26+
27+
\* handleUri reaches the call to showWarningMessage.
28+
Arrive(l) ==
29+
/\ l \notin open
30+
/\ answer[l] = "none"
31+
/\ open' = open \cup {l}
32+
/\ UNCHANGED <<answer, installed>>
33+
34+
\* The user clicks a button. The await on showWarningMessage returns.
35+
UserAnswers(l, c) ==
36+
/\ l \in open
37+
/\ c \in {"approve", "dismiss"}
38+
/\ answer' = [answer EXCEPT ![l] = c]
39+
/\ open' = open \ {l}
40+
/\ UNCHANGED installed
41+
42+
\* handleRequestyCallback writes the provider profile.
43+
Install(l) ==
44+
/\ answer[l] = "approve"
45+
/\ l \notin installed
46+
/\ installed' = installed \cup {l}
47+
/\ UNCHANGED <<open, answer>>
48+
49+
Next ==
50+
\E l \in Links :
51+
\/ Arrive(l)
52+
\/ \E c \in {"approve", "dismiss"} : UserAnswers(l, c)
53+
\/ Install(l)
54+
55+
Spec == Init /\ [][Next]_vars
56+
57+
\* Safety Rule 1: a profile is written only for an approved link.
58+
NoInstallWithoutConsent == \A l \in installed : answer[l] = "approve"
59+
60+
====
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
SPECIFICATION Spec
2+
CHECK_DEADLOCK FALSE
3+
CONSTANTS
4+
Hosts = {"requesty", "evil"}
5+
Variant = "Raw"
6+
INVARIANTS TypeOK ShownHostIsRequestHost
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
SPECIFICATION Spec
2+
CHECK_DEADLOCK FALSE
3+
CONSTANTS
4+
Hosts = {"requesty", "evil"}
5+
Variant = "Fixed"
6+
INVARIANTS TypeOK ShownHostIsRequestHost
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---- MODULE RequestyDialogHost ----
2+
\* Models the destination text in the consent dialog (handleUri, case "/requesty").
3+
\* Failure: the dialog shows a trusted name before the host that the request uses.
4+
\* Invariant: ShownHostIsRequestHost. Example: https://router.requesty.ai@evil.example/v1.
5+
\* Result: Raw fails with user "requesty" and host "evil". Fixed holds in 6 states.
6+
\* The Fixed variant removes the user name and password. It is true by construction.
7+
\* The Raw variant is a sabotage check for the removed fix. The code no longer has it.
8+
\* Not modeled: the path, the port, and how the user reads the text.
9+
\* Cost: TLC runs in under 1 second. Agent time is not measured.
10+
\* Review: 0 covered, 1 added (PR 2408 review finding 6, no spec for the host fix), 0 gap.
11+
\* The first version was written after the finding. It is not an independent first pass.
12+
13+
CONSTANTS Hosts, Variant \* Variant is "Raw" or "Fixed"
14+
15+
VARIABLE url
16+
17+
Users == {"none"} \cup Hosts \* A user name can look like a host name.
18+
19+
TypeOK == url \in [user : Users, host : Hosts]
20+
21+
Init == url \in [user : Users, host : Hosts]
22+
Next == UNCHANGED url
23+
Spec == Init /\ [][Next]_url
24+
25+
\* The first name in the dialog text. A raw URL shows the user name first.
26+
FirstShown ==
27+
IF Variant = "Raw" /\ url.user # "none" THEN url.user ELSE url.host
28+
29+
\* Safety: the first name in the dialog is the host that the request uses.
30+
ShownHostIsRequestHost == FirstShown = url.host
31+
32+
====
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
SPECIFICATION Spec
2+
CONSTANTS
3+
Alphabet = {"/", ":", "@", "x", "S"}
4+
MaxLen = 8
5+
Variant = "Regex"
6+
INVARIANTS TypeOK NoSecretInLog
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
SPECIFICATION Spec
2+
CONSTANTS
3+
Alphabet = {"/", ":", "@", "x", "S"}
4+
MaxLen = 8
5+
Variant = "Fixed"
6+
INVARIANTS TypeOK NoSecretInLog
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---- MODULE UrlRedaction ----
2+
\* Models the warning log in toRequestyServiceUrl (src/shared/utils/requesty.ts, catch branch).
3+
\* The code logs a fixed message now. The Regex variant models the removed redaction regex.
4+
\* The Regex variant is a sabotage check only. The Fixed variant is true by construction.
5+
\* Failure: an untrusted baseUrl puts credential text in the warning log.
6+
\* Invariant: NoSecretInLog. The oracle `parses` is unconstrained. The log runs when it is FALSE.
7+
\* Result, MaxLen 8: Regex fails with x:S@. Fixed holds in 20,624 states.
8+
\* Replay: https:secret@h:bad leaks in real code. The bot comment on PR 2408 does not name this form.
9+
\* Replay: https://secret/@h:bad parses in real code. It is a false alarm from the oracle.
10+
\* Cost: TLC runs in under 1 second. Agent time is not measured.
11+
\* Review: 0 covered, 1 added (bot thread on the redaction regex, PR 2408), 0 gap.
12+
\* The first version was written after the bot thread. It is not an independent first pass.
13+
14+
EXTENDS Naturals, Sequences
15+
16+
CONSTANTS Alphabet, MaxLen, Variant \* Variant is "Regex" or "Fixed"
17+
18+
VARIABLES in, parses
19+
20+
Delim == {"/"} \* The regex class [^/?#]. "?" and "#" are not in Alphabet.
21+
22+
Strings == UNION {[1..n -> Alphabet] : n \in 0..MaxLen}
23+
24+
\* Each "S" is credential text. It must come before some "@".
25+
\* The input starts with a scheme "x:".
26+
HasAtAfter(s, p) == \E q \in (p+1)..Len(s) : s[q] = "@"
27+
UrlShaped(s) == Len(s) >= 2 /\ s[1] = "x" /\ s[2] = ":"
28+
Inputs == {s \in Strings : UrlShaped(s) /\ \A p \in 1..Len(s) : s[p] = "S" => HasAtAfter(s, p)}
29+
30+
\* The regex /\/\/[^/?#]*@/ without the g flag. JavaScript replaces the first match.
31+
Slash2(s, i) == i + 1 <= Len(s) /\ s[i] = "/" /\ s[i+1] = "/"
32+
RunEnd(s, i) ==
33+
CHOOSE e \in (i+1)..Len(s) :
34+
/\ \A p \in (i+2)..e : s[p] \notin Delim
35+
/\ (e = Len(s) \/ s[e+1] \in Delim)
36+
AtPos(s, i) == {p \in (i+2)..RunEnd(s, i) : s[p] = "@"}
37+
Starts(s) == {i \in 1..Len(s) : Slash2(s, i) /\ AtPos(s, i) # {}}
38+
Min(S) == CHOOSE m \in S : \A q \in S : m <= q
39+
Max(S) == CHOOSE m \in S : \A q \in S : q <= m
40+
41+
RedactRegex(s) ==
42+
IF Starts(s) = {} THEN s
43+
ELSE LET i == Min(Starts(s))
44+
j == Max(AtPos(s, i))
45+
IN SubSeq(s, 1, i-1) \o <<"/", "/">> \o SubSeq(s, j+1, Len(s))
46+
47+
LogMsg(s) == IF Variant = "Regex" THEN RedactRegex(s) ELSE <<"m">>
48+
49+
TypeOK == in \in Inputs /\ parses \in BOOLEAN
50+
51+
Init == in \in Inputs /\ parses \in BOOLEAN
52+
Next == UNCHANGED <<in, parses>>
53+
Spec == Init /\ [][Next]_<<in, parses>>
54+
55+
\* Safety: when the parse fails, the log line holds no credential text.
56+
NoSecretInLog ==
57+
~parses => \A p \in 1..Len(LogMsg(in)) : LogMsg(in)[p] # "S"
58+
59+
====

0 commit comments

Comments
 (0)