apcore-js 0.1.0

package/tests/schema/test-loader.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { jsonSchemaToTypeBox } from '../../src/schema/loader.js';
+
+describe('jsonSchemaToTypeBox', () => {
+  it('converts string type', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'string' });
+    expect(Value.Check(schema, 'hello')).toBe(true);
+    expect(Value.Check(schema, 123)).toBe(false);
+  });
+
+  it('converts integer type', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'integer' });
+    expect(Value.Check(schema, 42)).toBe(true);
+    expect(Value.Check(schema, 3.14)).toBe(false);
+  });
+
+  it('converts number type', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'number' });
+    expect(Value.Check(schema, 3.14)).toBe(true);
+    expect(Value.Check(schema, 'abc')).toBe(false);
+  });
+
+  it('converts boolean type', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'boolean' });
+    expect(Value.Check(schema, true)).toBe(true);
+    expect(Value.Check(schema, 'true')).toBe(false);
+  });
+
+  it('converts null type', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'null' });
+    expect(Value.Check(schema, null)).toBe(true);
+    expect(Value.Check(schema, undefined)).toBe(false);
+  });
+
+  it('converts object with properties', () => {
+    const schema = jsonSchemaToTypeBox({
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' },
+      },
+      required: ['name'],
+    });
+    expect(Value.Check(schema, { name: 'Alice', age: 30 })).toBe(true);
+    expect(Value.Check(schema, { name: 'Alice' })).toBe(true);
+    expect(Value.Check(schema, { age: 30 })).toBe(false);
+  });
+
+  it('converts array type', () => {
+    const schema = jsonSchemaToTypeBox({
+      type: 'array',
+      items: { type: 'string' },
+    });
+    expect(Value.Check(schema, ['a', 'b'])).toBe(true);
+    expect(Value.Check(schema, [1, 2])).toBe(false);
+  });
+
+  it('converts enum', () => {
+    const schema = jsonSchemaToTypeBox({ enum: ['a', 'b', 'c'] });
+    expect(Value.Check(schema, 'a')).toBe(true);
+    expect(Value.Check(schema, 'd')).toBe(false);
+  });
+
+  it('converts anyOf', () => {
+    const schema = jsonSchemaToTypeBox({
+      anyOf: [{ type: 'string' }, { type: 'number' }],
+    });
+    expect(Value.Check(schema, 'hello')).toBe(true);
+    expect(Value.Check(schema, 42)).toBe(true);
+    expect(Value.Check(schema, true)).toBe(false);
+  });
+
+  it('returns Unknown for unrecognized schema', () => {
+    const schema = jsonSchemaToTypeBox({});
+    expect(Value.Check(schema, 'anything')).toBe(true);
+    expect(Value.Check(schema, 42)).toBe(true);
+  });
+
+  it('converts string with constraints', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'string', minLength: 2, maxLength: 5 });
+    expect(Value.Check(schema, 'ab')).toBe(true);
+    expect(Value.Check(schema, 'a')).toBe(false);
+    expect(Value.Check(schema, 'abcdef')).toBe(false);
+  });
+
+  it('converts object without properties', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'object' });
+    expect(Value.Check(schema, { any: 'value' })).toBe(true);
+  });
+
+  it('converts array without items', () => {
+    const schema = jsonSchemaToTypeBox({ type: 'array' });
+    expect(Value.Check(schema, [1, 'two', true])).toBe(true);
+  });
+});

