@brninpay/core 0.1.0

package/src/types/policy.ts

@@ -0,0 +1,289 @@
+import { ValidationError } from './errors.js'
+import type { Address } from './wallet.js'
+
+export const POLICY_DECISIONS = ['allow', 'deny', 'review'] as const
+
+export type PolicyDecision = (typeof POLICY_DECISIONS)[number]
+
+export interface PolicyReason {
+  code: string
+  message: string
+  detail?: Record<string, unknown>
+}
+
+export interface BasePolicy {
+  id: string
+  name: string
+  enabled: boolean
+}
+
+export interface BudgetPolicy extends BasePolicy {
+  kind: 'budget'
+  currency: 'USDC'
+  limit: bigint
+  softLimit?: bigint
+}
+
+export interface AllowlistPolicy extends BasePolicy {
+  kind: 'allowlist'
+  addresses: readonly Address[]
+  chains?: readonly number[]
+}
+
+export interface RateLimitPolicy extends BasePolicy {
+  kind: 'rate_limit'
+  maxRequests: number
+  intervalMs: number
+  burst?: number
+  scope: 'actor' | 'workspace' | 'ip'
+}
+
+export type PolicyDefinition = BudgetPolicy | AllowlistPolicy | RateLimitPolicy
+
+export interface PolicyEvaluationContext {
+  actorId: string
+  workspaceId: string
+  recipient: Address
+  chainId: number
+  amount: bigint
+  currency: 'USDC'
+  timestampMs: number
+  spentAmount: bigint
+  requestCount: number
+  sourceIp?: string
+}
+
+export interface PolicyEvaluationResult {
+  policyId: string
+  decision: PolicyDecision
+  reason: PolicyReason
+}
+
+export interface AggregatedPolicyDecision {
+  decision: PolicyDecision
+  reasons: PolicyReason[]
+  evaluations: PolicyEvaluationResult[]
+}
+
+function assertBasePolicy(policy: BasePolicy): void {
+  if (!policy.id.trim()) {
+    throw new ValidationError('Policy id is required', { field: 'id' })
+  }
+
+  if (!policy.name.trim()) {
+    throw new ValidationError('Policy name is required', { field: 'name' })
+  }
+}
+
+function normalizeAddress(address: Address): string {
+  return address.toLowerCase()
+}
+
+export function evaluatePolicy(
+  policy: PolicyDefinition,
+  context: PolicyEvaluationContext
+): PolicyEvaluationResult {
+  assertBasePolicy(policy)
+
+  if (!policy.enabled) {
+    return {
+      policyId: policy.id,
+      decision: 'allow',
+      reason: {
+        code: 'policy_disabled',
+        message: `Policy ${policy.name} is disabled`,
+      },
+    }
+  }
+
+  switch (policy.kind) {
+    case 'budget': {
+      if (policy.currency !== context.currency) {
+        return {
+          policyId: policy.id,
+          decision: 'deny',
+          reason: {
+            code: 'budget_currency_mismatch',
+            message: `Budget policy ${policy.name} only allows ${policy.currency}`,
+          },
+        }
+      }
+
+      const nextSpend = context.spentAmount + context.amount
+      if (nextSpend > policy.limit) {
+        return {
+          policyId: policy.id,
+          decision: 'deny',
+          reason: {
+            code: 'budget_limit_exceeded',
+            message: `Budget policy ${policy.name} would exceed its hard limit`,
+            detail: {
+              limit: policy.limit.toString(),
+              spentAmount: context.spentAmount.toString(),
+              requestedAmount: context.amount.toString(),
+            },
+          },
+        }
+      }
+
+      if (policy.softLimit !== undefined && nextSpend > policy.softLimit) {
+        return {
+          policyId: policy.id,
+          decision: 'review',
+          reason: {
+            code: 'budget_soft_limit_exceeded',
+            message: `Budget policy ${policy.name} exceeded its soft limit`,
+            detail: {
+              softLimit: policy.softLimit.toString(),
+              nextSpend: nextSpend.toString(),
+            },
+          },
+        }
+      }
+
+      return {
+        policyId: policy.id,
+        decision: 'allow',
+        reason: {
+          code: 'budget_ok',
+          message: `Budget policy ${policy.name} approved the request`,
+        },
+      }
+    }
+
+    case 'allowlist': {
+      const addressAllowed = policy.addresses
+        .map((address) => normalizeAddress(address))
+        .includes(normalizeAddress(context.recipient))
+
+      if (!addressAllowed) {
+        return {
+          policyId: policy.id,
+          decision: 'deny',
+          reason: {
+            code: 'recipient_not_allowlisted',
+            message: `Recipient ${context.recipient} is not allowlisted by ${policy.name}`,
+          },
+        }
+      }
+
+      if (policy.chains && !policy.chains.includes(context.chainId)) {
+        return {
+          policyId: policy.id,
+          decision: 'deny',
+          reason: {
+            code: 'chain_not_allowlisted',
+            message: `Chain ${context.chainId} is not allowlisted by ${policy.name}`,
+          },
+        }
+      }
+
+      return {
+        policyId: policy.id,
+        decision: 'allow',
+        reason: {
+          code: 'allowlist_ok',
+          message: `Allowlist policy ${policy.name} approved the request`,
+        },
+      }
+    }
+
+    case 'rate_limit': {
+      if (!Number.isInteger(policy.maxRequests) || policy.maxRequests <= 0) {
+        throw new ValidationError('Rate limit maxRequests must be a positive integer', {
+          field: 'maxRequests',
+          value: policy.maxRequests,
+        })
+      }
+
+      if (!Number.isInteger(policy.intervalMs) || policy.intervalMs <= 0) {
+        throw new ValidationError('Rate limit intervalMs must be a positive integer', {
+          field: 'intervalMs',
+          value: policy.intervalMs,
+        })
+      }
+
+      const nextCount = context.requestCount + 1
+      if (nextCount > policy.maxRequests) {
+        return {
+          policyId: policy.id,
+          decision: 'deny',
+          reason: {
+            code: 'rate_limit_exceeded',
+            message: `Rate limit policy ${policy.name} denied the request`,
+            detail: {
+              scope: policy.scope,
+              maxRequests: policy.maxRequests,
+              requestCount: context.requestCount,
+            },
+          },
+        }
+      }
+
+      if (policy.burst !== undefined && nextCount > policy.burst) {
+        return {
+          policyId: policy.id,
+          decision: 'review',
+          reason: {
+            code: 'rate_limit_burst_review',
+            message: `Rate limit policy ${policy.name} exceeded its preferred burst`,
+            detail: {
+              burst: policy.burst,
+              requestCount: nextCount,
+            },
+          },
+        }
+      }
+
+      return {
+        policyId: policy.id,
+        decision: 'allow',
+        reason: {
+          code: 'rate_limit_ok',
+          message: `Rate limit policy ${policy.name} approved the request`,
+        },
+      }
+    }
+  }
+}
+
+export function aggregatePolicyDecisions(
+  evaluations: readonly PolicyEvaluationResult[]
+): AggregatedPolicyDecision {
+  const denyResult = evaluations.find((evaluation) => evaluation.decision === 'deny')
+  if (denyResult) {
+    return {
+      decision: 'deny',
+      reasons: evaluations
+        .filter((evaluation) => evaluation.decision === 'deny')
+        .map((evaluation) => evaluation.reason),
+      evaluations: [...evaluations],
+    }
+  }
+
+  const reviewResult = evaluations.find((evaluation) => evaluation.decision === 'review')
+  if (reviewResult) {
+    return {
+      decision: 'review',
+      reasons: evaluations
+        .filter((evaluation) => evaluation.decision === 'review')
+        .map((evaluation) => evaluation.reason),
+      evaluations: [...evaluations],
+    }
+  }
+
+  return {
+    decision: 'allow',
+    reasons: evaluations.map((evaluation) => evaluation.reason),
+    evaluations: [...evaluations],
+  }
+}
+
+export function evaluatePolicies(
+  policies: readonly PolicyDefinition[],
+  context: PolicyEvaluationContext
+): AggregatedPolicyDecision {
+  return aggregatePolicyDecisions(
+    policies.map((policy) => evaluatePolicy(policy, context))
+  )
+}

