@sekyro/node 1.0.0-rc.16 → 1.0.0-rc.18

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 CHANGED
@@ -1,5 +1,75 @@
1
1
  # @sekyro/node
2
2
 
3
+ ## 1.0.0-rc.18
4
+
5
+ ### Major Changes
6
+
7
+ - db1d4d4: Breaking: the Sandbox speaks the Live contract, and the test tools live under `sekyro.test`.
8
+
9
+ Removed:
10
+
11
+ - `sekyro.sessions.simulate`: call `sekyro.test.sessions.simulate(id, input, opts)`.
12
+ - The `simulated` value of `CreatedSession.delivery.status` and `SessionLinkDelivery.delivery.status`: the status uses the Live values, and a Sandbox send that is not to an enrolled tester carries `simulated: true` instead.
13
+
14
+ Changed:
15
+
16
+ - `SimulateSessionInput` reaches every outcome of the session model: `status`, then optional `reason`, `closedBy`, `reasonCode`, `step` and `then` (`retake`, `decide:approve`, `decide:reject`, `binding_retake`). A pair the model cannot produce answers `422 simulate_pair_invalid`; a session a tester runs real checks in answers `409 session_bound`.
17
+
18
+ Added:
19
+
20
+ - `sekyro.webhooks.test({ event })`: sends a realistic sample of any event to the endpoints of the key's environment. Types `WebhooksApi`, `WebhookTestInput`, `WebhookTestResult`, `SekyroTestApi`, `SessionTestApi`.
21
+ - `sekyro.readiness()`: what Live would change for your integration, from the key environment's sessions of the last 30 days (`GET /readiness`), so CI can assert readiness. Types `ReadinessReport`, `ReadinessProtection`.
22
+
23
+ The connector snippets read `env` from your configuration (`SEKYRO_ENV`) instead of a literal.
24
+
25
+ ## 1.0.0-rc.17
26
+
27
+ ### Major Changes
28
+
29
+ - 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.
30
+ - 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.
31
+
32
+ Removed:
33
+
34
+ - `Session.riskSignals`: read `Session.signals`. Capture facts are now on the step: `SessionStep.document` (`source`, `findings`), `SessionStep.portrait` (`bound`, `compliant`) and `SessionStep.referenceSource`.
35
+ - `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`).
36
+ - The `ResultDuplicate` type: the person is now `PersonRef`.
37
+ - `SessionLifecycleEventData.risk`, `VerifiedResult.risk` and the `ResultRisk` type: read the `network` and `device_integrity` entries of `signals`.
38
+ - `Session.dedupUnavailable` and `SessionLifecycleEventData.dedupUnavailable`: the `face_dedup` step is `skipped` with reason `dedup_unavailable`.
39
+ - `SessionDevice.signals` and the `SessionDeviceSignal` type: the device facts are `device_integrity` entries of `signals`.
40
+ - `verifyResultToken` no longer reads the `sekyro.risk` and `sekyro.duplicates` claims.
41
+
42
+ Added:
43
+
44
+ - `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`.
45
+ - `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.
46
+ - `SessionStep.document`, `SessionStep.portrait`, `SessionStep.referenceSource`, and the types `SessionStepDocument` and `SessionStepPortrait`.
47
+ - `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`.
48
+ - The `signal.raised` and `signal.escalated` webhook events, typed `SignalEventData`.
49
+ - `ListSessionsQuery.signalKind` (one kind or a list) and `ListSessionsQuery.signalSeverity`, for `sessions.list`, `listPage` and `iterate`.
50
+
51
+ `@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.
52
+
53
+ ### Minor Changes
54
+
55
+ - 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.
56
+ - 202fe34: Breaking: the session outcome model. A session has one status and, once it is finished, says why and who closed it.
57
+
58
+ - `SessionStatus` is `created`, `in_progress`, `review_pending`, `verified` or `not_verified`. A session finishes once, as `verified` or `not_verified`.
59
+ - 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`.
60
+ - Every finished session carries `closedBy` (`ClosedBy`: `automatic`, `reviewer`, `deadline`, `expiry` or `organization`); `decision` comes with `closedBy: reviewer`.
61
+ - Each step carries `result` (`StepResult`: `passed`, `rejected`, `inconclusive`, `unreadable`, `unavailable` or `review`, what its last counted attempt said) and `attempts` (`{ used, max }`).
62
+ - 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? }`).
63
+ - A person's sessions (`PersonSession`) and `person.updated` carry `status` and `reason`.
64
+ - 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`.
65
+ - `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`.
66
+ - 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`.
67
+ - 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.
68
+
69
+ ### Patch Changes
70
+
71
+ - 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.
72
+
3
73
  ## 1.0.0-rc.16
