refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -10,16 +10,16 @@

 ## Elements and evidence

- **브라우저** (participant): AP4_SESSION cookie와 함께 edge endpoint를 호출하는 외부 client. Evidence: L992–L1007.
- **Nginx edge** (participant): Internal auth subrequest를 만들고 인증 결과를 allowlisted upstream header와 internal token으로 재조립한다. Evidence: L914–L939, L1009–L1028.
- **oauth2-proxy** (participant): AP4_SESSION을 검증하고 인증된 user, email과 필요 시 갱신 cookie를 auth response로 돌려준다. Evidence: L980–L990, L1009–L1015.
- **Spring upstream** (participant): Identity header와 internal token을 함께 검증해 allowlisted identity JSON을 반환한다. Evidence: L1017–L1026, L1030–L1063.
+- **브라우저** (participant): AP4_SESSION cookie와 함께 edge endpoint를 호출하는 외부 client. Evidence: L1032–L1047.
+- **Nginx edge** (participant): Internal auth subrequest를 만들고 인증 결과를 allowlisted upstream header와 internal token으로 재조립한다. Evidence: L954–L979, L1049–L1068.
+- **oauth2-proxy** (participant): AP4_SESSION을 검증하고 인증된 user, email과 필요 시 갱신 cookie를 auth response로 돌려준다. Evidence: L1020–L1030, L1049–L1055.
+- **Spring upstream** (participant): Identity header와 internal token을 함께 검증해 allowlisted identity JSON을 반환한다. Evidence: L1057–L1066, L1070–L1103.

 ## Relationships

- **브라우저 → Nginx edge:** GET /api/edge + AP4_SESSION. Evidence: L992–L999.
- **Nginx edge → oauth2-proxy:** internal /oauth2/auth subrequest. Evidence: L922–L939, L1009–L1009.
- **oauth2-proxy → Nginx edge:** authenticated user + email. Evidence: L1009–L1015.
- **Nginx edge → Spring upstream:** GET /edge/me · trusted headers + internal token. Evidence: L1017–L1026.
- **Spring upstream → Nginx edge:** trusted identity JSON. Evidence: L1030–L1048.
- **Nginx edge → 브라우저:** pattern + user + email + identityHeader. Evidence: L1039–L1048, L1065–L1076.
+- **브라우저 → Nginx edge:** GET /api/edge + AP4_SESSION. Evidence: L1032–L1039.
+- **Nginx edge → oauth2-proxy:** internal /oauth2/auth subrequest. Evidence: L962–L979, L1049–L1049.
+- **oauth2-proxy → Nginx edge:** authenticated user + email. Evidence: L1049–L1055.
+- **Nginx edge → Spring upstream:** GET /edge/me · trusted headers + internal token. Evidence: L1057–L1066.
+- **Spring upstream → Nginx edge:** trusted identity JSON. Evidence: L1070–L1088.
+- **Nginx edge → 브라우저:** pattern + user + email + identityHeader. Evidence: L1079–L1088, L1105–L1116.
@@ -5,16 +5,16 @@
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
-        <mxCell id="n_browser" value="브라우저" tooltip="AP4_SESSION cookie와 함께 edge endpoint를 호출하는 외부 client. | Evidence: L992-L1007" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
+        <mxCell id="n_browser" value="브라우저" tooltip="AP4_SESSION cookie와 함께 edge endpoint를 호출하는 외부 client. | Evidence: L1032-L1047" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
          <mxGeometry x="45.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
        </mxCell>
-        <mxCell id="n_nginx" value="Nginx edge" tooltip="Internal auth subrequest를 만들고 인증 결과를 allowlisted upstream header와 internal token으로 재조립한다. | Evidence: L914-L939, L1009-L1028" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
+        <mxCell id="n_nginx" value="Nginx edge" tooltip="Internal auth subrequest를 만들고 인증 결과를 allowlisted upstream header와 internal token으로 재조립한다. | Evidence: L954-L979, L1049-L1068" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
          <mxGeometry x="255.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
        </mxCell>
-        <mxCell id="n_oauth2-proxy" value="oauth2-proxy" tooltip="AP4_SESSION을 검증하고 인증된 user, email과 필요 시 갱신 cookie를 auth response로 돌려준다. | Evidence: L980-L990, L1009-L1015" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
+        <mxCell id="n_oauth2-proxy" value="oauth2-proxy" tooltip="AP4_SESSION을 검증하고 인증된 user, email과 필요 시 갱신 cookie를 auth response로 돌려준다. | Evidence: L1020-L1030, L1049-L1055" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
          <mxGeometry x="465.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
        </mxCell>
