@aduek/ne-sy 0.1.0-alpha.0

package/dist/validation.js

@@ -0,0 +1,226 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import * as addFormatsModule from "ajv-formats";
+export const ACTION_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://aduek.dev/schemas/action.schema.json",
+    title: "AduekAction",
+    type: "object",
+    required: ["id", "type", "actor", "target", "timestamp"],
+    additionalProperties: false,
+    properties: {
+        id: {
+            type: "string",
+            description: "Unique identifier for the proposed action.",
+        },
+        type: {
+            type: "string",
+            description: "Action type, such as http.request, tool.call, file.write, or message.send.",
+        },
+        actor: {
+            type: "object",
+            required: ["id", "kind"],
+            additionalProperties: true,
+            properties: {
+                id: { type: "string" },
+                kind: { type: "string", examples: ["agent", "workflow", "user"] },
+            },
+        },
+        target: {
+            type: "object",
+            required: ["id", "kind"],
+            additionalProperties: true,
+            properties: {
+                id: { type: "string" },
+                kind: { type: "string", examples: ["api", "file", "database", "human"] },
+                trustBoundary: { type: "string", examples: ["internal", "external"] },
+            },
+        },
+        input: {
+            description: "Action-specific input payload.",
+        },
+        metadata: {
+            type: "object",
+            additionalProperties: true,
+        },
+        timestamp: {
+            type: "string",
+            format: "date-time",
+        },
+    },
+};
+export const DECISION_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://aduek.dev/schemas/decision.schema.json",
+    title: "AduekDecision",
+    type: "object",
+    required: ["decision", "reason"],
+    additionalProperties: false,
+    properties: {
+        decision: {
+            type: "string",
+            enum: ["allow", "deny", "review", "log"],
+        },
+        reason: {
+            type: "string",
+        },
+        matchedPolicyIds: {
+            type: "array",
+            items: {
+                type: "string",
+            },
+            default: [],
+        },
+        metadata: {
+            type: "object",
+            additionalProperties: true,
+        },
+    },
+};
+export const POLICY_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://aduek.dev/schemas/policy.schema.json",
+    title: "AduekPolicyPack",
+    type: "object",
+    required: ["id", "version", "defaultDecision", "policies"],
+    additionalProperties: false,
+    properties: {
+        id: {
+            type: "string",
+            description: "Stable policy-pack identifier.",
+        },
+        version: {
+            type: "string",
+            description: "Policy-pack version used in audit evidence.",
+        },
+        defaultDecision: {
+            type: "string",
+            enum: ["allow", "deny", "review", "log"],
+            description: "Decision applied when no policy matches.",
+        },
+        defaultReason: {
+            type: "string",
+            description: "Human-readable reason used when the default decision applies.",
+        },
+        policies: {
+            type: "array",
+            items: {
+                $ref: "#/$defs/policy",
+            },
+        },
+    },
+    $defs: {
+        policy: {
+            type: "object",
+            required: ["id", "name", "effect", "conditions", "reason"],
+            additionalProperties: false,
+            properties: {
+                id: {
+                    type: "string",
+                },
+                name: {
+                    type: "string",
+                },
+                description: {
+                    type: "string",
+                },
+                effect: {
+                    type: "string",
+                    enum: ["allow", "deny", "review", "log"],
+                },
+                conditions: {
+                    type: "object",
+                    additionalProperties: true,
+                    description: "Portable condition tree evaluated by the verifier.",
+                },
+                reason: {
+                    type: "string",
+                },
+                metadata: {
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    },
+};
+export const AUDIT_EVENT_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://aduek.dev/schemas/audit-event.schema.json",
+    title: "AduekAuditEvent",
+    type: "object",
+    required: ["id", "action", "decision", "timestamp"],
+    additionalProperties: false,
+    properties: {
+        id: {
+            type: "string",
+        },
+        action: {
+            $ref: "action.schema.json",
+        },
+        decision: {
+            $ref: "decision.schema.json",
+        },
+        policyPackId: {
+            type: "string",
+        },
+        policyVersion: {
+            type: "string",
+        },
+        policyHash: {
+            type: "string",
+        },
+        actionHash: {
+            type: "string",
+        },
+        envelopeHash: {
+            type: "string",
+        },
+        evidenceHash: {
+            type: "string",
+        },
+        verifierVersion: {
+            type: "string",
+        },
+        runtime: {
+            type: "object",
+            additionalProperties: true,
+        },
+        timestamp: {
+            type: "string",
+            format: "date-time",
+        },
+    },
+};
+export const SDK_SCHEMAS = {
+    "action.schema.json": ACTION_SCHEMA,
+    "audit-event.schema.json": AUDIT_EVENT_SCHEMA,
+    "decision.schema.json": DECISION_SCHEMA,
+    "policy.schema.json": POLICY_SCHEMA,
+};
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const addFormats = addFormatsModule.default;
+addFormats(ajv);
+ajv.addSchema(ACTION_SCHEMA);
+ajv.addSchema(DECISION_SCHEMA);
+ajv.addSchema(POLICY_SCHEMA);
+ajv.addSchema(AUDIT_EVENT_SCHEMA);
+const validatePolicyPack = ajv.getSchema("https://aduek.dev/schemas/policy.schema.json");
+const validateAuditEvent = ajv.getSchema("https://aduek.dev/schemas/audit-event.schema.json");
+export function validatePolicyPackSchema(policyInput) {
+    if (!validatePolicyPack)
+        return ["schema_validation_error: <root>: policy schema unavailable"];
+    validatePolicyPack(policyInput);
+    return formatSchemaErrors(validatePolicyPack.errors);
+}
+export function validateAuditEventSchema(event) {
+    if (!validateAuditEvent)
+        return ["schema_validation_error: <root>: audit-event schema unavailable"];
+    validateAuditEvent(event);
+    return formatSchemaErrors(validateAuditEvent.errors);
+}
+function formatSchemaErrors(errors) {
+    return (errors ?? []).map((error) => {
+        const path = error.instancePath ? error.instancePath.slice(1).replaceAll("/", ".") : "<root>";
+        return `schema_validation_error: ${path}: ${error.message ?? "schema validation failed"}`;
+    });
+}

package/dist/verifier.d.ts

@@ -0,0 +1,13 @@
+import type { Decision, PolicyInput, VerificationResult, VerifyActionInput } from "./types.js";
+export declare function verifyAction(input: VerifyActionInput): Promise<Decision>;
+export declare function verifyActionWithEvent(input: VerifyActionInput): Promise<VerificationResult>;
+export declare function withAduek<Args extends unknown[], ReturnValue>(input: {
+    agent: unknown;
+    tool: (...args: Args) => ReturnValue | Promise<ReturnValue>;
+    policies: PolicyInput;
+    context?: unknown;
+    auditPath?: string;
+    actionType?: string;
+    target?: unknown;
+}): (...args: Args) => Promise<ReturnValue>;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../src/verifier.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAIpB,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAG9E;AAED,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAuC7B;AAED,wBAAgB,SAAS,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IACpE,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,QAAQ,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,WAAW,CAAC,CAuB1C"}

package/dist/verifier.js

@@ -0,0 +1,69 @@
+import { createAuditEvent, writeAuditEvent } from "./audit.js";
+import { createToolAction } from "./adapters.js";
+import { evaluatePolicies, policyHash, policyPackId, policyVersion, } from "./policy.js";
+import { AduekError as AduekErrorClass } from "./types.js";
+import { makeDecision } from "./utils.js";
+export async function verifyAction(input) {
+    const result = await verifyActionWithEvent(input);
+    return result.decision;
+}
+export async function verifyActionWithEvent(input) {
+    const failClosed = input.failClosed ?? true;
+    let decision;
+    try {
+        decision = evaluatePolicies(input.agent, input.action, input.context ?? {}, input.policies);
+    }
+    catch (error) {
+        if (!failClosed)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        decision = makeDecision({
+            decision: "review",
+            reason: `Verification failed closed: ${message}`,
+            matchedPolicyIds: [],
+            metadata: {
+                enforcementSource: "verification_error",
+                error: error instanceof Error ? error.name : "Error",
+                errorCategory: error instanceof AduekErrorClass ? error.category : "evaluation_error",
+                errorCode: error instanceof AduekErrorClass ? error.code : "unexpected_evaluation_error",
+                errorName: error instanceof Error ? error.name : "Error",
+                failClosed: true,
+            },
+        });
+    }
+    const auditEvent = createAuditEvent({
+        agent: input.agent,
+        action: input.action,
+        context: input.context ?? {},
+        decision,
+        policyPackId: policyPackId(input.policies),
+        policyVersion: policyVersion(input.policies),
+        policyHash: policyHash(input.policies),
+    });
+    if (input.auditPath) {
+        await writeAuditEvent(input.auditPath, auditEvent);
+    }
+    return { decision, auditEvent };
+}
+export function withAduek(input) {
+    return async (...args) => {
+        const action = createToolAction({
+            agent: input.agent,
+            tool: input.tool,
+            args,
+            actionType: input.actionType,
+            target: input.target,
+        });
+        const decision = await verifyAction({
+            agent: input.agent,
+            action,
+            context: input.context,
+            policies: input.policies,
+            auditPath: input.auditPath,
+        });
+        if (decision.allowed) {
+            return input.tool(...args);
+        }
+        throw new Error(decision.reason);
+    };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@aduek/ne-sy",
+  "version": "0.1.0-alpha.0",
+  "description": "Pre-action policy verification for AI agents.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hi-aduek/aduek-ne-sy.git",
+    "directory": "packages/typescript"
+  },
+  "homepage": "https://github.com/hi-aduek/aduek-ne-sy#readme",
+  "bugs": {
+    "url": "https://github.com/hi-aduek/aduek-ne-sy/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage --coverage.reportsDirectory ../../tmp/coverage/typescript"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-governance",
+    "agent-security",
+    "ai-safety",
+    "audit-logs",
+    "compliance",
+    "policy-engine",
+    "typescript"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "overrides": {
+    "fast-uri": "^3.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.5"
+  }
+}