@ciridae/auth 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @ciridae/auth
+
+Shared browser authentication capabilities and React session lifecycle for Ciridae applications.
+
+Install from npm:
+
+```bash
+npm install @ciridae/auth
+```
+
+Use the published package for new and updated consumers.
+
+Create one auth facade and pass it to the optional React integration:
+
+```ts
+import { createCiridaeAuth } from "@ciridae/auth/client";
+import { CiridaeAuthProvider } from "@ciridae/auth/react";
+```

package/dist/CiridaeAuthProvider.d.ts

@@ -0,0 +1,15 @@
+import type { FirebaseUid } from "./authenticatedUser.js";
+import type { AuthSession } from "./authSession.js";
+import type { CiridaeAuth } from "./createCiridaeAuth.js";
+type CiridaeAuthContextValue = {
+    auth: CiridaeAuth;
+    session: AuthSession;
+    signOut(): Promise<string | null>;
+};
+export declare function CiridaeAuthProvider({ children, auth, onAuthenticatedUserChange, }: {
+    children: React.ReactNode;
+    auth: CiridaeAuth;
+    onAuthenticatedUserChange?: (previousUserId: FirebaseUid | null, nextUserId: FirebaseUid | null) => void;
+}): import("@types/react").JSX.Element;
+export declare function useCiridaeAuth(): CiridaeAuthContextValue;
+export {};

package/dist/CiridaeAuthProvider.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+const CiridaeAuthContext = createContext(null);
+export function CiridaeAuthProvider({ children, auth, onAuthenticatedUserChange, }) {
+    const [session, setSession] = useState({ status: "unknown" });
+    const latestSettledUserId = useRef(undefined);
+    const signingOutUser = useRef(null);
+    useEffect(() => {
+        let cancelled = false;
+        let unsubscribe;
+        void auth
+            .subscribe((user) => {
+            if (cancelled)
+                return;
+            const nextUserId = user?.uid ?? null;
+            if (latestSettledUserId.current !== undefined &&
+                latestSettledUserId.current !== nextUserId) {
+                onAuthenticatedUserChange?.(latestSettledUserId.current, nextUserId);
+            }
+            latestSettledUserId.current = nextUserId;
+            if (signingOutUser.current && user === null)
+                return;
+            setSession(user ? { status: "signedIn", user } : { status: "signedOut" });
+        })
+            .then((nextUnsubscribe) => {
+            if (cancelled)
+                nextUnsubscribe();
+            else
+                unsubscribe = nextUnsubscribe;
+        })
+            .catch((error) => {
+            if (!cancelled)
+                setSession({ status: "unavailable", error });
+        });
+        return () => {
+            cancelled = true;
+            unsubscribe?.();
+        };
+    }, [auth, onAuthenticatedUserChange]);
+    const value = useMemo(() => ({
+        auth,
+        session,
+        async signOut() {
+            if (session.status !== "signedIn")
+                return null;
+            signingOutUser.current = session;
+            setSession({ status: "signingOut", user: session.user });
+            try {
+                return await auth.signOut();
+            }
+            catch (error) {
+                signingOutUser.current = null;
+                setSession(session);
+                throw error;
+            }
+        },
+    }), [auth, session]);
+    return _jsx(CiridaeAuthContext.Provider, { value: value, children: children });
+}
+export function useCiridaeAuth() {
+    const context = useContext(CiridaeAuthContext);
+    if (!context)
+        throw new Error("useCiridaeAuth must render below CiridaeAuthProvider.");
+    return context;
+}

package/dist/authServiceUrls.d.ts

@@ -0,0 +1,11 @@
+export type CiridaeAuthServiceConfiguration = {
+    authServiceFrontendUrl: string;
+    callbackUrl: string;
+    projectId: string;
+};
+export declare function buildCiridaeSignInUrl({ configuration, redirectPath, }: {
+    configuration: CiridaeAuthServiceConfiguration;
+    redirectPath: string;
+}): string;
+export declare function buildCiridaeSignOutUrl(configuration: CiridaeAuthServiceConfiguration): string;
+export declare function parseSameOriginPath(value: string | null, fallback?: string): string;

package/dist/authServiceUrls.js

