@brninpay/core 0.1.0

package/test/decision-resolver.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { DecisionResolver } from '../src/decision-resolver.js'
+import type { PolicyResult } from '../src/types.js'
+
+function makeResult(decision: PolicyResult['decision']): PolicyResult {
+  return {
+    policyId: 'pol_1',
+    policyType: 'test',
+    version: '1',
+    decision,
+    reason: { code: 'test', message: 'test' },
+    evaluatedAt: new Date().toISOString(),
+  }
+}
+
+describe('DecisionResolver', () => {
+  it('returns denied for empty results', () => {
+    expect(DecisionResolver.resolve([])).toBe('denied')
+  })
+
+  it('returns approved for single pass', () => {
+    expect(DecisionResolver.resolve([makeResult('pass')])).toBe('approved')
+  })
+
+  it('returns denied for single deny', () => {
+    expect(DecisionResolver.resolve([makeResult('deny')])).toBe('denied')
+  })
+
+  it('returns pending-review for single review', () => {
+    expect(DecisionResolver.resolve([makeResult('review')])).toBe('pending-review')
+  })
+
+  it('deny overrides pass', () => {
+    const results = [makeResult('pass'), makeResult('deny'), makeResult('pass')]
+    expect(DecisionResolver.resolve(results)).toBe('denied')
+  })
+
+  it('deny overrides review', () => {
+    const results = [makeResult('review'), makeResult('deny')]
+    expect(DecisionResolver.resolve(results)).toBe('denied')
+  })
+
+  it('review overrides pass', () => {
+    const results = [makeResult('pass'), makeResult('review')]
+    expect(DecisionResolver.resolve(results)).toBe('pending-review')
+  })
+
+  it('returns approved for all passes', () => {
+    const results = [makeResult('pass'), makeResult('pass'), makeResult('pass')]
+    expect(DecisionResolver.resolve(results)).toBe('approved')
+  })
+})

package/test/errors.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest'
+import {
+  AuthorizationError,
+  BudgetExhaustedError,
+  AllowlistDeniedError,
+  RateLimitExceededError,
+  AuthorizationExpiredError,
+  ExecutionError,
+  NetworkError,
+  GasEstimationError,
+  BroadcastError,
+  ReorgDetectedError,
+} from '../src/errors.js'
+
+describe('AuthorizationError', () => {
+  it('creates with code and message', () => {
+    const err = new AuthorizationError('test_code', 'test message')
+    expect(err.code).toBe('test_code')
+    expect(err.message).toBe('test message')
+    expect(err.name).toBe('AuthorizationError')
+  })
+})
+
+describe('BudgetExhaustedError', () => {
+  it('sets correct code and properties', () => {
+    const err = new BudgetExhaustedError('pol_1', 100n, 500n)
+    expect(err.code).toBe('budget_exhausted')
+    expect(err.budgetUsed).toBe(100n)
+    expect(err.budgetLimit).toBe(500n)
+    expect(err.policyId).toBe('pol_1')
+    expect(err.message).toContain('100')
+    expect(err.message).toContain('500')
+  })
+})
+
+describe('AllowlistDeniedError', () => {
+  it('sets correct code and target', () => {
+    const err = new AllowlistDeniedError('pol_1', 'openai:gpt-4')
+    expect(err.code).toBe('allowlist_denied')
+    expect(err.target).toBe('openai:gpt-4')
+    expect(err.message).toContain('openai:gpt-4')
+  })
+})
+
+describe('RateLimitExceededError', () => {
+  it('sets correct code and properties', () => {
+    const err = new RateLimitExceededError('pol_1', 60_000, 10)
+    expect(err.code).toBe('rate_limit_exceeded')
+    expect(err.windowMs).toBe(60_000)
+    expect(err.maxCalls).toBe(10)
+  })
+})
+
+describe('AuthorizationExpiredError', () => {
+  it('sets correct code', () => {
+    const err = new AuthorizationExpiredError()
+    expect(err.code).toBe('authorization_expired')
+  })
+})
+
+describe('ExecutionError', () => {
+  it('creates with code and message', () => {
+    const err = new ExecutionError('exec_code', 'exec message')
+    expect(err.code).toBe('exec_code')
+    expect(err.name).toBe('ExecutionError')
+  })
+})
+
+describe('NetworkError', () => {
+  it('sets correct code', () => {
+    const err = new NetworkError('connection refused')
+    expect(err.code).toBe('network_error')
+    expect(err.message).toBe('connection refused')
+  })
+})
+
+describe('GasEstimationError', () => {
+  it('sets correct code', () => {
+    const err = new GasEstimationError('gas too high')
+    expect(err.code).toBe('gas_estimation_error')
+  })
+})
+
+describe('BroadcastError', () => {
+  it('sets correct code', () => {
+    const err = new BroadcastError('tx failed')
+    expect(err.code).toBe('broadcast_error')
+  })
+})
+
+describe('ReorgDetectedError', () => {
+  it('sets correct code and depth', () => {
+    const err = new ReorgDetectedError(3)
+    expect(err.code).toBe('reorg_detected')
+    expect(err.depth).toBe(3)
+  })
+})

