@bstage-sdk/bridge 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -139,16 +139,16 @@ host.dispose()
139
139
 
140
140
  `new URL(url, hostOrigin)`으로 정규화한 뒤 목적지를 네 갈래로 나눈다.
141
141
 
142
- | 갈래 | 조건 | fetch | 자격증명·헤더 |
143
- | ---------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------- |
144
- | `gateway` | 같은 origin, 경로가 `gatewayPrefixes`(기본 `["/gw/"]`, `/gw` 정확 일치 포함) 안·거절 규칙 밖 | `fetchImpl` | `credentials: 'same-origin'`, 허용 헤더 + `pinnedHeaders` |
145
- | `partner` | `partnerOrigins`(**팬 토큰을 보낼 vibe 백엔드**, https 정확한 origin, 최대 10개, hostOrigin 제외)와 정확히 일치 | `partnerFetchImpl` | `credentials: 'omit'`, `referrerPolicy: 'no-referrer'`, 허용 헤더만 |
146
- | `external` | 그 밖의 https origin(hostOrigin 아님). **등록 불필요**. `policy.allowExternal: true`일 때만(기본 `false`, 옵트인) | `externalFetchImpl` | `credentials: 'omit'`, `referrerPolicy: 'no-referrer'`, 허용 헤더만 |
147
- | 거절 | http, userinfo, 비 http 스킴, 같은 origin의 `/gw` 밖·거절 경로, `allowExternal`을 켜지 않았을 때의 external | — | `FORBIDDEN_DESTINATION` |
142
+ | 갈래 | 조건 | fetch | 자격증명·헤더 |
143
+ | ---------- | ----------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------- |
144
+ | `gateway` | 같은 origin, 경로가 `gatewayPrefixes`(기본 `["/gw/"]`, `/gw` 정확 일치 포함) 안·거절 규칙 밖 | `fetchImpl` | `credentials: 'same-origin'`, 템플릿 헤더 + `pinnedHeaders` |
145
+ | `partner` | `partnerOrigins`(**팬 토큰을 보낼 vibe 백엔드**, https 정확한 origin, 최대 10개, hostOrigin 제외)와 정확히 일치 | `partnerFetchImpl` | `credentials: 'omit'`, `referrerPolicy: 'no-referrer'`, 템플릿 헤더 + `pinnedHeaders` |
146
+ | `external` | 그 밖의 https origin(hostOrigin 아님). **등록 불필요**. `policy.allowExternal: true`일 때만(기본 `false`, 옵트인) | `externalFetchImpl` | `credentials: 'omit'`, `referrerPolicy: 'no-referrer'`, 허용 헤더만 |
147
+ | 거절 | http, userinfo, 비 http 스킴, 같은 origin의 `/gw` 밖·거절 경로, `allowExternal`을 켜지 않았을 때의 external | — | `FORBIDDEN_DESTINATION` |
148
148
 
149
149
  - 세 갈래 모두 `redirect: 'error'`, 메서드·본문 상한·분당/동시 요청 상한·응답 본문 상한이 같게 적용된다.
150
150
  - 같은 origin은 gateway 규칙만 적용한다. hostOrigin을 파트너 목록에 넣어도 `/gw` 밖 경로는 열리지 않고, external로도 통과하지 않는다.
151
- - `pinnedHeaders`(테넌시·앱 헤더)는 **gateway에만** 싣는다. partner·external에는 프레임이 보낸 허용 헤더만 간다.
151
+ - 토큰이 실리는 요청(gateway·partner)에는 템플릿이 붙인 헤더가 그대로 가고 그 위에 `pinnedHeaders`가 덮인다. external에는 허용 헤더만 가고 `pinnedHeaders`는 싣지 않는다.
152
152
  - external·partner 기본 fetch는 `globalThis.fetch`를 쿠키·인증 헤더·Referer 없이 부른다. 응답은 호스트 페이지 origin 기준 CORS를 따른다.
153
153
  - external은 요청이 사용자 브라우저에서 호스트 `Origin`으로 나가므로 **IP 리터럴·단일 레이블·빈 레이블·로컬/예약 이름(`localhost`·`local`·`internal`·`home.arpa`·`test`·`invalid`·`example`·`lan`·`corp`·`intranet`·`localdomain`과 그 하위)·
154
154
  호스트와 같은 호스트명(다른 포트·끝 점 몇 개든)**을 겨누지 못한다(사설 IP로 풀리는 DNS 이름은 브라우저의 Local Network Access가 다룬다).
@@ -173,11 +173,22 @@ host.dispose()
173
173
  격리 프레임에서는 부를 수 없다(수용한 제약). 거절 규칙은 gateway 경로에만 적용한다.
174
174
  - userinfo가 붙은 URL은 거절한다.
175
175
  - 메서드는 GET·HEAD·POST·PUT·PATCH·DELETE.
