@multiplatform.one/auth 7.7.2

package/types/accessTokenRefresh.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Isomorphic helpers for Keycloak access-token refresh.
+ *
+ * better-auth's `/get-access-token` collapses every refresh failure into
+ * `FAILED_TO_GET_ACCESS_TOKEN` (400). The Keycloak SSO plugin in `createAuth`
+ * reclassifies: a dead refresh token (`invalid_grant`) stays 400 and revokes
+ * the session; a Keycloak blip (restart, 5xx, network) is rewritten to
+ * `TOKEN_REFRESH_UNAVAILABLE` so clients can retry instead of signing the
+ * user out.
+ *
+ * Web and native token getters share this classifier so a restart never
+ * looks like a logout. Stream 9 (native) can import
+ * `@multiplatform.one/auth/access-token` without pulling Node `async_hooks`.
+ */
+export declare const FAILED_TO_GET_ACCESS_TOKEN = "FAILED_TO_GET_ACCESS_TOKEN";
+export declare const TOKEN_REFRESH_UNAVAILABLE = "TOKEN_REFRESH_UNAVAILABLE";
+export type AccessTokenFailureKind = "signed-out" | "transient";
+/** First attempt is immediate; later attempts wait out a Keycloak bounce. */
+export declare const ACCESS_TOKEN_RETRY_DELAYS_MS: readonly [0, 400, 1000];
+export declare function classifyAccessTokenResponse(status: number, body?: {
+    code?: string;
+} | null): AccessTokenFailureKind;
+export type RetryAttemptResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    kind: AccessTokenFailureKind;
+};
+/**
+ * Retry an access-token fetch while the failure is transient (Keycloak
+ * restart, 5xx, network). A definitive signed-out answer stops immediately
+ * so we never hammer a revoked session.
+ */
+export declare function retryWhileTransient<T>(attempt: () => Promise<RetryAttemptResult<T>>, opts?: {
+    delaysMs?: readonly number[];
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<RetryAttemptResult<T>>;
+/**
+ * Revalidate when the tab becomes visible again (GitHub / Linear / Figma
+ * style: a backgrounded tab notices IdP logout or a recovered Keycloak
+ * without a full reload). Returns an unsubscribe. No-op on the server.
+ */
+export declare function watchDocumentVisible(revalidate: () => void): () => void;
+//# sourceMappingURL=accessTokenRefresh.d.ts.map

package/types/accessTokenRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessTokenRefresh.d.ts","sourceRoot":"","sources":["../src/accessTokenRefresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AACvE,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,WAAW,CAAC;AAEhE,6EAA6E;AAC7E,eAAO,MAAM,4BAA4B,yBAA0B,CAAC;AAEpE,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAC9B,sBAAsB,CAIxB;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,CAAC;AAEhD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,EAC7C,IAAI,CAAC,EAAE;IACL,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,GACA,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAYhC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAavE"}

package/types/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @multiplatform.one/auth
+ *
+ * Better Auth helpers for multiplatform.one apps with Keycloak.
+ * Provides factory functions for auth instances, route handlers, and session helpers.
+ *
+ * @example
+ * ```ts
+ * import { createAuth, createAuthRouteHandler, createSessionHelpers } from "@multiplatform.one/auth";
+ *
+ * export const auth = createAuth();
+ * export const { GET, POST } = createAuthRouteHandler(auth);
+ * export const { verifyAuth, getSession } = createSessionHelpers(auth);
+ * ```
+ */
+import { betterAuth } from "better-auth";
+export { ACCESS_TOKEN_RETRY_DELAYS_MS, FAILED_TO_GET_ACCESS_TOKEN, TOKEN_REFRESH_UNAVAILABLE, classifyAccessTokenResponse, retryWhileTransient, watchDocumentVisible, } from "./accessTokenRefresh";
+export type { AccessTokenFailureKind, RetryAttemptResult } from "./accessTokenRefresh";
+export interface KeycloakOptions {
+    baseUrl?: string;
+    realm?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+export interface CreateAuthOptions {
+    /** Base path for auth routes (default: "/api/auth") */
+    basePath?: string;
+    /** Base URL of the app (reads BASE_URL env var, or defaults to localhost:ONE_PORT) */
+    baseUrl?: string;
+    /** Auth secret (reads SECRET env var) */
+    secret?: string;
+    /** Trusted origins for CORS (auto-includes baseUrl and keycloak URL) */
+    trustedOrigins?: string[];
+    /** Keycloak configuration (reads env vars by default) */
+    keycloak?: KeycloakOptions;
+    /** Session cookie max age in seconds (default: 7 days) */
+    sessionMaxAge?: number;
+    /** Include @better-auth/expo plugin (default: true) */
+    enableExpo?: boolean;
+    /** Additional better-auth plugins */
+    plugins?: Parameters<typeof betterAuth>[0]["plugins"];
+    /**
+     * Database URL or Kysely adapter.
+     * Defaults to a SQLite file at `$DATA_DIR/better-auth.db` (or `./better-auth.db`).
+     */
+    database?: Parameters<typeof betterAuth>[0]["database"];
+}
+/** Structural type for a Better Auth instance used by helpers. */
+export interface AuthLike {
+    handler: (request: Request) => Promise<Response> | Response;
+    api: {
+        getSession: (opts: {
+            headers: Headers;
+        }) => Promise<unknown>;
+    };
+}
+/**
+ * Create a Better Auth instance configured for Keycloak.
+ * Keycloak is expected at ${BASE_URL}/auth (proxied by Frappe in dev).
+ */
+export declare function createAuth(options?: CreateAuthOptions): import("better-auth").Auth<{
+    secret: string;
+    trustedOrigins: string[];
+    session: {
+        cookieCache: {
+            enabled: true;
+            maxAge: number;
+            strategy: "jwe";
+            refreshCache: true;
+        };
+    };
+    account: {
+        storeStateStrategy: "cookie";
+        storeAccountCookie: true;
+    };
+    plugins: any[];
+    database?: any;
+    basePath: string;
+    baseURL: string;
+}>;
+/** The return type of `createAuth()`. */
+export type AuthInstance = ReturnType<typeof createAuth>;
+/**
+ * Create GET and POST route handlers for One framework `+api.ts` files.
+ *
+ * @example
+ * ```ts
+ * // lib/server/auth.ts
+ * export const { GET, POST } = createAuthRouteHandler(auth);
+ *
+ * // routes/api/auth/[route]+api.ts
+ * export { GET, POST } from "../../../lib/server/auth";
+ * ```
+ */
+export declare function createAuthRouteHandler(auth: AuthLike): {
+    readonly GET: (req: Request) => Response | Promise<Response>;
+    readonly POST: (req: Request) => Response | Promise<Response>;
+};
+/**
+ * Create session verification helpers bound to an auth instance.
+ *
+ * @returns `verifyAuth` (throws 401 Response) and `getSession` (returns session or null)
+ */
+export declare function createSessionHelpers(auth: AuthLike): {
+    verifyAuth: (req: Request) => Promise<{}>;
+    getSession: (req: Request) => Promise<unknown>;
+};
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,UAAU,EAAsB,MAAM,aAAa,CAAC;AAc7D,OAAO,EACL,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAmDvF,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qCAAqC;IACrC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;CACzD;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;IAC5D,GAAG,EAAE;QACH,UAAU,EAAE,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,OAAO,CAAA;SAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KAC9D,CAAC;CACH;AA2QD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB;;;;;;;;;;;;;;;;;;;GAoNzD;AAED,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAIzD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,QAAQ;wBAK7B,OAAO;yBAAP,OAAO;EAK9B;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ;sBAOlB,OAAO;sBALP,OAAO;EAcvC"}