@openlfcp/wire 0.2.1 → 0.3.0

package/dist/device.js

@@ -0,0 +1,427 @@
+import { bytesEqual, hash32, LfcpError, principalId, resourceId, secureRandom, toHex, } from "@openlfcp/core";
+import { isValidEd25519PublicKey, sha256 } from "@openlfcp/crypto";
+import { decodeStrict, encode } from "./cbor/index.js";
+import { parseSignedObject, signObject, verifySignedObject, } from "./cose.js";
+import { scanDeviceCertificate } from "./device-scan.js";
+import { invalid } from "./fields.js";
+import { derivePrincipalId, principalDescriptorFromCbor, principalDescriptorToCbor, } 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 const DEVICE_CERT_LABEL = "LFCP-DEVICE-CERT-v1";
+/** §7.3: `certificate-chain = [1*4 bstr]`. */
+export const MAX_CHAIN_LENGTH = 4;
+/** §7.3 (c7): a chain whose leaf lists `device/manage` has at most three certificates. */
+export const MAX_MANAGING_CHAIN_LENGTH = 3;
+/** §7.3 rule 4: `device-mask = [1*32 uint]`. */
+export const MAX_MASK_ENTRIES = 32;
+/** §7.3: `resource-scope = [*64 resource-id]`. */
+export const MAX_SCOPE_ENTRIES = 64;
+/** §7.3: `bstr .size 16`, the serial. */
+export const SERIAL_LENGTH = 16;
+/** §17.1 codes that have meaning only inside a Device Certificate mask. */
+export const DEVICE_ABILITY = Object.freeze({
+    /** `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 const DEVICE_KIND = Object.freeze({ PERSONAL: 0, SERVICE: 1, PAIRING: 2 });
+// ---------------------------------------------------------------------------
+// Payload
+const fail = (why) => invalid("device-certificate-payload", why);
+const UINT64_MAX = 2n ** 64n - 1n;
+const hasCode = (mask, code) => mask.includes(code);
+/** Distinct members, compared by value (Resource IDs as bytes). */
+function repeats(list, key) {
+    return new Set(list.map(key)).size !== list.length;
+}
+/**
+ * §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 function checkDeviceCertificatePayload(p) {
+    if (!(p.root instanceof Uint8Array) || p.root.length !== 32)
+        fail("the root must be a 32-byte Principal ID");
+    // Rule 2: the descriptor as §7 requires (recomputed ID, canonical
+    // Ed25519 point of large order), so that what passes here can be signed.
+    const d = p.device;
+    try {
+        if (!bytesEqual(derivePrincipalId(d.ed25519PublicKey, d.x25519PublicKey), d.principalId))
+            fail("the device descriptor's ID is not the §7 hash of its keys (§7.3 rule 2)");
+    }
+    catch (e) {
+        if (e instanceof LfcpError && e.code === "INVALID_STRUCTURE")
+            throw e;
+        fail("the device descriptor's keys are not 32-byte keys (§7.3 rule 2)");
+    }
+    if (!isValidEd25519PublicKey(d.ed25519PublicKey))
+        fail("the device's Ed25519 key is not a canonical point of large order (§7.3 rule 2)");
+    if (bytesEqual(p.root, p.device.principalId))
+        fail("the device is the root (§7.3 rule 2)");
+    if (p.kind !== 0 && p.kind !== 1 && p.kind !== 2)
+        fail("kind must be 0, 1 or 2 (§7.3 rule 3)");
+    if (p.mask.length < 1 || p.mask.length > MAX_MASK_ENTRIES)
+        fail(`the mask must hold 1 to ${MAX_MASK_ENTRIES} codes (§7.3 rule 4)`);
+    if (!p.mask.every((c) => typeof c === "bigint" && c >= 0n && c <= UINT64_MAX))
+        fail("every mask code must be an unsigned 64-bit integer (§7.3)");
+    if (repeats(p.mask, (c) => c))
+        fail("the mask repeats a code (§7.3 rule 4)");
+    const manage = hasCode(p.mask, DEVICE_ABILITY.DEVICE_MANAGE);
+    if (manage && !(hasCode(p.mask, 1n) && hasCode(p.mask, 2n)))
+        fail("a mask that lists 12 must list 1 and 2 (§7.3 rule 4)");
+    if (p.scope.length > MAX_SCOPE_ENTRIES)
+        fail(`the scope holds more than ${MAX_SCOPE_ENTRIES} Resources (§7.3)`);
+    if (!p.scope.every((r) => r instanceof Uint8Array && r.length === 32))
+        fail("every scope entry must be a 32-byte Resource ID (§7.3)");
+    if (repeats(p.scope, toHex))
+        fail("the scope repeats a Resource (§7.3 rule 5)");
+    if (!(p.serial instanceof Uint8Array) || p.serial.length !== SERIAL_LENGTH)
+        fail(`the serial must be ${SERIAL_LENGTH} bytes (§7.3)`);
+    switch (p.kind) {
+        case DEVICE_KIND.PERSONAL:
+            if (p.scope.length !== 0)
+                fail("a personal device has an empty scope (§7.3 rule 5)");
+            return;
+        case DEVICE_KIND.SERVICE:
+            if (p.scope.length === 0)
+                fail("a service device lists 1 to 64 Resources (§7.3 rule 5)");
+            if (manage || hasCode(p.mask, DEVICE_ABILITY.OWNER_ACT))
+                fail("a service device never lists 12 or 13 (§7.3 rule 5)");
+            return;
+        case DEVICE_KIND.PAIRING:
+            if (p.scope.length !== 1)
+                fail("a pairing device lists exactly one Resource (§7.3 rule 5)");
+            if (!p.mask.every((c) => c === 1n || c === 2n))
+                fail("a pairing device's mask is a subset of {1, 2} (§7.3 rule 5)");
+            return;
+    }
+}
+function uintOf(value) {
+    return (typeof value === "number" || typeof value === "bigint") && value >= 0
+        ? BigInt(value)
+        : undefined;
+}
+/**
+ * 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 function deviceCertificatePayloadFromCbor(value) {
+    if (!Array.isArray(value))
+        fail("not an array (§7.3 rule 1)");
+    const fields = value;
+    if (fields.length !== 7)
+        fail("must have seven elements (§7.3 rule 1)");
+    const [label, root, device, kind, mask, scope, serial] = fields;
+    if (label !== DEVICE_CERT_LABEL)
+        fail(`element 0 must be "${DEVICE_CERT_LABEL}" (§7.3 rule 1)`);
+    if (!(root instanceof Uint8Array) || root.length !== 32)
+        fail("field 1 must be a 32-byte Principal ID");
+    const k = uintOf(kind);
+    if (k === undefined || k > 2n)
+        fail("field 3 must be 0, 1 or 2 (§7.3 rule 3)");
+    if (!Array.isArray(mask))
+        fail("field 4 must be an array");
+    const maskList = mask;
+    if (maskList.length < 1 || maskList.length > MAX_MASK_ENTRIES)
+        fail(`field 4 must hold 1 to ${MAX_MASK_ENTRIES} codes (§7.3 rule 4)`);
+    if (!Array.isArray(scope))
+        fail("field 5 must be an array");
+    const scopeList = scope;
+    if (scopeList.length > MAX_SCOPE_ENTRIES)
+        fail(`field 5 must hold at most ${MAX_SCOPE_ENTRIES} Resource IDs (§7.3)`);
+    if (!(serial instanceof Uint8Array) || serial.length !== SERIAL_LENGTH)
+        fail(`field 6 must be ${SERIAL_LENGTH} bytes`);
+    let descriptor;
+    try {
+        descriptor = principalDescriptorFromCbor(device);
+    }
+    catch (e) {
+        return fail(`field 2 is not a valid Principal Descriptor (§7.3 rule 2): ${String(e)}`);
+    }
+    const payload = Object.freeze({
+        root: principalId(Uint8Array.from(root)),
+        device: descriptor,
+        kind: Number(k),
+        mask: Object.freeze(maskList.map((c) => uintOf(c) ?? fail("field 4 must hold unsigned integers only"))),
+        scope: Object.freeze(scopeList.map((r) => r instanceof Uint8Array && r.length === 32
+            ? resourceId(Uint8Array.from(r))
+            : fail("field 5 must hold 32-byte Resource IDs only"))),
+        serial: Uint8Array.from(serial),
+    });
+    checkDeviceCertificatePayload(payload);
+    return payload;
+}
+/** The payload as the §7.3 array. */
+export function deviceCertificatePayloadToCbor(p) {
+    return [
+        DEVICE_CERT_LABEL,
+        p.root,
+        principalDescriptorToCbor(p.device),
+        p.kind,
+        [...p.mask],
+        [...p.scope],
+        p.serial,
+    ];
+}
+/** Deterministic CBOR of a payload that satisfies §7.3 rules 1–5 (INVALID_STRUCTURE otherwise). */
+export function encodeDeviceCertificatePayload(p) {
+    checkDeviceCertificatePayload(p);
+    return encode(deviceCertificatePayloadToCbor(p));
+}
+/**
+ * §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 const deviceCertificatePayloadDigest = (p) => hash32(sha256(encodeDeviceCertificatePayload(p)));
+/** A fresh random serial (§7.3 field 6, §5.4). */
+export const newDeviceCertificateSerial = () => secureRandom(SERIAL_LENGTH);
+// ---------------------------------------------------------------------------
+// Certificate
+/**
+ * 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 function parseDeviceCertificate(bytes) {
+    // Bounds first, on the raw bytes: nothing is decoded or copied before them.
+    scanDeviceCertificate(bytes);
+    const signed = parseSignedObject(bytes);
+    const payload = deviceCertificatePayloadFromCbor(decodeStrict(signed.payloadBytes));
+    return Object.freeze({
+        signed,
+        payload,
+        id: signed.id,
+        payloadDigest: hash32(sha256(signed.payloadBytes)),
+    });
+}
+/**
+ * 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 function signDeviceCertificate(payload, signer) {
+    return parseDeviceCertificate(signObject(encodeDeviceCertificatePayload(payload), signer).bytes);
+}
+// ---------------------------------------------------------------------------
+// Chain structure
+const chainFail = (why) => invalid("certificate-chain", why);
+/**
+ * (c1) every certificate names `root`; (c5) no device twice and none is
+ * the root (rule 2 already refuses device = own root); (c7) a managing
+ * leaf has at most three certificates. Payloads are leaf first.
+ */
+function checkChainStructure(payloads, root) {
+    if (payloads.length < 1 || payloads.length > MAX_CHAIN_LENGTH)
+        chainFail(`must hold 1 to ${MAX_CHAIN_LENGTH} certificates (§7.3 (c1))`);
+    const seen = new Set();
+    for (const p of payloads) {
+        if (!bytesEqual(p.root, root))
+            chainFail("a certificate names another root (§7.3 (c1))");
+        const id = toHex(p.device.principalId);
+        if (seen.has(id) || bytesEqual(p.device.principalId, root))
+            chainFail("a device appears twice, or the root appears as a device (§7.3 (c5))");
+        seen.add(id);
+    }
+    const leaf = payloads[0];
+    if (hasCode(leaf.mask, DEVICE_ABILITY.DEVICE_MANAGE) &&
+        payloads.length > MAX_MANAGING_CHAIN_LENGTH)
+        chainFail(`a managing leaf has at most ${MAX_MANAGING_CHAIN_LENGTH} certificates (§7.3 (c7))`);
+}
+function chainOf(certificates, root) {
+    checkChainStructure(certificates.map((c) => c.payload), root);
+    return Object.freeze({
+        root: principalId(Uint8Array.from(root)),
+        certificates: Object.freeze([...certificates]),
+        leaf: certificates[0],
+        issuers: Object.freeze(certificates.slice(1).map((c) => c.payload.device.principalId)),
+    });
+}
+/** Builds a chain (leaf first) for `root`, applying (c1), (c5) and (c7). INVALID_STRUCTURE otherwise. */
+export const certificateChain = (certificates, root) => chainOf(certificates, root);
+/**
+ * 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 function certificateChainFromCbor(value, root) {
+    if (!Array.isArray(value))
+        chainFail("not an array");
+    const list = value;
+    if (list.length < 1 || list.length > MAX_CHAIN_LENGTH)
+        chainFail(`must hold 1 to ${MAX_CHAIN_LENGTH} certificates`);
+    if (!list.every((c) => c instanceof Uint8Array))
+        chainFail("must hold byte strings only");
+    return chainOf(list.map(parseDeviceCertificate), root);
+}
+/** The chain as the §7.3 array of exact certificate bytes (never re-encoded). */
+export const certificateChainToCbor = (chain) => chain.certificates.map((c) => c.signed.bytes);
+const WIRE_OF = {
+    "c1-root": "MALFORMED_MESSAGE",
+    structure: "MALFORMED_MESSAGE",
+    "root-descriptor": "MISSING_DEPENDENCY",
+    "c2-kid": "INVALID_SIGNATURE",
+    "c2-signature": "INVALID_SIGNATURE",
+    c3: "AUTHORIZATION_FAILED",
+    c4: "AUTHORIZATION_FAILED",
+    c6: "AUTHORIZATION_FAILED",
+    "root-role": "AUTHORIZATION_FAILED",
+    binding: "AUTHORIZATION_FAILED",
+    revoked: "AUTHORIZATION_FAILED",
+};
+const refuse = (rule, reason) => Object.freeze({ valid: false, rule, wireCode: WIRE_OF[rule], reason });
+/** The empty state of a Genesis (§15: `S = empty`); nothing is bound or revoked. */
+export const EMPTY_CHAIN_STATE = Object.freeze({
+    rootAllowed: () => true,
+    bindingMatches: () => true,
+    isRevoked: () => false,
+});
+/**
+ * (c2): the last certificate's kid must be the root, so a root descriptor
+ * for another Principal cannot verify it: INVALID_SIGNATURE, as in sdk-rs.
+ */
+function rootDescriptorMismatch(root, descriptor) {
+    return bytesEqual(descriptor.principalId, root)
+        ? undefined
+        : refuse("c2-kid", "the root descriptor is not the chain's root (c2)");
+}
+function verifySignatures(certificates, rootDescriptor) {
+    for (const [i, c] of certificates.entries()) {
+        const signer = certificates[i + 1]?.payload.device ?? rootDescriptor;
+        const v = verifySignedObject(c.signed, signer);
+        if (!v.valid)
+            return v.reason === "KID_MISMATCH"
+                ? refuse("c2-kid", `certificate ${i} is not signed by the Principal (c2) requires`)
+                : refuse("c2-signature", `certificate ${i}'s signature does not verify (c2)`);
+    }
+    return undefined;
+}
+/** (c3), (c4), (c6) for every link, each rule over the whole chain before the next. */
+function checkAuthority(payloads, resource) {
+    for (const issuer of payloads.slice(1))
+        if (issuer.kind !== DEVICE_KIND.PERSONAL || !hasCode(issuer.mask, DEVICE_ABILITY.DEVICE_MANAGE))
+            return refuse("c3", "an issuer is not a personal device with device/manage (c3)");
+    for (const [i, child] of payloads.entries()) {
+        const issuer = payloads[i + 1];
+        if (issuer !== undefined && !child.mask.every((c) => hasCode(issuer.mask, c)))
+            return refuse("c4", "a mask is not a subset of its issuer's mask (c4)");
+    }
+    const leaf = payloads[0];
+    const lists = leaf.scope.some((r) => bytesEqual(r, resource));
+    if (leaf.kind === DEVICE_KIND.PAIRING && !lists)
+        return refuse("c6", "a pairing leaf whose scope does not list this Resource (c6)");
+    return leaf.kind !== DEVICE_KIND.SERVICE || lists;
+}
+/**
+ * §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 function verifyChainSignatures(chain, rootDescriptor) {
+    return (rootDescriptorMismatch(chain.root, rootDescriptor) ??
+        verifySignatures(chain.certificates, rootDescriptor) ?? { valid: true });
+}
+/** §7.3 step 4.1 (class 5): (c3), (c4), (c6). `inScope` as in VerifiedChain. */
+export function checkChainAuthority(chain, resource) {
+    const r = checkAuthority(chain.certificates.map((c) => c.payload), resource);
+    return typeof r === "boolean" ? { valid: true, inScope: r } : r;
+}
+/** §7.3 step 4.2–4.4 (class 5): the root's role, then every binding, then every revocation. */
+export function checkChainState(chain, state) {
+    if (!state.rootAllowed(chain.root))
+        return refuse("root-role", "the root is bound as a device in this Resource (step 4.2)");
+    for (const c of chain.certificates)
+        if (!state.bindingMatches(c.payload))
+            return refuse("binding", "a device's role or binding conflicts with this chain (step 4.3, N8)");
+    for (const c of chain.certificates)
+        if (state.isRevoked(chain.root, c.payload.device.principalId))
+            return refuse("revoked", "a device of the chain is revoked for this root (step 4.4)");
+    return { 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 function verifyChain(chain, root, rootDescriptor, resource, state) {
+    if (!bytesEqual(chain.root, root))
+        return refuse("c1-root", "the chain is for another root (c1)");
+    if (rootDescriptor === undefined)
+        return refuse("root-descriptor", "the root's descriptor is not known (step 2)");
+    const signatures = verifyChainSignatures(chain, rootDescriptor);
+    if (!signatures.valid)
+        return signatures;
+    const authority = checkChainAuthority(chain, resource);
+    if (!authority.valid)
+        return authority;
+    const s = checkChainState(chain, state);
+    if (!s.valid)
+        return s;
+    return Object.freeze({
+        valid: true,
+        chain,
+        leaf: chain.leaf.payload,
+        leafId: chain.leaf.id,
+        issuers: chain.issuers,
+        inScope: authority.inScope,
+        bindings: Object.freeze(chain.certificates.map((c) => c.payload)),
+    });
+}
+/**
+ * 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 function preflightIssuance(leaf, issuers, rootDescriptor, resource) {
+    if (issuers.length >= MAX_CHAIN_LENGTH)
+        return refuse("structure", `a chain holds at most ${MAX_CHAIN_LENGTH} certificates (c1)`);
+    const payloads = [leaf, ...issuers.map((c) => c.payload)];
+    try {
+        checkDeviceCertificatePayload(leaf);
+        checkChainStructure(payloads, leaf.root);
+    }
+    catch (e) {
+        if (e instanceof LfcpError && e.code === "INVALID_STRUCTURE")
+            return refuse("structure", e.message);
+        throw e;
+    }
+    if (rootDescriptor === undefined)
+        return refuse("root-descriptor", "the root's descriptor is not known (step 2)");
+    const signatures = rootDescriptorMismatch(leaf.root, rootDescriptor) ?? verifySignatures(issuers, rootDescriptor);
+    if (signatures !== undefined)
+        return signatures;
+    const authority = checkAuthority(payloads, resource);
+    return typeof authority === "boolean" ? { valid: true, inScope: authority } : authority;
+}
+//# sourceMappingURL=device.js.map

package/dist/index.d.ts

@@ -1,20 +1,23 @@
 /** Name of this package. */
 export declare const PACKAGE = "@openlfcp/wire";
-export { ABILITY, ABILITY_NAMES, type Authorization, abilitiesOf, authorizeControlRecord, type CapabilityState, canDistributeKey, type Grant, hasAbility, isGrantActive, isStandardAbility, type VerifiedOwnerTransfer, verifyOwnerTransfer, } from "./capability.js";
+export { ABILITY, ABILITY_NAMES, type Authorization, abilitiesOf, authorizeControlRecord, type CapabilityState, canDistributeKey, exposedReaders, type Grant, hasAbility, isExposingRevocation, isGrantActive, isStandardAbility, type VerifiedOwnerTransfer, verifyOwnerTransfer, } from "./capability.js";
 export { type ChainOptions, type ChainProblem, type ChainResult, type ControlEpoch, type ControlRoute, type ControlState, type EpochHistory, validateControlChain, } from "./chain.js";
 export { type ControlBody, type ControlBodyType, type ControlRecord, type ControlRecordHeader, controlBodyFromCbor, controlBodyToCbor, controlRecordSigner, controlTypeOf, decodeControlRecord, encodeControlRecordPayload, isMvpSupported, type OwnerTransferAcceptPayload, type OwnerTransferOfferPayload, ownerTransferAcceptPayloadFromCbor, ownerTransferOfferPayloadFromCbor, parseOwnerTransferAccept, parseOwnerTransferOffer, type SignedControlRecord, signControlRecord, verifyGenesis, } from "./control.js";
 export { type ControlSyncPlan, type LocalControl, localControlOf, planControlSync, } from "./control-sync.js";
 export { COSE_ALG_EDDSA, objectId, parseSignedObject, type SignedBytes, type SignedObject, type Signer, signObject, sigStructureBytes, type VerifyResult, verifySignedObject, } from "./cose.js";
 export { checkDataUnit, type DataProfileCodec, type DataUnitAadFields, type DataUnitCheck, type DataUnitCheckOptions, type DataUnitEquivocation, type DataUnitHoldReason, type DataUnitQuarantined, type DataUnitRejected, type DataUnitRejectReason, dataUnitAad, encodeDataUnitPayload, InMemorySeenUnits, type ReceiveDataUnitOptions, type ReceivedDataUnit, receiveDataUnit, type SealedDataUnit, type SeenRecord, type SeenUnits, sealDataUnit, } from "./data-unit.js";
+export { type CertificateChain, type ChainRefusal, type ChainStateChecks, type ChainWireCode, certificateChain, certificateChainFromCbor, certificateChainToCbor, checkChainAuthority, checkChainState, checkDeviceCertificatePayload, DEVICE_ABILITY, DEVICE_CERT_LABEL, DEVICE_KIND, type DeviceCertificate, type DeviceCertificatePayload, type DeviceChainRule, type DeviceKind, deviceCertificatePayloadDigest, deviceCertificatePayloadFromCbor, deviceCertificatePayloadToCbor, EMPTY_CHAIN_STATE, encodeDeviceCertificatePayload, MAX_CHAIN_LENGTH, MAX_MANAGING_CHAIN_LENGTH, MAX_MASK_ENTRIES, MAX_SCOPE_ENTRIES, newDeviceCertificateSerial, parseDeviceCertificate, preflightIssuance, SERIAL_LENGTH, signDeviceCertificate, type VerifiedChain, verifyChain, verifyChainSignatures, } from "./device.js";
+export { activeDevice, actsFor, authorizeDeviceGrant, authorizeDeviceRevoke, type DeviceBinding, type DeviceRevocation, type DeviceRole, type DeviceState, deviceChainChecks, isBound, ownerAction, revocationOf, rootOf, rootStanding, sameRoot, } from "./device-state.js";
 export { checkReceivedUrl, checkWriterUrl, ENDPOINT_FLAGS, type Endpoint, endpointFromCbor, endpointToCbor, } from "./endpoint.js";
 export { type ControlView, classifyDataUnit, type DataPutDecision, type DataUnitHeader, type EpochClassification, type EpochRotation, isSequenceWithinFrontier, KEY_EPOCH_REASON, rotateEpoch, serverAcceptsDataPut, } from "./epoch.js";
 export { type AuthenticatedSession, type AuthProofCheck, type AuthTranscriptFields, authTranscript, type ClientHandshakeConfig, type ClientSession, type ClientStep, clientReceive, decodeAuthTranscript, isResourceMessage, type RandomSource, type ReadySession, type ServerHandshakeConfig, type ServerSession, type ServerStep, selectWireProfile, serverReceive, signAuthProof, startClientHandshake, startServerSession, verifyAuthProof, WIRE_PROFILE, } from "./handshake.js";
 export { type ActorHave, type ActorRange, actorHaveFromCbor, actorHaveToCbor, addRange, addSequence, batchDataRanges, canonicalFrontierFromCbor, canonicalFrontierToCbor, checkLiveHave, type HaveVector, hasSequence, haveDifference, type LiveHaveEntry, liveHavesOf, MAX_DATA_GET_RANGES, missingAfter, missingFrom, normalizeLiveHaves, type SequenceRange, unionHaves, } from "./have.js";
-export { assembleInviteUri, decodeInviteSecret, encodeInviteSecret, INVITE_SECRET_VERSION, type Invitation, invitationPrincipal, parseInviteUri, verifyInvitationSecret, } from "./invite.js";
+export { assembleInviteUri, assemblePairingUri, decodeInviteSecret, deviceFingerprint, encodeInviteSecret, INVITE_SECRET_VERSION, type Invitation, invitationPrincipal, type PairingLink, pairingDeviceSigner, parseInviteUri, parsePairingUri, verifyInvitationSecret, } from "./invite.js";
 export { type KeyPackageCheck, type KeyPackageRecipient, keyPackageHpkeAad, keyPackageHpkeInfo, openKeyPackage, type ReceivedKeyPackage, receiveKeyPackage, type SealedKeyPackage, sealKeyPackage, verifyKeyPackage, } from "./key-package.js";
 export { type AckBody, type AnyMessage, type AuthBody, type ChallengeBody, type ControlGetBody, type ControlHaveBody, type ControlHeadRef, type CoreMessageType, createMessage, type DataGetBody, type DataHaveBody, type DataRange, DEFAULT_MAX_MESSAGE_BYTES, type DecodedEnvelope, type DecodeOptions, decodeEnvelope, decodeFrame, decodeMessage, ERROR_CODE, type ErrorBody, type ExtensionMessage, encodeMessage, FIRST_EXTENSION_MESSAGE_TYPE, type Frame, type FrameResult, type HelloBody, type KeyPackageGetBody, type LfcpMessage, type LiveActorHave, MESSAGE_TYPE, type MessageBodies, messageErrorWireCode, newMessageId, type ObjectListBody, type PingBody, type PresenceBody, type PresenceLeaveBody, type ReadyBody, type ResourceBody, type ResourceHostBody, type ResourceHostedBody, type ResourceOpenBody, type ResourceOpenedBody, replyTo, type SnapshotBody, type SnapshotGetBody, type SnapshotSummary, type WireErrorName, } from "./message.js";
 export { CONTROL_TYPE, type ControlRecordPayload, controlRecordPayloadFromCbor, type DataUnitPayload, dataUnitPayloadFromCbor, decodeControlRecordPayload, decodeDataUnitPayload, decodeKeyPackagePayload, decodeSnapshotPayload, expectedSignerOf, type KeyPackagePayload, keyPackagePayloadFromCbor, type Parsed, parseControlRecord, parseDataUnit, parseKeyPackage, parseSnapshot, type SnapshotPayload, snapshotPayloadFromCbor, } from "./objects.js";
 export { decodePrincipalDescriptor, derivePrincipalId, encodePrincipalDescriptor, type PrincipalDescriptor, principalDescriptor, principalDescriptorFromCbor, principalDescriptorFromKeys, principalDescriptorToCbor, } from "./principal.js";
+export { type RevokedReaderPrefix, revokedReaderPrefix } from "./revoked-reader.js";
 export { type ClientConnectionEvent, type ClientConnectionState, clientConnectionTransition, type ServerSessionEvent, type ServerSessionState, serverSessionTransition, } from "./session-state.js";
 export { beyondCutoff, checkSnapshot, encodeSnapshotPayload, type ReceivedSnapshot, type ReceiveSnapshotOptions, receiveSnapshot, type SealedSnapshot, type SnapshotAadFields, type SnapshotCheck, type SnapshotCheckOptions, type SnapshotRejected, type SnapshotRejectReason, sealSnapshot, snapshotAad, } from "./snapshot.js";
 export { type ControlPutBody, controlPutBodyFromCbor, decodeControlPutBody, proposeControlPut, proposeControlTransition, type TransitionResult, } from "./transition.js";

package/dist/index.js

@@ -1,20 +1,23 @@
 /** Name of this package. */
 export const PACKAGE = "@openlfcp/wire";
-export { ABILITY, ABILITY_NAMES, abilitiesOf, authorizeControlRecord, canDistributeKey, hasAbility, isGrantActive, isStandardAbility, verifyOwnerTransfer, } from "./capability.js";
+export { ABILITY, ABILITY_NAMES, abilitiesOf, authorizeControlRecord, canDistributeKey, exposedReaders, hasAbility, isExposingRevocation, isGrantActive, isStandardAbility, verifyOwnerTransfer, } from "./capability.js";
 export { validateControlChain, } from "./chain.js";
 export { controlBodyFromCbor, controlBodyToCbor, controlRecordSigner, controlTypeOf, decodeControlRecord, encodeControlRecordPayload, isMvpSupported, ownerTransferAcceptPayloadFromCbor, ownerTransferOfferPayloadFromCbor, parseOwnerTransferAccept, parseOwnerTransferOffer, signControlRecord, verifyGenesis, } from "./control.js";
 export { localControlOf, planControlSync, } from "./control-sync.js";
 export { COSE_ALG_EDDSA, objectId, parseSignedObject, signObject, sigStructureBytes, verifySignedObject, } from "./cose.js";
 export { checkDataUnit, dataUnitAad, encodeDataUnitPayload, InMemorySeenUnits, receiveDataUnit, sealDataUnit, } from "./data-unit.js";
+export { certificateChain, certificateChainFromCbor, certificateChainToCbor, checkChainAuthority, checkChainState, checkDeviceCertificatePayload, DEVICE_ABILITY, DEVICE_CERT_LABEL, DEVICE_KIND, deviceCertificatePayloadDigest, deviceCertificatePayloadFromCbor, deviceCertificatePayloadToCbor, EMPTY_CHAIN_STATE, encodeDeviceCertificatePayload, MAX_CHAIN_LENGTH, MAX_MANAGING_CHAIN_LENGTH, MAX_MASK_ENTRIES, MAX_SCOPE_ENTRIES, newDeviceCertificateSerial, parseDeviceCertificate, preflightIssuance, SERIAL_LENGTH, signDeviceCertificate, verifyChain, verifyChainSignatures, } from "./device.js";
+export { activeDevice, actsFor, authorizeDeviceGrant, authorizeDeviceRevoke, deviceChainChecks, isBound, ownerAction, revocationOf, rootOf, rootStanding, sameRoot, } from "./device-state.js";
 export { checkReceivedUrl, checkWriterUrl, ENDPOINT_FLAGS, endpointFromCbor, endpointToCbor, } from "./endpoint.js";
 export { classifyDataUnit, isSequenceWithinFrontier, KEY_EPOCH_REASON, rotateEpoch, serverAcceptsDataPut, } from "./epoch.js";
 export { authTranscript, clientReceive, decodeAuthTranscript, isResourceMessage, selectWireProfile, serverReceive, signAuthProof, startClientHandshake, startServerSession, verifyAuthProof, WIRE_PROFILE, } from "./handshake.js";
 export { actorHaveFromCbor, actorHaveToCbor, addRange, addSequence, batchDataRanges, canonicalFrontierFromCbor, canonicalFrontierToCbor, checkLiveHave, hasSequence, haveDifference, liveHavesOf, MAX_DATA_GET_RANGES, missingAfter, missingFrom, normalizeLiveHaves, unionHaves, } from "./have.js";
-export { assembleInviteUri, decodeInviteSecret, encodeInviteSecret, INVITE_SECRET_VERSION, invitationPrincipal, parseInviteUri, verifyInvitationSecret, } from "./invite.js";
+export { assembleInviteUri, assemblePairingUri, decodeInviteSecret, deviceFingerprint, encodeInviteSecret, INVITE_SECRET_VERSION, invitationPrincipal, pairingDeviceSigner, parseInviteUri, parsePairingUri, verifyInvitationSecret, } from "./invite.js";
 export { keyPackageHpkeAad, keyPackageHpkeInfo, openKeyPackage, receiveKeyPackage, sealKeyPackage, verifyKeyPackage, } from "./key-package.js";
 export { createMessage, DEFAULT_MAX_MESSAGE_BYTES, decodeEnvelope, decodeFrame, decodeMessage, ERROR_CODE, encodeMessage, FIRST_EXTENSION_MESSAGE_TYPE, MESSAGE_TYPE, messageErrorWireCode, newMessageId, replyTo, } from "./message.js";
 export { CONTROL_TYPE, controlRecordPayloadFromCbor, dataUnitPayloadFromCbor, decodeControlRecordPayload, decodeDataUnitPayload, decodeKeyPackagePayload, decodeSnapshotPayload, expectedSignerOf, keyPackagePayloadFromCbor, parseControlRecord, parseDataUnit, parseKeyPackage, parseSnapshot, snapshotPayloadFromCbor, } from "./objects.js";
 export { decodePrincipalDescriptor, derivePrincipalId, encodePrincipalDescriptor, principalDescriptor, principalDescriptorFromCbor, principalDescriptorFromKeys, principalDescriptorToCbor, } from "./principal.js";
+export { revokedReaderPrefix } from "./revoked-reader.js";
 export { clientConnectionTransition, serverSessionTransition, } from "./session-state.js";
 export { beyondCutoff, checkSnapshot, encodeSnapshotPayload, receiveSnapshot, sealSnapshot, snapshotAad, } from "./snapshot.js";
 export { controlPutBodyFromCbor, decodeControlPutBody, proposeControlPut, proposeControlTransition, } from "./transition.js";

package/dist/invite.d.ts

@@ -1,4 +1,4 @@
-import { type ControlRecordId, type ResourceId } from "@openlfcp/core";
+import { type ControlRecordId, type PrincipalId, type ResourceId } from "@openlfcp/core";
 import { InvitationSecret } from "@openlfcp/crypto";
 import type { ControlState } from "./chain.js";
 import type { Signer } from "./cose.js";
@@ -65,16 +65,52 @@ export interface Invitation {
  */
 export declare function assembleInviteUri(invitation: Invitation): string;
 /**
- * Parses a §18.2 invitation URI. The scheme and host compare
- * case-insensitively (RFC 3986 §3.1, §3.2.2); the path is one Resource ID;
- * the query has one or more `endpoint` parameters and exactly one `grant`;
- * other parameters are ignored, for forward compatibility, once their
- * percent-encoding is checked; a fragment, if present, is exactly
- * `secret=<b64url>`.
+ * Parses a §18.2 invitation URI: lfcp://join/<resource>, one or more
+ * `endpoint` parameters and exactly one `grant` (see parseLink).
  * Endpoints are percent-decoded and must use ws or wss (§16). Throws
  * INVALID_INVITATION, never with the URI or the secret in the message.
  * Verify a bearer secret against the grant (verifyInvitationSecret) before
- * using it.
+ * using it. A pairing link (lfcp://pair/) is not an invitation.
  */
 export declare function parseInviteUri(uri: string): Invitation;
+/**
+ * A pairing link (IDENTITY-PROFILE-01 §5.2): the keys of a pairing device
+ * `J` (kind 2) registered in the Identity Resource. The secret reuses the
+ * §18.2 invite-secret codec; `J` is not an Invitation Principal (no grant,
+ * no claim). The link always carries the secret: treat it like a key.
+ */
+export interface PairingLink {
+    /** The Identity Resource `I`. */
+    readonly identityResourceId: ResourceId;
+    /** One or more endpoint URLs, in URI order. */
+    readonly endpoints: readonly string[];
+    /** `J`'s Principal ID. */
+    readonly pairingDevice: PrincipalId;
+    readonly secret: InvitationSecret;
+}
+/**
+ * The canonical pairing link: lfcp://pair/<I>?endpoint=…[&endpoint=…]&device=<J>#secret=<secret>.
+ * `pairingDevice` must be the Principal the secret determines.
+ */
+export declare function assemblePairingUri(link: PairingLink): string;
+/**
+ * Parses a pairing link (IDENTITY-PROFILE-01 §5.2) with the §18.2 rules
+ * (percent-encoding, several `endpoint` parameters, unknown parameters
+ * ignored) and exactly one `device`. The `#secret=` fragment is required,
+ * and the Principal recomputed from it must be `device`: a receiver MUST
+ * check that before using the secret. An lfcp://join/ link is rejected.
+ * Throws INVALID_INVITATION, never with the URI or the secret in the
+ * message. Opening `I` as `J` and checking that `J` is a registered,
+ * active kind-2 device of `I`'s owner is the client's next step.
+ */
+export declare function parsePairingUri(uri: string): PairingLink;
+/** The pairing device as a signer, recomputed from the link's secret (IDENTITY-PROFILE-01 §5.2). */
+export declare function pairingDeviceSigner(link: PairingLink): Signer;
+/**
+ * The device fingerprint shown during pairing (IDENTITY-PROFILE-01 §5.2):
+ * base32-lower-nopad(SHA-256("LFCP-DEVICE-FP-v1" || principal_id)[0..10]),
+ * as four groups of four characters joined by "-". A display convention,
+ * not a wire object.
+ */
+export declare function deviceFingerprint(device: PrincipalId): string;
 //# sourceMappingURL=invite.d.ts.map