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

package/dist/types/securitydept-token-set-context-client-angular.d.ts

@@ -0,0 +1,838 @@
+import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent } from '@angular/common/http';
+import * as i0 from '@angular/core';
+import { WritableSignal, InjectionToken, Provider, EnvironmentProviders, OnInit } from '@angular/core';
+import { Observable } from 'rxjs';
+import { ClientReadinessState } from '@securitydept/token-set-context-client/frontend-oidc-mode';
+import { OidcModeClient, OidcCallbackClient, TokenSetClientEntry as TokenSetClientEntry$1, ClientInitializationPriority, TokenSetAuthRegistry as TokenSetAuthRegistry$1, ClientMeta, ClientKeySelector, ClientFilter, ClientQueryOptions } from '@securitydept/token-set-context-client/registry';
+export { ClientFilter, ClientInitializationPriority, ClientKeySelector, ClientMeta, ClientQueryOptions, OidcCallbackClient, OidcModeClient } from '@securitydept/token-set-context-client/registry';
+import { AuthSnapshot } from '@securitydept/token-set-context-client/orchestration';
+import { UrlTree, ActivatedRouteSnapshot, RouterStateSnapshot, CanActivateFn, Route } from '@angular/router';
+import { AuthRequirement, PlannerHost, RequirementsClientSetComposition } from '@securitydept/client/auth-coordination';
+
+type TokenSetAngularClient = OidcModeClient & OidcCallbackClient;
+/**
+ * A registration entry for a single token-set auth client.
+ *
+ * Each client is identified by a unique string key (e.g. "main", "admin",
+ * the provider ID, or the requirement kind), so that routes, interceptors,
+ * and callbacks can discriminate between multiple concurrent auth sources.
+ *
+ * ## Sync vs Async client factory
+ *
+ * `clientFactory` supports both synchronous and asynchronous materialization:
+ *
+ * - **Sync** (`() => OidcModeClient`): The client config is available at
+ *   registration time. Classic inline config or pre-resolved projections.
+ *
+ * - **Async** (`() => Promise<OidcModeClient>`): The client config must be
+ *   resolved asynchronously (e.g. fetched from a backend config projection
+ *   endpoint). The registry tracks readiness state and provides `whenReady()`
+ *   for guards/interceptors that need to wait.
+ *
+ * When `clientFactory` returns a Promise, the registry enters
+ * `ClientReadinessState.Initializing` for this key and transitions to
+ * `Ready` or `Failed` when the promise settles.
+ *
+ * Two additional discrimination axes are supported:
+ *   - `requirementKind`: maps a RequirementKind (or custom string) → this client.
+ *     Guards and resolvers can look up the client for a pending requirement without
+ *     knowing the concrete key.
+ *   - `providerFamily`: maps a named provider family (e.g. "google", "internal-sso")
+ *     → this client. Useful when multiple clients share the same kind but differ
+ *     by provider / audience.
+ */
+interface TokenSetClientEntry extends Omit<TokenSetClientEntry$1<TokenSetAngularClient>, "clientFactory"> {
+    /**
+     * Factory that creates the OIDC mode client.
+     *
+     * May return the client synchronously (inline config) or a Promise
+     * (async config projection resolution). When a Promise is returned,
+     * the registry tracks initialization readiness automatically.
+     */
+    clientFactory: () => TokenSetAngularClient | Promise<TokenSetAngularClient>;
+    /**
+     * Initialization priority. Defaults to `"primary"` (eager). Set to
+     * `"lazy"` to defer clientFactory execution until the registry is asked
+     * for this key via `whenReady(key)` / `preload(key)` / `idleWarmup()`.
+     */
+    priority?: ClientInitializationPriority;
+}
+
+/**
+ * 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`.
+ */
+declare class TokenSetAuthService {
+    /** The underlying SDK client instance. */
+    readonly client: TokenSetAngularClient;
+    /** Current auth snapshot as an Angular signal. */
+    readonly authState: WritableSignal<AuthSnapshot | null>;
+    /** Current auth snapshot as an RxJS Observable. */
+    readonly authState$: Observable<AuthSnapshot | null>;
+    /** Promise that resolves when initial state restore completes (or null if skipped). */
+    readonly restorePromise: Promise<AuthSnapshot | null> | null;
+    private readonly cleanup;
+    private disposed;
+    constructor(
+    /** The underlying SDK client instance. */
+    client: TokenSetAngularClient, autoRestore: boolean);
+    /** Whether the user is currently authenticated. */
+    isAuthenticated(): boolean;
+    /** Current access token, or null. */
+    accessToken(): string | 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(): void;
+}
+
+type AngularClient = TokenSetAngularClient;
+declare 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.
+     */
+    readonly core: TokenSetAuthRegistry$1<AngularClient, TokenSetAuthService>;
+    constructor();
+    /**
+     * Register a client entry. Supports sync / async / lazy priority.
+     *
+     * Iteration 110 change: the second `destroyRef` argument is no longer
+     * required — the registry pulls its own `DestroyRef` via injection and
+     * binds teardown once per Angular scope.
+     */
+    register(entry: TokenSetClientEntry & {
+        priority?: "primary" | "lazy";
+        clientFactory: () => AngularClient;
+    }): TokenSetAuthService;
+    register(entry: TokenSetClientEntry & {
+        priority?: "primary" | "lazy";
+        clientFactory: () => Promise<AngularClient>;
+    }): Promise<TokenSetAuthService>;
+    register(entry: TokenSetClientEntry): TokenSetAuthService | Promise<TokenSetAuthService> | undefined;
+    /**
+     * 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(): void;
+    isReady(key: string): boolean;
+    readinessState(key: string): ClientReadinessState;
+    whenReady(key: string): Promise<TokenSetAuthService>;
+    /**
+     * Preload a lazy client without throwing on rejection. Callers are
+     * expected to attach `.catch` handlers for fire-and-forget usage.
+     */
+    preload(key: string): Promise<TokenSetAuthService>;
+    /**
+     * Schedule preload for every lazy+not-initialized client using
+     * `requestIdleCallback` / `setTimeout` fallback.
+     */
+    idleWarmup(): () => void;
+    reset(key: string): void;
+    metaFor(clientKey: string): ClientMeta | undefined;
+    get(key: string): TokenSetAuthService | undefined;
+    require(key: string): TokenSetAuthService;
+    keys(): string[];
+    entries(): Array<[string, TokenSetAuthService]>;
+    clientKeyGenForUrl(url: string): Generator<string, void, unknown>;
+    clientKeyGenForCallback(url: string): Generator<string, void, unknown>;
+    clientKeyGenForRequirement(requirementKind: string): Generator<string, void, unknown>;
+    clientKeyGenForProviderFamily(providerFamily: string): Generator<string, void, unknown>;
+    clientKeyListForUrl(url: string): string[];
+    clientKeyListForCallback(url: string): string[];
+    clientKeyListForRequirement(requirementKind: string): string[];
+    clientKeyListForProviderFamily(providerFamily: string): string[];
+    clientKeyForUrl(url: string, selector?: ClientKeySelector): string | undefined;
+    clientKeyForCallback(url: string, selector?: ClientKeySelector): string | undefined;
+    clientKeyForRequirement(requirementKind: string, selector?: ClientKeySelector): string | undefined;
+    clientKeyForProviderFamily(providerFamily: string, selector?: ClientKeySelector): string | undefined;
+    requireForRequirement(requirementKind: string, selector?: ClientKeySelector): TokenSetAuthService;
+    requireForProviderFamily(providerFamily: string, selector?: ClientKeySelector): TokenSetAuthService;
+    clientKeyGenForFilter(filter: ClientFilter): Generator<string, void, unknown>;
+    clientKeyGenForOptions(options: ClientQueryOptions): Generator<string, void, unknown>;
+    clientKeysForOptions(options: ClientQueryOptions): string[];
+    accessToken(key?: string): string | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TokenSetAuthRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<TokenSetAuthRegistry>;
+}
+
+/**
+ * Adopter-tunable behaviour for the token-set bearer interceptor.
+ *
+ * Iteration 150 (review 1) lifted `strictUrlMatch` out of the implicit
+ * single-client convenience path into an explicit option, so multi-backend
+ * adopters can guarantee that bearer tokens never leak outside the URL
+ * patterns they registered with `provideTokenSetAuth({ clients: [...] })`.
+ */
+interface BearerInterceptorOptions {
+    /**
+     * When `true`, the interceptor injects a bearer header ONLY for requests
+     * whose URL matches a registered client's `urlPatterns`. Requests with no
+     * matching client receive no `Authorization` header even when a token is
+     * available elsewhere in the registry.
+     *
+     * When `false` (default, single-client convenience), the interceptor
+     * falls back to `registry.accessToken()` for unmatched URLs — useful only
+     * when the host issues all HTTP traffic to one already-known backend.
+     *
+     * Adopters with more than one backend, more than one OIDC audience, or
+     * any third-party HTTP traffic from the same Angular host MUST set this
+     * to `true` to prevent cross-origin token leakage.
+     *
+     * @default false
+     */
+    strictUrlMatch?: boolean;
+}
+/**
+ * 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).
+ */
+declare const TOKEN_SET_BEARER_INTERCEPTOR_OPTIONS: InjectionToken<BearerInterceptorOptions>;
+/**
+ * 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 })
+ * ```
+ */
+declare class TokenSetBearerInterceptor implements HttpInterceptor {
+    private readonly registry;
+    private readonly options;
+    intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TokenSetBearerInterceptor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<TokenSetBearerInterceptor>;
+}
+/**
+ * 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 {}
+ * ```
+ */
+declare function provideTokenSetBearerInterceptor(options?: BearerInterceptorOptions): Provider[];
+/**
+ * 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 }),
+ * ]));
+ * ```
+ */
+declare function createTokenSetBearerInterceptor(registry: TokenSetAuthRegistry, options?: BearerInterceptorOptions): (req: {
+    url: string;
+    clone(update: {
+        setHeaders?: Record<string, string>;
+    }): unknown;
+}, next: (req: unknown) => Observable<unknown>) => Observable<unknown>;
+
+/**
+ * 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 });
+ *   }
+ * }
+ * ```
+ */
+declare class CallbackResumeService {
+    private readonly registry;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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.
+     */
+    handleCallback(callbackUrl: string, explicitClientKey?: string): Promise<{
+        clientKey: string;
+        snapshot: AuthSnapshot;
+        /** The URL to navigate to after a successful callback. */
+        resumeUrl: string;
+    }>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CallbackResumeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CallbackResumeService>;
+}
+
+/**
+ * A failing entry returned to `onUnauthenticated` when one or more clients
+ * could not be verified as authenticated.
+ */
+interface UnauthenticatedEntry {
+    /** The unauthenticated `TokenSetAuthService`. */
+    readonly service: TokenSetAuthService;
+    /** The client key for this service. */
+    readonly clientKey: string;
+    /** Full client metadata (urlPatterns, callbackPath, requirementKind, providerFamily). */
+    readonly meta: ClientMeta;
+}
+
+/**
+ * Check whether the current URL is an OIDC authorization callback.
+ */
+declare function isOidcCallback(options: {
+    currentUrl: string;
+    callbackPath: string;
+}): boolean;
+
+/**
+ * Options for {@link provideTokenSetAuth}.
+ */
+interface ProvideTokenSetAuthOptions {
+    /**
+     * Adapter/host registration entries.
+     *
+     * Each entry must have a unique `key`. The entry itself owns how one client
+     * composes auth-context config and runtime capabilities; Angular DI here only
+     * owns host registration, readiness wiring, and lifecycle.
+     */
+    clients: TokenSetClientEntry[];
+    /**
+     * When true (default), schedule `registry.idleWarmup()` during Angular
+     * environment initialization so `priority: "lazy"` clients get
+     * preloaded in the browser's idle callback.
+     *
+     * Disable for tests that want deterministic, manual materialization
+     * control.
+     *
+     * @default true
+     */
+    idleWarmup?: boolean;
+}
+/**
+ * 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",
+ *         },
+ *       ],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideTokenSetAuth(options: ProvideTokenSetAuthOptions): (Provider | EnvironmentProviders)[];
+
+/**
+ * How to select a token-set client from the registry for a specific requirement.
+ *
+ * Choose exactly one:
+ * - `clientKey` — direct key lookup (explicit, single client)
+ * - `query` — composite filter query ({@link ClientQueryOptions})
+ */
+type TokenSetClientSelector = {
+    clientKey: string;
+    query?: never;
+} | {
+    clientKey?: never;
+    query: ClientQueryOptions;
+};
+/**
+ * Policy override for a specific requirement ID in
+ * {@link CreateTokenSetRouteAggregationGuardOptions.requirementPolicies}.
+ *
+ * Allows fine-grained control per declared requirement:
+ * - `selector` overrides the default kind→client registry lookup (use when
+ *   you need a specific client key or a query instead of all clients of that kind).
+ * - `onUnauthenticated` overrides both `requirementHandlers[kind]` and
+ *   `defaultOnUnauthenticated` for this exact requirement.
+ *
+ * @example
+ * ```ts
+ * createTokenSetRouteAggregationGuard({
+ *   requirementPolicies: {
+ *     "confluence-oidc": {
+ *       selector: { clientKey: "confluence" },
+ *       onUnauthenticated: (failing, req) => {
+ *         inject(AuthService).redirectToLogin("confluence").subscribe();
+ *         return false;
+ *       },
+ *     },
+ *     "admin-oidc": {
+ *       selector: { query: { providerFamily: "internal-sso" } },
+ *       onUnauthenticated: () => "/admin/login",
+ *     },
+ *   },
+ * })
+ * ```
+ */
+interface TokenSetRequirementPolicy {
+    /**
+     * Override the default kind→client registry lookup for this requirement.
+     *
+     * When omitted, the guard resolves clients via
+     * `registry.clientKeyListForRequirement(requirement.kind)`.
+     */
+    selector?: TokenSetClientSelector;
+    /**
+     * Handler called when this requirement is selected as pending by the planner.
+     *
+     * Takes precedence over `requirementHandlers[kind]` and
+     * `defaultOnUnauthenticated`.
+     *
+     * Return:
+     *   - `true`  — allow navigation
+     *   - `false` — block navigation
+     *   - `string` — redirect URL path
+     *   - `UrlTree` — Angular router tree
+     */
+    onUnauthenticated: (unauthenticated: ReadonlyArray<UnauthenticatedEntry>, requirement: AuthRequirement) => boolean | string | UrlTree;
+}
+/**
+ * Options for {@link createTokenSetRouteAggregationGuard}.
+ */
+interface CreateTokenSetRouteAggregationGuardOptions {
+    /**
+     * Per-requirement-id policies.
+     *
+     * Keys are `AuthRequirement.id` strings (not kind). Policies declared here
+     * take precedence over {@link requirementHandlers} and
+     * {@link defaultOnUnauthenticated}.
+     *
+     * Use this for fine-grained control:
+     * - override client selection (specific key or composite query)
+     * - per-requirement redirect behaviour
+     * - multi-client / providerFamily selection per requirement
+     *
+     * @example
+     * ```ts
+     * createTokenSetRouteAggregationGuard({
+     *   requirementPolicies: {
+     *     "confluence-oidc": {
+     *       selector: { clientKey: "confluence" },
+     *       onUnauthenticated: () => "/auth/confluence",
+     *     },
+     *     "admin-oidc": {
+     *       selector: { query: { providerFamily: "internal-sso" } },
+     *       onUnauthenticated: () => "/auth/admin",
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    requirementPolicies?: Record<string, TokenSetRequirementPolicy>;
+    /**
+     * Per-requirement-kind handlers.
+     *
+     * When the planner selects a pending requirement whose `kind` maps to an
+     * entry here (and no `requirementPolicies[id]` is set), that handler is
+     * called instead of `defaultOnUnauthenticated`.
+     *
+     * Keys are `AuthRequirement.kind` strings.
+     *
+     * @example
+     * ```ts
+     * createTokenSetRouteAggregationGuard({
+     *   requirementHandlers: {
+     *     frontend_oidc: (failing, req) => {
+     *       inject(AuthService).redirectToLogin(failing[0].clientKey).subscribe();
+     *       return false;
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    requirementHandlers?: Record<string, (unauthenticated: ReadonlyArray<UnauthenticatedEntry>, requirement: AuthRequirement) => boolean | string | UrlTree>;
+    /**
+     * Fallback handler used when no `requirementPolicies[id]` or
+     * `requirementHandlers[kind]` is found for the pending requirement.
+     */
+    defaultOnUnauthenticated?: (unauthenticated: ReadonlyArray<UnauthenticatedEntry>, requirement: AuthRequirement) => boolean | string | UrlTree;
+    /**
+     * Custom route data key for reading requirements from route segments.
+     * @default "authRequirements"
+     */
+    requirementsKey?: string;
+    /**
+     * Inline planner-host instance. If provided, used instead of injecting
+     * `AUTH_PLANNER_HOST` from Angular DI.
+     */
+    plannerHost?: PlannerHost;
+    /**
+     * Resolve the planner-host for the current target route chain.
+     *
+     * Use this when planner-host selection depends on route metadata or other
+     * route-tree state. Takes precedence over `plannerHost` and DI lookup.
+     */
+    plannerHostResolver?: (route: ActivatedRouteSnapshot, state: RouterStateSnapshot) => PlannerHost | undefined;
+}
+/**
+ * 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],
+ *       },
+ *     ],
+ *   },
+ * ];
+ * ```
+ */
+declare function createTokenSetRouteAggregationGuard(options?: CreateTokenSetRouteAggregationGuardOptions): CanActivateFn;
+
+/**
+ * Route data key for choosing a planner-host registered at the route root.
+ */
+declare const TOKEN_SET_ROUTE_PLANNER_HOST_KEY_DATA_KEY = "tokenSetPlannerHostKey";
+/**
+ * Serializable route-level security declaration.
+ *
+ * This object is safe to embed in Angular route metadata. Non-serializable
+ * runtime policy (planner host instances, callbacks, chooser implementations)
+ * belongs in {@link SecureRouteRootSecurityOptions}.
+ */
+interface SecureRouteSecurityOptions {
+    /**
+     * Requirements declared at this route segment.
+     * @default []
+     */
+    requirements?: AuthRequirement[];
+    /**
+     * How this segment composes with ancestor route requirements.
+     * @default merge
+     */
+    composition?: RequirementsClientSetComposition;
+    /**
+     * Serializable lookup key for a planner-host provided by the root route.
+     *
+     * The nearest declared key on the active route chain wins.
+     */
+    plannerHostKey?: string;
+}
+/**
+ * Root-level runtime policy for a secured route tree.
+ *
+ * Everything here is intentionally non-serializable and lives outside route
+ * metadata. Child `secureRoute()` calls only reference these policies by
+ * serializable keys / requirement ids.
+ */
+interface SecureRouteRootSecurityOptions extends SecureRouteSecurityOptions, Omit<CreateTokenSetRouteAggregationGuardOptions, "plannerHost" | "plannerHostResolver"> {
+    /**
+     * Named planner-host instances available to the secured route tree.
+     */
+    plannerHosts?: Record<string, PlannerHost>;
+    /**
+     * Fallback planner-host key when no route segment declares one.
+     */
+    defaultPlannerHostKey?: string;
+}
+type SecureRouteOptions = Omit<Route, "path" | "data"> & {
+    data?: Record<string, unknown>;
+};
+/**
+ * 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.
+ */
+declare function secureRoute(path: string, securityOptions?: SecureRouteSecurityOptions, routeOptions?: SecureRouteOptions): Route;
+/**
+ * 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.
+ */
+declare function secureRouteRoot(path: string, securityOptions?: SecureRouteRootSecurityOptions, routeOptions?: SecureRouteOptions): Route;
+/**
+ * Alias with a token-set-specific name for callers who prefer explicit imports.
+ */
+declare const secureTokenSetRoute: typeof secureRoute;
+/**
+ * Alias with a token-set-specific name for callers who prefer explicit imports.
+ */
+declare const secureTokenSetRouteRoot: typeof secureRouteRoot;
+
+/**
+ * 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.
+ */
+declare class TokenSetCallbackComponent implements OnInit {
+    private readonly callbackService;
+    private readonly router;
+    ngOnInit(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TokenSetCallbackComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<TokenSetCallbackComponent, "token-set-callback", never, {}, {}, never, never, true, never>;
+}
+
+/** InjectionToken for the multi-client auth registry. */
+declare const TOKEN_SET_AUTH_REGISTRY: InjectionToken<TokenSetAuthRegistry>;
+
+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 };
+export type { BearerInterceptorOptions, CreateTokenSetRouteAggregationGuardOptions, ProvideTokenSetAuthOptions, SecureRouteRootSecurityOptions, SecureRouteSecurityOptions, TokenSetAngularClient, TokenSetClientEntry, TokenSetClientSelector, TokenSetRequirementPolicy, UnauthenticatedEntry };
+//# sourceMappingURL=securitydept-token-set-context-client-angular.d.ts.map