@securitydept/token-set-context-client-angular 0.2.0-beta.1

package/dist/fesm2022/securitydept-token-set-context-client-angular.mjs

@@ -0,0 +1,999 @@
+import { HTTP_INTERCEPTORS } from '@angular/common/http';
+import * as i0 from '@angular/core';
+import { signal, inject, DestroyRef, Injectable, InjectionToken, provideEnvironmentInitializer, Component } from '@angular/core';
+import { createTokenSetAuthRegistry } from '@securitydept/token-set-context-client/registry';
+export { ClientInitializationPriority } from '@securitydept/token-set-context-client/registry';
+import { bridgeToAngularSignal, signalToObservable, AUTH_PLANNER_HOST, extractFullRouteRequirements, withRouteRequirements } from '@securitydept/client-angular';
+import { Router } from '@angular/router';
+import { firstValueFrom, from, switchMap, take } from 'rxjs';
+
+// ============================================================================
+// 5. TokenSetAuthService — per-client service wrapper
+// ============================================================================
+/**
+ * Per-client Angular service that bridges a single OIDC mode client to
+ * Angular signals + RxJS.
+ *
+ * Iteration 110 change: lifecycle teardown is now explicit. Construct with
+ * `new TokenSetAuthService(client, autoRestore)` and call `.dispose()` when
+ * the service owner tears down. The shared registry core handles this
+ * automatically — adopters that wire the service directly (rare) must call
+ * `dispose()` themselves, typically bound to a `DestroyRef.onDestroy`.
+ */
+class TokenSetAuthService {
+    client;
+    /** Current auth snapshot as an Angular signal. */
+    authState;
+    /** Current auth snapshot as an RxJS Observable. */
+    authState$;
+    /** Promise that resolves when initial state restore completes (or null if skipped). */
+    restorePromise;
+    cleanup;
+    disposed = false;
+    constructor(
+    /** The underlying SDK client instance. */
+    client, autoRestore) {
+        this.client = client;
+        this.authState = signal(null, ...(ngDevMode ? [{ debugName: "authState" }] : /* istanbul ignore next */ []));
+        this.cleanup = bridgeToAngularSignal(client.state, this.authState);
+        this.authState$ = signalToObservable(client.state);
+        this.restorePromise = autoRestore ? client.restorePersistedState() : null;
+    }
+    /** Whether the user is currently authenticated. */
+    isAuthenticated() {
+        return this.authState() !== null;
+    }
+    /** Current access token, or null. */
+    accessToken() {
+        return this.authState()?.tokens.accessToken ?? null;
+    }
+    /**
+     * Release all resources owned by this service.
+     *
+     * - Unsubscribes the SDK state bridge
+     * - Calls `client.dispose()`
+     *
+     * Idempotent: subsequent calls are no-ops. Called by the shared registry
+     * at teardown; adopters invoking TokenSetAuthService directly must call
+     * this themselves (typically bound to `DestroyRef.onDestroy`).
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        try {
+            this.cleanup();
+        }
+        catch {
+            // Swallow — best effort.
+        }
+        try {
+            this.client.dispose();
+        }
+        catch {
+            // Swallow — best effort.
+        }
+    }
+}
+
+class TokenSetAuthRegistry {
+    /**
+     * Shared framework-neutral registry core. Angular consumers rarely need
+     * direct access, but this is exposed so adapter-internal helpers
+     * (`CallbackResumeService`, `bearer-interceptor`) can query the core
+     * directly when they don't need Angular-specific behaviour.
+     */
+    core;
+    constructor() {
+        this.core = createTokenSetAuthRegistry({
+            materialize: (client, entry) => new TokenSetAuthService(client, entry.autoRestore ?? true),
+            dispose: (service) => service.dispose(),
+            accessTokenOf: (service) => service.accessToken(),
+        });
+        // Try to bind core.dispose() to the current injection context's
+        // DestroyRef. Registry is typically constructed via DI (where this
+        // always succeeds); pure unit tests instantiate directly and must
+        // call `.dispose()` manually.
+        try {
+            const destroyRef = inject(DestroyRef);
+            destroyRef.onDestroy(() => this.core.dispose());
+        }
+        catch {
+            // Not in an injection context — adopter is expected to call
+            // registry.dispose() manually (or never, for short-lived tests).
+        }
+    }
+    register(entry) {
+        return this.core.register(entry);
+    }
+    /**
+     * Manually dispose the registry. Normally bound to the ambient
+     * `DestroyRef` at construction; call this explicitly when instantiating
+     * the registry outside of an Angular injection context (e.g. in unit
+     * tests).
+     */
+    dispose() {
+        this.core.dispose();
+    }
+    // --------------------------------------------------------------------------
+    // Pass-through API (backwards-compatible with iteration 109 surface)
+    // --------------------------------------------------------------------------
+    isReady(key) {
+        return this.core.isReady(key);
+    }
+    readinessState(key) {
+        return this.core.readinessState(key);
+    }
+    async whenReady(key) {
+        return this.core.whenReady(key);
+    }
+    /**
+     * Preload a lazy client without throwing on rejection. Callers are
+     * expected to attach `.catch` handlers for fire-and-forget usage.
+     */
+    preload(key) {
+        return this.core.preload(key);
+    }
+    /**
+     * Schedule preload for every lazy+not-initialized client using
+     * `requestIdleCallback` / `setTimeout` fallback.
+     */
+    idleWarmup() {
+        return this.core.idleWarmup();
+    }
+    reset(key) {
+        this.core.reset(key);
+    }
+    metaFor(clientKey) {
+        return this.core.metaFor(clientKey);
+    }
+    get(key) {
+        return this.core.get(key);
+    }
+    require(key) {
+        return this.core.require(key);
+    }
+    keys() {
+        return this.core.keys();
+    }
+    entries() {
+        return this.core.entriesSnapshot();
+    }
+    // ---- URL / callback / requirement / provider-family discrimination -----
+    *clientKeyGenForUrl(url) {
+        yield* this.core.clientKeyGenForUrl(url);
+    }
+    *clientKeyGenForCallback(url) {
+        yield* this.core.clientKeyGenForCallback(url);
+    }
+    *clientKeyGenForRequirement(requirementKind) {
+        yield* this.core.clientKeyGenForRequirement(requirementKind);
+    }
+    *clientKeyGenForProviderFamily(providerFamily) {
+        yield* this.core.clientKeyGenForProviderFamily(providerFamily);
+    }
+    clientKeyListForUrl(url) {
+        return this.core.clientKeyListForUrl(url);
+    }
+    clientKeyListForCallback(url) {
+        return this.core.clientKeyListForCallback(url);
+    }
+    clientKeyListForRequirement(requirementKind) {
+        return this.core.clientKeyListForRequirement(requirementKind);
+    }
+    clientKeyListForProviderFamily(providerFamily) {
+        return this.core.clientKeyListForProviderFamily(providerFamily);
+    }
+    clientKeyForUrl(url, selector) {
+        return this.core.clientKeyForUrl(url, selector);
+    }
+    clientKeyForCallback(url, selector) {
+        return this.core.clientKeyForCallback(url, selector);
+    }
+    clientKeyForRequirement(requirementKind, selector) {
+        return this.core.clientKeyForRequirement(requirementKind, selector);
+    }
+    clientKeyForProviderFamily(providerFamily, selector) {
+        return this.core.clientKeyForProviderFamily(providerFamily, selector);
+    }
+    requireForRequirement(requirementKind, selector) {
+        return this.core.requireForRequirement(requirementKind, selector);
+    }
+    requireForProviderFamily(providerFamily, selector) {
+        return this.core.requireForProviderFamily(providerFamily, selector);
+    }
+    *clientKeyGenForFilter(filter) {
+        yield* this.core.clientKeyGenForFilter(filter);
+    }
+    *clientKeyGenForOptions(options) {
+        yield* this.core.clientKeyGenForOptions(options);
+    }
+    clientKeysForOptions(options) {
+        return this.core.clientKeysForOptions(options);
+    }
+    accessToken(key) {
+        return this.core.accessToken(key);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetAuthRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetAuthRegistry });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetAuthRegistry, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+/**
+ * DI token for {@link BearerInterceptorOptions}. Adopters normally configure
+ * options via `provideTokenSetBearerInterceptor({ ... })`; the token is
+ * exported for advanced cases where the options need to be supplied or
+ * overridden separately (for example, in tests).
+ */
+const TOKEN_SET_BEARER_INTERCEPTOR_OPTIONS = new InjectionToken("TOKEN_SET_BEARER_INTERCEPTOR_OPTIONS");
+/**
+ * Angular class-based bearer-token interceptor (`HTTP_INTERCEPTORS` style).
+ *
+ * Selects the correct access token from the multi-client registry by URL
+ * pattern. Behaviour for unmatched URLs is governed by
+ * {@link BearerInterceptorOptions.strictUrlMatch}.
+ *
+ * Prefer the functional version via `createTokenSetBearerInterceptor()` +
+ * `withInterceptors()` when using `provideHttpClient`. Use this class-based
+ * version when you need classic `HTTP_INTERCEPTORS` multi-provider style
+ * (e.g. NgModule apps).
+ *
+ * @example
+ * ```ts
+ * // NgModule providers:
+ * provideTokenSetBearerInterceptor({ strictUrlMatch: true })
+ * ```
+ */
+class TokenSetBearerInterceptor {
+    registry = inject(TokenSetAuthRegistry);
+    options = inject(TOKEN_SET_BEARER_INTERCEPTOR_OPTIONS, { optional: true }) ?? {};
+    intercept(req, next) {
+        const key = this.registry.clientKeyForUrl(req.url);
+        // When a client key matches but the client is still initializing
+        // (async clientFactory not yet resolved), registry.get() returns
+        // undefined. This is an explicit design decision: interceptors do NOT
+        // block the HTTP request waiting for client initialization.
+        // Responsibility for "ensure client is ready before making requests"
+        // belongs to route guards (which use whenReady() to await readiness).
+        // A not-yet-ready client correctly produces no token → request proceeds
+        // without Authorization header.
+        const token = key
+            ? (this.registry.get(key)?.accessToken() ?? null)
+            : this.options.strictUrlMatch
+                ? null
+                : this.registry.accessToken();
+        if (!token) {
+            return next.handle(req);
+        }
+        const authReq = req.clone({
+            setHeaders: { Authorization: `Bearer ${token}` },
+        });
+        return next.handle(authReq);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetBearerInterceptor, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetBearerInterceptor });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetBearerInterceptor, decorators: [{
+            type: Injectable
+        }] });
+/**
+ * Create an `HTTP_INTERCEPTORS` multi-provider entry for bearer token injection.
+ *
+ * Returns a single `Provider` object that registers {@link TokenSetBearerInterceptor}
+ * as a class-based HTTP interceptor. Suitable for NgModule `providers` arrays.
+ *
+ * For functional-interceptor style (standalone apps using `provideHttpClient`),
+ * use `createTokenSetBearerInterceptor()` with `withInterceptors()` instead.
+ *
+ * @example
+ * ```ts
+ * @NgModule({
+ *   providers: [
+ *     provideTokenSetAuth({ clients: [...] }),
+ *     provideTokenSetBearerInterceptor(),     // <— replaces hand-written AuthInterceptor
+ *     provideHttpClient(withInterceptorsFromDi()),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+/**
+ * Create an `HTTP_INTERCEPTORS` multi-provider entry for bearer token injection.
+ *
+ * Returns Angular providers that register {@link TokenSetBearerInterceptor}
+ * as a class-based HTTP interceptor and (optionally) the
+ * {@link BearerInterceptorOptions} that govern its URL-match behaviour.
+ * Suitable for NgModule `providers` arrays.
+ *
+ * For functional-interceptor style (standalone apps using `provideHttpClient`),
+ * use `createTokenSetBearerInterceptor()` with `withInterceptors()` instead.
+ *
+ * @example
+ * ```ts
+ * @NgModule({
+ *   providers: [
+ *     provideTokenSetAuth({ clients: [...] }),
+ *     // Adopters with multiple backends or any third-party HTTP traffic
+ *     // MUST opt into strictUrlMatch to prevent token leakage.
+ *     provideTokenSetBearerInterceptor({ strictUrlMatch: true }),
+ *     provideHttpClient(withInterceptorsFromDi()),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+function provideTokenSetBearerInterceptor(options) {
+    const providers = [
+        {
+            provide: HTTP_INTERCEPTORS,
+            useClass: TokenSetBearerInterceptor,
+            multi: true,
+        },
+    ];
+    if (options) {
+        providers.push({
+            provide: TOKEN_SET_BEARER_INTERCEPTOR_OPTIONS,
+            useValue: options,
+        });
+    }
+    return providers;
+}
+/**
+ * Create an Angular `HttpInterceptorFn` that injects bearer authorization
+ * headers, selecting the correct token from the multi-client registry
+ * based on URL pattern matching.
+ *
+ * If no URL pattern matches, falls back to the first available token
+ * (single-client convenience).
+ *
+ * ## Async client readiness
+ *
+ * The interceptor does **not** block or delay the HTTP request waiting for
+ * an async client to materialize. If a client is still initializing when the
+ * request fires, the request proceeds without an Authorization header.
+ *
+ * This is intentional: blocking HTTP for client initialization would deadlock
+ * apps that make HTTP requests during initialization itself. Route guards
+ * (which use `registry.whenReady()`) are the correct place to enforce
+ * "client must be ready before user reaches this route".
+ *
+ * For NgModule-style apps using `HTTP_INTERCEPTORS`, use
+ * `provideTokenSetBearerInterceptor()` instead.
+ *
+ * @example
+ * ```ts
+ * import { provideHttpClient, withInterceptors } from "@angular/common/http";
+ * import { createTokenSetBearerInterceptor } from "@securitydept/token-set-context-client-angular";
+ *
+ * provideHttpClient(withInterceptors([
+ *   createTokenSetBearerInterceptor(registry),
+ * ]));
+ * ```
+ */
+/**
+ * Create an Angular `HttpInterceptorFn` that injects bearer authorization
+ * headers, selecting the correct token from the multi-client registry
+ * based on URL pattern matching.
+ *
+ * If no URL pattern matches, the unmatched-URL behaviour is governed by
+ * {@link BearerInterceptorOptions.strictUrlMatch}: the default falls back
+ * to `registry.accessToken()` (single-client convenience), while
+ * `strictUrlMatch: true` returns no token, ensuring bearer headers are
+ * never injected for URLs outside the registered patterns.
+ *
+ * ## Async client readiness
+ *
+ * The interceptor does **not** block or delay the HTTP request waiting for
+ * an async client to materialize. If a client is still initializing when the
+ * request fires, the request proceeds without an Authorization header.
+ *
+ * This is intentional: blocking HTTP for client initialization would deadlock
+ * apps that make HTTP requests during initialization itself. Route guards
+ * (which use `registry.whenReady()`) are the correct place to enforce
+ * "client must be ready before user reaches this route".
+ *
+ * For NgModule-style apps using `HTTP_INTERCEPTORS`, use
+ * `provideTokenSetBearerInterceptor()` instead.
+ *
+ * @example
+ * ```ts
+ * import { provideHttpClient, withInterceptors } from "@angular/common/http";
+ * import { createTokenSetBearerInterceptor } from "@securitydept/token-set-context-client-angular";
+ *
+ * provideHttpClient(withInterceptors([
+ *   createTokenSetBearerInterceptor(registry, { strictUrlMatch: true }),
+ * ]));
+ * ```
+ */
+function createTokenSetBearerInterceptor(registry, options = {}) {
+    return (req, next) => {
+        // Try URL-pattern-based client selection first.
+        const key = registry.clientKeyForUrl(req.url);
+        // Explicit not-yet-ready semantics: if the client exists in metadata
+        // (via clientKeyForUrl) but registry.get() returns undefined because the
+        // async clientFactory has not resolved yet, the request proceeds without
+        // a token. See class-based interceptor above for full rationale.
+        const token = key
+            ? (registry.get(key)?.accessToken() ?? null)
+            : options.strictUrlMatch
+                ? null
+                : registry.accessToken();
+        if (!token) {
+            return next(req);
+        }
+        const authReq = req.clone({
+            setHeaders: { Authorization: `Bearer ${token}` },
+        });
+        return next(authReq);
+    };
+}
+
+/**
+ * Angular-native service for handling OIDC redirect callbacks,
+ * with multi-client discrimination support.
+ *
+ * The post-authentication redirect URI is propagated automatically through
+ * the core client's pending state (set via `loginWithRedirect({ postAuthRedirectUri })`
+ * and recovered in `handleCallback()`). No manual URL storage is required.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * export class AuthCallbackComponent {
+ *   private readonly callbackService = inject(CallbackResumeService);
+ *   private readonly router = inject(Router);
+ *
+ *   async ngOnInit() {
+ *     const result = await this.callbackService.handleCallback(
+ *       window.location.href,
+ *     );
+ *     this.router.navigateByUrl(result.resumeUrl, { replaceUrl: true });
+ *   }
+ * }
+ * ```
+ */
+class CallbackResumeService {
+    registry = inject(TokenSetAuthRegistry);
+    /**
+     * Check whether a URL is an OIDC authorization callback for any registered
+     * client in this registry.
+     *
+     * This is a convenience wrapper over `clientKeyForCallback()`. Use it for
+     * programmatic early-exit guards (e.g. in a service constructor) before
+     * calling `handleCallback()`.
+     *
+     * @param url - The full URL to check (e.g. `window.location.href`).
+     * @returns `true` when the URL matches a registered callback path and
+     *   contains an `code` or `error` query parameter.
+     */
+    isCallback(url) {
+        return this.registry.clientKeyForCallback(url) !== undefined;
+    }
+    /**
+     * Handle the OIDC callback, auto-detecting which client the callback
+     * belongs to via registered callback paths.
+     *
+     * The `resumeUrl` in the result is taken directly from the core client's
+     * pending state (`postAuthRedirectUri` set at `loginWithRedirect()` time),
+     * falling back to `"/"` when no redirect URI was recorded.
+     *
+     * @param callbackUrl - The full current URL (e.g. `window.location.href`).
+     * @param explicitClientKey - Optional: force-select a client key instead of
+     *   auto-detecting from registered callback paths.
+     */
+    async handleCallback(callbackUrl, explicitClientKey) {
+        // Determine which client this callback is for.
+        const clientKey = explicitClientKey ?? this.registry.clientKeyForCallback(callbackUrl);
+        if (!clientKey) {
+            throw new Error(`[CallbackResumeService] Cannot determine which client this callback belongs to. ` +
+                `URL: ${callbackUrl}. Register callbackPath in the client entry.`);
+        }
+        // Use whenReady() — not require() — so that if the client's async
+        // clientFactory is still in-flight when the callback page first loads,
+        // we wait for it to materialize rather than throwing.
+        const service = await this.registry.whenReady(clientKey);
+        const result = await service.client.handleCallback(callbackUrl);
+        // postAuthRedirectUri is recovered from the core client's pending state,
+        // which was stored by authorizeUrl() when loginWithRedirect() was called.
+        return {
+            clientKey,
+            snapshot: result.snapshot,
+            resumeUrl: result.postAuthRedirectUri ?? "/",
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: CallbackResumeService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: CallbackResumeService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: CallbackResumeService, decorators: [{
+            type: Injectable
+        }] });
+
+// ============================================================================
+// 8. Callback helper — OIDC redirect callback with multi-client discrimination
+// ============================================================================
+/**
+ * Check whether the current URL is an OIDC authorization callback.
+ */
+function isOidcCallback(options) {
+    try {
+        const url = new URL(options.currentUrl);
+        const callbackUrl = new URL(options.callbackPath, url.origin);
+        return (url.pathname === callbackUrl.pathname &&
+            (url.searchParams.has("code") || url.searchParams.has("error")));
+    }
+    catch {
+        return false;
+    }
+}
+
+/** InjectionToken for the multi-client auth registry. */
+const TOKEN_SET_AUTH_REGISTRY = new InjectionToken("TOKEN_SET_AUTH_REGISTRY");
+
+/**
+ * Create Angular providers for the multi-client token-set auth integration.
+ *
+ * Registers all services into Angular DI so adopters can directly inject
+ * `TokenSetAuthRegistry`, `CallbackResumeService`, and look up individual
+ * `TokenSetAuthService` instances by key.
+ *
+ * ## Async client initialization
+ *
+ * When a client's `clientFactory` returns a `Promise` (e.g. because it
+ * needs to fetch a config projection from a backend endpoint), the
+ * registry tracks its initialization state automatically. Guards and
+ * interceptors should use `registry.whenReady(key)` to await
+ * materialization before accessing the service.
+ *
+ * @example
+ * ```ts
+ * import { provideTokenSetAuth } from "@securitydept/token-set-context-client-angular";
+ * import { resolveConfigProjection, networkConfigSource, createFrontendOidcModeClient }
+ *   from "@securitydept/token-set-context-client/frontend-oidc-mode";
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideTokenSetAuth({
+ *       clients: [
+ *         {
+ *           key: "main",
+ *           // Async clientFactory: fetches config projection from backend
+ *           clientFactory: async () => {
+ *             const resolved = await resolveConfigProjection([
+ *               networkConfigSource({
+ *                 apiEndpoint: "https://api.example.com/api",
+ *                 redirectUri: `${location.origin}/auth/callback`,
+ *               }),
+ *             ]);
+ *             return createFrontendOidcModeClient(resolved.config, runtime);
+ *           },
+ *           urlPatterns: ["/api/"],
+ *           callbackPath: "/auth/callback",
+ *         },
+ *       ],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+function provideTokenSetAuth(options) {
+    return [
+        // Registry is a singleton — all clients share one registry.
+        {
+            provide: TokenSetAuthRegistry,
+            useFactory: () => new TokenSetAuthRegistry(),
+        },
+        // Eagerly register all client entries during environment initialization.
+        // provideEnvironmentInitializer runs in injection context, so inject() works.
+        // Note: async clientFactories create promises that the registry tracks;
+        // the initializer does not block Angular bootstrap on them (guards/interceptors
+        // use registry.whenReady() instead).
+        provideEnvironmentInitializer(() => {
+            const registry = inject(TokenSetAuthRegistry);
+            for (const entry of options.clients) {
+                registry.register(entry);
+            }
+            if (options.idleWarmup !== false) {
+                // Kick off idle-time preload for any lazy clients. The cancel
+                // handle is intentionally discarded — teardown happens through
+                // the registry's own DestroyRef binding at dispose time.
+                registry.idleWarmup();
+            }
+        }),
+        // Token for direct registry access.
+        {
+            provide: TOKEN_SET_AUTH_REGISTRY,
+            useExisting: TokenSetAuthRegistry,
+        },
+        // Callback resume service.
+        CallbackResumeService,
+    ];
+}
+
+// ---------------------------------------------------------------------------
+// Guard factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an Angular `CanActivateFn` that performs full-route requirement
+ * aggregation and single-pass planner evaluation.
+ *
+ * **Canonical Angular Router auth pattern** (route-metadata driven):
+ * 1. Requirements are declared in route `data` using `withRouteRequirements()`.
+ * 2. When the guard runs, it walks `route.pathFromRoot` to collect ALL
+ *    requirements from every ancestor segment in a single pass.
+ * 3. Each requirement's `kind` is mapped to one or more registry clients,
+ *    unless overridden by a `requirementPolicies[id].selector`.
+ * 4. The complete candidate set is handed to the `PlannerHost` for a
+ *    single `evaluate()` call — the planner selects the first unresolved
+ *    requirement and calls the matching handler.
+ *
+ * **Handler resolution order** (most specific wins):
+ * 1. `requirementPolicies[requirement.id].onUnauthenticated`
+ * 2. `requirementHandlers[requirement.kind]`
+ * 3. `defaultOnUnauthenticated`
+ * 4. Block navigation (`false`) if none of the above is provided.
+ *
+ * **Client resolution order** for a requirement:
+ * 1. `requirementPolicies[requirement.id].selector.clientKey` — single explicit key
+ * 2. `requirementPolicies[requirement.id].selector.query` — composite query
+ * 3. `registry.clientKeyListForRequirement(requirement.kind)` — default mapping
+ *
+ * This model enables:
+ *   - One-pass requirement collection (no per-segment DI scope accumulation)
+ *   - One-call planner evaluation (chooser sees the full set at once)
+ *   - One redirect decision (no per-segment guard coordination needed)
+ *   - Fine-grained per-requirement policy via `requirementPolicies`
+ *
+ * @example
+ * ```ts
+ * // routes.ts — declare requirements in route data
+ * import { withRouteRequirements } from "@securitydept/client-angular";
+ * import { createTokenSetRouteAggregationGuard } from "@securitydept/token-set-context-client-angular";
+ *
+ * // Simple — kind-level handler
+ * const guard = createTokenSetRouteAggregationGuard({
+ *   requirementHandlers: {
+ *     frontend_oidc: (_failing, _req) => {
+ *       inject(AuthService).redirectToLogin("confluence").subscribe();
+ *       return false;
+ *     },
+ *   },
+ * });
+ *
+ * // Fine-grained — per-requirement policy
+ * const guard = createTokenSetRouteAggregationGuard({
+ *   requirementPolicies: {
+ *     "confluence-oidc": {
+ *       selector: { clientKey: "confluence" },
+ *       onUnauthenticated: () => "/auth/confluence",
+ *     },
+ *     "admin-oidc": {
+ *       selector: { query: { providerFamily: "internal-sso" } },
+ *       onUnauthenticated: (failing) => "/auth/admin",
+ *     },
+ *   },
+ * });
+ *
+ * export const routes: Routes = [
+ *   {
+ *     path: "",
+ *     data: withRouteRequirements([{ id: "session", kind: "session" }]),
+ *     children: [
+ *       {
+ *         path: "confluence",
+ *         data: withRouteRequirements([{ id: "confluence-oidc", kind: "frontend_oidc" }]),
+ *         canActivate: [guard],
+ *       },
+ *     ],
+ *   },
+ * ];
+ * ```
+ */
+function createTokenSetRouteAggregationGuard(options = {}) {
+    return async (route, state) => {
+        const registry = inject(TokenSetAuthRegistry);
+        const router = inject(Router);
+        // ── Resolve planner-host ────────────────────────────────────────────
+        const plannerHost = options.plannerHostResolver?.(route, state) ??
+            options.plannerHost ??
+            inject(AUTH_PLANNER_HOST, { optional: true });
+        if (!plannerHost) {
+            throw new Error("[createTokenSetRouteAggregationGuard] No PlannerHost found. " +
+                "Provide AUTH_PLANNER_HOST via provideAuthPlannerHost() " +
+                "in your app/route providers, or pass plannerHost inline.");
+        }
+        // ── Step 1: Full-route requirement aggregation ───────────────────────
+        const allRequirements = extractFullRouteRequirements(route, options.requirementsKey);
+        if (allRequirements.length === 0) {
+            return true;
+        }
+        const resolvedRequirements = [];
+        for (const req of allRequirements) {
+            const policy = options.requirementPolicies?.[req.id];
+            let clientKeys;
+            if (policy?.selector) {
+                // Policy provides an explicit selector — use it instead of kind mapping.
+                if (policy.selector.clientKey !== undefined) {
+                    clientKeys = [policy.selector.clientKey];
+                }
+                else {
+                    clientKeys = registry.clientKeysForOptions(policy.selector.query);
+                }
+            }
+            else {
+                // Default: resolve by requirement kind.
+                clientKeys = registry.clientKeyListForRequirement(req.kind);
+            }
+            if (clientKeys.length === 0) {
+                // No client for this requirement — skip (lets non-token-set requirements
+                // coexist in the same route chain without breaking the guard).
+                continue;
+            }
+            const entries = await Promise.all(clientKeys.map(async (key) => ({
+                // Use whenReady() — not require() — so that if the client's
+                // async clientFactory is still in-flight when the guard first
+                // fires, we block here until it materializes rather than
+                // crashing or silently bypassing auth.
+                service: await registry.whenReady(key),
+                clientKey: key,
+                meta: registry.metaFor(key),
+            })));
+            resolvedRequirements.push({ requirement: req, entries });
+        }
+        if (resolvedRequirements.length === 0) {
+            return true;
+        }
+        // ── Step 3: Build planner candidates ────────────────────────────────
+        // De-duplicate by requirementId (last declaration for the same id wins).
+        const seenIds = new Map();
+        for (const r of resolvedRequirements) {
+            seenIds.set(r.requirement.id, r);
+        }
+        const deduped = [...seenIds.values()];
+        const candidates = deduped.map((r) => ({
+            requirementId: r.requirement.id,
+            requirementKind: r.requirement.kind,
+            label: r.requirement.label,
+            attributes: r.requirement.attributes,
+            checkAuthenticated: () => r.entries.every(({ service }) => service.isAuthenticated()),
+            onUnauthenticated: () => {
+                const failing = r.entries.filter(({ service }) => !service.isAuthenticated());
+                // Handler resolution: policy > kind handler > default
+                const handler = options.requirementPolicies?.[r.requirement.id]?.onUnauthenticated ??
+                    options.requirementHandlers?.[r.requirement.kind] ??
+                    options.defaultOnUnauthenticated;
+                if (!handler)
+                    return false;
+                const result = handler(failing, r.requirement);
+                if (typeof result === "string")
+                    return result;
+                if (typeof result === "boolean")
+                    return result;
+                return result.toString();
+            },
+            _resolved: r,
+        }));
+        // ── Step 4: Single planner evaluation ───────────────────────────────
+        const decide = async () => {
+            const result = await plannerHost.evaluate(candidates);
+            if (result.allAuthenticated)
+                return true;
+            if (result.pendingCandidate) {
+                const candidate = result.pendingCandidate;
+                const failing = candidate._resolved.entries.filter(({ service }) => !service.isAuthenticated());
+                // Handler resolution: policy > kind handler > default
+                const handler = options.requirementPolicies?.[candidate._resolved.requirement.id]
+                    ?.onUnauthenticated ??
+                    options.requirementHandlers?.[candidate._resolved.requirement.kind] ??
+                    options.defaultOnUnauthenticated;
+                if (!handler)
+                    return false;
+                const action = await handler(failing, candidate._resolved.requirement);
+                if (typeof action === "string")
+                    return router.parseUrl(action);
+                if (typeof action === "boolean")
+                    return action;
+                return action;
+            }
+            return false;
+        };
+        // ── Restore-aware: wait for all pending restores ─────────────────────
+        const pendingRestores = deduped
+            .flatMap((r) => r.entries)
+            .map(({ service }) => service.restorePromise)
+            .filter((p) => p !== null);
+        if (pendingRestores.length === 0) {
+            return decide();
+        }
+        // await the restore-phase Observable before running planner evaluation
+        // so the async guard always returns a Promise, not an Observable.
+        return firstValueFrom(from(Promise.all(pendingRestores)).pipe(switchMap(() => from(decide())), take(1)));
+    };
+}
+
+/**
+ * Route data key for choosing a planner-host registered at the route root.
+ */
+const TOKEN_SET_ROUTE_PLANNER_HOST_KEY_DATA_KEY = "tokenSetPlannerHostKey";
+/**
+ * Build a secured child route declaration.
+ *
+ * The returned route contains only serializable metadata:
+ * requirements, composition strategy, planner-host lookup key, and any extra
+ * route data the caller provides.
+ */
+function secureRoute(path, securityOptions = {}, routeOptions = {}) {
+    const data = withRouteRequirements(securityOptions.requirements ?? [], {
+        composition: securityOptions.composition,
+        extra: {
+            ...(routeOptions.data ?? {}),
+            ...(securityOptions.plannerHostKey
+                ? {
+                    [TOKEN_SET_ROUTE_PLANNER_HOST_KEY_DATA_KEY]: securityOptions.plannerHostKey,
+                }
+                : {}),
+        },
+    });
+    return {
+        ...routeOptions,
+        path,
+        data,
+    };
+}
+/**
+ * Build a secured route-tree root.
+ *
+ * This is the canonical Angular adopter entry for token-set route security:
+ * root-level runtime policy stays here, child routes use {@link secureRoute}
+ * for serializable declarations only.
+ */
+function secureRouteRoot(path, securityOptions = {}, routeOptions = {}) {
+    const canActivate = createTokenSetRouteAggregationGuard({
+        requirementPolicies: securityOptions.requirementPolicies,
+        requirementHandlers: securityOptions.requirementHandlers,
+        defaultOnUnauthenticated: securityOptions.defaultOnUnauthenticated,
+        requirementsKey: securityOptions.requirementsKey,
+        plannerHostResolver: (route, state) => resolvePlannerHostForRoute(route, state, securityOptions),
+    });
+    const canActivateChild = createCanActivateChildAdapter(canActivate);
+    const baseRoute = secureRoute(path, securityOptions, routeOptions);
+    return {
+        ...baseRoute,
+        canActivate: [canActivate, ...(routeOptions.canActivate ?? [])],
+        canActivateChild: [
+            canActivateChild,
+            ...(routeOptions.canActivateChild ?? []),
+        ],
+    };
+}
+/**
+ * Alias with a token-set-specific name for callers who prefer explicit imports.
+ */
+const secureTokenSetRoute = secureRoute;
+/**
+ * Alias with a token-set-specific name for callers who prefer explicit imports.
+ */
+const secureTokenSetRouteRoot = secureRouteRoot;
+function createCanActivateChildAdapter(canActivate) {
+    return (childRoute, state) => canActivate(childRoute, state);
+}
+function resolvePlannerHostForRoute(route, _state, securityOptions) {
+    const plannerHostKey = findNearestPlannerHostKey(route) ?? securityOptions.defaultPlannerHostKey;
+    if (plannerHostKey) {
+        const resolved = securityOptions.plannerHosts?.[plannerHostKey];
+        if (!resolved) {
+            throw new Error(`[secureRouteRoot] No planner host registered for key "${plannerHostKey}"`);
+        }
+        return resolved;
+    }
+    return undefined;
+}
+function findNearestPlannerHostKey(route) {
+    const chain = route.pathFromRoot ?? [route];
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const segment = chain[index];
+        if (!segment)
+            continue;
+        const raw = segment.data[TOKEN_SET_ROUTE_PLANNER_HOST_KEY_DATA_KEY] ??
+            segment.routeConfig?.data?.[TOKEN_SET_ROUTE_PLANNER_HOST_KEY_DATA_KEY];
+        if (typeof raw === "string" && raw.length > 0) {
+            return raw;
+        }
+    }
+    return undefined;
+}
+
+// ============================================================================
+// 9. TokenSetCallbackComponent — drop-in standalone callback route component
+// ============================================================================
+/**
+ * Drop-in standalone Angular component for OIDC redirect callback routes.
+ *
+ * Handles the full callback lifecycle on initialization:
+ *   1. Calls `CallbackResumeService.handleCallback()` with the current URL.
+ *   2. Navigates to `result.resumeUrl` (the post-auth redirect set at login time).
+ *   3. On error: logs and falls back to navigating to `"/"`.
+ *
+ * Register as a route component — no additional glue needed:
+ * ```ts
+ * import { TokenSetCallbackComponent } from "@securitydept/token-set-context-client-angular";
+ *
+ * export const routes: Routes = [
+ *   { path: "auth/callback", component: TokenSetCallbackComponent },
+ * ];
+ * ```
+ *
+ * For custom error handling or UI, subclass this component or build your own
+ * using `CallbackResumeService` directly.
+ */
+class TokenSetCallbackComponent {
+    callbackService = inject(CallbackResumeService);
+    router = inject(Router);
+    ngOnInit() {
+        const currentUrl = window.location.href;
+        if (!this.callbackService.isCallback(currentUrl)) {
+            // Not a callback URL — navigate home to avoid processing errors.
+            this.router.navigateByUrl("/", { replaceUrl: true });
+            return;
+        }
+        this.callbackService
+            .handleCallback(currentUrl)
+            .then((result) => {
+            this.router.navigateByUrl(result.resumeUrl, { replaceUrl: true });
+        })
+            .catch((error) => {
+            console.error("[TokenSetCallbackComponent] Callback handling failed:", error);
+            this.router.navigateByUrl("/", { replaceUrl: true });
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetCallbackComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.8", type: TokenSetCallbackComponent, isStandalone: true, selector: "token-set-callback", ngImport: i0, template: "", isInline: true });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: TokenSetCallbackComponent, decorators: [{
+            type: Component,
+            args: [{
+                    selector: "token-set-callback",
+                    standalone: true,
+                    template: "",
+                }]
+        }] });
+
+// Angular integration family for @securitydept/token-set-context-client
+//
+// Canonical import path:
+//   import { ... } from "@securitydept/token-set-context-client-angular"
+//
+// Multi-client-first Angular-native adapter surface:
+//   - Keyed client registration via provideTokenSetAuth()
+//   - Multi-client lookup via TokenSetAuthRegistry
+//   - Per-client TokenSetAuthService with signal + RxJS bridge
+//   - Multi-client bearer interceptor (functional + class-based)
+//   - provideTokenSetBearerInterceptor() for NgModule HTTP_INTERCEPTORS setup
+//   - OIDC callback resume with client key discrimination
+//   - CallbackResumeService.isCallback() for programmatic callback detection
+//   - TokenSetCallbackComponent standalone component (drop-in callback route)
+//   - Requirement/provider-family → client key mapping
+//   - secureRouteRoot() / secureRoute() — canonical Angular Router route-security
+//     builders: keep non-serializable runtime policy at the root, let child
+//     routes declare serializable requirement metadata only, and wire both
+//     canActivate + canActivateChild to the full-route aggregation guard.
+//   - createTokenSetRouteAggregationGuard() — lower-level advanced guard for
+//     direct route-tree evaluation when adopters intentionally bypass the route
+//     builder helpers.
+//   - Signal/Observable bridge utilities live in @securitydept/client-angular
+//
+// Built by ng-packagr (APF / FESM2022). Decorators are fully supported.
+//
+// Stability: provisional (framework adapter)
+
+/*
+ * Public API Surface of @securitydept/token-set-context-client-angular
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { CallbackResumeService, TOKEN_SET_AUTH_REGISTRY, TOKEN_SET_BEARER_INTERCEPTOR_OPTIONS, TOKEN_SET_ROUTE_PLANNER_HOST_KEY_DATA_KEY, TokenSetAuthRegistry, TokenSetAuthService, TokenSetBearerInterceptor, TokenSetCallbackComponent, createTokenSetBearerInterceptor, createTokenSetRouteAggregationGuard, isOidcCallback, provideTokenSetAuth, provideTokenSetBearerInterceptor, secureRoute, secureRouteRoot, secureTokenSetRoute, secureTokenSetRouteRoot };
+//# sourceMappingURL=securitydept-token-set-context-client-angular.mjs.map