문제: AUTH_MODE external은 제품이 owner 8개 메서드를 직접 써야 하는데, 짝 백엔드(JWT·Keycloak 또는 Redis session)에 맞는 owner가 src·recipes 어디에도 없다. 쿠키 owner 모양은 테스트 파일 안 스케치뿐이다. 그래서 제품마다 첫 연동 전에 토큰 획득·갱신·subject·상태 전이·401 처리를 처음부터 쓴다. 짝 백엔드(bbe944bd)에서 확인한 계약: - jwt 모드(기본): OAuth2 resource server. iss = APP_SECURITY_JWT_ISSUER (local http://localhost:8081/realms/ca-skeleton), aud 필수. CSRF·세션 없음. 그러나 realm에는 서비스용 confidential client(ca-skeleton-api, standard flow 꺼짐)만 있고 브라우저용 public client가 없다. - redis-session 모드: CA_SESSION httpOnly 쿠키, CookieCsrfTokenRepository (XSRF-TOKEN 쿠키, X-XSRF-TOKEN 헤더, plain handler). 로그인·로그아웃· 세션 조회·CSRF 발급 엔드포인트는 운영 코드에 없다(테스트 픽스처만). 고른 방법: recipes/session-owners/에 둘을 둔다. 제품은 src/bootstrap/로 복사해 composeProductSessionOwner에서 돌려준다. - oidc-pkce-session-owner.ts: authorization code + PKCE S256, WebCrypto와 context fetch만 쓴다(라이브러리 없음). 토큰은 메모리에만, sessionStorage 에는 10분짜리 거래(verifier·state·nonce·returnTo)만 두고 콜백이 먼저 지운다. 콜백 URL에서 code를 네트워크 호출 전에 지운다. state·RFC 9207 iss·nonce·aud·azp·exp·sub를 검사하고, 갱신 때 sub가 바뀌면 로그아웃. bearer는 apiOrigins에만 보낸다. 만료 30초 전 갱신은 한 번만 하고 상태 알림이 없다. 401이면 refresh token으로 한 번 복구하고, 그 토큰도 401이면 로그아웃. 설정이 틀리면 integration-failed로 닫는다. - cookie-session-owner.ts: 세션 조회·로그아웃 URL과 로그인 시작을 기본값 없이 받는다(백엔드에 없는 엔드포인트를 지어내지 않는다). 200+subject → authenticated, 401 → unauthenticated, 그 밖은 reject(상태 유지). SESSION_COOKIE_READ/WRITE 프로필과 XSRF-TOKEN → x-xsrf-token provider. 쿠키가 없으면 쓰기는 UNAVAILABLE로 아무것도 보내지 않는다. - 두 owner 모두 SessionState·recover 전이 계약을 따른다. - PRODUCTION_IMPORTS_RECIPE 검사를 recipes/session-owners에도 건다. recipe는 복사하지 import하지 않는다(초기 번들 밖). 버린 대안: src에 기본 owner 내장(IdP 결합이 템플릿 본체에 들어간다), OIDC 라이브러리 의존(fetch·WebCrypto로 충분), 매뉴얼만(같은 실수 반복). 위험·한계: 실제 Keycloak·Redis session 백엔드에 붙여 보지 않았다. ID token 서명은 검사하지 않는다(토큰 엔드포인트 직접 응답, OIDC Core 3.1.3.7 (6)); access token 서명은 백엔드가 본다. 새로고침하면 메모리 토큰이 사라져 다시 로그인한다(Keycloak SSO면 비밀번호 없이 돌아온다). 쿠키 모드는 페이지와 API가 같은 host여야 XSRF-TOKEN을 읽는다. 검증: tests/recipes 3파일 52건(구현 전 모듈 없음으로 실패 확인). 변이 15개(state·origin·401 한 번·nonce·iss·URL 정리·갱신 sub·TTL, CSRF 헤더·401·로그아웃 실패·notify·단일 조회·subject 상한·credentials) 모두 실패로 잡힘. runtime 조립 테스트 4건이 실제 createRuntimeAdapters로 EXTERNAL_BEARER bearer, 401 뒤 갱신, 쿠키 쓰기의 x-xsrf-token을 확인. check:optional-recipe-fixtures(regex 변경 없이는 실패 확인), check:optional-recipes:source, check:types, eslint 통과. 두 recipe의 minify+gzip 크기 3.8 kB, 1.1 kB. Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
445 lines
14 KiB
TypeScript
445 lines
14 KiB
TypeScript
import { readFile, readdir } from "node:fs/promises";
|
|
import path from "node:path";
|
|
|
|
export const REQUIRED_RECIPE_IDS = Object.freeze([
|
|
"analytics-error-sink",
|
|
"browser-permission",
|
|
"client-workflow",
|
|
"feature-flag",
|
|
"file-transfer",
|
|
"generated-api",
|
|
"large-data-ui",
|
|
"multi-tab",
|
|
"offline-indexeddb",
|
|
"realtime",
|
|
"service-worker-pwa",
|
|
"web-worker",
|
|
] as const);
|
|
|
|
const lifecycleRecipes: ReadonlySet<string> = new Set([
|
|
"analytics-error-sink",
|
|
"browser-permission",
|
|
"client-workflow",
|
|
"file-transfer",
|
|
"generated-api",
|
|
"multi-tab",
|
|
"offline-indexeddb",
|
|
"realtime",
|
|
"service-worker-pwa",
|
|
"web-worker",
|
|
]);
|
|
|
|
type Document = Readonly<Record<string, unknown>>;
|
|
export type OptionalRecipeSourceViolation = Readonly<{
|
|
ruleId: string;
|
|
path: string;
|
|
}>;
|
|
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
|
|
}
|
|
|
|
function recordValue(value: unknown): Record<string, unknown> {
|
|
return isRecord(value) ? value : {};
|
|
}
|
|
|
|
function recordRows(value: unknown): Record<string, unknown>[] {
|
|
return Array.isArray(value) ? value.filter(isRecord) : [];
|
|
}
|
|
|
|
function nonEmptyStrings(value: unknown): value is string[] {
|
|
return (
|
|
Array.isArray(value) &&
|
|
value.length > 0 &&
|
|
value.every(
|
|
(entry): entry is string =>
|
|
typeof entry === "string" && entry.trim().length > 0,
|
|
)
|
|
);
|
|
}
|
|
|
|
function packageVersions(value: unknown): Record<string, string> {
|
|
return Object.fromEntries(
|
|
Object.entries(recordValue(value)).filter(
|
|
(entry): entry is [string, string] => typeof entry[1] === "string",
|
|
),
|
|
);
|
|
}
|
|
|
|
export function validateRecipeCatalog(
|
|
input: unknown,
|
|
packageDocument: Document,
|
|
): string[] {
|
|
const document = recordValue(input);
|
|
const violations: string[] = [];
|
|
if (document.schemaVersion !== 1) violations.push("CATALOG_SCHEMA_VERSION");
|
|
if (document.decisionId !== "VD-10") violations.push("CATALOG_DECISION");
|
|
if (document.defaultStatus !== "NOT_INSTALLED") {
|
|
violations.push("CATALOG_DEFAULT_MUST_BE_NOT_INSTALLED");
|
|
}
|
|
if (
|
|
!Array.isArray(document.productionRuntimeDependencies) ||
|
|
document.productionRuntimeDependencies.length > 0
|
|
) {
|
|
violations.push("UNSELECTED_RUNTIME_DEPENDENCY");
|
|
}
|
|
if (!nonEmptyStrings(document.vendorPackagePatterns)) {
|
|
violations.push("VENDOR_PATTERN_CATALOG");
|
|
}
|
|
if (!Array.isArray(document.recipes)) {
|
|
return [...violations, "RECIPE_CATALOG_MISSING"];
|
|
}
|
|
|
|
const recipes = recordRows(document.recipes);
|
|
const actualIds = recipes.map((recipe) => String(recipe.id ?? "")).sort();
|
|
if (JSON.stringify(actualIds) !== JSON.stringify(REQUIRED_RECIPE_IDS)) {
|
|
violations.push("RECIPE_ID_SET");
|
|
}
|
|
if (new Set(actualIds).size !== actualIds.length) {
|
|
violations.push("RECIPE_ID_DUPLICATE");
|
|
}
|
|
|
|
for (const recipe of recipes) {
|
|
const id = typeof recipe.id === "string" ? recipe.id : "unknown";
|
|
if (recipe.status !== "RECIPE_AVAILABLE") {
|
|
violations.push(`${id}:STATUS_MUST_NOT_CLAIM_INSTALLED`);
|
|
}
|
|
for (const field of [
|
|
"trigger",
|
|
"boundary",
|
|
"port",
|
|
"fake",
|
|
"owner",
|
|
"fallback",
|
|
"serverStatePolicy",
|
|
] as const) {
|
|
const value = recipe[field];
|
|
if (typeof value !== "string" || value.trim().length === 0) {
|
|
violations.push(`${id}:MISSING_${field.toUpperCase()}`);
|
|
}
|
|
}
|
|
for (const field of [
|
|
"forbiddenWhen",
|
|
"failureKinds",
|
|
"securityPrivacy",
|
|
"removal",
|
|
] as const) {
|
|
if (!nonEmptyStrings(recipe[field])) {
|
|
violations.push(`${id}:MISSING_${field.toUpperCase()}`);
|
|
}
|
|
}
|
|
if (
|
|
typeof recipe.bundleBudgetGzipBytes !== "number" ||
|
|
!Number.isInteger(recipe.bundleBudgetGzipBytes) ||
|
|
recipe.bundleBudgetGzipBytes < 1
|
|
) {
|
|
violations.push(`${id}:INVALID_BUNDLE_BUDGET`);
|
|
}
|
|
if (recipe.owner === "frontend-platform") {
|
|
violations.push(`${id}:PROJECT_OWNER_NOT_ASSIGNED`);
|
|
}
|
|
if (lifecycleRecipes.has(id) && !nonEmptyStrings(recipe.lifecycleMethods)) {
|
|
violations.push(`${id}:CLEANUP_CONTRACT_MISSING`);
|
|
}
|
|
if (
|
|
id === "client-workflow" &&
|
|
recipe.serverStatePolicy !== "reference-only"
|
|
) {
|
|
violations.push(`${id}:SERVER_STATE_DUPLICATION_POLICY`);
|
|
}
|
|
}
|
|
|
|
const dependencies = {
|
|
...packageVersions(packageDocument.dependencies),
|
|
...packageVersions(packageDocument.devDependencies),
|
|
};
|
|
const packageScripts = packageVersions(packageDocument.scripts);
|
|
for (const recipe of recipes) {
|
|
if (recipe.referenceRuntime === undefined) continue;
|
|
const runtime = recordValue(recipe.referenceRuntime);
|
|
const id = typeof recipe.id === "string" ? recipe.id : "unknown";
|
|
if (
|
|
runtime.status !== "AVAILABLE_NOT_COMPOSED" ||
|
|
runtime.productionComposition !== false
|
|
) {
|
|
violations.push(`${id}:REFERENCE_RUNTIME_COMPOSITION`);
|
|
}
|
|
if (!nonEmptyStrings(runtime.sourceRoots)) {
|
|
violations.push(`${id}:REFERENCE_RUNTIME_SOURCE_ROOTS`);
|
|
} else if (
|
|
runtime.sourceRoots.some(
|
|
(sourceRoot) =>
|
|
!sourceRoot.startsWith("src/") ||
|
|
sourceRoot.includes("\\") ||
|
|
sourceRoot.split("/").includes(".."),
|
|
)
|
|
) {
|
|
violations.push(`${id}:REFERENCE_RUNTIME_SOURCE_BOUNDARY`);
|
|
}
|
|
if (!nonEmptyStrings(runtime.coveredCapabilities)) {
|
|
violations.push(`${id}:REFERENCE_RUNTIME_CAPABILITIES`);
|
|
}
|
|
if (!nonEmptyStrings(runtime.conformanceScripts)) {
|
|
violations.push(`${id}:REFERENCE_RUNTIME_CONFORMANCE`);
|
|
} else {
|
|
for (const script of runtime.conformanceScripts) {
|
|
if (!(script in packageScripts)) {
|
|
violations.push(`${id}:UNKNOWN_CONFORMANCE_SCRIPT:${script}`);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
const vendorPatterns = Array.isArray(document.vendorPackagePatterns)
|
|
? document.vendorPackagePatterns.filter(
|
|
(entry): entry is string => typeof entry === "string",
|
|
)
|
|
: [];
|
|
for (const pattern of vendorPatterns) {
|
|
const wildcard = pattern.endsWith("*");
|
|
const prefix = pattern.replace(/\/?\*$/, "");
|
|
if (
|
|
Object.keys(dependencies).some(
|
|
(dependency) =>
|
|
dependency === prefix ||
|
|
dependency.startsWith(`${prefix}/`) ||
|
|
(wildcard && dependency.startsWith(prefix)),
|
|
)
|
|
) {
|
|
violations.push(`UNSELECTED_VENDOR_INSTALLED:${prefix}`);
|
|
}
|
|
}
|
|
return violations;
|
|
}
|
|
|
|
export async function sourceFiles(directory: string): Promise<string[]> {
|
|
let entries;
|
|
try {
|
|
entries = await readdir(directory, { withFileTypes: true });
|
|
} catch (error: unknown) {
|
|
if (
|
|
isRecord(error) &&
|
|
"code" in error &&
|
|
error.code === "ENOENT"
|
|
) {
|
|
return [];
|
|
}
|
|
throw error;
|
|
}
|
|
const groups: string[][] = await Promise.all(
|
|
entries.map((entry) => {
|
|
const target = path.join(directory, entry.name);
|
|
return entry.isDirectory()
|
|
? sourceFiles(target)
|
|
: /\.(?:[cm]?[jt]s|[jt]sx)$/.test(entry.name)
|
|
? [target]
|
|
: [];
|
|
}),
|
|
);
|
|
return groups.flat();
|
|
}
|
|
|
|
export async function scanOptionalRecipeSources(
|
|
root: string,
|
|
{ scanProductionBoundary = true }: Readonly<{
|
|
scanProductionBoundary?: boolean;
|
|
}> = {},
|
|
): Promise<OptionalRecipeSourceViolation[]> {
|
|
const violations: OptionalRecipeSourceViolation[] = [];
|
|
for (const file of await sourceFiles(root)) {
|
|
const relative = path.relative(process.cwd(), file).replaceAll("\\", "/");
|
|
const relativeToRoot = path.relative(root, file).replaceAll("\\", "/");
|
|
const content = await readFile(file, "utf8");
|
|
const imports = [
|
|
...content.matchAll(/(?:from\s*|import\s*\(\s*)["']([^"']+)["']/g),
|
|
]
|
|
.map((match) => match[1])
|
|
.filter((specifier): specifier is string => specifier !== undefined);
|
|
|
|
if (
|
|
scanProductionBoundary &&
|
|
(relativeToRoot.startsWith("src/") ||
|
|
(path.basename(path.resolve(root)) === "src" &&
|
|
!relativeToRoot.startsWith(".."))) &&
|
|
imports.some((specifier) =>
|
|
// 1103/09-03. Session owner recipes are copied too, never imported.
|
|
/(?:^|\/)recipes\/(?:frontend-capabilities|session-owners)(?:\/|$)/.test(
|
|
specifier,
|
|
),
|
|
)
|
|
) {
|
|
violations.push({ ruleId: "PRODUCTION_IMPORTS_RECIPE", path: relative });
|
|
}
|
|
|
|
const productionRelative =
|
|
path.basename(path.resolve(root)) === "src"
|
|
? `src/${relativeToRoot}`
|
|
: relativeToRoot;
|
|
const isCompositionSource =
|
|
/(?:^|\/)src\/bootstrap\//.test(productionRelative) ||
|
|
/(?:^|\/)src\/features\/installed-feature-(?:adapters|runtimes)\./.test(
|
|
productionRelative,
|
|
);
|
|
if (
|
|
scanProductionBoundary &&
|
|
isCompositionSource &&
|
|
(imports.some((specifier) =>
|
|
/(?:^|\/)adapters\/(?:browser-file-storage|browser-files|browser-transfer|cache-storage|storage\/(?:indexeddb|opfs))(?:\/|$)/.test(
|
|
specifier,
|
|
),
|
|
) ||
|
|
/["'][^"'\r\n]*(?:^|\/)adapters\/(?:browser-file-storage|browser-files|browser-transfer|cache-storage|storage\/(?:indexeddb|opfs))(?:\/|["'])/u.test(
|
|
content,
|
|
))
|
|
) {
|
|
violations.push({
|
|
ruleId: "REFERENCE_RUNTIME_COMPOSED_WITHOUT_SELECTION",
|
|
path: relative,
|
|
});
|
|
}
|
|
|
|
const localVendorAdapter =
|
|
relative.includes("recipes/") && relative.includes("/adapters/");
|
|
if (
|
|
!localVendorAdapter &&
|
|
imports.some((specifier) =>
|
|
/^(?:@launchdarkly\/|@sentry\/|@opentelemetry\/|@openapitools\/openapi-generator-cli$|@reduxjs\/toolkit$|@tanstack\/react-virtual$|@uppy\/|firebase(?:\/|$)|idb$|react-window$|redux(?:\/|$)|socket\.io-client$|tus-js-client$|workbox-window$|xstate$|zustand$)/.test(
|
|
specifier,
|
|
),
|
|
)
|
|
) {
|
|
violations.push({ ruleId: "VENDOR_IMPORT_OUTSIDE_ADAPTER", path: relative });
|
|
}
|
|
|
|
if (
|
|
/localStorage\s*\.\s*(?:setItem|getItem)\s*\([^)]*(?:credential|password|secret|token)/is.test(
|
|
content,
|
|
) ||
|
|
/searchParams\s*\.\s*set\s*\(\s*["'](?:credential|password|secret|token)/is.test(
|
|
content,
|
|
) ||
|
|
/(?:record|track|emit)\s*\(\s*\{[\s\S]{0,400}(?:credential|password|secret|token)\s*:/i.test(
|
|
content,
|
|
)
|
|
) {
|
|
violations.push({ ruleId: "CREDENTIAL_LEAK_PATH", path: relative });
|
|
}
|
|
|
|
if (
|
|
/(?:createStore|configureStore|create\s*\()\s*\([\s\S]{0,600}(?:apiResponse|queryData|serverState)\s*:/i.test(
|
|
content,
|
|
)
|
|
) {
|
|
violations.push({
|
|
ruleId: "CLIENT_STORE_DUPLICATES_SERVER_STATE",
|
|
path: relative,
|
|
});
|
|
}
|
|
}
|
|
return violations;
|
|
}
|
|
|
|
export async function scanProductionBundle(
|
|
distRoot: string,
|
|
): Promise<string[]> {
|
|
const violations: string[] = [];
|
|
const forbiddenRuntimeMarkers = [
|
|
"frontend-optional-recipe-must-not-reach-production",
|
|
"Browser file runtime hard limits are invalid.",
|
|
"Object URL allocation failed",
|
|
"Storage pressure policy is invalid.",
|
|
"IndexedDB runtime configuration is invalid.",
|
|
"Invalid IndexedDB schema migration.",
|
|
"OPFS runtime policy is invalid.",
|
|
"OPFS operation failed.",
|
|
"Public Cache Storage policy is invalid.",
|
|
"Public cache validation failed.",
|
|
"Presigned capability vault limit is invalid.",
|
|
"Resumable upload policy is invalid.",
|
|
"Image CDN policy registry is invalid.",
|
|
] as const;
|
|
for (const file of await sourceFiles(distRoot)) {
|
|
const content = await readFile(file, "utf8");
|
|
if (forbiddenRuntimeMarkers.some((marker) => content.includes(marker))) {
|
|
violations.push(path.relative(process.cwd(), file));
|
|
}
|
|
}
|
|
|
|
const viteManifestPath = path.join(distRoot, ".vite/manifest.json");
|
|
const emittedModuleInventoryPath = path.join(
|
|
distRoot,
|
|
".vite/module-inventory.json",
|
|
);
|
|
const moduleInventoryCandidates = [
|
|
emittedModuleInventoryPath,
|
|
...(path.resolve(distRoot) === path.resolve("dist")
|
|
? ["artifacts/quality/vite-module-inventory.json"]
|
|
: []),
|
|
];
|
|
const viteManifestExists = await readFile(viteManifestPath, "utf8")
|
|
.then(() => true)
|
|
.catch((error: unknown) => {
|
|
if (isRecord(error) && error.code === "ENOENT") return false;
|
|
throw error;
|
|
});
|
|
if (!viteManifestExists) return [...new Set(violations)];
|
|
|
|
let inventory: unknown;
|
|
let moduleInventoryPath = emittedModuleInventoryPath;
|
|
for (const candidate of moduleInventoryCandidates) {
|
|
try {
|
|
inventory = JSON.parse(await readFile(candidate, "utf8"));
|
|
moduleInventoryPath = candidate;
|
|
break;
|
|
} catch {
|
|
// A generated build may move the inventory out of the deploy directory.
|
|
}
|
|
}
|
|
if (inventory === undefined) {
|
|
violations.push(
|
|
path.relative(process.cwd(), moduleInventoryPath),
|
|
);
|
|
return [...new Set(violations)];
|
|
}
|
|
const inventoryDocument = recordValue(inventory);
|
|
const chunks = recordRows(inventoryDocument.chunks);
|
|
if (
|
|
inventoryDocument.schemaVersion !== 1 ||
|
|
!Array.isArray(inventoryDocument.chunks) ||
|
|
chunks.length !== inventoryDocument.chunks.length
|
|
) {
|
|
violations.push(path.relative(process.cwd(), moduleInventoryPath));
|
|
return [...new Set(violations)];
|
|
}
|
|
|
|
const forbiddenSourcePrefixes = [
|
|
"src/application/ports/browser-file-storage/",
|
|
"src/application/ports/browser-transfer/",
|
|
"src/adapters/browser-file-storage/",
|
|
"src/adapters/browser-files/",
|
|
"src/adapters/browser-transfer/",
|
|
"src/adapters/cache-storage/",
|
|
"src/adapters/storage/indexeddb/",
|
|
"src/adapters/storage/opfs/",
|
|
] as const;
|
|
for (const chunk of chunks) {
|
|
if (
|
|
typeof chunk.fileName !== "string" ||
|
|
!Array.isArray(chunk.modules) ||
|
|
chunk.modules.some((moduleId) => typeof moduleId !== "string")
|
|
) {
|
|
violations.push(path.relative(process.cwd(), moduleInventoryPath));
|
|
continue;
|
|
}
|
|
for (const moduleId of chunk.modules as string[]) {
|
|
if (
|
|
forbiddenSourcePrefixes.some((prefix) =>
|
|
moduleId.startsWith(prefix),
|
|
)
|
|
) {
|
|
violations.push(`${chunk.fileName}:${moduleId}`);
|
|
}
|
|
}
|
|
}
|
|
return [...new Set(violations)];
|
|
}
|