apcore-js 0.1.0

package/planning/acl-system/state.json

@@ -0,0 +1,76 @@
+{
+  "feature": "acl-system",
+  "created": "2026-02-16T00:00:00Z",
+  "updated": "2026-02-16T00:00:00Z",
+  "status": "completed",
+  "execution_order": [
+    "acl-rule",
+    "pattern-matching",
+    "conditional-rules",
+    "acl-core",
+    "yaml-loading"
+  ],
+  "progress": {
+    "total_tasks": 5,
+    "completed": 5,
+    "in_progress": 0,
+    "pending": 0
+  },
+  "tasks": [
+    {
+      "id": "acl-rule",
+      "file": "tasks/acl-rule.md",
+      "title": "ACLRule Interface Definition",
+      "status": "completed",
+      "started_at": "2026-02-16T08:00:00Z",
+      "completed_at": "2026-02-16T08:45:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "pattern-matching",
+      "file": "tasks/pattern-matching.md",
+      "title": "matchPattern() Wildcard Matching (Algorithm A08)",
+      "status": "completed",
+      "started_at": "2026-02-16T08:45:00Z",
+      "completed_at": "2026-02-16T10:15:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "conditional-rules",
+      "file": "tasks/conditional-rules.md",
+      "title": "Conditional Rule Evaluation (identity_types, roles, max_call_depth)",
+      "status": "completed",
+      "started_at": "2026-02-16T10:15:00Z",
+      "completed_at": "2026-02-16T11:45:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "acl-core",
+      "file": "tasks/acl-core.md",
+      "title": "ACL Class with check(), addRule(), removeRule()",
+      "status": "completed",
+      "started_at": "2026-02-16T11:45:00Z",
+      "completed_at": "2026-02-16T14:00:00Z",
+      "assignee": null,
+      "commits": []
+    },
+    {
+      "id": "yaml-loading",
+      "file": "tasks/yaml-loading.md",
+      "title": "ACL.load() from YAML and reload() Support",
+      "status": "completed",
+      "started_at": "2026-02-16T14:00:00Z",
+      "completed_at": "2026-02-16T15:30:00Z",
+      "assignee": null,
+      "commits": []
+    }
+  ],
+  "metadata": {
+    "source_doc": "planning/features/acl-system.md",
+    "created_by": "code-forge",
+    "version": "1.0"
+  }
+}

package/planning/acl-system/tasks/acl-core.md

