@autional/shared 0.0.0-stage → 0.1.0-rc.32

package/src/hooks/usePortalCatalog.ts

@@ -0,0 +1,199 @@
+'use client';
+
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { getAccessToken, useAuthStore } from '../auth/store';
+import { apiClient } from '../api/client';
+import { getPortalUrl } from '../config';
+import { useCurrentRole } from './useCurrentRole';
+
+/** 平台租户 well-known ULID（service-core base/constant TenantPlatformID，全环境同值） */
+export const PLATFORM_TENANT_ID = '01KSQCBNVMS6SX64PJS937CE33';
+
+/** 管理面平面角色集（admin/security 门户）——与登录入口门禁同集：member/guest 登录被拒 40000503 */
+export const ADMIN_PLANE_ROLES: readonly string[] = [
+	'super_admin',
+	'admin',
+	'security_admin',
+	'user_manager',
+];
+
+/**
+ * 门户可见性 = 入口门禁的镜像（谁能登录谁才看见）：
+ * - platform：仅平台租户成员
+ * - admin / security：仅管理面角色
+ * - 其余 code：不限制（叠加原则，未知门户不误伤）
+ */
+export function isPortalVisible(
+	code: string,
+	ctx: { role: string | null; isPlatformMember: boolean },
+): boolean {
+	if (code === 'platform') return ctx.isPlatformMember;
+	if (code === 'admin' || code === 'security') {
+		return ctx.role !== null && ADMIN_PLANE_ROLES.includes(ctx.role);
+	}
+	return true;
+}
+
+/** 平台门户目录项（映射自 tenant-service 应用列表响应，is_platform=true） */
+export interface PortalCatalogEntry {
+	code: string;
+	name: string;
+	description?: string;
+	/** getPortalUrl 按 code 拼装（slug 白名单门户带租户段，域根门户落根 URL） */
+	url: string;
+	order: number;
+}
+
+/**
+ * 数据面端点平面（网关路由隔离矩阵 §3.3）：
+ * - `self`：user 受众自视图端点 `/tenants/{id}/applications`（entry_plane=api；auth/user 门户）
+ * - `admin`：管理面双入口端点 `/admin/tenants/{id}/applications`（audiences [admin, platform]；
+ *   admin/security/platform 控制台共用。api 平面在该路由上 403，反之亦然）
+ */
+export type PortalCatalogAudience = 'self' | 'admin';
+
+export interface UsePortalCatalogOptions {
+	tenantId?: string | null;
+	/** 拼门户 URL 的第二参 slug（非 slug 白名单门户自动忽略，见 config.getPortalUrl） */
+	slug?: string | null;
+	/**
+	 * 可见性/角色判定用（缺省回退 store 当前角色 useCurrentRole）。
+	 * 显式 null = 按“无角色”过滤（管理面门户与 allowed_roles 门槛均不可见）。
+	 */
+	role?: string | null;
+	audience?: PortalCatalogAudience;
+	enabled?: boolean;
+	exclude?: readonly string[];
+}
+
+export interface UsePortalCatalogResult {
+	/** exclude + 可见性（入口门禁镜像）+ allowed_roles → order 升序（门户切换器 / 磁贴网格用） */
+	portals: PortalCatalogEntry[];
+	/** 同一可见集合、保持服务端顺序（偏好配置面板用） */
+	allPortals: PortalCatalogEntry[];
+	isLoading: boolean;
+	isError: boolean;
+	refetch: () => void;
+}
+
+// 「切换门户」清单默认排除：auth/landing 非切换目标；authenticator 为移动 App 形态
+// （TOTP/push），与其他门户功能形态不同，不列入桌面门户清单
+const DEFAULT_EXCLUDE: readonly string[] = ['auth', 'landing', 'authenticator'];
+const PORTAL_CATALOG_STALE_TIME = 60_000;
+
+interface RawPortalApplication {
+	code: string;
+	name: string;
+	description?: string;
+	order?: number;
+	/** allowedRoles 为 apiClient camelCase 归一后的键（snake 形态兼容后端透出前的原始键） */
+	config?: {
+		portal?: { allowedRoles?: readonly string[]; allowed_roles?: readonly string[] };
+	} | null;
+}
+
+function toEntry(app: RawPortalApplication, slug?: string): PortalCatalogEntry {
+	return {
+		code: app.code,
+		name: app.name,
+		description: app.description,
+		url: getPortalUrl(app.code, slug),
+		order: app.order ?? 0,
+	};
+}
+
+/**
+ * 平台门户目录（应用清单，is_platform=true 全租户同集）。
+ * 消费侧按所在控制台平面传 audience；403/网络失败 → isError（不静默吞），
+ * 调用方可据此降级（隐藏切换器或静态兜底）。401 由 apiClient 拦截器预刷新 + 重试自愈。
+ */
+export function usePortalCatalog(options: UsePortalCatalogOptions = {}): UsePortalCatalogResult {
+	const {
+		tenantId,
+		slug,
+		role: roleProp,
+		audience = 'self',
+		enabled = true,
+		exclude = DEFAULT_EXCLUDE,
+	} = options;
+	const token = getAccessToken();
+	const currentRole = useCurrentRole();
+	const role = roleProp !== undefined ? roleProp : currentRole;
+	const isPlatformMember = useAuthStore((s) =>
+		s.tenants.some((t) => t.id === PLATFORM_TENANT_ID),
+	);
+
+	const query = useQuery({
+		// slug 只影响 URL 拼装（memo 层），不进 key：同一份目录不随 slug 重复拉取
+		queryKey: ['portal-catalog', audience, tenantId],
+		staleTime: PORTAL_CATALOG_STALE_TIME,
+		retry: false,
+		enabled: enabled && !!tenantId && !!token,
+		queryFn: async (): Promise<RawPortalApplication[]> => {
+			// 走 apiClient：请求前预刷新 + 401→刷新→重试 + X-Tenant-ID 注入（裸 fetch 无此链路）
+			const apiPrefix = audience === 'admin' ? '/tenant/api/v1/admin' : '/tenant/api/v1';
+			const res = await apiClient.get(`${apiPrefix}/tenants/${tenantId}/applications`, {
+				params: { type: 'portal', is_platform: 'true', status: 'active' },
+			});
+			// 响应拦截器已 unwrap {code,data}/{code,items} 并做 camelCase；此处只做形状容错
+			const body: unknown = res.data;
+			if (Array.isArray(body)) return body as RawPortalApplication[];
+			if (body && typeof body === 'object') {
+				const shaped = body as {
+					items?: unknown;
+					data?: unknown;
+					code?: number;
+					message?: string;
+				};
+				if (Array.isArray(shaped.items)) return shaped.items as RawPortalApplication[];
+				if (Array.isArray(shaped.data)) return shaped.data as RawPortalApplication[];
+				if (typeof shaped.code === 'number' && shaped.code !== 0) {
+					throw new Error(shaped.message || `portal catalog request failed (code ${shaped.code})`);
+				}
+			}
+			return [];
+		},
+	});
+
+	// exclude 过滤后保持服务端顺序
+	const excludedPortals = useMemo(() => {
+		const excluded = new Set(exclude);
+		return (query.data ?? []).filter((app) => !excluded.has(app.code));
+	}, [query.data, exclude]);
+
+	// 可见性（入口门禁镜像）+ allowed_roles 叠加
+	// （allowed_roles 数据通路后端尚未透出——tenant-service 列表 DTO 无 config 字段；
+	//   存在时叠加生效，见 usePortalCatalog 审计记录）
+	const visiblePortals = useMemo(
+		() =>
+			excludedPortals.filter((app) => {
+				if (!isPortalVisible(app.code, { role, isPlatformMember })) return false;
+				const allowedRoles =
+					app.config?.portal?.allowedRoles ?? app.config?.portal?.allowed_roles;
+				return !allowedRoles || allowedRoles.includes(role ?? '');
+			}),
+		[excludedPortals, role, isPlatformMember],
+	);
+
+	const allPortals = useMemo(
+		() => visiblePortals.map((app) => toEntry(app, slug || undefined)),
+		[visiblePortals, slug],
+	);
+
+	const portals = useMemo(
+		() =>
+			visiblePortals
+				.map((app) => toEntry(app, slug || undefined))
+				.sort((a, b) => a.order - b.order),
+		[visiblePortals, slug],
+	);
+
+	return {
+		portals,
+		allPortals,
+		isLoading: query.isLoading,
+		isError: query.isError,
+		refetch: query.refetch,
+	};
+}

