@sekyro/node 0.1.0-rc.12 → 0.1.0-rc.14

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,26 @@
1
1
  # @sekyro/node
2
2
 
3
+ ## 0.1.0-rc.14
4
+
5
+ ### Minor Changes
6
+
7
+ - 4323262: `sekyro.blocks` creates, lists, checks and lifts blocks on devices, people, accounts and contacts. `sekyro.devices` reads a device and marks it shared. `sessions.list` filters by `deviceId`.
8
+
9
+ ### Patch Changes
10
+
11
+ - 96a3b2b: `SessionFailureReason` gains `blocked_by_org`: one of your blocks (a device, a person, an account or a contact) stopped the session. Not retryable, not billed. Nothing returns it until blocks are available to your organization.
12
+ - 6a58d80: Sessions carry `device.deviceId`, an opaque device identity inside your organization and environment.
13
+ - c3c8f3e: `Block.ruleId` is now a `rul_...` id and `Block.ruleVersion` is documented, on blocks made by an automatic rule. `ReviewReason` gains `org_rule`, for a review an organization rule asked for.
14
+
15
+ ## 0.1.0-rc.13
16
+
17
+ ### Minor Changes
18
+
19
+ - a43e198: The connector claim carries the proven minimum age. `SekyroClaim` gains `age_over` (the minimum age of the flow that proved it, never the person's age) and `age_method` (`estimated`, `document`, `chip`, `registry` or `eid`), written from the result token's `sekyro.age` (or from the webhook's `age` when a session has no token), never the estimate or a birth date. The claim keeps the stronger proof of the same person: a birth date from identity data beats an estimate, then the higher minimum age wins; a session below the stored level that proved a stronger age writes the age alone (new merge rule `age_proved`), and a revocation or deletion clears it. Gates take `minAge` and `ageMethods`, and fail with `age_not_proven` (action `verify`) or `age_method_not_allowed` (action `step_up`). `AgeMethod` is exported from `@sekyro/node/connect`. Claims without the fields still parse and pass gates without `minAge`.
20
+
21
+ `@sekyro/connect-clerk` sends `age_over` and `age_method` as `null` when absent, so Clerk's deep merge never keeps a cleared age. Its peer range now requires `@sekyro/node` 0.1.0-rc.13 or later, the release that writes the age, so an older adapter cannot run next to a core that writes an age it would never clear.
22
+ - fcba7e9: AML screening. Sessions on a flow with an AML screening step return `screening` (`SessionScreening`: the lists searched, the dataset version, the best score and the matching list entries, or `{ unavailable }` when the lists could not be searched), on `sessions.get()` and in the `session.completed` and `session.failed` data. `people.screen(id, { lists })` screens a person again (billed as one AML screening; pass an `idempotencyKey`), and `people.screenings(id)`, `people.screeningsPage()` and `people.iterateScreenings()` list their history. `aml.match_flagged` is sent again, with a typed payload (`AmlMatchFlaggedEventData`). `CheckType` gains `aml_screening`, the `aml_screening` flow settings take `onHit: "signal"`, `PolicyFailureReason` gains `aml_hit` and `ReviewReason` gains `screening`.
23
+
3
24
  ## 0.1.0-rc.12
4
25
 
5
26
  ### Minor Changes
package/README.md CHANGED
@@ -118,8 +118,7 @@ changes a service's settings, keyed by service id (`liveness`, `phone_otp`,
118
118
  the flow stricter unless the flow allows widening; turning a service `'off'`
119
119
  always widens. The changed paths come back on `session.overriddenFields`.
120
120
 
121
- > **Sekyro flows breaking change.** The `profile` override is gone: use
122
- > `overrides`. `flow` is accepted again, now as the app's flow slug or id.
121
+ `flow` takes the app's flow slug or id.
123
122
 
124
123
  The session view also carries `failureReason` (a policy stop such as
125
124
  `location_not_allowed` or `underage`), `failureDetail` (why, when that reason
@@ -185,8 +184,8 @@ patronymic per ISO 15924 script), `birthDate`, `birthPlace` (a string or
185
184
  (`{ type, issuingCountry, number }`), `phone`, `email`, and for a flow that
186
185
  verifies identity from your data, `photo` and `fetchedAt`.
187
186
  The session's flow decides how Sekyro AI uses it, never the request: when a step
188
- reads partner-supplied data (an environment Sekyro AI set to the `supplied`
189
- mode), the record is the **reference** to believe; otherwise it is a
187
+ reads partner-supplied data (a Partner-supplied identity step on the session's
188
+ path, available in every environment), the record is the **reference** to believe; otherwise it is a
190
189
  **prefill** checked against what the person shows. `created.subjectUse` says
191
190
  which (`"reference"` or `"prefill"`). The rules, the trust table and every
192
191
  error are on the [Person data](https://docs.sekyro.ai/en/guides/person-data)
@@ -206,8 +205,7 @@ await sekyro.sessions.create({
206
205
  If your data comes from your own call to a national registry,
207
206
  `personFromNationalRegistry()` converts that answer locally into the
208
207
  reference keys. Sekyro AI treats the result as identity data supplied by your
209
- organization: it makes no registry call, and it never receives or stores any
210
- registry key.
208
+ organization: it makes no registry call and needs no registry key.
211
209
 
212
210
  ```ts
213
211
  import { personFromNationalRegistry } from "@sekyro/node";
@@ -221,7 +219,7 @@ const created = await sekyro.sessions.create({
221
219
  ...personFromNationalRegistry("MR", answer, { fetchedAt: receivedAt }),
222
220
  },
223
221
  });
224
- created.subjectUse; // "reference" in a supplied-mode environment whose flow reads it
222
+ created.subjectUse; // "reference" when the flow has a Partner-supplied identity step
225
223
  ```
226
224
 
227
225
  The first argument is the registry's country (ISO alpha-2) and types the
@@ -237,8 +235,7 @@ An answer that states a nationality none of whose values the SDK can map throws
237
235
  yourself and pass `options.nationality` (ISO alpha-2), so the stated nationality
238
236
  is never dropped.
239
237
 
240
- Refusals of a reference, in this order: `403 supplied_identity_not_entitled`
241
- (the environment is not in `supplied` mode), `422 subject_record_incomplete`
238
+ Refusals of a reference, in this order: `422 subject_record_incomplete`
242
239
  (`error.details.fields` names the missing keys), `422 subject_record_stale`
243
240
  (obtained more than 24 h ago, or more than 5 min ahead) and
244
241
  `422 subject_photo_unusable` (not a JPEG or PNG of at most 1 MB within the size
@@ -250,15 +247,13 @@ the person consents, at the face match: a photo without one usable face fails th
250
247
  step with `no_face_reference` (or `low_quality_reference`). That step runs after liveness, so check
251
248
  that the photo shows exactly one clear face before you send it.
252
249
 
253
- Partner-supplied identity data is not billed: the identity step in `supplied` mode
250
+ Partner-supplied identity data is not billed: the Partner-supplied identity step
254
251
  records no usage event (other steps, such as the face match, bill as usual).
255
252
 
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)
261
- page.
253
+ The step reasons and codes about the number are `registry_record_not_found`,
254
+ `id_number_invalid`, `id_number_locked`, `document_id_number_mismatch` and
255
+ `sandbox_id_number_not_seeded`. See
256
+ [Person data](https://docs.sekyro.ai/en/guides/person-data).
262
257
 
263
258
  ### Errors
264
259
 
@@ -420,7 +415,7 @@ same person, reference photo and face was reused; `sessionId` names your
420
415
  earlier session). `mode` is `single` or `dual`, `votes` counts the votes that
421
416
  formed it and `agreement` says whether two dual reviewers agreed. `reasons`
422
417
  (`ReviewReason[]`: `document_authenticity`, `liveness`, `face_match`,
423
- `data_mismatch`, `other`) says what failed on a rejection, or what was
418
+ `data_mismatch`, `screening`, `org_rule`, `other`) says what failed on a rejection, or what was
424
419
  overridden on an approval. The object never names a reviewer or a vote.
425
420
 
426
421
  A review that reaches its deadline ends with `session.failed`, `decidedBy:
@@ -449,7 +444,7 @@ const result = await verifyResultToken(token, { appId: process.env.SEKYRO_APP_ID
449
444
  result.level; // 0 | 1 | 2 | 3 | null (1 human, 2 identity, 3 corroborated)
450
445
  result.assurance; // 'live_only' | 'document_biometric' | 'registry_biometric' | ...
451
446
  result.outcome; // 'approved' | 'rejected' | ...
452
- result.subjectId; // the person, when known
447
+ result.subjectId; // the person id without its per_ prefix, when known
453
448
  ```
454
449
 
455
450
  - Keys come from `https://api.sekyro.ai/.well-known/sekyro/jwks.json` and are
@@ -468,9 +463,9 @@ and `method` says how it was proved (`estimated` by the age check (selfie)
468
463
  step, or `document`, `chip`, `registry`, `eid`). The token never carries the
469
464
  estimated age; with the step's "Keep and show the estimated age" setting on,
470
465
  `estimate` and `sigma` arrive on the session (`sekyro.sessions.get`) and the
471
- `session.completed` / `session.failed` webhooks only. To carry the answer into
472
- an identity provider, map it to the claims `sekyro_age_over` (`result.age.over`)
473
- and `sekyro_age_method` (`result.age.method`).
466
+ `session.completed` / `session.failed` webhooks only. The connectors
467
+ (`@sekyro/node/connect`, see [Connect](#connect)) carry the answer into your
468
+ auth provider as `age_over` and `age_method` in the `sekyro` claim.
474
469
 
475
470
  `result.decision` is the `sekyro.decision` claim (`ResultDecision`, the same
476
471
  fields as a step's `decision`), when a person decided a step of the session.
@@ -555,13 +550,23 @@ app.get(
555
550
  // Next.js: sekyroGate() and gateRoute() from "@sekyro/node/connect/next".
556
551
  ```
557
552
 
558
- The claim (unix seconds; never a name, a document number, a photo or a score):
553
+ The claim (unix seconds; never a name, a document number, a photo, a score, a birth date or an estimated age):
559
554
 
560
555
  ```json
561
556
  { "v": 1, "level": 2, "assurance": "document_biometric", "verified_at": 1790000000, "rechecked_at": 1790003600,
562
- "session_id": "<session id>", "subject_id": "<subject id>", "env": "live", "flags": ["face_mismatch"] }
557
+ "session_id": "<session id>", "subject_id": "<subject id>", "env": "live", "flags": ["face_mismatch"],
558
+ "age_over": 18, "age_method": "document" }
563
559
  ```
564
560
 
561
+ `age_over` and `age_method` appear once a session of a flow with a minimum age
562
+ proved it: the flow's minimum age and how (`estimated`, or `document`, `chip`,
563
+ `registry`, `eid`). The claim keeps the stronger proof of the same person (a
564
+ birth date from identity data beats an estimate, then the higher minimum age).
565
+ Gate on it with `minAge`, and `ageMethods` when the route needs a proven birth
566
+ date: `{ level: 1, minAge: 18, ageMethods: ["document", "chip", "registry", "eid"] }`
567
+ fails with `age_not_proven` (action `verify`) or `age_method_not_allowed`
568
+ (action `step_up`).
569
+
565
570
  Trust rules:
566
571
 
567
572
  - 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).
@@ -1 +1 @@
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};
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};
@@ -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.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"]:[],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};