package/test/payment-types.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import {
+  assertValidPaymentIntentTransition,
+  canTransitionPaymentIntentStatus,
+  deserializePaymentIntent,
+  serializePaymentIntent,
+} from '../src/types/payment.js'
+import { ValidationError } from '../src/errors.js'
+import type { PaymentIntent } from '../src/types/payment.js'
+
+const paymentIntent: PaymentIntent = {
+  id: 'pi_123',
+  workspaceId: 'ws_123',
+  actorId: 'actor_123',
+  status: 'approved',
+  amount: {
+    currency: 'USDC',
+    value: 1250000n,
+    decimals: 6,
+  },
+  recipient: {
+    address: '0x1111111111111111111111111111111111111111',
+    chainId: 8453,
+  },
+  createdAt: '2026-07-06T10:00:00.000Z',
+  updatedAt: '2026-07-06T10:00:00.000Z',
+}
+
+describe('payment types', () => {
+  it('serializes and deserializes bigint fields without losing precision', () => {
+    const serialized = serializePaymentIntent(paymentIntent)
+    const restored = deserializePaymentIntent(serialized)
+
+    expect(restored.amount.value).toBe(1250000n)
+    expect(restored.recipient.address).toBe(paymentIntent.recipient.address)
+  })
+
+  it('allows valid state transitions', () => {
+    expect(canTransitionPaymentIntentStatus('approved', 'submitted')).toBe(true)
+    expect(() => assertValidPaymentIntentTransition('approved', 'submitted')).not.toThrow()
+  })
+
+  it('rejects invalid state transitions', () => {
+    expect(canTransitionPaymentIntentStatus('succeeded', 'approved')).toBe(false)
+    expect(() => assertValidPaymentIntentTransition('succeeded', 'approved')).toThrow(
+      ValidationError
+    )
+  })
+})

