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.
Files changed (56) hide show
  1. package/CHANGELOG.md +187 -134
  2. package/LICENSE +13 -13
  3. package/README.md +257 -243
  4. package/dist/cryptography/index.d.ts +1 -0
  5. package/dist/cryptography/index.d.ts.map +1 -1
  6. package/dist/cryptography/index.js +1 -0
  7. package/dist/cryptography/index.js.map +1 -1
  8. package/dist/cryptography/numeric-qr.d.ts +4 -0
  9. package/dist/cryptography/numeric-qr.d.ts.map +1 -0
  10. package/dist/cryptography/numeric-qr.js +22 -0
  11. package/dist/cryptography/numeric-qr.js.map +1 -0
  12. package/dist/cryptography/post-quantum-detached-qr.d.ts +14 -0
  13. package/dist/cryptography/post-quantum-detached-qr.d.ts.map +1 -0
  14. package/dist/cryptography/post-quantum-detached-qr.js +76 -0
  15. package/dist/cryptography/post-quantum-detached-qr.js.map +1 -0
  16. package/dist/encoding/base58btc.d.ts +3 -0
  17. package/dist/encoding/base58btc.d.ts.map +1 -0
  18. package/dist/encoding/base58btc.js +19 -0
  19. package/dist/encoding/base58btc.js.map +1 -0
  20. package/dist/identity-assurance/antifraud-data-card.d.ts +42 -0
  21. package/dist/identity-assurance/antifraud-data-card.d.ts.map +1 -0
  22. package/dist/identity-assurance/antifraud-data-card.js +120 -0
  23. package/dist/identity-assurance/antifraud-data-card.js.map +1 -0
  24. package/dist/identity-assurance/didcomm-binary-attachment.d.ts.map +1 -1
  25. package/dist/identity-assurance/didcomm-binary-attachment.js +1 -18
  26. package/dist/identity-assurance/didcomm-binary-attachment.js.map +1 -1
  27. package/dist/identity-assurance/identity-evidence.d.ts.map +1 -1
  28. package/dist/identity-assurance/identity-evidence.js +1 -16
  29. package/dist/identity-assurance/identity-evidence.js.map +1 -1
  30. package/dist/identity-assurance/index.d.ts +1 -0
  31. package/dist/identity-assurance/index.d.ts.map +1 -1
  32. package/dist/identity-assurance/index.js +1 -0
  33. package/dist/identity-assurance/index.js.map +1 -1
  34. package/dist/index.d.ts +3 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +3 -0
  37. package/dist/index.js.map +1 -1
  38. package/dist/organization-credentials.d.ts +75 -0
  39. package/dist/organization-credentials.d.ts.map +1 -0
  40. package/dist/organization-credentials.js +162 -0
  41. package/dist/organization-credentials.js.map +1 -0
  42. package/dist/organization-identity.d.ts +21 -0
  43. package/dist/organization-identity.d.ts.map +1 -0
  44. package/dist/organization-identity.js +47 -0
  45. package/dist/organization-identity.js.map +1 -0
  46. package/dist/service-conversation.d.ts +40 -0
  47. package/dist/service-conversation.d.ts.map +1 -0
  48. package/dist/service-conversation.js +58 -0
  49. package/dist/service-conversation.js.map +1 -0
  50. package/docs/ANTIFRAUD_DATA_CARD_V1.md +47 -0
  51. package/docs/DC4EU_EDUCATION_AND_MEDICAL_CREDENTIALS.md +93 -0
  52. package/docs/DIDCOMM_SCHEMA_ORG_ATTACHMENTS.md +73 -0
  53. package/docs/EDUCATION_ADMINISTRATIVE_ASSISTANT_IDENTITY_EVIDENCE.md +90 -0
  54. package/docs/IDENTITY_VERIFICATION_AND_ATTESTATION.md +354 -0
  55. package/docs/ORGANIZATION_CONTACT_IDENTITY.md +113 -0
  56. 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.