@@ -0,0 +1,226 @@
+# Task: ACL Class with check(), addRule(), removeRule()
+
+## Goal
+
+Implement the `ACL` class that manages an ordered list of `ACLRule` objects and provides first-match-wins permission evaluation via `check()`, runtime rule mutation via `addRule()` and `removeRule()`, and a configurable default effect.
+
+## Files Involved
+
+- `src/acl.ts` -- ACL class implementation (~188 lines total including YAML loading)
+- `src/errors.ts` -- `ACLDeniedError` (used by executor, not ACL directly)
+- `src/context.ts` -- `Context` and `Identity` types consumed by `check()`
+
+## Steps (TDD)
+
+### 1. Write failing tests for ACL constructor and default behavior
+
+```typescript
+// tests/acl.test.ts
+import { describe, it, expect } from 'vitest';
+import { ACL } from '../src/acl.js';
+import type { ACLRule } from '../src/acl.js';
+
+describe('ACL constructor', () => {
+  it('should default to deny when no rules match', () => {
+    const acl = new ACL([]);
+    expect(acl.check('moduleA', 'moduleB')).toBe(false);
+  });
+
+  it('should respect custom default effect', () => {
+    const acl = new ACL([], 'allow');
+    expect(acl.check('moduleA', 'moduleB')).toBe(true);
+  });
+});
+```
+
+### 2. Implement constructor with rules copy and default effect
+
+```typescript
+export class ACL {
+  private _rules: ACLRule[];
+  private _defaultEffect: string;
+
+  constructor(rules: ACLRule[], defaultEffect: string = 'deny') {
+    this._rules = [...rules];
+    this._defaultEffect = defaultEffect;
+  }
+}
+```
+
+### 3. Write failing tests for check() first-match-wins
+
+```typescript
+describe('ACL.check()', () => {
+  it('should allow when first matching rule has allow effect', () => {
+    const rules: ACLRule[] = [
+      { callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'test' },
+    ];
+    const acl = new ACL(rules);
+    expect(acl.check('moduleA', 'moduleB')).toBe(true);
+  });
+
+  it('should deny when first matching rule has deny effect', () => {
+    const rules: ACLRule[] = [
+      { callers: ['moduleA'], targets: ['moduleB'], effect: 'deny', description: 'test' },
+    ];
+    const acl = new ACL(rules);
+    expect(acl.check('moduleA', 'moduleB')).toBe(false);
+  });
+
+  it('should normalize null caller to @external', () => {
+    const rules: ACLRule[] = [
+      { callers: ['@external'], targets: ['auth'], effect: 'allow', description: 'test' },
+    ];
+    const acl = new ACL(rules);
+    expect(acl.check(null, 'auth')).toBe(true);
+  });
+
+  it('should use first matching rule and ignore later rules', () => {
+    const rules: ACLRule[] = [
+      { callers: ['moduleA'], targets: ['moduleB'], effect: 'deny', description: 'deny first' },
+      { callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'allow second' },
+    ];
+    const acl = new ACL(rules);
+    expect(acl.check('moduleA', 'moduleB')).toBe(false);
+  });
+
+  it('should fall through to default when no rules match', () => {
+    const rules: ACLRule[] = [
+      { callers: ['moduleX'], targets: ['moduleY'], effect: 'allow', description: 'unrelated' },
+    ];
+    const acl = new ACL(rules, 'deny');
+    expect(acl.check('moduleA', 'moduleB')).toBe(false);
+  });
+});
+```
+
+### 4. Implement check() with _matchesRule and _matchPattern
+
+```typescript
+check(callerId: string | null, targetId: string, context?: Context | null): boolean {
+  const effectiveCaller = callerId === null ? '@external' : callerId;
+  const rules = [...this._rules];
+
+  for (const rule of rules) {
+    if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
+      return rule.effect === 'allow';
+    }
+  }
+
+  return this._defaultEffect === 'allow';
+}
+
+private _matchPattern(pattern: string, value: string, context: Context | null): boolean {
+  if (pattern === '@external') return value === '@external';
+  if (pattern === '@system') {
+    return context !== null && context.identity !== null && context.identity.type === 'system';
+  }
+  return matchPattern(pattern, value);
+}
+
+private _matchesRule(rule: ACLRule, caller: string, target: string, context: Context | null): boolean {
+  const callerMatch = rule.callers.some((p) => this._matchPattern(p, caller, context));
+  if (!callerMatch) return false;
+
+  const targetMatch = rule.targets.some((p) => this._matchPattern(p, target, context));
+  if (!targetMatch) return false;
+
+  if (rule.conditions != null) {
+    if (!this._checkConditions(rule.conditions, context)) return false;
+  }
+
+  return true;
+}
+```
+
+### 5. Write failing tests for addRule() and removeRule()
+
+```typescript
+describe('ACL.addRule()', () => {
+  it('should prepend rule to beginning of list', () => {
+    const acl = new ACL([
+      { callers: ['*'], targets: ['*'], effect: 'deny', description: 'deny all' },
+    ]);
+    acl.addRule({ callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'allow A->B' });
+    // New rule is first, so it should match before the deny-all
+    expect(acl.check('moduleA', 'moduleB')).toBe(true);
+  });
+});
+
+describe('ACL.removeRule()', () => {
+  it('should remove rule matching callers and targets', () => {
+    const acl = new ACL([
+      { callers: ['moduleA'], targets: ['moduleB'], effect: 'allow', description: 'test' },
+    ]);
+    const removed = acl.removeRule(['moduleA'], ['moduleB']);
+    expect(removed).toBe(true);
+    expect(acl.check('moduleA', 'moduleB')).toBe(false); // falls to default deny
+  });
+
+  it('should return false when no matching rule found', () => {
+    const acl = new ACL([]);
+    expect(acl.removeRule(['moduleA'], ['moduleB'])).toBe(false);
+  });
+
+  it('should use JSON.stringify for array comparison', () => {
+    const acl = new ACL([
+      { callers: ['a', 'b'], targets: ['c'], effect: 'allow', description: 'test' },
+    ]);
+    // Different order should not match
+    expect(acl.removeRule(['b', 'a'], ['c'])).toBe(false);
+    // Same order should match
+    expect(acl.removeRule(['a', 'b'], ['c'])).toBe(true);
+  });
+});
+```
+
+### 6. Implement addRule() and removeRule()
+
+```typescript
+addRule(rule: ACLRule): void {
+  this._rules.unshift(rule);
+}
+
+removeRule(callers: string[], targets: string[]): boolean {
+  for (let i = 0; i < this._rules.length; i++) {
+    const rule = this._rules[i];
+    if (
+      JSON.stringify(rule.callers) === JSON.stringify(callers) &&
+      JSON.stringify(rule.targets) === JSON.stringify(targets)
+    ) {
+      this._rules.splice(i, 1);
+      return true;
+    }
+  }
+  return false;
+}
+```
+
+### 7. Run full test suite and type-check
+
+Run `tsc --noEmit` and `vitest` to confirm everything passes.
+
+## Acceptance Criteria
+
+- [x] `ACL` constructor accepts `rules` array and optional `defaultEffect` (default `'deny'`)
+- [x] Constructor shallow-copies the rules array to prevent external mutation
+- [x] `check()` returns `boolean` using first-match-wins evaluation
+- [x] Null `callerId` is normalized to `'@external'`
+- [x] `@external` pattern matches only the `@external` sentinel value
+- [x] `@system` pattern checks `context.identity.type === 'system'`
+- [x] Non-special patterns delegate to `matchPattern()` from `utils/pattern.ts`
+- [x] Falls through to `_defaultEffect` when no rule matches
+- [x] `addRule()` prepends the rule to the beginning of the list
+- [x] `removeRule()` uses `JSON.stringify` for caller/target array comparison and returns `boolean`
+- [x] `removeRule()` only removes the first matching rule
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## Dependencies
+
+- **acl-rule** -- ACLRule interface definition
+- **pattern-matching** -- matchPattern() utility
+- **conditional-rules** -- _checkConditions() method
+
+## Estimated Time
+
+3 hours

