Index

Generalized Cooperative Delegation (GCD) Credentials¶

Purpose¶

These credentials document the authorizations, constraints, and duties of delegated authority — what a delegate is empowered to do on behalf of a delegator, and under what limits.

The paradigmatic and strongest way to bind a delegate to a delegator is a KERI-style cooperative delegation: a special delegate AID bound to the delegator's AID via an inception event (dip) on the delegate side, and an interaction event (ixn) in the KEL on the delegator side. See section 2.3.4 in version 2.6 of the KERI whitepaper. This interlocking two-way binding is what gives rise to the term "cooperative delegation", and it is significantly more secure and flexible than many other delegation mechanisms. It remains fully supported and is the exemplar these credentials were named for.

But it is not a precondition. A GCD credential is a standard targeted ACDC; its authorization and constraint mechanics do not depend on the issuee being KEL-anchored to the issuer. It is usable whenever an issuer grants constrained authority to a delegate AID, whether or not that delegate is cooperatively delegated from the issuer — for example, an organization authorizing an independently-controlled role AID to act on its behalf. (This is what "Generalized Cooperative Delegation" implies.)

Whichever binding is used, it only proves the state of the delegation relationship and defines how it is controlled. It does not specify which specific actions are expected of the delegate, or what constraints govern the exercise of the authority they receive. That is the purpose of the Generalized Cooperative Delegation (GCD) credentials described here.

Suggested visual: svg | 256 px | 64 px | 32 px

Types of authority¶

In the physical world, authority can be exercised in many modalities, and constraints often take advantage of these modalities. For example, a king might delegate to a treasurer access to the royal vault, and this delegation might take the form of a key that unlocks a door. In such cases, there could never be risk that the treasurer could sign a treaty that sends the kingdom to war, since the door and the treaty have different affordances.

In the digital world, authority may be asserted in many ways, but it is always proved by a digital signature. A delegate always signs something, whether it be a message in the Trust-Spanning Protocol, an SMS message, a purchase order, an XBRL report, etc. The fact that they've signed is easily verified; the question GCD credentials answer is whether the delegate had the authority to act in behalf of the delegator when they affixed that signature.

Schema¶

See gcd.schema.json and also rules.json.

Version 3.1 admits custom keys inside the constraints container and inside a duty (this.i @vy7qoj), so an issuer can express a constraint or an obligation the standard fields do not cover. The fail-closed rule on an unrecognized constraint key is unchanged in substance — it is now an obligation on the verifier rather than something schema validation enforces. See Constraints below.

