02. 모듈 사이트 구축 명세

작성 2026-10-04 · 따르는 표준: 01_모듈_표준.md (표준 1) 작업 장소: 라이센스 서버 저장소 hnbbos/isolo_lic (lic.isolo.co.kr)

쉬운 요약

• 모듈 사이트는 「어떤 모듈이 있고, 몇 번까지 나왔고, 어느 프로그램이 몇 번을 쓰고, 검사는 통과했는가」를 관리하는 곳입니다.
• 새 사이트를 따로 만들지 않고, lic.isolo.co.kr 관리자 화면에 「모듈」 메뉴를 추가합니다. 제품·고객·서명 키·업데이트 기능이 이미 거기 있기 때문입니다.
• 라이센스 보호 장치·설치기·업데이트 도우미는 이 사이트에 올라가는 「기본 모듈」입니다(01 §2.5). 단독 설치로 파는 제품은 이 셋이 빠지면 묶음을 만들 수 없습니다.
• 사이트는 앱 스토어의 진열대 역할을 합니다. 이름표·번호·검사 결과·서명·안내서를 다루고, 실제 코드 파일은 GitHub 창고(hnbbos/isolo_modules, GitHub Packages, ghcr.io)에 둡니다. 사이트에서 고르면 modctl이 창고에서 받아 옵니다.
• 발행하면 라이센스 서버의 서명 키로 서명합니다. 고객 서버로 가는 묶음도 같은 키로 서명합니다.
• 함께 쓰는 명령줄 도구 modctl로 만들기·검사·가져오기·새 버전 받기·보고를 합니다.

0. Claude 요청문 (isolo_lic 저장소에서 붙여 넣기)

lic.isolo.co.kr(isolo_lic) 에 「모듈」 메뉴를 추가해 줘.
명세: docs/module-platform/02_모듈사이트_구축.md, 지킬 약속: 01_모듈_표준.md (이 두 파일을 먼저 끝까지 읽어).

