@kontrolia/react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KontrolIA Auth Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @kontrolia/react
+
+Bindings de React para [KontrolIA Auth](https://github.com/rauldolores/auth): `<AuthProvider>`, `<AuthGuard>`, `<GuestGuard>`, `<RequireRole>`, `<RequirePermission>` y el hook `useAuth()`.
+
+## Instalación
+
+```bash
+npm install @kontrolia/react @kontrolia/auth
+```
+
+## Uso
+
+```tsx
+import { AuthProvider, AuthGuard, useAuth } from "@kontrolia/react";
+
+function App() {
+  return (
+    <AuthProvider config={{ supabaseUrl, supabaseAnonKey }}>
+      <AuthGuard fallback={<LoginPage />}>
+        <Dashboard />
+      </AuthGuard>
+    </AuthProvider>
+  );
+}
+
+function Dashboard() {
+  const { user, organization, hasPermission, logout } = useAuth();
+  if (!hasPermission("facturacion.facturas.crear")) return null;
+  // ...
+}
+```
+
+`<RequirePermission>` / `<RequireRole>` renderizan condicionalmente según los claims del JWT (roles/permisos de la organización activa), sin round-trip al servidor.
+
+## Documentación
+
+Ver la [guía completa](https://github.com/rauldolores/auth) del monorepo.

package/dist/context.d.ts

@@ -0,0 +1,20 @@
+import { type KontroliaClient, type KontroliaClientConfig } from "@kontrolia/auth";
+import { type PermissionChecker } from "@kontrolia/permissions";
+import type { KontroliaOrganization, KontroliaUser } from "@kontrolia/shared";
+export interface KontroliaAuthState {
+    client: KontroliaClient;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    user: KontroliaUser | null;
+    organization: KontroliaOrganization | null;
+    roles: string[];
+    permissions: string[];
+    checker: PermissionChecker;
+}
+export interface AuthProviderProps {
+    config: KontroliaClientConfig;
+    children: React.ReactNode;
+}
+export declare function AuthProvider({ config, children }: AuthProviderProps): import("react").JSX.Element;
+export declare function useKontroliaAuthContext(): KontroliaAuthState;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,qBAAqB,EAAyB,MAAM,iBAAiB,CAAC;AAC1G,OAAO,EAAE,KAAK,iBAAiB,EAA2B,MAAM,wBAAwB,CAAC;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG9E,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC3C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAID,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,iBAAiB,+BAsDnE;AAED,wBAAgB,uBAAuB,IAAI,kBAAkB,CAM5D"}

package/dist/context.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createKontroliaClient } from "@kontrolia/auth";
+import { createPermissionChecker } from "@kontrolia/permissions";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+const KontroliaAuthContext = createContext(null);
+export function AuthProvider({ config, children }) {
+    const client = useMemo(() => createKontroliaClient(config), [config.supabaseUrl, config.supabaseAnonKey]);
+    const [state, setState] = useState({
+        isLoading: true,
+        isAuthenticated: false,
+        user: null,
+        organization: null,
+        roles: [],
+        permissions: [],
+    });
+    useEffect(() => {
+        let cancelled = false;
+        async function loadInitial() {
+            const [user, organization, roles, permissions] = await Promise.all([
+                client.getUser(),
+                client.getOrganization(),
+                client.getRoles(),
+                client.getPermissions(),
+            ]);
+            if (cancelled)
+                return;
+            setState({ isLoading: false, isAuthenticated: user !== null, user, organization, roles, permissions });
+        }
+        void loadInitial();
+        const unsubscribe = client.onAuthStateChange((next) => {
+            if (cancelled)
+                return;
+            setState({
+                isLoading: false,
+                isAuthenticated: next.user !== null,
+                user: next.user,
+                organization: next.organization,
+                roles: next.roles,
+                permissions: next.permissions,
+            });
+        });
+        return () => {
+            cancelled = true;
+            unsubscribe();
+        };
+    }, [client]);
+    const checker = useMemo(() => createPermissionChecker({ roles: state.roles, permissions: state.permissions }), [state.roles, state.permissions]);
+    const value = { ...state, client, checker };
+    return _jsx(KontroliaAuthContext.Provider, { value: value, children: children });
+}
+export function useKontroliaAuthContext() {
+    const context = useContext(KontroliaAuthContext);
+    if (!context) {
+        throw new Error("useAuth() must be used within an <AuthProvider>");
+    }
+    return context;
+}

package/dist/guards.d.ts

@@ -0,0 +1,23 @@
+import type { EvaluationMode } from "@kontrolia/permissions";
+export interface GuardProps {
+    children: React.ReactNode;
+    /** Rendered while the initial session is being resolved. */
+    loading?: React.ReactNode;
+    /** Rendered when the guard's condition is not met. */
+    fallback?: React.ReactNode;
+}
+/** Renders children only for an authenticated user. */
+export declare function AuthGuard({ children, loading, fallback }: GuardProps): import("react").JSX.Element;
+/** Renders children only for a guest (unauthenticated) — typical for login/register pages. */
+export declare function GuestGuard({ children, loading, fallback }: GuardProps): import("react").JSX.Element;
+export interface RequireRoleProps extends GuardProps {
+    role: string | string[];
+    mode?: EvaluationMode;
+}
+export declare function RequireRole({ role, mode, children, loading, fallback }: RequireRoleProps): import("react").JSX.Element;
+export interface RequirePermissionProps extends GuardProps {
+    permission: string | string[];
+    mode?: EvaluationMode;
+}
+export declare function RequirePermission({ permission, mode, children, loading, fallback, }: RequirePermissionProps): import("react").JSX.Element;
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,uDAAuD;AACvD,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,OAAc,EAAE,QAAe,EAAE,EAAE,UAAU,+BAIlF;AAED,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAc,EAAE,QAAe,EAAE,EAAE,UAAU,+BAInF;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,IAAY,EAAE,QAAQ,EAAE,OAAc,EAAE,QAAe,EAAE,EAAE,gBAAgB,+BAI9G;AAED,MAAM,WAAW,sBAAuB,SAAQ,UAAU;IACxD,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,IAAY,EACZ,QAAQ,EACR,OAAc,EACd,QAAe,GAChB,EAAE,sBAAsB,+BAIxB"}

package/dist/guards.js

@@ -0,0 +1,29 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useKontroliaAuthContext } from "./context.js";
+/** Renders children only for an authenticated user. */
+export function AuthGuard({ children, loading = null, fallback = null }) {
+    const { isLoading, isAuthenticated } = useKontroliaAuthContext();
+    if (isLoading)
+        return _jsx(_Fragment, { children: loading });
+    return _jsx(_Fragment, { children: isAuthenticated ? children : fallback });
+}
+/** Renders children only for a guest (unauthenticated) — typical for login/register pages. */
+export function GuestGuard({ children, loading = null, fallback = null }) {
+    const { isLoading, isAuthenticated } = useKontroliaAuthContext();
+    if (isLoading)
+        return _jsx(_Fragment, { children: loading });
+    return _jsx(_Fragment, { children: !isAuthenticated ? children : fallback });
+}
+export function RequireRole({ role, mode = "any", children, loading = null, fallback = null }) {
+    const { isLoading, checker } = useKontroliaAuthContext();
+    if (isLoading)
+        return _jsx(_Fragment, { children: loading });
+    return _jsx(_Fragment, { children: checker.hasRole(role, mode) ? children : fallback });
+}
+export function RequirePermission({ permission, mode = "any", children, loading = null, fallback = null, }) {
+    const { isLoading, checker } = useKontroliaAuthContext();
+    if (isLoading)
+        return _jsx(_Fragment, { children: loading });
+    return _jsx(_Fragment, { children: checker.hasPermission(permission, mode) ? children : fallback });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AuthProvider, useKontroliaAuthContext, type KontroliaAuthState } from "./context.js";
+export { useAuth } from "./use-auth.js";
+export { AuthGuard, GuestGuard, RequireRole, RequirePermission, type GuardProps } from "./guards.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { AuthProvider, useKontroliaAuthContext } from "./context.js";
+export { useAuth } from "./use-auth.js";
+export { AuthGuard, GuestGuard, RequireRole, RequirePermission } from "./guards.js";