package/src/types/wallet.ts

@@ -0,0 +1,84 @@
+export type Hex = `0x${string}`
+export type Address = `0x${string}`
+
+export type SmartWalletProvider = 'safe' | 'kernel' | 'circle'
+export type EntryPointVersion = 'v0.6' | 'v0.7'
+
+export interface SmartWallet {
+  address: Address
+  ownerAddress: Address
+  chainId: number
+  provider: SmartWalletProvider
+  entryPointAddress: Address
+  entryPointVersion: EntryPointVersion
+  factoryAddress?: Address
+  deployed: boolean
+}
+
+export interface UserOperationCall {
+  to: Address
+  value: bigint
+  data: Hex
+}
+
+export interface GasEstimate {
+  callGasLimit: bigint
+  verificationGasLimit: bigint
+  preVerificationGas: bigint
+  maxFeePerGas: bigint
+  maxPriorityFeePerGas: bigint
+  paymasterVerificationGasLimit?: bigint
+  paymasterPostOpGasLimit?: bigint
+}
+
+export interface UserOperationV06 {
+  version: 'v0.6'
+  sender: Address
+  nonce: bigint
+  initCode: Hex
+  callData: Hex
+  callGasLimit: bigint
+  verificationGasLimit: bigint
+  preVerificationGas: bigint
+  maxFeePerGas: bigint
+  maxPriorityFeePerGas: bigint
+  paymasterAndData: Hex
+  signature: Hex
+}
+
+export interface UserOperationV07 {
+  version: 'v0.7'
+  sender: Address
+  nonce: bigint
+  factory: Address | Hex
+  factoryData: Hex
+  callData: Hex
+  callGasLimit: bigint
+  verificationGasLimit: bigint
+  preVerificationGas: bigint
+  maxFeePerGas: bigint
+  maxPriorityFeePerGas: bigint
+  paymaster: Address | Hex
+  paymasterVerificationGasLimit: bigint
+  paymasterPostOpGasLimit: bigint
+  paymasterData: Hex
+  signature: Hex
+}
+
+export type UserOperation = UserOperationV06 | UserOperationV07
+
+export function isUserOperationV06(value: UserOperation): value is UserOperationV06 {
+  return value.version === 'v0.6'
+}
+
+export function isUserOperationV07(value: UserOperation): value is UserOperationV07 {
+  return value.version === 'v0.7'
+}
+
+export function getUserOperationSender(value: UserOperation): Address {
+  return value.sender
+}
+
+export function getUserOperationNonce(value: UserOperation): bigint {
+  return value.nonce
+}

