Built-in Libraries
Comprehensive reference for PolicyFlow's standard library
PolicyFlow provides a rich set of built-in libraries for common operations. These libraries are available in all policies without requiring imports. All built-in types (such as Email
, URL
, IPAddress
) and libraries are globally available.
DateTime Library
The DateTime library provides comprehensive date and time manipulation capabilities.
Static Methods
Method | Description | Returns |
---|---|---|
DateTime.Now() | Current date and time | DateTime |
DateTime.Today() | Today's date at midnight | DateTime |
DateTime.Parse(string, [pattern]) | Parse a datetime string | DateTime |
Instance Methods
Method | Description | Returns |
---|---|---|
.Age() | Years since the datetime until now | Number |
.DayOfWeek() | Day of week (0=Sunday, 6=Saturday) | Number |
.Add(unit, amount) | Add time to a datetime | DateTime |
.Subtract(unit, amount) | Subtract time from a datetime | DateTime |
.Format(pattern) | Format as string | String |
.ToUnit(unit) | Extract component (year, month, etc.) | Number |
Examples
rule CheckBusinessHours {
when {
const now = DateTime.Now();
const hour = now.ToUnit(TimeUnit.Hours);
const dayOfWeek = now.DayOfWeek();
// Monday-Friday (1-5), 9 AM - 5 PM
return dayOfWeek >= 1 AND dayOfWeek <= 5
AND hour >= 9 AND hour < 17;
}
then ALLOW
reason: "Access allowed during business hours"
}
rule CheckAge {
when {
const age = user.birthDate.Age();
return age >= 18;
}
then ALLOW
reason: "User is an adult"
}
Time Library
For working with time values without dates.
Static Methods
Method | Description | Returns |
---|---|---|
Time.Now() | Current time | Time |
Time.Parse(string) | Parse a time string | Time |
Examples
rule NightShiftAccess {
when {
const currentTime = Time.Now();
const nightStart = Time.Parse("22:00:00");
const nightEnd = Time.Parse("06:00:00");
// Handle time wrapping around midnight
return currentTime >= nightStart OR currentTime <= nightEnd;
}
then ALLOW
}
Duration Library
For representing and calculating time spans.
Creating Durations
Method | Description | Returns |
---|---|---|
Duration.FromUnit(unit, value) | Create duration from unit | Duration |
Duration Methods
Method | Description | Returns |
---|---|---|
.TotalDays() | Total days (including fractions) | Decimal |
.TotalHours() | Total hours (including fractions) | Decimal |
.TotalMinutes() | Total minutes (including fractions) | Decimal |
.TotalSeconds() | Total seconds (including fractions) | Decimal |
.TotalMilliseconds() | Total milliseconds | Number |
Examples
rule CheckExpiration {
when {
const timeUntilExpiry = resource.expiresAt - DateTime.Now();
const daysUntilExpiry = timeUntilExpiry.TotalDays();
// Deny if less than 7 days until expiration
return daysUntilExpiry < 7;
}
then DENY
reason: "Resource expires in less than 7 days"
}
rule EnforceTimeout {
when {
const sessionDuration = DateTime.Now() - user.sessionStart;
const hoursElapsed = sessionDuration.TotalHours();
const maxHours = 8;
return hoursElapsed > maxHours;
}
then DENY
reason: "Session timeout after 8 hours"
}
Math Library
Mathematical operations and utilities.
Methods
Method | Description | Returns | Input Types |
---|---|---|---|
Math.Abs(num) | Absolute value | Same as input | Number or Decimal |
Math.Min(n1, n2, ...) | Minimum value | Same as input | Number or Decimal |
Math.Max(n1, n2, ...) | Maximum value | Same as input | Number or Decimal |
Math.Round(decimal, places) | Round to decimal places | Decimal | Decimal |
Math.Floor(decimal) | Round down | Number | Decimal |
Math.Ceil(decimal) | Round up | Number | Decimal |
Math.Sum(array) | Sum of array elements | Same as array type | Number[] or Decimal[] |
Math.Avg(array) | Average of array elements | Decimal | Number[] or Decimal[] |
Type Handling
The Math library preserves types where possible:
- Methods that accept both
Number
andDecimal
return the same type as input Math.Sum()
returnsNumber
forNumber[]
arrays,Decimal
forDecimal[]
arraysMath.Avg()
always returnsDecimal
for precisionMath.Floor()
andMath.Ceil()
always returnNumber
Examples
rule CheckRiskScore {
when {
// Working with Number arrays
const scores: Number[] = [
user.creditScore,
user.behaviorScore,
user.reputationScore
];
const avgScore = Math.Avg(scores); // Returns Decimal
const minScore = Math.Min(...scores); // Returns Number
const totalScore = Math.Sum(scores); // Returns Number
// Require average > 70 and no score below 50
return avgScore > 70.0 AND minScore >= 50;
}
then ALLOW
}
rule CalculateTransactionFees {
when {
// Working with Decimal arrays
const fees: Decimal[] = [
resource.baseFee,
resource.serviceFee,
resource.processingFee
];
const totalFees = Math.Sum(fees); // Returns Decimal
const avgFee = Math.Avg(fees); // Returns Decimal
// Apply 10% discount if total fees exceed threshold
const discountedTotal = totalFees > 50.0
? totalFees * 0.9
: totalFees;
return discountedTotal <= user.maxFeeLimit;
}
then ALLOW
}
rule LimitTransactionAmount {
when {
// Mixed numeric operations
const dailyTransactions: Decimal[] = user.todayTransactions;
const dailyTotal = Math.Sum(dailyTransactions); // Returns Decimal
const proposedTotal = dailyTotal + resource.amount;
// Different limits based on user tier
const limit = user.isPremium ? 10000.0 : 1000.0;
return proposedTotal > limit;
}
then DENY
reason: "Daily transaction limit exceeded"
}
Runtime Library
For dynamic type inspection and safe property access.
Methods
Method | Description | Returns |
---|---|---|
Runtime.IsType(value, "TypeName") | Check if value is of type | Boolean |
Runtime.HasProperty(obj, "prop") | Check if property exists | Boolean |
Runtime.GetProperty(obj, "prop") | Get property value | Any |
Examples
rule CheckDynamicAttribute {
when {
// user.metadata is Map<String, Any>
if (!Runtime.HasProperty(user.metadata, "clearanceLevel")) {
return false;
}
const clearance = Runtime.GetProperty(user.metadata, "clearanceLevel");
return clearance >= resource.requiredClearance;
}
then ALLOW
}
rule ValidateCustomFields {
when {
// Check multiple dynamic properties
const hasAllFields = Runtime.HasProperty(resource.customData, "approver")
AND Runtime.HasProperty(resource.customData, "approvalDate")
AND Runtime.HasProperty(resource.customData, "approvalReason");
if (!hasAllFields) {
return false;
}
// Validate approval is recent
const approvalDate = Runtime.GetProperty(resource.customData, "approvalDate");
const timeSinceApproval = DateTime.Now() - approvalDate;
return timeSinceApproval.TotalDays() <= 30;
}
then ALLOW
}
Relationships Library
For querying the relationship graph between entities.
Methods
Method | Description | Returns |
---|---|---|
Relationships.Has(entity1, "relation", entity2) | Check direct relationship | Boolean |
Relationships.GetRelated(entity, "relation") | Get related entities | Array |
Relationships.PathExists(e1, "path", e2) | Check path existence | Boolean |
Relationships.GetRelationship(e1, "relation", e2) | Get relationship object with attributes | Relationship? |
Path Syntax
Paths use dots to chain relationships:
"member_of"
- Direct relationship"member_of.owns"
- Two-hop path"member_of.parent_of.owns"
- Multi-hop path
Relationship Object Methods
When you retrieve a relationship object using GetRelationship
, you can access its attributes.
Method | Description | Returns |
---|---|---|
.GetAttribute(key, [default]) | Get an attribute from the relationship | Any? |
Examples
rule TeamMemberAccess {
when Relationships.Has(user, "member_of", resource.team)
then ALLOW
reason: "User is a team member"
}
rule HierarchicalAccess {
when {
// Check if user manages the resource owner
const manages = Relationships.PathExists(
user,
"manages.manages.manages", // Up to 3 levels
resource.owner
);
return manages AND action == "read";
}
then ALLOW
reason: "Managers can read their reports' resources"
}
rule CollaboratorAccess {
when {
// Get the relationship object to check its attributes
const rel = Relationships.GetRelationship(user, "collaborates_on", resource);
if (rel == null) {
return false;
}
// Check an attribute on the relationship itself
const permissions = rel.GetAttribute("permissions");
return permissions?.Contains("edit") ?? false;
}
then ALLOW
}
Crypto Library
For secure hashing and comparison operations. Never use for encryption.
Methods
Method | Description | Returns |
---|---|---|
Crypto.Sha256(input) | SHA-256 hash | String |
Crypto.ConstantTimeCompare(s1, s2) | Timing-safe comparison | Boolean |
Crypto.Verify(plainText, hash) | Verify password/secret | Boolean |
Security Best Practices
rule VerifyAPIKey {
// BEST: Use Verify for password/secret validation
when Crypto.Verify(context.apiKey, resource.apiKeyHash)
then ALLOW
reason: "Valid API key"
}
rule VerifyToken {
// GOOD: Use constant-time comparison for hashes
when {
const providedHash = Crypto.Sha256(context.token + resource.salt);
return Crypto.ConstantTimeCompare(providedHash, resource.tokenHash);
}
then ALLOW
}
// NEVER: Don't use regular comparison for secrets
// when Crypto.Sha256(context.secret) == resource.secretHash // VULNERABLE TO TIMING ATTACKS!
Environment Variables
Access global configuration through the env
map. Values from .env
files are automatically parsed into String
, Number
, Decimal
, or Boolean
types. For detailed information about type detection and usage patterns, see the Language Syntax guide.
// .env file:
// ADMIN_ROLE = "system-admin"
// MAINTENANCE_MODE = false
// API_RATE_LIMIT = 1000
rule AdminAccess {
when env["ADMIN_ROLE"] in user.roles
then ALLOW
priority: 1000
}
rule MaintenanceMode {
when env["MAINTENANCE_MODE"] == true
then DENY
priority: 0
reason: "System under maintenance"
}
rule RateLimit {
when {
const limit = env["API_RATE_LIMIT"];
return user.requestCount > limit;
}
then DENY
reason: "Rate limit exceeded"
}