package/test/policies.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest'
+import { createBudgetCheckPolicy } from '../src/policies/budget-check.js'
+import { createAllowlistPolicy } from '../src/policies/allowlist.js'
+import { createMaxPerCallPolicy } from '../src/policies/max-per-call.js'
+import { createRateLimitPolicy } from '../src/policies/rate-limit.js'
+import type { Actor, Intent, BudgetState, PolicyResult } from '../src/types.js'
+
+const defaultActor: Actor = {
+  id: 'actor_1',
+  name: 'test-agent',
+  status: 'active',
+  createdAt: new Date().toISOString(),
+}
+
+const defaultBudget: BudgetState = {
+  total: 1000n,
+  used: 200n,
+  remaining: 800n,
+  period: 'monthly',
+  currency: 'USDC',
+}
+
+async function evaluatePolicy(
+  policy: { middleware: any },
+  intent: Intent,
+  budget: BudgetState = defaultBudget,
+  actor: Actor = defaultActor
+): Promise<PolicyResult> {
+  const next = async () => ({
+    policyId: 'test',
+    policyType: 'test',
+    version: '1',
+    decision: 'pass' as const,
+    reason: { code: 'noop', message: 'noop' },
+    evaluatedAt: new Date().toISOString(),
+  })
+  return policy.middleware(
+    { actor, intent, budget, evaluatedPolicies: [] },
+    next
+  )
+}
+
+describe('BudgetCheckPolicy', () => {
+  it('passes when used + amount <= limit', async () => {
+    const policy = createBudgetCheckPolicy('pol_budget', '1')
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 300n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('pass')
+  })
+
+  it('denies when used + amount > limit', async () => {
+    const policy = createBudgetCheckPolicy('pol_budget', '1')
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 900n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('deny')
+    expect(result.reason.code).toBe('budget_exhausted')
+  })
+
+  it('uses budget from context', async () => {
+    const policy = createBudgetCheckPolicy('pol_budget', '1')
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 50n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const smallBudget: BudgetState = {
+      total: 100n,
+      used: 80n,
+      remaining: 20n,
+      period: 'total',
+      currency: 'USDC',
+    }
+    const result = await evaluatePolicy(policy, intent, smallBudget)
+    expect(result.decision).toBe('deny')
+  })
+})
+
+describe('AllowlistPolicy', () => {
+  it('passes when target is in allowlist', async () => {
+    const policy = createAllowlistPolicy('pol_allow', '1', ['good:svc', 'better:svc'])
+    const intent: Intent = {
+      target: 'good:svc',
+      amount: 100n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('pass')
+  })
+
+  it('denies when target is not in allowlist', async () => {
+    const policy = createAllowlistPolicy('pol_allow', '1', ['good:svc'])
+    const intent: Intent = {
+      target: 'evil:svc',
+      amount: 100n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('deny')
+    expect(result.reason.code).toBe('allowlist_denied')
+  })
+})
+
+describe('MaxPerCallPolicy', () => {
+  it('passes when amount <= max', async () => {
+    const policy = createMaxPerCallPolicy('pol_max', '1', 500n)
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 300n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('pass')
+  })
+
+  it('denies when amount > max', async () => {
+    const policy = createMaxPerCallPolicy('pol_max', '1', 500n)
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 600n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('deny')
+  })
+})
+
+describe('RateLimitPolicy', () => {
+  it('passes when call count is within limit', async () => {
+    const store = new Map<string, number[]>()
+    const policy = createRateLimitPolicy('pol_rate', '1', 10, 60_000, store)
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 100n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('pass')
+  })
+
+  it('denies when call count exceeds limit', async () => {
+    const now = Date.now()
+    const store = new Map<string, number[]>()
+    store.set('actor_1', Array(10).fill(now - 1000))
+    const policy = createRateLimitPolicy('pol_rate', '1', 10, 60_000, store)
+    const intent: Intent = {
+      target: 'test:svc',
+      amount: 100n,
+      purpose: { type: 'test', id: '1' },
+    }
+    const result = await evaluatePolicy(policy, intent)
+    expect(result.decision).toBe('deny')
+    expect(result.reason.code).toBe('rate_limit_exceeded')
+  })
+})

package/test/policy-engine.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import { PolicyEngine } from '../src/policy-engine.js'
+import type {
+  Actor,
+  Intent,
+  PolicyContext,
+  PolicyMiddleware,
+  PolicyEvaluator,
+  BudgetState,
+  PolicyResult,
+} from '../src/types.js'
+
+const defaultActor: Actor = {
+  id: 'actor_1',
+  name: 'test-agent',
+  status: 'active',
+  createdAt: new Date().toISOString(),
+}
+
+const defaultIntent: Intent = {
+  target: 'test:service',
+  amount: 100n,
+  purpose: { type: 'test', id: '1' },
+}
+
+const defaultBudget: BudgetState = {
+  total: 1000n,
+  used: 200n,
+  remaining: 800n,
+  period: 'monthly',
+  currency: 'USDC',
+}
+
+function passMiddleware(id: string): PolicyEvaluator {
+  return {
+    id,
+    type: 'pass',
+    version: '1',
+    middleware: async (_ctx, next) => {
+      const result = await next()
+      return result
+    },
+  }
+}
+
+function denyMiddleware(id: string): PolicyEvaluator {
+  return {
+    id,
+    type: 'deny',
+    version: '1',
+    middleware: async (_ctx, _next) => ({
+      policyId: id,
+      policyType: 'deny',
+      version: '1',
+      decision: 'deny' as const,
+      reason: { code: 'test_deny', message: 'denied by test' },
+      evaluatedAt: new Date().toISOString(),
+    }),
+  }
+}
+
+describe('PolicyEngine', () => {
+  it('returns approved for empty middleware list', async () => {
+    const engine = new PolicyEngine([])
+    const result = await engine.evaluate(defaultActor, defaultIntent, defaultBudget)
+    expect(result.decision).toBe('approved')
+    expect(result.policyResults).toHaveLength(0)
+  })
+
+  it('evaluates all pass middlewares', async () => {
+    const engine = new PolicyEngine([
+      passMiddleware('pol_1'),
+      passMiddleware('pol_2'),
+    ])
+    const result = await engine.evaluate(defaultActor, defaultIntent, defaultBudget)
+    expect(result.decision).toBe('approved')
+    expect(result.policyResults).toHaveLength(2)
+  })
+
+  it('deny overrides pass results', async () => {
+    const engine = new PolicyEngine([
+      passMiddleware('pol_1'),
+      denyMiddleware('pol_2'),
+    ])
+    const result = await engine.evaluate(defaultActor, defaultIntent, defaultBudget)
+    expect(result.decision).toBe('denied')
+    expect(result.policyResults).toHaveLength(2)
+  })
+
+  it('includes actor version in authorization', async () => {
+    const engine = new PolicyEngine([])
+    const result = await engine.evaluate(defaultActor, defaultIntent, defaultBudget)
+    expect(result.actorVersion).toBe('1')
+    expect(result.intent).toEqual(defaultIntent)
+  })
+})

package/test/policy-types.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import {
+  aggregatePolicyDecisions,
+  evaluatePolicies,
+  type AllowlistPolicy,
+  type BudgetPolicy,
+  type PolicyEvaluationContext,
+  type RateLimitPolicy,
+} from '../src/types/policy.js'
+
+const context: PolicyEvaluationContext = {
+  actorId: 'actor_123',
+  workspaceId: 'ws_123',
+  recipient: '0x1111111111111111111111111111111111111111',
+  chainId: 8453,
+  amount: 2500000n,
+  currency: 'USDC',
+  timestampMs: Date.now(),
+  spentAmount: 1000000n,
+  requestCount: 2,
+}
+
+describe('policy types', () => {
+  it('returns deny when any policy denies the request', () => {
+    const policies: [BudgetPolicy, AllowlistPolicy] = [
+      {
+        id: 'budget_1',
+        name: 'Budget Guard',
+        enabled: true,
+        kind: 'budget',
+        currency: 'USDC',
+        limit: 5000000n,
+      },
+      {
+        id: 'allowlist_1',
+        name: 'Allowlist',
+        enabled: true,
+        kind: 'allowlist',
+        addresses: ['0x2222222222222222222222222222222222222222'],
+      },
+    ]
+
+    const result = evaluatePolicies(policies, context)
+    expect(result.decision).toBe('deny')
+    expect(result.reasons[0]?.code).toBe('recipient_not_allowlisted')
+  })
+
+  it('returns review when no policy denies but one flags review', () => {
+    const policies: [BudgetPolicy, RateLimitPolicy] = [
+      {
+        id: 'budget_2',
+        name: 'Soft Budget',
+        enabled: true,
+        kind: 'budget',
+        currency: 'USDC',
+        limit: 5000000n,
+        softLimit: 3000000n,
+      },
+      {
+        id: 'rate_1',
+        name: 'Rate Limit',
+        enabled: true,
+        kind: 'rate_limit',
+        maxRequests: 10,
+        intervalMs: 60000,
+        burst: 5,
+        scope: 'actor',
+      },
+    ]
+
+    const result = evaluatePolicies(policies, context)
+    expect(result.decision).toBe('review')
+    expect(result.reasons.some((reason) => reason.code === 'budget_soft_limit_exceeded')).toBe(true)
+  })
+
+  it('aggregates allow results when all policies pass', () => {
+    const result = aggregatePolicyDecisions([
+      {
+        policyId: 'budget_3',
+        decision: 'allow',
+        reason: { code: 'budget_ok', message: 'Budget okay' },
+      },
+      {
+        policyId: 'allowlist_3',
+        decision: 'allow',
+        reason: { code: 'allowlist_ok', message: 'Allowlist okay' },
+      },
+    ])
+
+    expect(result.decision).toBe('allow')
+    expect(result.reasons).toHaveLength(2)
+  })
+})

package/test/property/auth-invariants.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import fc from 'fast-check'
+import { PolicyEngine } from '../../src/policy-engine.js'
+import { createBudgetCheckPolicy } from '../../src/policies/budget-check.js'
+import { DecisionResolver } from '../../src/decision-resolver.js'
+import type { Actor, Intent, BudgetState, PolicyResult } from '../../src/types.js'
+
+const actor: Actor = {
+  id: 'actor_prop',
+  name: 'prop-test',
+  status: 'active',
+  createdAt: new Date().toISOString(),
+}
+
+describe('Authorization invariants (property-based)', () => {
+  it('same inputs always produce same authorization result', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.bigInt({ min: 0n, max: 1_000_000n }),
+        fc.bigInt({ min: 0n, max: 1_000_000n }),
+        async (budgetTotal, spendAmount) => {
+          const budget: BudgetState = {
+            total: budgetTotal,
+            used: 0n,
+            remaining: budgetTotal,
+            period: 'total',
+            currency: 'USDC',
+          }
+          const engine = new PolicyEngine([
+            createBudgetCheckPolicy('pol_budget', '1'),
+          ])
+          const intent: Intent = {
+            target: 'test:svc',
+            amount: spendAmount,
+            purpose: { type: 'test', id: 'prop' },
+          }
+          const a = await engine.evaluate(actor, intent, budget)
+          const b = await engine.evaluate(actor, intent, budget)
+          expect(a.decision).toBe(b.decision)
+        }
+      ),
+      { numRuns: 100 }
+    )
+  })
+
+  it('deny always dominates pass and review', () => {
+    fc.assert(
+      fc.property(
+        fc.array(
+          fc.constantFrom<'pass' | 'deny' | 'review'>('pass', 'deny', 'review'),
+          { minLength: 0, maxLength: 10 }
+        ),
+        (decisions) => {
+          const results: PolicyResult[] = decisions.map((d, i) => ({
+            policyId: `pol_${i}`,
+            policyType: 'prop-test',
+            version: '1',
+            decision: d,
+            reason: { code: 'prop', message: 'property test' },
+            evaluatedAt: new Date().toISOString(),
+          }))
+          const resolved = DecisionResolver.resolve(results)
+          if (decisions.length === 0) {
+            expect(resolved).toBe('denied')
+          } else if (decisions.some((d) => d === 'deny')) {
+            expect(resolved).toBe('denied')
+          } else if (decisions.some((d) => d === 'review')) {
+            expect(resolved).toBe('pending-review')
+          } else {
+            expect(resolved).toBe('approved')
+          }
+        }
+      ),
+      { numRuns: 200 }
+    )
+  })
+
+  it('budget enforcement never allows overspend', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.bigInt({ min: 1n, max: 1_000_000n }),
+        fc.bigInt({ min: 1n, max: 1_000_000n }),
+        async (total, amount) => {
+          const budget: BudgetState = {
+            total,
+            used: 0n,
+            remaining: total,
+            period: 'total',
+            currency: 'USDC',
+          }
+          const engine = new PolicyEngine([
+            createBudgetCheckPolicy('pol_budget', '1'),
+          ])
+          const intent: Intent = {
+            target: 'test:svc',
+            amount,
+            purpose: { type: 'test', id: 'prop' },
+          }
+          const auth = await engine.evaluate(actor, intent, budget)
+          if (amount > total) {
+            expect(auth.decision).toBe('denied')
+          } else {
+            expect(auth.decision).toBe('approved')
+          }
+        }
+      ),
+      { numRuns: 100 }
+    )
+  })
+})