Policy Layer (Thin Policy-as-Code)

Purpose

This layer adds declarative governance checks on top of existing permission guards. It does not replace RBAC and does not change JWT/auth flow.

Permission vs Policy

• Permission:
  • Atomic capability token (for example roles:request.review).
  • Evaluated by RBAC permission evaluator.
• Policy:
  • Declarative rule set that includes a permission plus optional account/identity gates.
  • Example fields:
    • permission
    • requiresActiveAccount
    • requiresVerifiedIdentity

Policy is a higher-level contract. Permission is one input to policy.

Current package

• @kvary/policy-domain
  • PolicyDefinition
  • POLICIES frozen set
  • evaluatePolicy(...)

How to add a new policy

1. Add or reuse frozen permission in @kvary/rbac-domain permission catalog.
2. Add new policy entry to packages/policy-domain/src/policies.ts.
3. Use requirePolicy(POLICIES.XYZ) in gateway route.
4. If governance meaning changes, update AUTHORIZATION_MATRIX.md.

Future extension (KYC gating)

When KYC enforcement is required, policy can enable:

• requiresVerifiedIdentity: true

This keeps route code unchanged while policy definition evolves declaratively.