@hotosm/hanko-auth 0.2.5 β 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +152 -146
- package/dist/hanko-auth.esm.js +2301 -2211
- package/dist/hanko-auth.iife.js +440 -0
- package/dist/hanko-auth.umd.js +440 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,210 +1,216 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Web Component: `<hotosm-auth>`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
**Note:** This package provides only the header widget. The actual login form and profile pages are hosted at the [HOTOSM Login service](https://login.hotosm.org). Users will be redirected there for authentication.
|
|
3
|
+
Lit-based web component for HOTOSM SSO authentication with Hanko and OpenStreetMap integration.
|
|
6
4
|
|
|
7
5
|
## Installation
|
|
8
6
|
|
|
9
|
-
Install the package and its peer dependency:
|
|
10
|
-
|
|
11
7
|
```bash
|
|
12
8
|
# npm
|
|
13
|
-
npm install @hotosm/hanko-auth
|
|
9
|
+
npm install @hotosm/hanko-auth
|
|
10
|
+
|
|
11
|
+
# pnpm
|
|
12
|
+
pnpm add @hotosm/hanko-auth
|
|
14
13
|
|
|
15
14
|
# yarn
|
|
16
|
-
yarn add @hotosm/hanko-auth
|
|
15
|
+
yarn add @hotosm/hanko-auth
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### Peer Dependencies
|
|
19
|
+
|
|
20
|
+
This package requires Web Awesome to be installed separately:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# npm
|
|
24
|
+
npm install @awesome.me/webawesome
|
|
17
25
|
|
|
18
26
|
# pnpm
|
|
19
|
-
pnpm add @
|
|
27
|
+
pnpm add @awesome.me/webawesome
|
|
28
|
+
|
|
29
|
+
# yarn
|
|
30
|
+
yarn add @awesome.me/webawesome
|
|
20
31
|
```
|
|
21
32
|
|
|
22
|
-
|
|
33
|
+
**Why peer dependencies?**
|
|
34
|
+
|
|
35
|
+
- Control the Web Awesome version in your project
|
|
36
|
+
- Share Web Awesome across multiple packages without duplication
|
|
37
|
+
- Reduce bundle size when multiple packages use Web Awesome
|
|
23
38
|
|
|
24
|
-
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
### Import the component
|
|
25
42
|
|
|
26
43
|
```javascript
|
|
27
|
-
|
|
28
|
-
import
|
|
44
|
+
// Import Web Awesome (required peer dependency)
|
|
45
|
+
import "@awesome.me/webawesome";
|
|
46
|
+
|
|
47
|
+
// Import the auth component
|
|
48
|
+
import "@hotosm/hanko-auth";
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Use in HTML
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<hotosm-auth
|
|
55
|
+
hanko-url="https://login.hotosm.org"
|
|
56
|
+
show-profile="true"
|
|
57
|
+
></hotosm-auth>
|
|
29
58
|
```
|
|
30
59
|
|
|
31
|
-
### React
|
|
60
|
+
### React Example
|
|
32
61
|
|
|
33
|
-
```
|
|
34
|
-
import
|
|
35
|
-
import
|
|
62
|
+
```tsx
|
|
63
|
+
import { useEffect, useRef } from "react";
|
|
64
|
+
import "@awesome.me/webawesome";
|
|
65
|
+
import "@hotosm/hanko-auth";
|
|
36
66
|
|
|
37
|
-
function
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
67
|
+
export function AuthButton({ hankoUrl, onLogin }) {
|
|
68
|
+
const ref = useRef<HTMLElement>(null);
|
|
69
|
+
|
|
70
|
+
useEffect(() => {
|
|
71
|
+
const el = ref.current;
|
|
72
|
+
const handler = (e: CustomEvent) => onLogin(e.detail.user);
|
|
73
|
+
el?.addEventListener("hanko-login", handler);
|
|
74
|
+
return () => el?.removeEventListener("hanko-login", handler);
|
|
75
|
+
}, [onLogin]);
|
|
76
|
+
|
|
77
|
+
return <hotosm-auth ref={ref} hanko-url={hankoUrl} osm-required />;
|
|
43
78
|
}
|
|
44
79
|
```
|
|
45
80
|
|
|
46
|
-
|
|
81
|
+
## Attributes
|
|
47
82
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
83
|
+
### Core
|
|
84
|
+
|
|
85
|
+
| Attribute | Type | Default | Description |
|
|
86
|
+
| ----------- | ------ | ------------------------ | ------------------------------------------ |
|
|
87
|
+
| `hanko-url` | string | `window.location.origin` | Login service URL for Hanko authentication |
|
|
88
|
+
| `base-path` | string | `""` | Base URL for OSM OAuth endpoints |
|
|
89
|
+
| `auth-path` | string | `/api/auth/osm` | OSM auth endpoints path |
|
|
90
|
+
|
|
91
|
+
### Behavior
|
|
92
|
+
|
|
93
|
+
| Attribute | Type | Default | Description |
|
|
94
|
+
| ---------------- | ------- | -------------- | -------------------------- |
|
|
95
|
+
| `osm-required` | boolean | `false` | Require OSM connection |
|
|
96
|
+
| `osm-scopes` | string | `"read_prefs"` | Space-separated OSM scopes |
|
|
97
|
+
| `auto-connect` | boolean | `false` | Auto-redirect to OSM OAuth |
|
|
98
|
+
| `verify-session` | boolean | `false` | Verify session on return |
|
|
99
|
+
|
|
100
|
+
### Display
|
|
101
|
+
|
|
102
|
+
| Attribute | Type | Default | Description |
|
|
103
|
+
| -------------- | ------- | ------- | ------------------------------------ |
|
|
104
|
+
| `show-profile` | boolean | `false` | Show full profile (vs header button) |
|
|
105
|
+
| `display-name` | string | `""` | Override display name |
|
|
106
|
+
|
|
107
|
+
### Redirects
|
|
108
|
+
|
|
109
|
+
| Attribute | Type | Default | Description |
|
|
110
|
+
| ----------------------- | ------ | ------- | -------------------------- |
|
|
111
|
+
| `redirect-after-login` | string | `""` | URL after successful login |
|
|
112
|
+
| `redirect-after-logout` | string | `""` | URL after logout |
|
|
113
|
+
|
|
114
|
+
### Cross-app
|
|
67
115
|
|
|
68
|
-
|
|
116
|
+
| Attribute | Type | Default | Description |
|
|
117
|
+
| ------------------- | ------ | ------- | ----------------------------- |
|
|
118
|
+
| `mapping-check-url` | string | `""` | URL to check user mapping |
|
|
119
|
+
| `app-id` | string | `""` | App identifier for onboarding |
|
|
69
120
|
|
|
70
|
-
|
|
121
|
+
## Events
|
|
71
122
|
|
|
72
|
-
|
|
73
|
-
|-----------|------|---------|-------------|
|
|
74
|
-
| `hanko-url` | `string` | `window.location.origin` | Hanko API URL (e.g., `https://login.hotosm.org`) |
|
|
75
|
-
| `redirect-after-login` | `string` | Current page | Redirect URL after successful login |
|
|
76
|
-
| `redirect-after-logout` | `string` | `""` | Redirect URL after logout |
|
|
77
|
-
| `display-name` | `string` | `""` | Override user display name |
|
|
78
|
-
| `osm-required` | `boolean` | `false` | Show OSM connection requirement indicator |
|
|
79
|
-
| `base-path` | `string` | `""` | Base path for API calls |
|
|
80
|
-
| `auth-path` | `string` | `"/api/auth/osm"` | OSM connection check endpoint |
|
|
123
|
+
The component dispatches the following custom events:
|
|
81
124
|
|
|
82
|
-
|
|
125
|
+
| Event | Detail | When |
|
|
126
|
+
| --------------- | ---------------------- | --------------------------- |
|
|
127
|
+
| `hanko-login` | `{ user: HankoUser }` | User logged in |
|
|
128
|
+
| `osm-connected` | `{ osmData: OSMData }` | OSM account linked |
|
|
129
|
+
| `osm-skipped` | `{}` | User skipped OSM connection |
|
|
130
|
+
| `auth-complete` | `{}` | Auth flow complete |
|
|
131
|
+
| `logout` | `{}` | User logged out |
|
|
83
132
|
|
|
84
|
-
|
|
133
|
+
### Event Handling Example
|
|
85
134
|
|
|
86
135
|
```javascript
|
|
87
|
-
document.
|
|
88
|
-
|
|
136
|
+
const auth = document.querySelector("hotosm-auth");
|
|
137
|
+
|
|
138
|
+
auth.addEventListener("hanko-login", (e) => {
|
|
139
|
+
console.log("Logged in:", e.detail.user.email);
|
|
89
140
|
});
|
|
90
141
|
|
|
91
|
-
|
|
92
|
-
console.log(
|
|
142
|
+
auth.addEventListener("osm-connected", (e) => {
|
|
143
|
+
console.log("OSM connected:", e.detail.osmData.osm_username);
|
|
93
144
|
});
|
|
94
145
|
|
|
95
|
-
|
|
96
|
-
console.log(
|
|
146
|
+
auth.addEventListener("logout", () => {
|
|
147
|
+
console.log("User logged out");
|
|
148
|
+
window.location.href = "/";
|
|
97
149
|
});
|
|
98
150
|
```
|
|
99
151
|
|
|
100
|
-
##
|
|
152
|
+
## Usage Modes
|
|
101
153
|
|
|
102
|
-
###
|
|
154
|
+
### Header Mode (default)
|
|
103
155
|
|
|
104
|
-
|
|
105
|
-
<hotosm-auth
|
|
106
|
-
hanko-url="https://login.hotosm.org"
|
|
107
|
-
></hotosm-auth>
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
### With Return URL
|
|
111
|
-
|
|
112
|
-
Redirect users back to a specific page after login:
|
|
156
|
+
Shows a compact login button in the header:
|
|
113
157
|
|
|
114
158
|
```html
|
|
115
|
-
<
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
159
|
+
<header>
|
|
160
|
+
<hotosm-auth
|
|
161
|
+
hanko-url="https://login.hotosm.org"
|
|
162
|
+
redirect-after-login="/"
|
|
163
|
+
></hotosm-auth>
|
|
164
|
+
</header>
|
|
119
165
|
```
|
|
120
166
|
|
|
121
|
-
###
|
|
167
|
+
### Profile Mode
|
|
122
168
|
|
|
123
|
-
|
|
169
|
+
Shows full authentication form (for login pages):
|
|
124
170
|
|
|
125
171
|
```html
|
|
126
172
|
<hotosm-auth
|
|
127
173
|
hanko-url="https://login.hotosm.org"
|
|
174
|
+
show-profile
|
|
128
175
|
osm-required
|
|
129
|
-
|
|
176
|
+
auto-connect
|
|
177
|
+
redirect-after-login="https://portal.hotosm.org"
|
|
130
178
|
></hotosm-auth>
|
|
131
179
|
```
|
|
132
180
|
|
|
133
|
-
|
|
181
|
+
## Configuration
|
|
182
|
+
|
|
183
|
+
### Hanko URL Detection
|
|
184
|
+
|
|
185
|
+
The component detects the Hanko URL in the following priority order:
|
|
134
186
|
|
|
135
|
-
|
|
187
|
+
1. `hanko-url` attribute
|
|
188
|
+
2. `<meta name="hanko-url" content="...">` tag
|
|
189
|
+
3. `window.HANKO_URL` global variable
|
|
190
|
+
4. `window.location.origin` (fallback)
|
|
136
191
|
|
|
137
192
|
```html
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
193
|
+
<!-- Option 1: Attribute -->
|
|
194
|
+
<hotosm-auth hanko-url="https://login.hotosm.org"></hotosm-auth>
|
|
195
|
+
|
|
196
|
+
<!-- Option 2: Meta tag -->
|
|
197
|
+
<meta name="hanko-url" content="https://login.hotosm.org" />
|
|
198
|
+
<hotosm-auth></hotosm-auth>
|
|
199
|
+
|
|
200
|
+
<!-- Option 3: JavaScript -->
|
|
201
|
+
<script>
|
|
202
|
+
window.HANKO_URL = "https://login.hotosm.org";
|
|
203
|
+
</script>
|
|
204
|
+
<hotosm-auth></hotosm-auth>
|
|
142
205
|
```
|
|
143
206
|
|
|
144
207
|
## Styling
|
|
145
208
|
|
|
146
|
-
The component uses
|
|
147
|
-
|
|
148
|
-
- `hotosm-ui-design/dist/hot.css` - Color, typography, spacing variables
|
|
149
|
-
- `hotosm-ui-design/dist/hot-font-face.css` - Font definitions
|
|
150
|
-
- `hotosm-ui-design/dist/hot-wa.css` - WebAwesome theme overrides
|
|
151
|
-
|
|
152
|
-
You can override styles by setting CSS custom properties:
|
|
209
|
+
The component uses Shadow DOM. Override styles with CSS custom properties:
|
|
153
210
|
|
|
154
211
|
```css
|
|
155
212
|
hotosm-auth {
|
|
156
|
-
--
|
|
157
|
-
--
|
|
213
|
+
--primary-color: #d73f3f;
|
|
214
|
+
--text-color: #333;
|
|
158
215
|
}
|
|
159
216
|
```
|
|
160
|
-
|
|
161
|
-
## Features
|
|
162
|
-
|
|
163
|
-
- π **Authentication State** - Shows login/logout status and user info
|
|
164
|
-
- π€ **Profile Dropdown** - Quick access to profile and logout
|
|
165
|
-
- πΊοΈ **OSM Status Indicator** - Shows OpenStreetMap connection status
|
|
166
|
-
- π¨ **HOT Design System** - Consistent styling with HOT branding
|
|
167
|
-
- π± **Responsive** - Works on desktop and mobile
|
|
168
|
-
- β‘ **Lightweight** - Built with Lit web components
|
|
169
|
-
- π **Cross-App Sessions** - Shared authentication across HOT tools
|
|
170
|
-
- π― **Framework Agnostic** - Works with React, Vue, vanilla JS, etc.
|
|
171
|
-
|
|
172
|
-
## How It Works
|
|
173
|
-
|
|
174
|
-
1. **Logged Out**: Displays a "Log in" button
|
|
175
|
-
2. **Click Login**: Redirects to `https://login.hotosm.org` for authentication
|
|
176
|
-
3. **After Login**: User returns to your app (or `redirect-after-login` URL)
|
|
177
|
-
4. **Logged In**: Shows user avatar with dropdown menu:
|
|
178
|
-
- My Profile (redirects to login service)
|
|
179
|
-
- OSM connection status
|
|
180
|
-
- Sign Out
|
|
181
|
-
|
|
182
|
-
## Browser Support
|
|
183
|
-
|
|
184
|
-
- Chrome/Edge (latest)
|
|
185
|
-
- Firefox (latest)
|
|
186
|
-
- Safari (latest)
|
|
187
|
-
|
|
188
|
-
## Development
|
|
189
|
-
|
|
190
|
-
```bash
|
|
191
|
-
# Install dependencies
|
|
192
|
-
pnpm install
|
|
193
|
-
|
|
194
|
-
# Build
|
|
195
|
-
pnpm build
|
|
196
|
-
|
|
197
|
-
# Development with hot reload
|
|
198
|
-
pnpm dev
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
## License
|
|
202
|
-
|
|
203
|
-
AGPL-3.0
|
|
204
|
-
|
|
205
|
-
## Links
|
|
206
|
-
|
|
207
|
-
- [Documentation](https://hotosm.github.io/auth-docs)
|
|
208
|
-
- [GitHub Repository](https://github.com/hotosm/login)
|
|
209
|
-
- [Issues](https://github.com/hotosm/login/issues)
|
|
210
|
-
- [HOTOSM Website](https://www.hotosm.org)
|