-        <mxCell id="n_spring-upstream" value="Spring upstream" tooltip="Identity header와 internal token을 함께 검증해 allowlisted identity JSON을 반환한다. | Evidence: L1017-L1026, L1030-L1063" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
+        <mxCell id="n_spring-upstream" value="Spring upstream" tooltip="Identity header와 internal token을 함께 검증해 allowlisted identity JSON을 반환한다. | Evidence: L1057-L1066, L1070-L1103" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;" vertex="1" parent="1">
          <mxGeometry x="675.0" y="35.0" width="150.0" height="64.0" as="geometry"/>
        </mxCell>
        <mxCell id="e_edge-request" value="GET /api/edge + AP4_SESSION" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_browser" target="n_nginx">
@@ -2,22 +2,22 @@
  "harness_version": "0.2.0",
  "spec_id": "ap4-edge-forward-auth-flow",
  "spec_version": "1.1",
-  "spec_sha256": "18ce47da22142be0655461f3677df193562cb037f936b1a8f3d846665187f300",
+  "spec_sha256": "5a2acba76a1d2eb7d67868f2927104e8730e86c9841272cf87f79aa84b82d53f",
  "source_context": {
    "document": "document.md",
-    "document_sha256": "df4d1a604c74e756672b5b40510abfedb8c67b39af280a5f51985ea9972f5371",
+    "document_sha256": "15e7c79412ac05ed39d6f3d0c14de8dda92abe7b402139ac2a90492dfe5e162c",
    "anchor": {
      "kind": "marker",
      "value": "ap4-edge-forward-auth-flow",
-      "line": 1108
+      "line": 1148
    }
  },
  "outputs": [
    "ap4-edge-forward-auth-flow.svg",
-    "ap4-edge-forward-auth-flow.drawio",
    "ap4-edge-forward-auth-flow.mmd",
    "ap4-edge-forward-auth-flow.d2",
    "ap4-edge-forward-auth-flow.dot",
+    "ap4-edge-forward-auth-flow.drawio",
    "ap4-edge-forward-auth-flow.excalidraw",
    "ap4-edge-forward-auth-flow.alt.md"
  ],
@@ -2,7 +2,7 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="870" height="542" viewBox="0 0 870 542" role="img" aria-labelledby="diagram-title diagram-description">
 <title id="diagram-title">AP4 proxy session에서 trusted identity JSON까지</title>
 <desc id="diagram-description">브라우저가 AP4_SESSION cookie로 Nginx의 /api/edge를 호출한다. Nginx는 oauth2-proxy의 internal auth endpoint에 subrequest를 보내고 인증된 user와 email 결과를 받는다. 이어서 client가 보낸 동명 header를 사용하지 않고 oauth2-proxy 결과와 Nginx 환경의 internal token으로 /edge/me 요청을 새로 조립한다. Spring controller가 user header와 internal token을 함께 확인해 identity JSON을 만들고 Nginx가 브라우저에 전달한다.</desc>
-<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;ap4-edge-forward-auth-flow&quot;,&quot;profile&quot;:&quot;sequence&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;document.md&quot;,&quot;document_sha256&quot;:&quot;df4d1a604c74e756672b5b40510abfedb8c67b39af280a5f51985ea9972f5371&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;marker&quot;,&quot;value&quot;:&quot;ap4-edge-forward-auth-flow&quot;,&quot;line&quot;:1108}},&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;ap4-edge-forward-auth-flow&quot;,&quot;profile&quot;:&quot;sequence&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;document.md&quot;,&quot;document_sha256&quot;:&quot;15e7c79412ac05ed39d6f3d0c14de8dda92abe7b402139ac2a90492dfe5e162c&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;marker&quot;,&quot;value&quot;:&quot;ap4-edge-forward-auth-flow&quot;,&quot;line&quot;:1148}},&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" />
@@ -50,34 +50,34 @@
  </style>
 </defs>
 <rect class="canvas" width="870" height="542" />
-<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="992-1007" x="45.0" y="35.0" width="150.0" height="64.0" rx="7" />
+<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="1032-1047" x="45.0" y="35.0" width="150.0" height="64.0" rx="7" />
 <text class="node-label" x="120.0" y="65.0">브라우저</text>
 <line class="lifeline" x1="120.0" y1="99.0" x2="120.0" y2="512.0" />
