@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 +175 -46
- package/dist/agent-permit.d.mts +190 -0
- package/dist/agent-permit.d.ts +190 -0
- package/dist/agent-permit.js +897 -0
- package/dist/agent-permit.js.map +1 -0
- package/dist/agent-permit.mjs +850 -0
- package/dist/agent-permit.mjs.map +1 -0
- package/dist/index.d.mts +91 -2
- package/dist/index.d.ts +91 -2
- package/dist/index.js +420 -20
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +420 -20
- package/dist/index.mjs.map +1 -1
- package/dist/policy.d.mts +173 -0
- package/dist/policy.d.ts +173 -0
- package/dist/policy.js +450 -0
- package/dist/policy.js.map +1 -0
- package/dist/policy.mjs +414 -0
- package/dist/policy.mjs.map +1 -0
- package/package.json +18 -1
package/README.md
CHANGED
|
@@ -2,91 +2,220 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@entros/verify)
|
|
4
4
|
|
|
5
|
-
React component for Entros verification on Solana devnet.
|
|
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
|
-
##
|
|
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) =>
|
|
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
|
-
|
|
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;
|
|
29
|
-
attestationPda: string
|
|
30
|
-
txSig: string;
|
|
31
|
-
trustScore: number;
|
|
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
|
|
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
|
-
|
|
39
|
-
|
|
40
|
-
## Full API
|
|
83
|
+
## Component options
|
|
41
84
|
|
|
42
85
|
```tsx
|
|
43
86
|
<EntrosVerify
|
|
44
|
-
integratorKey="your-integrator-key"
|
|
45
|
-
cluster="devnet"
|
|
46
|
-
minTrustScore={200}
|
|
47
|
-
popupWidth={480}
|
|
48
|
-
popupHeight={720}
|
|
49
|
-
timeoutMs={9 * 60 * 1000}
|
|
50
|
-
popupBlockedFallback={true}
|
|
51
|
-
className="
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
|
99
|
+
Verify with Entros
|
|
58
100
|
</EntrosVerify>
|
|
59
101
|
```
|
|
60
102
|
|
|
61
|
-
|
|
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
|
-
`
|
|
196
|
+
Version `0.2.0` changes the callback contract:
|
|
64
197
|
|
|
65
|
-
- `
|
|
66
|
-
- `
|
|
67
|
-
- `
|
|
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
|
-
|
|
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
|
-
##
|
|
206
|
+
## Limitations
|
|
77
207
|
|
|
78
|
-
- Devnet only. Mainnet support
|
|
79
|
-
-
|
|
80
|
-
-
|
|
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
|
-
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
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 };
|