@openlfcp/wire 0.2.2 → 0.3.0

package/dist/device-scan.js

@@ -0,0 +1,268 @@
+import { LfcpError } from "@openlfcp/core";
+import { MAX_DEPTH } from "./cbor/index.js";
+/**
+ * Bounds of Device Certificates and certificate chains checked on the raw
+ * bytes, before any CBOR value is decoded or any byte string copied
+ * (LFCP-WIRE-01 §7.3: chain 1–4, mask 1–32, scope at most 64, fixed field
+ * sizes, a managing leaf at most three deep). The full decoders run only
+ * after this scan, so a declared count beyond a limit is refused without
+ * walking or allocating its elements.
+ *
+ * The COSE envelope (§10) and the descriptor's fixed fields are checked
+ * here too, and a Genesis's null prev is skipped, so no shape reaches the
+ * decoder unscanned. The scan refuses only what the full decoder refuses
+ * too (COSE_MALFORMED for the envelope, INVALID_STRUCTURE otherwise, both
+ * MALFORMED_MESSAGE on the wire, §62 class 1); it accepts nothing the
+ * decoder would not check again.
+ */
+const MAX_CHAIN = 4;
+const MAX_MANAGING = 3;
+const MAX_MASK = 32;
+const MAX_SCOPE = 64;
+const LABEL_LENGTH = 19; // "LFCP-DEVICE-CERT-v1"
+const DEVICE_MANAGE = 12;
+function fail(why) {
+    throw new LfcpError("INVALID_STRUCTURE", `invalid device certificate (scan): ${why}`);
+}
+/** One CBOR head at `pos`, not past `end`. Indefinite and reserved forms are refused. */
+function head(bytes, pos, end) {
+    if (pos >= end)
+        fail("truncated");
+    const b = bytes[pos];
+    const major = b >> 5;
+    const ai = b & 31;
+    if (ai < 24)
+        return { major, value: ai, next: pos + 1 };
+    if (ai > 27)
+        fail("indefinite or reserved length");
+    const n = 1 << (ai - 24);
+    if (pos + 1 + n > end)
+        fail("truncated");
+    let value = 0;
+    for (let i = 0; i < n; i++)
+        value = value * 256 + bytes[pos + 1 + i];
+    return {
+        major,
+        value: Number.isSafeInteger(value) ? value : Number.POSITIVE_INFINITY,
+        next: pos + 1 + n,
+    };
+}
+/** The end of the item at `pos`, without decoding it. */
+function skip(bytes, pos, end, depth = 0) {
+    if (depth > MAX_DEPTH)
+        fail("nested too deeply");
+    const h = head(bytes, pos, end);
+    switch (h.major) {
+        case 0:
+        case 1:
+            return h.next;
+        case 2:
+        case 3:
+            if (h.value > end - h.next)
+                fail("truncated");
+            return h.next + h.value;
+        case 4:
+        case 5: {
+            const items = h.major === 5 ? h.value * 2 : h.value;
+            // Every item takes at least one byte: a count beyond the input is refused at once.
+            if (items > end - h.next)
+                fail("truncated");
+            let p = h.next;
+            for (let i = 0; i < items; i++)
+                p = skip(bytes, p, end, depth + 1);
+            return p;
+        }
+        case 7:
+            // false, true and null (a Genesis's prev is null, §13.1); the
+            // decoder refuses every other simple value and float too (§5.2).
+            if (h.value >= 20 && h.value <= 22 && h.next === pos + 1)
+                return h.next;
+            return fail("a float or an unused simple value");
+        default:
+            return fail("a tag"); // LFCP uses none (§5.2 rule 6)
+    }
+}
+/** A byte string head at `pos`: its content range. */
+function bstr(bytes, pos, end, length) {
+    const h = head(bytes, pos, end);
+    if (h.major !== 2)
+        fail("a byte string was expected");
+    if (h.value > end - h.next)
+        fail("truncated");
+    if (length !== undefined && h.value !== length)
+        fail(`a ${length}-byte string was expected`);
+    return [h.next, h.next + h.value];
+}
+function arrayHead(bytes, pos, end, what) {
+    const h = head(bytes, pos, end);
+    if (h.major !== 4)
+        fail(`${what} is not an array`);
+    return h;
+}
+/** The certificate payload array; returns whether its mask lists device/manage. */
+function scanPayload(bytes, start, end) {
+    const a = arrayHead(bytes, start, end, "the payload");
+    if (a.value !== 7)
+        fail("the payload has not seven elements");
+    let p = a.next;
+    const label = head(bytes, p, end);
+    if (label.major !== 3 || label.value !== LABEL_LENGTH)
+        fail("the label is not LFCP-DEVICE-CERT-v1");
+    p = skip(bytes, p, end);
+    p = bstr(bytes, p, end, 32)[1]; // root
+    p = scanDescriptor(bytes, p, end);
+    const kind = head(bytes, p, end);
+    if (kind.major !== 0 || kind.value > 2)
+        fail("the kind is not 0, 1 or 2");
+    p = kind.next;
+    const mask = arrayHead(bytes, p, end, "the mask");
+    if (mask.value < 1 || mask.value > MAX_MASK)
+        fail(`the mask holds 1 to ${MAX_MASK} codes`);
+    p = mask.next;
+    let managing = false;
+    for (let i = 0; i < mask.value; i++) {
+        const code = head(bytes, p, end);
+        if (code.major !== 0)
+            fail("a mask code is not an unsigned integer");
+        if (code.value === DEVICE_MANAGE)
+            managing = true;
+        p = code.next;
+    }
+    const scope = arrayHead(bytes, p, end, "the scope");
+    if (scope.value > MAX_SCOPE)
+        fail(`the scope holds at most ${MAX_SCOPE} Resources`);
+    p = scope.next;
+    for (let i = 0; i < scope.value; i++)
+        p = bstr(bytes, p, end, 32)[1];
+    p = bstr(bytes, p, end, 16)[1]; // serial
+    if (p !== end)
+        fail("bytes follow the payload");
+    return managing;
+}
+/** The device descriptor at `pos`: the closed map {0, 1, 2} of 32-byte strings (§7, §7.3 rule 2). */
+function scanDescriptor(bytes, pos, end) {
+    const m = head(bytes, pos, end);
+    if (m.major !== 5 || m.value !== 3)
+        fail("the descriptor is not a three-field map");
+    let p = m.next;
+    for (let key = 0; key < 3; key++) {
+        const k = head(bytes, p, end);
+        if (k.major !== 0 || k.value !== key)
+            fail("the descriptor's keys are not 0, 1 and 2");
+        p = bstr(bytes, k.next, end, 32)[1];
+    }
+    return p;
+}
+function malformed(why) {
+    throw new LfcpError("COSE_MALFORMED", `not a canonical LFCP COSE_Sign1 (scan): ${why}`);
+}
+/**
+ * The payload range of the COSE_Sign1 in `[start, end)`, its envelope
+ * checked as parseSignedObject does (§10): a protected header of exactly
+ * {1: -8, 4: 32-byte kid}, the empty unprotected map, a present payload
+ * and a 64-byte signature. Nothing is decoded or copied.
+ */
+function envelope(bytes, start, end) {
+    const a = head(bytes, start, end);
+    if (a.major !== 4 || a.value !== 4)
+        malformed("not a four-element array");
+    const [hs, he] = bstr(bytes, a.next, end);
+    const h = head(bytes, hs, he);
+    if (h.major !== 5 || h.value !== 2)
+        malformed("protected header must be exactly {1: -8, 4: kid}");
+    const alg = head(bytes, h.next, he);
+    const algValue = head(bytes, alg.next, he);
+    if (alg.major !== 0 || alg.value !== 1 || algValue.major !== 1 || algValue.value !== 7)
+        malformed("alg must be -8 (EdDSA)");
+    const kid = head(bytes, algValue.next, he);
+    if (kid.major !== 0 || kid.value !== 4)
+        malformed("protected header must be exactly {1: -8, 4: kid}");
+    const k = head(bytes, kid.next, he);
+    if (k.major !== 2 || k.value !== 32 || k.next + 32 !== he)
+        malformed("kid must be a 32-byte Principal ID");
+    const u = head(bytes, he, end);
+    if (u.major !== 5 || u.value !== 0)
+        malformed("unprotected header must be the empty map");
+    const payload = bstr(bytes, u.next, end);
+    const sig = head(bytes, payload[1], end);
+    if (sig.major !== 2 || sig.value !== 64)
+        malformed("signature must be 64 bytes");
+    if (sig.next + 64 !== end)
+        fail("bytes follow the signature");
+    return payload;
+}
+/** A Device Certificate's COSE_Sign1 in `[start, end)`; returns whether its mask lists 12. */
+function scanCertificateAt(bytes, start, end) {
+    const [ps, pe] = envelope(bytes, start, end);
+    return scanPayload(bytes, ps, pe);
+}
+/**
+ * Checks the envelope and the bounds of a standalone certificate on its
+ * exact bytes, before parseSignedObject decodes anything.
+ */
+export function scanDeviceCertificate(bytes) {
+    scanCertificateAt(bytes, 0, bytes.length);
+}
+/** A certificate-chain at `pos`: 1–4 certificates, a managing leaf at most three deep. */
+function scanChainAt(bytes, pos, end) {
+    const a = arrayHead(bytes, pos, end, "the certificate chain");
+    if (a.value < 1 || a.value > MAX_CHAIN)
+        fail(`a chain holds 1 to ${MAX_CHAIN} certificates`);
+    let p = a.next;
+    for (let i = 0; i < a.value; i++) {
+        const [cs, ce] = bstr(bytes, p, end);
+        const managing = scanCertificateAt(bytes, cs, ce);
+        if (i === 0 && managing && a.value > MAX_MANAGING)
+            fail(`a managing leaf has at most ${MAX_MANAGING} certificates`);
+        p = ce;
+    }
+    return p;
+}
+/**
+ * The value of unsigned key `key` in the map at `pos`, walking every
+ * entry without decoding it (the decoder checks order and duplicates).
+ */
+function field(bytes, pos, end, key) {
+    const m = head(bytes, pos, end);
+    if (m.major !== 5)
+        fail("a map was expected");
+    if (m.value * 2 > end - m.next)
+        fail("truncated");
+    let p = m.next;
+    let found;
+    for (let i = 0; i < m.value; i++) {
+        const k = head(bytes, p, end);
+        p = skip(bytes, p, end);
+        if (k.major === 0 && k.value === key)
+            found = p;
+        p = skip(bytes, p, end);
+    }
+    return found;
+}
+/** The body key that holds a certificate chain, by Control Record type (§15, §23.3, §17.4). */
+const CHAIN_KEY = { 0: 5, 6: 2, 9: 1 };
+/**
+ * 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 function scanControlRecord(bytes) {
+    const [ps, pe] = envelope(bytes, 0, bytes.length);
+    const typeAt = field(bytes, ps, pe, 3);
+    if (typeAt === undefined)
+        return;
+    const t = head(bytes, typeAt, pe);
+    const chainKey = t.major === 0 ? CHAIN_KEY[t.value] : undefined;
+    if (chainKey === undefined)
+        return;
+    const bodyAt = field(bytes, ps, pe, 5);
+    if (bodyAt === undefined)
+        return;
+    if (head(bytes, bodyAt, pe).major !== 5)
+        return; // the decoder names the wrong body type
+    const chainAt = field(bytes, bodyAt, pe, chainKey);
+    if (chainAt !== undefined)
+        scanChainAt(bytes, chainAt, pe);
+}
+//# sourceMappingURL=device-scan.js.map

package/dist/device-state.d.ts

@@ -0,0 +1,154 @@
+import { type ControlRecordId, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type Authorization } from "./capability.js";
+import type { ControlState } from "./chain.js";
+import type { ControlRecord } from "./control.js";
+import { type CertificateChain, type ChainStateChecks, type DeviceKind } from "./device.js";
+import { PersistentMap } from "./persistent-map.js";
+import type { PrincipalDescriptor } from "./principal.js";
+/**
+ * Resource-local device state and its transitions (LFCP-WIRE-01 §7.3,
+ * §17.4, §17.5, §79, §80.1). Every answer is a pure function of the
+ * Resource's accepted Control Chain (N3): no clock, no server table, no
+ * Identity Resource, no other Resource.
+ *
+ * A chain without device records has no bindings, so `bound` is false for
+ * every Principal and every question here reduces to §80.
+ */
+/** §79: a Principal's role in a Resource; assigned once, never changed. */
+export type DeviceRole = "device" | "non-device";
+/** §79 `Binding`: what an accepted chain fixed for a device in this Resource. */
+export interface DeviceBinding {
+    readonly root: PrincipalId;
+    readonly kind: DeviceKind;
+    /** The certificate's codes, unknown ones included; immutable, compared as a set (N8). */
+    readonly mask: readonly bigint[];
+    /** Immutable, compared as a set (N8). */
+    readonly scope: readonly ResourceId[];
+    /** Leaf of an accepted DEVICE_GRANT whose scope admits this Resource, of Genesis field 5 or of commit field 2. */
+    readonly registered: boolean;
+    /** The chain of the latest accepted record whose leaf this device is; null for an intermediate only. */
+    readonly chain: CertificateChain | null;
+    /** The certificate ID of that chain's leaf. */
+    readonly leafId: Hash32 | null;
+    /** Device IDs of `chain[1..]`, nearest first; empty when the root issued the leaf. */
+    readonly issuers: readonly PrincipalId[];
+    /** Accepted DEVICE_GRANT records whose leaf this device is (§17.4 rule 8: at most 8). */
+    readonly grantsAccepted: number;
+}
+/** §79 `Revocation` of an exact (root, device) pair; permanent (N5). */
+export interface DeviceRevocation {
+    readonly root: PrincipalId;
+    readonly device: PrincipalId;
+    /** As received; 4 and above are kept (§17.5). */
+    readonly reason: bigint;
+    /** The approved certificate payload digest, exactly for reason 3. */
+    readonly approval: Hash32 | null;
+    /** The DEVICE_REVOKE record. */
+    readonly revokedBy: ControlRecordId;
+}
+/** The device part of ControlState (§79). */
+export interface DeviceState {
+    /** Roles by Principal ID hex. */
+    readonly roles: ReadonlyMap<string, DeviceRole>;
+    /** Bindings by device ID hex: leaves, intermediates, suspended and revoked devices. */
+    readonly devices: ReadonlyMap<string, DeviceBinding>;
+    /** Revocations by `revocationKey(root, device)`. */
+    readonly revoked: ReadonlyMap<string, DeviceRevocation>;
+    /**
+     * §17.4 rule 8, by root ID hex: the live Principals bound to the root,
+     * entries of `devices` whose pair is not in `revoked`. Every binding path
+     * adds (Genesis, transfer, Device Grant); a direct revocation releases.
+     */
+    readonly liveBound: ReadonlyMap<string, number>;
+    /** §17.5 rule 5, by root ID hex: revoked pairs (R, E) with `devices[E]` absent. */
+    readonly preemptive: ReadonlyMap<string, number>;
+    /** By device ID hex: the roots (hex) that revoked it while it was unbound. */
+    readonly preemptiveRoots: ReadonlyMap<string, ReadonlyMap<string, true>>;
+}
+export declare const EMPTY_DEVICE_STATE: DeviceState;
+/** §17.4 rule 8: live Principals bound to one root in a Resource. */
+export declare const MAX_LIVE_BOUND = 32;
+/** §17.4 rule 8: accepted Device Grants per (root, leaf) pair. */
+export declare const MAX_DEVICE_GRANTS = 8;
+/** §17.5 rule 5: pre-emptive revocations of unbound Principals per root. */
+export declare const MAX_PREEMPTIVE_REVOCATIONS = 64;
+/** The key of `revoked` for the pair (root, device). */
+export declare const revocationKey: (root: PrincipalId, device: PrincipalId) => string;
+/** `bound(P)` (§80.1): P appeared as a device, at any level, in an accepted chain. */
+export declare const isBound: (state: ControlState, p: PrincipalId) => boolean;
+/** `revoked[(root, device)]`, if any. */
+export declare const revocationOf: (state: ControlState, root: PrincipalId, device: PrincipalId) => DeviceRevocation | undefined;
+/**
+ * `rootStanding(R)` (§17.5): R is the owner, or the subject of at least one
+ * active grant that does not list `invite/claim`.
+ */
+export declare function rootStanding(state: ControlState, root: PrincipalId): boolean;
+/**
+ * `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 declare function activeDevice(state: ControlState, p: PrincipalId): DeviceBinding | undefined;
+/** `actsFor(P)` (§80.1): the root of an active device, else P itself. */
+export declare const actsFor: (state: ControlState, p: PrincipalId) => PrincipalId;
+/**
+ * `rootOf(P)` (§80.1): the root of a bound P (registered, suspended,
+ * revoked or intermediate), else P itself. For attribution, never for
+ * authority.
+ */
+export declare const rootOf: (state: ControlState, p: PrincipalId) => PrincipalId;
+/**
+ * `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 declare function ownerAction(state: ControlState, p: PrincipalId): boolean;
+/**
+ * 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 declare function offerSigner(state: ControlState, kid: PrincipalId): PrincipalDescriptor | undefined;
+/** `sameRoot(a, b)` (§25.2): the same `actsFor`, and at least one of them an active device. */
+export declare const sameRoot: (state: ControlState, a: PrincipalId, b: PrincipalId) => boolean;
+/** §7.3 step 4.2–4.4 against `state`, for verifyChain. */
+export declare function deviceChainChecks(state: ControlState): ChainStateChecks;
+/**
+ * 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 declare function authorizeOwnerChain(state: ControlState, chain: CertificateChain): Authorization;
+type DeviceGrantBody = Extract<ControlRecord["body"], {
+    type: "DEVICE_GRANT";
+}>;
+type DeviceRevokeBody = Extract<ControlRecord["body"], {
+    type: "DEVICE_REVOKE";
+}>;
+/** §17.4 rules 4–7, in order (rules 1–3 are structure, dependencies and signatures). */
+export declare function authorizeDeviceGrant(state: ControlState, issuer: PrincipalId, body: DeviceGrantBody): Authorization;
+/** §17.5 rules 3–5, in order. */
+export declare function authorizeDeviceRevoke(state: ControlState, issuer: PrincipalId, body: DeviceRevokeBody): Authorization;
+/** The device part of a state, with the descriptors bindChain records. */
+type BindingState = DeviceState & Pick<ControlState, "principals">;
+/**
+ * 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 declare function bindChain(state: BindingState, chain: CertificateChain, inScope: boolean, keepSameLeaf: boolean, grant?: boolean): BindingState;
+/** The in-scope result of an accepted DEVICE_GRANT's chain at the state it was accepted on. */
+export declare const grantInScope: (state: ControlState, body: DeviceGrantBody) => boolean;
+/**
+ * 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 declare function recordRevocation(state: DeviceState, record: ControlRecord, body: DeviceRevokeBody): Pick<DeviceState, "revoked" | "liveBound" | "preemptive" | "preemptiveRoots">;
+/** Assigns the `non-device` role (§79). */
+export declare function nonDevice(roles: ReadonlyMap<string, DeviceRole>, p: PrincipalId): PersistentMap<DeviceRole>;
+export {};
+//# sourceMappingURL=device-state.d.ts.map