@graphoria/react 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,37 @@
+export interface TokenResponse<TRole extends string = string> {
+    access_token: string;
+    expires_in: number;
+    role: TRole;
+}
+export interface User<TRole extends string = string> {
+    role: TRole;
+}
+export interface AuthState<TRole extends string = string> {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    user: User<TRole> | null;
+    error: string | null;
+}
+export interface AuthContextType<TRole extends string = string> extends AuthState<TRole> {
+    login: (username: string, password: string) => Promise<User<TRole> | null>;
+    logout: () => Promise<void>;
+    hasRole: (role: TRole) => boolean;
+    hasAnyRole: (roles: TRole[]) => boolean;
+    /** Manually trigger a token refresh */
+    refreshToken: () => Promise<boolean>;
+}
+export interface RouteConfig<TRole extends string = string> {
+    /** Map of path to required roles (null = public) */
+    permissions: Record<string, TRole[] | null>;
+    /** Default route for each role after login */
+    defaultRoutes: Partial<Record<TRole, string>>;
+    /** Fallback route if role not in defaultRoutes */
+    fallbackRoute: string;
+}
+export interface AuthTransportOptions {
+    /** GraphQL HTTP endpoint for auth mutations (default: "/graphql") */
+    httpUri?: string;
+    /** Include credentials (cookies) in requests (default: true) */
+    includeCredentials?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC;CACb;AAED,MAAM,WAAW,IAAI,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACjD,IAAI,EAAE,KAAK,CAAC;CACb;AAED,MAAM,WAAW,SAAS,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACtD,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,SAAS,CAAC,KAAK,CAAC;IACtF,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3E,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC;IAClC,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;IACxC,uCAAuC;IACvC,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAMD,MAAM,WAAW,WAAW,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM;IACxD,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9C,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"fileNames":["../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2016.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2018.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2019.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2021.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2023.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.dom.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.core.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.collection.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.generator.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.iterable.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.promise.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.proxy.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.reflect.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.symbol.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2016.array.include.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2016.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.arraybuffer.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.date.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.object.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.sharedmemory.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.string.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2017.typedarrays.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2018.asyncgenerator.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2018.asynciterable.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2018.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2018.promise.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2018.regexp.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2019.array.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2019.object.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2019.string.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2019.symbol.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2019.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.bigint.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.date.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.promise.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.sharedmemory.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.string.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.symbol.wellknown.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2020.number.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2021.promise.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2021.string.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2021.weakref.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2021.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.array.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.object.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.string.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.regexp.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2023.array.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2023.collection.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2023.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.arraybuffer.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.collection.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.object.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.promise.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.regexp.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.sharedmemory.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2024.string.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.collection.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.float16.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.iterator.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.promise.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.es2025.regexp.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.array.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.collection.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.date.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.decorators.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.disposable.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.error.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.intl.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.sharedmemory.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.temporal.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.esnext.typedarrays.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.decorators.d.ts","../../../node_modules/.bun/typescript@6.0.3/node_modules/typescript/lib/lib.decorators.legacy.d.ts","../../../node_modules/.bun/@types+react@19.2.17/node_modules/@types/react/global.d.ts","../../../node_modules/.bun/csstype@3.2.3/node_modules/csstype/index.d.ts","../../../node_modules/.bun/@types+react@19.2.17/node_modules/@types/react/index.d.ts","../../../node_modules/.bun/@types+react@19.2.17/node_modules/@types/react/jsx-runtime.d.ts","../src/types.ts","../src/tokenStore.ts","../src/transport.ts","../src/AuthContext.tsx","../src/AppProvider.tsx","../src/gates.tsx","../src/index.ts"],"fileIdsList":[[89,90],[91],[91,92,93,96],[91,92,93,94,95],[91,92,96],[92,93,94,95,96,97,98],[92]],"fileInfos":[{"version":"bcd24271a113971ba9eb71ff8cb01bc6b0f872a85c23fdbe5d93065b375933cd","affectsGlobalScope":true,"impliedFormat":1},{"version":"3f88bedbeb09c6f5a6645cb24c7c55f1aa22d19ae96c8e6959cbd8b85a707bc6","impliedFormat":1},{"version":"7fe93b39b810eadd916be8db880dd7f0f7012a5cc6ffb62de8f62a2117fa6f1f","impliedFormat":1},{"version":"bb0074cc08b84a2374af33d8bf044b80851ccc9e719a5e202eacf40db2c31600","impliedFormat":1},{"version":"1a7daebe4f45fb03d9ec53d60008fbf9ac45a697fdc89e4ce218bc94b94f94d6","impliedFormat":1},{"version":"f94b133a3cb14a288803be545ac2683e0d0ff6661bcd37e31aaaec54fc382aed","impliedFormat":1},{"version":"f59d0650799f8782fd74cf73c19223730c6d1b9198671b1c5b3a38e1188b5953","impliedFormat":1},{"version":"8a15b4607d9a499e2dbeed9ec0d3c0d7372c850b2d5f1fb259e8f6d41d468a84","impliedFormat":1},{"version":"26e0fe14baee4e127f4365d1ae0b276f400562e45e19e35fd2d4c296684715e6","impliedFormat":1},{"version":"1e9332c23e9a907175e0ffc6a49e236f97b48838cc8aec9ce7e4cec21e544b65","impliedFormat":1},{"version":"3753fbc1113dc511214802a2342280a8b284ab9094f6420e7aa171e868679f91","impliedFormat":1},{"version":"999ca32883495a866aa5737fe1babc764a469e4cde6ee6b136a4b9ae68853e4b","impliedFormat":1},{"version":"17f13ecb98cbc39243f2eee1f16d45cd8ec4706b03ee314f1915f1a8b42f6984","impliedFormat":1},{"version":"d6b1eba8496bdd0eed6fc8a685768fe01b2da4a0388b5fe7df558290bffcf32f","affectsGlobalScope":true,"impliedFormat":1},{"version":"eadcffda2aa84802c73938e589b9e58248d74c59cb7fcbca6474e3435ac15504","affectsGlobalScope":true,"impliedFormat":1},{"version":"105ba8ff7ba746404fe1a2e189d1d3d2e0eb29a08c18dded791af02f29fb4711","affectsGlobalScope":true,"impliedFormat":1},{"version":"00343ca5b2e3d48fa5df1db6e32ea2a59afab09590274a6cccb1dbae82e60c7c","affectsGlobalScope":true,"impliedFormat":1},{"version":"ebd9f816d4002697cb2864bea1f0b70a103124e18a8cd9645eeccc09bdf80ab4","affectsGlobalScope":true,"impliedFormat":1},{"version":"2c1afac30a01772cd2a9a298a7ce7706b5892e447bb46bdbeef720f7b5da77ad","affectsGlobalScope":true,"impliedFormat":1},{"version":"7b0225f483e4fa685625ebe43dd584bb7973bbd84e66a6ba7bbe175ee1048b4f","affectsGlobalScope":true,"impliedFormat":1},{"version":"c0a4b8ac6ce74679c1da2b3795296f5896e31c38e888469a8e0f99dc3305de60","affectsGlobalScope":true,"impliedFormat":1},{"version":"3084a7b5f569088e0146533a00830e206565de65cae2239509168b11434cd84f","affectsGlobalScope":true,"impliedFormat":1},{"version":"c5079c53f0f141a0698faa903e76cb41cd664e3efb01cc17a5c46ec2eb0bef42","affectsGlobalScope":true,"impliedFormat":1},{"version":"32cafbc484dea6b0ab62cf8473182bbcb23020d70845b406f80b7526f38ae862","affectsGlobalScope":true,"impliedFormat":1},{"version":"fca4cdcb6d6c5ef18a869003d02c9f0fd95df8cfaf6eb431cd3376bc034cad36","affectsGlobalScope":true,"impliedFormat":1},{"version":"b93ec88115de9a9dc1b602291b85baf825c85666bf25985cc5f698073892b467","affectsGlobalScope":true,"impliedFormat":1},{"version":"f5c06dcc3fe849fcb297c247865a161f995cc29de7aa823afdd75aaaddc1419b","affectsGlobalScope":true,"impliedFormat":1},{"version":"b77e16112127a4b169ef0b8c3a4d730edf459c5f25fe52d5e436a6919206c4d7","affectsGlobalScope":true,"impliedFormat":1},{"version":"fbffd9337146eff822c7c00acbb78b01ea7ea23987f6c961eba689349e744f8c","affectsGlobalScope":true,"impliedFormat":1},{"version":"a995c0e49b721312f74fdfb89e4ba29bd9824c770bbb4021d74d2bf560e4c6bd","affectsGlobalScope":true,"impliedFormat":1},{"version":"c7b3542146734342e440a84b213384bfa188835537ddbda50d30766f0593aff9","affectsGlobalScope":true,"impliedFormat":1},{"version":"ce6180fa19b1cccd07ee7f7dbb9a367ac19c0ed160573e4686425060b6df7f57","affectsGlobalScope":true,"impliedFormat":1},{"version":"3f02e2476bccb9dbe21280d6090f0df17d2f66b74711489415a8aa4df73c9675","affectsGlobalScope":true,"impliedFormat":1},{"version":"45e3ab34c1c013c8ab2dc1ba4c80c780744b13b5676800ae2e3be27ae862c40c","affectsGlobalScope":true,"impliedFormat":1},{"version":"805c86f6cca8d7702a62a844856dbaa2a3fd2abef0536e65d48732441dde5b5b","affectsGlobalScope":true,"impliedFormat":1},{"version":"e42e397f1a5a77994f0185fd1466520691456c772d06bf843e5084ceb879a0ad","affectsGlobalScope":true,"impliedFormat":1},{"version":"f4c2b41f90c95b1c532ecc874bd3c111865793b23aebcc1c3cbbabcd5d76ffb0","affectsGlobalScope":true,"impliedFormat":1},{"version":"ab26191cfad5b66afa11b8bf935ef1cd88fabfcb28d30b2dfa6fad877d050332","affectsGlobalScope":true,"impliedFormat":1},{"version":"2088bc26531e38fb05eedac2951480db5309f6be3fa4a08d2221abb0f5b4200d","affectsGlobalScope":true,"impliedFormat":1},{"version":"cb9d366c425fea79716a8fb3af0d78e6b22ebbab3bd64d25063b42dc9f531c1e","affectsGlobalScope":true,"impliedFormat":1},{"version":"500934a8089c26d57ebdb688fc9757389bb6207a3c8f0674d68efa900d2abb34","affectsGlobalScope":true,"impliedFormat":1},{"version":"689da16f46e647cef0d64b0def88910e818a5877ca5379ede156ca3afb780ac3","affectsGlobalScope":true,"impliedFormat":1},{"version":"bc21cc8b6fee4f4c2440d08035b7ea3c06b3511314c8bab6bef7a92de58a2593","affectsGlobalScope":true,"impliedFormat":1},{"version":"7ca53d13d2957003abb47922a71866ba7cb2068f8d154877c596d63c359fed25","affectsGlobalScope":true,"impliedFormat":1},{"version":"54725f8c4df3d900cb4dac84b64689ce29548da0b4e9b7c2de61d41c79293611","affectsGlobalScope":true,"impliedFormat":1},{"version":"e5594bc3076ac29e6c1ebda77939bc4c8833de72f654b6e376862c0473199323","affectsGlobalScope":true,"impliedFormat":1},{"version":"2f3eb332c2d73e729f3364fcc0c2b375e72a121e8157d25a82d67a138c83a95c","affectsGlobalScope":true,"impliedFormat":1},{"version":"6f4427f9642ce8d500970e4e69d1397f64072ab73b97e476b4002a646ac743b1","affectsGlobalScope":true,"impliedFormat":1},{"version":"48915f327cd1dea4d7bd358d9dc7732f58f9e1626a29cc0c05c8c692419d9bb7","affectsGlobalScope":true,"impliedFormat":1},{"version":"b7bf9377723203b5a6a4b920164df22d56a43f593269ba6ae1fdc97774b68855","affectsGlobalScope":true,"impliedFormat":1},{"version":"db9709688f82c9e5f65a119c64d835f906efe5f559d08b11642d56eb85b79357","affectsGlobalScope":true,"impliedFormat":1},{"version":"4b25b8c874acd1a4cf8444c3617e037d444d19080ac9f634b405583fd10ce1f7","affectsGlobalScope":true,"impliedFormat":1},{"version":"37be57d7c90cf1f8112ee2636a068d8fd181289f82b744160ec56a7dc158a9f5","affectsGlobalScope":true,"impliedFormat":1},{"version":"a917a49ac94cd26b754ab84e113369a75d1a47a710661d7cd25e961cc797065f","affectsGlobalScope":true,"impliedFormat":1},{"version":"6d3261badeb7843d157ef3e6f5d1427d0eeb0af0cf9df84a62cfd29fd47ac86e","affectsGlobalScope":true,"impliedFormat":1},{"version":"195daca651dde22f2167ac0d0a05e215308119a3100f5e6268e8317d05a92526","affectsGlobalScope":true,"impliedFormat":1},{"version":"8b11e4285cd2bb164a4dc09248bdec69e9842517db4ca47c1ba913011e44ff2f","affectsGlobalScope":true,"impliedFormat":1},{"version":"0508571a52475e245b02bc50fa1394065a0a3d05277fbf5120c3784b85651799","affectsGlobalScope":true,"impliedFormat":1},{"version":"8f9af488f510c3015af3cc8c267a9e9d96c4dd38a1fdff0e11dc5a544711415b","affectsGlobalScope":true,"impliedFormat":1},{"version":"fc611fea8d30ea72c6bbfb599c9b4d393ce22e2f5bfef2172534781e7d138104","affectsGlobalScope":true,"impliedFormat":1},{"version":"0bd714129fca875f7d4c477a1a392200b0bcd13fb2e80928cd334b63830ea047","affectsGlobalScope":true,"impliedFormat":1},{"version":"e2c9037ae6cd2c52d80ceef0b3c5ffdb488627d71529cf4f63776daf11161c9a","affectsGlobalScope":true,"impliedFormat":1},{"version":"135d5cf4d345f59f1a9caadfafcd858d3d9cc68290db616cc85797224448cccc","affectsGlobalScope":true,"impliedFormat":1},{"version":"bc238c3f81c2984751932b6aab223cd5b830e0ac6cad76389e5e9d2ffc03287d","affectsGlobalScope":true,"impliedFormat":1},{"version":"4a07f9b76d361f572620927e5735b77d6d2101c23cdd94383eb5b706e7b36357","affectsGlobalScope":true,"impliedFormat":1},{"version":"7c4e8dc6ab834cc6baa0227e030606d29e3e8449a9f67cdf5605ea5493c4db29","affectsGlobalScope":true,"impliedFormat":1},{"version":"de7ba0fd02e06cd9a5bd4ab441ed0e122735786e67dde1e849cced1cd8b46b78","affectsGlobalScope":true,"impliedFormat":1},{"version":"6148e4e88d720a06855071c3db02069434142a8332cf9c182cda551adedf3156","affectsGlobalScope":true,"impliedFormat":1},{"version":"d63dba625b108316a40c95a4425f8d4294e0deeccfd6c7e59d819efa19e23409","affectsGlobalScope":true,"impliedFormat":1},{"version":"0568d6befee03dd435bed4fc25c4e46865b24bdcb8c563fdc21f580a2c301904","affectsGlobalScope":true,"impliedFormat":1},{"version":"30d62269b05b584741f19a5369852d5d34895aa2ac4fd948956f886d15f9cc0d","affectsGlobalScope":true,"impliedFormat":1},{"version":"f128dae7c44d8f35ee42e0a437000a57c9f06cc04f8b4fb42eebf44954d53dc8","affectsGlobalScope":true,"impliedFormat":1},{"version":"ffbe6d7b295306b2ba88030f65b74c107d8d99bdcf596ea99c62a02f606108b0","affectsGlobalScope":true,"impliedFormat":1},{"version":"996fb27b15277369c68a4ba46ed138b4e9e839a02fb4ec756f7997629242fd9f","affectsGlobalScope":true,"impliedFormat":1},{"version":"79b712591b270d4778c89706ca2cfc56ddb8c3f895840e477388f1710dc5eda9","affectsGlobalScope":true,"impliedFormat":1},{"version":"20884846cef428b992b9bd032e70a4ef88e349263f63aeddf04dda837a7dba26","affectsGlobalScope":true,"impliedFormat":1},{"version":"5fcab789c73a97cd43828ee3cc94a61264cf24d4c44472ce64ced0e0f148bdb2","affectsGlobalScope":true,"impliedFormat":1},{"version":"db59a81f070c1880ad645b2c0275022baa6a0c4f0acdc58d29d349c6efcf0903","affectsGlobalScope":true,"impliedFormat":1},{"version":"673294292640f5722b700e7d814e17aaf7d93f83a48a2c9b38f33cbc940ad8b0","affectsGlobalScope":true,"impliedFormat":1},{"version":"d786b48f934cbca483b3c6d0a798cb43bbb4ada283e76fb22c28e53ae05b9e69","affectsGlobalScope":true,"impliedFormat":1},{"version":"1ecb8e347cb6b2a8927c09b86263663289418df375f5e68e11a0ae683776978f","affectsGlobalScope":true,"impliedFormat":1},{"version":"142efd4ce210576f777dc34df121777be89eda476942d6d6663b03dcb53be3ff","affectsGlobalScope":true,"impliedFormat":1},{"version":"379bc41580c2d774f82e828c70308f24a005b490c25ba34d679d84bcf05c3d9d","affectsGlobalScope":true,"impliedFormat":1},{"version":"ed484fb2aa8a1a23d0277056ec3336e0a0b52f9b8d6a961f338a642faf43235d","affectsGlobalScope":true,"impliedFormat":1},{"version":"4ffedae1d1c2d53fdbca1c96d3c7dda544281f7d262f99b6880634f8fd8d9820","affectsGlobalScope":true,"impliedFormat":1},{"version":"83a730b125d477dd264df8ba479afab27a3dae7152b005c214ab94dc7ee44fd3","affectsGlobalScope":true,"impliedFormat":1},{"version":"1ce14b81c5cc821994aa8ec1d42b220dd41b27fcc06373bce3958af7421b77d4","affectsGlobalScope":true,"impliedFormat":1},{"version":"b3a048b3e9302ef9a34ef4ebb9aecfb28b66abb3bce577206a79fee559c230da","affectsGlobalScope":true,"impliedFormat":1},{"version":"7e29f41b158de217f94cb9676bf9cbd0cd9b5a46e1985141ed36e075c52bf6ad","affectsGlobalScope":true,"impliedFormat":1},{"version":"ac51dd7d31333793807a6abaa5ae168512b6131bd41d9c5b98477fc3b7800f9f","impliedFormat":1},{"version":"dc782ff85b2cb10075ecffc158af7bfb27ff97bf8491c917efea0c3d622d5ac4","impliedFormat":1},{"version":"b838d4c72740eb0afd284bf7575b74c624b105eff2e8c7b4aeead57e7ac320ff","impliedFormat":1},{"version":"f9d0fc094a64675bd2d04c6acc96171dec23930f055ca7c624dc3d8e951c186e","signature":"52684ff5e4d09e6445b874d804119a756e8865f8b08b8eb575e4224ce4464cb3"},{"version":"101dd6b7ea22568fa464b3d9a2eb6998477db0db88e7874c987e0eddef620596","signature":"a395764aadf834f27ee1767b7b991699768ab52fc188779609de1250c93af9a1"},{"version":"891d209f1dc2bc3b3a0cfecf2c612b4bd53c8ba841c29681e69138e171d3b5d0","signature":"cbad5a8a440f24b8d7b1ecb7014ab9460e43968c185aac23924c8a3a8c66a5e0"},{"version":"7acd1540db9702bcc6b2e21b735cd3480b346106addc0d0bc8c5778cbb0644ab","signature":"747fd3377ca9c6c52b539295ea6f039908bd9f4b88466992cc07d7883f5a6019"},{"version":"cb093b335f8e04271d823577499ac37388ec9d7a5d372eb254bbb67966cd3344","signature":"ba278872b5f95ab09279667c66a2b24348a4ee038ad8c2861db2d5d01bdea062"},{"version":"1bda17129f8893ac3c7dea4810ca62a1396d1cba7987182722bd06cc9555ecfb","signature":"4abdb40eaf156e2df744c8fd523cadae6f1062260d333435ff46425af91474b5"},{"version":"49d98b727e332155dee58c6c8650a794e9ca19ff3be68d92f9a9a62defde91e3","signature":"3fa3884c6cd1f5facf1b804eb65cbc17a19598b57ccd57fbab10b5788f33d556"}],"root":[[93,99]],"options":{"allowImportingTsExtensions":true,"allowJs":true,"composite":true,"declaration":true,"declarationMap":true,"emitDeclarationOnly":true,"jsx":4,"module":99,"noFallthroughCasesInSwitch":true,"noPropertyAccessFromIndexSignature":false,"noUnusedLocals":false,"noUnusedParameters":false,"outDir":"./","rootDir":"..","skipLibCheck":true,"strict":true,"target":99,"verbatimModuleSyntax":true},"referencedMap":[[91,1],[92,2],[97,3],[96,4],[98,5],[99,6],[94,7],[95,7],[93,7]],"latestChangedDtsFile":"./src/gates.d.ts","version":"6.0.3"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@graphoria/react",
+  "version": "0.1.0",
+  "description": "React hooks and utilities for Graphoria GraphQL APIs (client-agnostic)",
+  "keywords": [
+    "authentication",
+    "graphoria",
+    "graphql",
+    "hooks",
+    "react",
+    "typescript"
+  ],
+  "homepage": "https://github.com/graphoria/graphoria#readme",
+  "bugs": {
+    "url": "https://github.com/graphoria/graphoria/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Alex Ferreli <ferreli.ale@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/graphoria/graphoria.git",
+    "directory": "packages/react"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/__test/**",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "registry": "http://localhost:4873/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.9.0",
+    "@sinonjs/fake-timers": "^15.4.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/sinonjs__fake-timers": "^15.0.1",
+    "happy-dom": "^20.9.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "typescript": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/src/AppProvider.tsx

@@ -0,0 +1,138 @@
+import { createContext, useContext, useMemo } from "react";
+
+import type { ReactNode } from "react";
+import type { AuthTransportOptions, RouteConfig } from "./types";
+
+import { AuthProvider, useAuth } from "./AuthContext";
+
+// ============================================================================
+// App Provider - composes AuthProvider + RouteConfigContext.
+// Bring your own GraphQL client (Apollo, urql, relay, raw fetch — anything).
+// ============================================================================
+
+export interface RouteConfigContextType<TRole extends string = string> {
+  config: RouteConfig<TRole>;
+  isProtectedRoute: (path: string) => boolean;
+  getRequiredRoles: (path: string) => TRole[] | null;
+  canRoleAccess: (path: string, role: TRole | null) => boolean;
+  getRedirectPath: (role: TRole, returnTo?: string) => string;
+}
+
+const RouteConfigContext = createContext<RouteConfigContextType<string> | null>(null);
+
+export function useRouteConfig<TRole extends string = string>(): RouteConfigContextType<TRole> {
+  const context = useContext(RouteConfigContext);
+  if (!context) {
+    throw new Error("useRouteConfig must be used within an AppProvider");
+  }
+  return context as RouteConfigContextType<TRole>;
+}
+
+interface AppProviderProps<TRole extends string = string> extends AuthTransportOptions {
+  children: ReactNode;
+  /** Route configuration with permissions and default routes */
+  routeConfig: RouteConfig<TRole>;
+  /** Called when authentication state changes */
+  onAuthChange?: (user: { role: TRole } | null) => void;
+  /** Called after server logout completes — clear your GraphQL cache here */
+  onLogout?: () => void | Promise<void>;
+  /** Called after a successful token refresh — restart your WS / re-auth your middleware */
+  onTokenRefresh?: (accessToken: string, expiresIn: number) => void;
+  /** Rendered while initial session refresh is in flight */
+  loadingFallback?: ReactNode;
+}
+
+const configValue = <TRole extends string = string>({
+  routeConfig,
+}: {
+  routeConfig: RouteConfig<TRole>;
+}): RouteConfigContextType<TRole> => {
+  const { permissions, defaultRoutes, fallbackRoute } = routeConfig;
+
+  const canRoleAccess = (path: string, role: string | null): boolean => {
+    const requiredRoles = permissions[path];
+    if (requiredRoles === null || requiredRoles === undefined) return true;
+    if (!role) return false;
+    return requiredRoles.includes(role as TRole);
+  };
+
+  return {
+    config: routeConfig,
+    isProtectedRoute: (path: string) => {
+      const roles = permissions[path];
+      return roles !== null && roles !== undefined;
+    },
+    getRequiredRoles: (path: string) => permissions[path] ?? null,
+    canRoleAccess,
+    getRedirectPath: (role: string, returnTo?: string) => {
+      if (returnTo && canRoleAccess(returnTo, role)) return returnTo;
+      return defaultRoutes[role as TRole] ?? fallbackRoute;
+    },
+  };
+};
+
+/**
+ * Main application provider. Wraps the app with:
+ * - AuthProvider (authentication state + proactive token refresh)
+ * - RouteConfigContext (route access control)
+ *
+ * Bring your own GraphQL client. Wire it via `getAccessToken`,
+ * `subscribeAccessToken`, and `ensureFreshToken` from the public API.
+ *
+ * @example
+ * ```tsx
+ * const routeConfig: RouteConfig = {
+ *   permissions: { "/": null, "/dashboard": ["admin", "judge"] },
+ *   defaultRoutes: { admin: "/dashboard", judge: "/dashboard" },
+ *   fallbackRoute: "/dashboard",
+ * };
+ *
+ * <AppProvider
+ *   routeConfig={routeConfig}
+ *   onLogout={() => apolloClient.clearStore()}
+ *   onTokenRefresh={() => wsClient.terminate()}
+ * >
+ *   <App />
+ * </AppProvider>
+ * ```
+ */
+export function AppProvider<TRole extends string = string>({
+  children,
+  routeConfig,
+  onAuthChange,
+  onLogout,
+  onTokenRefresh,
+  loadingFallback,
+  httpUri,
+  includeCredentials,
+}: AppProviderProps<TRole>) {
+  const config = useMemo(() => configValue({ routeConfig }), [routeConfig]);
+
+  return (
+    <AuthProvider
+      onAuthChange={onAuthChange}
+      onLogout={onLogout}
+      onTokenRefresh={onTokenRefresh}
+      loadingFallback={loadingFallback}
+      httpUri={httpUri}
+      includeCredentials={includeCredentials}
+    >
+      <RouteConfigContext.Provider value={config as RouteConfigContextType<string>}>
+        {children}
+      </RouteConfigContext.Provider>
+    </AuthProvider>
+  );
+}
+
+/**
+ * Hook to check if current user can access a specific route.
+ */
+export function useCanAccess(path: string): boolean {
+  const { isAuthenticated, hasAnyRole } = useAuth();
+  const { getRequiredRoles } = useRouteConfig();
+  const requiredRoles = getRequiredRoles(path);
+
+  if (!requiredRoles) return true;
+  if (!isAuthenticated) return false;
+  return hasAnyRole(requiredRoles);
+}

package/src/AuthContext.tsx

@@ -0,0 +1,365 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+import type { ReactNode } from "react";
+import type {
+  AuthContextType,
+  AuthState,
+  AuthTransportOptions,
+  TokenResponse,
+  User,
+} from "./types";
+
+import { setAccessToken, setLogoutHandler, setRefreshHandler } from "./tokenStore";
+import { GraphQLFetchError, gqlFetch } from "./transport";
+
+// ============================================================================
+// Auth Context - in-memory token storage with proactive refresh.
+// Auth mutations go over raw fetch — no GraphQL client dependency.
+// ============================================================================
+
+const LOGIN_MUTATION = `
+  mutation Login($username: String!, $password: String!) {
+    auth_login(username: $username, password: $password) {
+      access_token
+      expires_in
+      role
+    }
+  }
+`;
+
+const REFRESH_MUTATION = `
+  mutation RefreshToken {
+    auth_refresh {
+      access_token
+      expires_in
+      role
+    }
+  }
+`;
+
+const LOGOUT_MUTATION = `
+  mutation Logout {
+    auth_logout
+  }
+`;
+
+function createAuthContext<TRole extends string>() {
+  return createContext<AuthContextType<TRole> | null>(null);
+}
+
+const AuthContext = createAuthContext<string>();
+
+// Module-level cache for the boot refresh. React 18 StrictMode mounts the
+// provider twice in dev (mount → cleanup → mount). Without this, the same
+// rotating refresh cookie is consumed twice and the second request fails
+// with "Token reuse detected". Cleared on logout, and shortly after settling
+// so HMR / legit remounts still re-validate.
+let bootRefreshPromise: Promise<TokenResponse<string> | null> | null = null;
+let bootRefreshClearTimer: ReturnType<typeof setTimeout> | null = null;
+
+function armBootRefreshCacheClear() {
+  if (bootRefreshClearTimer) clearTimeout(bootRefreshClearTimer);
+  // 1s is far longer than StrictMode's synchronous double-mount window and
+  // short enough that a real subsequent mount still re-checks the session.
+  bootRefreshClearTimer = setTimeout(() => {
+    bootRefreshPromise = null;
+    bootRefreshClearTimer = null;
+  }, 1000);
+}
+
+function resetBootRefreshCache() {
+  bootRefreshPromise = null;
+  if (bootRefreshClearTimer) {
+    clearTimeout(bootRefreshClearTimer);
+    bootRefreshClearTimer = null;
+  }
+}
+
+function createInitialState<TRole extends string>(): AuthState<TRole> {
+  return {
+    isAuthenticated: false,
+    isLoading: true,
+    user: null,
+    error: null,
+  };
+}
+
+interface AuthProviderProps<TRole extends string> extends AuthTransportOptions {
+  children: ReactNode;
+  /** Called when authentication state changes */
+  onAuthChange?: (user: User<TRole> | null) => void;
+  /** Called after server logout completes — user can clear GraphQL cache here */
+  onLogout?: () => void | Promise<void>;
+  /** Called after a successful token refresh — user can restart WS / re-auth middleware */
+  onTokenRefresh?: (accessToken: string, expiresIn: number) => void;
+  /** Rendered while initial session refresh is in flight (default: null) */
+  loadingFallback?: ReactNode;
+}
+
+export function AuthProvider<TRole extends string = string>({
+  children,
+  onAuthChange,
+  onLogout,
+  onTokenRefresh,
+  loadingFallback = null,
+  httpUri = "/graphql",
+  includeCredentials = true,
+}: AuthProviderProps<TRole>) {
+  const [state, setState] = useState<AuthState<TRole>>(createInitialState<TRole>());
+
+  const refreshTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onAuthChangeRef = useRef(onAuthChange);
+  const onLogoutRef = useRef(onLogout);
+  const onTokenRefreshRef = useRef(onTokenRefresh);
+
+  useEffect(() => {
+    onAuthChangeRef.current = onAuthChange;
+    onLogoutRef.current = onLogout;
+    onTokenRefreshRef.current = onTokenRefresh;
+  }, [onAuthChange, onLogout, onTokenRefresh]);
+
+  const clearRefreshTimer = useCallback(() => {
+    if (refreshTimerRef.current) {
+      clearTimeout(refreshTimerRef.current);
+      refreshTimerRef.current = null;
+    }
+  }, []);
+
+  const applyTokens = useCallback((tokens: TokenResponse<TRole>) => {
+    setAccessToken(tokens.access_token);
+    onTokenRefreshRef.current?.(tokens.access_token, tokens.expires_in);
+  }, []);
+
+  const setAuthFromToken = useCallback(
+    (tokens: TokenResponse<TRole>) => {
+      applyTokens(tokens);
+
+      const user: User<TRole> = { role: tokens.role };
+      setState({
+        isAuthenticated: true,
+        isLoading: false,
+        user,
+        error: null,
+      });
+
+      onAuthChangeRef.current?.(user);
+    },
+    [applyTokens],
+  );
+
+  const callRefresh = useCallback(async (): Promise<TokenResponse<TRole> | null> => {
+    const data = await gqlFetch<{ auth_refresh: TokenResponse<TRole> | null }>(
+      httpUri,
+      REFRESH_MUTATION,
+      undefined,
+      { credentials: includeCredentials },
+    );
+    return data.auth_refresh ?? null;
+  }, [httpUri, includeCredentials]);
+
+  const scheduleRefresh = useCallback(
+    (expiresIn: number) => {
+      clearRefreshTimer();
+      // Refresh 30s before expiry (minimum 10s)
+      const refreshInMs = Math.max((expiresIn - 30) * 1000, 10000);
+
+      refreshTimerRef.current = setTimeout(() => {
+        callRefresh()
+          .then((tokens) => {
+            if (tokens) {
+              applyTokens(tokens);
+              setState((s) => ({ ...s, user: { role: tokens.role } }));
+              scheduleRefresh(tokens.expires_in);
+            }
+          })
+          .catch((err) => {
+            console.error("[Auth] Refresh failed:", err);
+          });
+      }, refreshInMs);
+    },
+    [clearRefreshTimer, callRefresh, applyTokens],
+  );
+
+  const refreshToken = useCallback(async (): Promise<boolean> => {
+    try {
+      const tokens = await callRefresh();
+      if (tokens) {
+        applyTokens(tokens);
+        scheduleRefresh(tokens.expires_in);
+        setState((s) => ({ ...s, user: { role: tokens.role } }));
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }, [callRefresh, applyTokens, scheduleRefresh]);
+
+  const logout = useCallback(async (): Promise<void> => {
+    clearRefreshTimer();
+    resetBootRefreshCache();
+    setAccessToken(null);
+
+    setState({
+      isAuthenticated: false,
+      isLoading: false,
+      user: null,
+      error: null,
+    });
+
+    try {
+      await gqlFetch<{ auth_logout: boolean }>(httpUri, LOGOUT_MUTATION, undefined, {
+        credentials: includeCredentials,
+      });
+    } catch (error) {
+      console.error("Logout request failed:", error);
+    }
+
+    try {
+      await onLogoutRef.current?.();
+    } catch (error) {
+      console.error("onLogout callback failed:", error);
+    }
+
+    onAuthChangeRef.current?.(null);
+  }, [clearRefreshTimer, httpUri, includeCredentials]);
+
+  // Wire the module-level token store so any GraphQL client can drive
+  // the refresh/logout loop via ensureFreshToken().
+  useEffect(() => {
+    setRefreshHandler(refreshToken);
+    setLogoutHandler(logout);
+    return () => {
+      setRefreshHandler(null);
+      setLogoutHandler(null);
+    };
+  }, [refreshToken, logout]);
+
+  // Boot: try refreshing the session using the HTTP-only cookie.
+  useEffect(() => {
+    let mounted = true;
+
+    const tryRefresh = async () => {
+      try {
+        if (!bootRefreshPromise) {
+          bootRefreshPromise = callRefresh() as Promise<TokenResponse<string> | null>;
+          bootRefreshPromise.finally(armBootRefreshCacheClear).catch(() => {});
+        }
+        const tokens = (await bootRefreshPromise) as TokenResponse<TRole> | null;
+        if (!mounted) return;
+
+        if (tokens) {
+          setAuthFromToken(tokens);
+          scheduleRefresh(tokens.expires_in);
+        } else {
+          setState((s) => ({ ...s, isLoading: false }));
+        }
+      } catch {
+        if (!mounted) return;
+        setState((s) => ({ ...s, isLoading: false }));
+      }
+    };
+    void tryRefresh();
+
+    return () => {
+      mounted = false;
+      clearRefreshTimer();
+    };
+  }, [callRefresh, setAuthFromToken, scheduleRefresh, clearRefreshTimer]);
+
+  const login = useCallback(
+    async (username: string, password: string): Promise<User<TRole> | null> => {
+      setState((s) => ({ ...s, isLoading: true, error: null }));
+
+      try {
+        const data = await gqlFetch<{ auth_login: TokenResponse<TRole> | null }>(
+          httpUri,
+          LOGIN_MUTATION,
+          { username, password },
+          { credentials: includeCredentials },
+        );
+
+        if (data.auth_login) {
+          const tokens = data.auth_login;
+          // Invalidate any cached "no session" boot result so a later
+          // provider remount re-checks against the now-valid refresh cookie.
+          resetBootRefreshCache();
+          setAuthFromToken(tokens);
+          scheduleRefresh(tokens.expires_in);
+          return { role: tokens.role };
+        }
+
+        setState((s) => ({
+          ...s,
+          isLoading: false,
+          error: "Invalid credentials",
+        }));
+        return null;
+      } catch (error: unknown) {
+        const message =
+          error instanceof GraphQLFetchError
+            ? error.message
+            : error instanceof Error
+              ? error.message
+              : "Login failed";
+
+        setState((s) => ({ ...s, isLoading: false, error: message }));
+        return null;
+      }
+    },
+    [httpUri, includeCredentials, setAuthFromToken, scheduleRefresh],
+  );
+
+  const hasRole = useCallback((role: TRole) => state.user?.role === role, [state.user]);
+
+  const hasAnyRole = useCallback(
+    (roles: TRole[]): boolean => {
+      return state.user?.role ? roles.includes(state.user.role) : false;
+    },
+    [state.user],
+  );
+
+  const value = useMemo<AuthContextType<TRole>>(
+    () => ({
+      ...state,
+      login,
+      logout,
+      hasRole,
+      hasAnyRole,
+      refreshToken,
+    }),
+    [state, login, logout, hasRole, hasAnyRole, refreshToken],
+  );
+
+  if (state.isLoading) return <>{loadingFallback}</>;
+
+  return (
+    // AuthContext is type-erased to AuthContextType<string> at the React
+    // boundary; useAuth<TRole>() casts back. Both casts need the unknown
+    // intermediate because TRole's contravariant positions defeat narrowing.
+    <AuthContext.Provider value={value as unknown as AuthContextType<string>}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth<TRole extends string = string>(): AuthContextType<TRole> {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+  return context as unknown as AuthContextType<TRole>;
+}
+
+/** @internal Test-only: flushes the StrictMode boot-refresh cache. Not re-exported from index.ts. */
+export function __resetBootRefreshCacheForTest(): void {
+  resetBootRefreshCache();
+}