@sd-angular/core 19.0.35 → 19.0.36

package/modules/authom/authom.module.d.ts

@@ -1,16 +1,46 @@
-import { ModuleWithProviders, Type, EnvironmentProviders } from '@angular/core';
+import { EnvironmentProviders, ModuleWithProviders, Type } from '@angular/core';
 import { ISdAuthOmConfiguration } from './authom.configuration';
 import * as i0 from "@angular/core";
-interface ProvideOptions {
+export interface SdAuthOmProvideOptions {
     useClass?: Type<ISdAuthOmConfiguration>;
     useFactory?: (...args: any[]) => ISdAuthOmConfiguration;
     deps?: any[];
+    /**
+     * Cấp luôn `SD_AUTH_CONFIGURATION` bằng `SdAuthOmAuthConfiguration`. Mặc định `true`.
+     *
+     * Nhờ vậy `SdAuthGuard`, `SdPortalGuard` và `SdAuthService.signout()` chạy được trên AuthOM mà
+     * app không phải khai báo gì thêm. Đặt `false` khi app tự bind token này (ví dụ portal chạy
+     * song song nhiều provider và tự chọn theo môi trường).
+     */
+    withAuthConfiguration?: boolean;
 }
-export declare function provideSdAuthOm(options: ProvideOptions): EnvironmentProviders;
+/**
+ * Đăng ký AuthOM cho app standalone (gọi trong `app.config.ts`).
+ *
+ * ```ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(withInterceptors([SdAuthOmInterceptor])),
+ *     provideSdAuthOm({
+ *       useFactory: () => ({
+ *         loadTenantConfig: () => Promise.resolve({
+ *           issuer: 'https://api-qc.onemount.dev/auth-om/iam/v1/mag-qc/',
+ *           clientId: 'YOUR_CLIENT_ID',
+ *           redirectUri: `${location.origin}/callback`,
+ *           audience: 'http://api-qc.int.onemount.dev/auth-om/api/v1/mag-qc',
+ *           secureRoutes: ['https://api-qc.onemount.dev'],
+ *         }),
+ *       }),
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export declare function provideSdAuthOm(options: SdAuthOmProvideOptions): EnvironmentProviders;
+/** Đăng ký AuthOM cho kiến trúc `NgModule` cũ. */
 export declare class SdAuthOmModule {
-    static forRoot(options: ProvideOptions): ModuleWithProviders<SdAuthOmModule>;
+    static forRoot(options: SdAuthOmProvideOptions): ModuleWithProviders<SdAuthOmModule>;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdAuthOmModule, never>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<SdAuthOmModule, never, never, never>;
     static ɵinj: i0.ɵɵInjectorDeclaration<SdAuthOmModule>;
 }
-export {};

package/modules/authom/authom.return-url.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Giữ deep link sống sót qua vòng redirect đăng nhập.
+ *
+ * AuthOM chỉ chấp nhận một `redirect_uri` đã đăng ký (các portal hiện dùng `/callback`), nên một
+ * user mở thẳng link sâu mà chưa có token sẽ mất đích đến: guard gọi code flow, cookie SSO của
+ * AuthOM trả lời ngay không cần hỏi, và trình duyệt quay về `/callback` rồi bị route mặc định đẩy
+ * sang trang chủ.
+ *
+ * Đích đến đi kèm tham số OIDC `state` (IdP round-trip nguyên vẹn) chứ không nằm trong storage:
+ * như vậy nó gắn với đúng một lần đăng nhập, không thể cũ đi và không rò sang điều hướng khác.
+ */
+/**
+ * Mã hoá trang mà user thực sự muốn vào, để gửi kèm `initCodeFlow`.
+ *
+ * Trả về `undefined` khi không có gì đáng khôi phục — lúc đó caller khởi động đăng nhập bình thường.
+ *
+ * Giá trị trả về là chuỗi THÔ, cố ý không percent-encode: client OIDC đã tự
+ * `encodeURIComponent(additionalState)` trước khi ghép vào `state`, và chuỗi giải mã của nó chỉ bóc
+ * đúng một lớp. Encode thêm ở đây làm giá trị quay về dạng double-encoded (`%252F...`) và
+ * `resolveReturnUrl` sẽ loại bỏ nó.
+ */
+export declare function captureReturnUrl(requestedUrl: string | undefined | null, callbackPath?: string): string | undefined;
+/**
+ * Đọc lại giá trị mà `captureReturnUrl` đã gửi đi; trả `null` khi `state` rỗng hoặc không khôi phục được.
+ *
+ * Một lần `decodeURIComponent` để bóc lớp mã hoá mà client OIDC áp lên phần state của app; lớp ngoài
+ * bọc cả tham số đã được chính nó gỡ trước khi giá trị tới đây. Chuỗi không mã hoá sẽ giải mã ra
+ * chính nó, nên hàm vẫn đúng trong cả hai trường hợp.
+ */
+export declare function resolveReturnUrl(state: string | undefined | null, callbackPath?: string): string | null;
+/**
+ * `state` đi vòng qua IdP nên kẻ tấn công có thể tác động; chỉ chấp nhận path nằm trong chính app này.
+ *
+ * URL tuyệt đối hoặc protocol-relative (`//evil.example`, hoặc `/\evil.example` — trình duyệt tự
+ * chuẩn hoá dấu gạch ngược) sẽ biến vòng đăng nhập thành open redirect.
+ */
+export declare function isRestorableAppUrl(url: string, callbackPath?: string): boolean;

package/modules/authom/authom.service.d.ts

@@ -1,32 +1,126 @@
+import { AuthConfig } from 'angular-oauth2-oidc';
+import { Observable } from 'rxjs';
+import type { SdAuthInfo } from '@sd-angular/core/modules/auth';
+import type { SdLayoutUserInfo } from '@sd-angular/core/modules/layout';
 import { SdAuthOmTenantConfig } from './authom.configuration';
+import { SdAuthOmEvent } from './authom.event';
 import * as i0 from "@angular/core";
+/**
+ * Client xác thực AuthOM: Authorization Code + PKCE trên discovery document của IdP.
+ *
+ * Service sở hữu toàn bộ vòng đời phiên — bootstrap, khôi phục deep link, gia hạn token chủ động,
+ * phát hiện hết phiên, đăng xuất xuyên tab — nên app chỉ cần khai báo cấu hình tenant.
+ */
 export declare class SdAuthOmService {
-    private readonly platformId;
-    private readonly isBrowser;
+    #private;
+    /** Cấu hình tenant đang dùng. `undefined` cho tới khi `init()` chạy xong. */
+    config?: SdAuthOmTenantConfig;
     readonly accessToken: import("@angular/core").WritableSignal<string | null>;
     readonly idTokenClaims: import("@angular/core").WritableSignal<Record<string, unknown> | null>;
     readonly isAuthenticated: import("@angular/core").Signal<boolean>;
-    config: SdAuthOmTenantConfig;
-    private refreshTimer;
-    getAccessToken(): string | null;
-    private base64UrlEncode;
-    private generateCodeVerifier;
-    private generateCodeChallenge;
-    private buildAuthorizeUrl;
-    private getDefaultRedirectUri;
-    private getSilentRedirectUri;
-    private decodeJwtPayload;
+    /** `true` khi gia hạn đã thất bại VÀ access token cuối cùng cũng đã hết hạn. */
+    readonly sessionExpired: import("@angular/core").WritableSignal<boolean>;
+    /** Sự kiện `auth_error` gần nhất, hoặc `null` khi lần đăng nhập gần nhất sạch. */
+    readonly lastAuthError: import("@angular/core").WritableSignal<SdAuthOmEvent | null>;
+    /** Luồng sự kiện xác thực. Xem `SdAuthOmEventType`. */
+    readonly events$: Observable<SdAuthOmEvent>;
+    constructor();
+    /**
+     * Cấu hình client, tải discovery document, xử lý callback nếu có, rồi bật gia hạn chủ động.
+     *
+     * Chạy trong APP_INITIALIZER (xem `provideSdAuthOm`), tức trước điều hướng đầu tiên của Router —
+     * nhờ vậy guard của route đầu tiên đã thấy trạng thái phiên đúng.
+     *
+     * @returns `true` khi kết thúc với một access token hợp lệ.
+     */
+    init(config: SdAuthOmTenantConfig): Promise<boolean>;
+    /**
+     * Quy đổi cấu hình tenant sang `AuthConfig` của client OIDC.
+     *
+     * Public để app kiểm tra được cấu hình thực tế trong test mà không phải chạy cả `init()`.
+     */
+    buildAuthConfig(config: SdAuthOmTenantConfig): AuthConfig;
+    /**
+     * Khởi động Authorization Code flow.
+     *
+     * `returnTo` mặc định là URL hiện tại, đi kèm tham số OIDC `state` để deep link sống sót qua
+     * vòng redirect (xem `authom.return-url.ts`).
+     */
     login(options?: {
         returnTo?: string;
+        prompt?: 'login' | 'none' | 'consent';
     }): Promise<void>;
+    /**
+     * Kết thúc phiên cục bộ rồi (mặc định) bắt đăng nhập lại với `prompt=login`.
+     *
+     * AuthOM không công bố `end_session_endpoint` và không hỗ trợ thu hồi token, nên đăng xuất
+     * KHÔNG gọi endpoint nào của IdP trừ khi `endSessionOnLogout` được bật rõ ràng.
+     */
     logout(options?: {
         returnTo?: string;
+        prompt?: 'login' | 'none' | false;
     }): void;
-    private exchangeCode;
-    private scheduleRefresh;
+    /**
+     * Gia hạn access token ngay lập tức.
+     *
+     * Dùng refresh_token grant khi IdP đã phát hành refresh token, ngược lại rơi về silent refresh
+     * bằng iframe ẩn. Các lời gọi chồng nhau dùng chung một request đang bay.
+     *
+     * @returns `true` khi kết thúc với access token hợp lệ.
+     */
+    refresh(): Promise<boolean>;
+    /**
+     * Tên cũ của `refresh()`, giữ để tương thích ngược.
+     *
+     * @deprecated Dùng `refresh()`.
+     */
     silentRefresh(): Promise<boolean>;
+    /**
+     * Ghi nhận một `401` từ route đã được bảo vệ.
+     *
+     * Đây là tín hiệu hết phiên đáng tin nhất: một lần refresh hỏng vẫn có thể xảy ra khi token cũ
+     * còn hạn, nhưng `401` nghĩa là resource server đã từ chối đúng token đang dùng.
+     *
+     * - Token đã hết hạn ⇒ phiên chết, phát `session_expired` (và đăng nhập lại nếu cấu hình cho phép).
+     * - Token vẫn còn hạn ⇒ server từ chối vì lý do khác (sai `audience`, client bị thu hồi...);
+     *   phát `auth_error` với `reason = 'unauthorized'` để app tự hiển thị thông báo.
+     *
+     * `SdAuthOmInterceptor` gọi sẵn; chỉ cần gọi tay khi app dùng HTTP client riêng.
+     */
+    handleUnauthorized(): void;
+    /** `true` khi có thể thử gia hạn mà không cần user tương tác. */
+    canRefresh(): boolean;
+    /**
+     * Xử lý callback `?code=` thủ công.
+     *
+     * `init()` đã tự làm việc này; chỉ cần gọi tay khi app tách riêng một route `/callback` chạy
+     * ngoài APP_INITIALIZER.
+     */
     handleCallback(): Promise<boolean>;
-    init(config: SdAuthOmTenantConfig): Promise<boolean>;
+    getAccessToken(): string | null;
+    /** `true` khi không còn access token dùng được (chưa đăng nhập, hoặc đã quá hạn). */
+    isAccessTokenExpired(): boolean;
+    /** URL có nằm trong `secureRoutes` không — tức có được đính Bearer token không. */
+    isSecureUrl(url: string): boolean;
+    /** Origin của IdP, để interceptor không bao giờ tự đính token vào chính request lấy token. */
+    getIssuerOrigin(): string | null;
+    /** Claims của user hiện tại ở dạng `SdAuthInfo` của module auth, hoặc `null` khi chưa đăng nhập. */
+    authInfo(): SdAuthInfo | null;
+    /** Claims của user hiện tại ở dạng `SdLayoutUserInfo` của module layout. */
+    userInfo(): SdLayoutUserInfo;
+    /** Điều hướng full-page. */
+    protected navigate(url: string): void;
+    /** Viết lại URL trên thanh địa chỉ mà không tạo entry mới trong history. */
+    protected replaceHistoryState(url: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<SdAuthOmService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<SdAuthOmService>;
 }
+/**
+ * Khớp một URL với một phần tử `secureRoutes`.
+ *
+ * Có `*` → glob trên toàn bộ URL. Không có `*` → khớp tiền tố, không phân biệt hoa thường
+ * (đây là dạng "danh sách host" mà các portal đang dùng).
+ */
+export declare function matchSecureRoute(pattern: string, url: string): boolean;
+/** Khớp glob đơn giản, `*` thay cho một đoạn bất kỳ. Giữ nguyên hành vi từ bản trước của module. */
+export declare const matchGlob: (pattern: string, url: string) => boolean;

package/modules/authom/authom.session-channel.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Đồng bộ đăng xuất giữa các tab cùng origin.
+ *
+ * Phiên AuthOM sống trong bộ nhớ của client OIDC, có `sessionStorage` làm nền — mà `sessionStorage`
+ * bị trình duyệt cô lập theo tab. Không có server-side session để thu hồi (AuthOM không công bố
+ * `end_session_endpoint`) và cũng không có cơ chế kiểm tra liveness xuyên tab. Hệ quả: đăng xuất ở
+ * một tab để các tab còn lại dùng được bình thường cho tới khi access token của chính chúng hết hạn.
+ *
+ * `BroadcastChannel` không bao giờ gửi message ngược về đối tượng đã post, nên tab kích hoạt đăng
+ * xuất không tự xử lý lại sự kiện của chính nó.
+ */
+/**
+ * Bọc `BroadcastChannel` cho tín hiệu đăng xuất, và tự vô hiệu hoá khi môi trường không hỗ trợ
+ * (SSR, trình duyệt cũ, `BroadcastChannel` bị chặn).
+ */
+export declare class SdAuthOmSessionChannel {
+    #private;
+    constructor(name: string);
+    /** `true` khi môi trường thực sự hỗ trợ kênh; `false` thì mọi thao tác là no-op. */
+    get enabled(): boolean;
+    /** Báo cho mọi tab khác rằng phiên vừa kết thúc. */
+    notifyLogout(): void;
+    /** Đăng ký callback chạy khi một tab khác báo đã đăng xuất. */
+    onLogout(handler: () => void): void;
+    close(): void;
+}

package/modules/authom/index.d.ts

@@ -1,5 +1,9 @@
 /**
- * Module `authom` — OAuth 2.0 + PKCE authentication client cho AuthOM (Auth0-based).
+ * Module `authom` — client xác thực OAuth 2.0 Authorization Code + PKCE cho AuthOM.
+ *
+ * Module sở hữu trọn vòng đời phiên: bootstrap qua discovery document, đổi authorization code,
+ * khôi phục deep link, gia hạn token chủ động, phát hiện hết phiên, xử lý lỗi xác thực và đăng
+ * xuất đồng bộ giữa các tab.
  *
  * Cách dùng (standalone):
  * ```ts
@@ -12,12 +16,11 @@
  *     provideSdAuthOm({
  *       useFactory: () => ({
  *         loadTenantConfig: () => Promise.resolve({
- *           domain: 'login.example.com',
+ *           issuer: 'https://api-qc.onemount.dev/auth-om/iam/v1/mag-qc/',
  *           clientId: 'YOUR_CLIENT_ID',
- *           audience: 'https://api.example.com',
- *           organization: 'org_xxx',
- *           scope: 'openid profile email offline_access',
- *           secureRoutes: ['https://api.example.com/*'],
+ *           redirectUri: `${location.origin}/callback`,
+ *           audience: 'http://api-qc.int.onemount.dev/auth-om/api/v1/mag-qc',
+ *           secureRoutes: ['https://api-qc.onemount.dev'],
  *         }),
  *       }),
  *     }),
@@ -25,11 +28,18 @@
  * };
  * ```
  *
- * Yêu cầu setup thêm:
- * 1. Copy file `silent-authom.html` từ source module này vào thư mục `public/` của app.
- * 2. App phải chạy trên HTTPS (hoặc localhost) — Web Crypto API yêu cầu secure context.
+ * Yêu cầu phía app:
+ * 1. Cài `angular-oauth2-oidc` (peer dependency, chọn major khớp Angular của app).
+ * 2. App chạy trên HTTPS hoặc localhost — Web Crypto API cần secure context để tạo PKCE.
+ * 3. `redirectUri` phải trùng giá trị đã đăng ký trên client AuthOM.
+ * 4. Chỉ khi bật `useSilentRefresh`: copy `silent-authom.html` cạnh source module này vào `public/`.
  */
 export * from './authom.configuration';
+export * from './authom.event';
+export * from './authom.return-url';
+export * from './authom.session-channel';
 export * from './authom.service';
 export * from './authom.interceptor';
+export * from './authom.guard';
+export * from './authom.auth-configuration';
 export * from './authom.module';

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@sd-angular/core",
-  "version": "19.0.35",
+  "version": "19.0.36",
   "peerDependencies": {
     "@angular/common": "^19.0.0 || ^20.0.0 || ^21.0.0",
     "@angular/core": "^19.0.0 || ^20.0.0 || ^21.0.0",
     "@angular/material": "^19.0.0 || ^20.0.0 || ^21.0.0",
-    "@angular/material-date-fns-adapter": "^19.0.0 || ^20.0.0 || ^21.0.0"
+    "@angular/material-date-fns-adapter": "^19.0.0 || ^20.0.0 || ^21.0.0",
+    "angular-oauth2-oidc": ">=19.0.0"
   },
   "dependencies": {
-    "@sdcorejs/utils": "1.1.4",
+    "@sdcorejs/utils": "1.2.2",
     "@ckeditor/ckeditor5-angular": "11.1.2",
     "@omer-go/docx-parser-converter-ts": "^1.0.0",
     "@bjorn3/browser_wasi_shim": "^0.4.2",
@@ -22,6 +23,11 @@
     "tslib": "^2.8.0"
   },
   "sideEffects": false,
+  "peerDependenciesMeta": {
+    "angular-oauth2-oidc": {
+      "optional": true
+    }
+  },
   "module": "fesm2022/sd-angular-core.mjs",
   "typings": "index.d.ts",
   "exports": {

package/utilities/extensions/src/string.extension.d.ts

@@ -38,10 +38,14 @@ export declare const StringUtilities: {
     changeAliasLowerCase: (alias: any) => string;
     aliasIncludes: (alias: any, searchText: any) => boolean;
     format: (template: string, ...arr: any[]) => string;
-    templateToDisplay: (template: string, entity: Record<string, any>) => string;
-    parseExpression: (template: string, entity: Record<string, any>) => any;
+    templateToDisplay: (template: string, entity: Record<string, any>, options?: import("@sdcorejs/utils/fns").TemplatePathOptions) => string;
+    parseExpression: (template: string, entity: Record<string, any>, options?: import("@sdcorejs/utils/fns").TemplatePathOptions) => unknown;
+    obfuscate: (obj: any) => string;
+    deobfuscate: (encripted: string) => any;
     encrypt: (obj: any) => string;
     decrypt: (encripted: string) => any;
+    encryptAesGcm: <T>(value: T, key: CryptoKey | Uint8Array, options?: import("@sdcorejs/utils/fns").AesGcmEncryptOptions) => Promise<string>;
+    decryptAesGcm: <T>(token: string, key: CryptoKey | Uint8Array, options?: import("@sdcorejs/utils/fns").AesGcmDecryptOptions) => Promise<T>;
     isNullOrEmpty: (value: any) => boolean;
     isNullOrWhiteSpace: (value: any) => boolean;
     convertToSnakeCaseCode: (name: string) => string;

package/utilities/models/src/maybe-async.model.d.ts

@@ -7,4 +7,4 @@ export type SdMaybeAsync<T> = MaybeAsync<T>;
 /** @deprecated Use {@link resolveMaybeAsync} from `@sdcorejs/utils/models` instead */
 export declare const SdResolveMaybeAsync: <T>(value: MaybeAsync<T>) => Promise<T>;
 /** @deprecated Use {@link normalizeAsync} from `@sdcorejs/utils/models` instead */
-export declare const SdNormalizeAsync: <T>(value: MaybeAsync<T>) => import("rxjs").Observable<T>;
+export declare const SdNormalizeAsync: typeof import("@sdcorejs/utils/models").normalizeSubscribable;