@vorim/sdk 3.18.1 → 3.19.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/dist/index.cjs +1 -1
- package/dist/index.d.cts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/integrations/anthropic.d.cts +1 -1
- package/dist/integrations/anthropic.d.ts +1 -1
- package/dist/integrations/ap2.d.cts +1 -1
- package/dist/integrations/ap2.d.ts +1 -1
- package/dist/integrations/aws-iam.d.cts +1 -1
- package/dist/integrations/aws-iam.d.ts +1 -1
- package/dist/integrations/bank-rails.d.cts +1 -1
- package/dist/integrations/bank-rails.d.ts +1 -1
- package/dist/integrations/circle.d.cts +1 -1
- package/dist/integrations/circle.d.ts +1 -1
- package/dist/integrations/cloudflare.d.cts +1 -1
- package/dist/integrations/cloudflare.d.ts +1 -1
- package/dist/integrations/coinbase-cdp.d.cts +1 -1
- package/dist/integrations/coinbase-cdp.d.ts +1 -1
- package/dist/integrations/crewai.d.cts +1 -1
- package/dist/integrations/crewai.d.ts +1 -1
- package/dist/integrations/entra.d.cts +1 -1
- package/dist/integrations/entra.d.ts +1 -1
- package/dist/integrations/fhir.d.cts +1 -1
- package/dist/integrations/fhir.d.ts +1 -1
- package/dist/integrations/grok.d.cts +1 -1
- package/dist/integrations/grok.d.ts +1 -1
- package/dist/integrations/guidewire.d.cts +1 -1
- package/dist/integrations/guidewire.d.ts +1 -1
- package/dist/integrations/hermes.d.cts +1 -1
- package/dist/integrations/hermes.d.ts +1 -1
- package/dist/integrations/jira.cjs +190 -0
- package/dist/integrations/jira.cjs.map +1 -0
- package/dist/integrations/jira.d.cts +162 -0
- package/dist/integrations/jira.d.ts +162 -0
- package/dist/integrations/jira.js +164 -0
- package/dist/integrations/jira.js.map +1 -0
- package/dist/integrations/langchain.d.cts +1 -1
- package/dist/integrations/langchain.d.ts +1 -1
- package/dist/integrations/langgraph.d.cts +1 -1
- package/dist/integrations/langgraph.d.ts +1 -1
- package/dist/integrations/legal.d.cts +1 -1
- package/dist/integrations/legal.d.ts +1 -1
- package/dist/integrations/life-sciences.d.cts +1 -1
- package/dist/integrations/life-sciences.d.ts +1 -1
- package/dist/integrations/linear.cjs +193 -0
- package/dist/integrations/linear.cjs.map +1 -0
- package/dist/integrations/linear.d.cts +173 -0
- package/dist/integrations/linear.d.ts +173 -0
- package/dist/integrations/linear.js +167 -0
- package/dist/integrations/linear.js.map +1 -0
- package/dist/integrations/lithic.d.cts +1 -1
- package/dist/integrations/lithic.d.ts +1 -1
- package/dist/integrations/llamaindex.d.cts +1 -1
- package/dist/integrations/llamaindex.d.ts +1 -1
- package/dist/integrations/marqeta.d.cts +1 -1
- package/dist/integrations/marqeta.d.ts +1 -1
- package/dist/integrations/modern-treasury.d.cts +1 -1
- package/dist/integrations/modern-treasury.d.ts +1 -1
- package/dist/integrations/nekuda.d.cts +1 -1
- package/dist/integrations/nekuda.d.ts +1 -1
- package/dist/integrations/okta.d.cts +1 -1
- package/dist/integrations/okta.d.ts +1 -1
- package/dist/integrations/openai.d.cts +1 -1
- package/dist/integrations/openai.d.ts +1 -1
- package/dist/integrations/openrouter.cjs +1 -1
- package/dist/integrations/openrouter.cjs.map +1 -1
- package/dist/integrations/openrouter.d.cts +5 -5
- package/dist/integrations/openrouter.d.ts +5 -5
- package/dist/integrations/openrouter.js +1 -1
- package/dist/integrations/openrouter.js.map +1 -1
- package/dist/integrations/paypal-agent.d.cts +1 -1
- package/dist/integrations/paypal-agent.d.ts +1 -1
- package/dist/integrations/perplexity.cjs +430 -0
- package/dist/integrations/perplexity.cjs.map +1 -0
- package/dist/integrations/perplexity.d.cts +65 -0
- package/dist/integrations/perplexity.d.ts +65 -0
- package/dist/integrations/perplexity.js +388 -0
- package/dist/integrations/perplexity.js.map +1 -0
- package/dist/integrations/plaid.d.cts +1 -1
- package/dist/integrations/plaid.d.ts +1 -1
- package/dist/integrations/ramp.d.cts +1 -1
- package/dist/integrations/ramp.d.ts +1 -1
- package/dist/integrations/shopify.d.cts +1 -1
- package/dist/integrations/shopify.d.ts +1 -1
- package/dist/integrations/siem.d.cts +1 -1
- package/dist/integrations/siem.d.ts +1 -1
- package/dist/integrations/skyfire.d.cts +1 -1
- package/dist/integrations/skyfire.d.ts +1 -1
- package/dist/integrations/stripe-acp.d.cts +1 -1
- package/dist/integrations/stripe-acp.d.ts +1 -1
- package/dist/integrations/stripe-issuing.d.cts +1 -1
- package/dist/integrations/stripe-issuing.d.ts +1 -1
- package/dist/integrations/truanon.d.cts +1 -1
- package/dist/integrations/truanon.d.ts +1 -1
- package/dist/integrations/ucp.d.cts +1 -1
- package/dist/integrations/ucp.d.ts +1 -1
- package/dist/integrations/vercel-ai.d.cts +1 -1
- package/dist/integrations/vercel-ai.d.ts +1 -1
- package/dist/integrations/x402.d.cts +1 -1
- package/dist/integrations/x402.d.ts +1 -1
- package/dist/{types-Lp1iHEDz.d.cts → types-BmeluKHI.d.cts} +1 -1
- package/dist/{types-Lp1iHEDz.d.ts → types-BmeluKHI.d.ts} +1 -1
- package/package.json +31 -1
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/integrations/linear.ts
|
|
21
|
+
var linear_exports = {};
|
|
22
|
+
__export(linear_exports, {
|
|
23
|
+
VorimLinear: () => VorimLinear,
|
|
24
|
+
createVorimLinear: () => createVorimLinear
|
|
25
|
+
});
|
|
26
|
+
module.exports = __toCommonJS(linear_exports);
|
|
27
|
+
var OPERATION_SCOPE = {
|
|
28
|
+
read: "agent:read",
|
|
29
|
+
issueCreate: "agent:write",
|
|
30
|
+
issueUpdate: "agent:write",
|
|
31
|
+
issueDelete: "agent:write",
|
|
32
|
+
issueArchive: "agent:write",
|
|
33
|
+
projectUpdate: "agent:write",
|
|
34
|
+
issueBatchUpdate: "agent:write",
|
|
35
|
+
commentCreate: "agent:communicate"
|
|
36
|
+
};
|
|
37
|
+
var VorimLinear = class {
|
|
38
|
+
sdk;
|
|
39
|
+
agentId;
|
|
40
|
+
workspaceKey;
|
|
41
|
+
humanId;
|
|
42
|
+
minTrustScore;
|
|
43
|
+
onError;
|
|
44
|
+
constructor(sdk, config) {
|
|
45
|
+
if (!config?.agentId) throw new Error("[vorim] Linear integration requires an agentId.");
|
|
46
|
+
if (!config?.workspaceKey) throw new Error("[vorim] Linear integration requires a workspaceKey.");
|
|
47
|
+
this.sdk = sdk;
|
|
48
|
+
this.agentId = config.agentId;
|
|
49
|
+
this.workspaceKey = config.workspaceKey;
|
|
50
|
+
this.humanId = config.humanId;
|
|
51
|
+
this.minTrustScore = config.minTrustScore ?? 0;
|
|
52
|
+
this.onError = config.onError ?? "closed";
|
|
53
|
+
}
|
|
54
|
+
/** The Vorim scope a given operation requires. Unknown mutations fall back to
|
|
55
|
+
* agent:write (a mutation is at least a write). */
|
|
56
|
+
scopeFor(operation) {
|
|
57
|
+
return OPERATION_SCOPE[operation] ?? "agent:write";
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Check whether the acting agent may run this workspace operation, before it
|
|
61
|
+
* runs. Enforces (in order): trust floor, permission scope. Returns
|
|
62
|
+
* { authorized, reason }.
|
|
63
|
+
*/
|
|
64
|
+
async authorize(action) {
|
|
65
|
+
const scope = this.scopeFor(action.operation);
|
|
66
|
+
try {
|
|
67
|
+
if (this.minTrustScore > 0) {
|
|
68
|
+
const trust = await this.sdk.verify(this.agentId);
|
|
69
|
+
if ((trust?.trust_score ?? 0) < this.minTrustScore) {
|
|
70
|
+
return { authorized: false, reason: `trust score below ${this.minTrustScore}` };
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
const perm = await this.sdk.check(this.agentId, scope);
|
|
74
|
+
return perm.allowed ? { authorized: true } : { authorized: false, reason: perm.reason ?? `missing scope ${scope}` };
|
|
75
|
+
} catch (e) {
|
|
76
|
+
return this.onError === "open" ? { authorized: true, reason: "vorim unreachable, failed open" } : { authorized: false, reason: `vorim unreachable: ${e?.message ?? "error"}` };
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Emit a source-signed audit event for a workspace operation and return
|
|
81
|
+
* whether it was recorded. Called after the mutation runs (or after a
|
|
82
|
+
* denial). The event names the agent, the workspace, and the human the agent
|
|
83
|
+
* acts for, so the record is attributable and independently verifiable
|
|
84
|
+
* offline.
|
|
85
|
+
*/
|
|
86
|
+
async record(action, result, reason) {
|
|
87
|
+
const scope = this.scopeFor(action.operation);
|
|
88
|
+
try {
|
|
89
|
+
await this.sdk.emit({
|
|
90
|
+
agent_id: this.agentId,
|
|
91
|
+
event_type: "api_request",
|
|
92
|
+
action: `linear:${action.operation}${action.resourceId ? " " + action.resourceId : ""}`,
|
|
93
|
+
resource: action.resourceId || this.workspaceKey,
|
|
94
|
+
permission: scope,
|
|
95
|
+
result,
|
|
96
|
+
input_hash: action.inputHash,
|
|
97
|
+
metadata: {
|
|
98
|
+
integration: "linear",
|
|
99
|
+
workspace: this.workspaceKey,
|
|
100
|
+
acts_for_human: this.humanId,
|
|
101
|
+
operation: action.operation,
|
|
102
|
+
...reason ? { reason } : {}
|
|
103
|
+
}
|
|
104
|
+
}, { sign: true });
|
|
105
|
+
return true;
|
|
106
|
+
} catch {
|
|
107
|
+
return false;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* The full flow for one workspace operation: authorize, run the Linear
|
|
112
|
+
* GraphQL mutation if allowed, sign a receipt either way. If not authorized,
|
|
113
|
+
* `run` is never called (the mutation does not happen). Rethrows an error from
|
|
114
|
+
* `run` after recording it, with the receipt attached as `vorimReceipt`, so
|
|
115
|
+
* your handler still sees Linear failures.
|
|
116
|
+
*/
|
|
117
|
+
async guard(action, run) {
|
|
118
|
+
const auth = await this.authorize(action);
|
|
119
|
+
if (!auth.authorized) {
|
|
120
|
+
const recorded = await this.record(action, "denied", auth.reason);
|
|
121
|
+
return { receipt: this.receipt(action, false, "denied", auth.reason, recorded) };
|
|
122
|
+
}
|
|
123
|
+
try {
|
|
124
|
+
const value = await run();
|
|
125
|
+
const recorded = await this.record(action, "success");
|
|
126
|
+
return { receipt: this.receipt(action, true, "success", void 0, recorded), value };
|
|
127
|
+
} catch (e) {
|
|
128
|
+
const recorded = await this.record(action, "error", e?.message);
|
|
129
|
+
throw Object.assign(e ?? new Error("linear operation failed"), {
|
|
130
|
+
vorimReceipt: this.receipt(action, true, "error", e?.message, recorded)
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
// --- Named helpers for the Linear mutations --------------------------------
|
|
135
|
+
// Each wraps guard() with the right operation label so the scope and receipt
|
|
136
|
+
// are correct without the caller having to remember the mapping. You pass the
|
|
137
|
+
// GraphQL call as `run`; this layer never talks to Linear itself.
|
|
138
|
+
/** Guard an `issueCreate`. Requires agent:write. */
|
|
139
|
+
issueCreate(meta, run) {
|
|
140
|
+
return this.guard({ operation: "issueCreate", resourceId: meta.issueId, inputHash: meta.inputHash }, run);
|
|
141
|
+
}
|
|
142
|
+
/** Guard an `issueUpdate` (edit or state transition). Requires agent:write. */
|
|
143
|
+
issueUpdate(meta, run) {
|
|
144
|
+
return this.guard({ operation: "issueUpdate", resourceId: meta.issueId, inputHash: meta.inputHash }, run);
|
|
145
|
+
}
|
|
146
|
+
/** Guard an `issueDelete`. Requires agent:write. DESTRUCTIVE — it removes an
|
|
147
|
+
* issue rather than editing it; consider a higher trust floor. */
|
|
148
|
+
issueDelete(meta, run) {
|
|
149
|
+
return this.guard({ operation: "issueDelete", resourceId: meta.issueId, inputHash: meta.inputHash }, run);
|
|
150
|
+
}
|
|
151
|
+
/** Guard a `commentCreate`. Requires agent:communicate — an agent posting a
|
|
152
|
+
* comment is communication, not just a data write. */
|
|
153
|
+
commentCreate(meta, run) {
|
|
154
|
+
return this.guard({ operation: "commentCreate", resourceId: meta.issueId, inputHash: meta.inputHash }, run);
|
|
155
|
+
}
|
|
156
|
+
/** Guard an `issueArchive`. Requires agent:write. */
|
|
157
|
+
issueArchive(meta, run) {
|
|
158
|
+
return this.guard({ operation: "issueArchive", resourceId: meta.issueId, inputHash: meta.inputHash }, run);
|
|
159
|
+
}
|
|
160
|
+
/** Guard a `projectUpdate`. Requires agent:write. */
|
|
161
|
+
projectUpdate(meta, run) {
|
|
162
|
+
return this.guard({ operation: "projectUpdate", resourceId: meta.projectId, inputHash: meta.inputHash }, run);
|
|
163
|
+
}
|
|
164
|
+
/** Guard an `issueBatchUpdate`. Requires agent:write. BULK — one call can
|
|
165
|
+
* rewrite many issues at once (higher blast radius); consider a higher trust
|
|
166
|
+
* floor or a tighter grant. */
|
|
167
|
+
issueBatchUpdate(meta, run) {
|
|
168
|
+
return this.guard({ operation: "issueBatchUpdate", resourceId: meta.resourceId, inputHash: meta.inputHash }, run);
|
|
169
|
+
}
|
|
170
|
+
receipt(action, authorized, result, reason, recorded) {
|
|
171
|
+
return {
|
|
172
|
+
authorized,
|
|
173
|
+
agentId: this.agentId,
|
|
174
|
+
humanId: this.humanId,
|
|
175
|
+
workspace: this.workspaceKey,
|
|
176
|
+
operation: action.operation,
|
|
177
|
+
resourceId: action.resourceId,
|
|
178
|
+
result,
|
|
179
|
+
scope: this.scopeFor(action.operation),
|
|
180
|
+
reason,
|
|
181
|
+
recorded
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
};
|
|
185
|
+
function createVorimLinear(sdk, config) {
|
|
186
|
+
return new VorimLinear(sdk, config);
|
|
187
|
+
}
|
|
188
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
189
|
+
0 && (module.exports = {
|
|
190
|
+
VorimLinear,
|
|
191
|
+
createVorimLinear
|
|
192
|
+
});
|
|
193
|
+
//# sourceMappingURL=linear.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/integrations/linear.ts"],"sourcesContent":["// ============================================================================\n// Vorim AI — Linear (issue-tracker mutation guard) Integration\n//\n// This guards an AI agent that WORKS a Linear workspace through the Linear\n// GraphQL API — creating and updating issues, transitioning and archiving them,\n// commenting, editing projects, and running bulk issue changes. Before each\n// mutation runs it checks the acting agent holds the right permission, then\n// signs a tamper-evident audit record of what the agent did.\n//\n// WHY A GUARD ON LINEAR\n// On Linear's GraphQL API an agent authenticates with a single API key or OAuth\n// token and coarse scopes: every agent on that token looks identical, there is\n// no way to cap a sub-agent below \"write\", and nothing proves agent X (not\n// agent Y) ran a given issueDelete or issueBatchUpdate. That is the gap this\n// fills. It sits BESIDE Linear's own auth rather than replacing it: Linear still\n// authenticates the token; Vorim proves which agent, acting for which human,\n// ran which mutation — and signs a record you can verify offline.\n//\n// SCOPE MAPPING (uses Vorim's real scopes)\n// read workspace data -> agent:read\n// mutate the workspace -> agent:write (issueCreate, issueUpdate,\n// issueDelete, issueArchive,\n// projectUpdate, issueBatchUpdate)\n// post a comment -> agent:communicate (an agent commenting is\n// communication, not just\n// a data write)\n//\n// Two operations carry more blast radius and are called out below:\n// - issueDelete destructive: it removes an issue, not just edits it.\n// - issueBatchUpdate bulk: one call can rewrite many issues at once.\n// Both still map to agent:write here; gate them with a higher trust floor or a\n// tighter permission grant if you want them held to a stricter bar.\n//\n// This layer never holds a Linear token and never calls Linear itself. You pass\n// it the mutation to run; it authorizes, runs it, and signs the receipt.\n//\n// Usage:\n// import createVorim from '@vorim/sdk';\n// import { createVorimLinear } from '@vorim/sdk/integrations/linear';\n//\n// const vorim = createVorim({ apiKey: 'agid_sk_...' });\n// const linear = createVorimLinear(vorim, {\n// agentId: 'agid_abc123',\n// workspaceKey: 'acme', // the workspace URL key / slug\n// humanId: 'user_42', // the person the agent acts for\n// minTrustScore: 60, // optional trust floor\n// });\n//\n// // Wrap the Linear GraphQL call you were going to make anyway:\n// const { receipt, value } = await linear.issueUpdate(\n// { issueId: 'ISS-123', inputHash },\n// () => linearClient.updateIssue('ISS-123', { stateId }),\n// );\n// if (!receipt.authorized) console.warn(receipt.reason);\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { PermissionScope } from '../types.js';\n\n/** The Linear GraphQL mutations this guard knows how to classify. Any other\n * label is accepted too; it just defaults to the 'write' risk tier. */\nexport type LinearOperation =\n | 'issueCreate'\n | 'issueUpdate'\n | 'issueDelete'\n | 'commentCreate'\n | 'issueArchive'\n | 'projectUpdate'\n | 'issueBatchUpdate'\n | 'read';\n\n/** Map each Linear mutation to the least Vorim scope that should be required to\n * run it. Reads need read; workspace mutations need write; an agent posting a\n * comment needs communicate, the scope Vorim requires for any agent-authored\n * message. issueDelete (destructive) and issueBatchUpdate (bulk) still map to\n * write here — hold them to a stricter bar via minTrustScore or the grant. */\nconst OPERATION_SCOPE: Record<string, PermissionScope> = {\n read: 'agent:read',\n issueCreate: 'agent:write',\n issueUpdate: 'agent:write',\n issueDelete: 'agent:write',\n issueArchive: 'agent:write',\n projectUpdate: 'agent:write',\n issueBatchUpdate: 'agent:write',\n commentCreate: 'agent:communicate',\n};\n\nexport interface LinearGuardConfig {\n /** The acting agent's Vorim id (agid_...). */\n agentId: string;\n /** The workspace this agent operates on, e.g. 'acme' (the URL key / slug).\n * Recorded in every receipt so an action is attributable to a specific\n * workspace. */\n workspaceKey: string;\n /** The human/principal the agent acts for. Recorded in every receipt so a\n * workspace action is attributable to a person, not just a machine. */\n humanId?: string;\n /** Minimum trust score the acting agent must hold before any mutation runs.\n * Default 0 (off). */\n minTrustScore?: number;\n /** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */\n onError?: 'closed' | 'open';\n}\n\nexport interface LinearAction {\n /** The Linear GraphQL mutation being run, e.g. 'issueUpdate'. Drives the\n * scope requirement. Unknown labels default to the 'write' tier. */\n operation: LinearOperation | string;\n /** The Linear resource the action targets, e.g. an issue or project id. */\n resourceId?: string;\n /** Optional hash of the mutation variables so the receipt covers the exact\n * input without the guard storing it. */\n inputHash?: string;\n}\n\n/** An offline-verifiable receipt for one Linear workspace operation. */\nexport interface LinearReceipt {\n authorized: boolean;\n agentId: string;\n humanId?: string;\n workspace: string;\n operation: string;\n resourceId?: string;\n result: 'success' | 'denied' | 'error';\n scope: PermissionScope;\n /** Reason a check failed, when authorized is false. */\n reason?: string;\n /** True once the audit event was signed and ingested. */\n recorded: boolean;\n}\n\nexport class VorimLinear {\n private sdk: VorimSDK;\n private agentId: string;\n private workspaceKey: string;\n private humanId?: string;\n private minTrustScore: number;\n private onError: 'closed' | 'open';\n\n constructor(sdk: VorimSDK, config: LinearGuardConfig) {\n if (!config?.agentId) throw new Error('[vorim] Linear integration requires an agentId.');\n if (!config?.workspaceKey) throw new Error('[vorim] Linear integration requires a workspaceKey.');\n this.sdk = sdk;\n this.agentId = config.agentId;\n this.workspaceKey = config.workspaceKey;\n this.humanId = config.humanId;\n this.minTrustScore = config.minTrustScore ?? 0;\n this.onError = config.onError ?? 'closed';\n }\n\n /** The Vorim scope a given operation requires. Unknown mutations fall back to\n * agent:write (a mutation is at least a write). */\n private scopeFor(operation: string): PermissionScope {\n return OPERATION_SCOPE[operation] ?? 'agent:write';\n }\n\n /**\n * Check whether the acting agent may run this workspace operation, before it\n * runs. Enforces (in order): trust floor, permission scope. Returns\n * { authorized, reason }.\n */\n async authorize(action: LinearAction): Promise<{ authorized: boolean; reason?: string }> {\n const scope = this.scopeFor(action.operation);\n\n try {\n // Trust floor (optional): refuse low-trust agents up front.\n if (this.minTrustScore > 0) {\n const trust = await this.sdk.verify(this.agentId);\n if ((trust?.trust_score ?? 0) < this.minTrustScore) {\n return { authorized: false, reason: `trust score below ${this.minTrustScore}` };\n }\n }\n const perm = await this.sdk.check(this.agentId, scope);\n return perm.allowed\n ? { authorized: true }\n : { authorized: false, reason: perm.reason ?? `missing scope ${scope}` };\n } catch (e: any) {\n // Fail closed by default: a check we could not complete is a deny.\n return this.onError === 'open'\n ? { authorized: true, reason: 'vorim unreachable, failed open' }\n : { authorized: false, reason: `vorim unreachable: ${e?.message ?? 'error'}` };\n }\n }\n\n /**\n * Emit a source-signed audit event for a workspace operation and return\n * whether it was recorded. Called after the mutation runs (or after a\n * denial). The event names the agent, the workspace, and the human the agent\n * acts for, so the record is attributable and independently verifiable\n * offline.\n */\n async record(action: LinearAction, result: 'success' | 'denied' | 'error', reason?: string): Promise<boolean> {\n const scope = this.scopeFor(action.operation);\n try {\n await this.sdk.emit({\n agent_id: this.agentId,\n event_type: 'api_request',\n action: `linear:${action.operation}${action.resourceId ? ' ' + action.resourceId : ''}`,\n resource: action.resourceId || this.workspaceKey,\n permission: scope,\n result,\n input_hash: action.inputHash,\n metadata: {\n integration: 'linear',\n workspace: this.workspaceKey,\n acts_for_human: this.humanId,\n operation: action.operation,\n ...(reason ? { reason } : {}),\n },\n }, { sign: true }); // source-signed: the agent's key signs the record\n return true;\n } catch {\n return false;\n }\n }\n\n /**\n * The full flow for one workspace operation: authorize, run the Linear\n * GraphQL mutation if allowed, sign a receipt either way. If not authorized,\n * `run` is never called (the mutation does not happen). Rethrows an error from\n * `run` after recording it, with the receipt attached as `vorimReceipt`, so\n * your handler still sees Linear failures.\n */\n async guard<T>(action: LinearAction, run: () => Promise<T>): Promise<{ receipt: LinearReceipt; value?: T }> {\n const auth = await this.authorize(action);\n if (!auth.authorized) {\n const recorded = await this.record(action, 'denied', auth.reason);\n return { receipt: this.receipt(action, false, 'denied', auth.reason, recorded) };\n }\n try {\n const value = await run();\n const recorded = await this.record(action, 'success');\n return { receipt: this.receipt(action, true, 'success', undefined, recorded), value };\n } catch (e: any) {\n const recorded = await this.record(action, 'error', e?.message);\n throw Object.assign(e ?? new Error('linear operation failed'), {\n vorimReceipt: this.receipt(action, true, 'error', e?.message, recorded),\n });\n }\n }\n\n // --- Named helpers for the Linear mutations --------------------------------\n // Each wraps guard() with the right operation label so the scope and receipt\n // are correct without the caller having to remember the mapping. You pass the\n // GraphQL call as `run`; this layer never talks to Linear itself.\n\n /** Guard an `issueCreate`. Requires agent:write. */\n issueCreate<T>(meta: { issueId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'issueCreate', resourceId: meta.issueId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard an `issueUpdate` (edit or state transition). Requires agent:write. */\n issueUpdate<T>(meta: { issueId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'issueUpdate', resourceId: meta.issueId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard an `issueDelete`. Requires agent:write. DESTRUCTIVE — it removes an\n * issue rather than editing it; consider a higher trust floor. */\n issueDelete<T>(meta: { issueId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'issueDelete', resourceId: meta.issueId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard a `commentCreate`. Requires agent:communicate — an agent posting a\n * comment is communication, not just a data write. */\n commentCreate<T>(meta: { issueId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'commentCreate', resourceId: meta.issueId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard an `issueArchive`. Requires agent:write. */\n issueArchive<T>(meta: { issueId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'issueArchive', resourceId: meta.issueId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard a `projectUpdate`. Requires agent:write. */\n projectUpdate<T>(meta: { projectId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'projectUpdate', resourceId: meta.projectId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard an `issueBatchUpdate`. Requires agent:write. BULK — one call can\n * rewrite many issues at once (higher blast radius); consider a higher trust\n * floor or a tighter grant. */\n issueBatchUpdate<T>(meta: { resourceId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'issueBatchUpdate', resourceId: meta.resourceId, inputHash: meta.inputHash }, run);\n }\n\n private receipt(\n action: LinearAction,\n authorized: boolean,\n result: 'success' | 'denied' | 'error',\n reason: string | undefined,\n recorded: boolean,\n ): LinearReceipt {\n return {\n authorized,\n agentId: this.agentId,\n humanId: this.humanId,\n workspace: this.workspaceKey,\n operation: action.operation,\n resourceId: action.resourceId,\n result,\n scope: this.scopeFor(action.operation),\n reason,\n recorded,\n };\n }\n}\n\n/**\n * Create a VorimLinear guard around a Vorim SDK instance.\n *\n * @example\n * ```typescript\n * import createVorim from '@vorim/sdk';\n * import { createVorimLinear } from '@vorim/sdk/integrations/linear';\n *\n * const vorim = createVorim({ apiKey: 'agid_sk_...' });\n * const linear = createVorimLinear(vorim, {\n * agentId: 'agid_abc123',\n * workspaceKey: 'acme',\n * humanId: 'user_42',\n * minTrustScore: 60,\n * });\n *\n * const { receipt, value } = await linear.issueUpdate(\n * { issueId: 'ISS-123', inputHash },\n * () => linearClient.updateIssue('ISS-123', { stateId }),\n * );\n * ```\n */\nexport function createVorimLinear(sdk: VorimSDK, config: LinearGuardConfig): VorimLinear {\n return new VorimLinear(sdk, config);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4EA,IAAM,kBAAmD;AAAA,EACvD,MAAM;AAAA,EACN,aAAa;AAAA,EACb,aAAa;AAAA,EACb,aAAa;AAAA,EACb,cAAc;AAAA,EACd,eAAe;AAAA,EACf,kBAAkB;AAAA,EAClB,eAAe;AACjB;AA8CO,IAAM,cAAN,MAAkB;AAAA,EACf;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAER,YAAY,KAAe,QAA2B;AACpD,QAAI,CAAC,QAAQ,QAAS,OAAM,IAAI,MAAM,iDAAiD;AACvF,QAAI,CAAC,QAAQ,aAAc,OAAM,IAAI,MAAM,qDAAqD;AAChG,SAAK,MAAM;AACX,SAAK,UAAU,OAAO;AACtB,SAAK,eAAe,OAAO;AAC3B,SAAK,UAAU,OAAO;AACtB,SAAK,gBAAgB,OAAO,iBAAiB;AAC7C,SAAK,UAAU,OAAO,WAAW;AAAA,EACnC;AAAA;AAAA;AAAA,EAIQ,SAAS,WAAoC;AACnD,WAAO,gBAAgB,SAAS,KAAK;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,UAAU,QAAyE;AACvF,UAAM,QAAQ,KAAK,SAAS,OAAO,SAAS;AAE5C,QAAI;AAEF,UAAI,KAAK,gBAAgB,GAAG;AAC1B,cAAM,QAAQ,MAAM,KAAK,IAAI,OAAO,KAAK,OAAO;AAChD,aAAK,OAAO,eAAe,KAAK,KAAK,eAAe;AAClD,iBAAO,EAAE,YAAY,OAAO,QAAQ,qBAAqB,KAAK,aAAa,GAAG;AAAA,QAChF;AAAA,MACF;AACA,YAAM,OAAO,MAAM,KAAK,IAAI,MAAM,KAAK,SAAS,KAAK;AACrD,aAAO,KAAK,UACR,EAAE,YAAY,KAAK,IACnB,EAAE,YAAY,OAAO,QAAQ,KAAK,UAAU,iBAAiB,KAAK,GAAG;AAAA,IAC3E,SAAS,GAAQ;AAEf,aAAO,KAAK,YAAY,SACpB,EAAE,YAAY,MAAM,QAAQ,iCAAiC,IAC7D,EAAE,YAAY,OAAO,QAAQ,sBAAsB,GAAG,WAAW,OAAO,GAAG;AAAA,IACjF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,OAAO,QAAsB,QAAwC,QAAmC;AAC5G,UAAM,QAAQ,KAAK,SAAS,OAAO,SAAS;AAC5C,QAAI;AACF,YAAM,KAAK,IAAI,KAAK;AAAA,QAClB,UAAU,KAAK;AAAA,QACf,YAAY;AAAA,QACZ,QAAQ,UAAU,OAAO,SAAS,GAAG,OAAO,aAAa,MAAM,OAAO,aAAa,EAAE;AAAA,QACrF,UAAU,OAAO,cAAc,KAAK;AAAA,QACpC,YAAY;AAAA,QACZ;AAAA,QACA,YAAY,OAAO;AAAA,QACnB,UAAU;AAAA,UACR,aAAa;AAAA,UACb,WAAW,KAAK;AAAA,UAChB,gBAAgB,KAAK;AAAA,UACrB,WAAW,OAAO;AAAA,UAClB,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;AAAA,QAC7B;AAAA,MACF,GAAG,EAAE,MAAM,KAAK,CAAC;AACjB,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAM,MAAS,QAAsB,KAAuE;AAC1G,UAAM,OAAO,MAAM,KAAK,UAAU,MAAM;AACxC,QAAI,CAAC,KAAK,YAAY;AACpB,YAAM,WAAW,MAAM,KAAK,OAAO,QAAQ,UAAU,KAAK,MAAM;AAChE,aAAO,EAAE,SAAS,KAAK,QAAQ,QAAQ,OAAO,UAAU,KAAK,QAAQ,QAAQ,EAAE;AAAA,IACjF;AACA,QAAI;AACF,YAAM,QAAQ,MAAM,IAAI;AACxB,YAAM,WAAW,MAAM,KAAK,OAAO,QAAQ,SAAS;AACpD,aAAO,EAAE,SAAS,KAAK,QAAQ,QAAQ,MAAM,WAAW,QAAW,QAAQ,GAAG,MAAM;AAAA,IACtF,SAAS,GAAQ;AACf,YAAM,WAAW,MAAM,KAAK,OAAO,QAAQ,SAAS,GAAG,OAAO;AAC9D,YAAM,OAAO,OAAO,KAAK,IAAI,MAAM,yBAAyB,GAAG;AAAA,QAC7D,cAAc,KAAK,QAAQ,QAAQ,MAAM,SAAS,GAAG,SAAS,QAAQ;AAAA,MACxE,CAAC;AAAA,IACH;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,YAAe,MAAgD,KAAuB;AACpF,WAAO,KAAK,MAAM,EAAE,WAAW,eAAe,YAAY,KAAK,SAAS,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAC1G;AAAA;AAAA,EAGA,YAAe,MAAgD,KAAuB;AACpF,WAAO,KAAK,MAAM,EAAE,WAAW,eAAe,YAAY,KAAK,SAAS,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAC1G;AAAA;AAAA;AAAA,EAIA,YAAe,MAAgD,KAAuB;AACpF,WAAO,KAAK,MAAM,EAAE,WAAW,eAAe,YAAY,KAAK,SAAS,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAC1G;AAAA;AAAA;AAAA,EAIA,cAAiB,MAAgD,KAAuB;AACtF,WAAO,KAAK,MAAM,EAAE,WAAW,iBAAiB,YAAY,KAAK,SAAS,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAC5G;AAAA;AAAA,EAGA,aAAgB,MAAgD,KAAuB;AACrF,WAAO,KAAK,MAAM,EAAE,WAAW,gBAAgB,YAAY,KAAK,SAAS,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAC3G;AAAA;AAAA,EAGA,cAAiB,MAAkD,KAAuB;AACxF,WAAO,KAAK,MAAM,EAAE,WAAW,iBAAiB,YAAY,KAAK,WAAW,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAC9G;AAAA;AAAA;AAAA;AAAA,EAKA,iBAAoB,MAAmD,KAAuB;AAC5F,WAAO,KAAK,MAAM,EAAE,WAAW,oBAAoB,YAAY,KAAK,YAAY,WAAW,KAAK,UAAU,GAAG,GAAG;AAAA,EAClH;AAAA,EAEQ,QACN,QACA,YACA,QACA,QACA,UACe;AACf,WAAO;AAAA,MACL;AAAA,MACA,SAAS,KAAK;AAAA,MACd,SAAS,KAAK;AAAA,MACd,WAAW,KAAK;AAAA,MAChB,WAAW,OAAO;AAAA,MAClB,YAAY,OAAO;AAAA,MACnB;AAAA,MACA,OAAO,KAAK,SAAS,OAAO,SAAS;AAAA,MACrC;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAwBO,SAAS,kBAAkB,KAAe,QAAwC;AACvF,SAAO,IAAI,YAAY,KAAK,MAAM;AACpC;","names":[]}
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import { VorimSDK } from '../index.cjs';
|
|
2
|
+
import { P as PermissionScope } from '../types-BmeluKHI.cjs';
|
|
3
|
+
|
|
4
|
+
/** The Linear GraphQL mutations this guard knows how to classify. Any other
|
|
5
|
+
* label is accepted too; it just defaults to the 'write' risk tier. */
|
|
6
|
+
type LinearOperation = 'issueCreate' | 'issueUpdate' | 'issueDelete' | 'commentCreate' | 'issueArchive' | 'projectUpdate' | 'issueBatchUpdate' | 'read';
|
|
7
|
+
interface LinearGuardConfig {
|
|
8
|
+
/** The acting agent's Vorim id (agid_...). */
|
|
9
|
+
agentId: string;
|
|
10
|
+
/** The workspace this agent operates on, e.g. 'acme' (the URL key / slug).
|
|
11
|
+
* Recorded in every receipt so an action is attributable to a specific
|
|
12
|
+
* workspace. */
|
|
13
|
+
workspaceKey: string;
|
|
14
|
+
/** The human/principal the agent acts for. Recorded in every receipt so a
|
|
15
|
+
* workspace action is attributable to a person, not just a machine. */
|
|
16
|
+
humanId?: string;
|
|
17
|
+
/** Minimum trust score the acting agent must hold before any mutation runs.
|
|
18
|
+
* Default 0 (off). */
|
|
19
|
+
minTrustScore?: number;
|
|
20
|
+
/** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */
|
|
21
|
+
onError?: 'closed' | 'open';
|
|
22
|
+
}
|
|
23
|
+
interface LinearAction {
|
|
24
|
+
/** The Linear GraphQL mutation being run, e.g. 'issueUpdate'. Drives the
|
|
25
|
+
* scope requirement. Unknown labels default to the 'write' tier. */
|
|
26
|
+
operation: LinearOperation | string;
|
|
27
|
+
/** The Linear resource the action targets, e.g. an issue or project id. */
|
|
28
|
+
resourceId?: string;
|
|
29
|
+
/** Optional hash of the mutation variables so the receipt covers the exact
|
|
30
|
+
* input without the guard storing it. */
|
|
31
|
+
inputHash?: string;
|
|
32
|
+
}
|
|
33
|
+
/** An offline-verifiable receipt for one Linear workspace operation. */
|
|
34
|
+
interface LinearReceipt {
|
|
35
|
+
authorized: boolean;
|
|
36
|
+
agentId: string;
|
|
37
|
+
humanId?: string;
|
|
38
|
+
workspace: string;
|
|
39
|
+
operation: string;
|
|
40
|
+
resourceId?: string;
|
|
41
|
+
result: 'success' | 'denied' | 'error';
|
|
42
|
+
scope: PermissionScope;
|
|
43
|
+
/** Reason a check failed, when authorized is false. */
|
|
44
|
+
reason?: string;
|
|
45
|
+
/** True once the audit event was signed and ingested. */
|
|
46
|
+
recorded: boolean;
|
|
47
|
+
}
|
|
48
|
+
declare class VorimLinear {
|
|
49
|
+
private sdk;
|
|
50
|
+
private agentId;
|
|
51
|
+
private workspaceKey;
|
|
52
|
+
private humanId?;
|
|
53
|
+
private minTrustScore;
|
|
54
|
+
private onError;
|
|
55
|
+
constructor(sdk: VorimSDK, config: LinearGuardConfig);
|
|
56
|
+
/** The Vorim scope a given operation requires. Unknown mutations fall back to
|
|
57
|
+
* agent:write (a mutation is at least a write). */
|
|
58
|
+
private scopeFor;
|
|
59
|
+
/**
|
|
60
|
+
* Check whether the acting agent may run this workspace operation, before it
|
|
61
|
+
* runs. Enforces (in order): trust floor, permission scope. Returns
|
|
62
|
+
* { authorized, reason }.
|
|
63
|
+
*/
|
|
64
|
+
authorize(action: LinearAction): Promise<{
|
|
65
|
+
authorized: boolean;
|
|
66
|
+
reason?: string;
|
|
67
|
+
}>;
|
|
68
|
+
/**
|
|
69
|
+
* Emit a source-signed audit event for a workspace operation and return
|
|
70
|
+
* whether it was recorded. Called after the mutation runs (or after a
|
|
71
|
+
* denial). The event names the agent, the workspace, and the human the agent
|
|
72
|
+
* acts for, so the record is attributable and independently verifiable
|
|
73
|
+
* offline.
|
|
74
|
+
*/
|
|
75
|
+
record(action: LinearAction, result: 'success' | 'denied' | 'error', reason?: string): Promise<boolean>;
|
|
76
|
+
/**
|
|
77
|
+
* The full flow for one workspace operation: authorize, run the Linear
|
|
78
|
+
* GraphQL mutation if allowed, sign a receipt either way. If not authorized,
|
|
79
|
+
* `run` is never called (the mutation does not happen). Rethrows an error from
|
|
80
|
+
* `run` after recording it, with the receipt attached as `vorimReceipt`, so
|
|
81
|
+
* your handler still sees Linear failures.
|
|
82
|
+
*/
|
|
83
|
+
guard<T>(action: LinearAction, run: () => Promise<T>): Promise<{
|
|
84
|
+
receipt: LinearReceipt;
|
|
85
|
+
value?: T;
|
|
86
|
+
}>;
|
|
87
|
+
/** Guard an `issueCreate`. Requires agent:write. */
|
|
88
|
+
issueCreate<T>(meta: {
|
|
89
|
+
issueId?: string;
|
|
90
|
+
inputHash?: string;
|
|
91
|
+
}, run: () => Promise<T>): Promise<{
|
|
92
|
+
receipt: LinearReceipt;
|
|
93
|
+
value?: T | undefined;
|
|
94
|
+
}>;
|
|
95
|
+
/** Guard an `issueUpdate` (edit or state transition). Requires agent:write. */
|
|
96
|
+
issueUpdate<T>(meta: {
|
|
97
|
+
issueId?: string;
|
|
98
|
+
inputHash?: string;
|
|
99
|
+
}, run: () => Promise<T>): Promise<{
|
|
100
|
+
receipt: LinearReceipt;
|
|
101
|
+
value?: T | undefined;
|
|
102
|
+
}>;
|
|
103
|
+
/** Guard an `issueDelete`. Requires agent:write. DESTRUCTIVE — it removes an
|
|
104
|
+
* issue rather than editing it; consider a higher trust floor. */
|
|
105
|
+
issueDelete<T>(meta: {
|
|
106
|
+
issueId?: string;
|
|
107
|
+
inputHash?: string;
|
|
108
|
+
}, run: () => Promise<T>): Promise<{
|
|
109
|
+
receipt: LinearReceipt;
|
|
110
|
+
value?: T | undefined;
|
|
111
|
+
}>;
|
|
112
|
+
/** Guard a `commentCreate`. Requires agent:communicate — an agent posting a
|
|
113
|
+
* comment is communication, not just a data write. */
|
|
114
|
+
commentCreate<T>(meta: {
|
|
115
|
+
issueId?: string;
|
|
116
|
+
inputHash?: string;
|
|
117
|
+
}, run: () => Promise<T>): Promise<{
|
|
118
|
+
receipt: LinearReceipt;
|
|
119
|
+
value?: T | undefined;
|
|
120
|
+
}>;
|
|
121
|
+
/** Guard an `issueArchive`. Requires agent:write. */
|
|
122
|
+
issueArchive<T>(meta: {
|
|
123
|
+
issueId?: string;
|
|
124
|
+
inputHash?: string;
|
|
125
|
+
}, run: () => Promise<T>): Promise<{
|
|
126
|
+
receipt: LinearReceipt;
|
|
127
|
+
value?: T | undefined;
|
|
128
|
+
}>;
|
|
129
|
+
/** Guard a `projectUpdate`. Requires agent:write. */
|
|
130
|
+
projectUpdate<T>(meta: {
|
|
131
|
+
projectId?: string;
|
|
132
|
+
inputHash?: string;
|
|
133
|
+
}, run: () => Promise<T>): Promise<{
|
|
134
|
+
receipt: LinearReceipt;
|
|
135
|
+
value?: T | undefined;
|
|
136
|
+
}>;
|
|
137
|
+
/** Guard an `issueBatchUpdate`. Requires agent:write. BULK — one call can
|
|
138
|
+
* rewrite many issues at once (higher blast radius); consider a higher trust
|
|
139
|
+
* floor or a tighter grant. */
|
|
140
|
+
issueBatchUpdate<T>(meta: {
|
|
141
|
+
resourceId?: string;
|
|
142
|
+
inputHash?: string;
|
|
143
|
+
}, run: () => Promise<T>): Promise<{
|
|
144
|
+
receipt: LinearReceipt;
|
|
145
|
+
value?: T | undefined;
|
|
146
|
+
}>;
|
|
147
|
+
private receipt;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Create a VorimLinear guard around a Vorim SDK instance.
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```typescript
|
|
154
|
+
* import createVorim from '@vorim/sdk';
|
|
155
|
+
* import { createVorimLinear } from '@vorim/sdk/integrations/linear';
|
|
156
|
+
*
|
|
157
|
+
* const vorim = createVorim({ apiKey: 'agid_sk_...' });
|
|
158
|
+
* const linear = createVorimLinear(vorim, {
|
|
159
|
+
* agentId: 'agid_abc123',
|
|
160
|
+
* workspaceKey: 'acme',
|
|
161
|
+
* humanId: 'user_42',
|
|
162
|
+
* minTrustScore: 60,
|
|
163
|
+
* });
|
|
164
|
+
*
|
|
165
|
+
* const { receipt, value } = await linear.issueUpdate(
|
|
166
|
+
* { issueId: 'ISS-123', inputHash },
|
|
167
|
+
* () => linearClient.updateIssue('ISS-123', { stateId }),
|
|
168
|
+
* );
|
|
169
|
+
* ```
|
|
170
|
+
*/
|
|
171
|
+
declare function createVorimLinear(sdk: VorimSDK, config: LinearGuardConfig): VorimLinear;
|
|
172
|
+
|
|
173
|
+
export { type LinearAction, type LinearGuardConfig, type LinearOperation, type LinearReceipt, VorimLinear, createVorimLinear };
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import { VorimSDK } from '../index.js';
|
|
2
|
+
import { P as PermissionScope } from '../types-BmeluKHI.js';
|
|
3
|
+
|
|
4
|
+
/** The Linear GraphQL mutations this guard knows how to classify. Any other
|
|
5
|
+
* label is accepted too; it just defaults to the 'write' risk tier. */
|
|
6
|
+
type LinearOperation = 'issueCreate' | 'issueUpdate' | 'issueDelete' | 'commentCreate' | 'issueArchive' | 'projectUpdate' | 'issueBatchUpdate' | 'read';
|
|
7
|
+
interface LinearGuardConfig {
|
|
8
|
+
/** The acting agent's Vorim id (agid_...). */
|
|
9
|
+
agentId: string;
|
|
10
|
+
/** The workspace this agent operates on, e.g. 'acme' (the URL key / slug).
|
|
11
|
+
* Recorded in every receipt so an action is attributable to a specific
|
|
12
|
+
* workspace. */
|
|
13
|
+
workspaceKey: string;
|
|
14
|
+
/** The human/principal the agent acts for. Recorded in every receipt so a
|
|
15
|
+
* workspace action is attributable to a person, not just a machine. */
|
|
16
|
+
humanId?: string;
|
|
17
|
+
/** Minimum trust score the acting agent must hold before any mutation runs.
|
|
18
|
+
* Default 0 (off). */
|
|
19
|
+
minTrustScore?: number;
|
|
20
|
+
/** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */
|
|
21
|
+
onError?: 'closed' | 'open';
|
|
22
|
+
}
|
|
23
|
+
interface LinearAction {
|
|
24
|
+
/** The Linear GraphQL mutation being run, e.g. 'issueUpdate'. Drives the
|
|
25
|
+
* scope requirement. Unknown labels default to the 'write' tier. */
|
|
26
|
+
operation: LinearOperation | string;
|
|
27
|
+
/** The Linear resource the action targets, e.g. an issue or project id. */
|
|
28
|
+
resourceId?: string;
|
|
29
|
+
/** Optional hash of the mutation variables so the receipt covers the exact
|
|
30
|
+
* input without the guard storing it. */
|
|
31
|
+
inputHash?: string;
|
|
32
|
+
}
|
|
33
|
+
/** An offline-verifiable receipt for one Linear workspace operation. */
|
|
34
|
+
interface LinearReceipt {
|
|
35
|
+
authorized: boolean;
|
|
36
|
+
agentId: string;
|
|
37
|
+
humanId?: string;
|
|
38
|
+
workspace: string;
|
|
39
|
+
operation: string;
|
|
40
|
+
resourceId?: string;
|
|
41
|
+
result: 'success' | 'denied' | 'error';
|
|
42
|
+
scope: PermissionScope;
|
|
43
|
+
/** Reason a check failed, when authorized is false. */
|
|
44
|
+
reason?: string;
|
|
45
|
+
/** True once the audit event was signed and ingested. */
|
|
46
|
+
recorded: boolean;
|
|
47
|
+
}
|
|
48
|
+
declare class VorimLinear {
|
|
49
|
+
private sdk;
|
|
50
|
+
private agentId;
|
|
51
|
+
private workspaceKey;
|
|
52
|
+
private humanId?;
|
|
53
|
+
private minTrustScore;
|
|
54
|
+
private onError;
|
|
55
|
+
constructor(sdk: VorimSDK, config: LinearGuardConfig);
|
|
56
|
+
/** The Vorim scope a given operation requires. Unknown mutations fall back to
|
|
57
|
+
* agent:write (a mutation is at least a write). */
|
|
58
|
+
private scopeFor;
|
|
59
|
+
/**
|
|
60
|
+
* Check whether the acting agent may run this workspace operation, before it
|
|
61
|
+
* runs. Enforces (in order): trust floor, permission scope. Returns
|
|
62
|
+
* { authorized, reason }.
|
|
63
|
+
*/
|
|
64
|
+
authorize(action: LinearAction): Promise<{
|
|
65
|
+
authorized: boolean;
|
|
66
|
+
reason?: string;
|
|
67
|
+
}>;
|
|
68
|
+
/**
|
|
69
|
+
* Emit a source-signed audit event for a workspace operation and return
|
|
70
|
+
* whether it was recorded. Called after the mutation runs (or after a
|
|
71
|
+
* denial). The event names the agent, the workspace, and the human the agent
|
|
72
|
+
* acts for, so the record is attributable and independently verifiable
|
|
73
|
+
* offline.
|
|
74
|
+
*/
|
|
75
|
+
record(action: LinearAction, result: 'success' | 'denied' | 'error', reason?: string): Promise<boolean>;
|
|
76
|
+
/**
|
|
77
|
+
* The full flow for one workspace operation: authorize, run the Linear
|
|
78
|
+
* GraphQL mutation if allowed, sign a receipt either way. If not authorized,
|
|
79
|
+
* `run` is never called (the mutation does not happen). Rethrows an error from
|
|
80
|
+
* `run` after recording it, with the receipt attached as `vorimReceipt`, so
|
|
81
|
+
* your handler still sees Linear failures.
|
|
82
|
+
*/
|
|
83
|
+
guard<T>(action: LinearAction, run: () => Promise<T>): Promise<{
|
|
84
|
+
receipt: LinearReceipt;
|
|
85
|
+
value?: T;
|
|
86
|
+
}>;
|
|
87
|
+
/** Guard an `issueCreate`. Requires agent:write. */
|
|
88
|
+
issueCreate<T>(meta: {
|
|
89
|
+
issueId?: string;
|
|
90
|
+
inputHash?: string;
|
|
91
|
+
}, run: () => Promise<T>): Promise<{
|
|
92
|
+
receipt: LinearReceipt;
|
|
93
|
+
value?: T | undefined;
|
|
94
|
+
}>;
|
|
95
|
+
/** Guard an `issueUpdate` (edit or state transition). Requires agent:write. */
|
|
96
|
+
issueUpdate<T>(meta: {
|
|
97
|
+
issueId?: string;
|
|
98
|
+
inputHash?: string;
|
|
99
|
+
}, run: () => Promise<T>): Promise<{
|
|
100
|
+
receipt: LinearReceipt;
|
|
101
|
+
value?: T | undefined;
|
|
102
|
+
}>;
|
|
103
|
+
/** Guard an `issueDelete`. Requires agent:write. DESTRUCTIVE — it removes an
|
|
104
|
+
* issue rather than editing it; consider a higher trust floor. */
|
|
105
|
+
issueDelete<T>(meta: {
|
|
106
|
+
issueId?: string;
|
|
107
|
+
inputHash?: string;
|
|
108
|
+
}, run: () => Promise<T>): Promise<{
|
|
109
|
+
receipt: LinearReceipt;
|
|
110
|
+
value?: T | undefined;
|
|
111
|
+
}>;
|
|
112
|
+
/** Guard a `commentCreate`. Requires agent:communicate — an agent posting a
|
|
113
|
+
* comment is communication, not just a data write. */
|
|
114
|
+
commentCreate<T>(meta: {
|
|
115
|
+
issueId?: string;
|
|
116
|
+
inputHash?: string;
|
|
117
|
+
}, run: () => Promise<T>): Promise<{
|
|
118
|
+
receipt: LinearReceipt;
|
|
119
|
+
value?: T | undefined;
|
|
120
|
+
}>;
|
|
121
|
+
/** Guard an `issueArchive`. Requires agent:write. */
|
|
122
|
+
issueArchive<T>(meta: {
|
|
123
|
+
issueId?: string;
|
|
124
|
+
inputHash?: string;
|
|
125
|
+
}, run: () => Promise<T>): Promise<{
|
|
126
|
+
receipt: LinearReceipt;
|
|
127
|
+
value?: T | undefined;
|
|
128
|
+
}>;
|
|
129
|
+
/** Guard a `projectUpdate`. Requires agent:write. */
|
|
130
|
+
projectUpdate<T>(meta: {
|
|
131
|
+
projectId?: string;
|
|
132
|
+
inputHash?: string;
|
|
133
|
+
}, run: () => Promise<T>): Promise<{
|
|
134
|
+
receipt: LinearReceipt;
|
|
135
|
+
value?: T | undefined;
|
|
136
|
+
}>;
|
|
137
|
+
/** Guard an `issueBatchUpdate`. Requires agent:write. BULK — one call can
|
|
138
|
+
* rewrite many issues at once (higher blast radius); consider a higher trust
|
|
139
|
+
* floor or a tighter grant. */
|
|
140
|
+
issueBatchUpdate<T>(meta: {
|
|
141
|
+
resourceId?: string;
|
|
142
|
+
inputHash?: string;
|
|
143
|
+
}, run: () => Promise<T>): Promise<{
|
|
144
|
+
receipt: LinearReceipt;
|
|
145
|
+
value?: T | undefined;
|
|
146
|
+
}>;
|
|
147
|
+
private receipt;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Create a VorimLinear guard around a Vorim SDK instance.
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```typescript
|
|
154
|
+
* import createVorim from '@vorim/sdk';
|
|
155
|
+
* import { createVorimLinear } from '@vorim/sdk/integrations/linear';
|
|
156
|
+
*
|
|
157
|
+
* const vorim = createVorim({ apiKey: 'agid_sk_...' });
|
|
158
|
+
* const linear = createVorimLinear(vorim, {
|
|
159
|
+
* agentId: 'agid_abc123',
|
|
160
|
+
* workspaceKey: 'acme',
|
|
161
|
+
* humanId: 'user_42',
|
|
162
|
+
* minTrustScore: 60,
|
|
163
|
+
* });
|
|
164
|
+
*
|
|
165
|
+
* const { receipt, value } = await linear.issueUpdate(
|
|
166
|
+
* { issueId: 'ISS-123', inputHash },
|
|
167
|
+
* () => linearClient.updateIssue('ISS-123', { stateId }),
|
|
168
|
+
* );
|
|
169
|
+
* ```
|
|
170
|
+
*/
|
|
171
|
+
declare function createVorimLinear(sdk: VorimSDK, config: LinearGuardConfig): VorimLinear;
|
|
172
|
+
|
|
173
|
+
export { type LinearAction, type LinearGuardConfig, type LinearOperation, type LinearReceipt, VorimLinear, createVorimLinear };
|