@mintplayer/ng-spark-auth 22.0.1 → 22.2.0

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

@@ -1,4 +1,5 @@
 import { InjectionToken, Type } from '@angular/core';
+import { Router } from '@angular/router';
 
 interface AuthUser {
     isAuthenticated: boolean;
@@ -15,19 +16,63 @@ interface SparkAuthConfig {
 declare const SPARK_AUTH_CONFIG: InjectionToken<SparkAuthConfig>;
 declare const defaultSparkAuthConfig: SparkAuthConfig;
 
+/** An external provider a user can actually click, as reported by the server. */
+interface SparkExternalProvider {
+    scheme: string;
+    displayName: string;
+}
+/**
+ * What `GET /spark/auth/capabilities` reports: how much of the local-credential surface this
+ * application mounts, and which external providers are registered.
+ *
+ * This exists so the two tiers cannot silently disagree. The route config is a build-time choice
+ * and the server's mode is a deployment-time one; without a channel between them, a mismatch shows
+ * up as a form that posts into a 404, or a sign-in page with no way to sign in.
+ */
+interface SparkAuthCapabilities {
+    localCredentials: 'Full' | 'SignInOnly' | 'Disabled';
+    externalProviders: SparkExternalProvider[];
+}
+
 type SparkAuthRouteEntry = string | {
     path: string;
     component?: Type<unknown>;
 };
-interface SparkAuthRouteConfig {
+/**
+ * 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}. */
+interface SparkAuthRouteEntries {
+    /** The provider-button landing page. Routed whenever local credentials are limited. */
+    signIn?: SparkAuthRouteEntry;
     login?: SparkAuthRouteEntry;
     twoFactor?: SparkAuthRouteEntry;
     register?: SparkAuthRouteEntry;
     forgotPassword?: SparkAuthRouteEntry;
     resetPassword?: SparkAuthRouteEntry;
 }
-type SparkAuthRoutePaths = Required<Record<keyof SparkAuthRouteConfig, string>>;
-declare const SPARK_AUTH_ROUTE_PATHS: InjectionToken<Required<Record<keyof SparkAuthRouteConfig, string>>>;
+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.
+ */
+type SparkAuthRoutePaths = Required<Record<keyof SparkAuthRouteEntries, string>>;
+declare const SPARK_AUTH_ROUTE_PATHS: InjectionToken<Required<Record<keyof SparkAuthRouteEntries, string>>>;
 
 /**
  * Shared validator for `returnUrl` query parameters consumed by the auth
@@ -47,5 +92,46 @@ declare const SPARK_AUTH_ROUTE_PATHS: InjectionToken<Required<Record<keyof Spark
 declare function isSafeReturnUrl(value: string | null | undefined): boolean;
 declare function sanitizeReturnUrl(value: string | null | undefined, defaultUrl: string): string;
 
-export { SPARK_AUTH_CONFIG, SPARK_AUTH_ROUTE_PATHS, defaultSparkAuthConfig, isSafeReturnUrl, sanitizeReturnUrl };
-export type { AuthUser, SparkAuthConfig, SparkAuthRouteConfig, SparkAuthRouteEntry, SparkAuthRoutePaths };
+/** How the user is sent to the external provider, and how the result comes back. */
+type SparkExternalLoginMode = 'popup' | 'redirect';
+interface SparkExternalLoginOptions {
+    /** Where to land after a successful sign-in. Server-side sanitized to an in-app path. */
+    returnUrl?: string;
+    /** Defaults to `'popup'`. */
+    mode?: SparkExternalLoginMode;
+}
+/**
+ * Why an external login did not sign anyone in. The three `no_login_info` /
+ * `email_not_verified` / `account_creation_failed` codes come from the server; the two
+ * `popup_*` codes are raised here, because the browser is the only place that can observe
+ * them. Deliberately coarse — never enough to tell "no such account" from anything else.
+ */
+type SparkExternalLoginError = 'no_login_info' | 'email_not_verified' | 'account_creation_failed' | 'popup_blocked' | 'popup_closed';
+interface SparkExternalLoginResult {
+    success: boolean;
+    error?: SparkExternalLoginError;
+}
+/** The message the callback page posts back to the window that opened it. */
+interface SparkExternalLoginMessage {
+    type: 'spark:external-login';
+    success: boolean;
+    error?: SparkExternalLoginError;
+}
+declare const SPARK_EXTERNAL_LOGIN_MESSAGE_TYPE = "spark:external-login";
+
+/**
+ * Where to send someone who is not signed in.
+ *
+ * `loginUrl` is the single source of truth for this, and the only thing the guard, the interceptor
+ * and the auth bar should consult — an application that turns off local credentials points it at
+ * its own sign-in landing route.
+ *
+ * The reason this is a function rather than a property read is the failure mode it closes: nothing
+ * connects `loginUrl` to the routes that actually exist, so pointing it at a route that was never
+ * registered produces a redirect into a blank page with no type error, no build failure and no
+ * runtime error. In development that now warns, once, naming the value and the fix.
+ */
+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 };

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.SparkAuthRouteConfig, string>>;
+    readonly routePaths: Required<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.SparkAuthRouteConfig, string>>;
+    readonly routePaths: Required<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,5 +1,20 @@
 import { SparkAuthRouteConfig } from '@mintplayer/ng-spark-auth/models';
 
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * `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`.
+ */
 declare function sparkAuthRoutes(config?: SparkAuthRouteConfig): any[];
 
 export { sparkAuthRoutes };

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

@@ -0,0 +1,36 @@
+import * as _angular_core 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.
+ *
+ * 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.
+ */
+declare class SparkSignInComponent {
+    private readonly authService;
+    readonly routePaths: Required<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
+    readonly colors: typeof Color;
+    readonly providers: _angular_core.WritableSignal<SparkExternalProvider[]>;
+    readonly localCredentialsAvailable: _angular_core.WritableSignal<boolean>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly failed: _angular_core.WritableSignal<boolean>;
+    constructor();
+    private load;
+    /**
+     * The routes are a build-time decision and the server's mode a deployment-time one, so they can
+     * disagree without anything failing loudly. Reaching this page at all means the app routed it,
+     * which it only does when local credentials are meant to be limited.
+     */
+    private warnOnMismatch;
+    signInWith(provider: SparkExternalProvider): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SparkSignInComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SparkSignInComponent, "spark-sign-in", never, {}, {}, never, never, true, never>;
+}
+
+export { SparkSignInComponent };

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.SparkAuthRouteConfig, string>>;
+    readonly routePaths: Required<Record<keyof _mintplayer_ng_spark_auth_models.SparkAuthRouteEntries, string>>;
     colors: typeof Color;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly errorMessage: _angular_core.WritableSignal<string>;