@securitydept/client-angular 0.3.0-beta.1 → 0.3.0-beta.10

package/fesm2022/securitydept-client-angular.mjs

@@ -1,521 +1,610 @@
-import * as i0 from '@angular/core';
-import { InjectionToken, makeEnvironmentProviders, inject, Injectable } from '@angular/core';
-import { createPlannerHost, resolveEffectiveClientSet, RequirementsClientSetComposition } from '@securitydept/client/auth-coordination';
-export { resolveEffectiveClientSet } from '@securitydept/client/auth-coordination';
-import { Observable } from 'rxjs';
+import { InjectionToken, makeEnvironmentProviders, inject, DestroyRef, Injector, Optional } from '@angular/core';
+import { Router } from '@angular/router';
+import { createSecuritydeptDestroyRef, SecuritydeptDestroyRef, SecuritydeptInjector, readSecuritydeptRouteMetadata, RouteCompositionRequirementPlanner, PipelineOutcome, injectRequirementPlannerHost, RequirementPlannerHost, ENVIRONMENT_TOKEN, writeSecuritydeptRouteMetadata, provideRequirementPlannerHost, UriReferenceStringSchema, validateTraitInput, throwValidationClientError, RouterNavigationMode, ClientError, ClientErrorKind, UriReferenceString, TransportErrorCode, ClientErrorSource, getSecuritydeptProviderToken, createProviderIfTokenMissing, ROUTER_TRAIT_TOKEN, TRANSPORT_TRAIT_TOKEN, notMissingProvider, SYMBOL_OBSERVABLE } from '@securitydept/client';
+import { HttpErrorResponse, HttpClient } from '@angular/common/http';
+import { createRouterForNativeWeb } from '@securitydept/client/web';
+import { type } from 'arktype';
+import { takeUntil, from, firstValueFrom } from 'rxjs';
+import { toSignal, rxResource } from '@angular/core/rxjs-interop';
 
-// Angular planner-host integration — DI-based planner provider / lookup
+const SECURITYDEPT_INJECTOR = new InjectionToken("SECURITYDEPT_INJECTOR");
+function provideSecuritydept(options = {}) {
+    return makeEnvironmentProviders([
+        {
+            provide: SECURITYDEPT_INJECTOR,
+            useFactory: () => {
+                const parentInjector = inject(SECURITYDEPT_INJECTOR, {
+                    optional: true,
+                    skipSelf: true,
+                }) ?? undefined;
+                const angularDestroyRef = inject(DestroyRef);
+                const securitydeptDestroyRef = options.autoCreateDestroyRef === false
+                    ? null
+                    : createSecuritydeptDestroyRef();
+                if (securitydeptDestroyRef) {
+                    angularDestroyRef.onDestroy(() => securitydeptDestroyRef.dispose());
+                }
+                const providers = [
+                    ...(options.providers ?? []),
+                    ...(securitydeptDestroyRef
+                        ? [
+                            {
+                                provide: SecuritydeptDestroyRef,
+                                useValue: securitydeptDestroyRef,
+                            },
+                        ]
+                        : []),
+                ];
+                return parentInjector
+                    ? SecuritydeptInjector.fromParentInjector(parentInjector, providers)
+                    : SecuritydeptInjector.resolveAndCreate(providers);
+            },
+        },
+    ]);
+}
+
+// Angular route metadata projection
 //
 // Canonical import path:
-//   import { AUTH_PLANNER_HOST, provideAuthPlannerHost, ... } from "@securitydept/client-angular"
+//   import { projectAngularRouteSegments } from "@securitydept/client-angular"
+//
+// Reads serializable auth requirement metadata declared in Angular route
+// `data` and projects a matched route chain (`pathFromRoot`) into the SDK's
+// framework-agnostic `RouteTreeSegment[]`. Composition folding is owned by the
+// `RouteCompositionRequirementPlanner`, so this layer only extracts per-segment
+// declarations.
 //
-// Provides Angular DI glue for the shared planner-host contract:
-//   - InjectionToken for PlannerHost
-//   - Provider helpers for app / module / route scoped planners
-//   - InjectionToken + provider helpers for ScopedRequirementsClientSet
-//   - injectPlannerHost() convenience function with fail-fast
+// Route metadata storage is owned by `@securitydept/client`
+// ({@link readSecuritydeptRouteMetadata} / {@link writeSecuritydeptRouteMetadata}).
 //
 // Architecture boundary:
-//   - Does NOT own the planner-host contract (that lives in @securitydept/client)
-//   - Does NOT carry token-set-specific mapping
-//   - Provides the Angular DI wiring for the shared contract
+//   - Does NOT own auth enforcement, planner logic, or navigation.
+//   - Does NOT carry token-set-specific mapping or policy.
+//   - Framework-specific (Angular Router types) but requirement-system-agnostic.
 //
 // Stability: provisional
-// ---------------------------------------------------------------------------
-// PlannerHost injection token
-// ---------------------------------------------------------------------------
 /**
- * DI token for the shared {@link PlannerHost}.
- *
- * Provide at the app level via {@link provideAuthPlannerHost}.
- * Guards use {@link injectPlannerHost} to look up the nearest instance.
+ * Resolved route `data` for a segment: static `routeConfig.data` merged with
+ * snapshot `data` (snapshot wins on key collision).
  */
