Add option to use custom webId

README.md

@@ -13,9 +13,9 @@ There are three endpoints that need to be set up:
 
 - `/.well-known/openid-configuration`
 - `/path/to/jwks`
-- `/path/to/webId`
+- `/path/to/webId` - unless you want to use custom webId
 
-For more details, you can check the output of `getEndpoints(webId)` from the `@soid/core` package.
+For more details, you can check the output of `getEndpoints(webId: string, issuer?: string)` from the `@soid/core` package.
 
 ## Limitations
 

packages/core/README.md

@@ -2,12 +2,35 @@
 
 Give your Solid service a Solid-OIDC-compatible identity.
 
+## Overview
+
+This library:
+
+- tells you which endpoints your service has to serve: `getEndpoints(webId: string, issuer?: string)`
+- provides authenticated fetch that your service can use to access protected resources: `await getAuthenticatedFetch(webId: string, issuer?: string)`
+
+Please consider using higher-level libraries like [`@soid/koa`](https://npmjs.com/package/@soid/koa).
+
 ## Usage
 
+### Installation
+
+```bash
+npm install --save @soid/core
+# or
+yarn add @soid/core
+```
+
+### Identity for service's own webId
+
+By default, your service can serve its own webId.
+
 ```ts
 import { getEndpoints, getAuthenticatedFetch } from '@soid/core'
 
+// The webId's origin has to match the service's origin
 const webId = 'https://service.example/profile/card#bot'
+
 // Get authenticated fetch to make requests with this identity
 const authenticatedFetch = await getAuthenticatedFetch(webId)
 
@@ -24,4 +47,21 @@ const endpoints = getEndpoints(webId)
 // }]
 ```
 
-Please consider using higher-level libraries like [`@soid/koa`](https://npmjs.com/package/@soid/koa).
+### Identity for custom webId
+
+You can also authenticate your service with custom webId, such as your personal webId.
+
+You MUST add triple `<webId> solid:oidcIssuer <issuer>.` to your webId, where `issuer` MUST match the origin of the service. (no trailing slashes!)
+
+```ts
+import { getEndpoints, getAuthenticatedFetch } from '@soid/core'
+
+const webId = 'https://custom.webid/profile/card#me' // you'll have to serve this somewhere, and add the required triple
+const issuer = 'https://service.example' // this has to match your service's origin
+
+// Get authenticated fetch to make requests with this identity
+const authenticatedFetch = await getAuthenticatedFetch(webId, issuer)
+
+// Get configuration of endpoints that your service MUST serve
+const endpoints = getEndpoints(webId, issuer)
+```

packages/core/src/endpoints.ts

@@ -7,17 +7,22 @@ export interface Endpoint {
   defaultContentType: string
 }
 
-export const getEndpoints = (webId: string): Endpoint[] => {
+export const getEndpoints = (webId: string, issuer?: string): Endpoint[] => {
   const { pathname, hash, origin } = new URL(webId)
 
-  return [
+  issuer = issuer ? new URL(issuer).origin : origin
+
+  // make sure that issuer doesn't contain any unwanted paths etc.
+  issuer = new URL(issuer).origin
+
+  const endpoints: Endpoint[] = [
     {
       method: 'get',
       path: '/.well-known/openid-configuration',
       body: {
         'application/json': {
-          issuer: origin,
-          jwks_uri: new URL('/jwks', webId).toString(),
+          issuer,
+          jwks_uri: new URL('/jwks', issuer).toString(),
           response_types_supported: ['id_token', 'token'],
           scopes_supported: ['openid', 'webid'],
         },
@@ -30,7 +35,10 @@ export const getEndpoints = (webId: string): Endpoint[] => {
       body: { 'application/json': { keys: [fullJwkPublicKey] } },
       defaultContentType: 'application/json',
     },
-    {
+  ]
+
+  if (issuer === origin) {
+    endpoints.push({
       method: 'get',
       path: pathname,
       body: {
@@ -46,6 +54,8 @@ export const getEndpoints = (webId: string): Endpoint[] => {
       },
       // TODO add application/ld+json
       defaultContentType: 'text/turtle',
-    },
-  ]
+    })
+  }
+
+  return endpoints
 }

packages/core/src/identity.ts

@@ -22,8 +22,11 @@ export const fullJwkPublicKey = {
 
 export const getAuthenticatedFetch = async (
   webId: string,
+  issuer?: string,
 ): Promise<typeof globalThis.fetch> => {
-  const { origin: baseUrl } = new URL(webId)
+  const { origin } = new URL(webId)
+
+  issuer = issuer ? new URL(issuer).origin : origin
   const dpopKey = await generateDpopKeyPair()
 
   const jkt = await calculateJwkThumbprint(
@@ -42,7 +45,7 @@ export const getAuthenticatedFetch = async (
     .setIssuedAt(now)
     .setExpirationTime(now + 3600)
     .setAudience('solid')
-    .setIssuer(baseUrl)
+    .setIssuer(issuer)
     .setJti(randomUUID())
     .sign(tokenKeyPair.privateKey)
 

packages/core/src/index.ts

@@ -1,5 +1,2 @@
-export {
-  fullJwkPublicKey as jwkPublicKey,
-  getAuthenticatedFetch,
-} from './identity.js'
 export { getEndpoints, type Endpoint } from './endpoints.js'
+export { getAuthenticatedFetch } from './identity.js'

packages/koa/README.md

@@ -2,13 +2,35 @@
 
 Give your koa-based Solid service a Solid-OIDC-compatible identity.
 
+## Overview
+
+This library provides:
+
+- identity-serving middleware for your koa-based service: `solidIdentity(webId: string, issuer?: string)`
+- authenticated fetch that your service can use to access protected resources: `await getAuthenticatedFetch(webId: string, issuer?: string)`
+
+If you want to serve identity for a koa-incompatible service, consider using lower level [`@soid/core`](https://npmjs.com/package/@soid/core), or [open an issue](https://github.com/solidcouch/solid-identity/issues).
+
 ## Usage
 
+### Installation
+
+```bash
+npm install --save @soid/koa
+# or
+yarn add @soid/koa
+```
+
+### Identity for service's own webId
+
+By default, your service can serve its own webId.
+
 ```ts
 import Koa from 'koa'
 import Router from '@koa/router'
 import { solidIdentity, getAuthenticatedFetch } from '@soid/koa'
 
+// The webId origin MUST match your service origin
 const webId = 'https://service.example/profile/card#bot'
 
 const app = new Koa()
@@ -19,8 +41,38 @@ router.use(solidIdentity(webId).routes())
 // register your other routes
 // ...
 
-app.use(router)
+app.use(router.routes()).use(router.allowedMethods())
 
 // use the authenticated fetch to make authenticated requests to Solid Pods or other Solid-compatible services
 const fetch = getAuthenticatedFetch(webId)
 ```
+
+### Identity for custom webId
+
+You can also authenticate your service with custom webId (for example your own webId)
+
+You MUST add triple `<webId> solid:oidcIssuer <issuer>.` to your webId, where `issuer` MUST match the origin of the service. (no trailing slashes!)
+
+```ts
+import Koa from 'koa'
+import Router from '@koa/router'
+import { solidIdentity, getAuthenticatedFetch } from '@soid/koa'
+
+// The webId must serve a profile in text/turtle, and has to contain the required triple pointing to the issuer
+const webId = 'https://custom.webid/profile/card#me'
+// The issuer has to match your service's origin
+const issuer = 'https://service.example'
+
+const app = new Koa()
+const router = new Router()
+
+// register the identity middleware in your router
+router.use(solidIdentity(webId, issuer).routes())
+// register your other routes
+// ...
+
+app.use(router.routes()).use(router.allowedMethods())
+
+// use the authenticated fetch to make authenticated requests to Solid Pods or other Solid-compatible services
+const fetch = getAuthenticatedFetch(webId, issuer)
+```

packages/koa/package.json

@@ -66,6 +66,7 @@
     "@types/koa__router": "^12.0.4",
     "css-authn": "^0.0.16",
     "koa": "^2.15.3",
+    "msw": "^2.6.0",
     "rdf-namespaces": "^1.12.0",
     "typescript": "^5.6.2",
     "vitest": "^2.1.4"

packages/koa/src/index.ts

@@ -2,10 +2,10 @@ import Router from '@koa/router'
 import { getEndpoints } from '@soid/core'
 export { getAuthenticatedFetch } from '@soid/core'
 
-export const solidIdentity = (identity: string) => {
+export const solidIdentity = (webId: string, issuer?: string) => {
   const router = new Router()
 
-  const endpoints = getEndpoints(identity)
+  const endpoints = getEndpoints(webId, issuer)
 
   for (const endpoint of endpoints) {
     router[endpoint.method](endpoint.path, async ctx => {