docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: docs/runbooks, docs/security, docs/styling/design-tokens.md, docs/accessibility, docs/contracts, docs/testing/taxonomy.md와 src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다. PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code, 기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로 둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장 끝만 바꾼다. 위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임 문체를 더하면 verify:documentation이 실패한다. 검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다. 문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
This commit is contained in:
+21
-21
@@ -8,49 +8,49 @@ web
|
||||
|
||||
## Users
|
||||
|
||||
- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도입니다.
|
||||
- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 합니다.
|
||||
- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람이다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도다.
|
||||
- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 한다.
|
||||
|
||||
## Product Purpose
|
||||
|
||||
도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둡니다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것입니다.
|
||||
도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점이다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둔다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것이다.
|
||||
|
||||
## Positioning
|
||||
|
||||
화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트입니다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않습니다.
|
||||
화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제한다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않는다.
|
||||
|
||||
## Operating Context
|
||||
|
||||
- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다.
|
||||
- 파생 서비스는 운영 중인 desktop 서버에 배포됩니다.
|
||||
- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다.
|
||||
- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다.
|
||||
- 파생 서비스는 운영 중인 desktop 서버에 배포된다.
|
||||
- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있다.
|
||||
|
||||
## Capabilities and Constraints
|
||||
|
||||
- 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다.
|
||||
- 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(`tokens/primitive.css`, `semantic.css`, `component.css`).
|
||||
- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다.
|
||||
- 템플릿에는 샘플 기능이 없습니다(참조 기능과 예제 화면은 2026-11-07에 지웠습니다). 기능은 `create:feature`로 만듭니다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상입니다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성입니다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남습니다.
|
||||
- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다.
|
||||
- 하나의 디자인 시스템으로 세 종류의 서비스를 받친다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지다.
|
||||
- 디자인 시스템 위치는 `src/presentation/design-system/`이다. 토큰은 primitive → semantic → component 세 단계로 파생된다(`tokens/primitive.css`, `semantic.css`, `component.css`).
|
||||
- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있다. 화면을 바꾸면 골든도 의도적으로 갱신해야 한다.
|
||||
- 템플릿에는 샘플 기능이 없다(참조 기능과 예제 화면은 2026-11-07에 지웠다). 기능은 `create:feature`로 만든다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상이다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남는다.
|
||||
- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았다.
|
||||
|
||||
## Brand Commitments
|
||||
|
||||
브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자입니다.
|
||||
브랜드는 중립으로 유지한다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힌다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자다.
|
||||
|
||||
## Evidence on Hand
|
||||
|
||||
- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다.
|
||||
- 예제 문구는 템플릿 기능 설명뿐입니다(`src/presentation/i18n/catalog.ts`).
|
||||
- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없다. 지어내지 않는다.
|
||||
- 예제 문구는 템플릿 기능 설명뿐이다(`src/presentation/i18n/catalog.ts`).
|
||||
- 현재 화면 기록: `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/`, Storybook(`src/presentation/design-system/design-system.stories.tsx`).
|
||||
|
||||
## Product Principles
|
||||
|
||||
1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다.
|
||||
2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다.
|
||||
3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복제하지 않습니다.
|
||||
4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다.
|
||||
5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다.
|
||||
1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것이다. 둘을 섞지 않는다.
|
||||
2. 브랜드는 토큰으로만 바꾼다. 컴포넌트에 브랜드 값을 직접 넣지 않는다.
|
||||
3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절한다. 컴포넌트를 서비스 종류별로 복제하지 않는다.
|
||||
4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값이다.
|
||||
5. 한국어가 기본이고 영어를 함께 지원한다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 한다.
|
||||
|
||||
## Accessibility & Inclusion
|
||||
|
||||
WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킵니다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있습니다(`docs/accessibility/manual-checklist.md`).
|
||||
WCAG 2.2 AA를 기준으로 한다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킨다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있다(`docs/accessibility/manual-checklist.md`).
|
||||
|
||||
@@ -1,31 +1,31 @@
|
||||
# Manual accessibility review checklist
|
||||
# 수동 접근성 리뷰 체크리스트
|
||||
|
||||
Automated axe checks do not establish WCAG conformance. A human reviewer must
|
||||
review every route record in `artifacts/tests/a11y-manual/` against one
|
||||
release candidate and sign them. The required scope is the route registry
|
||||
(`ROUTE_REGISTRY` in `src/features/installed-feature-contracts.ts`): one
|
||||
record per route, named `<ROUTE_ID>.md`. Copy the template fields exactly; the
|
||||
gate rejects blank identity/timestamp/signature fields, pending verdicts,
|
||||
mismatched release IDs, or missing routes.
|
||||
자동 axe 검사만으로는 WCAG 준수를 증명하지 못한다. 사람 리뷰어가
|
||||
`artifacts/tests/a11y-manual/`의 route 기록을 모두 한 release 후보에 대해
|
||||
리뷰하고 서명해야 한다. 필요한 범위는 route
|
||||
registry(`src/features/installed-feature-contracts.ts`의 `ROUTE_REGISTRY`)다.
|
||||
route 하나에 기록 하나를 두고, 이름은 `<ROUTE_ID>.md`로 한다. template 필드를
|
||||
그대로 복사한다. gate는 다음을 거부한다: 비어 있는 신원·시각·서명 필드, 아직
|
||||
정하지 않은(pending) 판정, 맞지 않는 release ID, 빠진 route.
|
||||
|
||||
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
|
||||
it is required once per release candidate, not on every merge. The merge gate
|
||||
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
|
||||
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
|
||||
and a record marked `reviewed` must be complete.
|
||||
서명된 리뷰는 release gate FE-GATE-028(`review:a11y-manual`)이다. 그래서
|
||||
merge마다가 아니라 release 후보마다 한 번 필요하다. merge gate FE-GATE-009는
|
||||
`review:a11y-manual -- --format-only`를 돌린다. 각 기록은 아래 필드를 유지하고
|
||||
판정 값은 `pending`, `pass`, `not-applicable (<reason>)` 중 하나여야 한다.
|
||||
`reviewed`로 표시한 기록은 빠짐없이 채워져 있어야 한다.
|
||||
|
||||
This document keeps no route list. A list here once said six routes while ten
|
||||
were registered, and keeping it current made every new feature edit this file.
|
||||
Instead `verify:documentation` fails, naming the route ID, when a registered
|
||||
route has no record file. A new route starts from a copy of a pending record
|
||||
with its title and `Route ID` changed.
|
||||
이 문서에는 route 목록을 두지 않는다. 예전에 여기 목록이 route 6개라고 적었을 때
|
||||
실제로는 10개가 등록돼 있었다. 그리고 목록을 최신으로 유지하느라 새 feature마다
|
||||
이 파일을 고쳐야 했다. 대신 등록된 route에 기록 파일이 없으면
|
||||
`verify:documentation`이 그 route ID를 밝히며 실패한다. 새 route는 pending 기록
|
||||
하나를 복사하고 제목과 `Route ID`만 바꿔서 시작한다.
|
||||
|
||||
Allowed item verdicts:
|
||||
항목에 쓸 수 있는 판정:
|
||||
|
||||
- `pass`
|
||||
- `not-applicable (<specific reason>)`
|
||||
|
||||
Required record:
|
||||
필수 기록:
|
||||
|
||||
```text
|
||||
Status: reviewed
|
||||
@@ -46,39 +46,37 @@ Screen reader: pass
|
||||
Notes: <observations and linked defect IDs>
|
||||
```
|
||||
|
||||
The reviewer must verify:
|
||||
리뷰어가 확인해야 할 것:
|
||||
|
||||
- M1: every action works without a pointing device
|
||||
- M2: every focused element has a visible indicator
|
||||
- M3: route transitions move focus to a deterministic target
|
||||
- M4: modal focus is trapped and restored, when a modal exists
|
||||
- M5: errors are programmatically associated with their controls, when present
|
||||
- M6: state never relies on color alone
|
||||
- M7: non-essential motion is suppressed with reduced-motion preference
|
||||
- Screen reader: headings, live regions, errors, and actions are announced once
|
||||
- M1: 모든 동작이 포인팅 장치 없이 된다
|
||||
- M2: focus를 받은 모든 요소에 눈에 보이는 표시가 있다
|
||||
- M3: route가 바뀌면 focus가 정해진 대상으로 옮겨 간다
|
||||
- M4: modal이 있으면 focus가 modal 안에 갇히고, 닫으면 원래 자리로 돌아간다
|
||||
- M5: 오류가 있으면 해당 입력 요소와 프로그램으로 연결돼 있다
|
||||
- M6: 상태를 색으로만 나타내지 않는다
|
||||
- M7: 동작 줄이기(reduced-motion) 설정이 켜지면 꼭 필요하지 않은 움직임을 멈춘다
|
||||
- Screen reader: 제목, live region, 오류, 동작이 한 번씩 읽힌다
|
||||
|
||||
A route with a form or a dialog requires real M4 modal and M5 field-error
|
||||
review; those items must not be marked not-applicable on that route. Passing automated evidence means
|
||||
only that tested pages had no critical or serious axe findings under the
|
||||
recorded Chromium, Firefox, and WebKit runs.
|
||||
form이나 dialog가 있는 route는 M4 modal 리뷰와 M5 필드 오류 리뷰를 실제로 해야
|
||||
한다. 그런 route에서는 그 항목을 not-applicable로 표시하면 안 된다. 자동 증거가
|
||||
통과했다는 것은 이것만 뜻한다: 기록된 Chromium, Firefox, WebKit 실행에서
|
||||
테스트한 페이지에 critical이나 serious 등급의 axe 발견이 없었다.
|
||||
|
||||
What the automated run scans:
|
||||
자동 실행이 검사하는 것:
|
||||
|
||||
- Every registered route, after the route's own `h1` is on screen, so the scan
|
||||
never lands on the app shell's loading surface
|
||||
(`tests/e2e/accessibility.spec.ts`). A public route's `h1` must equal its
|
||||
catalog title.
|
||||
- Protected routes after the demo sign-in, never the sign-in prompt. A list
|
||||
read answers an empty list in the frame its descriptor declares (inside the
|
||||
Envelope for `responseEnvelope: "ENVELOPE_V1"`), and the scan runs only once
|
||||
no alert box is on screen, so a list page is scanned in its empty state. A
|
||||
read of one resource (a detail page) has no generic answer: that route is
|
||||
scanned in its failure state and the run records an `a11y-data-state`
|
||||
annotation. `a11y.json` lists it under `notChecked`. When a protected
|
||||
route's `paramsSchema` is the input of such a read, the report expects that
|
||||
record from the descriptors alone and fails without it
|
||||
(`scripts/write-a11y-report.ts`).
|
||||
- The list of the feature `create:feature` writes, in its success, empty and
|
||||
error states, its detail and its form with submit errors, each after that
|
||||
state is on screen (`tests/e2e/generated-feature.spec.ts`, on a build with
|
||||
that feature). A product's own features get the route scan above.
|
||||
- 등록된 모든 route. route 자신의 `h1`이 화면에 나온 뒤 검사한다. 그래서 앱 셸의
|
||||
로딩 화면을 검사하는 일이 없다(`tests/e2e/accessibility.spec.ts`). 공개
|
||||
route의 `h1`은 catalog 제목과 같아야 한다.
|
||||
- 보호된 route는 데모 로그인 뒤에 검사하고, 로그인 안내 화면은 검사하지 않는다.
|
||||
목록 읽기에는 빈 목록이 응답으로 온다. 그 응답은 descriptor가 선언한 frame에
|
||||
담긴다(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope 안). 검사는 화면에
|
||||
alert 상자가 없을 때만 돈다. 그래서 목록 페이지는 빈 상태로 검사된다. 자원
|
||||
하나를 읽는 경우(상세 페이지)에는 범용 응답이 없다. 그런 route는 실패 상태로
|
||||
검사하고, 실행이 `a11y-data-state` annotation을 기록한다. `a11y.json`은 그
|
||||
route를 `notChecked` 아래에 적는다. 보호된 route의 `paramsSchema`가 그런
|
||||
읽기의 입력이면, 보고서는 descriptor만 보고 그 기록이 있어야 한다고 판단하고,
|
||||
없으면 실패한다(`scripts/write-a11y-report.ts`).
|
||||
- `create:feature`가 만드는 feature의 목록(성공·빈·오류 상태), 상세, 제출 오류가
|
||||
난 form. 각 상태가 화면에 나온 뒤
|
||||
검사한다(`tests/e2e/generated-feature.spec.ts`, 그 feature가 들어간 빌드에서).
|
||||
제품이 직접 만든 feature는 위의 route 검사를 받는다.
|
||||
|
||||
@@ -1,80 +1,82 @@
|
||||
# Contract compatibility and rollback rules
|
||||
# 계약 호환성과 rollback 규칙
|
||||
|
||||
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
|
||||
assetManifestHash, releaseId)`. Versions are parsed numerically.
|
||||
차단 기준이 되는 tuple은 `(buildId, configSchemaVersion, apiContractVersion,
|
||||
assetManifestHash, releaseId)`이다. version은 숫자로 파싱한다.
|
||||
|
||||
1. a change is additive only when it adds an optional field that every
|
||||
reader of the previous version tolerates; see the boundary table below
|
||||
2. breaking changes require a major version bump or a reader-first deployment
|
||||
3. persisted cache is discarded unless an explicit tested migration exists
|
||||
4. an incompatible config or API contract blocks product mount
|
||||
5. rollback restores HTML, assets, runtime config, API compatibility, and
|
||||
release manifest as one coherent set
|
||||
1. 변경이 추가(additive)로 인정되는 것은 이전 version의 모든 reader가 받아들이는
|
||||
선택 필드를 더할 때뿐이다. 아래 경계별 표를 본다
|
||||
2. 깨지는(breaking) 변경은 major version을 올리거나 reader를 먼저 배포해야 한다
|
||||
3. 저장된 cache는 테스트된 명시적 migration이 없으면 버린다
|
||||
4. 호환되지 않는 config나 API 계약은 제품 mount를 막는다
|
||||
5. rollback은 HTML, asset, runtime config, API 호환성, release manifest를 하나의
|
||||
일관된 묶음으로 되돌린다
|
||||
|
||||
## Per-boundary rules
|
||||
## 경계별 규칙
|
||||
|
||||
Whether "add a field" is safe depends on the reader, not on the writer. Old
|
||||
readers stay alive: several tabs, cached app shells and rollbacks are all
|
||||
supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the
|
||||
reader that accepts it must ship before any writer sends it.
|
||||
"필드 추가"가 안전한지는 쓰는 쪽(writer)이 아니라 읽는 쪽(reader)에 달려 있다.
|
||||
옛 reader는 계속 살아 있다. 여러 탭, cache된 앱 셸, rollback을 모두 지원하기
|
||||
때문이다. `REJECT_UNKNOWN` 경계에서는 필드를 더하면 깨진다. 그래서 그 필드를
|
||||
받아들이는 reader를 먼저 배포해야 한다. 어떤 writer든 그 뒤에야 그 필드를 보낼
|
||||
수 있다.
|
||||
|
||||
| Boundary | Reader policy | Adding a field or value | Code |
|
||||
| 경계 | reader 정책 | 필드나 값 추가 | 코드 |
|
||||
|---|---|---|---|
|
||||
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `runtimeConfigV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `capabilityOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| HTTP success/failure envelope (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/backend-envelope.ts` |
|
||||
| HTTP V3 response DTO (a feature's) | `.strip()` drops unknown fields | additive | `<camel>ItemDtoSchema` in `contracts/<base>-schemas.ts` of a feature `create:feature` writes |
|
||||
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` |
|
||||
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` |
|
||||
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` |
|
||||
| Runtime config V2 (`/config.json`) | 엄격한(strict) object. `CONFIG_SCHEMA_VERSION`은 리터럴 `"2.0"` | 깨짐 | `src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema` |
|
||||
| `CAPABILITY_OVERRIDES` | 엄격함. 모르는 capability는 거부 | 깨짐 | `src/contracts/release-artifacts.ts`의 `capabilityOverrideArtifactSchema` |
|
||||
| `FEATURE_OVERRIDES` | record. 모르는 feature id는 무시 | 추가로 인정 | `src/contracts/release-artifacts.ts`의 `featureOverrideArtifactSchema` |
|
||||
| Release manifest V2 | 엄격한 object | 깨짐 | `src/contracts/release-artifacts.ts`의 `releaseManifestV2ArtifactSchema` |
|
||||
| HTTP 성공·실패 envelope (V3에서 `responseEnvelope: "ENVELOPE_V1"`) | 엄격한 object(`meta`는 걸러 냄) | 깨짐 | `src/adapters/http/backend-envelope.ts`의 `successEnvelopeSchema`, `failureEnvelopeSchema` |
|
||||
| HTTP V3 응답 DTO (feature의 것) | `.strip()`이 모르는 필드를 버림 | 추가로 인정 | `create:feature`가 만드는 feature의 `contracts/<base>-schemas.ts`에 있는 `<camel>ItemDtoSchema` |
|
||||
| Realtime envelope | 정확한 key 집합. 모르는 `eventType`은 `MALFORMED_EVENT` | 깨짐 | `src/adapters/realtime/event-codec.ts`의 `decodeUnsafe` |
|
||||
| Browser RPC 전송 오류 code | 닫힌 어휘. 모르는 code는 protocol 위반 | 깨짐 | `src/adapters/browser-rpc/browser-rpc-runtime.ts`의 `decodeTransportFailure` |
|
||||
| 저장된 클라이언트 storage | version이 붙은 key. 호환되지 않는 값은 버림 | 새 key version을 쓴다 | `src/contracts/storage-keys.ts`의 `defineStorageKey` |
|
||||
|
||||
Turning a response DTO strict changes its row in this table. `check:registries`
|
||||
grades it as breaking (`response-reader-narrowed`) when the FE-REG-SCHEMA row
|
||||
of a `RESPONSE` schema goes from `STRIP_UNKNOWN` to `REJECT_UNKNOWN`, so the
|
||||
change needs registry evidence (1105/07-02).
|
||||
응답 DTO를 엄격하게 바꾸면 이 표에서 그 행이 바뀐다. `RESPONSE` schema의
|
||||
FE-REG-SCHEMA 행이 `STRIP_UNKNOWN`에서 `REJECT_UNKNOWN`으로 바뀌면
|
||||
`check:registries`가 이를 깨지는 변경(`response-reader-narrowed`)으로 판정한다.
|
||||
그래서 그 변경에는 registry 증거가 필요하다(1105/07-02).
|
||||
|
||||
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
|
||||
vary per build because each downstream project installs its own features, and
|
||||
one shared config document may cover several builds. The capability set is
|
||||
fixed by the platform version, so an unknown capability means the config was
|
||||
written for a newer platform; it is treated like any other strict config
|
||||
addition.
|
||||
`CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`는 일부러 다르게 둔다. feature id는
|
||||
빌드마다 다르다. 다운스트림 프로젝트마다 자기 feature를 설치하기 때문이다.
|
||||
그리고 공유 config 문서 하나가 여러 빌드를 덮을 수 있다. capability 집합은
|
||||
platform version이 정한다. 그래서 모르는 capability가 있다는 것은 그 config가 더
|
||||
새 platform을 위해 쓰였다는 뜻이다. 이것은 다른 엄격한 config 추가와 똑같이
|
||||
다룬다.
|
||||
|
||||
## Schema change classifier and FE-GATE-014
|
||||
## Schema 변경 분류기와 FE-GATE-014
|
||||
|
||||
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts`) answers
|
||||
for a reader built against `before`. It is fail-closed: only a new property
|
||||
under a reader without `additionalProperties: false` is `additive`. A removed
|
||||
or changed property (type, enum, nullable, format, ...), a different required
|
||||
set, or any other changed keyword is `breaking`. Nothing differs: `none`.
|
||||
`classifyObjectSchemaChange`(`src/contracts/compatibility.ts`)는 `before`를
|
||||
기준으로 만든 reader 입장에서 답한다. fail closed로 동작한다:
|
||||
`additionalProperties: false`가 없는 reader 아래에 새 property를 더한 경우만
|
||||
`additive`다. property를 지우거나 바꾸는 것(type, enum, nullable, format 등),
|
||||
required 집합이 달라지는 것, 그 밖의 keyword가 바뀌는 것은 모두 `breaking`이다.
|
||||
아무것도 다르지 않으면 `none`이다.
|
||||
|
||||
FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`)
|
||||
runs `scripts/check-compatibility.ts`. It does two things:
|
||||
FE-GATE-014(`config-compatibility`, `corepack pnpm verify:compatibility`)는
|
||||
`scripts/check-compatibility.ts`를 실행한다. 이 스크립트는 두 가지를 한다.
|
||||
|
||||
1. Classifies the hand-written cases in `config/compatibility/fixtures.json`
|
||||
and fails if any result differs from `expected`.
|
||||
2. Compares the committed baseline
|
||||
`config/compatibility/runtime-config.schema.baseline.json` with the current
|
||||
runtime config schema, which is the same `z.toJSONSchema` output the build
|
||||
writes to `dist/runtime-config.schema.json`
|
||||
(`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate.
|
||||
1. `config/compatibility/fixtures.json`에 손으로 쓴 사례를 분류하고, 결과가
|
||||
하나라도 `expected`와 다르면 실패한다.
|
||||
2. commit된 기준선 `config/compatibility/runtime-config.schema.baseline.json`을
|
||||
지금 runtime config schema와 비교한다. 지금 schema는 빌드가
|
||||
`dist/runtime-config.schema.json`에 쓰는 것과 같은 `z.toJSONSchema`
|
||||
출력이다(`scripts/generate-build-manifest.ts`). 결과가 `breaking`이면 gate가
|
||||
실패한다.
|
||||
|
||||
The baseline stands for the schema that readers of the previous release
|
||||
accept. When a breaking config change is intended, deploy the reader first (or
|
||||
bump the config major version), then run
|
||||
`corepack pnpm verify:compatibility --update-baseline` and commit the new
|
||||
baseline with the change. The result is recorded in
|
||||
`artifacts/release/compatibility.json`.
|
||||
기준선은 이전 release의 reader가 받아들이는 schema를 나타낸다. 깨지는 config
|
||||
변경을 의도했다면 reader를 먼저 배포한다(또는 config major version을 올린다).
|
||||
그다음 `corepack pnpm verify:compatibility --update-baseline`을 실행하고, 새
|
||||
기준선을 변경과 함께 commit한다. 결과는 `artifacts/release/compatibility.json`에
|
||||
기록된다.
|
||||
|
||||
The current `apiContractVersion` check proves release/config coherence, not
|
||||
provider conformance by itself. The target multi-protocol contract set binds
|
||||
REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests,
|
||||
protobuf source/descriptors/codegen profiles, Connect/gRPC-Web provider profiles,
|
||||
ProtoJSON/HttpRule/generated OpenAPI/gateway artifacts, runtime schema/mapper
|
||||
registries, and server-state policy digests as defined in
|
||||
[API contract, Schema, Mapper, and Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md).
|
||||
Browser Protobuf and REST Gateway compatibility is further split in
|
||||
[Protobuf browser transport and REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md);
|
||||
binary/JSON/HTTP-route compatibility gates are not interchangeable.
|
||||
지금의 `apiContractVersion` 검사는 release와 config가 서로 맞는다는 것을
|
||||
증명한다. 그것만으로 provider가 계약을 지킨다는 것까지 증명하지는 않는다. 목표로
|
||||
하는 다중 protocol 계약 묶음은
|
||||
[API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)에
|
||||
정의된 대로 다음을 묶는다: REST/OpenAPI artifact, GraphQL schema와
|
||||
persisted-operation manifest, protobuf source·descriptor·codegen profile,
|
||||
Connect/gRPC-Web provider profile, ProtoJSON·HttpRule·생성된 OpenAPI·gateway
|
||||
artifact, runtime schema·mapper registry, server-state 정책 digest.
|
||||
브라우저 Protobuf와 REST Gateway 호환성은
|
||||
[Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)에서
|
||||
더 나눈다. binary·JSON·HTTP route 호환성 gate는 서로 바꿔 쓸 수 없다.
|
||||
|
||||
+26
-25
@@ -1,32 +1,33 @@
|
||||
# FE-RB-001 — Boot configuration failure
|
||||
# FE-RB-001 — 부트 설정 실패
|
||||
|
||||
Trigger on `BOOT_CONFIG_FAILURE` after the single bounded refetch fails. Stop
|
||||
product route mounting and show the safe support shell; the planned owner
|
||||
triage target is five minutes. Escalate from the environment/config owner to
|
||||
the release owner.
|
||||
`BOOT_CONFIG_FAILURE`가 나고, 한 번만 허용된 재요청(refetch)도 실패하면 이
|
||||
runbook을 시작한다. 제품 route를 mount하지 않고 안전한 지원 화면(support
|
||||
shell)을 보여 준다. owner가 원인을 가르는(triage) 계획 목표 시간은 5분이다.
|
||||
환경·설정 owner에서 release owner로 올린다(escalate).
|
||||
|
||||
Close only after a clean-session boot mounts the product root, config
|
||||
validation evidence passes, and repeated boot-error telemetry is absent.
|
||||
깨끗한 세션에서 부트했을 때 제품 root가 mount되고, 설정 검증 증거가 통과하고,
|
||||
부트 오류 telemetry가 다시 나오지 않을 때만 닫는다.
|
||||
|
||||
## Changing an emergency switch without a rebuild
|
||||
## 다시 빌드하지 않고 긴급 스위치 바꾸기
|
||||
|
||||
Only `CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` may change in a deployed
|
||||
`config.json`. Every browser validates the document on boot, so a typo there
|
||||
causes this runbook's failure for every user. Change it in four steps:
|
||||
배포된 `config.json`에서 바꿔도 되는 것은 `CAPABILITY_OVERRIDES`와
|
||||
`FEATURE_OVERRIDES`뿐이다. 모든 브라우저가 부트할 때 이 문서를 검증한다. 그래서
|
||||
여기에 오타가 있으면 모든 사용자에게 이 runbook의 실패가 난다. 네 단계로 바꾼다.
|
||||
|
||||
1. Download the deployed `config.json` twice, as `deployed.json` (keep it as
|
||||
is) and `edited.json`. Change only the switch in `edited.json`.
|
||||
2. From a checkout of the deployed commit, run
|
||||
1. 배포된 `config.json`을 두 번 내려받는다. 하나는 `deployed.json`(손대지 않고
|
||||
둔다), 다른 하나는 `edited.json`이다. `edited.json`에서 스위치만 바꾼다.
|
||||
2. 배포된 commit을 checkout한 곳에서 다음을 실행한다.
|
||||
`RELEASE_TARGET=<environment> corepack pnpm check:release-admission --config /abs/edited.json --original /abs/deployed.json`
|
||||
(absolute paths: pnpm runs it from the repository root). It must print
|
||||
`ADMITTED`. It refuses a schema error, a target rule, and any changed field
|
||||
other than the two switches, `BUILD_ID` and `RELEASE_ID` included.
|
||||
3. Upload `edited.json` next to the live file and rename it over
|
||||
`config.json` on the same filesystem. Never edit the live file in place.
|
||||
To undo, rename `deployed.json` back the same way.
|
||||
4. Boot in a clean session (new browser profile) and see the product root
|
||||
mount. The switch takes effect on the next boot only.
|
||||
절대 경로를 쓴다. pnpm이 이 명령을 repository root에서 실행하기 때문이다.
|
||||
출력은 `ADMITTED`여야 한다. 이 명령은 schema 오류, target 규칙 위반, 두
|
||||
스위치 말고 바뀐 필드를 모두 거부한다. 바뀐 필드에는 `BUILD_ID`와
|
||||
`RELEASE_ID`도 들어간다.
|
||||
3. `edited.json`을 live 파일 옆에 올린다. 그다음 같은 파일 시스템 안에서 이름을
|
||||
바꿔 `config.json`을 덮어쓴다. live 파일을 그 자리에서 고치지 않는다. 되돌릴
|
||||
때는 같은 방법으로 `deployed.json`의 이름을 다시 바꾼다.
|
||||
4. 깨끗한 세션(새 브라우저 프로필)에서 부트하고 제품 root가 mount되는지 본다.
|
||||
스위치는 다음 부트부터만 적용된다.
|
||||
|
||||
The served document then differs from the release record (`checksums.txt`,
|
||||
the promoted archive). Note the change in the release log, and put it in the
|
||||
profile (`config/runtime/<environment>.json`) for the next build.
|
||||
그러면 서빙되는 문서가 release 기록(`checksums.txt`, promotion된 archive)과
|
||||
달라진다. release 로그에 이 변경을 적는다. 다음 빌드를 위해
|
||||
프로필(`config/runtime/<environment>.json`)에도 넣는다.
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
# FE-RB-002 — Chunk or deployment mismatch
|
||||
# FE-RB-002 — chunk 또는 배포 불일치
|
||||
|
||||
Trigger on `CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, or
|
||||
`DEPLOY_MISMATCH`. Warn when dirty state may be lost, fetch the manifest
|
||||
`no-store` once, record the release pair, and allow only one reload. The
|
||||
planned release-owner triage target is five minutes. Escalate to the hosting/CDN
|
||||
owner.
|
||||
`CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, `DEPLOY_MISMATCH` 중 하나가
|
||||
나면 시작한다. 저장하지 않은 상태(dirty state)를 잃을 수 있으면 경고한다.
|
||||
manifest를 `no-store`로 한 번 가져오고, release 쌍을 기록하고, 새로고침은 한
|
||||
번만 허용한다. release owner가 원인을 가르는(triage) 계획 목표 시간은 5분이다.
|
||||
hosting/CDN owner에게 올린다(escalate).
|
||||
|
||||
Close only after entry/lazy assets are reachable, the manifest parses into a
|
||||
coherent tuple, a second automatic reload is blocked, and the critical route
|
||||
smoke passes.
|
||||
다음이 모두 맞을 때만 닫는다. entry·lazy asset에 접근할 수 있다. manifest가 서로
|
||||
맞는 tuple로 파싱된다. 두 번째 자동 새로고침이 막힌다. 핵심 route smoke가
|
||||
통과한다.
|
||||
|
||||
@@ -1,10 +1,11 @@
|
||||
# FE-RB-003 — Backend API degradation
|
||||
# FE-RB-003 — 백엔드 API 품질 저하
|
||||
|
||||
Trigger when terminal network/timeout/5xx failures exceed the rolling
|
||||
five-minute threshold or on one `SCHEMA_MISMATCH`. Do not expand client retry
|
||||
caps, do not retry schema mismatches, and never retry an unkeyed mutation.
|
||||
Escalate from the API client owner to backend operations and then release
|
||||
compatibility; the planned first-classification target is ten minutes.
|
||||
다음 중 하나면 시작한다. 더 재시도하지 않는(terminal) 네트워크·시간 초과·5xx
|
||||
실패가 최근 5분 이동 구간(rolling)의 기준치를 넘는다. 또는 `SCHEMA_MISMATCH`가
|
||||
한 번 난다. 클라이언트 재시도 상한을 늘리지 않는다. schema 불일치는 재시도하지
|
||||
않는다. 멱등 키가 없는 mutation(unkeyed mutation)은 절대 재시도하지 않는다. API
|
||||
client owner에서 백엔드 운영으로, 그다음 release 호환성 담당으로
|
||||
올린다(escalate). 첫 분류의 계획 목표 시간은 10분이다.
|
||||
|
||||
Close only after the failure rate returns to baseline, retry amplification is
|
||||
absent, critical read/write smoke passes, and schema fixtures pass.
|
||||
다음이 모두 맞을 때만 닫는다. 실패율이 평소 수준(baseline)으로 돌아온다. 재시도
|
||||
증폭이 없다. 핵심 읽기·쓰기 smoke가 통과한다. schema fixture가 통과한다.
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
# FE-RB-004 — Telemetry sink failure
|
||||
# FE-RB-004 — telemetry sink 실패
|
||||
|
||||
Trigger on sink network/non-2xx errors, queue overflow, or adapter
|
||||
initialization failure. Keep product flows available, bound the queue, and do
|
||||
not recursively report to the failed sink. Escalate from observability to the
|
||||
telemetry platform owner; the planned triage target is fifteen minutes.
|
||||
sink로 보낼 때 네트워크 오류나 2xx가 아닌 응답이 나거나, 큐가 넘치거나, adapter
|
||||
초기화가 실패하면 시작한다. 제품 흐름은 계속 쓸 수 있게 둔다. 큐 길이에 상한을
|
||||
둔다. 실패한 sink에 그 실패를 다시 보고하지 않는다(재귀 보고 금지).
|
||||
observability 담당에서 telemetry 플랫폼 owner로 올린다(escalate). 원인을
|
||||
가르는(triage) 계획 목표 시간은 15분이다.
|
||||
|
||||
Close only after product e2e remains unaffected, delivery self-check succeeds,
|
||||
the queue drains within its bound, and the forbidden-attribute scan passes.
|
||||
다음이 모두 맞을 때만 닫는다. 제품 e2e가 영향을 받지 않는다. 전송 자체
|
||||
점검(self-check)이 성공한다. 큐가 상한 안에서 비워진다. 금지 속성 검사가
|
||||
통과한다.
|
||||
|
||||
+17
-15
@@ -1,18 +1,20 @@
|
||||
# FE-RB-005 — Coherent release rollback
|
||||
# FE-RB-005 — 일관된 release rollback
|
||||
|
||||
Trigger on a release-blocking boot, chunk, render, API, or security defect when
|
||||
a safe forward fix is not demonstrated inside the incident window. Select a
|
||||
prior immutable release, verify its asset/config/API tuple, atomically switch
|
||||
the complete set, perform the provider cache action, and run smoke checks.
|
||||
Escalate from the release-cache owner to the release approver/hosting owner.
|
||||
The provider recovery target remains TBD until hosting is selected.
|
||||
release를 막는 결함(부트, chunk, 렌더링, API, 보안)이 났는데 사고 대응
|
||||
시간(incident window) 안에 안전한 forward fix(앞으로 고치는 수정)가 증명되지
|
||||
않으면 시작한다. 바뀌지 않는(immutable) 이전 release 하나를 고르고, 그 release의
|
||||
asset·config·API tuple을 검증한다. 전체 묶음을 한 번에(atomic) 바꾸고,
|
||||
provider의 cache 조치를 하고, smoke 검사를 돌린다. release-cache owner에서
|
||||
release 승인자·hosting owner로 올린다(escalate). provider 복구 목표 시간은
|
||||
hosting을 고를 때까지 미정(TBD)이다.
|
||||
|
||||
Close only when compatibility and release-coherence gates pass, critical smoke
|
||||
passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
|
||||
the restored release ID. Pointer-switch or cache-purge completion alone is not
|
||||
recovery evidence.
|
||||
다음이 모두 맞을 때만 닫는다. 호환성 gate와 release 일관성 gate가 통과한다. 핵심
|
||||
smoke가 통과한다. `DEPLOY_MISMATCH`가 반복되지 않는다. 사고 타임라인에 복원한
|
||||
release ID가 기록된다. pointer 전환이나 cache purge가 끝났다는 것만으로는 복구
|
||||
증거가 되지 않는다.
|
||||
|
||||
Verify the prior release before switching to it: `verify:promotion -- --root
|
||||
<bundle> --archived` and `drill:runbook -- FE-RB-005 --release-root <extracted
|
||||
archive>`. The commands and inputs are in
|
||||
[`docs/operations/release-cache-rollback.md`](../operations/release-cache-rollback.md).
|
||||
이전 release로 바꾸기 전에 그 release를 검증한다. `verify:promotion -- --root
|
||||
<bundle> --archived`와 `drill:runbook -- FE-RB-005 --release-root <extracted
|
||||
archive>`를 쓴다. 명령과 입력은
|
||||
[`docs/operations/release-cache-rollback.md`](../operations/release-cache-rollback.md)에
|
||||
있다.
|
||||
|
||||
@@ -1,28 +1,28 @@
|
||||
# Browser security boundary
|
||||
# 브라우저 보안 경계
|
||||
|
||||
The browser bundle is public. Secrets, token lifecycle, raw HTML injection,
|
||||
dynamic code execution, untrusted script URLs, and public production source
|
||||
maps are prohibited defaults.
|
||||
브라우저 bundle은 공개된다. 그래서 다음은 기본으로 금지한다: 비밀값, 토큰 수명
|
||||
주기 관리, raw HTML 주입, 동적 코드 실행, 믿을 수 없는 script URL, 공개된
|
||||
production source map.
|
||||
|
||||
`config/hosting/security-headers.json` is the declared header set. Hosting
|
||||
verification compares that declaration with live responses. CSP deliberately
|
||||
omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
|
||||
remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of
|
||||
`test:e2e`, FE-GATE-008) serves the build with these headers and fails on a
|
||||
`securitypolicyviolation` event or console error (review 13-08). zod probes
|
||||
`Function("")` on its first object schema, which the policy would report on
|
||||
every boot. `src/contracts/zod.ts` sets `jitless` to skip that probe, and every
|
||||
module that builds a schema imports `z` from there, so the setting is applied
|
||||
before the first schema whatever order the bundler evaluates chunks in.
|
||||
`z.config` in the entry module would be too late. Import `z` from
|
||||
`src/contracts/zod.ts`, not from `zod`, in new schema code. Features that are off by
|
||||
default need CSP additions when a project selects them; see step 9 in
|
||||
[optional adapter recipes](../architecture/optional-adapter-recipes.md).
|
||||
`connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to
|
||||
the runtime config's `API_BASE_URL` and `TELEMETRY_ENDPOINT` origins needs a
|
||||
header generated per environment at deploy time, because those values are set
|
||||
per deployment (`scripts/generate-runtime-config.ts`). That generator does not
|
||||
exist yet; a project that deploys should add it with its provider adapter.
|
||||
선언된 header 집합은 `config/hosting/security-headers.json`이다. hosting 검증은
|
||||
이 선언과 실제 응답을 비교한다. CSP는 일부러 `unsafe-inline`과 `unsafe-eval`을
|
||||
뺀다. production 코드와 빌드된 asset은 이 기준선에서도 동작해야 한다.
|
||||
`tests/e2e/production-csp.spec.ts`(`test:e2e`의 일부, FE-GATE-008)는 이 header로
|
||||
빌드를 서빙한다. 그리고 `securitypolicyviolation` 이벤트나 console 오류가 나면
|
||||
실패한다(리뷰 13-08). zod는 첫 object schema에서 `Function("")`을 시험 삼아
|
||||
실행한다. 그러면 정책이 부트할 때마다 이것을 위반으로 보고한다.
|
||||
`src/contracts/zod.ts`는 `jitless`를 켜서 이 시험을 건너뛴다. schema를 만드는
|
||||
모든 모듈은 `z`를 그 파일에서 import한다. 그래서 bundler가 chunk를 어떤 순서로
|
||||
평가하든 이 설정이 첫 schema보다 먼저 적용된다. entry 모듈에서 `z.config`를
|
||||
부르면 너무 늦다. 새 schema 코드에서는 `z`를 `zod`가 아니라
|
||||
`src/contracts/zod.ts`에서 import한다. 기본으로 꺼진 기능은 프로젝트가 그 기능을
|
||||
고를 때 CSP에 항목을 더해야 한다.
|
||||
[선택형 adapter recipe](../architecture/optional-adapter-recipes.md)의 9단계를 본다.
|
||||
`connect-src 'self' https:`는 script가 모든 HTTPS origin에 닿게 둔다. 이것을
|
||||
runtime config의 `API_BASE_URL`과 `TELEMETRY_ENDPOINT` origin으로 좁히려면
|
||||
배포할 때 환경마다 header를 만들어야 한다. 그 값들은 배포마다 정해지기
|
||||
때문이다(`scripts/generate-runtime-config.ts`). 그런 header 생성기는 아직 없다.
|
||||
배포하는 프로젝트는 provider adapter를 만들 때 함께 더해야 한다.
|
||||
|
||||
Route guards are UX hints and client validation does not replace backend
|
||||
authorization or validation.
|
||||
route guard는 UX 힌트일 뿐이다. 클라이언트 검증은 백엔드의 인가(authorization)나
|
||||
검증을 대신하지 않는다.
|
||||
|
||||
+253
-264
@@ -1,30 +1,31 @@
|
||||
# Build and supply-chain gate
|
||||
# 빌드·공급망 gate
|
||||
|
||||
## Local blocking controls
|
||||
## 로컬 차단 통제
|
||||
|
||||
- `pnpm install --frozen-lockfile --ignore-scripts` and a real manifest/lock
|
||||
mismatch fixture; contract loading applies the root-only graph and lifecycle
|
||||
policy to every registered command before the gate runner can spawn one, and
|
||||
rejects nested installs without effective `--ignore-scripts`; npm script
|
||||
traversal includes existing pre/post hooks unless an ordered bare or explicit
|
||||
true `--ignore-scripts` suppresses them. Workspace/prefix and indirect
|
||||
user/global config authority are rejected in npm options, direct or dynamic
|
||||
assignments, exact `command`/`exec`/`env` prefix chains, cross-segment shell
|
||||
state, and the inherited runner environment. Unknown or cwd-changing `env`
|
||||
options and unquoted pre-delimiter pathname expansion fail closed, while the
|
||||
explicitly modeled non-scope `env` options remain usable
|
||||
- all direct and transitive lockfile rows with package SHA-512 integrity
|
||||
- production/development, direct/transitive and platform-optional classification
|
||||
- package-manifest license allow/deny policy
|
||||
- approved inventory baseline digest and actual add/remove/change/upgrade diff
|
||||
- independent review for new direct production dependencies
|
||||
- CycloneDX 1.6 SBOM and inventory component/edge coherence
|
||||
- source/lock/SBOM/dist-linked local provenance statement
|
||||
- source, opt-in recipes, scripts, tests, tracked config/schema, public, built asset and generated
|
||||
release metadata secret scan
|
||||
- two-build `SOURCE_DATE_EPOCH` reproducibility check
|
||||
- `pnpm install --frozen-lockfile --ignore-scripts`, 그리고 manifest와 lock이
|
||||
실제로 어긋나는 fixture. contract를 읽을 때 등록된 모든 명령에 root 전용
|
||||
그래프 정책과 lifecycle 정책을 적용한다. gate runner가 명령을 띄우기 전이다.
|
||||
실제로 효력이 있는 `--ignore-scripts` 없이 하는 중첩 설치는 거부한다. npm
|
||||
script를 따라갈 때는 이미 있는 pre/post hook도 따라간다. 단, 순서상 앞에 있는
|
||||
`--ignore-scripts`가 hook을 막으면 따라가지 않는다. 값 없이 쓴(bare) 경우와
|
||||
명시적으로 true를 준 경우가 그렇다. workspace·prefix 설정 권한과 간접적인
|
||||
user·global 설정 권한은 다음 어디에 있어도 거부한다: npm 옵션, 직접 할당이나
|
||||
동적 할당, 정확한 `command`/`exec`/`env` 접두 체인, segment를 넘나드는 shell
|
||||
상태, 물려받은 runner 환경. 알 수 없거나 cwd를 바꾸는 `env` 옵션, 그리고
|
||||
구분자 앞의 따옴표 없는 경로 확장은 허용하지 않고 실패한다(fail closed).
|
||||
명시적으로 모델링한, scope와 무관한 `env` 옵션은 계속 쓸 수 있다
|
||||
- 직접·전이 의존성의 lockfile 행 전부와 각 패키지의 SHA-512 integrity
|
||||
- production/development, 직접/전이, platform 선택(platform-optional) 분류
|
||||
- 패키지 manifest license의 허용·거부 정책
|
||||
- 승인된 inventory baseline digest와 실제 추가·삭제·변경·업그레이드 diff
|
||||
- 새 직접 production 의존성에 대한 독립 리뷰
|
||||
- CycloneDX 1.6 SBOM, 그리고 inventory와의 component·edge 일치
|
||||
- source·lock·SBOM·dist를 묶은 local provenance 문서(statement)
|
||||
- secret scan. 대상은 source, 선택해서 켜는(opt-in) recipe, script, 테스트,
|
||||
추적되는 config/schema, public 폴더, 빌드된 asset, 생성된 release metadata다
|
||||
- 두 번 빌드해 비교하는 `SOURCE_DATE_EPOCH` 재현성 검사
|
||||
|
||||
The canonical commands are:
|
||||
기준 명령은 다음과 같다.
|
||||
|
||||
```bash
|
||||
corepack pnpm verify:lockfile
|
||||
@@ -34,10 +35,9 @@ corepack pnpm verify:local-evidence
|
||||
corepack pnpm check:supply-chain:fixtures
|
||||
```
|
||||
|
||||
`config/security/dependency-baseline.json` is the approved local baseline.
|
||||
Changing it requires `DEPENDENCY_BASELINE_OWNER` and
|
||||
`DEPENDENCY_BASELINE_REASON`; editing the digest or hardcoding an empty diff is
|
||||
rejected.
|
||||
승인된 로컬 baseline은 `config/security/dependency-baseline.json`이다. 이것을
|
||||
바꾸려면 `DEPENDENCY_BASELINE_OWNER`와 `DEPENDENCY_BASELINE_REASON`이 있어야
|
||||
한다. digest를 직접 고치거나 빈 diff를 하드코딩하면 거부한다.
|
||||
|
||||
## 무엇을 증명하고 무엇을 증명하지 않는가
|
||||
|
||||
@@ -55,9 +55,11 @@ rejected.
|
||||
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
|
||||
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
|
||||
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
|
||||
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
|
||||
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이
|
||||
패키지를
|
||||
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
|
||||
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로
|
||||
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야
|
||||
하므로
|
||||
(`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다.
|
||||
|
||||
## 최소 구성과 전체 구성
|
||||
@@ -74,7 +76,8 @@ workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나
|
||||
|
||||
최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가
|
||||
올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를
|
||||
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는
|
||||
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다.
|
||||
`production_gate`는
|
||||
`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영
|
||||
게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로
|
||||
`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다.
|
||||
@@ -108,262 +111,248 @@ SHA-256을 남긴다.
|
||||
archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이
|
||||
repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다.
|
||||
|
||||
## External promotion controls
|
||||
## 외부 승격(promotion) 통제
|
||||
|
||||
Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and
|
||||
`PROVENANCE_ATTESTATION_PATH`. The vulnerability report must bind both the
|
||||
exact lockfile digest and candidate `distSha256`; the provenance attestation
|
||||
must name `dist` with that same digest. Both documents use strict schemas and
|
||||
Ed25519 signatures verified with separately configured trusted public keys and
|
||||
key IDs (`VULNERABILITY_PUBLIC_KEY_PATH`, `VULNERABILITY_KEY_ID`,
|
||||
`PROVENANCE_PUBLIC_KEY_PATH`, and `PROVENANCE_KEY_ID`). Keys of another curve,
|
||||
including Ed448, are rejected even if a document labels its algorithm
|
||||
`Ed25519`. The two roles must use different key IDs and different canonical
|
||||
DER-SPKI key bytes; giving the same key two IDs is rejected.
|
||||
승격은 `VULNERABILITY_REPORT_PATH`와 `PROVENANCE_ATTESTATION_PATH`가 가리키는
|
||||
provider 파일을 읽는다. 취약점 보고서(vulnerability report)는 정확한 lockfile
|
||||
digest와 후보 `distSha256`을 둘 다 묶어야(bind) 한다. provenance attestation은
|
||||
같은 digest로 `dist`를 명시해야 한다. 두 문서 모두 엄격한 schema와 Ed25519
|
||||
서명을 쓴다. 서명은 따로 설정한 신뢰 공개 키와 key
|
||||
ID(`VULNERABILITY_PUBLIC_KEY_PATH`, `VULNERABILITY_KEY_ID`,
|
||||
`PROVENANCE_PUBLIC_KEY_PATH`, `PROVENANCE_KEY_ID`)로 검증한다. 다른 curve의 키는
|
||||
거부한다. 문서가 알고리즘을 `Ed25519`라고 적어도 Ed448 키 같은 것은 거부한다. 두
|
||||
역할은 서로 다른 key ID와 서로 다른 canonical DER-SPKI 키 바이트를 써야 한다.
|
||||
같은 키에 ID 두 개를 붙여도 거부한다.
|
||||
|
||||
`immutable_build` archives the raw `pnpm-lock.yaml`, `dist` (including hidden
|
||||
`.vite` files), the build manifest, module inventory, release verification,
|
||||
secret-scan result, and local supply-chain evidence once. The candidate
|
||||
manifest hashes the raw lockfile bytes and requires that digest to equal the
|
||||
dependency inventory's `lockfileSha256`. Before upload, the producer validates
|
||||
the manifest-bound exact archive member set and every member digest, then
|
||||
publishes the archive SHA-256 as an immutable job output. The two provider jobs
|
||||
download this same archive separately, compare that output digest, validate the
|
||||
exact member set before extracting only into isolated roots, and receive
|
||||
`CANDIDATE_LOCKFILE_PATH` and `CANDIDATE_DIST_SHA256`; configured
|
||||
`VULNERABILITY_PROVIDER_COMMAND` and `PROVENANCE_PROVIDER_COMMAND` must emit the
|
||||
signed reports. After each external command returns, provider upload validation
|
||||
rechecks the unchanged archive and extracted candidate, parses the provider JSON
|
||||
with its strict schema, and binds its dist and lockfile digests before upload.
|
||||
`immutable_build`는 다음을 한 번만 archive로 묶는다: 가공하지 않은
|
||||
`pnpm-lock.yaml`, `dist`(숨은 `.vite` 파일 포함), build manifest, module
|
||||
inventory, release 검증 결과, secret scan 결과, 로컬 공급망 증거. 후보
|
||||
manifest는 가공하지 않은 lockfile 바이트의 hash를 구하고, 그 digest가 의존성
|
||||
inventory의 `lockfileSha256`과 같기를 요구한다. 올리기 전에 만드는
|
||||
쪽(producer)은 manifest에 묶인 정확한 archive member 집합과 member마다의
|
||||
digest를 검증한다. 그다음 archive SHA-256을 바뀌지 않는 job output으로 내보낸다.
|
||||
두 provider job은 같은 archive를 각자 내려받아 그 output digest와 비교한다.
|
||||
정확한 member 집합을 검증한 뒤 격리된 root에만 풀고, `CANDIDATE_LOCKFILE_PATH`와
|
||||
`CANDIDATE_DIST_SHA256`을 받는다. 설정된 `VULNERABILITY_PROVIDER_COMMAND`와
|
||||
`PROVENANCE_PROVIDER_COMMAND`는 서명된 보고서를 내야 한다. 외부 명령이 하나 끝날
|
||||
때마다 provider upload 검증이 다음을 한다: archive와 풀어 둔 후보가 바뀌지
|
||||
않았는지 다시 확인하고, provider JSON을 엄격한 schema로 파싱하고, 올리기 전에 그
|
||||
dist digest와 lockfile digest를 묶는다.
|
||||
|
||||
If either provider input is absent, local verification remains meaningful but
|
||||
`artifacts/security/supply-chain-verification.json` records
|
||||
`promotionStatus: FAIL_UNVERIFIED`. The finalizer and downstream
|
||||
`verify:promotion` exact-five validator then exit non-zero. Promotion derives
|
||||
the candidate file set and digests only from the captured tar bytes, then
|
||||
read-only revalidates archived executable schemas, archived policy/verifier
|
||||
source bytes, raw lockfile, module inventory, build outputs, release coherence,
|
||||
SBOM, provenance and supply-chain coherence. Candidate-internal checks are
|
||||
recomputed; for the checkout-dependent secret scan, promotion independently
|
||||
checks the archived policy, exact rule set, strict SARIF, zero findings and all
|
||||
manifest/assessment digest bindings. It does not claim to rescan source bytes
|
||||
that are not candidate members. It never rebuilds or rewrites candidate
|
||||
evidence and never falls back to the checkout tree.
|
||||
Promotion uploads the already verified archive itself with the two provider
|
||||
reports and generated verification records; it does not create a replacement
|
||||
archive from extracted files. Scanner or signing outages are not converted to
|
||||
an empty PASS.
|
||||
provider 입력이 하나라도 없으면 로컬 검증은 여전히 의미가 있다. 다만
|
||||
`artifacts/security/supply-chain-verification.json`에
|
||||
`promotionStatus: FAIL_UNVERIFIED`가 기록된다. 그러면 finalizer와 뒤에 오는
|
||||
`verify:promotion` exact-five 검증기가 0이 아닌 코드로 끝난다. 승격은 후보 파일
|
||||
집합과 digest를 붙잡아 둔(captured) tar 바이트에서만 얻는다. 그다음 읽기
|
||||
전용으로 다음을 다시 검증한다: archive에 든 실행 schema, archive에 든
|
||||
policy·verifier source 바이트, 가공하지 않은 lockfile, module inventory, build
|
||||
출력, release 일관성, SBOM, provenance, 공급망 일관성. 후보 내부 검사는 다시
|
||||
계산한다. checkout에 따라 달라지는 secret scan은 승격이 따로 확인한다: archive에
|
||||
든 policy, 정확한 rule 집합, 엄격한 SARIF, 발견 0건, manifest·assessment digest
|
||||
연결 전부. 후보 member가 아닌 source 바이트를 다시 검사했다고 주장하지 않는다.
|
||||
후보 증거를 다시 빌드하거나 다시 쓰지 않고, checkout tree로 대신 가지도 않는다.
|
||||
승격은 이미 검증한 archive 자체를 provider 보고서 두 개, 생성된 검증 기록과 함께
|
||||
올린다. 풀어 둔 파일로 대체 archive를 만들지 않는다. scanner나 서명 서비스가
|
||||
멈춰도 빈 PASS로 바꾸지 않는다.
|
||||
|
||||
The generated workflow is also a supply-chain control. `config/ci/gates.json`
|
||||
is its sole typed authority. Run `corepack pnpm generate:ci-workflow` after a
|
||||
contract change and `corepack pnpm check:ci-workflow` (or the encompassing
|
||||
`corepack pnpm check:ci`) to reject byte drift in the checked-in Gitea adapter.
|
||||
생성된 workflow도 공급망 통제다. 그 workflow의 유일한 타입 있는 원천(typed
|
||||
authority)은 `config/ci/gates.json`이다. contract를 바꾼 뒤
|
||||
`corepack pnpm generate:ci-workflow`를 돌린다. 그리고
|
||||
`corepack pnpm check:ci-workflow`(또는 이것을 포함하는
|
||||
`corepack pnpm check:ci`)로 commit된 Gitea adapter의 바이트 어긋남을 거부한다.
|
||||
|
||||
Action resolution is separately closed over one typed, runtime-frozen registry
|
||||
in `scripts/contracts/ci-gates.ts`. Every generated `uses:` value is an absolute
|
||||
upstream URL pinned to a full commit SHA:
|
||||
action 해석은 따로, `scripts/contracts/ci-gates.ts`에 있는 타입 있는 registry
|
||||
하나 안에서만 닫혀 있다. 이 registry는 runtime에 얼려 둔다(frozen). 생성된
|
||||
`uses:` 값은 모두 전체 commit SHA로 고정한 절대 upstream URL이다.
|
||||
|
||||
- `https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5`
|
||||
(`v4.3.1`)
|
||||
- `https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020`
|
||||
(`v4.4.0`)
|
||||
- `https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7`
|
||||
(patched `v4` branch)
|
||||
(패치한 `v4` branch)
|
||||
- `https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7`
|
||||
(patched `v4` branch)
|
||||
(패치한 `v4` branch)
|
||||
|
||||
Unknown actions, relative repositories, tags/branches and short SHAs are
|
||||
rejected. Gitea 1.22's official Actions documentation recommends the
|
||||
`ChristopherHX` patched artifact forks for v4 compatibility; the supported
|
||||
deployment baseline is nevertheless Gitea 1.26.4+ with Gitea Runner 1.0.0+.
|
||||
A real end-to-end provider smoke on the staging Gitea instance remains
|
||||
mandatory before any generated job becomes a required check.
|
||||
알 수 없는 action, 상대 repository, tag·branch, 짧은 SHA는 거부한다. Gitea 1.22
|
||||
공식 Actions 문서는 v4 호환을 위해 `ChristopherHX`가 패치한 artifact fork를
|
||||
권한다. 그래도 지원하는 배포 기준선은 Gitea 1.26.4 이상과 Gitea Runner 1.0.0
|
||||
이상이다. 생성된 job을 필수 검사(required check)로 만들기 전에 staging Gitea
|
||||
인스턴스에서 실제 end-to-end provider smoke를 꼭 돌려야 한다.
|
||||
|
||||
External provider supervision is fail-closed and requires a Linux runner with
|
||||
executable `/usr/bin/bwrap`, `/usr/bin/prlimit`, `/usr/bin/systemd-run`, and
|
||||
`/usr/bin/systemctl`, bubblewrap support for `--size`, an active user bus, a
|
||||
systemd user manager version 254 or newer, unified cgroup v2, and delegated
|
||||
memory, pids, and CPU controllers. The runner must also let an unprivileged
|
||||
process create user and network namespaces with bubblewrap: the sandbox runs
|
||||
`bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`, and Ubuntu
|
||||
23.10 and later refuse that while
|
||||
`kernel.apparmor_restrict_unprivileged_userns=1` unless `/usr/bin/bwrap` has
|
||||
an AppArmor profile that allows `userns` (1105/12-01). The same holds for
|
||||
FE-GATE-013, whose `test:system` probes it first
|
||||
(`scripts/check-system-test-prerequisites.ts`); the fixes are in
|
||||
`docs/operations/ci-quality-gates.md`. Executable access, user-manager/version,
|
||||
trust, archive, and path failures are rejected before raw creation. Bubblewrap
|
||||
`--size` acceptance and effective delegated controller values can only be
|
||||
verified after the owned raw inode exists inside a new scope; failures there
|
||||
remove that inode by identity and fail closed. Each invocation runs in a unique collected user scope and verifies
|
||||
its effective cgroup membership and limits before bubblewrap starts: memory is
|
||||
exactly 1 GiB, swap is zero, `TasksMax` is 64, and CPU quota is 100% per 100 ms.
|
||||
The inner process also has zero core size, a 8,388,607-byte file-size limit,
|
||||
64 open files and at most 1,200 CPU seconds. `TasksMax=64` is the authoritative
|
||||
aggregate PID boundary; no per-provider `RLIMIT_NPROC=32` claim is made because
|
||||
that limit is counted across the runner's same-UID process population.
|
||||
외부 provider 감독은 fail closed다. 다음을 갖춘 Linux runner가 필요하다: 실행할
|
||||
수 있는 `/usr/bin/bwrap`, `/usr/bin/prlimit`, `/usr/bin/systemd-run`,
|
||||
`/usr/bin/systemctl`, `--size`를 지원하는 bubblewrap, 동작 중인 user bus, 254
|
||||
이상인 systemd user manager, 통합(unified) cgroup v2, 위임된 memory·pids·CPU
|
||||
controller. runner는 권한 없는 프로세스가 bubblewrap으로 user namespace와
|
||||
network namespace를 만들 수 있게도 해야 한다. sandbox는
|
||||
`bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`을 실행한다.
|
||||
Ubuntu 23.10 이상은 `kernel.apparmor_restrict_unprivileged_userns=1`이면 이것을
|
||||
거부한다. 단, `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor profile이 있으면
|
||||
허용한다(1105/12-01). FE-GATE-013도 마찬가지다. 그 gate의 `test:system`이 이것을
|
||||
먼저 검사한다(`scripts/check-system-test-prerequisites.ts`). 고치는 법은
|
||||
`docs/operations/ci-quality-gates.md`에 있다. 실행 권한, user manager·버전,
|
||||
신뢰, archive, 경로 실패는 raw 파일을 만들기 전에 거부한다. bubblewrap이
|
||||
`--size`를 받아들이는지와 실제로 위임된 controller 값은, 새 scope 안에 자기가
|
||||
소유한 raw inode가 생긴 뒤에만 검증할 수 있다. 거기서 실패하면 그 inode를
|
||||
identity로 찾아 지우고 fail closed한다. 호출마다 고유한 user scope 안에서 돌고,
|
||||
그 scope는 끝나면 수거된다(collected). bubblewrap이 시작하기 전에 실제 cgroup
|
||||
소속과 제한을 검증한다: memory는 정확히 1 GiB, swap은 0, `TasksMax`는 64, CPU
|
||||
quota는 100 ms마다 100%다. 안쪽 프로세스에는 core 크기 0, 파일 크기 제한
|
||||
8,388,607바이트, 열린 파일 64개, CPU 시간 최대 1,200초도 걸린다. 전체 PID 수의
|
||||
기준 경계는 `TasksMax=64`다. provider마다 `RLIMIT_NPROC=32`가 걸린다고 주장하지
|
||||
않는다. 그 제한은 runner에서 같은 UID로 도는 프로세스를 모두 함께 세기 때문이다.
|
||||
|
||||
Bubblewrap uses a private network namespace (`--unshare-net`), mounts the
|
||||
workspace and verified candidate read-only, hides `.git`, and read-only binds
|
||||
the trusted `process.execPath` at `/tmp/node`. The supervisor creates and pins
|
||||
the exact configured raw-report inode only after sandbox/trust/archive
|
||||
preflight; that inode is the only provider evidence path mounted read-write.
|
||||
The provider cannot write the surrounding `untrusted` directory, workspace,
|
||||
candidate, host home/toolcache, sealed evidence path, or general temporary
|
||||
filesystem. Pre-execution and provider failures remove only the supervisor-
|
||||
owned raw inode so the same job can retry without a stale empty report.
|
||||
bubblewrap은 전용 network namespace(`--unshare-net`)를 쓴다. workspace와 검증된
|
||||
후보를 읽기 전용으로 mount하고, `.git`을 숨기고, 신뢰하는 `process.execPath`를
|
||||
`/tmp/node`에 읽기 전용으로 bind한다. supervisor는 sandbox·신뢰·archive 사전
|
||||
점검(preflight)이 끝난 뒤에만 설정에 적힌 바로 그 raw 보고서 inode를 만들고
|
||||
고정(pin)한다. 그 inode가 읽기·쓰기로 mount되는 유일한 provider 증거 경로다.
|
||||
provider는 둘러싼 `untrusted` 디렉터리, workspace, 후보, host home·toolcache,
|
||||
봉인된 증거 경로, 일반 임시 파일 시스템에 쓸 수 없다. 실행 전 실패와 provider
|
||||
실패는 supervisor가 소유한 raw inode만 지운다. 그래서 같은 job이 낡은 빈 보고서
|
||||
없이 다시 시도할 수 있다.
|
||||
|
||||
The complete bwrap argument/environment vector, including the provider command
|
||||
and provider-prefixed environment, is carried in a bounded length-prefixed frame over
|
||||
`systemd-run` stdin rather
|
||||
than placed in the supervisor, systemd, or bwrap wrapper argv. This prevents
|
||||
credentials from entering unit metadata and wrapper command lines. The final
|
||||
provider executable and its ordinary arguments remain visible to same-UID
|
||||
process inspection, so commands must never contain tokens or secrets. The same
|
||||
stdin remains open as a parent-liveness channel until normal provider exit; EOF
|
||||
caused by supervisor death makes the in-scope wrapper kill the provider process
|
||||
group and remove only the dev/inode-matched raw report. Supply
|
||||
credentials only through the provider-kind prefix
|
||||
(`VULNERABILITY_PROVIDER_*` or `PROVENANCE_PROVIDER_*`, excluding `*_COMMAND`).
|
||||
bwrap 인자·환경 벡터 전체는 provider 명령과 provider 접두 환경 변수를 포함해,
|
||||
길이를 앞에 붙인 크기 제한 frame에 담겨 `systemd-run` stdin으로 전달된다.
|
||||
supervisor, systemd, bwrap wrapper의 argv에는 넣지 않는다. 그래서 자격 증명이
|
||||
unit metadata와 wrapper 명령줄에 들어가지 않는다. 마지막 provider 실행 파일과 그
|
||||
일반 인자는 같은 UID의 프로세스 조회로 여전히 보인다. 그러므로 명령에는 토큰이나
|
||||
비밀값을 절대 넣지 않는다. 같은 stdin은 provider가 정상 종료할 때까지 부모 생존
|
||||
확인 채널로 열려 있다. supervisor가 죽어서 EOF가 오면 scope 안 wrapper가
|
||||
provider 프로세스 그룹을 죽이고, dev/inode가 맞는 raw 보고서만 지운다. 자격
|
||||
증명은 provider 종류 접두(`VULNERABILITY_PROVIDER_*` 또는
|
||||
`PROVENANCE_PROVIDER_*`, `*_COMMAND` 제외)로만 넘긴다.
|
||||
|
||||
A separate trusted guardian starts outside the provider scope and owns the
|
||||
filesystem transaction. Before spawn, the client opens and identity-checks the
|
||||
canonical raw and evidence directories with `O_DIRECTORY|O_NOFOLLOW`, derives
|
||||
the exact canonical and nonce-private leaves, and exclusively allocates empty
|
||||
mode-`0600` raw-staging and sealed-temp files. It records both dev/inode pairs
|
||||
before spawn and inherits the directory descriptors as guardian fd 3/fd 4 and
|
||||
the private file descriptors as fd 5/fd 6. Its argv contains only the trusted
|
||||
Node and helper paths. A bounded canonical v2 request carries only provider
|
||||
kind, an absolute deadline, and a random 32-byte control nonce.
|
||||
신뢰하는 별도 guardian이 provider scope 밖에서 시작해 파일 시스템 트랜잭션을
|
||||
맡는다. 띄우기(spawn) 전에 client는 canonical raw 디렉터리와 증거 디렉터리를
|
||||
`O_DIRECTORY|O_NOFOLLOW`로 열고 identity를 확인한다. 정확한 canonical leaf와
|
||||
nonce 전용 leaf를 정하고, mode `0600`인 빈 raw-staging 파일과 sealed-temp 파일을
|
||||
배타적으로 만든다. 띄우기 전에 두 dev/inode 쌍을 기록한다. 디렉터리 descriptor는
|
||||
guardian의 fd 3/fd 4로, 전용 파일 descriptor는 fd 5/fd 6으로 물려준다.
|
||||
guardian의 argv에는 신뢰하는 Node 경로와 helper 경로만 있다. 크기 제한이 있는
|
||||
canonical v2 요청에는 provider 종류, 절대 마감 시각, 무작위 32바이트 control
|
||||
nonce만 담긴다.
|
||||
|
||||
At bootstrap the guardian fstats fd 5/fd 6 before reading their procfs links.
|
||||
Each procfs target is accepted only as a direct-child alias whose exact grammar,
|
||||
descriptor-relative lstat, type, mode, size, link count, and dev/inode match the
|
||||
already-recorded descriptor identity. The guardian publishes raw staging to the
|
||||
fixed raw leaf with a no-overwrite hard link, verifies both aliases at link
|
||||
count two, removes the private raw alias, syncs the raw directory, and verifies
|
||||
the canonical raw alias at link count one before authenticated READY. If startup
|
||||
ends before READY is accepted, the client cleans raw staging/canonical only when
|
||||
they match its pre-spawn raw identity and sealed temp/final only when they match
|
||||
its pre-spawn sealed identity. It never derives cleanup ownership by opening a
|
||||
current canonical pathname, so an external file or a concurrent same-kind
|
||||
winner is preserved. Provider execution starts only after the supervisor
|
||||
confirms that the returned identities and canonical targets match exactly.
|
||||
시작(bootstrap)할 때 guardian은 procfs link를 읽기 전에 fd 5/fd 6을 fstat한다.
|
||||
각 procfs 대상은 바로 아래 자식(direct-child) alias일 때만 받아들인다. 그리고
|
||||
정확한 문법, descriptor 기준 lstat, 종류, mode, 크기, link 수, dev/inode가 이미
|
||||
기록한 descriptor identity와 맞아야 한다. guardian은 raw staging을 덮어쓰지 않는
|
||||
hard link로 고정된 raw leaf에 게시한다. 이어서 두 alias의 link 수가 2인지
|
||||
확인하고, 전용 raw alias를 지우고, raw 디렉터리를 sync하고, canonical raw
|
||||
alias의 link 수가 1인지 확인한다. 이 모두가 인증된 READY 전에 일어난다. READY가
|
||||
받아들여지기 전에 시작이 끝나면 client는 다음만 치운다: 띄우기 전 raw identity와
|
||||
맞는 raw staging·canonical, 띄우기 전 sealed identity와 맞는 sealed temp·final.
|
||||
지금 있는 canonical 경로 이름을 열어서 치울 권한을 정하지 않는다. 그래서 외부
|
||||
파일이나 동시에 돈 같은 종류의 승자(winner)는 보존된다. provider 실행은 돌려받은
|
||||
identity와 canonical 대상이 정확히 맞는다고 supervisor가 확인한 뒤에만 시작한다.
|
||||
|
||||
After evidence validation, the supervisor writes schema-validated bytes to the
|
||||
pinned temp inode, changes it to `0400`, fsyncs it, and sends authenticated
|
||||
size/hash/identity metadata. The guardian verifies the held descriptor and
|
||||
pathname, publishes without replacement using same-directory `link`, removes
|
||||
the temp name, fsyncs the directory, and returns authenticated PUBLISHED. Only
|
||||
after successful `GITHUB_OUTPUT` append does the supervisor send commit. Commit
|
||||
removes the raw inode and enters `commitPending`; clean control EOF is the sole
|
||||
success terminal and preserves the sealed final. EOF without that terminal,
|
||||
deadline expiry, malformed/trailing control data, a wrong nonce, or premature
|
||||
guardian exit cleans every matching raw/temp/final identity and fails closed.
|
||||
Guardian loss while the provider scope is active also triggers whole-scope kill
|
||||
and collection.
|
||||
증거 검증이 끝나면 supervisor는 schema로 검증한 바이트를 고정한 temp inode에
|
||||
쓰고, `0400`으로 바꾸고, fsync한 뒤, 인증된 크기·hash·identity metadata를
|
||||
보낸다. guardian은 쥐고 있는 descriptor와 경로 이름을 검증하고, 같은 디렉터리 안
|
||||
`link`로 교체 없이 게시하고, temp 이름을 지우고, 디렉터리를 fsync한 뒤, 인증된
|
||||
PUBLISHED를 돌려준다. supervisor는 `GITHUB_OUTPUT` 덧붙이기가 성공한 뒤에만
|
||||
commit을 보낸다. commit은 raw inode를 지우고 `commitPending`에 들어간다. 깨끗한
|
||||
control EOF만이 성공 종료이고, 봉인된 final을 보존한다. 다음 경우에는 맞는
|
||||
raw·temp·final identity를 모두 치우고 fail closed한다: 그 종료 없이 온 EOF, 마감
|
||||
시각 초과, 형식이 틀리거나 뒤에 남는 control 데이터, 틀린 nonce, guardian의 이른
|
||||
종료. provider scope가 살아 있는 동안 guardian을 잃어도 scope 전체를 죽이고
|
||||
수거한다.
|
||||
|
||||
`GITHUB_OUTPUT` is assumed to be a runner-owned regular file. This protocol
|
||||
does not claim OS-level cancellation of sealing or output I/O. If the guardian
|
||||
exits after scope collection, the scope-active latch records the lifecycle error
|
||||
without starting a late kill. Publication or terminal commit observes the
|
||||
nonzero exit and the client removes every identity-pinned raw/temp/final
|
||||
fallback before failing closed. The lease is bounded by the 30-minute provider
|
||||
wall limit plus a fixed ten-minute post-processing allowance.
|
||||
`GITHUB_OUTPUT`은 runner가 소유한 일반 파일이라고 가정한다. 이 protocol은
|
||||
봉인이나 output I/O를 OS 수준에서 취소한다고 주장하지 않는다. scope를 수거한 뒤
|
||||
guardian이 끝나면, scope-active latch가 lifecycle 오류를 기록하되 뒤늦은 kill은
|
||||
시작하지 않는다. 게시나 마지막 commit 단계가 0이 아닌 종료를 보면, client는
|
||||
identity로 고정한 raw·temp·final 잔여 파일(fallback)을 모두 지우고 fail closed
|
||||
한다. lease는 provider 실제 시간(wall) 제한 30분에 고정 후처리 여유 10분을
|
||||
더한 시간으로 제한된다.
|
||||
|
||||
A client hard stop after private allocation but before guardian spawn can leave
|
||||
only empty mode-`0600` nonce-private leaves. Automatic sweeping is intentionally
|
||||
omitted because an unrecorded pathname does not prove ownership; these private
|
||||
leaves cannot occupy the fixed raw or final names and do not block a retry.
|
||||
전용 파일을 만든 뒤 guardian을 띄우기 전에 client가 강제로 멈추면, mode `0600`인
|
||||
빈 nonce 전용 leaf만 남을 수 있다. 자동 정리는 일부러 넣지 않았다. 기록되지 않은
|
||||
경로 이름은 소유를 증명하지 못하기 때문이다. 이 전용 leaf는 고정된 raw 이름이나
|
||||
final 이름을 차지할 수 없고, 재시도를 막지 않는다.
|
||||
|
||||
Provider stdout and stderr are untrusted secret-bearing bytes. The supervisor
|
||||
does not retain or forward them to CI logs; it counts them only to enforce one
|
||||
1 MiB aggregate limit. Guardian diagnostics are best effort, so closed stderr
|
||||
or control descriptors cannot bypass cleanup or the required nonzero exit. The
|
||||
provider wall-clock limit is 30 minutes. Wall timeout, output overflow, parent-liveness loss,
|
||||
and active-scope guardian loss explicitly SIGKILL the whole provider process group. Ordinary command and
|
||||
RLIMIT failures complete through systemd with their concrete exit/signal; every
|
||||
path still waits for wrapper closure and requires the systemd unit/cgroup to be
|
||||
collected before returning. Provider adapters must therefore operate entirely from pre-populated
|
||||
offline data, consume the supplied candidate bindings, and write exactly the
|
||||
pinned report inode. Missing prerequisites, cgroup drift, stale or misplaced
|
||||
outputs, post-command candidate drift, and residual scope cleanup all stop
|
||||
publication.
|
||||
provider stdout과 stderr는 비밀값을 담고 있을 수 있는 믿을 수 없는 바이트다.
|
||||
supervisor는 이것을 보관하지도, CI 로그로 넘기지도 않는다. 합계 1 MiB 제한
|
||||
하나를 지키려고 바이트 수만 센다. guardian 진단은 최선 노력(best effort)이다.
|
||||
그래서 stderr나 control descriptor가 닫혀도 정리 작업이나 필수인 0이 아닌 종료를
|
||||
건너뛸 수 없다. provider 실제 시간 제한은 30분이다. 실제 시간 초과, 출력 초과,
|
||||
부모 생존 확인 끊김, scope가 살아 있을 때의 guardian 손실은 provider 프로세스
|
||||
그룹 전체에 명시적으로 SIGKILL을 보낸다. 일반 명령 실패와 RLIMIT 실패는
|
||||
systemd를 거쳐 구체적인 exit·signal로 끝난다. 어느 경로든 wrapper가 닫히기를
|
||||
기다리고, 돌아오기 전에 systemd unit·cgroup이 수거되기를 요구한다. 그러므로
|
||||
provider adapter는 미리 채워 둔 오프라인 데이터만으로 동작하고, 받은 후보
|
||||
binding을 쓰고, 고정된 보고서 inode에 정확히 써야 한다. 다음은 모두 게시를
|
||||
멈춘다: 전제 조건 누락, cgroup 어긋남(drift), 낡았거나 엉뚱한 곳에 있는 출력,
|
||||
명령 뒤 후보 어긋남, scope 정리 잔여물.
|
||||
|
||||
Provider documents are strict schema v2. Their Ed25519 signature covers the
|
||||
supervisor-supplied evidence type, validity window, run ID/attempt, independent
|
||||
32-byte invocation nonce, archived source identity, and all four candidate
|
||||
digests. Each provider job exposes its supervisor-generated nonce as a job
|
||||
output; promotion treats those outputs as the independent expected values and
|
||||
never lets a report define its own expected nonce. A report from another
|
||||
attempt, source, archive, nonce, or key fingerprint is fail-closed even when it
|
||||
has been correctly re-signed.
|
||||
provider 문서는 엄격한 schema v2다. Ed25519 서명이 덮는 범위는 다음과 같다:
|
||||
supervisor가 준 증거 종류, 유효 기간, run ID·attempt, 독립된 32바이트 호출
|
||||
nonce, archive에 든 source identity, 후보 digest 네 개 전부. provider job마다
|
||||
supervisor가 만든 nonce를 job output으로 내보낸다. 승격은 그 output을 독립된
|
||||
기대값으로 쓰고, 보고서가 자기 기대 nonce를 정하게 두지 않는다. 다른 attempt,
|
||||
source, archive, nonce, 키 지문에서 온 보고서는 올바르게 다시 서명됐더라도 fail
|
||||
closed다.
|
||||
|
||||
The immutable archive contains a strict producer-local assessment plus the
|
||||
policy and verifier source bytes needed to validate its archived relationships.
|
||||
Promotion recomputes candidate-internal checks and validates the captured
|
||||
secret-scan policy/rules/SARIF/digest relationships from an isolated extraction
|
||||
root; it does not reopen checkout policy or source paths or claim to rescan
|
||||
unarchived checkout source. The finalizer captures the archive,
|
||||
both reports, and both public keys once, generates both verification v3 records
|
||||
in memory, and writes exactly five mode-`0400` files beneath a random
|
||||
mode-`0700` directory in `RUNNER_TEMP`, independently of a restrictive runner
|
||||
umask. The exact five are the captured archive, captured vulnerability report,
|
||||
captured provenance attestation, generated provider-verification v3, and
|
||||
generated promotion-verification v3. Before returning, the finalizer validates
|
||||
those exact bytes again with live-time provider signature/freshness checks. The
|
||||
promotion record binds the exact provider-record hash, local-assessment hash,
|
||||
both report hashes, run/source/candidate identities, both nonces, both key
|
||||
IDs/fingerprints, canonical trust-policy hash, and the vulnerability provider's
|
||||
signed `secretScanAttestation`. That strict attestation says `PASS` and binds
|
||||
the captured local-assessment, source-set, secret-scan policy, SARIF, and actual
|
||||
scan-input digests. The supervisor derives the expected tuple from the captured
|
||||
archive and exact equality is rechecked at upload and finalization. The trusted
|
||||
vulnerability provider remains responsible for independently scanning that
|
||||
source set and refusing to sign a forged empty SARIF or incomplete scan input;
|
||||
the signature proves the provider made the claim, not that an untrusted
|
||||
provider performed the scan honestly. It never creates or reuses
|
||||
`.release/promoted-staging`.
|
||||
바뀌지 않는(immutable) archive에는 producer 쪽의 엄격한 로컬 assessment와,
|
||||
archive 안 관계를 검증하는 데 필요한 policy·verifier source 바이트가 들어 있다.
|
||||
승격은 격리된 압축 해제 root에서 후보 내부 검사를 다시 계산하고, 붙잡아 둔
|
||||
secret scan의 policy·rule·SARIF·digest 관계를 검증한다. checkout의 policy나
|
||||
source 경로를 다시 열지 않고, archive에 없는 checkout source를 다시 검사했다고
|
||||
주장하지 않는다. finalizer는 archive, 보고서 두 개, 공개 키 두 개를 한 번 붙잡아
|
||||
두고, 검증 v3 기록 두 개를 메모리에서 만든다. 그리고 `RUNNER_TEMP` 안 무작위
|
||||
mode `0700` 디렉터리 아래에 mode `0400` 파일을 정확히 다섯 개 쓴다. runner
|
||||
umask가 엄격해도 이 mode는 그대로다. 다섯 개는 붙잡아 둔 archive, 붙잡아 둔
|
||||
취약점 보고서, 붙잡아 둔 provenance attestation, 생성한 provider-verification
|
||||
v3, 생성한 promotion-verification v3다. 돌아오기 전에 finalizer는 바로 그
|
||||
바이트를 현재 시각 기준의 provider 서명·신선도 검사로 다시 검증한다. 승격 기록은
|
||||
다음을 묶는다: 정확한 provider 기록 hash, 로컬 assessment hash, 보고서 hash 두
|
||||
개, run·source·후보 identity, nonce 두 개, key ID·지문 두 개, canonical trust
|
||||
policy hash, 취약점 provider가 서명한 `secretScanAttestation`. 그 엄격한
|
||||
attestation은 `PASS`라고 적고, 붙잡아 둔 로컬 assessment, source 집합, secret
|
||||
scan policy, SARIF, 실제 scan 입력의 digest를 묶는다. supervisor는 붙잡아 둔
|
||||
archive에서 기대 tuple을 얻는다. upload와 마무리(finalization) 때 그 tuple과
|
||||
정확히 같은지 다시 확인한다. 그 source 집합을 독립적으로 검사하고, 위조된 빈
|
||||
SARIF나 불완전한 scan 입력에는 서명을 거부할 책임은 여전히 신뢰하는 취약점
|
||||
provider에게 있다. 서명은 provider가 그 주장을 했다는 것을 증명할 뿐이다. 믿을
|
||||
수 없는 provider가 검사를 성실히 했다는 것은 증명하지 않는다. finalizer는
|
||||
`.release/promoted-staging`을 만들지도 재사용하지도 않는다.
|
||||
|
||||
The final promotion verification/staging step must be immediately adjacent to
|
||||
the promoted-release upload, and that upload must not use `always()`. This
|
||||
reduces the post-verification mutation window but does not seal a pathname
|
||||
across two action steps. The runner is therefore required to be trusted,
|
||||
exclusive and single-tenant, with no provider command or other same-UID process
|
||||
surviving from staging into the immediately following upload. The artifact
|
||||
service and transfer actions also remain outside the candidate's cryptographic
|
||||
identity: every downstream consumer must revalidate the downloaded archive,
|
||||
manifest member digests and signed provider evidence. Producer-side adjacency
|
||||
does not provide consumer-side digest revalidation.
|
||||
The promotion job has no job-level `if`: ordinary `needs` success semantics
|
||||
require immutable build and both provider jobs to succeed, and cancellation is
|
||||
not overridden with `always()` or `cancelled()`. Cleanup alone uses bare `always()`
|
||||
and is guarded by all six finalizer outputs: staging path, token, parent
|
||||
device/inode, and staging-leaf device/inode. Cleanup opens the pinned leaf,
|
||||
requires the exact five names, unlinks only those known files through the
|
||||
descriptor, and uses a non-recursive `rmdir`; an exchanged directory or canary
|
||||
is never recursively removed.
|
||||
The immediately following upload action still reopens pathnames. The
|
||||
descriptor-relative staging and cleanup code does not claim an atomic
|
||||
`renameat2` handoff or close a malicious same-UID Gitea upload adapter; the
|
||||
staging Gitea smoke/native platform adapter remains the required closure for
|
||||
that boundary. That smoke must exercise exact-five upload and download plus
|
||||
cleanup on success, validation failure, upload failure, and cancellation. No
|
||||
native uploader or `renameat2` guarantee exists in this repository today.
|
||||
Portable Node also cannot make `mkdir` plus the first pathname `lstat` atomic.
|
||||
The implementation compares the immediate post-`mkdir` identity with the
|
||||
subsequent `O_DIRECTORY|O_NOFOLLOW` descriptor before changing permissions, but
|
||||
a malicious same-UID actor that wins before that first `lstat` remains part of
|
||||
the native/privilege boundary. The private `0700` runner-temp ancestor and
|
||||
single-tenant runner requirement are therefore security controls, not merely
|
||||
hardening.
|
||||
Failure cleanup is armed only after that created device/inode matches the opened
|
||||
descriptor. If the opened descriptor is a replacement, it is closed without
|
||||
unlinking or removing anything; the visible replacement is likewise untouched.
|
||||
Portable Node cannot safely rediscover an attacker-moved original directory by
|
||||
scanning the parent, so that residual must be removed by the isolated test
|
||||
fixture or trusted runner/native cleanup after the attacker is excluded.
|
||||
마지막 승격 검증·staging 단계는 승격된 release upload 바로 앞에 붙어 있어야
|
||||
하고, 그 upload는 `always()`를 쓰면 안 된다. 이렇게 하면 검증 뒤 내용이 바뀔 수
|
||||
있는 시간 틈이 준다. 하지만 두 action 단계에 걸쳐 경로 이름을 봉인하지는 못한다.
|
||||
그래서 runner는 신뢰할 수 있고, 독점적이고, 단일 tenant여야 한다. staging에서
|
||||
바로 다음 upload까지 provider 명령이나 같은 UID의 다른 프로세스가 살아남으면 안
|
||||
된다. artifact 서비스와 전송 action도 후보의 암호학적 identity 밖에 있다.
|
||||
그러므로 뒤에 오는 모든 소비자는 내려받은 archive, manifest member digest,
|
||||
서명된 provider 증거를 다시 검증해야 한다. producer 쪽에서 단계를 붙여 둔다고
|
||||
소비자 쪽 digest 재검증이 되지는 않는다.
|
||||
승격 job에는 job 수준 `if`가 없다. 일반 `needs` 성공 규칙에 따라 immutable
|
||||
build와 provider job 두 개가 모두 성공해야 한다. 취소는 `always()`나
|
||||
`cancelled()`로 덮어쓰지 않는다. 정리(cleanup) 단계만 조건 없는 `always()`를
|
||||
쓰고, finalizer output 여섯 개 전부로 보호된다: staging 경로, token, 부모
|
||||
device/inode, staging leaf device/inode. 정리 단계는 고정한 leaf를 열고, 정확히
|
||||
그 다섯 이름을 요구하고, descriptor를 거쳐 그 알려진 파일만 unlink하고, 재귀하지
|
||||
않는 `rmdir`를 쓴다. 바꿔치기된 디렉터리나 canary는 절대 재귀로 지우지 않는다.
|
||||
바로 다음 upload action은 여전히 경로 이름을 다시 연다. descriptor 기준
|
||||
staging·정리 코드는 원자적인 `renameat2` 넘겨주기를 한다고 주장하지 않는다.
|
||||
악의적인 같은 UID의 Gitea upload adapter를 막는다고도 주장하지 않는다. 그 경계를
|
||||
닫으려면 여전히 staging Gitea smoke와 native platform adapter가 필요하다. 그
|
||||
smoke는 exact-five upload·download를 돌리고, 성공·검증 실패·upload 실패·취소
|
||||
때의 정리도 실제로 돌려 봐야 한다. 지금 이 repository에는 native uploader도
|
||||
`renameat2` 보장도 없다.
|
||||
이식 가능한(portable) Node는 `mkdir`와 첫 경로 이름 `lstat`를 하나의 원자적
|
||||
동작으로 만들 수도 없다. 구현은 권한을 바꾸기 전에 `mkdir` 직후의 identity를
|
||||
그다음 `O_DIRECTORY|O_NOFOLLOW` descriptor와 비교한다. 그러나 첫 `lstat` 전에
|
||||
끼어든 악의적인 같은 UID 행위자는 native·권한 경계가 맡아야 할 몫으로 남는다.
|
||||
그러므로 전용 `0700` runner-temp 상위 디렉터리와 단일 tenant runner 요구는
|
||||
단순한 강화(hardening)가 아니라 보안 통제다.
|
||||
실패 정리는 만든 device/inode가 연 descriptor와 맞은 뒤에만 켜진다. 연
|
||||
descriptor가 바꿔치기된 것이면 아무것도 unlink하거나 지우지 않고 닫는다. 눈에
|
||||
보이는 바꿔치기 대상도 마찬가지로 건드리지 않는다. 이식 가능한 Node는 부모
|
||||
디렉터리를 훑어서 공격자가 옮긴 원래 디렉터리를 안전하게 다시 찾을 수 없다.
|
||||
그래서 그 잔여물은 공격자를 배제한 뒤 격리된 test fixture나, 신뢰하는
|
||||
runner·native 정리가 지워야 한다.
|
||||
|
||||
Approved vulnerability exceptions require vulnerability/package identity,
|
||||
owner, a different reviewer, reason and expiry. Expired or self-approved
|
||||
exceptions are blocking.
|
||||
승인된 취약점 예외에는 취약점·패키지 identity, owner, owner와 다른 리뷰어, 이유,
|
||||
만료일이 있어야 한다. 만료됐거나 스스로 승인한 예외는 차단한다.
|
||||
|
||||
@@ -1,74 +1,74 @@
|
||||
# Design-token styling contract
|
||||
# 디자인 토큰 스타일 계약
|
||||
|
||||
Tokens are defined in three layers under `src/presentation/design-system/tokens/`:
|
||||
`primitive.css` holds the raw palette and scales, `semantic.css` maps them to
|
||||
roles (surface, content, border, action, status) and overrides those roles for
|
||||
the dark theme, and `component.css` maps roles to per-component values.
|
||||
`src/presentation/styles/theme.css` only imports the three files and the style
|
||||
files under `src/presentation/styles/theme/`. Components consume semantic
|
||||
color, spacing, typography, status, and radius tokens through static classes.
|
||||
The executable token and primitive gallery is the workshop story
|
||||
`src/presentation/design-system/galleries.stories.tsx` (`corepack pnpm storybook`).
|
||||
토큰은 `src/presentation/design-system/tokens/` 아래 세 층으로 정의한다.
|
||||
`primitive.css`에는 가공하지 않은 색 팔레트와 단계(scale)가 있다.
|
||||
`semantic.css`는 그것을 역할(surface, content, border, action, status)에
|
||||
연결하고, 어두운 테마에서는 그 역할 값을 덮어쓴다. `component.css`는 역할을
|
||||
component별 값에 연결한다.
|
||||
`src/presentation/styles/theme.css`는 세 파일과 `src/presentation/styles/theme/`
|
||||
아래 스타일 파일을 import만 한다. component는 semantic 색, 간격,
|
||||
글자(typography), status, 모서리 반경(radius) 토큰을 정적 class로 쓴다.
|
||||
실행해 볼 수 있는 토큰·primitive 갤러리는 workshop story
|
||||
`src/presentation/design-system/galleries.stories.tsx`다(`corepack pnpm storybook`).
|
||||
|
||||
## Rules a rebrand must keep
|
||||
## 리브랜드할 때 지켜야 할 규칙
|
||||
|
||||
`check:design-system` (`scripts/check-design-system.ts`) fails when a token
|
||||
edit breaks one of these. The reasons are next to each rule in
|
||||
`scripts/lib/design-system-rules.ts`.
|
||||
토큰을 고쳐서 아래 규칙 하나라도 깨지면
|
||||
`check:design-system`(`scripts/check-design-system.ts`)이 실패한다. 규칙마다
|
||||
이유는 `scripts/lib/design-system-rules.ts`에서 그 규칙 옆에 적혀 있다.
|
||||
|
||||
- UI-01: `--color-focus` has at least 3:1 contrast against every surface a
|
||||
focus ring can sit on, in both themes. Those tokens must resolve to opaque
|
||||
`oklch()` values so the contrast can be computed.
|
||||
- UI-02: `color-mix()` mixes in `oklab`, never in a hue-based space.
|
||||
- UI-03: every component token is read by some style.
|
||||
- UI-05: `--font-sans` starts with a generic family or one the repository
|
||||
ships with `@font-face`.
|
||||
- UI-01: `--color-focus`는 두 테마 모두에서, focus ring이 놓일 수 있는 모든
|
||||
surface와 3:1 이상 대비를 가진다. 대비를 계산할 수 있도록 그 토큰들은 불투명한
|
||||
`oklch()` 값으로 풀려야 한다.
|
||||
- UI-02: `color-mix()`는 `oklab`에서 섞는다. 색상(hue) 기반 색 공간에서는 섞지
|
||||
않는다.
|
||||
- UI-03: 모든 component 토큰은 어떤 스타일이든 하나에서 읽힌다.
|
||||
- UI-05: `--font-sans`는 generic family로 시작하거나, repository가
|
||||
`@font-face`로 함께 배포하는 글꼴로 시작한다.
|
||||
|
||||
The same check requires the token names in `token-contract.ts`, the dark
|
||||
overrides of the core semantic roles, a forced-colors fallback in
|
||||
`component.css`, no raw palette values outside the token files, and no direct
|
||||
headless-library imports.
|
||||
같은 검사는 다음도 요구한다: `token-contract.ts`의 토큰 이름, 핵심 semantic
|
||||
역할의 어두운 테마 덮어쓰기, `component.css`의 forced-colors fallback, 토큰 파일
|
||||
밖에서 가공하지 않은 팔레트 값을 쓰지 않을 것, headless 라이브러리를 직접
|
||||
import하지 않을 것.
|
||||
|
||||
## Theme contract
|
||||
## 테마 계약
|
||||
|
||||
The supported public preference is the closed set `system`, `light`, and
|
||||
`dark`. `ThemeProvider` reads and writes `COLOR_SCHEME` through the application
|
||||
storage port; it does not access a raw storage key. `system` subscribes to
|
||||
`prefers-color-scheme` changes. Bootstrap applies the persisted preference
|
||||
before React paints.
|
||||
공개로 지원하는 선택값은 닫힌 집합 `system`, `light`, `dark`다.
|
||||
`ThemeProvider`는 application storage port를 거쳐 `COLOR_SCHEME`을 읽고 쓴다.
|
||||
가공하지 않은 storage key에 직접 접근하지 않는다. `system`은
|
||||
`prefers-color-scheme` 변화를 구독한다. 부트 과정(bootstrap)은 React가 화면을
|
||||
그리기 전에 저장된 선택값을 적용한다.
|
||||
|
||||
Components use semantic tokens such as `--color-panel`, `--color-content`,
|
||||
`--color-border`, `--color-action`, and status surface/content/border triples.
|
||||
They must not hard-code a light-only panel or text color. Both light and dark
|
||||
surfaces are included in automated axe checks.
|
||||
component는 `--color-panel`, `--color-content`, `--color-border`,
|
||||
`--color-action` 같은 semantic 토큰과 status의 surface/content/border 세 쌍을
|
||||
쓴다.
|
||||
밝은 테마에서만 맞는 panel 색이나 글자 색을 하드코딩하면 안 된다. 자동 axe
|
||||
검사는 밝은 surface와 어두운 surface를 모두 본다.
|
||||
|
||||
## Included primitives
|
||||
## 들어 있는 primitive
|
||||
|
||||
- `Button`: primary, secondary, danger, and ghost intent
|
||||
- `TextField`: label, help text, required state, and associated validation error
|
||||
- `Card`: labelled surface with optional footer
|
||||
- `Alert` and `Badge`: non-color-only status feedback
|
||||
- `Dialog`: native modal semantics, Escape/backdrop close, and trigger focus
|
||||
restoration
|
||||
- async and access state surfaces: loading, refresh, empty, terminal error,
|
||||
auth required, forbidden, and not found
|
||||
- `Button`: primary, secondary, danger, ghost 의도
|
||||
- `TextField`: label, 도움말, 필수 상태, 연결된 검증 오류
|
||||
- `Card`: 이름이 붙은 surface와 선택적 footer
|
||||
- `Alert`와 `Badge`: 색에만 기대지 않는 status 피드백
|
||||
- `Dialog`: native modal 의미, Escape·backdrop으로 닫기, 닫은 뒤 trigger로 focus
|
||||
되돌리기
|
||||
- 비동기·접근 상태 surface: 로딩, 새로고침, 빈 상태, 끝난(terminal) 오류, 인증
|
||||
필요, 권한 없음, 찾을 수 없음
|
||||
|
||||
Arbitrary-value policy:
|
||||
임의 값(arbitrary value) 정책:
|
||||
|
||||
- prefer a named semantic token
|
||||
- bracket values are allowed only for one-off platform constraints that cannot
|
||||
be expressed by the current scale
|
||||
- a repeated bracket value must be promoted into `@theme`
|
||||
- user-controlled or runtime-composed class strings are forbidden
|
||||
- class variants must be selected from a closed static map
|
||||
- 이름 있는 semantic 토큰을 먼저 쓴다
|
||||
- 대괄호 값은 지금 scale로 나타낼 수 없는 일회성 platform 제약에만 쓴다
|
||||
- 같은 대괄호 값이 반복되면 `@theme`으로 올려야 한다
|
||||
- 사용자가 정하거나 runtime에 조합하는 class 문자열은 금지한다
|
||||
- class 변형은 닫힌 정적 map에서 골라야 한다
|
||||
|
||||
A feature may demonstrate tokens, but generic production starter modules do
|
||||
not import a feature's domain, application, adapter, or presentation
|
||||
implementation.
|
||||
feature는 토큰을 시연할 수 있다. 하지만 범용 production starter 모듈은 feature의
|
||||
domain, application, adapter, presentation 구현을 import하지 않는다.
|
||||
|
||||
This file documents the currently implemented token and primitive baseline.
|
||||
The [design-system platform contract](../design/2026-07-26-design-system-platform-design.md) defines the
|
||||
target token layers, component catalog, local Lucide/headless-library
|
||||
facades, page patterns, accessibility and internationalization rules, isolated
|
||||
workshop, and component-authoring recipe. Items in that target document are not
|
||||
treated as implemented until their acceptance tests pass.
|
||||
이 파일은 지금 구현된 토큰과 primitive 기준선을 적는다.
|
||||
[디자인 시스템 platform 계약](../design/2026-07-26-design-system-platform-design.md)은 목표 상태를
|
||||
정의한다: 목표 토큰 층, component 목록, 로컬 Lucide·headless 라이브러리 facade,
|
||||
페이지 패턴, 접근성·국제화 규칙, 격리된 workshop, component 작성 recipe. 그 목표
|
||||
문서의 항목은 인수 테스트가 통과하기 전에는 구현된 것으로 보지 않는다.
|
||||
|
||||
+93
-95
@@ -1,130 +1,128 @@
|
||||
# Test and evidence taxonomy
|
||||
# 테스트와 증거 분류
|
||||
|
||||
Each gate is blocking in its declared scope. Failures are not downgraded with
|
||||
`continue-on-error` or warning-only scripts.
|
||||
각 gate는 선언된 범위 안에서 차단한다. 실패를 `continue-on-error`나 경고만 내는
|
||||
script로 낮추지 않는다.
|
||||
|
||||
## Executable levels
|
||||
## 실행 단계
|
||||
|
||||
| Level | Command | Ownership / prerequisite | Evidence |
|
||||
| 단계 | 명령 | 담당 범위 / 전제 조건 | 증거 |
|
||||
| --- | --- | --- | --- |
|
||||
| runtime schema | `pnpm test:runtime-schema` | pure runtime schema contracts | `artifacts/tests/runtime-schema.xml` |
|
||||
| unit | `pnpm test:unit` | Node-only domain/application/pure policy/runtime units; no systemd/bwrap/cgroup prerequisite | `artifacts/tests/unit.xml` |
|
||||
| capability contract | `pnpm test:contract` | reusable capability consumer contracts | `artifacts/tests/contract.xml` |
|
||||
| component | `pnpm test:component` | React/hook/UI behavior | `artifacts/tests/component.xml` |
|
||||
| integration | `pnpm test:integration` | HTTP/MSW, IndexedDB, composed browser-runtime boundaries, child-process/filesystem/IPC integration | `artifacts/tests/integration.xml` |
|
||||
| system / CI runner | `pnpm test:system` | compatible Linux host with systemd, bubblewrap, cgroup v2 and CI-provider process controls, where bubblewrap may create unprivileged user and network namespaces | `artifacts/tests/system.xml` |
|
||||
| end-to-end | `pnpm test:e2e` | pinned browser engines | `artifacts/tests/e2e/` |
|
||||
| accessibility | `pnpm test:a11y` | pinned browser engines | `artifacts/tests/a11y.json` |
|
||||
| runtime schema | `pnpm test:runtime-schema` | 순수 runtime schema 계약 | `artifacts/tests/runtime-schema.xml` |
|
||||
| unit | `pnpm test:unit` | Node만 쓰는 domain·application·순수 정책·runtime 단위. systemd·bwrap·cgroup 전제 조건 없음 | `artifacts/tests/unit.xml` |
|
||||
| capability contract | `pnpm test:contract` | 재사용하는 capability의 소비자 계약 | `artifacts/tests/contract.xml` |
|
||||
| component | `pnpm test:component` | React·hook·UI 동작 | `artifacts/tests/component.xml` |
|
||||
| integration | `pnpm test:integration` | HTTP/MSW, IndexedDB, 조립된 browser-runtime 경계, 자식 프로세스·파일 시스템·IPC 통합 | `artifacts/tests/integration.xml` |
|
||||
| system / CI runner | `pnpm test:system` | systemd, bubblewrap, cgroup v2, CI provider 프로세스 통제를 갖춘 호환 Linux host. 그 host에서 bubblewrap이 권한 없는 user namespace와 network namespace를 만들 수 있어야 한다 | `artifacts/tests/system.xml` |
|
||||
| end-to-end | `pnpm test:e2e` | 버전을 고정한 브라우저 엔진 | `artifacts/tests/e2e/` |
|
||||
| accessibility | `pnpm test:a11y` | 버전을 고정한 브라우저 엔진 | `artifacts/tests/a11y.json` |
|
||||
|
||||
`test:all` is the normal product-development loop. It runs, in order,
|
||||
`test:all`은 평소 제품 개발 루프다. 다음을 순서대로 돌린다:
|
||||
`test:runtime-schema`, `test:unit`, `test:contract`, `test:component`,
|
||||
`test:integration`, the rest of what `test:coverage` runs (`tests/features`,
|
||||
each installed feature's tests, `tests/scripts` and
|
||||
`tests/scale/browser-soak.contract.test.ts`), `test:platform` (`tests/platform`
|
||||
and `tests/architecture`), `check:release-coherence` and `test:recipes`
|
||||
(`package.json` `test:all`). So every Vitest path the merge gate's coverage
|
||||
run covers also runs here (`tests/unit/test-all-paths.test.ts`, 0929/10-05).
|
||||
It does not include `test:system`. CI-runner and
|
||||
supply-chain assurance has different host prerequisites and is invoked
|
||||
explicitly in the assurance path.
|
||||
`test:integration`, `test:coverage`가 돌리는 나머지(`tests/features`,
|
||||
설치된 각 feature의 테스트, `tests/scripts`,
|
||||
`tests/scale/browser-soak.contract.test.ts`), `test:platform`(`tests/platform`과
|
||||
`tests/architecture`), `check:release-coherence`, `test:recipes`
|
||||
(`package.json`의 `test:all`). 그래서 merge gate의 coverage 실행이 덮는 Vitest
|
||||
경로는 모두 여기서도 돈다(`tests/unit/test-all-paths.test.ts`, 0929/10-05).
|
||||
`test:system`은 들어 있지 않다. CI runner 보증과 공급망 보증은 host 전제 조건이
|
||||
달라서, 보증 경로에서 따로 명시적으로 부른다.
|
||||
|
||||
## Deterministic test process
|
||||
## 결정적인 테스트 프로세스
|
||||
|
||||
All Vitest package scripts launch through `scripts/run-vitest.ts`.
|
||||
Vitest package script는 모두 `scripts/run-vitest.ts`를 거쳐 실행한다.
|
||||
|
||||
That runner:
|
||||
이 runner는 다음을 한다.
|
||||
|
||||
1. rejects Node versions outside the repository-supported
|
||||
`>=24.11.0 <25.0.0` range before the suite starts,
|
||||
2. owns `NODE_ENV=test` rather than trusting the parent shell,
|
||||
3. removes host-specific `npm_config_userconfig`, `npm_config_prefix` and
|
||||
`npm_config_globalconfig` values before Vitest starts.
|
||||
1. suite가 시작하기 전에 repository가 지원하는 `>=24.11.0 <25.0.0` 범위 밖의
|
||||
Node version을 거부한다.
|
||||
2. 부모 shell을 믿지 않고 `NODE_ENV=test`를 직접 정한다.
|
||||
3. Vitest가 시작하기 전에 host마다 다른 `npm_config_userconfig`,
|
||||
`npm_config_prefix`, `npm_config_globalconfig` 값을 지운다.
|
||||
|
||||
`vitest.config.ts` also fixes `NODE_ENV=test` so a direct Vitest invocation
|
||||
cannot accidentally select React's production behavior.
|
||||
`vitest.config.ts`도 `NODE_ENV=test`를 고정한다. 그래서 Vitest를 직접 불러도
|
||||
React의 production 동작이 실수로 선택되지 않는다.
|
||||
|
||||
To run one test file, use the same runner:
|
||||
테스트 파일 하나만 돌릴 때도 같은 runner를 쓴다.
|
||||
|
||||
```sh
|
||||
node scripts/run-vitest.ts run tests/component/router.test.tsx
|
||||
```
|
||||
|
||||
The runner renders the gitignored `src/.generated/` product index first
|
||||
(`scripts/run-vitest.ts`), so this works in a fresh clone. A direct
|
||||
`pnpm exec vitest run <file>` skips that step and fails there with
|
||||
`Failed to resolve import "../.generated/product-feature-index.ts"`.
|
||||
`pnpm test:unit -- <file>` does not narrow the run, because the script already
|
||||
passes the whole `tests/unit` directory.
|
||||
runner는 gitignore된 `src/.generated/` 제품 index를 먼저
|
||||
만든다(`scripts/run-vitest.ts`). 그래서 새로 clone한 곳에서도 동작한다.
|
||||
`pnpm exec vitest run <file>`를 직접 부르면 그 단계를 건너뛰고,
|
||||
`Failed to resolve import "../.generated/product-feature-index.ts"`로 실패한다.
|
||||
`pnpm test:unit -- <file>`은 실행 범위를 좁히지 않는다. script가 이미
|
||||
`tests/unit` 디렉터리 전체를 넘기기 때문이다.
|
||||
|
||||
`vitest.config.ts` collects only `tests/**/*.test.{ts,tsx}`; Playwright
|
||||
`*.spec.ts` files are not Vitest tests. `tests/system/` is collected only when
|
||||
the command names it, as `test:system` does, so a bare `vitest` run does not
|
||||
start the CI-runner suite.
|
||||
`vitest.config.ts`는 `tests/**/*.test.{ts,tsx}`만 모은다. Playwright의
|
||||
`*.spec.ts` 파일은 Vitest 테스트가 아니다. `tests/system/`은 명령이 그 경로를
|
||||
직접 지정할 때만 모은다(`test:system`이 그렇게 한다). 그래서 맨 `vitest` 실행은
|
||||
CI runner suite를 시작하지 않는다.
|
||||
|
||||
The system suite additionally runs
|
||||
`scripts/check-system-test-prerequisites.ts` and fails with one prerequisite
|
||||
report when the CI-runner host does not provide its required Linux facilities.
|
||||
Besides the executables, cgroup v2 and the systemd bus, it runs bubblewrap once
|
||||
with the provider sandbox's namespace options on `/bin/true`, so a host that
|
||||
refuses unprivileged user namespaces (Ubuntu 23.10 and later with
|
||||
`kernel.apparmor_restrict_unprivileged_userns=1`) fails there by name instead of
|
||||
in the provider tests (1105/12-01, `docs/operations/ci-quality-gates.md`).
|
||||
system suite는 추가로 `scripts/check-system-test-prerequisites.ts`를 돌린다. CI
|
||||
runner host가 필요한 Linux 기능을 갖추지 않으면 전제 조건 보고서 하나를 내고
|
||||
실패한다.
|
||||
실행 파일, cgroup v2, systemd bus 말고도, provider sandbox와 같은 namespace
|
||||
옵션으로 bubblewrap을 `/bin/true`에 한 번 돌려 본다. 그래서 권한 없는 user
|
||||
namespace를 거부하는 host(`kernel.apparmor_restrict_unprivileged_userns=1`인
|
||||
Ubuntu 23.10 이상)는 provider 테스트가 아니라 여기서 이름이 밝혀진 채
|
||||
실패한다(1105/12-01, `docs/operations/ci-quality-gates.md`).
|
||||
|
||||
## Development paths
|
||||
## 개발 경로
|
||||
|
||||
Product feature:
|
||||
제품 feature:
|
||||
|
||||
- focused feature/unit/component test
|
||||
- capability contract test when a reusable boundary changes
|
||||
- type/lint/architecture
|
||||
- 대상을 좁힌 feature·unit·component 테스트
|
||||
- 재사용 경계가 바뀌면 capability contract 테스트
|
||||
- type·lint·architecture
|
||||
- `test:all`
|
||||
|
||||
Reusable capability:
|
||||
재사용 capability:
|
||||
|
||||
- focused unit tests
|
||||
- capability contract tests
|
||||
- integration tests
|
||||
- type/lint/architecture
|
||||
- 대상을 좁힌 unit 테스트
|
||||
- capability contract 테스트
|
||||
- integration 테스트
|
||||
- type·lint·architecture
|
||||
|
||||
CI / release assurance:
|
||||
CI·release 보증:
|
||||
|
||||
- `test:system`
|
||||
- supply-chain / promotion / release gates
|
||||
- 공급망·승격(promotion)·release gate
|
||||
|
||||
A host-level process/sandbox test must not be placed in `tests/unit` merely
|
||||
because it uses Vitest. The classification follows the system boundary and
|
||||
prerequisites, not the test framework:
|
||||
host 수준 프로세스·sandbox 테스트를 Vitest를 쓴다는 이유만으로 `tests/unit`에
|
||||
두면 안 된다. 분류는 테스트 framework가 아니라 system 경계와 전제 조건을 따른다.
|
||||
|
||||
- Tests that need systemd, bubblewrap, cgroup v2 or CI-provider process
|
||||
controls belong in `tests/system`.
|
||||
- Tests of a long-lived child-process protocol belong in `tests/integration`;
|
||||
for example the provider guardian transaction protocol lives at
|
||||
`tests/integration/provider-guardian-transaction.test.ts`. Its handshake
|
||||
timeout is a test watchdog, not a production protocol deadline.
|
||||
- A script's own tests may start that script, Node or Vitest as a short-lived
|
||||
child process to check its command-line contract, and stay in `tests/unit`
|
||||
next to the script's other tests. Such a suite declares its own longer
|
||||
timeout instead of raising the global one; for example
|
||||
`tests/unit/risk-coverage.test.ts` uses `PROCESS_HEAVY_TIMEOUT_MS`.
|
||||
- systemd, bubblewrap, cgroup v2, CI provider 프로세스 통제가 필요한 테스트는
|
||||
`tests/system`에 둔다.
|
||||
- 오래 사는 자식 프로세스 protocol의 테스트는 `tests/integration`에 둔다. 예를
|
||||
들어 provider guardian 트랜잭션 protocol 테스트는
|
||||
`tests/integration/provider-guardian-transaction.test.ts`에 있다. 그 handshake
|
||||
시간 제한은 테스트용 watchdog이지, production protocol의 마감 시간이 아니다.
|
||||
- script 자신의 테스트는 명령줄 계약을 확인하려고 그 script, Node, Vitest를 짧게
|
||||
사는 자식 프로세스로 띄울 수 있다. 이런 테스트는 그 script의 다른 테스트 옆
|
||||
`tests/unit`에 그대로 둔다. 이런 suite는 전역 시간 제한을 올리지 않고 자기
|
||||
시간 제한을 더 길게 선언한다. 예를 들어 `tests/unit/risk-coverage.test.ts`는
|
||||
`PROCESS_HEAVY_TIMEOUT_MS`를 쓴다.
|
||||
|
||||
End-to-end and automated accessibility scenarios run on the pinned Chromium,
|
||||
Firefox, and WebKit engines. The responsive contract explicitly exercises
|
||||
320px reflow, a mobile navigation drawer, and a wide two-column gallery.
|
||||
Theme scenarios verify persistence, operating-system changes, and dark-surface
|
||||
axe results. Native modal focus and validation association are exercised in
|
||||
both component and browser tests.
|
||||
end-to-end 시나리오와 자동 접근성 시나리오는 버전을 고정한 Chromium, Firefox,
|
||||
WebKit 엔진에서 돈다. responsive 계약은 320px reflow, 모바일 navigation drawer,
|
||||
넓은 화면의 2열 gallery를 명시적으로 확인한다. 테마 시나리오는 선택값 저장,
|
||||
운영체제 설정 변경, 어두운 surface의 axe 결과를 검증한다. native modal focus와
|
||||
검증 오류 연결은 component 테스트와 브라우저 테스트 양쪽에서 확인한다.
|
||||
|
||||
A control is verified only when a positive fixture passes and its deliberately
|
||||
failing negative fixture is rejected. Generated evidence is retained by CI;
|
||||
the repository tracks only the evidence directory structure.
|
||||
통제는 양성(positive) fixture가 통과하고, 일부러 실패하게 만든 음성(negative)
|
||||
fixture가 거부될 때만 검증된 것으로 본다. 생성된 증거는 CI가 보관한다.
|
||||
repository는 증거 디렉터리 구조만 추적한다.
|
||||
|
||||
Promotion is an AND graph:
|
||||
승격은 AND 그래프다.
|
||||
|
||||
1. merge gates
|
||||
2. merge gates plus release gates
|
||||
3. release gates plus rollback/runbook drills
|
||||
4. production promotion plus eligible field Web Vitals evidence
|
||||
1. merge gate
|
||||
2. merge gate와 release gate
|
||||
3. release gate와 rollback·runbook drill
|
||||
4. production 승격과, 조건을 만족하는 현장(field) Web Vitals 증거
|
||||
|
||||
The [frontend platform testing strategy](../design/2026-07-26-frontend-platform-testing-strategy-design.md)
|
||||
contains the broader testing design. This file is the executable taxonomy for
|
||||
where a test belongs and which environment is allowed to run it.
|
||||
더 넓은 테스트 설계는
|
||||
[frontend platform 테스트 전략](../design/2026-07-26-frontend-platform-testing-strategy-design.md)에 있다.
|
||||
이 파일은 테스트가 어디에 속하고 어떤 환경이 그 테스트를 돌려도 되는지를 정하는,
|
||||
실행 가능한 분류다.
|
||||
|
||||
@@ -5,37 +5,4 @@
|
||||
# - 고쳐서 더는 걸리지 않는 줄은 지운다. 남겨 두면 검사가 실패한다. 줄을 지우면 같은 변경에서
|
||||
# FROZEN에서 그 지문도 뺀다.
|
||||
# - 형식: <검사><탭><경로>[<탭><걸린 값>]. 「#」으로 시작하는 줄과 빈 줄은 읽지 않는다.
|
||||
# - 2026-11-08 문서 체계를 켤 때의 기준선이다. 문서를 고쳐 더는 걸리지 않으면 그 줄을 지운다.
|
||||
|
||||
language docs/accessibility/manual-checklist.md
|
||||
language docs/contracts/compatibility.md
|
||||
language docs/runbooks/FE-RB-001.md
|
||||
language docs/runbooks/FE-RB-002.md
|
||||
language docs/runbooks/FE-RB-003.md
|
||||
language docs/runbooks/FE-RB-004.md
|
||||
language docs/runbooks/FE-RB-005.md
|
||||
language docs/security/browser-boundary.md
|
||||
language docs/security/supply-chain.md
|
||||
language docs/styling/design-tokens.md
|
||||
language docs/testing/taxonomy.md
|
||||
language src/adapters/browser-transfer/image-cdn/README.md
|
||||
style PRODUCT.md - **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 기본 화면(홈, 플랫폼 구성)과 Storyboo
|
||||
style PRODUCT.md - **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로
|
||||
style PRODUCT.md - 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → c
|
||||
style PRODUCT.md - 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다.
|
||||
style PRODUCT.md - 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다.
|
||||
style PRODUCT.md - 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다.
|
||||
style PRODUCT.md - 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다.
|
||||
style PRODUCT.md - 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다.
|
||||
style PRODUCT.md - 템플릿에는 샘플 기능이 없습니다(참조 기능과 예제 화면은 2026-11-07에 지웠습니다). 기능은 `create:feature`로 만듭니다
|
||||
style PRODUCT.md - 파생 서비스는 운영 중인 desktop 서버에 배포됩니다.
|
||||
style PRODUCT.md - 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩
|
||||
style PRODUCT.md 1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다.
|
||||
style PRODUCT.md 2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다.
|
||||
style PRODUCT.md 3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복
|
||||
style PRODUCT.md 4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다.
|
||||
style PRODUCT.md 5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다.
|
||||
style PRODUCT.md WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를
|
||||
style PRODUCT.md 도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성,
|
||||
style PRODUCT.md 브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "
|
||||
style PRODUCT.md 화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트
|
||||
# - 2026-11-08에 문서 체계를 적용하면서 걸린 문서를 모두 고쳐 목록이 비었다.
|
||||
|
||||
@@ -59,40 +59,7 @@ export const EXCEPTIONS_FILE = "scripts/docs-system-exceptions.txt";
|
||||
* 2026-11-08 baseline, which only shrinks. When it is empty no document is
|
||||
* excused, and any line added to the list fails.
|
||||
*/
|
||||
export const FROZEN: ReadonlySet<string> = new Set<string>([
|
||||
"cd62292c1faf9312",
|
||||
"0ea431405727b1ba",
|
||||
"f6c533a3450c74be",
|
||||
"b76f8449ca6ad18b",
|
||||
"61a22114f0f80622",
|
||||
"ee082cac5fe9f20e",
|
||||
"2fcb1b008276a6f0",
|
||||
"d1b5e5cfbd8887fc",
|
||||
"67fcfa6470a125a0",
|
||||
"07db060102714081",
|
||||
"a42bc30fb525d6c9",
|
||||
"59569b9b066cffcc",
|
||||
"dce0f0c48d3876a4",
|
||||
"e1e286fae81074d4",
|
||||
"4495c81b34b2ccc9",
|
||||
"9b5a07b82e98f153",
|
||||
"24298b522fdc5404",
|
||||
"d21b67aefa16fe30",
|
||||
"c93a4077c595bfd6",
|
||||
"e23d9d9bf15712e4",
|
||||
"09f0dfe98de3c278",
|
||||
"e7f28af3b9e31580",
|
||||
"7d97ca40a8ec73f8",
|
||||
"399a89014bf0dda7",
|
||||
"4360f2d0bd948db2",
|
||||
"6fd03906dc2c2f23",
|
||||
"1e550a75f934225e",
|
||||
"ec854cee6e8ca7dd",
|
||||
"bf813a1c94ef9800",
|
||||
"e3b8f5f5b45d54c2",
|
||||
"9b512220105c506a",
|
||||
"c38dda017bafd925",
|
||||
]);
|
||||
export const FROZEN: ReadonlySet<string> = new Set<string>();
|
||||
|
||||
type RecordKind = "설계서" | "계획서" | "증거" | "납품 패키지" | "학습 문서" | "결정 기록";
|
||||
|
||||
|
||||
@@ -1,10 +1,9 @@
|
||||
# Image CDN composition
|
||||
# Image CDN 조립(composition)
|
||||
|
||||
This adapter accepts no source URL or transform query from a feature. Product
|
||||
composition owns the origin registry and named presets. A backend gateway may
|
||||
use `runtime.assets`; presentation receives only the narrow
|
||||
`runtime.presentation` facade plus registry-issued asset and preset
|
||||
references.
|
||||
이 adapter는 feature에게서 source URL이나 변환(transform) query를 받지 않는다.
|
||||
origin registry와 이름 붙은 preset은 제품 composition이 소유한다. 백엔드
|
||||
gateway는 `runtime.assets`를 쓸 수 있다. presentation은 좁은
|
||||
`runtime.presentation` facade와, registry가 발급한 asset·preset 참조만 받는다.
|
||||
|
||||
```ts
|
||||
import {
|
||||
@@ -125,46 +124,46 @@ const resolveCardImage = (signal: AbortSignal) =>
|
||||
const closeImageRuntime = (): void => runtime.close();
|
||||
```
|
||||
|
||||
For a public immutable asset, the trusted gateway calls
|
||||
`acceptPublicImmutable` with only an allowlisted `originKey`, opaque `assetId`
|
||||
and `revision`, raster metadata and intrinsic dimensions. `applicationOrigin`
|
||||
must be the deployment's canonical HTTPS origin, without a trailing slash,
|
||||
and every CDN origin must differ from it. This is required because an
|
||||
`anonymous` image request omits credentials only when it is cross-origin.
|
||||
Private descriptors must be backend-signed, remain above the configured
|
||||
minimum TTL at every resolve, and use an eager, non-low-priority
|
||||
`PRIMARY_REQUIRED` preset. A `PRIMARY_REQUIRED` preset must use `fit`
|
||||
`cover`, `contain` or `fill`: the probe expects the exact primary pixel size,
|
||||
and `inside`/`outside` keep the source ratio, so the registry rejects that
|
||||
combination at composition time. Digest and signature verification share one
|
||||
composition-owned deadline and race the caller's abort signal. The probe sends
|
||||
no credentials, rejects any final URL other than the exact signed URL, and
|
||||
requires the private response to declare the flag-only directive
|
||||
`Cache-Control: no-store`.
|
||||
Before native decode, the adapter parses the bounded PNG, JPEG, WebP or AVIF
|
||||
container, rejects animation and enforces both pixel and decoded-byte budgets.
|
||||
Its adapter-owned timeout covers response headers, streamed body consumption
|
||||
and decode; abort paths cancel the reader and close even a late ImageBitmap.
|
||||
The client never purges a CDN: public URLs roll forward by revision, while
|
||||
private delivery relies on backend capability revocation or expiry.
|
||||
공개된 바뀌지 않는(public immutable) asset이면 신뢰하는 gateway가
|
||||
`acceptPublicImmutable`을 부른다. 넘기는 것은 허용 목록에 있는 `originKey`,
|
||||
불투명한(opaque) `assetId`와 `revision`, raster metadata, 원본 크기(intrinsic
|
||||
dimensions)뿐이다. `applicationOrigin`은 배포의 canonical HTTPS origin이어야
|
||||
하고, 끝에 slash가 없어야 한다. 모든 CDN origin은 그것과 달라야 한다.
|
||||
`anonymous` 이미지 요청은 cross-origin일 때만 자격 증명을 빼기 때문이다. private
|
||||
descriptor는 백엔드가 서명해야 한다. 또 resolve할 때마다 설정된 최소 TTL보다
|
||||
많이 남아 있어야 하고, eager이면서 낮은 우선순위가 아닌 `PRIMARY_REQUIRED`
|
||||
preset을 써야 한다. `PRIMARY_REQUIRED` preset의 `fit`은 `cover`, `contain`,
|
||||
`fill` 중 하나여야 한다. probe는 정확한 기본(primary) 픽셀 크기를 기대하는데,
|
||||
`inside`/`outside`는 원본 비율을 유지하기 때문이다. 그래서 registry는
|
||||
composition 시점에 그 조합을 거부한다. digest 검증과 서명 검증은 composition이
|
||||
소유한 마감 시간 하나를 함께 쓰고, 호출한 쪽의 abort signal과 경쟁한다. probe는
|
||||
자격 증명을 보내지 않는다. 서명된 URL과 정확히 같지 않은 최종 URL은 모두
|
||||
거부한다. private 응답에는 값 없는 지시어 `Cache-Control: no-store`가 선언돼
|
||||
있어야 한다.
|
||||
native decode 전에 adapter는 크기 제한이 있는 PNG, JPEG, WebP, AVIF container를
|
||||
파싱한다. animation은 거부하고, 픽셀 budget과 decode된 바이트 budget을 둘 다
|
||||
강제한다. adapter가 소유한 시간 제한은 응답 header, stream 본문 읽기, decode를
|
||||
모두 덮는다. abort 경로는 reader를 취소하고, 늦게 도착한 ImageBitmap까지 닫는다.
|
||||
클라이언트는 CDN을 절대 purge하지 않는다. 공개 URL은 revision을 올려 앞으로
|
||||
넘어가고, private 전달은 백엔드의 capability 폐기나 만료에 기댄다.
|
||||
|
||||
Composition-supplied hard limits may only tighten
|
||||
`IMAGE_CDN_IMPLEMENTATION_CEILINGS`; configuration cannot raise intrinsic,
|
||||
source/output pixel, decoded/encoded byte, candidate, URL or capability
|
||||
lifetime ceilings owned by the adapter. Private verification additionally
|
||||
reserves one of the bounded `maxConcurrentCapabilityVerifications` slots and
|
||||
always releases it after success, failure, abort or close.
|
||||
composition이 주는 hard limit은 `IMAGE_CDN_IMPLEMENTATION_CEILINGS`를 더
|
||||
조이기만 할 수 있다. 설정으로는 adapter가 소유한 상한을 올릴 수 없다: 원본 크기,
|
||||
source·output 픽셀, decode·encode 바이트, 후보 수, URL, capability 수명. private
|
||||
검증은 추가로, 개수가 제한된 `maxConcurrentCapabilityVerifications` 슬롯 하나를
|
||||
잡는다. 성공, 실패, abort, close 뒤에는 늘 그 슬롯을 돌려준다.
|
||||
|
||||
`acceptedKeyIds` is a bounded, unique overlap set, not the active signing-key
|
||||
selector. The verifier registry must cover every accepted ID. Rotate by first
|
||||
deploying the new public key and an old/new overlap set, then switch the
|
||||
backend signer. Retain the old key for client rollout plus at least
|
||||
`maxCapabilityLifetimeMs + maxClockSkewMs`; remove it only after old clients
|
||||
and capabilities are exhausted. A compromised key instead requires backend
|
||||
revocation, `runtime.close()`, recomposition and a forced client rollout.
|
||||
`acceptedKeyIds`는 크기 제한이 있고 중복 없는 겹침(overlap) 집합이다. 지금
|
||||
서명에 쓰는 키를 고르는 값이 아니다. verifier registry는 받아들이는 ID를 모두
|
||||
덮어야 한다. 키를 교체할 때는 먼저 새 공개 키와 옛·새 겹침 집합을 배포하고,
|
||||
그다음 백엔드 서명 주체(signer)를 바꾼다. 옛 키는 클라이언트 배포(rollout)에
|
||||
걸리는 시간에 최소 `maxCapabilityLifetimeMs + maxClockSkewMs`를 더한 동안 남겨
|
||||
둔다. 옛 클라이언트와 capability가 모두 사라진 뒤에만 지운다. 키가 유출됐다면 이
|
||||
순서 대신 백엔드 폐기, `runtime.close()`, 다시 조립(recomposition), 강제
|
||||
클라이언트 배포가 필요하다.
|
||||
|
||||
`close()` is terminal and idempotent. It aborts in-flight private verification
|
||||
and probing and replaces the runtime's WeakMap capability registry, immediately
|
||||
revoking every issued reference without retaining them strongly. Every later
|
||||
accept or resolve returns closed `UNAVAILABLE`; resuming requires a newly
|
||||
composed runtime.
|
||||
`close()`는 끝 상태로 가고(terminal), 여러 번 불러도 결과가 같다(idempotent).
|
||||
진행 중인 private 검증과 probe를 abort하고, runtime의 WeakMap capability
|
||||
registry를 새것으로 바꾼다. 그래서 발급한 참조를 강하게 붙잡지 않고도 모두 즉시
|
||||
폐기한다. 그 뒤의 accept나 resolve는 모두 닫힘 상태의 `UNAVAILABLE`을 돌려준다.
|
||||
다시 쓰려면 새로 조립한 runtime이 필요하다.
|
||||
|
||||
Reference in New Issue
Block a user