package/src/hooks/useSodMode.ts

@@ -0,0 +1,81 @@
+/**
+ * useSodMode — 租户 SoD 模式 Hook
+ *
+ * 通过 tenant-service API 读取当前租户的 sod_mode 配置，
+ * 决定 `admin` 角色对审计功能的可见性。
+ *
+ * 模式:
+ *   'single' — 小客户模式（默认）: admin 可看 L1 统计 + L2 操作反馈
+ *   'strict' — 大客户/受监管: admin 仅看 L1 统计摘要
+ *
+ * API: GET /tenant/api/v1/admin/tenants/{tenantId}/sod-config   （apiClient baseURL=/bff）
+ *      PUT /tenant/api/v1/admin/tenants/{tenantId}/sod-config
+ * {tenantId} 为租户 ULID —— 后端 GetSodConfig 按租户主键（id）查找，传 slug 必 404。
+ *
+ * @see document/architecture/decisions/007-security-dashboard-audit.md §2.3
+ */
+
+'use client';
+
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { apiClient } from '../api/client';
+import { API as API_PATHS } from '../constants/api-paths';
+import { extractItem } from '../utils/response';
+import { useAuthStore } from '../auth/store';
+import { useCurrentRole } from './useCurrentRole';
+
+export type SodMode = 'single' | 'strict';
+
+/**
+ * 响应字段为 camelCase —— axios 响应拦截器（api/client.ts）对后端
+ * `{tenant_id, sod_mode, updated_at}` 做过 camelCaseKeys 转换。
+ */
+interface SodConfigResponse {
+	tenantId: string;
+	sodMode: SodMode;
+	updatedAt: string;
+}
+
+/**
+ * 返回当前租户的 sod_mode。
+ * 从 tenant-service 的 /admin/tenants/{ULID}/sod-config 读取（经 /bff 网关）。
+ *
+ * 返回 null 表示模式未知（无租户 / 加载中 / 请求失败）—— 不再折叠成 'single':
+ * 'single' 仅表示服务端确认的小客户模式；请求失败经 react-query 错误通道暴露。
+ * （U97: 此前路径缺 /tenant 服务段 + 传 slug + catch 吞错 + 读 snake_case 键，
+ * 四连缺陷叠加使 strict 租户的审计 L2 限制恒不生效。）
+ */
+export function useSodMode(): SodMode | null {
+	const tenantId = useAuthStore((s) => s.currentTenantId);
+
+	const { data: config } = useQuery<SodConfigResponse | null>({
+		queryKey: ['sod-config', tenantId],
+		queryFn: () => fetchSodConfig(tenantId),
+		staleTime: 5 * 60 * 1000, // 5 min cache
+		retry: 1,
+		enabled: !!tenantId,
+	});
+
+	return config?.sodMode ?? null;
+}
+
+async function fetchSodConfig(tenantId: string | null): Promise<SodConfigResponse | null> {
+	if (!tenantId) return null;
+	// 路径须循 /<服务>/api/v1/... 惯例（U97: 此前漏 /tenant 服务段 → 网关 404）
+	const res = await apiClient.get(API_PATHS.TENANT.SOD_CONFIG(tenantId));
+	return extractItem<SodConfigResponse>(res.data);
+}
+
+/**
+ * 判断当前用户在 strict 模式下是否被限制查看审计详情。
+ * 模式未知（null）时不判定为受限（维持既有 fail-open 语义）。
+ */
+export function useIsAuditRestricted(): boolean {
+	const sodMode = useSodMode();
+	const role = useCurrentRole();
+
+	return useMemo(() => {
+		return sodMode === 'strict' && role === 'admin';
+	}, [sodMode, role]);
+}

