@sekyro/node 1.0.0-rc.24 → 1.0.0-rc.26

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,21 @@
1
1
  # @sekyro/node
2
2
 
3
+ ## 1.0.0-rc.26
4
+
5
+ ### Minor Changes
6
+
7
+ - d8f24f3: Automatic fraud blocks: `Block` gains `source` (`"automatic"` for entries Sekyro AI made), `level`, `trigger`, the effect `protect` (an ID protection: native app only for 30 days) and the reason `fraud_detected`. `Session` gains `fraudResponse`, `automaticBlock` and `idProtection`. Webhook payloads are unchanged.
8
+ - 0a8e356: Form step types: `Session.declared` and the `declared` field of `session.review_pending`, `session.verified` and `session.not_verified` (`Declared`: the ready-made fields, custom answers, consents and mismatches the person declared, never verified data), and `answers` on `CreateSessionInput` to prefill the form. Additive and optional.
9
+
10
+ ## 1.0.0-rc.25
11
+
12
+ ### Minor Changes
13
+
14
+ - d291557: `SignalEvidence` adds three session evidence codes of the `presentation_attack` kind: `capture_untrusted` (strong: the selfie video did not come from a Sekyro AI SDK's camera), `clip_reencoded` (strong: the video was made by video software) and `clip_atypical` (weak: the video file has one trait unusual for a phone camera).
15
+ - 1b8395d: Session flow overrides accept `services.device_network.captureOn` (`"any" | "native"`): `native` keeps the session's camera steps to a native app (a browser gets `409 native_app_required`).
16
+ - 655cf14: `person.deleted` can carry `mergedInto`: when a person's Human-only record is joined to their identity record, the webhook for the deleted record names the person id that stays (`PersonDeletedEventData.mergedInto`). `@sekyro/node/connect` follows it: a claim that names the deleted record now names the one that stays and keeps its level (`MergeRule` gains `merged`); it is not treated as a revocation.
17
+ - 4489e83: Signal types: `SignalKind` gains `person_stuck`, `session_face_swap`, `automated_browser` and `agent_results`, `SignalEvidence` gains their evidence codes, and a finding's `closedReason` can be `shared_device`. `account_targeted` now means account takeover attempts and `presentation_attack` an injected or tampered capture.
18
+
3
19
  ## 1.0.0-rc.24
4
20
 
5
21
  ### Patch Changes
package/README.md CHANGED
@@ -518,7 +518,9 @@ answer the same `404 subject_not_found` on `get`, `revoke` and `delete`, and
518
518
 
519
519
  `person.enrolled` (first reference photo stored), `person.updated` (a linked
520
520
  session finished, or `status: 'revoked'`) and `person.deleted` webhooks are
521
- typed on the envelope, with `personId`.
521
+ typed on the envelope, with `personId`. A `person.deleted` with `mergedInto`
522
+ is not a deletion of the person: their Human-only record joined their identity
523
+ record, and `mergedInto` is the person id that stays.
522
524
 
523
525
  ## Blocks and devices
524
526
 
@@ -816,6 +818,7 @@ Trust rules:
816
818
  - 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.
817
819
  - 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.
818
820
  - 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.
821
+ - A `person.deleted` with `mergedInto` revokes nothing: the person's Human-only record joined their identity record. A claim that names the deleted record now names the one that stays (rule `merged`) and keeps its level; any other claim is left as it is.
819
822
 
820
823
  Telemetry: the six Sekyro provider packages tell Sekyro the connector is wired, so the dashboard's
821
824
  Connectors page can show it as connected. Every API call carries an `x-sekyro-connector` header
@@ -1 +1 @@
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};
1
+ import{evaluateGate}from"./chunk-4RWEISPN.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 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(event.kind==="deleted"&&event.mergedInto!==void 0&&event.mergedInto.length>0)return prev.subject_id===void 0||prev.subject_id!==canonicalId(event.subjectId)?same(prev,prev.subject_id===void 0?"no_change":"subject_mismatch"):wrote(build({...prev,subject_id:event.mergedInto}),"merged");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};
@@ -127,7 +127,7 @@ interface PersonRef {
127
127
  * {@link SessionSignal} and on a finding ({@link Signal}).
128
128
  * @public
129
129
  */
130
- type SignalKind = "account_targeted" | "id_many_faces" | "duplicate_identity" | "device_farm" | "document_reuse" | "presentation_attack" | "probing" | "velocity" | "network" | "contact_reuse" | "age_probing" | "known_person_new_device" | "registry_burst" | "link_sharing" | "device_integrity" | "too_fast" | "account_volume" | "document_conflict";
130
+ type SignalKind = "account_targeted" | "id_many_faces" | "duplicate_identity" | "device_farm" | "document_reuse" | "presentation_attack" | "probing" | "velocity" | "network" | "contact_reuse" | "age_probing" | "known_person_new_device" | "registry_burst" | "link_sharing" | "device_integrity" | "too_fast" | "account_volume" | "document_conflict" | "person_stuck" | "session_face_swap" | "automated_browser" | "agent_results";
131
131
  /** How strong a signal is. @public */
132
132
  type SignalSeverity = "low" | "medium" | "high";
133
133
  /** The strength of the evidence that set a finding's severity. @public */
@@ -137,7 +137,7 @@ type SignalGrade = "strong" | "medium" | "weak";
137
137
  * a value.
138
138
  * @public
139
139
  */
140
- type SignalEvidence = "injection_suspected" | "capture_tampered" | "capture_provenance_invalid" | "virtual_camera" | "repeated_spoof" | "identity_stop" | "identity_switch" | "registry_burst" | "many_faces" | "face_many_ids" | "dedup_match" | "digest_conflict" | "documents_only" | "subject_conflict" | "session_velocity" | "many_people" | "device_velocity_exceeded" | "counted_rejections" | "shared_device" | "print_only" | "location_mismatch" | "anonymizer_asn" | "vpn" | "tor" | "proxy" | "hosting" | "attestation_failed" | "emulator" | "hooking" | "debugger" | "webdriver" | "headless" | "rooted_device" | "no_device_id" | "too_fast" | "account_volume" | "identities_vary" | "contact_reuse" | "disposable_email" | "role_email" | "age_probing" | "image_reuse" | "document_altered" | "document_substitution" | "mrz_visual_mismatch" | "many_devices" | "new_device";
140
+ type SignalEvidence = "injection_suspected" | "capture_tampered" | "capture_provenance_invalid" | "virtual_camera" | "capture_untrusted" | "clip_reencoded" | "clip_atypical" | "repeated_spoof" | "other_face" | "distinct_faces" | "repeated_failures" | "passed_after_failures" | "face_swap" | "automated_sessions" | "reject_share" | "attack_share" | "identity_stop" | "identity_switch" | "registry_burst" | "many_faces" | "face_many_ids" | "dedup_match" | "digest_conflict" | "documents_only" | "subject_conflict" | "session_velocity" | "many_people" | "device_velocity_exceeded" | "counted_rejections" | "shared_device" | "print_only" | "location_mismatch" | "anonymizer_asn" | "vpn" | "tor" | "proxy" | "hosting" | "attestation_failed" | "emulator" | "hooking" | "debugger" | "webdriver" | "headless" | "rooted_device" | "no_device_id" | "too_fast" | "account_volume" | "identities_vary" | "contact_reuse" | "disposable_email" | "role_email" | "age_probing" | "image_reuse" | "document_altered" | "document_substitution" | "mrz_visual_mismatch" | "many_devices" | "new_device";
141
141
  /**
142
142
  * One signal on a session: a kind, a severity and the evidence behind it.
143
143
  * Facts only, never a verdict. On {@link Session.signals}, the terminal
@@ -221,7 +221,7 @@ interface Signal {
221
221
  /** Your note. */
222
222
  note?: string;
223
223
  /** Why it closed, on a closed finding. */
224
- closedReason?: "rules_changed" | "disabled" | "quiet" | "under_threshold";
224
+ closedReason?: "rules_changed" | "disabled" | "quiet" | "under_threshold" | "shared_device";
225
225
  /** ISO 8601: when it closed, on a closed finding. */
226
226
  closedAt?: string;
227
227
  /** ISO 8601: when it was first raised. */
@@ -917,6 +917,8 @@ interface FlowServiceSettings {
917
917
  };
918
918
  attestation?: "off" | "signal" | "enforce";
919
919
  captureIntegrity?: "off" | "signal" | "enforce";
920
+ /** Where camera steps run: any device (absent), or a native app only (browsers get `409 native_app_required`). */
921
+ captureOn?: "any" | "native";
920
922
  };
