@clazic/urban 0.2.9 → 0.2.10

package/src/agent/skills/dbpia.js

@@ -0,0 +1,678 @@
+/**
+ * DBpia 학술 DB 외부검색 스킬 (B2B 기관 라이선스)
+ *
+ * - 세션: Bootstrap → b2bLoginProc → 쿠키 보관 (TTL 25분)
+ * - 검색: POST /api/search/list (JSON)
+ * - Phase 1: search + normalize 전용 (discover·download 미지원)
+ * - 결과 필터: externalLink === true 인 항목만 반환 (원문 있는 것만)
+ */
+import { Agent, fetch, request } from 'undici';
+import zlib from 'node:zlib';
+import { promisify } from 'node:util';
+import { Skill } from './base.js';
+import { normalizeDbpiaItem } from './_normalize.js';
+import { getSecureConfig } from '../../kb/db.js';
+
+// ── 상수 ─────────────────────────────────────────────────────────────
+
+const BASE_URL = 'https://www.dbpia.co.kr';
+const URLS = {
+  bootstrap:     `${BASE_URL}/`,
+  loginPage:     `${BASE_URL}/member/b2bLogin`,
+  loginProc:     `${BASE_URL}/member/b2bLoginProc`,
+  searchPage:    `${BASE_URL}/search/topSearch`,
+  searchList:    `${BASE_URL}/api/search/list`,
+  me:            `${BASE_URL}/member/me`,
+  articleDetail: (nodeId) => `${BASE_URL}/journal/articleDetail?nodeId=${encodeURIComponent(nodeId)}`,
+  pdfView:       (nodeId) => `${BASE_URL}/pdf/pdfView.do?nodeId=${encodeURIComponent(nodeId)}&width=1920`,
+  downloadData:  `${BASE_URL}/download/downloadData`,
+};
+
+const SESSION_TTL_MS   = 25 * 60 * 1_000;  // 25분
+const REQUEST_DELAY_MS = 800;               // 요청 간 최소 간격 (ms)
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+// Chrome 124 기반 공통 브라우저 헤더
+const CHROME_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36';
+const HEADERS_NAV = {
+  'user-agent':        CHROME_UA,
+  'accept':            'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+  'accept-language':   'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+  'accept-encoding':   'gzip, deflate, br',
+  'sec-ch-ua':         '"Chromium";v="124", "Google Chrome";v="124", "Not-A.Brand";v="99"',
+  'sec-ch-ua-mobile':  '?0',
+  'sec-ch-ua-platform': '"macOS"',
+  'upgrade-insecure-requests': '1',
+};
+const HEADERS_XHR = {
+  'user-agent':        CHROME_UA,
+  'accept':            'application/json, text/plain, */*',
+  'accept-language':   'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+  'accept-encoding':   'gzip, deflate, br',
+  'sec-ch-ua':         '"Chromium";v="124", "Google Chrome";v="124", "Not-A.Brand";v="99"',
+  'sec-ch-ua-mobile':  '?0',
+  'sec-ch-ua-platform': '"macOS"',
+  'sec-fetch-dest':    'empty',
+  'sec-fetch-mode':    'cors',
+  'sec-fetch-site':    'same-origin',
+  'x-requested-with':  'XMLHttpRequest',
+};
+
+// ── 압축 해제 ─────────────────────────────────────────────────────────
+
+const _gunzip          = promisify(zlib.gunzip);
+const _brotliDecompress = promisify(zlib.brotliDecompress);
+const _inflate         = promisify(zlib.inflate);
+
+async function readBody(res) {
+  const chunks = [];
+  for await (const chunk of res.body) chunks.push(chunk);
+  const buf = Buffer.concat(chunks);
+  const enc = (res.headers?.['content-encoding'] ?? '').toLowerCase();
+  try {
+    if (enc.includes('br'))      return (await _brotliDecompress(buf)).toString('utf-8');
+    if (enc.includes('gzip'))    return (await _gunzip(buf)).toString('utf-8');
+    if (enc.includes('deflate')) return (await _inflate(buf)).toString('utf-8');
+  } catch { /* 압축 해제 실패 시 raw 반환 */ }
+  return buf.toString('utf-8');
+}
+
+// ── 쿠키 유틸 ────────────────────────────────────────────────────────
+
+function parseSetCookies(headers) {
+  const raw = headers['set-cookie'];
+  if (!raw) return [];
+  return Array.isArray(raw) ? raw : [raw];
+}
+
+function mergeCookies(jar, setCookieArray) {
+  for (const line of setCookieArray) {
+    const eq = line.indexOf('=');
+    if (eq < 0) continue;
+    const name  = line.slice(0, eq).trim();
+    const value = line.slice(eq + 1).split(';')[0].trim();
+    // null 값 쿠키 무시 (dbp_pxy=null 세션 리셋 방지)
+    if (value === 'null' || value === '') continue;
+    jar[name] = value;
+  }
+}
+
+function cookieStr(jar) {
+  return Object.entries(jar)
+    .filter(([, v]) => v && v !== 'null')
+    .map(([k, v]) => `${k}=${v}`)
+    .join('; ');
+}
+
+// ── 인증정보 로드 ─────────────────────────────────────────────────────
+
+function loadCredentials() {
+  let b2bAcc, userPass;
+  try {
+    b2bAcc   = getSecureConfig('source.dbpia.b2bAcc');
+    userPass = getSecureConfig('source.dbpia.userPass');
+  } catch { /* DB 미초기화 */ }
+
+  if (!b2bAcc || !userPass) {
+    throw new Error(
+      'DBpia 인증정보가 없습니다. 설정 → 계정 정보 화면에서 DBpia 기관 계정을 저장하세요.'
+    );
+  }
+
+  // 기관 고정값 — secure_config 우선, 없으면 기본값
+  let b2bId, b2bName, b2bLoginType;
+  try {
+    b2bId        = getSecureConfig('source.dbpia.b2bId')        || 'ICST00001014';
+    b2bName      = getSecureConfig('source.dbpia.b2bName')      || '울산연구원';
+    b2bLoginType = getSecureConfig('source.dbpia.b2bLoginType') || '151004';
+  } catch {
+    b2bId        = 'ICST00001014';
+    b2bName      = '울산연구원';
+    b2bLoginType = '151004';
+  }
+
+  return { b2bAcc, userPass, b2bId, b2bName, b2bLoginType };
+}
+
+// ── 세션 클래스 ──────────────────────────────────────────────────────
+
+class DbpiaSession {
+  constructor() {
+    this._agent = new Agent({
+      connect: { connectTimeout: 15_000 },
+      connections: 3,
+      pipelining: 1,
+      keepAliveTimeout: 30_000,
+      keepAliveMaxTimeout: 60_000,
+      maxRedirections: 5,
+      headersTimeout: DEFAULT_TIMEOUT_MS,
+      bodyTimeout: DEFAULT_TIMEOUT_MS,
+    });
+    this._cookies = {};
+    this._loginTime = null;
+    this._lastRequestTime = 0;
+    this._bootstrapReady = false;
+    this._credentials = null;
+  }
+
+  get isExpired() {
+    return !this._loginTime || (Date.now() - this._loginTime) > SESSION_TTL_MS;
+  }
+
+  async _throttle() {
+    const elapsed = Date.now() - this._lastRequestTime;
+    if (elapsed < REQUEST_DELAY_MS)
+      await new Promise(r => setTimeout(r, REQUEST_DELAY_MS - elapsed));
+    this._lastRequestTime = Date.now();
+  }
+
+  /** 메인 페이지 방문으로 기본 쿠키(AWSALB, SESSION, dbp_bid 등) 수집 */
+  async _ensureBootstrap() {
+    if (this._bootstrapReady) return;
+
+    // 메인 페이지
+    const r1 = await request(URLS.bootstrap, {
+      method: 'GET',
+      dispatcher: this._agent,
+      headers: {
+        ...HEADERS_NAV,
+        'sec-fetch-dest': 'document',
+        'sec-fetch-mode': 'navigate',
+        'sec-fetch-site': 'none',
+      },
+    });
+    await readBody(r1);
+    mergeCookies(this._cookies, parseSetCookies(r1.headers));
+
+    // 로그인 페이지 (dbp_bid 수집)
+    const r2 = await request(URLS.loginPage, {
+      method: 'GET',
+      dispatcher: this._agent,
+      headers: {
+        ...HEADERS_NAV,
+        'sec-fetch-dest': 'document',
+        'sec-fetch-mode': 'navigate',
+        'sec-fetch-site': 'same-origin',
+        referer: URLS.bootstrap,
+        cookie: cookieStr(this._cookies),
+      },
+    });
+    await readBody(r2);
+    mergeCookies(this._cookies, parseSetCookies(r2.headers));
+
+    this._bootstrapReady = true;
+  }
+
+  async login() {
+    if (this._loginTime && !this.isExpired) return;
+
+    if (!this._credentials) this._credentials = loadCredentials();
+    const creds = this._credentials;
+
+    await this._ensureBootstrap();
+
+    const formBody = new URLSearchParams({
+      b2bAcc:       creds.b2bAcc,
+      userPass:     creds.userPass,
+      b2bLoginType: creds.b2bLoginType,
+      b2bId:        creds.b2bId,
+      b2bName:      creds.b2bName,
+      reAuth:       '',
+    }).toString();
+
+    const ctrl  = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+    let text;
+    try {
+      const res = await request(URLS.loginProc, {
+        method: 'POST',
+        dispatcher: this._agent,
+        signal: ctrl.signal,
+        headers: {
+          ...HEADERS_XHR,
+          'content-type': 'application/x-www-form-urlencoded',
+          referer: URLS.loginPage,
+          origin:  BASE_URL,
+          cookie:  cookieStr(this._cookies),
+        },
+        body: formBody,
+      });
+      text = await readBody(res);
+      mergeCookies(this._cookies, parseSetCookies(res.headers));
+    } finally {
+      clearTimeout(timer);
+    }
+
+    // 성공 검증: SESSION + NSSO 쿠키 확인
+    if (!this._cookies.SESSION && !this._cookies.NSSO) {
+      const preview = text?.startsWith('<') ? '(HTML 응답)' : text?.slice(0, 120);
+      throw new Error(`DBpia 로그인 실패: 세션 쿠키 없음. ${preview}`);
+    }
+
+    // 로그인 응답 JSON 검증 (경고만, 실패 처리 안함)
+    try {
+      const json = JSON.parse(text);
+      if (json.loginSucYN !== 'Y') {
+        console.warn(`[dbpia] 로그인 응답 loginSucYN=${json.loginSucYN}`);
+      }
+    } catch { /* JSON 아닐 수 있음 */ }
+
+    this._loginTime = Date.now();
+  }
+
+  cookieHeader() { return cookieStr(this._cookies); }
+
+  invalidate() {
+    this._cookies = {};
+    this._loginTime = null;
+    this._bootstrapReady = false;
+  }
+
+  async close() { await this._agent.close(); }
+}
+
+// ── 싱글턴 세션 ──────────────────────────────────────────────────────
+
+let _session = null;
+function getSession() {
+  if (!_session) _session = new DbpiaSession();
+  return _session;
+}
+
+/** 인증정보 변경 시 기존 세션 무효화 (server.js에서 호출) */
+export function invalidateDbpiaSession() {
+  if (_session) _session.invalidate();
+}
+
+// ── 검색 실행 ────────────────────────────────────────────────────────
+
+async function _doSearch(query, limit, page) {
+  const session = getSession();
+  await session.login();
+  await session._throttle();
+
+  const payload = JSON.stringify({
+    query,
+    page,
+    pageSize: Math.min(limit * 3, 100), // 파일 없는 결과 필터 후에도 충분히 남도록
+    sort: 'RANK',
+    searchType: 'ALL',
+    dataTypes: [],
+    language: 'KO',
+    isFullText: false,
+    isAccessible: false,
+    accessOption: 'ALL',
+    subjectCodes: [],
+    pbshYears: [],
+    plctNames: [],
+    publicationInfos: [],
+    collection: 'ALL',
+    includeAr: false,
+    collectionQuery: [],
+    filter: [],
+    prefix: [],
+    realQuery: '',
+    startDate: '1970.01.01',
+    endDate: '',
+    originText: false,
+  });
+
+  const referer = `${URLS.searchPage}?query=${encodeURIComponent(query)}`;
+  const ctrl    = new AbortController();
+  const timer   = setTimeout(() => ctrl.abort(), DEFAULT_TIMEOUT_MS);
+
+  let text;
+  try {
+    const res = await request(URLS.searchList, {
+      method: 'POST',
+      dispatcher: session._agent,
+      signal: ctrl.signal,
+      headers: {
+        ...HEADERS_XHR,
+        'content-type': 'application/json',
+        referer,
+        origin: BASE_URL,
+        cookie: session.cookieHeader(),
+      },
+      body: payload,
+    });
+    text = await readBody(res);
+    mergeCookies(session._cookies, parseSetCookies(res.headers));
+
+    if (!res.statusCode || res.statusCode >= 400) {
+      throw new Error(`DBpia 검색 HTTP ${res.statusCode}`);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+
+  // 세션 만료 감지 (HTML 응답)
+  if (text.startsWith('<!') || text.startsWith('<html') || text.startsWith('<HTML')) {
+    session.invalidate();
+    throw new Error('DBpia 세션 만료: 서버가 HTML 페이지를 반환했습니다');
+  }
+
+  let json;
+  try { json = JSON.parse(text); }
+  catch { throw new Error(`DBpia 검색 JSON 파싱 실패: ${text.slice(0, 120)}`); }
+
+  const rawList = json?.list ?? [];
+  const total   = json?.pageInfo?.totalCount ?? rawList.length;
+
+  return { rawList, total };
+}
+
+// ── Skill 클래스 ─────────────────────────────────────────────────────
+
+export class DbpiaSkill extends Skill {
+  static manifest = {
+    id: 'dbpia',
+    name: 'DBpia (학술 DB)',
+    version: '1.0.0',
+    defaultCron: null,          // 정기 수집 대상 아님
+    defaultKeywords: [
+      '도시기본계획', '도시재생', '스마트시티', '지속가능발전',
+      '지역경제', '주택정책', '교통계획',
+    ],
+    rateLimit: { rps: 1, burst: 2 },
+    requiredEnv: [],
+    capabilities: ['search', 'normalize', 'download'], // B2B 기관 세션으로 원문 다운로드 지원
+  };
+
+  get meta() {
+    return {
+      sessionTtlMs: SESSION_TTL_MS,
+      minRequestIntervalMs: REQUEST_DELAY_MS,
+      earlyStopConsecutiveEmpty: 3,
+      supportsRangeRequest: false,
+    };
+  }
+
+  /** DB 주입 (access cache upsert/조회용) — server.js 에서 호출 */
+  setDb(db) {
+    this._db = db;
+  }
+
+  _b2bId() {
+    try {
+      return getSecureConfig('source.dbpia.b2bId') || 'ICST00001014';
+    } catch {
+      return 'ICST00001014';
+    }
+  }
+
+  async ensureSession() {
+    await getSession().login();
+  }
+
+  invalidateSession() {
+    getSession().invalidate();
+  }
+
+  /**
+   * DBpia 학술 검색 (UI 실시간 검색 전용)
+   * - 학위논문(T*) 제외: downloadData HTTP 500 구조적 실패 (Sonnet §9.1)
+   * - access cache 기반 필터 (Phase 1): db 주입 시 strict=true 에서는 status='ok' 만 통과
+   * - externalLink 는 필터 조건으로 사용하지 않음 (판별력 없음, VOIS 연계 포함)
+   */
+  async search(query, { limit = 20, page = 1, db = null, strict = true } = {}) {
+    let rawList, total;
+    try {
+      ({ rawList, total } = await _doSearch(query, limit, page));
+    } catch (err) {
+      if (err.message.includes('세션 만료')) {
+        // 1회 자동 재시도
+        ({ rawList, total } = await _doSearch(query, limit, page));
+      } else {
+        throw err;
+      }
+    }
+
+    const seen = new Set();
+    let items = rawList
+      .filter(it => !String(it.nodeId || '').startsWith('T'))  // AD-2: 학위논문 차단
+      .map(it => normalizeDbpiaItem(it, query))
+      .filter(item => {
+        if (seen.has(item.docid)) return false;
+        seen.add(item.docid);
+        return true;
+      });
+
+    // Phase 1: access cache 적용 (db 미주입 시 노옵)
+    if (db) {
+      try {
+        const { filterByAccessCache } = await import('./_dbpia-access-filter.js');
+        const b2bId = getSecureConfig('source.dbpia.b2bId') || 'ICST00001014';
+        items = filterByAccessCache(items, { db, strict, b2bId });
+      } catch (e) {
+        console.warn('[dbpia] access cache 필터 미적용:', e.message);
+      }
+    }
+
+    return items.slice(0, limit);
+  }
+
+  /** discover: Phase 1 미지원 — 빈 배열 반환 */
+  async discover({ keywords = [], limit = 50 } = {}) {
+    return [];
+  }
+
+  /**
+   * DBpia 원문 PDF 다운로드 (B2B 기관 세션)
+   *
+   * 흐름:
+   *  1) articleDetail 방문 (Referer 체인 + 세션 워밍)
+   *  2) pdfView 방문 (뷰어 페이지 — 추가 세션 토큰 발급)
+   *  3) POST /download/downloadData (form-urlencoded) → JSON { link: "<download.dbpia.co.kr/File/Download?key=...>" }
+   *  4) GET link → PDF 바이너리 Response 반환
+   */
+  async openDownloadResponse(item, { signal } = {}) {
+    const session = getSession();
+    await session.login();
+
+    const nodeId = item.nodeId || (item.docid?.startsWith('dbpia-') ? item.docid.slice(6) : '');
+    if (!nodeId) {
+      throw new Error(`DBpia 다운로드: nodeId 없음 (docid=${item.docid})`);
+    }
+
+    // Phase 1: access cache upsert 준비 (db 주입 시에만)
+    const db = this._db;
+    const b2bId = this._b2bId();
+    const cacheUpsert = db
+      ? async (status, reason, extra = {}) => {
+          try {
+            const { upsertAccessCache } = await import('./_dbpia-access-filter.js');
+            upsertAccessCache(db, { nodeId, b2bId, status, reason, ...extra });
+          } catch (e) { console.warn('[dbpia] cache upsert 실패:', e.message); }
+        }
+      : async () => {};
+
+    // 1) articleDetail 방문
+    await session._throttle();
+    {
+      const r = await request(URLS.articleDetail(nodeId), {
+        method: 'GET',
+        dispatcher: session._agent,
+        headers: {
+          ...HEADERS_NAV,
+          'sec-fetch-dest': 'document',
+          'sec-fetch-mode': 'navigate',
+          'sec-fetch-site': 'same-origin',
+          referer: URLS.searchPage,
+          cookie: session.cookieHeader(),
+        },
+      });
+      await readBody(r);
+      mergeCookies(session._cookies, parseSetCookies(r.headers));
+      if (!session._cookies.SESSION && !session._cookies.NSSO) {
+        session.invalidate();
+        throw new Error('DBpia 세션 만료: articleDetail 방문 실패');
+      }
+    }
+
+    // 2) pdfView 방문 (뷰어 페이지 — 세션 쿠키 갱신·foreignIP 등 설정)
+    await session._throttle();
+    {
+      const r = await request(URLS.pdfView(nodeId), {
+        method: 'GET',
+        dispatcher: session._agent,
+        headers: {
+          ...HEADERS_NAV,
+          'sec-fetch-dest': 'document',
+          'sec-fetch-mode': 'navigate',
+          'sec-fetch-site': 'same-origin',
+          referer: URLS.articleDetail(nodeId),
+          cookie: session.cookieHeader(),
+        },
+      });
+      await readBody(r);
+      mergeCookies(session._cookies, parseSetCookies(r.headers));
+    }
+
+    // 3) POST /download/downloadData → JSON { link }
+    await session._throttle();
+    let downloadLink;
+    {
+      const body = new URLSearchParams({
+        nodeId,
+        systemCode: '',
+        depth: 'Article',
+        shape: 'pdf',
+      }).toString();
+      const r = await request(URLS.downloadData, {
+        method: 'POST',
+        dispatcher: session._agent,
+        headers: {
+          ...HEADERS_XHR,
+          'content-type': 'application/x-www-form-urlencoded',
+          origin: BASE_URL,
+          referer: URLS.pdfView(nodeId),
+          'x-referer': URLS.articleDetail(nodeId),
+          cookie: session.cookieHeader(),
+        },
+        body,
+      });
+      const text = await readBody(r);
+      mergeCookies(session._cookies, parseSetCookies(r.headers));
+
+      // 학위논문(T*) 등은 HTTP 500 반환 — 구조적 미지원 (nonRetryable)
+      if (r.statusCode >= 500) {
+        await cacheUpsert('thesis_unsupported', `HTTP ${r.statusCode}`);
+        const err = new Error(`DBpia downloadData HTTP ${r.statusCode}: 이 자료 타입은 원문 다운로드 미지원 (nodeId=${nodeId})`);
+        err.nonRetryable = true;
+        err.reason = 'thesis_unsupported';
+        throw err;
+      }
+
+      let json;
+      try { json = JSON.parse(text); }
+      catch {
+        await cacheUpsert('link_missing', 'JSON 파싱 실패');
+        const err = new Error(`DBpia downloadData JSON 파싱 실패: ${text.slice(0, 120)}`);
+        err.nonRetryable = true;
+        err.reason = 'link_missing';
+        throw err;
+      }
+
+      downloadLink = json.link;
+      if (!downloadLink) {
+        const msg = json.msg || json.resultCode || '원문 링크 없음';
+        if (json.isNotDownloadPlct === 'true') {
+          await cacheUpsert('publisher_disallow', msg);
+          const err = new Error(`DBpia 다운로드 불가: 해당 출판사가 다운로드를 허용하지 않음 (nodeId=${nodeId})`);
+          err.nonRetryable = true;
+          err.reason = 'publisher_disallow';
+          throw err;
+        }
+        await cacheUpsert('link_missing', msg);
+        const err = new Error(`DBpia 다운로드 불가: ${msg} (nodeId=${nodeId}, showAlert=${json.showAlert_YN})`);
+        err.nonRetryable = true;
+        err.reason = 'link_missing';
+        throw err;
+      }
+    }
+
+    // 4) ★ GET /pdfviewer/web/viewer.html?file=<encoded_link> (iframe 뷰어 워밍)
+    //    — 이 단계에서 download.dbpia.co.kr 접근에 필요한 dbp_auk 쿠키가 세팅됨
+    //    — 이 단계를 건너뛰면 download.dbpia.co.kr GET 시 HTML(접근 제한 페이지) 반환
+    const viewerFullUrl = `${BASE_URL}/pdfviewer/web/viewer.html?file=${encodeURIComponent(downloadLink)}`;
+    await session._throttle();
+    {
+      const r = await request(viewerFullUrl, {
+        method: 'GET',
+        dispatcher: session._agent,
+        headers: {
+          ...HEADERS_NAV,
+          'sec-fetch-dest': 'iframe',
+          'sec-fetch-mode': 'navigate',
+          'sec-fetch-site': 'same-origin',
+          referer: URLS.pdfView(nodeId),
+          cookie: session.cookieHeader(),
+        },
+      });
+      await readBody(r);
+      mergeCookies(session._cookies, parseSetCookies(r.headers));
+    }
+
+    // 5) GET {downloadLink} → PDF 바이너리 Response
+    await session._throttle();
+    const ctrl = signal ? null : new AbortController();
+    const timer = ctrl ? setTimeout(() => ctrl.abort(), 300_000) : null;
+    try {
+      const res = await fetch(downloadLink, {
+        method: 'GET',
+        dispatcher: session._agent,
+        redirect: 'follow',
+        signal: signal ?? ctrl.signal,
+        headers: {
+          'user-agent':      CHROME_UA,
+          'accept':          'application/pdf,application/octet-stream,*/*',
+          'accept-language': 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+          'accept-encoding': 'identity',
+          'sec-fetch-dest':  'empty',       // pdf.js 시뮬레이션 (cors 모드)
+          'sec-fetch-mode':  'cors',
+          'sec-fetch-site':  'same-site',
+          origin:  BASE_URL,
+          referer: viewerFullUrl,          // iframe viewer.html을 Referer로
+          cookie:  session.cookieHeader(),
+        },
+      });
+
+      if (res.status === 401 || res.status === 403) {
+        session.invalidate();
+        await cacheUpsert('license_out', `HTTP ${res.status}`);
+        const err = new Error(`DBpia 원문 권한 없음 (HTTP ${res.status})`);
+        err.nonRetryable = true;
+        err.reason = 'license_out_of_scope';
+        throw err;
+      }
+
+      // 200 + text/html 선제 분류 — 라이선스 범위 밖 접근 제한 페이지 반환
+      // (downloader.js 가 재감지하면 invalidateSession 이 잘못 호출될 수 있으므로 여기서 차단)
+      const ctype = res.headers.get('content-type') || '';
+      if (/^text\/html/i.test(ctype)) {
+        await cacheUpsert('license_out', 'HTML 응답', { contentType: ctype });
+        const err = new Error('DBpia: 기관 라이선스 범위 밖 또는 외부 연계자료');
+        err.nonRetryable = true;
+        err.reason = 'license_out_of_scope';
+        // 세션은 유효 — invalidate 하지 않음
+        throw err;
+      }
+
+      // 성공 경로 — 응답은 downloader 가 stream 처리하므로 여기서 cache 는 적재 안 함
+      // (downloader 완료 후 별도 훅에서 적재해야 정확한 bytes 기록. 일단 'ok' 를 선제 기록)
+      const cl = Number(res.headers.get('content-length')) || null;
+      await cacheUpsert('ok', null, { contentType: ctype, bytes: cl });
+
+      return res;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  normalize(item, _unused, query) {
+    return normalizeDbpiaItem(item, query);
+  }
+}
+
+export default DbpiaSkill;