@entros/verify 0.1.1 → 0.3.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,220 @@
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
+ Pin an exact version when you integrate the policy contract.
11
+ The package is published, and the hosted Entros popup supports this policy contract.
12
+ A self-hosted popup must implement the same contract before it can serve an upgraded consumer.
13
+
14
+ Install with React 19:
15
+
9
16
  ```bash
10
17
  npm install @entros/verify
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)}
29
+ />;
30
+ ```
31
+
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)}
21
54
  />
22
55
  ```
23
56
 
24
- ## Result shape
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.
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
- SAS issuance is best-effort after wallet-connected verification. Check that the returned address contains an attestation account before relying on it.
39
-
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 Pulse `4.10.2` or later 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
+ Run the [protected-action example](examples/protected-action) to exercise signature checks, fresh policy evaluation, and one-use settlement with synthetic data.
135
+
136
+ ## Agent Operator Permit
137
+
138
+ The React-free `@entros/verify/agent-permit` subpath implements permit version 1 for agents in the 8004 agent registry on devnet.
139
+ A permit authorizes one action by one registered agent. The wallet that owns the agent signs it, and the agent's registered agent wallet presents it.
140
+
141
+ 1. Your service reads the agent with `readAgentState` from Pulse `4.12.0` or later.
142
+ 2. Your service calls `createAgentPermitRequest` and stores the rendered text under its nonce.
143
+ 3. The owner opens the request on the Entros signing page and signs it with the owning wallet.
144
+ 4. The agent signs `renderAgentPermitPresentation(permitId)` with its agent wallet and sends the settlement bundle.
145
+ 5. Your service runs `precheckAgentPermit`, reads agent state and operator evidence, and runs `evaluateAgentPermit`.
146
+ 6. On `allow`, your service consumes the nonce and executes the stored action in one atomic operation.
147
+
148
+ ```ts
149
+ import {
150
+ evaluateAgentPermit,
151
+ parseAgentPermitSettlement,
152
+ precheckAgentPermit,
153
+ } from "@entros/verify/agent-permit";
154
+
155
+ const bundle = parseAgentPermitSettlement(body);
156
+ const stored = bundle && pending.get(bundle.nonce);
157
+ if (!bundle || !stored) return reject("nonce_unavailable");
158
+
159
+ const signatures = {
160
+ operatorSignature: bundle.operatorSignature,
161
+ presentationSignature: bundle.presentationSignature,
162
+ };
163
+ const precheck = precheckAgentPermit({ request: stored, ...signatures, nowSeconds: now() });
164
+ if (!precheck.ok) return reject(precheck.reason);
165
+
166
+ const [agentState, operatorEvidence] = await Promise.all([
167
+ readAgentState({ agent: stored.agent, connection }),
168
+ readIntegratorEvidence({
169
+ walletPubkey: stored.operator,
170
+ transactionSignature: bundle.verifiedTransaction,
171
+ connection,
172
+ nowSeconds: now,
173
+ }),
174
+ ]);
175
+ const result = evaluateAgentPermit({
176
+ request: stored,
177
+ ...signatures,
178
+ agentState,
179
+ operatorEvidence,
180
+ nowSeconds: now(),
181
+ });
182
+ ```
183
+
184
+ The precheck covers expiry and both signatures, so an expired or forged permit costs your service no chain read.
185
+ Sample the clock again after the reads, because a permit can expire while they run.
186
+
187
+ - Settle only requests that your service stored. Never take request text, policy, or RPC settings from the agent.
188
+ - Execute the stored action at settlement. Do not return a reusable credential to the presenter.
189
+ - The owner is the wallet in the Metaplex Core asset. The registry's cached owner and the `entros:human-operator` metadata grant nothing.
190
+ - A transfer after the settlement read can still land before your action. An on-chain action must check ownership inside its transaction.
191
+
192
+ A permit states current wallet control of a registered agent and the owner's Entros policy result. It does not establish legal ownership, population uniqueness, or hardware assurance.
193
+
194
+ ## Migration from `0.1.1`
62
195
 
63
- `onError` receives one of:
196
+ Version `0.2.0` changes the callback contract:
64
197
 
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
198
+ - Handle `attestationPda: null` when optional SAS issuance is missing or unavailable.
199
+ - Read the required `policy` result for evaluated requirements, expiry, and evidence status.
200
+ - Handle `onError` when the hosted popup lacks the policy contract or the returned evidence does not satisfy it.
73
201
 
74
- Specific server-side rejection signals are deliberately not surfaced to the client.
202
+ The popup retains transport envelope version `1` and negotiates the policy contract through separate request fields.
203
+ The compatible popup supplies legacy consumers with their original payload types after a valid attestation exists and the requested score floor passes.
204
+ A popup rollback makes upgraded consumers reject results until compatible service returns.
75
205
 
76
- ## v1 limitations
206
+ ## Limitations
77
207
 
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.
208
+ - Devnet only. Mainnet support remains planned.
209
+ - The browser callback reports the completed flow. Protected actions require the settlement checks above.
210
+ - Integrator origins require the hosted allowlist. Self-serve onboarding remains planned.
211
+ - Mobile browsers can open the popup in a new tab. This component does not implement native Mobile Wallet Adapter support.
81
212
 
82
213
  ## Integration safeguards
83
214
 
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
215
+ - Checks the message origin against the configured popup origin.
216
+ - Checks the popup window and per-popup `request_id`.
217
+ - Rejects invalid, expired, or mismatched policy results.
218
+ - Applies the parent timeout and handles popup blocking and cancellation.
90
219
 
91
220
  ## License
92
221
 
@@ -0,0 +1,190 @@
1
+ import { PolicyRequest, PolicyEvidenceReadResult, PolicyResult } from './policy.mjs';
2
+
3
+ declare const AGENT_PERMIT_VERSION_LINE = "Entros-Agent-Permit-v1";
4
+ declare const AGENT_PERMIT_NOTICE_LINE = "Sign only to let this agent perform the action below. This is not a transaction.";
5
+ declare const AGENT_PERMIT_PRESENTATION_LINE = "Entros-Agent-Permit-Presentation-v1";
6
+ declare const AGENT_PERMIT_NETWORK: Readonly<{
7
+ readonly cluster: "devnet";
8
+ readonly genesisHash: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG";
9
+ readonly entrosAnchorProgram: string;
10
+ readonly agentRegistryProgram: "8oo4J9tBB3Hna1jRQ3rWvJjojqM5DYTDJo5cejUuJy3C";
11
+ readonly agentCollection: "6CTyGPcn8dMwKEqgtvx2XCpkGUd7uqCVK6937RSM5bhA";
12
+ readonly coreProgram: "CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d";
13
+ }>;
14
+ declare const AGENT_PERMIT_LIMITS: Readonly<{
15
+ minLifetimeSeconds: 30;
16
+ maxLifetimeSeconds: 900;
17
+ clockSkewSeconds: 30;
18
+ maxAudienceLength: 200;
19
+ maxLabelLength: 96;
20
+ minTimeSeconds: 946684800;
21
+ maxTimeSeconds: 253402300799;
22
+ }>;
23
+ interface AgentPermitAction {
24
+ label: string;
25
+ /** Lowercase hex SHA-256 of the consumer's own action record. */
26
+ sha256: string;
27
+ }
28
+ interface AgentPermitRequest {
29
+ version: 1;
30
+ agent: string;
31
+ agentWallet: string;
32
+ operator: string;
33
+ audience: string;
34
+ action: AgentPermitAction;
35
+ policy: PolicyRequest;
36
+ cluster: "devnet";
37
+ genesisHash: string;
38
+ entrosAnchorProgram: string;
39
+ agentRegistryProgram: string;
40
+ agentCollection: string;
41
+ issuedAt: number;
42
+ expiresAt: number;
43
+ nonce: string;
44
+ }
45
+ interface CreateAgentPermitRequestInput {
46
+ agent: string;
47
+ agentWallet: string;
48
+ operator: string;
49
+ audience: string;
50
+ action: AgentPermitAction;
51
+ policy: PolicyRequest;
52
+ issuedAt: number;
53
+ lifetimeSeconds: number;
54
+ /** Omit to draw 32 random bytes from `crypto.getRandomValues`. */
55
+ nonce?: string;
56
+ }
57
+ type AgentWalletStatus = "bound" | "unbound" | "stale";
58
+ interface AgentStateEvidence {
59
+ cluster: "devnet";
60
+ genesisHash: string;
61
+ coreProgram: string;
62
+ agentRegistryProgram: string;
63
+ agentCollection: string;
64
+ agent: string;
65
+ agentAccount: string;
66
+ /** Owner field of the Metaplex Core asset. The only owner source. */
67
+ owner: string;
68
+ /** Registry cache. Informational, and the agent wallet counts only when it matches. */
69
+ cachedOwner: string;
70
+ agentWallet: string | null;
71
+ agentWalletStatus: AgentWalletStatus;
72
+ readContextSlot: number;
73
+ }
74
+ type AgentStateFailureReason = "invalid_request" | "wrong_cluster" | "agent_missing" | "agent_invalid" | "agent_unregistered" | "rpc_unavailable";
75
+ type AgentStateReadResult = {
76
+ status: "available";
77
+ evidence: AgentStateEvidence;
78
+ } | {
79
+ status: "invalid" | "unavailable";
80
+ reason: AgentStateFailureReason;
81
+ };
82
+ type AgentPermitReason = "accepted" | "invalid_permit" | "permit_expired" | "invalid_signature" | "invalid_presentation" | "wrong_cluster" | "agent_missing" | "agent_invalid" | "agent_unregistered" | "agent_unavailable" | "owner_changed" | "agent_wallet_stale" | "agent_wallet_unbound" | "agent_wallet_changed" | "score_below_minimum" | "verification_stale" | "attestation_required" | "invalid_evidence" | "state_unavailable";
83
+ type AgentPermitDenyReason = Exclude<AgentPermitReason, "accepted" | "agent_unavailable" | "state_unavailable">;
84
+ type AgentPermitPrecheck = {
85
+ ok: true;
86
+ request: AgentPermitRequest;
87
+ permitId: string;
88
+ } | {
89
+ ok: false;
90
+ reason: "invalid_permit" | "permit_expired" | "invalid_signature" | "invalid_presentation";
91
+ request: AgentPermitRequest | null;
92
+ permitId: string | null;
93
+ };
94
+ interface AgentPermitResultBase {
95
+ permitId: string | null;
96
+ request: AgentPermitRequest | null;
97
+ evaluatedAt: number;
98
+ expiresAt: number | null;
99
+ agentState: AgentStateEvidence | null;
100
+ policy: PolicyResult | null;
101
+ }
102
+ type AgentPermitResult = AgentPermitResultBase & ({
103
+ decision: "allow";
104
+ reason: "accepted";
105
+ } | {
106
+ decision: "deny";
107
+ reason: AgentPermitDenyReason;
108
+ } | {
109
+ decision: "unavailable";
110
+ reason: "agent_unavailable" | "state_unavailable";
111
+ });
112
+ interface AgentPermitSignatures {
113
+ operatorSignature: string;
114
+ presentationSignature: string;
115
+ }
116
+ interface AgentPermitEvaluationInput extends AgentPermitSignatures {
117
+ request: AgentPermitRequest;
118
+ agentState: AgentStateReadResult;
119
+ operatorEvidence: PolicyEvidenceReadResult;
120
+ nowSeconds: number;
121
+ }
122
+ interface AgentPermitApproval {
123
+ version: 1;
124
+ permitId: string;
125
+ operatorSignature: string;
126
+ verifiedTransaction: string;
127
+ }
128
+ interface AgentPermitSettlementBundle extends AgentPermitSignatures {
129
+ version: 1;
130
+ nonce: string;
131
+ verifiedTransaction: string;
132
+ }
133
+ declare class AgentPermitValidationError extends Error {
134
+ readonly field: string;
135
+ constructor(field: string);
136
+ }
137
+ /** Accepts only URLs that already equal their WHATWG `URL.href`. */
138
+ declare function isAgentPermitAudience(value: unknown): value is string;
139
+ /** Validates every field and returns a detached copy. Throws `AgentPermitValidationError`. */
140
+ declare function normalizeAgentPermitRequest(value: unknown): AgentPermitRequest;
141
+ /** Builds a permit request for the consumer to store and render. */
142
+ declare function createAgentPermitRequest(input: CreateAgentPermitRequestInput): AgentPermitRequest;
143
+ /** Renders the seventeen-line text that the operator signs. */
144
+ declare function renderAgentPermitMessage(request: AgentPermitRequest): string;
145
+ /** Parses a permit request and requires byte equality with its own rendering. */
146
+ declare function parseAgentPermitMessage(text: unknown): AgentPermitRequest;
147
+ /** Lowercase hex SHA-256 of the permit request text. */
148
+ declare function agentPermitId(request: AgentPermitRequest): string;
149
+ /** The two-line text that the agent wallet signs. */
150
+ declare function renderAgentPermitPresentation(permitId: string): string;
151
+ /** Checks the operator signature and the agent wallet presentation with strict rules. */
152
+ declare function verifyAgentPermitSignatures(request: AgentPermitRequest, signatures: {
153
+ operatorSignature: unknown;
154
+ presentationSignature: unknown;
155
+ }): {
156
+ operator: boolean;
157
+ presentation: boolean;
158
+ };
159
+ /**
160
+ * Runs every check that needs no chain read: request shape, clock, expiry and both signatures.
161
+ * Call it before reading chain state so an expired or forged permit costs no RPC request.
162
+ */
163
+ declare function precheckAgentPermit(input: {
164
+ request: unknown;
165
+ operatorSignature: unknown;
166
+ presentationSignature: unknown;
167
+ nowSeconds: number;
168
+ }): AgentPermitPrecheck;
169
+ /** Strict shape check for agent state from a trusted reader. */
170
+ declare function isAgentStateEvidence(value: unknown): value is AgentStateEvidence;
171
+ /**
172
+ * Evaluates a permit at settlement against agent state and operator evidence read after the
173
+ * precheck. Pass a clock value sampled after those reads complete.
174
+ */
175
+ declare function evaluateAgentPermit(input: AgentPermitEvaluationInput): AgentPermitResult;
176
+ /** Serializes the approval that the signing page hands to the agent. */
177
+ declare function encodeAgentPermitApproval(approval: Omit<AgentPermitApproval, "version">): string;
178
+ declare function parseAgentPermitApproval(input: unknown): AgentPermitApproval | null;
179
+ /** Serializes the bundle that the agent sends to the consumer. */
180
+ declare function encodeAgentPermitSettlement(bundle: Omit<AgentPermitSettlementBundle, "version">): string;
181
+ declare function parseAgentPermitSettlement(input: unknown): AgentPermitSettlementBundle | null;
182
+ /** URL fragment for the signing page, without the leading `#`. */
183
+ declare function encodeAgentPermitFragment(request: AgentPermitRequest): string;
184
+ /** Parses a `request=` fragment. Returns null for anything else. */
185
+ declare function parseAgentPermitFragment(fragment: string): {
186
+ request: AgentPermitRequest;
187
+ message: string;
188
+ } | null;
189
+
190
+ export { AGENT_PERMIT_LIMITS, AGENT_PERMIT_NETWORK, AGENT_PERMIT_NOTICE_LINE, AGENT_PERMIT_PRESENTATION_LINE, AGENT_PERMIT_VERSION_LINE, type AgentPermitAction, type AgentPermitApproval, type AgentPermitDenyReason, type AgentPermitEvaluationInput, type AgentPermitPrecheck, type AgentPermitReason, type AgentPermitRequest, type AgentPermitResult, type AgentPermitSettlementBundle, type AgentPermitSignatures, AgentPermitValidationError, type AgentStateEvidence, type AgentStateFailureReason, type AgentStateReadResult, type AgentWalletStatus, type CreateAgentPermitRequestInput, agentPermitId, createAgentPermitRequest, encodeAgentPermitApproval, encodeAgentPermitFragment, encodeAgentPermitSettlement, evaluateAgentPermit, isAgentPermitAudience, isAgentStateEvidence, normalizeAgentPermitRequest, parseAgentPermitApproval, parseAgentPermitFragment, parseAgentPermitMessage, parseAgentPermitSettlement, precheckAgentPermit, renderAgentPermitMessage, renderAgentPermitPresentation, verifyAgentPermitSignatures };
@@ -0,0 +1,190 @@
1
+ import { PolicyRequest, PolicyEvidenceReadResult, PolicyResult } from './policy.js';
2
+
3
+ declare const AGENT_PERMIT_VERSION_LINE = "Entros-Agent-Permit-v1";
4
+ declare const AGENT_PERMIT_NOTICE_LINE = "Sign only to let this agent perform the action below. This is not a transaction.";
5
+ declare const AGENT_PERMIT_PRESENTATION_LINE = "Entros-Agent-Permit-Presentation-v1";
6
+ declare const AGENT_PERMIT_NETWORK: Readonly<{
7
+ readonly cluster: "devnet";
8
+ readonly genesisHash: "EtWTRABZaYq6iMfeYKouRu166VU2xqa1wcaWoxPkrZBG";
9
+ readonly entrosAnchorProgram: string;
10
+ readonly agentRegistryProgram: "8oo4J9tBB3Hna1jRQ3rWvJjojqM5DYTDJo5cejUuJy3C";
11
+ readonly agentCollection: "6CTyGPcn8dMwKEqgtvx2XCpkGUd7uqCVK6937RSM5bhA";
12
+ readonly coreProgram: "CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d";
13
+ }>;
14
+ declare const AGENT_PERMIT_LIMITS: Readonly<{
15
+ minLifetimeSeconds: 30;
16
+ maxLifetimeSeconds: 900;
17
+ clockSkewSeconds: 30;
18
+ maxAudienceLength: 200;
19
+ maxLabelLength: 96;
20
+ minTimeSeconds: 946684800;
21
+ maxTimeSeconds: 253402300799;
22
+ }>;
23
+ interface AgentPermitAction {
24
+ label: string;
25
+ /** Lowercase hex SHA-256 of the consumer's own action record. */
26
+ sha256: string;
27
+ }
28
+ interface AgentPermitRequest {
29
+ version: 1;
30
+ agent: string;
31
+ agentWallet: string;
32
+ operator: string;
33
+ audience: string;
34
+ action: AgentPermitAction;
35
+ policy: PolicyRequest;
36
+ cluster: "devnet";
37
+ genesisHash: string;
38
+ entrosAnchorProgram: string;
39
+ agentRegistryProgram: string;
40
+ agentCollection: string;
41
+ issuedAt: number;
42
+ expiresAt: number;
43
+ nonce: string;
44
+ }
45
+ interface CreateAgentPermitRequestInput {
46
+ agent: string;
47
+ agentWallet: string;
48
+ operator: string;
49
+ audience: string;
50
+ action: AgentPermitAction;
51
+ policy: PolicyRequest;
52
+ issuedAt: number;
53
+ lifetimeSeconds: number;
54
+ /** Omit to draw 32 random bytes from `crypto.getRandomValues`. */
55
+ nonce?: string;
56
+ }
57
+ type AgentWalletStatus = "bound" | "unbound" | "stale";
58
+ interface AgentStateEvidence {
59
+ cluster: "devnet";
60
+ genesisHash: string;
61
+ coreProgram: string;
62
+ agentRegistryProgram: string;
63
+ agentCollection: string;
64
+ agent: string;
65
+ agentAccount: string;
66
+ /** Owner field of the Metaplex Core asset. The only owner source. */
67
+ owner: string;
68
+ /** Registry cache. Informational, and the agent wallet counts only when it matches. */
69
+ cachedOwner: string;
70
+ agentWallet: string | null;
71
+ agentWalletStatus: AgentWalletStatus;
72
+ readContextSlot: number;
73
+ }
74
+ type AgentStateFailureReason = "invalid_request" | "wrong_cluster" | "agent_missing" | "agent_invalid" | "agent_unregistered" | "rpc_unavailable";
75
+ type AgentStateReadResult = {
76
+ status: "available";
77
+ evidence: AgentStateEvidence;
78
+ } | {
79
+ status: "invalid" | "unavailable";
80
+ reason: AgentStateFailureReason;
81
+ };
82
+ type AgentPermitReason = "accepted" | "invalid_permit" | "permit_expired" | "invalid_signature" | "invalid_presentation" | "wrong_cluster" | "agent_missing" | "agent_invalid" | "agent_unregistered" | "agent_unavailable" | "owner_changed" | "agent_wallet_stale" | "agent_wallet_unbound" | "agent_wallet_changed" | "score_below_minimum" | "verification_stale" | "attestation_required" | "invalid_evidence" | "state_unavailable";
83
+ type AgentPermitDenyReason = Exclude<AgentPermitReason, "accepted" | "agent_unavailable" | "state_unavailable">;
84
+ type AgentPermitPrecheck = {
85
+ ok: true;
86
+ request: AgentPermitRequest;
87
+ permitId: string;
88
+ } | {
89
+ ok: false;
90
+ reason: "invalid_permit" | "permit_expired" | "invalid_signature" | "invalid_presentation";
91
+ request: AgentPermitRequest | null;
92
+ permitId: string | null;
93
+ };
94
+ interface AgentPermitResultBase {
95
+ permitId: string | null;
96
+ request: AgentPermitRequest | null;
97
+ evaluatedAt: number;
98
+ expiresAt: number | null;
99
+ agentState: AgentStateEvidence | null;
100
+ policy: PolicyResult | null;
101
+ }
102
+ type AgentPermitResult = AgentPermitResultBase & ({
103
+ decision: "allow";
104
+ reason: "accepted";
105
+ } | {
106
+ decision: "deny";
107
+ reason: AgentPermitDenyReason;
108
+ } | {
109
+ decision: "unavailable";
110
+ reason: "agent_unavailable" | "state_unavailable";
111
+ });
112
+ interface AgentPermitSignatures {
113
+ operatorSignature: string;
114
+ presentationSignature: string;
115
+ }
116
+ interface AgentPermitEvaluationInput extends AgentPermitSignatures {
117
+ request: AgentPermitRequest;
118
+ agentState: AgentStateReadResult;
119
+ operatorEvidence: PolicyEvidenceReadResult;
120
+ nowSeconds: number;
121
+ }
122
+ interface AgentPermitApproval {
123
+ version: 1;
124
+ permitId: string;
125
+ operatorSignature: string;
126
+ verifiedTransaction: string;
127
+ }
128
+ interface AgentPermitSettlementBundle extends AgentPermitSignatures {
129
+ version: 1;
130
+ nonce: string;
131
+ verifiedTransaction: string;
132
+ }
133
+ declare class AgentPermitValidationError extends Error {
134
+ readonly field: string;
135
+ constructor(field: string);
136
+ }
137
+ /** Accepts only URLs that already equal their WHATWG `URL.href`. */
138
+ declare function isAgentPermitAudience(value: unknown): value is string;
139
+ /** Validates every field and returns a detached copy. Throws `AgentPermitValidationError`. */
140
+ declare function normalizeAgentPermitRequest(value: unknown): AgentPermitRequest;
141
+ /** Builds a permit request for the consumer to store and render. */
142
+ declare function createAgentPermitRequest(input: CreateAgentPermitRequestInput): AgentPermitRequest;
143
+ /** Renders the seventeen-line text that the operator signs. */
144
+ declare function renderAgentPermitMessage(request: AgentPermitRequest): string;
145
+ /** Parses a permit request and requires byte equality with its own rendering. */
146
+ declare function parseAgentPermitMessage(text: unknown): AgentPermitRequest;
147
+ /** Lowercase hex SHA-256 of the permit request text. */
148
+ declare function agentPermitId(request: AgentPermitRequest): string;
149
+ /** The two-line text that the agent wallet signs. */
150
+ declare function renderAgentPermitPresentation(permitId: string): string;
151
+ /** Checks the operator signature and the agent wallet presentation with strict rules. */
152
+ declare function verifyAgentPermitSignatures(request: AgentPermitRequest, signatures: {
153
+ operatorSignature: unknown;
154
+ presentationSignature: unknown;
155
+ }): {
156
+ operator: boolean;
157
+ presentation: boolean;
158
+ };
159
+ /**
160
+ * Runs every check that needs no chain read: request shape, clock, expiry and both signatures.
161
+ * Call it before reading chain state so an expired or forged permit costs no RPC request.
162
+ */
163
+ declare function precheckAgentPermit(input: {
164
+ request: unknown;
165
+ operatorSignature: unknown;
166
+ presentationSignature: unknown;
167
+ nowSeconds: number;
168
+ }): AgentPermitPrecheck;
169
+ /** Strict shape check for agent state from a trusted reader. */
170
+ declare function isAgentStateEvidence(value: unknown): value is AgentStateEvidence;
171
+ /**
172
+ * Evaluates a permit at settlement against agent state and operator evidence read after the
173
+ * precheck. Pass a clock value sampled after those reads complete.
174
+ */
175
+ declare function evaluateAgentPermit(input: AgentPermitEvaluationInput): AgentPermitResult;
176
+ /** Serializes the approval that the signing page hands to the agent. */
177
+ declare function encodeAgentPermitApproval(approval: Omit<AgentPermitApproval, "version">): string;
178
+ declare function parseAgentPermitApproval(input: unknown): AgentPermitApproval | null;
179
+ /** Serializes the bundle that the agent sends to the consumer. */
180
+ declare function encodeAgentPermitSettlement(bundle: Omit<AgentPermitSettlementBundle, "version">): string;
181
+ declare function parseAgentPermitSettlement(input: unknown): AgentPermitSettlementBundle | null;
182
+ /** URL fragment for the signing page, without the leading `#`. */
183
+ declare function encodeAgentPermitFragment(request: AgentPermitRequest): string;
184
+ /** Parses a `request=` fragment. Returns null for anything else. */
185
+ declare function parseAgentPermitFragment(fragment: string): {
186
+ request: AgentPermitRequest;
187
+ message: string;
188
+ } | null;
189
+
190
+ export { AGENT_PERMIT_LIMITS, AGENT_PERMIT_NETWORK, AGENT_PERMIT_NOTICE_LINE, AGENT_PERMIT_PRESENTATION_LINE, AGENT_PERMIT_VERSION_LINE, type AgentPermitAction, type AgentPermitApproval, type AgentPermitDenyReason, type AgentPermitEvaluationInput, type AgentPermitPrecheck, type AgentPermitReason, type AgentPermitRequest, type AgentPermitResult, type AgentPermitSettlementBundle, type AgentPermitSignatures, AgentPermitValidationError, type AgentStateEvidence, type AgentStateFailureReason, type AgentStateReadResult, type AgentWalletStatus, type CreateAgentPermitRequestInput, agentPermitId, createAgentPermitRequest, encodeAgentPermitApproval, encodeAgentPermitFragment, encodeAgentPermitSettlement, evaluateAgentPermit, isAgentPermitAudience, isAgentStateEvidence, normalizeAgentPermitRequest, parseAgentPermitApproval, parseAgentPermitFragment, parseAgentPermitMessage, parseAgentPermitSettlement, precheckAgentPermit, renderAgentPermitMessage, renderAgentPermitPresentation, verifyAgentPermitSignatures };