@@ -0,0 +1,38 @@
+export function buildCiridaeSignInUrl({ configuration, redirectPath, }) {
+    const callbackUrl = new URL(configuration.callbackUrl);
+    callbackUrl.searchParams.set("redirect_path", requireSameOriginPath(redirectPath));
+    const signInUrl = new URL(configuration.authServiceFrontendUrl);
+    signInUrl.searchParams.set("project_id", requireValue("projectId", configuration.projectId));
+    signInUrl.searchParams.set("redirect_url", callbackUrl.toString());
+    return signInUrl.toString();
+}
+export function buildCiridaeSignOutUrl(configuration) {
+    const signInUrl = new URL(configuration.authServiceFrontendUrl);
+    signInUrl.searchParams.set("project_id", requireValue("projectId", configuration.projectId));
+    signInUrl.searchParams.set("redirect_url", new URL(configuration.callbackUrl).toString());
+    const signOutUrl = new URL("/signout", configuration.authServiceFrontendUrl);
+    signOutUrl.searchParams.set("redirect_url", signInUrl.toString());
+    return signOutUrl.toString();
+}
+export function parseSameOriginPath(value, fallback = "/") {
+    if (!value?.startsWith("/") || value.startsWith("//"))
+        return fallback;
+    try {
+        const url = new URL(value, "https://ciridae-auth.local");
+        return `${url.pathname}${url.search}${url.hash}`;
+    }
+    catch {
+        return fallback;
+    }
+}
+function requireSameOriginPath(value) {
+    const parsed = parseSameOriginPath(value, "");
+    if (parsed)
+        return parsed;
+    throw new Error("redirectPath must be a same-origin path.");
+}
+function requireValue(name, value) {
+    if (value.trim())
+        return value;
+    throw new Error(`${name} is required.`);
+}

package/dist/authSession.d.ts

@@ -0,0 +1,15 @@
+import type { AuthenticatedUser } from "./authenticatedUser.js";
+export type AuthSession = {
+    status: "unknown";
+} | {
+    status: "unavailable";
+    error: unknown;
+} | {
+    status: "signedOut";
+} | {
+    status: "signingOut";
+    user: AuthenticatedUser;
+} | {
+    status: "signedIn";
+    user: AuthenticatedUser;
+};

package/dist/authSession.js

@@ -0,0 +1 @@
+export {};

package/dist/authenticatedUser.d.ts

@@ -0,0 +1,17 @@
+import type { User } from "firebase/auth";
+import { z } from "zod";
+export declare const FirebaseUidSchema: z.core.$ZodBranded<z.ZodString, "FirebaseUid", "out">;
+export type FirebaseUid = z.infer<typeof FirebaseUidSchema>;
+export declare const UserEmailSchema: z.core.$ZodBranded<z.ZodEmail, "UserEmail", "out">;
+export type UserEmail = z.infer<typeof UserEmailSchema>;
+export declare const AuthenticatedUserSchema: z.ZodObject<{
+    displayName: z.ZodNullable<z.ZodString>;
+    email: z.ZodNullable<z.core.$ZodBranded<z.ZodEmail, "UserEmail", "out">>;
+    emailVerified: z.ZodBoolean;
+    photoURL: z.ZodNullable<z.ZodString>;
+    uid: z.core.$ZodBranded<z.ZodString, "FirebaseUid", "out">;
+}, z.core.$strip>;
+export type AuthenticatedUser = z.infer<typeof AuthenticatedUserSchema>;
+type FirebaseAuthenticatedUser = Pick<User, "displayName" | "email" | "emailVerified" | "photoURL" | "uid">;
+export declare function parseAuthenticatedUser(user: FirebaseAuthenticatedUser): AuthenticatedUser;
+export {};

package/dist/authenticatedUser.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const FirebaseUidSchema = z.string().min(1).max(128).brand();
+export const UserEmailSchema = z.email().brand();
+export const AuthenticatedUserSchema = z.object({
+    displayName: z.string().nullable(),
+    email: UserEmailSchema.nullable(),
+    emailVerified: z.boolean(),
+    photoURL: z.string().nullable(),
+    uid: FirebaseUidSchema,
+});
+export function parseAuthenticatedUser(user) {
+    return AuthenticatedUserSchema.parse(user);
+}

package/dist/createCiridaeAuth.d.ts

