Chapter 3: policies, rules, and conditions

Roles answer "is Bob an editor". They cannot answer "may Bob update this document". That needs attributes: who owns the document, what state it is in, when the request arrived. This chapter adds two ABAC policies to DocDuck and shows how they combine with the roles from chapter 2.

Learning goals

• Write a policy with definePolicy, rules with .rule(), and conditions with the When builder.
• Read a condition as three parts: field, operator, value.
• Know all nineteen operators and how each behaves on missing or wrong-typed data.
• Use $-variables to compare one part of the request against another.
• Pick a combining algorithm for a policy, and know how policies combine with each other.
• Avoid the deny-only policy trap that silently denies everything it targets.

Where policies sit

Each policy decides on its own, using its own combining algorithm over its own rules. The engine then merges those verdicts with policyCombine, which defaults to 'and': every applicable policy must allow. A policy that has nothing to say is marked not applicable and skipped rather than counted as a deny.

Writing the policies

What just happened

Take the denial - Bob updating Alice's document - and ask the engine to narrate it:

const trace = await engine.explain('bob', 'update', aliceDoc)
console.log(trace.summary)

DENIED: "bob" attempting update on document
  Roles: [editor, viewer]
  __rbac__ [allow-overrides]: Allowed by rule "__rbac__#5" (1/16 rules matched)
  document-ownership [deny-overrides]: Denied by rule "deny-non-owner-write" (2/2 rules matched)
  document-lifecycle [deny-overrides]: Allowed by rule "allow-otherwise" (1/3 rules matched)
  Result: Denied by rule "deny-non-owner-write"

1. __rbac__ allows: Bob's editor role grants update on document.
2. document-ownership is applicable - its targets cover update on document. Both its rules match by shape; the deny rule's conditions hold (ownerId is alice, not bob; Bob is not an admin), so deny-overrides returns the deny.
3. document-lifecycle is applicable too, and its allow-otherwise rule matches, so it consents.
4. policyCombine: 'and' returns the first deny it meets. Overall: denied.

A policy is skipped entirely - applicable: false - in exactly two cases: its targets do not match the request, or none of its rules covers this action and resource at all. Anything else counts as a vote.

How a condition works

interface ICondition {
  readonly field: string
  readonly operator: AccessControl.Operator
  readonly value?: IamPrimitives.AttributeValue
}

Field resolution

A missing field resolves to null, and null flows into the operator like any other value. That is why neq against an absent ownerId is true and the deny fires: omitting data cannot buy you access.

Every operator

Nineteen of them. Read the two right-hand columns together: the field is whatever the request happened to carry, so a wrong-typed field is an ordinary miss, while the value you wrote in the policy is screened before the operator runs and a wrong-typed one throws.

The numeric, string, and array operators refuse to coerce. gt on a string field is false, not a lexicographic comparison, so a stringly-typed attribute can never accidentally satisfy a threshold. contains is array membership and nothing else: a CSV string arriving where a list was expected fails contains and not_contains, so the same type confusion cannot bypass one in each direction.

The four bolded trues are the whole risk surface for a missing attribute. allow when subject.attributes.tier neq 'banned' grants to a subject with no tier at all. Pair a negated operator with an exists guard: w.exists('subject.attributes.tier').attr('tier', 'neq', 'banned').

$-variables

A string value that starts with $ is resolved as a path against the same request, at evaluation time:

w.resourceAttr('ownerId', 'eq', '$subject.id')       // owner is the caller
w.check('resource.attributes.teamId', 'eq', '$scope') // resource belongs to the active scope
w.check('resource.attributes.expiresAt', 'after', '$environment.now')

Anything without a leading $ is a literal. 'published' is the string; '$subject.id' is a lookup.

The When builder

.when(fn) and .whenAny(fn) hand you a When instance. Every method returns this.

The standalone when() factory builds groups outside a rule:

import { when } from '@gentleduck/iam'

const adminOrOwner = when().role('admin').isOwner().buildAny()
const notArchived = when().resourceAttr('status', 'eq', 'archived').buildNone()

Grouping conditions

// AND (the default for .when)
.when((w) => w.isOwner().resourceAttr('status', 'neq', 'archived'))

// OR
.whenAny((w) => w.role('admin').isOwner())

// NOT, nested inside an AND
.when((w) => w.isOwner().not((n) => n.role('suspended')))

// admin OR (editor AND owner)
.when((w) => w.or((o) => o.role('admin').and((a) => a.role('editor').isOwner())))

Groups nest up to MAX_CONDITION_DEPTH, which is 10; the comparison is >=, so a tree exactly ten groups deep evaluates and eleven throws IamConditionGroupError. It throws rather than answering false for the reason above - a false inside a none group is a grant. validateRoles and validatePolicy enforce the same bound at authoring time, so a policy that builds cannot hit it at runtime.

The RuleBuilder API

definePolicy('example').rule('my-rule', (r) =>
  r
    .deny()                       // or .allow(); allow is the default
    .desc('why this rule exists')
    .priority(100)                // default 10
    .on('update', 'delete')       // default ['*']
    .of('document')               // default ['*']
    .forScope('team-acme')        // chapter 5
    .when((w) => w.isOwner())     // all-of group
    .meta({ owner: 'platform' }),
)

defineRule(id) builds a rule outside a policy; .addRule(rule) puts a prebuilt rule into one. Rules are plain data and can be shared across policies.

The PolicyBuilder API

targets.resources uses the plain matcher, not the dot-aware hierarchical one that rule resources use. A target of ['document'] will not cover document.draft.

Combining algorithms

When no rule matched, every algorithm returns defaultEffect with the reason No matching rules. Defaulted to deny.

Combining policies

policyCombine is engine-level and defaults to 'and'.

Not-applicable policies are skipped under all three. When nothing was applicable at all, the reason reads No policy applicable. Defaulted to deny.

Try it

1. Delete allow-owner-write and rerun the matrix. Every write, including Bob's own, becomes false. Put it back.
2. Add a suspension rule to document-ownership: deny every write when subject.attributes.status is 'suspended'. Seed the adapter with attributes: { bob: { status: 'suspended' } } and confirm Bob loses write access to his own document.
3. Add an expiry rule: deny read when resource.attributes.expiresAt is before '$environment.now'. Pass an explicit environment of { now: Date.parse('2030-01-01') } and watch the same document flip.
4. Switch document-lifecycle to algorithm('highest-priority') and give allow-otherwise a priority of 100. The deny rules stop mattering - that is the algorithm doing exactly what it says.

See also

• Building policies - the builder reference
• Rules and targets
• Conditions - the full operator semantics table
• Dollar variables and nesting
• Combining algorithms and cross-policy combination
• Chapter 4: the engine in depth