-<rect class="node-shape kind-participant emphasis-primary role-participant" data-evidence="914-939,1009-1028" x="255.0" y="35.0" width="150.0" height="64.0" rx="7" />
+<rect class="node-shape kind-participant emphasis-primary role-participant" data-evidence="954-979,1049-1068" x="255.0" y="35.0" width="150.0" height="64.0" rx="7" />
 <text class="node-label" x="330.0" y="65.0">Nginx edge</text>
 <line class="lifeline" x1="330.0" y1="99.0" x2="330.0" y2="512.0" />
-<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="980-990,1009-1015" x="465.0" y="35.0" width="150.0" height="64.0" rx="7" />
+<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="1020-1030,1049-1055" x="465.0" y="35.0" width="150.0" height="64.0" rx="7" />
 <text class="node-label" x="540.0" y="65.0">oauth2-proxy</text>
 <line class="lifeline" x1="540.0" y1="99.0" x2="540.0" y2="512.0" />
-<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="1017-1026,1030-1063" x="675.0" y="35.0" width="150.0" height="64.0" rx="7" />
+<rect class="node-shape kind-participant emphasis-normal role-participant" data-evidence="1057-1066,1070-1103" x="675.0" y="35.0" width="150.0" height="64.0" rx="7" />
 <text class="node-label" x="750.0" y="65.0">Spring upstream</text>
 <line class="lifeline" x1="750.0" y1="99.0" x2="750.0" y2="512.0" />
-<polyline class="edge kind-request style-solid emphasis-normal" points="120.0,140.0 330.0,140.0" data-evidence="992-999" />
+<polyline class="edge kind-request style-solid emphasis-normal" points="120.0,140.0 330.0,140.0" data-evidence="1032-1039" />
 <rect class="edge-label-bg" x="115.5" y="114.0" width="219.0" height="22" rx="3" />
 <text class="edge-label" x="225.0" y="129.0">1. GET /api/edge + AP4_SESSION</text>
-<polyline class="edge kind-request style-solid emphasis-normal" points="330.0,202.0 540.0,202.0" data-evidence="922-939,1009-1009" />
+<polyline class="edge kind-request style-solid emphasis-normal" points="330.0,202.0 540.0,202.0" data-evidence="962-979,1049-1049" />
 <rect class="edge-label-bg" x="308.8" y="176.0" width="252.5" height="22" rx="3" />
 <text class="edge-label" x="435.0" y="191.0">2. internal /oauth2/auth subrequest</text>
-<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="540.0,264.0 330.0,264.0" data-evidence="1009-1015" />
+<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="540.0,264.0 330.0,264.0" data-evidence="1049-1055" />
 <rect class="edge-label-bg" x="328.9" y="238.0" width="212.3" height="22" rx="3" />
 <text class="edge-label" x="435.0" y="253.0">3. authenticated user + email</text>
-<polyline class="edge kind-request style-solid emphasis-primary" points="330.0,326.0 750.0,326.0" data-evidence="1017-1026" />
+<polyline class="edge kind-request style-solid emphasis-primary" points="330.0,326.0 750.0,326.0" data-evidence="1057-1066" />
 <rect class="edge-label-bg" x="380.0" y="300.0" width="320.0" height="22" rx="3" />
 <text class="edge-label" x="540.0" y="315.0">4. GET /edge/me · trusted headers + internal token</text>
-<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="750.0,388.0 330.0,388.0" data-evidence="1030-1048" />
+<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="750.0,388.0 330.0,388.0" data-evidence="1070-1088" />
 <rect class="edge-label-bg" x="450.6" y="362.0" width="178.8" height="22" rx="3" />
 <text class="edge-label" x="540.0" y="377.0">5. trusted identity JSON</text>
-<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="330.0,450.0 120.0,450.0" data-evidence="1039-1048,1065-1076" />
+<polyline class="edge kind-response style-dashed emphasis-normal semantic-dashed" points="330.0,450.0 120.0,450.0" data-evidence="1079-1088,1105-1116" />
 <rect class="edge-label-bg" x="75.3" y="424.0" width="299.4" height="22" rx="3" />
 <text class="edge-label" x="225.0" y="439.0">6. pattern + user + email + identityHeader</text>
 </svg>