package/src/index.ts

@@ -0,0 +1,247 @@
+// API
+export { apiClient, createApiClient } from './api/client';
+export {
+	setTraceParentProvider,
+	getTraceParentHeader,
+	resetSessionTraceId,
+	enableOtelBridge,
+} from './api/trace';
+export { bffLogin, bffRefresh, bffLogout, isBFFAvailable } from './api/bff-client';
+
+// Auth
+export {
+	useAuthStore,
+	getAccessToken,
+	getRefreshToken,
+	getCurrentTenantId,
+	getCurrentRole,
+	loginWithTokens,
+	logout,
+	isTokenExpired,
+	refreshAccessToken,
+} from './auth/store';
+export { AuthService } from './auth/service';
+export { generatePKCE, generateCodeChallenge } from './auth/pkce';
+export type { PKCEPair } from './auth/pkce';
+export {
+	initiateOAuthLogin,
+	handleOAuthCallback,
+	isOAuthEnabled,
+	OAuthCallbackError,
+} from './auth/oauth-login';
+export { decodeJwtPayload } from './auth/jwt-payload';
+export { buildLoginUrl } from './auth/roles';
+export { traceRedirect, traceEvent, traceDump } from './auth/auth-trace';
+export type { AuthTraceEntry, AuthTraceRedirectOptions } from './auth/auth-trace';
+
+// Types
+export type {
+	User,
+	LoginRequest,
+	LoginResponse,
+	RegisterRequest,
+	Tenant,
+	TenantMember,
+	Role,
+	Permission,
+	Application,
+	AuditLog,
+	Session,
+	Department,
+	ListResponse,
+	PageRequest,
+	ApiError,
+	ApiResponse,
+} from './types';
+
+// Hooks
+export {
+	useAuth,
+	useAuthActions,
+	useIsAuthenticated,
+	useUser,
+	useUserId,
+	useAccessToken,
+	useAuthPermissions,
+	useCurrentTenantId,
+	useTenants,
+} from './hooks/useAuth';
+export { useCurrentTenantIdOr } from './hooks/useCurrentTenantIdOr';
+export type { AuthSnapshot, AuthActions } from './hooks/useAuth';
+export { usePermission } from './hooks/usePermission';
+export type { PermissionResult } from './hooks/usePermission';
+export { useLogout } from './hooks/useLogout';
+export { useBootstrap } from './hooks/useBootstrap';
+export type { BootstrapState } from './hooks/useBootstrap';
+export { useSodMode, useIsAuditRestricted } from './hooks/useSodMode';
+export type { SodMode } from './hooks/useSodMode';
+export { useCurrentRole } from './hooks/useCurrentRole';
+export {
+	usePortalCatalog,
+	isPortalVisible,
+	PLATFORM_TENANT_ID,
+	ADMIN_PLANE_ROLES,
+} from './hooks/usePortalCatalog';
+export type {
+	PortalCatalogEntry,
+	PortalCatalogAudience,
+	UsePortalCatalogOptions,
+	UsePortalCatalogResult,
+} from './hooks/usePortalCatalog';
+
+// Constants
+export { API as API_PATHS } from './constants/api-paths';
+
+// Config
+export {
+	// U351：AUTH_PAGES_URL 别名导出已移除（字符串模板误用会静默产出函数源码）；
+	// 消费方一律 `getAUTH_PAGES_URL()`（其余别名族 93 行起保留，登记为同族潜伏面）。
+	getAUTH_PAGES_URL,
+	getADMIN_CONSOLE_URL as ADMIN_CONSOLE_URL,
+	getADMIN_CONSOLE_URL,
+	getDEVELOPER_PORTAL_URL as DEVELOPER_PORTAL_URL,
+	getDEVELOPER_PORTAL_URL,
+	getEND_USER_PORTAL_URL as END_USER_PORTAL_URL,
+	getEND_USER_PORTAL_URL,
+	getSECURITY_DASHBOARD_URL as SECURITY_DASHBOARD_URL,
+	getSECURITY_DASHBOARD_URL,
+	getSTATUS_PAGE_URL as STATUS_PAGE_URL,
+	getSTATUS_PAGE_URL,
+	getLANDING_SITE_URL as LANDING_SITE_URL,
+	getLANDING_SITE_URL,
+	getAUTHENTICATOR_APP_URL as AUTHENTICATOR_APP_URL,
+	getAUTHENTICATOR_APP_URL,
+	getTRUST_CENTER_URL as TRUST_CENTER_URL,
+	getTRUST_CENTER_URL,
+	getPLATFORM_CONSOLE_URL as PLATFORM_CONSOLE_URL,
+	getPLATFORM_CONSOLE_URL,
+	API_BASE_URL,
+	BASE_PATH,
+	ROUTER_BASENAME,
+	getRouterBasename,
+	VITE_BASE,
+	appPath,
+	navigateTo,
+	crossAppUrl,
+	isValidRedirect,
+	// Portal URL resolver (VITE_PORTAL_CONFIG driven)
+	getRootDomain,
+	getPortalUrl,
+	getAppPortalSlugs,
+} from './config';
+export {
+	SITE_DOMAIN,
+	SITE_EMAIL,
+	SITE_BASE_URL,
+	AUTH_DOMAIN,
+	USER_DOMAIN,
+	APP_DOMAIN,
+	AUTHENTICATOR_DOMAIN,
+	AUTH_BASE_URL,
+	USER_BASE_URL,
+	APP_BASE_URL,
+	AUTHENTICATOR_BASE_URL,
+	DEFAULT_OG_IMAGE,
+	DEFAULT_LOGO,
+} from './config/constants';
+
+// SEO
+export * from './seo';
+
+// Components
+export { RequireAuth } from './components/RequireAuth';
+export { TenantRootRedirect } from './components/TenantRootRedirect';
+export { OAuthCallbackPage } from './components/OAuthCallbackPage';
+export { TenantSlugProvider, useTenantSlug } from './auth/tenant-slug-context';
+export { useTenantSlugFromUrl, extractSlugFromPath, registerNonTenantSegments, clearNonTenantSegments } from './auth/slug-from-url';
+export { useOAuthClientIdFromUrl, fetchOAuthClientIdBySlug } from './auth/oauth-client-from-slug';
+export {
+	useTenantRoute,
+	resolveEffectiveClientId,
+	isSameDomainOAuth,
+} from './auth/tenant-route-middleware';
+export {
+	usePermissionsQuery,
+	useTenantsQuery,
+	useMeQuery,
+	AUTH_DATA_STALE_TIME,
+} from './auth/auth-queries';
+export { authQueryKeys } from './auth/auth-queries';
+export type { TenantRouteResult } from './auth/tenant-route-middleware';
+export {
+	AdminGuard,
+	UserMgmtGuard,
+	SecurityGuard,
+	SecurityAdminGuard,
+	AuditorGuard,
+	PlatformGuard,
+	AuthGuard,
+} from './components/PortalGuard';
+export { AuditStatsOnly } from './components/AuditStatsOnly';
+export { TenantIndexGuard, usePublicTenantSlugs } from './components/TenantIndexGuard';
+export type { TenantIndexGuardProps } from './components/TenantIndexGuard';
+export { buildTenantUrls } from './auth/build-tenant-urls';
+export { resolvePortalBasename } from './config/resolve-basename';
+
+// 生成代码的命名空间再导出（GeneratedApi / ApiGenerated / GeneratedTypes / ApiTypes）。
+// 说明：这 4 行原先指向 @autional/api-generated —— 那是各站逐站副本里用
+// file:../../scripts/generate/api-generated-package 提供的本地包，一旦 shared 走 npm 发布
+// 就必然解析不到（authenticator / security 的 tsc 就是这么炸的：TS2305 has no exported member）。
+// 本包内的 src/generated/* 是同一份生成结果，因此改指包内相对路径；
+// 消费方实际用到的类型面由逐站 tsc 验证。
+export * as GeneratedApi from './generated/api';
+export * as GeneratedTypes from './generated/types';
+export * as ApiGenerated from './generated/api';
+export * as ApiTypes from './generated/types';
+
+// Branding（租户品牌 → CSS 变量 / favicon / customCss）
+export {
+	useBranding,
+	applyBrandColors,
+	BrandingInitializer,
+	useTenantBrandingStore,
+	extractBranding,
+	readCachedBranding,
+	writeCachedBranding,
+	BRANDING_CACHE_PREFIX,
+} from './branding';
+export type { Branding } from './branding';
+
+// Lib
+export { getVapidPublicKey, subscribeBrowserPush, unsubscribeBrowserPush } from './lib/push';
+
+// Utils
+export { urlBase64ToUint8Array } from './utils/browser';
+export { camelCaseKeys, snakeCaseKeys } from './utils/case';
+// 分页/形状单点（H008 收敛口径）：新页面一律经 toPageParams / fromPageResult 适配
+export { toPageParams, fromPageResult } from './utils/page';
+export type { PageParams, PageResult } from './utils/page';
+export { extractApiErrorMessage, extractApiError, createHandleApiError } from './utils/error';
+// 查询状态分类单点（RC-B4-01 / ADR-B4-01）：error/空/无权判定的唯一语义源
+export {
+	classifyQueryState,
+	getHttpStatus,
+	isForbiddenError,
+	isRetryableError,
+	isEmptyData,
+} from './utils/query-state';
+export type { QueryState, QueryStateInput } from './utils/query-state';
+export {
+	extractList,
+	extractItem,
+	extractPagination,
+	extractListResult,
+	fetchList,
+	fetchItem,
+	fetchListResult,
+} from './utils/response';
+export { formatTime, formatDate, formatRelativeTime, setLocaleGetter } from './utils/format';
+export { normalizeViteBase } from './utils/vite';
+export {
+	processPasswordForTransmission,
+	hashPasswordForTransmission,
+} from './utils/password-transmission';
+export type { TransmissionResult } from './utils/password-transmission';
+export type { ExtractedApiError } from './utils/error';
+export type { PaginationInfo, ListResult } from './utils/response';
+// force rebuild 1781616516