package/planning/acl-system/tasks/acl-rule.md

@@ -0,0 +1,92 @@
+# Task: ACLRule Interface Definition
+
+## Goal
+
+Define the `ACLRule` TypeScript interface that represents a single access control rule, specifying caller patterns, target patterns, an effect (allow/deny), a human-readable description, and optional conditions for conditional evaluation.
+
+## Files Involved
+
+- `src/acl.ts` -- Interface definition exported alongside the ACL class
+
+## Steps (TDD)
+
+### 1. Write failing tests for ACLRule shape
+
+```typescript
+// tests/acl.test.ts
+import { describe, it, expect } from 'vitest';
+import type { ACLRule } from '../src/acl.js';
+
+describe('ACLRule interface', () => {
+  it('should accept a fully-specified rule', () => {
+    const rule: ACLRule = {
+      callers: ['moduleA', 'moduleB'],
+      targets: ['moduleC'],
+      effect: 'allow',
+      description: 'Allow A and B to call C',
+      conditions: { roles: ['admin'] },
+    };
+    expect(rule.callers).toEqual(['moduleA', 'moduleB']);
+    expect(rule.targets).toEqual(['moduleC']);
+    expect(rule.effect).toBe('allow');
+    expect(rule.description).toBe('Allow A and B to call C');
+    expect(rule.conditions).toEqual({ roles: ['admin'] });
+  });
+
+  it('should accept a rule with no conditions', () => {
+    const rule: ACLRule = {
+      callers: ['*'],
+      targets: ['*'],
+      effect: 'deny',
+      description: 'Deny all by default',
+    };
+    expect(rule.conditions).toBeUndefined();
+  });
+
+  it('should accept null conditions', () => {
+    const rule: ACLRule = {
+      callers: ['@external'],
+      targets: ['auth.*'],
+      effect: 'allow',
+      description: 'Allow external to auth modules',
+      conditions: null,
+    };
+    expect(rule.conditions).toBeNull();
+  });
+});
+```
+
+### 2. Define the ACLRule interface
+
+```typescript
+// src/acl.ts
+export interface ACLRule {
+  callers: string[];
+  targets: string[];
+  effect: string;
+  description: string;
+  conditions?: Record<string, unknown> | null;
+}
+```
+
+### 3. Verify type-check and tests pass
+
+Run `tsc --noEmit` to confirm no type errors, then run `vitest` to confirm all tests pass.
+
+## Acceptance Criteria
+
+- [x] `ACLRule` interface is exported from `src/acl.ts`
+- [x] `callers` is `string[]` representing caller module ID patterns
+- [x] `targets` is `string[]` representing target module ID patterns
+- [x] `effect` is `string` (validated as `'allow'` | `'deny'` at runtime during YAML loading)
+- [x] `description` is `string` for human-readable rule documentation
+- [x] `conditions` is optional `Record<string, unknown> | null` for conditional evaluation
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## Dependencies
+
+- None (this is a standalone type definition)
+
+## Estimated Time
+
+1 hour

