@openlfcp/wire 0.2.2 → 0.3.0

package/dist/capability.d.ts

@@ -15,6 +15,11 @@ import type { PrincipalDescriptor } from "./principal.js";
  * H). Evaluating at an older H means using the state at that H (see
  * `stateAt` on a linear chain result), so a later revocation never
  * changes an earlier answer.
+ *
+ * With devices (§80.1): `hasAbility` is `holds`, owner-only rules use
+ * `ownerAction`, issuer comparisons use `actsFor` at the previous head, and
+ * a bound Principal is never a grant subject, claimant or new owner. A
+ * chain without device records gives the answers of §80 alone.
  */
 /** §17.1 standard ability codes. */
 export declare const ABILITY: Readonly<{
@@ -44,6 +49,8 @@ export interface Grant {
     readonly id: ControlRecordId;
     readonly source: "grant" | "claim";
     readonly issuer: PrincipalId;
+    /** §79 `issuer_root`: `actsFor(issuer)` at the head the grant was committed on. */
+    readonly issuerRoot: PrincipalId;
     readonly subject: PrincipalId;
     readonly abilities: readonly bigint[];
     readonly delegable: readonly bigint[];
@@ -68,12 +75,30 @@ export interface CapabilityState {
  */
 export declare function isGrantActive(state: CapabilityState, grantId: Uint8Array): boolean;
 /**
- * Whether `principal` holds `ability` at the head of `state`: the owner
- * holds every standard ability implicitly (§17.1, no self-grant); anyone
- * else holds it through an active grant that confers it. Unknown codes and
- * the reserved ability 9 are held by no one (§17.1, §23.1).
+ * `holds(P, A)` (§80.1): whether `principal` holds `ability` at the head of
+ * `state`. A Principal that no device record names holds it directly: the
+ * owner implicitly (§17.1), anyone else through an active grant that
+ * confers it. A bound Principal holds nothing of its own (N4): only an
+ * active device holds, everything when it is an owner-acting device of
+ * the owner, else what its mask lists and its root holds. Unknown codes,
+ * the reserved 9, and 12 and 13 (mask-only codes) are held by no one.
+ *
+ * `holds(P, 11)` is false for every bound Principal, `owner/act` included
+ * (§80.1, spec#2 1cfe51b): invite/claim belongs to invitation grants, and
+ * owner/act confers the standard abilities 1-10 only.
  */
 export declare function hasAbility(state: ControlState, principal: PrincipalId, ability: bigint): boolean;
+/**
+ * W §17.5 Exposure: the Principals registered at `before` (the state a
+ * DEVICE_REVOKE is accepted on) that hold `data/read` there and not at
+ * `after` (the state after it): the revoked device itself or any device
+ * its revocation suspends through the cascade. The record is exposing
+ * exactly when this is non-empty. Computed from the Resource's own chain
+ * alone; it is what the rotation policy of IDENTITY-PROFILE-01 §8 reacts to.
+ */
+export declare function exposedReaders(before: ControlState, after: ControlState): readonly PrincipalId[];
+/** Whether the revocation that took `before` to `after` is exposing (W §17.5). */
+export declare const isExposingRevocation: (before: ControlState, after: ControlState) => boolean;
 /** Every standard ability `principal` holds at the head of `state`, ascending. */
 export declare function abilitiesOf(state: ControlState, principal: PrincipalId): readonly bigint[];
 /**
@@ -98,10 +123,11 @@ export type Authorization = {
  */
 export declare function authorizeControlRecord(record: ControlRecord, state: ControlState): Authorization;
 /** The capability transitions of an applied record (called by applyRecord). */
-export declare function applyCapabilities(grants: ReadonlyMap<string, Grant>, record: ControlRecord): ReadonlyMap<string, Grant>;
+export declare function applyCapabilities(state: ControlState, record: ControlRecord): ReadonlyMap<string, Grant>;
 /**
  * §25.2 Key Package authority at the package's referenced Control Head:
- * the sender must hold key/distribute, and the recipient must hold
+ * the sender must hold key/distribute or be of the recipient's root
+ * (`sameRoot`, §80.1), and the recipient must hold
  * data/read, "except for an Invitation Principal explicitly authorized by
  * an active invite grant: a recipient that is the subject of an active
  * grant that includes and still confers invite/claim". `epoch` is the
@@ -140,4 +166,6 @@ export declare function verifyOwnerTransfer(record: ControlRecord, state: Contro
  * before can still be verified. Undefined for other records.
  */
 export declare function transferIssuerDescriptor(record: ControlRecord): PrincipalDescriptor | undefined;
+/** The new owner a transfer commit names (offer field 3), whoever signed the commit. */
+export declare function transferNewOwner(record: ControlRecord): PrincipalDescriptor | undefined;
 //# sourceMappingURL=capability.d.ts.map

package/dist/capability.js

@@ -1,6 +1,8 @@
-import { bytesEqual, controlRecordId, toHex, } from "@openlfcp/core";
+import { bytesEqual, controlRecordId, fromHex, principalId, toHex, } from "@openlfcp/core";
 import { parseOwnerTransferAccept, parseOwnerTransferOffer, } from "./control.js";
 import { objectId, verifySignedObject } from "./cose.js";
+import { activeDevice, actsFor, authorizeDeviceGrant, authorizeDeviceRevoke, authorizeOwnerChain, isBound, offerSigner, ownerAction, sameRoot, } from "./device-state.js";
+import { put } from "./persistent-map.js";
 /**
  * The LFCP capability engine (LFCP-WIRE-01 §17, §18, §20, §19, §25.2).
  *
@@ -14,6 +16,11 @@ import { objectId, verifySignedObject } from "./cose.js";
  * H). Evaluating at an older H means using the state at that H (see
  * `stateAt` on a linear chain result), so a later revocation never
  * changes an earlier answer.
+ *
+ * With devices (§80.1): `hasAbility` is `holds`, owner-only rules use
+ * `ownerAction`, issuer comparisons use `actsFor` at the previous head, and
+ * a bound Principal is never a grant subject, claimant or new owner. A
+ * chain without device records gives the answers of §80 alone.
  */
 /** §17.1 standard ability codes. */
 export const ABILITY = Object.freeze({
@@ -90,15 +97,8 @@ function grantConfers(state, g, ability) {
         return false;
     return ability !== ABILITY.INVITE_CLAIM || !claimsExhausted(g);
 }
-/**
- * Whether `principal` holds `ability` at the head of `state`: the owner
- * holds every standard ability implicitly (§17.1, no self-grant); anyone
- * else holds it through an active grant that confers it. Unknown codes and
- * the reserved ability 9 are held by no one (§17.1, §23.1).
- */
-export function hasAbility(state, principal, ability) {
-    if (!confers(ability))
-        return false;
+/** `direct(P, A)` (§80.1): §80 steps 2–7 for P itself; the owner holds every standard ability. */
+function direct(state, principal, ability) {
     if (isOwner(state, principal))
         return true;
     for (const g of state.grants.values())
@@ -106,6 +106,54 @@ export function hasAbility(state, principal, ability) {
             return true;
     return false;
 }
+/**
+ * `holds(P, A)` (§80.1): whether `principal` holds `ability` at the head of
+ * `state`. A Principal that no device record names holds it directly: the
+ * owner implicitly (§17.1), anyone else through an active grant that
+ * confers it. A bound Principal holds nothing of its own (N4): only an
+ * active device holds, everything when it is an owner-acting device of
+ * the owner, else what its mask lists and its root holds. Unknown codes,
+ * the reserved 9, and 12 and 13 (mask-only codes) are held by no one.
+ *
+ * `holds(P, 11)` is false for every bound Principal, `owner/act` included
+ * (§80.1, spec#2 1cfe51b): invite/claim belongs to invitation grants, and
+ * owner/act confers the standard abilities 1-10 only.
+ */
+export function hasAbility(state, principal, ability) {
+    if (!confers(ability))
+        return false;
+    if (!isBound(state, principal))
+        return direct(state, principal, ability);
+    if (ability === ABILITY.INVITE_CLAIM)
+        return false;
+    const d = activeDevice(state, principal);
+    if (d === undefined)
+        return false;
+    if (ownerAction(state, principal))
+        return true;
+    return d.mask.includes(ability) && direct(state, d.root, ability);
+}
+/**
+ * W §17.5 Exposure: the Principals registered at `before` (the state a
+ * DEVICE_REVOKE is accepted on) that hold `data/read` there and not at
+ * `after` (the state after it): the revoked device itself or any device
+ * its revocation suspends through the cascade. The record is exposing
+ * exactly when this is non-empty. Computed from the Resource's own chain
+ * alone; it is what the rotation policy of IDENTITY-PROFILE-01 §8 reacts to.
+ */
+export function exposedReaders(before, after) {
+    const out = [];
+    for (const [hex, d] of before.devices) {
+        if (!d.registered)
+            continue;
+        const p = principalId(fromHex(hex));
+        if (hasAbility(before, p, ABILITY.DATA_READ) && !hasAbility(after, p, ABILITY.DATA_READ))
+            out.push(p);
+    }
+    return Object.freeze(out);
+}
+/** Whether the revocation that took `before` to `after` is exposing (W §17.5). */
+export const isExposingRevocation = (before, after) => exposedReaders(before, after).length > 0;
 /** Every standard ability `principal` holds at the head of `state`, ascending. */
 export function abilitiesOf(state, principal) {
     return [...ABILITY_NAMES.keys()].filter((a) => hasAbility(state, principal, a));
@@ -124,7 +172,7 @@ function covers(state, target, revoker) {
     const seen = new Set();
     let grant = target;
     while (grant !== undefined && !seen.has(key(grant.id))) {
-        if (bytesEqual(grant.issuer, revoker))
+        if (bytesEqual(grant.issuerRoot, revoker))
             return true;
         seen.add(key(grant.id));
         grant = grant.parentGrantId === null ? undefined : state.grants.get(key(grant.parentGrantId));
@@ -144,6 +192,10 @@ export function authorizeControlRecord(record, state) {
         case "GENESIS":
             return ALLOW;
         case "CAPABILITY_GRANT": {
+            // §80.1 role exclusivity: a bound subject would get direct authority.
+            if (isBound(state, body.subject.principalId))
+                return deny("the subject is bound as a device in this Resource (§17.2, §80.1)");
+            const owner = ownerAction(state, issuer);
             // §17.2: "The owner MAY grant any abilities without a parent grant. A
             // non-owner issuer MUST hold capability/grant and MUST reference a
             // parent grant." "If parent grant id is present: the parent grant
@@ -157,18 +209,25 @@ export function authorizeControlRecord(record, state) {
                     return deny("the parent grant does not exist (§17.2)");
                 if (!isGrantActive(state, parent.id))
                     return deny("the parent grant is not active (§17.2)");
-                if (!bytesEqual(parent.subject, issuer))
+                // §17.2 with devices: actsFor(kid) at the previous head is the parent's subject.
+                if (!bytesEqual(parent.subject, actsFor(state, issuer)))
                     return deny("the issuer is not the subject of the parent grant (§17.2)");
                 if (!subset(body.abilities, parent.delegable))
                     return deny("a granted ability is not delegable under the parent grant (§17.2)");
                 if (!subset(body.delegable, parent.delegable))
                     return deny("a delegable ability is not delegable under the parent grant (§17.2)");
             }
-            else if (!isOwner(state, issuer)) {
+            else if (!owner) {
                 return deny("a non-owner grant must prove its authority through a parent grant (§17.2)");
             }
-            if (!isOwner(state, issuer) && !hasAbility(state, issuer, ABILITY.CAPABILITY_GRANT))
+            if (!owner && !hasAbility(state, issuer, ABILITY.CAPABILITY_GRANT))
                 return deny("the issuer does not hold capability/grant (§17.2)");
+            // §17.2 delegation bound: a device that is not owner-acting lists no
+            // code 1-10 outside its mask; 11, 12, 13 and unknown codes pass.
+            const device = owner ? undefined : state.devices.get(key(issuer));
+            if (device !== undefined &&
+                [...body.abilities, ...body.delegable].some((a) => a >= 1n && a <= 10n && !device.mask.includes(a)))
+                return deny("the grant lists an ability outside the issuing device's mask (§17.2)");
             return ALLOW;
         }
         case "CAPABILITY_REVOKE": {
@@ -179,10 +238,11 @@ export function authorizeControlRecord(record, state) {
                 return deny("the revoked grant does not exist (§17.3)");
             // "The owner may revoke any grant." Otherwise the issuer MUST "possess
             // capability/revoke authority that covers the target grant".
-            if (!isOwner(state, issuer)) {
+            if (!ownerAction(state, issuer)) {
                 if (!hasAbility(state, issuer, ABILITY.CAPABILITY_REVOKE))
                     return deny("the issuer does not hold capability/revoke (§17.3)");
-                if (!covers(state, target, issuer))
+                // §17.3 with devices: coverage compares actsFor(kid) with issuer_root.
+                if (!covers(state, target, actsFor(state, issuer)))
                     return deny("the issuer's capability/revoke authority does not cover the grant (§17.3)");
             }
             if (target.revokedBy !== null)
@@ -216,6 +276,9 @@ export function authorizeControlRecord(record, state) {
             const transferable = invitation.abilities.filter((a) => a !== ABILITY.INVITE_CLAIM || invitation.delegable.includes(ABILITY.INVITE_CLAIM));
             if (!subset(body.abilities.filter(isStandardAbility), transferable))
                 return deny("the claim requests abilities beyond the invitation grant (§18.1 rule 4)");
+            // §80.1: the claimant is a root, never a bound device.
+            if (isBound(state, body.claimant.principalId))
+                return deny("the claimant is bound as a device in this Resource (§18.1, §80.1)");
             return ALLOW;
         }
         case "KEY_EPOCH":
@@ -223,8 +286,14 @@ export function authorizeControlRecord(record, state) {
             return hasAbility(state, issuer, ABILITY.KEY_ROTATE)
                 ? ALLOW
                 : deny("the issuer does not hold key/rotate (§19)");
-        case "OWNER_TRANSFER_COMMIT":
+        case "OWNER_TRANSFER_COMMIT": {
+            if (body.deviceChain !== undefined) {
+                const chain = authorizeOwnerChain(state, body.deviceChain);
+                if (!chain.allowed)
+                    return chain;
+            }
             return verifyOwnerTransfer(record, state).authorization;
+        }
         case "ROUTE_UPDATE":
             // §20: "The issuer MUST possess route/update"; "Each Route Update MUST
             // carry a route version strictly greater than the current one: 0 after
@@ -240,25 +309,32 @@ export function authorizeControlRecord(record, state) {
             // owner authority: its issuer MUST be the Resource owner at the
             // record's position in the chain, whether or not the receiver supports
             // the extension." §14 names no code: AUTHORIZATION_FAILED here.
-            return isOwner(state, issuer)
+            return ownerAction(state, issuer)
                 ? ALLOW
                 : deny("an extension record must be issued by the owner (§14)");
         case "COORDINATOR_RECOVERY":
         case "RESOURCE_TOMBSTONE":
             return deny(`${body.type} is refused in MVP 0.1 (scope §4, DV1)`);
+        case "DEVICE_GRANT":
+            return authorizeDeviceGrant(state, issuer, body);
+        case "DEVICE_REVOKE":
+            return authorizeDeviceRevoke(state, issuer, body);
     }
 }
 /** The capability transitions of an applied record (called by applyRecord). */
-export function applyCapabilities(grants, record) {
+export function applyCapabilities(state, record) {
+    const grants = state.grants;
+    // §79: issuer_root is actsFor(issuer) at the head the grant is committed on.
+    const issuerRoot = actsFor(state, record.payload.issuer);
     const body = record.body;
     const id = controlRecordId(record.signed.id);
     switch (body.type) {
         case "CAPABILITY_GRANT": {
-            const next = new Map(grants);
-            next.set(key(id), Object.freeze({
+            return put(grants, key(id), Object.freeze({
                 id,
                 source: "grant",
                 issuer: record.payload.issuer,
+                issuerRoot,
                 subject: body.subject.principalId,
                 abilities: body.abilities,
                 delegable: body.delegable,
@@ -267,15 +343,12 @@ export function applyCapabilities(grants, record) {
                 claimsUsed: 0n,
                 revokedBy: null,
             }));
-            return next;
         }
         case "CAPABILITY_REVOKE": {
             const target = grants.get(key(body.grantId));
             if (target === undefined)
                 return grants;
-            const next = new Map(grants);
-            next.set(key(target.id), Object.freeze({ ...target, revokedBy: id }));
-            return next;
+            return put(grants, key(target.id), Object.freeze({ ...target, revokedBy: id }));
         }
         case "CAPABILITY_CLAIM": {
             // §18.1: "A successful claim creates a new capability grant to the
@@ -285,13 +358,14 @@ export function applyCapabilities(grants, record) {
             // claimed abilities; it has no parent grant and an empty delegable
             // list, so revoking the Invitation Grant later does not revoke it."
             const invitation = grants.get(key(body.invitationGrantId));
-            const next = new Map(grants);
-            if (invitation !== undefined)
-                next.set(key(invitation.id), Object.freeze({ ...invitation, claimsUsed: invitation.claimsUsed + 1n }));
-            next.set(key(id), Object.freeze({
+            const used = invitation === undefined
+                ? grants
+                : put(grants, key(invitation.id), Object.freeze({ ...invitation, claimsUsed: invitation.claimsUsed + 1n }));
+            return put(used, key(id), Object.freeze({
                 id,
                 source: "claim",
                 issuer: record.payload.issuer,
+                issuerRoot,
                 subject: body.claimant.principalId,
                 abilities: body.abilities,
                 delegable: [],
@@ -300,7 +374,6 @@ export function applyCapabilities(grants, record) {
                 claimsUsed: 0n,
                 revokedBy: null,
             }));
-            return next;
         }
         default:
             return grants;
@@ -308,7 +381,8 @@ export function applyCapabilities(grants, record) {
 }
 /**
  * §25.2 Key Package authority at the package's referenced Control Head:
- * the sender must hold key/distribute, and the recipient must hold
+ * the sender must hold key/distribute or be of the recipient's root
+ * (`sameRoot`, §80.1), and the recipient must hold
  * data/read, "except for an Invitation Principal explicitly authorized by
  * an active invite grant: a recipient that is the subject of an active
  * grant that includes and still confers invite/claim". `epoch` is the
@@ -316,8 +390,10 @@ export function applyCapabilities(grants, record) {
  * checked with the epoch rules (LFCP-023, LFCP-024).
  */
 export function canDistributeKey(state, sender, recipient, _epoch) {
-    if (!hasAbility(state, sender, ABILITY.KEY_DISTRIBUTE))
-        return deny("the sender does not hold key/distribute (§25.2)");
+    // §25.2: key/distribute, or the same-root rule (a device delivering to
+    // its root or an active sibling, or the root to its active device).
+    if (!sameRoot(state, sender, recipient) && !hasAbility(state, sender, ABILITY.KEY_DISTRIBUTE))
+        return deny("the sender holds no key/distribute and is not of the recipient's root (§25.2)");
     if (hasAbility(state, recipient, ABILITY.DATA_READ))
         return ALLOW;
     if (hasAbility(state, recipient, ABILITY.INVITE_CLAIM))
@@ -360,13 +436,32 @@ export function verifyOwnerTransfer(record, state) {
     }
     const o = offer.payload;
     const a = accept.payload;
-    if (!bytesEqual(o.resourceId, state.resourceId) || !bytesEqual(a.resourceId, state.resourceId))
-        return { authorization: deny("the offer or accept is for another Resource (§23.1, §23.2)") };
-    const offerSigned = verifySignedObject(offer.signed, state.owner);
-    if (!offerSigned.valid)
+    // §62 class 4, before any authority: the offer verifies under its kid
+    // when that kid is the owner or a device bound to it (any other offer
+    // fails rule 1 below), the accept under the new owner or, with field 2,
+    // the leaf device. validateControlChain has checked both already (with
+    // the dependency class first); these repeat them for a direct caller.
+    const leaf = body.deviceChain?.leaf.payload.device;
+    const acceptor = leaf ?? o.proposedOwner;
+    const signer = offerSigner(state, offer.signed.kid);
+    const offerSigned = signer === undefined ? undefined : verifySignedObject(offer.signed, signer);
+    if (offerSigned !== undefined && !offerSigned.valid)
         return {
-            authorization: badSignature(`the offer is not signed by the current owner (${offerSigned.reason}, §23.3 rule 1)`),
+            authorization: badSignature(`the offer's signature does not verify (${offerSigned.reason}, §23.3 rule 1)`),
         };
+    const acceptSigned = verifySignedObject(accept.signed, acceptor);
+    if (!acceptSigned.valid)
+        return {
+            authorization: badSignature(`the accept is not signed by the new owner or its leaf device (${acceptSigned.reason}, §23.3 rule 4)`),
+        };
+    // §80.1: the new owner is a root, never a bound device.
+    if (isBound(state, o.proposedOwner.principalId))
+        return { authorization: deny("the new owner is bound as a device here (§23.3, §80.1)") };
+    if (!bytesEqual(o.resourceId, state.resourceId) || !bytesEqual(a.resourceId, state.resourceId))
+        return { authorization: deny("the offer or accept is for another Resource (§23.1, §23.2)") };
+    // Rule 1 with devices: ownerAction(offer.kid) at the offer's head.
+    if (!ownerAction(state, offer.signed.kid))
+        return { authorization: deny("the offer is not signed by the current owner (§23.3 rule 1)") };
     if (!bytesEqual(o.controlHead, state.head))
         return {
             authorization: deny("the offer does not reference the current Control Head (§23.3 rule 2)"),
@@ -377,13 +472,10 @@ export function verifyOwnerTransfer(record, state) {
         };
     if (!bytesEqual(a.offerId, objectId(offer.signed.bytes)))
         return { authorization: deny("the accept does not name this offer (§23.2)") };
-    const acceptSigned = verifySignedObject(accept.signed, o.proposedOwner);
-    if (!acceptSigned.valid)
+    if (!bytesEqual(record.payload.issuer, (leaf ?? o.proposedOwner).principalId))
         return {
-            authorization: badSignature(`the accept is not signed by the new owner (${acceptSigned.reason}, §23.3 rule 4)`),
+            authorization: deny("the commit is not issued by the new owner or its leaf (§23.3 rule 5)"),
         };
-    if (!bytesEqual(record.payload.issuer, o.proposedOwner.principalId))
-        return { authorization: deny("the commit is not issued by the new owner (§23.3 rule 5)") };
     if (o.expectedControlSeq !== record.payload.controlSeq)
         return {
             authorization: deny("the offer's expected Control Sequence is not the commit's (§23.3 rule 6)"),
@@ -396,11 +488,17 @@ export function verifyOwnerTransfer(record, state) {
  * before can still be verified. Undefined for other records.
  */
 export function transferIssuerDescriptor(record) {
+    const proposed = transferNewOwner(record);
+    return proposed !== undefined && bytesEqual(proposed.principalId, record.payload.issuer)
+        ? proposed
+        : undefined;
+}
+/** The new owner a transfer commit names (offer field 3), whoever signed the commit. */
+export function transferNewOwner(record) {
     if (record.body.type !== "OWNER_TRANSFER_COMMIT")
         return undefined;
     try {
-        const proposed = parseOwnerTransferOffer(record.body.offer).payload.proposedOwner;
-        return bytesEqual(proposed.principalId, record.payload.issuer) ? proposed : undefined;
+        return parseOwnerTransferOffer(record.body.offer).payload.proposedOwner;
     }
     catch {
         return undefined;

package/dist/chain.d.ts

@@ -1,6 +1,7 @@
 import { type ControlRecordId, type DataEpoch, type Hash32, LfcpError, type PrincipalId, type ResourceId } from "@openlfcp/core";
 import { type Authorization, type Grant } from "./capability.js";
 import { type ControlRecord } from "./control.js";
+import { type DeviceState } from "./device-state.js";
 import type { Endpoint } from "./endpoint.js";
 import type { ActorHave } from "./have.js";
 import type { PrincipalDescriptor } from "./principal.js";
@@ -54,7 +55,7 @@ export interface EpochHistory extends ControlEpoch {
  * LFCP-021 adds the grants and applies route updates; LFCP-023 applies
  * Key Epoch rotation (`epoch`, `epochs`).
  */
-export interface ControlState {
+export interface ControlState extends DeviceState {
     readonly resourceId: ResourceId;
     readonly genesisId: ControlRecordId;
     /** The current Control Head: the record ID of the last validated record. */
@@ -74,7 +75,8 @@ export interface ControlState {
     readonly grants: ReadonlyMap<string, Grant>;
     /**
      * Principal Descriptors carried by applied records (Genesis owner, grant
-     * subjects, claimants), by Principal ID hex. Descriptors are
+     * subjects, claimants, new owners, every device of an accepted
+     * certificate chain), by Principal ID hex. Descriptors are
      * self-certifying (§7), so knowing one grants nothing; it only lets later
      * records by that Principal be verified.
      */
@@ -120,14 +122,18 @@ export interface ChainOptions {
     readonly start?: ControlState;
     /**
      * Resolves an issuer that no earlier record in the chain describes.
-     * The returned descriptor is checked against the ID like any other.
+     * The returned descriptor is checked against the ID like any other. Not
+     * consulted for DEVICE_GRANT and DEVICE_REVOKE, whose issuer must be
+     * known to the chain (§17.4 rule 2, §17.5 rule 2).
      */
     readonly resolvePrincipal?: (id: PrincipalId) => PrincipalDescriptor | undefined;
     /**
      * Authorization, called for every non-Genesis record with the state
      * before it (the previous head). Defaults to authorizeControlRecord, the
      * LFCP-021 capability engine; a caller may substitute a policy (tests).
-     * A refusal makes the chain invalid (UNAUTHORIZED).
+     * A refusal makes the chain invalid (UNAUTHORIZED). A substitute applies
+     * §23.3 item 1 itself: a transfer offer whose kid is neither the owner
+     * nor a device bound to it reaches it with its signature unchecked.
      */
     readonly authorize?: (record: ControlRecord, state: ControlState) => boolean | Authorization;
 }