package/src/lib/__tests__/push.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('../../generated/api', () => ({
+	pushVapidPublicKey: vi.fn(),
+}));
+
+import { getVapidPublicKey } from '../push';
+import { pushVapidPublicKey } from '../../generated/api';
+
+const mockPushVapidPublicKey = vi.mocked(pushVapidPublicKey);
+
+describe('getVapidPublicKey', () => {
+	// 回归锁（2026-10-05）：响应拦截器（api/client.ts）把 data.public_key 深转为
+	// camelCase，此前此处死读 public_key ⇒ 线上「启用 Push 通知」100% 抛
+	// "Failed to get VAPID public key"（authenticator W4/AU-33 验证腿实证）。
+	it('reads camelCase publicKey（拦截器转换后的形状）', async () => {
+		mockPushVapidPublicKey.mockResolvedValue({ publicKey: 'BPwrXxzEBIzhhbZcFnDb-85' });
+		await expect(getVapidPublicKey()).resolves.toBe('BPwrXxzEBIzhhbZcFnDb-85');
+	});
+
+	it('tolerates snake_case public_key（双键兜底）', async () => {
+		mockPushVapidPublicKey.mockResolvedValue({ public_key: 'snake-key' });
+		await expect(getVapidPublicKey()).resolves.toBe('snake-key');
+	});
+
+	it('throws when payload carries neither key', async () => {
+		mockPushVapidPublicKey.mockResolvedValue({});
+		await expect(getVapidPublicKey()).rejects.toThrow('Failed to get VAPID public key');
+	});
+});