-const AUTH_PLANNER_HOST = new InjectionToken("AUTH_PLANNER_HOST");
+function routeDataFromSegment(segment) {
+    return {
+        ...(segment.routeConfig?.data ?? {}),
+        ...segment.data,
+    };
+}
 /**
- * Provide an {@link AUTH_PLANNER_HOST} at the current injector level.
+ * Project the `pathFromRoot` of an `ActivatedRouteSnapshot` into the SDK's
+ * `RouteTreeSegment[]` chain (root -> leaf).
  *
- * Use in app config, route providers, or NgModule providers to establish
- * a planner-host scope. Child routes inherit the nearest parent's planner.
+ * Each segment carries its declared requirements and composition strategy;
+ * inherit/merge/replace folding is applied later by the
+ * `RouteCompositionRequirementPlanner`.
  *
- * @example
- * ```ts
- * // app.config.ts — app-level planner (default sequential strategy)
- * export const appConfig: ApplicationConfig = {
- *   providers: [provideAuthPlannerHost()],
- * };
- *
- * // Feature route — override with custom async chooser strategy
- * {
- *   path: "admin",
- *   providers: [provideAuthPlannerHost({
- *     selectCandidate: async (candidates) => showAdminChooser(candidates),
- *   })],
- *   children: [...]
- * }
- * ```
+ * Segments without a `routeConfig` (e.g. the root) get routeId `"__root__"`;
+ * empty-path segments get `"__index__"`.
  */