package/tests/schema/test-ref-resolver.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+import { RefResolver } from '../../src/schema/ref-resolver.js';
+import { SchemaCircularRefError, SchemaNotFoundError } from '../../src/errors.js';
+
+describe('RefResolver', () => {
+  it('resolves local $ref', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { $ref: '#/definitions/NameType' },
+      },
+      definitions: {
+        NameType: { type: 'string' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    expect((resolved['properties'] as Record<string, unknown>)['name']).toEqual({ type: 'string' });
+  });
+
+  it('detects circular references', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      definitions: {
+        A: { $ref: '#/definitions/B' },
+        B: { $ref: '#/definitions/A' },
+      },
+      type: 'object',
+      properties: {
+        x: { $ref: '#/definitions/A' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaCircularRefError);
+  });
+
+  it('resolves nested $ref', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      type: 'object',
+      properties: {
+        user: { $ref: '#/definitions/User' },
+      },
+      definitions: {
+        User: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    const user = (resolved['properties'] as Record<string, unknown>)['user'] as Record<string, unknown>;
+    expect(user['type']).toBe('object');
+    expect(user['properties']).toBeDefined();
+  });
+
+  it('throws SchemaNotFoundError for missing pointer segment', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: '#/definitions/Missing' },
+      },
+      definitions: {},
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaNotFoundError);
+  });
+
+  it('clearCache works', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    resolver.clearCache();
+    // Should not throw
+  });
+
+  it('respects max depth', () => {
+    const resolver = new RefResolver('/tmp/schemas', 2);
+    // Properties must come before definitions so the $ref chain isn't
+    // collapsed by in-place resolution of definitions first.
+    const schema = {
+      type: 'object',
+      properties: {
+        x: { $ref: '#/definitions/A' },
+      },
+      definitions: {
+        A: { $ref: '#/definitions/B' },
+        B: { $ref: '#/definitions/C' },
+        C: { type: 'string' },
+      },
+    };
+    expect(() => resolver.resolve(schema)).toThrow(SchemaCircularRefError);
+  });
+
+  it('resolves schema without $ref unchanged', () => {
+    const resolver = new RefResolver('/tmp/schemas');
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+    };
+    const resolved = resolver.resolve(schema);
+    expect(resolved).toEqual(schema);
+  });
+});

package/tests/schema/test-strict.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest';
+import { toStrictSchema, applyLlmDescriptions, stripExtensions } from '../../src/schema/strict.js';
+
+describe('toStrictSchema', () => {
+  it('adds additionalProperties: false', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+      },
+      required: ['name'],
+    };
+    const strict = toStrictSchema(schema);
+    expect(strict['additionalProperties']).toBe(false);
+  });
+
+  it('makes all properties required', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' },
+      },
+      required: ['name'],
+    };
+    const strict = toStrictSchema(schema);
+    expect(strict['required']).toEqual(['age', 'name']);
+  });
+
+  it('makes optional properties nullable', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' },
+      },
+      required: ['name'],
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['age']['type']).toEqual(['integer', 'null']);
+    expect(props['name']['type']).toBe('string');
+  });
+
+  it('does not modify original schema', () => {
+    const schema: Record<string, unknown> = {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+    };
+    toStrictSchema(schema);
+    expect(schema['additionalProperties']).toBeUndefined();
+  });
+
+  it('strips x- extensions', () => {
+    const schema = {
+      type: 'object',
+      'x-sensitive': true,
+      properties: {
+        name: { type: 'string', 'x-llm-description': 'Name field' },
+      },
+    };
+    const strict = toStrictSchema(schema);
+    expect(strict['x-sensitive']).toBeUndefined();
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['name']['x-llm-description']).toBeUndefined();
+  });
+
+  it('strips default values', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', default: 'world' },
+      },
+    };
+    const strict = toStrictSchema(schema);
+    const props = strict['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['name']['default']).toBeUndefined();
+  });
+});
+
+describe('applyLlmDescriptions', () => {
+  it('replaces description with x-llm-description', () => {
+    const schema = {
+      description: 'Original',
+      'x-llm-description': 'LLM version',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Name',
+          'x-llm-description': 'User name for LLM',
+        },
+      },
+    };
+    applyLlmDescriptions(schema);
+    expect(schema['description']).toBe('LLM version');
+    expect((schema['properties'] as Record<string, Record<string, unknown>>)['name']['description']).toBe('User name for LLM');
+  });
+
+  it('does not modify without x-llm-description', () => {
+    const schema = { description: 'Original' };
+    applyLlmDescriptions(schema);
+    expect(schema['description']).toBe('Original');
+  });
+});
+
+describe('stripExtensions', () => {
+  it('removes x- prefixed keys', () => {
+    const schema: Record<string, unknown> = {
+      type: 'string',
+      'x-custom': 'value',
+      'x-another': 123,
+    };
+    stripExtensions(schema);
+    expect(schema['x-custom']).toBeUndefined();
+    expect(schema['x-another']).toBeUndefined();
+    expect(schema['type']).toBe('string');
+  });
+
+  it('removes default key', () => {
+    const schema: Record<string, unknown> = {
+      type: 'string',
+      default: 'hello',
+    };
+    stripExtensions(schema);
+    expect(schema['default']).toBeUndefined();
+  });
+
+  it('handles nested structures', () => {
+    const schema: Record<string, unknown> = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', 'x-sensitive': true },
+      },
+    };
+    stripExtensions(schema);
+    const props = schema['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['name']['x-sensitive']).toBeUndefined();
+  });
+});