[순서]
1. 먼저 지금 구조를 읽고 보고해: index.js 의 표 만드는 방식(CREATE TABLE IF NOT EXISTS)과 PG 경로(db.js shim),
   requireAdmin / requireRoleAdmin / resolveAuth(api_keys scope), auditLicense, lib/vendor/vendor-sign.js(signPayload·canonical),
   public/admin.html 의 탭 방식(data-tab / switchTab / #tab-*) 과 public/admin/js/pages.js.
2. 명세 §13 의 「1단계」만 만든다. 2·3단계는 하지 마.
   화면은 docs/module-platform/design/모듈센터_시안.html 과 design/screens/*.png 를 그대로 따른다(§4.0 디자인 표).
3. §12 의 검사 항목 중 1단계 해당 것을 scripts/ 아래 검사 스크립트로 만들고 MySQL·PG 두 경로에서 돌려 결과(통과/실패 수)를 보고해.

[지킬 것]
- 기존 기능(라이센스 발급·검증·업데이트·.lic)은 동작이 바뀌면 안 된다. 기존 e2e 검사(scripts/e2e-test.js)도 그대로 통과해야 한다.
- 서명 개인키는 지금처럼 다룬다(VENDOR-KEY-RUNBOOK.md). 키가 없으면 발행을 막고(503), 서명 없는 발행은 절대 만들지 않는다.
- 안내서(INTEGRATION.md)를 화면에 보여 줄 때는 반드시 정화(XSS)한다.
- ON DUPLICATE KEY UPDATE 는 쓰지 않는다(PG shim 미지원) — vendor_instances 처럼 SELECT 후 UPDATE/INSERT.
- 운영 서버 배포는 하지 말고, 바뀐 파일·새 표·새 API·검사 결과를 보고해.

1. 목표와 하지 않는 것

목표

1. 모듈 목록과 버전(검사 중·발행·회수)을 한곳에서 봅니다.
2. 어느 프로그램이 어느 모듈의 몇 번을 쓰는지, 누가 뒤처졌는지 봅니다.
3. 새 버전을 모든 사용처의 검사를 통과해야 발행하고, 발행은 서명합니다.
4. 사용처에 「새 번호 나옴 / 이 번호 회수됨」을 알립니다.
5. 고객 서버로 보낼 묶음을 만들어 서명하고, 기존 업데이트 기능에 연결합니다.
6. 나혼자워크 패키지 센터에 고객용 목록(카탈로그)을 줍니다.
7. 기본 모듈(라이센스 보호 장치·설치기·업데이트 도우미)을 지정하고, 단독 설치 제품이 빠뜨리지 못하게 막습니다.

하지 않는 것

• 소스 코드 보관 (GitHub가 원본)
• 서버에서 올라온 코드 실행 (검사는 GitHub Actions나 각 프로그램에서)
• 고객 서버에 원격으로 명령 내리기 (고객 쪽 업데이트 도우미가 가져가는 방식만)
• 결제 (기존 주문·결제 기능을 그대로 씀)

2. 왜 lic.isolo.co.kr 안에 두나 — 그대로 쓰는 것

3. 전체 흐름

[개발자]  isolo_modules 에서 고침 → modctl lint·test → 번호 올림 → 태그 license-guard-v1.5.0 push
   │
[GitHub Actions (isolo_modules)]
   │  단위·약속 검사 → npm 패키지 게시 / 이미지 게시(ghcr) → 지문 수집
   │  modctl register  ─────────────────────────►  POST /api/modules/register   (상태: 검사 중)
   │  (3단계) 사용처 저장소들에 「검사해 줘」 신호(repository_dispatch)
   │
[각 프로그램 저장소 CI]  새 번호로 바꿔 자기 검사 → modctl check-report ─► POST …/checks
   │
[관리자 — 모듈 탭]  호환표 확인 → 「발행」 ─► 서명 · 상태: 발행 · 알림
   │
[각 프로그램]  modctl outdated / update → 검사 → 커밋 → modctl report ─► POST /api/modules/report
   │
[관리자 — 묶음]  제품 버전 + 모듈 번호 + 이미지 지문 → 서명 → update_packages 연결
   │
[고객 서버 업데이트 도우미]  묶음 받기 → 서명·typ 확인 → 지문으로 이미지 받기 → 백업 → 교체 → 보고

4. 화면 — 「모듈 센터」

4.0 디자인과 위치

• 디자인 시안: design/모듈센터_시안.html(브라우저로 열면 화면을 오갈 수 있음) · 화면 캡처 design/screens/ 10장(PC 8장 + 모바일 2장)
• 01_홈 · 02_모듈상세_개요 · 03_모듈상세_버전 · 04_모듈상세_사용처 · 05_모듈상세_호환표 · 06_모듈상세_안내서 · 07_발행창 · 08_사용처_묶음 · 09_모바일_홈 · 10_모바일_상세
• 같은 집안 디자인: 매뉴얼 센터(man.isolo.co.kr)·버그개선(bug.isolo.co.kr)과 맞춥니다. 2026-10-04 두 사이트의 화면과 계산된 스타일을 확인해 가져왔습니다.

• 종류별 색띠: 부품 #3B6FE0, 서비스 #12a37f, 시작 틀 #7b5ce0, 기본 모듈은 남색
• 위치: lic 서버가 https://lic.isolo.co.kr/modules/로 제공합니다(정적 HTML+JS, 데이터는 §6 API). 기존 관리자 로그인(세션)을 그대로 쓰기 위해 같은 주소 아래에 둡니다. 기존 public/admin.html에는 탭 data-tab="modules"를 추가하되 「모듈 센터 열기」 링크만 둡니다. 따로 주소가 필요하면 mod.isolo.co.kr를 같은 서버로 연결합니다.
• 시안의 데이터는 예시입니다. 실제 화면은 §6 API에서 읽어 옵니다.

4.1 모듈 목록

거르기: 종류 · 「뒤처진 곳 있음」 · 「회수 번호 사용 중」

4.2 모듈 상세 — 탭 6개

1. 개요: 이름표 요약(연결부·설정 칸·바깥 접속·회사 격리), 원본 위치 링크
2. 버전: 번호·상태·변경 크기(patch/minor/major)·발행자·발행일·「사용처가 할 일」
3. 사용처: 제품별 사용 번호, 마지막 보고, 임시 덧댐 여부, 뒤처짐
4. 호환표: 행 = 버전, 열 = 사용처, 칸 = 검사 결과(통과 수/실패 수, 기록 링크)
5. 안내서: INTEGRATION.md 표시(정화 필수) + 「Claude 요청문 복사」 버튼
6. 기록: 이 모듈의 감사 기록

4.3 발행 화면

• 검사 결과 요약: 모든 사용처 통과 → 「발행」 버튼 활성화
• 검사 없음·실패가 있으면 버튼이 비활성입니다. 관리자 역할만 「사유 쓰고 강제 발행」을 할 수 있습니다(사유 10자 이상, 기록에 남음).
• MAJOR이면 경고 문구와 함께 「사용처가 할 일」을 다시 보여 줍니다.

4.4 회수

• 사유 필수. 이 번호를 쓰는 사용처와, 이 번호가 들어간 묶음을 함께 보여 줍니다.

4.5 묶음

• 제품 선택 → 묶음 번호 → 이미지 지문 입력(또는 CI가 등록) → 모듈 번호(그 제품의 마지막 보고값을 기본으로) → 확인 → 서명
• 「업데이트 패키지로 등록」 체크 시 update_packages에 한 줄을 만듭니다.

4.6 제품 화면과 연결

• 기존 제품 상세에 설치 형태(SaaS / 단독 / 둘 다) 선택을 추가합니다(products.deploy_modes).
• 기존 제품 상세에 「쓰는 모듈」 표를 추가합니다(모듈 · 번호 · 뒤처짐).
• 단독 설치 제품인데 기본 모듈이 빠져 있으면 빨간 줄로 「기본 모듈 없음: installer」처럼 보여 줍니다.

5. DB 표

기존 표(products 등)와 같은 방식으로 시작할 때 CREATE TABLE IF NOT EXISTS로 만듭니다. PG 경로는 기존 표를 PG에서 어떻게 만드는지 먼저 확인하고 똑같이 따릅니다. ENUM 대신 VARCHAR(값 제약은 앱에서), ON DUPLICATE KEY UPDATE 금지, 묶음 고유 제약은 양쪽 공통인 UNIQUE (a, b) 문법을 씁니다.

-- 모듈 (이름표의 바뀌지 않는 부분 + 화면용 캐시)
CREATE TABLE IF NOT EXISTS modules (
  id INT AUTO_INCREMENT PRIMARY KEY,
  module_id VARCHAR(40) NOT NULL UNIQUE,
  name VARCHAR(200) NOT NULL,
  kind VARCHAR(10) NOT NULL,                 -- part | service | starter
  summary VARCHAR(500) NOT NULL DEFAULT '',
  owner VARCHAR(100) NOT NULL DEFAULT '',
  source_repo VARCHAR(200) NOT NULL,
  source_path VARCHAR(300) NOT NULL DEFAULT '',
  latest_version VARCHAR(40) DEFAULT NULL,   -- 발행된 것 중 가장 높은 번호(캐시)
  required_for VARCHAR(10) NOT NULL DEFAULT '', -- 기본 모듈: '' 선택 | 'onprem' 단독 설치 제품 필수 | 'all' 모든 제품 필수
  catalog JSON DEFAULT NULL,                 -- module.json 의 catalog
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 버전 (발행 후에는 바꾸지 않음 — 회수 표시만)
CREATE TABLE IF NOT EXISTS module_versions (
  id INT AUTO_INCREMENT PRIMARY KEY,
  module_id VARCHAR(40) NOT NULL,
  version VARCHAR(40) NOT NULL,
  status VARCHAR(12) NOT NULL DEFAULT 'testing',   -- testing | released | withdrawn
  bump VARCHAR(6) NOT NULL DEFAULT '',             -- patch | minor | major (서버가 계산)
  suspect_bump BOOLEAN DEFAULT FALSE,              -- 연결부·설정·표가 바뀌었는데 patch 로 올린 경우
  manifest JSON NOT NULL,
  manifest_sha256 CHAR(64) NOT NULL,
  artifacts JSON NOT NULL,                         -- npm / git / image (01 §14.1)
  changelog TEXT,                                  -- 이 번호의 변경 기록(60KB 이하)
  integration_md TEXT,                             -- 안내서 원문(60KB 이하, 보여 줄 때 정화)
  payload JSON DEFAULT NULL,                       -- 서명한 내용 그대로
  signature TEXT DEFAULT NULL,
  note VARCHAR(500) DEFAULT '',                    -- 강제 발행·회수 사유
  created_by VARCHAR(100) DEFAULT '',
  released_by VARCHAR(100) DEFAULT '',
  released_at TIMESTAMP NULL DEFAULT NULL,
  withdrawn_at TIMESTAMP NULL DEFAULT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE (module_id, version)
);

-- 사용처 검사 결과 (이력으로 쌓음 — 같은 버전·사용처는 마지막 것이 유효)
CREATE TABLE IF NOT EXISTS module_checks (
  id INT AUTO_INCREMENT PRIMARY KEY,
  module_id VARCHAR(40) NOT NULL,
  version VARCHAR(40) NOT NULL,
  product_code VARCHAR(50) NOT NULL,
  product_version VARCHAR(40) DEFAULT '',
  runtime VARCHAR(10) DEFAULT '',
  passed INT DEFAULT 0,
  failed INT DEFAULT 0,
  ok BOOLEAN NOT NULL,
  log_url VARCHAR(500) DEFAULT '',
  reported_by VARCHAR(100) DEFAULT '',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 사용처 (각 프로그램의 modules.lock.json 보고값)
CREATE TABLE IF NOT EXISTS module_consumers (
  id INT AUTO_INCREMENT PRIMARY KEY,
  module_id VARCHAR(40) NOT NULL,
  product_code VARCHAR(50) NOT NULL,
  version_in_use VARCHAR(40) NOT NULL,
  runtime VARCHAR(10) DEFAULT '',
  patched BOOLEAN DEFAULT FALSE,                   -- 임시 덧댐 있음
  patch_remove_by DATE DEFAULT NULL,
  repo VARCHAR(200) DEFAULT '',
  reported_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE (module_id, product_code)
);

-- 묶음 (고객 서버로 보내는 세트)
CREATE TABLE IF NOT EXISTS module_bundles (
  id INT AUTO_INCREMENT PRIMARY KEY,
  product_code VARCHAR(50) NOT NULL,
  bundle_version VARCHAR(40) NOT NULL,
  payload JSON NOT NULL,                           -- 01 §14.2 그대로
  signature TEXT NOT NULL,
  update_package_id INT DEFAULT NULL,
  status VARCHAR(12) DEFAULT 'active',             -- active | withdrawn
  created_by VARCHAR(100) DEFAULT '',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE (product_code, bundle_version)
);

기존 products 표에는 칸 하나를 더합니다. 기존 productNewCols 방식(시작 시 ALTER TABLE … ADD COLUMN, 이미 있으면 무시)을 따릅니다.

-- 설치 형태: 'saas' | 'onprem' | 'saas,onprem'  (단독이 들어 있으면 기본 모듈 필수)
ALTER TABLE products ADD COLUMN deploy_modes VARCHAR(20) DEFAULT 'saas';

감사 기록은 새 표를 만들지 않고 auditLicense({ action: 'module.<동작>', detail })로 남깁니다(licenseId는 비움).

6. API

6.1 관리자 화면용 — requireAdmin (★ = requireRoleAdmin)

6.2 CI·도구용 — requireModulesKey (연동 키 scope modules 또는 full)

6.3 공개 — 인증 없음, 속도 제한

6.4 등록 요청 예 (POST /api/modules/register)

{
  "manifest": { "moduleStandard": 1, "id": "license-guard", "version": "1.5.0", "kind": "part", "...": "..." },
  "artifacts": {
    "npm": { "name": "@hnbbos/license-guard", "version": "1.5.0", "integrity": "sha512-…" },
    "git": { "repo": "hnbbos/isolo_modules", "tag": "license-guard-v1.5.0", "commit": "0a1b…(40자리)" }
  },
  "changelog": "## 1.5.0 — 2026-10-20\n### 새 기능\n- …\n### 사용처가 할 일\n- 없음",
  "integration": "# 라이센스 보호 장치 붙이기 안내서 …"
}

응답: 201 { "module": "license-guard", "version": "1.5.0", "status": "testing", "bump": "minor", "suspectBump": false, "consumers": ["nahonza-work", "zerolabel-saas"] }

7. 등록·발행 규칙

7.1 등록할 때 확인 (어기면 거절)

1. 이름표가 표준 형식에 맞는지(schemas/module-1.json): moduleStandard, id 형식, kind, 버전 형식, 필수 칸. 틀리면 400 MANIFEST_INVALID + 틀린 칸 목록.
2. 같은 번호는 상태와 상관없이 다시 등록할 수 없습니다 → 409 VERSION_EXISTS.
3. 같은 MAJOR 줄에서 가장 높은 번호보다 커야 합니다 → 409 VERSION_NOT_GREATER. 옛 줄의 보안 고침은 허용합니다(01 §7).
4. 종류별 산출물 필수
5. 부품: npm 또는 git(태그 + 40자리 커밋)
6. 서비스: image(@sha256: 지문 필수)
7. 시작 틀: git
8. 없으면 400 ARTIFACT_MISSING.
9. 크기 제한: 이름표 64KB, 안내서 60KB, 변경 기록 60KB.
10. 변경 크기 계산: 직전 발행 번호와 비교해 bump를 정합니다. 연결부·설정·provides.tables가 바뀌었는데 patch면 suspect_bump = true로 표시하고 화면에 경고합니다.
11. 이미 있는 모듈의 kind·source가 바뀌면 거절합니다(409 MODULE_IDENTITY_CHANGED).

7.2 발행할 때 확인

1. 상태가 「검사 중」이어야 합니다.
2. 사용처 = module_consumers에 있는 제품 + 이름표 compat에 적힌 제품.
3. 사용처마다 이 번호의 마지막 검사 결과가 통과여야 합니다. 아니면 409 CHECKS_MISSING / 409 CHECKS_FAILED(어느 사용처인지 포함).
4. force: true는 관리자 역할 + note 10자 이상일 때만 허용하고, 기록에 남깁니다.
5. 사용처가 아직 하나도 없으면(첫 발행) 모듈 자체 검사 결과만으로 발행할 수 있습니다.
6. 서명 키가 없으면 503 SIGNING_KEY_MISSING입니다. 서명 없는 발행은 만들지 않습니다.
7. 서명 내용은 01 §14.1의 typ: "isolo.module-release/1" 형식이고, vendor-sign.js의 signPayload()로 서명합니다.
8. 성공하면 status=released, modules.latest_version을 갱신하고, 알림을 보내고(§9.3), 기록을 남깁니다.

7.3 회수

• 「발행」 상태만 회수할 수 있습니다. 사유는 필수입니다.
• 회수된 번호는 updates에 나오지 않습니다. 그 번호를 쓰는 사용처에는 withdrawnInUse로 표시되고 알림이 갑니다.
• 그 번호가 들어간 묶음은 화면에서 빨간색으로 표시됩니다. 묶음 회수는 따로 합니다.

8. 묶음 (고객 서버용)

요청: POST /api/modules/bundles (관리자 역할)

{
  "product": "nahonza-work",
  "bundleVersion": "1.8.0",
  "minFrom": "1.6.0",
  "images": {
    "server": "ghcr.io/hnbbos/nahonza-server@sha256:…",
    "client": "ghcr.io/hnbbos/nahonza-client@sha256:…"
  },
  "modules": { "license-guard": "1.5.0" },
  "registerUpdate": true
}

규칙

1. 이미지 값은 모두 @sha256:을 포함해야 합니다(이름표 :latest 거절).
2. modules의 번호는 모두 발행 상태여야 합니다(회수·검사 중 거절). modules를 생략하면 그 제품의 마지막 보고값을 씁니다.
3. 기본 모듈 확인: 묶음은 단독 설치용이므로, required_for가 onprem 또는 all인 모듈이 모두 modules에 발행 번호로 들어 있어야 합니다. 빠지면 409 BASE_MODULE_MISSING(빠진 모듈 목록 포함)입니다. 제품의 deploy_modes에 onprem이 없으면 묶음을 만들 수 없습니다(409 PRODUCT_NOT_ONPREM).
4. 01 §14.2 형식(typ: "isolo.bundle/1")으로 서명하고 module_bundles에 저장합니다.
5. registerUpdate: true이면 update_packages에 한 줄을 만듭니다.
6. product_code = 제품, version = 묶음 번호, download_url = 공개 묶음 주소, file_sha256 = 서명 내용의 sha256
7. 기존 /api/update/check가 그대로 「새 버전 있음」을 알려 줍니다.
8. 진품 확인은 기존 HMAC 서명(고객 쪽에서 확인 불가)이 아니라 묶음의 Ed25519 서명으로 합니다.

9. 인증·보안

9.1 연동 키 scope modules

• 기존 api_keys.scope는 read/full입니다. modules를 추가하고, 연동 키 만들기 화면의 선택지에도 넣습니다.
• requireModulesKey는 scope ∈ {modules, full}일 때 §6.2 주소만 통과시킵니다. modules 키로 §6.1(관리자) 주소에 오면 403입니다.
• CI에는 GitHub Actions 비밀값 LIC_MODULES_KEY로 넣습니다. 도구는 이 키를 화면이나 기록에 출력하지 않습니다.
• 참고: 지금 api_keys는 키 원문을 저장합니다(WHERE api_key = ?). 이번 작업 범위는 아니지만 해시 저장으로 바꾸는 개선을 따로 권합니다.

9.2 그 밖의 규칙

1. 안내서·변경 기록을 화면에 보여 줄 때 정화합니다. <script>, on*= 속성, javascript:/data: 링크, <iframe>을 제거합니다.
2. 사이트는 올라온 코드를 실행하지 않습니다. 이름표는 JSON 형식 검사만 합니다.
3. 쓰기 API는 모두 auditLicense로 기록합니다. 기록에는 누가(키 이름/관리자), 무엇을(모듈·번호), 왜(사유)가 들어갑니다.
4. 공개 API에는 기존 속도 제한 방식(예: limitUpdate)과 같은 제한을 겁니다.
5. 서명 개인키 취급은 기존 VENDOR-KEY-RUNBOOK.md를 따릅니다(키 백업·교체·키링).

9.3 알림

• 발행: 「license-guard 1.5.0 발행 — 뒤처진 곳: 제로라벨(1.4.0)」
• 회수: 「license-guard 1.5.0 회수(사유) — 쓰는 곳: 나혼자워크」
• 임시 덧댐 기한 지남: 「나혼자워크의 license-guard 임시 덧댐 기한(11/01) 지남」
• 기존 알림 채널 설정을 그대로 쓰고, notification_logs에 남깁니다.

10. 카탈로그 — 나혼자워크 패키지 센터와 연결

나혼자워크는 LICENSE_CATALOG_URL에서 { programs: [...] }를 받아 normalizeCatalog()로 정리합니다 (server/src/controllers/integration.controller.ts). 이 모양에 맞춰 줍니다.

GET /api/public/modules/catalog (요청 머리 X-License-Key 선택)

{
  "programs": [
    {
      "appKey": "messenger",
      "name": "팀 메신저",
      "description": "대화방·공지·첨부·실시간 알림",
      "icon": "message-circle",
      "category": "업무",
      "baseUrl": "https://messenger.isolo.co.kr/embed/messenger",
      "tier": "licensed",
      "licenseRequired": true,
      "licensed": false,
      "link": "https://lic.isolo.co.kr/modules/messenger"
    }
  ]
}

• kind = service이고 catalog.visible = true인 모듈만 보여 줍니다. 부품·시작 틀은 고객에게 보이지 않습니다.
• licensed: X-License-Key가 유효하고 그 라이센스의 기능 목록에 catalog.featureKey가 있으면 true, 아니면 false.
• baseUrl은 나혼자워크와 다른 원본(주소)이어야 합니다(01 §10-9).

10-2. 패키지 카탈로그 (1.26.0) — 기능 패키지 + 외부 프로그램, 서명

나혼자워크 1.9 부터 메뉴를 「기본 프로그램」(메일·캘린더·주소록·할일)과 「추가 제품」으로 나누고, 추가 제품 목록을 이 사이트에서 받습니다.

GET /api/public/packages/catalog?product=<제품 코드>&appVersion=<판> (요청 머리 X-License-Key 선택)

{
  "catalog": {
    "typ": "isolo.package-catalog/1", "product": "nahonza-work", "generatedAt": "…",
    "packages": [
      { "key": "estimates", "name": "견적서", "summary": "…", "features": ["…"], "tier": "free", "licenseRequired": false, "licensed": true, "version": "1.9.1" },
      { "key": "places", "name": "내 장소", "tier": "free", "licenseRequired": false, "licensed": true, "hidden": true },
      { "type": "external", "appKey": "erp", "name": "회계 ERP", "baseUrl": "https://erp.example.com/embed", "tier": "licensed", "licenseRequired": true, "licensed": false }
    ]
  },
  "signature": "<base64 Ed25519(canonical(catalog))>", "keyId": "…"
}

• 관리: 화면 「패키지」(표 product_packages). 기능 패키지(kind builtin)는 제품 코드 안의 메뉴라 지우지 않고 숨김·내림만, 주소 없음. 외부 프로그램(kind external)은 https 주소 필수.
• licensed: 무료는 늘 true. 「라이센스」 조건은 X-License-Key 가 「라이센스 허용」(표 package_grants, 키 sha256)에 있을 때만 true.
• 웹훅: package.released · package.updated · package.withdrawn · license.changed (02 §9 와 같은 서명 머리). 받는 쪽은 서명 확인 뒤 카탈로그를 다시 받는다.
• 설치 현황: POST /api/connect/package-installs (연동 키 scope modules) — { product, appVersion, scope(회사 id 해시), packages[], externals[] }. 표 package_installs.
• 받는 쪽 약속(나혼자워크): docs/운영/패키지센터_연동.md — 공개키는 받는 쪽 설정(PACKAGE_CENTER_PUBKEYS)과만 대조, 서명이 없으면 「더 막는 쪽」 값만 받음.

기록 (1.27.0)

• GET /api/products/:code/packages/:key (관리 키) — { package, catalogEntry, history[], installs{now,reported,events[],byDay}, deliveries[], grants[] }
• GET /api/products/:code/package-activity (관리 키) — 제품 전체 최근 기록 40 · 받아 간 횟수 14일 · 설치 바뀜 20
• POST /api/products/:code/packages/:key/history/:id/revert (관리자) — 그 기록의 before 값으로 고침. update·status·revert 기록만(넣기·지움은 400 NOT_REVERTABLE). 되돌림도 revert 기록으로 남고, 받는 쪽엔 고칠 때와 같은 웹훅이 감
• 화면: 「패키지」 카드 → #package/<제품>/<key>/{overview|history|installs|alerts}. 「활동 기록」의 package.* 줄을 누르면 그 패키지의 변경 기록으로

연동 설정 · 켜고 끄기 · 쓰는 모듈 (1.59.0)

• 카탈로그 ?scope=<설치 해시> (선택) — 설치 현황을 보고한 적 있는 scope 만 기록. 답의 catalog.scope 로 돌아옴(서명 안). 패키지마다 enabled — 끔·숨김·내림이면 false(끈 것은 hidden:true 도 붙여 예전 받는 쪽도 숨김), 「켬」은 숨김 패키지를 그 대상에게만 보이게(내림은 못 되살림). 설치 줄이 라이센스 줄보다 먼저, licensed 는 그대로
• GET /api/products/:code/package-integration (관리 키) — { connection(상태 live·stale·none · 받아 간 횟수 · 서명 키 · 웹훅), license(라이센스 서버 대조·제품 코드), packages[](modules[] 쓰는 판→최신·state, moduleState, grants, switchedOff/On, suggested[]), sharedModules[], installs[], licenses[] }. 직원에게는 라이센스 앞 4자만·해시 없음
• PUT /api/products/:code/package-switches (관리자) — { target: 'license'|'install', scope | licenseKey | licenseHash, switches: { key: true|false|null } }. null 은 기본으로. 바뀌면 package.updated 웹훅 · 패키지 기록 switch
• PUT /api/products/:code/packages/:key/modules (관리자) — { modules: [id…] } 통째로(센터에 없는 id 는 400 MODULE_UNKNOWN) · 기록 modules
• POST /api/products/:code/package-modules/suggest (관리자) — 기본 틀에 적어 둔 추천 모듈 중 센터에 있는 것만 붙임 (「기본 패키지 넣기」 때도 저절로)
• 화면: 「패키지」 → 탭 「연동 설정」 #packages/<제품>/link

11. 모듈 도구 modctl

• 위치: isolo_modules/tools/modctl/ (Node 20 이상, 외부 의존 없이 fetch·crypto·child_process만 사용)
• 배포: @hnbbos/modctl (GitHub Packages). Python 프로그램 저장소에서도 개발 PC·CI에 Node가 있으면 그대로 씁니다.
• 설정: MODULES_SITE_URL(기본 https://lic.isolo.co.kr), LIC_MODULES_KEY(CI 전용), NODE_AUTH_TOKEN·MODULES_READ_TOKEN(비공개 저장소 읽기)
• 모든 명령은 실패하면 0이 아닌 값으로 끝나고, 비밀값은 출력하지 않습니다.

11.1 모듈 저장소에서

lint의 금지 검사(완벽하지 않은 휴리스틱이며, 걸리면 사람이 확인합니다)

• 모듈 코드가 사용처 경로를 import함 (../../server/, from app. 등 이름표 밖 경로)
• 보안 관련 이름(PUBKEY, PUBLIC_KEY, ENFORCE, PRODUCT_CODE, SECRET)을 process.env/os.environ에서 읽음
• iframe에 allow-same-origin과 allow-scripts를 함께 줌
• 이름표 network에 없는 고정 주소(https://…)로 접속함

11.2 프로그램 저장소에서

11.3 자동화 (3단계)

• isolo_modules: 태그 push → 검사 → 게시 → register → 사용처 저장소마다 repository_dispatch(이벤트 module-check, 내용 {id, version})
• 각 프로그램 저장소 module-check.yml: 그 번호로 바꿔 검사 → check-report (커밋하지 않음)
• 각 프로그램 저장소 주간 작업: modctl outdated → patch·minor가 있으면 업데이트 PR을 자동으로 엶(MAJOR는 이슈만)
• 다른 저장소로 신호를 보내려면 권한이 좁은 토큰(GitHub App 또는 세분화 토큰)이 필요합니다. 대표님이 만들어 비밀값으로 넣습니다.

12. 검사 항목 (만든 뒤 반드시 돌릴 것)

검사는 결과 줄이 없으면 실패로 칩니다. 또 검사 시작 시 지금 도는 서버의 버전을 출력해, 낡은 서버로 통과하는 일을 막습니다.

13. 단계

14. 대표님이 직접 하실 일

1. GitHub에 비공개 저장소 hnbbos/isolo_modules 만들기 + 태그 보호 규칙 켜기
2. GitHub Packages 사용 설정(npm @hnbbos 범위)
3. lic.isolo.co.kr에서 연동 키(scope modules)를 만들어 isolo_modules의 Actions 비밀값 LIC_MODULES_KEY로 넣기
4. (3단계) 다른 저장소에 신호를 보낼 권한이 좁은 토큰 만들기
5. 운영 서버(lic.isolo.co.kr)에 반영