package/planning/acl-system/tasks/conditional-rules.md

@@ -0,0 +1,259 @@
+# Task: Conditional Rule Evaluation (_checkConditions)
+
+## Goal
+
+Implement the `_checkConditions()` private method on the `ACL` class that evaluates optional conditions attached to ACL rules. Conditions use AND logic: all present condition keys must pass for the rule to match. Supported conditions are `identity_types`, `roles`, and `max_call_depth`.
+
+## Files Involved
+
+- `src/acl.ts` -- `_checkConditions()` private method on the ACL class
+- `src/context.ts` -- `Context` class (provides `identity` and `callChain`) and `Identity` interface (provides `type` and `roles`)
+
+## Steps (TDD)
+
+### 1. Write failing tests for identity_types condition
+
+```typescript
+// tests/acl.test.ts
+import { describe, it, expect } from 'vitest';
+import { ACL } from '../src/acl.js';
+import type { ACLRule } from '../src/acl.js';
+import type { Context } from '../src/context.js';
+
+// Helper to create a minimal mock context
+function mockContext(overrides: {
+  identityType?: string;
+  identityRoles?: string[];
+  callChainLength?: number;
+} = {}): Context {
+  return {
+    identity: overrides.identityType !== undefined ? {
+      id: 'test-user',
+      type: overrides.identityType,
+      roles: overrides.identityRoles ?? [],
+      attrs: {},
+    } : null,
+    callChain: Array(overrides.callChainLength ?? 0).fill('module'),
+  } as unknown as Context;
+}
+
+describe('_checkConditions via check()', () => {
+  describe('identity_types condition', () => {
+    const rules: ACLRule[] = [
+      {
+        callers: ['*'],
+        targets: ['admin.*'],
+        effect: 'allow',
+        description: 'Allow system callers',
+        conditions: { identity_types: ['system', 'service'] },
+      },
+    ];
+
+    it('should allow when identity type matches', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'system' });
+      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(true);
+    });
+
+    it('should deny when identity type does not match', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user' });
+      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
+    });
+
+    it('should deny when identity is null', () => {
+      const acl = new ACL(rules);
+      const ctx = { identity: null, callChain: [] } as unknown as Context;
+      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
+    });
+  });
+});
+```
+
+### 2. Write failing tests for roles condition
+
+```typescript
+  describe('roles condition', () => {
+    const rules: ACLRule[] = [
+      {
+        callers: ['*'],
+        targets: ['admin.*'],
+        effect: 'allow',
+        description: 'Allow admin role',
+        conditions: { roles: ['admin', 'superadmin'] },
+      },
+    ];
+
+    it('should allow when identity has at least one matching role', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user', identityRoles: ['admin'] });
+      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(true);
+    });
+
+    it('should deny when identity has no matching roles', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user', identityRoles: ['viewer'] });
+      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
+    });
+
+    it('should deny when identity is null', () => {
+      const acl = new ACL(rules);
+      const ctx = { identity: null, callChain: [] } as unknown as Context;
+      expect(acl.check('moduleA', 'admin.panel', ctx)).toBe(false);
+    });
+  });
+```
+
+### 3. Write failing tests for max_call_depth condition
+
+```typescript
+  describe('max_call_depth condition', () => {
+    const rules: ACLRule[] = [
+      {
+        callers: ['*'],
+        targets: ['recursive.*'],
+        effect: 'allow',
+        description: 'Allow with depth limit',
+        conditions: { max_call_depth: 3 },
+      },
+    ];
+
+    it('should allow when call chain is within limit', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user', callChainLength: 2 });
+      expect(acl.check('moduleA', 'recursive.handler', ctx)).toBe(true);
+    });
+
+    it('should allow when call chain is exactly at limit', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user', callChainLength: 3 });
+      expect(acl.check('moduleA', 'recursive.handler', ctx)).toBe(true);
+    });
+
+    it('should deny when call chain exceeds limit', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user', callChainLength: 4 });
+      expect(acl.check('moduleA', 'recursive.handler', ctx)).toBe(false);
+    });
+  });
+```
+
+### 4. Write failing tests for AND logic across multiple conditions
+
+```typescript
+  describe('AND logic across conditions', () => {
+    const rules: ACLRule[] = [
+      {
+        callers: ['*'],
+        targets: ['sensitive.*'],
+        effect: 'allow',
+        description: 'Require admin role AND system type AND depth <= 2',
+        conditions: {
+          identity_types: ['system'],
+          roles: ['admin'],
+          max_call_depth: 2,
+        },
+      },
+    ];
+
+    it('should allow when all conditions pass', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'system', identityRoles: ['admin'], callChainLength: 1 });
+      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(true);
+    });
+
+    it('should deny when one condition fails (wrong type)', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'user', identityRoles: ['admin'], callChainLength: 1 });
+      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(false);
+    });
+
+    it('should deny when one condition fails (wrong role)', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'system', identityRoles: ['viewer'], callChainLength: 1 });
+      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(false);
+    });
+
+    it('should deny when one condition fails (depth exceeded)', () => {
+      const acl = new ACL(rules);
+      const ctx = mockContext({ identityType: 'system', identityRoles: ['admin'], callChainLength: 5 });
+      expect(acl.check('moduleA', 'sensitive.data', ctx)).toBe(false);
+    });
+  });
+```
+
+### 5. Write failing test for null context with conditions
+
+```typescript
+  describe('null context with conditions', () => {
+    it('should deny when context is null and conditions are present', () => {
+      const rules: ACLRule[] = [
+        {
+          callers: ['*'],
+          targets: ['*'],
+          effect: 'allow',
+          description: 'conditional rule',
+          conditions: { roles: ['admin'] },
+        },
+      ];
+      const acl = new ACL(rules);
+      expect(acl.check('moduleA', 'moduleB', null)).toBe(false);
+    });
+  });
+```
+
+### 6. Implement _checkConditions()
+
+```typescript
+private _checkConditions(conditions: Record<string, unknown>, context: Context | null): boolean {
+  // Null context cannot satisfy any conditions
+  if (context === null) return false;
+
+  // identity_types: caller's identity.type must be in the list
+  if ('identity_types' in conditions) {
+    const types = conditions['identity_types'] as string[];
+    if (context.identity === null || !types.includes(context.identity.type)) return false;
+  }
+
+  // roles: caller's identity must have at least one matching role (OR within roles, AND with other conditions)
+  if ('roles' in conditions) {
+    const roles = conditions['roles'] as string[];
+    if (context.identity === null) return false;
+    const identityRoles = new Set(context.identity.roles);
+    if (!roles.some((r) => identityRoles.has(r))) return false;
+  }
+
+  // max_call_depth: call chain length must not exceed the limit
+  if ('max_call_depth' in conditions) {
+    const maxDepth = conditions['max_call_depth'] as number;
+    if (context.callChain.length > maxDepth) return false;
+  }
+
+  return true;
+}
+```
+
+### 7. Run full test suite and type-check
+
+Run `tsc --noEmit` and `vitest` to confirm everything passes.
+
+## Acceptance Criteria
+
+- [x] `_checkConditions()` returns `false` when context is `null`
+- [x] `identity_types` condition checks `context.identity.type` is in the allowed list
+- [x] `identity_types` returns `false` when `context.identity` is `null`
+- [x] `roles` condition checks that at least one role in the condition list matches a role in `context.identity.roles` (OR within roles)
+- [x] `roles` returns `false` when `context.identity` is `null`
+- [x] `roles` uses `Set` for efficient lookup on the identity's roles
+- [x] `max_call_depth` condition checks `context.callChain.length <= maxDepth`
+- [x] Multiple conditions use AND logic: all present conditions must pass
+- [x] Unknown condition keys are silently ignored (forward-compatible)
+- [x] All tests pass with `vitest`; zero errors from `tsc --noEmit`
+
+## Dependencies
+
+- **acl-rule** -- ACLRule interface (conditions field definition)
+
+## Estimated Time
+
+2 hours