@sekyro/node 1.0.0-rc.20 → 1.0.0-rc.22

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,22 @@
1
1
  # @sekyro/node
2
2
 
3
+ ## 1.0.0-rc.22
4
+
5
+ ### Minor Changes
6
+
7
+ - ef4be5d: `sessions.create({ resumeOpen: true })` and `people.createSession(target, { mode, resumeOpen: true })` return the person's open session of the same purpose instead of creating one. The result carries `resumed` (`true` for the open session, `false` for a new one).
8
+
9
+ ## 1.0.0-rc.21
10
+
11
+ ### Major Changes
12
+
13
+ - c491b0b: Flow overrides: `settings.confirmDetails` (`enabled`, `retake`) replaces `services.summary_confirm`; session steps still report the `summary_confirm` service. `OverridableServiceId` names the services `FlowOverrides.services` accepts.
14
+ - 21d94d7: Levels are renumbered: 1 Contact, 2 Human, 3 Identity. A gate that says identity as `level: 2` must become `level: 3`, and a check for a real person as `level >= 1` must become `level >= 2`; left alone they accept weaker results. Corroborated is no longer a level: gate on `assurance`, for example `{ level: 3, assurance: ["registry_biometric"] }` for a registry match. The stored claim is version 2, and version 1 claims are no longer read: a stored version 1 claim is no claim, so the person reads as not verified (`no_claim`, action `verify`) until a new verification or re-check writes a version 2 claim.
15
+
16
+ - `VerificationAssurance` gains the four Contact values `device_only`, `contact_email`, `contact_phone` and `unbound_identity`.
17
+ - At the same level the claim keeps the stronger assurance: a registry match is never replaced by a document check, and a chip read is never replaced by a national eID sign-in.
18
+ - A gate that fails on the level answers `step_up` for a Human or Identity claim and `verify` for a Contact claim.
19
+
3
20
  ## 1.0.0-rc.20
4
21
 
5
22
  ### Minor Changes
package/README.md CHANGED
@@ -56,9 +56,12 @@ const created = await sekyro.sessions.create(
56
56
  {
57
57
  flow: "default",
58
58
  locale: "ar",
59
- person: { idNumber: { type: "national_id", issuingCountry: "<ISO alpha-2>", number: "<id number>" } },
59
+ // Your own stable id for the person: links their sessions and returning-person checks.
60
+ person: { externalRef: userId, idNumber: { type: "national_id", issuingCountry: "<ISO alpha-2>", number: "<id number>" } },
60
61
  },
61
- { idempotencyKey: `signup:${userId}` },
62
+ // One key per attempt (made when the person clicks, kept for a retry of this request).
63
+ // A key per user would hand back the same, possibly finished, session on the next attempt.
64
+ { idempotencyKey: attemptId },
62
65
  );
63
66
  created.id; // `ses_…`: persist against your user before returning to the page
64
67
  created.clientToken; // give this to the browser; it is returned ONCE