@@ -0,0 +1,23 @@
+import { type AuthenticatedUser } from "./authenticatedUser.js";
+import { type CiridaeAuthServiceConfiguration } from "./authServiceUrls.js";
+export type CiridaeAuth = {
+    readonly mode: "firebase" | "localDevelopment";
+    getAccessToken(): Promise<string | null>;
+    getAuthenticatedUser(): AuthenticatedUser | null;
+    getSignInUrl(redirectPath: string): string | null;
+    completeSignIn(customToken: string): Promise<void>;
+    clearSession(): Promise<void>;
+    signOut(): Promise<string | null>;
+    subscribe(onAuthenticatedUser: (user: AuthenticatedUser | null) => void): Promise<() => void>;
+};
+export type CiridaeAuthConfiguration = {
+    identity: {
+        mode: "firebase";
+        apiKey: string;
+        authDomain: string;
+    } | {
+        mode: "localDevelopment";
+    };
+    authService: CiridaeAuthServiceConfiguration;
+};
+export declare function createCiridaeAuth(configuration: CiridaeAuthConfiguration): CiridaeAuth;

package/dist/createCiridaeAuth.js

@@ -0,0 +1,109 @@
+import { getApps, initializeApp } from "firebase/app";
+import { getAuth, inMemoryPersistence, onAuthStateChanged, setPersistence, signInWithCustomToken, signOut as firebaseSignOut, } from "firebase/auth";
+import { AuthenticatedUserSchema } from "./authenticatedUser.js";
+import { buildCiridaeSignInUrl, buildCiridaeSignOutUrl, } from "./authServiceUrls.js";
+const FIREBASE_APP_NAME = "ciridae-browser-auth";
+const LOCAL_DEVELOPMENT_TOKEN = "dev-only-auth-bypass";
+const LOCAL_DEVELOPMENT_USER = AuthenticatedUserSchema.parse({
+    displayName: "Local Developer",
+    email: "dev-only-auth-bypass@ciridae.dev",
+    emailVerified: true,
+    photoURL: null,
+    uid: LOCAL_DEVELOPMENT_TOKEN,
+});
+export function createCiridaeAuth(configuration) {
+    if (configuration.identity.mode === "localDevelopment") {
+        return createLocalDevelopmentAuth(configuration.authService);
+    }
+    return createFirebaseAuth(configuration.identity, configuration.authService);
+}
+function createLocalDevelopmentAuth(authServiceConfiguration) {
+    return {
+        mode: "localDevelopment",
+        async getAccessToken() {
+            return LOCAL_DEVELOPMENT_TOKEN;
+        },
+        getAuthenticatedUser() {
+            return LOCAL_DEVELOPMENT_USER;
+        },
+        getSignInUrl(redirectPath) {
+            return getSignInUrl(authServiceConfiguration, redirectPath);
+        },
+        async completeSignIn() {
+            throw new Error("Sign in is unavailable in local development auth mode.");
+        },
+        async clearSession() {
+            return undefined;
+        },
+        async signOut() {
+            return null;
+        },
+        async subscribe(onAuthenticatedUser) {
+            onAuthenticatedUser(LOCAL_DEVELOPMENT_USER);
+            return () => undefined;
+        },
+    };
+}
+function createFirebaseAuth(identityConfiguration, authServiceConfiguration) {
+    let auth;
+    function getFirebaseAuth() {
+        if (auth)
+            return auth;
+        const firebaseOptions = {
+            apiKey: requireSetting("apiKey", identityConfiguration.apiKey),
+            authDomain: requireSetting("authDomain", identityConfiguration.authDomain),
+        };
+        const existingApp = getApps().find((app) => app.name === FIREBASE_APP_NAME);
+        const app = existingApp ?? initializeApp(firebaseOptions, FIREBASE_APP_NAME);
+        auth = getAuth(app);
+        return auth;
+    }
+    async function clearSession() {
+        await firebaseSignOut(getFirebaseAuth());
+    }
+    return {
+        mode: "firebase",
+        async getAccessToken() {
+            return getFirebaseAuth().currentUser?.getIdToken() ?? null;
+        },
+        getAuthenticatedUser() {
+            const user = getFirebaseAuth().currentUser;
+            return user ? AuthenticatedUserSchema.parse(user) : null;
+        },
+        getSignInUrl(redirectPath) {
+            return getSignInUrl(authServiceConfiguration, redirectPath);
+        },
+        async completeSignIn(customToken) {
+            await signInWithCustomToken(getFirebaseAuth(), customToken);
+        },
+        clearSession,
+        async signOut() {
+            await clearSession();
+            return hasAuthServiceConfiguration(authServiceConfiguration)
+                ? buildCiridaeSignOutUrl(authServiceConfiguration)
+                : null;
+        },
+        async subscribe(onAuthenticatedUser) {
+            const firebaseAuth = getFirebaseAuth();
+            await setPersistence(firebaseAuth, inMemoryPersistence);
+            return onAuthStateChanged(firebaseAuth, (user) => {
+                onAuthenticatedUser(user ? AuthenticatedUserSchema.parse(user) : null);
+            });
+        },
+    };
+}
+function getSignInUrl(configuration, redirectPath) {
+    return hasAuthServiceConfiguration(configuration)
+        ? buildCiridaeSignInUrl({ configuration, redirectPath })
+        : null;
+}
+function hasAuthServiceConfiguration(configuration) {
+    return Boolean(configuration.authServiceFrontendUrl.trim() &&
+        configuration.callbackUrl.trim() &&
+        configuration.projectId.trim());
+}
+function requireSetting(name, value) {
+    if (value.trim())
+        return value;
+    throw new Error(`${name} is required when Firebase authentication is enabled.`);
+}