package/src/types.ts

@@ -0,0 +1,193 @@
+export interface Actor {
+  id: string
+  name: string
+  status: 'active' | 'frozen' | 'depleted'
+  createdAt: string
+}
+
+export interface Budget {
+  id: string
+  actorId: string
+  amount: bigint
+  used: bigint
+  currency: 'USDC'
+  period: 'monthly' | 'total'
+  resetAt: string
+}
+
+export interface Policy {
+  id: string
+  actorId: string
+  type: string
+  version: string
+  config: Record<string, unknown>
+  priority: number
+}
+
+export interface SettlementDescriptor {
+  address: string
+  chain: string
+  asset: string
+}
+
+export interface Target {
+  id: string
+  actorId: string
+  name: string
+  settlement: SettlementDescriptor
+}
+
+export interface Purpose {
+  type: string
+  id: string
+  description?: string
+}
+
+export interface Intent {
+  target: string
+  amount: bigint
+  purpose: Purpose
+  idempotencyKey?: string
+}
+
+export interface BudgetState {
+  total: bigint
+  used: bigint
+  remaining: bigint
+  period: string
+  currency: string
+}
+
+export interface PolicyResult {
+  policyId: string
+  policyType: string
+  version: string
+  decision: 'pass' | 'deny' | 'review'
+  reason: { code: string; message: string }
+  evaluatedAt: string
+}
+
+export type AuthorizationDecision = 'approved' | 'denied' | 'pending-review'
+
+export interface Authorization {
+  intent: Intent
+  policyResults: PolicyResult[]
+  decision: AuthorizationDecision
+  evaluatedAt: string
+  actorVersion: string
+}
+
+export interface SettlementHint {
+  preferredChain?: string
+  deadline?: string
+  gasStrategy?: string
+}
+
+export interface ExecutionPlan {
+  authorization: Authorization
+  settlementHints: SettlementHint
+}
+
+export interface PolicyContext {
+  actor: Actor
+  intent: Intent
+  budget: BudgetState
+  evaluatedPolicies: PolicyResult[]
+}
+
+export type PolicyMiddleware = (
+  ctx: PolicyContext,
+  next: () => Promise<PolicyResult>
+) => Promise<PolicyResult>
+
+export interface PolicyEvaluator {
+  id: string
+  type: string
+  version: string
+  middleware: PolicyMiddleware
+}
+
+export interface SimulationResult {
+  decision: AuthorizationDecision
+  policyResults: PolicyResult[]
+  estimatedGas?: bigint
+  estimatedCost?: bigint
+}
+
+export interface SignedTransaction {
+  serialized: `0x${string}`
+  hash: `0x${string}`
+}
+
+export interface Receipt {
+  txHash: `0x${string}`
+  status: 'confirmed' | 'failed'
+  blockNumber: bigint
+  gasUsed: bigint
+  effectiveGasPrice: bigint
+}
+
+export type {
+  PaymentIntentStatus,
+  PaymentAmount,
+  PaymentRecipient,
+  PaymentIntentFailure,
+  PaymentMetadataValue,
+  PaymentIntent,
+  SerializedBigInt,
+} from './types/payment.js'
+
+export {
+  PAYMENT_INTENT_STATUSES,
+  PAYMENT_INTENT_TERMINAL_STATUSES,
+  PAYMENT_INTENT_TRANSITIONS,
+  validatePaymentAmount,
+  isPaymentIntentTerminalStatus,
+  canTransitionPaymentIntentStatus,
+  assertValidPaymentIntentTransition,
+  assertPaymentIntent,
+  serializeBigInts,
+  deserializeBigInts,
+  serializePaymentIntent,
+  deserializePaymentIntent,
+} from './types/payment.js'
+
+export type {
+  PolicyDecision,
+  PolicyReason,
+  BasePolicy,
+  BudgetPolicy,
+  AllowlistPolicy,
+  RateLimitPolicy,
+  PolicyDefinition,
+  PolicyEvaluationContext,
+  PolicyEvaluationResult,
+  AggregatedPolicyDecision,
+} from './types/policy.js'
+
+export {
+  POLICY_DECISIONS,
+  evaluatePolicy,
+  aggregatePolicyDecisions,
+  evaluatePolicies,
+} from './types/policy.js'
+
+export type {
+  Hex,
+  Address,
+  SmartWalletProvider,
+  EntryPointVersion,
+  SmartWallet,
+  UserOperationCall,
+  GasEstimate,
+  UserOperationV06,
+  UserOperationV07,
+  UserOperation,
+} from './types/wallet.js'
+
+export {
+  isUserOperationV06,
+  isUserOperationV07,
+  getUserOperationSender,
+  getUserOperationNonce,
+} from './types/wallet.js'