package/tests/schema/test-validator.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { SchemaValidator } from '../../src/schema/validator.js';
+import { SchemaValidationError } from '../../src/errors.js';
+
+describe('SchemaValidator', () => {
+  it('validates correct data', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ name: Type.String() });
+    const result = validator.validate({ name: 'Alice' }, schema);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('rejects invalid data', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ name: Type.String() });
+    const result = validator.validate({ name: 123 }, schema);
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  it('validates without coercion', () => {
+    const validator = new SchemaValidator(false);
+    const schema = Type.Object({ x: Type.Number() });
+    const result = validator.validate({ x: 42 }, schema);
+    expect(result.valid).toBe(true);
+  });
+
+  it('validateInput returns data on valid input', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ x: Type.Number() });
+    const data = validator.validateInput({ x: 42 }, schema);
+    expect(data['x']).toBe(42);
+  });
+
+  it('validateInput throws on invalid input', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ x: Type.Number() });
+    expect(() => validator.validateInput({ x: 'not-a-number' }, schema)).toThrow(SchemaValidationError);
+  });
+
+  it('validateOutput returns data on valid output', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ result: Type.String() });
+    const data = validator.validateOutput({ result: 'ok' }, schema);
+    expect(data['result']).toBe('ok');
+  });
+
+  it('validateOutput throws on invalid output', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ result: Type.String() });
+    expect(() => validator.validateOutput({ result: 123 }, schema)).toThrow(SchemaValidationError);
+  });
+
+  it('error details include path and message', () => {
+    const validator = new SchemaValidator();
+    const schema = Type.Object({ nested: Type.Object({ x: Type.Number() }) });
+    const result = validator.validate({ nested: { x: 'bad' } }, schema);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].path).toBeDefined();
+    expect(result.errors[0].message).toBeDefined();
+  });
+});