package/dist/entries/client.d.ts

@@ -0,0 +1,4 @@
+export * from "../authenticatedUser.js";
+export { parseSameOriginPath } from "../authServiceUrls.js";
+export * from "../authSession.js";
+export * from "../createCiridaeAuth.js";

package/dist/entries/client.js

@@ -0,0 +1,4 @@
+export * from "../authenticatedUser.js";
+export { parseSameOriginPath } from "../authServiceUrls.js";
+export * from "../authSession.js";
+export * from "../createCiridaeAuth.js";

package/dist/entries/react.d.ts

@@ -0,0 +1,2 @@
+export * from "../CiridaeAuthProvider.js";
+export * from "../useCompleteCiridaeSignIn.js";

package/dist/entries/react.js

@@ -0,0 +1,2 @@
+export * from "../CiridaeAuthProvider.js";
+export * from "../useCompleteCiridaeSignIn.js";

package/dist/useCompleteCiridaeSignIn.d.ts

@@ -0,0 +1,18 @@
+export type CompleteCiridaeSignInState = {
+    status: "waitingForAuth";
+} | {
+    status: "authUnavailable";
+} | {
+    status: "signingIn";
+} | {
+    status: "missingToken";
+} | {
+    status: "failed";
+} | {
+    status: "redirecting";
+};
+export declare function useCompleteCiridaeSignIn({ customToken, onComplete, redirectPath, }: {
+    customToken: string | null;
+    onComplete: (redirectPath: string) => void;
+    redirectPath: string;
+}): CompleteCiridaeSignInState;

package/dist/useCompleteCiridaeSignIn.js

@@ -0,0 +1,40 @@
+import { useEffect, useRef, useState } from "react";
+import { useCiridaeAuth } from "./CiridaeAuthProvider.js";
+export function useCompleteCiridaeSignIn({ customToken, onComplete, redirectPath, }) {
+    const { auth, session } = useCiridaeAuth();
+    const [failedToken, setFailedToken] = useState(null);
+    const signInAttempt = useRef(null);
+    useEffect(() => {
+        if (session.status !== "signedOut" || !customToken)
+            return;
+        if (signInAttempt.current?.customToken !== customToken) {
+            signInAttempt.current = {
+                customToken,
+                promise: auth.completeSignIn(customToken),
+            };
+        }
+        let cancelled = false;
+        void signInAttempt.current.promise.catch(() => {
+            if (!cancelled)
+                setFailedToken(customToken);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [auth, customToken, session.status]);
+    useEffect(() => {
+        if (session.status === "signedIn")
+            onComplete(redirectPath);
+    }, [onComplete, redirectPath, session.status]);
+    if (session.status === "unknown")
+        return { status: "waitingForAuth" };
+    if (session.status === "unavailable")
+        return { status: "authUnavailable" };
+    if (session.status === "signedIn")
+        return { status: "redirecting" };
+    if (failedToken === customToken)
+        return { status: "failed" };
+    if (!customToken)
+        return { status: "missingToken" };
+    return { status: "signingIn" };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@ciridae/auth",
+	"version": "0.1.0",
+	"type": "module",
+	"private": false,
+	"engines": {
+		"node": ">=22.18"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ciridae-ai/ciridae.git",
+		"directory": "packages/auth"
+	},
+	"homepage": "https://github.com/ciridae-ai/ciridae#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		"./package.json": "./package.json",
+		"./*": {
+			"types": "./dist/entries/*.d.ts",
+			"default": "./dist/entries/*.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"peerDependencies": {
+		"@types/react": ">=18",
+		"react": ">=18"
+	},
+	"peerDependenciesMeta": {
+		"@types/react": {
+			"optional": true
+		}
+	},
+	"dependencies": {
+		"firebase": "12.15.0",
+		"zod": "^4.4.3"
+	}
+}