@owlmeans/server-oidc-provider 0.1.7 → 0.1.9

package/README.md

@@ -63,3 +63,20 @@ Returns middleware that mounts the OIDC authorize/token/userinfo/jwks endpoints
 - [`@owlmeans/server-oidc-rp`](../server-oidc-rp) — relying-party counterpart for consuming external IdPs
 - [`@owlmeans/server-api`](../server-api) — the underlying server API the middleware mounts onto
 - [`@owlmeans/web-oidc-provider`](../web-oidc-provider) — browser UI for the provider's interaction screens
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/server-oidc-provider.instructions.md

@@ -0,0 +1,41 @@
+---
+description: "How to use @owlmeans/server-oidc-provider — embedded OIDC identity provider built on the oidc-provider library."
+applyTo: "**/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/server-oidc-provider
+
+**Layer:** Server
+**Install:** `"@owlmeans/server-oidc-provider": "^0.1.9"` in `dependencies`
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makeOidcProviderService()` | Factory for the OIDC provider service |
+| Middleware | OIDC endpoints |
+| Constants | Endpoint paths, default scopes |
+| `OidcProvider` types | Provider config shape |
+
+## Usage
+
+```typescript
+import { makeOidcProviderService } from '@owlmeans/server-oidc-provider'
+context.registerService(makeOidcProviderService())
+```
+
+For consuming an external IdP instead, use `@owlmeans/server-oidc-rp`.
+
+## Permissions claim seam (integrated IAM)
+
+- `findAccount` threads the requesting `clientId` into `OidcAccountService.loadById(ctx, id, { clientId })`
+  (`OidcAccountParams`) so the account service can scope claims per client.
+- `combineConfig` registers the `permissions` scope and the `permissions → [permissions]` claim mapping
+  by default (consts from `@owlmeans/oidc`); this is inert unless the account service emits the claim.
+- To mint the claim into the id_token set `customConfiguration.conformIdTokenClaims: false` and return
+  `permissions: PermissionSet[]` from the account's `claims()` when the scope includes `permissions`.
+
+## Depends On
+
+- `@owlmeans/oidc`, `@owlmeans/server-api`, `@owlmeans/server-context`, `oidc-provider`

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/server-oidc-provider",
+  "version": "0.1.9",
+  "generatedAt": "2026-06-14T13:34:06.137Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "server-oidc-provider",
+      "category": "package-specific",
+      "file": "skills/server-oidc-provider/SKILL.md",
+      "canonicalPath": ".claude/skills/server-oidc-provider/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "server-oidc-provider",
+      "category": "package-specific",
+      "file": "instructions/server-oidc-provider.instructions.md",
+      "canonicalPath": ".github/instructions/server-oidc-provider.instructions.md"
+    }
+  ]
+}

package/agent-meta/skills/server-oidc-provider/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: server-oidc-provider
+description: How to use @owlmeans/server-oidc-provider — embedded OIDC identity provider built on the oidc-provider library. Auto-invoked when serving OIDC endpoints from your own service.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/server-oidc-provider
+
+**Layer:** Server
+**Install:** `"@owlmeans/server-oidc-provider": "^0.1.9"` in `dependencies`
+**Runtime deps:** `oidc-provider@9.8.4` (exact), `jose@6.2.3` (exact)
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `createOidcProviderService(alias?)` | Factory for the embedded OIDC provider service |
+| `appendOidcProviderService<C,T>(ctx, alias?)` | Register the provider service on a context |
+| Constants | `DEFAULT_ALIAS`, `OIDC_ACCOUNT_SERVICE` |
+| Types | `OidcProviderService`, `OidcAccountService`, `OidcAdapterService`, `Config`, `Context` |
+
+## Usage
+
+Use this only when your service IS the identity provider (e.g. self-hosted Keycloak alternative). For consuming an external IdP, use `@owlmeans/server-oidc-rp`.
+
+```typescript
+import { appendOidcProviderService } from '@owlmeans/server-oidc-provider'
+appendOidcProviderService<C, T>(context)
+```
+
+The service mounts the oidc-provider Koa app onto Fastify via `api.server.use(base, oidc.callback())`. It wires `findAccount`, `interactions.url`, the JWKS, and optional adapter.
+
+## oidc-provider v9 notes (important)
+
+- **Provider is a Koa app instance.** `oidc.use()` callbacks where the work happens *after* `await next()` will **not** fire once a route is matched — Koa's downstream does not continue past matched routes in v9. Move post-response header work (e.g. CSP rewrites) to a **Fastify `onSend`/`preHandler` hook** scoped to the OIDC base path.
+- **`enableHttpPostMethods`** defaults `false` — set it in the Provider config if your interaction UI POSTs to the authorization/end-session endpoints.
+- **DPoP is enabled by default.** Add `features: { dPoP: { enabled: false } }` if RP clients do not send DPoP proofs.
+- **Cookie `sameSite` defaults to `lax`** (was `none`). Adjust `cookies.*.sameSite` if the interaction UI is on a different subdomain.
+- **JWKS `kid` must be unique.** Every key in `jwks.keys` needs a distinct `kid`.
+- **Node 22+** required.
+
+## jose v6 notes
+
+`importPKCS8` now returns a **non-extractable `CryptoKey`** by default. Pass `{ extractable: true }` so `exportJWK` succeeds:
+
+```typescript
+const key = await jose.importPKCS8(pkcs8Pem, 'RS256', { extractable: true })
+const jwk = await jose.exportJWK(key)
+```
+
+## Depends On
+
+- `@owlmeans/oidc`, `@owlmeans/server-api`, `@owlmeans/server-context`
+- `oidc-provider` v9, `jose` v6 (runtime — see [[oidc-versions]] for pinned versions and upgrade checklist)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-oidc-provider",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/context": "^0.1.7",
+    "@owlmeans/context": "^0.1.9",
     "@types/bun": "^1.3.0",
     "@types/node": "^24.10.1",
     "@types/oidc-provider": "9.5.0",
@@ -36,13 +36,13 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/client-entrypoint": "^0.1.7",
-    "@owlmeans/config": "^0.1.7",
-    "@owlmeans/context": "^0.1.7",
-    "@owlmeans/oidc": "^0.1.7",
-    "@owlmeans/route": "^0.1.7",
-    "@owlmeans/server-api": "^0.1.7",
-    "@owlmeans/server-context": "^0.1.7",
+    "@owlmeans/client-entrypoint": "^0.1.9",
+    "@owlmeans/config": "^0.1.9",
+    "@owlmeans/context": "^0.1.9",
+    "@owlmeans/oidc": "^0.1.9",
+    "@owlmeans/route": "^0.1.9",
+    "@owlmeans/server-api": "^0.1.9",
+    "@owlmeans/server-context": "^0.1.9",
     "@scure/base": "^1.1.9",
     "jose": "6.2.3",
     "oidc-provider": "9.8.4"