@@ -199,6 +202,34 @@ for await (const s of sekyro.sessions.iterate({ externalRef: userId, status: "ve
199
202
  }
200
203
  ```
201
204
 
205
+ ### Reuse an open session
206
+
207
+ `resumeOpen: true` returns the person's open session instead of creating a new
208
+ one, so a page load or a retry of your own flow does not start a second
209
+ verification. The person is `person.externalRef` (else the `person.reuse`
210
+ target); without one the API answers `400 resume_needs_person_reference`.
211
+
212
+ ```ts
213
+ const s = await sekyro.sessions.create({
214
+ flow: "default",
215
+ person: { externalRef: userId },
216
+ resumeOpen: true,
217
+ });
218
+ s.resumed; // true: the open session (same id, clientToken, hostedUrl, expiresAt)
219
+ // false: a new session
220
+ // The same for a re-check or step-up:
221
+ await sekyro.people.createSession({ externalRef: userId }, { mode: "recheck", resumeOpen: true });
222
+ ```
223
+
224
+ A session is returned when it has the same app and environment, flow version,
225
+ reuse mode and options (`person`, `overrides`, `input`, `identityMethod`,
226
+ `link`, `assistedBy`), status `created` or `in_progress` and at least 120
227
+ seconds left. Its expiry is never extended. A returned session takes no
228
+ creation limit, holds no balance and sends no `session.created` webhook.
229
+ `idempotencyKey` is for network retries of one request; `resumeOpen` is for
230
+ later page loads. See
231
+ [Reuse an open session](https://docs.sekyro.ai/en/getting-started/quickstart#reuse-an-open-session).
232
+
202
233
  ### Test in the Sandbox
203
234
 
204
235
  A `sk_test_…` key runs on the same API as a `sk_live_…` key; the key chooses the
@@ -458,7 +489,7 @@ for await (const p of sekyro.people.iterate()) p.id; // every pag
458
489
  await sekyro.sessions.create({ person: { reuse: { personId } } });
459
490
 
460
491
  // The same in one call, with a mode: `recheck` (verify the same person again)
461
- // or `step_up` (raise a level 1 person to identity level). A person id (`per_…`
492
+ // or `step_up` (raise a Human person to Identity). A person id (`per_…`
462
493
  // or 24 hexadecimal characters) names the person; anything else is your external reference.
463
494
  await sekyro.people.createSession(userId, { mode: "step_up", flow: "identity" });
464
495
 
@@ -585,7 +616,7 @@ const result = await verifyResultToken(token, {
585
616
  // Required. Set SEKYRO_ENV to "sandbox" while you integrate and to "live" at go-live.
586
617
  env: process.env.SEKYRO_ENV as "live" | "sandbox",
587
618
  });
588
- result.level; // 0 | 1 | 2 | 3 | null (1 human, 2 identity, 3 corroborated)
619
+ result.level; // 0 | 1 | 2 | 3 | null (1 Contact, 2 Human, 3 Identity)
589
620
  result.assurance; // 'live_only' | 'document_biometric' | 'registry_biometric' | ...
590
621
  result.status; // 'verified' (the sekyro.status claim)
591
622
  result.personId; // the person id (per_…), when known
@@ -689,27 +720,45 @@ import { requireLevel } from "@sekyro/node/connect/express";
689
720
 
690
721
  app.get(
691
722
  "/payouts",
692
- requireLevel(connector, { level: 2, maxAgeDays: 365 }, { claims: (req) => (req as { auth?: Record<string, unknown> }).auth }),
723
+ requireLevel(connector, { level: 3, maxAgeDays: 365 }, { claims: (req) => (req as { auth?: Record<string, unknown> }).auth }),
693
724
  handler,
694
725
  );
695
726
  // Fails with 403 { error: "sekyro_gate", reason, action }; action is verify | step_up | recheck | block.
696
727
  // Next.js: sekyroGate() and gateRoute() from "@sekyro/node/connect/next".
697
728
  ```
698
729
 
730
+ Levels are 1 Contact, 2 Human (a live, real person) and 3 Identity (who the
731
+ person is). To require a particular proof of identity, add the assurances
732
+ that pass. There is no ordered scale of assurances; name the ones you accept:
733
+
734
+ ```ts
735
+ // A registry match.
736
+ requireLevel(connector, { level: 3, assurance: ["registry_biometric"] }, { claims });
737
+ // A government record of any kind, with or without a face.
738
+ sekyroGate(connector, claims, { level: 3, assurance: ["registry_biometric", "eid_authenticated"] });
739
+ ```
740
+
741
+ A failed assurance answers `assurance_not_allowed` with the action `step_up`.
742
+
699
743
  The claim (unix seconds; never a name, a document number, a photo, a score, a birth date or an estimated age):
700
744
 
701
745
  ```json
702
- { "v": 1, "level": 2, "assurance": "document_biometric", "verified_at": 1790000000, "rechecked_at": 1790003600,
746
+ { "v": 2, "level": 3, "assurance": "document_biometric", "verified_at": 1790000000, "rechecked_at": 1790003600,
703
747
  "session_id": "<session id>", "subject_id": "<person id>", "env": "live", "flags": ["face_mismatch"],
704
748
  "age_over": 18, "age_method": "document" }
705
749
  ```
706
750
 
751
+ `v` is the claim format, always `2`. A stored claim of an older format is no
752
+ claim: the person reads as not verified (`no_claim`) until a new verification
753
+ or re-check writes a version 2 claim. A claim of a newer format is refused
754
+ (`unsupported_version`).
755
+
707
756
  `age_over` and `age_method` appear once a session of a flow with a minimum age
708
757
  proved it: the flow's minimum age and how (`estimated`, or `document`, `chip`,
709
758
  `registry`, `eid`). The claim keeps the stronger proof of the same person (a
710
759
  birth date from identity data beats an estimate, then the higher minimum age).
711
760
  Gate on it with `minAge`, and `ageMethods` when the route needs a proven birth
712
- date: `{ level: 1, minAge: 18, ageMethods: ["document", "chip", "registry", "eid"] }`
761
+ date: `{ level: 2, minAge: 18, ageMethods: ["document", "chip", "registry", "eid"] }`
713
762
  fails with `age_not_proven` (action `verify`) or `age_method_not_allowed`
714
763
  (action `step_up`).
715
764
 
@@ -719,7 +768,7 @@ Trust rules:
719
768
  - 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.
720
769
  - 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.
721
770
  - 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`.
722
- - 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.
771
+ - Every input goes through one merge: a failed attempt never erases a proof, a weaker proof never replaces a stronger one (a higher level wins; at the same level the stronger assurance wins), an older result never overwrites a newer one, and a result from the other environment is refused.
723
772
  - 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.
724
773
  - 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.
725
774
 
@@ -0,0 +1 @@
1
+ var ASSURANCE_ORDER=["device_only","contact_email","contact_phone","unbound_identity","live_only","live_unique","supplied_biometric","document_biometric","eid_authenticated","chip_biometric","registry_biometric"];function standingOf(assurance){return ASSURANCE_ORDER.indexOf(assurance)}var CLAIM_VERSION=2,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:CLAIM_VERSION,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}return!isRecord(v)||!isFiniteNumber(v.v)?null:v.v>CLAIM_VERSION?v:v.v!==CLAIM_VERSION||v.level!==0&&v.level!==1&&v.level!==2&&v.level!==3||typeof v.assurance!="string"||!isFiniteNumber(v.verified_at)||typeof v.session_id!="string"||v.env!=="live"&&v.env!=="sandbox"?null:build({level:v.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>CLAIM_VERSION)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),stronger=level>prev.level||level===prev.level&&standingOf(assurance)>standingOf(prev.assurance);if(!revokedPrev&&(r.reuseMode==="recheck"||r.returning===!0&&!stronger))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(stronger){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&&standingOf(assurance)===standingOf(prev.assurance)&&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>CLAIM_VERSION)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>=2?"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-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};
1
+ import{evaluateGate}from"./chunk-TPQKBAO4.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};
@@ -56,23 +56,26 @@ interface SessionDecidingStep {
56
56
  service: string;
57
57
  }
58
58
  /**
59
- * What a finished session proved: `1` a live, real person (human), `2` that
60
- * person's identity (document, chip, registry or supplied data bound to the
61
- * face), `3` an identity corroborated by an independent source. `0` on a
62
- * rejected session.
59
+ * What a finished session proved: `1` Contact (a contact, a device check or
60
+ * identity data with no live person), `2` Human (a live, real person), `3`
61
+ * Identity (who the person is). `0` when nothing was proven.
63
62
  * @public
64
63
  */
65
64
  type VerificationLevel = 0 | 1 | 2 | 3;
66
65
  /**
67
- * How a session's {@link VerificationLevel} was proved: `live_only` (liveness
68
- * only), `live_unique` (liveness plus a duplicate search), and the
69
- * `*_biometric` values, where a face match bound the person to a document,
70
- * its chip, the registry record or partner-supplied identity data, and
71
- * `eid_authenticated`, where the person signed in with a national digital
72
- * identity (level 3 without a Sekyro selfie).
66
+ * How a session's {@link VerificationLevel} was proved. Level 1:
67
+ * `device_only` (a device and network check), `contact_email`,
68
+ * `contact_phone` (a verified contact), `unbound_identity` (identity data
69
+ * with no live face matched to it). Level 2: `live_only` (liveness only),
70
+ * `live_unique` (liveness plus a duplicate search). Level 3: the
71
+ * `*_biometric` values, where a face match bound the person to
72
+ * partner-supplied identity data, a document, its chip or the registry
73
+ * record, and `eid_authenticated`, where the person signed in with a
74
+ * national digital identity. To require a particular proof, gate on a list
75
+ * of these values, for example `["registry_biometric"]`.
73
76
  * @public
74
77
  */
75
- type VerificationAssurance = "live_only" | "live_unique" | "document_biometric" | "chip_biometric" | "registry_biometric" | "supplied_biometric" | "eid_authenticated";
78
+ type VerificationAssurance = "device_only" | "contact_email" | "contact_phone" | "unbound_identity" | "live_only" | "live_unique" | "supplied_biometric" | "document_biometric" | "eid_authenticated" | "chip_biometric" | "registry_biometric";
76
79
  /** The one billing unit a finished session consumed. @public */
77
80
  type VerificationUnit = "human_verification" | "identity_verification";
78
81
  /** The lowest and highest {@link VerificationLevel} the session's flow can reach. @public */
@@ -285,7 +288,7 @@ interface SignalEventData {
285
288
  /**
286
289
  * How a `person.reuse` session runs: `recheck` verifies the same person
287
290
  * again (liveness and face match against the stored photo), `step_up` raises
288
- * the subject to identity level with a flow that proves level 2 on every path.
291
+ * the subject to identity level with a flow that proves Identity (level 3) on every path.
289
292
  * @public
290
293
  */
291
294
  type SubjectReuseMode = "recheck" | "step_up";
@@ -783,7 +786,7 @@ type SubjectReuseTarget = ({
783
786
  }) & {
784
787
  /**
785
788
  * `recheck` (default) or `step_up` ({@link SubjectReuseMode}). `step_up` on
786
- * a flow that does not prove level 2 on every path answers
789
+ * a flow that does not prove Identity (level 3) on every path answers
787
790
  * `400 step_up_flow_too_weak`.
788
791
  */
789
792
  mode?: SubjectReuseMode;
@@ -791,13 +794,21 @@ type SubjectReuseTarget = ({
791
794
  /** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). @public */
792
795
  type ProfileDocumentType = "carte_identite" | "passport" | "residence_permit";
793
796
  /**
794
- * The services a Sekyro flow is built from. A session's steps
795
- * ({@link SessionStep.service}) and {@link FlowOverrides.services} use these
796
- * ids; one service may run several checks (e.g. `liveness` with an ICAO
797
- * portrait).
797
+ * The services of a session's steps ({@link SessionStep.service}); one service
798
+ * may run several checks (e.g. `liveness` with an ICAO portrait).
799
+ * `summary_confirm` is the confirmation of details, which a flow turns on with
800
+ * its `confirmDetails` setting (see {@link OverridableServiceId}).
798
801
  * @public
799
802
  */
800
803
  type ServiceId = "device_network" | "phone_otp" | "email_otp" | "national_eid" | "document" | "nfc" | "proof_of_address" | "population_registry" | "supplied_identity" | "summary_confirm" | "liveness" | "portrait" | "face_match" | "aml_screening" | "face_dedup" | "age_estimation";
804
+ /**
805
+ * The services a Sekyro flow is built from, as {@link FlowOverrides.services}
806
+ * names them: every {@link ServiceId} except `summary_confirm` (the
807
+ * confirmation of details is the `confirmDetails` setting,
808
+ * {@link FlowOverridableSettings.confirmDetails}).
809
+ * @public
810
+ */
811
+ type OverridableServiceId = Exclude<ServiceId, "summary_confirm">;
801
812
  /**
802
813
  * The general settings of a flow that a session may override (the flow's
803
814
  * `link`, `language` and override policy are not overridable). Country codes
@@ -848,6 +859,15 @@ interface FlowOverridableSettings {
848
859
  };
849
860
  authenticity: "standard" | "off";
850
861
  };
862
+ /**
863
+ * Ask the person to confirm the identity data read from them (`enabled`),
864
+ * and let them retake the identity step from there (`retake`). Turning it on
865
+ * narrows the flow, turning it off widens it; allowing a retake widens it.
866
+ */
867
+ confirmDetails?: {
868
+ enabled: boolean;
869
+ retake: boolean;
870
+ };
851
871
  }
852
872
  /**
853
873
  * Document substitution: the portrait a `document` or `nfc` step produces is
@@ -862,7 +882,7 @@ interface DocumentSubstitutionSettings {
862
882
  failBelow?: number;
863
883
  }
864
884
  /**
865
- * The per-service settings a session may override, by {@link ServiceId}.
885
+ * The per-service settings a session may override, by {@link OverridableServiceId}.
866
886
  * `attempts` limits are per step (absent = the platform default).
867
887
  * @public
868
888
  */
@@ -965,10 +985,6 @@ interface FlowServiceSettings {
965
985
  attempts?: number;
966
986
  };
967
987
  supplied_identity: Record<string, never>;
968
- summary_confirm: {
969
- /** Offer « Reprendre » (re-open the identity source). */
970
- retake: boolean;
971
- };
972
988
  liveness: {
973
989
  /** `off`, selfie ICAO `alert` / `reject`, or `id_document` (ID-photo portrait, always rejects). */
974
990
  icao: "off" | "alert" | "reject" | "id_document";
@@ -1066,7 +1082,7 @@ type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
1066
1082
  interface FlowOverrides {
1067
1083
  settings?: DeepPartial<FlowOverridableSettings>;
1068
1084
  services?: {
1069
- [S in ServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
1085
+ [S in OverridableServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
1070
1086
  };
1071
1087
  }
1072
1088
  /**
@@ -1311,6 +1327,18 @@ interface CreateSessionInput {
1311
1327
  * `400 input_field_misplaced`.
1312
1328
  */
1313
1329
  input?: Record<string, unknown>;
1330
+ /**
1331
+ * Return the person's open session instead of creating one. The person is
1332
+ * `person.externalRef`, else the `person.reuse` target; without either the
1333
+ * API answers `400 resume_needs_person_reference`. An open session of the
1334
+ * same app and environment, flow version, reuse mode and options, with
1335
+ * status `created` or `in_progress` and at least 120 seconds left, is
1336
+ * answered with `resumed: true`, its own `clientToken` and `hostedUrl` and
1337
+ * its own `expiresAt` (never extended). Otherwise a new session is created
1338
+ * (`resumed: false`). Use it to reuse a session across page loads; use
1339
+ * {@link RequestOptions.idempotencyKey} for network retries.
1340
+ */
1341
+ resumeOpen?: boolean;
1314
1342
  }
1315
1343
  /** Per-request options. @public */
1316
1344
  interface RequestOptions {
@@ -1346,6 +1374,11 @@ interface CreatedSession {
1346
1374
  * person's document or registry record). Absent from older API versions.
1347
1375
  */
1348
1376
  subjectUse?: "reference" | "prefill";
1377
+ /**
1378
+ * `true` when {@link CreateSessionInput.resumeOpen} returned the person's
1379
+ * open session (HTTP 200), `false` for a new session (HTTP 201).
1380
+ */
1381
+ resumed?: boolean;
1349
1382
  /**
1350
1383
  * With {@link CreateSessionInput.deliver} only: the send of the hosted link.
1351
1384
  * `failed` never fails the create. `simulated: true` in the Sandbox when the
@@ -1370,6 +1403,8 @@ interface PersonSessionInput {
1370
1403
  /** Session lifetime in minutes, within the flow's link range. */
1371
1404
  ttlMinutes?: number;
1372
1405
  locale?: Locale;
1406
+ /** Return this person's open session of the same purpose (see {@link CreateSessionInput.resumeOpen}). */
1407
+ resumeOpen?: boolean;
1373
1408
  }
1374
1409
  /**
1375
1410
  * Which person {@link PeopleApi.createSession} targets: the person id
@@ -2671,7 +2706,9 @@ declare class SessionsApi {
2671
2706
  /**
2672
2707
  * `POST /sessions`. Returns the one-time `clientToken` — hand it to the
2673
2708
  * browser, never persist it. Pass an `idempotencyKey` so a retried call
2674
- * cannot create a second session.
2709
+ * cannot create a second session, and `resumeOpen: true` to get the
2710
+ * person's open session back instead of a new one on every page load
2711
+ * (`resumed: true`).
2675
2712
  */
2676
2713
  create(input?: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
2677
2714
  /**
@@ -3043,4 +3080,4 @@ declare class Sekyro {
3043
3080
  readiness(): Promise<ReadinessReport>;
3044
3081
  }
3045
3082
 
3046
- export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type ConnectorIdentity as D, type CreateBlockInput as E, type FetchLike as F, type CreateSessionInput as G, DEFAULT_BASE_URL as H, DEFAULT_TIMEOUT_MS as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, type SessionReason as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, Sekyro as a, type ScreeningUnavailableReason as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityAddress as a3, type IdentityBirthPlace as a4, type IdentityDocument as a5, type IdentityIdNumber as a6, type IdentityMethod as a7, type IdentityName as a8, type IdentityProofOfAddress as a9, type PersonSession as aA, type PersonSessionInput as aB, type PersonSessionTarget as aC, type PersonUpdatedEventData as aD, type PoaDocumentKind as aE, type PoaReason as aF, type PoaRule as aG, type PoaRuleKind as aH, type PoaRules as aI, type PortraitReportEntry as aJ, type PriorReviewReason as aK, type ProbeBindingReason as aL, type ProbeQuality as aM, type ProfileDocumentType as aN, type ReadinessProtection as aO, type ReadinessReport as aP, type RequestOptions as aQ, type ResultTokenResponse as aR, type ReviewOutcomeReason as aS, type RevokePersonInput as aT, type ScreenPersonInput as aU, type Screening as aV, type ScreeningHit as aW, type ScreeningHitSummary as aX, type ScreeningList as aY, type ScreeningStatus as aZ, type ScreeningTrigger as a_, type IdentityScalarKey as aa, type IdentitySource as ab, type IdentitySources as ac, type LevelTarget as ad, type LiftBlockInput as ae, type ListBlocksQuery as af, type ListPeopleQuery as ag, type ListScreeningsQuery as ah, type ListSessionsQuery as ai, type ListSignalsQuery as aj, type MatchReason as ak, type MediaBytes as al, type MediaBytesOptions as am, type MediaItem as an, type MediaKind as ao, type MediaList as ap, type NameForm as aq, type Page as ar, PeopleApi as as, type Person as at, type PersonAddressInput as au, type PersonBirthPlaceInput as av, type PersonDeletedEventData as aw, type PersonDocumentInput as ax, type PersonEnrolledEventData as ay, type PersonRef as az, type ServiceId as b, type SekyroOptions as b0, SekyroTestApi as b1, type Session as b2, type SessionClosedEventDataBase as b3, type SessionDecidingStep as b4, type SessionDevice as b5, type SessionEventDataBase as b6, type SessionEventStep as b7, type SessionFailureReason as b8, type SessionFlowRef as b9, type SignalKeyKind as bA, type SignalKind as bB, type SignalSeverity as bC, type SignalStatus as bD, SignalsApi as bE, type SimulateSessionInput as bF, type StepResult as bG, type SubjectAssurance as bH, type SubjectIdNumber as bI, type SubjectName as bJ, type SubjectReferenceSource as bK, type SubjectReuseTarget as bL, type SubjectStatus as bM, type UpdateSignalInput as bN, type UsageThresholdReachedEventData as bO, type VerifiedContacts as bP, type WebhookEnvelopeOf as bQ, type WebhookEventDataMap as bR, type WebhookTestInput as bS, type WebhookTestResult as bT, WebhooksApi as bU, type SessionHandoff as ba, type SessionHandoffDevice as bb, type SessionLifecycleEventData as bc, type SessionLinkDelivery as bd, type SessionLinkExpiry as be, type SessionLinkInput as bf, type SessionNetwork as bg, type SessionNetworkEvent as bh, type SessionNotVerifiedEventData as bi, type SessionRetakeRequestedEventData as bj, type SessionReviewPendingEventData as bk, type SessionScreening as bl, type SessionStatus as bm, type SessionStep as bn, type SessionStepAttempts as bo, type SessionStepBand as bp, type SessionStepDecision as bq, type SessionStepDocument as br, type SessionStepPortrait as bs, SessionTestApi as bt, type SessionVerifiedEventData as bu, SessionsApi as bv, type Signal as bw, type SignalEventData as bx, type SignalEvidence as by, type SignalGrade as bz, type SessionPersonInput as c, type WebhookEnvelope as d, type SekyroEnvironment as e, type VerificationAssurance as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultCheckProofs as i, type SessionSignal as j, type FailureIdentification as k, type AgeResult as l, type AmlMatchFlaggedEventData as m, type ApiKeyIdentity as n, type BlockCheck as o, type BlockCheckInput as p, type BlockDuration as q, type BlockIdNumber as r, type BlockKind as s, type BlockMatch as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ClosedBy as z };
3083
+ export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type ConnectorIdentity as D, type CreateBlockInput as E, type FetchLike as F, type CreateSessionInput as G, DEFAULT_BASE_URL as H, DEFAULT_TIMEOUT_MS as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, type SessionReason as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, Sekyro as a, type ScreeningTrigger as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityAddress as a3, type IdentityBirthPlace as a4, type IdentityDocument as a5, type IdentityIdNumber as a6, type IdentityMethod as a7, type IdentityName as a8, type IdentityProofOfAddress as a9, type PersonRef as aA, type PersonSession as aB, type PersonSessionInput as aC, type PersonSessionTarget as aD, type PersonUpdatedEventData as aE, type PoaDocumentKind as aF, type PoaReason as aG, type PoaRule as aH, type PoaRuleKind as aI, type PoaRules as aJ, type PortraitReportEntry as aK, type PriorReviewReason as aL, type ProbeBindingReason as aM, type ProbeQuality as aN, type ProfileDocumentType as aO, type ReadinessProtection as aP, type ReadinessReport as aQ, type RequestOptions as aR, type ResultTokenResponse as aS, type ReviewOutcomeReason as aT, type RevokePersonInput as aU, type ScreenPersonInput as aV, type Screening as aW, type ScreeningHit as aX, type ScreeningHitSummary as aY, type ScreeningList as aZ, type ScreeningStatus as a_, type IdentityScalarKey as aa, type IdentitySource as ab, type IdentitySources as ac, type LevelTarget as ad, type LiftBlockInput as ae, type ListBlocksQuery as af, type ListPeopleQuery as ag, type ListScreeningsQuery as ah, type ListSessionsQuery as ai, type ListSignalsQuery as aj, type MatchReason as ak, type MediaBytes as al, type MediaBytesOptions as am, type MediaItem as an, type MediaKind as ao, type MediaList as ap, type NameForm as aq, type OverridableServiceId as ar, type Page as as, PeopleApi as at, type Person as au, type PersonAddressInput as av, type PersonBirthPlaceInput as aw, type PersonDeletedEventData as ax, type PersonDocumentInput as ay, type PersonEnrolledEventData as az, type ServiceId as b, type ScreeningUnavailableReason as b0, type SekyroOptions as b1, SekyroTestApi as b2, type Session as b3, type SessionClosedEventDataBase as b4, type SessionDecidingStep as b5, type SessionDevice as b6, type SessionEventDataBase as b7, type SessionEventStep as b8, type SessionFailureReason as b9, type SignalGrade as bA, type SignalKeyKind as bB, type SignalKind as bC, type SignalSeverity as bD, type SignalStatus as bE, SignalsApi as bF, type SimulateSessionInput as bG, type StepResult as bH, type SubjectAssurance as bI, type SubjectIdNumber as bJ, type SubjectName as bK, type SubjectReferenceSource as bL, type SubjectReuseTarget as bM, type SubjectStatus as bN, type UpdateSignalInput as bO, type UsageThresholdReachedEventData as bP, type VerifiedContacts as bQ, type WebhookEnvelopeOf as bR, type WebhookEventDataMap as bS, type WebhookTestInput as bT, type WebhookTestResult as bU, WebhooksApi as bV, type SessionFlowRef as ba, type SessionHandoff as bb, type SessionHandoffDevice as bc, type SessionLifecycleEventData as bd, type SessionLinkDelivery as be, type SessionLinkExpiry as bf, type SessionLinkInput as bg, type SessionNetwork as bh, type SessionNetworkEvent as bi, type SessionNotVerifiedEventData as bj, type SessionRetakeRequestedEventData as bk, type SessionReviewPendingEventData as bl, type SessionScreening as bm, type SessionStatus as bn, type SessionStep as bo, type SessionStepAttempts as bp, type SessionStepBand as bq, type SessionStepDecision as br, type SessionStepDocument as bs, type SessionStepPortrait as bt, SessionTestApi as bu, type SessionVerifiedEventData as bv, SessionsApi as bw, type Signal as bx, type SignalEventData as by, type SignalEvidence as bz, type SessionPersonInput as c, type WebhookEnvelope as d, type SekyroEnvironment as e, type VerificationAssurance as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultCheckProofs as i, type SessionSignal as j, type FailureIdentification as k, type AgeResult as l, type AmlMatchFlaggedEventData as m, type ApiKeyIdentity as n, type BlockCheck as o, type BlockCheckInput as p, type BlockDuration as q, type BlockIdNumber as r, type BlockKind as s, type BlockMatch as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ClosedBy as z };
@@ -56,23 +56,26 @@ interface SessionDecidingStep {
56
56
  service: string;
57
57
  }
58
58
  /**
59
- * What a finished session proved: `1` a live, real person (human), `2` that
60
- * person's identity (document, chip, registry or supplied data bound to the
61
- * face), `3` an identity corroborated by an independent source. `0` on a
62
- * rejected session.
59
+ * What a finished session proved: `1` Contact (a contact, a device check or
60
+ * identity data with no live person), `2` Human (a live, real person), `3`
61
+ * Identity (who the person is). `0` when nothing was proven.
63
62
  * @public
64
63
  */
65
64
  type VerificationLevel = 0 | 1 | 2 | 3;
66
65
  /**
67
- * How a session's {@link VerificationLevel} was proved: `live_only` (liveness
68
- * only), `live_unique` (liveness plus a duplicate search), and the
69
- * `*_biometric` values, where a face match bound the person to a document,
70
- * its chip, the registry record or partner-supplied identity data, and
71
- * `eid_authenticated`, where the person signed in with a national digital
72
- * identity (level 3 without a Sekyro selfie).
66
+ * How a session's {@link VerificationLevel} was proved. Level 1:
67
+ * `device_only` (a device and network check), `contact_email`,
68
+ * `contact_phone` (a verified contact), `unbound_identity` (identity data
69
+ * with no live face matched to it). Level 2: `live_only` (liveness only),
70
+ * `live_unique` (liveness plus a duplicate search). Level 3: the
71
+ * `*_biometric` values, where a face match bound the person to
72
+ * partner-supplied identity data, a document, its chip or the registry
73
+ * record, and `eid_authenticated`, where the person signed in with a
74
+ * national digital identity. To require a particular proof, gate on a list
75
+ * of these values, for example `["registry_biometric"]`.
73
76
  * @public
74
77
  */
75
- type VerificationAssurance = "live_only" | "live_unique" | "document_biometric" | "chip_biometric" | "registry_biometric" | "supplied_biometric" | "eid_authenticated";
78
+ type VerificationAssurance = "device_only" | "contact_email" | "contact_phone" | "unbound_identity" | "live_only" | "live_unique" | "supplied_biometric" | "document_biometric" | "eid_authenticated" | "chip_biometric" | "registry_biometric";
76
79
  /** The one billing unit a finished session consumed. @public */
77
80
  type VerificationUnit = "human_verification" | "identity_verification";
78
81
  /** The lowest and highest {@link VerificationLevel} the session's flow can reach. @public */
@@ -285,7 +288,7 @@ interface SignalEventData {
285
288
  /**
286
289
  * How a `person.reuse` session runs: `recheck` verifies the same person
287
290
  * again (liveness and face match against the stored photo), `step_up` raises
288
- * the subject to identity level with a flow that proves level 2 on every path.
291
+ * the subject to identity level with a flow that proves Identity (level 3) on every path.
289
292
  * @public
290
293
  */
291
294
  type SubjectReuseMode = "recheck" | "step_up";
@@ -783,7 +786,7 @@ type SubjectReuseTarget = ({
783
786
  }) & {
784
787
  /**
785
788
  * `recheck` (default) or `step_up` ({@link SubjectReuseMode}). `step_up` on
786
- * a flow that does not prove level 2 on every path answers
789
+ * a flow that does not prove Identity (level 3) on every path answers
787
790
  * `400 step_up_flow_too_weak`.
788
791
  */
789
792
  mode?: SubjectReuseMode;
@@ -791,13 +794,21 @@ type SubjectReuseTarget = ({
791
794
  /** A document type the backend reads (kyc-docs-v2 vocabulary; `carte_identite` = identity card of any issuer). @public */
792
795
  type ProfileDocumentType = "carte_identite" | "passport" | "residence_permit";
793
796
  /**
794
- * The services a Sekyro flow is built from. A session's steps
795
- * ({@link SessionStep.service}) and {@link FlowOverrides.services} use these
796
- * ids; one service may run several checks (e.g. `liveness` with an ICAO
797
- * portrait).
797
+ * The services of a session's steps ({@link SessionStep.service}); one service
798
+ * may run several checks (e.g. `liveness` with an ICAO portrait).
799
+ * `summary_confirm` is the confirmation of details, which a flow turns on with
800
+ * its `confirmDetails` setting (see {@link OverridableServiceId}).
798
801
  * @public
799
802
  */
800
803
  type ServiceId = "device_network" | "phone_otp" | "email_otp" | "national_eid" | "document" | "nfc" | "proof_of_address" | "population_registry" | "supplied_identity" | "summary_confirm" | "liveness" | "portrait" | "face_match" | "aml_screening" | "face_dedup" | "age_estimation";
804
+ /**
805
+ * The services a Sekyro flow is built from, as {@link FlowOverrides.services}
806
+ * names them: every {@link ServiceId} except `summary_confirm` (the
807
+ * confirmation of details is the `confirmDetails` setting,
808
+ * {@link FlowOverridableSettings.confirmDetails}).
809
+ * @public
810
+ */
811
+ type OverridableServiceId = Exclude<ServiceId, "summary_confirm">;
801
812
  /**
802
813
  * The general settings of a flow that a session may override (the flow's
803
814
  * `link`, `language` and override policy are not overridable). Country codes
@@ -848,6 +859,15 @@ interface FlowOverridableSettings {
848
859
  };
849
860
  authenticity: "standard" | "off";
850
861
  };
862
+ /**
863
+ * Ask the person to confirm the identity data read from them (`enabled`),
864
+ * and let them retake the identity step from there (`retake`). Turning it on
865
+ * narrows the flow, turning it off widens it; allowing a retake widens it.
866
+ */
867
+ confirmDetails?: {
868
+ enabled: boolean;
869
+ retake: boolean;
870
+ };
851
871
  }
852
872
  /**
853
873
  * Document substitution: the portrait a `document` or `nfc` step produces is
@@ -862,7 +882,7 @@ interface DocumentSubstitutionSettings {
862
882
  failBelow?: number;
863
883
  }
864
884
  /**
865
- * The per-service settings a session may override, by {@link ServiceId}.
885
+ * The per-service settings a session may override, by {@link OverridableServiceId}.
866
886
  * `attempts` limits are per step (absent = the platform default).
867
887
  * @public
868
888
  */
@@ -965,10 +985,6 @@ interface FlowServiceSettings {
965
985
  attempts?: number;
966
986
  };
967
987
  supplied_identity: Record<string, never>;
968
- summary_confirm: {
969
- /** Offer « Reprendre » (re-open the identity source). */
970
- retake: boolean;
971
- };
972
988
  liveness: {
973
989
  /** `off`, selfie ICAO `alert` / `reject`, or `id_document` (ID-photo portrait, always rejects). */
974
990
  icao: "off" | "alert" | "reject" | "id_document";
@@ -1066,7 +1082,7 @@ type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
1066
1082
  interface FlowOverrides {
1067
1083
  settings?: DeepPartial<FlowOverridableSettings>;
1068
1084
  services?: {
1069
- [S in ServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
1085
+ [S in OverridableServiceId]?: DeepPartial<FlowServiceSettings[S]> | "off";
1070
1086
  };
1071
1087
  }
1072
1088
  /**
@@ -1311,6 +1327,18 @@ interface CreateSessionInput {
1311
1327
  * `400 input_field_misplaced`.
1312
1328
  */
1313
1329
  input?: Record<string, unknown>;
1330
+ /**
1331
+ * Return the person's open session instead of creating one. The person is
1332
+ * `person.externalRef`, else the `person.reuse` target; without either the
1333
+ * API answers `400 resume_needs_person_reference`. An open session of the
1334
+ * same app and environment, flow version, reuse mode and options, with
1335
+ * status `created` or `in_progress` and at least 120 seconds left, is
1336
+ * answered with `resumed: true`, its own `clientToken` and `hostedUrl` and
1337
+ * its own `expiresAt` (never extended). Otherwise a new session is created
1338
+ * (`resumed: false`). Use it to reuse a session across page loads; use
1339
+ * {@link RequestOptions.idempotencyKey} for network retries.
1340
+ */
1341
+ resumeOpen?: boolean;
1314
1342
  }
1315
1343
  /** Per-request options. @public */
1316
1344
  interface RequestOptions {
@@ -1346,6 +1374,11 @@ interface CreatedSession {
1346
1374
  * person's document or registry record). Absent from older API versions.
1347
1375
  */
1348
1376
  subjectUse?: "reference" | "prefill";
1377
+ /**
1378
+ * `true` when {@link CreateSessionInput.resumeOpen} returned the person's
1379
+ * open session (HTTP 200), `false` for a new session (HTTP 201).
1380
+ */
1381
+ resumed?: boolean;
1349
1382
  /**
1350
1383
  * With {@link CreateSessionInput.deliver} only: the send of the hosted link.
1351
1384
  * `failed` never fails the create. `simulated: true` in the Sandbox when the
@@ -1370,6 +1403,8 @@ interface PersonSessionInput {
1370
1403
  /** Session lifetime in minutes, within the flow's link range. */
1371
1404
  ttlMinutes?: number;
1372
1405
  locale?: Locale;
1406
+ /** Return this person's open session of the same purpose (see {@link CreateSessionInput.resumeOpen}). */
1407
+ resumeOpen?: boolean;
1373
1408
  }
1374
1409
  /**
1375
1410
  * Which person {@link PeopleApi.createSession} targets: the person id
@@ -2671,7 +2706,9 @@ declare class SessionsApi {
2671
2706
  /**
2672
2707
  * `POST /sessions`. Returns the one-time `clientToken` — hand it to the
2673
2708
  * browser, never persist it. Pass an `idempotencyKey` so a retried call
2674
- * cannot create a second session.
2709
+ * cannot create a second session, and `resumeOpen: true` to get the
2710
+ * person's open session back instead of a new one on every page load
2711
+ * (`resumed: true`).
2675
2712
  */
2676
2713
  create(input?: CreateSessionInput, opts?: RequestOptions): Promise<CreatedSession>;
2677
2714
  /**
@@ -3043,4 +3080,4 @@ declare class Sekyro {
3043
3080
  readiness(): Promise<ReadinessReport>;
3044
3081
  }
3045
3082
 
3046
- export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type ConnectorIdentity as D, type CreateBlockInput as E, type FetchLike as F, type CreateSessionInput as G, DEFAULT_BASE_URL as H, DEFAULT_TIMEOUT_MS as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, type SessionReason as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, Sekyro as a, type ScreeningUnavailableReason as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityAddress as a3, type IdentityBirthPlace as a4, type IdentityDocument as a5, type IdentityIdNumber as a6, type IdentityMethod as a7, type IdentityName as a8, type IdentityProofOfAddress as a9, type PersonSession as aA, type PersonSessionInput as aB, type PersonSessionTarget as aC, type PersonUpdatedEventData as aD, type PoaDocumentKind as aE, type PoaReason as aF, type PoaRule as aG, type PoaRuleKind as aH, type PoaRules as aI, type PortraitReportEntry as aJ, type PriorReviewReason as aK, type ProbeBindingReason as aL, type ProbeQuality as aM, type ProfileDocumentType as aN, type ReadinessProtection as aO, type ReadinessReport as aP, type RequestOptions as aQ, type ResultTokenResponse as aR, type ReviewOutcomeReason as aS, type RevokePersonInput as aT, type ScreenPersonInput as aU, type Screening as aV, type ScreeningHit as aW, type ScreeningHitSummary as aX, type ScreeningList as aY, type ScreeningStatus as aZ, type ScreeningTrigger as a_, type IdentityScalarKey as aa, type IdentitySource as ab, type IdentitySources as ac, type LevelTarget as ad, type LiftBlockInput as ae, type ListBlocksQuery as af, type ListPeopleQuery as ag, type ListScreeningsQuery as ah, type ListSessionsQuery as ai, type ListSignalsQuery as aj, type MatchReason as ak, type MediaBytes as al, type MediaBytesOptions as am, type MediaItem as an, type MediaKind as ao, type MediaList as ap, type NameForm as aq, type Page as ar, PeopleApi as as, type Person as at, type PersonAddressInput as au, type PersonBirthPlaceInput as av, type PersonDeletedEventData as aw, type PersonDocumentInput as ax, type PersonEnrolledEventData as ay, type PersonRef as az, type ServiceId as b, type SekyroOptions as b0, SekyroTestApi as b1, type Session as b2, type SessionClosedEventDataBase as b3, type SessionDecidingStep as b4, type SessionDevice as b5, type SessionEventDataBase as b6, type SessionEventStep as b7, type SessionFailureReason as b8, type SessionFlowRef as b9, type SignalKeyKind as bA, type SignalKind as bB, type SignalSeverity as bC, type SignalStatus as bD, SignalsApi as bE, type SimulateSessionInput as bF, type StepResult as bG, type SubjectAssurance as bH, type SubjectIdNumber as bI, type SubjectName as bJ, type SubjectReferenceSource as bK, type SubjectReuseTarget as bL, type SubjectStatus as bM, type UpdateSignalInput as bN, type UsageThresholdReachedEventData as bO, type VerifiedContacts as bP, type WebhookEnvelopeOf as bQ, type WebhookEventDataMap as bR, type WebhookTestInput as bS, type WebhookTestResult as bT, WebhooksApi as bU, type SessionHandoff as ba, type SessionHandoffDevice as bb, type SessionLifecycleEventData as bc, type SessionLinkDelivery as bd, type SessionLinkExpiry as be, type SessionLinkInput as bf, type SessionNetwork as bg, type SessionNetworkEvent as bh, type SessionNotVerifiedEventData as bi, type SessionRetakeRequestedEventData as bj, type SessionReviewPendingEventData as bk, type SessionScreening as bl, type SessionStatus as bm, type SessionStep as bn, type SessionStepAttempts as bo, type SessionStepBand as bp, type SessionStepDecision as bq, type SessionStepDocument as br, type SessionStepPortrait as bs, SessionTestApi as bt, type SessionVerifiedEventData as bu, SessionsApi as bv, type Signal as bw, type SignalEventData as bx, type SignalEvidence as by, type SignalGrade as bz, type SessionPersonInput as c, type WebhookEnvelope as d, type SekyroEnvironment as e, type VerificationAssurance as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultCheckProofs as i, type SessionSignal as j, type FailureIdentification as k, type AgeResult as l, type AmlMatchFlaggedEventData as m, type ApiKeyIdentity as n, type BlockCheck as o, type BlockCheckInput as p, type BlockDuration as q, type BlockIdNumber as r, type BlockKind as s, type BlockMatch as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ClosedBy as z };
3083
+ export { type FlowSummary as $, type AgeMethod as A, type Block as B, type CreatedSession as C, type ConnectorIdentity as D, type CreateBlockInput as E, type FetchLike as F, type CreateSessionInput as G, DEFAULT_BASE_URL as H, DEFAULT_TIMEOUT_MS as I, type DecisionReason as J, type DeepPartial as K, type Locale as L, type DeletedPerson as M, type DeliverOptions as N, type Device as O, DevicesApi as P, type DocumentSubstitutionSettings as Q, type ReviewReason as R, type SessionReason as S, type EidResult as T, type EligibilityReason as U, type VerificationLevel as V, type WebhookEventType as W, type ExtendLinkInput as X, type FlowOverridableSettings as Y, type FlowOverrides as Z, type FlowServiceSettings as _, Sekyro as a, type ScreeningTrigger as a$, FlowsApi as a0, type IdNumberReason as a1, type Identity as a2, type IdentityAddress as a3, type IdentityBirthPlace as a4, type IdentityDocument as a5, type IdentityIdNumber as a6, type IdentityMethod as a7, type IdentityName as a8, type IdentityProofOfAddress as a9, type PersonRef as aA, type PersonSession as aB, type PersonSessionInput as aC, type PersonSessionTarget as aD, type PersonUpdatedEventData as aE, type PoaDocumentKind as aF, type PoaReason as aG, type PoaRule as aH, type PoaRuleKind as aI, type PoaRules as aJ, type PortraitReportEntry as aK, type PriorReviewReason as aL, type ProbeBindingReason as aM, type ProbeQuality as aN, type ProfileDocumentType as aO, type ReadinessProtection as aP, type ReadinessReport as aQ, type RequestOptions as aR, type ResultTokenResponse as aS, type ReviewOutcomeReason as aT, type RevokePersonInput as aU, type ScreenPersonInput as aV, type Screening as aW, type ScreeningHit as aX, type ScreeningHitSummary as aY, type ScreeningList as aZ, type ScreeningStatus as a_, type IdentityScalarKey as aa, type IdentitySource as ab, type IdentitySources as ac, type LevelTarget as ad, type LiftBlockInput as ae, type ListBlocksQuery as af, type ListPeopleQuery as ag, type ListScreeningsQuery as ah, type ListSessionsQuery as ai, type ListSignalsQuery as aj, type MatchReason as ak, type MediaBytes as al, type MediaBytesOptions as am, type MediaItem as an, type MediaKind as ao, type MediaList as ap, type NameForm as aq, type OverridableServiceId as ar, type Page as as, PeopleApi as at, type Person as au, type PersonAddressInput as av, type PersonBirthPlaceInput as aw, type PersonDeletedEventData as ax, type PersonDocumentInput as ay, type PersonEnrolledEventData as az, type ServiceId as b, type ScreeningUnavailableReason as b0, type SekyroOptions as b1, SekyroTestApi as b2, type Session as b3, type SessionClosedEventDataBase as b4, type SessionDecidingStep as b5, type SessionDevice as b6, type SessionEventDataBase as b7, type SessionEventStep as b8, type SessionFailureReason as b9, type SignalGrade as bA, type SignalKeyKind as bB, type SignalKind as bC, type SignalSeverity as bD, type SignalStatus as bE, SignalsApi as bF, type SimulateSessionInput as bG, type StepResult as bH, type SubjectAssurance as bI, type SubjectIdNumber as bJ, type SubjectName as bK, type SubjectReferenceSource as bL, type SubjectReuseTarget as bM, type SubjectStatus as bN, type UpdateSignalInput as bO, type UsageThresholdReachedEventData as bP, type VerifiedContacts as bQ, type WebhookEnvelopeOf as bR, type WebhookEventDataMap as bS, type WebhookTestInput as bT, type WebhookTestResult as bU, WebhooksApi as bV, type SessionFlowRef as ba, type SessionHandoff as bb, type SessionHandoffDevice as bc, type SessionLifecycleEventData as bd, type SessionLinkDelivery as be, type SessionLinkExpiry as bf, type SessionLinkInput as bg, type SessionNetwork as bh, type SessionNetworkEvent as bi, type SessionNotVerifiedEventData as bj, type SessionRetakeRequestedEventData as bk, type SessionReviewPendingEventData as bl, type SessionScreening as bm, type SessionStatus as bn, type SessionStep as bo, type SessionStepAttempts as bp, type SessionStepBand as bq, type SessionStepDecision as br, type SessionStepDocument as bs, type SessionStepPortrait as bt, SessionTestApi as bu, type SessionVerifiedEventData as bv, SessionsApi as bw, type Signal as bx, type SignalEventData as by, type SignalEvidence as bz, type SessionPersonInput as c, type WebhookEnvelope as d, type SekyroEnvironment as e, type VerificationAssurance as f, type VerificationUnit as g, type SubjectReuseMode as h, type ResultCheckProofs as i, type SessionSignal as j, type FailureIdentification as k, type AgeResult as l, type AmlMatchFlaggedEventData as m, type ApiKeyIdentity as n, type BlockCheck as o, type BlockCheckInput as p, type BlockDuration as q, type BlockIdNumber as r, type BlockKind as s, type BlockMatch as t, type BlockReason as u, BlocksApi as v, type CameraUnavailableCause as w, type CheckState as x, type CheckType as y, type ClosedBy as z };
@@ -1 +1 @@
1
- "use strict";var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:!0})},__copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to};var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:!0}),mod);var express_exports={};__export(express_exports,{requireLevel:()=>requireLevel});module.exports=__toCommonJS(express_exports);var 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}}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 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})}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 deny2=policy.denyFlags??DEFAULT_DENY_FLAGS;if(parsed.flags?.some(f=>deny2.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}}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 deny(res,result){let body={error:"sekyro_gate",reason:result.reason,action:result.action},r=res;if(typeof r.status=="function"){r.status(403).json(body);return}let n=res;n.statusCode=403,n.setHeader("content-type","application/json"),n.end(JSON.stringify(body))}function requireLevel(source,policy,opts){return(req,res,next)=>{Promise.resolve().then(()=>opts.claims(req)).then(claims=>{let result=sekyroGate(source,claims,policy);if(typeof req=="object"&&req!==null&&(req.sekyro=result),result.ok)return next();if(opts.onFail)return opts.onFail(result,req,res);deny(res,result)},err=>next(err))}}0&&(module.exports={requireLevel});
1
+ "use strict";var __defProp=Object.defineProperty;var __getOwnPropDesc=Object.getOwnPropertyDescriptor;var __getOwnPropNames=Object.getOwnPropertyNames;var __hasOwnProp=Object.prototype.hasOwnProperty;var __export=(target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:!0})},__copyProps=(to,from,except,desc)=>{if(from&&typeof from=="object"||typeof from=="function")for(let key of __getOwnPropNames(from))!__hasOwnProp.call(to,key)&&key!==except&&__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to};var __toCommonJS=mod=>__copyProps(__defProp({},"__esModule",{value:!0}),mod);var express_exports={};__export(express_exports,{requireLevel:()=>requireLevel});module.exports=__toCommonJS(express_exports);var CLAIM_VERSION=2,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}}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:CLAIM_VERSION,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 parseClaim(value){let v=value;if(typeof v=="string")try{v=JSON.parse(v)}catch{return null}return!isRecord(v)||!isFiniteNumber(v.v)?null:v.v>CLAIM_VERSION?v:v.v!==CLAIM_VERSION||v.level!==0&&v.level!==1&&v.level!==2&&v.level!==3||typeof v.assurance!="string"||!isFiniteNumber(v.verified_at)||typeof v.session_id!="string"||v.env!=="live"&&v.env!=="sandbox"?null:build({level:v.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})}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>CLAIM_VERSION)return fail("unsupported_version","verify",parsed);if(policy.env!==void 0&&parsed.env!==policy.env)return fail("wrong_env","verify",parsed);let deny2=policy.denyFlags??DEFAULT_DENY_FLAGS;if(parsed.flags?.some(f=>deny2.includes(f)))return fail("flagged","block",parsed);if(parsed.level<policy.level)return fail("level_too_low",parsed.level>=2?"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}}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 deny(res,result){let body={error:"sekyro_gate",reason:result.reason,action:result.action},r=res;if(typeof r.status=="function"){r.status(403).json(body);return}let n=res;n.statusCode=403,n.setHeader("content-type","application/json"),n.end(JSON.stringify(body))}function requireLevel(source,policy,opts){return(req,res,next)=>{Promise.resolve().then(()=>opts.claims(req)).then(claims=>{let result=sekyroGate(source,claims,policy);if(typeof req=="object"&&req!==null&&(req.sekyro=result),result.ok)return next();if(opts.onFail)return opts.onFail(result,req,res);deny(res,result)},err=>next(err))}}0&&(module.exports={requireLevel});