donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

refactor: 문서 개선 중

Browse Source
This commit is contained in:
donghyeon-ka
2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/keycloak-session-store/final/assets/b3-rotation-contention/b3-rotation-contention.alt.md
+7 -7
View File
@@ -10,13 +10,13 @@ revokeRefreshToken 을 켜고 refreshTokenMaxReuse 를 0 으로 둔 상태에서
## Elements and evidence
- **동시 refresh 5건** (actor): 같은 refresh token 을 쓴다. Evidence: L369–L375.
- **회전 검사** (process): 이미 쓴 토큰인지 본다. Evidence: L369–L377.
- **client session** (component): 경쟁이 감지되면 지워진다. Evidence: L378–L384.
- **이긴 요청의 새 토큰** (component): 세션이 지워져 쓸 수 없다. Evidence: L378–L384.
- **동시 refresh 5건** (actor): 같은 refresh token 을 쓴다. Evidence: L776–L781.
- **회전 검사** (process): 이미 쓴 토큰인지 본다. Evidence: L776–L781.
- **client session** (component): 경쟁이 감지되면 지워진다. Evidence: L789–L794.
- **이긴 요청의 새 토큰** (component): 세션이 지워져 쓸 수 없다. Evidence: L789–L794.
## Relationships
- **동시 refresh 5건 → 회전 검사:** 동시 도착. Evidence: L369–L377.
- **client session → 이긴 요청의 새 토큰:** 사용 불가. Evidence: L378–L384.
- **회전 검사 → client session:** 경쟁 감지 시 삭제. Evidence: L378–L384.
- **동시 refresh 5건 → 회전 검사:** 동시 도착. Evidence: L776–L781.
- **client session → 이긴 요청의 새 토큰:** 사용 불가. Evidence: L789–L794.
- **회전 검사 → client session:** 경쟁 감지 시 삭제. Evidence: L789–L794.
docs/keycloak-session-store/final/assets/b3-rotation-contention/b3-rotation-contention.drawio
+12 -12
View File
@@ -1,35 +1,35 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" modified="2026-07-23T00:00:00.000Z" agent="techviz-harness" version="24.7.17" type="device">
<diagram id="b3-rotation-contention" name="회전 경쟁에서 이긴 요청도 진다">
<mxGraphModel dx="680" dy="676" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
<mxGraphModel dx="680" dy="1334" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1334" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="n_concurrent" value="동시 refresh 5건&lt;br/&gt;&amp; + wait 필요" tooltip="같은 refresh token 을 쓴다. | Evidence: L369-L375" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;dashed=1;fillColor=#f5f7fa;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="145.0" y="60.0" width="150.0" height="84.0" as="geometry"/>
<mxCell id="n_concurrent" value="동시 refresh 5건&lt;br/&gt;&amp; + wait 필요" tooltip="같은 refresh token 을 쓴다. | Evidence: L776-L781" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;dashed=1;fillColor=#f5f7fa;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="35.0" y="145.0" width="150.0" height="84.0" as="geometry"/>
</mxCell>
<mxCell id="n_rotation" value="회전 검사&lt;br/&gt;revokeRefreshToken=true · refreshTokenMaxReuse=0" tooltip="이미 쓴 토큰인지 본다. | Evidence: L369-L377" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="70.0" y="240.0" width="300.0" height="71.0" as="geometry"/>
<mxCell id="n_rotation" value="회전 검사&lt;br/&gt;revokeRefreshToken=true · refreshTokenMaxReuse=0" tooltip="이미 쓴 토큰인지 본다. | Evidence: L776-L781" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="41.5" y="455.0" width="300.0" height="71.0" as="geometry"/>
</mxCell>
<mxCell id="n_client-session" value="client session" tooltip="경쟁이 감지되면 지워진다. | Evidence: L378-L384" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="145.0" y="407.0" width="150.0" height="64.0" as="geometry"/>
<mxCell id="n_client-session" value="client session" tooltip="경쟁이 감지되면 지워진다. | Evidence: L789-L794" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="45.0" y="915.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="n_new-token" value="이긴 요청의 새 토큰" tooltip="세션이 지워져 쓸 수 없다. | Evidence: L378-L384" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="145.0" y="567.0" width="150.0" height="64.0" as="geometry"/>
<mxCell id="n_new-token" value="이긴 요청의 새 토큰" tooltip="세션이 지워져 쓸 수 없다. | Evidence: L789-L794" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#d97706;fillColor=#fffdf5;" vertex="1" parent="1">
<mxGeometry x="45.0" y="1225.0" width="150.0" height="64.0" as="geometry"/>
</mxCell>
<mxCell id="e_c-r" value="동시 도착" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_concurrent" target="n_rotation">
<mxGeometry relative="1" as="geometry">
<mxPoint x="244.0" y="192.0" as="offset"/>
<mxPoint x="150.8" y="314.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_cs-nt" value="사용 불가" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_client-session" target="n_new-token">
<mxGeometry relative="1" as="geometry">
<mxPoint x="244.0" y="519.0" as="offset"/>
<mxPoint x="144.0" y="1102.0" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_r-cs" value="경쟁 감지 시 삭제" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_rotation" target="n_client-session">
<mxGeometry relative="1" as="geometry">
<mxPoint x="244.0" y="359.0" as="offset"/>
<mxPoint x="155.8" y="692.5" as="offset"/>
</mxGeometry>
</mxCell>
</root>
docs/keycloak-session-store/final/assets/b3-rotation-contention/b3-rotation-contention.excalidraw
+46 -46
View File
@@ -6,10 +6,10 @@
{
"id": "edge-c-r",
"type": "arrow",
"x": 220.0,
"y": 144.0,
"width": 0.0,
"height": 96.0,
"x": 110.0,
"y": 229.0,
"width": 81.5,
"height": 226.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -37,15 +37,15 @@
],
[
0.0,
48.0
113.0
],
[
0.0,
48.0
81.5,
113.0
],
[
0.0,
96.0
81.5,
226.0
]
],
"lastCommittedPoint": null,
@@ -66,8 +66,8 @@
{
"id": "edge-label-c-r",
"type": "text",
"x": 199.0,
"y": 180.0,
"x": 105.75,
"y": 302.0,
"width": 90,
"height": 24,
"angle": 0,
@@ -105,10 +105,10 @@
{
"id": "edge-cs-nt",
"type": "arrow",
"x": 220.0,
"y": 471.0,
"x": 120.0,
"y": 979.0,
"width": 0.0,
"height": 96.0,
"height": 246.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -136,15 +136,15 @@
],
[
0.0,
48.0
123.0
],
[
0.0,
48.0
123.0
],
[
0.0,
96.0
246.0
]
],
"lastCommittedPoint": null,
@@ -165,8 +165,8 @@
{
"id": "edge-label-cs-nt",
"type": "text",
"x": 199.0,
"y": 507.0,
"x": 99.0,
"y": 1090.0,
"width": 90,
"height": 24,
"angle": 0,
@@ -204,10 +204,10 @@
{
"id": "edge-r-cs",
"type": "arrow",
"x": 220.0,
"y": 311.0,
"width": 0.0,
"height": 96.0,
"x": 120.0,
"y": 526.0,
"width": 71.5,
"height": 389.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -230,20 +230,20 @@
"locked": false,
"points": [
[
0.0,
71.5,
0.0
],
[
0.0,
48.0
71.5,
194.5
],
[
0.0,
48.0
194.5
],
[
0.0,
96.0
389.0
]
],
"lastCommittedPoint": null,
@@ -264,8 +264,8 @@
{
"id": "edge-label-r-cs",
"type": "text",
"x": 199.0,
"y": 347.0,
"x": 110.75,
"y": 680.5,
"width": 90,
"height": 24,
"angle": 0,
@@ -303,8 +303,8 @@
{
"id": "node-concurrent",
"type": "rectangle",
"x": 145.0,
"y": 60.0,
"x": 35.0,
"y": 145.0,
"width": 150.0,
"height": 84.0,
"angle": 0,
@@ -333,8 +333,8 @@
{
"id": "node-label-concurrent",
"type": "text",
"x": 155.0,
"y": 70.0,
"x": 45.0,
"y": 155.0,
"width": 130.0,
"height": 64.0,
"angle": 0,
@@ -372,8 +372,8 @@
{
"id": "node-rotation",
"type": "rectangle",
"x": 70.0,
"y": 240.0,
"x": 41.5,
"y": 455.0,
"width": 300.0,
"height": 71.0,
"angle": 0,
@@ -402,8 +402,8 @@
{
"id": "node-label-rotation",
"type": "text",
"x": 80.0,
"y": 250.0,
"x": 51.5,
"y": 465.0,
"width": 280.0,
"height": 51.0,
"angle": 0,
@@ -441,8 +441,8 @@
{
"id": "node-client-session",
"type": "rectangle",
"x": 145.0,
"y": 407.0,
"x": 45.0,
"y": 915.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
@@ -471,8 +471,8 @@
{
"id": "node-label-client-session",
"type": "text",
"x": 155.0,
"y": 417.0,
"x": 55.0,
"y": 925.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
@@ -510,8 +510,8 @@
{
"id": "node-new-token",
"type": "rectangle",
"x": 145.0,
"y": 567.0,
"x": 45.0,
"y": 1225.0,
"width": 150.0,
"height": 64.0,
"angle": 0,
@@ -540,8 +540,8 @@
{
"id": "node-label-new-token",
"type": "text",
"x": 155.0,
"y": 577.0,
"x": 55.0,
"y": 1235.0,
"width": 130.0,
"height": 44.0,
"angle": 0,
docs/keycloak-session-store/final/assets/b3-rotation-contention/b3-rotation-contention.manifest.json
+4 -4
View File
@@ -2,14 +2,14 @@
"harness_version": "0.2.0",
"spec_id": "b3-rotation-contention",
"spec_version": "1.1",
"spec_sha256": "31779474e5400d5e719faf81a62da35a657994d952e4e0324a1c76c5d18183e4",
"spec_sha256": "511db5ddd2312ac2ee0eff68694683e9de62a6ced55f2ba9a828abff6f952f72",
"source_context": {
"document": "docs/keycloak-session-store/final/document.md",
"document_sha256": "1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe",
"document_sha256": "28aef96a2bbb94fbb10ade26a71238fee62a5a4d9fa6e7749ae98cfd0a65e560",
"anchor": {
"kind": "heading",
"value": "B-3 · Refresh Token Rotation 경쟁 (Q2)",
"line": 391
"line": 806
}
},
"outputs": [
@@ -21,7 +21,7 @@
"b3-rotation-contention.excalidraw",
"b3-rotation-contention.alt.md"
],
"lint_issue_count": 0,
"lint_issue_count": 1,
"assumption_count": 0,
"assumptions_allowed": false,
"composition_profile": "component-flow",
docs/keycloak-session-store/final/assets/b3-rotation-contention/b3-rotation-contention.svg
+22 -22
View File
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="680" height="676" viewBox="0 0 680 676" role="img" aria-labelledby="diagram-title diagram-description">
<svg xmlns="http://www.w3.org/2000/svg" width="680" height="1334" viewBox="0 0 680 1334" role="img" aria-labelledby="diagram-title diagram-description">
<title id="diagram-title">회전 경쟁에서 이긴 요청도 진다</title>
<desc id="diagram-description">revokeRefreshToken 을 켜고 refreshTokenMaxReuse 를 0 으로 둔 상태에서 같은 refresh token 으로 동시에 5건을 보냈다. 순차로 돌리면 재현되지 않으며 백그라운드로 띄우고 wait 해야 경합이 생긴다. 이긴 요청이 받은 새 토큰조차 쓸 수 없었다. Keycloak 이 경쟁을 감지하면 client session 을 지우기 때문이다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;b3-rotation-contention&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/keycloak-session-store/final/document.md&quot;,&quot;document_sha256&quot;:&quot;1d44cba1905544d92f1d26ae36a8deb64a3db3914d6b488fd30d6ae7f8cfbabe&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;B-3 · Refresh Token Rotation 경쟁 (Q2)&quot;,&quot;line&quot;:391}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;b3-rotation-contention&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/keycloak-session-store/final/document.md&quot;,&quot;document_sha256&quot;:&quot;28aef96a2bbb94fbb10ade26a71238fee62a5a4d9fa6e7749ae98cfd0a65e560&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;B-3 · Refresh Token Rotation 경쟁 (Q2)&quot;,&quot;line&quot;:806}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" />
@@ -49,32 +49,32 @@
.timeline-detail { font-size: 11px; fill: #4b5563; text-anchor: middle; }
</style>
</defs>
<rect class="canvas" width="680" height="676" />
<polyline class="edge kind-request style-solid emphasis-normal" points="220.0,144.0 220.0,192.0 220.0,192.0 220.0,240.0" data-evidence="369-377" />
<rect class="edge-label-bg" x="218.2" y="178.0" width="51.5" height="22" rx="3" />
<text class="edge-label" x="244.0" y="193.0">동시 도착</text>
<polyline class="edge kind-blocked style-solid emphasis-normal" points="220.0,471.0 220.0,519.0 220.0,519.0 220.0,567.0" data-evidence="378-384" />
<rect class="edge-label-bg" x="218.2" y="505.0" width="51.5" height="22" rx="3" />
<text class="edge-label" x="244.0" y="520.0">사용 불가</text>
<polyline class="edge kind-blocked style-solid emphasis-normal" points="220.0,311.0 220.0,359.0 220.0,359.0 220.0,407.0" data-evidence="378-384" />
<rect class="edge-label-bg" x="201.5" y="345.0" width="85.0" height="22" rx="3" />
<text class="edge-label" x="244.0" y="360.0">경쟁 감지 시 삭제</text>
<rect class="canvas" width="680" height="1334" />
<polyline class="edge kind-request style-solid emphasis-normal" points="110.0,229.0 110.0,342.0 191.5,342.0 191.5,455.0" data-evidence="776-781" />
<rect class="edge-label-bg" x="125.0" y="300.0" width="51.5" height="22" rx="3" />
<text class="edge-label" x="150.8" y="315.0">동시 도착</text>
<polyline class="edge kind-blocked style-solid emphasis-normal" points="120.0,979.0 120.0,1102.0 120.0,1102.0 120.0,1225.0" data-evidence="789-794" />
<rect class="edge-label-bg" x="118.2" y="1088.0" width="51.5" height="22" rx="3" />
<text class="edge-label" x="144.0" y="1103.0">사용 불가</text>
<polyline class="edge kind-blocked style-solid emphasis-normal" points="191.5,526.0 191.5,720.5 120.0,720.5 120.0,915.0" data-evidence="789-794" />
<rect class="edge-label-bg" x="113.2" y="678.5" width="85.0" height="22" rx="3" />
<text class="edge-label" x="155.8" y="693.5">경쟁 감지 시 삭제</text>
<g id="node-concurrent">
<g class="actor-symbol emphasis-primary" data-evidence="369-375"><circle cx="220.0" cy="80.0" r="11.0" /><line x1="220.0" y1="96.0" x2="220.0" y2="105.0" /><line x1="202.0" y1="106.0" x2="238.0" y2="106.0" /><line x1="220.0" y1="105.0" x2="205.0" y2="122.0" /><line x1="220.0" y1="105.0" x2="235.0" y2="122.0" /></g>
<text class="node-label" x="220.0" y="137.0">동시 refresh 5건</text>
<g class="actor-symbol emphasis-primary" data-evidence="776-781"><circle cx="110.0" cy="165.0" r="11.0" /><line x1="110.0" y1="181.0" x2="110.0" y2="200.0" /><line x1="92.0" y1="191.0" x2="128.0" y2="191.0" /><line x1="110.0" y1="200.0" x2="95.0" y2="217.0" /><line x1="110.0" y1="200.0" x2="125.0" y2="217.0" /></g>
<text class="node-label" x="110.0" y="222.0">동시 refresh 5건</text>
</g>
<g id="node-rotation">
<rect class="node-shape kind-process emphasis-warning role-control" data-evidence="369-377" x="70.0" y="240.0" width="300.0" height="71.0" rx="7" />
<text class="node-label" x="220.0" y="267.0">회전 검사</text>
<line class="node-detail-divider" x1="84.0" y1="288.0" x2="356.0" y2="288.0" />
<text class="node-detail" x="86.0" y="305.0">revokeRefreshToken=true · refreshTokenMaxReuse=0</text>
<rect class="node-shape kind-process emphasis-warning role-control" data-evidence="776-781" x="41.5" y="455.0" width="300.0" height="71.0" rx="7" />
<text class="node-label" x="191.5" y="482.0">회전 검사</text>
<line class="node-detail-divider" x1="55.5" y1="503.0" x2="327.5" y2="503.0" />
<text class="node-detail" x="57.5" y="520.0">revokeRefreshToken=true · refreshTokenMaxReuse=0</text>
</g>
<g id="node-client-session">
<rect class="node-shape kind-component emphasis-warning role-target" data-evidence="378-384" x="145.0" y="407.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="220.0" y="437.0">client session</text>
<rect class="node-shape kind-component emphasis-warning role-target" data-evidence="789-794" x="45.0" y="915.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="120.0" y="945.0">client session</text>
</g>
<g id="node-new-token">
<rect class="node-shape kind-component emphasis-warning role-target" data-evidence="378-384" x="145.0" y="567.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="220.0" y="597.0">이긴 요청의 새 토큰</text>
<rect class="node-shape kind-component emphasis-warning role-target" data-evidence="789-794" x="45.0" y="1225.0" width="150.0" height="64.0" rx="7" />
<text class="node-label" x="120.0" y="1255.0">이긴 요청의 새 토큰</text>
</g>
</svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.6 KiB

After

Width:  |  Height:  |  Size: 6.6 KiB