@entros/verify 0.1.0 → 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,89 +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
- Drop-in React component for Entros verification on Solana. Click → popup window opens to entros.io → user completes wallet-connected verification → component fires `onVerified` with the on-chain attestation reference.
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; // base58 SAS attestation PDA
30
- txSig: string; // base58 verification tx signature
31
- trustScore: number; // current Trust Score (0–10000)
32
- cluster: "devnet" | "mainnet-beta";
69
+ walletPubkey: string;
70
+ attestationPda: string | null;
71
+ txSig: string;
72
+ trustScore: number;
73
+ cluster: "devnet";
74
+ policy: PolicyResult & { decision: "allow" };
33
75
  }
34
76
  ```
35
77
 
36
- Read the on-chain attestation from any Solana program or client. No API keys, no escrow, no per-call billing.
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.
37
82
 
38
- ## Full API
83
+ ## Component options
39
84
 
40
85
  ```tsx
41
86
  <EntrosVerify
42
- integratorKey="jupiter" // required, registered with Entros
43
- cluster="devnet" // "devnet" | "mainnet-beta", default "devnet"
44
- minTrustScore={200} // optional gate
45
- popupWidth={480} // CSS px, default 480
46
- popupHeight={720} // CSS px, default 720
47
- timeoutMs={5 * 60 * 1000} // 5 min default
48
- popupBlockedFallback={true} // inline retry UI when popup blocked
49
- className="..." // applied to trigger button
50
- style={{ ... }}
51
- onVerified={(r) => {}} // required
52
- onError={(e) => {}} // optional — covers cancel, reject, timeout, etc.
53
- 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)}
54
98
  >
55
- Verify with Entros {/* custom button content */}
99
+ Verify with Entros
56
100
  </EntrosVerify>
57
101
  ```
58
102
 
59
- ## 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`
60
135
 
61
- `onError` receives one of:
136
+ Version `0.2.0` changes the callback contract:
62
137
 
63
- - `wallet_rejected` — user denied wallet connection or signing
64
- - `validation_failed` — verification did not pass server-side checks
65
- - `network_error` — popup encountered a network failure mid-flow
66
- - `user_canceled` — user closed the popup before completing
67
- - `origin_invalid` — integrator origin was not on the Entros allowlist
68
- - `popup_blocked` — browser blocked `window.open()`
69
- - `timeout` — popup remained open longer than `timeoutMs` without completing
70
- - `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.
71
141
 
72
- 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.
73
145
 
74
- ## v1 limitations
146
+ ## Limitations
75
147
 
76
- - Devnet only. Mainnet support lands in v2.
77
- - Hardcoded integrator allowlist on the entros.io side. Self-serve integrator onboarding lands in v2.
78
- - Mobile browsers may open the popup as a new tab rather than a windowed popup. Mobile-Wallet-Adapter-aware mobile flow lands in v1.5.
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.
79
152
 
80
- ## Production-readiness
153
+ ## Integration safeguards
81
154
 
82
- - Origin gate on every postMessage (`event.origin === "https://entros.io"`)
83
- - Replay protection via per-popup `request_id`
84
- - 5-minute timeout
85
- - Popup-blocked fallback with user-gesture retry
86
- - Idempotent cancel
87
- - 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.
88
159
 
89
160
  ## License
90
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
  */
10
- type Cluster = "devnet" | "mainnet-beta";
92
+
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. */
@@ -62,10 +151,7 @@ interface EntrosVerifyProps {
62
151
  popupWidth?: number;
63
152
  /** Popup height in CSS pixels. Defaults to 720. */
64
153
  popupHeight?: number;
65
- /**
66
- * Maximum time the popup is allowed to be open before this component
67
- * fires onError({reason: "timeout"}). Defaults to 5 minutes.
68
- */
154
+ /** See README.md#full-api for timeout behavior and the default. */
69
155
  timeoutMs?: number;
70
156
  /** Custom button content. Defaults to "Verify with Entros". */
71
157
  children?: ReactNode;
@@ -88,4 +174,4 @@ interface EntrosVerifyProps {
88
174
  }
89
175
  declare function EntrosVerify(props: EntrosVerifyProps): ReactElement;
90
176
 
91
- 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
  */
10
- type Cluster = "devnet" | "mainnet-beta";
92
+
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. */
@@ -62,10 +151,7 @@ interface EntrosVerifyProps {
62
151
  popupWidth?: number;
63
152
  /** Popup height in CSS pixels. Defaults to 720. */
64
153
  popupHeight?: number;
65
- /**
66
- * Maximum time the popup is allowed to be open before this component
67
- * fires onError({reason: "timeout"}). Defaults to 5 minutes.
68
- */
154
+ /** See README.md#full-api for timeout behavior and the default. */
69
155
  timeoutMs?: number;
70
156
  /** Custom button content. Defaults to "Verify with Entros". */
71
157
  children?: ReactNode;
@@ -88,4 +174,4 @@ interface EntrosVerifyProps {
88
174
  }
89
175
  declare function EntrosVerify(props: EntrosVerifyProps): ReactElement;
90
176
 
91
- 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 };