@agent-corpus/policy-manager 0.6.0 → 0.8.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 +28 -5
- package/dist/adapters.d.ts +11 -0
- package/dist/adapters.js +77 -6
- package/dist/cli.js +58 -3
- package/dist/evidence.js +1 -1
- package/dist/flow.js +37 -3
- package/dist/grants.d.ts +18 -0
- package/dist/grants.js +131 -0
- package/dist/permissive.js +406 -18
- package/dist/policy.d.ts +2 -0
- package/dist/policy.js +1 -1
- package/dist/service.d.ts +7 -2
- package/dist/service.js +17 -5
- package/dist/session.d.ts +56 -1
- package/dist/session.js +189 -4
- package/dist/types.d.ts +4 -0
- package/package.json +1 -1
package/dist/session.d.ts
CHANGED
|
@@ -2,11 +2,30 @@ import { type Profile } from "./profile.js";
|
|
|
2
2
|
import { type Classification, type Decision, type OutcomeReport, type Request } from "./types.js";
|
|
3
3
|
/** AI approvals per session; beyond this, ambiguous requests go to a human. */
|
|
4
4
|
export declare const MAX_AI_APPROVALS = 50;
|
|
5
|
+
export declare const APPROVE_GUARD = "Only the user may approve a request, by running approve in their own terminal";
|
|
6
|
+
/** How long after a human decision the user may still approve that exact request once. */
|
|
7
|
+
export declare const GRANT_WINDOW_MS: number;
|
|
8
|
+
/** What `approve` shows the user before a one-time grant: the request a person must decide. */
|
|
9
|
+
export interface GrantPreview {
|
|
10
|
+
requestHash: string;
|
|
11
|
+
tool: string;
|
|
12
|
+
category: Decision["category"];
|
|
13
|
+
reason: string;
|
|
14
|
+
/** Redacted command or target, for the user to recognize the request. */
|
|
15
|
+
detail: string;
|
|
16
|
+
/** What a session approval would cover, when this request can be approved for the session. */
|
|
17
|
+
sessionScope?: string;
|
|
18
|
+
}
|
|
19
|
+
/** A grant the service refuses; its message is safe to show the user. */
|
|
20
|
+
export declare class GrantError extends Error {
|
|
21
|
+
}
|
|
5
22
|
export declare class PolicySession {
|
|
6
23
|
readonly directory: string;
|
|
7
24
|
readonly harness: string;
|
|
8
25
|
readonly sessionId: string;
|
|
9
26
|
readonly profile: Profile;
|
|
27
|
+
/** This package's `cli.js`: the path in the record command the hook gives the model. */
|
|
28
|
+
readonly cliPath?: string | undefined;
|
|
10
29
|
private cache;
|
|
11
30
|
private pending;
|
|
12
31
|
private states;
|
|
@@ -15,7 +34,43 @@ export declare class PolicySession {
|
|
|
15
34
|
/** Files this session created, and the paths each approved request may create. */
|
|
16
35
|
private created;
|
|
17
36
|
private creating;
|
|
18
|
-
|
|
37
|
+
/** Requests this session sent to a person, which the user may approve once. */
|
|
38
|
+
private humanDecisions;
|
|
39
|
+
/** One-time user approvals, each usable once per hook phase. */
|
|
40
|
+
private grants;
|
|
41
|
+
/** Session grants: hashes of a human rule and the scope the user approved it for. */
|
|
42
|
+
private sessionGrants;
|
|
43
|
+
constructor(directory: string, harness: string, sessionId: string, profile?: Profile,
|
|
44
|
+
/** This package's `cli.js`: the path in the record command the hook gives the model. */
|
|
45
|
+
cliPath?: string | undefined);
|
|
46
|
+
/**
|
|
47
|
+
* The record command the hook gives this session is approved before the policy runs: the
|
|
48
|
+
* engine cannot always verify an installed CLI outside the repository or a here-string (strict
|
|
49
|
+
* mode never can), so the round trip could not finish. Any other classification record, for
|
|
50
|
+
* another session or CLI or with anything added, goes to a person.
|
|
51
|
+
*/
|
|
52
|
+
private classifyRecord;
|
|
53
|
+
/**
|
|
54
|
+
* Only the user approves a request once, from their own terminal. A shell command that runs a
|
|
55
|
+
* policy-manager `approve`, in any form or nesting, is never approved for the agent.
|
|
56
|
+
*/
|
|
57
|
+
private approveGrant;
|
|
58
|
+
/**
|
|
59
|
+
* A user approval that covers this human decision: a one-time grant for this exact request
|
|
60
|
+
* (used once per hook phase), or a session grant for its rule and scope. Each use is audited.
|
|
61
|
+
*/
|
|
62
|
+
private granted;
|
|
63
|
+
/**
|
|
64
|
+
* Looks up, and with `confirm` grants, a user approval of a request this session sent to a
|
|
65
|
+
* person within the last GRANT_WINDOW_MS. Without `session` the next review of that exact
|
|
66
|
+
* request is approved once per hook phase; with it, every later request in this session that
|
|
67
|
+
* hits the same rule for the same scope is approved. A request with no session scope (credential
|
|
68
|
+
* reads, possible unrecoverable loss) is approved once only, and the result says so.
|
|
69
|
+
*/
|
|
70
|
+
grant(requestHash: string, confirm: boolean, session?: boolean): GrantPreview & {
|
|
71
|
+
granted: boolean;
|
|
72
|
+
scope: "once" | "session";
|
|
73
|
+
};
|
|
19
74
|
private state;
|
|
20
75
|
private remember;
|
|
21
76
|
/**
|
package/dist/session.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
+
import { isClassifyRecord, looksLikeApproveGrant, looksLikeClassifyRecord } from "./adapters.js";
|
|
1
2
|
import { audit, requestSummary } from "./audit.js";
|
|
2
3
|
import { creationTargets, pathKey, settle, withCreated, } from "./created.js";
|
|
3
|
-
import {
|
|
4
|
+
import { grantScope, scopeLabel } from "./grants.js";
|
|
5
|
+
import { evaluate, hash, requestHash as requestHashOf, result, SHELL_TOOLS } from "./policy.js";
|
|
4
6
|
import { strictProfile } from "./profile.js";
|
|
5
7
|
import { redactText } from "./redact.js";
|
|
6
8
|
import { CATEGORIES, } from "./types.js";
|
|
@@ -10,11 +12,32 @@ const CLASSIFICATION_TTL_MS = 5 * 60_000;
|
|
|
10
12
|
export const MAX_AI_APPROVALS = 50;
|
|
11
13
|
/** How long after its approval an execution report may still record the files a tool created. */
|
|
12
14
|
const CREATION_REPORT_MS = 15 * 60_000;
|
|
15
|
+
export const APPROVE_GUARD = "Only the user may approve a request, by running approve in their own terminal";
|
|
16
|
+
/** How long after a human decision the user may still approve that exact request once. */
|
|
17
|
+
export const GRANT_WINDOW_MS = 15 * 60_000;
|
|
18
|
+
/** A grant the service refuses; its message is safe to show the user. */
|
|
19
|
+
export class GrantError extends Error {
|
|
20
|
+
}
|
|
21
|
+
function grantDetail(request) {
|
|
22
|
+
const command = request.input.command ?? request.input.cmd;
|
|
23
|
+
if (typeof command === "string")
|
|
24
|
+
return redactText(command, 300);
|
|
25
|
+
const file = request.input.file_path ?? request.input.path;
|
|
26
|
+
if (typeof file === "string")
|
|
27
|
+
return redactText(file, 300);
|
|
28
|
+
if (typeof request.input.patch === "string" || typeof request.input.input === "string")
|
|
29
|
+
return redactText(String(request.input.patch ?? request.input.input)
|
|
30
|
+
.split("\n")
|
|
31
|
+
.filter((line) => /^\*\*\* (?:Add|Update|Delete) File:/.test(line))
|
|
32
|
+
.join("; "), 300);
|
|
33
|
+
return request.tool;
|
|
34
|
+
}
|
|
13
35
|
export class PolicySession {
|
|
14
36
|
directory;
|
|
15
37
|
harness;
|
|
16
38
|
sessionId;
|
|
17
39
|
profile;
|
|
40
|
+
cliPath;
|
|
18
41
|
cache = new Map();
|
|
19
42
|
pending = new Map();
|
|
20
43
|
states = new Map();
|
|
@@ -23,11 +46,147 @@ export class PolicySession {
|
|
|
23
46
|
/** Files this session created, and the paths each approved request may create. */
|
|
24
47
|
created = new Map();
|
|
25
48
|
creating = new Map();
|
|
26
|
-
|
|
49
|
+
/** Requests this session sent to a person, which the user may approve once. */
|
|
50
|
+
humanDecisions = new Map();
|
|
51
|
+
/** One-time user approvals, each usable once per hook phase. */
|
|
52
|
+
grants = new Map();
|
|
53
|
+
/** Session grants: hashes of a human rule and the scope the user approved it for. */
|
|
54
|
+
sessionGrants = new Set();
|
|
55
|
+
constructor(directory, harness, sessionId, profile = strictProfile,
|
|
56
|
+
/** This package's `cli.js`: the path in the record command the hook gives the model. */
|
|
57
|
+
cliPath) {
|
|
27
58
|
this.directory = directory;
|
|
28
59
|
this.harness = harness;
|
|
29
60
|
this.sessionId = sessionId;
|
|
30
61
|
this.profile = profile;
|
|
62
|
+
this.cliPath = cliPath;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The record command the hook gives this session is approved before the policy runs: the
|
|
66
|
+
* engine cannot always verify an installed CLI outside the repository or a here-string (strict
|
|
67
|
+
* mode never can), so the round trip could not finish. Any other classification record, for
|
|
68
|
+
* another session or CLI or with anything added, goes to a person.
|
|
69
|
+
*/
|
|
70
|
+
classifyRecord(request) {
|
|
71
|
+
const input = request.input;
|
|
72
|
+
const command = input.command ?? input.cmd;
|
|
73
|
+
if (!SHELL_TOOLS.has(request.tool) ||
|
|
74
|
+
typeof command !== "string" ||
|
|
75
|
+
!looksLikeClassifyRecord(command))
|
|
76
|
+
return undefined;
|
|
77
|
+
const cwd = input.workdir ?? input.cwd ?? request.cwd;
|
|
78
|
+
if (this.cliPath &&
|
|
79
|
+
cwd === request.cwd &&
|
|
80
|
+
input.env === undefined &&
|
|
81
|
+
input.shell === undefined &&
|
|
82
|
+
input.stdin === undefined &&
|
|
83
|
+
isClassifyRecord(command, request.harness, {
|
|
84
|
+
cliPath: this.cliPath,
|
|
85
|
+
sessionId: this.sessionId,
|
|
86
|
+
}))
|
|
87
|
+
return result(request, "temp-write", "Records a classification for this session", true);
|
|
88
|
+
return result(request, "unknown", "A classification record for another session or CLI, or with anything added, requires human review");
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Only the user approves a request once, from their own terminal. A shell command that runs a
|
|
92
|
+
* policy-manager `approve`, in any form or nesting, is never approved for the agent.
|
|
93
|
+
*/
|
|
94
|
+
approveGrant(request) {
|
|
95
|
+
const command = request.input.command ?? request.input.cmd;
|
|
96
|
+
if (!SHELL_TOOLS.has(request.tool) || typeof command !== "string")
|
|
97
|
+
return undefined;
|
|
98
|
+
if (!looksLikeApproveGrant(command))
|
|
99
|
+
return undefined;
|
|
100
|
+
return result(request, "sensitive", APPROVE_GUARD);
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* A user approval that covers this human decision: a one-time grant for this exact request
|
|
104
|
+
* (used once per hook phase), or a session grant for its rule and scope. Each use is audited.
|
|
105
|
+
*/
|
|
106
|
+
granted(request, decision, phase) {
|
|
107
|
+
const once = this.grants.get(decision.requestHash);
|
|
108
|
+
const slot = phase ?? "review";
|
|
109
|
+
if (once && !once.phases.has(slot)) {
|
|
110
|
+
once.phases.add(slot);
|
|
111
|
+
// PreToolUse runs before PermissionRequest; once both have allowed the tool, it is spent.
|
|
112
|
+
if (once.phases.has("PreToolUse") && once.phases.has("PermissionRequest"))
|
|
113
|
+
this.grants.delete(decision.requestHash);
|
|
114
|
+
audit(this.directory, {
|
|
115
|
+
event: "human-grant-use",
|
|
116
|
+
requestHash: decision.requestHash,
|
|
117
|
+
scope: "once",
|
|
118
|
+
phase: slot,
|
|
119
|
+
});
|
|
120
|
+
return { ...result(request, decision.category, "Approved once by the user", true) };
|
|
121
|
+
}
|
|
122
|
+
const scope = grantScope(request, decision, this.profile);
|
|
123
|
+
if (scope === undefined)
|
|
124
|
+
return undefined;
|
|
125
|
+
const key = hash([decision.reason, scope]);
|
|
126
|
+
if (!this.sessionGrants.has(key))
|
|
127
|
+
return undefined;
|
|
128
|
+
audit(this.directory, {
|
|
129
|
+
event: "human-grant-use",
|
|
130
|
+
requestHash: decision.requestHash,
|
|
131
|
+
scope: "session",
|
|
132
|
+
scopeHash: key,
|
|
133
|
+
phase: slot,
|
|
134
|
+
});
|
|
135
|
+
return {
|
|
136
|
+
...result(request, decision.category, "Approved for this session by the user", true),
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Looks up, and with `confirm` grants, a user approval of a request this session sent to a
|
|
141
|
+
* person within the last GRANT_WINDOW_MS. Without `session` the next review of that exact
|
|
142
|
+
* request is approved once per hook phase; with it, every later request in this session that
|
|
143
|
+
* hits the same rule for the same scope is approved. A request with no session scope (credential
|
|
144
|
+
* reads, possible unrecoverable loss) is approved once only, and the result says so.
|
|
145
|
+
*/
|
|
146
|
+
grant(requestHash, confirm, session = false) {
|
|
147
|
+
if (!/^[a-f0-9]{64}$/.test(requestHash))
|
|
148
|
+
throw new GrantError("Not a request hash");
|
|
149
|
+
const pending = this.humanDecisions.get(requestHash);
|
|
150
|
+
if (!pending || Date.now() - pending.at > GRANT_WINDOW_MS) {
|
|
151
|
+
this.humanDecisions.delete(requestHash);
|
|
152
|
+
throw new GrantError("No request in this session needed a person with that hash in the last 15 minutes. Retry the request so it is blocked again, then approve the new hash.");
|
|
153
|
+
}
|
|
154
|
+
const { at: _at, sessionScope, ...rest } = pending;
|
|
155
|
+
const scope = session && sessionScope !== undefined ? "session" : "once";
|
|
156
|
+
const preview = {
|
|
157
|
+
...rest,
|
|
158
|
+
...(scope === "session" && sessionScope !== undefined
|
|
159
|
+
? { sessionScope: scopeLabel(sessionScope, this.profile) }
|
|
160
|
+
: {}),
|
|
161
|
+
};
|
|
162
|
+
if (!confirm)
|
|
163
|
+
return { ...preview, granted: false, scope };
|
|
164
|
+
this.humanDecisions.delete(requestHash);
|
|
165
|
+
if (scope === "session" && sessionScope !== undefined) {
|
|
166
|
+
if (this.sessionGrants.size >= 64)
|
|
167
|
+
this.sessionGrants.clear();
|
|
168
|
+
this.sessionGrants.add(hash([preview.reason, sessionScope]));
|
|
169
|
+
}
|
|
170
|
+
if (this.grants.size >= 64)
|
|
171
|
+
this.grants.delete(this.grants.keys().next().value ?? "");
|
|
172
|
+
this.grants.set(requestHash, { phases: new Set() });
|
|
173
|
+
audit(this.directory, {
|
|
174
|
+
event: "human-grant",
|
|
175
|
+
requestHash,
|
|
176
|
+
category: preview.category,
|
|
177
|
+
scope,
|
|
178
|
+
...(scope === "session" ? { scopeHash: hash([preview.reason, sessionScope]) } : {}),
|
|
179
|
+
summary: scope === "session"
|
|
180
|
+
? "User approved the rule for this session"
|
|
181
|
+
: "User approved the request once",
|
|
182
|
+
});
|
|
183
|
+
audit(this.directory, {
|
|
184
|
+
event: "human-response",
|
|
185
|
+
requestHash,
|
|
186
|
+
response: "approved",
|
|
187
|
+
summary: "User approved the request from the terminal",
|
|
188
|
+
});
|
|
189
|
+
return { ...preview, granted: true, scope };
|
|
31
190
|
}
|
|
32
191
|
state(requestHash) {
|
|
33
192
|
const state = this.states.get(requestHash);
|
|
@@ -93,7 +252,9 @@ export class PolicySession {
|
|
|
93
252
|
...(ai.recoverable === undefined ? {} : { recoverable: ai.recoverable }),
|
|
94
253
|
...(ai.rationale ? { rationale: redactText(ai.rationale, 200) } : {}),
|
|
95
254
|
});
|
|
96
|
-
let decision =
|
|
255
|
+
let decision = this.approveGrant(request) ??
|
|
256
|
+
this.classifyRecord(request) ??
|
|
257
|
+
withCreated(this.created, () => evaluate(request, ai ?? cachedAi ?? known?.ai, this.profile));
|
|
97
258
|
if (decision.tier === "ambiguous") {
|
|
98
259
|
if (ai && !decision.classification)
|
|
99
260
|
this.remember(requestHash, { invalid: true });
|
|
@@ -148,8 +309,32 @@ export class PolicySession {
|
|
|
148
309
|
}
|
|
149
310
|
}
|
|
150
311
|
}
|
|
151
|
-
if (decision.decision === "human")
|
|
312
|
+
if (decision.decision === "human") {
|
|
313
|
+
const allowed = this.granted(request, decision, phase);
|
|
314
|
+
if (allowed)
|
|
315
|
+
decision = allowed;
|
|
316
|
+
}
|
|
317
|
+
if (decision.decision === "human" && decision.reason === APPROVE_GUARD) {
|
|
152
318
|
this.cache.delete(key);
|
|
319
|
+
decision = { ...decision, userOnly: true, sessionGrantable: false };
|
|
320
|
+
}
|
|
321
|
+
else if (decision.decision === "human") {
|
|
322
|
+
this.cache.delete(key);
|
|
323
|
+
const sessionScope = grantScope(request, decision, this.profile);
|
|
324
|
+
decision = { ...decision, sessionGrantable: sessionScope !== undefined };
|
|
325
|
+
if (this.humanDecisions.size >= 256)
|
|
326
|
+
this.humanDecisions.delete(this.humanDecisions.keys().next().value ?? "");
|
|
327
|
+
this.humanDecisions.delete(requestHash);
|
|
328
|
+
this.humanDecisions.set(requestHash, {
|
|
329
|
+
requestHash,
|
|
330
|
+
tool: request.tool,
|
|
331
|
+
category: decision.category,
|
|
332
|
+
reason: decision.reason,
|
|
333
|
+
detail: grantDetail(request),
|
|
334
|
+
at: Date.now(),
|
|
335
|
+
...(sessionScope === undefined ? {} : { sessionScope }),
|
|
336
|
+
});
|
|
337
|
+
}
|
|
153
338
|
// Evaluation always precedes lookup. Filesystem evidence is never cached.
|
|
154
339
|
if (decision.decision === "approve" && decision.cache === "session") {
|
|
155
340
|
decision.cached = entry !== undefined && entry.expires > Date.now() && ai === undefined;
|
package/dist/types.d.ts
CHANGED
|
@@ -38,6 +38,10 @@ export interface Decision {
|
|
|
38
38
|
/** Why a human was asked after classification could not decide. */
|
|
39
39
|
fallbackReason?: "unavailable" | "invalid-result" | "limit";
|
|
40
40
|
ai?: Classification;
|
|
41
|
+
/** A human decision the user may approve for the rest of the session (`approve --session`). */
|
|
42
|
+
sessionGrantable?: boolean;
|
|
43
|
+
/** The agent tried to approve a request itself: no approval instruction is offered for it. */
|
|
44
|
+
userOnly?: boolean;
|
|
41
45
|
}
|
|
42
46
|
export interface OutcomeReport {
|
|
43
47
|
requestHash: string;
|
package/package.json
CHANGED