package/dist/use-auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The single hook every consuming app uses to talk to KontrolIA Auth.
+ * Mirrors the @kontrolia/auth client 1:1 plus the current reactive state,
+ * so components never need to import @kontrolia/auth or supabase-js
+ * directly.
+ */
+export declare function useAuth(): {
+    login: ({ email, password }: import("@kontrolia/auth").LoginCredentials) => Promise<void>;
+    loginWithOAuth: (provider: import("@kontrolia/auth").OAuthProvider, redirectTo?: string) => Promise<void>;
+    logout: () => Promise<void>;
+    register: ({ email, password, fullName }: import("@kontrolia/auth").RegisterInput) => Promise<void>;
+    refresh: () => Promise<void>;
+    requestPasswordReset: (email: string, redirectTo?: string) => Promise<void>;
+    updatePassword: (newPassword: string) => Promise<void>;
+    updateProfile: (input: import("@kontrolia/auth").UpdateProfileInput) => Promise<void>;
+    switchOrganization: (organizationId: string) => Promise<void>;
+    getToken: () => Promise<string | null>;
+    enrollMfa: (friendlyName?: string) => Promise<import("@kontrolia/auth").MfaEnrollment>;
+    verifyMfaEnrollment: (factorId: string, code: string) => Promise<void>;
+    challengeMfa: (factorId: string) => Promise<string>;
+    verifyMfaChallenge: (factorId: string, challengeId: string, code: string) => Promise<void>;
+    listMfaFactors: () => Promise<import("@kontrolia/auth").MfaFactor[]>;
+    unenrollMfa: (factorId: string) => Promise<void>;
+    getAuthenticatorAssuranceLevel: () => Promise<import("@kontrolia/auth").AuthenticatorAssuranceLevel>;
+    hasPermission: (required: string | string[], mode?: import("@kontrolia/permissions").EvaluationMode) => boolean;
+    hasRole: (required: string | string[], mode?: import("@kontrolia/permissions").EvaluationMode) => boolean;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    user: import("@kontrolia/shared").KontroliaUser | null;
+    organization: import("@kontrolia/shared").KontroliaOrganization | null;
+    roles: string[];
+    permissions: string[];
+};
+//# sourceMappingURL=use-auth.d.ts.map

