@owlmeans/server-oidc-rp 0.1.7 → 0.1.9
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
CHANGED
|
@@ -103,3 +103,20 @@ const oidc = context.service<OidcClientService>(OIDC_SERVICE)
|
|
|
103
103
|
- [`@owlmeans/server-auth`](../server-auth) — works alongside the OIDC guard for token verification
|
|
104
104
|
- [`@owlmeans/server-context`](../server-context) — base context where services are registered
|
|
105
105
|
- [`@owlmeans/auth-common`](../auth-common) — `DEFAULT_GUARD` co-attached via `setupOidcGuard`
|
|
106
|
+
|
|
107
|
+
<!-- owlmeans:agent-guidance:start -->
|
|
108
|
+
## Agent guidance
|
|
109
|
+
|
|
110
|
+
This package ships embedded Claude Code skills and GitHub Copilot instructions under
|
|
111
|
+
`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
|
|
112
|
+
agent-skills installer to place them into your project's native locations
|
|
113
|
+
(`.claude/skills/` and `.github/instructions/`):
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
npx @owlmeans/agent-skills
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The embedded files are version-matched to this package release. Do not edit them
|
|
120
|
+
directly — they are regenerated on each publish. To contribute guidance edits,
|
|
121
|
+
open a PR against the source monorepo.
|
|
122
|
+
<!-- owlmeans:agent-guidance:end -->
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "How to use @owlmeans/server-oidc-rp — OIDC relying party. appendOidcGuard(), makeOidcWrappingService(), makeOidcGate(), setupOidcGuard() to wire OIDC into a server context."
|
|
3
|
+
applyTo: "**/context.ts, **/modules.ts, **/*.ts, **/*.tsx"
|
|
4
|
+
---
|
|
5
|
+
<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
|
|
6
|
+
|
|
7
|
+
# @owlmeans/server-oidc-rp
|
|
8
|
+
|
|
9
|
+
**Layer:** Server
|
|
10
|
+
**Install:** `"@owlmeans/server-oidc-rp": "^0.1.9"` in `dependencies`
|
|
11
|
+
|
|
12
|
+
## Key Exports
|
|
13
|
+
|
|
14
|
+
| Export | Description |
|
|
15
|
+
|--------|-------------|
|
|
16
|
+
| `appendOidcGuard<C, T>(context)` | Add OIDC auth guard to context |
|
|
17
|
+
| `makeOidcWrappingService()` | OIDC token service factory |
|
|
18
|
+
| `makeOidcGate()` | OIDC gate factory (used by guards) |
|
|
19
|
+
| `setupOidcGuard(modules, options?)` | Wire OIDC guard onto modules |
|
|
20
|
+
| Constants | OIDC service / guard aliases |
|
|
21
|
+
| `OidcRp` types | RP-side config and token shapes |
|
|
22
|
+
|
|
23
|
+
## Subpath Exports
|
|
24
|
+
|
|
25
|
+
- `./auth`, `./auth/plugins`
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
// context.ts
|
|
31
|
+
import { appendOidcGuard, makeOidcWrappingService, makeOidcGate } from '@owlmeans/server-oidc-rp'
|
|
32
|
+
context.registerService(makeOidcWrappingService())
|
|
33
|
+
context.registerService(makeOidcGate())
|
|
34
|
+
appendOidcGuard<C, T>(context)
|
|
35
|
+
|
|
36
|
+
// modules.ts
|
|
37
|
+
import { setupOidcGuard } from '@owlmeans/server-oidc-rp'
|
|
38
|
+
setupOidcGuard(appModules)
|
|
39
|
+
|
|
40
|
+
// config.ts
|
|
41
|
+
cfg.oidc.providers.push({
|
|
42
|
+
clientId: OIDC_ADMIN_CLIENT,
|
|
43
|
+
basePath: 'realms/master',
|
|
44
|
+
service: OIDC_PRODUCT,
|
|
45
|
+
secret: '/etc/master-secret/oidc-admin-secret',
|
|
46
|
+
internal: true
|
|
47
|
+
})
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Product-Viable Usage Notes
|
|
51
|
+
|
|
52
|
+
- Viable uses `makeOidcClientService()` to read provider descriptors from `cfg.oidc.providers`, including Google and internal admin providers.
|
|
53
|
+
- `findProvider(predicate)`, `hasProvider(params)`, and `entityToClientId(params)` are the preferred provider lookup helpers; avoid scanning config ad hoc in downstream code.
|
|
54
|
+
- `setupAuthServiceModules(managerModules, AUTH_API)` exposes provider-list and token-update service modules protected by `GUARD_ED25519`.
|
|
55
|
+
- When a downstream app uses OIDC/Google only for login and maps users into `@owlmeans/server-auth-identity`, do not reintroduce `appendOidcGuard()`, `makeOidcGate()`, or `setupOidcGuard()` as product authorization. Use a product-specific `GateService` over local identity data.
|
|
56
|
+
|
|
57
|
+
## Integrated-IAM permissions claim (Phase 3)
|
|
58
|
+
|
|
59
|
+
- `extractPermissionSets(claim)` (exported) shape-validates a `permissions` token claim into
|
|
60
|
+
`PermissionSet[]`; non-conforming claims (e.g. anything Keycloak emits) return `undefined`.
|
|
61
|
+
- `authenticate` (actions/process.ts) maps a conforming id_token `permissions` claim into
|
|
62
|
+
`Auth.permissions` + `permissioned: true`; the wrapping service re-extracts it on token refresh.
|
|
63
|
+
- `createGateModel` is exported for `@owlmeans/server-iam`, whose `makeIamGate` asserts claims first
|
|
64
|
+
and falls back to this UMA2 model — registered under the same `OIDC_GATE` alias by `appendIam()`.
|
|
65
|
+
|
|
66
|
+
## Depends On
|
|
67
|
+
|
|
68
|
+
- `@owlmeans/oidc`, `@owlmeans/server-auth`, `@owlmeans/server-context`, `@owlmeans/server-entrypoint`, `@owlmeans/auth-common`, `@owlmeans/basic-keys`
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"package": "@owlmeans/server-oidc-rp",
|
|
4
|
+
"version": "0.1.9",
|
|
5
|
+
"generatedAt": "2026-06-14T13:34:06.134Z",
|
|
6
|
+
"canonicalRepo": "https://github.com/owlmeans/common",
|
|
7
|
+
"entries": [
|
|
8
|
+
{
|
|
9
|
+
"kind": "skill",
|
|
10
|
+
"name": "server-oidc-rp",
|
|
11
|
+
"category": "package-specific",
|
|
12
|
+
"file": "skills/server-oidc-rp/SKILL.md",
|
|
13
|
+
"canonicalPath": ".claude/skills/server-oidc-rp/SKILL.md"
|
|
14
|
+
},
|
|
15
|
+
{
|
|
16
|
+
"kind": "instruction",
|
|
17
|
+
"name": "server-oidc-rp",
|
|
18
|
+
"category": "package-specific",
|
|
19
|
+
"file": "instructions/server-oidc-rp.instructions.md",
|
|
20
|
+
"canonicalPath": ".github/instructions/server-oidc-rp.instructions.md"
|
|
21
|
+
}
|
|
22
|
+
]
|
|
23
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: server-oidc-rp
|
|
3
|
+
description: How to use @owlmeans/server-oidc-rp — OIDC relying party. appendOidcGuard(), makeOidcWrappingService(), makeOidcGate() to wire OIDC into a server context; setupOidcGuard() to attach the guard to module declarations. Auto-invoked when importing server-oidc-rp helpers.
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
|
|
7
|
+
|
|
8
|
+
# @owlmeans/server-oidc-rp
|
|
9
|
+
|
|
10
|
+
**Layer:** Server
|
|
11
|
+
**Install:** `"@owlmeans/server-oidc-rp": "^0.1.9"` in `dependencies`
|
|
12
|
+
|
|
13
|
+
## Key Exports
|
|
14
|
+
|
|
15
|
+
| Export | Description |
|
|
16
|
+
|--------|-------------|
|
|
17
|
+
| `appendOidcGuard<C, T>(context)` | Add OIDC auth guard to context |
|
|
18
|
+
| `makeOidcWrappingService()` | OIDC token service factory |
|
|
19
|
+
| `makeOidcGate()` | OIDC gate factory (used by guards) |
|
|
20
|
+
| `setupOidcGuard(modules, options?)` | Wire OIDC guard onto module declarations |
|
|
21
|
+
| Constants | OIDC service / guard aliases |
|
|
22
|
+
| `OidcRp` types | RP-side config and token shapes |
|
|
23
|
+
|
|
24
|
+
## Subpath Exports
|
|
25
|
+
|
|
26
|
+
- `./auth` — auth integration helpers
|
|
27
|
+
- `./auth/plugins` — pluggable token verifiers
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
### In `context.ts`
|
|
32
|
+
```typescript
|
|
33
|
+
import { appendOidcGuard, makeOidcWrappingService, makeOidcGate } from '@owlmeans/server-oidc-rp'
|
|
34
|
+
|
|
35
|
+
context.registerService(makeOidcWrappingService())
|
|
36
|
+
context.registerService(makeOidcGate())
|
|
37
|
+
appendOidcGuard<C, T>(context)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### In `modules.ts`
|
|
41
|
+
```typescript
|
|
42
|
+
import { setupOidcGuard } from '@owlmeans/server-oidc-rp'
|
|
43
|
+
setupOidcGuard(appModules)
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Configure OIDC providers in `config.ts`
|
|
47
|
+
```typescript
|
|
48
|
+
cfg.oidc ??= {}
|
|
49
|
+
cfg.oidc.providers ??= []
|
|
50
|
+
cfg.oidc.providers.push({
|
|
51
|
+
clientId: OIDC_ADMIN_CLIENT,
|
|
52
|
+
basePath: 'realms/master',
|
|
53
|
+
service: OIDC_PRODUCT,
|
|
54
|
+
secret: '/etc/master-secret/oidc-admin-secret',
|
|
55
|
+
internal: true
|
|
56
|
+
})
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Product-Viable Usage Notes
|
|
60
|
+
|
|
61
|
+
- Viable uses `makeOidcClientService()` to read provider descriptors from `cfg.oidc.providers`, including Google and internal admin providers.
|
|
62
|
+
- `findProvider(predicate)`, `hasProvider(params)`, and `entityToClientId(params)` are the preferred provider lookup helpers; avoid scanning config ad hoc in downstream code.
|
|
63
|
+
- `setupAuthServiceModules(managerModules, AUTH_API)` exposes provider-list and token-update service modules protected by `GUARD_ED25519`.
|
|
64
|
+
- When a downstream app uses OIDC/Google only for login and maps users into `@owlmeans/server-auth-identity`, do not reintroduce `appendOidcGuard()`, `makeOidcGate()`, or `setupOidcGuard()` as product authorization. Use a product-specific `GateService` over local identity data.
|
|
65
|
+
|
|
66
|
+
## Public type contract (isolation principle)
|
|
67
|
+
|
|
68
|
+
`openid-client` types **never appear in this package's public exports**. All public types are OwlMeans-owned:
|
|
69
|
+
|
|
70
|
+
| Owned type | Replaces upstream | Description |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| `OidcTokenSet` | `TokenEndpointResponse & TokenEndpointResponseHelpers` | `access_token`, `refresh_token`, `id_token`, `token_type`, `expires_in`, `scope` |
|
|
73
|
+
| `OidcTokenSetParameters` | `TokenEndpointResponse` | Subset without helper methods |
|
|
74
|
+
| `OidcGrantChecks` | `AuthorizationCodeGrantChecks` | `{ pkceCodeVerifier?: string; idTokenExpected?: boolean }` |
|
|
75
|
+
| `OidcServerMetadata` | `ServerMetadata` | Issuer and endpoint metadata |
|
|
76
|
+
| `OidcIntrospectionResponse` | `IntrospectionResponse` | Active, scope, sub, client_id |
|
|
77
|
+
| `OidcClientDescriptor` | `Configuration` (opaque) | Pass-through; consumers must never read its internals |
|
|
78
|
+
|
|
79
|
+
Upstream `openid-client` types are imported **only** in `src/service.ts`; mappings happen at the method boundaries. This keeps future library swaps confined to that one file.
|
|
80
|
+
|
|
81
|
+
## Depends On
|
|
82
|
+
|
|
83
|
+
- `@owlmeans/oidc`, `@owlmeans/server-auth`, `@owlmeans/server-context`, `@owlmeans/server-entrypoint`
|
|
84
|
+
- `@owlmeans/auth-common`, `@owlmeans/basic-keys`
|
|
85
|
+
- `openid-client@6.8.4` (exact), `jose@6.2.3` (exact) — see [[oidc-versions]]
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@owlmeans/server-oidc-rp",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.9",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
39
|
"@owlmeans/dep-config": "workspace:*",
|
|
40
|
-
"@owlmeans/test-auth": "^0.1.
|
|
40
|
+
"@owlmeans/test-auth": "^0.1.9",
|
|
41
41
|
"@types/bun": "^1.3.0",
|
|
42
42
|
"@types/node": "^24.10.1",
|
|
43
43
|
"nodemon": "^3.1.11",
|
|
@@ -46,21 +46,21 @@
|
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
48
|
"@noble/hashes": "^1.5.0",
|
|
49
|
-
"@owlmeans/auth": "^0.1.
|
|
50
|
-
"@owlmeans/auth-common": "^0.1.
|
|
51
|
-
"@owlmeans/basic-envelope": "^0.1.
|
|
52
|
-
"@owlmeans/client-entrypoint": "^0.1.
|
|
53
|
-
"@owlmeans/config": "^0.1.
|
|
54
|
-
"@owlmeans/context": "^0.1.
|
|
55
|
-
"@owlmeans/did": "^0.1.
|
|
56
|
-
"@owlmeans/entrypoint": "^0.1.
|
|
57
|
-
"@owlmeans/oidc": "^0.1.
|
|
58
|
-
"@owlmeans/resource": "^0.1.
|
|
59
|
-
"@owlmeans/route": "^0.1.
|
|
60
|
-
"@owlmeans/server-api": "^0.1.
|
|
61
|
-
"@owlmeans/server-auth": "^0.1.
|
|
62
|
-
"@owlmeans/server-context": "^0.1.
|
|
63
|
-
"@owlmeans/server-entrypoint": "^0.1.
|
|
49
|
+
"@owlmeans/auth": "^0.1.9",
|
|
50
|
+
"@owlmeans/auth-common": "^0.1.9",
|
|
51
|
+
"@owlmeans/basic-envelope": "^0.1.9",
|
|
52
|
+
"@owlmeans/client-entrypoint": "^0.1.9",
|
|
53
|
+
"@owlmeans/config": "^0.1.9",
|
|
54
|
+
"@owlmeans/context": "^0.1.9",
|
|
55
|
+
"@owlmeans/did": "^0.1.9",
|
|
56
|
+
"@owlmeans/entrypoint": "^0.1.9",
|
|
57
|
+
"@owlmeans/oidc": "^0.1.9",
|
|
58
|
+
"@owlmeans/resource": "^0.1.9",
|
|
59
|
+
"@owlmeans/route": "^0.1.9",
|
|
60
|
+
"@owlmeans/server-api": "^0.1.9",
|
|
61
|
+
"@owlmeans/server-auth": "^0.1.9",
|
|
62
|
+
"@owlmeans/server-context": "^0.1.9",
|
|
63
|
+
"@owlmeans/server-entrypoint": "^0.1.9",
|
|
64
64
|
"@scure/base": "^1.1.9",
|
|
65
65
|
"dayjs": "^1.11.13",
|
|
66
66
|
"jose": "6.2.3",
|