@iyulab/modern-app 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.6.0] - 2026-07-03
+
+### Added
+- **`AppConfig.auth`** — 부팅 인증 게이트. 지정하면 앱 셸(레이아웃·라우터)을 만들기 전에 `me()` 로 세션을 판정하여, 인증 시 셸을 로드하고 미인증 시 `renderLogin` 으로 로그인 UI 를 띄운다. 로그인 성공 시 `onSuccess()` 를 호출하면 앱이 (재)로드되어 셸이 나타난다. `onAuthenticated(user)` 로 셸 구성 직전 훅(권한 set 등)을 제공한다.
+  - 프레임워크는 인증 **오케스트레이션**(판정→분기→재로드)만 소유. 세션 조회/로그인 HTTP·사용자/권한 형태·세션-중 401 은 앱/`@iyulab/enterprise`(`createAuthClient`/`createODataService`)가 소유한다. 소비앱이 `app.load()` 앞단에 손으로 짜던 부팅 게이트를 표준화.
+- **`app.user`** getter — 인증 게이트 사용 시 인증된 현재 사용자(미인증/미사용이면 `undefined`).
+- **사이드바 네이티브 권한 메뉴 필터** — 모든 메뉴 항목(link/section/group/button/html)에 `requirePermission?`/`requireAnyPermission?` 지원(공통 `SidebarPermissionGuard`). `SidebarLayoutConfig.hasPermission` 판정 함수를 주면 만족하지 않는 항목을 숨기고, 항목이 모두 걸러진 section/group 은 통째로 숨긴다. 소비앱이 손으로 짜던 `filterMenu` 를 표준화. 순수 헬퍼 `filterSidebarItems(items, hasPermission)` 도 export.
+
+### Notes
+- `auth`/`hasPermission` 미지정 시 동작은 완전히 하위호환(게이트·필터 없이 기존대로 셸 로드).
+
+## [0.5.0] - 2026-07-02
+
+### Added
+- `AppConfig.enter` — global route guard, forwarded to the underlying `@iyulab/router` `Router`. Previously `@iyulab/router` already supported this via `RouterConfig.enter`, but `App.load()` never passed it through, so the global guard path was unreachable from modern-app. Return a `string` to redirect, `false` to cancel (403), `true`/nothing to proceed. See [docs/routing.md#authentication--guards](./docs/routing.md#authentication--guards).
+- `AppConfig.initialLoad` / `AppConfig.useIntercept` — forwarded to `Router` alongside `enter` (previously also unreachable; `initialLoad: false` is needed for guard unit tests that drive navigation explicitly).
+- Vitest + happy-dom test infrastructure (`npm test`) — first automated test suite for this package, covering `AppConfig.enter` redirect/cancel behavior.
+
+### Changed
+- `package.json` `scripts`: `"test"` now runs `vitest run` (was `vite`, which only started the dev server). The old behavior is available as `"start"`.
+
 ## [0.4.0] - 2026-07-02
 
 ### Added

package/README.md

@@ -109,12 +109,67 @@ import { translate } from 'lit-i18n';
 html`<p>${translate('common::greeting')}</p>`;
 ```
 
+### 부팅 인증 게이트 (`auth`)
+
+셸을 만들기 전에 세션을 판정한다. 소비앱이 `app.load()` 앞단에 손으로 짜던 "me 조회 → 미인증이면 로그인, 인증이면 앱 로드" 게이트를 표준화한다. 세션 조회/로그인 HTTP 는 `@iyulab/enterprise` 의 `createAuthClient` 가, 세션-중 401 은 `createODataService` 의 `onUnauthorized` 가 담당한다(프레임워크는 오케스트레이션만 소유).
+
+```typescript
+import { createAuthClient, setPermissions } from '@iyulab/enterprise';
+
+const auth = createAuthClient<User, Cred>({ meUrl: '/api/auth/me', loginUrl: '/api/auth/login', logoutUrl: '/api/auth/logout' });
+
+await app.load({
+  layout: { type: 'sidebar', /* ... */ },
+  auth: {
+    me: () => auth.fetchMe(),                         // null → 미인증 → renderLogin
+    renderLogin: ({ root, onSuccess }) => renderLoginPage(root, auth, onSuccess),
+    onAuthenticated: (user) => setPermissions((user as User).Permissions),
+  },
+  routes: [ /* ... */ ],
+});
+
+app.user; // 인증된 현재 사용자(미인증/미사용 시 undefined)
+```
+
+- `me()` 가 값을 반환하면 셸 로드, `null`/`undefined` 면 `renderLogin({ root, onSuccess })`.
+- 로그인 성공 시 `onSuccess()` 를 호출하면 앱이 재로드되어 셸이 나타나고 로그인 UI 는 정리된다.
+- `auth` 미지정 시 완전히 하위호환(게이트 없이 기존대로 로드).
+
+### 권한 기반 메뉴 필터
+
+모든 사이드바 메뉴 항목에 `requirePermission`/`requireAnyPermission` 를 달고, 레이아웃에 `hasPermission` 판정 함수를 주면 권한 없는 항목이 숨겨진다. 항목이 모두 걸러진 section/group 은 통째로 숨는다. 소비앱이 손으로 짜던 `filterMenu` 를 대체한다.
+
+```typescript
+import { hasPermission } from '@iyulab/enterprise';
+
+await app.load({
+  layout: {
+    type: 'sidebar',
+    hasPermission,                                  // enterprise 권한 store 판정
+    main: [
+      { type: 'link', icon: 'house', label: '홈', href: '/' },
+      { type: 'link', icon: 'gear', label: '설정', href: '/settings', requirePermission: 'admin.maintenance' },
+      {
+        type: 'section', title: '주문',
+        items: [
+          { type: 'link', label: '주문 목록', href: '/orders', requireAnyPermission: ['orders.read', 'orders.write'] },
+        ],
+      },
+    ],
+  },
+  auth: { /* ... */ },
+});
+```
+
+- `hasPermission` 미지정 시 필터링하지 않는다(모든 항목 표시 — 하위호환).
+- 순수 헬퍼 `filterSidebarItems(items, hasPermission)` 를 직접 재사용할 수도 있다.
+
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
 | [getting-started.md](./docs/getting-started.md) | Bootstrap, architecture, entry point setup |
-| [routing.md](./docs/routing.md) | Route config, URL params, async routes, progress |
+| [routing.md](./docs/routing.md) | Route config, URL params, async routes, progress, auth guards |
 | [layout.md](./docs/layout.md) | Sidebar layout, all menu item types, responsive behaviour |
 | [theme.md](./docs/theme.md) | Theme init, runtime switching, CSS tokens |
 | [notifications.md](./docs/notifications.md) | Toast methods and options |

package/dist/App.d.ts

@@ -12,6 +12,8 @@ declare class App {
     private _layout?;
     private _router?;
     private _screen?;
+    private _user?;
+    private _loginTeardown?;
     private constructor();
     /** 싱글톤 인스턴스 반환 */
     static get instance(): App;
@@ -21,6 +23,8 @@ declare class App {
     get router(): Router | undefined;
     /** 화면 크기 반환 */
     get screen(): ScreenSize | undefined;
+    /** 인증 게이트(`auth`) 사용 시 인증된 현재 사용자. 미인증/미사용이면 undefined. */
+    get user(): unknown;
     /** 스타일 테마 관리 유틸리티 객체 반환 */
     get theme(): typeof Theme;
     /** 다국어 로컬라이저(i18next) 반환 */

package/dist/App.js

@@ -18,6 +18,9 @@ var o = class o {
 	get screen() {
 		return this._screen?.get();
 	}
+	get user() {
+		return this._user;
+	}
 	get theme() {
 		return i;
 	}
@@ -25,7 +28,21 @@ var o = class o {
 		return t;
 	}
 	async load(a) {
-		if (this.unload(), this._config = a, await i.init(a.theme), a.iconBasepath && r(a.iconBasepath), a.i18n) {
+		if (this.unload(), this._config = a, a.auth) {
+			let e = await a.auth.me();
+			if (e == null) {
+				let e = a.root || document.body, t = a.auth.renderLogin({
+					root: e,
+					onSuccess: () => {
+						this.load(a);
+					}
+				});
+				t && (this._loginTeardown = t);
+				return;
+			}
+			this._user = e, await a.auth.onAuthenticated?.(e);
+		}
+		if (await i.init(a.theme), a.iconBasepath && r(a.iconBasepath), a.i18n) {
 			for (let e of a.i18n.plugins || []) t.use(e);
 			await t.init(a.i18n);
 		}
@@ -39,11 +56,14 @@ var o = class o {
 			root: this._layout,
 			basepath: a.basepath,
 			routes: a.routes,
-			fallback: a.fallback
+			fallback: a.fallback,
+			enter: a.enter,
+			initialLoad: a.initialLoad,
+			useIntercept: a.useIntercept
 		});
 	}
 	unload() {
-		this._screen &&= (this._screen.destroy(), void 0), this._layout &&= (this._layout.remove(), void 0), this._router &&= (this._router.destroy(), void 0), this._config &&= void 0;
+		this._loginTeardown &&= (this._loginTeardown(), void 0), this._user = void 0, this._screen &&= (this._screen.destroy(), void 0), this._layout &&= (this._layout.remove(), void 0), this._router &&= (this._router.destroy(), void 0), this._config &&= void 0;
 	}
 	navigate(e) {
 		this._router?.go(e);

package/dist/components/SidebarButton.d.ts

@@ -1,9 +1,10 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 /** 버튼 항목 부분 */
 type ElementParts = 'host' | 'base' | 'icon' | 'label';
 /** 버튼 항목 구성 */
-export interface SidebarButtonConfig {
+export interface SidebarButtonConfig extends SidebarPermissionGuard {
     type: 'button';
     icon?: string;
     label?: string | DirectiveResult;

package/dist/components/SidebarGroup.d.ts

@@ -1,9 +1,10 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
 import { SidebarLinkConfig } from './SidebarLink.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 type ElementParts = 'host' | 'header' | 'icon' | 'label' | 'caret' | 'items';
 /** 그룹: 하위 링크들 묶음 */
-export interface SidebarGroupConfig {
+export interface SidebarGroupConfig extends SidebarPermissionGuard {
     type: 'group';
     /** 기본 접힘 상태 */
     collapsed?: boolean;

package/dist/components/SidebarLink.d.ts

@@ -1,8 +1,9 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 type ElementParts = 'host' | 'base' | 'icon' | 'label';
 /** 링크 항목 디폴트 타입 */
-export interface SidebarLinkConfig {
+export interface SidebarLinkConfig extends SidebarPermissionGuard {
     type: 'link';
     icon?: string;
     label: string | DirectiveResult;

package/dist/components/SidebarSection.d.ts

@@ -2,9 +2,10 @@ import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
 import { SidebarLinkConfig } from './SidebarLink.js';
 import { SidebarGroupConfig } from './SidebarGroup.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 type ElementParts = 'host' | 'header' | 'title' | 'subtitle' | 'items';
 /** 섹션 내에는 그룹 또는 링크들만 허용 */
-export interface SidebarSectionConfig {
+export interface SidebarSectionConfig extends SidebarPermissionGuard {
     type: 'section';
     title: string | DirectiveResult;
     subTitle?: string | DirectiveResult;

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { app } from './App.js';
 export type * from './types/AppConfigs';
 export type * from './types/AppOptions';
+export type * from './types/AuthConfig';
+export type { SidebarPermissionGuard } from './layouts/SidebarPermission';
+export { filterSidebarItems } from './layouts/filterSidebarItems.js';
 export { app };
 export default app;

package/dist/index.js

@@ -1,5 +1,6 @@
 import { app as e } from "./App.js";
+import { filterSidebarItems as t } from "./layouts/filterSidebarItems.js";
 //#region src/index.ts
-var t = e;
+var n = e;
 //#endregion
-export { e as app, t as default };
+export { e as app, n as default, t as filterSidebarItems };

package/dist/layouts/SidebarLayout.js

@@ -1,27 +1,28 @@
 import { app as e } from "../App.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import n from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
-import { StyledElement as r } from "../internals/StyledElement.js";
+import { filterSidebarItems as t } from "./filterSidebarItems.js";
+import n from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
+import r from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
+import { StyledElement as i } from "../internals/StyledElement.js";
 import "../components/SidebarSection.js";
 import "../components/SidebarLink.js";
 import "../components/SidebarGroup.js";
 import "../components/SidebarButton.js";
-import { styles as i } from "./SidebarLayout.styles.js";
-import { html as a, nothing as o } from "lit";
-import { customElement as s, property as c, query as l, state as u } from "lit/decorators.js";
-import { unsafeHTML as d } from "lit/directives/unsafe-html.js";
-import { repeat as f } from "lit/directives/repeat.js";
+import { styles as a } from "./SidebarLayout.styles.js";
+import { html as o, nothing as s } from "lit";
+import { customElement as c, property as l, query as u, state as d } from "lit/decorators.js";
+import { unsafeHTML as f } from "lit/directives/unsafe-html.js";
+import { repeat as p } from "lit/directives/repeat.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 import "@iyulab/components/dist/components/button/UButton.js";
-import { UProgressBar as p } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
+import { UProgressBar as m } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
 //#region src/layouts/SidebarLayout.ts
-function m(e) {
+function h(e) {
 	let t = e.tagName;
 	if (t === "INPUT" || t === "TEXTAREA" || t === "SELECT" || e.isContentEditable) return !0;
 	let n = e.getAttribute("role");
 	return n === "textbox" || n === "searchbox" || n === "combobox" || n === "spinbutton";
 }
-var h = class extends r {
+var g = class extends i {
 	constructor(...t) {
 		super(...t), this.state = "default", this.context = null, this.isMatchedLink = (e) => !this.context || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.context.path, window.location.origin)), this.handleBrandLogoClick = (t) => () => {
 			e.navigate(t ?? "");
@@ -44,7 +45,7 @@ var h = class extends r {
 			}, 300);
 		}, this._handleMainKeydown = (e) => {
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && m(t)) return;
+			if (t instanceof HTMLElement && h(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
 			if (!n) return;
 			let r = n.clientHeight;
@@ -77,7 +78,7 @@ var h = class extends r {
 		};
 	}
 	static {
-		this.styles = [super.styles, i];
+		this.styles = [super.styles, a];
 	}
 	connectedCallback() {
 		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("route-error", this.handleRouteError), window.addEventListener("screen-resize", this.handleScreenResize);
@@ -89,7 +90,7 @@ var h = class extends r {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);
 	}
 	render() {
-		return this.config ? a`
+		return this.config ? o`
       <!-- Mobile Header -->
       <div class="mobile-header" part="mobile-header" ?hidden="${!this.state.startsWith("mobile")}">
         ${this.renderLogo()}
@@ -124,12 +125,12 @@ var h = class extends r {
 
         <!-- Sidebar Navigation Menu -->
         <nav class="sidebar-main" part="sidebar-main" scrollable>
-          ${f(this.config.main ?? [], (e, t) => t, (e) => this.renderItem(e))}
+          ${p(t(this.config.main ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
         </nav>
 
         <!-- Sidebar Footer -->
         <div class="sidebar-footer" part="sidebar-footer">
-          ${f(this.config.footer ?? [], (e, t) => t, (e) => this.renderItem(e))}
+          ${p(t(this.config.footer ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
         </div>
       </aside>
 
@@ -144,14 +145,14 @@ var h = class extends r {
       <div class="backdrop" ?hidden="${this.state !== "modal"}"
         @click="${this.handleBackdropClick}"
       ></div>
-    ` : o;
+    ` : s;
 	}
 	renderItem(e) {
-		if (!e) return o;
+		if (!e) return s;
 		if (e.type === "html") {
 			let t = e.render(this.state);
-			return typeof t == "string" ? d(t) : a`${t}`;
-		} else if (e.type === "button") return a`
+			return typeof t == "string" ? f(t) : o`${t}`;
+		} else if (e.type === "button") return o`
         <u-sidebar-button
           ?compact=${this.state === "slim"}
           .icon="${e.icon}"
@@ -162,7 +163,7 @@ var h = class extends r {
       `;
 		else if (e.type === "link") {
 			let t = this.isMatchedLink(e.pattern || e.href);
-			return a`
+			return o`
         <u-sidebar-link
           ?compact=${this.state === "slim"}
           ?selected=${t}
@@ -173,18 +174,18 @@ var h = class extends r {
           .styles="${e.styles}"
         ></u-sidebar-link>
       `;
-		} else if (e.type === "section") return a`
+		} else if (e.type === "section") return o`
         <u-sidebar-section
           ?compact=${this.state === "slim"}
           .mainTitle="${e.title}"
           .subTitle="${e.subTitle}"
           .styles="${e.styles}">
-          ${f(e.items, (e, t) => t, (e) => this.renderItem(e))}
+          ${p(e.items, (e, t) => t, (e) => this.renderItem(e))}
         </u-sidebar-section>
       `;
 		else if (e.type === "group") {
 			let t = e.items.some((e) => this.isMatchedLink(e.pattern || e.href));
-			return a`
+			return o`
         <u-sidebar-group
           ?compact=${this.state === "slim"}
           ?selected=${t}
@@ -192,14 +193,14 @@ var h = class extends r {
           .icon="${e.icon}"
           .label="${e.label}"
           .styles="${e.styles}">
-          ${f(e.items, (e, t) => t, (e) => this.renderItem(e))}
+          ${p(e.items, (e, t) => t, (e) => this.renderItem(e))}
         </u-sidebar-group>
       `;
-		} else return o;
+		} else return s;
 	}
 	renderLogo() {
 		let e = this.config?.logo;
-		if (!e || typeof e == "string") return a`
+		if (!e || typeof e == "string") return o`
         <u-icon class="logo"
           .name="${e}"
           @click=${this.handleBrandLogoClick()}
@@ -207,13 +208,13 @@ var h = class extends r {
       `;
 		if (typeof e == "function") {
 			let t = e(this.state);
-			return a`
+			return o`
         <span class="logo" @click=${this.handleBrandLogoClick()}>
-          ${typeof t == "string" ? d(t) : t}
+          ${typeof t == "string" ? f(t) : t}
         </span>
       `;
 		}
-		return a`
+		return o`
       <img class="logo"
         src="${e.src}"
         alt="${e.alt ?? ""}"
@@ -222,9 +223,9 @@ var h = class extends r {
     `;
 	}
 };
-n([c({
+r([l({
 	type: String,
 	reflect: !0
-}), t("design:type", Object)], h.prototype, "state", void 0), n([c({ type: Object }), t("design:type", Object)], h.prototype, "config", void 0), n([l("u-progress-bar"), t("design:type", p === void 0 ? Object : p)], h.prototype, "progressBarEl", void 0), n([u(), t("design:type", Object)], h.prototype, "context", void 0), h = n([s("u-sidebar-layout")], h);
+}), n("design:type", Object)], g.prototype, "state", void 0), r([l({ type: Object }), n("design:type", Object)], g.prototype, "config", void 0), r([u("u-progress-bar"), n("design:type", m === void 0 ? Object : m)], g.prototype, "progressBarEl", void 0), r([d(), n("design:type", Object)], g.prototype, "context", void 0), g = r([c("u-sidebar-layout")], g);
 //#endregion
-export { h as SidebarLayout };
+export { g as SidebarLayout };

package/dist/layouts/SidebarLayout.types.d.ts

@@ -4,12 +4,14 @@ import { SidebarLinkConfig } from '../components/SidebarLink';
 import { SidebarSectionConfig } from '../components/SidebarSection';
 import { SidebarGroupConfig } from '../components/SidebarGroup';
 import { SidebarButtonConfig } from '../components/SidebarButton';
+import { SidebarPermissionGuard } from './SidebarPermission';
+export type { SidebarPermissionGuard } from './SidebarPermission';
 /** 사이드바 레이아웃 컴포넌트의 요소(part) 타입 */
 export type SidebarParts = 'host' | 'mobile-header' | 'sidebar' | 'sidebar-header' | 'sidebar-main' | 'sidebar-footer' | 'main' | 'progress';
 /** 사이드바 상태 타입 */
 export type SidebarState = 'default' | 'slim' | 'modal' | 'mobile' | 'mobile-open';
 /** 사이드바 안에 HTML 또는 엘리먼트를 직접 렌더링하는 설정 */
-export interface SidebarHtmlConfig {
+export interface SidebarHtmlConfig extends SidebarPermissionGuard {
     type: 'html';
     render: (state: SidebarState) => TemplateResult<1> | HTMLElement | string;
 }
@@ -36,6 +38,12 @@ export interface SidebarLayoutConfig {
     main?: SidebarItem[];
     /** 하단(footer)에 고정해서 렌더할 항목들 */
     footer?: SidebarItem[];
+    /**
+     * 메뉴 항목 권한 필터 판정. 지정하면 `requirePermission`/`requireAnyPermission` 를 만족하지
+     * 않는 항목을 숨기고, 항목이 모두 걸러진 section/group 은 통째로 숨긴다.
+     * 미지정 시 필터링하지 않는다(모든 항목 표시). 보통 `@iyulab/enterprise` 의 `hasPermission` 을 넘긴다.
+     */
+    hasPermission?: (code: string) => boolean;
     /** 사이드바 스타일 맵 */
     styles?: StyleMap<SidebarParts>;
 }

package/dist/layouts/SidebarPermission.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 사이드바 메뉴 항목의 권한 가드. 모든 메뉴 config(link/section/group/button/html)가 확장한다.
+ *
+ * 판정 자체는 `SidebarLayoutConfig.hasPermission` 으로 **주입**한다 — 라이브러리는 권한 코드를
+ * 불투명 문자열로만 다루고 의미(도메인)는 앱이 소유한다. `@iyulab/enterprise` 의 `hasPermission`
+ * 을 그대로 넘겨 쓰는 것이 일반적이다.
+ *
+ * 의존성 없는 leaf 모듈 — 각 메뉴 config 파일이 순환 없이 import 한다.
+ */
+export interface SidebarPermissionGuard {
+    /** 이 권한 코드를 보유해야 항목이 표시된다. */
+    requirePermission?: string;
+    /** 이 코드 중 하나라도 보유하면 표시된다(빈 배열은 제약 없음). */
+    requireAnyPermission?: string[];
+}

package/dist/layouts/filterSidebarItems.d.ts

@@ -0,0 +1,11 @@
+import { SidebarItem } from './SidebarLayout.types';
+/**
+ * 권한에 따라 사이드바 메뉴 트리를 필터링한다. 소비앱이 손으로 짜던 `filterMenu` 를 표준화.
+ *
+ * - 각 항목의 `requirePermission`/`requireAnyPermission` 를 `hasPermission` 으로 검사해 탈락 항목 제거.
+ * - `section`/`group` 은 자식(`items`)을 재귀 필터하고, **자식이 모두 걸러지면 컨테이너째 제거**한다.
+ * - `hasPermission` 이 없으면(undefined) 원본을 그대로 반환한다(필터링 없음).
+ *
+ * 원본 배열/항목을 변형하지 않고 새 배열/얕은 복제본을 반환한다(순수).
+ */
+export declare function filterSidebarItems(items: readonly SidebarItem[], hasPermission?: (code: string) => boolean): SidebarItem[];

package/dist/layouts/filterSidebarItems.js

@@ -0,0 +1,19 @@
+//#region src/layouts/filterSidebarItems.ts
+function e(e, t) {
+	return !(e.requirePermission && !t(e.requirePermission) || e.requireAnyPermission && e.requireAnyPermission.length > 0 && !e.requireAnyPermission.some((e) => t(e)));
+}
+function t(n, r) {
+	if (!r) return n;
+	let i = r, a = [];
+	for (let r of n) if (r && e(r, i)) if (r.type === "section" || r.type === "group") {
+		let e = t(r.items, i);
+		if (e.length === 0) continue;
+		a.push({
+			...r,
+			items: e
+		});
+	} else a.push(r);
+	return a;
+}
+//#endregion
+export { t as filterSidebarItems };

package/dist/types/AppConfigs.d.ts

@@ -1,7 +1,8 @@
 import { InitOptions, Module, Newable, NewableModule } from 'i18next';
-import { RouteConfig, FallbackRouteConfig } from '@iyulab/router';
+import { RouteConfig, FallbackRouteConfig, RouteContext } from '@iyulab/router';
 import { ThemeInitOptions } from '@iyulab/components/dist/utilities/Theme.js';
 import { SidebarLayoutConfig } from '../layouts/SidebarLayout.types';
+import { AuthGateConfig } from './AuthConfig';
 /**
  * i18next의 초기화 옵션과 플러그인 배열을 포함한 다국어 설정
  */
@@ -45,6 +46,33 @@ export interface AppConfig {
      * 라우팅 실패 시 대체 컨텐츠 설정
      */
     fallback?: FallbackRouteConfig;
+    /**
+     * 모든 라우트 전환 전에 호출되는 전역 인증/권한 가드입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소(403)
+     * - `true`/무반환: 통과
+     * @example
+     * ```typescript
+     * app.load({
+     *   enter: (ctx) => isAuthenticated() || `/login?returnTo=${encodeURIComponent(ctx.pathname)}`,
+     *   routes: [
+     *     { path: '/login', render: () => html`<login-page></login-page>` },
+     *     // ...
+     *   ],
+     * });
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
+    /**
+     * 초기 로드 시 현재 URL로 라우팅을 자동으로 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    initialLoad?: boolean;
+    /**
+     * `a` 태그 클릭 시 클라이언트 라우팅을 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    useIntercept?: boolean;
     /**
      * 애플리케이션이 렌더링될 루트 HTML 요소
      * @default document.body
@@ -65,4 +93,22 @@ export interface AppConfig {
      * @see 설정에 대한 자세한 내용은 {@link https://www.i18next.com/overview/configuration-options} 참조하십시오.
      */
     i18n?: I18nInitOptions;
+    /**
+     * 부팅 인증 게이트(선택). 지정하면 앱 셸을 만들기 전에 `me()` 로 세션을 판정하여
+     * 인증 시 셸 로드, 미인증 시 `renderLogin` 으로 로그인 UI 를 띄운다.
+     * @see AuthGateConfig
+     * @example
+     * ```typescript
+     * app.load({
+     *   layout: { type: 'sidebar', ... },
+     *   auth: {
+     *     me: () => authClient.fetchMe(),                 // null → 미인증
+     *     renderLogin: ({ root, onSuccess }) => renderLoginPage(root, onSuccess),
+     *     onAuthenticated: (user) => setPermissions((user as User).Permissions),
+     *   },
+     *   routes: [ ... ],
+     * });
+     * ```
+     */
+    auth?: AuthGateConfig;
 }

package/dist/types/AuthConfig.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 부팅 인증 게이트 설정.
+ *
+ * `app.load({ auth })` 에 넘기면, 앱 셸(레이아웃·라우터)을 만들기 전에 세션을 판정한다:
+ * `me()` 가 값을 반환하면 인증된 것으로 보고 셸을 로드하고, `null`/`undefined` 면
+ * 미인증으로 보고 `renderLogin` 으로 로그인 UI 를 띄운다. 로그인 성공 시 `onSuccess()` 를
+ * 호출하면 앱이 (재)로드되어 셸이 나타난다.
+ *
+ * 프레임워크는 인증의 **오케스트레이션**(판정 → 분기 → 재로드)만 소유한다. 세션 조회/로그인
+ * 자체(HTTP)와 사용자·권한 형태, 세션-중 401 처리는 앱/`@iyulab/enterprise` 가 소유한다.
+ */
+export interface AuthGateContext {
+    /** 로그인 UI 를 그릴 루트 요소(= `app.load` 의 `root`, 기본 `document.body`). */
+    root: Element;
+    /** 로그인 성공 시 호출한다. 앱이 (재)로드되어 셸을 띄운다(이때 `me()` 는 사용자를 반환해야 한다). */
+    onSuccess: () => void;
+}
+export interface AuthGateConfig {
+    /**
+     * 현재 세션 조회. 값을 반환하면 인증, `null`/`undefined` 면 미인증으로 본다.
+     * 동기/비동기 모두 허용한다.
+     */
+    me: () => Promise<unknown | null | undefined> | unknown | null | undefined;
+    /**
+     * 미인증 시 `context.root` 에 로그인 UI 를 그린다. 성공하면 `context.onSuccess()` 를 호출해야 한다.
+     * 정리 함수를 반환하면 앱 로드/`unload` 시 호출되어 로그인 UI 를 제거한다.
+     */
+    renderLogin: (context: AuthGateContext) => (() => void) | void;
+    /**
+     * 인증 성공 후, 앱 셸을 만들기 직전에 호출된다(선택).
+     * 사용자별 라우트/메뉴 필터 등 셸 구성 전 처리를 여기서 한다.
+     */
+    onAuthenticated?: (user: unknown) => void | Promise<void>;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -34,7 +34,9 @@
     }
   },
   "scripts": {
-    "test": "vite",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "vite",
     "build": "vite build"
   },
   "dependencies": {
@@ -45,8 +47,10 @@
   },
   "devDependencies": {
     "@types/node": "^25.8.0",
+    "happy-dom": "^20.10.2",
     "typescript": "^5.9.3",
     "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.0"
+    "vite-plugin-dts": "^5.0.0",
+    "vitest": "^4.1.8"
   }
 }