@openlfcp/wire 0.2.1 → 0.3.0

package/dist/chain.js

@@ -1,7 +1,10 @@
-import { controlRecordId, dataEpoch, LfcpError, toHex, } from "@openlfcp/core";
-import { applyCapabilities, authorizeControlRecord, transferIssuerDescriptor, } from "./capability.js";
-import { controlRecordSigner, decodeControlRecord, verifyGenesis, } from "./control.js";
+import { bytesEqual, controlRecordId, dataEpoch, LfcpError, toHex, } from "@openlfcp/core";
+import { applyCapabilities, authorizeControlRecord, transferIssuerDescriptor, transferNewOwner, } from "./capability.js";
+import { controlRecordSigner, decodeControlRecord, parseOwnerTransferAccept, parseOwnerTransferOffer, verifyGenesis, } from "./control.js";
 import { objectId, verifySignedObject } from "./cose.js";
+import { verifyChainSignatures } from "./device.js";
+import { bindChain, EMPTY_DEVICE_STATE, grantInScope, nonDevice, offerSigner, recordRevocation, } from "./device-state.js";
+import { PersistentMap, put } from "./persistent-map.js";
 const WIRE = {
     MALFORMED: "MALFORMED_MESSAGE",
     // §14: "Unknown core Control Record types MUST cause validation failure, with INVALID_CONTROL_CHAIN."
@@ -103,10 +106,21 @@ function genesisState(record) {
                 }),
             ],
         ]),
-        grants: new Map(),
-        principals: new Map([[toHex(body.owner.principalId), body.owner]]),
+        grants: PersistentMap.empty(),
+        ...genesisDevices(body),
     });
 }
