@mintplayer/ng-spark-auth 22.2.1 → 22.6.0

package/types/mintplayer-ng-spark-auth-models.d.ts

@@ -38,19 +38,9 @@ type SparkAuthRouteEntry = string | {
     path: string;
     component?: Type<unknown>;
 };
-/**
- * How much of the local-credential (email + password) page family to route.
- *
- * Mirrors the server's `SparkLocalCredentials`, and for the same reason it is a mode rather
- * than five independent switches: the pages form a star centred on the login page, and every
- * template dereferences its siblings' paths unconditionally, so removing any proper subset
- * leaves a dangling link. The family is the unit on both tiers.
- */
-type SparkLocalCredentialsMode = 'full' | 'sign-in-only' | 'disabled';
-/** The routable local-credential pages. Kept separate from {@link SparkAuthRouteConfig} so that
- * adding non-route options below cannot widen {@link SparkAuthRoutePaths}. */
+/** The routable authentication pages. */
 interface SparkAuthRouteEntries {
-    /** The provider-button landing page. Routed whenever local credentials are limited. */
+    /** The provider-button landing page, mounted by `withExternalLogin()`. */
     signIn?: SparkAuthRouteEntry;
     login?: SparkAuthRouteEntry;
     twoFactor?: SparkAuthRouteEntry;
@@ -58,21 +48,36 @@ interface SparkAuthRouteEntries {
     forgotPassword?: SparkAuthRouteEntry;
     resetPassword?: SparkAuthRouteEntry;
 }
-interface SparkAuthRouteConfig extends SparkAuthRouteEntries {
-    /**
-     * Defaults to `'full'`, which routes every page — the behaviour of every version before this
-     * option existed. Set it to match the server's `LocalCredentials` mode; `GET /spark/auth/capabilities`
-     * reports what the server is actually running.
-     */
-    localCredentials?: SparkLocalCredentialsMode;
-}
 /**
- * Every path is present regardless of mode. The pages that are dropped are dropped together, so no
- * surviving template can dereference a missing sibling — which is what lets this stay `Required`
- * and keeps the change additive for consumers.
+ * The paths of the pages that were actually mounted.
+ *
+ * Partial, and that is the change: pages are opted into individually now, so a template cannot
+ * assume its siblings exist. `login` links to `register` only when registration was opted into, and
+ * the sign-in landing page links to `login` only when local login was. A `[routerLink]` bound to
+ * `undefined` silently navigates to the current route, so every cross-feature link is guarded.
+ */
+type SparkAuthRoutePaths = Partial<Record<keyof SparkAuthRouteEntries, string>>;
+declare const SPARK_AUTH_ROUTE_PATHS: InjectionToken<Partial<Record<keyof SparkAuthRouteEntries, string>>>;
+/**
+ * Presentation for one external provider's button — an icon, a label, an ordering.
+ *
+ * **It decorates; it does not declare.** The server stays authoritative over which providers exist
+ * (`GET /spark/auth/capabilities`), because letting the client declare them would reintroduce exactly
+ * the string-literal mismatch that endpoint exists to prevent. A scheme the server reports with no
+ * matching declaration falls back to the default button, so adding a provider server-side never
+ * yields a blank page; a declaration matching no reported scheme is simply unused.
  */
-type SparkAuthRoutePaths = Required<Record<keyof SparkAuthRouteEntries, string>>;
-declare const SPARK_AUTH_ROUTE_PATHS: InjectionToken<Required<Record<keyof SparkAuthRouteEntries, string>>>;
+interface SparkExternalProviderPresentation {
+    /** The ASP.NET Core authentication scheme, as the server reports it. Matched case-insensitively. */
+    scheme: string;
+    /** Overrides the server's display name. */
+    displayName?: string;
+    /** A CSS class for an icon element rendered before the label. */
+    iconClass?: string;
+    /** Lower sorts first. Providers with no declared order keep the server's order, after declared ones. */
+    order?: number;
+}
+declare const SPARK_EXTERNAL_PROVIDERS: InjectionToken<SparkExternalProviderPresentation[]>;
 
 /**
  * Shared validator for `returnUrl` query parameters consumed by the auth
@@ -133,5 +138,5 @@ declare const SPARK_EXTERNAL_LOGIN_MESSAGE_TYPE = "spark:external-login";
  */
 declare function resolveSignInUrl(config: SparkAuthConfig, router: Router): string;
 
-export { SPARK_AUTH_CONFIG, SPARK_AUTH_ROUTE_PATHS, SPARK_EXTERNAL_LOGIN_MESSAGE_TYPE, defaultSparkAuthConfig, isSafeReturnUrl, resolveSignInUrl, sanitizeReturnUrl };
-export type { AuthUser, SparkAuthCapabilities, SparkAuthConfig, SparkAuthRouteConfig, SparkAuthRouteEntries, SparkAuthRouteEntry, SparkAuthRoutePaths, SparkExternalLoginError, SparkExternalLoginMessage, SparkExternalLoginMode, SparkExternalLoginOptions, SparkExternalLoginResult, SparkExternalProvider, SparkLocalCredentialsMode };
+export { SPARK_AUTH_CONFIG, SPARK_AUTH_ROUTE_PATHS, SPARK_EXTERNAL_LOGIN_MESSAGE_TYPE, SPARK_EXTERNAL_PROVIDERS, defaultSparkAuthConfig, isSafeReturnUrl, resolveSignInUrl, sanitizeReturnUrl };
+export type { AuthUser, SparkAuthCapabilities, SparkAuthConfig, SparkAuthRouteEntries, SparkAuthRouteEntry, SparkAuthRoutePaths, SparkExternalLoginError, SparkExternalLoginMessage, SparkExternalLoginMode, SparkExternalLoginOptions, SparkExternalLoginResult, SparkExternalProvider, SparkExternalProviderPresentation };

package/types/mintplayer-ng-spark-auth-register.d.ts

@@ -8,7 +8,7 @@ declare class SparkRegisterComponent {
     private readonly authService;
     private readonly router;
     private readonly translation;
-    readonly routePaths: Required<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
+    readonly routePaths: Partial<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
     colors: typeof Color;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly errorMessage: _angular_core.WritableSignal<string>;

package/types/mintplayer-ng-spark-auth-reset-password.d.ts

@@ -10,7 +10,7 @@ declare class SparkResetPasswordComponent implements OnInit {
     private readonly router;
     private readonly route;
     private readonly translation;
-    readonly routePaths: Required<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
+    readonly routePaths: Partial<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
     colors: typeof Color;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly errorMessage: _angular_core.WritableSignal<string>;

package/types/mintplayer-ng-spark-auth-routes.d.ts

@@ -1,20 +1,90 @@
-import { SparkAuthRouteConfig } from '@mintplayer/ng-spark-auth/models';
+import { SparkAuthRoutePaths, SparkExternalProviderPresentation, SparkAuthRouteEntries, SparkAuthRouteEntry } from '@mintplayer/ng-spark-auth/models';
 
+type Loader = () => Promise<any>;
+interface Child {
+    path: string;
+    loadComponent: Loader;
+}
+/**
+ * One opt-in group of authentication pages. Produced by `withLocalLogin()`, `withRegistration()` and
+ * `withExternalLogin()`; not constructible by consumers, which is what keeps the set of mountable
+ * pages a decision this library makes rather than a shape an application can invent.
+ */
+interface SparkAuthRoutesFeature {
+    readonly children: Child[];
+    readonly paths: SparkAuthRoutePaths;
+    readonly providers?: SparkExternalProviderPresentation[];
+}
+/** Path override for the sign-in landing page. Named to stay clear of the core package's
+ * `SparkExternalLoginOptions`, which is about the sign-in *call* rather than the route. */
+type SparkExternalLoginRouteOptions = Pick<SparkAuthRouteEntries, 'signIn'>;
 /**
  * The routes for Spark's authentication pages.
  *
- * `config.localCredentials` chooses how much of the email/password family to route, mirroring the
- * server's `SparkLocalCredentials`. `GET /spark/auth/capabilities` reports what the server is
- * actually running, so the two can be checked against each other.
+ * **Nothing is mounted unless a feature asks for it.** Passing no features emits no pages at all —
+ * opt-in enforced by construction rather than by a flag, matching `provideHttpClient(withFetch())`
+ * and `provideRouter(withComponentInputBinding())`. Before this the pages mounted by default and an
+ * application had to opt *out*, so every app shipped a registration form whether or not it wanted
+ * one.
+ *
+ * ```ts
+ * sparkAuthRoutes(
+ *   withLocalLogin(),
+ *   withRegistration(),
+ *   withExternalLogin(githubProvider(), facebookProvider()),
+ * )
+ * ```
+ *
+ * The `import()` expressions live *inside* each feature. That placement is the point: a bundler
+ * decides whether to emit a lazy chunk from whether the `import()` call site is reachable, not from
+ * whether the route object referencing it survives — so filtering a children array after the fact
+ * would still ship every page. A page nobody opted into has no reachable `import()` at all.
+ */
+declare function sparkAuthRoutes(...features: SparkAuthRoutesFeature[]): any[];
+/**
+ * Mounts the email/password family: login, two-factor, forgot-password, reset-password.
+ *
+ * These four are one feature rather than four because they form a star centred on the login page and
+ * every template dereferences its siblings unconditionally — removing any proper subset leaves a
+ * dangling link. Registration is genuinely separable, and is its own feature.
+ *
+ * Two-factor belongs here because it is reachable only from the login page's `RequiresTwoFactor`
+ * branch and posts to the same `/login` endpoint: it is part of password sign-in, not of
+ * authentication in general.
+ */
+declare function withLocalLogin(entries?: Pick<SparkAuthRouteEntries, 'login' | 'twoFactor' | 'forgotPassword' | 'resetPassword'>): SparkAuthRoutesFeature;
+/**
+ * Mounts the self-service registration page.
+ *
+ * Separate from {@link withLocalLogin} because the two decisions genuinely are separate: an
+ * application whose accounts are provisioned by an administrator still needs password sign-in and
+ * password reset. Mount it only alongside a server whose `SparkLocalCredentials` is `Full` — with
+ * `SignInOnly` the endpoint it posts to is not mapped.
+ */
+declare function withRegistration(entry?: SparkAuthRouteEntry): SparkAuthRoutesFeature;
+/**
+ * Mounts the sign-in landing page — a button per external provider the *server* reports.
+ *
+ * Accepts provider declarations and, in any position, one options object for the page's own path;
+ * the two shapes are disjoint, so `withExternalLogin(githubProvider(), facebookProvider())` and
+ * `withExternalLogin({ signIn: 'landing' }, githubProvider())` both read naturally.
  *
- * The `import()` expressions live *inside* the branches that need them. That placement is the point:
- * a bundler decides whether to emit a lazy chunk from whether the `import()` call site is reachable,
- * not from whether the route object referencing it survives — so filtering the children array after
- * the fact would still ship every page. Excluded pages must have no reachable `import()` at all.
+ * Declaring no providers is valid and useful: the page still renders whatever
+ * `GET /spark/auth/capabilities` reports, using default buttons.
+ */
+declare function withExternalLogin(...providersOrOptions: (SparkExternalProviderPresentation | SparkExternalLoginRouteOptions)[]): SparkAuthRoutesFeature;
+/**
+ * Presentation for one provider's button, keyed by the scheme the server reports.
  *
- * `SPARK_AUTH_ROUTE_PATHS` is still provided in full. The excluded pages are excluded together, so
- * nothing that survives can link to something that does not, and the token stays `Required`.
+ * The generic form. `githubProvider()` and friends are this with a scheme and an icon filled in —
+ * they exist so the common case does not require knowing the scheme string, not because the library
+ * has an opinion about which providers exist.
  */
-declare function sparkAuthRoutes(config?: SparkAuthRouteConfig): any[];
+declare function externalProvider(scheme: string, presentation?: Omit<SparkExternalProviderPresentation, 'scheme'>): SparkExternalProviderPresentation;
+declare function githubProvider(presentation?: Omit<SparkExternalProviderPresentation, 'scheme'>): SparkExternalProviderPresentation;
+declare function googleProvider(presentation?: Omit<SparkExternalProviderPresentation, 'scheme'>): SparkExternalProviderPresentation;
+declare function facebookProvider(presentation?: Omit<SparkExternalProviderPresentation, 'scheme'>): SparkExternalProviderPresentation;
+declare function microsoftProvider(presentation?: Omit<SparkExternalProviderPresentation, 'scheme'>): SparkExternalProviderPresentation;
 
-export { sparkAuthRoutes };
+export { externalProvider, facebookProvider, githubProvider, googleProvider, microsoftProvider, sparkAuthRoutes, withExternalLogin, withLocalLogin, withRegistration };
+export type { SparkAuthRoutesFeature, SparkExternalLoginRouteOptions };

package/types/mintplayer-ng-spark-auth-sign-in.d.ts

@@ -1,25 +1,73 @@
 import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
 import * as _mintplayer_ng_spark_auth_models from '@mintplayer/ng-spark-auth/models';
 import { SparkExternalProvider } from '@mintplayer/ng-spark-auth/models';
 import { Color } from '@mintplayer/ng-bootstrap';
 
 /**
- * The sign-in landing page for an application whose local credentials are turned off — a button per
- * external provider, and a link to the password form when there still is one.
+ * One provider's button, as the template sees it: the provider itself, and the call that signs in
+ * with it.
+ *
+ * **Passing the closure is the point.** A consumer never touches `provider.scheme`, so the failure
+ * this component exists to prevent — a hard-coded scheme string that silently stops matching when
+ * the server's registration changes — is unreachable by construction. It also means busy state,
+ * `returnUrl` handling and popup-versus-redirect can move behind `signIn` later without a
+ * consumer-facing change.
+ */
+interface SparkProviderButtonContext {
+    $implicit: SparkExternalProviderView;
+    signIn: () => void;
+}
+/** A provider the server reported, merged with whatever presentation the app declared for it. */
+interface SparkExternalProviderView extends SparkExternalProvider {
+    iconClass?: string;
+}
+/**
+ * The sign-in landing page: a button per external provider, and a link to the password form when the
+ * application mounted one.
  *
  * The providers come from `GET /spark/auth/capabilities` rather than from a list the application
  * hard-codes. That is the point of the component: every consumer that hand-rolled this before wrote
  * the scheme name as a string literal, which is a silent mismatch waiting to happen the moment the
- * server's provider registration changes.
+ * server's provider registration changes. A `withExternalLogin(githubProvider())` declaration only
+ * *decorates* what the server reports — it cannot conjure a provider the server does not have.
  */
 declare class SparkSignInComponent {
     private readonly authService;
-    readonly routePaths: Required<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
+    private readonly declaredProviders;
+    private readonly route;
+    readonly routePaths: Partial<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
     readonly colors: typeof Color;
-    readonly providers: _angular_core.WritableSignal<SparkExternalProvider[]>;
+    /**
+     * Where to land after a successful external sign-in.
+     *
+     * Falls back to a `?returnUrl=` query parameter, matching what the login page already does — so a
+     * plain `<a routerLink="/sign-in" [queryParams]="{ returnUrl: '/somewhere' }">` works with no
+     * wiring, which is what a routed page needs since the router passes it no inputs. The query value
+     * is validated as a local path before use; an off-site one is dropped rather than followed.
+     */
+    readonly returnUrl: _angular_core.InputSignal<string | undefined>;
+    private effectiveReturnUrl;
+    /**
+     * Replaces the default provider button. Rendered once per provider with a
+     * {@link SparkProviderButtonContext}.
+     *
+     * Reachable only when the consumer *hosts* this component — the router instantiates it with no
+     * projected content, so on a default `withExternalLogin()` route there is nothing to project into.
+     * Host it via `withExternalLogin({ signIn: { path: 'sign-in', component: MySignIn } })` and pass
+     * the template from there.
+     */
+    readonly providerTemplate: _angular_core.InputSignal<TemplateRef<SparkProviderButtonContext> | null>;
+    private readonly reported;
     readonly localCredentialsAvailable: _angular_core.WritableSignal<boolean>;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly failed: _angular_core.WritableSignal<boolean>;
+    /**
+     * The server's list, decorated and ordered by whatever the application declared. Declared-but-not-
+     * reported schemes are dropped and reported-but-not-declared ones keep a default button, so
+     * neither side can produce a provider the other does not have.
+     */
+    readonly providers: _angular_core.Signal<SparkExternalProviderView[]>;
     constructor();
     private load;
     /**
@@ -28,9 +76,12 @@ declare class SparkSignInComponent {
      * which it only does when local credentials are meant to be limited.
      */
     private warnOnMismatch;
-    signInWith(provider: SparkExternalProvider): void;
+    /** The closure handed to a projected template, so a consumer never names a scheme itself. */
+    contextFor(provider: SparkExternalProviderView): SparkProviderButtonContext;
+    signInWith(provider: SparkExternalProviderView): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkSignInComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkSignInComponent, "spark-sign-in", never, {}, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkSignInComponent, "spark-sign-in", never, { "returnUrl": { "alias": "returnUrl"; "required": false; "isSignal": true; }; "providerTemplate": { "alias": "providerTemplate"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 export { SparkSignInComponent };
+export type { SparkExternalProviderView, SparkProviderButtonContext };

package/types/mintplayer-ng-spark-auth-two-factor.d.ts

@@ -10,7 +10,7 @@ declare class SparkTwoFactorComponent {
     private readonly route;
     private readonly config;
     private readonly translation;
-    readonly routePaths: Required<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
+    readonly routePaths: Partial<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
     colors: typeof Color;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly errorMessage: _angular_core.WritableSignal<string>;