921
923
  phone_otp: {
922
924
  /** Where the number comes from: your `person.phone`, the person, or either. */
@@ -1339,6 +1341,16 @@ interface CreateSessionInput {
1339
1341
  * {@link RequestOptions.idempotencyKey} for network retries.
1340
1342
  */
1341
1343
  resumeOpen?: boolean;
1344
+ /**
1345
+ * Prefill the flow's Form step: question id (a custom question id, or a
1346
+ * ready-made field name such as `full_name` or `birth_date`) to value. The
1347
+ * person sees each value and can change it. A ready-made field left out here
1348
+ * is prefilled from the matching {@link CreateSessionInput.person} value.
1349
+ * An unknown id or a bad value answers `422 form_answers_invalid` naming the
1350
+ * id; a flow with no Form step answers `422 form_answers_not_accepted`.
1351
+ * Consents are never prefilled.
1352
+ */
1353
+ answers?: Record<string, FormAnswerValue>;
1342
1354
  }
1343
1355
  /** Per-request options. @public */
1344
1356
  interface RequestOptions {
@@ -1558,6 +1570,97 @@ interface VerifiedContacts {
1558
1570
  verifiedAt: string;
1559
1571
  };
1560
1572
  }
1573
+ /**
1574
+ * A Form answer value, by question type: text (`short_text`, `long_text`), a
1575
+ * choice value (`single_choice`), a list of choice values (`multiple_choice`),
1576
+ * `true` or `false` (`yes_no`), a date `YYYY-MM-DD` (`date`) or a number
1577
+ * (`number`). The ready-made `address` field holds a {@link DeclaredAddress}.
1578
+ * @public
1579
+ */
1580
+ type FormAnswerValue = string | number | boolean | string[] | DeclaredAddress;
1581
+ /**
1582
+ * An address the person typed on a Form step.
1583
+ * @public
1584
+ */
1585
+ interface DeclaredAddress {
1586
+ /** ISO 3166-1 alpha-2. */
1587
+ country: string;
1588
+ city: string;
1589
+ /** 1 to 4 street lines. */
1590
+ lines: string[];
1591
+ postcode?: string;
1592
+ }
1593
+ /**
1594
+ * The type of a custom Form question.
1595
+ * @public
1596
+ */
1597
+ type FormQuestionType = "short_text" | "long_text" | "single_choice" | "multiple_choice" | "yes_no" | "date" | "number";
1598
+ /**
1599
+ * A declared value that differs from what the same session verified: the
1600
+ * full name or birth date against {@link Identity} (`identity`), the phone or
1601
+ * email against {@link VerifiedContacts} (`contact`).
1602
+ * @public
1603
+ */
1604
+ interface DeclaredMismatch {
1605
+ field: "fullName" | "birthDate" | "phone" | "email";
1606
+ against: "identity" | "contact";
1607
+ }
1608
+ /**
1609
+ * What the person declared on the flow's Form step. Declared, never verified:
1610
+ * it does not change {@link Identity}, the level or the result token.
1611
+ *
1612
+ * Present once the session was charged (it ended `verified` or `not_verified`
1613
+ * and was billed) or while it is in review; in Sandbox once it ended or
1614
+ * entered review. Absent while the session runs, for a session the person
1615
+ * left, and after the retention purge or an erasure.
1616
+ * @public
1617
+ */
1618
+ interface Declared {
1619
+ /** ISO 8601: when the person submitted the form. */
1620
+ submittedAt: string;
1621
+ /** The language the form was shown in. */
1622
+ locale: "ar" | "fr" | "en" | "es" | "pt" | "de";
1623
+ /** The ready-made fields the form asked and the person answered. */
1624
+ fields: {
1625
+ fullName?: string;
1626
+ /** `YYYY-MM-DD`. */
1627
+ birthDate?: string;
1628
+ /** Lower case. */
1629
+ email?: string;
1630
+ /** E.164. */
1631
+ phone?: string;
1632
+ address?: DeclaredAddress;
1633
+ /** ISO 3166-1 alpha-2. */
1634
+ country?: string;
1635
+ occupation?: string;
1636
+ };
1637
+ /** Your custom questions, by question id. */
1638
+ answers: Record<string, DeclaredAnswer>;
1639
+ /** Your consent checkboxes, by consent id. */
1640
+ consents: Record<string, DeclaredConsent>;
1641
+ /** Declared values that differ from the verified ones (non-empty only). */
1642
+ mismatches?: DeclaredMismatch[];
1643
+ }
1644
+ /**
1645
+ * One custom question's answer in {@link Declared.answers}.
1646
+ * @public
1647
+ */
1648
+ interface DeclaredAnswer {
1649
+ type: FormQuestionType;
1650
+ value: FormAnswerValue;
1651
+ /** You sent this value in {@link CreateSessionInput.answers} and the person kept it. */
1652
+ prefilled?: true;
1653
+ }
1654
+ /**
1655
+ * One consent checkbox in {@link Declared.consents}.
1656
+ * @public
1657
+ */
1658
+ interface DeclaredConsent {
1659
+ /** The person ticked the box. */
1660
+ accepted: boolean;
1661
+ /** ISO 8601: when the person ticked it. */
1662
+ acceptedAt?: string;
1663
+ }
1561
1664
  /**
1562
1665
  * Where a value of {@link Identity} comes from: the `document` (its machine
1563
1666
  * readable zone or printed text), the passport `chip`, the population
@@ -1852,6 +1955,19 @@ interface Session {
1852
1955
  signals?: SessionSignal[];
1853
1956
  /** Your blocks and rules that flagged the session or held it for review (non-empty only). */
1854
1957
  blockMatches?: BlockMatch[];
1958
+ /** Automatic fraud blocks: what Sekyro AI did after this session showed fraud evidence. Not in webhooks. */
1959
+ fraudResponse?: FraudResponse;
1960
+ /** This session was stopped (`reasonCode: "blocked_by_org"`) by a block Sekyro AI made. */
1961
+ automaticBlock?: {
1962
+ blockId: string;
1963
+ level?: 1 | 2 | 3;
1964
+ expiresAt: string | null;
1965
+ };
1966
+ /** This session held an ID number under protection: its camera steps ran in a native app only. */
1967
+ idProtection?: {
1968
+ blockId: string;
1969
+ afterCapture?: true;
1970
+ };
1855
1971
  /**
1856
1972
  * `true` for a returning-user session (created with
1857
1973
  * {@link SessionPersonInput.reuse}): liveness + face match against the
@@ -1867,6 +1983,8 @@ interface Session {
1867
1983
  reuseMode?: SubjectReuseMode;
1868
1984
  /** The contacts verified in this session (passed OTP checks only); absent when none. */
1869
1985
  verifiedContacts?: VerifiedContacts;
1986
+ /** What the person declared on the Form step ({@link Declared}), once released. Never verified data. */
1987
+ declared?: Declared;
1870
1988
  /**
1871
1989
  * When the flow sets a minimum age and the session proved it: the threshold
1872
1990
  * and how it was proved ({@link AgeResult}). Absent otherwise.
@@ -1993,6 +2111,12 @@ interface SessionEventDataBase {
1993
2111
  * the event. Absent in Live and on a session a tester ran.
1994
2112
  */
1995
2113
  sandbox?: SandboxSimulation;
2114
+ /**
2115
+ * What the person declared on the Form step ({@link Declared}), once
2116
+ * released: on `session.review_pending`, and on a terminal event of a
2117
+ * charged session. Never verified data.
2118
+ */
2119
+ declared?: Declared;
1996
2120
  }
