@fluixi/oauth2 1.0.0-alpha.1

package/dist/callback.cjs

@@ -0,0 +1,125 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/callback.ts
+var callback_exports = {};
+__export(callback_exports, {
+  OAuthCallback: () => OAuthCallback,
+  useOAuthCallback: () => useOAuthCallback
+});
+module.exports = __toCommonJS(callback_exports);
+var import_core = require("@fluixi/core");
+var import_signal = require("@fluixi/reactive/signal");
+var import_di2 = require("@fluixi/start/di");
+
+// src/tokens.ts
+var import_di = require("@fluixi/start/di");
+var AuthServiceToken = (0, import_di.injectionToken)("AuthService");
+var AuthClientToken = (0, import_di.injectionToken)("AuthClient");
+
+// src/service.ts
+var import_session = require("@fluixi/session");
+var import_client = require("@fluixi/auth/client");
+function paramsFromUrl(url) {
+  const href = url ?? (typeof location === "undefined" ? null : location.href);
+  if (!href) return {};
+  const { searchParams } = new URL(String(href));
+  return {
+    code: searchParams.get("code") ?? void 0,
+    state: searchParams.get("state") ?? void 0,
+    error: searchParams.get("error") ?? void 0,
+    errorDescription: searchParams.get("error_description") ?? void 0
+  };
+}
+
+// src/callback.ts
+function reasonFor(cause) {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+var spent = /* @__PURE__ */ new Set();
+function useOAuthCallback(options = {}) {
+  const stage = (0, import_signal.signal)("waiting");
+  const error = (0, import_signal.signal)(null);
+  const destination = (0, import_signal.signal)(null);
+  const params = (0, import_signal.signal)({});
+  let lastQuery = null;
+  let injected = null;
+  let injectionError = null;
+  if (!options.service) {
+    try {
+      injected = (0, import_di2.inject)(AuthServiceToken);
+    } catch (cause) {
+      injectionError = cause;
+    }
+  }
+  (0, import_core.onMount)(() => {
+    if (typeof location !== "undefined") {
+      const query = new URL(location.href).search;
+      if (query !== lastQuery) {
+        lastQuery = query;
+        params.set(Object.fromEntries(new URL(location.href).searchParams.entries()));
+      }
+    }
+    if (options.enabled && !options.enabled()) return;
+    const service = typeof options.service === "function" ? options.service() : options.service ?? injected;
+    if (!service) {
+      stage.set("failed");
+      error.set(
+        "No auth service to finish the flow with. Provide `AuthServiceToken`, or pass `service` to useOAuthCallback." + (injectionError ? ` Injection said: ${reasonFor(injectionError)}` : "")
+      );
+      return;
+    }
+    const callback = options.params ?? paramsFromUrl();
+    if (callback.error) {
+      stage.set("failed");
+      error.set(`${callback.error}: ${callback.errorDescription ?? "no description given"}`);
+      options.onFailed?.(callback.error, callback);
+      return;
+    }
+    if (callback.code) {
+      if (spent.has(callback.code)) return;
+      spent.add(callback.code);
+    }
+    stage.set("exchanging");
+    void service.complete(callback).then((target) => {
+      destination.set(target);
+      stage.set("signed-in");
+      if (options.onSignedIn) options.onSignedIn(target);
+      else if (typeof location !== "undefined") location.replace(target);
+    }).catch((cause) => {
+      stage.set("failed");
+      error.set(reasonFor(cause));
+      options.onFailed?.(reasonFor(cause), cause);
+    });
+  });
+  return { stage, error, destination, params };
+}
+function OAuthCallback(props = {}) {
+  return () => {
+    const { stage, error } = useOAuthCallback(props);
+    return () => {
+      if (stage() === "failed") {
+        const reason = error() ?? "The sign in did not complete.";
+        return props.failed ? props.failed(reason) : reason;
+      }
+      return props.pending ? props.pending() : null;
+    };
+  };
+}

package/dist/callback.d.ts

@@ -0,0 +1,113 @@
+import { type SignalHandle } from '@fluixi/reactive/signal';
+import type { AuthService } from './service.js';
+import type { CallbackParams } from './types.js';
+/** Anything a fluixi renderer accepts as output. */
+type ComponentChild = unknown;
+/** How far the exchange got. */
+export type CallbackStage = 'waiting' | 'exchanging' | 'signed-in' | 'failed';
+export interface OAuthCallbackOptions {
+    /**
+     * The service to finish the flow with.
+     *
+     * Left out, it is injected from `AuthServiceToken`, which is what an app providing auth
+     * through DI already registers. Pass one to skip DI, or when a page chooses between
+     * several providers.
+     */
+    service?: AuthService<any, any, any> | (() => AuthService<any, any, any>);
+    /**
+     * The parameters to exchange. Read from `location` when absent.
+     *
+     * Only worth giving in a test, or when something has already consumed the URL.
+     */
+    params?: CallbackParams;
+    /**
+     * Where to go once signed in. Defaults to `location.replace`, which is deliberate: this
+     * page exists for one transition, and a document navigation arrives with the session
+     * already established and no router to resolve.
+     *
+     * Give a function to keep the visitor in the client router instead. It runs after mount,
+     * so `useNavigate` is safe to have closed over from the route that renders this.
+     */
+    onSignedIn?: (destination: string) => void;
+    /** Called when the exchange fails, for logging. The error is rendered either way. */
+    onFailed?: (reason: string, cause: unknown) => void;
+    /**
+     * Whether to exchange at all. Checked on mount, so it may read the browser.
+     *
+     * For a route that is reached in more than one configuration: in server mode the provider
+     * redirects to the middleware's own path and no exchange belongs here, and attempting one
+     * produces a state mismatch that describes nothing real. Returning false leaves the stage
+     * at `waiting` and sets no error, so the page can say why itself.
+     */
+    enabled?: () => boolean;
+}
+/** What the hook reports, all reactive. */
+export interface CallbackState {
+    /** How far it got. `waiting` until the browser takes over. */
+    stage: SignalHandle<CallbackStage>;
+    /** Why it stopped, or null. */
+    error: SignalHandle<string | null>;
+    /** Where it is going, once known. */
+    destination: SignalHandle<string | null>;
+    /** Everything the provider put on the URL, for a page that wants to show it. */
+    params: SignalHandle<Record<string, string>>;
+}
+/**
+ * Finish a sign in on the redirect URI.
+ *
+ * Runs the exchange on mount and reports progress. Use this when the page needs its own
+ * markup or wants to show what the provider sent; `OAuthCallback` wraps it for the common
+ * case.
+ *
+ * @example
+ * ```tsx
+ * export default function Callback() {
+ *   const { stage, error } = useOAuthCallback();
+ *
+ *   return (
+ *     <main>
+ *       <Show when={error} fallback={<p>Signing you in…</p>}>
+ *         <h1>Could not sign you in</h1>
+ *         <p>{error}</p>
+ *         <a href="/login">Try again</a>
+ *       </Show>
+ *     </main>
+ *   );
+ * }
+ * ```
+ */
+export declare function useOAuthCallback(options?: OAuthCallbackOptions): CallbackState;
+export interface OAuthCallbackProps extends OAuthCallbackOptions {
+    /** Shown while the exchange runs. A short line is usually right. */
+    pending?: () => ComponentChild;
+    /**
+     * Shown when it fails, with the reason.
+     *
+     * Worth filling in. The default states the reason and offers nothing to do about it, and a
+     * visitor who cannot get past this page needs a way back to the login.
+     */
+    failed?: (reason: string) => ComponentChild;
+}
+/**
+ * A whole redirect-URI route.
+ *
+ * @example
+ * ```tsx
+ * // src/routes/callback/index.tsx, the entire file
+ * import { OAuthCallback } from '@fluixi/oauth2/callback';
+ *
+ * export default OAuthCallback({
+ *   pending: () => <p>Signing you in…</p>,
+ *   failed: (reason) => (
+ *     <>
+ *       <h1>Could not sign you in</h1>
+ *       <p>{reason}</p>
+ *       <a href="/login">Try again</a>
+ *     </>
+ *   ),
+ * });
+ * ```
+ */
+export declare function OAuthCallback(props?: OAuthCallbackProps): () => ComponentChild;
+export {};
+//# sourceMappingURL=callback.d.ts.map

package/dist/callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.d.ts","sourceRoot":"","sources":["../src/callback.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAIpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,oDAAoD;AACpD,KAAK,cAAc,GAAG,OAAO,CAAC;AAE9B,gCAAgC;AAChC,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE9E,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1E;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;CACzB;AAED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,KAAK,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;IACnC,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnC,qCAAqC;IACrC,WAAW,EAAE,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,gFAAgF;IAChF,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC9C;AAqBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAyFlF;AAED,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,cAAc,CAAC;IAC/B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,kBAAuB,GAAG,MAAM,cAAc,CAYlF"}

package/dist/callback.js

@@ -0,0 +1,183 @@
+/**
+ * The redirect URI route, as something an app does not have to write.
+ *
+ * `complete()` has always been here; the route around it was not, so every application
+ * rewrote the same forty lines and met the same four traps. Each of these produced a page
+ * that rendered and then did nothing, which is the worst failure to diagnose:
+ *
+ *  - Reading `location` while rendering. It does not exist on the server, so the two sides
+ *    produce different markup, hydration finds a mismatch and keeps the server's version.
+ *    The parameters then read as absent on a URL that has them.
+ *  - Calling a router hook in the component body. `useNavigate` resolves the router during
+ *    render, and a route that throws there fails to hydrate, leaving markup that responds to
+ *    nothing. This navigates with `location.replace` instead, which needs no router at all.
+ *  - Starting the exchange during render, so it runs once on the server and again in the
+ *    browser.
+ *  - Building the client from state that a page has not restored yet, which looks for a
+ *    `state` this flow never stored and reports a mismatch.
+ *
+ * All of it happens in `onMount`, and every signal starts at a value the server can render.
+ *
+ * No JSX here: an app passes its own markup, so the package stays free of a JSX runtime and
+ * the page looks like the rest of the application.
+ */
+import { onMount } from '@fluixi/core';
+import { signal } from '@fluixi/reactive/signal';
+import { inject } from '@fluixi/start/di';
+import { AuthServiceToken } from './tokens.js';
+import { paramsFromUrl } from './service.js';
+/** The message for a failure, preferring the provider's own words. */
+function reasonFor(cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    return String(cause);
+}
+/**
+ * Codes this document has already spent.
+ *
+ * An authorization code is single use, and the PKCE verifier is consumed with it, so a
+ * second exchange of the same code fails and reports a state mismatch, which describes
+ * nothing that is actually wrong. Anything that runs a component body more than once would
+ * do that: a re-render, a remount, a development refresh.
+ *
+ * Module scope rather than a closure, because a closure is made fresh by the thing being
+ * guarded against.
+ */
+const spent = new Set();
+/**
+ * Finish a sign in on the redirect URI.
+ *
+ * Runs the exchange on mount and reports progress. Use this when the page needs its own
+ * markup or wants to show what the provider sent; `OAuthCallback` wraps it for the common
+ * case.
+ *
+ * @example
+ * ```tsx
+ * export default function Callback() {
+ *   const { stage, error } = useOAuthCallback();
+ *
+ *   return (
+ *     <main>
+ *       <Show when={error} fallback={<p>Signing you in…</p>}>
+ *         <h1>Could not sign you in</h1>
+ *         <p>{error}</p>
+ *         <a href="/login">Try again</a>
+ *       </Show>
+ *     </main>
+ *   );
+ * }
+ * ```
+ */
+export function useOAuthCallback(options = {}) {
+    const stage = signal('waiting');
+    const error = signal(null);
+    const destination = signal(null);
+    const params = signal({});
+    /**
+     * Resolved now rather than on mount, because `inject` reads the owner scope that only
+     * exists while a component is setting up. A server render where the app provides auth on
+     * the client only has nothing to resolve, and nothing there needs it: the failure is
+     * reported at mount, where it is visible.
+     */
+    /** The query string already reported, so a repeat pass writes nothing. */
+    let lastQuery = null;
+    let injected = null;
+    let injectionError = null;
+    if (!options.service) {
+        try {
+            injected = inject(AuthServiceToken);
+        }
+        catch (cause) {
+            injectionError = cause;
+        }
+    }
+    onMount(() => {
+        // Reported before anything else, because a provider that refused put its reason on the
+        // URL and a page showing nothing is the alternative.
+        //
+        // Compared against a plain variable rather than by reading `params()`. A read here
+        // subscribes whatever scope is running this to the signal, so the write that follows
+        // schedules that scope again, which runs this again: the work is idempotent but the loop
+        // is not. Writing only on a change is also what stops a fresh object, which never
+        // compares equal, from waking every watcher on each pass.
+        if (typeof location !== 'undefined') {
+            const query = new URL(location.href).search;
+            if (query !== lastQuery) {
+                lastQuery = query;
+                params.set(Object.fromEntries(new URL(location.href).searchParams.entries()));
+            }
+        }
+        if (options.enabled && !options.enabled())
+            return;
+        const service = typeof options.service === 'function' ? options.service() : (options.service ?? injected);
+        if (!service) {
+            stage.set('failed');
+            error.set('No auth service to finish the flow with. Provide `AuthServiceToken`, or pass `service` to useOAuthCallback.' +
+                (injectionError ? ` Injection said: ${reasonFor(injectionError)}` : ''));
+            return;
+        }
+        const callback = options.params ?? paramsFromUrl();
+        if (callback.error) {
+            stage.set('failed');
+            error.set(`${callback.error}: ${callback.errorDescription ?? 'no description given'}`);
+            options.onFailed?.(callback.error, callback);
+            return;
+        }
+        // One exchange per code. A second would spend a verifier that is already gone and
+        // report a state mismatch for a flow that actually worked.
+        if (callback.code) {
+            if (spent.has(callback.code))
+                return;
+            spent.add(callback.code);
+        }
+        stage.set('exchanging');
+        void service
+            .complete(callback)
+            .then((target) => {
+            destination.set(target);
+            stage.set('signed-in');
+            if (options.onSignedIn)
+                options.onSignedIn(target);
+            else if (typeof location !== 'undefined')
+                location.replace(target);
+        })
+            .catch((cause) => {
+            stage.set('failed');
+            error.set(reasonFor(cause));
+            options.onFailed?.(reasonFor(cause), cause);
+        });
+    });
+    return { stage, error, destination, params };
+}
+/**
+ * A whole redirect-URI route.
+ *
+ * @example
+ * ```tsx
+ * // src/routes/callback/index.tsx, the entire file
+ * import { OAuthCallback } from '@fluixi/oauth2/callback';
+ *
+ * export default OAuthCallback({
+ *   pending: () => <p>Signing you in…</p>,
+ *   failed: (reason) => (
+ *     <>
+ *       <h1>Could not sign you in</h1>
+ *       <p>{reason}</p>
+ *       <a href="/login">Try again</a>
+ *     </>
+ *   ),
+ * });
+ * ```
+ */
+export function OAuthCallback(props = {}) {
+    return () => {
+        const { stage, error } = useOAuthCallback(props);
+        return () => {
+            if (stage() === 'failed') {
+                const reason = error() ?? 'The sign in did not complete.';
+                return props.failed ? props.failed(reason) : reason;
+            }
+            return props.pending ? props.pending() : null;
+        };
+    };
+}

package/dist/callback.mjs

@@ -0,0 +1,106 @@
+import "./chunk-7P6ASYW6.mjs";
+
+// src/callback.ts
+import { onMount } from "@fluixi/core";
+import { signal } from "@fluixi/reactive/signal";
+import { inject } from "@fluixi/start/di";
+
+// src/tokens.ts
+import { injectionToken } from "@fluixi/start/di";
+var AuthServiceToken = injectionToken("AuthService");
+var AuthClientToken = injectionToken("AuthClient");
+
+// src/service.ts
+import { createSession } from "@fluixi/session";
+import { createAuthHooks } from "@fluixi/auth/client";
+function paramsFromUrl(url) {
+  const href = url ?? (typeof location === "undefined" ? null : location.href);
+  if (!href) return {};
+  const { searchParams } = new URL(String(href));
+  return {
+    code: searchParams.get("code") ?? void 0,
+    state: searchParams.get("state") ?? void 0,
+    error: searchParams.get("error") ?? void 0,
+    errorDescription: searchParams.get("error_description") ?? void 0
+  };
+}
+
+// src/callback.ts
+function reasonFor(cause) {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+var spent = /* @__PURE__ */ new Set();
+function useOAuthCallback(options = {}) {
+  const stage = signal("waiting");
+  const error = signal(null);
+  const destination = signal(null);
+  const params = signal({});
+  let lastQuery = null;
+  let injected = null;
+  let injectionError = null;
+  if (!options.service) {
+    try {
+      injected = inject(AuthServiceToken);
+    } catch (cause) {
+      injectionError = cause;
+    }
+  }
+  onMount(() => {
+    if (typeof location !== "undefined") {
+      const query = new URL(location.href).search;
+      if (query !== lastQuery) {
+        lastQuery = query;
+        params.set(Object.fromEntries(new URL(location.href).searchParams.entries()));
+      }
+    }
+    if (options.enabled && !options.enabled()) return;
+    const service = typeof options.service === "function" ? options.service() : options.service ?? injected;
+    if (!service) {
+      stage.set("failed");
+      error.set(
+        "No auth service to finish the flow with. Provide `AuthServiceToken`, or pass `service` to useOAuthCallback." + (injectionError ? ` Injection said: ${reasonFor(injectionError)}` : "")
+      );
+      return;
+    }
+    const callback = options.params ?? paramsFromUrl();
+    if (callback.error) {
+      stage.set("failed");
+      error.set(`${callback.error}: ${callback.errorDescription ?? "no description given"}`);
+      options.onFailed?.(callback.error, callback);
+      return;
+    }
+    if (callback.code) {
+      if (spent.has(callback.code)) return;
+      spent.add(callback.code);
+    }
+    stage.set("exchanging");
+    void service.complete(callback).then((target) => {
+      destination.set(target);
+      stage.set("signed-in");
+      if (options.onSignedIn) options.onSignedIn(target);
+      else if (typeof location !== "undefined") location.replace(target);
+    }).catch((cause) => {
+      stage.set("failed");
+      error.set(reasonFor(cause));
+      options.onFailed?.(reasonFor(cause), cause);
+    });
+  });
+  return { stage, error, destination, params };
+}
+function OAuthCallback(props = {}) {
+  return () => {
+    const { stage, error } = useOAuthCallback(props);
+    return () => {
+      if (stage() === "failed") {
+        const reason = error() ?? "The sign in did not complete.";
+        return props.failed ? props.failed(reason) : reason;
+      }
+      return props.pending ? props.pending() : null;
+    };
+  };
+}
+export {
+  OAuthCallback,
+  useOAuthCallback
+};

package/dist/chunk-25WE6UWI.mjs

@@ -0,0 +1,10 @@
+/*! @fluixi/oauth2 v1.0.0-alpha.1 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/dist/chunk-4NSOGPLM.mjs

@@ -0,0 +1,15 @@
+/*! @fluixi/oauth2 v1.0.0-alpha.1 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+
+// src/types.ts
+var OAuthError = class extends Error {
+  constructor(message, code, description) {
+    super(message);
+    this.code = code;
+    this.description = description;
+    this.name = "OAuthError";
+  }
+};
+
+export {
+  OAuthError
+};

package/dist/chunk-7P6ASYW6.mjs

@@ -0,0 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/dist/chunk-OGSFNTKA.mjs

@@ -0,0 +1,13 @@
+// src/types.ts
+var OAuthError = class extends Error {
+  constructor(message, code, description) {
+    super(message);
+    this.code = code;
+    this.description = description;
+    this.name = "OAuthError";
+  }
+};
+
+export {
+  OAuthError
+};