KeyCard Policy Specification — v0.1
This document is the authoritative definition of the PolicyDefinition
format and its evaluation semantics for the v0 line. SPEC.md at the
repository root is the informal overview, and GLOSSARY.md holds term
definitions. Where either of those disagrees with this document, this document
wins.
The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as in RFC 2119.
Overview
This document defines:
- The shape of a
PolicyDefinitionand itsversionfield. - What an action and a subject are, and how they're matched, including the policy-declared wildcard tokens.
- The rule-evaluation algorithm —
can/cannot/require. - The condition language and the evaluation semantics of every operator.
- The optional test-case format embedded in a policy document,
tests.
It does not define the PolicyBuilder's fluent API, the wire format (YAML
vs. JSON), or any language-specific type system.
Versioning
version is a SemVer string, MAJOR.MINOR.PATCH (e.g.
"0.1.0").
What counts as a MAJOR, MINOR, or PATCH change to this spec
This subsection governs how this specification is versioned from release to
release — guidance for spec maintainers, not something an implementation checks
at runtime. It describes the general, post-1.0 mapping; while MAJOR is
0, the pre-alpha rules below apply instead.
MAJOR: any change that could alter the allow/deny outcome for some already-valid document under the currentMAJORversion, or that makes a previously-valid document invalid (removing a field, operator, or matching guarantee; narrowing what was previously valid; changing a default).MINOR: any purely additive change — a new optional field, a new operator, new advisory (SHOULD/MAY) guidance — that cannot alter the outcome for any document that doesn't use the new feature.PATCH: wording-only changes with zero effect on any implementation's behavior (typo fixes, clarified examples, added cross-references).PATCHcarries no compatibility meaning (see Envelope).
Pre-Alpha Specification v0
While MAJOR is 0, the entire 0.y.z line is unstable and carries no
compatibility promise. A change that would otherwise count as MINOR lands
within the current 0.1 without a version bump.
Terminology
Implementation
An implementation is a library or package that loads a PolicyDefinition and
evaluates it as this document describes.
Claims
Claims are an object of key/value pairs, used either for constructing a policy (Policy Claims) or during permission checks (Subject Claims). Claims SHOULD be scoped to the subset of values the policy actually needs.
Action
An Action is something the user wants to do (Read, Create, Update,
MarkDone, ...). An Action is not tied to any particular Subject.
Subject
A Subject is something the user wants to act upon (e.g. Article, Comment,
User). A Subject can optionally carry the Subject Claims of one specific
instance (e.g. an Article with { id: 1, ownerId: 5 }). This document calls a
Subject without instance data a SubjectDef and one with instance data a
SubjectRef.
Condition and operators
A Condition is the optional fourth element of a rule. It filters which
subject instances the rule applies to. A condition operator is a $-prefixed
key inside a Condition (e.g. $eq, $gt, $hasRole). Every implementation
MUST support all of the built-in operators defined in this document.
Builder
A PolicyBuilder takes Policy Claims (arbitrary application data, e.g. a JWT or
{ ownerOf: number[] }) and produces a Policy and/or
PolicyDefinition.
This document does not define the builder's API surface. Implementations SHOULD follow the pattern used by the existing implementations.
Policy
A Policy is the object that evaluates checks (can/cannot/require). It
is constructed from a PolicyDefinition or directly by a PolicyBuilder.
Rule
A rule combines an Effect (allow or deny), an Action, a Subject, and
optionally a Condition. For example, [allow, Update, Article, { ownerId: 4 }]
reads in English as "allow the user to Update an Article when the article's
ownerId is 4."
Definition Structure
version: "0.1" # required, SemVer string
name: string # optional, informational only
description: string # optional, informational only
meta: # optional
anyAction: string | false | null # optional, defaults to "_ANY_"
anySubject: string | false | null # optional, defaults to "_ANY_"
actions: string[] # optional catalog
subjects: string[] # optional catalog
operators: string[] # optional catalog
application: any # optional, opaque application data
rules:
- [ Effect, Action, Subject, Condition? ]
tests: # optional
- name: string
description: string # optional
cases:
- name: string # optional
check: [ Action, Subject, SubjectClaims? ]
expected: boolean
Envelope
version— REQUIRED. A SemVer string (MAJOR.MINOR.PATCH).PATCHMAY be omitted from the version string (e.g."0.1"). It has no effect on compatibility either way.- Implementations MAY support a different
MAJORversion than the one they primarily target (e.g. a 2.x implementation MAY still understand 1.x documents). If an implementation does not support a document'sMAJORversion — whether older or newer than what it implements — it MUST throw aPolicyVersionExceptionwhen loading a policy rather than guess at compatibility. - Implementations MUST support every
MINORversion lower than or equal to the one they implement, within the sameMAJORversion — an implementation of 1.5.0 MUST correctly evaluate a document declaring anywhere from 1.0.0 through 1.5.0. A document declaring aMINORversion the implementation doesn't know yet (higher than what it implements, within the sameMAJOR) MUST cause aPolicyVersionExceptionwhen loading a policy. - Implementations MAY provide an option to disable
MINORversion checks (e.g. for a caller that wants to accept a document declaring a newerMINORthan the implementation knows, at its own risk), but this MUST be an explicit opt-in. - Implementations MUST ignore
PATCHwhen deciding compatibility —"1.0.0"and"1.0.7"MUST be treated identically. - Serializing a
PolicyDefinitionthat aPolicyBuilderassembled from scratch MUST stamp the builder's own implemented version. - Serializing a
PolicyDefinitionobtained from an existingPolicy(e.g.Policy.toDefinition()/def()), by contrast, MUST preserve that input definition's ownversionrather than overwrite it with the implementation's. APolicyround-tripped back to a definition MUST NOT claim a different version than the document it was constructed from.
name— OPTIONAL. A human-readable name for the policy. Informational only; it plays no role in evaluation.description— OPTIONAL. A human-readable description of the policy. Informational only.
Meta
meta is an OPTIONAL object that holds the policy's wildcard tokens, the
catalogs of Actions, Subjects, and custom operators its rules may use, and
opaque application data.
meta.anyAction / meta.anySubject
- The wildcard tokens for the policy's Action and Subject positions,
respectively. When either is not declared, implementations MUST use the
literal string
"_ANY_". - A policy MAY override either to a different string, and MAY declare one without the other.
- Either MAY instead be explicitly set to
nullorfalseto disable the wildcard mechanism for that position entirely. When disabled, every rule'sAction(orSubject) MUST be matched literally, and"_ANY_"becomes an ordinary name. - A declared value that is not a string,
null, orfalse(e.g.true, a number, a list) is invalid. Implementations SHOULD throw aPolicyLoadExceptionimmediately upon encountering one, rather than silently coercing it or passing it through as a raw value to be compared against later. - Whatever string is currently
meta.anyAction's (ormeta.anySubject's) effective value MUST NOT be used as an ordinary action (or subject) name within that policy, because a rule could not distinguish that literal name from the wildcard.
meta.actions / meta.subjects
- Optional catalogs of the action names and subject names this policy's rules may use.
- When a catalog is declared, implementations SHOULD throw a
PolicyLoadExceptionwhen loading aPolicyif a rule's action is neither the effectiveanyActionnor listed inmeta.actions(and likewise for subjects andmeta.subjects). - Each entry MUST be unique.
- The wildcard token SHOULD NOT be listed in the catalog.
- A name listed in the catalog that no rule actually uses SHOULD NOT be
treated as an issue. These catalogs describe the vocabulary a policy is
allowed to use, not a requirement that every entry be exercised. For example,
a superuser's policy consisting only of
[allow, _ANY_, _ANY_]is valid even ifmeta.actions/meta.subjectslist many names that rule doesn't mention. Validation only checks that rules don't reference undeclared names. - Implementations MAY trim a declared catalog down to only the subset of
names a policy's rules actually use (e.g. when a tool regenerates or
re-serializes a
PolicyDefinition).
meta.operators
- A catalog of the custom
$-prefixed condition operator names (e.g."$hasRole") this policy's rules use. - When declared, implementations SHOULD check every rule's
Conditionwhen loading aPolicyand throw aPolicyLoadExceptionif a rule references a custom operator not listed here. - Declaring an operator here does not implement it.
PolicyDefinitionis JSON encodable and cannot carry executable code, so the host application MUST supply the operator's behavior separately, through whatever operator-registration mechanism the implementation provides. - Every operator listed here MUST be registered when the
Policyis constructed. If one is not, the implementation MUST throw aPolicyLoadExceptionat construction, even if no rule uses it. - Each entry MUST be unique and MUST NOT name a built-in operator.
- A policy SHOULD include
meta.operatorswhenever any rule uses a custom operator. - Implementations MAY trim a declared catalog as described for
meta.actions/meta.subjects.
meta.application
- An open slot for a host application to embed its own custom data in the
PolicyDefinition— this spec imposes no shape on it and gives it no meaning. - Implementations MAY expose
meta.applicationback to the application (e.g. viadef()/toDefinition()), but MUST NOT raise an error or otherwise reject a definition merely becausemeta.applicationis present, regardless of its shape or contents.
Rules
rulesMUST be present and MAY be an empty array (an empty policy —rules: []— is structurally valid and denies everything).- It is a single, ordered list. An implementation MUST NOT treat
rulesas an unordered set. - Each entry is a tuple of
[Effect, Action, Subject, Condition?].EffectMUST be the literal string"allow"or"deny".ActionandSubjectMUST be strings.Conditionis optional; a three-element tuple[Effect, Action, Subject]is an unconditional rule.
- A rule wildcarded on both sides (its
Actionis the effectiveanyActionand itsSubjectis the effectiveanySubject) MUST NOT carry aCondition.new Policy(...)MUST throw aPolicyLoadExceptionfor such a rule, and aPolicyBuilder'sallow()/deny()(or equivalent) MUST throw an argument error as soon as it is called with one. - A rule wildcarded on only one side MAY carry a
Condition. With a concrete subject ([effect, anyAction, Article, Condition]), theConditionis evaluated against that one subject type's data. With a wildcard subject ([effect, Update, anySubject, Condition]), the rule is valid but SHOULD NOT be used: theConditionmay be evaluated against many unrelated subject shapes, and those that lack its fields fail to match silently rather than raising an error. - Conditions evaluate against the subject's data, not claims about the caller.
An "admins can do anything" rule therefore can't be written as a
both-sides-wildcarded rule with a role condition. Instead, generate a
different
PolicyDefinitionfor admins when building the policy.
Tests
tests is an OPTIONAL top-level field that embeds test cases directly in a
PolicyDefinition, so a policy's expected can outcomes travel with the
policy. Tooling can then verify a policy's intended behavior without the same
unit tests being duplicated in every implementation language.
tests:
- name: string # required — the suite's name
description: string # optional
cases:
- name: string # optional — the case's name
check: [ Action, Subject, SubjectClaims? ]
expected: boolean
- When present,
testsMUST be an array of Test Suite objects. It MAY be an empty array. - A Test Suite groups related cases under a name:
name— REQUIRED. A human-readable identifier for the suite (e.g. for a test runner's output). Informational only.description— OPTIONAL. Informational only.cases— REQUIRED. An array of Test Case objects. MAY be empty.
- A Test Case is one expected
canoutcome:name— OPTIONAL. A human-readable identifier for the case.check— REQUIRED. A tuple[ Action, Subject ]or[ Action, Subject, SubjectClaims ].- A two-element
checkMUST be evaluated as a check without instance data (aSubjectDef). - A three-element
checkMUST be evaluated with the third element as the subject's instance data (aSubjectRef).
- A two-element
expected— REQUIRED. A boolean: the expected result of callingcanwith the givencheck.
Operators
A Condition filters when a rule applies. It is evaluated against the
subject's instance data.
General requirements
- A condition that cannot be meaningfully evaluated against the given subject
(e.g. a type mismatch) SHOULD evaluate to
false. Implementations MAY log a diagnostic to alert the developer. - Implementations SHOULD NOT convert values between types when evaluating a
condition (
$substris the one exception). Implementations MAY log a diagnostic when a type mismatch is detected. - A condition that is itself a string, number, boolean, or
nullMUST be treated as shorthand for{ $eq: <that value> }:
{ status: archived } # same as { status: { $eq: archived } }
Missing fields vs. explicit null
These are two different things and MUST be distinguished:
- Missing field — the subject is an object/map that does not have the key at
all (or the subject isn't an object/map-like value in the first place). The
entire field condition evaluates to
false, whatever is nested inside it, with one exception: when the field's condition is exactly{ $ne: value }, it evaluates totrue(see$ne). Other negations, such as{ field: { $not: { $eq: value } } }, still evaluate tofalseon a missing field. - Explicit
null— the subject has the key, and its value isnull. This is a real value and is compared like any other:{ field: null }matches only whensubject.fieldisnull;{ field: { $ne: null } }matches wheneversubject.fieldis anything other thannull, including when it is missing. nullMUST NOT be treated as a wildcard that matches anything.
Built-in operators
Every operator below receives the current subject value at its point in the condition tree: initially the subject's full instance data, narrowed by each enclosing field condition.
$eq
{ $eq: value }. Matches when subject equals value.
Requirements:
- Equality MUST use value equality (not reference/identity equality) for primitives.
NaNMUST NOT equal anything, including itself, even where the host language's default equality says otherwise (e.g. Java'sDouble.equalstreatsNaNas equal toNaN).- Behavior when either side is an array or object is not defined in v0.
Policies SHOULD compare only strings, numbers, booleans, and
null.
$ne
{ $ne: value }. Matches when subject does not equal value.
Requirements:
- MUST be the exact negation of
$eqfor the samesubject/valuepair, including when the field being tested is missing: because$eqon a missing field isfalse,$neon a missing field MUST betrue.
$gt / $gte / $lt / $lte
{ $gt: number } (and $gte/$lt/$lte identically shaped). Numeric
comparison.
Requirements:
- If the subject or the value is not a number, the condition MUST evaluate
to
false. - Any comparison involving
NaNMUST evaluate tofalse.
$in
{ $in: value[] }. Matches when the array value contains subject.
Requirements:
- If
valueis not an array, the condition MUST evaluate tofalse. - Containment MUST use the same equality semantics as
$eqper element.
$has
{ $has: value }. Matches when the array subject contains value.
Requirements:
- If
subjectis not an array, the condition MUST evaluate tofalse. - Containment MUST use the same equality semantics as
$eqper element.
$substr
{ $substr: pattern }. Matches when the subject, as a string, contains a
substring described by pattern. Matching is case-sensitive.
pattern is a string built from literal characters plus these special tokens:
Token ^
: when it is the first character, anchors the match to the start of the
subject string.
Token $
: when it is the last character, anchors the match to the end of the
subject string.
Token *
: matches zero or more characters.
Token \
: escapes the next character, making it literal. For example, \^, \$,
\*, \\, and \e are the literals ^, $, *, \, and e. A trailing
\ with nothing after it MUST be ignored.
Requirements:
- A
nullor missing subject is an ordinary non-match: the condition evaluates tofalse. - Any other non-string subject is matched against its string form. This is the
one exception to the no-conversion rule. Because string forms can differ
between languages, policies SHOULD apply
$substronly to string fields. - If
patternis not a string, or it contains an unescaped^anywhere but the start or an unescaped$anywhere but the end, the pattern is malformed and the condition MUST evaluate tofalse.
$or
{ $or: Condition[] }. Matches when at least one sub-condition matches.
Requirements:
- If the operand is not an array, the condition MUST evaluate to
false. { $or: [] }MUST evaluate tofalse(no alternative can be satisfied).
$and
{ $and: Condition[] }. Matches when every sub-condition matches.
Requirements:
- If the operand is not an array, the condition MUST evaluate to
false. { $and: [] }MUST evaluate totrue(there is no unsatisfied conjunct).
$not
{ $not: Condition }. Matches when the sub-condition does not match.
Requirements:
- MUST be the exact negation of evaluating
Conditionagainst the samesubject.
$always
{ $always: true }. Matches every subject, without inspecting it.
Requirements:
- The only valid operand is
true. Any other operand, includingfalse, is malformed and the condition MUST evaluate tofalse. - Under a field condition, the usual missing-field rule still applies:
{ field: { $always: true } }evaluates tofalsewhenfieldis missing.
$never
{ $never: true }. Matches no subject.
Requirements:
- MUST evaluate to
falsefor every subject. - The only valid operand is
true. Any other operand, includingfalse, is malformed (and, like every malformed condition, evaluates tofalse).
Field condition
{ fieldName: Condition } — any object key that does not start with $.
Requirements:
- MUST narrow the subject to
subject[fieldName]and evaluateConditionagainst that narrowed value. - When
fieldNameis missing fromsubject, the condition MUST evaluate tofalse(except for a bare$ne; see Missing fields vs. explicitnull). - In v0, field conditions reach only the subject's top-level fields. The
Conditionunder a field key MUST NOT itself narrow into another field (so{ author: { name: "Alice" } }is not supported); if it does, the condition MUST evaluate tofalse. Operators such as$ne,$or, or$gtmay still be used on the field's own value.
$field (explicit field access)
{ $field: [name, Condition] }. Equivalent to the bare-key field condition, but
the field name is given as a tuple element instead of as the object key.
Requirements:
- A field whose name starts with
$MUST be accessed with$field, because a$-prefixed object key is always treated as an operator. - The same top-level-only restriction applies as for a bare-key field condition.
- If the operand is not a two-element
[name, Condition]array, the condition MUST evaluate tofalse.
Custom operators ($op)
{ $op: value }, where $op is not a built-in operator.
The implementation delegates to an operator the host application registered when
constructing the Policy, through whatever registration mechanism it provides.
A custom operator receives the same (subject, value) pair a built-in does, plus
a context offering something equivalent to
resolveSubcondition(subject, condition). This lets a custom operator recurse
into the condition language (e.g. to implement its own $and-like combinator)
the same way the built-in $and/$or/$not do.
Requirements:
- A
$-prefixed key is always an operator, never a field name. - An operator that is neither registered nor listed in
meta.operatorsMUST evaluate tofalse. (One that is listed but not registered is a construction-time error; seemeta.operators.)
Multi-key condition objects
A condition object MAY contain more than one key. Every key in a condition object MUST be evaluated, and the object matches only if all of them do. Keys MUST be implicitly ANDed together, whether they are operators, field names, or a mix of both:
{ $ne: null, status: "open" } # subject is not null, AND subject.status == "open"
- An operator key (
$eq,$gt,$or, ...) MUST NOT "consume" the whole object or cause sibling keys to be ignored.
Evaluating a check
can / cannot / require
The last matching rule wins:
function can (action, subject) {
for (const [effect, ruleAction, ruleSubject, ruleCondition] of reverse(rules)) {
if (!matchesAction(action, ruleAction)) continue
if (!matchesSubject(subject.name, ruleSubject)) continue
if (ruleCondition) {
if (!hasInstance(subject)) continue
if (!evaluate(getInstance(subject), ruleCondition)) continue
}
return effect == 'allow'
}
return false // nothing matched: default deny
}
function matchesAction (action, ruleAction) {
return action == ruleAction || ruleAction == effectiveAnyAction(meta)
}
function matchesSubject (subjectName, ruleSubject) {
return subjectName == ruleSubject || ruleSubject == effectiveAnySubject(meta)
}
// meta.anyAction/meta.anySubject: absent -> "_ANY_" default; an explicit
// string -> that string; explicit null or false -> DISABLED (a sentinel no
// rule's Action/Subject can ever equal, so the wildcard branch of
// matchesAction/matchesSubject above never succeeds); anything else -> throw.
function effectiveAnyAction (meta) {
return resolveWildcard(meta?.anyAction)
}
function effectiveAnySubject (meta) {
return resolveWildcard(meta?.anySubject)
}
function resolveWildcard (declared) {
if (declared === undefined) return '_ANY_'
if (declared === null || declared === false) return DISABLED
if (typeof declared === 'string') return declared
throw new PolicyLoadException('...') // anything else is invalid
}
matchesAction/matchesSubject perform exact, case-sensitive string
comparison: the string "read" MUST NOT match a rule written for
"Read", and if the effective anyAction is "_ANY_", the string
"_any_" MUST NOT be treated as the wildcard. Field names inside conditions
are likewise matched exactly as written.
The subject argument can take three shapes:
- A bare string (
"Article"). Implementations MAY support this; it is checked without instance data. - A
SubjectDef(a subject type with no instance). Implementations MUST support this; it is checked without instance data. - A
SubjectRef(a subject type plus a wrapped instance). Implementations MUST support this.hasInstanceabove istrueonly for this shape.
A check without instance data (a bare string or SubjectDef) still runs the
algorithm above, but it can never satisfy a rule that carries a Condition,
because hasInstance(subject) is false:
can("Update", "Article")against the rule[allow, Update, Article, { owner_id: 1 }]isfalse(assuming no other rule matches). A condition that can't be checked without instance data counts as "does not match," not as an error or an automatic pass.- However an implementation represents a
SubjectDefinternally, it MUST NOT expose fields that could make an ordinary condition (onowner_id,status, etc.) match by accident.
cannot(action, subject) MUST return the exact negation of
can(action, subject). require(action, subject) MUST perform the same
evaluation as can, but instead of returning a boolean it returns normally when
the result is true and signals failure (e.g. by throwing) when it is false.
The exact error type is up to the implementation.
An implementation MAY implement this algorithm differently (an index by
action/subject, a compiled decision structure, etc.) as long as its observable
can/cannot/require results are identical to this reverse scan for every
input. Every implementation MUST verify that equivalence against the shared
conformance fixtures (test/fixtures in the KeyCard repository), not by
inspection alone.
Every v0-conformant implementation MUST satisfy these requirements:
- Default deny. If the scan reaches the front of
ruleswithout a single match, the result MUST befalse. An empty policy (rules: []) denies everything. - Last-matching-rule-wins. An implementation MUST scan
rulesfrom the last-declared entry back to the first, and MUST return as soon as it finds a rule whose action, subject, and (if present) condition all match. That rule's effect (allowordeny) is the answer; every earlier rule, however specific or unconditional, is irrelevant. There is no "any deny beats any allow" veto and no combining of several matching rules' effects: exactly one rule decides the outcome, or none does and default deny applies.- A rule with no
Conditionallows or denies every instance of its action/subject combination, unless a rule declared after it also matches. A later, more specific rule for the same action/subject can reopen or reclose it. To make a blanket rule final, declare it after the rules it should override. - Each rule's condition is evaluated independently against the same subject. Matching rules are not combined; only the last-declared one decides.
- Policy authors SHOULD place general rules first and the rules that
override them later, including a later
allowthat reopens something an earlierdenyclosed. Reordering two overlapping rules can flipcan's answer. Implementation documentation SHOULD explain this convention. - Implementations MAY warn about a blanket rule (no
Condition) that is declared after other rules for the same action/subject, since it makes those earlier rules unreachable.
- A rule with no
- Order is significant. Implementations, builders, and parsers MUST
preserve declaration order end to end: moving a rule can change
can's answer for the cases it overlaps with. - Wildcard matching is policy-scoped.
matchesAction/matchesSubjectuse this policy's own effectiveanyAction/anySubject; there is no global wildcard token.- Both default to
"_ANY_", so[allow, _ANY_, _ANY_]is a valid rule matching every action on every subject, even in a policy with nometa.[allow, _ANY_, Article]matches every action onArticle;[allow, Delete, _ANY_]matchesDeleteon every subject. Wildcards are plain string comparisons, not regex or glob patterns. - Either can be disabled by setting it to
nullorfalse. For a disabled position, no string has wildcard meaning, and"_ANY_"becomes an ordinary name.
- Both default to
- A rule wildcarded on both sides MUST be unconditional. See Rules for the exact requirement and the errors implementations must raise.
Running tests
- An implementation that can run a
PolicyDefinition's embeddedtests(whatever it calls that operation, and whatever its report looks like) MUST, for each case, callcanwith that case'scheckelements as arguments, and MUST report the case as passing if and only if the result equalsexpected. - Running
testsMUST NOT mutate thePolicyinstance or otherwise affect its subsequentcan/cannot/requirebehavior. - This spec does not require a report format or a CLI, and it does not require
new Policy(...)to reject an otherwise-validPolicyDefinitionbecause one of its test cases fails. Whether a failing case blocks construction, a build, or a CI job is up to the application or tooling.
Prior work
KeyCard's condition language and rule-based allow/deny model draw on
CASL, a JavaScript authorization library. In particular,
the last-matching-rule-wins combining behavior mirrors CASL's own approach to
resolving overlapping rules. KeyCard differs from CASL in scope: a declarative,
JSON/YAML-serializable PolicyDefinition, produced server-side and evaluated in
any language, rather than an in-process JavaScript ability builder. It also
differs in the details: the condition operators, the meta catalogs and
wildcard tokens, and the validation and exception behavior. This document
defines KeyCard's behavior in full and does not assume familiarity with CASL.
Appendix: worked example
version: "0.1"
name: "Article Ownership Policy"
description: "Users can only modify their own articles"
meta:
actions: [ Read, Create, Update, Delete ]
subjects: [ Article ]
operators: [ $hasRole ]
rules:
- [ allow, Read, _ANY_ ]
- [ allow, Create, Article ]
- [ allow, Update, Article, { owner_id: 1 } ]
- [ allow, Delete, Article, { owner_id: 1 } ]
- [ deny, Delete, Article, { status: archived } ]
- [ allow, Delete, Article, { $hasRole: admin } ]
tests:
- name: "ownership"
cases:
- name: "owner can update their own article"
check: [ Update, Article, { owner_id: 1 } ]
expected: true
- name: "non-owner cannot update someone else's article"
check: [ Update, Article, { owner_id: 2 } ]
expected: false
- name: "archived articles"
cases:
- name: "owner cannot delete their own archived article"
check: [ Delete, Article, { owner_id: 1, status: archived, roles: [ ] } ]
expected: false
- name: "admin can delete an archived article regardless of ownership"
check: [ Delete, Article, { owner_id: 1, status: archived, roles: [ admin ] } ]
expected: true
The first rule uses the default subject wildcard, _ANY_, because this policy
declares no meta.anySubject. A rule wildcarded on only one side may carry a
condition, but this one doesn't need one.
The last rule is declared last on purpose. It is an allow whose condition
($hasRole: admin) can still be satisfied for an archived article, so an admin
can delete an archived article even though the deny rule before it would
otherwise block that. This is last-rule-wins overriding an earlier rule.
$hasRole isn't a built-in operator. It is a custom operator that this policy
declares in meta.operators, so the host application must register it when
constructing the Policy (e.g. one that checks
subject.roles.includes("admin")). If the application forgets,
new Policy(...) throws a PolicyLoadException immediately, rather than every
admin-only check quietly failing later. Because conditions only see subject
data, the application must include roles in the Subject Claims it passes to
the check.
The tests block records this policy's intent as executable cases. The
"ownership" suite exercises the third and fourth rules, and the "archived
articles" suite pins down the last-rule-wins interaction described above, so an
edit that reorders or narrows those rules is caught by re-running tests.