package/src/lib/push.ts

@@ -0,0 +1,44 @@
+import { pushVapidPublicKey } from '../generated/api';
+import { extractItem } from '../utils/response';
+import { urlBase64ToUint8Array } from '../utils/browser';
+
+export async function getVapidPublicKey(): Promise<string> {
+	const res = await pushVapidPublicKey();
+	// 拦截器已把 data.public_key 深转为 camelCase（api/client.ts）；
+	// snake 兜底与本包既有双键读取惯例一致。
+	const data = extractItem(res) as { publicKey?: string; public_key?: string } | null;
+	const key = data?.publicKey ?? data?.public_key;
+	if (!key) {
+		throw new Error('Failed to get VAPID public key');
+	}
+	return key;
+}
+
+export async function subscribeBrowserPush(
+	vapidPublicKey: string,
+): Promise<PushSubscription | null> {
+	if (!('serviceWorker' in navigator) || !('PushManager' in window)) return null;
+	const registration = await navigator.serviceWorker.ready;
+	const existing = await registration.pushManager.getSubscription();
+	if (existing) return existing;
+	try {
+		return await registration.pushManager.subscribe({
+			userVisibleOnly: true,
+			applicationServerKey: urlBase64ToUint8Array(vapidPublicKey),
+		});
+	} catch (err) {
+		console.error('Push subscription failed:', err);
+		return null;
+	}
+}
+
+export async function unsubscribeBrowserPush(): Promise<boolean> {
+	if (!('serviceWorker' in navigator)) return false;
+	const registration = await navigator.serviceWorker.ready;
+	const sub = await registration.pushManager.getSubscription();
+	if (sub) {
+		await sub.unsubscribe();
+		return true;
+	}
+	return false;
+}

