Skip to content

Commit 7eade9a

Browse files
melvincarvalhomelvincarvalho
committed
v0.0.2: Improve README and update providers
- Add badges (npm, license, zero-dependencies) - Add "Why solid-oidc?" comparison table - Link to live demo at top - Better section organization with dividers - Update provider list (remove Inrupt, add solidweb.me)
1 parent 5c5f5d5 commit 7eade9a

File tree

3 files changed

+81
-39
lines changed

3 files changed

+81
-39
lines changed

‎README.md‎

Lines changed: 79 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,37 @@
11
# solid-oidc
22

3-
Minimal, zero-build Solid-OIDC client for browsers.
3+
[![npm version](https://img.shields.io/npm/v/solid-oidc.svg)](https://www.npmjs.com/package/solid-oidc)
4+
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5+
[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#)
46

5-
A single JavaScript file (~500 lines) that handles the complete Solid-OIDC authentication flow. No bundler, no transpiler, no build step required.
7+
**Minimal, zero-build Solid-OIDC client for browsers.**
8+
9+
A single JavaScript file (~600 lines) that handles the complete Solid-OIDC authentication flow. No bundler, no transpiler, no build step required.
10+
11+
[**Live Demo**](https://javascriptsolidserver.github.io/solid-oidc/example.html) · [**API Reference**](#api-reference) · [**Examples**](#advanced-usage)
12+
13+
---
14+
15+
## Why solid-oidc?
16+
17+
| Feature | solid-oidc | Other libraries |
18+
|---------|------------|-----------------|
19+
| **Size** | ~600 lines | 5,000+ lines |
20+
| **Build step** | None | Required |
21+
| **Copy-paste ready** | Yes | No |
22+
| **Readable source** | Yes | Compiled/minified |
623

724
## Features
825

9-
- **Zero build step** - Just import and use
10-
- **Single file** - Copy `solid-oidc.js` or import from CDN
11-
- **~500 lines** - Readable, auditable, hackable
12-
- **Full Solid-OIDC** - Login, logout, token refresh, authenticated fetch
13-
- **DPoP bound tokens** - Secure proof-of-possession
14-
- **Persistent sessions** - Survives page refresh via IndexedDB
15-
- **Event-driven** - React to session state changes
26+
- **Zero build step** — Import from CDN or copy the file
27+
- **Single file** — One `solid-oidc.js`, nothing else
28+
- **~600 lines** — Readable, auditable, hackable
29+
- **Full Solid-OIDC** — Login, logout, token refresh, authenticated fetch
30+
- **DPoP bound tokens** — Secure proof-of-possession (RFC 9449)
31+
- **Persistent sessions** — Survives page refresh via IndexedDB
32+
- **Event-driven** — React to session state changes
33+
34+
---
1635

1736
## Quick Start
1837

@@ -60,6 +79,10 @@ A single JavaScript file (~500 lines) that handles the complete Solid-OIDC authe
6079
</html>
6180
```
6281

82+
**That's it.** No npm install, no webpack, no configuration.
83+
84+
---
85+
6386
## Installation
6487

6588
### Option 1: CDN (Recommended)
@@ -80,12 +103,14 @@ import { Session } from 'solid-oidc'
80103

81104
### Option 3: Copy the file
82105

83-
Just copy `solid-oidc.js` into your project and import it:
106+
Download [`solid-oidc.js`](solid-oidc.js) and import it directly:
84107

85108
```js
86109
import { Session } from './solid-oidc.js'
87110
```
88111

112+
---
113+
89114
## API Reference
90115

91116
### `new Session(options)`
@@ -115,9 +140,10 @@ Redirect user to identity provider for authentication.
115140
await session.login('https://solidcommunity.net', window.location.href)
116141
```
117142

118-
**Parameters:**
119-
- `idp` - Identity provider URL (e.g., `https://solidcommunity.net`)
120-
- `redirectUri` - URL to redirect back to after login
143+
| Parameter | Description |
144+
|-----------|-------------|
145+
| `idp` | Identity provider URL (e.g., `https://solidcommunity.net`) |
146+
| `redirectUri` | URL to redirect back to after login |
121147

122148
### `session.handleRedirectFromLogin()`
123149

@@ -181,7 +207,7 @@ The session extends `EventTarget` and emits these events:
181207
|-------|--------|-------------|
182208
| `sessionStateChange` | `{ isActive, webId }` | Login/logout occurred |
183209
| `sessionExpirationWarning` | `{ expires_in }` | Token refresh failed but not expired |
184-
| `sessionExpiration` | - | Token expired and refresh failed |
210+
| `sessionExpiration` | — | Token expired and refresh failed |
185211

186212
```js
187213
session.addEventListener('sessionStateChange', (event) => {
@@ -190,6 +216,8 @@ session.addEventListener('sessionStateChange', (event) => {
190216
})
191217
```
192218

219+
---
220+
193221
## Advanced Usage
194222

195223
### Custom Session Database
@@ -204,7 +232,7 @@ const session = new Session({ database })
204232

205233
### Pre-registered Client ID
206234

207-
If your app has a pre-registered client ID, provide it to skip dynamic registration:
235+
Skip dynamic registration by providing your client ID:
208236

209237
```js
210238
const session = new Session({
@@ -217,8 +245,8 @@ const session = new Session({
217245
```js
218246
const providers = [
219247
{ name: 'Solid Community', url: 'https://solidcommunity.net' },
220-
{ name: 'Inrupt PodSpaces', url: 'https://login.inrupt.com' },
221-
{ name: 'solidweb.org', url: 'https://solidweb.org' }
248+
{ name: 'solidweb.org', url: 'https://solidweb.org' },
249+
{ name: 'solidweb.me', url: 'https://solidweb.me' }
222250
]
223251

224252
// Let user choose
@@ -235,7 +263,6 @@ const session = new Session({
235263
try {
236264
await session.restore()
237265
} catch {
238-
// Refresh failed, maybe prompt re-login
239266
if (confirm('Session expired. Login again?')) {
240267
await session.login(idp, window.location.href)
241268
}
@@ -244,39 +271,54 @@ const session = new Session({
244271
})
245272
```
246273

247-
## Specifications Implemented
274+
---
275+
276+
## Specifications
248277

249-
- [RFC 6749](https://tools.ietf.org/html/rfc6749) - OAuth 2.0
250-
- [RFC 7636](https://tools.ietf.org/html/rfc7636) - PKCE
251-
- [RFC 9207](https://tools.ietf.org/html/rfc9207) - Authorization Server Issuer Identification
252-
- [RFC 9449](https://tools.ietf.org/html/rfc9449) - DPoP (Demonstration of Proof-of-Possession)
253-
- [Solid-OIDC](https://solidproject.org/TR/oidc) - Solid OIDC Specification
278+
This library implements:
279+
280+
| Specification | Description |
281+
|---------------|-------------|
282+
| [RFC 6749](https://tools.ietf.org/html/rfc6749) | OAuth 2.0 |
283+
| [RFC 7636](https://tools.ietf.org/html/rfc7636) | PKCE |
284+
| [RFC 9207](https://tools.ietf.org/html/rfc9207) | Authorization Server Issuer Identification |
285+
| [RFC 9449](https://tools.ietf.org/html/rfc9449) | DPoP (Demonstration of Proof-of-Possession) |
286+
| [Solid-OIDC](https://solidproject.org/TR/oidc) | Solid OIDC Specification |
287+
288+
---
254289

255290
## Testing
256291

257-
Open `test.html` in a browser to run the test suite. Tests cover:
258-
- Session instantiation and state management
259-
- SessionDatabase (IndexedDB) operations
260-
- Event dispatching
292+
Open [`test.html`](test.html) in a browser to run the test suite:
261293

262294
```bash
263-
# Serve locally and open test.html
264295
npx serve .
265-
# Then visit http://localhost:3000/test.html
296+
# Visit http://localhost:3000/test.html
266297
```
267298

268-
## Browser Requirements
299+
Tests cover:
300+
- Session instantiation and state management
301+
- SessionDatabase (IndexedDB) operations
302+
- Event dispatching
303+
304+
---
305+
306+
## Browser Support
307+
308+
| Requirement | Notes |
309+
|-------------|-------|
310+
| ES Modules | `<script type="module">` |
311+
| `crypto.subtle` | Requires HTTPS or localhost |
312+
| `indexedDB` | For session persistence |
269313

270-
- ES Modules (`<script type="module">`)
271-
- `crypto.subtle` (requires HTTPS or localhost)
272-
- `indexedDB` (for session persistence)
314+
**Supported browsers:** Chrome 63+, Firefox 57+, Safari 11+, Edge 79+
273315

274-
Works in all modern browsers (Chrome 63+, Firefox 57+, Safari 11+, Edge 79+).
316+
---
275317

276318
## Credits
277319

278-
Based on [solid-oidc-client-browser](https://github.com/uvdsl/solid-oidc-client-browser) by [uvdsl (Christoph Braun)](https://github.com/uvdsl). Refactored into a minimal, zero-dependency, single-file library.
320+
Based on [solid-oidc-client-browser](https://github.com/uvdsl/solid-oidc-client-browser) by [uvdsl (Christoph Braun)](https://github.com/uvdsl). Refactored into a minimal, zero-build, single-file library.
279321

280322
## License
281323

282-
MIT
324+
[MIT](LICENSE)

‎example.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ <h1>Solid-OIDC Demo</h1>
7979
<label for="idp">Identity Provider</label>
8080
<select id="idp">
8181
<option value="https://solidcommunity.net">solidcommunity.net</option>
82-
<option value="https://login.inrupt.com">login.inrupt.com</option>
8382
<option value="https://solidweb.org">solidweb.org</option>
83+
<option value="https://solidweb.me">solidweb.me</option>
8484
<option value="custom">Custom...</option>
8585
</select>
8686
<input type="url" id="custom-idp" placeholder="https://your-provider.example" hidden>

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "solid-oidc",
3-
"version": "0.0.1",
3+
"version": "0.0.2",
44
"description": "Minimal, zero-build Solid-OIDC client for browsers",
55
"type": "module",
66
"main": "solid-oidc.js",

0 commit comments

Comments
 (0)