@entros/verify 0.1.1 → 0.2.0

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/README.md CHANGED
@@ -2,91 +2,160 @@
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@entros/verify.svg)](https://www.npmjs.com/package/@entros/verify)
4
4
 
5
- React component for Entros verification on Solana devnet. It opens the Entros popup and reports a completed wallet-connected verification.
5
+ React component for wallet-connected Entros verification on Solana devnet.
6
+ It opens the Entros popup and checks the returned application policy result before calling `onVerified`.
6
7
 
7
8
  Source: [github.com/entros-protocol/entros-verify](https://github.com/entros-protocol/entros-verify) · Hosted by [entros.io](https://entros.io).
8
9
 
10
+ This README describes the prepared `0.2.0` source release. npm still serves `0.1.1` as `latest`.
11
+ Package publication and the compatible hosted popup release remain pending.
12
+ Deploy an upgraded consumer after the compatible popup release completes.
13
+
14
+ After publication, install the prepared version with React 19:
15
+
9
16
  ```bash
10
- npm install @entros/verify
17
+ npm install @entros/verify@0.2.0
11
18
  ```
12
19
 
13
- ## Five-line usage
20
+ ## Usage
14
21
 
15
22
  ```tsx
16
23
  import { EntrosVerify } from "@entros/verify";
17
24
 
18
25
  <EntrosVerify
19
26
  integratorKey="your-integrator-key"
20
- onVerified={(result) => unlockClaim(result.walletPubkey)}
27
+ onVerified={(result) => showVerificationResult(result)}
28
+ onError={(error) => showVerificationError(error.reason, error.policyReason)}
21
29
  />
22
30
  ```
23
31
 
24
- ## Result shape
32
+ Without `policy`, the component uses a one-day verification age, a 90-second evaluation age, and optional SAS issuance.
33
+ The score floor defaults to zero or the supplied `minTrustScore`.
34
+ The consumer rejects older popups that omit the policy result.
35
+
36
+ ## Application policy
37
+
38
+ ```tsx
39
+ <EntrosVerify
40
+ integratorKey="your-integrator-key"
41
+ policy={{
42
+ id: "claim-access",
43
+ version: 1,
44
+ minTrustScore: 200,
45
+ maxVerificationAgeSeconds: 300,
46
+ maxEvaluationAgeSeconds: 90,
47
+ requiredAssurance: "browser_unattested",
48
+ uniquenessRequirement: "allow_unmeasured",
49
+ requireAttestation: false,
50
+ cluster: "devnet",
51
+ }}
52
+ onVerified={(result) => showVerificationResult(result)}
53
+ onError={(error) => showVerificationError(error.reason, error.policyReason)}
54
+ />
55
+ ```
56
+
57
+ The consumer checks the requested policy, account observations, score, freshness, and matching result fields.
58
+ Supplying conflicting `minTrustScore` and `policy.minTrustScore` values fails before the popup opens.
59
+
60
+ The result states `browser_unattested` assurance and `unmeasured` uniqueness.
61
+ These fields do not establish sensor provenance or population uniqueness.
62
+
63
+ ## Result
25
64
 
26
65
  ```ts
66
+ import type { PolicyResult } from "@entros/verify/policy";
67
+
27
68
  interface EntrosVerifyResult {
28
- walletPubkey: string; // base58 Solana pubkey
29
- attestationPda: string; // derived SAS account address
30
- txSig: string; // base58 verification tx signature
31
- trustScore: number; // current Trust Score (0–10000)
69
+ walletPubkey: string;
70
+ attestationPda: string | null;
71
+ txSig: string;
72
+ trustScore: number;
32
73
  cluster: "devnet";
74
+ policy: PolicyResult & { decision: "allow" };
33
75
  }
34
76
  ```
35
77
 
36
- The callback reports a completed Entros verification and its derived attestation address. It does not independently prove physical presence.
37
-
38
- SAS issuance is best-effort after wallet-connected verification. Check that the returned address contains an attestation account before relying on it.
78
+ The `policy` result contains the evaluated requirements, expiry, and typed evidence.
79
+ A non-null `attestationPda` identifies an account that passed validation during evaluation.
80
+ Optional attestations with `missing` or `unavailable` status carry no issued address. Invalid accounts fail the policy.
81
+ Required attestations must exist and remain valid through consumption.
39
82
 
40
- ## Full API
83
+ ## Component options
41
84
 
42
85
  ```tsx
43
86
  <EntrosVerify
44
- integratorKey="your-integrator-key" // required
45
- cluster="devnet" // only supported cluster
46
- minTrustScore={200} // optional floor on verification history
47
- popupWidth={480} // CSS px, default 480
48
- popupHeight={720} // CSS px, default 720
49
- timeoutMs={9 * 60 * 1000} // 9 min default
50
- popupBlockedFallback={true} // inline retry UI when popup blocked
51
- className="..." // applied to trigger button
52
- style={{ ... }}
53
- onVerified={(r) => {}} // required
54
- onError={(e) => {}} // optional — covers cancel, reject, timeout, etc.
55
- onProgress={(p) => {}} // optional — heartbeats from popup
87
+ integratorKey="your-integrator-key"
88
+ cluster="devnet"
89
+ minTrustScore={200}
90
+ popupWidth={480}
91
+ popupHeight={720}
92
+ timeoutMs={9 * 60 * 1000}
93
+ popupBlockedFallback={true}
94
+ className="verification-button"
95
+ onVerified={(result) => showVerificationResult(result)}
96
+ onError={(error) => showVerificationError(error.reason, error.policyReason)}
97
+ onProgress={(progress) => showProgress(progress.status)}
56
98
  >
57
- Verify with Entros {/* custom button content */}
99
+ Verify with Entros
58
100
  </EntrosVerify>
59
101
  ```
60
102
 
61
- ## Error reasons
103
+ `integratorKey` and `onVerified` are required. The dimensions, timeout, and popup fallback above show their defaults.
104
+ Use `style` for inline styles and children for custom button content.
105
+ `onProgress` reports popup heartbeats during the flow.
106
+
107
+ ## Errors
108
+
109
+ `onError` receives `reason` and an optional `policyReason`.
110
+ Policy reasons describe application requirements or evidence availability. They do not expose private behavioral rejection signals.
111
+
112
+ | Reason | Meaning |
113
+ |---|---|
114
+ | `wallet_rejected` | User denied wallet connection or signing |
115
+ | `validation_failed` | Verification or the application policy did not pass |
116
+ | `network_error` | The flow encountered a network failure |
117
+ | `user_canceled` | User closed the popup before completion |
118
+ | `origin_invalid` | The integrator origin failed the allowlist check |
119
+ | `popup_blocked` | The browser blocked `window.open()` |
120
+ | `timeout` | The popup exceeded `timeoutMs` |
121
+ | `unknown` | The flow encountered an unclassified failure |
122
+
123
+ ## Settlement checks
124
+
125
+ The React-free `@entros/verify/policy` subpath exports `normalizePolicyRequest`, `evaluatePolicy`, and strict wire guards.
126
+ Pair the evaluator with `readIntegratorEvidence` from the prepared Pulse `4.10.0` release against your service's configured RPC connection.
127
+ The evaluator accepts typed observations. It cannot authenticate observations supplied by a browser.
128
+
129
+ For protected actions, your service owns the policy and authenticates the wallet's signature over a one-use action challenge.
130
+ Bind the challenge to the wallet, action parameters, audience, and expiry.
131
+ Read current chain evidence before executing the action. Consume the challenge and execute the action in one atomic operation.
132
+ An on-chain action must enforce its requirements within the action transaction.
133
+
134
+ ## Migration from `0.1.1`
62
135
 
63
- `onError` receives one of:
136
+ Version `0.2.0` changes the callback contract:
64
137
 
65
- - `wallet_rejected` — user denied wallet connection or signing
66
- - `validation_failed` — verification did not pass server-side checks
67
- - `network_error` — popup encountered a network failure mid-flow
68
- - `user_canceled` — user closed the popup before completing
69
- - `origin_invalid` — integrator origin was not on the Entros allowlist
70
- - `popup_blocked` — browser blocked `window.open()`
71
- - `timeout` — popup remained open longer than `timeoutMs` without completing
72
- - `unknown` — fallback for unexpected failure modes
138
+ - Handle `attestationPda: null` when optional SAS issuance is missing or unavailable.
139
+ - Read the required `policy` result for evaluated requirements, expiry, and evidence status.
140
+ - Handle `onError` when the hosted popup lacks the policy contract or the returned evidence does not satisfy it.
73
141
 
74
- Specific server-side rejection signals are deliberately not surfaced to the client.
142
+ The popup retains transport envelope version `1` and negotiates the policy contract through separate request fields.
143
+ The compatible popup supplies legacy consumers with their original payload types after a valid attestation exists and the requested score floor passes.
144
+ A popup rollback makes upgraded consumers reject results until compatible service returns.
75
145
 
76
- ## v1 limitations
146
+ ## Limitations
77
147
 
78
- - Devnet only. Mainnet support is planned after the protocol clears its release gates.
79
- - Hardcoded integrator allowlist on the entros.io side. Self-serve integrator onboarding is planned.
80
- - Mobile browsers may open the popup as a new tab rather than a windowed popup. Native mobile support via Mobile Wallet Adapter is not yet implemented in this component; see [`entros-mobile`](https://github.com/entros-protocol/entros-mobile) for the native Solana Mobile dApp.
148
+ - Devnet only. Mainnet support remains planned.
149
+ - The browser callback reports the completed flow. Protected actions require the settlement checks above.
150
+ - Integrator origins require the hosted allowlist. Self-serve onboarding remains planned.
151
+ - Mobile browsers can open the popup in a new tab. This component does not implement native Mobile Wallet Adapter support.
81
152
 
82
153
  ## Integration safeguards
83
154
 
84
- - Origin gate on every postMessage (`event.origin === "https://entros.io"`)
85
- - Replay protection via per-popup `request_id`
86
- - Parent timeout through [`timeoutMs`](#full-api)
87
- - Popup-blocked fallback with user-gesture retry
88
- - Idempotent cancel
89
- - React 19 typed strict-mode
155
+ - Checks the message origin against the configured popup origin.
156
+ - Checks the popup window and per-popup `request_id`.
157
+ - Rejects invalid, expired, or mismatched policy results.
158
+ - Applies the parent timeout and handles popup blocking and cancellation.
90
159
 
91
160
  ## License
92
161
 
package/dist/index.d.mts CHANGED
@@ -1,5 +1,87 @@
1
1
  import { ReactNode, CSSProperties, ReactElement } from 'react';
2
2
 
3
+ /** Pure policy evaluation. RPC evidence must come from a trusted account reader. */
4
+ interface PolicyRequest {
5
+ id: string;
6
+ version: 1;
7
+ minTrustScore: number;
8
+ maxVerificationAgeSeconds: number;
9
+ maxEvaluationAgeSeconds: number;
10
+ requiredAssurance: "browser_unattested";
11
+ uniquenessRequirement: "allow_unmeasured";
12
+ requireAttestation: boolean;
13
+ cluster: "devnet";
14
+ }
15
+ type PolicyRequestInput = Omit<PolicyRequest, "maxEvaluationAgeSeconds" | "requireAttestation"> & Partial<Pick<PolicyRequest, "maxEvaluationAgeSeconds" | "requireAttestation">>;
16
+ interface PolicyProgramIds {
17
+ anchor: string;
18
+ verifier: string;
19
+ registry: string;
20
+ sas: string;
21
+ credential: string;
22
+ schema: string;
23
+ }
24
+ type PolicyAttestation = {
25
+ status: "present";
26
+ address: string;
27
+ readContextSlot: number;
28
+ expiresAt: number | null;
29
+ } | {
30
+ status: "missing" | "invalid" | "unavailable";
31
+ };
32
+ interface PolicyEvidence {
33
+ cluster: "devnet";
34
+ genesisHash: string;
35
+ programIds: PolicyProgramIds;
36
+ assuranceTier: "browser_unattested";
37
+ uniquenessStatus: "unmeasured";
38
+ readContextSlot: number;
39
+ identity: {
40
+ walletPubkey: string;
41
+ identityPda: string;
42
+ creationTimestamp: number;
43
+ lastVerificationTimestamp: number;
44
+ verificationCount: number;
45
+ trustScore: number;
46
+ currentCommitment: string;
47
+ projectionVersion: number;
48
+ lastResetTimestamp: number;
49
+ lastRebaselineTimestamp: number;
50
+ mint: string;
51
+ };
52
+ transaction: {
53
+ signature: string;
54
+ slot: number;
55
+ blockTime: number;
56
+ commitment: string;
57
+ kind: "mint" | "update" | "rebaseline";
58
+ };
59
+ attestation: PolicyAttestation;
60
+ }
61
+ type PolicyReason = "accepted" | "score_below_minimum" | "verification_stale" | "attestation_required" | "unsupported_policy" | "unsupported_assurance" | "unsupported_uniqueness" | "invalid_evidence" | "state_unavailable";
62
+ interface PolicyResultBase {
63
+ policyId: string;
64
+ policyVersion: 1;
65
+ requirements: PolicyRequest;
66
+ evaluatedAt: number;
67
+ expiresAt: number;
68
+ evidenceTimestamp: number | null;
69
+ evaluatedAgeSeconds: number | null;
70
+ }
71
+ type PolicyResult = PolicyResultBase & ({
72
+ decision: "allow";
73
+ reason: "accepted";
74
+ evidence: PolicyEvidence;
75
+ } | {
76
+ decision: "deny";
77
+ reason: Exclude<PolicyReason, "accepted" | "state_unavailable">;
78
+ evidence: PolicyEvidence | null;
79
+ } | {
80
+ decision: "unavailable";
81
+ reason: "state_unavailable";
82
+ evidence: PolicyEvidence | null;
83
+ });
84
+
3
85
  /**
4
86
  * Public type surface for `@entros/verify`.
5
87
  *
@@ -7,14 +89,18 @@ import { ReactNode, CSSProperties, ReactElement } from 'react';
7
89
  * (`wallet_pubkey`); the JS API surfaced to integrators uses camelCase
8
90
  * (`walletPubkey`). The popup-manager layer translates between them.
9
91
  */
92
+
10
93
  type Cluster = "devnet";
11
94
  /** Result delivered to the integrator's onVerified callback. */
12
95
  interface EntrosVerifyResult {
13
96
  walletPubkey: string;
14
- attestationPda: string;
97
+ attestationPda: string | null;
15
98
  txSig: string;
16
99
  trustScore: number;
17
100
  cluster: Cluster;
101
+ policy: PolicyResult & {
102
+ decision: "allow";
103
+ };
18
104
  }
19
105
  /**
20
106
  * Opaque error categories. Specific server-side reason codes never reach
@@ -23,6 +109,7 @@ interface EntrosVerifyResult {
23
109
  type EntrosVerifyErrorReason = "wallet_rejected" | "validation_failed" | "network_error" | "user_canceled" | "origin_invalid" | "popup_blocked" | "timeout" | "unknown";
24
110
  interface EntrosVerifyError {
25
111
  reason: EntrosVerifyErrorReason;
112
+ policyReason?: PolicyReason;
26
113
  }
27
114
  type EntrosVerifyProgressStatus = "wallet_connecting" | "capturing" | "proving" | "submitting" | "attesting";
28
115
  interface EntrosVerifyProgress {
@@ -52,6 +139,8 @@ interface EntrosVerifyProps {
52
139
  * `validation_failed` instead of `entros/verified`.
53
140
  */
54
141
  minTrustScore?: number;
142
+ /** Application requirements. Missing policy uses the documented day/90-second defaults. */
143
+ policy?: PolicyRequestInput;
55
144
  /** Called on successful verification. Required. */
56
145
  onVerified: (result: EntrosVerifyResult) => void;
57
146
  /** Called on any failure or cancellation. Optional. */
@@ -85,4 +174,4 @@ interface EntrosVerifyProps {
85
174
  }
86
175
  declare function EntrosVerify(props: EntrosVerifyProps): ReactElement;
87
176
 
88
- export { type Cluster, EntrosVerify, type EntrosVerifyError, type EntrosVerifyErrorReason, type EntrosVerifyProgress, type EntrosVerifyProgressStatus, type EntrosVerifyProps, type EntrosVerifyResult };
177
+ export { type Cluster, EntrosVerify, type EntrosVerifyError, type EntrosVerifyErrorReason, type EntrosVerifyProgress, type EntrosVerifyProgressStatus, type EntrosVerifyProps, type EntrosVerifyResult, type PolicyReason, type PolicyRequest, type PolicyRequestInput, type PolicyResult };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,87 @@
1
1
  import { ReactNode, CSSProperties, ReactElement } from 'react';
2
2
 
3
+ /** Pure policy evaluation. RPC evidence must come from a trusted account reader. */
4
+ interface PolicyRequest {
5
+ id: string;
6
+ version: 1;
7
+ minTrustScore: number;
8
+ maxVerificationAgeSeconds: number;
9
+ maxEvaluationAgeSeconds: number;
10
+ requiredAssurance: "browser_unattested";
11
+ uniquenessRequirement: "allow_unmeasured";
12
+ requireAttestation: boolean;
13
+ cluster: "devnet";
14
+ }
15
+ type PolicyRequestInput = Omit<PolicyRequest, "maxEvaluationAgeSeconds" | "requireAttestation"> & Partial<Pick<PolicyRequest, "maxEvaluationAgeSeconds" | "requireAttestation">>;
16
+ interface PolicyProgramIds {
17
+ anchor: string;
18
+ verifier: string;
19
+ registry: string;
20
+ sas: string;
21
+ credential: string;
22
+ schema: string;
23
+ }
24
+ type PolicyAttestation = {
25
+ status: "present";
26
+ address: string;
27
+ readContextSlot: number;
28
+ expiresAt: number | null;
29
+ } | {
30
+ status: "missing" | "invalid" | "unavailable";
31
+ };
32
+ interface PolicyEvidence {
33
+ cluster: "devnet";
34
+ genesisHash: string;
35
+ programIds: PolicyProgramIds;
36
+ assuranceTier: "browser_unattested";
37
+ uniquenessStatus: "unmeasured";
38
+ readContextSlot: number;
39
+ identity: {
40
+ walletPubkey: string;
41
+ identityPda: string;
42
+ creationTimestamp: number;
43
+ lastVerificationTimestamp: number;
44
+ verificationCount: number;
45
+ trustScore: number;
46
+ currentCommitment: string;
47
+ projectionVersion: number;
48
+ lastResetTimestamp: number;
49
+ lastRebaselineTimestamp: number;
50
+ mint: string;
51
+ };
52
+ transaction: {
53
+ signature: string;
54
+ slot: number;
55
+ blockTime: number;
56
+ commitment: string;
57
+ kind: "mint" | "update" | "rebaseline";
58
+ };
59
+ attestation: PolicyAttestation;
60
+ }
61
+ type PolicyReason = "accepted" | "score_below_minimum" | "verification_stale" | "attestation_required" | "unsupported_policy" | "unsupported_assurance" | "unsupported_uniqueness" | "invalid_evidence" | "state_unavailable";
62
+ interface PolicyResultBase {
63
+ policyId: string;
64
+ policyVersion: 1;
65
+ requirements: PolicyRequest;
66
+ evaluatedAt: number;
67
+ expiresAt: number;
68
+ evidenceTimestamp: number | null;
69
+ evaluatedAgeSeconds: number | null;
70
+ }
71
+ type PolicyResult = PolicyResultBase & ({
72
+ decision: "allow";
73
+ reason: "accepted";
74
+ evidence: PolicyEvidence;
75
+ } | {
76
+ decision: "deny";
77
+ reason: Exclude<PolicyReason, "accepted" | "state_unavailable">;
78
+ evidence: PolicyEvidence | null;
79
+ } | {
80
+ decision: "unavailable";
81
+ reason: "state_unavailable";
82
+ evidence: PolicyEvidence | null;
83
+ });
84
+
3
85
  /**
4
86
  * Public type surface for `@entros/verify`.
5
87
  *
@@ -7,14 +89,18 @@ import { ReactNode, CSSProperties, ReactElement } from 'react';
7
89
  * (`wallet_pubkey`); the JS API surfaced to integrators uses camelCase
8
90
  * (`walletPubkey`). The popup-manager layer translates between them.
9
91
  */
92
+
10
93
  type Cluster = "devnet";
11
94
  /** Result delivered to the integrator's onVerified callback. */
12
95
  interface EntrosVerifyResult {
13
96
  walletPubkey: string;
14
- attestationPda: string;
97
+ attestationPda: string | null;
15
98
  txSig: string;
16
99
  trustScore: number;
17
100
  cluster: Cluster;
101
+ policy: PolicyResult & {
102
+ decision: "allow";
103
+ };
18
104
  }
19
105
  /**
20
106
  * Opaque error categories. Specific server-side reason codes never reach
@@ -23,6 +109,7 @@ interface EntrosVerifyResult {
23
109
  type EntrosVerifyErrorReason = "wallet_rejected" | "validation_failed" | "network_error" | "user_canceled" | "origin_invalid" | "popup_blocked" | "timeout" | "unknown";
24
110
  interface EntrosVerifyError {
25
111
  reason: EntrosVerifyErrorReason;
112
+ policyReason?: PolicyReason;
26
113
  }
27
114
  type EntrosVerifyProgressStatus = "wallet_connecting" | "capturing" | "proving" | "submitting" | "attesting";
28
115
  interface EntrosVerifyProgress {
@@ -52,6 +139,8 @@ interface EntrosVerifyProps {
52
139
  * `validation_failed` instead of `entros/verified`.
53
140
  */
54
141
  minTrustScore?: number;
142
+ /** Application requirements. Missing policy uses the documented day/90-second defaults. */
143
+ policy?: PolicyRequestInput;
55
144
  /** Called on successful verification. Required. */
56
145
  onVerified: (result: EntrosVerifyResult) => void;
57
146
  /** Called on any failure or cancellation. Optional. */
@@ -85,4 +174,4 @@ interface EntrosVerifyProps {
85
174
  }
86
175
  declare function EntrosVerify(props: EntrosVerifyProps): ReactElement;
87
176
 
88
- export { type Cluster, EntrosVerify, type EntrosVerifyError, type EntrosVerifyErrorReason, type EntrosVerifyProgress, type EntrosVerifyProgressStatus, type EntrosVerifyProps, type EntrosVerifyResult };
177
+ export { type Cluster, EntrosVerify, type EntrosVerifyError, type EntrosVerifyErrorReason, type EntrosVerifyProgress, type EntrosVerifyProgressStatus, type EntrosVerifyProps, type EntrosVerifyResult, type PolicyReason, type PolicyRequest, type PolicyRequestInput, type PolicyResult };