4
74
 
5
75
  ### 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, assurance and outcome.
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; // 'created' | 'in_progress' | 'review_pending' | 'completed' | 'expired' | 'failed'
68
- session.outcome; // 'approved' | 'review' | 'rejected' | null (null on a superseded session: see `supersededBy`)
69
- session.decidedBy; // 'automatic' | 'review' on a completed or failed session
70
- session.flow; // { id: 'flw_…', slug: 'default', version: 3 }: the flow version the session runs
71
- session.steps; // [{ id, service, state, handled?, reason?, calibratedScore?, decision? }]
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 `failureReason` (a policy stop such as
124
- `location_not_allowed` or `underage`), `failureDetail` (why, when that reason
125
- is `camera_unavailable`: `denied` or `no_camera`), `overriddenFields`, `riskSignals`,
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.failed` with `failureReason: 'cancelled_by_organization'`
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` and `createdBefore`. `sessions.iterate(query)` reads every page;
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: "completed" })) {
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
  ```
@@ -155,28 +197,58 @@ for await (const s of sekyro.sessions.iterate({ externalRef: userId, status: "co
155
197
  ### Test in the Sandbox
156
198
 
157
199
  A `sk_test_…` key runs on the same API as a `sk_live_…` key; the key chooses the
158
- environment. `sekyro.me()` tells you which key you hold, and
159
- `sekyro.sessions.simulate()` finishes a simulated session in one call, for tests
160
- and CI. It runs the real engine, so the webhooks, the result token and the
161
- dashboard behave as for a session driven by a person. It is never billed.
200
+ environment, and your production code runs unchanged with either. `sekyro.me()`
201
+ tells you which key you hold. The tools for tests and CI live under
202
+ `sekyro.test`, so they stay out of your production path:
203
+ `sekyro.test.sessions.simulate()` ends a simulated session with the outcome you
204
+ name, in one call. It runs the real engine (expiry, cancel, supersession,
205
+ reviewer decision), so the webhooks, the result token and the dashboard behave
206
+ as for a session driven by a person. It is never billed.
162
207
 
163
208
  ```ts
164
209
  const me = await sekyro.me();
165
210
  // { env: "sandbox", keyPrefix, scopes, app: { id, slug, name }, org: { name } }
166
211
 
167
212
  const { id } = await sekyro.sessions.create({ person: { externalRef: "<your user id>" } });
168
- const session = await sekyro.sessions.simulate(
213
+ const session = await sekyro.test.sessions.simulate(
169
214
  id,
170
- { outcome: "rejected", reason: "spoof_detected" }, // or "approved", "review"
215
+ { status: "not_verified", reason: "rejected", reasonCode: "spoof_detected" },
171
216
  { idempotencyKey: "<your CI run id>" },
172
217
  );
218
+ // Other outcomes: { status: "verified" }, { status: "not_verified", reason: "abandoned" },
219
+ // { status: "review_pending", then: "decide:approve" }, { status: "review_pending", then: "retake" }
220
+ ```
221
+
222
+ `status` is required. `reason` and `closedBy` default to the pair the engine
223
+ produces for the path; `reasonCode` and `step` name the step that decides it;
224
+ `then` runs a follow-up: after `review_pending`, `decide:approve`,
225
+ `decide:reject` or `retake`; with `verified`, `binding_retake`. Errors:
226
+ `400 sandbox_only` (a Live key), `409 session_bound` (a tester runs real
227
+ checks in it), `409 session_already_final`,
228
+ `422 simulate_pair_invalid` (`details.validPairs` lists the valid pairs),
229
+ `422 simulate_status_unreachable` (`details.issues` says why) and
230
+ `422 simulate_reason_invalid`.
231
+
232
+ `sekyro.webhooks.test({ event })` sends a realistic sample of any event to the
233
+ endpoints of the key's environment, signed like a real delivery:
234
+
235
+ ```ts
236
+ await sekyro.webhooks.test({ event: "session.verified" }); // { dispatched, endpoints }
173
237
  ```
174
238
 
175
- `reason` is optional and goes only with `rejected`. Errors: `400 sandbox_only`
176
- (a Live key), `409 session_not_simulated` (bound to a tester),
177
- `409 session_already_final`, `422 simulate_outcome_unreachable` (the flow cannot
178
- reach this outcome; `details.issues` says why) and `422 simulate_reason_invalid`.
179
- See the [Sandbox guide](https://docs.sekyro.ai/en/getting-started/sandbox).
239
+ `sekyro.readiness()` reports what Live would change for your integration, from
240
+ the last 30 days of the key environment's sessions: client protections Live
241
+ would enforce, webhook endpoints per environment and failed deliveries, registry
242
+ access per flow, Live rate limits against your peak, and the SDK versions your
243
+ sessions used. Assert on it in CI before you go live:
244
+
245
+ ```ts
246
+ const report = await sekyro.readiness();
247
+ if (report.webhooks.endpoints.live === 0) throw new Error("no Live webhook endpoint");
248
+ ```
249
+
250
+ See the [Sandbox guide](https://docs.sekyro.ai/en/getting-started/sandbox) and
251
+ [Test identities and outcomes](https://docs.sekyro.ai/en/getting-started/test-identities).
180
252
 
181
253
  ### Identity data and media
182
254
 
@@ -184,9 +256,9 @@ See the [Sandbox guide](https://docs.sekyro.ai/en/getting-started/sandbox).
184
256
  one `names[]` entry per source and script (`form`: `mrz`, `printed`, `chip`,
185
257
  `registry`, `eid` or `supplied`), `birthDate`, `birthPlace[]`, `sex`,
186
258
  `nationalities`, `idNumber`, `document` and `sources` (which sources agree on
187
- each value). It is present once an identity step settled, whatever the outcome,
188
- and it rides on `session.completed` and `session.failed` when that is enabled
189
- for your organization.
259
+ each value). It is present once an identity step settled, whatever the status,
260
+ and it rides on `session.verified` and `session.not_verified` when that is
261
+ enabled for your organization.
190
262
 
191
263
  ```ts
192
264
  const { items } = await sekyro.sessions.media(id); // [{ kind, check, attempt?, decisive, contentType, url, expiresAt }]
@@ -277,8 +349,7 @@ Partner-supplied identity data is not billed: the Partner-supplied identity step
277
349
  records no usage event (other steps, such as the face match, bill as usual).
278
350
 
279
351
  The step reasons and codes about the number are `registry_record_not_found`,
280
- `id_number_invalid`, `id_number_locked`, `document_id_number_mismatch` and
281
- `sandbox_id_number_not_seeded`. See
352
+ `id_number_invalid`, `id_number_locked` and `document_id_number_mismatch`. See
282
353
  [Person data](https://docs.sekyro.ai/en/guides/person-data).
283
354
 
284
355
  ### Errors
@@ -339,6 +410,25 @@ try {
339
410
  }
340
411
  ```
341
412
 
413
+ ## Signals
414
+
415
+ `session.signals` lists what the session's facts point to, one entry per kind:
416
+ `{ kind, severity, evidence, details?, signalId? }`. The
417
+ terminal `session.*` webhooks and the result token carry the same entries. A
418
+ `duplicate_identity` entry lists the other people the face matched in
419
+ `details.people`.
420
+
421
+ A finding groups the sessions of your environment that share a key and met a
422
+ pattern. Read and mark findings with `sekyro.signals` (scopes `signals:read` and
423
+ `signals:write`); `signal.raised` and `signal.escalated` tell you when one opens or
424
+ its severity rises.
425
+
426
+ ```ts
427
+ for await (const f of sekyro.signals.iterate({ severity: "high" })) {
428
+ await sekyro.signals.update(f.id, { status: "reviewed", note: "<your note>" });
429
+ }
430
+ ```
431
+
342
432
  ## People
343
433
 
344
434
  A **person** is the same person across all of your apps (`per_…` ids). Reads
@@ -353,7 +443,7 @@ person.reference; // { source: 'registry' | 'doc_registry' | 'chip' | 'docu
353
443
  person.assurance; // 'registry_biometric' | 'chip_biometric' | 'document_biometric' | 'registry_only' | 'document_only' | null
354
444
  person.returningReady; // a returning-user session can be created now
355
445
  person.level; // the highest level proved: 0 | 1 | 2 | 3 (0 once revoked), null before any
356
- person.identity; // the identity of the latest approved session that read one
446
+ person.identity; // the identity of the latest verified session that read one
357
447
 
358
448
  const [byRef] = await sekyro.people.list({ externalRef: userId }); // first page, newest first
359
449
  for await (const p of sekyro.people.iterate()) p.id; // every page
@@ -398,13 +488,16 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
398
488
  );
399
489
  // The envelope is discriminated on `event`: narrowing it types `data`.
400
490
  switch (envelope.event) {
401
- case "session.completed":
402
- case "session.failed":
403
- // The one terminal event of a session: { sessionId, status, outcome, decidedBy, decision?, flow, steps, identity?, media?, … }
404
- envelope.data; // SessionLifecycleEventData
491
+ case "session.verified":
492
+ // { sessionId, status: 'verified', closedBy, decision?, level, assurance, steps, resultToken?, identity?, media?, … }
493
+ envelope.data; // SessionVerifiedEventData
494
+ break;
495
+ case "session.not_verified":
496
+ // { sessionId, status: 'not_verified', reason, reasonCode?, closedBy, step?, decision?, supersededBy?, level: 0, steps, … }
497
+ envelope.data; // SessionNotVerifiedEventData
405
498
  break;
406
- case "session.superseded":
407
- envelope.data; // SessionSupersededEventData: { sessionId, supersededBy, reason: 'superseded_by_retry' }
499
+ case "session.retake_requested":
500
+ envelope.data; // SessionRetakeRequestedEventData: { sessionId, status: 'in_progress', step, expiresAt }
408
501
  break;
409
502
  case "person.updated":
410
503
  envelope.data; // PersonUpdatedEventData: { personId, status, externalRefs, … }
@@ -418,6 +511,20 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
418
511
  });
419
512
  ```
420
513
 
514
+ Each session sends exactly one terminal event, `session.verified` or
515
+ `session.not_verified`, expiry, cancellation and supersession included.
516
+
517
+ | event | when | `data` |
518
+ |---|---|---|
519
+ | `session.started` | the person opened the session (`created` to `in_progress`) | `{ sessionId, … }` |
520
+ | `session.review_pending` | a step entered review | `SessionReviewPendingEventData`: `steps[]` with `result`, `reason`, `attempts` |
521
+ | `session.verified` | `status: verified` | `SessionVerifiedEventData`: `closedBy`, `decision?`, `level`, `assurance`, `unit`, `verifiedAt`, `steps[]`, `resultToken?` |
522
+ | `session.not_verified` | `status: not_verified`, any `reason` | `SessionNotVerifiedEventData`: `reason`, `reasonCode?`, `closedBy`, `step?`, `decision?`, `supersededBy?`, `level: 0`, `steps[]` |
523
+ | `session.retake_requested` | a reviewer sent the session back for a new capture | `SessionRetakeRequestedEventData`: `status: in_progress`, `step`, `expiresAt` |
524
+
525
+ Webhook `steps[]` entries are `{ id, service, state, result?, reason?, attempts, simulated?, decision? }`
526
+ (`SessionEventStep`).
527
+
421
528
  - The header is `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. During a secret
422
529
  rotation Sekyro AI signs with both the current and the previous secret, so the
423
530
  delivery is accepted when **any** `v1` matches the secret you hold.
@@ -434,35 +541,36 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
434
541
 
435
542
  When a person decides a step, the step carries `decision`
436
543
  (`SessionStepDecision`) on `sekyro.sessions.get` and on the `steps` of the
437
- `session.*` webhooks, and `session.completed` / `session.failed` carry it at the
438
- top level with `decidedBy: 'review'`:
544
+ `session.*` webhooks, and `session.verified` / `session.not_verified` carry it at the
545
+ top level with `closedBy: 'reviewer'`:
439
546
  `{ source, mode, votes, agreement?, reasons, decidedAt, sessionId? }`.
440
- `source` is `review` (a reviewer) or `prior_review` (an earlier review of the
547
+ `source` is `review` (a reviewer) or `prior_review` (an earlier approval of the
441
548
  same person, reference photo and face was reused; `sessionId` names your
442
- earlier session). `mode` is `single` or `dual`, `votes` counts the votes that
549
+ earlier session). Only approvals are reused: after an earlier rejection, the new
550
+ session goes through the checks and, when it needs one, to review again. `mode` is `single` or `dual`, `votes` counts the votes that
443
551
  formed it and `agreement` says whether two dual reviewers agreed. `reasons`
444
552
  (`ReviewReason[]`: `document_authenticity`, `liveness`, `face_match`,
445
553
  `data_mismatch`, `screening`, `org_rule`, `other`) says what failed on a rejection, or what was
446
554
  overridden on an approval. The object never names a reviewer or a vote.
447
555
 
448
- A review that reaches its deadline ends with `session.failed`, `decidedBy:
449
- 'automatic'` and `failureReason: 'review_timeout'`, or `review_split` when two
450
- reviewers disagreed and nobody settled it; those carry no `decision`.
556
+ A review that reaches its deadline ends with `session.not_verified`, `reason:
557
+ 'inconclusive'`, `closedBy: 'deadline'` and `reasonCode: 'review_timeout'`, or
558
+ `review_split` when two reviewers disagreed and nobody settled it; those carry
559
+ no `decision`.
451
560
 
452
- Reason codes of these paths: `prior_review_approved` and
453
- `prior_review_rejected` on a face match settled by an earlier review
454
- (`PriorReviewReason`), and `superseded_by_retry` and `review_split` on any
561
+ Reason codes of these paths: `prior_review_approved` on a face match passed by
562
+ an earlier approval (`PriorReviewReason`), and `superseded_by_retry` and `review_split` on any
455
563
  reviewed step (`ReviewOutcomeReason`). A session that waited for a review ends
456
- with `outcome: null` and `supersededBy` when a newer attempt of the same person
457
- takes the review over: `session.superseded`, its one terminal event, names the
458
- newer session in `supersededBy`.
564
+ `not_verified` with `reason: 'superseded'` when a newer attempt of the same
565
+ person takes the review over: its `session.not_verified` names the newer
566
+ session in `supersededBy`.
459
567
 
460
568
  ## Result tokens
461
569
 
462
- A finished session carries a short-lived ES256 JWT: `resultToken` on the
463
- `session.completed` and `session.failed` webhooks, or on demand with
464
- `sekyro.sessions.resultToken(id)`. Verify it against the public key set before
465
- trusting it:
570
+ A verified session carries a short-lived ES256 JWT: `resultToken` on the
571
+ `session.verified` webhook, or on demand with `sekyro.sessions.resultToken(id)`.
572
+ A token is minted only for a verified session, so a `not_verified` session has
573
+ none. Verify it against the public key set before trusting it:
466
574
 
467
575
  ```ts
468
576
  import { verifyResultToken, SekyroResultTokenError } from "@sekyro/node";
@@ -474,7 +582,7 @@ const result = await verifyResultToken(token, {
474
582
  });
475
583
  result.level; // 0 | 1 | 2 | 3 | null (1 human, 2 identity, 3 corroborated)
476
584
  result.assurance; // 'live_only' | 'document_biometric' | 'registry_biometric' | ...
477
- result.outcome; // 'approved' | 'rejected' | ...
585
+ result.status; // 'verified' (the sekyro.status claim)
478
586
  result.personId; // the person id (per_…), when known
479
587
  ```
480
588
 
@@ -487,7 +595,8 @@ result.personId; // the person id (per_…), when known
487
595
  never passes in production. A missing or other value throws `env_required`.
488
596
  - Failures throw `SekyroResultTokenError` with a `code`: `invalid_token`,
489
597
  `expired`, `wrong_audience`, `wrong_issuer`, `wrong_env`, `env_required`,
490
- `key_env_mismatch`, `jwks_unavailable` or `invalid_options`.
598
+ `key_env_mismatch`, `jwks_unavailable` or `invalid_options`. A token whose
599
+ `sekyro.status` claim is not `verified` throws `invalid_token`.
491
600
 
492
601
  When the flow sets a minimum age, `result.age` is `{ over, method }` from the
493
602
  `sekyro.age` claim: `over` is the flow's minimum age (never the person's age)
@@ -495,7 +604,7 @@ and `method` says how it was proved (`estimated` by the age check (selfie)
495
604
  step, or `document`, `chip`, `registry`, `eid`). The token never carries the
496
605
  estimated age; with the step's "Keep and show the estimated age" setting on,
497
606
  `estimate` and `sigma` arrive on the session (`sekyro.sessions.get`) and the
498
- `session.completed` / `session.failed` webhooks only. The connectors
607
+ `session.verified` webhook only. The connectors
499
608
  (`@sekyro/node/connect`, see [Connect](#connect)) carry the answer into your
500
609
  auth provider as `age_over` and `age_method` in the `sekyro` claim.
501
610
 
@@ -529,7 +638,7 @@ import { createConnector } from "@sekyro/node/connect";
529
638
  const connector = createConnector({
530
639
  sekyro: new Sekyro({ apiKey: process.env.SEKYRO_API_KEY! }),
531
640
  appId: process.env.SEKYRO_APP_ID!, // or an array of app ids
532
- env: "live",
641
+ env: process.env.SEKYRO_ENV as "sandbox" | "live", // "sandbox" with an sk_test_ key, "live" with an sk_live_ key
533
642
  webhookSecret: process.env.SEKYRO_WEBHOOK_SECRET!,
534
643
  provider, // from a provider package
535
644
  onUserDeleted: "ignore", // 'ignore' | 'revoke' | 'delete'
@@ -603,11 +712,11 @@ Trust rules:
603
712
 
604
713
  - 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
714
  - 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 the webhook carries a result token it must verify too (audience, environment, same session, same user), and it is the source of the level, the assurance and the time.
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.
715
+ - 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.
716
+ - 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
717
  - 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
718
  - 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 an approved session of another person writes a level again.
719
+ - 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
720
 
612
721
  Telemetry: the six Sekyro provider packages tell Sekyro the connector is wired, so the dashboard's
613
722
  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-J6U2QY7M.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};
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};