@owf/eudi-registration-certificate 0.0.0-stage → 0.4.2

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
@@ -1,3 +1,363 @@
1
- # Temporary Holding Version
1
+ # @owf/eudi-registration-certificate
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/@owf/eudi-registration-certificate)](https://npmjs.com/package/@owf/eudi-registration-certificate)
4
+ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/openwallet-foundation-labs/identity-common-ts/blob/main/LICENSE)
5
+
6
+ Implementation of **ETSI TS 119 475 v1.2.1** - Wallet-Relying Party Registration Certificates (WRPRC) for [Identity Common TypeScript](https://github.com/openwallet-foundation-labs/identity-common-ts).
7
+
8
+ ## Spec fidelity
9
+
10
+ This library follows ETSI TS 119 475 v1.2.1 **literally**, including its known editorial defects. The specification is referenced by the eIDAS 2 implementing acts, and other SDKs implement it as written, so reproducing it verbatim is what makes WRPRCs interoperable. Where the text is inconsistent, the **normative tables in clause 5** take precedence over the informative Annex C example.
11
+
12
+ Known defects that this library reproduces on purpose:
13
+
14
+ | Where | What the spec says | Note |
15
+ |-------|--------------------|------|
16
+ | Tables 8 and 9, Annex B.2.9 | The array of claim queries inside a `Credential` is named `claim` (singular) | Reads as a typo for `claims`, but it is consistent across the normative tables, Annex B and the Annex C example, so `claim` is emitted and accepted |
17
+ | Table 8 | `provides_attestations` holds `Credential` objects with `format` and `meta` only | Claim queries are for requested credentials. Provided attestations describe what the WRP issues, so `claim` / `claims` is rejected there and wallets do not have to resolve external scheme documents to understand what is provided |
18
+ | Table 10 vs. Annex C | Table 10 names the intermediary common name `sname`; the Annex C example uses `name` | Table 10 is normative, so `sname` is used |
19
+ | Tables 5 and 6 | The header lists only `typ`, `alg` and `x5c` / `x5chain`, and the Annex C example header shows nothing else | Table 5 is a minimum set. GEN-5.2.1-04 additionally requires a JAdES B-B signature, whose protected header must carry `iat` as the claimed signing time, so signed WRPRCs have one |
20
+ | Table 7 | The payload has no unique identifier for the certificate | An optional `jti` (RFC 7519) is accepted and can be set through the builder, but is never required |
21
+
22
+ When ETSI publishes a corrected edition, these names will be updated in a major release rather than silently diverging from the current text.
23
+
24
+ ### Reading and writing the anticipated corrections
25
+
26
+ Parsing is deliberately more liberal than writing for the two field renames. `claims` and `intermediary.name` are accepted on input and normalized to the shape above, so certificates produced by an SDK that already applies those corrections still validate.
27
+
28
+ Writing stays on the published edition unless you ask for otherwise:
29
+
30
+ ```typescript
31
+ import { signWRPRC, WRPRC_DIALECTS } from '@owf/eudi-registration-certificate'
32
+
33
+ const signed = await signWRPRC({
34
+ payload,
35
+ accessCertificateSub,
36
+ certificates: [certificatePEM],
37
+ signer,
38
+ dialect: WRPRC_DIALECTS.DRAFT, // emits claims and intermediary.name
39
+ })
40
+ ```
41
+
42
+ `WRPRC_DIALECTS.DRAFT` is **unstable**. No published edition defines it, so a certificate emitted this way may match neither the current specification nor its eventual correction. Leave the default in place unless you are testing against a counterpart that has already moved.
43
+
44
+ The dialect covers the two renames only. It does not touch `provides_attestations`, which is always represented as `Credential` objects with `format` and `meta` only.
45
+
46
+ `toWRPRCDialect(payload, dialect)` and `normalizeWRPRCPayload(value)` expose the same mapping if you need it outside the signer.
47
+
48
+ ## Overview
49
+
50
+ This package provides:
51
+
52
+ - **Zod schemas** for validating WRPRC payloads and headers
53
+ - **TypeScript types** derived from the schemas
54
+ - **Entitlement constants** per ETSI TS 119 475 Annex A
55
+ - **Fluent builder API** for creating WRPRC payloads
56
+ - **Validators** implementing ETSI requirements
57
+ - **Signer** for creating signed JWT WRPRCs
58
+
59
+ ## Installation
60
+
61
+ ```bash
62
+ # Using npm
63
+ npm install @owf/eudi-registration-certificate
64
+
65
+ # Using pnpm
66
+ pnpm add @owf/eudi-registration-certificate
67
+
68
+ # Using yarn
69
+ yarn add @owf/eudi-registration-certificate
70
+ ```
71
+
72
+ ## Usage
73
+
74
+ ### Creating a WRPRC with the Fluent Builder
75
+
76
+ ```typescript
77
+ import { wrprc, WRP_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
78
+
79
+ const payload = wrprc()
80
+ .name('Example Service')
81
+ .legalName('Example Inc.')
82
+ .identifier('LEIXG-529900T8BM49AURSDO55')
83
+ .country('DE')
84
+ .registryUri('https://registry.example.com/api')
85
+ .addEntitlement(WRP_ENTITLEMENTS.SERVICE_PROVIDER)
86
+ .addEntitlement(WRP_ENTITLEMENTS.QEAA_PROVIDER)
87
+ .privacyPolicy('https://example.com/privacy')
88
+ .build()
89
+ ```
90
+
91
+ ### Creating a WRPRC for a Natural Person
92
+
93
+ ```typescript
94
+ import { wrprc, WRP_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
95
+
96
+ const payload = wrprc()
97
+ .name('Self-Employed Consultant')
98
+ .givenName('Maria')
99
+ .familyName('Rossi')
100
+ .identifier('TINIT-RSSMRA85T10A562S')
101
+ .country('IT')
102
+ .registryUri('https://registry.example.it/api')
103
+ .addEntitlement(WRP_ENTITLEMENTS.SERVICE_PROVIDER)
104
+ .build()
105
+ ```
106
+
107
+ ### Using Factory Functions
108
+
109
+ ```typescript
110
+ import { createLegalPersonWRPRC, WRP_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
111
+
112
+ const payload = createLegalPersonWRPRC({
113
+ name: 'Example Service',
114
+ legalName: 'Example Inc.',
115
+ identifier: 'LEIXG-529900T8BM49AURSDO55',
116
+ country: 'DE',
117
+ registryUri: 'https://registry.example.com/api',
118
+ entitlements: [WRP_ENTITLEMENTS.SERVICE_PROVIDER],
119
+ })
120
+ ```
121
+
122
+ ### Specifying Credentials to Request
123
+
124
+ ```typescript
125
+ import { wrprc, credential, WRP_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
126
+
127
+ const payload = wrprc()
128
+ .name('Verification Service')
129
+ .legalName('VerifyCo Ltd.')
130
+ .identifier('LEIXG-123456789ABCDEFGH')
131
+ .country('NL')
132
+ .registryUri('https://registry.example.nl/api')
133
+ .addEntitlement(WRP_ENTITLEMENTS.SERVICE_PROVIDER)
134
+ .addCredential(
135
+ credential()
136
+ .format('dc+sd-jwt')
137
+ .meta({ vct: 'https://example.com/credentials/identity' })
138
+ .addPathClaim('given_name')
139
+ .addPathClaim('family_name')
140
+ .build()
141
+ )
142
+ .build()
143
+ ```
144
+
145
+ ### Declaring Provided Attestations
146
+
147
+ Attestation providers declare what they issue with `provides_attestations` (GEN-5.2.4-05). ETSI TS 119 475 v1.2.1 defines this as `Credential` objects containing `format` and `meta` only:
148
+
149
+ ```typescript
150
+ import { wrprc, credential, WRP_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
151
+
152
+ const payload = wrprc()
153
+ .name('Attestation Provider')
154
+ .legalName('Issuer GmbH')
155
+ .identifier('LEIXG-529900T8BM49AURSDO55')
156
+ .country('DE')
157
+ .registryUri('https://registry.example.com/api')
158
+ .addEntitlement(WRP_ENTITLEMENTS.NON_Q_EAA_PROVIDER)
159
+ .addProvidedAttestation(
160
+ credential().sdJwtMeta(['https://example.com/attestations/age_over_18']).build()
161
+ )
162
+ .build()
163
+ ```
164
+
165
+ Scheme URLs are not accepted for `provides_attestations`: wallets should be able to inspect the declared credential format and metadata directly without resolving an external document first. Claim queries are not accepted either, because the WRP is declaring what it issues rather than what it requests.
166
+
167
+ ### Signing a WRPRC
168
+
169
+ GEN-5.2.1-04 requires the JWT to carry a JAdES signature with the B-B profile of ETSI TS 119 182-1. `signWRPRC` builds one through [`@owf/eudi-jades`](../eudi-jades), so the protected header holds `typ`, `alg`, the `x5c` certificate chain and the `iat` claimed signing time. `decodeWRPRC` rejects tokens that do not meet the B-B profile.
170
+
171
+ ```typescript
172
+ import { signWRPRC, wrprc, WRP_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
173
+ import { ES256 } from '@owf/crypto'
174
+
175
+ const payload = wrprc()
176
+ .name('Example Service')
177
+ .legalName('Example Inc.')
178
+ .identifier('LEIXG-529900T8BM49AURSDO55')
179
+ .country('DE')
180
+ .registryUri('https://registry.example.com/api')
181
+ .addEntitlement(WRP_ENTITLEMENTS.SERVICE_PROVIDER)
182
+ .build()
183
+
184
+ const { privateKey } = await ES256.generateKeyPair()
185
+ const signer = await ES256.getSigner(privateKey)
186
+
187
+ // PEM-encoded x509 certificate chain (leaf first)
188
+ const certificatePEM = `-----BEGIN CERTIFICATE-----
189
+ ...
190
+ -----END CERTIFICATE-----`
191
+
192
+ const signed = await signWRPRC({
193
+ payload,
194
+ accessCertificateSub,
195
+ algorithm: 'ES256',
196
+ certificates: [certificatePEM],
197
+ signer,
198
+ })
199
+
200
+ console.log(signed.jws) // Compact JWS string
201
+ ```
202
+
203
+ Pass `signingTime` to pin the claimed signing time; it defaults to now.
204
+
205
+ ### Decoding a WRPRC
206
+
207
+ ```typescript
208
+ import { decodeWRPRC } from '@owf/eudi-registration-certificate'
209
+
210
+ const jwsString = 'eyJ0eXAiOiJyYy13cnArand0Ii...'
211
+ const decoded = decodeWRPRC(jwsString, accessCertificateSub)
212
+
213
+ console.log(decoded.header) // { typ: 'rc-wrp+jwt', alg: 'ES256', ... }
214
+ console.log(decoded.payload) // { name: '...', sub: '...', ... }
215
+ ```
216
+
217
+ ### Validating a WRPRC
218
+
219
+ ```typescript
220
+ import { validateWRPRCPayload } from '@owf/eudi-registration-certificate'
221
+
222
+ const result = validateWRPRCPayload(payload, accessCertificateSub)
223
+
224
+ if (result.valid) {
225
+ console.log('WRPRC is valid')
226
+ } else {
227
+ console.log('Errors:', result.errors)
228
+ }
229
+
230
+ // Warnings are returned even for valid payloads
231
+ if (result.warnings.length > 0) {
232
+ console.log('Warnings:', result.warnings)
233
+ }
234
+ ```
235
+
236
+ `accessCertificateSub` is required for payload validation, parsing, signing, and decoding. It is compared with `intermediary.sub` when the WRPRC has an intermediary, and with `sub` otherwise.
237
+
238
+ ### Entitlement Constants
239
+
240
+ The package exports all entitlement URIs from ETSI TS 119 475 Annex A:
241
+
242
+ ```typescript
243
+ import { WRP_ENTITLEMENTS, PSP_SUB_ENTITLEMENTS } from '@owf/eudi-registration-certificate'
244
+
245
+ // Main entitlements
246
+ WRP_ENTITLEMENTS.SERVICE_PROVIDER // Basic service provider
247
+ WRP_ENTITLEMENTS.QEAA_PROVIDER // Qualified EAA provider
248
+ WRP_ENTITLEMENTS.NON_Q_EAA_PROVIDER // Non-qualified EAA provider
249
+ WRP_ENTITLEMENTS.PUB_EAA_PROVIDER // Public EAA provider
250
+ WRP_ENTITLEMENTS.PID_PROVIDER // Person Identification Data provider
251
+ WRP_ENTITLEMENTS.QCERT_FOR_ESEAL_PROVIDER // Qualified cert for e-seal issuer
252
+ WRP_ENTITLEMENTS.QCERT_FOR_ESIG_PROVIDER // Qualified cert for e-sig issuer
253
+ WRP_ENTITLEMENTS.RQSEALCDS_PROVIDER // Remote qualified seal creation device
254
+ WRP_ENTITLEMENTS.RQSIGCDS_PROVIDER // Remote qualified sig creation device
255
+ WRP_ENTITLEMENTS.ESIG_ESEAL_CREATION_PROVIDER // Non-qualified e-sig/seal creation
256
+
257
+ // PSP sub-entitlements (require SERVICE_PROVIDER)
258
+ PSP_SUB_ENTITLEMENTS.PAYMENT_INITIATION // Payment initiation services
259
+ PSP_SUB_ENTITLEMENTS.ACCOUNT_INFORMATION // Account information services
260
+ PSP_SUB_ENTITLEMENTS.ACCOUNT_SERVICING // Account servicing provider
261
+ PSP_SUB_ENTITLEMENTS.CARD_BASED // Card-based payment instruments
262
+ PSP_SUB_ENTITLEMENTS.UNSPECIFIED // Unspecified payment service provider
263
+ ```
264
+
265
+ ## ETSI TS 119 475 Compliance
266
+
267
+ This implementation follows ETSI TS 119 475 v1.2.1 requirements:
268
+
269
+ - **GEN-5.2.1-04**: JAdES B-B signature (ETSI TS 119 182-1), with the JAdES B-B algorithm set (`ES*`, `PS*`, `RS*`, `EdDSA`)
270
+ - **GEN-5.2.2 / GEN-5.2.3**: JWT/CWT headers with `typ: "rc-wrp+jwt"` or `typ: "rc-wrp+cwt"`
271
+ - **GEN-5.2.4-03**: At least one entitlement must be specified
272
+ - **GEN-5.2.4-04**: Sub-entitlements require the base entitlement
273
+ - **GEN-5.2.4-05**: Attestation providers should specify `provides_attestations`
274
+ - **GEN-5.2.4-06**: Service providers should specify `credentials` and `purpose`
275
+ - **GEN-5.2.4-08**: `exp` at most 12 months after `iat`
276
+ - Under intermediation, `intermediary.sub` is checked against the supplied access-certificate subject
277
+
278
+ ### Semantic Identifiers
279
+
280
+ Subject identifiers (`sub`) follow ETSI EN 319 412-1, with the type-to-prefix mapping of Table 2 (legal persons) and Table 4 (natural persons).
281
+
282
+ Legal persons (Table 2, EN 319 412-1 clause 5.1.4):
283
+
284
+ | Identifier type | Prefix | Example |
285
+ |-----------------|--------|---------|
286
+ | EORI-No | `EOR` | `EORDE-DE1234567890` |
287
+ | LEI | `LEI` | `LEIXG-529900T8BM49AURSDO55` |
288
+ | EUID | `NTR` | `NTRNL-12345678` |
289
+ | VATIN | `VAT` | `VATDE-123456789` |
290
+ | TIN | `VAT` | `VATDE-123456789` |
291
+ | Excise | `EXC` | `EXCDE-DE00012345678` |
292
+
293
+ Natural persons (Table 4, EN 319 412-1 clause 5.1.3):
294
+
295
+ | Identifier type | Prefix | Example |
296
+ |-----------------|--------|---------|
297
+ | VATIN / TIN | `TIN` | `TINIT-RSSMRA85T10A562S` |
298
+ | Passport number | `PAS` | `PASDE-C01X00T47` |
299
+ | Identity card number | `IDC` | `IDCIT-AX1234567` |
300
+ | National personal number | `PNO` | `PNOSE-197001019999` |
301
+
302
+ ## Platform Support
303
+
304
+ This library is **platform agnostic** and works in:
305
+
306
+ - ✅ Node.js (>=20)
307
+ - ✅ Browsers (modern browsers with ES2020 support)
308
+ - ✅ React Native
309
+
310
+ ## API Reference
311
+
312
+ ### Schemas
313
+
314
+ - `WRPRCPayloadSchema` - Full WRPRC payload validation
315
+ - `WRPRCJWTHeaderSchema` - JWT header validation
316
+ - `WRPRCCWTHeaderSchema` - CWT header validation
317
+ - `CredentialSchema` - Credential specification validation
318
+ - `ClaimSchema` - Claim specification validation
319
+ - `MultiLangStringSchema` - Multilingual string validation
320
+
321
+ ### Types
322
+
323
+ - `WRPRCPayload` - WRPRC payload type
324
+ - `WRPRCJWTHeader` - JWT header type
325
+ - `SignedWRPRC` - Signed WRPRC with JWS string
326
+ - `Credential` - Credential specification type
327
+ - `ProvidedAttestation` - Provided attestation credential type with `format` and `meta` only
328
+ - `Claim` - Claim specification type
329
+
330
+ ### Builders
331
+
332
+ - `WRPRCBuilder` - Fluent builder for WRPRC payloads
333
+ - `CredentialBuilder` - Fluent builder for credential specifications
334
+ - `wrprc()` - Factory function for WRPRCBuilder
335
+ - `credential()` - Factory function for CredentialBuilder
336
+
337
+ ### Validators
338
+
339
+ - `validateWRPRCPayload(payload, accessCertificateSub)` - Validate payload and access-certificate identity
340
+ - `validateWRPRCJWTHeader(header)` - Validate JWT header
341
+ - `validateWRPRC(header, payload, accessCertificateSub)` - Validate complete WRPRC and access-certificate identity
342
+ - `assertValidWRPRCPayload(payload, accessCertificateSub)` - Assert or throw
343
+ - `parseWRPRCPayload(payload, accessCertificateSub)` - Validate and return the canonical payload
344
+
345
+ ### Dialects
346
+
347
+ - `WRPRC_DIALECTS` - Supported wire dialects
348
+ - `normalizeWRPRCPayload(value)` - Map either spelling to the published one
349
+ - `toWRPRCDialect(payload, dialect)` - Serialize a canonical payload in a dialect
350
+
351
+ ### Signer
352
+
353
+ - `signWRPRC(options)` - Sign a WRPRC payload to JWT
354
+ - `decodeWRPRC(jws, accessCertificateSub)` - Decode and validate a signed WRPRC
355
+ - `parseWRPRC(jws)` - Parse without validation
356
+
357
+ ## Contributing
358
+
359
+ 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.
360
+
361
+ ## License
362
+
363
+ 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).