176
- - 요청 헤더는 `content-type`·`accept`·`accept-language`, 앱 헤더 `x-bstage-app-id`·`x-bstage-app-key`, `x-bmf-sdk-version`만 프레임 값을
177
- 통과시킨다(대소문자 무시, 세 갈래 공통). **테넌시 헤더(`x-bstage-tenant-id`·`x-bstage-org-id`·`x-bstage-enterprise-id`)는 프레임 값을
178
- 버리고** 호스트가 `pinnedHeaders`로 준 값만 게이트웨이 요청에 싣는다(앱 헤더도 여기 주면 프레임 값을 덮는다).
179
- `authorization`·`cookie`·(`x-bmf-sdk-version` 밖의) `x-bmf-*` 등 나머지는 버린다. 템플릿의 `BstageClient`가 테넌트 헤더를 보내므로 호스트는
180
- `pinnedHeaders: { 'x-bstage-tenant-id': spaceId }`처럼 현재 스페이스 값을 고정해야 한다.
176
+ - 요청 헤더(키는 소문자로 정규화):
177
+ - **토큰이 실리는 요청(gateway·partner)**: 템플릿이 붙인 헤더를 inline 실행과 같이 그대로 넘긴다(`x-bmf-language` 등 사용자 정의 헤더 포함,
178
+ 최대 `MAX_PASS_THROUGH_HEADERS`=32개 — 넘으면 `BAD_REQUEST`). 다음은 프레임 값을 버린다.
179
+ - 자격증명(`CREDENTIAL_HEADERS`): `authorization`·`proxy-authorization`·`authentication`·`cookie`·CF Access 3종·`x-api-key`·`api-key`·
180
+ `x-auth-token`·`x-access-token`·`x-amz-security-token`·`x-csrf-token`·`x-xsrf-token`. 토큰은 호스트의 주입 fetch만 붙인다.
181
+ - 테넌시·스페이스(`HOST_ONLY_HEADERS`): `x-bstage-tenant-id`·`x-bstage-org-id`·`x-bstage-enterprise-id`·`x-bmf-space-id`·`x-bmf-sid`.
182
+ 호스트가 `pinnedHeaders`로 준 값만 실린다.
183
+ - 라우팅·신뢰(`ROUTING_HEADERS`·`ROUTING_HEADER_PREFIXES`): `host`·`forwarded`·`x-real-ip`·`x-client-ip`·`true-client-ip`·
184
+ `x-original-url`·`x-rewrite-url`·`x-original-method`·`x-http-method-override`·`x-http-method`·`x-method-override`·`x-bmf-tier`,
185
+ 접두사 `x-forwarded-`·`x-envoy-`·`x-amz-`·`proxy-`·`sec-`·`cf-`.
186
+ - `pinnedHeaders`의 다른 키는 템플릿 값을 덮는다.
187
+ - **external**: `content-type`·`accept`·`accept-language`, 앱 헤더 `x-bstage-app-id`·`x-bstage-app-key`, `x-bmf-sdk-version`만 통과(대소문자 무시).
188
+ - 이름이 올바르지 않거나 값이 문자열이 아니거나 개행·NUL이 든 헤더는 버린다.
189
+ - 템플릿의 `BstageClient`가 테넌트 헤더를 보내고 파트너 백엔드가 스페이스 헤더를 요구할 수 있으므로 호스트는
190
+ `pinnedHeaders: { 'x-bstage-tenant-id': spaceId, 'x-bmf-space-id': spaceId }`처럼 현재 스페이스 값을 고정해야 한다.
191
+ - 파트너 백엔드는 템플릿이 보내는 비단순 헤더(`x-bmf-*` 등)를 CORS `Access-Control-Allow-Headers`에 열어 두어야 한다.
181
192
  - 본문은 문자열만, UTF-8 바이트로 `maxBodyBytes`(기본 1MB) 이하. 프레임별 분당 `maxRequestsPerMinute`(기본 300,
182
193
  resize 제외), 동시 진행 fetch 16개, toast 분당 5회, ready 응답 초당 2회, resize 초당 30회.
183
194
  - 응답 본문은 스트림으로 읽으며 `maxResponseBytes`(기본 10MB)를 넘는 순간 취소한다.
@@ -195,7 +206,7 @@ host.dispose()
195
206
  프레임으로 흘릴 수 있다는 위험을 받아들이는 것이다.** 그래서 `partnerOrigins`에는 팬 토큰을 보낼 vibe 백엔드만 넣는다.
196
207
 
197
208
  `externalFetchImpl`의 기본값도 같은 무인증 fetch다. 토큰 없이 부르는 공개 API·CDN은 등록 없이 이 갈래로 간다.
198
- external에 인증을 붙이는 fetch를 주입하지 않는다. 외부 갈래는 **옵트인**이다 — 켜면 프레임이 임의 https로 데이터를 보내고 응답을 읽는 양방향 채널이 생기므로, 패키지를 올리기만 해서 열리지 않게 기본을 `false`로 둔다. 외부 호출을 허용하는 호스트만 `allowExternal: true`를 명시한다(포털 미리보기 등은 생략).
209
+ external에 인증을 붙이는 fetch를 주입하지 않는다. 외부 갈래는 **옵트인**이다 — 켜면 프레임이 임의 https로 데이터를 보내고 응답을 읽는 양방향 채널이 생기므로, 패키지를 올리기만 해서 열리지 않게 기본을 `false`로 둔다. 외부 호출을 허용하는 호스트만 `allowExternal: true`를 명시한다(콘솔 미리보기 등은 생략).
199
210
 
200
211
  ## 요청과 이벤트
201
212
 
@@ -210,7 +221,7 @@ external에 인증을 붙이는 fetch를 주입하지 않는다. 외부 갈래
210
221
  | `track` | `{ name, params? }` | 이름 100자, params 직렬화 4KB |
211
222
  | `storage` | `{ op, key, value? }` | placement 스코프 메모리(키 50개, 값 4KB) |
212
223
  | `log` | `{ level, message }` | real phase에서는 버림 |
213
- | `report` | `{ kind, message, frames, count }` | 템플릿 에러 보고. 아래 "에러 보고" |
224
+ | `report` | `{ kind, message, frames, count }` | 템플릿 에러 보고. 아래 "에러 보고" |
214
225
 
