@entros/verify 0.2.0 → 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 +76 -16
- 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/package.json +10 -1
package/README.md
CHANGED
|
@@ -7,14 +7,14 @@ It opens the Entros popup and checks the returned application policy result befo
|
|
|
7
7
|
|
|
8
8
|
Source: [github.com/entros-protocol/entros-verify](https://github.com/entros-protocol/entros-verify) · Hosted by [entros.io](https://entros.io).
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
13
|
|
|
14
|
-
|
|
14
|
+
Install with React 19:
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
npm install @entros/verify
|
|
17
|
+
npm install @entros/verify
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
## Usage
|
|
@@ -26,7 +26,7 @@ import { EntrosVerify } from "@entros/verify";
|
|
|
26
26
|
integratorKey="your-integrator-key"
|
|
27
27
|
onVerified={(result) => showVerificationResult(result)}
|
|
28
28
|
onError={(error) => showVerificationError(error.reason, error.policyReason)}
|
|
29
|
-
|
|
29
|
+
/>;
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
Without `policy`, the component uses a one-day verification age, a 90-second evaluation age, and optional SAS issuance.
|
|
@@ -109,21 +109,21 @@ Use `style` for inline styles and children for custom button content.
|
|
|
109
109
|
`onError` receives `reason` and an optional `policyReason`.
|
|
110
110
|
Policy reasons describe application requirements or evidence availability. They do not expose private behavioral rejection signals.
|
|
111
111
|
|
|
112
|
-
| Reason
|
|
113
|
-
|
|
114
|
-
| `wallet_rejected`
|
|
112
|
+
| Reason | Meaning |
|
|
113
|
+
| ------------------- | --------------------------------------------------- |
|
|
114
|
+
| `wallet_rejected` | User denied wallet connection or signing |
|
|
115
115
|
| `validation_failed` | Verification or the application policy did not pass |
|
|
116
|
-
| `network_error`
|
|
117
|
-
| `user_canceled`
|
|
118
|
-
| `origin_invalid`
|
|
119
|
-
| `popup_blocked`
|
|
120
|
-
| `timeout`
|
|
121
|
-
| `unknown`
|
|
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
122
|
|
|
123
123
|
## Settlement checks
|
|
124
124
|
|
|
125
125
|
The React-free `@entros/verify/policy` subpath exports `normalizePolicyRequest`, `evaluatePolicy`, and strict wire guards.
|
|
126
|
-
Pair the evaluator with `readIntegratorEvidence` from
|
|
126
|
+
Pair the evaluator with `readIntegratorEvidence` from Pulse `4.10.2` or later against your service's configured RPC connection.
|
|
127
127
|
The evaluator accepts typed observations. It cannot authenticate observations supplied by a browser.
|
|
128
128
|
|
|
129
129
|
For protected actions, your service owns the policy and authenticates the wallet's signature over a one-use action challenge.
|
|
@@ -131,6 +131,66 @@ Bind the challenge to the wallet, action parameters, audience, and expiry.
|
|
|
131
131
|
Read current chain evidence before executing the action. Consume the challenge and execute the action in one atomic operation.
|
|
132
132
|
An on-chain action must enforce its requirements within the action transaction.
|
|
133
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
|
+
|
|
134
194
|
## Migration from `0.1.1`
|
|
135
195
|
|
|
136
196
|
Version `0.2.0` changes the callback contract:
|
|
@@ -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 };
|