1997
2121
  /**
1998
2122
  * The fields of the two terminal events, `session.verified` and
@@ -2131,7 +2255,8 @@ interface PersonEnrolledEventData {
2131
2255
  * `data` of `person.deleted`. A delete through the people API carries
2132
2256
  * `personId`; a right-to-erasure request carries the tokenized `subjectRef`
2133
2257
  * (with `orgId` / `env`), and `personId` when it named exactly one person, never
2134
- * the national number.
2258
+ * the national number. A record joined to another record of the same person
2259
+ * carries `personId` and `mergedInto`.
2135
2260
  * @public
2136
2261
  */
2137
2262
  interface PersonDeletedEventData {
@@ -2144,6 +2269,13 @@ interface PersonDeletedEventData {
2144
2269
  * can find your user. Never on the erasure variant.
2145
2270
  */
2146
2271
  externalRefs?: string[];
2272
+ /**
2273
+ * Set when the person was not erased but joined to another record of the
2274
+ * same person (their Human-only record joined their identity record): the
2275
+ * person id that stays (`per_...`). The deleted id answers `404`; use this
2276
+ * one from now on. Absent on a delete and on an erasure.
2277
+ */
2278
+ mergedInto?: string;
2147
2279
  }
2148
2280
  /** Subject lifecycle: a revoked subject cannot be reused. @public */
2149
2281
  type SubjectStatus = "active" | "revoked";
@@ -2274,7 +2406,36 @@ interface ListSessionsQuery {
2274
2406
  */
2275
2407
  type BlockKind = "id_number" | "external_ref" | "phone" | "email" | "device" | "face";
2276
2408
  /** Why a block exists. `rule`: an automatic rule made it. @public */
2277
- type BlockReason = "fraud_confirmed" | "chargeback" | "abuse" | "test" | "rule" | "other";
2409
+ /** `fraud_detected`: made by Sekyro AI from a session with fraud evidence (`source: "automatic"`). @public */
2410
+ type BlockReason = "fraud_confirmed" | "chargeback" | "abuse" | "test" | "rule" | "other" | "fraud_detected";
2411
+ /** The fraud evidence that makes Sekyro AI block a device and protect an ID number. @public */
2412
+ type FraudReason = "injection_suspected" | "capture_tampered" | "spoof_detected" | "document_photo_mismatch" | "document_sides_mismatch";
2413
+ /**
2414
+ * What Sekyro AI did after a session showed fraud evidence: the device blocked (24 hours, then 7
2415
+ * days, then 30 days on a repeat) and each ID number it held protected for 30 days. In Sandbox
2416
+ * nothing is blocked (`recordedOnly`). @public
2417
+ */
2418
+ interface FraudResponse {
2419
+ reason: FraudReason;
2420
+ at: string;
2421
+ recordedOnly?: true;
2422
+ /** `effect: "flag"` on a device shared by several people; `created: false` when a block already held it. */
2423
+ deviceBlock?: {
2424
+ blockId: string;
2425
+ label: string;
2426
+ level: 1 | 2 | 3;
2427
+ effect: "block" | "flag";
2428
+ expiresAt: string | null;
2429
+ created: boolean;
2430
+ };
2431
+ /** No device to block (no per-install device id). */
2432
+ deviceSkipped?: "no_device";
2433
+ idProtections?: Array<{
2434
+ blockId: string;
2435
+ label: string;
2436
+ expiresAt: string | null;
2437
+ }>;
2438
+ }
2278
2439
  /** How long a block lasts; `null` has no end. @public */
2279
2440
  type BlockDuration = "P1D" | "P7D" | "P30D" | null;
2280
2441
  /**
@@ -2289,8 +2450,21 @@ interface Block {
2289
2450
  label: string;
2290
2451
  /** The device, on a device block. */
2291
2452
  deviceId?: string;
2292
- effect: "block" | "flag" | "review";
2453
+ /**
2454
+ * `protect` is an ID protection (made by Sekyro AI only): for its duration, a session holding
2455
+ * this ID number takes its photos in a native app only. It never stops a session.
2456
+ */
2457
+ effect: "block" | "flag" | "review" | "protect";
2293
2458
  reason: BlockReason;
2459
+ /** Who made it: your dashboard, the API, a rule, or Sekyro AI (`automatic`) from fraud evidence. */
2460
+ source: "dashboard" | "api" | "rule" | "automatic";
2461
+ /** An automatic device block's level: 1 lasts 24 hours, 2 seven days, 3 thirty days. */
2462
+ level?: 1 | 2 | 3;
2463
+ /** An automatic entry: the fraud reason code and the session (`ses_...`) that made it. */
2464
+ trigger?: {
2465
+ reason: FraudReason;
2466
+ sessionId?: string;
2467
+ };
2294
2468
  /** When it ends; `null` has no end. */
2295
2469
  expiresAt: string | null;
2296
2470
  createdAt: string;
@@ -3117,4 +3291,4 @@ declare class Sekyro {
3117
3291
  readiness(): Promise<ReadinessReport>;
3118
3292
  }
3119
3293
 
3120
- 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 ScreeningList 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 SandboxSimulatedReason as aV, type SandboxSimulation as aW, type ScreenPersonInput as aX, type Screening as aY, type ScreeningHit as aZ, type ScreeningHitSummary 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 ScreeningStatus as b0, type ScreeningTrigger as b1, type ScreeningUnavailableReason as b2, type SekyroOptions as b3, SekyroTestApi as b4, type Session as b5, type SessionClosedEventDataBase as b6, type SessionDecidingStep as b7, type SessionDevice as b8, type SessionEventDataBase as b9, type SignalEventData as bA, type SignalEvidence as bB, type SignalGrade as bC, type SignalKeyKind as bD, type SignalKind as bE, type SignalSeverity as bF, type SignalStatus as bG, SignalsApi as bH, type SimulateSessionInput as bI, type StepResult as bJ, type SubjectAssurance as bK, type SubjectIdNumber as bL, type SubjectName as bM, type SubjectReferenceSource as bN, type SubjectReuseTarget as bO, type SubjectStatus as bP, type UpdateSignalInput as bQ, type UsageThresholdReachedEventData as bR, type VerifiedContacts as bS, type WebhookEnvelopeOf as bT, type WebhookEventDataMap as bU, type WebhookTestInput as bV, type WebhookTestResult as bW, WebhooksApi as bX, type SessionEventStep as ba, type SessionFailureReason as bb, type SessionFlowRef as bc, type SessionHandoff as bd, type SessionHandoffDevice as be, type SessionLifecycleEventData as bf, type SessionLinkDelivery as bg, type SessionLinkExpiry as bh, type SessionLinkInput as bi, type SessionNetwork as bj, type SessionNetworkEvent as bk, type SessionNotVerifiedEventData as bl, type SessionRetakeRequestedEventData as bm, type SessionReviewPendingEventData as bn, type SessionScreening as bo, type SessionStatus as bp, type SessionStep as bq, type SessionStepAttempts as br, type SessionStepBand as bs, type SessionStepDecision as bt, type SessionStepDocument as bu, type SessionStepPortrait as bv, SessionTestApi as bw, type SessionVerifiedEventData as bx, SessionsApi as by, type Signal 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 };
3294
+ export { type EligibilityReason 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 Declared as K, type Locale as L, type DeclaredAddress as M, type DeclaredAnswer as N, type DeclaredConsent as O, type DeclaredMismatch as P, type DeepPartial as Q, type ReviewReason as R, type SessionReason as S, type DeletedPerson as T, type DeliverOptions as U, type VerificationLevel as V, type WebhookEventType as W, type Device as X, DevicesApi as Y, type DocumentSubstitutionSettings as Z, type EidResult as _, Sekyro as a, type ResultTokenResponse as a$, type ExtendLinkInput as a0, type FlowOverridableSettings as a1, type FlowOverrides as a2, type FlowServiceSettings as a3, type FlowSummary as a4, FlowsApi as a5, type FormAnswerValue as a6, type FormQuestionType as a7, type FraudReason as a8, type FraudResponse as a9, type OverridableServiceId as aA, type Page as aB, PeopleApi as aC, type Person as aD, type PersonAddressInput as aE, type PersonBirthPlaceInput as aF, type PersonDeletedEventData as aG, type PersonDocumentInput as aH, type PersonEnrolledEventData as aI, type PersonRef as aJ, type PersonSession as aK, type PersonSessionInput as aL, type PersonSessionTarget as aM, type PersonUpdatedEventData as aN, type PoaDocumentKind as aO, type PoaReason as aP, type PoaRule as aQ, type PoaRuleKind as aR, type PoaRules as aS, type PortraitReportEntry as aT, type PriorReviewReason as aU, type ProbeBindingReason as aV, type ProbeQuality as aW, type ProfileDocumentType as aX, type ReadinessProtection as aY, type ReadinessReport as aZ, type RequestOptions as a_, type IdNumberReason as aa, type Identity as ab, type IdentityAddress as ac, type IdentityBirthPlace as ad, type IdentityDocument as ae, type IdentityIdNumber as af, type IdentityMethod as ag, type IdentityName as ah, type IdentityProofOfAddress as ai, type IdentityScalarKey as aj, type IdentitySource as ak, type IdentitySources as al, type LevelTarget as am, type LiftBlockInput as an, type ListBlocksQuery as ao, type ListPeopleQuery as ap, type ListScreeningsQuery as aq, type ListSessionsQuery as ar, type ListSignalsQuery as as, type MatchReason as at, type MediaBytes as au, type MediaBytesOptions as av, type MediaItem as aw, type MediaKind as ax, type MediaList as ay, type NameForm as az, type ServiceId as b, type VerifiedContacts as b$, type ReviewOutcomeReason as b0, type RevokePersonInput as b1, type SandboxSimulatedReason as b2, type SandboxSimulation as b3, type ScreenPersonInput as b4, type Screening as b5, type ScreeningHit as b6, type ScreeningHitSummary as b7, type ScreeningList as b8, type ScreeningStatus as b9, type SessionStepAttempts as bA, type SessionStepBand as bB, type SessionStepDecision as bC, type SessionStepDocument as bD, type SessionStepPortrait as bE, SessionTestApi as bF, type SessionVerifiedEventData as bG, SessionsApi as bH, type Signal as bI, type SignalEventData as bJ, type SignalEvidence as bK, type SignalGrade as bL, type SignalKeyKind as bM, type SignalKind as bN, type SignalSeverity as bO, type SignalStatus as bP, SignalsApi as bQ, type SimulateSessionInput as bR, type StepResult as bS, type SubjectAssurance as bT, type SubjectIdNumber as bU, type SubjectName as bV, type SubjectReferenceSource as bW, type SubjectReuseTarget as bX, type SubjectStatus as bY, type UpdateSignalInput as bZ, type UsageThresholdReachedEventData as b_, type ScreeningTrigger as ba, type ScreeningUnavailableReason as bb, type SekyroOptions as bc, SekyroTestApi as bd, type Session as be, type SessionClosedEventDataBase as bf, type SessionDecidingStep as bg, type SessionDevice as bh, type SessionEventDataBase as bi, type SessionEventStep as bj, type SessionFailureReason as bk, type SessionFlowRef as bl, type SessionHandoff as bm, type SessionHandoffDevice as bn, type SessionLifecycleEventData as bo, type SessionLinkDelivery as bp, type SessionLinkExpiry as bq, type SessionLinkInput as br, type SessionNetwork as bs, type SessionNetworkEvent as bt, type SessionNotVerifiedEventData as bu, type SessionRetakeRequestedEventData as bv, type SessionReviewPendingEventData as bw, type SessionScreening as bx, type SessionStatus as by, type SessionStep as bz, type SessionPersonInput as c, type WebhookEnvelopeOf as c0, type WebhookEventDataMap as c1, type WebhookTestInput as c2, type WebhookTestResult as c3, WebhooksApi as c4, 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 };