package/src/seo/dom-utils.ts

@@ -0,0 +1,94 @@
+export function upsertMeta(
+	attribute: string,
+	value: string,
+	attrName: 'name' | 'property' = 'name',
+): () => void {
+	const selector = `meta[${attrName}="${attribute}"]`;
+	const el = document.querySelector<HTMLMetaElement>(selector);
+	const previous = el?.content;
+
+	if (el) {
+		el.content = value;
+	} else {
+		const meta = document.createElement('meta');
+		meta.setAttribute(attrName, attribute);
+		meta.content = value;
+		document.head.appendChild(meta);
+		return () => {
+			meta.remove();
+		};
+	}
+
+	return () => {
+		if (previous !== undefined) {
+			el.content = previous;
+		}
+	};
+}
+
+export function upsertCanonical(href: string): () => void {
+	let link = document.querySelector<HTMLLinkElement>('link[rel="canonical"]');
+	const previous = link?.href;
+
+	if (link) {
+		link.href = href;
+	} else {
+		link = document.createElement('link');
+		link.rel = 'canonical';
+		link.href = href;
+		document.head.appendChild(link);
+		return () => {
+			link!.remove();
+		};
+	}
+
+	return () => {
+		if (previous !== undefined && link) {
+			link.href = previous;
+		}
+	};
+}
+
+export function upsertLink(
+	rel: string,
+	href: string,
+	extraAttrs?: Record<string, string>,
+): () => void {
+	const selector = `link[rel="${rel}"]${extraAttrs?.hreflang ? `[hreflang="${extraAttrs.hreflang}"]` : ''}`;
+	const existing = document.querySelector<HTMLLinkElement>(selector);
+	const previous = existing?.href;
+
+	if (existing) {
+		existing.href = href;
+		return () => {
+			if (previous !== undefined) {
+				existing.href = previous;
+			}
+		};
+	} else {
+		const link = document.createElement('link');
+		link.rel = rel;
+		link.href = href;
+		if (extraAttrs) {
+			Object.entries(extraAttrs).forEach(([k, v]) => link.setAttribute(k, v));
+		}
+		document.head.appendChild(link);
+		return () => {
+			link.remove();
+		};
+	}
+}
+
+export function injectJSONLD(schemas: object[]): () => void {
+	schemas.forEach((schema, idx) => {
+		const script = document.createElement('script');
+		script.type = 'application/ld+json';
+		script.setAttribute('data-seo-jsonld', String(idx));
+		script.textContent = JSON.stringify(schema);
+		document.head.appendChild(script);
+	});
+
+	return () => {
+		document.querySelectorAll('script[data-seo-jsonld]').forEach((el) => el.remove());
+	};
+}