Version 3.0 adopts the ACDC v2 envelope (this.i @enr3eg): credentials are acm/JSON messages whose top-level fields appear in the order [v, t, d, u, i, rd, s, a, e, r], with SAIDs computed by the v2 most-compact-form algorithm. rd (the SAID of the issuer's credential-status registry inception) replaces v1's ri and is required — the ACDC spec makes rd optional for correlation minimization, but a GCD is authority evidence, so secure discovery of its revocation registry wins here. t is optional (a JSON ACDC without it is of type acm), and the attribute block's d is optional (the reference v2 builder emits none; a d-less attribute section simply cannot be compacted). Earlier versions remain published and resolvable by their original SAIDs: gcd-2.0.1 (the same semantic content on the v1 envelope) and gcd-1.0.0 (the pre-SDA c_* model).

Constraints¶

Delegated authority may need to be constrained in many ways. For example, the talent agent for a famous rock 'n roll diva may be able to represent her, subject to constraints like these:

• The agent cannot represent her outside the context of the music business (can't vote on the diva's behalf in an election, can't sign their will, can't make medical decisions).
• The agent may only have authority to represent the diva in a particular geography or language or market.
• The agent's authority may be contingent on the agent remaining licensed by the industry.

GCD credentials allow the issuer to express analogous constraints. These live inside the constraints container in the attributes block (the enabling "may"). Each field is optional; an absent field means that dimension is unconstrained. For example:

• goals constrains the goal-driven behaviors in which the delegate can engage on behalf of the delegator (e.g., to sign SMS messages, to buy, to sell, to schedule appointments...).
• acts names the (effect, state-kind) points the delegate may act on — the enabling "may" over the act grid. An act is located by its effect (observe, create, modify, preserve, destroy) over a kind of state (info, record, commitment, authority, resource, relationship); these are the two axes of one coordinate, and neither is meaningful alone — "create" is create what, "commitment" is do what to it. Each entry is a point written effect state-kind (e.g. create commitment), or a one-sided brace enumeration — observe {info, record} (one effect, several kinds) or {create, modify} record (several effects, one kind). An act is authorized only if every point it occupies is covered (filing a return is create record and create commitment in one move). The gate an act must clear (auto / rule / human) is derived per act from its points and its target via the governance framework (gfw) — not enumerated here. A pure delegator (exerciseMode: authorize) omits acts entirely, having an empty act surface.
• domains names the authorization domain(s) in which the delegated authority applies.
• physGeos constrains the locations in which a physically present delegate can exercise their delegated authority.
• virtGeos constrains where a potentially remote (virtually present) delegate can be located while exercising their delegated authority.
• jurisdictions constrains the legal jurisdictions in which the delegate can undertake actions with their delegated authority that legally bind the delegator (e.g., to sign a contract on the delegator's behalf).
• icals constrains the days and times, and possibly the URLs, in which the delegate can exercise their delegated authority (e.g., only when, in India's timezone, it is a Saturday or Sunday between midnight and noon, and only in a particular slack channel).
• monetaryLimit creates a ceiling for the financial stakes of the delegated action; that is, the delegate can act only in contexts where a financial value < N is at stake. Value is a string that contains a number followed by a space, then units: an ISO 4217 currency symbol, a three-letter cryptocurrency abbreviation, or another brief single-token symbol with obvious meaning: "25 CHF", "0.3 BTC", "4 OZ-XAU". This field is money-locked — it is not a general "stakes" quantity.
• protos constrains protocol+role combinations in which the delegate can exercise their delegated authority (e.g., the delegate is allowed to play the getter role in the vtp protocol).
• proofs identifies schemas for proof requests in the IPEX protocol; the delegate's authority depends on their ability to prove what the schema demands (e.g., a chauffeur is allowed to drive the delegator's limousine as long as they can prove they have a valid driver's license). This constraint should not be confused with ACDC edges (chained credentials), which justify the delegator's status in the first place, and which are the SAIDs of concrete credentials rather than identifiers of schemas which could satisfy a constraint.
• validFrom / validUntil bound the validity window as single absolute floor / ceiling.
• humanReview carries free-text instructions that force human judgment; any GCD with this field MUST NOT be verified without a human.

Two sibling axes sit alongside constraints in the attributes block:

• terminatingEvents — voiding polarity: proof-shaped attested events that end the authority when any one fires. A GCD that carries them MUST also carry validUntil as a hard backstop.
• disclosables — the outbound axis: the credential schemas a delegate MAY reveal about its principal.

The facet container carries relationship metadata — role, relationType (delegation / guardianship / controllership / stewardship), liableParty (who answers outward if it goes wrong), presentsAs (the facet-AID the act is presented under), and exerciseMode (act / authorize / both). The facet is descriptive; only constraints gates the authorization decision.

All fields inside constraints share these semantic rules:

1. Enforceable constraints live only inside the constraints container (or in the role field when gfw is defined). Nothing outside constraints constrains, and an unrecognized key inside constraints is fail-closed — a verifier that does not recognize it MUST assume that constraint is unmet and MUST deny. (See the noConstraintOutsideConstraints rule.)
2. Each field MUST identify one or more values that are allowed (e.g., with a regex or an allow list). Within a single field, values are effectively ORed, meaning that any match is enough to satisfy that field. If the jurisdictions field says that valid jurisdictions are ["FR", "DE", "IN"], then the delegator authorizes the delegate to take legally binding actions if they are enforceable in France OR Germany OR India.
3. Across all fields, matches are ANDed, meaning that all of the constraints must be satisfied. Building on the previous example of jurisdictions, if the virtGeos field also says that valid locations for the remote delegate are ["FR", "DE", "IN"], then the delegate's actions are valid if they are legally enforceable in one of the 3 legal jurisdictions (first field), AND if the delegate appears to be operating from one of those same 3 countries (second field).

Because of the third rule, these credentials do not support graduated disclosure. All constraints must be disclosed every time a verifier is evaluating delegated authority.

Custom constraints¶

The fields above are the standard dimensions, but they are not the only ones an issuer may use. As of 3.1.0 the constraints container accepts custom keys (additionalProperties: true), and so does a duty in the rules block. A custom key takes its semantics from the governance framework named in gfw, and useStdIfPossible still obliges an issuer to reach for a standard field wherever one fits — an absent standard field must keep meaning "unconstrained in that dimension".

What this does not change is rule 1 above. A verifier that meets a key here it does not understand MUST assume the constraint is unmet and deny. What changed is who enforces that: through 3.0.0 the schema itself refused the credential, which made a plain JSON Schema validator a stand-in for the gate. It never was one. Validating against this schema is not an authorization decision — the schema admits a custom key without vouching for it, and any verifier that deals in GCD credentials owes the fail-closed check in its own code. The reasoning is recorded at this.i @vy7qoj.

gfw and useStdIfPossible both presumed custom constraints from the start; before 3.1.0 neither could be honored, because there was no way to write one.

Governance Framework¶

These credentials are governed by rules to enhance assurance, discourage abuse, and keep use cases crisp. The current rules are stated in rules.json and are identified by SAID ENiUyBCG2MjCHa9djlgHiogd6uZHECc09ZELmQ3fEMzR. Five are disclaimers (noRoleSemanticsWithoutGfw, issuerNotResponsibleOutsideConstraints, noConstraintOutsideConstraints, useStdIfPossible, onlyDelegateHeldAuthority).

In v2.0 the rules block also carries first-class duties (the "must"), each named by its bearer. A bearer: delegate duty is a structured obligation {effect, goal, cadence?, priority}; a bearer: issuer duty names a governance obligation {rule, l?, priority}. Since 3.1.0 a duty may also carry custom keys, defined by the framework named in gfw; bearer itself stays closed, so an unknown bearer is still rejected. The baseline ruleset carries timelyReviewAndRevoke — the issuer's standing duty to review each delegation on a cadence appropriate to its stakes and to revoke or narrow it promptly once the conditions that justified the grant no longer hold (it does not extend authority; see this.i @k3wm7d). Voiding of an authority by an attested event is expressed with the terminatingEvents axis in the attributes block (this.i @v5nq2r).

New governance frameworks can be written that supplement these rules; see the gfw field in the schema. It is also possible to modify or override these rules, by placing a different value in the r field. The act of issuing or receiving a GCD credential constitutes binding acceptance of the rules.

Worked examples¶

The canonical example.json is a minimal valid instance. The examples/ gallery shows the GCD feature set across five scenarios — each is a full, SAID-minted credential that the conformance linter validates (schema-validity, s-vs-$id, and SAID self-consistency), so none can silently drift:

The invalid/ corpus holds the should-reject fixtures. Each is the canonical example one mutation away from valid: a missing rd (the v2 envelope's required registry binding), a missing issuee (a.i), a missing top-level s, a non-string top-level d, an acts point missing its state-kind, a two-sided brace, an unknown acts token, terminatingEvents without a validUntil backstop, exerciseMode: delegated-only (the rejected pre-reconciliation token), a malformed monetaryLimit, an unknown duty bearer, a delegate duty missing its effect, and a non-integer duty priority.

The corpus lost one fixture at 3.1.0: an unknown key inside constraints is now valid, so constraints-unknown-key.json was deleted rather than rewritten. Its job — proving the schema does not go quietly on that key — passed to a positive oracle, the maxDeploysPerDay / escalateTo pair in ai-deploy-agent, which 3.0.0 rejected and 3.1.0 accepts. A regression to a closed container fails the conformance suite on that example.