@openlfcp/wire 0.2.1 → 0.3.0

package/dist/device-state.js

@@ -0,0 +1,318 @@
+import { bytesEqual, controlRecordId, toHex, } from "@openlfcp/core";
+import { ABILITY, isGrantActive } from "./capability.js";
+import { checkChainAuthority, checkChainState, DEVICE_ABILITY, DEVICE_KIND, } from "./device.js";
+import { PersistentMap, put } from "./persistent-map.js";
+export const EMPTY_DEVICE_STATE = Object.freeze({
+    roles: PersistentMap.empty(),
+    devices: PersistentMap.empty(),
+    revoked: PersistentMap.empty(),
+    liveBound: PersistentMap.empty(),
+    preemptive: PersistentMap.empty(),
+    preemptiveRoots: PersistentMap.empty(),
+});
+/** §17.4 rule 8: live Principals bound to one root in a Resource. */
+export const MAX_LIVE_BOUND = 32;
+/** §17.4 rule 8: accepted Device Grants per (root, leaf) pair. */
+export const MAX_DEVICE_GRANTS = 8;
+/** §17.5 rule 5: pre-emptive revocations of unbound Principals per root. */
+export const MAX_PREEMPTIVE_REVOCATIONS = 64;
+const count = (map, key) => map.get(key) ?? 0;
+/** The key of `revoked` for the pair (root, device). */
+export const revocationKey = (root, device) => `${toHex(root)}:${toHex(device)}`;
+const hasCode = (mask, code) => mask.includes(code);
+/** `bound(P)` (§80.1): P appeared as a device, at any level, in an accepted chain. */
+export const isBound = (state, p) => state.devices.has(toHex(p));
+/** `revoked[(root, device)]`, if any. */
+export const revocationOf = (state, root, device) => state.revoked.get(revocationKey(root, device));
+const isOwner = (state, p) => bytesEqual(state.owner.principalId, p);
+/**
+ * `rootStanding(R)` (§17.5): R is the owner, or the subject of at least one
+ * active grant that does not list `invite/claim`.
+ */
+export function rootStanding(state, root) {
+    if (isOwner(state, root))
+        return true;
+    for (const g of state.grants.values())
+        if (bytesEqual(g.subject, root) &&
+            !g.abilities.includes(ABILITY.INVITE_CLAIM) &&
+            isGrantActive(state, g.id))
+            return true;
+    return false;
+}
+/**
+ * `activeDevice(P)` (§17.5): registered, `(root, P)` not revoked, no
+ * revoked issuer in its current chain (the cascade), and its root in good
+ * standing. Undefined otherwise.
+ */
+export function activeDevice(state, p) {
+    const d = state.devices.get(toHex(p));
+    if (d === undefined || !d.registered)
+        return undefined;
+    if (revocationOf(state, d.root, p) !== undefined)
+        return undefined;
+    if (d.issuers.some((e) => revocationOf(state, d.root, e) !== undefined))
+        return undefined;
+    return rootStanding(state, d.root) ? d : undefined;
+}
+/** `actsFor(P)` (§80.1): the root of an active device, else P itself. */
+export const actsFor = (state, p) => activeDevice(state, p)?.root ?? p;
+/**
+ * `rootOf(P)` (§80.1): the root of a bound P (registered, suspended,
+ * revoked or intermediate), else P itself. For attribution, never for
+ * authority.
+ */
+export const rootOf = (state, p) => state.devices.get(toHex(p))?.root ?? p;
+/**
+ * `ownerAction(P)` (§80.1): for a bound P, an active device of the owner
+ * with `owner/act` in its mask; otherwise P is the owner.
+ */
+export function ownerAction(state, p) {
+    if (!isBound(state, p))
+        return isOwner(state, p);
+    const d = activeDevice(state, p);
+    return d !== undefined && isOwner(state, d.root) && hasCode(d.mask, DEVICE_ABILITY.OWNER_ACT);
+}
+/**
+ * The descriptor a transfer offer with `kid` is verified under (§62 class
+ * 4, §23.3): the kid's, when it is the owner or a device bound to the
+ * owner, active or not. Any other kid, known here or not, is neither a
+ * dependency nor signature-checked: the offer fails §23.3 item 1 in the
+ * authority class (ownerAction), AUTHORIZATION_FAILED.
+ */
+export function offerSigner(state, kid) {
+    if (isOwner(state, kid))
+        return state.owner;
+    const d = state.devices.get(toHex(kid));
+    return d !== undefined && isOwner(state, d.root) ? state.principals.get(toHex(kid)) : undefined;
+}
+/** `sameRoot(a, b)` (§25.2): the same `actsFor`, and at least one of them an active device. */
+export const sameRoot = (state, a, b) => bytesEqual(actsFor(state, a), actsFor(state, b)) &&
+    (activeDevice(state, a) !== undefined || activeDevice(state, b) !== undefined);
+const sameSet = (a, b) => a.length === b.length && new Set([...a, ...b]).size === new Set(a).size;
+/** §7.3 step 4.2–4.4 against `state`, for verifyChain. */
+export function deviceChainChecks(state) {
+    return {
+        rootAllowed: (root) => state.roles.get(toHex(root)) !== "device",
+        bindingMatches: (p) => {
+            const id = toHex(p.device.principalId);
+            if (state.roles.get(id) === "non-device")
+                return false;
+            const d = state.devices.get(id);
+            return (d === undefined ||
+                (bytesEqual(d.root, p.root) &&
+                    d.kind === p.kind &&
+                    sameSet(d.mask.map(String), p.mask.map(String)) &&
+                    sameSet(d.scope.map(toHex), p.scope.map(toHex))));
+        },
+        isRevoked: (root, device) => revocationOf(state, root, device) !== undefined,
+    };
+}
+// ---------------------------------------------------------------------------
+// Authority (class 5 of §62), after every dependency and signature
+const ALLOW = Object.freeze({ allowed: true });
+const deny = (reason) => Object.freeze({ allowed: false, reason });
+/** (c3), (c4), (c6) then step 4.2–4.4 of verifyChain at `state`; `inScope` on success. */
+function chainAuthority(state, chain) {
+    const intrinsic = checkChainAuthority(chain, state.resourceId);
+    if (!intrinsic.valid)
+        return deny(intrinsic.reason);
+    const s = checkChainState(chain, deviceChainChecks(state));
+    if (!s.valid)
+        return deny(s.reason);
+    return { allowed: true, inScope: intrinsic.inScope };
+}
+/**
+ * The device chain of a Genesis (field 5) or a transfer commit (field 2):
+ * verifyChain step 4 at `state`, then the leaf is a personal device with
+ * `owner/act` (§15, §23.3).
+ */
+export function authorizeOwnerChain(state, chain) {
+    const a = chainAuthority(state, chain);
+    if (!a.allowed)
+        return a;
+    const leaf = chain.leaf.payload;
+    if (leaf.kind !== DEVICE_KIND.PERSONAL || !hasCode(leaf.mask, DEVICE_ABILITY.OWNER_ACT))
+        return deny("the leaf is not a personal device with owner/act (§15, §23.3)");
+    return ALLOW;
+}
+/** An active device of `root` with `device/manage`. */
+const manages = (state, issuer, root) => {
+    const d = activeDevice(state, issuer);
+    return (d !== undefined && bytesEqual(d.root, root) && hasCode(d.mask, DEVICE_ABILITY.DEVICE_MANAGE));
+};
+/** §17.4 rules 4–7, in order (rules 1–3 are structure, dependencies and signatures). */
+export function authorizeDeviceGrant(state, issuer, body) {
+    const root = body.root;
+    // Rule 4.
+    if (!rootStanding(state, root))
+        return deny("the root has no standing (§17.4 rule 4)");
+    // Rule 5: verifyChain step 4, then a repeated leaf certificate is not a transition.
+    const a = chainAuthority(state, body.chain);
+    if (!a.allowed)
+        return a;
+    const leaf = body.chain.leaf;
+    const leafId = leaf.payload.device.principalId;
+    const existing = state.devices.get(toHex(leafId));
+    if (existing?.leafId !== null &&
+        existing?.leafId !== undefined &&
+        bytesEqual(existing.leafId, leaf.id))
+        return deny("the leaf certificate is already the device's current one (§17.4 rule 5)");
+    // Rule 6. A personal device submits only its first registration: once
+    // it has a chain it never re-certifies itself, not even with device/manage
+    // or owner/act, so a device suspended by the cascade waits for the root
+    // or another managing device (spec#2 7d75f7d).
+    const personal = leaf.payload.kind === DEVICE_KIND.PERSONAL;
+    const self = personal && bytesEqual(issuer, leafId);
+    if (self && existing !== undefined && existing.chain !== null)
+        return deny("a registered device never re-certifies itself (§17.4 rule 6)");
+    const allowed = bytesEqual(issuer, root) ||
+        self ||
+        (personal && body.chain.issuers.some((e) => bytesEqual(e, issuer))) ||
+        manages(state, issuer, root) ||
+        (isOwner(state, root) && ownerAction(state, issuer));
+    if (!allowed)
+        return deny("the issuer may not bind or register this device (§17.4 rule 6)");
+    // Rule 7.
+    if (body.pairingDevice !== undefined) {
+        const session = state.devices.get(toHex(body.pairingDevice));
+        const consumed = revocationOf(state, root, body.pairingDevice);
+        if (session === undefined ||
+            session.kind !== DEVICE_KIND.PAIRING ||
+            !bytesEqual(session.root, root) ||
+            consumed === undefined ||
+            consumed.reason !== 3n ||
+            consumed.approval === null ||
+            !bytesEqual(consumed.approval, leaf.payloadDigest))
+            return deny("no consumed pairing approval names this leaf (§17.4 rule 7)");
+    }
+    // Rule 8 (spec#2 bc03b0f): live bindings per root, grants per pair.
+    const fresh = body.chain.certificates.filter((c) => !state.devices.has(toHex(c.payload.device.principalId))).length;
+    if (count(state.liveBound, toHex(root)) + fresh > MAX_LIVE_BOUND)
+        return deny(`more than ${MAX_LIVE_BOUND} live devices would be bound to the root (§17.4 rule 8)`);
+    if ((existing?.grantsAccepted ?? 0) >= MAX_DEVICE_GRANTS)
+        return deny(`the device has had ${MAX_DEVICE_GRANTS} Device Grants for its root (§17.4 rule 8)`);
+    return ALLOW;
+}
+/** §17.5 rules 3–5, in order. */
+export function authorizeDeviceRevoke(state, issuer, body) {
+    const { root, device } = body;
+    const binding = state.devices.get(toHex(device));
+    // Rule 3: consistency.
+    if (binding !== undefined && !bytesEqual(binding.root, root))
+        return deny("the device is bound to another root (§17.5 rule 3)");
+    if (state.roles.get(toHex(device)) === "non-device")
+        return deny("the device is a non-device Principal here (§17.5 rule 3)");
+    if (state.roles.get(toHex(root)) === "device")
+        return deny("the root is bound as a device here (§17.5 rule 3)");
+    if (body.reason === 3n && binding?.kind !== DEVICE_KIND.PAIRING)
+        return deny("only a bound pairing device is consumed (§17.5 rule 3)");
+    // Rule 4.
+    const existing = revocationOf(state, root, device) !== undefined;
+    const allowed = (bytesEqual(issuer, root) && rootStanding(state, root)) ||
+        manages(state, issuer, root) ||
+        ownerAction(state, issuer) ||
+        (bytesEqual(issuer, device) && body.reason === 0n && binding?.registered === true && !existing);
+    if (!allowed)
+        return deny("the issuer may not revoke this device (§17.5 rule 4)");
+    // Rule 5 (spec#2 bc03b0f): only a pre-emptive revocation is limited.
+    if (existing)
+        return deny("the pair is already revoked (§17.5 rule 5)");
+    if (binding === undefined && count(state.preemptive, toHex(root)) >= MAX_PREEMPTIVE_REVOCATIONS)
+        return deny(`the root has ${MAX_PREEMPTIVE_REVOCATIONS} revocations of unbound Principals (§17.5 rule 5)`);
+    return ALLOW;
+}
+/**
+ * Binds every device of an accepted chain to its root and records the
+ * leaf's chain (§17.4 rule 9, §15, §23.3). Intermediates keep their own
+ * registration and current chains. `keepSameLeaf`: a transfer commit
+ * leaves a leaf registered with the same certificate ID unchanged.
+ * `grant`: a Device Grant, which counts towards its leaf's eight.
+ */
+export function bindChain(state, chain, inScope, keepSameLeaf, grant = false) {
+    let { roles, devices, principals, liveBound, preemptive } = state;
+    for (const c of chain.certificates) {
+        const p = c.payload;
+        const id = toHex(p.device.principalId);
+        if (!devices.has(id)) {
+            devices = put(devices, id, Object.freeze({
+                root: p.root,
+                kind: p.kind,
+                mask: p.mask,
+                scope: p.scope,
+                registered: false,
+                chain: null,
+                leafId: null,
+                issuers: Object.freeze([]),
+                grantsAccepted: 0,
+            }));
+            // A chain never holds a revoked pair (§7.3 step 4): the binding is live.
+            liveBound = put(liveBound, toHex(p.root), count(liveBound, toHex(p.root)) + 1);
+            // Its pre-emptive revocations no longer count: it is bound now.
+            for (const r of state.preemptiveRoots.get(id)?.keys() ?? [])
+                preemptive = put(preemptive, r, count(preemptive, r) - 1);
+        }
+        if (roles.get(id) !== "device")
+            roles = put(roles, id, "device");
+        if (principals.get(id) !== p.device)
+            principals = put(principals, id, p.device);
+    }
+    const leafKey = toHex(chain.leaf.payload.device.principalId);
+    const leaf = devices.get(leafKey);
+    const grantsAccepted = leaf.grantsAccepted + (grant ? 1 : 0);
+    if (keepSameLeaf &&
+        leaf.registered &&
+        leaf.leafId !== null &&
+        bytesEqual(leaf.leafId, chain.leaf.id)) {
+        if (grant)
+            devices = put(devices, leafKey, Object.freeze({ ...leaf, grantsAccepted }));
+    }
+    else
+        devices = put(devices, leafKey, Object.freeze({
+            ...leaf,
+            chain,
+            leafId: chain.leaf.id,
+            issuers: chain.issuers,
+            registered: leaf.registered || inScope,
+            grantsAccepted,
+        }));
+    return { ...state, roles, devices, principals, liveBound, preemptive };
+}
+/** The in-scope result of an accepted DEVICE_GRANT's chain at the state it was accepted on. */
+export const grantInScope = (state, body) => {
+    const a = checkChainAuthority(body.chain, state.resourceId);
+    return a.valid && a.inScope;
+};
+/**
+ * Records the revocation of an accepted DEVICE_REVOKE (§17.5 rule 6): a
+ * bound device releases its live place (§17.4 rule 8), an unbound one
+ * spends one of the root's pre-emptive revocations (§17.5 rule 5).
+ */
+export function recordRevocation(state, record, body) {
+    const root = toHex(body.root);
+    const device = toHex(body.device);
+    const revoked = put(state.revoked, revocationKey(body.root, body.device), Object.freeze({
+        root: body.root,
+        device: body.device,
+        reason: body.reason,
+        approval: body.approval ?? null,
+        revokedBy: controlRecordId(record.signed.id),
+    }));
+    if (state.devices.has(device))
+        return {
+            revoked,
+            liveBound: put(state.liveBound, root, count(state.liveBound, root) - 1),
+            preemptive: state.preemptive,
+            preemptiveRoots: state.preemptiveRoots,
+        };
+    return {
+        revoked,
+        liveBound: state.liveBound,
+        preemptive: put(state.preemptive, root, count(state.preemptive, root) + 1),
+        preemptiveRoots: put(state.preemptiveRoots, device, put(state.preemptiveRoots.get(device) ?? PersistentMap.empty(), root, true)),
+    };
+}
+/** Assigns the `non-device` role (§79). */
+export function nonDevice(roles, p) {
+    return put(roles, toHex(p), "non-device");
+}
+//# sourceMappingURL=device-state.js.map