215
226
  이벤트(호스트 → 프레임, `host.send`): `slot.context`·`locale`(`{ locale, translations? }`)·`member`·`theme`·`visibility`.
216
227
 
@@ -271,7 +282,7 @@ connect-src https: wss:; frame-src 'none'; form-action 'none'; base-uri 'none'
271
282
  ### 프레임 네트워크 (항상 적용)
272
283
 
273
284
  결정(2026-10-21, 2026-10-22에 옵트인 제거): 격리 프레임에서 **토큰이 필요한 정해진 API만 브리지**로 보내고(호스트가 팬 토큰을 붙인다),
274
- **그 밖의 API는 템플릿이 프레임 안에서 직접** 부른다. 호스트 옵션은 없다 — `createSrcdoc`로 만든 모든 프레임(포털 미리보기 포함)이
285
+ **그 밖의 API는 템플릿이 프레임 안에서 직접** 부른다. 호스트 옵션은 없다 — `createSrcdoc`로 만든 모든 프레임(콘솔 미리보기 포함)이
275
286
  이 규칙으로 돈다. (0.3.0에서 추가한 `directNetwork` 옵트인과 `buildFrameCsp`의 4번째 인자 `FrameCspOptions`는 다음 minor에서 없앴다. 넘기던 호스트는 인자를 지우면 된다.)
276
287
 
277
288
  동작:
