@sayren/store-sdk 0.30.7 → 0.30.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.30.7",
+  "version": "0.30.9",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -21,6 +21,14 @@ import {
   analyticsSourcesSchema,
 } from "./schemas/analytics";
 import { type ApiLogListOptions, apiLogPageSchema, apiLogSummarySchema } from "./schemas/api-log";
+import {
+  type AppInstallationSettingsUpdate,
+  appInstallationSchema,
+  appInstallationSelfSchema,
+  appInstallationSettingsUpdateSchema,
+  appInstallRequestSchema,
+  appSessionSchema,
+} from "./schemas/apps";
 import {
   type ApprovalDecisionRequest,
   type ApprovalListOptions,
@@ -336,7 +344,10 @@ import {
   storefrontVerifyReportSchema,
   storefrontVersionCreatedSchema,
   storefrontVersionSchema,
+  storeTemplateSchema,
+  type UpdateStoreTemplateRequest,
   type UploadStorefrontSourceBlobsRequest,
+  updateStoreTemplateRequestSchema,
   uploadStorefrontSourceBlobsRequestSchema,
   type WriteStorefrontFilesRequest,
   writeStorefrontFilesRequestSchema,
@@ -1419,6 +1430,45 @@ export function createStoreClient(options: StoreClientOptions) {
         ),
     },
 
+    /** 설치 앱(#22, 매뉴얼 「앱 설치와 관리 › 관리 API」) — 설치·설정·제거·세션은 상점 플랫폼 OWNER·ADMIN만 */
+    apps: {
+      installations: {
+        /** 설치 결과(accounts 동의 화면의 1회용 JWT)를 내 설치를 만든다 */
+        install: (result: string) =>
+          storeHttp.request("POST", "/apps/installations", appInstallationSchema, {
+            body: appInstallRequestSchema.parse({ result }),
+          }),
+        list: () => storeHttp.request("GET", "/apps/installations", z.array(appInstallationSchema)),
+        get: (installationId: string) =>
+          storeHttp.request(
+            "GET",
+            path`/apps/installations/${installationId}`,
+            appInstallationSchema,
+          ),
+        /** 비밀 필드를 생략하면 현재 값을 유지한다. null은 비운다 */
+        updateSettings: (installationId: string, body: AppInstallationSettingsUpdate) =>
+          storeHttp.request(
+            "PUT",
+            path`/apps/installations/${installationId}/settings`,
+            appInstallationSchema,
+            { body: appInstallationSettingsUpdateSchema.parse(body) },
+          ),
+        remove: (installationId: string) =>
+          storeHttp.requestVoid("DELETE", path`/apps/installations/${installationId}`),
+        /** 앱 화면 iframe에 넘길 세션 토큰(5분) */
+        session: (installationId: string) =>
+          storeHttp.request(
+            "POST",
+            path`/apps/installations/${installationId}/session`,
+            appSessionSchema,
+          ),
+      },
+    },
+    /** 앱 설치 토큰 전용 — 자기 설치 */
+    app: {
+      installation: () => storeHttp.request("GET", "/app/installation", appInstallationSelfSchema),
+    },
+
     webhooks: {
       list: () => storeHttp.request("GET", "/webhooks", z.array(webhookSchema)),
       /** 서명 시크릿 평문은 이 응답에서만 노출된다 */
@@ -1615,6 +1665,13 @@ export function createStoreClient(options: StoreClientOptions) {
       /** `GET /v1/storefront/templates` — 템플릿 카탈로그 */
       listTemplates: () =>
         storeHttp.request("GET", "/storefront/templates", z.array(storefrontTemplateSchema)),
+      /** `GET /v1/storefront/template` — 템플릿 상점의 템플릿 정보(#123). 템플릿 상점이 아니면 404 `TEMPLATE_STORE_NOT_FOUND` */
+      getStoreTemplate: () => storeHttp.request("GET", "/storefront/template", storeTemplateSchema),
+      /** `PUT /v1/storefront/template` — 템플릿 이름·소개·썸네일을 바꾼다(템플릿 상점만) */
+      updateStoreTemplate: (body: UpdateStoreTemplateRequest) =>
+        storeHttp.request("PUT", "/storefront/template", storeTemplateSchema, {
+          body: updateStoreTemplateRequestSchema.parse(body),
+        }),
       /** `GET /v1/storefront/site` — 스위치 상태와 현재 사이트(없으면 `site: null`) */
       get: () => storeHttp.request("GET", "/storefront/site", storefrontHostingSchema),
       /** `GET /v1/storefront/slug-availability?slug=` — 슬러그를 쓸 수 있는가 */

package/src/index.ts

@@ -18,6 +18,8 @@ export {
 } from "./oauth";
 export * from "./schemas/analytics";
 export * from "./schemas/api-log";
+export * from "./schemas/app-manifest";
+export * from "./schemas/apps";
 export * from "./schemas/audit";
 export * from "./schemas/auth";
 export * from "./schemas/category";
@@ -40,7 +42,9 @@ export * from "./schemas/promotion";
 export * from "./schemas/refund-policy";
 export * from "./schemas/saved-option-set";
 export * from "./schemas/scope";
+export * from "./schemas/scope-descriptions";
 export * from "./schemas/shipping-policy";
+export * from "./schemas/starter";
 export * from "./schemas/stay";
 export * from "./schemas/store";
 export * from "./schemas/storefront-hosting";

package/src/schemas/app-manifest.ts

@@ -0,0 +1,407 @@
+import { z } from "zod";
+import { isStoreScope, STORE_SCOPE_RESOURCES, type StoreScopeResource } from "./scope";
+import { describeScope } from "./scope-descriptions";
+import { KNOWN_WEBHOOK_EVENT_TYPES, type WebhookEventType } from "./webhook-event";
+
+/**
+ * 서드파티 앱 매니페스트 `sayren.app.json` (이슈 #22) — CLI(`sayren app`)·api(빌드 `VERIFY`·버전 판정·동의 화면 자료)·런타임이
+ * 같은 원천을 쓴다. 매니페스트는 정적 JSON이고 빌드 없이 읽는다.
+ *
+ * 기능 하나는 **capability** 하나다(`APP_CAPABILITIES`). capability는 매니페스트 조각·동의 문단·넓어짐 판정(재동의 조건)을 한 곳에 둔다.
+ * 새 기능(예약 작업·공개 HTTP·설치 저장소·외부 런타임)은 여기에 항목 하나를 더하고, 설치·버전·정지·감사·사용량 코드는 건드리지 않는다.
+ * 모르는 키는 거부한다(`strictObject`) — 아직 없는 capability를 쓴 매니페스트는 빌드가 분명히 실패한다.
+ */
+
+/** 앱 handle — 전역 유일, 앱 도메인의 라벨(`{handle}.{앱 도메인}`). 상점 코드와 같은 형식, 3~40자 */
+export const APP_HANDLE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,38}[a-z0-9])$/;
+/** handle로 쓸 수 없는 라벨 — 플랫폼 호스트·혼동되는 이름 */
+export const APP_RESERVED_HANDLES: ReadonlySet<string> = new Set([
+  "www",
+  "api",
+  "app",
+  "apps",
+  "admin",
+  "accounts",
+  "store",
+  "mcp",
+  "docs",
+  "sayren",
+  "preview",
+  "runner",
+  "static",
+  "cdn",
+]);
+
+export const appHandleSchema = z
+  .string()
+  .regex(APP_HANDLE_PATTERN, "앱 handle은 소문자·숫자·하이픈 3~40자입니다")
+  .refine((value) => !APP_RESERVED_HANDLES.has(value) && !value.endsWith("-preview"), {
+    message: "쓸 수 없는 handle입니다",
+  });
+
+/**
+ * 설치 앱에 열지 않는 스코프 — 구성원(초대로 권한 상승), 상점 설정 전반(`storefrontOrigins`로 소셜 로그인 code 가로채기), 스토어 웹훅
+ * (앱 구독으로 대체, 제거 뒤에도 남는 문제), 스토어프론트 편집·발행, 감사 로그. 커스텀 연동은 계정 액세스 토큰(#71)이 맡는다
+ */
+export const NON_INSTALLABLE_SCOPES: ReadonlySet<string> = new Set([
+  "member:r",
+  "member:rw",
+  "store:rw",
+  "webhook:r",
+  "webhook:rw",
+  "storefront:r",
+  "storefront:rw",
+  "audit:r",
+]);
+
+/** 앱이 요청할 수 있는 스코프 — 카탈로그 전체에서 위를 뺀 것 */
+export const INSTALLABLE_SCOPES: readonly string[] = (
+  Object.entries(STORE_SCOPE_RESOURCES) as [StoreScopeResource, readonly string[]][]
+)
+  .flatMap(([resource, accesses]) => accesses.map((access) => `${resource}:${access}`))
+  .filter((scope) => !NON_INSTALLABLE_SCOPES.has(scope));
+
+export function isInstallableScope(scope: string): boolean {
+  return isStoreScope(scope) && !NON_INSTALLABLE_SCOPES.has(scope);
+}
+
+export const appScopeSchema = z
+  .string()
+  .refine(isInstallableScope, { message: "앱이 요청할 수 없는 스코프입니다" });
+
+/**
+ * 앱 생명주기 이벤트 — 웹훅 카탈로그 밖이고 앱 코드만 받는다. `APP.UNINSTALLED`·`APP.STORE_REDACT`는 설치가 끝난 뒤라 토큰 없이 온다
+ * (`APP.STORE_REDACT`는 제거 48시간 뒤).
+ */
+export const APP_LIFECYCLE_EVENT_TYPES = [
+  "APP.INSTALLED",
+  "APP.UNINSTALLED",
+  "APP.SETTINGS_UPDATED",
+  "APP.SCOPES_UPDATED",
+  "APP.STORE_REDACT",
+  "APP.CUSTOMER_REDACT",
+] as const;
+export type AppLifecycleEventType = (typeof APP_LIFECYCLE_EVENT_TYPES)[number];
+export type AppEventType = WebhookEventType | AppLifecycleEventType;
+
+/**
+ * 이벤트를 받는 데 필요한 스코프 — 동의 스코프가 이것을 덮지 못하면 분배하지 않고, 매니페스트 `scopes`가 덮지 못하면 빌드가 실패한다.
+ * 생명주기 이벤트는 스코프가 없다(null). 새 웹훅 이벤트를 더하면 이 표도 더해야 테스트가 통과한다
+ */
+export const APP_EVENT_SCOPES: Record<AppEventType, string | null> = {
+  "ORDER.PAID": "order:r",
+  "ORDER.CONFIRMED": "order:r",
+  "ORDER.DISPATCHED": "order:r",
+  "ORDER.DELIVERED": "order:r",
+  "ORDER.PURCHASE_DECIDED": "order:r",
+  "ORDER.ADDRESS_CHANGE_REQUESTED": "order:r",
+  "ORDER.FULFILLED": "order:r",
+  "ORDER.CANCELED": "order:r",
+  "ORDER.FLOW_NOTIFICATION": "order:r",
+  "ORDER.FLOW_STATE_CHANGED": "order:r",
+  "CLAIM.CANCEL_REQUESTED": "claim:r",
+  "CLAIM.RETURN_REQUESTED": "claim:r",
+  "CLAIM.EXCHANGE_REQUESTED": "claim:r",
+  "CLAIM.COMPLETED": "claim:r",
+  "INQUIRY.CREATED": "inquiry:r",
+  "REVIEW.CREATED": "review:r",
+  "PRODUCT.OUT_OF_STOCK": "product:r",
+  "APP.INSTALLED": null,
+  "APP.UNINSTALLED": null,
+  "APP.SETTINGS_UPDATED": null,
+  "APP.SCOPES_UPDATED": null,
+  "APP.STORE_REDACT": null,
+  "APP.CUSTOMER_REDACT": null,
+};
+
+export const APP_EVENT_TYPES: readonly AppEventType[] = [
+  ...KNOWN_WEBHOOK_EVENT_TYPES,
+  ...APP_LIFECYCLE_EVENT_TYPES,
+];
+
+export const appEventTypeSchema = z.enum(APP_EVENT_TYPES as [AppEventType, ...AppEventType[]]);
+
+/** 동의 스코프가 이벤트를 받을 수 있는가 — `rw`는 `r`을 함의한다 */
+export function scopesCoverEvent(scopes: readonly string[], event: AppEventType): boolean {
+  const required = APP_EVENT_SCOPES[event];
+  if (required === null) return true;
+  const [resource] = required.split(":");
+  return scopes.includes(required) || scopes.includes(`${resource}:rw`);
+}
+
+/**
+ * 외부 호출 호스트 — https·443·소문자 호스트명. 와일드카드는 한 단계(`*.example.com`)만. IP·`localhost`·sayren 플랫폼 호스트는
+ * 받지 않는다(내부 호스트 차단은 outbound Worker가 다시 본다 — 여기는 매니페스트 형식). 253자 이하, 라벨 2개 이상
+ */
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const TLD = /^(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/;
+export const APP_NETWORK_DENIED_SUFFIXES: readonly string[] = [
+  "sayren.app",
+  "sayren.co",
+  "avarlabs.com",
+  "localhost",
+  "local",
+  "internal",
+];
+
+export function appNetworkHostProblem(raw: string): string | null {
+  const host = raw.trim();
+  if (host !== raw || host !== host.toLowerCase())
+    return "호스트는 소문자이고 앞뒤 공백이 없어야 합니다";
+  if (host.length > 253) return "호스트가 너무 깁니다";
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(host) || host.includes(":")) return "IP 주소는 쓸 수 없습니다";
+  const labels = host.split(".");
+  const wildcard = labels[0] === "*";
+  const named = wildcard ? labels.slice(1) : labels;
+  if (named.length < 2) return "호스트는 라벨이 둘 이상이어야 합니다";
+  if (!named.every((label) => HOST_LABEL.test(label))) return "호스트 형식이 맞지 않습니다";
+  if (!TLD.test(named[named.length - 1] as string)) return "최상위 도메인 형식이 맞지 않습니다";
+  const apex = named.join(".");
+  for (const suffix of APP_NETWORK_DENIED_SUFFIXES) {
+    if (apex === suffix || apex.endsWith(`.${suffix}`))
+      return "sayren 플랫폼·내부 호스트는 쓸 수 없습니다";
+  }
+  return null;
+}
+
+export const appNetworkHostSchema = z.string().superRefine((value, ctx) => {
+  const problem = appNetworkHostProblem(value);
+  if (problem) ctx.addIssue({ code: "custom", message: problem });
+});
+
+/** 셀러가 콘솔에서 채우는 설정 필드 — 콘솔이 폼을 그릴 수 있는 네 형식만 */
+export const APP_SETTING_FIELD_TYPES = ["string", "number", "boolean", "select"] as const;
+export type AppSettingFieldType = (typeof APP_SETTING_FIELD_TYPES)[number];
+
+export const APP_SETTINGS_MAX_FIELDS = 30;
+export const APP_SETTING_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{0,39}$/;
+
+export const appSettingFieldSchema = z.strictObject({
+  type: z.enum(APP_SETTING_FIELD_TYPES),
+  label: z.string().trim().min(1).max(60),
+  description: z.string().trim().max(200).optional(),
+  required: z.boolean().optional(),
+  /** 비밀 값 — 암호화 저장, 응답에서 가린다, 에이전트·토큰으로 읽을 수 없다. `string`만 */
+  secret: z.boolean().optional(),
+  /** `select`의 선택지 */
+  options: z
+    .array(
+      z.strictObject({ value: z.string().min(1).max(60), label: z.string().trim().min(1).max(60) }),
+    )
+    .min(1)
+    .max(50)
+    .optional(),
+  default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+});
+export type AppSettingField = z.infer<typeof appSettingFieldSchema>;
+
+export const APP_SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
+export const APP_SECRETS_MAX = 20;
+export const APP_EVENTS_MAX = 50;
+export const APP_NETWORK_HOSTS_MAX = 20;
+
+export const appManifestSchema = z.strictObject({
+  handle: appHandleSchema,
+  name: z.string().trim().min(1).max(60),
+  description: z.string().trim().max(500).optional(),
+  /** https 이미지 주소. 동의 화면·상점 플랫폼 목록에 보인다 */
+  iconUrl: z.url().startsWith("https://").optional(),
+  supportEmail: z.email().optional(),
+  /** 실행 위치 — A1은 코드 업로드 앱만. 외부 런타임(`external`)은 A3에서 연다 */
+  runtime: z.literal("code").default("code"),
+  /** 설치 때 전체 동의하는 스코프 */
+  scopes: z.array(appScopeSchema).max(32).default([]),
+  network: z
+    .strictObject({ hosts: z.array(appNetworkHostSchema).max(APP_NETWORK_HOSTS_MAX) })
+    .default({ hosts: [] }),
+  /** 이벤트 함수 구독 */
+  events: z.array(appEventTypeSchema).max(APP_EVENTS_MAX).default([]),
+  ui: z
+    .strictObject({
+      /** 상점 플랫폼 앱 화면(iframe) — 정적 SPA 진입 파일 */
+      adminPage: z.strictObject({ entry: z.string().regex(/^ui\/[A-Za-z0-9._/-]+\.html$/) }),
+    })
+    .optional(),
+  settings: z
+    .record(z.string().regex(APP_SETTING_KEY_PATTERN), appSettingFieldSchema)
+    .refine((fields) => Object.keys(fields).length <= APP_SETTINGS_MAX_FIELDS, {
+      message: `설정 필드는 ${APP_SETTINGS_MAX_FIELDS}개까지입니다`,
+    })
+    .default({}),
+  /** 개발자 비밀 값 이름 — 값은 CLI(`sayren app secret put`)로 따로 넣는다 */
+  secrets: z.array(z.string().regex(APP_SECRET_NAME_PATTERN)).max(APP_SECRETS_MAX).default([]),
+});
+export type AppManifest = z.infer<typeof appManifestSchema>;
+export type AppManifestInput = z.input<typeof appManifestSchema>;
+
+/** 소스 안 비밀 값 형식(매뉴얼 「빌드」 `SECRET_IN_SOURCE`) — 번들에 들어가면 막는다. CLI `app verify`와 api 빌드 `BUNDLE`이 같은 표를 쓴다 */
+export const APP_SECRET_PATTERNS: readonly RegExp[] = [
+  /sy_pat_[A-Za-z0-9]{8,}/,
+  /\b(?:test|live)_sk_[A-Za-z0-9]{8,}/,
+  /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
+  /\bsak_[a-z0-9]+_[0-9a-f]{32}\b/,
+];
+
+/** 서버 번들 gzip 상한(3MiB)·화면 정적 파일 상한 — 매뉴얼 「빌드 › 한도」 */
+export const APP_SERVER_BUNDLE_MAX_GZIP_BYTES = 3 * 1024 * 1024;
+export const APP_UI_MAX_BYTES = 25 * 1024 * 1024;
+export const APP_UI_MAX_FILES = 2_000;
+
+export interface AppManifestProblem {
+  path: string;
+  code:
+    | "EVENT_SCOPE_MISSING"
+    | "SELECT_OPTIONS_REQUIRED"
+    | "SECRET_FIELD_TYPE"
+    | "DEFAULT_TYPE_MISMATCH"
+    | "DUPLICATE";
+  message: string;
+}
+
+/** 스키마가 보지 못하는 필드 사이 규칙 — 빌드 `VERIFY`·CLI `app verify`가 같은 결과를 낸다. 비어 있으면 통과 */
+export function appManifestProblems(manifest: AppManifest): AppManifestProblem[] {
+  const problems: AppManifestProblem[] = [];
+  const unique = (values: readonly string[], path: string, label: string) => {
+    const seen = new Set<string>();
+    for (const value of values) {
+      if (seen.has(value)) {
+        problems.push({ path, code: "DUPLICATE", message: `${label}이 중복됐습니다: ${value}` });
+      }
+      seen.add(value);
+    }
+  };
+  unique(manifest.scopes, "scopes", "스코프");
+  unique(manifest.events, "events", "이벤트");
+  unique(manifest.network.hosts, "network.hosts", "호스트");
+  unique(manifest.secrets, "secrets", "비밀 값 이름");
+  for (const event of manifest.events) {
+    if (!scopesCoverEvent(manifest.scopes, event)) {
+      problems.push({
+        path: `events.${event}`,
+        code: "EVENT_SCOPE_MISSING",
+        message: `${event} 이벤트를 받으려면 ${APP_EVENT_SCOPES[event]} 스코프가 필요합니다`,
+      });
+    }
+  }
+  for (const [key, field] of Object.entries(manifest.settings)) {
+    if (field.type === "select" && !field.options) {
+      problems.push({
+        path: `settings.${key}`,
+        code: "SELECT_OPTIONS_REQUIRED",
+        message: "select 필드에는 options가 필요합니다",
+      });
+    }
+    if (field.secret && field.type !== "string") {
+      problems.push({
+        path: `settings.${key}`,
+        code: "SECRET_FIELD_TYPE",
+        message: "비밀 필드는 string만 됩니다",
+      });
+    }
+    if (field.default !== undefined) {
+      const expected = field.type === "select" ? "string" : field.type;
+      const matchesOption =
+        field.type !== "select" || field.options?.some((o) => o.value === field.default);
+      if (typeof field.default !== expected || !matchesOption) {
+        problems.push({
+          path: `settings.${key}`,
+          code: "DEFAULT_TYPE_MISMATCH",
+          message: "default가 필드 형식과 맞지 않습니다",
+        });
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * 판정용 요약 — `app_versions.capabilities`에 저장하고 분배·동의·넓어짐 판정이 매니페스트 전체 대신 읽는다. 매니페스트에서만 만든다
+ */
+export interface AppCapabilities {
+  scopes: string[];
+  events: AppEventType[];
+  networkHosts: string[];
+  adminPage: boolean;
+  /** 필수 설정 키 — 하나라도 비어 있으면 이벤트 함수를 부르지 않는다 */
+  requiredSettings: string[];
+  secretSettings: string[];
+}
+
+export function appCapabilitiesOf(manifest: AppManifest): AppCapabilities {
+  const sorted = (values: readonly string[]) => [...new Set(values)].sort();
+  return {
+    scopes: sorted(manifest.scopes),
+    events: sorted(manifest.events) as AppEventType[],
+    networkHosts: sorted(manifest.network.hosts),
+    adminPage: Boolean(manifest.ui?.adminPage),
+    requiredSettings: Object.entries(manifest.settings)
+      .filter(([, field]) => field.required)
+      .map(([key]) => key)
+      .sort(),
+    secretSettings: Object.entries(manifest.settings)
+      .filter(([, field]) => field.secret)
+      .map(([key]) => key)
+      .sort(),
+  };
+}
+
+/**
+ * capability 레지스트리 — 키마다 동의 문단과 넓어짐 판정. 「넓어졌다」= 기존 설치가 재동의해야 새 버전으로 옮길 수 있다.
+ * 동의 문단은 accounts 설치 화면·상점 플랫폼 앱 상세·유저 문서가 같은 문장을 쓴다.
+ */
+export interface AppCapabilityDefinition {
+  key: "scopes" | "network" | "events" | "ui";
+  /** 동의 화면의 문단 제목 */
+  title: string;
+  /** 동의 화면에 보일 줄 — 없으면 문단을 그리지 않는다 */
+  describe(capabilities: AppCapabilities): string[];
+  /** 새 버전이 넓어졌는가 */
+  widens(previous: AppCapabilities, next: AppCapabilities): boolean;
+}
+
+const grew = (previous: readonly string[], next: readonly string[]) =>
+  next.some((value) => !previous.includes(value));
+
+/** 스코프 집합이 넓어졌는가 — `r`→`rw`는 넓어짐, `rw`→`r`은 아님 */
+function scopesWiden(previous: readonly string[], next: readonly string[]): boolean {
+  return next.some((scope) => {
+    if (previous.includes(scope)) return false;
+    const [resource, access] = scope.split(":");
+    return !(access === "r" && previous.includes(`${resource}:rw`));
+  });
+}
+
+export const APP_CAPABILITIES: readonly AppCapabilityDefinition[] = [
+  {
+    key: "scopes",
+    title: "이 앱이 할 수 있는 일",
+    describe: (c) => c.scopes.map((scope) => describeScope(scope) ?? scope),
+    widens: (p, n) => scopesWiden(p.scopes, n.scopes),
+  },
+  {
+    key: "network",
+    title: "이 앱이 데이터를 보내는 곳",
+    describe: (c) => c.networkHosts,
+    widens: (p, n) => grew(p.networkHosts, n.networkHosts),
+  },
+  {
+    key: "events",
+    title: "이 앱이 받는 알림",
+    describe: (c) => c.events,
+    widens: (p, n) => grew(p.events, n.events),
+  },
+  {
+    key: "ui",
+    title: "상점 플랫폼 화면",
+    describe: (c) => (c.adminPage ? ["상점 플랫폼에 이 앱의 화면을 더합니다"] : []),
+    widens: (p, n) => !p.adminPage && n.adminPage,
+  },
+];
+
+/** 재동의가 필요한 capability 키 — 비어 있으면 release가 모든 설치에 곧바로 반영된다 */
+export function appManifestWidens(
+  previous: AppCapabilities,
+  next: AppCapabilities,
+): AppCapabilityDefinition["key"][] {
+  return APP_CAPABILITIES.filter((c) => c.widens(previous, next)).map((c) => c.key);
+}