+/** §15: the owner is `non-device`; with field 5 every chain device is bound and the leaf registered. */
+function genesisDevices(body) {
+    const owner = {
+        ...EMPTY_DEVICE_STATE,
+        roles: nonDevice(EMPTY_DEVICE_STATE.roles, body.owner.principalId),
+        principals: PersistentMap.from([[toHex(body.owner.principalId), body.owner]]),
+    };
+    if (body.deviceChain === undefined)
+        return owner;
+    return { ...owner, ...bindChain(owner, body.deviceChain, true, false) };
+}
 /**
  * The state after a validated record. Applied records (mvpSupported)
  * change derived state: descriptors (LFCP-020), grants, revocations, claims
@@ -117,17 +131,36 @@ function applyRecord(state, record) {
     const next = { head: controlRecordId(record.signed.id), seq: record.payload.controlSeq };
     if (!record.mvpSupported)
         return Object.freeze({ ...state, ...next });
-    const principals = new Map(state.principals);
     const body = record.body;
+    // §79: roles on acceptance; device bindings and revocations (§17.4, §17.5).
+    // Maps are persistent: a record copies only the entries it changes, so
+    // the states kept for every head share the rest (review of #8, R8-1).
+    let devices = state;
+    const known = (d, role) => {
+        devices = {
+            ...devices,
+            principals: put(devices.principals, toHex(d.principalId), d),
+            ...(role ? { roles: nonDevice(devices.roles, d.principalId) } : {}),
+        };
+    };
     if (body.type === "CAPABILITY_GRANT")
-        principals.set(toHex(body.subject.principalId), body.subject);
+        known(body.subject, true);
     if (body.type === "CAPABILITY_CLAIM")
-        principals.set(toHex(body.claimant.principalId), body.claimant);
+        known(body.claimant, true);
     // §23.3 "After commit, the accepting Principal becomes the Resource owner"
-    // (verified by authorizeControlRecord before this record was accepted).
-    const newOwner = transferIssuerDescriptor(record);
-    if (newOwner !== undefined)
-        principals.set(toHex(newOwner.principalId), newOwner);
+    // (verified by authorizeControlRecord before this record was accepted);
+    // with field 2 its chain is bound and the leaf registered, a leaf already
+    // registered with the same certificate left unchanged.
+    const newOwner = transferNewOwner(record);
+    if (newOwner !== undefined) {
+        known(newOwner, true);
+        if (body.type === "OWNER_TRANSFER_COMMIT" && body.deviceChain !== undefined)
+            devices = bindChain(devices, body.deviceChain, true, true);
+    }
+    if (body.type === "DEVICE_GRANT")
+        devices = bindChain(state, body.chain, grantInScope(state, body), false, true);
+    if (body.type === "DEVICE_REVOKE")
+        devices = { ...devices, ...recordRevocation(state, record, body) };
     const route = body.type === "ROUTE_UPDATE"
         ? {
             route: Object.freeze({ endpoints: body.endpoints, coordinatorUrl: body.coordinatorUrl }),
@@ -140,8 +173,14 @@ function applyRecord(state, record) {
         ...route,
         ...(body.type === "KEY_EPOCH" ? rotate(state, record, body) : {}),
         ...(newOwner !== undefined ? { owner: newOwner } : {}),
-        principals,
-        grants: applyCapabilities(state.grants, record),
+        principals: devices.principals,
+        roles: devices.roles,
+        devices: devices.devices,
+        revoked: devices.revoked,
+        liveBound: devices.liveBound,
+        preemptive: devices.preemptive,
+        preemptiveRoots: devices.preemptiveRoots,
+        grants: applyCapabilities(state, record),
     });
 }
 /**
@@ -164,6 +203,91 @@ function rotate(state, record, body) {
     }));
     return { epoch: Object.freeze({ epoch: body.epoch, dekCommitment: body.dekCommitment }), epochs };
 }
+/**
+ * §62 classes 3 and 4 for a non-Genesis record at `state`: every
+ * dependency first (a Device Grant's root known to the Resource's state,
+ * the issuer's descriptor), then every signature (the record under its
+ * issuer, the certificates of an embedded chain leaf first, the offer
+ * under its kid when that is the owner or a device bound to it, and the
+ * accept under the new owner or, with commit field 2, under the leaf). §13: kid MUST equal the
+ * issuer (controlRecordSigner); with commit field 2 the issuer MUST be the
+ * leaf. Undefined when all hold.
+ */
+function dependenciesAndSignatures(record, state, options) {
+    const body = record.body;
+    const issuer = controlRecordSigner(record);
+    const known = (id) => state.principals.get(toHex(id));
+    const missing = (reason) => ({ problem: "UNRESOLVED_ISSUER", reason });
+    const bad = (reason) => ({ problem: "SIGNATURE", reason });
+    // Class 3.
+    let root;
+    if (body.type === "DEVICE_GRANT") {
+        // §17.4 rule 2: the root's descriptor is known to the previous state.
+        root = known(body.root);
+        if (root === undefined)
+            return missing("the Device Grant's root is not known (§17.4 rule 2)");
+    }
+    const offer = body.type === "OWNER_TRANSFER_COMMIT" ? parseOwnerTransferOffer(body.offer) : null;
+    const accept = body.type === "OWNER_TRANSFER_COMMIT" ? parseOwnerTransferAccept(body.accept) : null;
+    if (offer !== null)
+        root = offer.payload.proposedOwner;
+    const chain = body.type === "DEVICE_GRANT"
+        ? body.chain
+        : body.type === "OWNER_TRANSFER_COMMIT"
+            ? body.deviceChain
+            : undefined;
+    const leaf = chain?.leaf.payload.device;
+    const required = body.type === "OWNER_TRANSFER_COMMIT" ? leaf : undefined;
+    const descriptor = required ??
+        known(issuer) ??
+        (body.type === "DEVICE_GRANT"
+            ? body.chain.certificates.find((c) => toHex(c.payload.device.principalId) === toHex(issuer))
+                ?.payload.device
+            : undefined) ??
+        transferIssuerDescriptor(record) ??
+        // §17.4 rule 2, §17.5 rule 2: a device record's issuer is known to the
+        // Resource's state (or carried by the grant's chain), never resolved
+        // from outside, so its verdict is a function of the chain alone
+        // (review of #8, R8-3).
+        (body.type === "DEVICE_GRANT" || body.type === "DEVICE_REVOKE"
+            ? undefined
+            : options.resolvePrincipal?.(issuer));
+    if (descriptor === undefined)
+        return missing("no descriptor is known for the issuer");
+    // Class 4. §13: the kid is the payload issuer; with commit field 2 that
+    // issuer is the leaf, whose descriptor the commit is verified under
+    // (review of #8, R8-2: a policy substituted for authority never sees a
+    // commit whose field 4 names another Principal).
+    if (!bytesEqual(record.signed.kid, issuer))
+        return bad("the record's kid is not its issuer (§13)");
+    if (required !== undefined && !bytesEqual(issuer, required.principalId))
+        return bad("the commit's issuer is not the leaf device of field 2 (§13, §23.3)");
+    const v = verifySignedObject(record.signed, descriptor);
+    if (!v.valid)
+        return bad(required !== undefined
+            ? `the commit is not signed by the leaf device of field 2 (${v.reason}, §23.3)`
+            : `the record is not signed by its issuer (${v.reason})`);
+    if (chain !== undefined && root !== undefined) {
+        const c = verifyChainSignatures(chain, root);
+        if (!c.valid)
+            return bad(`${c.reason} (§7.3)`);
+    }
+    if (offer !== null && accept !== null && root !== undefined) {
+        // §23.3, §62 class 4: the offer's signer is never a dependency; its
+        // signature is checked only under the owner or a device bound to it.
+        const signer = offerSigner(state, offer.signed.kid);
+        const o = signer === undefined ? undefined : verifySignedObject(offer.signed, signer);
+        if (o !== undefined && !o.valid)
+            return bad(`the offer's signature does not verify (${o.reason}, §23.3)`);
+        // PENDING spec clarification: §62 checks the accept under its required
+        // signer before authority, so a wrong accept kid is INVALID_SIGNATURE
+        // (as sdk-rs), with or without field 2.
+        const a = verifySignedObject(accept.signed, leaf ?? root);
+        if (!a.valid)
+            return bad(`the accept is not signed by the new owner or its leaf (${a.reason}, §23.3)`);
+    }
+    return undefined;
+}
 /**
  * Validates a set of exact signed Control Records of one Resource, from
  * Genesis or after `options.start`. Input objects that are already decoded
@@ -236,7 +360,13 @@ export function validateControlChain(inputs, options = {}) {
         for (const g of geneses) {
             const v = verifyGenesis(g.record);
             if (!v.valid)
-                bad.push(problem(v.reason === "ISSUER_NOT_OWNER" ? "GENESIS_SIGNER" : "SIGNATURE", at(g), `Genesis is not signed by its owner (${v.reason}, §15)`));
+                bad.push(problem(v.reason === "ISSUER_NOT_OWNER"
+                    ? "GENESIS_SIGNER"
+                    : v.reason === "DEVICE_CHAIN_UNAUTHORIZED"
+                        ? "UNAUTHORIZED"
+                        : "SIGNATURE", at(g), v.reason === "DEVICE_CHAIN_UNAUTHORIZED"
+                    ? "the Genesis chain fails (c3), (c4) or (c6), or its leaf is not a personal device with owner/act (§15)"
+                    : `Genesis is not signed by its owner (${v.reason}, §15)`));
         }
         if (bad.length > 0)
             return invalid(bad);
@@ -282,25 +412,19 @@ export function validateControlChain(inputs, options = {}) {
                 problems.push(problem("SEQUENCE", at(k), `control_seq ${p.controlSeq} after ${state.seq} (§13.1)`));
                 continue;
             }
-            // §13: the issuer signs, and kid MUST equal it (see controlRecordSigner).
-            const issuer = controlRecordSigner(k.record);
-            const descriptor = state.principals.get(toHex(issuer)) ??
-                transferIssuerDescriptor(k.record) ??
-                options.resolvePrincipal?.(issuer);
-            if (descriptor === undefined) {
-                problems.push(problem("UNRESOLVED_ISSUER", at(k), "no descriptor is known for the issuer"));
-                continue;
-            }
-            const v = verifySignedObject(k.record.signed, descriptor);
-            if (!v.valid) {
-                problems.push(problem("SIGNATURE", at(k), `the record is not signed by its issuer (${v.reason})`));
-                continue;
-            }
             // §19: "The new epoch number MUST be exactly the previous Data Epoch plus one."
+            // A chain placement check, §62 class 2: before dependencies, signatures
+            // and authority, so a wrong number is INVALID_CONTROL_CHAIN even when
+            // the signature does not verify or the issuer is unknown (decision I9).
             if (k.record.body.type === "KEY_EPOCH" && k.record.body.epoch !== state.epoch.epoch + 1n) {
                 problems.push(problem("EPOCH", at(k), `Key Epoch ${k.record.body.epoch} after epoch ${state.epoch.epoch}: must be the previous epoch plus one (§19)`));
                 continue;
             }
+            const verified = dependenciesAndSignatures(k.record, state, options);
+            if (verified !== undefined) {
+                problems.push(problem(verified.problem, at(k), verified.reason));
+                continue;
+            }
             const decision = authorize(k.record, state);
             if (decision === false || (typeof decision === "object" && !decision.allowed)) {
                 const refusal = typeof decision === "object" && !decision.allowed ? decision : undefined;

package/dist/control.d.ts

@@ -1,6 +1,7 @@
 import { type ControlRecordId, type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
 import { type CborValue } from "./cbor/index.js";
 import { type SignedBytes, type Signer, type VerifyResult } from "./cose.js";
+import { type CertificateChain } from "./device.js";
 import { type Endpoint } from "./endpoint.js";
 import { type ActorHave } from "./have.js";
 import { type ControlRecordPayload, type Parsed } from "./objects.js";
@@ -32,6 +33,8 @@ export type ControlBody = {
     readonly dekCommitment: Hash32;
     readonly endpoints: readonly Endpoint[];
     readonly coordinatorUrl: string;
+    /** Field 5 (§15): present when a device of the owner signs the Genesis; the chain's root is the owner. */
+    readonly deviceChain?: CertificateChain;
 } | {
     readonly type: "CAPABILITY_GRANT";
     readonly subject: PrincipalDescriptor;
@@ -64,6 +67,8 @@ export type ControlBody = {
     /** Exact COSE bytes of the transfer offer and accept (§23.3); see parseOwnerTransferOffer/Accept. */
     readonly offer: Uint8Array;
     readonly accept: Uint8Array;
+    /** Field 2 (§23.3): present when a device of the new owner signs accept and commit; rooted at offer field 3. */
+    readonly deviceChain?: CertificateChain;
 } | {
     readonly type: "COORDINATOR_RECOVERY";
     readonly routeVersion: bigint;
@@ -75,6 +80,25 @@ export type ControlBody = {
     readonly reason: bigint;
     readonly note?: string;
 }
+/** §17.4: binds the chain's devices to `root`; registers or re-certifies the leaf. */
+ | {
+    readonly type: "DEVICE_GRANT";
+    readonly root: PrincipalId;
+    /** Rooted at `root`; the leaf is the device bound or registered. */
+    readonly chain: CertificateChain;
+    /** Field 2: the pairing device whose consumed approval names the leaf (§17.4 rule 7). */
+    readonly pairingDevice?: PrincipalId;
+}
+/** §17.5: revokes the pair (root, device) in this Resource. */
+ | {
+    readonly type: "DEVICE_REVOKE";
+    readonly root: PrincipalId;
+    readonly device: PrincipalId;
+    /** 0 retired, 1 lost, 2 compromised, 3 consumed; 4 and above kept as received. */
+    readonly reason: bigint;
+    /** Field 4, exactly when the reason is 3: the approved certificate's payload digest. */
+    readonly approval?: Hash32;
+}
 /** A §14 extension type (32 and up): kept, never interpreted. */
  | {
     readonly type: "EXTENSION";
@@ -87,8 +111,9 @@ export declare const isMvpSupported: (type: ControlBodyType) => boolean;
 /** The §14 code of a body. */
 export declare const controlTypeOf: (body: ControlBody) => bigint;
 /**
- * Decodes the body of a Control Record of §14 type `type`. Core types 0-8
- * get their closed-map structure; 9-31 are UNSUPPORTED_VALUE (§14:
+ * Decodes the body of a Control Record of §14 type `type`. Core types 0-10
+ * get their closed-map structure, embedded certificates and transfer
+ * objects included (§62 class 1); 11-31 are UNSUPPORTED_VALUE (§14:
  * INVALID_CONTROL_CHAIN on the wire); 32 and up are kept as opaque
  * EXTENSION bodies.
  */
@@ -101,7 +126,8 @@ export interface ControlRecord extends Parsed<ControlRecordPayload> {
 }
 /**
  * Parses a received Control Record: canonical COSE and the generic
- * envelope (parseControlRecord), then the typed body. The record ID is
+ * envelope (parseControlRecord), then the typed body, then the Genesis
+ * placement rule (§62: structure before placement). The record ID is
  * `signed.id`, SHA-256 of the exact received bytes. The signature is not
  * checked here; see controlRecordSigner and verifyGenesis.
  */
@@ -118,11 +144,17 @@ export declare const controlRecordSigner: (record: Parsed<ControlRecordPayload>)
  * Verifies a Genesis record against the owner in its own body (§15:
  * "MUST be signed by the owner Principal contained in the body"): the
  * issuer and the kid must be the owner and the signature must verify with
- * the owner's key. A failure surfaces as INVALID_SIGNATURE.
+ * the owner's key. With field 5 the chain's leaf device is the required
+ * signer instead, the owner included in "any other Principal"
+ * (ISSUER_NOT_OWNER), and every certificate must verify up to the owner
+ * (§7.3 (c2)); these are INVALID_SIGNATURE on the wire. Then, as
+ * authority (AUTHORIZATION_FAILED, DEVICE_CHAIN_UNAUTHORIZED): (c3), (c4),
+ * (c6) and a personal leaf with owner/act. S is empty at Genesis, so
+ * nothing about roles or revocations applies.
  */
 export declare function verifyGenesis(record: ControlRecord): VerifyResult | {
     readonly valid: false;
-    readonly reason: "NOT_GENESIS" | "ISSUER_NOT_OWNER";
+    readonly reason: "NOT_GENESIS" | "ISSUER_NOT_OWNER" | "DEVICE_CHAIN_UNAUTHORIZED";
 };
 /** The CBOR of a typed body, applying the writer rules. */
 export declare function controlBodyToCbor(body: ControlBody): CborValue;

package/dist/control.js

@@ -1,10 +1,12 @@
 import { bytesEqual, controlRecordId, dataEpoch, hash32, LfcpError, principalId, resourceId, } from "@openlfcp/core";
 import { cborMap, decodeStrict, encode } from "./cbor/index.js";
 import { parseSignedObject, signObject, verifySignedObject, } from "./cose.js";
+import { certificateChainFromCbor, certificateChainToCbor, checkChainAuthority, DEVICE_ABILITY, DEVICE_KIND, verifyChainSignatures, } from "./device.js";
+import { scanControlRecord } from "./device-scan.js";
 import { checkReceivedUrl, checkWriterUrl, endpointFromCbor, endpointToCbor, } from "./endpoint.js";
 import { Fields } from "./fields.js";
 import { canonicalFrontierFromCbor, canonicalFrontierToCbor } from "./have.js";
-import { CONTROL_TYPE, controlRecordPayloadFromCbor, parseControlRecord, } from "./objects.js";
+import { CONTROL_TYPE, checkGenesisPlacement, controlRecordPayloadFromCbor, readControlRecordPayload, } from "./objects.js";
 import { principalDescriptorFromCbor, principalDescriptorToCbor, } from "./principal.js";
 const CODE = CONTROL_TYPE;
 /**
@@ -12,7 +14,8 @@ const CODE = CONTROL_TYPE;
  * applied. OWNER_TRANSFER_COMMIT is verified and applied
  * (MVP-0.1-PROTOCOL-SCOPE §4: "ownership transfer verification is in MVP
  * 0.1"). A chain containing Coordinator Recovery or Resource Tombstone is
- * refused (DV1, chain.ts); extensions are kept unapplied.
+ * refused (DV1, chain.ts); extensions are kept unapplied. DEVICE_GRANT and
+ * DEVICE_REVOKE (IDENTITY-01, §17.4, §17.5) are verified and applied.
  */
 const MVP_SUPPORTED = new Set([
     "GENESIS",
@@ -22,6 +25,8 @@ const MVP_SUPPORTED = new Set([
     "KEY_EPOCH",
     "ROUTE_UPDATE",
     "OWNER_TRANSFER_COMMIT",
+    "DEVICE_GRANT",
+    "DEVICE_REVOKE",
 ]);
 /** Whether MVP 0.1 implements a body type (false for deferred core types and extensions). */
 export const isMvpSupported = (type) => MVP_SUPPORTED.has(type);
@@ -67,23 +72,42 @@ function abilityList(f, key, nonEmpty) {
         f.fail(key, "lists an ability twice");
     return list;
 }
+/** An optional `certificate-chain` field rooted at `root` (§15 field 5, §23.3 field 2). */
+function optionalChain(f, key, root) {
+    return f.has(key) ? { deviceChain: certificateChainFromCbor(f.any(key), root) } : {};
+}
 /**
- * Decodes the body of a Control Record of §14 type `type`. Core types 0-8
- * get their closed-map structure; 9-31 are UNSUPPORTED_VALUE (§14:
+ * The embedded offer and accept of a transfer commit are structure of the
+ * commit (§62 class 1, with or without field 2): each must be a canonical
+ * signed object with its typed payload. Returns the parsed offer.
+ */
+function transferObjects(f) {
+    const offer = parseOwnerTransferOffer(f.bytes(0));
+    parseOwnerTransferAccept(f.bytes(1));
+    return offer;
+}
+/** `reason = 3` if and only if field 4 is present (§17.5 rule 1). */
+const CONSUMED = 3n;
+/**
+ * Decodes the body of a Control Record of §14 type `type`. Core types 0-10
+ * get their closed-map structure, embedded certificates and transfer
+ * objects included (§62 class 1); 11-31 are UNSUPPORTED_VALUE (§14:
  * INVALID_CONTROL_CHAIN on the wire); 32 and up are kept as opaque
  * EXTENSION bodies.
  */
 export function controlBodyFromCbor(type, value) {
     switch (type) {
         case CONTROL_TYPE.GENESIS: {
-            const f = new Fields(value, "genesis-body", [0, 1, 2, 3, 4]);
+            const f = new Fields(value, "genesis-body", [0, 1, 2, 3, 4], [5]);
+            const owner = principalDescriptorFromCbor(f.any(1));
             return Object.freeze({
                 type: "GENESIS",
                 dataProfile: f.text(0),
-                owner: principalDescriptorFromCbor(f.any(1)),
+                owner,
                 dekCommitment: hash32(f.bytes(2, 32)),
                 endpoints: endpoints(f, 3),
                 coordinatorUrl: coordinatorUrl(f, 4),
+                ...optionalChain(f, 5, owner.principalId),
             });
         }
         case CONTROL_TYPE.CAPABILITY_GRANT: {
@@ -130,11 +154,13 @@ export function controlBodyFromCbor(type, value) {
             });
         }
         case CONTROL_TYPE.OWNER_TRANSFER_COMMIT: {
-            const f = new Fields(value, "owner-transfer-commit-body", [0, 1]);
+            const f = new Fields(value, "owner-transfer-commit-body", [0, 1], [2]);
+            const offer = transferObjects(f);
             return Object.freeze({
                 type: "OWNER_TRANSFER_COMMIT",
                 offer: f.bytes(0),
                 accept: f.bytes(1),
+                ...optionalChain(f, 2, offer.payload.proposedOwner.principalId),
             });
         }
         case CONTROL_TYPE.COORDINATOR_RECOVERY: {
@@ -155,6 +181,38 @@ export function controlBodyFromCbor(type, value) {
                 ...(f.has(1) ? { note: f.text(1) } : {}),
             });
         }
+        case CONTROL_TYPE.DEVICE_GRANT: {
+            const f = new Fields(value, "device-grant-body", [0, 1], [2]);
+            const root = principalId(f.bytes(0, 32));
+            const chain = certificateChainFromCbor(f.any(1), root);
+            // §17.4 rule 1: a record whose leaf is of kind 2 MUST NOT carry field 2.
+            if (f.has(2) && chain.leaf.payload.kind === DEVICE_KIND.PAIRING)
+                f.fail(2, "must be absent when the leaf is a pairing device (§17.4)");
+            return Object.freeze({
+                type: "DEVICE_GRANT",
+                root,
+                chain,
+                ...(f.has(2) ? { pairingDevice: principalId(f.bytes(2, 32)) } : {}),
+            });
+        }
+        case CONTROL_TYPE.DEVICE_REVOKE: {
+            // Field 3 is reserved (§108.1): not in the closed map, so MALFORMED_MESSAGE.
+            const f = new Fields(value, "device-revoke-body", [0, 1, 2], [4]);
+            const root = principalId(f.bytes(0, 32));
+            const device = principalId(f.bytes(1, 32));
+            if (bytesEqual(root, device))
+                f.fail(1, "must differ from the root (§17.5 rule 1)");
+            const reason = f.uint(2);
+            if (f.has(4) !== (reason === CONSUMED))
+                f.fail(4, "must be present exactly when the reason is 3 (§17.5 rule 1)");
+            return Object.freeze({
+                type: "DEVICE_REVOKE",
+                root,
+                device,
+                reason,
+                ...(f.has(4) ? { approval: hash32(f.bytes(4, 32)) } : {}),
+            });
+        }
         default:
             if (type >= 32n)
                 return Object.freeze({ type: "EXTENSION", code: type, body: value });
@@ -163,14 +221,21 @@ export function controlBodyFromCbor(type, value) {
 }
 /**
  * Parses a received Control Record: canonical COSE and the generic
- * envelope (parseControlRecord), then the typed body. The record ID is
+ * envelope (parseControlRecord), then the typed body, then the Genesis
+ * placement rule (§62: structure before placement). The record ID is
  * `signed.id`, SHA-256 of the exact received bytes. The signature is not
  * checked here; see controlRecordSigner and verifyGenesis.
  */
 export function decodeControlRecord(bytes) {
-    const parsed = parseControlRecord(bytes);
-    const body = controlBodyFromCbor(parsed.payload.controlType, parsed.payload.body);
-    return Object.freeze({ ...parsed, body, mvpSupported: isMvpSupported(body.type) });
+    // A certificate chain's bounds, on the raw bytes, before anything is decoded.
+    scanControlRecord(bytes);
+    const signed = parseSignedObject(bytes);
+    const payload = readControlRecordPayload(decodeStrict(signed.payloadBytes));
+    // §62: the structure of the body and every embedded object (class 1)
+    // before the Genesis placement rule of §13.1 (class 2).
+    const body = controlBodyFromCbor(payload.controlType, payload.body);
+    checkGenesisPlacement(payload);
+    return Object.freeze({ signed, payload, body, mvpSupported: isMvpSupported(body.type) });
 }
 /**
  * The Principal whose key must have signed a Control Record: its issuer
@@ -184,14 +249,35 @@ export const controlRecordSigner = (record) => record.payload.issuer;
  * Verifies a Genesis record against the owner in its own body (§15:
  * "MUST be signed by the owner Principal contained in the body"): the
  * issuer and the kid must be the owner and the signature must verify with
- * the owner's key. A failure surfaces as INVALID_SIGNATURE.
+ * the owner's key. With field 5 the chain's leaf device is the required
+ * signer instead, the owner included in "any other Principal"
+ * (ISSUER_NOT_OWNER), and every certificate must verify up to the owner
+ * (§7.3 (c2)); these are INVALID_SIGNATURE on the wire. Then, as
+ * authority (AUTHORIZATION_FAILED, DEVICE_CHAIN_UNAUTHORIZED): (c3), (c4),
+ * (c6) and a personal leaf with owner/act. S is empty at Genesis, so
+ * nothing about roles or revocations applies.
  */
 export function verifyGenesis(record) {
-    if (record.body.type !== "GENESIS")
+    const body = record.body;
+    if (body.type !== "GENESIS")
         return { valid: false, reason: "NOT_GENESIS" };
-    if (!bytesEqual(record.payload.issuer, record.body.owner.principalId))
+    const chain = body.deviceChain;
+    const signer = chain?.leaf.payload.device ?? body.owner;
+    if (!bytesEqual(record.payload.issuer, signer.principalId))
         return { valid: false, reason: "ISSUER_NOT_OWNER" };
-    return verifySignedObject(record.signed, record.body.owner);
+    const v = verifySignedObject(record.signed, signer);
+    if (!v.valid || chain === undefined)
+        return v;
+    const c = verifyChainSignatures(chain, body.owner);
+    if (!c.valid)
+        return { valid: false, reason: c.rule === "c2-kid" ? "KID_MISMATCH" : "BAD_SIGNATURE" };
+    const authority = checkChainAuthority(chain, record.payload.resourceId);
+    const leaf = chain.leaf.payload;
+    if (!authority.valid ||
+        leaf.kind !== DEVICE_KIND.PERSONAL ||
+        !leaf.mask.includes(DEVICE_ABILITY.OWNER_ACT))
+        return { valid: false, reason: "DEVICE_CHAIN_UNAUTHORIZED" };
+    return { valid: true };
 }
 // ---------------------------------------------------------------------------
 // Encoding (writers)
@@ -222,6 +308,14 @@ function abilities(list, nonEmpty) {
         refuse("an ability is listed twice");
     return [...list];
 }
+/** An optional chain field; its root must be the Principal the body names (§7.3 (c1)). */
+function writerChain(key, chain, root) {
+    if (chain === undefined)
+        return [];
+    if (!bytesEqual(chain.root, root))
+        refuse("the certificate chain is for another root (§7.3 (c1))");
+    return [[key, certificateChainToCbor(chain)]];
+}
 /** The CBOR of a typed body, applying the writer rules. */
 export function controlBodyToCbor(body) {
     switch (body.type) {
@@ -232,6 +326,7 @@ export function controlBodyToCbor(body) {
                 [2, hash32(body.dekCommitment)],
                 [3, writerEndpoints(body.endpoints)],
                 [4, writerUrl(body.coordinatorUrl)],
+                ...writerChain(5, body.deviceChain, body.owner.principalId),
             ]);
         case "CAPABILITY_GRANT":
             return cborMap([
@@ -264,10 +359,43 @@ export function controlBodyToCbor(body) {
                 [1, writerEndpoints(body.endpoints)],
                 [2, writerUrl(body.coordinatorUrl)],
             ]);
-        case "OWNER_TRANSFER_COMMIT":
+        case "OWNER_TRANSFER_COMMIT": {
+            let offer;
+            try {
+                offer = parseOwnerTransferOffer(body.offer);
+                parseOwnerTransferAccept(body.accept);
+            }
+            catch {
+                return refuse("the offer and accept must be canonical transfer objects (§23)");
+            }
             return cborMap([
                 [0, Uint8Array.from(body.offer)],
                 [1, Uint8Array.from(body.accept)],
+                ...writerChain(2, body.deviceChain, offer.payload.proposedOwner.principalId),
+            ]);
+        }
+        case "DEVICE_GRANT":
+            if (!bytesEqual(body.chain.root, body.root))
+                refuse("the chain is for another root (§7.3 (c1))");
+            if (body.pairingDevice !== undefined && body.chain.leaf.payload.kind === DEVICE_KIND.PAIRING)
+                refuse("a grant of a pairing leaf carries no pairing device (§17.4)");
+            return cborMap([
+                [0, principalId(body.root)],
+                [1, certificateChainToCbor(body.chain)],
+                ...(body.pairingDevice !== undefined
+                    ? [[2, principalId(body.pairingDevice)]]
+                    : []),
+            ]);
+        case "DEVICE_REVOKE":
+            if (bytesEqual(body.root, body.device))
+                refuse("the device must differ from the root (§17.5)");
+            if ((body.approval !== undefined) !== (body.reason === CONSUMED))
+                refuse("the approval is present exactly when the reason is 3 (§17.5)");
+            return cborMap([
+                [0, principalId(body.root)],
+                [1, principalId(body.device)],
+                [2, body.reason],
+                ...(body.approval !== undefined ? [[4, hash32(body.approval)]] : []),
             ]);
         case "COORDINATOR_RECOVERY":
             return cborMap([
@@ -300,8 +428,10 @@ export function encodeControlRecordPayload(header, issuer, body) {
     if (genesis) {
         if (header.controlSeq !== 0n || header.prevControlId !== null)
             refuse("Genesis must have control_seq 0 and a null previous record (§13.1)");
-        if (!bytesEqual(issuer, body.owner.principalId))
-            refuse("Genesis must be issued by the owner in its body (§15)");
+        // §15: the owner signs, or with field 5 the chain's leaf device does.
+        const signer = body.deviceChain?.leaf.payload.device.principalId ?? body.owner.principalId;
+        if (!bytesEqual(issuer, signer))
+            refuse("Genesis must be issued by its owner, or by the leaf of field 5 (§15)");
     }
     else if (header.controlSeq < 1n || header.prevControlId === null) {
         refuse("a non-Genesis record needs control_seq >= 1 and the previous record ID (§13.1)");

package/dist/device-scan.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks the envelope and the bounds of a standalone certificate on its
+ * exact bytes, before parseSignedObject decodes anything.
+ */
+export declare function scanDeviceCertificate(bytes: Uint8Array): void;
+/**
+ * Checks the envelope of a Control Record and the bounds of the
+ * certificate chain a record of type 0, 6 or 9 carries, on its exact
+ * bytes. Every refusal found is final: nothing is left to the decoder
+ * once the scan has seen it.
+ */
+export declare function scanControlRecord(bytes: Uint8Array): void;
+//# sourceMappingURL=device-scan.d.ts.map