@@ -183,8 +183,54 @@ var ALLOWED_REQUEST_HEADERS = Object.freeze([
183
183
  var HOST_ONLY_HEADERS = Object.freeze([
184
184
  "x-bstage-tenant-id",
185
185
  "x-bstage-org-id",
186
- "x-bstage-enterprise-id"
186
+ "x-bstage-enterprise-id",
187
+ // 스페이스 지정 헤더 — 프레임이 다른 스페이스로 회원 자격 요청을 돌리지 못하게 호스트 값만 싣는다.
188
+ "x-bmf-space-id",
189
+ "x-bmf-sid"
187
190
  ]);
191
+ var CREDENTIAL_HEADERS = Object.freeze([
192
+ "authorization",
193
+ "proxy-authorization",
194
+ "authentication",
195
+ "cookie",
196
+ "cf-access-client-id",
197
+ "cf-access-client-secret",
198
+ "cf-access-token",
199
+ "x-api-key",
200
+ "api-key",
201
+ "x-auth-token",
202
+ "x-access-token",
203
+ "x-amz-security-token",
204
+ "x-csrf-token",
205
+ "x-xsrf-token"
206
+ ]);
207
+ var ROUTING_HEADERS = Object.freeze([
208
+ "host",
209
+ "forwarded",
210
+ "x-real-ip",
211
+ "x-client-ip",
212
+ "true-client-ip",
213
+ "x-original-url",
214
+ "x-rewrite-url",
215
+ "x-original-method",
216
+ "x-http-method-override",
217
+ "x-http-method",
218
+ "x-method-override",
219
+ "x-bmf-tier"
220
+ ]);
221
+ var ROUTING_HEADER_PREFIXES = Object.freeze([
222
+ "x-forwarded-",
223
+ "x-envoy-",
224
+ "x-amz-",
225
+ "proxy-",
226
+ "sec-",
227
+ "cf-"
228
+ ]);
229
+ function isFrameDeniedHeader(name) {
230
+ return CREDENTIAL_HEADERS.includes(name) || HOST_ONLY_HEADERS.includes(name) || ROUTING_HEADERS.includes(name) || ROUTING_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix));
231
+ }
232
+ var MAX_PASS_THROUGH_HEADERS = 32;
233
+ var HEADER_NAME_RE = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
188
234
  var ALLOWED_METHODS = Object.freeze([
189
235
  "GET",
190
236
  "HEAD",
@@ -334,7 +380,7 @@ function normalizePinnedHeaders(pinned) {
334
380
  }
335
381
  const entries = Object.entries(pinned).map(([k, v]) => {
336
382
  const key = k.toLowerCase();
337
- if (!ALLOWED_REQUEST_HEADERS.includes(key) && !HOST_ONLY_HEADERS.includes(key)) {
383
+ if (!HEADER_NAME_RE.test(key) || CREDENTIAL_HEADERS.includes(key)) {
338
384
  throw new TypeError(`[bstage-bridge] pinnedHeaders\uC5D0 \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uB294 \uD5E4\uB354: ${k}`);
339
385
  }
340
386
  if (typeof v !== "string" || UNSAFE_HEADER_VALUE_RE.test(v)) {
@@ -344,8 +390,19 @@ function normalizePinnedHeaders(pinned) {
344
390
  });
345
391
  return Object.freeze(Object.fromEntries(entries));
346
392
  }
393
+ function passThroughHeaders(headers) {
394
+ if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return {};
395
+ const raw = Object.entries(headers);
396
+ if (raw.length > MAX_PASS_THROUGH_HEADERS) {
397
+ throw new BridgeError("BAD_REQUEST", "too many headers");
398
+ }
399
+ const entries = raw.map(([k, v]) => [k.toLowerCase(), v]).filter(
400
+ (entry) => HEADER_NAME_RE.test(entry[0]) && !isFrameDeniedHeader(entry[0]) && typeof entry[1] === "string" && !UNSAFE_HEADER_VALUE_RE.test(entry[1])
401
+ );
402
+ return Object.freeze(Object.fromEntries(entries));
403
+ }
347
404
  function mergeHeaders(frameHeaders, pinned) {
348
- return Object.freeze({ ...filterHeaders(frameHeaders), ...pinned });
405
+ return Object.freeze({ ...passThroughHeaders(frameHeaders), ...pinned });
349
406
  }
350
407
  function filterHeaders(headers) {
351
408
  if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return {};
@@ -376,7 +433,7 @@ function prepareFetch(payload, ctx) {
376
433
  const method = resolveMethod(req.method);
377
434
  const { url, kind } = classifyDestination(req.url, ctx);
378
435
  const body = resolveBody(req.body, method, ctx.policy.maxBodyBytes);
379
- const headers = kind === "gateway" ? mergeHeaders(req.headers, ctx.pinnedHeaders ?? {}) : filterHeaders(req.headers);
436
+ const headers = kind === "external" ? filterHeaders(req.headers) : mergeHeaders(req.headers, ctx.pinnedHeaders ?? {});
380
437
  return {
381
438
  url,
382
439
  kind,
@@ -604,6 +661,10 @@ export {
604
661
  DEFAULT_POLICY,
605
662
  ALLOWED_REQUEST_HEADERS,
606
663
  HOST_ONLY_HEADERS,
664
+ CREDENTIAL_HEADERS,
665
+ ROUTING_HEADERS,
666
+ ROUTING_HEADER_PREFIXES,
667
+ MAX_PASS_THROUGH_HEADERS,
607
668
  ALLOWED_METHODS,
608
669
  MAX_PARTNER_ORIGINS,
609
670
  resolvePolicy,
package/dist/host.cjs CHANGED
@@ -23,13 +23,17 @@ __export(host_exports, {
23
23
  ALLOWED_METHODS: () => ALLOWED_METHODS,
24
24
  ALLOWED_REQUEST_HEADERS: () => ALLOWED_REQUEST_HEADERS,
25
25
  BRIDGE_SURFACES: () => BRIDGE_SURFACES,
26
+ CREDENTIAL_HEADERS: () => CREDENTIAL_HEADERS,
26
27
  DEFAULT_GATEWAY_DENY_SEGMENTS: () => DEFAULT_GATEWAY_DENY_SEGMENTS,
27
28
  DEFAULT_POLICY: () => DEFAULT_POLICY,
28
29
  HOST_ONLY_HEADERS: () => HOST_ONLY_HEADERS,
29
30
  IFRAME_ATTRIBUTES: () => IFRAME_ATTRIBUTES,
30
31
  MAX_DECODE_PASSES: () => MAX_DECODE_PASSES,
31
32
  MAX_PARTNER_ORIGINS: () => MAX_PARTNER_ORIGINS,
33
+ MAX_PASS_THROUGH_HEADERS: () => MAX_PASS_THROUGH_HEADERS,
32
34
  REPORTS_PER_SESSION: () => REPORTS_PER_SESSION,
35
+ ROUTING_HEADERS: () => ROUTING_HEADERS,
36
+ ROUTING_HEADER_PREFIXES: () => ROUTING_HEADER_PREFIXES,
33
37
  checkPath: () => checkPath,
34
38
  classifyDestination: () => classifyDestination,
35
39
  createBridgeHost: () => createBridgeHost,
@@ -224,8 +228,54 @@ var ALLOWED_REQUEST_HEADERS = Object.freeze([
224
228
  var HOST_ONLY_HEADERS = Object.freeze([
225
229
  "x-bstage-tenant-id",
226
230
  "x-bstage-org-id",
227
- "x-bstage-enterprise-id"
231
+ "x-bstage-enterprise-id",
232
+ // 스페이스 지정 헤더 — 프레임이 다른 스페이스로 회원 자격 요청을 돌리지 못하게 호스트 값만 싣는다.
233
+ "x-bmf-space-id",
234
+ "x-bmf-sid"
228
235
  ]);
236
+ var CREDENTIAL_HEADERS = Object.freeze([
237
+ "authorization",
238
+ "proxy-authorization",
239
+ "authentication",
240
+ "cookie",
241
+ "cf-access-client-id",
242
+ "cf-access-client-secret",
243
+ "cf-access-token",
244
+ "x-api-key",
245
+ "api-key",
246
+ "x-auth-token",
247
+ "x-access-token",
248
+ "x-amz-security-token",
249
+ "x-csrf-token",
250
+ "x-xsrf-token"
251
+ ]);
252
+ var ROUTING_HEADERS = Object.freeze([
253
+ "host",
254
+ "forwarded",
255
+ "x-real-ip",
256
+ "x-client-ip",
257
+ "true-client-ip",
258
+ "x-original-url",
259
+ "x-rewrite-url",
260
+ "x-original-method",
261
+ "x-http-method-override",
262
+ "x-http-method",
263
+ "x-method-override",
264
+ "x-bmf-tier"
265
+ ]);
266
+ var ROUTING_HEADER_PREFIXES = Object.freeze([
267
+ "x-forwarded-",
268
+ "x-envoy-",
269
+ "x-amz-",
270
+ "proxy-",
271
+ "sec-",
272
+ "cf-"
273
+ ]);
274
+ function isFrameDeniedHeader(name) {
275
+ return CREDENTIAL_HEADERS.includes(name) || HOST_ONLY_HEADERS.includes(name) || ROUTING_HEADERS.includes(name) || ROUTING_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix));
276
+ }
277
+ var MAX_PASS_THROUGH_HEADERS = 32;
278
+ var HEADER_NAME_RE = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
229
279
  var ALLOWED_METHODS = Object.freeze([
230
280
  "GET",
231
281
  "HEAD",
@@ -375,7 +425,7 @@ function normalizePinnedHeaders(pinned) {
375
425
  }
376
426
  const entries = Object.entries(pinned).map(([k, v]) => {
377
427
  const key = k.toLowerCase();
378
- if (!ALLOWED_REQUEST_HEADERS.includes(key) && !HOST_ONLY_HEADERS.includes(key)) {
428
+ if (!HEADER_NAME_RE.test(key) || CREDENTIAL_HEADERS.includes(key)) {
379
429
  throw new TypeError(`[bstage-bridge] pinnedHeaders\uC5D0 \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uB294 \uD5E4\uB354: ${k}`);
380
430
  }
381
431
  if (typeof v !== "string" || UNSAFE_HEADER_VALUE_RE.test(v)) {
@@ -385,8 +435,19 @@ function normalizePinnedHeaders(pinned) {
385
435
  });
386
436
  return Object.freeze(Object.fromEntries(entries));
387
437
  }
438
+ function passThroughHeaders(headers) {
439
+ if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return {};
440
+ const raw = Object.entries(headers);
441
+ if (raw.length > MAX_PASS_THROUGH_HEADERS) {
442
+ throw new BridgeError("BAD_REQUEST", "too many headers");
443
+ }
444
+ const entries = raw.map(([k, v]) => [k.toLowerCase(), v]).filter(
445
+ (entry) => HEADER_NAME_RE.test(entry[0]) && !isFrameDeniedHeader(entry[0]) && typeof entry[1] === "string" && !UNSAFE_HEADER_VALUE_RE.test(entry[1])
446
+ );
447
+ return Object.freeze(Object.fromEntries(entries));
448
+ }
388
449
  function mergeHeaders(frameHeaders, pinned) {
389
- return Object.freeze({ ...filterHeaders(frameHeaders), ...pinned });
450
+ return Object.freeze({ ...passThroughHeaders(frameHeaders), ...pinned });
390
451
  }
391
452
  function filterHeaders(headers) {
392
453
  if (typeof headers !== "object" || headers === null || Array.isArray(headers)) return {};
@@ -417,7 +478,7 @@ function prepareFetch(payload, ctx) {
417
478
  const method = resolveMethod(req.method);
418
479
  const { url, kind } = classifyDestination(req.url, ctx);
419
480
  const body = resolveBody(req.body, method, ctx.policy.maxBodyBytes);
420
- const headers = kind === "gateway" ? mergeHeaders(req.headers, ctx.pinnedHeaders ?? {}) : filterHeaders(req.headers);
481
+ const headers = kind === "external" ? filterHeaders(req.headers) : mergeHeaders(req.headers, ctx.pinnedHeaders ?? {});
421
482
  return {
422
483
  url,
423
484
  kind,
@@ -1794,13 +1855,17 @@ ${script}
1794
1855
  ALLOWED_METHODS,
1795
1856
  ALLOWED_REQUEST_HEADERS,
1796
1857
  BRIDGE_SURFACES,
1858
+ CREDENTIAL_HEADERS,
1797
1859
  DEFAULT_GATEWAY_DENY_SEGMENTS,
1798
1860
  DEFAULT_POLICY,
1799
1861
  HOST_ONLY_HEADERS,
1800
1862
  IFRAME_ATTRIBUTES,
1801
1863
  MAX_DECODE_PASSES,
1802
1864
  MAX_PARTNER_ORIGINS,
1865
+ MAX_PASS_THROUGH_HEADERS,
1803
1866
  REPORTS_PER_SESSION,
1867
+ ROUTING_HEADERS,
1868
+ ROUTING_HEADER_PREFIXES,
1804
1869
  checkPath,
1805
1870
  classifyDestination,
1806
1871
  createBridgeHost,
package/dist/host.d.cts CHANGED
@@ -50,8 +50,8 @@ interface BridgePolicy {
50
50
  declare const DEFAULT_GATEWAY_DENY_SEGMENTS: readonly string[];
51
51
  declare const DEFAULT_POLICY: BridgePolicy;
52
52
  /**
53
- * 통과시키는 요청 헤더(소문자). 나머지(authorization·cookie·`x-bmf-sdk-version` 밖의 x-bmf-* 포함)는 버린다.
54
- * 목적지 갈래(gateway·partner·external)와 무관하게 같은 목록이다.
53
+ * external(토큰 없는 그 밖의 https) 요청에 통과시키는 요청 헤더(소문자). 나머지는 버린다.
54
+ * 토큰이 실리는 gateway·partner 요청은 이 목록이 아니라 {@link passThroughHeaders} 규칙을 따른다.
55
55
  */
56
56
  declare const ALLOWED_REQUEST_HEADERS: readonly string[];
57
57
  /**
@@ -59,6 +59,19 @@ declare const ALLOWED_REQUEST_HEADERS: readonly string[];
59
59
  * 프레임이 테넌트를 고르면 사용자 자격증명이 실린 요청을 다른 테넌트로 보내 응답을 읽을 수 있다.
60
60
  */
61
61
  declare const HOST_ONLY_HEADERS: readonly string[];
62
+ /**
63
+ * 자격증명 헤더 — 어느 갈래에서도 프레임 값을 통과시키지 않고 `pinnedHeaders`로도 받지 않는다.
64
+ * 회원 토큰·쿠키·CF Access는 호스트의 주입 fetch만 붙인다. 백엔드가 인증·CSRF 근거로 읽는 흔한 이름도 포함한다.
65
+ */
66
+ declare const CREDENTIAL_HEADERS: readonly string[];
67
+ /**
68
+ * 라우팅·신뢰 헤더 — 프록시·게이트웨이가 경로·메서드·클라이언트 IP·내부 티어를 바꾸는 근거로 읽는다.
69
+ * 프레임 값은 통과시키지 않는다(정확 일치 + 접두사).
70
+ */
71
+ declare const ROUTING_HEADERS: readonly string[];
72
+ declare const ROUTING_HEADER_PREFIXES: readonly string[];
73
+ /** 토큰이 실리는 요청에 프레임이 보낼 수 있는 헤더 개수 상한. */
74
+ declare const MAX_PASS_THROUGH_HEADERS = 32;
62
75
  declare const ALLOWED_METHODS: readonly string[];
63
76
  /** partnerOrigins 최대 개수. */
64
77
  declare const MAX_PARTNER_ORIGINS = 10;
@@ -78,7 +91,7 @@ interface DestinationContext {
78
91
  readonly hostOrigin: string;
79
92
  readonly partnerOrigins: readonly string[];
80
93
  readonly policy: BridgePolicy;
81
- /** 게이트웨이 요청에 호스트가 덮어 싣는 헤더(`normalizePinnedHeaders` 결과). 파트너·외부 요청에는 싣지 않는다. */
94
+ /** 토큰이 실리는 요청(gateway·partner)에 호스트가 덮어 싣는 헤더(`normalizePinnedHeaders` 결과). 외부 요청에는 싣지 않는다. */
82
95
  readonly pinnedHeaders?: Readonly<Record<string, string>>;
83
96
  }
84
97
  /**
@@ -106,8 +119,8 @@ declare function classifyDestination(rawUrl: unknown, ctx: DestinationContext):
106
119
  /** `classifyDestination`의 URL만. */
107
120
  declare function resolveDestination(rawUrl: unknown, ctx: DestinationContext): string;
108
121
  /**
109
- * 호스트가 고정하는 헤더를 검증·소문자화한다. 허용 헤더·테넌시 헤더만 받는다(그 밖은 TypeError —
110
- * 이 경로로 authorization 같은 값을 실수로 넣지 못하게).
122
+ * 호스트가 고정하는 헤더를 검증·소문자화한다. 올바른 헤더 이름이면 받고, 자격증명 헤더
123
+ * ({@link CREDENTIAL_HEADERS})는 TypeError — 이 경로로 authorization 같은 값을 실수로 넣지 못하게.
111
124
  */
112
125
  declare function normalizePinnedHeaders(pinned: unknown): Readonly<Record<string, string>>;
113
126
  interface PreparedFetch {
@@ -206,9 +219,10 @@ interface CreateBridgeHostOptions {
206
219
  */
207
220
  readonly externalFetchImpl?: HostFetch;
208
221
  /**
209
- * 게이트웨이 요청에 호스트가 덮어 싣는 헤더. 테넌시 헤더(`x-bstage-tenant-id`·`x-bstage-org-id`·
210
- * `x-bstage-enterprise-id`)는 프레임 값이 버려지고 **여기 준 값만** 실린다. 앱 헤더
211
- * (`x-bstage-app-id`·`x-bstage-app-key`)는 여기 주면 프레임 값을 덮는다. 그 밖의 키는 TypeError.
222
+ * 토큰이 실리는 요청(gateway·partner)에 호스트가 덮어 싣는 헤더. 그 요청에는 템플릿이 붙인 헤더가 그대로
223
+ * 실리고(자격증명·테넌시 헤더 제외) 그 위에 이 값이 덮인다. 테넌시 헤더(`x-bstage-tenant-id`·
224
+ * `x-bstage-org-id`·`x-bstage-enterprise-id`)는 프레임 값이 버려지고 **여기 준 값만** 실린다. 그 밖의 키는
225
+ * 프레임 값을 덮는다. 자격증명 헤더(`authorization`·`cookie`·CF Access)나 올바르지 않은 이름은 TypeError.
212
226
  */
213
227
  readonly pinnedHeaders?: Readonly<Record<string, string>>;
214
228
  readonly handlers?: BridgeHostHandlers;
@@ -285,4 +299,4 @@ interface PathCheck {
285
299
  */
286
300
  declare function checkPath(pathname: string, options?: PathCheckOptions): PathCheck;
287
301
 
288
- export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeDisposeReason, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, TemplateReport, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };
302
+ export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeDisposeReason, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, CREDENTIAL_HEADERS, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, MAX_PASS_THROUGH_HEADERS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, ROUTING_HEADERS, ROUTING_HEADER_PREFIXES, TemplateReport, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };
package/dist/host.d.ts CHANGED
@@ -50,8 +50,8 @@ interface BridgePolicy {
50
50
  declare const DEFAULT_GATEWAY_DENY_SEGMENTS: readonly string[];
51
51
  declare const DEFAULT_POLICY: BridgePolicy;
52
52
  /**
53
- * 통과시키는 요청 헤더(소문자). 나머지(authorization·cookie·`x-bmf-sdk-version` 밖의 x-bmf-* 포함)는 버린다.
54
- * 목적지 갈래(gateway·partner·external)와 무관하게 같은 목록이다.
53
+ * external(토큰 없는 그 밖의 https) 요청에 통과시키는 요청 헤더(소문자). 나머지는 버린다.
54
+ * 토큰이 실리는 gateway·partner 요청은 이 목록이 아니라 {@link passThroughHeaders} 규칙을 따른다.
55
55
  */
56
56
  declare const ALLOWED_REQUEST_HEADERS: readonly string[];
57
57
  /**
@@ -59,6 +59,19 @@ declare const ALLOWED_REQUEST_HEADERS: readonly string[];
59
59
  * 프레임이 테넌트를 고르면 사용자 자격증명이 실린 요청을 다른 테넌트로 보내 응답을 읽을 수 있다.
60
60
  */
61
61
  declare const HOST_ONLY_HEADERS: readonly string[];
62
+ /**
63
+ * 자격증명 헤더 — 어느 갈래에서도 프레임 값을 통과시키지 않고 `pinnedHeaders`로도 받지 않는다.
64
+ * 회원 토큰·쿠키·CF Access는 호스트의 주입 fetch만 붙인다. 백엔드가 인증·CSRF 근거로 읽는 흔한 이름도 포함한다.
65
+ */
66
+ declare const CREDENTIAL_HEADERS: readonly string[];
67
+ /**
68
+ * 라우팅·신뢰 헤더 — 프록시·게이트웨이가 경로·메서드·클라이언트 IP·내부 티어를 바꾸는 근거로 읽는다.
69
+ * 프레임 값은 통과시키지 않는다(정확 일치 + 접두사).
70
+ */
71
+ declare const ROUTING_HEADERS: readonly string[];
72
+ declare const ROUTING_HEADER_PREFIXES: readonly string[];
73
+ /** 토큰이 실리는 요청에 프레임이 보낼 수 있는 헤더 개수 상한. */
74
+ declare const MAX_PASS_THROUGH_HEADERS = 32;
62
75
  declare const ALLOWED_METHODS: readonly string[];
63
76
  /** partnerOrigins 최대 개수. */
64
77
  declare const MAX_PARTNER_ORIGINS = 10;
@@ -78,7 +91,7 @@ interface DestinationContext {
78
91
  readonly hostOrigin: string;
79
92
  readonly partnerOrigins: readonly string[];
80
93
  readonly policy: BridgePolicy;
81
- /** 게이트웨이 요청에 호스트가 덮어 싣는 헤더(`normalizePinnedHeaders` 결과). 파트너·외부 요청에는 싣지 않는다. */
94
+ /** 토큰이 실리는 요청(gateway·partner)에 호스트가 덮어 싣는 헤더(`normalizePinnedHeaders` 결과). 외부 요청에는 싣지 않는다. */
82
95
  readonly pinnedHeaders?: Readonly<Record<string, string>>;
83
96
  }
84
97
  /**
@@ -106,8 +119,8 @@ declare function classifyDestination(rawUrl: unknown, ctx: DestinationContext):
106
119
  /** `classifyDestination`의 URL만. */
107
120
  declare function resolveDestination(rawUrl: unknown, ctx: DestinationContext): string;
108
121
  /**
109
- * 호스트가 고정하는 헤더를 검증·소문자화한다. 허용 헤더·테넌시 헤더만 받는다(그 밖은 TypeError —
110
- * 이 경로로 authorization 같은 값을 실수로 넣지 못하게).
122
+ * 호스트가 고정하는 헤더를 검증·소문자화한다. 올바른 헤더 이름이면 받고, 자격증명 헤더
123
+ * ({@link CREDENTIAL_HEADERS})는 TypeError — 이 경로로 authorization 같은 값을 실수로 넣지 못하게.
111
124
  */
112
125
  declare function normalizePinnedHeaders(pinned: unknown): Readonly<Record<string, string>>;
113
126
  interface PreparedFetch {
@@ -206,9 +219,10 @@ interface CreateBridgeHostOptions {
206
219
  */
207
220
  readonly externalFetchImpl?: HostFetch;
208
221
  /**
209
- * 게이트웨이 요청에 호스트가 덮어 싣는 헤더. 테넌시 헤더(`x-bstage-tenant-id`·`x-bstage-org-id`·
210
- * `x-bstage-enterprise-id`)는 프레임 값이 버려지고 **여기 준 값만** 실린다. 앱 헤더
211
- * (`x-bstage-app-id`·`x-bstage-app-key`)는 여기 주면 프레임 값을 덮는다. 그 밖의 키는 TypeError.
222
+ * 토큰이 실리는 요청(gateway·partner)에 호스트가 덮어 싣는 헤더. 그 요청에는 템플릿이 붙인 헤더가 그대로
223
+ * 실리고(자격증명·테넌시 헤더 제외) 그 위에 이 값이 덮인다. 테넌시 헤더(`x-bstage-tenant-id`·
224
+ * `x-bstage-org-id`·`x-bstage-enterprise-id`)는 프레임 값이 버려지고 **여기 준 값만** 실린다. 그 밖의 키는
225
+ * 프레임 값을 덮는다. 자격증명 헤더(`authorization`·`cookie`·CF Access)나 올바르지 않은 이름은 TypeError.
212
226
  */
213
227
  readonly pinnedHeaders?: Readonly<Record<string, string>>;
214
228
  readonly handlers?: BridgeHostHandlers;
@@ -285,4 +299,4 @@ interface PathCheck {
285
299
  */
286
300
  declare function checkPath(pathname: string, options?: PathCheckOptions): PathCheck;
287
301
 
288
- export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeDisposeReason, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, TemplateReport, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };
302
+ export { ALLOWED_METHODS, ALLOWED_REQUEST_HEADERS, type BridgeDisposeReason, type BridgeHost, type BridgeHostHandlers, type BridgeInitInput, type BridgePolicy, BridgeSurface, CREDENTIAL_HEADERS, type CreateBridgeHostOptions, DEFAULT_GATEWAY_DENY_SEGMENTS, DEFAULT_POLICY, type Destination, type DestinationContext, type DestinationKind, type FrameWindow, HOST_ONLY_HEADERS, type HostFetch, type HostWindow, type IframeLike, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, MAX_PASS_THROUGH_HEADERS, type MessageEventLike, type PathCheck, type PathCheckOptions, type PreparedFetch, ROUTING_HEADERS, ROUTING_HEADER_PREFIXES, TemplateReport, checkPath, classifyDestination, createBridgeHost, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy };
package/dist/host.js CHANGED
@@ -3,6 +3,7 @@ import {
3
3
  ALLOWED_REQUEST_HEADERS,
4
4
  BRIDGE_SURFACES,
5
5
  BridgeError,
6
+ CREDENTIAL_HEADERS,
6
7
  DEFAULT_GATEWAY_DENY_SEGMENTS,
7
8
  DEFAULT_POLICY,
8
9
  FRAME_UNLOAD_EVENT,
@@ -11,12 +12,15 @@ import {
11
12
  INIT_RESPONSE,
12
13
  MAX_DECODE_PASSES,
13
14
  MAX_PARTNER_ORIGINS,
15
+ MAX_PASS_THROUGH_HEADERS,
14
16
  READY_EVENT,
15
17
  REPORTS_PER_SESSION,
16
18
  REPORT_COUNT_MAX,
17
19
  REPORT_FRAME_MAX_LENGTH,
18
20
  REPORT_MAX_FRAMES,
19
21
  REPORT_MESSAGE_MAX_LENGTH,
22
+ ROUTING_HEADERS,
23
+ ROUTING_HEADER_PREFIXES,
20
24
  TEMPLATE_REPORT_KINDS,
21
25
  checkPath,
22
26
  classifyDestination,
@@ -38,7 +42,7 @@ import {
38
42
  prepareFetch,
39
43
  resolveDestination,
40
44
  resolvePolicy
41
- } from "./chunk-NXB47KPE.js";
45
+ } from "./chunk-5OWBSJ6E.js";
42
46
  import "./chunk-TPKNGW34.js";
43
47
 
44
48
  // src/host/rateLimiter.ts
@@ -660,13 +664,17 @@ export {
660
664
  ALLOWED_METHODS,
661
665
  ALLOWED_REQUEST_HEADERS,
662
666
  BRIDGE_SURFACES,
667
+ CREDENTIAL_HEADERS,
663
668
  DEFAULT_GATEWAY_DENY_SEGMENTS,
664
669
  DEFAULT_POLICY,
665
670
  HOST_ONLY_HEADERS,
666
671
  IFRAME_ATTRIBUTES,
667
672
  MAX_DECODE_PASSES,
668
673
  MAX_PARTNER_ORIGINS,
674
+ MAX_PASS_THROUGH_HEADERS,
669
675
  REPORTS_PER_SESSION,
676
+ ROUTING_HEADERS,
677
+ ROUTING_HEADER_PREFIXES,
670
678
  checkPath,
671
679
  classifyDestination,
672
680
  createBridgeHost,
package/dist/index.cjs CHANGED
@@ -791,7 +791,48 @@ var ALLOWED_REQUEST_HEADERS = Object.freeze([
791
791
  var HOST_ONLY_HEADERS = Object.freeze([
792
792
  "x-bstage-tenant-id",
793
793
  "x-bstage-org-id",
794
- "x-bstage-enterprise-id"
794
+ "x-bstage-enterprise-id",
795
+ // 스페이스 지정 헤더 — 프레임이 다른 스페이스로 회원 자격 요청을 돌리지 못하게 호스트 값만 싣는다.
796
+ "x-bmf-space-id",
797
+ "x-bmf-sid"
798
+ ]);
799
+ var CREDENTIAL_HEADERS = Object.freeze([
800
+ "authorization",
801
+ "proxy-authorization",
802
+ "authentication",
803
+ "cookie",
804
+ "cf-access-client-id",
805
+ "cf-access-client-secret",
806
+ "cf-access-token",
807
+ "x-api-key",
808
+ "api-key",
809
+ "x-auth-token",
810
+ "x-access-token",
811
+ "x-amz-security-token",
812
+ "x-csrf-token",
813
+ "x-xsrf-token"
814
+ ]);
815
+ var ROUTING_HEADERS = Object.freeze([
816
+ "host",
817
+ "forwarded",
818
+ "x-real-ip",
819
+ "x-client-ip",
820
+ "true-client-ip",
821
+ "x-original-url",
822
+ "x-rewrite-url",
823
+ "x-original-method",
824
+ "x-http-method-override",
825
+ "x-http-method",
826
+ "x-method-override",
827
+ "x-bmf-tier"
828
+ ]);
829
+ var ROUTING_HEADER_PREFIXES = Object.freeze([
830
+ "x-forwarded-",
831
+ "x-envoy-",
832
+ "x-amz-",
833
+ "proxy-",
834
+ "sec-",
835
+ "cf-"
795
836
  ]);
796
837
  var ALLOWED_METHODS = Object.freeze([
797
838
  "GET",
package/dist/index.js CHANGED
@@ -36,7 +36,7 @@ import {
36
36
  isRequestType,
37
37
  isValidNonce,
38
38
  isValidSession
39
- } from "./chunk-NXB47KPE.js";
39
+ } from "./chunk-5OWBSJ6E.js";
40
40
  import "./chunk-TPKNGW34.js";
41
41
  export {
42
42
  BRIDGE_ERROR_CODES,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bstage-sdk/bridge",
3
- "version": "0.12.0",
3
+ "version": "0.14.0",
4
4
  "description": "bstage SDK bridge — isolated template iframe protocol, host policy and frame client",
5
5
  "type": "module",
6
6
  "publishConfig": {