-function provideAuthPlannerHost(options) {
-    const plannerOptions = {};
-    if (options?.selectCandidate) {
-        plannerOptions.selectCandidate = options.selectCandidate;
+function projectAngularRouteSegments(leafRoute) {
+    const chain = leafRoute.pathFromRoot ?? [leafRoute];
+    return chain.map((segment) => segmentToTreeNode(segment));
+}
+function segmentToTreeNode(segment) {
+    const metadata = readSecuritydeptRouteMetadata(routeDataFromSegment(segment));
+    const requirements = metadata?.requirements ? [...metadata.requirements] : [];
+    const composition = metadata?.composition;
+    return composition
+        ? { routeId: resolveRouteId(segment), requirements, composition }
+        : { routeId: resolveRouteId(segment), requirements };
+}
+function resolveRouteId(segment) {
+    if (!segment.routeConfig) {
+        return "__root__";
     }
-    return makeEnvironmentProviders([
-        { provide: AUTH_PLANNER_HOST, useValue: createPlannerHost(plannerOptions) },
-    ]);
+    const path = segment.routeConfig.path;
+    if (path === undefined || path === null || path === "") {
+        return "__index__";
+    }
+    return path;
 }
-/**
- * Inject the nearest {@link PlannerHost} from the DI hierarchy.
- *
- * Throws an explicit error if no planner-host is provided, preventing
- * silent fallback behavior.
- *
- * @example
- * ```ts
- * const plannerHost = injectPlannerHost();
- * const result = await plannerHost.evaluate(candidates);
- * ```
- */
-function injectPlannerHost() {
-    const host = inject(AUTH_PLANNER_HOST, { optional: true });
-    if (!host) {
-        throw new Error("[injectPlannerHost] No AUTH_PLANNER_HOST found in the injector hierarchy. " +
-            "Use provideAuthPlannerHost() in your app config or route providers.");
+
+// Angular route guards — bridge to RouteCompositionRequirementPlanner
+//
+// Canonical import path:
+//   import {
+//     createAngularCanActivate,
+//     createAngularCanActivateChild,
+//   } from "@securitydept/client-angular"
+//
+// Produces Angular `CanActivateFn` / `CanActivateChildFn` guards that project
+// the matched route chain into `RouteTreeSegment[]`, run the SDK's
+// `RouteCompositionRequirementPlanner` against the nearest
+// `RequirementPlannerHost` resolved from the current Securitydept injector,
+// and map the pipeline result onto Angular's guard return contract (`true` /
+// `false` / `UrlTree`).
+//
+// Injection-context discipline: DI reads (host, Router) happen synchronously at
+// guard entry, before any `await`. Behaviour that needs DI services should be
+// provided through `provideSecuritydept({ providers: [...] })`, not inline
+// callbacks that call `inject()` here.
+//
+// Architecture boundary:
+//   - Does NOT own behaviour (checkAuthenticated / onUnauthenticated) — that is
+//     resolved through the RequirementPlannerHost chain.
+//   - Does NOT carry token-set-specific mapping or policy.
+//
+// Stability: provisional
+async function runRouteGuard(route, state, host, router) {
+    const segments = projectAngularRouteSegments(route);
+    const planner = RouteCompositionRequirementPlanner.fromRouteSegments(host, segments, { url: state.url });
+    const result = await planner.runUntilSettled();
+    switch (result.outcome) {
+        case PipelineOutcome.Settled:
+            return true;
+        case PipelineOutcome.Blocked:
+            return false;
+        case PipelineOutcome.Redirect:
+            return router.parseUrl(result.location);
     }
-    return host;
 }
-// ---------------------------------------------------------------------------
-// Requirements client set injection token — stores the already-resolved
-// effective options for the current scope (parent + child composed).
-// ---------------------------------------------------------------------------
 /**
- * DI token for the effective requirements client set at the current scope.
- *
- * The value is always the **resolved** options after composing all ancestor
- * scopes — it is NOT the raw `ScopedRequirementsClientSet` declaration.
- *
- * Provide via {@link provideRouteScopedRequirements}.
- * Guards inject this token to get the effective scope requirements and then
- * merge their own declared candidates on top.
+ * Create a `CanActivateFn` bridging the route chain to the requirement
+ * planner pipeline.
  */
-const AUTH_REQUIREMENTS_CLIENT_SET = new InjectionToken("AUTH_REQUIREMENTS_CLIENT_SET");
+function createAngularCanActivate(options) {
+    return (route, state) => {
+        const securitydeptInjector = inject(SECURITYDEPT_INJECTOR, {
+            optional: true,
+        });
+        const parentHost = securitydeptInjector
+            ? injectRequirementPlannerHost({ injector: securitydeptInjector })
+            : null;
+        const host = options?.plannerHost ??
+            (options?.behaviour
+                ? RequirementPlannerHost.fromBehaviour(typeof options.behaviour === "function"
+                    ? options.behaviour()
+                    : options.behaviour, {
+                    parent: parentHost ?? undefined,
+                    environment: securitydeptInjector?.get(ENVIRONMENT_TOKEN, null) ?? undefined,
+                })
+                : parentHost) ??
+            RequirementPlannerHost.fromBehaviour({});
+        const router = inject(Router);
+        return runRouteGuard(route, state, host, router);
+    };
+}
 /**
- * Provide a {@link ScopedRequirementsClientSet} at the current route/module scope.
- *
- * Internally, the provider resolves the effective client set by composing the
- * declared `scopedSet` with the parent scope's already-resolved options
- * (injected via `skipSelf: true`). The token value stored in DI is the
- * resolved `readonly AuthGuardClientOption[]`, not the raw declaration.
- *
- * This mirrors the React `AuthRequirementsClientSetProvider` semantics:
- * each level stores its resolved effective options, so children inherit
- * the composed result without re-resolving the full ancestor chain.
- *
- * The `scopedSet` argument may also be a **factory function** — it will be
- * called inside Angular's `useFactory` context, so `inject()` is valid.
- * Use this when the requirement options need DI-resolved services (e.g. a
- * token-set registry or a redirect service).
- *
- * @example
- * ```ts
- * // routes.ts — static declaration (no DI needed)
- * {
- *   path: "",
- *   providers: [
- *     provideRouteScopedRequirements({
- *       composition: RequirementsClientSetComposition.Replace,
- *       options: [sessionClientOption],
- *     }),
- *   ],
- * }
- *
- * // Feature route merges OIDC on top of the parent's session requirement
- * {
- *   path: "confluence",
- *   providers: [
- *     provideRouteScopedRequirements({
- *       composition: RequirementsClientSetComposition.Merge,
- *       options: [confluenceOidcClientOption],
- *     }),
- *   ],
- *   // Route-level DI scope only. Angular Router adopters should prefer
- *   // secureRouteRoot()/secureRoute() over direct guard wiring.
- * }
- *
- * // Factory form — use when options depend on injected services
- * {
- *   path: "protected",
- *   providers: [
- *     provideRouteScopedRequirements(() => {
- *       const registry = inject(TokenSetAuthRegistry);
- *       const authService = inject(AuthService);
- *       return {
- *         composition: RequirementsClientSetComposition.Replace,
- *         options: [{
- *           requirementId: "oidc",
- *           requirementKind: "frontend_oidc",
- *           checkAuthenticated: () => registry.require(clientKey).isAuthenticated(),
- *           onUnauthenticated: () => { authService.redirectToLogin(clientKey).subscribe(); return false; },
- *         }],
- *       };
- *     }),
- *   ],
- * }
- * ```
+ * Create a `CanActivateChildFn` bridging the child route chain to the
+ * requirement planner pipeline.
  */
-function provideRouteScopedRequirements(scopedSet) {
-    return makeEnvironmentProviders([
-        {
-            provide: AUTH_REQUIREMENTS_CLIENT_SET,
-            useFactory: () => {
-                // Walk up to the nearest parent scope's already-resolved effective set.
-                // skipSelf: true ensures we don't read our own (not-yet-set) value.
-                const parentOptions = inject(AUTH_REQUIREMENTS_CLIENT_SET, {
-                    optional: true,
-                    skipSelf: true,
-                }) ?? [];
-                // Support factory form so callers can use inject() to resolve
-                // DI services (e.g. auth registry, redirect service) inside their
-                // option callbacks without bypassing this helper.
-                const resolved = typeof scopedSet === "function" ? scopedSet() : scopedSet;
-                return resolveEffectiveClientSet(parentOptions, resolved);
-            },
-        },
-    ]);
+function createAngularCanActivateChild(options) {
+    return (childRoute, state) => {
+        const injector = inject(SECURITYDEPT_INJECTOR, {
+            optional: true,
+        });
+        const parentHost = injector
+            ? injectRequirementPlannerHost({ injector })
+            : null;
+        const host = options?.plannerHost ??
+            (options?.behaviour
+                ? RequirementPlannerHost.fromBehaviour(typeof options.behaviour === "function"
+                    ? options.behaviour()
+                    : options.behaviour, {
+                    parent: parentHost ?? undefined,
+                    environment: injector?.get(ENVIRONMENT_TOKEN, null) ?? undefined,
+                })
+                : parentHost) ??
+            RequirementPlannerHost.fromBehaviour({});
+        const router = inject(Router);
+        return runRouteGuard(childRoute, state, host, router);
+    };
 }
 
-// Angular Router route adapter for auth-coordination
+// Angular secure route helpers — declarative route assembly
 //
 // Canonical import path:
-//   import { ... } from "@securitydept/client-angular"
+//   import { secureRoute, secureRouteRoot } from "@securitydept/client-angular"
+//
+// Two composable helpers for wiring auth requirements onto Angular routes:
+//   - secureRoute:     writes requirement metadata into route `data` ONLY.
+//   - secureRouteRoot: writes metadata AND attaches the canActivate /
+//                      canActivateChild guards (and, optionally, a scoped
+//                      RequirementPlannerHost provider).
 //
-// Provides the projection layer between Angular Router's ActivatedRouteSnapshot
-// tree and the SDK's framework-agnostic RouteMatchNode[] contract.
-// Uses real @angular/router types (ActivatedRouteSnapshot) so consuming apps
-// get full type-safety and IDE autocomplete without any casting.
+// The split lets a single guarded root route cover a whole subtree: child
+// segments declare their own requirements via `secureRoute`, and the root's
+// canActivateChild folds the full chain through the planner.
 //
 // Architecture boundary:
-//   - Does NOT own the Angular router, guards, or navigation lifecycle.
-//   - Does NOT re-export core orchestration primitives.
-//   - Does NOT carry token-set-specific mapping or policy.
-//   - The adopter wires this into their guards / resolvers.
+//   - Does NOT own behaviour or token-set-specific policy.
+//   - Delegates enforcement to createAngularCanActivate/Child.
 //
 // Stability: provisional
-/** Default key for auth requirements in Angular route `data`. */
-const DEFAULT_ROUTE_REQUIREMENTS_KEY = "authRequirements";
-// ---------------------------------------------------------------------------
-// Service
-// ---------------------------------------------------------------------------
-/**
- * Angular service that bridges Angular Router's `ActivatedRouteSnapshot` to
- * the SDK's framework-agnostic `RouteMatchNode[]` contract.
- *
- * Inject this into `CanActivateFn` guards or class-based guards.
- *
- * @example
- * ```ts
- * export const authGuard: CanActivateFn = (route) => {
- *   const adapter = inject(AuthRouteAdapter);
- *   const result = adapter.check(route, orchestrator);
- *   if (!result.canActivate && result.pendingRequirement) {
- *     // Trigger auth flow for the pending requirement
- *   }
- *   return result.canActivate;
- * };
- * ```
- */
-class AuthRouteAdapter {
-    /**
-     * Project the `pathFromRoot` of an `ActivatedRouteSnapshot` into the SDK's
-     * `RouteMatchNode[]` chain.
-     *
-     * Route segments without a `routeConfig` (e.g. the root segment) are
-     * assigned routeId `"__root__"`. Segments with a config use the `path`
-     * as their routeId (or `"__index__"` for empty-path segments).
-     */
-    projectRouteMatch(leafRoute, options) {
-        const key = options?.requirementsKey ?? DEFAULT_ROUTE_REQUIREMENTS_KEY;
-        const chain = leafRoute.pathFromRoot ?? [leafRoute];
-        return chain.map((segment) => this.segmentToNode(segment, key));
-    }
-    /**
-     * Project an explicit array of `ActivatedRouteSnapshot` segments into the
-     * SDK's `RouteMatchNode[]` chain.
-     *
-     * Use when you already have a flattened chain (e.g. from
-     * `ActivatedRoute.pathFromRoot`).
-     */
-    projectRouteSegments(segments, options) {
-        const key = options?.requirementsKey ?? DEFAULT_ROUTE_REQUIREMENTS_KEY;
-        return segments.map((segment) => this.segmentToNode(segment, key));
+function writeRequirementData(security, base) {
+    const patch = {};
+    if (security.requirements !== undefined) {
+        patch.requirements = security.requirements;
     }
-    /**
-     * Project the route snapshot and check whether all requirements are settled.
-     *
-     * @param leafRoute - The leaf `ActivatedRouteSnapshot` from the guard call.
-     * @param orchestrator - The SDK orchestrator managing the requirement plan.
-     * @param options - Optional projection options.
-     */
-    check(leafRoute, orchestrator, options) {
-        const chain = this.projectRouteMatch(leafRoute, options);
-        orchestrator.activateMatchedRoutes(chain);
-        const snap = orchestrator.snapshot();
-        return {
-            canActivate: snap.settled,
-            pendingRequirement: snap.pendingRequirement,
-        };
+    if (security.composition !== undefined) {
+        patch.composition = security.composition;
     }
-    segmentToNode(segment, key) {
-        const routeId = this.resolveRouteId(segment);
-        const rawRequirements = segment.data[key] ?? segment.routeConfig?.data?.[key];
-        const requirements = Array.isArray(rawRequirements)
-            ? rawRequirements
-            : [];
-        return { routeId, requirements };
+    if (Object.keys(patch).length === 0) {
+        return { ...(base ?? {}) };
     }
-    resolveRouteId(segment) {
-        if (!segment.routeConfig)
-            return "__root__";
-        const path = segment.routeConfig.path;
-        if (path === undefined || path === null || path === "")
-            return "__index__";
-        return path;
+    return writeSecuritydeptRouteMetadata(base, patch);
+}
+/**
+ * Declare a secure route segment: writes requirement metadata into route
+ * `data` only. No guard is attached — a guarded ancestor (see
+ * {@link secureRouteRoot}) enforces the folded chain.
+ */
+function secureRoute(path, security, routeOptions) {
+    return {
+        ...routeOptions,
+        path,
+        data: writeRequirementData(security, routeOptions?.data),
+    };
+}
+/**
+ * Declare a guarded root route: writes requirement metadata AND attaches
+ * `canActivate` + `canActivateChild` guards bound to the requirement planner.
+ *
+ * When `security.behaviour` is set, a scoped {@link RequirementPlannerHost}
+ * provider is mounted so descendant guards inherit it through DI.
+ */
+function secureRouteRoot(path, security, routeOptions) {
+    const guardOptions = security.plannerHost
+        ? { plannerHost: security.plannerHost }
+        : undefined;
+    const providers = security.behaviour
+        ? [
+            ...(routeOptions?.providers ?? []),
+            provideSecuritydept({
+                providers: [
+                    provideRequirementPlannerHost(security.behaviour),
+                ],
+            }),
+        ]
+        : routeOptions?.providers;
+    const route = {
+        ...routeOptions,
+        path,
+        data: writeRequirementData(security, routeOptions?.data),
+        canActivate: [
+            ...(routeOptions?.canActivate ?? []),
+            createAngularCanActivate(guardOptions),
+        ],
+        canActivateChild: [
+            ...(routeOptions?.canActivateChild ?? []),
+            createAngularCanActivateChild(guardOptions),
+        ],
+    };
+    if (providers) {
+        route.providers = providers;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: AuthRouteAdapter, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: AuthRouteAdapter, providedIn: "root" });
+    return route;
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: AuthRouteAdapter, decorators: [{
-            type: Injectable,
-            args: [{ providedIn: "root" }]
-        }] });
 
-// Angular route metadata requirement helper
+// Angular Router trait adapter
 //
 // Canonical import path:
-//   import { withRouteRequirements, extractFullRouteRequirements, ... } from "@securitydept/client-angular"
+//   import { createRouterForAngular } from "@securitydept/client-angular"
 //
-// Provides the canonical route-metadata layer for Angular Router auth requirement
-// declaration. Requirements are stored in route `data` rather than in DI scope,
-// enabling full-route aggregation guards to collect the complete requirement set
-// from the entire path-from-root chain in a single pass.
+// Projects an Angular `Router` (or any navigation-capable object) onto the
+// framework-agnostic `RouterTrait` (currentUrl + navigate) from
+// `@securitydept/client`. Adopters use this to give SDK primitives a way to
+// read the current URL and start navigations without depending on Angular.
 //
 // Architecture boundary:
-//   - Does NOT own auth enforcement or planner logic.
+//   - Does NOT own the Angular router, guards, or navigation lifecycle.
+//   - Does NOT read auth requirements or run planners (see route-guard.ts).
 //   - Does NOT carry token-set-specific mapping or policy.
-//   - Provides typed helpers for declaring and reading requirements from route data.
-//   - framework-specific (Angular Router types) but requirement-system-agnostic.
-//
-// Relationship to provideRouteScopedRequirements():
-//   - provideRouteScopedRequirements() is a lower-level DI-scope helper.
-//   - This module is the canonical path for Angular Router auth requirement
-//     declaration when full-route aggregation is needed.
-//
-// Key sentinel note:
-//   DEFAULT_ROUTE_REQUIREMENTS_KEY is defined in router.ts (AuthRouteAdapter's
-//   companion constant). ROUTE_REQUIREMENTS_DATA_KEY exported here is its
-//   semantic alias — both hold the same value ("authRequirements").
-//   Adopters may use either name; they are interchangeable.
 //
 // Stability: provisional
-// ---------------------------------------------------------------------------
-// Route data key
-// ---------------------------------------------------------------------------
+const AngularRouterNavigationLikeSchema = type({
+    url: "string?",
+    navigateByUrl: "Function",
+});
+const ResolvedRouterForAngularCreateOptionsSchema = type({
+    router: AngularRouterNavigationLikeSchema,
+    currentUrl: UriReferenceStringSchema.or("null"),
+});
 /**
- * Default key for auth requirements in Angular route `data`.
- *
- * Semantic alias for {@link DEFAULT_ROUTE_REQUIREMENTS_KEY} (defined in
- * `router.ts`). Both hold the same value (`"authRequirements"`).
- * Use either name — they are interchangeable.
- *
- * Set this key in `Route.data` to declare auth requirements for a route segment:
- * ```ts
- * { path: "dashboard", data: withRouteRequirements([{ id: "session", kind: "session" }]) }
- * ```
- *
- * The key is also read by {@link AuthRouteAdapter} when projecting snapshots.
- *
- * @see {@link withRouteRequirements}
- * @see {@link extractFullRouteRequirements}
- */
-const ROUTE_REQUIREMENTS_DATA_KEY = DEFAULT_ROUTE_REQUIREMENTS_KEY;
-/**
- * Default key for the route-level composition strategy in Angular route `data`.
- *
- * Used together with {@link ROUTE_REQUIREMENTS_DATA_KEY}. The default
- * composition is `merge` when the key is omitted.
- */
-const ROUTE_REQUIREMENTS_COMPOSITION_DATA_KEY = "authRequirementsComposition";
-// ---------------------------------------------------------------------------
-// Declaration helper
-// ---------------------------------------------------------------------------
-/**
- * Build an Angular route `data` object declaring auth requirements for a
- * single route segment.
- *
- * Use this as the `data` field in an Angular `Route` config. Nested routes
- * can declare their own requirements; a full-route aggregation guard will
- * walk the entire `pathFromRoot` chain to collect all requirements in one pass.
+ * Create a {@link RouterTrait} backed by an Angular `Router`.
  *
  * @example
  * ```ts
- * // Parent route declares base requirement
- * {
- *   path: "app",
- *   data: withRouteRequirements([{ id: "session", kind: "session" }]),
- *   children: [
- *     // Child route adds an additional requirement
- *     {
- *       path: "admin",
- *       data: withRouteRequirements([{ id: "admin-oidc", kind: "backend_oidc" }]),
- *       canActivate: [createTokenSetRouteAggregationGuard(...)],
- *     },
- *   ],
- * }
+ * const routerTrait = createRouterForAngular({
+ *   router: inject(Router),
+ *   location: window.location,
+ * });
  * ```
- *
- * @param requirements - One or more auth requirements for this route segment.
- * @param extra - Optional additional data properties to merge.
  */
-function withRouteRequirements(requirements, optionsOrExtra, maybeExtra) {
-    const { composition, extra } = normalizeRequirementOptions(optionsOrExtra, maybeExtra);
+function createRouterForAngular(options) {
+    const routerInput = options.router;
+    const resolvedCreateOptions = {
+        router: options.router,
+        get currentUrl() {
+            return Object.hasOwn(options, "currentUrl")
+                ? (options.currentUrl ?? null)
+                : (routerInput?.url ?? null);
+        },
+    };
+    validateTraitInput({
+        value: resolvedCreateOptions,
+        bundledSchema: ResolvedRouterForAngularCreateOptionsSchema,
+        validator: options.validators?.router,
+        onInvalid: (failure) => throwValidationClientError({
+            code: "client_angular.router.invalid_router_options",
+            source: "client-angular",
+            messagePrefix: "createRouterForAngular could not validate routerForAngularCreateOptions",
+            failure,
+        }),
+    });
+    const { router } = resolvedCreateOptions;
+    const nativeWebRouter = createRouterForNativeWeb(projectNativeWebRouterCreateOptions(options));
     return {
-        ...extra,
-        [ROUTE_REQUIREMENTS_DATA_KEY]: requirements,
-        [ROUTE_REQUIREMENTS_COMPOSITION_DATA_KEY]: composition,
+        currentUrl() {
+            const currentUrl = resolvedCreateOptions.currentUrl;
+            return currentUrl == null ? null : UriReferenceString.parse(currentUrl);
+        },
+        async navigate(request) {
+            if (request.mode === RouterNavigationMode.External) {
+                if (!nativeWebRouter) {
+                    throw new ClientError({
+                        kind: ClientErrorKind.Configuration,
+                        code: "client_angular.router.native_web_router_unavailable",
+                        message: "Angular router cannot perform external navigation without a native web router",
+                        source: "client-angular.router",
+                    });
+                }
+                await nativeWebRouter.navigate(request);
+                return;
+            }
+            await router.navigateByUrl(request.url.toString(), {
+                replaceUrl: request.mode === RouterNavigationMode.Replace,
+                state: request.state,
+            });
+        },
     };
 }
-// ---------------------------------------------------------------------------
-// Aggregation helper
-// ---------------------------------------------------------------------------
-/**
- * Extract and flatten auth requirements from a complete Angular route chain.
- *
- * Walks all segments from root to leaf (from `leafRoute.pathFromRoot`)
- * and concatenates the declared {@link AuthRequirement} arrays in order.
- * Requirements from ancestor routes appear before requirements from
- * descendant routes. Duplicate `id` values are NOT de-duplicated here —
- * the caller (guard / enforcement layer) is responsible for deduplication
- * or merge logic.
- *
- * This is the extraction counter-part to {@link withRouteRequirements}.
- * A full-route aggregation guard calls this once and hands the complete
- * flat array to the planner / enforcement layer.
- *
- * @param leafRoute - The leaf `ActivatedRouteSnapshot` from the guard call.
- * @param requirementsKey - Override the route data key (default: `"authRequirements"`).
- */
-function extractFullRouteRequirements(leafRoute, requirementsKey = ROUTE_REQUIREMENTS_DATA_KEY, compositionKey = ROUTE_REQUIREMENTS_COMPOSITION_DATA_KEY) {
-    const chain = leafRoute.pathFromRoot ?? [leafRoute];
-    let result = [];
-    for (const segment of chain) {
-        const raw = segment.data[requirementsKey] ??
-            segment.routeConfig?.data?.[requirementsKey];
-        const composition = readRouteComposition(segment, compositionKey) ??
-            RequirementsClientSetComposition.Merge;
-        const requirements = Array.isArray(raw) ? raw : [];
-        result = resolveEffectiveRequirements(result, {
-            composition,
-            requirements,
-        });
-    }
-    return result;
+function projectNativeWebRouterCreateOptions(options) {
+    return {
+        ...(Object.hasOwn(options, "navigation")
+            ? { navigation: options.navigation }
+            : {}),
+        ...(Object.hasOwn(options, "location")
+            ? { location: options.location }
+            : {}),
+        ...(Object.hasOwn(options, "history") ? { history: options.history } : {}),
+        ...(Object.hasOwn(options, "window") ? { window: options.window } : {}),
+    };
 }
-/**
- * Resolve the effective auth requirements by composing the parent chain with a
- * child route declaration.
- *
- * Composition semantics mirror `resolveEffectiveClientSet()`:
- * - `inherit` keeps the parent requirements unchanged
- * - `merge` appends child requirements and replaces same-id parent entries
- * - `replace` discards the parent chain and uses only the child's requirements
- */
-function resolveEffectiveRequirements(parentRequirements, child) {
-    switch (child.composition) {
-        case RequirementsClientSetComposition.Inherit:
-            return [...parentRequirements];
-        case RequirementsClientSetComposition.Merge: {
-            const merged = new Map();
-            for (const requirement of parentRequirements) {
-                merged.set(requirement.id, requirement);
+
+const BaseTransportForAngularCreateOptionsSchema = type({
+    httpClient: {
+        request: "Function",
+    },
+    baseUrl: "unknown",
+});
+function createBaseTransportForAngular(options) {
+    const resolvedCreateOptions = {
+        httpClient: options.httpClient,
+        baseUrl: options.baseUrl,
+    };
+    validateTraitInput({
+        value: resolvedCreateOptions,
+        bundledSchema: BaseTransportForAngularCreateOptionsSchema,
+        validator: options.validators,
+        onInvalid: (failure) => throwValidationClientError({
+            code: TransportErrorCode.InvalidAngularOptions,
+            source: "client-angular",
+            messagePrefix: "createBaseTransportForAngular could not validate transportForAngularCreateOptions",
+            failure,
+        }),
+    });
+    const { httpClient, baseUrl } = resolvedCreateOptions;
+    return {
+        async execute(request) {
+            const requestUrl = baseUrl
+                ? new URL(request.url, baseUrl).toString()
+                : request.url;
+            const requestOptions = {
+                headers: request.headers,
+                observe: "response",
+                responseType: "text",
+                ...(request.body !== undefined &&
+                    request.method !== "GET" &&
+                    request.method !== "HEAD"
+                    ? {
+                        body: typeof request.body === "string"
+                            ? request.body
+                            : JSON.stringify(request.body),
+                    }
+                    : {}),
+            };
+            try {
+                const responseSource = request.cancellationToken
+                    ? httpClient
+                        .request(request.method, requestUrl, requestOptions)
+                        .pipe(takeUntil(from(request.cancellationToken)))
+                    : httpClient.request(request.method, requestUrl, requestOptions);
+                const response = await firstValueFrom(responseSource);
+                try {
+                    return angularResponseToHttpResponse(response);
+                }
+                catch (error) {
+                    throw new ClientError({
+                        kind: ClientErrorKind.Protocol,
+                        message: "The HTTP response body could not be decoded",
+                        code: TransportErrorCode.ResponseDecodeFailed,
+                        source: ClientErrorSource.Transport,
+                        cause: error,
+                    });
+                }
             }
-            for (const requirement of child.requirements) {
-                merged.set(requirement.id, requirement);
+            catch (error) {
+                if (error instanceof HttpErrorResponse && error.status !== 0) {
+                    try {
+                        return angularErrorResponseToHttpResponse(error);
+                    }
+                    catch (decodeError) {
+                        throw new ClientError({
+                            kind: ClientErrorKind.Protocol,
+                            message: "The HTTP response body could not be decoded",
+                            code: TransportErrorCode.ResponseDecodeFailed,
+                            source: ClientErrorSource.Transport,
+                            cause: decodeError,
+                        });
+                    }
+                }
+                const normalized = normalizeAngularTransportError(request.cancellationToken, error);
+                if (normalized instanceof ClientError) {
+                    throw normalized;
+                }
+                throw new ClientError({
+                    kind: ClientErrorKind.Transport,
+                    message: "The HTTP request could not reach the remote service",
+                    code: TransportErrorCode.RequestFailed,
+                    source: ClientErrorSource.Transport,
+                    retryable: true,
+                    cause: error,
+                });
             }
-            return [...merged.values()];
-        }
-        case RequirementsClientSetComposition.Replace:
-            return [...child.requirements];
-        default: {
-            const _exhaustive = child.composition;
-            throw new Error(`[resolveEffectiveRequirements] Unknown composition: ${_exhaustive}`);
-        }
-    }
+        },
+    };
 }
-function normalizeRequirementOptions(optionsOrExtra, maybeExtra) {
-    if (optionsOrExtra &&
-        ("composition" in optionsOrExtra || "extra" in optionsOrExtra)) {
-        const options = optionsOrExtra;
-        return {
-            composition: options.composition ?? RequirementsClientSetComposition.Merge,
-            extra: maybeExtra ?? options.extra,
-        };
-    }
+function angularResponseToHttpResponse(response) {
+    return {
+        status: response.status,
+        headers: angularHeadersToRecord(response.headers),
+        body: parseAngularResponseBody(response.status, response.headers, response.body),
+    };
+}
+function angularErrorResponseToHttpResponse(error) {
     return {
-        composition: RequirementsClientSetComposition.Merge,
-        extra: optionsOrExtra,
+        status: error.status,
+        headers: angularHeadersToRecord(error.headers),
+        body: parseAngularResponseBody(error.status, error.headers, error.error),
     };
 }
-function readRouteComposition(segment, compositionKey) {
-    const raw = segment.data[compositionKey] ?? segment.routeConfig?.data?.[compositionKey];
-    if (raw === RequirementsClientSetComposition.Inherit ||
-        raw === RequirementsClientSetComposition.Merge ||
-        raw === RequirementsClientSetComposition.Replace) {
-        return raw;
+function angularHeadersToRecord(headers) {
+    const responseHeaders = {};
+    for (const key of headers.keys()) {
+        const value = headers.get(key);
+        if (value !== null) {
+            responseHeaders[key] = value;
+        }
+    }
+    return responseHeaders;
+}
+function parseAngularResponseBody(status, headers, body) {
+    const contentType = headers.get("content-type");
+    if (contentType?.includes("application/json") && typeof body === "string") {
+        return body.length > 0 ? JSON.parse(body) : undefined;
+    }
+    if (status !== 302 && status !== 303 && status !== 301) {
+        return body;
     }
     return undefined;
 }
+function normalizeAngularTransportError(token, error) {
+    if (!token?.isCancellationRequested) {
+        return error;
+    }
+    return token.cancellationError ?? error;
+}
 
-// Angular signal / Observable bridge utilities
-//
-// Canonical import path:
-//   import { bridgeToAngularSignal, signalToObservable } from "@securitydept/client-angular"
-//
-// These utilities convert SDK-native ReadableSignalTrait values to Angular-native
-// primitives (WritableSignal, Observable) so that framework adapter packages
-// can surface reactive state using idiomatic Angular APIs.
-//
-// Owner: @securitydept/client-angular — these are generic framework bridges,
-// not token-set-specific utilities. All Angular adapters (basic-auth, session,
-// token-set, …) should import from here instead of implementing their own.
-//
-// Stability: provisional (framework adapter)
-/**
- * Bridge an SDK `ReadableSignalTrait` to an Angular writable signal.
- *
- * Immediately syncs the current value, then subscribes to future changes.
- *
- * @returns Cleanup function that unsubscribes from the SDK signal.
- */
-function bridgeToAngularSignal(source, target) {
-    target.set(source.get());
-    return source.subscribe(() => {
-        target.set(source.get());
+const ENVIRONMENT = new InjectionToken("ENVIRONMENT");
+const ENVIRONMENT_PROVIDER = new InjectionToken("ENVIRONMENT_PROVIDER");
+function createEnvironmentForAngular(options) {
+    const { createBaseEnvironment, routerForAngularCreateOptions, transportForAngularCreateOptions, injectorForAngularProvider, providers = [], ...baseOptions } = options;
+    const externalProviderTokens = new Set(providers.map((provider) => getSecuritydeptProviderToken(provider)));
+    const angularProviders = [
+        createProviderIfTokenMissing(externalProviderTokens, ROUTER_TRAIT_TOKEN, () => ({
+            provide: ROUTER_TRAIT_TOKEN,
+            useValue: createRouterForAngular(routerForAngularCreateOptions),
+        })),
+        createProviderIfTokenMissing(externalProviderTokens, TRANSPORT_TRAIT_TOKEN, () => ({
+            provide: TRANSPORT_TRAIT_TOKEN,
+            useValue: createBaseTransportForAngular(transportForAngularCreateOptions),
+        })),
+        injectorForAngularProvider
+            ? createProviderIfTokenMissing(externalProviderTokens, Injector, () => ({
+                provide: Injector,
+                useValue: injectorForAngularProvider,
+            }))
+            : null,
+    ].filter(notMissingProvider);
+    return createBaseEnvironment({
+        ...baseOptions,
+        providers: [...angularProviders, ...providers],
     });
 }
-/**
- * Bridge an SDK `ReadableSignalTrait` to an RxJS Observable.
- *
- * The observable emits the current value immediately on subscribe, then
- * emits whenever the SDK signal value changes. Completes on unsubscribe.
- */
-function signalToObservable(source) {
-    return new Observable((subscriber) => {
-        subscriber.next(source.get());
-        const unsubscribe = source.subscribe(() => {
-            subscriber.next(source.get());
-        });
-        return () => unsubscribe();
-    });
+function provideEnvironment(options) {
+    return [
+        {
+            provide: ENVIRONMENT,
+            useFactory: (router, httpClient, injector, destroyRef, providers) => {
+                const { autoCreateDestroyRef, providers: optionProviders, ...environmentOptions } = options;
+                const securitydeptDestroyRef = autoCreateDestroyRef === false
+                    ? null
+                    : createSecuritydeptDestroyRef();
+                if (securitydeptDestroyRef) {
+                    destroyRef.onDestroy(() => securitydeptDestroyRef.dispose());
+                }
+                const environmentProviders = [
+                    ...(optionProviders ?? []),
+                    ...(providers ?? []),
+                    ...(securitydeptDestroyRef
+                        ? [
+                            {
+                                provide: SecuritydeptDestroyRef,
+                                useValue: securitydeptDestroyRef,
+                            },
+                        ]
+                        : []),
+                ];
+                return createEnvironmentForAngular({
+                    ...environmentOptions,
+                    routerForAngularCreateOptions: {
+                        router,
+                        ...environmentOptions.routerForAngularCreateOptions,
+                    },
+                    transportForAngularCreateOptions: {
+                        httpClient,
+                        ...environmentOptions.transportForAngularCreateOptions,
+                    },
+                    injectorForAngularProvider: injector,
+                    providers: environmentProviders,
+                });
+            },
+            deps: [
+                Router,
+                HttpClient,
+                Injector,
+                DestroyRef,
+                [new Optional(), ENVIRONMENT_PROVIDER],
+            ],
+        },
+        {
+            provide: SECURITYDEPT_INJECTOR,
+            useFactory: (environment) => environment.injector,
+            deps: [ENVIRONMENT],
+        },
+    ];
+}
+function provideEnvironmentProvider(provider) {
+    return {
+        provide: ENVIRONMENT_PROVIDER,
+        useValue: provider,
+        multi: true,
+    };
+}
+
+function toNgSignal(source, options) {
+    return toSignal(source[SYMBOL_OBSERVABLE](), options);
 }
+const toNgResource = rxResource;
 
 /*
  * Public API Surface of @securitydept/client-angular
@@ -525,5 +614,5 @@ function signalToObservable(source) {
  * Generated bundle index. Do not edit.
  */
 
-export { AUTH_PLANNER_HOST, AUTH_REQUIREMENTS_CLIENT_SET, AuthRouteAdapter, DEFAULT_ROUTE_REQUIREMENTS_KEY, ROUTE_REQUIREMENTS_COMPOSITION_DATA_KEY, ROUTE_REQUIREMENTS_DATA_KEY, bridgeToAngularSignal, extractFullRouteRequirements, injectPlannerHost, provideAuthPlannerHost, provideRouteScopedRequirements, resolveEffectiveRequirements, signalToObservable, withRouteRequirements };
+export { AngularRouterNavigationLikeSchema, BaseTransportForAngularCreateOptionsSchema, ENVIRONMENT, ENVIRONMENT_PROVIDER, SECURITYDEPT_INJECTOR, createAngularCanActivate, createAngularCanActivateChild, createBaseTransportForAngular, createEnvironmentForAngular, createRouterForAngular, projectAngularRouteSegments, provideEnvironment, provideEnvironmentProvider, provideSecuritydept, routeDataFromSegment, secureRoute, secureRouteRoot, toNgResource, toNgSignal };
 //# sourceMappingURL=securitydept-client-angular.mjs.map