Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
+321
@@ -0,0 +1,321 @@
|
||||
import type { PluginCapabilityName } from "./capabilities.js";
|
||||
import { isPluginCapabilityHostBindingAvailable } from "./capabilities.js";
|
||||
import { isCapabilityGrantScopeSatisfied, type PluginCapabilityGrant } from "./capability-grants.js";
|
||||
import { isCapabilityCallWithinScope } from "./capability-scope.js";
|
||||
import { hashCapabilityPayload } from "./audit.js";
|
||||
import { manifestDeclaresCapability, type PluginManifest } from "./manifest.js";
|
||||
|
||||
/**
|
||||
* Capability gateway — Phase 06 #21 foundation.
|
||||
*
|
||||
* Wraps a record of host functions so that a plugin can only invoke
|
||||
* the ones it declared in its manifest. Calls to undeclared host
|
||||
* functions throw `CapabilityDeniedError`. The gateway also charges a
|
||||
* configurable fuel cost on every successful host-fn invocation, which
|
||||
* is what the sandbox uses to enforce a CPU-budget-by-proxy on plugins
|
||||
* (since V8 has no public hook for per-instruction metering).
|
||||
*
|
||||
* Defaults are deny-by-default: capabilities not in `PLUGIN_CAPABILITY_NAMES`
|
||||
* (the closed enum from `capabilities.ts`) cannot be registered.
|
||||
*/
|
||||
|
||||
export type CapabilityHostFn = (...args: unknown[]) => unknown | Promise<unknown>;
|
||||
|
||||
export type CapabilityHostFnMap = Partial<Record<PluginCapabilityName, CapabilityHostFn>>;
|
||||
|
||||
export type CapabilityGatewayOptions = {
|
||||
manifest: PluginManifest;
|
||||
hostFns: CapabilityHostFnMap;
|
||||
/**
|
||||
* Tenant-approved grants for this invocation. When provided, the gateway
|
||||
* requires every host-fn call to be both manifest-declared and granted.
|
||||
*/
|
||||
approvedGrants?: ReadonlyArray<PluginCapabilityGrant>;
|
||||
/** Charged on every successful host-fn call. Default: 100. */
|
||||
fuelCostPerCall?: number;
|
||||
/** Called when a denied capability is invoked — for audit logging. */
|
||||
onDenied?: (info: { capability: PluginCapabilityName; reason: CapabilityDenyReason }) => void;
|
||||
/**
|
||||
* Phase 06 #23 — called after every host-fn call (success / error /
|
||||
* denied). Wire to a `PluginCapabilityUseRecorder` to feed the audit
|
||||
* log. Synchronous and best-effort: errors thrown here are swallowed
|
||||
* so audit-sink trouble never aborts a plugin invocation.
|
||||
*/
|
||||
onCall?: (info: CapabilityCallInfo) => void;
|
||||
};
|
||||
|
||||
export type CapabilityCallInfo = {
|
||||
capability: PluginCapabilityName;
|
||||
outcome: "success" | "denied" | "error";
|
||||
durationMs: number;
|
||||
errorCode?: string;
|
||||
payloadHash?: string;
|
||||
};
|
||||
|
||||
export type CapabilityDenyReason =
|
||||
| "not_declared_in_manifest"
|
||||
| "not_granted_for_tenant"
|
||||
| "scope_violation"
|
||||
| "unknown_capability"
|
||||
| "no_host_implementation";
|
||||
|
||||
export class CapabilityDeniedError extends Error {
|
||||
override readonly name = "CapabilityDeniedError";
|
||||
readonly capability: string;
|
||||
readonly reason: CapabilityDenyReason;
|
||||
constructor(capability: string, reason: CapabilityDenyReason) {
|
||||
super(`capability denied: ${capability} (${reason})`);
|
||||
this.capability = capability;
|
||||
this.reason = reason;
|
||||
}
|
||||
}
|
||||
|
||||
export type CapabilityGateway = {
|
||||
/** Invoke a host-fn through the gateway. Throws on denial. */
|
||||
invoke<T = unknown>(capability: PluginCapabilityName, ...args: unknown[]): Promise<T>;
|
||||
/**
|
||||
* Invoke a synchronous host-fn through the gateway. Intended for WASM
|
||||
* imports that cannot await promises.
|
||||
*/
|
||||
invokeSync<T = unknown>(capability: PluginCapabilityName, ...args: unknown[]): T;
|
||||
/** Cumulative fuel cost charged across all calls so far. */
|
||||
fuelCharged(): number;
|
||||
/** Reset the fuel counter — used between invocations. */
|
||||
resetFuel(): void;
|
||||
};
|
||||
|
||||
const DEFAULT_FUEL_COST = 100;
|
||||
|
||||
/**
|
||||
* Build a gateway. The gateway is invocation-scoped (one per plugin
|
||||
* call); callers `resetFuel()` between calls when reusing the same
|
||||
* sandbox instance.
|
||||
*/
|
||||
export function createCapabilityGateway(options: CapabilityGatewayOptions): CapabilityGateway {
|
||||
const { manifest, hostFns } = options;
|
||||
const fuelCostPerCall = options.fuelCostPerCall ?? DEFAULT_FUEL_COST;
|
||||
const approvedGrantByName = options.approvedGrants ? new Map(options.approvedGrants.map((grant) => [grant.capabilityName, grant])) : null;
|
||||
let fuel = 0;
|
||||
|
||||
function notifyCall(info: CapabilityCallInfo): void {
|
||||
if (!options.onCall) return;
|
||||
try {
|
||||
options.onCall(info);
|
||||
} catch {
|
||||
// Audit sink must never abort a plugin invocation. Drop and
|
||||
// continue — the sink's own logger reports the failure.
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
invoke: async <T>(capability: PluginCapabilityName, ...args: unknown[]): Promise<T> => {
|
||||
const startedAt = Date.now();
|
||||
if (!manifestDeclaresCapability(manifest, capability)) {
|
||||
options.onDenied?.({ capability, reason: "not_declared_in_manifest" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "not_declared_in_manifest",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "not_declared_in_manifest");
|
||||
}
|
||||
const approvedGrant = approvedGrantByName ? getCapabilityApprovedGrantForManifestScope(manifest, approvedGrantByName, capability) : null;
|
||||
if (approvedGrantByName && !approvedGrant) {
|
||||
options.onDenied?.({ capability, reason: "not_granted_for_tenant" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "not_granted_for_tenant",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "not_granted_for_tenant");
|
||||
}
|
||||
if (!isPluginCapabilityHostBindingAvailable(capability)) {
|
||||
options.onDenied?.({ capability, reason: "no_host_implementation" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "no_host_implementation",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "no_host_implementation");
|
||||
}
|
||||
const fn = hostFns[capability];
|
||||
if (typeof fn !== "function") {
|
||||
options.onDenied?.({ capability, reason: "no_host_implementation" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "no_host_implementation",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "no_host_implementation");
|
||||
}
|
||||
if (
|
||||
approvedGrant &&
|
||||
!isCapabilityCallWithinScope({
|
||||
capability,
|
||||
callArgs: args,
|
||||
scope: approvedGrant.scopeJson,
|
||||
})
|
||||
) {
|
||||
options.onDenied?.({ capability, reason: "scope_violation" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "scope_violation",
|
||||
payloadHash: hashCapabilityPayload(createCapabilityPayloadDescriptor(capability, args)),
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "scope_violation");
|
||||
}
|
||||
// Always charge fuel before invoking, so a host-fn that throws
|
||||
// still counts against the plugin's budget — matches Wasmtime
|
||||
// semantics where consumed fuel survives a trap.
|
||||
fuel += fuelCostPerCall;
|
||||
try {
|
||||
const result = await fn(...args);
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "success",
|
||||
durationMs: Date.now() - startedAt,
|
||||
payloadHash: hashCapabilityPayload(createCapabilityPayloadDescriptor(capability, args)),
|
||||
});
|
||||
return result as T;
|
||||
} catch (err) {
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "error",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: err instanceof Error ? err.name : "unknown",
|
||||
payloadHash: hashCapabilityPayload(createCapabilityPayloadDescriptor(capability, args)),
|
||||
});
|
||||
throw err;
|
||||
}
|
||||
},
|
||||
invokeSync: <T>(capability: PluginCapabilityName, ...args: unknown[]): T => {
|
||||
const startedAt = Date.now();
|
||||
if (!manifestDeclaresCapability(manifest, capability)) {
|
||||
options.onDenied?.({ capability, reason: "not_declared_in_manifest" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "not_declared_in_manifest",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "not_declared_in_manifest");
|
||||
}
|
||||
const approvedGrant = approvedGrantByName ? getCapabilityApprovedGrantForManifestScope(manifest, approvedGrantByName, capability) : null;
|
||||
if (approvedGrantByName && !approvedGrant) {
|
||||
options.onDenied?.({ capability, reason: "not_granted_for_tenant" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "not_granted_for_tenant",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "not_granted_for_tenant");
|
||||
}
|
||||
if (!isPluginCapabilityHostBindingAvailable(capability)) {
|
||||
options.onDenied?.({ capability, reason: "no_host_implementation" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "no_host_implementation",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "no_host_implementation");
|
||||
}
|
||||
const fn = hostFns[capability];
|
||||
if (typeof fn !== "function") {
|
||||
options.onDenied?.({ capability, reason: "no_host_implementation" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "no_host_implementation",
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "no_host_implementation");
|
||||
}
|
||||
if (
|
||||
approvedGrant &&
|
||||
!isCapabilityCallWithinScope({
|
||||
capability,
|
||||
callArgs: args,
|
||||
scope: approvedGrant.scopeJson,
|
||||
})
|
||||
) {
|
||||
options.onDenied?.({ capability, reason: "scope_violation" });
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "denied",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: "scope_violation",
|
||||
payloadHash: hashCapabilityPayload(createCapabilityPayloadDescriptor(capability, args)),
|
||||
});
|
||||
throw new CapabilityDeniedError(capability, "scope_violation");
|
||||
}
|
||||
fuel += fuelCostPerCall;
|
||||
try {
|
||||
const result = fn(...args);
|
||||
if (result && typeof (result as Promise<unknown>).then === "function") {
|
||||
throw new Error("async_host_fn_not_supported");
|
||||
}
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "success",
|
||||
durationMs: Date.now() - startedAt,
|
||||
payloadHash: hashCapabilityPayload(createCapabilityPayloadDescriptor(capability, args)),
|
||||
});
|
||||
return result as T;
|
||||
} catch (err) {
|
||||
notifyCall({
|
||||
capability,
|
||||
outcome: "error",
|
||||
durationMs: Date.now() - startedAt,
|
||||
errorCode: err instanceof Error ? err.name : "unknown",
|
||||
payloadHash: hashCapabilityPayload(createCapabilityPayloadDescriptor(capability, args)),
|
||||
});
|
||||
throw err;
|
||||
}
|
||||
},
|
||||
fuelCharged: () => fuel,
|
||||
resetFuel: () => {
|
||||
fuel = 0;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function getCapabilityApprovedGrantForManifestScope(
|
||||
manifest: PluginManifest,
|
||||
approvedGrantByName: ReadonlyMap<string, PluginCapabilityGrant>,
|
||||
capability: PluginCapabilityName
|
||||
): PluginCapabilityGrant | null {
|
||||
const grant = approvedGrantByName.get(capability);
|
||||
const declaredCapability = manifest.capabilities.find((candidate) => candidate.name === capability);
|
||||
return grant &&
|
||||
declaredCapability &&
|
||||
isCapabilityGrantScopeSatisfied({
|
||||
declaredScope: declaredCapability.scope ?? null,
|
||||
grantedScopeJson: grant.scopeJson,
|
||||
})
|
||||
? grant
|
||||
: null;
|
||||
}
|
||||
|
||||
function createCapabilityPayloadDescriptor(capability: PluginCapabilityName, args: readonly unknown[]): string {
|
||||
return JSON.stringify({
|
||||
capability,
|
||||
args: args.map((arg) => describeCapabilityArgument(arg)),
|
||||
});
|
||||
}
|
||||
|
||||
function describeCapabilityArgument(arg: unknown): unknown {
|
||||
if (arg === null) return null;
|
||||
if (Array.isArray(arg)) return { type: "array", length: arg.length };
|
||||
if (typeof arg === "object") {
|
||||
return { type: "object", keys: Object.keys(arg).sort() };
|
||||
}
|
||||
return { type: typeof arg, value: arg };
|
||||
}
|
||||
Reference in new issue
Block a user