@sekyro/node 0.1.0-rc.11 → 0.1.0-rc.12
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 +11 -0
- package/README.md +131 -102
- package/dist/chunk-D53NUEJ6.js +1 -0
- package/dist/{chunk-H5TUZAV5.js → chunk-SZQEL3LK.js} +1 -1
- package/dist/{client-B7_KS_rG.d.cts → client-edr9f2Ec.d.cts} +635 -119
- package/dist/{client-B7_KS_rG.d.ts → client-edr9f2Ec.d.ts} +635 -119
- package/dist/connect/express/index.cjs +1 -1
- 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.cjs +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-S_99xkJf.d.cts → connector-C0M4NWwZ.d.cts} +21 -13
- package/dist/{connector-DHK_cSbs.d.ts → connector-DKP_ebGH.d.ts} +21 -13
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +35 -14
- package/dist/index.d.ts +35 -14
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/sbom.cdx.json +7 -7
- package/dist/chunk-4JZXIGA6.js +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,16 @@
|
|
|
1
1
|
# @sekyro/node
|
|
2
2
|
|
|
3
|
+
## 0.1.0-rc.12
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 6bad03d: `SessionNetworkEvent.anonymizer` gains two optional flags, present only when true: `proxy` (a public open proxy) and `relay` (Apple iCloud Private Relay, a privacy relay that is not counted as an anonymizer). The existing `vpn`, `tor` and `hosting` flags are documented.
|
|
8
|
+
- 71ab282: Partner API contract and identity data. New: `sekyro.people` (`get`, `list`, `listPage`, `iterate`, `revoke`, `delete`, `createSession`) on the `/people` routes, with `per_` ids; `sessions.iterate` and `sessions.listPage` follow the list cursor, and `sessions.list` takes `flow`, `createdAfter`, `createdBefore`, `limit` and `cursor` (it still returns the first page); `sessions.cancel`, `sessions.resendLink` and `sessions.extendLink`; `sessions.media` and `sessions.mediaBytes` for the session's documents, portraits, selfie and clips; `identity` and `media` on sessions, people and the terminal webhooks; `decidedBy`, `personId` and `supersededBy` on sessions; the `person.*` webhook events; the `person` create key with `nationalities`, `document` and per-script `birthPlace`. Errors read the new `{ success: false, error: { requestId } }` envelope and the older one. The connector core handles `person.updated` and `person.deleted` and reads `personId` first.
|
|
9
|
+
|
|
10
|
+
Deprecated for one release, still working: `sekyro.subjects` (the same object as `sekyro.people`), the `Subject*` types, `sessions.portrait` (now served from the media list, scope `sessions:read`) and `portraitAvailable`, `subject` and the `nationality` / `documentNumber` keys, `subjectId` on sessions and webhooks, step `checkType` and `nodeId`, and the `subject.*`, `session.review_decided`, `session.step.completed`, `session.created` and `aml.match_flagged` events. Read `outcome: null` with `supersededBy` instead of `outcome: "superseded"`.
|
|
11
|
+
|
|
12
|
+
`personFromNationalRegistry()` returns a `PersonRecord` for the `person` key, with `nationalities: [code]`; `subjectFromNationalRegistry()`, `SubjectRecord` and `SubjectFromRegistryOptions` stay as deprecated names. `sessions.portrait()` is deprecated for `sessions.media()` and stays on the portrait route for this release. `people.listPage` and the connector's `userDeleted` keep only people whose `externalRefs` include the user id, and the connector handles a person's `subject.*` and `person.*` twin events once. `Session.createdAt` is optional and `Session.eid` is deprecated for `identity.eid`.
|
|
13
|
+
|
|
3
14
|
## 0.1.0-rc.11
|
|
4
15
|
|
|
5
16
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -7,9 +7,8 @@ Three jobs, nothing else:
|
|
|
7
7
|
|
|
8
8
|
1. **Sessions**: create a verification session from your backend and read its
|
|
9
9
|
result. The API key never leaves your server.
|
|
10
|
-
2. **Webhooks**: verify the `x-sekyro-signature` header on deliveries
|
|
11
|
-
|
|
12
|
-
back.
|
|
10
|
+
2. **Webhooks**: verify the `x-sekyro-signature` header on deliveries and get
|
|
11
|
+
a typed envelope back.
|
|
13
12
|
3. **Result tokens**: verify the signed result token of a finished session
|
|
14
13
|
(`verifyResultToken`) and read its level, assurance and outcome.
|
|
15
14
|
|
|
@@ -46,32 +45,39 @@ const sekyro = new Sekyro({
|
|
|
46
45
|
|
|
47
46
|
// Create: returns the one-time client token your front end hands to @sekyro/web.
|
|
48
47
|
// `flow` picks one of the app's flows (omit it for the default flow).
|
|
49
|
-
// `
|
|
50
|
-
// the number (a different one is refused with 409
|
|
48
|
+
// `person.idNumber` BINDS the session to that identity: the browser never sends
|
|
49
|
+
// the number (a different one is refused with a 409).
|
|
51
50
|
const created = await sekyro.sessions.create(
|
|
52
51
|
{
|
|
53
52
|
flow: "default",
|
|
54
53
|
locale: "ar",
|
|
55
|
-
|
|
54
|
+
person: { idNumber: { type: "national_id", issuingCountry: "<ISO alpha-2>", number: "<id number>" } },
|
|
56
55
|
},
|
|
57
56
|
{ idempotencyKey: `signup:${userId}` },
|
|
58
57
|
);
|
|
59
|
-
created.id; // persist against your user before returning to the page
|
|
58
|
+
created.id; // `ses_…`: persist against your user before returning to the page
|
|
60
59
|
created.clientToken; // give this to the browser; it is returned ONCE
|
|
61
60
|
created.hostedUrl; // the hosted-flow link, if you use that path instead
|
|
62
61
|
created.expiresAt; // ISO 8601
|
|
63
62
|
created.flow; // { id, slug, version }: the flow version the session runs
|
|
64
|
-
created.subjectUse; // 'reference' | 'prefill': whether the flow believes or checks your
|
|
65
|
-
created.warnings; // one { code: 'deprecated_field', field, replacement } per deprecated key you sent
|
|
63
|
+
created.subjectUse; // 'reference' | 'prefill': whether the flow believes or checks your person data
|
|
66
64
|
|
|
67
65
|
// Read: the whitelisted session view (never contains the client token).
|
|
68
66
|
const session = await sekyro.sessions.get(created.id);
|
|
69
67
|
session.status; // 'created' | 'in_progress' | 'review_pending' | 'completed' | 'expired' | 'failed'
|
|
70
|
-
session.outcome; // 'approved' | 'review' | 'rejected' | null
|
|
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
|
|
71
70
|
session.flow; // { id: 'flw_…', slug: 'default', version: 3 }: the flow version the session runs
|
|
72
|
-
session.steps; // [{
|
|
71
|
+
session.steps; // [{ id, service, state, handled?, reason?, calibratedScore?, decision? }]
|
|
72
|
+
session.personId; // 'per_…' once the person passed a verification
|
|
73
|
+
session.identity; // what the session read: names, birth date, document, sources (see Identity data and media)
|
|
74
|
+
session.media; // the media kinds it has: ['document_front', 'selfie', …]
|
|
73
75
|
```
|
|
74
76
|
|
|
77
|
+
Ids are prefixed: `ses_` sessions, `per_` people, `flw_` flows. Every route also
|
|
78
|
+
accepts the bare 24 hexadecimal characters, so an id you stored before keeps
|
|
79
|
+
working.
|
|
80
|
+
|
|
75
81
|
Your API key belongs to an **app**. The app's **flows**, designed in the Sekyro AI
|
|
76
82
|
dashboard (app page → **Flows**), decide which steps run; a session runs the
|
|
77
83
|
flow you name in `flow`, or the app's default flow. To list the published flows
|
|
@@ -87,8 +93,8 @@ Every field is optional:
|
|
|
87
93
|
| `overrides` | `{ settings?, services? }`: changes the flow for this session only (see below; `403 override_widens_flow` for a looser change unless the flow allows it, `400 override_invalid` for an invalid one) |
|
|
88
94
|
| `locale` | `ar`, `fr` or `en`: pins the hosted-flow language |
|
|
89
95
|
| `ttlMinutes` | session lifetime, within the flow's link range (`400 ttl_out_of_policy` otherwise); omit for the flow default |
|
|
90
|
-
| `
|
|
91
|
-
| `input` | an open record of branch facts your flow's conditions read
|
|
96
|
+
| `person` | what you know about the person: `idNumber` (`{ type, issuingCountry, number }`, binds the session), `fullName`, `names` (per script), `birthDate`, `birthPlace` (a string or `[{ script, value }]`), `sex`, `nationalities`, `document` (`{ type, issuingCountry, number }`, compared with the capture), `phone`, `email`, and for a reference record `photo`, `photoDate`, `fetchedAt`; your own id for them (`externalRef`), or `reuse` for a [returning user](#people). The flow decides whether the data is checked or believed (`created.subjectUse`) |
|
|
97
|
+
| `input` | an open record of branch facts your flow's conditions read; facts about the person go in `person` |
|
|
92
98
|
| `identityMethod` | `national_number`, `document_photo`, `document_chip` or `national_eid`: pre-chooses the option of the flow's identity choice |
|
|
93
99
|
| `deliver` | `{ channel: "sms" \| "whatsapp", to: "+1555…" }`: also send the hosted link to the person |
|
|
94
100
|
|
|
@@ -118,30 +124,66 @@ always widens. The changed paths come back on `session.overriddenFields`.
|
|
|
118
124
|
The session view also carries `failureReason` (a policy stop such as
|
|
119
125
|
`location_not_allowed` or `underage`), `failureDetail` (why, when that reason
|
|
120
126
|
is `camera_unavailable`: `denied` or `no_camera`), `overriddenFields`, `riskSignals`,
|
|
121
|
-
`
|
|
127
|
+
`personId` / `externalRef`, `verifiedContacts`, `eid`, and the end user's
|
|
122
128
|
`network` and `device`. A step with `handled: true` failed, but the flow's
|
|
123
129
|
fallback took over.
|
|
124
130
|
|
|
125
|
-
|
|
131
|
+
More session calls:
|
|
126
132
|
|
|
127
133
|
- `sekyro.sessions.selectMethod(id, method)` chooses the identity method of a
|
|
128
134
|
session on the person's behalf (`POST /sessions/:id/method`): `409 choice_locked`
|
|
129
135
|
once the flow's identity choice can no longer change, `409 choice_option_unavailable`
|
|
130
136
|
for a method the flow does not offer this session, `409 choice_not_found` when the
|
|
131
137
|
flow has no identity choice.
|
|
132
|
-
- `sekyro.sessions.
|
|
133
|
-
|
|
134
|
-
`
|
|
138
|
+
- `sekyro.sessions.cancel(id)` stops a session that has not ended: the hosted link
|
|
139
|
+
stops working and one `session.failed` with `failureReason: 'cancelled_by_organization'`
|
|
140
|
+
is sent (`409 session_not_cancellable` once it ended).
|
|
141
|
+
- `sekyro.sessions.resendLink(id)` sends the hosted link again through the session's own
|
|
142
|
+
`deliver` channel, to the same destination; `sekyro.sessions.extendLink(id, { ttlMinutes })`
|
|
143
|
+
(or `{ expiresAt }`) gives the link a later expiry within the flow's bounds. Both need a
|
|
144
|
+
session created with `deliver` (`409 link_not_deliverable` otherwise).
|
|
145
|
+
- `sekyro.sessions.list(query)` returns the first page of your sessions, newest first
|
|
146
|
+
(50 by default, up to 100 with `limit`), filtered by `externalRef`, `status`, `flow`,
|
|
147
|
+
`createdAfter` and `createdBefore`. `sessions.iterate(query)` reads every page;
|
|
148
|
+
`sessions.listPage(query)` returns one page and its `nextCursor`.
|
|
149
|
+
|
|
150
|
+
```ts
|
|
151
|
+
for await (const s of sekyro.sessions.iterate({ externalRef: userId, status: "completed" })) {
|
|
152
|
+
s.id; // newest first, page after page
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Identity data and media
|
|
157
|
+
|
|
158
|
+
`session.identity` holds what the session read, with the source of every value:
|
|
159
|
+
one `names[]` entry per source and script (`form`: `mrz`, `printed`, `chip`,
|
|
160
|
+
`registry`, `eid` or `supplied`), `birthDate`, `birthPlace[]`, `sex`,
|
|
161
|
+
`nationalities`, `idNumber`, `document` and `sources` (which sources agree on
|
|
162
|
+
each value). It is present once an identity step settled, whatever the outcome,
|
|
163
|
+
and it rides on `session.completed` and `session.failed` when that is enabled
|
|
164
|
+
for your organization.
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
const { items } = await sekyro.sessions.media(id); // [{ kind, check, attempt?, decisive, contentType, url, expiresAt }]
|
|
168
|
+
const { contentType, bytes } = await sekyro.sessions.mediaBytes(id, "reference_portrait");
|
|
169
|
+
await sekyro.sessions.mediaBytes(id, "liveness_clip", { attempt: 2 });
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
`url` is a download link valid 15 minutes, or the bytes route on this API (read
|
|
173
|
+
it with `mediaBytes`, which sends your key). Both need `sessions:read`. The
|
|
174
|
+
ICAO portrait is the `icao_portrait` media item.
|
|
135
175
|
|
|
136
176
|
`sekyro.sessions` is a `SessionsApi`, exported as a type only: you get the
|
|
137
177
|
instance from the client, never by constructing one.
|
|
138
178
|
|
|
139
179
|
### Person data
|
|
140
180
|
|
|
141
|
-
Send what you know about the person in `
|
|
181
|
+
Send what you know about the person in `person`: `idNumber`
|
|
142
182
|
(`{ type, issuingCountry, number }`), `fullName` or `names` (given, family and
|
|
143
|
-
patronymic per ISO 15924 script), `birthDate`, `
|
|
144
|
-
|
|
183
|
+
patronymic per ISO 15924 script), `birthDate`, `birthPlace` (a string or
|
|
184
|
+
`[{ script, value }]`), `sex`, `nationalities`, `document`
|
|
185
|
+
(`{ type, issuingCountry, number }`), `phone`, `email`, and for a flow that
|
|
186
|
+
verifies identity from your data, `photo` and `fetchedAt`.
|
|
145
187
|
The session's flow decides how Sekyro AI uses it, never the request: when a step
|
|
146
188
|
reads partner-supplied data (an environment Sekyro AI set to the `supplied`
|
|
147
189
|
mode), the record is the **reference** to believe; otherwise it is a
|
|
@@ -153,7 +195,7 @@ page.
|
|
|
153
195
|
```ts
|
|
154
196
|
// A prefill: the flow checks it against the registry or the document.
|
|
155
197
|
await sekyro.sessions.create({
|
|
156
|
-
|
|
198
|
+
person: {
|
|
157
199
|
externalRef: userId,
|
|
158
200
|
idNumber: { type: "passport", issuingCountry: "<ISO alpha-2>", number: "<id number>" },
|
|
159
201
|
birthDate: "<YYYY-MM-DD>",
|
|
@@ -162,21 +204,21 @@ await sekyro.sessions.create({
|
|
|
162
204
|
```
|
|
163
205
|
|
|
164
206
|
If your data comes from your own call to a national registry,
|
|
165
|
-
`
|
|
207
|
+
`personFromNationalRegistry()` converts that answer locally into the
|
|
166
208
|
reference keys. Sekyro AI treats the result as identity data supplied by your
|
|
167
209
|
organization: it makes no registry call, and it never receives or stores any
|
|
168
210
|
registry key.
|
|
169
211
|
|
|
170
212
|
```ts
|
|
171
|
-
import {
|
|
213
|
+
import { personFromNationalRegistry } from "@sekyro/node";
|
|
172
214
|
|
|
173
215
|
const answer = await myRegistryClient.lookup(idNumber); // your call, your key
|
|
174
216
|
const receivedAt = new Date();
|
|
175
217
|
const created = await sekyro.sessions.create({
|
|
176
|
-
|
|
218
|
+
person: {
|
|
177
219
|
externalRef: userId,
|
|
178
220
|
// fetchedAt: when YOUR system received this answer (required; > 24 h old is refused)
|
|
179
|
-
...
|
|
221
|
+
...personFromNationalRegistry("MR", answer, { fetchedAt: receivedAt }),
|
|
180
222
|
},
|
|
181
223
|
});
|
|
182
224
|
created.subjectUse; // "reference" in a supplied-mode environment whose flow reads it
|
|
@@ -184,17 +226,16 @@ created.subjectUse; // "reference" in a supplied-mode environment whose flow rea
|
|
|
184
226
|
|
|
185
227
|
The first argument is the registry's country (ISO alpha-2) and types the
|
|
186
228
|
answer: `"MR"` takes the ANRPTS `getPersonne` answer
|
|
187
|
-
(`AnrptsPersonneResponse`). The result is a `
|
|
229
|
+
(`AnrptsPersonneResponse`). The result is a `PersonRecord`: `idNumber`,
|
|
188
230
|
`names` (one entry per script found), `birthDate`, `birthPlace`, `sex`,
|
|
189
|
-
`
|
|
190
|
-
a number, a birth date, a photo or any name, or with an invalid `fetchedAt`,
|
|
231
|
+
`nationalities` (`[code]`, alpha-2), `photo`, `photoDate` and `fetchedAt`. A
|
|
232
|
+
record without a number, a birth date, a photo or any name, or with an invalid `fetchedAt`,
|
|
191
233
|
throws `SekyroConfigError` `invalid_registry_record` naming the field (never
|
|
192
234
|
its value); a country without an adapter throws `registry_country_unsupported`.
|
|
193
235
|
An answer that states a nationality none of whose values the SDK can map throws
|
|
194
236
|
`registry_nationality_unmapped` (the message never carries the value): map it
|
|
195
237
|
yourself and pass `options.nationality` (ISO alpha-2), so the stated nationality
|
|
196
238
|
is never dropped.
|
|
197
|
-
`subjectFromNationalRegistry()` replaces `registryFromAnrpts()`.
|
|
198
239
|
|
|
199
240
|
Refusals of a reference, in this order: `403 supplied_identity_not_entitled`
|
|
200
241
|
(the environment is not in `supplied` mode), `422 subject_record_incomplete`
|
|
@@ -212,16 +253,11 @@ that the photo shows exactly one clear face before you send it.
|
|
|
212
253
|
Partner-supplied identity data is not billed: the identity step in `supplied` mode
|
|
213
254
|
records no usage event (other steps, such as the face match, bill as usual).
|
|
214
255
|
|
|
215
|
-
|
|
216
|
-
`
|
|
217
|
-
`
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
replacement }`). The step reasons and codes about the number get generic names
|
|
221
|
-
(`registry_record_not_found` for `nni_not_found`, `id_number_locked` for
|
|
222
|
-
`nni_locked`, `document_id_number_mismatch` for `document_nni_mismatch`, ...):
|
|
223
|
-
the API still sends the previous names, so accept both. The full migration
|
|
224
|
-
table is on the [Person data](https://docs.sekyro.ai/en/guides/person-data#deprecated-keys)
|
|
256
|
+
The step reasons and codes about the number have generic names
|
|
257
|
+
(`registry_record_not_found`, `id_number_locked`, `document_id_number_mismatch`, ...)
|
|
258
|
+
and the API sends them as `nni_not_found`, `nni_locked`, `document_nni_mismatch`
|
|
259
|
+
today, so accept both. The table is on the
|
|
260
|
+
[Person data](https://docs.sekyro.ai/en/guides/person-data#renamed-reasons-and-codes)
|
|
225
261
|
page.
|
|
226
262
|
|
|
227
263
|
### Errors
|
|
@@ -233,7 +269,7 @@ Every non-2xx response, network failure and timeout throws `SekyroApiError`:
|
|
|
233
269
|
| `status` | HTTP status (`0` for network / timeout) |
|
|
234
270
|
| `code` | API error code, or `network` / `timeout` / `http_error` / `malformed_response` |
|
|
235
271
|
| `message` | human-readable, from the API when available |
|
|
236
|
-
| `requestId` | the API's `
|
|
272
|
+
| `requestId` | the API's `requestId`, quote it to support |
|
|
237
273
|
| `details` | the API's `error.details` when sent, else `undefined`; typed for the flow codes through `isFlowError()` |
|
|
238
274
|
| `retryable` | `true` for `network`, `timeout`, `429`, `5xx` and `idempotency_in_progress` |
|
|
239
275
|
| `retryAfterSeconds` | seconds to wait from the response's `Retry-After` header (seconds or an HTTP date), else `undefined` |
|
|
@@ -242,7 +278,7 @@ Every non-2xx response, network failure and timeout throws `SekyroApiError`:
|
|
|
242
278
|
import { SekyroApiError } from "@sekyro/node";
|
|
243
279
|
|
|
244
280
|
try {
|
|
245
|
-
await sekyro.sessions.create({
|
|
281
|
+
await sekyro.sessions.create({ person: { idNumber } });
|
|
246
282
|
} catch (err) {
|
|
247
283
|
if (err instanceof SekyroApiError && err.retryable) {
|
|
248
284
|
// wait err.retryAfterSeconds when set, else back off; retry with the SAME idempotencyKey
|
|
@@ -264,7 +300,7 @@ returns `false` when the details are missing or not in that shape, so read
|
|
|
264
300
|
| `409 flow_not_published`, `409 flow_archived` | `sessions.create` | `issues`, `flow` |
|
|
265
301
|
| `400 override_invalid` | `sessions.create` | `issues`, one per problem (`path: "overrides.services.liveness.attempts"`, …) |
|
|
266
302
|
| `403 override_widens_flow` | `sessions.create` | `issues` (`field_widens_flow`), `fields` |
|
|
267
|
-
| `409 reuse_disabled` | `sessions.create` with `
|
|
303
|
+
| `409 reuse_disabled` | `sessions.create` with `person.reuse` | `issues`, `flow` |
|
|
268
304
|
| `409 choice_not_found`, `choice_locked`, `choice_option_unavailable` | `sessions.selectMethod` | `issues` |
|
|
269
305
|
|
|
270
306
|
```ts
|
|
@@ -281,54 +317,52 @@ try {
|
|
|
281
317
|
}
|
|
282
318
|
```
|
|
283
319
|
|
|
284
|
-
##
|
|
320
|
+
## People
|
|
285
321
|
|
|
286
|
-
A **
|
|
287
|
-
`
|
|
288
|
-
from the dashboard carry both; mint a new key if
|
|
322
|
+
A **person** is the same person across all of your apps (`per_…` ids). Reads
|
|
323
|
+
need the `people:read` scope; `revoke` and `delete` need `people:write` (keys
|
|
324
|
+
minted from the dashboard carry both; mint a new key if one answers
|
|
289
325
|
`403 insufficient_scope`).
|
|
290
326
|
|
|
291
327
|
```ts
|
|
292
|
-
const
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
const recent = await sekyro.sessions.list({ externalRef: userId, status: "completed" }); // newest first, at most 100; filters re-applied client-side
|
|
328
|
+
const person = await sekyro.people.get(personId);
|
|
329
|
+
person.status; // 'active' | 'revoked'
|
|
330
|
+
person.reference; // { source: 'registry' | 'doc_registry' | 'chip' | 'document', capturedAt } | null
|
|
331
|
+
person.assurance; // 'registry_biometric' | 'chip_biometric' | 'document_biometric' | 'registry_only' | 'document_only' | null
|
|
332
|
+
person.returningReady; // a returning-user session can be created now
|
|
333
|
+
person.level; // the highest level proved: 0 | 1 | 2 | 3 (0 once revoked), null before any
|
|
334
|
+
person.identity; // the identity of the latest approved session that read one
|
|
300
335
|
|
|
301
|
-
const [byRef] = await sekyro.
|
|
336
|
+
const [byRef] = await sekyro.people.list({ externalRef: userId }); // first page, newest first
|
|
337
|
+
for await (const p of sekyro.people.iterate()) p.id; // every page
|
|
302
338
|
|
|
303
339
|
// Returning user: liveness + face match against the stored reference photo.
|
|
304
|
-
// Name exactly one of subjectId, externalRef or idNumber
|
|
305
|
-
await sekyro.sessions.create({
|
|
340
|
+
// Name exactly one of subjectId (the person id), externalRef or idNumber.
|
|
341
|
+
await sekyro.sessions.create({ person: { reuse: { subjectId: personId } } });
|
|
306
342
|
|
|
307
343
|
// The same in one call, with a mode: `recheck` (verify the same person again)
|
|
308
|
-
// or `step_up` (raise a level 1
|
|
309
|
-
//
|
|
310
|
-
await sekyro.
|
|
344
|
+
// or `step_up` (raise a level 1 person to identity level). A person id (`per_…`
|
|
345
|
+
// or 24 hexadecimal characters) names the person; anything else is your external reference.
|
|
346
|
+
await sekyro.people.createSession(userId, { mode: "step_up", flow: "identity" });
|
|
311
347
|
|
|
312
|
-
await sekyro.
|
|
313
|
-
await sekyro.
|
|
348
|
+
await sekyro.people.revoke(personId, { reason: "account closed" }); // idempotent
|
|
349
|
+
await sekyro.people.delete(personId); // photos, face templates, identifiers and their sessions' data; cannot be undone
|
|
314
350
|
```
|
|
315
351
|
|
|
316
|
-
A
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
`
|
|
320
|
-
|
|
352
|
+
A person is visible once they have passed a verification. A person who never
|
|
353
|
+
passed, an unknown id and a person of another organization or environment all
|
|
354
|
+
answer the same `404 subject_not_found` on `get`, `revoke` and `delete`, and
|
|
355
|
+
`list` leaves them out (the list can be empty while sessions with that
|
|
356
|
+
`externalRef` exist).
|
|
321
357
|
|
|
322
|
-
`
|
|
323
|
-
session finished, or `status: 'revoked'`) and `
|
|
324
|
-
typed on the envelope
|
|
358
|
+
`person.enrolled` (first reference photo stored), `person.updated` (a linked
|
|
359
|
+
session finished, or `status: 'revoked'`) and `person.deleted` webhooks are
|
|
360
|
+
typed on the envelope, with `personId`.
|
|
325
361
|
|
|
326
362
|
## Webhooks
|
|
327
363
|
|
|
328
364
|
Verify with the **raw** request body (bytes as received, before any JSON
|
|
329
|
-
parsing or re-serialisation) and the signature header
|
|
330
|
-
(primary), falling back to the legacy `x-ibtikar-signature` while both are
|
|
331
|
-
sent.
|
|
365
|
+
parsing or re-serialisation) and the signature header, `x-sekyro-signature`.
|
|
332
366
|
|
|
333
367
|
```ts
|
|
334
368
|
import { verifyWebhook, signatureFromHeaders, SekyroWebhookError } from "@sekyro/node";
|
|
@@ -337,23 +371,21 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
|
|
|
337
371
|
try {
|
|
338
372
|
const envelope = verifyWebhook(
|
|
339
373
|
req.body.toString("utf8"),
|
|
340
|
-
signatureFromHeaders(req.headers), // x-sekyro-signature
|
|
374
|
+
signatureFromHeaders(req.headers), // the x-sekyro-signature header
|
|
341
375
|
process.env.SEKYRO_WEBHOOK_SECRET!,
|
|
342
376
|
);
|
|
343
377
|
// The envelope is discriminated on `event`: narrowing it types `data`.
|
|
344
378
|
switch (envelope.event) {
|
|
345
379
|
case "session.completed":
|
|
346
380
|
case "session.failed":
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
case "session.review_decided":
|
|
350
|
-
envelope.data; // SessionReviewDecidedEventData: { sessionId, outcome: 'pass' | 'fail', reason, reasons, decision, flow, … }
|
|
381
|
+
// The one terminal event of a session: { sessionId, status, outcome, decidedBy, decision?, flow, steps, identity?, media?, … }
|
|
382
|
+
envelope.data; // SessionLifecycleEventData
|
|
351
383
|
break;
|
|
352
384
|
case "session.superseded":
|
|
353
|
-
envelope.data; // SessionSupersededEventData: { sessionId, supersededBy,
|
|
385
|
+
envelope.data; // SessionSupersededEventData: { sessionId, supersededBy, reason: 'superseded_by_retry' }
|
|
354
386
|
break;
|
|
355
|
-
case "
|
|
356
|
-
envelope.data; //
|
|
387
|
+
case "person.updated":
|
|
388
|
+
envelope.data; // PersonUpdatedEventData: { personId, status, externalRefs, … }
|
|
357
389
|
break;
|
|
358
390
|
}
|
|
359
391
|
res.sendStatus(200);
|
|
@@ -368,12 +400,9 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
|
|
|
368
400
|
rotation Sekyro AI signs with both the current and the previous secret, so the
|
|
369
401
|
delivery is accepted when **any** `v1` matches the secret you hold.
|
|
370
402
|
- **Header names.** Deliveries carry the signature in `x-sekyro-signature`
|
|
371
|
-
(`SEKYRO_SIGNATURE_HEADER`)
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
header, else the legacy one. The event id/type travel the same way:
|
|
375
|
-
`x-sekyro-event-id` / `x-sekyro-event-type` alongside their `x-ibtikar-*`
|
|
376
|
-
twins.
|
|
403
|
+
(`SEKYRO_SIGNATURE_HEADER`). `signatureFromHeaders()` takes a Fetch `Headers`
|
|
404
|
+
or a Node headers record and returns it. The event id and type travel in
|
|
405
|
+
`x-sekyro-event-id` and `x-sekyro-event-type`.
|
|
377
406
|
- Each `v1` is `HMAC-SHA256(secret, "<t>.<rawBody>")`, compared in constant time.
|
|
378
407
|
- Deliveries older or newer than `toleranceSec` (default 300 s) are rejected as
|
|
379
408
|
`stale`; pass `{ now }` to inject a clock in tests.
|
|
@@ -383,7 +412,8 @@ app.post("/webhooks/sekyro", express.raw({ type: "application/json" }), (req, re
|
|
|
383
412
|
|
|
384
413
|
When a person decides a step, the step carries `decision`
|
|
385
414
|
(`SessionStepDecision`) on `sekyro.sessions.get` and on the `steps` of the
|
|
386
|
-
`session.*` webhooks, and `session.
|
|
415
|
+
`session.*` webhooks, and `session.completed` / `session.failed` carry it at the
|
|
416
|
+
top level with `decidedBy: 'review'`:
|
|
387
417
|
`{ source, mode, votes, agreement?, reasons, decidedAt, sessionId? }`.
|
|
388
418
|
`source` is `review` (a reviewer) or `prior_review` (an earlier review of the
|
|
389
419
|
same person, reference photo and face was reused; `sessionId` names your
|
|
@@ -393,18 +423,17 @@ formed it and `agreement` says whether two dual reviewers agreed. `reasons`
|
|
|
393
423
|
`data_mismatch`, `other`) says what failed on a rejection, or what was
|
|
394
424
|
overridden on an approval. The object never names a reviewer or a vote.
|
|
395
425
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
deadline sends `reason: 'review_timeout'`, or `review_split` when two reviewers
|
|
400
|
-
disagreed and nobody settled it; those carry no `decision`.
|
|
426
|
+
A review that reaches its deadline ends with `session.failed`, `decidedBy:
|
|
427
|
+
'automatic'` and `failureReason: 'review_timeout'`, or `review_split` when two
|
|
428
|
+
reviewers disagreed and nobody settled it; those carry no `decision`.
|
|
401
429
|
|
|
402
430
|
Reason codes of these paths: `prior_review_approved` and
|
|
403
431
|
`prior_review_rejected` on a face match settled by an earlier review
|
|
404
432
|
(`PriorReviewReason`), and `superseded_by_retry` and `review_split` on any
|
|
405
433
|
reviewed step (`ReviewOutcomeReason`). A session that waited for a review ends
|
|
406
|
-
with outcome `
|
|
407
|
-
review over: `session.superseded
|
|
434
|
+
with `outcome: null` and `supersededBy` when a newer attempt of the same person
|
|
435
|
+
takes the review over: `session.superseded`, its one terminal event, names the
|
|
436
|
+
newer session in `supersededBy`.
|
|
408
437
|
|
|
409
438
|
## Result tokens
|
|
410
439
|
|
|
@@ -541,13 +570,13 @@ Trust rules:
|
|
|
541
570
|
- 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.
|
|
542
571
|
- 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.
|
|
543
572
|
- 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.
|
|
544
|
-
- A revocation or deletion of the
|
|
573
|
+
- 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.
|
|
545
574
|
|
|
546
575
|
Telemetry: the six Sekyro provider packages tell Sekyro the connector is wired, so the dashboard's
|
|
547
576
|
Connectors page can show it as connected. Every API call carries an `x-sekyro-connector` header
|
|
548
577
|
(`<provider>/<version>`), and after each claim write, and each revocation the connector could not
|
|
549
578
|
resolve to a user (`revocation_unresolved`), it posts an event with ids only: the event type, the
|
|
550
|
-
provider, the session id, the
|
|
579
|
+
provider, the session id, the person id and the time. Never the claim, a token, a secret or user
|
|
551
580
|
data. Events go in the background with a 2-second timeout and no retry, and never slow or fail a
|
|
552
581
|
webhook. A custom adapter sends nothing. Turn both off with `telemetry: false`:
|
|
553
582
|
|
|
@@ -557,10 +586,10 @@ const connector = createConnector({ /* ... */ provider, telemetry: false });
|
|
|
557
586
|
|
|
558
587
|
Outside a connector, `new Sekyro({ apiKey, connector: { provider, version } })` sends the same header.
|
|
559
588
|
|
|
560
|
-
Revocations it cannot resolve: when Sekyro revokes or deletes a
|
|
589
|
+
Revocations it cannot resolve: when Sekyro revokes or deletes a person and the connector finds no
|
|
561
590
|
user for it (no `externalRefs`, no `store` entry), no claim is cleared and the connector logs
|
|
562
591
|
`revocation_unresolved`. Pass `onRevocationUnresolved` to act on it. The event carries ids only
|
|
563
|
-
(`
|
|
592
|
+
(`personId`, `provider`, `reason`: `revoked` or `deleted`), never provider data. It runs after the
|
|
564
593
|
log line and telemetry event, in the background; a throw or rejection is caught and reported to
|
|
565
594
|
`logger` as `revocation_handler_failed`.
|
|
566
595
|
|
|
@@ -568,8 +597,8 @@ log line and telemetry event, in the background; a throw or rejection is caught
|
|
|
568
597
|
const connector = createConnector({
|
|
569
598
|
/* ... */
|
|
570
599
|
provider,
|
|
571
|
-
onRevocationUnresolved: async ({
|
|
572
|
-
// Find the user for
|
|
600
|
+
onRevocationUnresolved: async ({ personId, reason }) => {
|
|
601
|
+
// Find the user for personId and remove their access.
|
|
573
602
|
},
|
|
574
603
|
});
|
|
575
604
|
```
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
var CLAIM_VERSION=1,KNOWN_FLAGS=["face_mismatch","duplicate","revoked"];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);return flags.size>0&&(out.flags=[...flags].sort()),out}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})}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,...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.outcome==="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.outcome!=="approved"||r.level===null||r.level===0)return same(prev,"not_approved");let level=r.level,assurance=r.assurance??"none",duplicate=r.duplicates===!0?["duplicate"]:[];if(!prev)return wrote(build({level,assurance,verified_at:t,session_id:r.sessionId,subject_id:r.subjectId,env:r.env,flags:duplicate}),"created");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}),"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]}),"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]}),"renewed"):same(prev,"no_change")}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;return parsed.flags?.some(f=>deny.includes(f))?fail("flagged","block",parsed):parsed.level<policy.level?fail("level_too_low",parsed.level>=1?"step_up":"verify",parsed):policy.maxAgeDays!==void 0&&nowSec-parsed.verified_at>policy.maxAgeDays*86400?fail("stale","recheck",parsed):policy.maxRecheckAgeMinutes!==void 0&&nowSec-(parsed.rechecked_at??parsed.verified_at)>policy.maxRecheckAgeMinutes*60?fail("recheck_stale","recheck",parsed):policy.assurance&&!policy.assurance.includes(parsed.assurance)?fail("assurance_not_allowed","step_up",parsed):{ok:!0,claim:parsed}}export{CLAIM_VERSION,canonicalId,parseClaim,mergeClaim,evaluateGate};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{evaluateGate}from"./chunk-
|
|
1
|
+
import{evaluateGate}from"./chunk-D53NUEJ6.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};
|