@sekyro/node 1.0.0-rc.16 → 1.0.0-rc.17
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 +48 -0
- package/README.md +135 -53
- package/dist/chunk-HQ4S5AND.js +1 -0
- package/dist/{chunk-IM3UCVDB.js → chunk-VO3VIX3L.js} +1 -1
- package/dist/{client-BDULrZqs.d.cts → client-DkpEJOBk.d.cts} +570 -219
- package/dist/{client-BDULrZqs.d.ts → client-DkpEJOBk.d.ts} +570 -219
- package/dist/connect/express/index.d.cts +2 -2
- package/dist/connect/express/index.d.ts +2 -2
- package/dist/connect/express/index.js +1 -1
- package/dist/connect/index.cjs +1 -1
- package/dist/connect/index.d.cts +2 -2
- package/dist/connect/index.d.ts +2 -2
- package/dist/connect/index.js +1 -1
- package/dist/connect/next/index.d.cts +2 -2
- package/dist/connect/next/index.d.ts +2 -2
- package/dist/connect/next/index.js +1 -1
- package/dist/{connector-B90Jh4fv.d.cts → connector-CiZVHNOR.d.ts} +25 -12
- package/dist/{connector-BXzO5Wgf.d.ts → connector-D97yp6iq.d.cts} +25 -12
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +18 -15
- package/dist/index.d.ts +18 -15
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/sbom.cdx.json +7 -7
- package/dist/chunk-J6U2QY7M.js +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,53 @@
|
|
|
1
1
|
# @sekyro/node
|
|
2
2
|
|
|
3
|
+
## 1.0.0-rc.17
|
|
4
|
+
|
|
5
|
+
### Major Changes
|
|
6
|
+
|
|
7
|
+
- d28443c: Breaking: `VerifiedResult.subjectId` is removed. It held the token's `sub`, the same person as `VerifiedResult.personId` without the `per_` prefix: read `personId`. `@sekyro/node/connect` now takes the person from `personId`; its stored claim (`subject_id`) does not change.
|
|
8
|
+
- 5a643ec: Breaking: signals are one field. A session's facts and the duplicate search now arrive as `signals`, the catalog the dashboard uses, and findings have their own API. No alias is kept.
|
|
9
|
+
|
|
10
|
+
Removed:
|
|
11
|
+
|
|
12
|
+
- `Session.riskSignals`: read `Session.signals`. Capture facts are now on the step: `SessionStep.document` (`source`, `findings`), `SessionStep.portrait` (`bound`, `compliant`) and `SessionStep.referenceSource`.
|
|
13
|
+
- `Session.duplicates`, `SessionLifecycleEventData.duplicates` (the `session.*` webhooks) and `VerifiedResult.duplicates`: read the `duplicate_identity` entry of `signals`, whose `details.people` lists the people (`personId`, `externalRef`).
|
|
14
|
+
- The `ResultDuplicate` type: the person is now `PersonRef`.
|
|
15
|
+
- `SessionLifecycleEventData.risk`, `VerifiedResult.risk` and the `ResultRisk` type: read the `network` and `device_integrity` entries of `signals`.
|
|
16
|
+
- `Session.dedupUnavailable` and `SessionLifecycleEventData.dedupUnavailable`: the `face_dedup` step is `skipped` with reason `dedup_unavailable`.
|
|
17
|
+
- `SessionDevice.signals` and the `SessionDeviceSignal` type: the device facts are `device_integrity` entries of `signals`.
|
|
18
|
+
- `verifyResultToken` no longer reads the `sekyro.risk` and `sekyro.duplicates` claims.
|
|
19
|
+
|
|
20
|
+
Added:
|
|
21
|
+
|
|
22
|
+
- `Session.signals`, `SessionLifecycleEventData.signals` (on `session.completed` and `session.failed`) and `VerifiedResult.signals` (from the `sekyro.signals` claim): `SessionSignal[]`, each with `kind`, `severity`, `evidence`, `details` and `signalId`. Types `SessionSignal`, `SignalKind`, `SignalSeverity`, `SignalEvidence`, `PersonRef`.
|
|
23
|
+
- `Session.blockMatches` and `SessionLifecycleEventData.blockMatches`: `BlockMatch[]` (`blockId`, `effect`, and `ruleId` when a rule made the block), your blocks and rules that flagged the session or held it for review.
|
|
24
|
+
- `SessionStep.document`, `SessionStep.portrait`, `SessionStep.referenceSource`, and the types `SessionStepDocument` and `SessionStepPortrait`.
|
|
25
|
+
- `sekyro.signals`: `list`, `listPage`, `iterate`, `get` and `update` over `GET /signals`, `GET /signals/{id}` and `PATCH /signals/{id}` (scopes `signals:read` and `signals:write`). Types `SignalsApi`, `Signal`, `SignalStatus`, `SignalGrade`, `SignalKeyKind`, `ListSignalsQuery`, `UpdateSignalInput`.
|
|
26
|
+
- The `signal.raised` and `signal.escalated` webhook events, typed `SignalEventData`.
|
|
27
|
+
- `ListSessionsQuery.signalKind` (one kind or a list) and `ListSessionsQuery.signalSeverity`, for `sessions.list`, `listPage` and `iterate`.
|
|
28
|
+
|
|
29
|
+
`@sekyro/node/connect` sets its `duplicates` fact from a `duplicate_identity` entry on the token, the webhook or the session view. Its stored claim (the `duplicate` flag) does not change.
|
|
30
|
+
|
|
31
|
+
### Minor Changes
|
|
32
|
+
|
|
33
|
+
- f4840d7: `PriorReviewReason` no longer has `prior_review_rejected`: an earlier review is reused only when it approved the match, so a face match step never ends with that reason.
|
|
34
|
+
- 202fe34: Breaking: the session outcome model. A session has one status and, once it is finished, says why and who closed it.
|
|
35
|
+
|
|
36
|
+
- `SessionStatus` is `created`, `in_progress`, `review_pending`, `verified` or `not_verified`. A session finishes once, as `verified` or `not_verified`.
|
|
37
|
+
- A `not_verified` session carries `reason` (`SessionReason`: `rejected`, `inconclusive`, `unavailable`, `abandoned`, `not_opened`, `policy`, `cancelled` or `superseded`), `reasonCode` (the detailed code, such as `spoof_detected`, `device_cooldown` or `review_timeout`, when one exists) and `step` (`{ id, service }` of the step that decided it, when one did). `supersededBy` names the newer session when `reason` is `superseded`.
|
|
38
|
+
- Every finished session carries `closedBy` (`ClosedBy`: `automatic`, `reviewer`, `deadline`, `expiry` or `organization`); `decision` comes with `closedBy: reviewer`.
|
|
39
|
+
- Each step carries `result` (`StepResult`: `passed`, `rejected`, `inconclusive`, `unreadable`, `unavailable` or `review`, what its last counted attempt said) and `attempts` (`{ used, max }`).
|
|
40
|
+
- Webhooks: `session.started`, `session.review_pending`, `session.verified`, `session.not_verified` and `session.retake_requested`. Each session sends exactly one terminal event, `session.verified` or `session.not_verified`, expiry, cancellation and supersession included. Their data types are `SessionVerifiedEventData` and `SessionNotVerifiedEventData` (with `reason` typed as a `SessionReason`), `SessionReviewPendingEventData` and `SessionRetakeRequestedEventData`; webhook steps are `SessionEventStep` (`{ id, service, state, result?, reason?, attempts, simulated?, decision? }`).
|
|
41
|
+
- A person's sessions (`PersonSession`) and `person.updated` carry `status` and `reason`.
|
|
42
|
+
- Result tokens are minted only for verified sessions: `VerifiedResult.status` is `verified` (the `sekyro.status` claim), and a token without it is refused with `invalid_token`.
|
|
43
|
+
- `sessions.simulate(id, { status, reasonCode? })` ends a Sandbox session as `verified`, `not_verified` (with the `reasonCode` a step on the path fails with) or `review_pending`.
|
|
44
|
+
- Connect: only `session.verified` writes a level. `session.not_verified` carries no result token and is applied from the signed webhook: with `reason: rejected` and `personConflict` it adds the `face_mismatch` flag, otherwise it changes nothing. `sync` on a `not_verified` session writes nothing and returns the stored claim. The merge rule and skip reason for a result that proves no level is `not_verified`.
|
|
45
|
+
- 6d7d1a2: `SessionStep.band` (`SessionStepBand`): on liveness and face match steps, the lines the step decided on, on the same 0 to 1 scale as `calibratedScore`. Below `failBelow` the step fails, at or above `passAtOrAbove` it passes, between them it is reviewed or retried.
|
|
46
|
+
|
|
47
|
+
### Patch Changes
|
|
48
|
+
|
|
49
|
+
- 745caf9: `Session.handoff` (`SessionHandoff`, `SessionHandoffDevice`): when a session started on a computer that was shown the QR code at a camera step and continued on a phone. `from` / `fromSource` / `startedAt`, then `to` / `toSource` / `continuedVia` / `continuedAt` once the phone sent the first camera capture; `fromDevice` is the computer. After a handoff `Session.device` describes the phone. Types only.
|
|
50
|
+
|
|
3
51
|
## 1.0.0-rc.16
|
|
4
52
|
|
|
5
53
|
### Major Changes
|
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ Three jobs, nothing else:
|
|
|
10
10
|
2. **Webhooks**: verify the `x-sekyro-signature` header on deliveries and get
|
|
11
11
|
a typed envelope back.
|
|
12
12
|
3. **Result tokens**: verify the signed result token of a finished session
|
|
13
|
-
(`verifyResultToken`) and read its level
|
|
13
|
+
(`verifyResultToken`) and read its level and assurance.
|
|
14
14
|
|
|
15
15
|
The SDK does **not** orchestrate checks or retry for you; the partner owns the
|
|
16
16
|
retry policy (`SekyroApiError.retryable` tells you when a retry is sensible).
|
|
@@ -64,16 +64,57 @@ created.subjectUse; // 'reference' | 'prefill': whether the flow believes or ch
|
|
|
64
64
|
|
|
65
65
|
// Read: the whitelisted session view (never contains the client token).
|
|
66
66
|
const session = await sekyro.sessions.get(created.id);
|
|
67
|
-
session.status;
|
|
68
|
-
session.
|
|
69
|
-
session.
|
|
70
|
-
session.
|
|
71
|
-
session.
|
|
67
|
+
session.status; // 'created' | 'in_progress' | 'review_pending' | 'verified' | 'not_verified'
|
|
68
|
+
session.reason; // not_verified only: 'rejected' | 'inconclusive' | 'unavailable' | 'abandoned' | 'not_opened' | 'policy' | 'cancelled' | 'superseded'
|
|
69
|
+
session.reasonCode; // not_verified only: the detailed code, e.g. 'spoof_detected', when one exists
|
|
70
|
+
session.closedBy; // finished sessions: 'automatic' | 'reviewer' | 'deadline' | 'expiry' | 'organization'
|
|
71
|
+
session.step; // not_verified only: { id, service } of the step that decided it, when one did
|
|
72
|
+
session.flow; // { id: 'flw_…', slug: 'default', version: 3 }: the flow version the session runs
|
|
73
|
+
session.steps; // [{ id, service, state, result?, reason?, attempts: { used, max }, handled?, calibratedScore?, decision? }]
|
|
72
74
|
session.personId; // 'per_…' once the person passed a verification
|
|
73
75
|
session.identity; // what the session read: names, birth date, document, sources (see Identity data and media)
|
|
74
76
|
session.media; // the media kinds it has: ['document_front', 'selfie', …]
|
|
75
77
|
```
|
|
76
78
|
|
|
79
|
+
A session is open while its status is `created`, `in_progress` or
|
|
80
|
+
`review_pending`, and finishes once, as `verified` or `not_verified`.
|
|
81
|
+
|
|
82
|
+
| `status` | meaning |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `created` | the session exists; nobody opened the link yet |
|
|
85
|
+
| `in_progress` | the person is going through the steps |
|
|
86
|
+
| `review_pending` | a step waits for a person's review; the session stays open |
|
|
87
|
+
| `verified` | the person is verified at `level` |
|
|
88
|
+
| `not_verified` | the session closed without a verification; `reason` says why |
|
|
89
|
+
|
|
90
|
+
| `reason` (on `not_verified`) | meaning |
|
|
91
|
+
|---|---|
|
|
92
|
+
| `rejected` | a check decided against the person, or a reviewer did |
|
|
93
|
+
| `inconclusive` | no verdict could be reached: the model was unsure, the captures stayed unreadable, or a review was not decided by its deadline |
|
|
94
|
+
| `unavailable` | a check could not run |
|
|
95
|
+
| `abandoned` | the person left before a result |
|
|
96
|
+
| `not_opened` | nobody opened the link before it expired |
|
|
97
|
+
| `policy` | a flow rule stopped the session (location, anonymizer, device, eligibility, your blocks) |
|
|
98
|
+
| `cancelled` | you cancelled the session |
|
|
99
|
+
| `superseded` | a newer session of the same person took its review over (`supersededBy` names it) |
|
|
100
|
+
|
|
101
|
+
| `closedBy` | meaning |
|
|
102
|
+
|---|---|
|
|
103
|
+
| `automatic` | the checks closed it |
|
|
104
|
+
| `reviewer` | a person's review decided it (`decision` says how) |
|
|
105
|
+
| `deadline` | the review deadline passed |
|
|
106
|
+
| `expiry` | the link expired |
|
|
107
|
+
| `organization` | you cancelled it |
|
|
108
|
+
|
|
109
|
+
`reasonCode` is the detailed code behind `reason`: the deciding step's reason
|
|
110
|
+
(`spoof_detected`, `face_mismatch`, `underage`, `camera_unavailable`, …), a
|
|
111
|
+
session stop code (`location_not_allowed`, `device_cooldown`,
|
|
112
|
+
`cancelled_by_organization`, …), or `review_timeout`, `review_split`,
|
|
113
|
+
`inference_unavailable` or `superseded_by_retry`. Each step carries `result`
|
|
114
|
+
(`passed`, `rejected`, `inconclusive`, `unreadable`, `unavailable` or `review`,
|
|
115
|
+
what its last counted attempt said) and `attempts` (`{ used, max }`: `used >= max`
|
|
116
|
+
means none is left).
|
|
117
|
+
|
|
77
118
|
Ids are prefixed: `ses_` sessions, `per_` people, `flw_` flows. Every route also
|
|
78
119
|
accepts the bare 24 hexadecimal characters, so an id you stored before keeps
|
|
79
120
|
working.
|
|
@@ -120,12 +161,12 @@ always widens. The changed paths come back on `session.overriddenFields`.
|
|
|
120
161
|
|
|
121
162
|
`flow` takes the app's flow slug or id.
|
|
122
163
|
|
|
123
|
-
The session view also carries `
|
|
124
|
-
`
|
|
125
|
-
|
|
126
|
-
`personId` / `externalRef`, `verifiedContacts`, `eid`, and the end user's
|
|
164
|
+
The session view also carries `retryAfter` (when the device may try again, with
|
|
165
|
+
`reasonCode: 'device_cooldown'`), `overriddenFields`, `signals`
|
|
166
|
+
(see [Signals](#signals)), `blockMatches`, `personId` / `externalRef`, `verifiedContacts`, `eid`, and the end user's
|
|
127
167
|
`network` and `device`. A step with `handled: true` failed, but the flow's
|
|
128
|
-
fallback took over.
|
|
168
|
+
fallback took over. A step whose reason is `camera_unavailable` says why in
|
|
169
|
+
`reasonDetail` (`denied` or `no_camera`).
|
|
129
170
|
|
|
130
171
|
More session calls:
|
|
131
172
|
|
|
@@ -135,19 +176,20 @@ More session calls:
|
|
|
135
176
|
for a method the flow does not offer this session, `409 choice_not_found` when the
|
|
136
177
|
flow has no identity choice.
|
|
137
178
|
- `sekyro.sessions.cancel(id)` stops a session that has not ended: the hosted link
|
|
138
|
-
stops working and one `session.
|
|
139
|
-
is sent (`409 session_not_cancellable` once it ended).
|
|
179
|
+
stops working and one `session.not_verified` with `reason: 'cancelled'` and
|
|
180
|
+
`closedBy: 'organization'` is sent (`409 session_not_cancellable` once it ended).
|
|
140
181
|
- `sekyro.sessions.resendLink(id)` sends the hosted link again through the session's own
|
|
141
182
|
`deliver` channel, to the same destination; `sekyro.sessions.extendLink(id, { ttlMinutes })`
|
|
142
183
|
(or `{ expiresAt }`) gives the link a later expiry within the flow's bounds. Both need a
|
|
143
184
|
session created with `deliver` (`409 link_not_deliverable` otherwise).
|
|
144
185
|
- `sekyro.sessions.list(query)` returns the first page of your sessions, newest first
|
|
145
186
|
(50 by default, up to 100 with `limit`), filtered by `externalRef`, `status`, `flow`,
|
|
146
|
-
`createdAfter
|
|
187
|
+
`createdAfter`, `createdBefore`, `deviceId`, `signalKind` (one kind or a list) and
|
|
188
|
+
`signalSeverity`. `sessions.iterate(query)` reads every page;
|
|
147
189
|
`sessions.listPage(query)` returns one page and its `nextCursor`.
|
|
148
190
|
|
|
149
191
|
```ts
|
|
150
|
-
for await (const s of sekyro.sessions.iterate({ externalRef: userId, status: "
|
|
192
|
+
for await (const s of sekyro.sessions.iterate({ externalRef: userId, status: "verified" })) {
|
|
151
193
|
s.id; // newest first, page after page
|
|
152
194
|
}
|
|
153
195
|
```
|
|
@@ -167,15 +209,17 @@ const me = await sekyro.me();
|
|
|
167
209
|
const { id } = await sekyro.sessions.create({ person: { externalRef: "<your user id>" } });
|
|
168
210
|
const session = await sekyro.sessions.simulate(
|
|
169
211
|
id,
|
|
170
|
-
{
|
|
212
|
+
{ status: "not_verified", reasonCode: "spoof_detected" }, // or { status: "verified" }, { status: "review_pending" }
|
|
171
213
|
{ idempotencyKey: "<your CI run id>" },
|
|
172
214
|
);
|
|
173
215
|
```
|
|
174
216
|
|
|
175
|
-
`
|
|
176
|
-
|
|
177
|
-
`409
|
|
178
|
-
|
|
217
|
+
`reasonCode` is optional and goes only with `not_verified`: the code a step on
|
|
218
|
+
the flow's path fails with. Errors: `400 sandbox_only` (a Live key),
|
|
219
|
+
`409 session_not_simulated` (bound to a tester), `409 session_already_final`,
|
|
220
|
+
`422 simulate_status_unreachable` (the flow cannot reach this status;
|
|
221
|
+
`details.issues` says why) and `422 simulate_reason_invalid` (no step on the
|
|
222
|
+
path can fail with that code).
|
|
179
223
|
See the [Sandbox guide](https://docs.sekyro.ai/en/getting-started/sandbox).
|
|
180
224
|
|
|
181
225
|
### Identity data and media
|
|
@@ -184,9 +228,9 @@ See the [Sandbox guide](https://docs.sekyro.ai/en/getting-started/sandbox).
|
|
|
184
228
|
one `names[]` entry per source and script (`form`: `mrz`, `printed`, `chip`,
|
|
185
229
|
`registry`, `eid` or `supplied`), `birthDate`, `birthPlace[]`, `sex`,
|
|
186
230
|
`nationalities`, `idNumber`, `document` and `sources` (which sources agree on
|
|
187
|
-
each value). It is present once an identity step settled, whatever the
|
|
188
|
-
and it rides on `session.
|
|
189
|
-
for your organization.
|
|
231
|
+
each value). It is present once an identity step settled, whatever the status,
|
|
232
|
+
and it rides on `session.verified` and `session.not_verified` when that is
|
|
233
|
+
enabled for your organization.
|
|
190
234
|
|
|
191
235
|
```ts
|
|
192
236
|
const { items } = await sekyro.sessions.media(id); // [{ kind, check, attempt?, decisive, contentType, url, expiresAt }]
|
|
@@ -339,6 +383,25 @@ try {
|
|
|
339
383
|
}
|
|
340
384
|
```
|
|
341
385
|
|
|
386
|
+
## Signals
|
|
387
|
+
|
|
388
|
+
`session.signals` lists what the session's facts point to, one entry per kind:
|
|
389
|
+
`{ kind, severity, evidence, details?, signalId? }`. The
|
|
390
|
+
terminal `session.*` webhooks and the result token carry the same entries. A
|
|
391
|
+
`duplicate_identity` entry lists the other people the face matched in
|
|
392
|
+
`details.people`.
|
|
393
|
+
|
|
394
|
+
A finding groups the sessions of your environment that share a key and met a
|
|
395
|
+
pattern. Read and mark findings with `sekyro.signals` (scopes `signals:read` and
|
|
396
|
+
`signals:write`); `signal.raised` and `signal.escalated` tell you when one opens or
|
|
397
|
+
its severity rises.
|
|
398
|
+
|
|
399
|
+
```ts
|
|
400
|
+
for await (const f of sekyro.signals.iterate({ severity: "high" })) {
|
|
401
|
+
await sekyro.signals.update(f.id, { status: "reviewed", note: "<your note>" });
|
|
402
|
+
}
|
|
403
|
+
```
|
|
404
|
+
|
|
342
405
|
## People
|
|
343
406
|
|
|
344
407
|
A **person** is the same person across all of your apps (`per_…` ids). Reads
|
|
@@ -353,7 +416,7 @@ person.reference; // { source: 'registry' | 'doc_registry' | 'chip' | 'docu
|
|
|
353
416
|
person.assurance; // 'registry_biometric' | 'chip_biometric' | 'document_biometric' | 'registry_only' | 'document_only' | null
|
|
354
417
|
person.returningReady; // a returning-user session can be created now
|
|
355
418
|
person.level; // the highest level proved: 0 | 1 | 2 | 3 (0 once revoked), null before any
|
|
356
|
-
person.identity; // the identity of the latest
|
|
419
|
+
person.identity; // the identity of the latest verified session that read one
|
|
357
420
|
|
|
358
421
|
const [byRef] = await sekyro.people.list({ externalRef: userId }); // first page, newest first
|
|
359
422
|
for await (const p of sekyro.people.iterate()) p.id; // every page
|
|
@@ -398,13 +461,16 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
|
|
|
398
461
|
);
|
|
399
462
|
// The envelope is discriminated on `event`: narrowing it types `data`.
|
|
400
463
|
switch (envelope.event) {
|
|
401
|
-
case "session.
|
|
402
|
-
|
|
403
|
-
//
|
|
404
|
-
|
|
464
|
+
case "session.verified":
|
|
465
|
+
// { sessionId, status: 'verified', closedBy, decision?, level, assurance, steps, resultToken?, identity?, media?, … }
|
|
466
|
+
envelope.data; // SessionVerifiedEventData
|
|
467
|
+
break;
|
|
468
|
+
case "session.not_verified":
|
|
469
|
+
// { sessionId, status: 'not_verified', reason, reasonCode?, closedBy, step?, decision?, supersededBy?, level: 0, steps, … }
|
|
470
|
+
envelope.data; // SessionNotVerifiedEventData
|
|
405
471
|
break;
|
|
406
|
-
case "session.
|
|
407
|
-
envelope.data; //
|
|
472
|
+
case "session.retake_requested":
|
|
473
|
+
envelope.data; // SessionRetakeRequestedEventData: { sessionId, status: 'in_progress', step, expiresAt }
|
|
408
474
|
break;
|
|
409
475
|
case "person.updated":
|
|
410
476
|
envelope.data; // PersonUpdatedEventData: { personId, status, externalRefs, … }
|
|
@@ -418,6 +484,20 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
|
|
|
418
484
|
});
|
|
419
485
|
```
|
|
420
486
|
|
|
487
|
+
Each session sends exactly one terminal event, `session.verified` or
|
|
488
|
+
`session.not_verified`, expiry, cancellation and supersession included.
|
|
489
|
+
|
|
490
|
+
| event | when | `data` |
|
|
491
|
+
|---|---|---|
|
|
492
|
+
| `session.started` | the person opened the session (`created` to `in_progress`) | `{ sessionId, … }` |
|
|
493
|
+
| `session.review_pending` | a step entered review | `SessionReviewPendingEventData`: `steps[]` with `result`, `reason`, `attempts` |
|
|
494
|
+
| `session.verified` | `status: verified` | `SessionVerifiedEventData`: `closedBy`, `decision?`, `level`, `assurance`, `unit`, `verifiedAt`, `steps[]`, `resultToken?` |
|
|
495
|
+
| `session.not_verified` | `status: not_verified`, any `reason` | `SessionNotVerifiedEventData`: `reason`, `reasonCode?`, `closedBy`, `step?`, `decision?`, `supersededBy?`, `level: 0`, `steps[]` |
|
|
496
|
+
| `session.retake_requested` | a reviewer sent the session back for a new capture | `SessionRetakeRequestedEventData`: `status: in_progress`, `step`, `expiresAt` |
|
|
497
|
+
|
|
498
|
+
Webhook `steps[]` entries are `{ id, service, state, result?, reason?, attempts, simulated?, decision? }`
|
|
499
|
+
(`SessionEventStep`).
|
|
500
|
+
|
|
421
501
|
- The header is `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. During a secret
|
|
422
502
|
rotation Sekyro AI signs with both the current and the previous secret, so the
|
|
423
503
|
delivery is accepted when **any** `v1` matches the secret you hold.
|
|
@@ -434,35 +514,36 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
|
|
|
434
514
|
|
|
435
515
|
When a person decides a step, the step carries `decision`
|
|
436
516
|
(`SessionStepDecision`) on `sekyro.sessions.get` and on the `steps` of the
|
|
437
|
-
`session.*` webhooks, and `session.
|
|
438
|
-
top level with `
|
|
517
|
+
`session.*` webhooks, and `session.verified` / `session.not_verified` carry it at the
|
|
518
|
+
top level with `closedBy: 'reviewer'`:
|
|
439
519
|
`{ source, mode, votes, agreement?, reasons, decidedAt, sessionId? }`.
|
|
440
|
-
`source` is `review` (a reviewer) or `prior_review` (an earlier
|
|
520
|
+
`source` is `review` (a reviewer) or `prior_review` (an earlier approval of the
|
|
441
521
|
same person, reference photo and face was reused; `sessionId` names your
|
|
442
|
-
earlier session).
|
|
522
|
+
earlier session). Only approvals are reused: after an earlier rejection, the new
|
|
523
|
+
session goes through the checks and, when it needs one, to review again. `mode` is `single` or `dual`, `votes` counts the votes that
|
|
443
524
|
formed it and `agreement` says whether two dual reviewers agreed. `reasons`
|
|
444
525
|
(`ReviewReason[]`: `document_authenticity`, `liveness`, `face_match`,
|
|
445
526
|
`data_mismatch`, `screening`, `org_rule`, `other`) says what failed on a rejection, or what was
|
|
446
527
|
overridden on an approval. The object never names a reviewer or a vote.
|
|
447
528
|
|
|
448
|
-
A review that reaches its deadline ends with `session.
|
|
449
|
-
'
|
|
450
|
-
reviewers disagreed and nobody settled it; those carry
|
|
529
|
+
A review that reaches its deadline ends with `session.not_verified`, `reason:
|
|
530
|
+
'inconclusive'`, `closedBy: 'deadline'` and `reasonCode: 'review_timeout'`, or
|
|
531
|
+
`review_split` when two reviewers disagreed and nobody settled it; those carry
|
|
532
|
+
no `decision`.
|
|
451
533
|
|
|
452
|
-
Reason codes of these paths: `prior_review_approved`
|
|
453
|
-
|
|
454
|
-
(`PriorReviewReason`), and `superseded_by_retry` and `review_split` on any
|
|
534
|
+
Reason codes of these paths: `prior_review_approved` on a face match passed by
|
|
535
|
+
an earlier approval (`PriorReviewReason`), and `superseded_by_retry` and `review_split` on any
|
|
455
536
|
reviewed step (`ReviewOutcomeReason`). A session that waited for a review ends
|
|
456
|
-
with `
|
|
457
|
-
takes the review over: `session.
|
|
458
|
-
|
|
537
|
+
`not_verified` with `reason: 'superseded'` when a newer attempt of the same
|
|
538
|
+
person takes the review over: its `session.not_verified` names the newer
|
|
539
|
+
session in `supersededBy`.
|
|
459
540
|
|
|
460
541
|
## Result tokens
|
|
461
542
|
|
|
462
|
-
A
|
|
463
|
-
`session.
|
|
464
|
-
|
|
465
|
-
trusting it:
|
|
543
|
+
A verified session carries a short-lived ES256 JWT: `resultToken` on the
|
|
544
|
+
`session.verified` webhook, or on demand with `sekyro.sessions.resultToken(id)`.
|
|
545
|
+
A token is minted only for a verified session, so a `not_verified` session has
|
|
546
|
+
none. Verify it against the public key set before trusting it:
|
|
466
547
|
|
|
467
548
|
```ts
|
|
468
549
|
import { verifyResultToken, SekyroResultTokenError } from "@sekyro/node";
|
|
@@ -474,7 +555,7 @@ const result = await verifyResultToken(token, {
|
|
|
474
555
|
});
|
|
475
556
|
result.level; // 0 | 1 | 2 | 3 | null (1 human, 2 identity, 3 corroborated)
|
|
476
557
|
result.assurance; // 'live_only' | 'document_biometric' | 'registry_biometric' | ...
|
|
477
|
-
result.
|
|
558
|
+
result.status; // 'verified' (the sekyro.status claim)
|
|
478
559
|
result.personId; // the person id (per_…), when known
|
|
479
560
|
```
|
|
480
561
|
|
|
@@ -487,7 +568,8 @@ result.personId; // the person id (per_…), when known
|
|
|
487
568
|
never passes in production. A missing or other value throws `env_required`.
|
|
488
569
|
- Failures throw `SekyroResultTokenError` with a `code`: `invalid_token`,
|
|
489
570
|
`expired`, `wrong_audience`, `wrong_issuer`, `wrong_env`, `env_required`,
|
|
490
|
-
`key_env_mismatch`, `jwks_unavailable` or `invalid_options`.
|
|
571
|
+
`key_env_mismatch`, `jwks_unavailable` or `invalid_options`. A token whose
|
|
572
|
+
`sekyro.status` claim is not `verified` throws `invalid_token`.
|
|
491
573
|
|
|
492
574
|
When the flow sets a minimum age, `result.age` is `{ over, method }` from the
|
|
493
575
|
`sekyro.age` claim: `over` is the flow's minimum age (never the person's age)
|
|
@@ -495,7 +577,7 @@ and `method` says how it was proved (`estimated` by the age check (selfie)
|
|
|
495
577
|
step, or `document`, `chip`, `registry`, `eid`). The token never carries the
|
|
496
578
|
estimated age; with the step's "Keep and show the estimated age" setting on,
|
|
497
579
|
`estimate` and `sigma` arrive on the session (`sekyro.sessions.get`) and the
|
|
498
|
-
`session.
|
|
580
|
+
`session.verified` webhook only. The connectors
|
|
499
581
|
(`@sekyro/node/connect`, see [Connect](#connect)) carry the answer into your
|
|
500
582
|
auth provider as `age_over` and `age_method` in the `sekyro` claim.
|
|
501
583
|
|
|
@@ -603,11 +685,11 @@ Trust rules:
|
|
|
603
685
|
|
|
604
686
|
- A webhook writes only after its HMAC signature verified; retries are de-duplicated on the envelope id, which is never left recorded for a delivery whose handling failed (see the `store` contract in the guide).
|
|
605
687
|
- A key set outage while checking a result token throws `SekyroConnectError` with code `unavailable`: answer `503` so Sekyro retries, and `400` for every other refusal.
|
|
606
|
-
- When
|
|
607
|
-
- The return URL is a hint: store the session id with your `state` at start and compare both on return; `sync` then reads the session and its signed result token with your API key, verifies the token (your app ids, your environment) and refuses a session of another user, of another app or created without one.
|
|
688
|
+
- Only `session.verified` writes a level. When it carries a result token, the token must verify too (audience, environment, same session, same user), and it is the source of the level, the assurance and the time. `session.not_verified` carries no token and never writes a level; with `reason: 'rejected'` and `personConflict` it adds the `face_mismatch` flag.
|
|
689
|
+
- The return URL is a hint: store the session id with your `state` at start and compare both on return; `sync` then reads the session and its signed result token with your API key, verifies the token (your app ids, your environment) and refuses a session of another user, of another app or created without one. On a `not_verified` session it writes nothing and returns the stored claim with rule `not_verified`.
|
|
608
690
|
- Every input goes through one merge: a failed attempt never erases a proof, a weaker proof never lowers the level, an older result never overwrites a newer one, and a result from the other environment is refused.
|
|
609
691
|
- Writes for one user are serialised: each one reads the stored claim, merges and writes it back through the adapter's optional `update` when it has one (the Firebase adapter does), otherwise under a lock per user inside the connector. That lock is per process: two server instances can still interleave for one user, and a re-check result read just before a revocation could write over it. When that matters, send the webhook route to one instance or queue its deliveries per user id.
|
|
610
|
-
- A revocation or deletion of the person (`person.updated` with `status: 'revoked'`, `person.deleted`) sets the level to 0 with the `revoked` flag (a claim stored without `subject_id` too, when the event's `externalRefs` include the user's id); the gate blocks `revoked` and `face_mismatch` by default. A revoked claim stays revoked: a later result of the same person, or one without a person id, is `revoked_ignored`; only
|
|
692
|
+
- A revocation or deletion of the person (`person.updated` with `status: 'revoked'`, `person.deleted`) sets the level to 0 with the `revoked` flag (a claim stored without `subject_id` too, when the event's `externalRefs` include the user's id); the gate blocks `revoked` and `face_mismatch` by default. A revoked claim stays revoked: a later result of the same person, or one without a person id, is `revoked_ignored`; only a verified session of another person writes a level again.
|
|
611
693
|
|
|
612
694
|
Telemetry: the six Sekyro provider packages tell Sekyro the connector is wired, so the dashboard's
|
|
613
695
|
Connectors page can show it as connected. Every API call carries an `x-sekyro-connector` header
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
var CLAIM_VERSION=1,KNOWN_FLAGS=["face_mismatch","duplicate","revoked"],AGE_METHODS=["estimated","document","chip","registry","eid"];function ageProofOf(over,method){if(!(typeof over!="number"||!Number.isInteger(over)||over<=0)&&!(typeof method!="string"||!AGE_METHODS.includes(method)))return{over,method}}var ageRank=a=>a.method==="estimated"?0:1;function strongerAge(stored,next){if(!stored)return next;if(!next)return stored;let r=ageRank(next)-ageRank(stored);return r!==0?r>0?next:stored:next.over>stored.over?next:stored}var sameAge=(a,b)=>a?.over===b?.over&&a?.method===b?.method;function canonicalId(id){return id.replace(/^(ses|per)_/,"")}function isRecord(v){return typeof v=="object"&&v!==null&&!Array.isArray(v)}function isFiniteNumber(v){return typeof v=="number"&&Number.isFinite(v)}function build(c){let out={v:1,level:c.level,assurance:c.assurance,verified_at:c.verified_at};c.rechecked_at!==void 0&&(out.rechecked_at=c.rechecked_at),out.session_id=c.session_id,c.subject_id!==void 0&&(out.subject_id=canonicalId(c.subject_id)),out.env=c.env;let flags=new Set;for(let f of c.flags??[])KNOWN_FLAGS.includes(f)&&flags.add(f);flags.size>0&&(out.flags=[...flags].sort());let age=ageProofOf(c.age_over,c.age_method);return age&&(out.age_over=age.over,out.age_method=age.method),out}function ageFields(age){return{age_over:age?.over,age_method:age?.method}}function parseClaim(value){let v=value;if(typeof v=="string")try{v=JSON.parse(v)}catch{return null}if(!isRecord(v)||!isFiniteNumber(v.v))return null;if(v.v>1)return v;if(v.v!==1)return null;let level=v.level;return level!==0&&level!==1&&level!==2&&level!==3||typeof v.assurance!="string"||!isFiniteNumber(v.verified_at)||typeof v.session_id!="string"||v.env!=="live"&&v.env!=="sandbox"?null:build({level,assurance:v.assurance,verified_at:v.verified_at,rechecked_at:isFiniteNumber(v.rechecked_at)?v.rechecked_at:void 0,session_id:v.session_id,subject_id:typeof v.subject_id=="string"?v.subject_id:void 0,env:v.env,flags:Array.isArray(v.flags)?v.flags:void 0,age_over:v.age_over,age_method:v.age_method})}function toUnix(isoTime,now){let ms=Date.parse(isoTime);return Math.floor((Number.isFinite(ms)?ms:now())/1e3)}var same=(claim,rule)=>({claim,changed:!1,rule}),wrote=(claim,rule)=>({claim,changed:!0,rule});function mergeClaim(previous,event,opts){let now=opts.now??Date.now,prev=parseClaim(previous);if(prev&&prev.v>1)return same(prev,"unsupported_version");if(event.kind==="revoked"||event.kind==="deleted"){if(!prev)return same(null,"no_change");if(!(prev.subject_id===void 0?event.userInExternalRefs===!0:prev.subject_id===canonicalId(event.subjectId)))return same(prev,"subject_mismatch");if(prev.level===0&&prev.flags?.includes("revoked"))return same(prev,"no_change");let{rechecked_at:_cleared,age_over:_over,age_method:_method,...kept}=prev;return wrote(build({...kept,level:0,subject_id:event.subjectId,flags:["revoked"]}),"revoked")}let r=event.result;if(r.env!==opts.env)return same(prev,"env_mismatch");let t=toUnix(r.verifiedAt,now);if(prev&&t<prev.verified_at)return same(prev,"stale_ignored");let revokedPrev=prev?.flags?.includes("revoked")===!0;if(prev&&revokedPrev&&(r.subjectId===void 0||canonicalId(r.subjectId)===prev.subject_id))return same(prev,"revoked_ignored");if(r.status==="not_verified"&&r.reason==="rejected"&&r.subjectConflict===!0)return!prev||prev.flags?.includes("face_mismatch")?same(prev,"no_change"):wrote(build({...prev,flags:[...prev.flags??[],"face_mismatch"]}),"face_mismatch");if(r.status!=="verified"||r.level===null||r.level===0)return same(prev,"not_verified");let level=r.level,assurance=r.assurance??"none",duplicate=r.duplicates===!0?["duplicate"]:[],nextAge=r.age?ageProofOf(r.age.over,r.age.method):void 0;if(!prev)return wrote(build({level,assurance,verified_at:t,session_id:r.sessionId,subject_id:r.subjectId,env:r.env,flags:duplicate,...ageFields(nextAge)}),"created");let prevAge=ageProofOf(prev.age_over,prev.age_method),otherPerson=prev.subject_id!==void 0&&r.subjectId!==void 0&&canonicalId(r.subjectId)!==prev.subject_id,mergedAge=otherPerson?prevAge:strongerAge(prevAge,nextAge);if(!revokedPrev&&(r.reuseMode==="recheck"||r.returning===!0&&level<=prev.level))return prev.rechecked_at!==void 0&&t<=prev.rechecked_at?same(prev,t<prev.rechecked_at?"stale_ignored":"no_change"):wrote(build({...prev,rechecked_at:t,subject_id:prev.subject_id??r.subjectId,...ageFields(mergedAge)}),"rechecked");if(level>prev.level){let kept=(prev.flags??[]).filter(f=>f!=="face_mismatch"&&f!=="revoked");return wrote(build({...prev,level,assurance,verified_at:t,session_id:r.sessionId,subject_id:r.subjectId??prev.subject_id,flags:[...kept,...duplicate],...ageFields(otherPerson?nextAge:mergedAge)}),"raised")}return level===prev.level&&t>prev.verified_at?wrote(build({...prev,assurance,verified_at:t,session_id:r.sessionId,subject_id:prev.subject_id??r.subjectId,flags:[...prev.flags??[],...duplicate],...ageFields(mergedAge)}),"renewed"):sameAge(mergedAge,prevAge)?same(prev,"no_change"):wrote(build({...prev,subject_id:prev.subject_id??r.subjectId,...ageFields(mergedAge)}),"age_proved")}var DEFAULT_DENY_FLAGS=["revoked","face_mismatch"],fail=(reason,action,claim)=>({ok:!1,reason,action,claim});function evaluateGate(claim,policy,nowSec=Math.floor(Date.now()/1e3)){let parsed=parseClaim(claim);if(!parsed)return fail("no_claim","verify",null);if(parsed.v>1)return fail("unsupported_version","verify",parsed);if(policy.env!==void 0&&parsed.env!==policy.env)return fail("wrong_env","verify",parsed);let deny=policy.denyFlags??DEFAULT_DENY_FLAGS;if(parsed.flags?.some(f=>deny.includes(f)))return fail("flagged","block",parsed);if(parsed.level<policy.level)return fail("level_too_low",parsed.level>=1?"step_up":"verify",parsed);if(policy.maxAgeDays!==void 0&&nowSec-parsed.verified_at>policy.maxAgeDays*86400)return fail("stale","recheck",parsed);if(policy.maxRecheckAgeMinutes!==void 0&&nowSec-(parsed.rechecked_at??parsed.verified_at)>policy.maxRecheckAgeMinutes*60)return fail("recheck_stale","recheck",parsed);if(policy.assurance&&!policy.assurance.includes(parsed.assurance))return fail("assurance_not_allowed","step_up",parsed);if(policy.minAge!==void 0){if(parsed.age_over===void 0||parsed.age_over<policy.minAge)return fail("age_not_proven","verify",parsed);if(policy.ageMethods&&(parsed.age_method===void 0||!policy.ageMethods.includes(parsed.age_method)))return fail("age_method_not_allowed","step_up",parsed)}return{ok:!0,claim:parsed}}export{CLAIM_VERSION,canonicalId,parseClaim,mergeClaim,evaluateGate};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{evaluateGate}from"./chunk-
|
|
1
|
+
import{evaluateGate}from"./chunk-HQ4S5AND.js";function sekyroGate(source,tokenClaims,policy){let claims=tokenClaims??{};if("gate"in source)return source.gate(claims,policy);let effective=source.env!==void 0&&policy.env===void 0?{...policy,env:source.env}:policy;return evaluateGate(source.provider.readClaimFromToken(claims),effective)}function gateRoute(result,routes){if(result.ok)return null;switch(result.action){case"verify":return routes.verify;case"step_up":return routes.stepUp;case"recheck":return routes.recheck;case"block":return routes.block}}export{sekyroGate,gateRoute};
|