@owf/openid-federation 0.0.0-stage → 0.0.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 +198 -2
- package/dist/index.d.mts +3127 -0
- package/dist/index.mjs +1490 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +44 -4
package/README.md
CHANGED
|
@@ -1,3 +1,199 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @owf/openid-federation
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://npmjs.com/package/@owf/openid-federation)
|
|
4
|
+
[](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE)
|
|
5
|
+
|
|
6
|
+
[OpenID Federation 1.0](https://openid.net/specs/openid-federation-1_0.html): create, fetch and validate entity
|
|
7
|
+
configurations and subordinate statements, resolve trust chains to trust anchors, and apply metadata policies.
|
|
8
|
+
|
|
9
|
+
Signing and signature verification are callbacks, so private keys never enter the package and can stay in WebCrypto, a
|
|
10
|
+
KMS or an HSM. The package uses neither Node.js built-ins nor global crypto, so it runs on servers, in browsers and in
|
|
11
|
+
React Native.
|
|
12
|
+
|
|
13
|
+
Previously published as `@openid-federation/core` from
|
|
14
|
+
[openid-federation-ts](https://github.com/openwallet-foundation-labs/openid-federation-ts).
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @owf/openid-federation
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Callbacks
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
import type { SignCallback, VerifyCallback } from '@owf/openid-federation'
|
|
26
|
+
|
|
27
|
+
// Called with the JWS signing input and the JWK of the `kid` in the header. Return the JWS signature.
|
|
28
|
+
const signJwtCallback: SignCallback = async ({ toBeSigned, jwk }) => {
|
|
29
|
+
const privateKey = await getPrivateKey(jwk.kid)
|
|
30
|
+
return new Uint8Array(await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, privateKey, toBeSigned))
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// Called with the JWS signing input, the signature and the JWK the statement must be signed with
|
|
34
|
+
const verifyJwtCallback: VerifyCallback = async ({ data, signature, jwk }) => {
|
|
35
|
+
const publicKey = await crypto.subtle.importKey('jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, [
|
|
36
|
+
'verify',
|
|
37
|
+
])
|
|
38
|
+
return crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, publicKey, signature, data)
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Entity statements
|
|
43
|
+
|
|
44
|
+
### Creating an entity configuration
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
import { createEntityConfiguration } from '@owf/openid-federation'
|
|
48
|
+
|
|
49
|
+
const now = Math.floor(Date.now() / 1000)
|
|
50
|
+
|
|
51
|
+
// Serve it at `${entityId}/.well-known/openid-federation` as `application/entity-statement+jwt`
|
|
52
|
+
const entityConfigurationJwt = await createEntityConfiguration({
|
|
53
|
+
header: { kid: 'federation-key', typ: 'entity-statement+jwt', alg: 'ES256' },
|
|
54
|
+
claims: {
|
|
55
|
+
iss: 'https://rp.example.org',
|
|
56
|
+
sub: 'https://rp.example.org',
|
|
57
|
+
iat: now,
|
|
58
|
+
exp: now + 24 * 60 * 60,
|
|
59
|
+
jwks: { keys: [federationPublicJwk] },
|
|
60
|
+
authority_hints: ['https://intermediate.example.org'],
|
|
61
|
+
metadata: {
|
|
62
|
+
openid_relying_party: { client_name: 'Example RP', redirect_uris: ['https://rp.example.org/callback'] },
|
|
63
|
+
},
|
|
64
|
+
},
|
|
65
|
+
signJwtCallback,
|
|
66
|
+
})
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`iat`, `exp` and the other date claims are NumericDate values (seconds since the epoch). Parsed claims return them as
|
|
70
|
+
`Date` objects.
|
|
71
|
+
|
|
72
|
+
### Creating a subordinate statement
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
import { createEntityStatement } from '@owf/openid-federation'
|
|
76
|
+
|
|
77
|
+
// Serve it from the `federation_fetch_endpoint` of the issuer for `?sub=https://rp.example.org`
|
|
78
|
+
const subordinateStatementJwt = await createEntityStatement({
|
|
79
|
+
jwk: intermediateFederationJwk, // the issuer's key, used for the `kid` in the header
|
|
80
|
+
claims: {
|
|
81
|
+
iss: 'https://intermediate.example.org',
|
|
82
|
+
sub: 'https://rp.example.org',
|
|
83
|
+
iat: now,
|
|
84
|
+
exp: now + 24 * 60 * 60,
|
|
85
|
+
jwks: { keys: [federationPublicJwk] }, // the subject's federation keys
|
|
86
|
+
metadata_policy: {
|
|
87
|
+
openid_relying_party: { grant_types: { subset_of: ['authorization_code', 'refresh_token'] } },
|
|
88
|
+
},
|
|
89
|
+
},
|
|
90
|
+
signJwtCallback,
|
|
91
|
+
})
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Fetching
|
|
95
|
+
|
|
96
|
+
```typescript
|
|
97
|
+
import { fetchEntityConfiguration, fetchEntityStatement } from '@owf/openid-federation'
|
|
98
|
+
|
|
99
|
+
const entityConfiguration = await fetchEntityConfiguration({
|
|
100
|
+
entityId: 'https://intermediate.example.org',
|
|
101
|
+
verifyJwtCallback,
|
|
102
|
+
})
|
|
103
|
+
|
|
104
|
+
const subordinateStatement = await fetchEntityStatement({
|
|
105
|
+
iss: 'https://intermediate.example.org',
|
|
106
|
+
sub: 'https://rp.example.org',
|
|
107
|
+
issEntityConfiguration: entityConfiguration,
|
|
108
|
+
verifyJwtCallback,
|
|
109
|
+
})
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`fetchEntityConfiguration` checks that the entity configuration is about the requested entity and signed with one of its
|
|
113
|
+
own keys. `fetchEntityStatement` checks the `iss` and `sub` of the statement and its signature with the issuer's keys.
|
|
114
|
+
|
|
115
|
+
## Resolving trust chains
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
import { resolveTrustChains } from '@owf/openid-federation'
|
|
119
|
+
|
|
120
|
+
const trustChains = await resolveTrustChains({
|
|
121
|
+
entityId: 'https://rp.example.org',
|
|
122
|
+
trustAnchors: [{ entityId: 'https://ta.example.org', jwks: trustAnchorJwks }],
|
|
123
|
+
verifyJwtCallback,
|
|
124
|
+
fetchCallback, // optional, defaults to the global fetch
|
|
125
|
+
})
|
|
126
|
+
|
|
127
|
+
for (const { resolvedLeafMetadata, jwtChain, expiresAt } of trustChains) {
|
|
128
|
+
resolvedLeafMetadata?.openid_relying_party // metadata after the metadata policies of the chain are applied
|
|
129
|
+
jwtChain // leaf entity configuration, subordinate statements and trust anchor entity configuration as JWTs
|
|
130
|
+
expiresAt // earliest `exp` of the chain
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
The resolver follows the `authority_hints` of the leaf to the trust anchors and validates every path as described in
|
|
135
|
+
[Section 10](https://openid.net/specs/openid-federation-1_0.html#section-10):
|
|
136
|
+
|
|
137
|
+
- the signature of each statement with a key the next statement lists for its issuer, and of the last one with the
|
|
138
|
+
trust anchor's keys. Pass the trust anchor's `jwks`, obtained out of band, to check its entity configuration as well.
|
|
139
|
+
- `iat`, `exp` (`currentDate`, `clockSkewSeconds`) and `crit` (`understoodCriticalClaims`) of every statement.
|
|
140
|
+
- the claims each kind of statement may contain (Section 3.2).
|
|
141
|
+
- the `max_path_length` and `allowed_entity_types` constraints. Chains with `naming_constraints` are rejected, as they
|
|
142
|
+
are not evaluated.
|
|
143
|
+
- the metadata policies (Section 6), which are merged from the trust anchor down and applied to the leaf's metadata.
|
|
144
|
+
|
|
145
|
+
Trust marks are not verified.
|
|
146
|
+
|
|
147
|
+
The entity configurations name the URLs that are fetched. Pass a `fetchCallback` that applies your outbound request
|
|
148
|
+
policy (allowed hosts, timeouts, response size). `maxDepth` (default 8), `maxRequests` (default 64) and
|
|
149
|
+
`maxAuthorityHints` (default 10) bound the resolution.
|
|
150
|
+
|
|
151
|
+
`resolveTrustChainsWithFailures` also returns why each path was rejected:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { resolveTrustChainsWithFailures } from '@owf/openid-federation'
|
|
155
|
+
|
|
156
|
+
const { trustChains, failures } = await resolveTrustChainsWithFailures(options)
|
|
157
|
+
for (const { entityIds, reason } of failures) {
|
|
158
|
+
console.log(`${entityIds.join(' -> ')}: ${reason}`)
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Metadata policies
|
|
163
|
+
|
|
164
|
+
The policy functions the resolver uses are exported as well:
|
|
165
|
+
|
|
166
|
+
```typescript
|
|
167
|
+
import { applyMetadataPolicyToMetadata, combineMetadataPolicies } from '@owf/openid-federation'
|
|
168
|
+
|
|
169
|
+
// The subordinate statements of the chain, leaf side first
|
|
170
|
+
const { mergedPolicy } = combineMetadataPolicies({ statements })
|
|
171
|
+
const { resolvedLeafMetadata } = applyMetadataPolicyToMetadata({ leafMetadata, policyMetadata: mergedPolicy })
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The standard operators `value`, `add`, `default`, `one_of`, `subset_of`, `superset_of` and `essential` are supported.
|
|
175
|
+
Merging operators that conflict throws a `PolicyOperatorMergeError`, applying a policy the metadata does not satisfy
|
|
176
|
+
throws a `PolicyValidationError`.
|
|
177
|
+
|
|
178
|
+
## Platform Support
|
|
179
|
+
|
|
180
|
+
This library is **platform agnostic** and works in:
|
|
181
|
+
|
|
182
|
+
- ✅ Node.js (>=20)
|
|
183
|
+
- ✅ Browsers (modern browsers with ES2020 support)
|
|
184
|
+
- ✅ React Native
|
|
185
|
+
|
|
186
|
+
`TextEncoder`, `TextDecoder` and, unless a `fetchCallback` is passed, `fetch` must be available.
|
|
187
|
+
|
|
188
|
+
## Contributing
|
|
189
|
+
|
|
190
|
+
See the [Contributing Guide](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/CONTRIBUTING.md) for details on how to contribute to this project.
|
|
191
|
+
|
|
192
|
+
## License
|
|
193
|
+
|
|
194
|
+
This project is licensed under the [Apache License Version 2.0](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE) (Apache-2.0).
|
|
195
|
+
|
|
196
|
+
## Credits
|
|
197
|
+
|
|
198
|
+
This library was initially created by [Animo](https://animo.id) as part of the
|
|
199
|
+
[SPRIN-D EUDI Wallet Prototypes Funke](https://www.sprind.org/en/impulses/challenges/eudi-wallet-prototypes).
|