antifraud-data-utils-ts 0.1.10 → 0.2.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/CHANGELOG.md +187 -134
- package/LICENSE +13 -13
- package/README.md +257 -243
- package/dist/cryptography/index.d.ts +1 -0
- package/dist/cryptography/index.d.ts.map +1 -1
- package/dist/cryptography/index.js +1 -0
- package/dist/cryptography/index.js.map +1 -1
- package/dist/cryptography/numeric-qr.d.ts +4 -0
- package/dist/cryptography/numeric-qr.d.ts.map +1 -0
- package/dist/cryptography/numeric-qr.js +22 -0
- package/dist/cryptography/numeric-qr.js.map +1 -0
- package/dist/cryptography/post-quantum-detached-qr.d.ts +14 -0
- package/dist/cryptography/post-quantum-detached-qr.d.ts.map +1 -0
- package/dist/cryptography/post-quantum-detached-qr.js +76 -0
- package/dist/cryptography/post-quantum-detached-qr.js.map +1 -0
- package/dist/encoding/base58btc.d.ts +3 -0
- package/dist/encoding/base58btc.d.ts.map +1 -0
- package/dist/encoding/base58btc.js +19 -0
- package/dist/encoding/base58btc.js.map +1 -0
- package/dist/identity-assurance/antifraud-data-card.d.ts +42 -0
- package/dist/identity-assurance/antifraud-data-card.d.ts.map +1 -0
- package/dist/identity-assurance/antifraud-data-card.js +120 -0
- package/dist/identity-assurance/antifraud-data-card.js.map +1 -0
- package/dist/identity-assurance/didcomm-binary-attachment.d.ts.map +1 -1
- package/dist/identity-assurance/didcomm-binary-attachment.js +1 -18
- package/dist/identity-assurance/didcomm-binary-attachment.js.map +1 -1
- package/dist/identity-assurance/identity-evidence.d.ts.map +1 -1
- package/dist/identity-assurance/identity-evidence.js +1 -16
- package/dist/identity-assurance/identity-evidence.js.map +1 -1
- package/dist/identity-assurance/index.d.ts +1 -0
- package/dist/identity-assurance/index.d.ts.map +1 -1
- package/dist/identity-assurance/index.js +1 -0
- package/dist/identity-assurance/index.js.map +1 -1
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -1
- package/dist/organization-credentials.d.ts +75 -0
- package/dist/organization-credentials.d.ts.map +1 -0
- package/dist/organization-credentials.js +162 -0
- package/dist/organization-credentials.js.map +1 -0
- package/dist/organization-identity.d.ts +21 -0
- package/dist/organization-identity.d.ts.map +1 -0
- package/dist/organization-identity.js +47 -0
- package/dist/organization-identity.js.map +1 -0
- package/dist/service-conversation.d.ts +40 -0
- package/dist/service-conversation.d.ts.map +1 -0
- package/dist/service-conversation.js +58 -0
- package/dist/service-conversation.js.map +1 -0
- package/docs/ANTIFRAUD_DATA_CARD_V1.md +47 -0
- package/docs/DC4EU_EDUCATION_AND_MEDICAL_CREDENTIALS.md +93 -0
- package/docs/DIDCOMM_SCHEMA_ORG_ATTACHMENTS.md +73 -0
- package/docs/EDUCATION_ADMINISTRATIVE_ASSISTANT_IDENTITY_EVIDENCE.md +90 -0
- package/docs/IDENTITY_VERIFICATION_AND_ATTESTATION.md +354 -0
- package/docs/ORGANIZATION_CONTACT_IDENTITY.md +113 -0
- package/package.json +69 -55
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Education Administrative Assistant Identity-Evidence Journey
|
|
2
|
+
|
|
3
|
+
This document defines the product-neutral Antifraud contract used when an
|
|
4
|
+
education organization authorizes an administrative assistant to record
|
|
5
|
+
identity evidence. It is an acceptance contract, not evidence that a portal,
|
|
6
|
+
gateway or credential issuer is deployed.
|
|
7
|
+
|
|
8
|
+
The public Antifraud controller portal is separate from sector role portals.
|
|
9
|
+
The controller configures departments, invitations, employee groups and their
|
|
10
|
+
reusable authorizations there. The administrative assistant will perform the
|
|
11
|
+
student evidence journey in the planned `qualification-education` role portal.
|
|
12
|
+
That role portal is currently a public scaffold and must not be described as
|
|
13
|
+
implemented.
|
|
14
|
+
|
|
15
|
+
## Authority established by the controller
|
|
16
|
+
|
|
17
|
+
The organization controller creates a workforce group for the administrative
|
|
18
|
+
task and gives that group only the capabilities needed for the journey. The
|
|
19
|
+
administrative assistant gains eligibility through an active employee
|
|
20
|
+
assignment, active membership in that exact group and the group's active
|
|
21
|
+
authorization. The employee does not receive a separate Consent merely by
|
|
22
|
+
joining the group.
|
|
23
|
+
|
|
24
|
+
The browser never chooses the actor, employer, assignment, controller or group
|
|
25
|
+
authorization. The trusted service derives them from the authenticated
|
|
26
|
+
session and reads them back before accepting evidence. If the use case requires
|
|
27
|
+
authorization from the student, parent, guardian or another lawful
|
|
28
|
+
representative, that authorization is a separate gate.
|
|
29
|
+
|
|
30
|
+
## What the administrative assistant may do
|
|
31
|
+
|
|
32
|
+
An authorized administrative assistant may:
|
|
33
|
+
|
|
34
|
+
1. create or update the permitted subject record;
|
|
35
|
+
2. record evidence examined for that subject;
|
|
36
|
+
3. attest a relationship, such as a lawful representative acting for a minor;
|
|
37
|
+
4. record a derived age-over result when access to the source birth-date claim
|
|
38
|
+
and the intended purpose are authorized; and
|
|
39
|
+
5. submit qualification evidence reviewed by the employer without claiming
|
|
40
|
+
that the employer is the awarding university.
|
|
41
|
+
|
|
42
|
+
The assistant cannot grant their own capability, select a different employer,
|
|
43
|
+
sign as a university, convert an employer observation into an issuer
|
|
44
|
+
credential or infer professional authority from a qualification scan.
|
|
45
|
+
|
|
46
|
+
## Canonical data and exchange projections
|
|
47
|
+
|
|
48
|
+
Canonical business data uses governed Schema.org flat claims. A qualification
|
|
49
|
+
uses `EducationalOccupationalCredential`. A scanned PDF, PNG, JPEG or TIFF is
|
|
50
|
+
represented as its `MediaObject` encoding with a protected `contentUrl`, media
|
|
51
|
+
type, size and a CIDv1(raw, SHA3-384) identifier. The exact file remains in
|
|
52
|
+
confidential storage.
|
|
53
|
+
|
|
54
|
+
OpenID Identity Assurance is an exchange projection describing the verified
|
|
55
|
+
claims, evidence and checks. EUDI Person Identification Data, education
|
|
56
|
+
credentials and Open Badges are separate target profiles. Each adapter maps
|
|
57
|
+
only the claims defined by that profile; it must report unsupported claims and
|
|
58
|
+
must not silently overwrite an existing assertion.
|
|
59
|
+
|
|
60
|
+
`age_over_18` is the standardized EUDI Person Identification Data element.
|
|
61
|
+
Thresholds such as 19, 21 or 65 remain explicit governed predicates and must
|
|
62
|
+
not be labelled as EUDI Person Identification Data attributes.
|
|
63
|
+
|
|
64
|
+
## Required local user-interface proof
|
|
65
|
+
|
|
66
|
+
The local automated journey must use the real portal, backend for frontend,
|
|
67
|
+
high-level SDK and gateway boundary. It must prove authoritative persistence by
|
|
68
|
+
reading the resulting statement back after submission. A component test,
|
|
69
|
+
fixture screen, mocked route, screenshot or successful HTTP status is not this
|
|
70
|
+
proof.
|
|
71
|
+
|
|
72
|
+
The positive journey is:
|
|
73
|
+
|
|
74
|
+
1. a controller creates the group and its reusable authorization;
|
|
75
|
+
2. the controller assigns the administrative assistant to the group;
|
|
76
|
+
3. the employee signs in and records subject identity evidence;
|
|
77
|
+
4. the employee records any permitted representative relationship;
|
|
78
|
+
5. the employee records an authorized age-over result without exposing the
|
|
79
|
+
source birth date unnecessarily; and
|
|
80
|
+
6. the employee sees the authoritative readback with actor, organization,
|
|
81
|
+
group authorization, evidence, time, status and proof references.
|
|
82
|
+
|
|
83
|
+
Negative journeys must cover an inactive employee, inactive or mismatched
|
|
84
|
+
membership, missing capability, missing required subject authorization,
|
|
85
|
+
cross-tenant subject access, caller-authored actor fields, invalid evidence
|
|
86
|
+
digest or CID, and conflicting claims.
|
|
87
|
+
|
|
88
|
+
The contract deliberately uses opaque subject references, but this document
|
|
89
|
+
defines only the education journey. Product-specific reuse belongs in the
|
|
90
|
+
documentation of the consuming product.
|
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
# Identity Verification and Attestation Contract
|
|
2
|
+
|
|
3
|
+
This is a core Antifraud trust contract. A system can rely on an identity or
|
|
4
|
+
qualification only when it can preserve who asserted it, the actor's authority
|
|
5
|
+
and jurisdiction, the evidence examined, the time, the proof, and the current
|
|
6
|
+
status without substituting one issuer for another.
|
|
7
|
+
|
|
8
|
+
## Purpose
|
|
9
|
+
|
|
10
|
+
This document defines a product-neutral foundation for verifying identity data
|
|
11
|
+
and issuing attestations about subjects, individual claims and relationships.
|
|
12
|
+
It is the normative companion to implementation prompts: a prompt states that
|
|
13
|
+
this contract must be reused, while this document owns the precise data and
|
|
14
|
+
acceptance rules.
|
|
15
|
+
|
|
16
|
+
## Required semantic separation
|
|
17
|
+
|
|
18
|
+
An asserted claim, its verification and an attestation are different records.
|
|
19
|
+
|
|
20
|
+
- An asserted claim is the value supplied by or for a subject.
|
|
21
|
+
- Verification describes how evidence was assessed.
|
|
22
|
+
- An attestation is the signed, versioned result issued by an authorized actor.
|
|
23
|
+
|
|
24
|
+
Verification must never replace the original author or silently overwrite an
|
|
25
|
+
asserted value. A correction creates a new version and preserves the previous
|
|
26
|
+
statement and audit history.
|
|
27
|
+
|
|
28
|
+
Subject identity, a relationship to the subject and authority over the subject
|
|
29
|
+
are also separate facts. Attesting a relationship does not appoint a
|
|
30
|
+
controller and does not grant access to unrelated data.
|
|
31
|
+
|
|
32
|
+
## Capabilities
|
|
33
|
+
|
|
34
|
+
The neutral capability vocabulary is:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
identity.subject.create
|
|
38
|
+
identity.subject.update
|
|
39
|
+
identity.evidence.record
|
|
40
|
+
identity.claim.verify
|
|
41
|
+
identity.subject.attest
|
|
42
|
+
identity.relationship.attest
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Capabilities are authorization inputs, not occupations, roles or flat claims.
|
|
46
|
+
A downstream policy maps its governed workforce credentials to one of these
|
|
47
|
+
capabilities and constrains it by subject, target claim or relationship,
|
|
48
|
+
purpose, jurisdiction, organization, evidence class, audience and expiry.
|
|
49
|
+
|
|
50
|
+
Authentication alone never grants a capability. A complete decision can
|
|
51
|
+
require authenticated actor identity, active organization delegation, subject
|
|
52
|
+
authorization and current policy at the same time.
|
|
53
|
+
|
|
54
|
+
## Authorized workforce maintenance
|
|
55
|
+
|
|
56
|
+
The normal Antifraud actor is an authorized workforce member, not a hard-coded
|
|
57
|
+
occupation. An administrative employee of an education institution is one
|
|
58
|
+
example. Sector applications may apply the same contract to staff maintaining
|
|
59
|
+
an insured beneficiary, a patient or another governed subject.
|
|
60
|
+
|
|
61
|
+
The organization controller creates the operational group, governs which
|
|
62
|
+
employee assignments belong to it and configures one reusable authorization
|
|
63
|
+
for the group. That group authorization restricts the permitted operation,
|
|
64
|
+
purpose, organization, jurisdiction and validity period. It may be represented
|
|
65
|
+
by a Consent where that standard and profile apply, or by another governed
|
|
66
|
+
policy record. It is not duplicated for every employee.
|
|
67
|
+
|
|
68
|
+
All of the following are required before the member can create or update a
|
|
69
|
+
subject record or record identity evidence:
|
|
70
|
+
|
|
71
|
+
1. authenticated workforce actor;
|
|
72
|
+
2. active employee assignment;
|
|
73
|
+
3. membership in the controller-governed group;
|
|
74
|
+
4. active authorization for that exact group;
|
|
75
|
+
5. the exact `identity.subject.create`, `identity.subject.update` or
|
|
76
|
+
`identity.evidence.record` capability.
|
|
77
|
+
|
|
78
|
+
The browser submits the subject and evidence fields. It never supplies the
|
|
79
|
+
authoritative actor, employee assignment, group membership, group authorization
|
|
80
|
+
or issuer identity. Those values come from trusted server state.
|
|
81
|
+
|
|
82
|
+
The employee has no individual Consent merely because they joined a group.
|
|
83
|
+
Removing the employee deactivates or removes only their group membership; the
|
|
84
|
+
group authorization remains usable by the other active members. A subject,
|
|
85
|
+
student, patient, beneficiary or lawful representative may have a separate
|
|
86
|
+
authorization governing operations on that subject. That authorization is
|
|
87
|
+
evaluated independently and must never be confused with workforce membership.
|
|
88
|
+
|
|
89
|
+
### Invitation, department and group changes
|
|
90
|
+
|
|
91
|
+
When a controller creates and invites an employee, the invitation may propose
|
|
92
|
+
an optional department and zero or more professional groups. These are pending
|
|
93
|
+
assignments and grant no capability until the employee accepts the invitation,
|
|
94
|
+
activates the professional assignment and the authoritative backend persists
|
|
95
|
+
the memberships.
|
|
96
|
+
|
|
97
|
+
The invitation identifies the proposed organization, role, department and
|
|
98
|
+
groups in understandable language. Acceptance produces a Communication notice.
|
|
99
|
+
Later additions or removals of groups, department transfers, suspensions and
|
|
100
|
+
reactivations also produce a Communication containing the change, controller
|
|
101
|
+
reference and effective time. A notification records the change; it is not an
|
|
102
|
+
authorization and does not create a Consent.
|
|
103
|
+
|
|
104
|
+
Recording evidence and issuing an attestation are separate actions. The
|
|
105
|
+
workforce member creates an unsigned, auditable evidence statement. The
|
|
106
|
+
authoritative tenant later reads the stored statement and subject record,
|
|
107
|
+
evaluates policy and signs the credential. The member cannot cause the tenant
|
|
108
|
+
to sign caller-authored claims merely by possessing form access.
|
|
109
|
+
|
|
110
|
+
Education occupations do not determine authority inside this shared package.
|
|
111
|
+
The controller-governed assignment and exact capabilities do; authentication
|
|
112
|
+
or a job title alone grants none of them.
|
|
113
|
+
|
|
114
|
+
## Canonical data and exchange projection
|
|
115
|
+
|
|
116
|
+
Canonical business values use governed Schema.org flat claims. The initial
|
|
117
|
+
person mapping is:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
org.schema.Person.name <-> name
|
|
121
|
+
org.schema.Person.givenName <-> given_name
|
|
122
|
+
org.schema.Person.familyName <-> family_name
|
|
123
|
+
org.schema.Person.birthDate <-> birthdate
|
|
124
|
+
org.schema.Person.gender <-> gender
|
|
125
|
+
org.schema.Person.email <-> email
|
|
126
|
+
org.schema.Person.telephone <-> phone_number
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The right-hand values are registered OpenID Connect claim names used inside
|
|
130
|
+
`verified_claims.claims`. `verified_claims.verification` remains separate and
|
|
131
|
+
contains the assurance and evidence metadata.
|
|
132
|
+
|
|
133
|
+
EUDI Person Identification Data attributes are not simply another name for
|
|
134
|
+
the OpenID Identity Assurance claim set. EUDI PID credentials define data
|
|
135
|
+
elements such as `birth_date` and the data-minimizing `age_over_18`. The OpenID
|
|
136
|
+
Identity Assurance projection uses registered OpenID claims such as
|
|
137
|
+
`birthdate` inside `verified_claims.claims`, together with separate
|
|
138
|
+
verification and evidence information. A governed converter may map between
|
|
139
|
+
them when their semantics match, but it must retain the source profile and
|
|
140
|
+
must not treat the two vocabularies as interchangeable.
|
|
141
|
+
|
|
142
|
+
OpenID4VCI is the issuance protocol and OpenID4VP is the presentation protocol.
|
|
143
|
+
Neither protocol by itself defines the meaning of every PID or Identity
|
|
144
|
+
Assurance claim.
|
|
145
|
+
|
|
146
|
+
Relationship claims require an explicit governed mapping before exchange.
|
|
147
|
+
The converter must not invent a lossy OpenID name or flatten an identifier in a
|
|
148
|
+
way that removes the subject, related party or relationship type. Until such a
|
|
149
|
+
mapping is registered, export fails closed.
|
|
150
|
+
|
|
151
|
+
## Conversion rules
|
|
152
|
+
|
|
153
|
+
`projectSchemaOrgFlatClaimsToOidc4Ida`:
|
|
154
|
+
|
|
155
|
+
- accepts only governed mappings;
|
|
156
|
+
- emits both `claims` and `verification`;
|
|
157
|
+
- rejects unknown flat claims;
|
|
158
|
+
- does not mutate its input;
|
|
159
|
+
- does not introduce evidence or assurance values.
|
|
160
|
+
|
|
161
|
+
`importOidc4IdaToSchemaOrgFlatClaims`:
|
|
162
|
+
|
|
163
|
+
- imports only governed mappings;
|
|
164
|
+
- returns unknown OpenID claims in `unmappedClaims`;
|
|
165
|
+
- returns contradictions in `conflicts`;
|
|
166
|
+
- never overwrites an existing flat claim;
|
|
167
|
+
- returns verification metadata separately from canonical claims.
|
|
168
|
+
|
|
169
|
+
Conversion is therefore intentionally not a blind serialization round trip.
|
|
170
|
+
The caller must resolve contradictions and decide whether to create a new
|
|
171
|
+
assertion, correction or attestation.
|
|
172
|
+
|
|
173
|
+
## Claim proof bindings and selective disclosure
|
|
174
|
+
|
|
175
|
+
A canonical claim value and the cryptographic material that supports it are
|
|
176
|
+
different records. `ClaimProofBinding` links either one governed claim path or
|
|
177
|
+
one derived predicate to one or more `ClaimProofReference` objects. This is how
|
|
178
|
+
the same claim can be supported by several credentials, registers or signed
|
|
179
|
+
evidence sources without duplicating or overwriting the canonical value.
|
|
180
|
+
|
|
181
|
+
The reference records the proof format, issuer, credential reference,
|
|
182
|
+
cryptographic binding, status and optional verification method, validity and
|
|
183
|
+
disclosure digest. It never embeds a raw wallet presentation, SD-JWT
|
|
184
|
+
Disclosure, identity document or signing key in the flat claim.
|
|
185
|
+
|
|
186
|
+
For an SD-JWT Verifiable Credential, “proof for a claim” does not mean a
|
|
187
|
+
separate digital signature for every field. The issuer signs an SD-JWT whose
|
|
188
|
+
payload commits to selectively disclosable claims through digests. A
|
|
189
|
+
Disclosure reveals a selected claim and is validated against the signed
|
|
190
|
+
digest. A presentation may additionally use a Key Binding JWT to prove holder
|
|
191
|
+
control. One proof reference therefore points to the signed credential and may
|
|
192
|
+
identify the applicable disclosure digest; it does not copy the Disclosure.
|
|
193
|
+
|
|
194
|
+
ISO/IEC 18013-5 mdoc issuer-signed data elements, W3C Verifiable Credential
|
|
195
|
+
proofs, OpenID Identity Assurance verification results and separately signed
|
|
196
|
+
evidence use different cryptographic bindings. They must retain distinct
|
|
197
|
+
formats instead of being labelled generically as SD-JWT.
|
|
198
|
+
|
|
199
|
+
Age checks are derived predicates, not aliases for date of birth. To prove
|
|
200
|
+
that a person is over a threshold, use a predicate target with:
|
|
201
|
+
|
|
202
|
+
```text
|
|
203
|
+
predicate: age-over
|
|
204
|
+
sourceClaimPath: org.schema.Person.birthDate
|
|
205
|
+
threshold: 18
|
|
206
|
+
result: true
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
The EUDI PID data-element name is then `age_over_18`. The proof binding contains
|
|
210
|
+
no birth-date value. A verifier that needs only majority status requests that
|
|
211
|
+
predicate rather than `birth_date`, preserving data minimization. The current
|
|
212
|
+
EUDI PID profile standardizes the 18-year predicate; another threshold requires
|
|
213
|
+
a separately governed credential profile and must not be labelled EUDI PID
|
|
214
|
+
merely because it follows an `age_over_NN` spelling.
|
|
215
|
+
|
|
216
|
+
Normative references:
|
|
217
|
+
|
|
218
|
+
- [SD-JWT-based Verifiable Digital Credentials](https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/)
|
|
219
|
+
- [OpenID for Verifiable Presentations 1.0](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html)
|
|
220
|
+
- [EUDI PID Rulebook](https://eu-digital-identity-wallet.github.io/eudi-doc-architecture-and-reference-framework/latest/annexes/annex-06-pid-rulebook/)
|
|
221
|
+
|
|
222
|
+
## JSON Schema and forms
|
|
223
|
+
|
|
224
|
+
The package exports the JSON Schema 2020-12 object
|
|
225
|
+
`verifiedClaimsJsonSchema`. It requires `claims` and `verification`, and
|
|
226
|
+
requires at least one evidence object.
|
|
227
|
+
|
|
228
|
+
The schema validates data; it does not authorize an operation. A form renderer
|
|
229
|
+
may consume it, but browser state must never decide that evidence is verified.
|
|
230
|
+
The host submits the governed request and displays only authoritative readback.
|
|
231
|
+
|
|
232
|
+
The package also exports
|
|
233
|
+
`workforceIdentityEvidenceStatementJsonSchema`. Its `createdBy`, capability and
|
|
234
|
+
authorization fields are read-only because the server derives them from the
|
|
235
|
+
authenticated assignment, active group membership and reusable group
|
|
236
|
+
authorization. An optional subject-authorization reference is separate. The
|
|
237
|
+
form may capture evidence observations and digest-bound attachment references;
|
|
238
|
+
it cannot embed a raw identity document.
|
|
239
|
+
|
|
240
|
+
The supported OpenID Identity Assurance evidence categories are `document`,
|
|
241
|
+
`electronic_record`, `vouch` and `electronic_signature`. A workforce member who
|
|
242
|
+
personally reviews evidence normally records the check and, where applicable,
|
|
243
|
+
a `vouch`; this does not make their statement an issuer-signed credential.
|
|
244
|
+
|
|
245
|
+
Scanned PDF, PNG, JPEG and TIFF evidence is represented canonically as a
|
|
246
|
+
Schema.org `MediaObject`. Its flat claims retain the protected `contentUrl`,
|
|
247
|
+
`encodingFormat`, `contentSize`, and a CIDv1(raw, SHA3-384) identifier in
|
|
248
|
+
multibase base58btc form. An OpenID Identity Assurance export projects the same
|
|
249
|
+
artifact into its external-attachment structure with a protected URL and a
|
|
250
|
+
negotiated base64 digest. The CID is an integrity and retrieval reference; it
|
|
251
|
+
is not proof that the claimed qualification issuer created or validated the
|
|
252
|
+
document.
|
|
253
|
+
|
|
254
|
+
### Employee identity and qualification evidence
|
|
255
|
+
|
|
256
|
+
A controller or human-resources employee may record evidence about an
|
|
257
|
+
employee's identity or qualifications only through an active group whose
|
|
258
|
+
authorization contains the exact evidence capability. The actor records what
|
|
259
|
+
was examined and may add a separately signed `vouch` or
|
|
260
|
+
`electronic_signature`.
|
|
261
|
+
|
|
262
|
+
An awarding university, licensing body or other organization is identified by
|
|
263
|
+
the exact pair of legal identifier and jurisdiction. A display name is not an
|
|
264
|
+
authority key. A trusted backend resolves that pair through the configured
|
|
265
|
+
authoritative organization directory and retains the resolved organization
|
|
266
|
+
reference in the evidence trail.
|
|
267
|
+
|
|
268
|
+
When no credential issued by the awarding organization is available, the
|
|
269
|
+
employer may attest only that it reviewed specified evidence and reached a
|
|
270
|
+
stated conclusion. The issuer and signature remain those of the employer; the
|
|
271
|
+
attestation must not claim that the university signed or confirmed it. If the
|
|
272
|
+
awarding organization later supplies its own credential or confirmation, add
|
|
273
|
+
that issuer proof to the claim's proof binding. Do not delete the employer
|
|
274
|
+
proof. `ClaimProofBinding` supports several credential-level proof references
|
|
275
|
+
for one claim, so provenance remains distinguishable.
|
|
276
|
+
|
|
277
|
+
In health and other regulated sectors, keep identity evidence, qualification
|
|
278
|
+
evidence, professional licence status, employment assignment, group
|
|
279
|
+
authorization, and subject authorization as independent gates. A signed
|
|
280
|
+
employer attestation about a diploma does not prove that the university issued
|
|
281
|
+
it and does not prove that a professional licence is active. Suspension,
|
|
282
|
+
revocation, expiry, jurisdiction mismatch, or issuer mismatch must fail closed
|
|
283
|
+
for the operation that depends on that fact.
|
|
284
|
+
|
|
285
|
+
## Tenant Clearing House and source authority
|
|
286
|
+
|
|
287
|
+
A Clearing House is a capability published by a tenant, not necessarily one
|
|
288
|
+
central service. A tenant may act as an employer, an index provider, a verifier
|
|
289
|
+
or more than one of these. Its endpoint advertises the capabilities it actually
|
|
290
|
+
provides.
|
|
291
|
+
|
|
292
|
+
An internal application initially trusts only its home tenant. The home tenant
|
|
293
|
+
may select another employer or index-provider tenant only when that exact
|
|
294
|
+
source is present in its explicit federation trust and advertises the required
|
|
295
|
+
capability. Resolving an index provider identifies the authoritative source;
|
|
296
|
+
it does not grant access and does not authorize issuance.
|
|
297
|
+
|
|
298
|
+
The authoritative source tenant performs readback from its own record before
|
|
299
|
+
signing. An employer therefore attests employment data from the employer's
|
|
300
|
+
record; an index provider attests subject or relationship data from its index.
|
|
301
|
+
A verifier may validate presented evidence, but it must not impersonate the
|
|
302
|
+
source issuer. A separate Clearing House verification attestation has its own
|
|
303
|
+
issuer identity.
|
|
304
|
+
|
|
305
|
+
## Signing, persistence and ledger boundary
|
|
306
|
+
|
|
307
|
+
This data package performs none of these operations. A downstream runtime:
|
|
308
|
+
|
|
309
|
+
1. authenticates the actor and evaluates the exact capability;
|
|
310
|
+
2. verifies evidence through a trusted verifier;
|
|
311
|
+
3. creates and signs the attestation;
|
|
312
|
+
4. persists confidential claims and evidence references;
|
|
313
|
+
5. optionally anchors a privacy-minimized projection on a ledger;
|
|
314
|
+
6. returns authoritative status through the public boundary.
|
|
315
|
+
|
|
316
|
+
The ledger projection may contain an attestation or credential identifier,
|
|
317
|
+
content hash, issuer, protected subject reference, type, status, timestamps and
|
|
318
|
+
evidence hashes or references. It must not contain raw documents, names,
|
|
319
|
+
contacts, exact identity values or private demographics.
|
|
320
|
+
|
|
321
|
+
## Completion criteria for a downstream implementation
|
|
322
|
+
|
|
323
|
+
A downstream implementation is not complete until automated tests prove:
|
|
324
|
+
|
|
325
|
+
1. An actor without the exact capability is rejected.
|
|
326
|
+
2. Scope mismatches for subject, claim, relationship, purpose or jurisdiction
|
|
327
|
+
are rejected.
|
|
328
|
+
3. Missing or inactive employee assignment, group membership or reusable group
|
|
329
|
+
authorization is rejected before evidence persistence.
|
|
330
|
+
4. An external source tenant is rejected unless the home tenant explicitly
|
|
331
|
+
trusts it for the required advertised capability.
|
|
332
|
+
5. Adding or removing one employee never creates, replaces or disables the
|
|
333
|
+
shared authorization for the other group members.
|
|
334
|
+
6. A required subject authorization is evaluated separately from group
|
|
335
|
+
membership.
|
|
336
|
+
7. The source claim remains unchanged after verification.
|
|
337
|
+
8. The signed attestation preserves creator, submitter, verifier, organization,
|
|
338
|
+
subject and related party as distinct identities.
|
|
339
|
+
9. Conflicting imported values are not silently accepted.
|
|
340
|
+
10. Suspension, expiry and revocation fail closed.
|
|
341
|
+
11. Replaying the same operation identity is idempotent.
|
|
342
|
+
12. Invitation acceptance and later assignment changes produce Communication
|
|
343
|
+
notices without creating employee-specific Consents.
|
|
344
|
+
13. An organization mentioned as the source of a qualification is resolved by
|
|
345
|
+
legal identifier and jurisdiction, and an employer-only attestation is not
|
|
346
|
+
mislabeled as a source-issued credential.
|
|
347
|
+
14. Employer and later source-issuer proofs can coexist without overwriting
|
|
348
|
+
each other.
|
|
349
|
+
15. The result is read back through the public boundary.
|
|
350
|
+
16. When ledger anchoring is claimed, a real local-network transaction ID and
|
|
351
|
+
status readback are retained before Test Network promotion.
|
|
352
|
+
|
|
353
|
+
Unit tests, mocked adapters, interface components and successful HTTP responses
|
|
354
|
+
do not by themselves prove this journey.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Organization contact identity
|
|
2
|
+
|
|
3
|
+
The `antifraud-data-utils-ts/organization-identity` entry point owns neutral,
|
|
4
|
+
deterministic contact identity construction. It contains no portal, transport,
|
|
5
|
+
identity-provider session, storage or role-authorization policy.
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
import {
|
|
9
|
+
StableActorContactKinds,
|
|
10
|
+
buildStableActorIdentifier,
|
|
11
|
+
buildOrganizationEmployeeDidWeb,
|
|
12
|
+
} from 'antifraud-data-utils-ts/organization-identity'
|
|
13
|
+
|
|
14
|
+
const contact = {
|
|
15
|
+
contactKind: StableActorContactKinds.Phone,
|
|
16
|
+
contact: '+16505550111',
|
|
17
|
+
} as const
|
|
18
|
+
|
|
19
|
+
const actorIdentifier = buildStableActorIdentifier(contact)
|
|
20
|
+
const employeeDid = buildOrganizationEmployeeDidWeb({
|
|
21
|
+
...contact,
|
|
22
|
+
organizationDidWeb: 'did:web:example.invalid:organization',
|
|
23
|
+
role: 'ISCO-08|2359',
|
|
24
|
+
})
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The caller selects the contact channel explicitly. A phone value is rejected
|
|
28
|
+
in the email channel, an email is rejected in the phone channel, and an unknown
|
|
29
|
+
channel fails. `normalizeActorContact` strips `mailto:` and normalizes email
|
|
30
|
+
case/whitespace, or strips `tel:` and phone formatting before requiring E.164.
|
|
31
|
+
It never invents an email for a phone account. A leading country calling code
|
|
32
|
+
is required; national-format numbers need an earlier governed normalization
|
|
33
|
+
step with known country context.
|
|
34
|
+
|
|
35
|
+
## Established representations and compatibility
|
|
36
|
+
|
|
37
|
+
The actor identifier retains the existing representation:
|
|
38
|
+
|
|
39
|
+
`urn:multibase:<base58btc(multihash(SHA3-256, normalized-contact))>`
|
|
40
|
+
|
|
41
|
+
The multihash algorithm byte is `0x16` and digest-length byte is `0x20`. The
|
|
42
|
+
employee DID retains the existing organization `did:web` root followed by
|
|
43
|
+
`:employee:<bare-multibase-actor>:<role>` and an optional device suffix. The role
|
|
44
|
+
is separate from the stable actor; two roles for one phone do not require two
|
|
45
|
+
phone accounts. Neither clear contact is embedded in the generated identifier.
|
|
46
|
+
|
|
47
|
+
The algorithm and representation are ported from the published predecessor
|
|
48
|
+
`gdc-common-utils-ts@2.9.30` actor identifier and employee DID helpers. Tests use
|
|
49
|
+
that existing **development dependency only** as a compatibility oracle for
|
|
50
|
+
email case, plus-addresses, URI/format normalization, phone hashes, employee
|
|
51
|
+
DIDs and device suffixes. Email DID compatibility is defined on normalized
|
|
52
|
+
email values; malformed historical inputs are not accepted as new contacts.
|
|
53
|
+
There is no runtime dependency on the frozen package. Existing evidence CID
|
|
54
|
+
and DIDComm attachment code share the same internal base58btc encoder.
|
|
55
|
+
|
|
56
|
+
## Trust boundary and migration scope
|
|
57
|
+
|
|
58
|
+
A contact string is input data, not proof of possession. The owning BFF must
|
|
59
|
+
verify the identity-provider token and bind the selected contact to the exact
|
|
60
|
+
account and protected profile. Organization admission, official contact
|
|
61
|
+
evidence, controller authority, employee role, licence capacity, device grants
|
|
62
|
+
and subject access retain their independent verification requirements.
|
|
63
|
+
|
|
64
|
+
The deterministic contact hash is a continuity identifier; it is not an access
|
|
65
|
+
token, encryption or protection against guessing a known email/phone number.
|
|
66
|
+
Do not substitute a generic organization telephone for an employee's verified
|
|
67
|
+
contact.
|
|
68
|
+
|
|
69
|
+
This entry point does not migrate an existing account, grant or credential.
|
|
70
|
+
Gateway employee creation and SDK enrollment must adopt the contact-aware
|
|
71
|
+
contract separately before a complete phone-only organization lifecycle can be
|
|
72
|
+
claimed. Existing email records are not rewritten automatically and no new
|
|
73
|
+
wire-level contact object is introduced.
|
|
74
|
+
|
|
75
|
+
## Reviewed organization credential drafts
|
|
76
|
+
|
|
77
|
+
The separate `organization-credentials` entry point exports
|
|
78
|
+
`buildOrganizationTestNetworkCredential` and
|
|
79
|
+
`buildTestNetworkOrganizationCredentialSet`, together with their existing
|
|
80
|
+
proof-free canonicalization helpers. The first builds the admission draft; the
|
|
81
|
+
second builds the Organization, legal representative and Service controller
|
|
82
|
+
domain drafts. They neither issue a trusted credential nor verify a signature.
|
|
83
|
+
|
|
84
|
+
Supply exactly one of `controllerEmail` or `controllerTelephone`. For the domain
|
|
85
|
+
set, independently supply exactly one of `legalRepresentativeEmail` or
|
|
86
|
+
`legalRepresentativeTelephone`. A representative and controller may use the
|
|
87
|
+
same verified phone account, or independently verified channels. Missing or
|
|
88
|
+
ambiguous party contacts fail instead of selecting a channel silently.
|
|
89
|
+
|
|
90
|
+
The admission projection preserves `credentialSubject.controller.email` for
|
|
91
|
+
email, and uses Schema.org `telephone` for a phone. Domain Person/owner `sameAs`
|
|
92
|
+
values preserve the established stable actor hash. There is no new wire contact
|
|
93
|
+
object, invented email, DID representation or proof algorithm.
|
|
94
|
+
|
|
95
|
+
The domain builder requires caller-governed `legalRepresentativeOccupation`,
|
|
96
|
+
`controllerOccupation` and `controllerAuthorityRole`; it does not choose
|
|
97
|
+
occupation or authority policy. The trusted domain layer supplies its governed
|
|
98
|
+
values and the gateway verifies their legitimacy. Compatibility tests supply
|
|
99
|
+
the predecessor's role values and compare the complete email JSON bytes.
|
|
100
|
+
|
|
101
|
+
`canonicalizeOrganizationTestNetworkCredential` and
|
|
102
|
+
`canonicalizeTestNetworkOrganizationCredential` retain the predecessor's exact
|
|
103
|
+
recursive proof removal and object-key ordering. This is the existing signing
|
|
104
|
+
payload contract, not a signature algorithm or evidence that a supplied proof
|
|
105
|
+
is valid. The enclosing host/GW still checks the trusted issuer, signer,
|
|
106
|
+
credential type/environment, PDF digest, party contact, controller key and
|
|
107
|
+
validity period.
|
|
108
|
+
|
|
109
|
+
On the reviewed technical-sector Test Network path, the host signs and the GW
|
|
110
|
+
verifies these admission/domain credentials before Offer/Order continuation.
|
|
111
|
+
That path legitimately need not invoke an external ICA. Real ICA issuance is a
|
|
112
|
+
separate verification boundary and must not be claimed from constructing drafts
|
|
113
|
+
or completing host-reviewed admission.
|