package/dist/device.d.ts

@@ -0,0 +1,231 @@
+import { type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type CborValue } from "./cbor/index.js";
+import { type SignedObject, type Signer } from "./cose.js";
+import { type PrincipalDescriptor } from "./principal.js";
+/**
+ * Device Certificates and certificate chains (LFCP-WIRE-01 §7.2, §7.3,
+ * IDENTITY-01): the codec, the structural rules, and `verifyChain` with
+ * the class order of §62 (structure, dependencies, signatures, authority
+ * and state).
+ *
+ * Structure only decides what can be decided from the bytes: every
+ * failure of §7.3 rules 1–5, (c1), (c5) and (c7) is INVALID_STRUCTURE
+ * (MALFORMED_MESSAGE on the wire), thrown while decoding. The state
+ * questions of §7.3 step 4.2–4.4 (roles, bindings, revocations) are asked
+ * through the read-only `ChainStateChecks`; this module stores no state
+ * and applies no transition.
+ *
+ * Unknown mask codes (and 9, 11) are kept as received, in received order,
+ * and never promoted to abilities. Exact certificate bytes are kept: a
+ * chain re-encodes to the byte strings it was read from.
+ */
+/** §7.3 rule 1: the domain and version label, payload element 0. */
+export declare const DEVICE_CERT_LABEL = "LFCP-DEVICE-CERT-v1";
+/** §7.3: `certificate-chain = [1*4 bstr]`. */
+export declare const MAX_CHAIN_LENGTH = 4;
+/** §7.3 (c7): a chain whose leaf lists `device/manage` has at most three certificates. */
+export declare const MAX_MANAGING_CHAIN_LENGTH = 3;
+/** §7.3 rule 4: `device-mask = [1*32 uint]`. */
+export declare const MAX_MASK_ENTRIES = 32;
+/** §7.3: `resource-scope = [*64 resource-id]`. */
+export declare const MAX_SCOPE_ENTRIES = 64;
+/** §7.3: `bstr .size 16`, the serial. */
+export declare const SERIAL_LENGTH = 16;
+/** §17.1 codes that have meaning only inside a Device Certificate mask. */
+export declare const DEVICE_ABILITY: Readonly<{
+    /** `device/manage`: may sign Device Certificates and issue device records for its root. */
+    DEVICE_MANAGE: 12n;
+    /** `owner/act`: in a Resource its root owns, holds every standard ability. */
+    OWNER_ACT: 13n;
+}>;
+/** §7.2 kinds: 0 personal, 1 service, 2 pairing. 3 and above are reserved. */
+export declare const DEVICE_KIND: Readonly<{
+    readonly PERSONAL: 0;
+    readonly SERVICE: 1;
+    readonly PAIRING: 2;
+}>;
+export type DeviceKind = (typeof DEVICE_KIND)[keyof typeof DEVICE_KIND];
+/** `device-certificate-payload` (§7.3). */
+export interface DeviceCertificatePayload {
+    /** Field 1: the root the device acts for. */
+    readonly root: PrincipalId;
+    /** Field 2: the device (self-certifying, §7). */
+    readonly device: PrincipalDescriptor;
+    readonly kind: DeviceKind;
+    /** Field 4: 1–32 distinct codes, in received order. Unknown codes confer nothing. */
+    readonly mask: readonly bigint[];
+    /** Field 5: distinct Resource IDs, subject to the kind rules. */
+    readonly scope: readonly ResourceId[];
+    /** Field 6: 16 random bytes; no order, no time. */
+    readonly serial: Uint8Array;
+}
+/** A Device Certificate: the exact signed object and its payload. */
+export interface DeviceCertificate {
+    readonly signed: SignedObject;
+    readonly payload: DeviceCertificatePayload;
+    /** §7.3 rule 6: the §10.6 object ID of the exact COSE bytes. */
+    readonly id: Hash32;
+    /** §7.3 rule 6: SHA-256 of the exact payload bytes; what a pairing approval commits to. */
+    readonly payloadDigest: Hash32;
+}
+/** A chain well-formed for `root` (§7.3 (c1), (c5), (c7)): leaf first, issued by the root last. */
+export interface CertificateChain {
+    readonly root: PrincipalId;
+    readonly certificates: readonly DeviceCertificate[];
+    readonly leaf: DeviceCertificate;
+    /** The devices that issued inside the chain (`c_1 .. c_{n-1}`), leaf's issuer first. */
+    readonly issuers: readonly PrincipalId[];
+}
+/**
+ * §7.3 rules 2–5 on a payload: a 32-byte root, a valid device descriptor
+ * (§7) that is not the root; a mask of 1–32
+ * distinct unsigned 64-bit codes, with `1` and `2` whenever it lists `12`; at most 64
+ * distinct scope entries; and the kind rules for scope and mask. Throws
+ * INVALID_STRUCTURE. Writers and readers apply the same rules.
+ */
+export declare function checkDeviceCertificatePayload(p: DeviceCertificatePayload): void;
+/**
+ * Decodes `device-certificate-payload` (§7.3): a seven-element array
+ * labelled `LFCP-DEVICE-CERT-v1`, then rules 2–5. Array lengths are
+ * checked before their entries are decoded.
+ */
+export declare function deviceCertificatePayloadFromCbor(value: CborValue): DeviceCertificatePayload;
+/** The payload as the §7.3 array. */
+export declare function deviceCertificatePayloadToCbor(p: DeviceCertificatePayload): CborValue;
+/** Deterministic CBOR of a payload that satisfies §7.3 rules 1–5 (INVALID_STRUCTURE otherwise). */
+export declare function encodeDeviceCertificatePayload(p: DeviceCertificatePayload): Uint8Array;
+/**
+ * §7.3 rule 6: the certificate payload digest, SHA-256 of the payload's
+ * deterministic CBOR. Computed before the certificate exists, it is what a
+ * `DEVICE_REVOKE` with reason 3 commits to (§17.5, invariant N9).
+ */
+export declare const deviceCertificatePayloadDigest: (p: DeviceCertificatePayload) => Hash32;
+/** A fresh random serial (§7.3 field 6, §5.4). */
+export declare const newDeviceCertificateSerial: () => Uint8Array;
+/**
+ * Parses a Device Certificate from its exact COSE bytes: the canonical
+ * COSE_Sign1 shape with the §5.2 canonical-bytes check of its protected
+ * header and payload (cose.ts), then the payload rules. The signature is
+ * not verified here; its signer is decided by chain position (§7.3 (c2)).
+ */
+export declare function parseDeviceCertificate(bytes: Uint8Array): DeviceCertificate;
+/**
+ * Signs a Device Certificate. `signer` is the root or a managing device of
+ * the root; which one is valid is decided by the chain it is placed in.
+ * The payload must satisfy §7.3 rules 1–5 (INVALID_STRUCTURE otherwise).
+ */
+export declare function signDeviceCertificate(payload: DeviceCertificatePayload, signer: Signer): DeviceCertificate;
+/** Builds a chain (leaf first) for `root`, applying (c1), (c5) and (c7). INVALID_STRUCTURE otherwise. */
+export declare const certificateChain: (certificates: readonly DeviceCertificate[], root: PrincipalId) => CertificateChain;
+/**
+ * Decodes a received `certificate-chain` for `root`: an array of one to
+ * four byte strings (checked before any certificate is parsed), each a
+ * Device Certificate, then (c1), (c5), (c7). Every certificate is parsed
+ * in full before any chain rule, so every structural failure of every
+ * certificate is reported as structure (§62 class 1).
+ */
+export declare function certificateChainFromCbor(value: CborValue, root: PrincipalId): CertificateChain;
+/** The chain as the §7.3 array of exact certificate bytes (never re-encoded). */
+export declare const certificateChainToCbor: (chain: CertificateChain) => CborValue;
+/** The rule that decided a chain verdict, for diagnostics and tests. */
+export type DeviceChainRule = 
+/** (c1): the chain is for another root than the one the record names. */
+"c1-root"
+/** (c1), (c5), (c7) or rules 1–5 on a prospective certificate (preflight). */
+ | "structure"
+/** §7.3 step 2: the root's descriptor is not available. */
+ | "root-descriptor"
+/** (c2): a certificate's kid is not the Principal its position requires. */
+ | "c2-kid"
+/** (c2): a certificate's signature does not verify. */
+ | "c2-signature"
+/** (c3): an issuer is not a managing personal device. */
+ | "c3"
+/** (c4): a mask is not a subset of its issuer's mask. */
+ | "c4"
+/** (c6): a pairing leaf whose scope does not list the Resource. */
+ | "c6"
+/** step 4.2: `roles[R]` is `device`. */
+ | "root-role"
+/** step 4.3: a device's role or existing binding conflicts with this chain (N8). */
+ | "binding"
+/** step 4.4: `(R, E)` is revoked. */
+ | "revoked";
+export type ChainWireCode = "MALFORMED_MESSAGE" | "MISSING_DEPENDENCY" | "INVALID_SIGNATURE" | "AUTHORIZATION_FAILED";
+/** A refusal: the first failing rule in §62 class order and its wire code. */
+export interface ChainRefusal {
+    readonly valid: false;
+    readonly rule: DeviceChainRule;
+    readonly wireCode: ChainWireCode;
+    readonly reason: string;
+}
+/** An accepted chain (§7.3 result): evidence for the state validator, not a transition. */
+export interface VerifiedChain {
+    readonly valid: true;
+    readonly chain: CertificateChain;
+    /** The leaf's payload: its descriptor, kind, mask and scope. */
+    readonly leaf: DeviceCertificatePayload;
+    readonly leafId: Hash32;
+    readonly issuers: readonly PrincipalId[];
+    /** False only for a kind-1 leaf whose scope does not list the Resource (bound, never registered). */
+    readonly inScope: boolean;
+    /** Every certificate's payload, leaf first: the bindings to record (§79). */
+    readonly bindings: readonly DeviceCertificatePayload[];
+}
+/**
+ * Read-only view of the previous Control state for §7.3 step 4.2–4.4.
+ * Mask and scope are compared as sets; serial and issuer may differ.
+ */
+export interface ChainStateChecks {
+    /** Step 4.2: `roles[root]` is absent or `non-device`. */
+    rootAllowed(root: PrincipalId): boolean;
+    /**
+     * Step 4.3: `roles[device]` is absent or `device`, and an existing
+     * `devices[device]` has this root and the certificate's kind, mask and scope.
+     */
+    bindingMatches(certificate: DeviceCertificatePayload): boolean;
+    /** Step 4.4: whether `(root, device)` is in `revoked`. */
+    isRevoked(root: PrincipalId, device: PrincipalId): boolean;
+}
+/** The empty state of a Genesis (§15: `S = empty`); nothing is bound or revoked. */
+export declare const EMPTY_CHAIN_STATE: ChainStateChecks;
+/**
+ * §7.3 step 3 only (class 4): (c2) for every certificate, leaf first.
+ * A validator of a record that embeds a chain resolves every dependency
+ * of the record (outer issuer and chain root) before any signature, so
+ * this is separate from the descriptor lookup (§62).
+ */
+export declare function verifyChainSignatures(chain: CertificateChain, rootDescriptor: PrincipalDescriptor): ChainRefusal | {
+    readonly valid: true;
+};
+/** §7.3 step 4.1 (class 5): (c3), (c4), (c6). `inScope` as in VerifiedChain. */
+export declare function checkChainAuthority(chain: CertificateChain, resource: ResourceId): ChainRefusal | {
+    readonly valid: true;
+    readonly inScope: boolean;
+};
+/** §7.3 step 4.2–4.4 (class 5): the root's role, then every binding, then every revocation. */
+export declare function checkChainState(chain: CertificateChain, state: ChainStateChecks): ChainRefusal | {
+    readonly valid: true;
+};
+/**
+ * `verifyChain(chain, R, R_descriptor, S)` (§7.3) in Resource `resource`:
+ * one pass of the §62 classes. Structure was checked when the chain was
+ * decoded; here (c1) is checked against `root`, then the root descriptor
+ * (MISSING_DEPENDENCY when undefined), then every signature, then (c3),
+ * (c4), (c6), then the state predicates. Pure; reads no clock.
+ */
+export declare function verifyChain(chain: CertificateChain, root: PrincipalId, rootDescriptor: PrincipalDescriptor | undefined, resource: ResourceId, state: ChainStateChecks): VerifiedChain | ChainRefusal;
+/**
+ * Checks a prospective leaf before it is signed, against the issuing
+ * device's chain (`issuers`, leaf-first; empty when the root issues): the
+ * structure of the chain the leaf would form, the root descriptor, the
+ * issuers' signatures, then (c3), (c4), (c6). Lets a managing installation
+ * refuse an issuance (managing depth 4, an empty service scope) before it
+ * consumes a pairing session (§7.3 N9, IDENTITY-PROFILE-01 §5). Current
+ * state (standing, activity) is the caller's to check.
+ */
+export declare function preflightIssuance(leaf: DeviceCertificatePayload, issuers: readonly DeviceCertificate[], rootDescriptor: PrincipalDescriptor | undefined, resource: ResourceId): ChainRefusal | {
+    readonly valid: true;
+    readonly inScope: boolean;
+};
+//# sourceMappingURL=device.d.ts.map