package/dist/use-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-auth.d.ts","sourceRoot":"","sources":["../src/use-auth.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAgB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;EAyBtB"}

package/dist/use-auth.js

@@ -0,0 +1,33 @@
+"use client";
+import { useKontroliaAuthContext } from "./context.js";
+/**
+ * The single hook every consuming app uses to talk to KontrolIA Auth.
+ * Mirrors the @kontrolia/auth client 1:1 plus the current reactive state,
+ * so components never need to import @kontrolia/auth or supabase-js
+ * directly.
+ */
+export function useAuth() {
+    const { client, checker, ...state } = useKontroliaAuthContext();
+    return {
+        ...state,
+        login: client.login.bind(client),
+        loginWithOAuth: client.loginWithOAuth.bind(client),
+        logout: client.logout.bind(client),
+        register: client.register.bind(client),
+        refresh: client.refresh.bind(client),
+        requestPasswordReset: client.requestPasswordReset.bind(client),
+        updatePassword: client.updatePassword.bind(client),
+        updateProfile: client.updateProfile.bind(client),
+        switchOrganization: client.switchOrganization.bind(client),
+        getToken: client.getToken.bind(client),
+        enrollMfa: client.enrollMfa.bind(client),
+        verifyMfaEnrollment: client.verifyMfaEnrollment.bind(client),
+        challengeMfa: client.challengeMfa.bind(client),
+        verifyMfaChallenge: client.verifyMfaChallenge.bind(client),
+        listMfaFactors: client.listMfaFactors.bind(client),
+        unenrollMfa: client.unenrollMfa.bind(client),
+        getAuthenticatorAssuranceLevel: client.getAuthenticatorAssuranceLevel.bind(client),
+        hasPermission: checker.hasPermission,
+        hasRole: checker.hasRole,
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kontrolia/react",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "React bindings for KontrolIA Auth: <AuthProvider>, <AuthGuard>, <GuestGuard>, <RequireRole>, <RequirePermission> and useAuth().",
+  "keywords": [
+    "kontrolia",
+    "auth",
+    "react",
+    "authentication",
+    "authorization",
+    "rbac",
+    "sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rauldolores/auth.git",
+    "directory": "packages/react-sdk"
+  },
+  "homepage": "https://github.com/rauldolores/auth#readme",
+  "bugs": "https://github.com/rauldolores/auth/issues",
+  "author": "KontrolIA",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@kontrolia/permissions": "1.0.0",
+    "@kontrolia/shared": "1.0.0",
+    "@kontrolia/auth": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.17",
+    "@types/react-dom": "^18.3.5",
+    "eslint": "^9.17.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.7.2",
+    "@kontrolia/config": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rimraf dist"
+  }
+}