@bstage-sdk/bridge 0.16.0 → 0.17.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
@@ -38,7 +38,7 @@ const host = createBridgeHost({
38
38
  session,
39
39
  hostOrigin: location.origin,
40
40
  init: {
41
- placementId, // 호스트가 만든 스코프 키 — 예: `page:{경로}|{url}`, `slot:{id}|{url}`
41
+ placementId, // 호스트가 만든 스코프 키 — 예: 페이지 `page:{경로}`, 위젯 `slot:{id}|{url}`
42
42
  surface: 'page', // 'page' | 'slot'
43
43
  phase,
44
44
  spaceId,
@@ -47,6 +47,7 @@ const host = createBridgeHost({
47
47
  member: { signedIn },
48
48
  partnerOrigins, // 팬 토큰을 보낼 vibe 백엔드 목록(토큰 없이 부를 외부 API는 넣지 않는다)
49
49
  translations, // 선택: 현재 locale 번역 사전
50
+ page: { path: location.pathname, search: location.search }, // 선택: 아래 "페이지 위치"
50
51
  },
51
52
  fetchImpl: platformFetch, // 같은 origin /gw — 인증·목적지 허용 목록을 적용하는 플랫폼 fetch
52
53
  partnerFetchImpl, // 선택: partnerOrigins용(토큰을 붙일지는 호스트가 결정)
@@ -56,7 +57,8 @@ const host = createBridgeHost({
56
57
  gatewayDenySegments: DEFAULT_GATEWAY_DENY_SEGMENTS, // 정책을 코드에 드러낸다(필요하면 [...상수, '추가'])
57
58
  allowExternal: true, // 외부 https 갈래는 옵트인(기본 false). 미리보기처럼 막을 호스트는 생략
58
59
  },
59
- handlers: { navigate, back, toast, resize, track },
60
+ handlers: { navigate, back, toast, resize, track, navigateExternal },
61
+ storageBackend, // 선택: storage 요청을 리로드 뒤에도 남기려면 주입(아래 "storage")
60
62
  })
61
63
 
62
64
  iframe.srcdoc = createSrcdoc({
@@ -216,21 +218,55 @@ external에 인증을 붙이는 fetch를 주입하지 않습니다. 외부 갈
216
218
  | `navigate` | `{ path, replace?, reload? }` | `/`로 시작, `//`·`/\`·공백·제어문자 거절. 옵션은 boolean만 |
217
219
  | `back` | `{}` | |
218
220
  | `openExternal` | `{ url }` | https만. 처리기가 없으면 `noopener,noreferrer`로 새 창 |
221
+ | `navigateExternal` | `{ url }` | 같은 탭 외부 이동. https만(userinfo 거절). 처리기 `navigateExternal`이 확인 창을 띄운다. 처리기가 없으면 `UNSUPPORTED`(새 창으로 대신하지 않음). 프레임당 분당 3회(넘으면 `RATE_LIMITED`) |
219
222
  | `toast` | `{ message, kind? }` | 500자에서 자름 |
220
223
  | `resize` | `{ height }` | 0~200000px, rAF 디바운스 |
221
224
  | `track` | `{ name, params? }` | 이름 100자, params 직렬화 4KB |
222
- | `storage` | `{ op, key, value? }` | 페이지·위젯(placement) 단위 메모리(키 50개, 값 4KB) |
225
+ | `storage` | `{ op, key, value? }` | 페이지·위젯(placement) 단위(키 50개, 값 4KB). 기본은 메모리, 호스트가 `storageBackend`를 주입하면 영속. 아래 "storage" |
223
226
  | `log` | `{ level, message }` | real phase에서는 버림 |
224
227
  | `report` | `{ kind, message, frames, count }` | 템플릿 에러 보고. 아래 "에러 보고" |
225
228
  | `session` | `{ op, body }` | 계정 세션 작업. 아래 "계정 세션" |
226
229
  | `otp` | `{ op, body }` | SMS OTP 중계. 아래 "계정 세션" |
227
230
 
228
- 이벤트(호스트 → 프레임, `host.send`): `slot.context`·`locale`(`{ locale, translations? }`)·`member`·`theme`·`visibility`.
231
+ 이벤트(호스트 → 프레임, `host.send`): `slot.context`·`locale`(`{ locale, translations? }`)·`member`·`theme`·`visibility`·`page`(`{ path, search }`).
229
232
 
230
- 오류 코드: `FORBIDDEN_DESTINATION`·`FORBIDDEN_METHOD`·`BODY_TOO_LARGE`·`RATE_LIMITED`·`BAD_REQUEST`·`TIMEOUT`·`NETWORK_ERROR`·`UNSUPPORTED`·`NOT_ALLOWED`.
233
+ 오류 코드: `FORBIDDEN_DESTINATION`·`FORBIDDEN_METHOD`·`BODY_TOO_LARGE`·`RATE_LIMITED`·`BAD_REQUEST`·`TIMEOUT`·`NETWORK_ERROR`·`UNSUPPORTED`·`NOT_ALLOWED`·`STORAGE_UNAVAILABLE`.
231
234
  프레임 요청은 15초 안에 응답이 없으면 `TIMEOUT`. 핸드셰이크(`ready`)는 init을 받을 때까지 재전송합니다(처음 10초는 250ms, 이후 2초 간격).
232
235
  프레임 → 호스트 봉투에는 최상위 `frame`(프레임 토큰)이 붙고, 문서가 내려갈 때 `evt:frame-unload`(`FRAME_UNLOAD_EVENT`)가 갑니다(위 "세션 수명").
233
236
 
237
+ ### 페이지 위치 (`init.page`·`page` 이벤트)
238
+
239
+ 호스트 페이지의 경로·쿼리를 프레임에 알립니다(프레임은 opaque origin이라 호스트 `location`을 읽을 수 없습니다).
240
+ `path`는 `/`로 시작, `search`는 빈 문자열이거나 `?`로 시작, 각각 2048자 이하입니다. 해시는 싣지 않습니다.
241
+ 형식이 틀리면 init에서는 필드를 빼고, `host.send('page', …)`는 던지지 않고 그 이벤트를 버립니다. 이벤트는 프레임 init
242
+ 스냅샷에도 반영됩니다. 템플릿은 core `getPageLocation()`·`onPageLocationChange()`로 읽습니다.
243
+
244
+ **어느 배치에 실을지는 SDK가 정하지 않습니다 — 호스트가 정합니다.** 계정 세션 배치(`account-session`)와 플랫폼 인증
245
+ 콜백 경로(OAuth `code`·`state`가 쿼리에 있는 페이지)에는 `page`를 싣지도 보내지도 마세요. 쿼리는 그대로 템플릿 코드에
246
+ 넘어가므로 토큰·일회용 코드가 든 URL을 넘기지 않는 것은 호스트 책임입니다.
247
+
248
+ ### storage
249
+
250
+ `storage` 요청은 `${spaceId}\u0000${placementId}` 스코프로 나뉩니다(placement당 키 50개, 값 4096자, 키 200자).
251
+
252
+ - **기본(`storageBackend` 생략)**: 브리지 모듈 메모리. 같은 페이지 세션에서 같은 placement가 다시 마운트되면 이어 쓰고,
253
+ 호스트 페이지를 새로 열면 사라집니다.
254
+ - **주입(`storageBackend`)**: `StorageBackend`(`get`·`set`·`remove`·`keys(prefix)`, 동기)에
255
+ `${spaceId}\u0000${placementId}\u0000${key}` 전체 키로 씁니다. `keys(prefix)`는 그 접두사로 시작하는 **전체 키**를
256
+ 돌려줘야 합니다(키 상한을 여기로 셉니다). `set`(또는 상한 확인용 `keys`)이 던지면 `STORAGE_UNAVAILABLE`, `get`이
257
+ 던지면 `null`, `remove`의 예외는 무시합니다. 이 경로에서는 `\u0000`이 든 키를 거절합니다. 호스트 localStorage를 감싸면
258
+ 리로드 뒤에도 남습니다.
259
+ - 어느 쪽이든 템플릿이 마음대로 읽고 쓰는 값입니다. **토큰·시크릿·개인정보를 저장하는 곳과 섞지 말고**, 템플릿에도
260
+ 그런 값을 담지 않도록 안내합니다.
261
+
262
+ ### 같은 탭 외부 이동 (`navigateExternal`)
263
+
264
+ 프레임 안에서 `window.open`은 sandbox(`allow-popups` 없음) 때문에 아무 일도 하지 않고, `location.assign`으로 직접 나가면
265
+ 프레임 자기 내비게이션이 되어 세션이 끊기고(위 "세션 수명") 콘솔 격리 검사에도 걸립니다. 그래서 같은 탭 외부 이동은
266
+ 호스트에 요청합니다. 호스트는 `validateExternalUrl`(https만, userinfo 거절)로 검증한 href를 `handlers.navigateExternal`로
267
+ 넘기고, 처리기는 확인 창을 띄워 사용자가 동의할 때만 이동합니다. 처리기가 없으면 `UNSUPPORTED`입니다 — `openExternal`과
268
+ 달리 기본 동작(새 창)으로 대신하지 않습니다.
269
+
234
270
  ### 계정 세션 (`session`·`otp`)
235
271
 
236
272
  가입·소셜 가입·재인증 화면처럼 **로그인 쿠키를 설정해야 하는 템플릿**을 격리 프레임에서 돌리기 위한 요청입니다.
@@ -360,7 +396,7 @@ connect-src https: wss:; frame-src 'none'; form-action 'none'; base-uri 'none'
360
396
  ② CORS에 `null` origin을 허용하지 않으며 ③ 쿠키로 인증하는 상태 변경 엔드포인트에 CSRF 방어를 유지합니다.
361
397
  - 토큰을 응답 본문으로 돌려주는 경로(토큰 갱신 등)는 브리지의 게이트웨이 거절 규칙으로 계속 막힙니다 — 직접 호출로는 토큰이 없으니 닿아도 얻을 것이 없습니다.
362
398
 
363
- 프레임 안 제약: 쿠키·`localStorage`·호스트 DOM에 접근할 수 없습니다(opaque origin). 번역 사전은 CDN이 아니라
399
+ 프레임 안 제약: 쿠키·`localStorage`·호스트 DOM에 접근할 수 없습니다(opaque origin — 영속 저장은 위 "storage"). 번역 사전은 CDN이 아니라
364
400
  호스트가 init·`locale` 이벤트의 `translations`로 넘깁니다. 브리지 모드의 `fetchTranslations`는 **현재 locale 사전만**
365
401
  돌려주고, 다른 locale(폴백 체인의 `en`·`ko` 등)은 빈 사전 `{}`입니다. 같은 locale에 사전만 새로 와도 `useBstageTranslations`가 다시 읽습니다.
366
402
 
@@ -419,6 +419,8 @@ function bridgeRuntime(g, makeFetch, config) {
419
419
  init = Object.assign({}, init, { theme: payload });
420
420
  } else if (type === "slot.context" && typeof p.id === "string") {
421
421
  init = Object.assign({}, init, { slot: payload });
422
+ } else if (type === "page" && typeof p.path === "string" && typeof p.search === "string") {
423
+ init = Object.assign({}, init, { page: { path: p.path, search: p.search } });
422
424
  }
423
425
  }
424
426
  function onMessage(ev) {
@@ -3,7 +3,7 @@ import {
3
3
  createBridgeFetch,
4
4
  installDirectFetch,
5
5
  installErrorReport
6
- } from "./chunk-TPKNGW34.js";
6
+ } from "./chunk-B3TKEEX3.js";
7
7
 
8
8
  // src/protocol/envelope.ts
9
9
  var BRIDGE_VERSION = 1;
@@ -37,7 +37,9 @@ var BRIDGE_ERROR_CODES = [
37
37
  "NETWORK_ERROR",
38
38
  "UNSUPPORTED",
39
39
  // 권한(capability) 없는 배치의 계정 요청, 또는 결속 조건을 벗어난 세션 요청.
40
- "NOT_ALLOWED"
40
+ "NOT_ALLOWED",
41
+ // 호스트가 주입한 storage 저장소에 쓸 수 없음(용량 초과·접근 차단 등).
42
+ "STORAGE_UNAVAILABLE"
41
43
  ];
42
44
  var BridgeError = class extends Error {
43
45
  constructor(code, message) {
@@ -60,6 +62,7 @@ var REQUEST_TYPES = [
60
62
  "navigate",
61
63
  "back",
62
64
  "openExternal",
65
+ "navigateExternal",
63
66
  "toast",
64
67
  "resize",
65
68
  "track",
@@ -69,10 +72,37 @@ var REQUEST_TYPES = [
69
72
  "session",
70
73
  "otp"
71
74
  ];
72
- var HOST_EVENT_TYPES = ["slot.context", "locale", "member", "theme", "visibility"];
75
+ var HOST_EVENT_TYPES = [
76
+ "slot.context",
77
+ "locale",
78
+ "member",
79
+ "theme",
80
+ "visibility",
81
+ "page"
82
+ ];
73
83
  var READY_EVENT = "ready";
74
84
  var INIT_RESPONSE = "init";
75
85
  var FRAME_UNLOAD_EVENT = "frame-unload";
86
+ var PAGE_LOCATION_MAX_LENGTH = 2048;
87
+ var UNSAFE_PATH_CHARS = /[\s\\\u0000-\u001f\u007f]/;
88
+ function isSafePagePath(path) {
89
+ if (!path.startsWith("/") || path.startsWith("//")) return false;
90
+ if (UNSAFE_PATH_CHARS.test(path) || path.includes("?") || path.includes("#")) return false;
91
+ try {
92
+ const resolved = new URL(path, "https://page.invalid");
93
+ return resolved.origin === "https://page.invalid" && !resolved.pathname.startsWith("//");
94
+ } catch {
95
+ return false;
96
+ }
97
+ }
98
+ function toPageLocation(value) {
99
+ if (typeof value !== "object" || value === null) return void 0;
100
+ const { path, search } = value;
101
+ if (typeof path !== "string" || typeof search !== "string" || path.length > PAGE_LOCATION_MAX_LENGTH || !isSafePagePath(path) || search !== "" && !search.startsWith("?") || search.length > PAGE_LOCATION_MAX_LENGTH) {
102
+ return void 0;
103
+ }
104
+ return { path, search };
105
+ }
76
106
  var BRIDGE_SURFACES = ["page", "slot"];
77
107
  function isBridgeSurface(value) {
78
108
  return BRIDGE_SURFACES.includes(value);
@@ -1210,6 +1240,8 @@ export {
1210
1240
  READY_EVENT,
1211
1241
  INIT_RESPONSE,
1212
1242
  FRAME_UNLOAD_EVENT,
1243
+ PAGE_LOCATION_MAX_LENGTH,
1244
+ toPageLocation,
1213
1245
  BRIDGE_SURFACES,
1214
1246
  isBridgeSurface,
1215
1247
  ACCOUNT_SESSION_CAPABILITY,
package/dist/frame.cjs CHANGED
@@ -222,6 +222,8 @@ function bridgeRuntime(g, makeFetch, config) {
222
222
  init = Object.assign({}, init, { theme: payload });
223
223
  } else if (type === "slot.context" && typeof p.id === "string") {
224
224
  init = Object.assign({}, init, { slot: payload });
225
+ } else if (type === "page" && typeof p.path === "string" && typeof p.search === "string") {
226
+ init = Object.assign({}, init, { page: { path: p.path, search: p.search } });
225
227
  }
226
228
  }
227
229
  function onMessage(ev) {
package/dist/frame.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { i as BridgeInit, l as BridgeRequestType, k as BridgeRequestMap, g as BridgeEventMap, X as TemplateReportKind } from './messages-_p1yCNj9.cjs';
1
+ import { i as BridgeInit, l as BridgeRequestType, k as BridgeRequestMap, g as BridgeEventMap, Z as TemplateReportKind } from './messages-pMXAlatW.cjs';
2
2
 
3
3
  /** 프레임 런타임 설정 — srcdoc 부트스트랩이 상수로 넘긴다. */
4
4
  interface BridgeClientConfig {
@@ -16,7 +16,7 @@ interface BridgeClient {
16
16
  readonly hostOrigin: string;
17
17
  /** init 수신 시 resolve. reject하지 않는다(호스트가 늦게 붙으면 ready를 계속 재전송한다). */
18
18
  readonly ready: Promise<BridgeInit>;
19
- /** 지금까지 받은 init(이후 locale·member·theme·slot.context 이벤트가 반영된 값). 수신 전이면 undefined. */
19
+ /** 지금까지 받은 init(이후 locale·member·theme·slot.context·page 이벤트가 반영된 값). 수신 전이면 undefined. */
20
20
  getInit(): BridgeInit | undefined;
21
21
  request<T extends BridgeRequestType>(type: T, payload: BridgeRequestMap[T]['req']): Promise<BridgeRequestMap[T]['res']>;
22
22
  on<E extends keyof BridgeEventMap>(type: E, fn: (payload: BridgeEventMap[E]) => void): Unsubscribe;
package/dist/frame.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { i as BridgeInit, l as BridgeRequestType, k as BridgeRequestMap, g as BridgeEventMap, X as TemplateReportKind } from './messages-_p1yCNj9.js';
1
+ import { i as BridgeInit, l as BridgeRequestType, k as BridgeRequestMap, g as BridgeEventMap, Z as TemplateReportKind } from './messages-pMXAlatW.js';
2
2
 
3
3
  /** 프레임 런타임 설정 — srcdoc 부트스트랩이 상수로 넘긴다. */
4
4
  interface BridgeClientConfig {
@@ -16,7 +16,7 @@ interface BridgeClient {
16
16
  readonly hostOrigin: string;
17
17
  /** init 수신 시 resolve. reject하지 않는다(호스트가 늦게 붙으면 ready를 계속 재전송한다). */
18
18
  readonly ready: Promise<BridgeInit>;
19
- /** 지금까지 받은 init(이후 locale·member·theme·slot.context 이벤트가 반영된 값). 수신 전이면 undefined. */
19
+ /** 지금까지 받은 init(이후 locale·member·theme·slot.context·page 이벤트가 반영된 값). 수신 전이면 undefined. */
20
20
  getInit(): BridgeInit | undefined;
21
21
  request<T extends BridgeRequestType>(type: T, payload: BridgeRequestMap[T]['req']): Promise<BridgeRequestMap[T]['res']>;
22
22
  on<E extends keyof BridgeEventMap>(type: E, fn: (payload: BridgeEventMap[E]) => void): Unsubscribe;
package/dist/frame.js CHANGED
@@ -3,7 +3,7 @@ import {
3
3
  createBridgeFetch,
4
4
  installDirectFetch,
5
5
  installErrorReport
6
- } from "./chunk-TPKNGW34.js";
6
+ } from "./chunk-B3TKEEX3.js";
7
7
 
8
8
  // src/frame/createBridgeClient.ts
9
9
  var BRIDGE_CONFIG_GLOBAL = "__bstage_bridge_config__";
package/dist/host.cjs CHANGED
@@ -40,6 +40,9 @@ __export(host_exports, {
40
40
  ROUTING_HEADER_PREFIXES: () => ROUTING_HEADER_PREFIXES,
41
41
  SESSION_PER_FRAME: () => SESSION_PER_FRAME,
42
42
  SESSION_PER_MINUTE: () => SESSION_PER_MINUTE,
43
+ STORAGE_MAX_KEYS: () => STORAGE_MAX_KEYS,
44
+ STORAGE_MAX_KEY_LENGTH: () => STORAGE_MAX_KEY_LENGTH,
45
+ STORAGE_MAX_VALUE_LENGTH: () => STORAGE_MAX_VALUE_LENGTH,
43
46
  checkPath: () => checkPath,
44
47
  classifyDestination: () => classifyDestination,
45
48
  createBridgeHost: () => createBridgeHost,
@@ -91,7 +94,9 @@ var BRIDGE_ERROR_CODES = [
91
94
  "NETWORK_ERROR",
92
95
  "UNSUPPORTED",
93
96
  // 권한(capability) 없는 배치의 계정 요청, 또는 결속 조건을 벗어난 세션 요청.
94
- "NOT_ALLOWED"
97
+ "NOT_ALLOWED",
98
+ // 호스트가 주입한 storage 저장소에 쓸 수 없음(용량 초과·접근 차단 등).
99
+ "STORAGE_UNAVAILABLE"
95
100
  ];
96
101
  var BridgeError = class extends Error {
97
102
  constructor(code, message) {
@@ -113,6 +118,7 @@ var REQUEST_TYPES = [
113
118
  "navigate",
114
119
  "back",
115
120
  "openExternal",
121
+ "navigateExternal",
116
122
  "toast",
117
123
  "resize",
118
124
  "track",
@@ -122,10 +128,37 @@ var REQUEST_TYPES = [
122
128
  "session",
123
129
  "otp"
124
130
  ];
125
- var HOST_EVENT_TYPES = ["slot.context", "locale", "member", "theme", "visibility"];
131
+ var HOST_EVENT_TYPES = [
132
+ "slot.context",
133
+ "locale",
134
+ "member",
135
+ "theme",
136
+ "visibility",
137
+ "page"
138
+ ];
126
139
  var READY_EVENT = "ready";
127
140
  var INIT_RESPONSE = "init";
128
141
  var FRAME_UNLOAD_EVENT = "frame-unload";
142
+ var PAGE_LOCATION_MAX_LENGTH = 2048;
143
+ var UNSAFE_PATH_CHARS = /[\s\\\u0000-\u001f\u007f]/;
144
+ function isSafePagePath(path) {
145
+ if (!path.startsWith("/") || path.startsWith("//")) return false;
146
+ if (UNSAFE_PATH_CHARS.test(path) || path.includes("?") || path.includes("#")) return false;
147
+ try {
148
+ const resolved = new URL(path, "https://page.invalid");
149
+ return resolved.origin === "https://page.invalid" && !resolved.pathname.startsWith("//");
150
+ } catch {
151
+ return false;
152
+ }
153
+ }
154
+ function toPageLocation(value) {
155
+ if (typeof value !== "object" || value === null) return void 0;
156
+ const { path, search } = value;
157
+ if (typeof path !== "string" || typeof search !== "string" || path.length > PAGE_LOCATION_MAX_LENGTH || !isSafePagePath(path) || search !== "" && !search.startsWith("?") || search.length > PAGE_LOCATION_MAX_LENGTH) {
158
+ return void 0;
159
+ }
160
+ return { path, search };
161
+ }
129
162
  var BRIDGE_SURFACES = ["page", "slot"];
130
163
  function isBridgeSurface(value) {
131
164
  return BRIDGE_SURFACES.includes(value);
@@ -534,7 +567,7 @@ function createRateLimiter(max, windowMs = DEFAULT_WINDOW_MS) {
534
567
  }
535
568
 
536
569
  // src/host/validators.ts
537
- var MAX_PATH_LENGTH = 2048;
570
+ var MAX_PATH_LENGTH = PAGE_LOCATION_MAX_LENGTH;
538
571
  var TOAST_MAX_LENGTH = 500;
539
572
  var TRACK_NAME_MAX_LENGTH = 100;
540
573
  var TRACK_PARAMS_MAX_BYTES = 4096;
@@ -1041,6 +1074,10 @@ function sanitizeTranslations(value) {
1041
1074
  )
1042
1075
  );
1043
1076
  }
1077
+ function sanitizePage(value) {
1078
+ const page = toPageLocation(value);
1079
+ return page ? Object.freeze(page) : void 0;
1080
+ }
1044
1081
  function sanitizeEvent(type, payload) {
1045
1082
  const p = obj2(payload);
1046
1083
  switch (type) {
@@ -1062,6 +1099,8 @@ function sanitizeEvent(type, payload) {
1062
1099
  const translations = sanitizeTranslations(p.translations);
1063
1100
  return { locale: p.locale, ...translations ? { translations } : {} };
1064
1101
  }
1102
+ case "page":
1103
+ return sanitizePage(p);
1065
1104
  default:
1066
1105
  throw new TypeError(`[bstage-bridge] \uC54C \uC218 \uC5C6\uB294 \uC774\uBCA4\uD2B8: ${String(type)}`);
1067
1106
  }
@@ -1069,6 +1108,7 @@ function sanitizeEvent(type, payload) {
1069
1108
  function buildInit(init, hostOrigin, partnerOrigins, policy) {
1070
1109
  const slot = init.slot ? sanitizeSlot(init.slot) : void 0;
1071
1110
  const translations = sanitizeTranslations(init.translations);
1111
+ const page = hasAccountCapability(init) ? void 0 : sanitizePage(init.page);
1072
1112
  return Object.freeze({
1073
1113
  placementId: String(init.placementId),
1074
1114
  surface: init.surface,
@@ -1087,6 +1127,7 @@ function buildInit(init, hostOrigin, partnerOrigins, policy) {
1087
1127
  },
1088
1128
  partnerOrigins,
1089
1129
  ...translations ? { translations } : {},
1130
+ ...page ? { page } : {},
1090
1131
  ...buildAccountInit(init)
1091
1132
  });
1092
1133
  }
@@ -1107,6 +1148,8 @@ function applyEvent(init, type, payload) {
1107
1148
  return Object.freeze({ ...init, theme: payload });
1108
1149
  case "slot.context":
1109
1150
  return Object.freeze({ ...init, slot: payload });
1151
+ case "page":
1152
+ return Object.freeze({ ...init, page: payload });
1110
1153
  default:
1111
1154
  return init;
1112
1155
  }
@@ -1117,11 +1160,61 @@ var STORAGE_MAX_KEYS = 50;
1117
1160
  var STORAGE_MAX_VALUE_LENGTH = 4096;
1118
1161
  var STORAGE_MAX_KEY_LENGTH = 200;
1119
1162
  var stores = /* @__PURE__ */ new Map();
1120
- function handleStorage(scope, req) {
1121
- const { op, key, value } = req;
1163
+ function assertKey(key) {
1122
1164
  if (typeof key !== "string" || key.length === 0 || key.length > STORAGE_MAX_KEY_LENGTH) {
1123
1165
  throw new BridgeError("BAD_REQUEST", "invalid storage key");
1124
1166
  }
1167
+ }
1168
+ function assertValue(value) {
1169
+ if (typeof value !== "string" || value.length > STORAGE_MAX_VALUE_LENGTH) {
1170
+ throw new BridgeError("BAD_REQUEST", "invalid storage value");
1171
+ }
1172
+ }
1173
+ var KEY_LIMIT = () => new BridgeError("BAD_REQUEST", "storage key limit reached");
1174
+ var UNAVAILABLE = () => new BridgeError("STORAGE_UNAVAILABLE", "storage unavailable");
1175
+ function handleBackendStorage(backend, scope, req) {
1176
+ const { op, key, value } = req;
1177
+ assertKey(key);
1178
+ if (key.includes("\0")) throw new BridgeError("BAD_REQUEST", "invalid storage key");
1179
+ const prefix = `${scope}\0`;
1180
+ const fullKey = prefix + key;
1181
+ if (op === "get") {
1182
+ try {
1183
+ const stored = backend.get(fullKey);
1184
+ return { value: typeof stored === "string" ? stored : null };
1185
+ } catch {
1186
+ return { value: null };
1187
+ }
1188
+ }
1189
+ if (op === "remove") {
1190
+ try {
1191
+ backend.remove(fullKey);
1192
+ } catch {
1193
+ }
1194
+ return { value: null };
1195
+ }
1196
+ if (op === "set") {
1197
+ assertValue(value);
1198
+ let existing;
1199
+ try {
1200
+ existing = backend.keys(prefix);
1201
+ } catch {
1202
+ throw UNAVAILABLE();
1203
+ }
1204
+ if (!existing.includes(fullKey) && existing.length >= STORAGE_MAX_KEYS) throw KEY_LIMIT();
1205
+ try {
1206
+ backend.set(fullKey, value);
1207
+ } catch {
1208
+ throw UNAVAILABLE();
1209
+ }
1210
+ return { value };
1211
+ }
1212
+ throw new BridgeError("BAD_REQUEST", "invalid storage op");
1213
+ }
1214
+ function handleStorage(scope, req, backend) {
1215
+ if (backend) return handleBackendStorage(backend, scope, req);
1216
+ const { op, key, value } = req;
1217
+ assertKey(key);
1125
1218
  const current = stores.get(scope) ?? {};
1126
1219
  const has = Object.prototype.hasOwnProperty.call(current, key);
1127
1220
  if (op === "get") return { value: has ? current[key] : null };
@@ -1133,12 +1226,8 @@ function handleStorage(scope, req) {
1133
1226
  return { value: null };
1134
1227
  }
1135
1228
  if (op === "set") {
1136
- if (typeof value !== "string" || value.length > STORAGE_MAX_VALUE_LENGTH) {
1137
- throw new BridgeError("BAD_REQUEST", "invalid storage value");
1138
- }
1139
- if (!has && Object.keys(current).length >= STORAGE_MAX_KEYS) {
1140
- throw new BridgeError("BAD_REQUEST", "storage key limit reached");
1141
- }
1229
+ assertValue(value);
1230
+ if (!has && Object.keys(current).length >= STORAGE_MAX_KEYS) throw KEY_LIMIT();
1142
1231
  stores = new Map([...stores, [scope, { ...current, [key]: value }]]);
1143
1232
  return { value };
1144
1233
  }
@@ -1151,6 +1240,7 @@ var UNLIMITED_REQUESTS = ["resize"];
1151
1240
  var EMPTY = Object.freeze({});
1152
1241
  var MAX_IN_FLIGHT_FETCHES = 16;
1153
1242
  var TOAST_PER_MINUTE = 5;
1243
+ var NAVIGATE_EXTERNAL_PER_MINUTE = 3;
1154
1244
  var READY_PER_SECOND = 2;
1155
1245
  var RESIZE_PER_SECOND = 30;
1156
1246
  var defaultUncredentialedFetch = (url, init) => globalThis.fetch(url, {
@@ -1261,6 +1351,15 @@ async function dispatch(ctx, type, payload) {
1261
1351
  else unsupported();
1262
1352
  return EMPTY;
1263
1353
  }
1354
+ case "navigateExternal": {
1355
+ const url = validateExternalUrl(payload);
1356
+ if (!h.navigateExternal) unsupported();
1357
+ if (!ctx.navigateExternalLimiter.take()) {
1358
+ throw new BridgeError("RATE_LIMITED", "too many external navigations");
1359
+ }
1360
+ h.navigateExternal(url);
1361
+ return EMPTY;
1362
+ }
1264
1363
  case "toast": {
1265
1364
  const { message, kind } = validateToast(payload);
1266
1365
  if (!h.toast) unsupported();
@@ -1278,7 +1377,11 @@ async function dispatch(ctx, type, payload) {
1278
1377
  return EMPTY;
1279
1378
  }
1280
1379
  case "storage":
1281
- return handleStorage(ctx.storageScope, payload ?? {});
1380
+ return handleStorage(
1381
+ ctx.storageScope,
1382
+ payload ?? {},
1383
+ ctx.storageBackend
1384
+ );
1282
1385
  case "log": {
1283
1386
  const { level, message } = validateLog(payload);
1284
1387
  if (ctx.phase === "real") return EMPTY;
@@ -1309,6 +1412,14 @@ function toFailure(err) {
1309
1412
  if (err instanceof BridgeError || isBridgeErrorLike(err)) return failure(err.code, err.message);
1310
1413
  return failure("BAD_REQUEST", "request failed");
1311
1414
  }
1415
+ function storageScopeOf(spaceId, placementId) {
1416
+ return `${encodeURIComponent(spaceId)}\0${encodeURIComponent(placementId)}`;
1417
+ }
1418
+ function isStorageBackend(value) {
1419
+ if (typeof value !== "object" || value === null) return false;
1420
+ const b = value;
1421
+ return ["get", "set", "remove", "keys"].every((name) => typeof b[name] === "function");
1422
+ }
1312
1423
  function assertOptions(options) {
1313
1424
  if (!options || typeof options !== "object") {
1314
1425
  throw new TypeError("[bstage-bridge] createBridgeHost \uC635\uC158\uC774 \uD544\uC694\uD569\uB2C8\uB2E4");
@@ -1352,6 +1463,9 @@ function assertOptions(options) {
1352
1463
  if (options.onTemplateReport !== void 0 && typeof options.onTemplateReport !== "function") {
1353
1464
  throw new TypeError("[bstage-bridge] onTemplateReport\uB294 \uD568\uC218\uC5EC\uC57C \uD569\uB2C8\uB2E4");
1354
1465
  }
1466
+ if (options.storageBackend !== void 0 && !isStorageBackend(options.storageBackend)) {
1467
+ throw new TypeError("[bstage-bridge] storageBackend\uB294 get\xB7set\xB7remove\xB7keys \uD568\uC218\uB97C \uAC00\uC838\uC57C \uD569\uB2C8\uB2E4");
1468
+ }
1355
1469
  if (!options.iframe || !options.init) {
1356
1470
  throw new TypeError("[bstage-bridge] iframe\xB7init\uC774 \uD544\uC694\uD569\uB2C8\uB2E4");
1357
1471
  }
@@ -1396,13 +1510,17 @@ function createBridgeHost(options) {
1396
1510
  handlers,
1397
1511
  win,
1398
1512
  destination: { hostOrigin, partnerOrigins, policy, pinnedHeaders },
1399
- storageScope: `${options.init.spaceId}\0${options.init.placementId}`,
1513
+ // 각 성분을 인코딩해 잇는다 — 인코딩한 값에는 NUL이 없으므로 구분자가 모호해지지 않아, NUL이 든
1514
+ // spaceId·placementId로 다른 배치의 스코프 접두사를 만들 수 없다.
1515
+ storageScope: storageScopeOf(options.init.spaceId, options.init.placementId),
1516
+ ...options.storageBackend ? { storageBackend: options.storageBackend } : {},
1400
1517
  phase: options.init.phase,
1401
1518
  fetchImpl: options.fetchImpl,
1402
1519
  partnerFetchImpl: options.partnerFetchImpl ?? defaultUncredentialedFetch,
1403
1520
  externalFetchImpl: options.externalFetchImpl ?? defaultUncredentialedFetch,
1404
1521
  hostOrigin,
1405
1522
  toastLimiter: createRateLimiter(TOAST_PER_MINUTE),
1523
+ navigateExternalLimiter: createRateLimiter(NAVIGATE_EXTERNAL_PER_MINUTE),
1406
1524
  scheduleResize,
1407
1525
  takeReportSlot() {
1408
1526
  if (reportsTaken >= REPORTS_PER_SESSION) return false;
@@ -1500,7 +1618,9 @@ function createBridgeHost(options) {
1500
1618
  if (typeof payload !== "object" || payload === null) {
1501
1619
  throw new TypeError("[bstage-bridge] \uC774\uBCA4\uD2B8 payload\uB294 \uAC1D\uCCB4\uC5EC\uC57C \uD569\uB2C8\uB2E4");
1502
1620
  }
1621
+ if (type === "page" && hasAccountCapability(options.init)) return;
1503
1622
  const clean = sanitizeEvent(type, payload);
1623
+ if (clean === void 0) return;
1504
1624
  current = applyEvent(current, type, clean);
1505
1625
  if (boundFrame === void 0) {
1506
1626
  if (type === "visibility") pendingVisibility = clean;
@@ -1618,6 +1738,8 @@ function bridgeRuntime(g, makeFetch, config) {
1618
1738
  init = Object.assign({}, init, { theme: payload });
1619
1739
  } else if (type === "slot.context" && typeof p.id === "string") {
1620
1740
  init = Object.assign({}, init, { slot: payload });
1741
+ } else if (type === "page" && typeof p.path === "string" && typeof p.search === "string") {
1742
+ init = Object.assign({}, init, { page: { path: p.path, search: p.search } });
1621
1743
  }
1622
1744
  }
1623
1745
  function onMessage(ev) {
@@ -2833,6 +2955,9 @@ ${script}
2833
2955
  ROUTING_HEADER_PREFIXES,
2834
2956
  SESSION_PER_FRAME,
2835
2957
  SESSION_PER_MINUTE,
2958
+ STORAGE_MAX_KEYS,
2959
+ STORAGE_MAX_KEY_LENGTH,
2960
+ STORAGE_MAX_VALUE_LENGTH,
2836
2961
  checkPath,
2837
2962
  classifyDestination,
2838
2963
  createBridgeHost,
package/dist/host.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { h as BridgeHostEventType, g as BridgeEventMap, N as NavigateOptions, Z as ToastKind, L as LogLevel, n as BridgeSurface, Y as ThemeState, T as SlotState, M as MemberState, o as BridgeTranslations, a as AccountHostQuery, b as AccountSpaceInfo, G as ReverificationStatus, J as SessionOp, s as OtpOp, t as OtpPurpose, W as TemplateReport } from './messages-_p1yCNj9.cjs';
2
- export { A as ACCOUNT_SESSION_CAPABILITY, c as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, w as REPORTS_PER_SESSION, X as TemplateReportKind, a1 as isBridgeSurface } from './messages-_p1yCNj9.cjs';
1
+ import { h as BridgeHostEventType, g as BridgeEventMap, N as NavigateOptions, $ as ToastKind, L as LogLevel, n as BridgeSurface, _ as ThemeState, V as SlotState, M as MemberState, o as BridgeTranslations, w as PageLocationState, a as AccountHostQuery, b as AccountSpaceInfo, J as ReverificationStatus, Q as SessionOp, s as OtpOp, t as OtpPurpose, Y as TemplateReport } from './messages-pMXAlatW.cjs';
2
+ export { A as ACCOUNT_SESSION_CAPABILITY, c as BRIDGE_SURFACES, I as IFRAME_ATTRIBUTES, x as REPORTS_PER_SESSION, Z as TemplateReportKind, a3 as isBridgeSurface } from './messages-pMXAlatW.cjs';
3
3
  export { C as CreateSrcdocOptions, c as createNonce, d as createSession, e as createSrcdoc, f as isValidSession } from './createSrcdoc-DYZk6dDJ.cjs';
4
4
 
5
5
  /**
@@ -30,6 +30,24 @@ interface AccountStateStore {
30
30
  set(value: string): void;
31
31
  }
32
32
 
33
+ /** placement당 키 수 상한. */
34
+ declare const STORAGE_MAX_KEYS = 50;
35
+ /** 값 상한(문자열 길이, 브리지 프로토콜의 4KB). */
36
+ declare const STORAGE_MAX_VALUE_LENGTH = 4096;
37
+ /** 키 길이 상한 — 프로토콜에 정해지지 않은 값(구현 선택). */
38
+ declare const STORAGE_MAX_KEY_LENGTH = 200;
39
+ /**
40
+ * 호스트가 주입하는 storage 저장소(`CreateBridgeHostOptions.storageBackend`). 동기 API다.
41
+ * 키는 브리지가 만든 전체 키(`${scope}\u0000${key}`)이고, `keys(prefix)`는 그 접두사로 시작하는 **전체 키**를
42
+ * 돌려준다. 예외를 던지면 브리지가 처리한다 — set은 `STORAGE_UNAVAILABLE`, get은 없음(null), remove는 무시.
43
+ */
44
+ interface StorageBackend {
45
+ get(key: string): string | null;
46
+ set(key: string, value: string): void;
47
+ remove(key: string): void;
48
+ keys(prefix: string): readonly string[];
49
+ }
50
+
33
51
  /** 호스트 fetch 정책. */
34
52
  interface BridgePolicy {
35
53
  /** 같은 origin에서 허용할 경로 접두사. 기본 `["/gw/"]`(`/gw` 정확 일치 포함). */
@@ -196,7 +214,7 @@ interface IframeLike {
196
214
  * 호스트가 넘기는 init 원본. `hostOrigin`·`gatewayBase`·`limits`는 호스트 옵션·정책에서 채운다.
197
215
  */
198
216
  interface BridgeInitInput {
199
- /** 호스트가 만든 placement 스코프 키(예: `page:{경로}|{url}`, `slot:{id}|{url}`). storage 스코프에도 쓴다. */
217
+ /** 호스트가 만든 placement 스코프 키(예: 페이지 `page:{경로}`, 위젯 `slot:{id}|{url}`). storage 스코프에도 쓴다. */
200
218
  readonly placementId: string;
201
219
  /** 커스텀 페이지(`page`) 또는 슬롯 위젯(`slot`). 그 밖의 값은 생성 시 TypeError. */
202
220
  readonly surface: BridgeSurface;
@@ -208,6 +226,12 @@ interface BridgeInitInput {
208
226
  readonly member: MemberState;
209
227
  readonly partnerOrigins: readonly string[];
210
228
  readonly translations?: BridgeTranslations;
229
+ /**
230
+ * 호스트 페이지의 현재 경로(`/`로 시작)·쿼리(빈 문자열 또는 `?`로 시작), 각 2048자 이하. 형식이 틀리면 init에서 뺀다.
231
+ * 어느 배치에 실을지는 호스트가 정한다 — 계정 세션 배치·플랫폼 인증 콜백 경로(OAuth `code`·`state`가 쿼리에 있다)에는
232
+ * 싣지 말 것. 이후 변화는 `send('page', …)`로 보낸다.
233
+ */
234
+ readonly page?: PageLocationState;
211
235
  /**
212
236
  * 이 배치에 허용된 기능. `account-session`이 있고 page 배치일 때만 계정 세션 요청(session·otp)을 처리한다.
213
237
  * 판정 근거는 호스트가 가진 배치 설정이어야 한다 — manifest·프레임 메시지를 근거로 채우지 말 것.
@@ -257,6 +281,11 @@ interface BridgeHostHandlers {
257
281
  readonly back?: () => void;
258
282
  /** 없으면 `window.open(url, '_blank', 'noopener,noreferrer')`. */
259
283
  readonly openExternal?: (url: string) => void;
284
+ /**
285
+ * 같은 탭 외부 이동(https만, userinfo 없음 — 검증된 href). 확인 창을 띄우고 사용자가 거절하면 이동하지 않는다.
286
+ * 없으면 `UNSUPPORTED`(window.open 등 기본 동작으로 대신하지 않는다).
287
+ */
288
+ readonly navigateExternal?: (url: string) => void;
260
289
  readonly toast?: (message: string, kind?: ToastKind) => void;
261
290
  /** rAF로 디바운스된 높이(px, 0~200000). */
262
291
  readonly resize?: (height: number) => void;
@@ -305,6 +334,13 @@ interface CreateBridgeHostOptions {
305
334
  * sessionStorage(접근 불가면 메모리). 테스트·SSR에서 바꿔 끼운다.
306
335
  */
307
336
  readonly accountStateStore?: AccountStateStore;
337
+ /**
338
+ * `storage` 요청의 저장소. 생략하면 페이지 세션 메모리(리로드하면 사라진다). 주입하면 그 저장소에
339
+ * `${spaceId}\u0000${placementId}\u0000${key}` 키로 쓴다(예: 호스트 localStorage 래퍼 — 리로드 뒤에도 남는다).
340
+ * 상한(placement당 키 50개·값 4096자·키 200자)은 같다. 템플릿이 쓰는 값이므로 토큰·시크릿·개인정보를 담는
341
+ * 저장소와 섞지 말 것.
342
+ */
343
+ readonly storageBackend?: StorageBackend;
308
344
  readonly policy?: Partial<BridgePolicy>;
309
345
  /**
310
346
  * 호스트가 dispose될 때 한 번 불린다. `frame-unload`(프레임 문서가 내려감)·`frame-mismatch`(토큰이 없거나 다른
@@ -378,4 +414,4 @@ interface PathCheck {
378
414
  */
379
415
  declare function checkPath(pathname: string, options?: PathCheckOptions): PathCheck;
380
416
 
381
- 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, LOGIN_BINDING_MS, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, MAX_PASS_THROUGH_HEADERS, type MessageEventLike, NavigateOptions, OTP_SEND_PER_MINUTE, OTP_VERIFY_PER_MINUTE, type OtpImpl, OtpOp, OtpPurpose, type PathCheck, type PathCheckOptions, type PreparedFetch, ROUTING_HEADERS, ROUTING_HEADER_PREFIXES, SESSION_PER_FRAME, SESSION_PER_MINUTE, type SessionImpl, SessionOp, TemplateReport, checkPath, classifyDestination, createBridgeHost, hasAccountCapability, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy, stripTokenKeys };
417
+ 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, LOGIN_BINDING_MS, MAX_DECODE_PASSES, MAX_PARTNER_ORIGINS, MAX_PASS_THROUGH_HEADERS, type MessageEventLike, NavigateOptions, OTP_SEND_PER_MINUTE, OTP_VERIFY_PER_MINUTE, type OtpImpl, OtpOp, OtpPurpose, PageLocationState, type PathCheck, type PathCheckOptions, type PreparedFetch, ROUTING_HEADERS, ROUTING_HEADER_PREFIXES, SESSION_PER_FRAME, SESSION_PER_MINUTE, STORAGE_MAX_KEYS, STORAGE_MAX_KEY_LENGTH, STORAGE_MAX_VALUE_LENGTH, type SessionImpl, SessionOp, type StorageBackend, TemplateReport, checkPath, classifyDestination, createBridgeHost, hasAccountCapability, isAllowedGatewayPath, normalizePartnerOrigins, normalizePinnedHeaders, prepareFetch, resolveDestination, resolvePolicy, stripTokenKeys };