specs/acl/update/v0_2/payload library

Classes

AclEntry
One access-control entry: who the grant is for (subject), the ceiling it is held under (role), where the subject may act (act) and approve (approve), and which capabilities it may exercise (capabilities) and approve (approveCapabilities). The act axis and the approve axis are independent and a consumer MUST resolve them separately: act + capabilities (+ keys) answer "may this subject do X"; approve + approveCapabilities answer "may this subject ratify someone else doing X". Neither implies the other. An entry with act: {scope: none} and an approve scope other than none is a least-privilege approver — able to satisfy an approval and unable to initiate any change.
AclEntryStepUp
Per-entry authentication step-up configuration, consumed by the ACL maintainer when it gates an operation behind a step-up (see auth/step-up/policy). ADDITIVE-ONLY: a per-entry setting MAY raise the assurance required of this subject above the maintainer's system-wide floor, but MUST NOT lower it. The maintainer resolves the effective requirement as the strictest of (system floor, this entry). Carried forward from 0.1 unchanged.
ApproveCapabilityScopeListed
Exactly the listed capabilities, intersected with the role's approve ceiling where the maintainer's roles define one.
AuthorityScopeAll
Unrestricted: every context the maintainer holds, present and future. On the act axis this is a super-administrator (or, at a maintainer without contexts, an entry whose authority is not narrowed by location).
AuthorityScopeContexts
The named contexts and, where the maintainer's contexts are hierarchical, every descendant of them — and nowhere else. contexts MUST carry at least one path.
AuthorityScopeNone
No authority on this axis. Stated, not implied: none is how an entry says it may not act (a least-privilege approver) or may not approve.
CapabilityGrant
A capability held by an entry, optionally qualified by a resource, optionally marked additive. A qualified grant confers nothing without a live entry for the same subject, and is bounded as delegated authority is.
CapabilityRef
A capability, optionally qualified by a resource. Used where a capability is named but not granted — a role's ceiling, a role's approve ceiling, an entry's approvable capabilities. An unqualified reference covers every resource of the capability's kind.
CapabilityScopeCeiling
The role's full ceiling on this axis, unnarrowed: what the role admits, the entry holds (or, for approvable capabilities, may approve). Stated, not implied — it is the explicit spelling of "no narrowing".
CapabilityScopeListed
Exactly the listed grants: (role ceiling ∩ non-additive grants) ∪ additive grants.
CapabilityScopeNone
No capabilities on this axis.
KeyScopeAll
Every key the entry's act scope reaches.
KeyScopeListed
Exactly the listed keys, intersected with the entry's act scope.
KeyScopeNone
No keys.
Payload
Amend the non-role attributes of an existing AclEntry 0.2: its act scope (widening only), approve scope, capability scope, approvable-capability scope, key scope, label, expiry or step-up requirement. Every member REPLACES the stored value; an omitted member leaves it unchanged. Role changes are NOT expressible here — they go through acl/change-role, which requires the current role as a compare-and-swap. delegatedBy and the provenance timestamps are maintainer-populated and not settable.
PayloadStepUp
Replacement per-entry step-up configuration. Same additive-only rule as on the entry itself: it MAY raise the assurance required of this subject above the system floor but MUST NOT lower it.
Response
The success response to an acl/update/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/acl/update/0.2#response.

Extension Types

AclEntryStepUpRequire
Minimum step-up mode this subject MUST satisfy for gated operations, raising the system floor. self = the subject re-authenticates its own session; delegated = a separate approver MUST ratify. Omitted → the system floor applies unchanged. A value weaker than the resolved floor is ignored (additive-only).

Constants

payloadSchemaJson → const String
This specification's payload schema, as JSON text.
responsePayloadSchemaJson → const String
As payloadSchemaJson, for the success-response variant.
responseSpec → const SpecPolicy
The SPEC §7.2 policy for the success-response variant.
responseTypeUri → const String
The success-response form of typeUri (SPEC §4.4.1).
spec → const SpecPolicy
The SPEC §7.2 policy for the request variant, taken from this specification's front matter.
typeUri → const String
The Trust Task type URI this library's Payload is carried under.

Typedefs

ApproveCapabilityScope = Object?
An explicit statement of the capabilities a subject may approve. Exactly one of ceiling (the role's full approve ceiling), none, or listed with a NON-EMPTY list of CapabilityRef.
AuthorityScope = Object?
An explicit authority scope — used for both the act scope and the approve scope of an entry. Exactly one of three shapes, discriminated by scope: all, none, or contexts with a NON-EMPTY list. The empty list is not a fourth shape: it is invalid, so a serializer that drops or empties the list produces a document that fails validation rather than one that silently means something else.
Capability = String
Opaque identifier of one administrative power in the maintainer's capability registry — lowercase dot-separated segments (e.g. keys.sign, vtc.roles.assign, git.repo.manage). A consumer MUST NOT treat a capability it does not recognise as granted.
CapabilityScope = Object?
An explicit statement of the capabilities an entry holds. Exactly one of three shapes, discriminated by scope: ceiling (the role's full ceiling), none, or listed with a NON-EMPTY list of CapabilityGrant. The empty list is invalid, not a fourth shape.
ContextPath = String
Opaque identifier of one of the maintainer's contexts, compared by the maintainer's own ancestry predicate. Its grammar is the maintainer's.
Ext = Map<String, dynamic>
Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.
KeyScope = Object?
An explicit key scope. Exactly one of three shapes, discriminated by scope: all, none, or listed with a NON-EMPTY list of key identifiers. The empty list is invalid, not a fourth shape.
ResourceQualifier = String
Opaque qualifier naming the part of the maintainer's resources a capability applies to (e.g. git-ns:github.com/acme, git-repo:github.com/acme/r#4211, policy:join). Its grammar and containment rule are the maintainer's: a qualified capability covers the named resource and the resources inside it. A qualifier MUST NOT be read as widening the entry's act scope.