package/tests/test-acl.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect } from 'vitest';
+import { ACL } from '../src/acl.js';
+import { Context, createIdentity } from '../src/context.js';
+
+function makeContext(opts: {
+  callerId?: string | null;
+  callChain?: string[];
+  identityType?: string;
+  roles?: string[];
+} = {}): Context {
+  const identity = opts.identityType
+    ? createIdentity('test-user', opts.identityType, opts.roles ?? [])
+    : null;
+  return new Context(
+    'trace-test',
+    opts.callerId ?? null,
+    opts.callChain ?? [],
+    null,
+    identity,
+  );
+}
+
+describe('ACL', () => {
+  it('allows access when allow rule matches', () => {
+    const acl = new ACL([
+      { callers: ['module.a'], targets: ['module.b'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('module.a', 'module.b')).toBe(true);
+  });
+
+  it('denies access when deny rule matches', () => {
+    const acl = new ACL([
+      { callers: ['module.a'], targets: ['module.b'], effect: 'deny', description: '' },
+    ]);
+    expect(acl.check('module.a', 'module.b')).toBe(false);
+  });
+
+  it('returns default deny when no rule matches', () => {
+    const acl = new ACL([
+      { callers: ['module.a'], targets: ['module.b'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('module.x', 'module.y')).toBe(false);
+  });
+
+  it('first-match-wins: deny before allow', () => {
+    const acl = new ACL([
+      { callers: ['module.a'], targets: ['module.b'], effect: 'deny', description: '' },
+      { callers: ['module.a'], targets: ['module.b'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('module.a', 'module.b')).toBe(false);
+  });
+
+  it('first-match-wins: allow before deny', () => {
+    const acl = new ACL([
+      { callers: ['module.a'], targets: ['module.b'], effect: 'allow', description: '' },
+      { callers: ['module.a'], targets: ['module.b'], effect: 'deny', description: '' },
+    ]);
+    expect(acl.check('module.a', 'module.b')).toBe(true);
+  });
+
+  it('default effect allow when no rules match', () => {
+    const acl = new ACL([], 'allow');
+    expect(acl.check('any', 'thing')).toBe(true);
+  });
+
+  it('maps null callerId to @external', () => {
+    const acl = new ACL([
+      { callers: ['@external'], targets: ['public.api'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check(null, 'public.api')).toBe(true);
+  });
+
+  it('does not match @external for real module caller', () => {
+    const acl = new ACL([
+      { callers: ['@external'], targets: ['public.api'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('module.a', 'public.api')).toBe(false);
+  });
+
+  it('wildcard * matches all callers', () => {
+    const acl = new ACL([
+      { callers: ['*'], targets: ['public.api'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('module.a', 'public.api')).toBe(true);
+    expect(acl.check('module.b', 'public.api')).toBe(true);
+  });
+
+  it('wildcard * matches all targets', () => {
+    const acl = new ACL([
+      { callers: ['module.admin'], targets: ['*'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('module.admin', 'anything')).toBe(true);
+  });
+
+  it('prefix wildcard matching', () => {
+    const acl = new ACL([
+      { callers: ['core.*'], targets: ['data.*'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('core.auth', 'data.store')).toBe(true);
+    expect(acl.check('other.x', 'data.y')).toBe(false);
+  });
+
+  it('@system matches system identity type', () => {
+    const acl = new ACL([
+      { callers: ['@system'], targets: ['*'], effect: 'allow', description: '' },
+    ]);
+    const ctx = makeContext({ identityType: 'system' });
+    expect(acl.check('any.module', 'any.target', ctx)).toBe(true);
+  });
+
+  it('@system does not match non-system identity', () => {
+    const acl = new ACL([
+      { callers: ['@system'], targets: ['*'], effect: 'allow', description: '' },
+    ]);
+    const ctx = makeContext({ identityType: 'user' });
+    expect(acl.check('any.module', 'any.target', ctx)).toBe(false);
+  });
+
+  it('conditions: identity_types allows matching type', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['admin'], effect: 'allow', description: '',
+      conditions: { identity_types: ['admin'] },
+    }]);
+    const ctx = makeContext({ identityType: 'admin' });
+    expect(acl.check('mod.a', 'admin', ctx)).toBe(true);
+  });
+
+  it('conditions: identity_types denies non-matching type', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['admin'], effect: 'allow', description: '',
+      conditions: { identity_types: ['admin'] },
+    }]);
+    const ctx = makeContext({ identityType: 'user' });
+    expect(acl.check('mod.a', 'admin', ctx)).toBe(false);
+  });
+
+  it('conditions: roles allows matching role', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['settings'], effect: 'allow', description: '',
+      conditions: { roles: ['editor', 'admin'] },
+    }]);
+    const ctx = makeContext({ identityType: 'user', roles: ['editor'] });
+    expect(acl.check('mod.a', 'settings', ctx)).toBe(true);
+  });
+
+  it('conditions: roles denies missing role', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['settings'], effect: 'allow', description: '',
+      conditions: { roles: ['admin'] },
+    }]);
+    const ctx = makeContext({ identityType: 'user', roles: ['viewer'] });
+    expect(acl.check('mod.a', 'settings', ctx)).toBe(false);
+  });
+
+  it('conditions: max_call_depth allows within limit', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['deep'], effect: 'allow', description: '',
+      conditions: { max_call_depth: 3 },
+    }]);
+    const ctx = makeContext({ callChain: ['a', 'b'] });
+    expect(acl.check('mod.a', 'deep', ctx)).toBe(true);
+  });
+
+  it('conditions: max_call_depth denies exceeding limit', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['deep'], effect: 'allow', description: '',
+      conditions: { max_call_depth: 2 },
+    }]);
+    const ctx = makeContext({ callChain: ['a', 'b', 'c'] });
+    expect(acl.check('mod.a', 'deep', ctx)).toBe(false);
+  });
+
+  it('conditions fail when no context provided', () => {
+    const acl = new ACL([{
+      callers: ['*'], targets: ['deep'], effect: 'allow', description: '',
+      conditions: { max_call_depth: 5 },
+    }]);
+    expect(acl.check('mod.a', 'deep')).toBe(false);
+  });
+
+  it('addRule adds to highest priority', () => {
+    const acl = new ACL([
+      { callers: ['*'], targets: ['*'], effect: 'deny', description: '' },
+    ]);
+    expect(acl.check('mod.a', 'mod.b')).toBe(false);
+
+    acl.addRule({ callers: ['mod.a'], targets: ['mod.b'], effect: 'allow', description: '' });
+    expect(acl.check('mod.a', 'mod.b')).toBe(true);
+  });
+
+  it('removeRule removes matching rule', () => {
+    const acl = new ACL([
+      { callers: ['mod.a'], targets: ['mod.b'], effect: 'allow', description: '' },
+    ]);
+    expect(acl.check('mod.a', 'mod.b')).toBe(true);
+
+    const removed = acl.removeRule(['mod.a'], ['mod.b']);
+    expect(removed).toBe(true);
+    expect(acl.check('mod.a', 'mod.b')).toBe(false);
+  });
+
+  it('removeRule returns false when no match', () => {
+    const acl = new ACL([]);
+    expect(acl.removeRule(['x'], ['y'])).toBe(false);
+  });
+});