@typecad/framework-zephyr 1.0.0-alpha.18 → 1.0.0-alpha.19

package/dist/audit.d.ts

@@ -0,0 +1,111 @@
+import type { ReadFile } from '@typecad/cuttlefish/api/shared';
+export type KconfigValue = string | number | boolean;
+/** Parse a merged Kconfig file: `CONFIG_X=y` (true), `# CONFIG_X is not set`
+ *  (explicit false), `CONFIG_X=123` / `CONFIG_X="s"` (value). Comment blocks
+ *  and everything else are ignored. Absent symbols are simply not in the map
+ *  (Kconfig default applies — treat as "not enabled" for y/n symbols). */
+export declare function parseMergedConfig(text: string): Map<string, KconfigValue>;
+/** Sweep a resolved devicetree for every `compatible` string — the enabled
+ *  hardware the firmware actually wired (attack-surface inventory input).
+ *  Multi-string compatibles ("a,b", "a,b-fallback") contribute EVERY entry
+ *  (the fallback binds the same node); nodes marked status = "disabled"
+ *  contribute nothing. Node scoping is a brace-depth walk: every block is a
+ *  node, and only its OWN properties (nested child blocks stripped) decide
+ *  its status/compatibles. */
+export declare function sweepCompatibles(dtsText: string): string[];
+export interface SecurityFacts {
+    config: Map<string, KconfigValue>;
+    compatibles: string[];
+}
+export type AuditSeverity = 'high' | 'medium' | 'low';
+export interface AuditFinding {
+    rule: string;
+    title: string;
+    severity: AuditSeverity;
+    requirement: string;
+    remediation: string;
+    /** The as-built evidence line(s) that triggered the rule. */
+    evidence: string;
+}
+export interface AuditRule {
+    id: string;
+    title: string;
+    severity: AuditSeverity;
+    /** CRA essential-requirement paraphrase this rule maps to. */
+    requirement: string;
+    remediation: string;
+    /** Returns the evidence string when the rule fires, else null. */
+    evaluate: (facts: SecurityFacts) => string | null;
+}
+/**
+ * The Zephyr security baseline. Rules read ONLY config/devicetree facts —
+ * never a board name or SoC family (all-boards-are-equal). Every rule must
+ * be waivable with a recorded justification: real products have real
+ * exceptions, and a conformity assessor wants to see them documented, not
+ * hidden.
+ */
+export declare const SECURITY_RULES: readonly AuditRule[];
+/** Evaluate the baseline over the facts. Order follows rule severity. */
+export declare function evaluateSecurityRules(facts: SecurityFacts): AuditFinding[];
+export interface AuditWaiver {
+    rule: string;
+    justification: string;
+    date?: string;
+}
+export declare function parseWaiverFile(text: string | undefined): {
+    waivers: AuditWaiver[];
+    error?: string;
+};
+/** Find .typecad-hal/audit-waivers.json, walking up from `cwd` (bounded). */
+export declare function findWaiverFile(readFile: ReadFile, cwd: string): string | undefined;
+export interface AuditRunner {
+    cwd?: string;
+    /** The last build's compile_commands.json path, or undefined. */
+    compileCommandsPath?: () => string | undefined;
+    readFile: ReadFile;
+}
+export interface AuditReport {
+    schema: 'typecad-hal/security-audit@1';
+    generated: string;
+    buildDir: string;
+    summary: {
+        console: 'uart' | 'usb' | 'rtt' | 'none';
+        shell: boolean;
+        network: boolean;
+        bluetooth: boolean;
+        usbDevice: boolean;
+        entropy: boolean;
+        watchdog: boolean;
+        hardware: string[];
+    };
+    findings: AuditFinding[];
+    deviations: (AuditFinding & {
+        justification: string;
+        date?: string;
+    })[];
+    rulesEvaluated: number;
+    waiverFile?: string;
+}
+export declare function buildAuditReport(args: {
+    buildDir: string;
+    facts: SecurityFacts;
+    findings: AuditFinding[];
+    deviations: (AuditFinding & {
+        justification: string;
+        date?: string;
+    })[];
+    generated?: string;
+    waiverFile?: string;
+}): AuditReport;
+/** Options accepted by `runAuditPresenter` (structurally compatible with the
+ *  parsed `typecad-hal audit` CLI options). */
+export interface AuditPresenterOptions {
+    /** Exit 1 on any unwaived high/medium finding. */
+    strict?: boolean;
+    /** Print only the JSON report (clean CI pipe); the sidecar is still written. */
+    json?: boolean;
+}
+/** @internal Test-only override of the default runner. */
+export declare function __setAuditRunnerForTest(runner: AuditRunner | undefined): void;
+/** `typecad-hal audit` presenter. */
+export declare function runAuditPresenter(options: AuditPresenterOptions): void;

package/dist/audit.js

@@ -0,0 +1,416 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — security baseline audit
+//
+// `typecad-hal audit` — evaluate the last build's MERGED Kconfig
+// (<buildDir>/zephyr/.config, the as-built truth nothing else reads) against
+// a curated Zephyr security baseline, in the spirit of the EU Cyber
+// Resilience Act's essential requirements (secure by default, attack surface
+// minimised, no hard-coded credentials, functioning crypto underpinnings).
+//
+// Architecture mirrors the AUTOSAR compliance module and the sbom command:
+// rules are DATA evaluated over facts, never board-name branches; justified
+// exceptions are DEVIATIONS recorded in a committed waiver file
+// (.typecad-hal/audit-waivers.json) rather than suppressed findings; the
+// presenter never calls process.exit() and sets process.exitCode under
+// --strict only for unwaived high/medium findings. A machine-readable
+// sidecar (<buildDir>/security-audit.json) is written on every run — the
+// input the CRA technical file and the future VEX/audit feed consume.
+// ---------------------------------------------------------------------------
+import { readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+import * as ui from '@typecad/cuttlefish/utils/ui';
+import { loadTypecadConfig } from '@typecad/cuttlefish/config-loader';
+import { findCompileCommandsPath } from './west-inventory.js';
+/** Parse a merged Kconfig file: `CONFIG_X=y` (true), `# CONFIG_X is not set`
+ *  (explicit false), `CONFIG_X=123` / `CONFIG_X="s"` (value). Comment blocks
+ *  and everything else are ignored. Absent symbols are simply not in the map
+ *  (Kconfig default applies — treat as "not enabled" for y/n symbols). */
+export function parseMergedConfig(text) {
+    const out = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const notSet = line.match(/^#\s*CONFIG_([A-Z0-9_]+) is not set$/);
+        if (notSet) {
+            out.set(`CONFIG_${notSet[1]}`, false);
+            continue;
+        }
+        const set = line.match(/^CONFIG_([A-Z0-9_]+)=(.*)$/);
+        if (set) {
+            const raw = set[2].trim();
+            if (raw === 'y')
+                out.set(`CONFIG_${set[1]}`, true);
+            else if (raw === 'n')
+                out.set(`CONFIG_${set[1]}`, false);
+            else if (/^-?\d+$/.test(raw))
+                out.set(`CONFIG_${set[1]}`, Number(raw));
+            else if (/^".*"$/s.test(raw))
+                out.set(`CONFIG_${set[1]}`, raw.slice(1, -1));
+            else
+                out.set(`CONFIG_${set[1]}`, raw);
+        }
+    }
+    return out;
+}
+/** Sweep a resolved devicetree for every `compatible` string — the enabled
+ *  hardware the firmware actually wired (attack-surface inventory input).
+ *  Multi-string compatibles ("a,b", "a,b-fallback") contribute EVERY entry
+ *  (the fallback binds the same node); nodes marked status = "disabled"
+ *  contribute nothing. Node scoping is a brace-depth walk: every block is a
+ *  node, and only its OWN properties (nested child blocks stripped) decide
+ *  its status/compatibles. */
+export function sweepCompatibles(dtsText) {
+    const found = new Set();
+    // The block's own properties: the text with nested child blocks removed.
+    const ownProps = (body) => {
+        let out = '';
+        let depth = 0;
+        for (const ch of body) {
+            if (ch === '{') {
+                depth++;
+                continue;
+            }
+            if (ch === '}') {
+                depth--;
+                continue;
+            }
+            if (depth === 0)
+                out += ch;
+        }
+        return out;
+    };
+    // Visit EVERY node block (advancing past '{' only, so nested nodes are
+    // found by later iterations too).
+    let i = 0;
+    while (i < dtsText.length) {
+        const open = dtsText.indexOf('{', i);
+        if (open < 0)
+            break;
+        let depth = 1;
+        let j = open + 1;
+        while (j < dtsText.length && depth > 0) {
+            const c = dtsText[j];
+            if (c === '{')
+                depth++;
+            else if (c === '}')
+                depth--;
+            j++;
+        }
+        const props = ownProps(dtsText.slice(open + 1, Math.min(j, dtsText.length) - (depth === 0 ? 1 : 0)));
+        if (!/status\s*=\s*"disabled"/.test(props)) {
+            for (const m of props.matchAll(/compatible\s*=\s*((?:"[^"]*"\s*,?\s*)+)/g)) {
+                for (const s of m[1].matchAll(/"([^"]+)"/g))
+                    found.add(s[1]);
+            }
+        }
+        i = open + 1;
+    }
+    return [...found].sort();
+}
+const on = (f, name) => f.config.get(name) === true;
+const anyOn = (f, ...names) => names.some((n) => on(f, n));
+/**
+ * The Zephyr security baseline. Rules read ONLY config/devicetree facts —
+ * never a board name or SoC family (all-boards-are-equal). Every rule must
+ * be waivable with a recorded justification: real products have real
+ * exceptions, and a conformity assessor wants to see them documented, not
+ * hidden.
+ */
+export const SECURITY_RULES = [
+    {
+        id: 'zephyr.gdbstub',
+        title: 'remote debug stub compiled into the image',
+        severity: 'high',
+        requirement: 'Annex I 1.2(a) — attack surface minimised; no remotely exploitable debug interfaces',
+        remediation: 'disable CONFIG_GDBSTUB for production builds (gate it behind a debug build type)',
+        evaluate: (f) => (on(f, 'CONFIG_GDBSTUB') ? 'CONFIG_GDBSTUB=y' : null),
+    },
+    {
+        id: 'zephyr.bt-fixed-passkey',
+        title: 'static Bluetooth pairing passkey (hard-coded credential)',
+        severity: 'high',
+        requirement: 'Annex I 1.2(f) — no hard-coded credentials; unique per-device secrets',
+        remediation: 'remove CONFIG_BT_FIXED_PASSKEY and use per-device pairing (just-in-time/numeric comparison)',
+        evaluate: (f) => {
+            const v = f.config.get('CONFIG_BT_FIXED_PASSKEY');
+            return typeof v === 'number' ? `CONFIG_BT_FIXED_PASSKEY=${v}` : null;
+        },
+    },
+    {
+        id: 'zephyr.entropy-missing',
+        title: 'crypto/networking enabled without a hardware entropy source',
+        severity: 'high',
+        requirement: 'Annex I 1.2(c) — cryptographic primitives backed by proper randomness',
+        remediation: 'enable CONFIG_ENTROPY_GENERATOR (the board SoC entropy driver) — keys and nonces '
+            + 'derived without it are predictable',
+        evaluate: (f) => {
+            if (on(f, 'CONFIG_ENTROPY_GENERATOR'))
+                return null;
+            const consumers = ['CONFIG_BT', 'CONFIG_NETWORKING', 'CONFIG_MBEDTLS', 'CONFIG_TINYCRYPT'].filter((n) => on(f, n));
+            if (consumers.length === 0)
+                return null;
+            return '# CONFIG_ENTROPY_GENERATOR is not set (while '
+                + consumers.map((c) => `${c}=y`).join(', ')
+                + ')';
+        },
+    },
+    {
+        id: 'zephyr.shell-enabled',
+        title: 'interactive shell compiled in',
+        severity: 'high',
+        requirement: 'Annex I 1.2(a) — attack surface minimised; no unnecessary interactive interfaces',
+        remediation: 'disable CONFIG_SHELL for production builds, or restrict it to a debug build type',
+        evaluate: (f) => (on(f, 'CONFIG_SHELL') ? 'CONFIG_SHELL=y' : null),
+    },
+    {
+        id: 'zephyr.network-no-tls',
+        title: 'network stack enabled without a TLS library',
+        severity: 'medium',
+        requirement: 'Annex I 1.2(c)/(e) — confidential communication over networks',
+        remediation: 'enable CONFIG_MBEDTLS (mbedTLS SSL) for networked firmware, or document why the '
+            + 'traffic may stay in cleartext',
+        evaluate: (f) => on(f, 'CONFIG_NETWORKING') && !on(f, 'CONFIG_MBEDTLS')
+            ? 'CONFIG_NETWORKING=y, # CONFIG_MBEDTLS is not set'
+            : null,
+    },
+    {
+        id: 'zephyr.watchdog-absent',
+        title: 'no watchdog configured',
+        severity: 'medium',
+        requirement: 'Annex I 1.3(b) — resilience and availability of essential functions',
+        remediation: 'enable CONFIG_WATCHDOG and feed it from the app (hal: `new Watchdog(...)` on a '
+            + 'watchdog-capable board) so hangs recover instead of bricking the product',
+        evaluate: (f) => (on(f, 'CONFIG_WATCHDOG') ? null : '# CONFIG_WATCHDOG is not set'),
+    },
+    {
+        id: 'zephyr.console-enabled',
+        title: 'diagnostic console enabled',
+        severity: 'low',
+        requirement: 'Annex I 1.2(a) — attack surface minimised (informational: consoles are often '
+            + 'intentional in the field)',
+        remediation: 'if the console is not needed in production, disable it (CONFIG_UART_CONSOLE / '
+            + 'CONFIG_USB_CONSOLE / CONFIG_RTT_CONSOLE)',
+        evaluate: (f) => {
+            const which = ['CONFIG_UART_CONSOLE', 'CONFIG_USB_CONSOLE', 'CONFIG_RTT_CONSOLE'].filter((n) => on(f, n));
+            return which.length > 0 ? which.join(', ') + ' enabled' : null;
+        },
+    },
+    {
+        id: 'zephyr.hardening-off',
+        title: 'compiler hardening stack not enabled',
+        severity: 'low',
+        requirement: 'Annex I 1.2(b) — reduce exploitability of residual vulnerabilities',
+        remediation: 'enable CONFIG_HARDENING (stack canaries and friends) unless the overhead is '
+            + 'measured to matter',
+        evaluate: (f) => (on(f, 'CONFIG_HARDENING') ? null : 'CONFIG_HARDENING not enabled'),
+    },
+];
+/** Evaluate the baseline over the facts. Order follows rule severity. */
+export function evaluateSecurityRules(facts) {
+    const order = { high: 0, medium: 1, low: 2 };
+    const findings = [];
+    for (const rule of SECURITY_RULES) {
+        const evidence = rule.evaluate(facts);
+        if (evidence !== null) {
+            findings.push({
+                rule: rule.id,
+                title: rule.title,
+                severity: rule.severity,
+                requirement: rule.requirement,
+                remediation: rule.remediation,
+                evidence,
+            });
+        }
+    }
+    findings.sort((a, b) => order[a.severity] - order[b.severity]);
+    return findings;
+}
+export function parseWaiverFile(text) {
+    if (!text)
+        return { waivers: [] };
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || !Array.isArray(parsed.waivers)) {
+            return { waivers: [], error: 'waiver file must be `{ "waivers": [...] }` — ignored' };
+        }
+        const waivers = [];
+        for (const w of parsed.waivers) {
+            if (w &&
+                typeof w === 'object' &&
+                typeof w.rule === 'string' &&
+                typeof w.justification === 'string') {
+                const entry = w;
+                if (entry.justification.trim().length === 0) {
+                    return { waivers: [], error: `waiver for ${entry.rule} has an empty justification — ignored` };
+                }
+                waivers.push(entry);
+            }
+        }
+        return { waivers };
+    }
+    catch {
+        return { waivers: [], error: 'waiver file is not valid JSON — ignored' };
+    }
+}
+/** Find .typecad-hal/audit-waivers.json, walking up from `cwd` (bounded). */
+export function findWaiverFile(readFile, cwd) {
+    let dir = path.resolve(cwd);
+    for (let i = 0; i < 5; i++) {
+        const p = path.join(dir, '.typecad-hal', 'audit-waivers.json');
+        if (readFile(p))
+            return p;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+function defaultAuditRunner(cwd = process.cwd()) {
+    const readFile = (p) => {
+        try {
+            return readFileSync(p, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const readdir = (d) => {
+        try {
+            return readdirSync(d);
+        }
+        catch {
+            return [];
+        }
+    };
+    return {
+        cwd,
+        compileCommandsPath: () => findCompileCommandsPath(readFile, readdir, cwd),
+        readFile,
+    };
+}
+export function buildAuditReport(args) {
+    const f = args.facts;
+    const consoleType = on(f, 'CONFIG_UART_CONSOLE')
+        ? 'uart'
+        : on(f, 'CONFIG_USB_CONSOLE')
+            ? 'usb'
+            : on(f, 'CONFIG_RTT_CONSOLE')
+                ? 'rtt'
+                : 'none';
+    return {
+        schema: 'typecad-hal/security-audit@1',
+        generated: args.generated ?? new Date().toISOString(),
+        buildDir: args.buildDir,
+        summary: {
+            console: consoleType,
+            shell: on(f, 'CONFIG_SHELL'),
+            network: on(f, 'CONFIG_NETWORKING'),
+            bluetooth: on(f, 'CONFIG_BT'),
+            usbDevice: anyOn(f, 'CONFIG_USB_DEVICE_STACK', 'CONFIG_USB_DEVICE_DRIVER'),
+            entropy: on(f, 'CONFIG_ENTROPY_GENERATOR'),
+            watchdog: on(f, 'CONFIG_WATCHDOG'),
+            hardware: f.compatibles,
+        },
+        findings: args.findings,
+        deviations: args.deviations,
+        rulesEvaluated: SECURITY_RULES.length,
+        waiverFile: args.waiverFile,
+    };
+}
+let testRunner;
+/** @internal Test-only override of the default runner. */
+export function __setAuditRunnerForTest(runner) {
+    testRunner = runner;
+}
+function printFinding(f, waived) {
+    // ui.printWarning already stamps its own "! " marker.
+    ui.printWarning(`${waived ? 'waived ' : ''}[${f.severity}] ${f.rule} — ${f.title}`);
+    ui.printInfo(`    requirement: ${f.requirement}`);
+    ui.printInfo(`    evidence:    ${f.evidence}`);
+    ui.printInfo(`    fix:         ${f.remediation}`);
+    if (waived)
+        ui.printInfo(`    waived:      ${waived}`);
+}
+/** `typecad-hal audit` presenter. */
+export function runAuditPresenter(options) {
+    const runner = testRunner ?? defaultAuditRunner();
+    const cwd = runner.cwd ?? process.cwd();
+    const ccPath = runner.compileCommandsPath ? runner.compileCommandsPath() : undefined;
+    const buildDir = ccPath ? path.dirname(ccPath) : undefined;
+    const configText = buildDir ? runner.readFile(path.join(buildDir, 'zephyr', '.config')) : undefined;
+    if (!buildDir || configText === undefined) {
+        ui.printError('No build found — audit reads the merged zephyr/.config of the last build. Run typecad-hal build first.');
+        process.exitCode = 1;
+        return;
+    }
+    const dtsText = runner.readFile(path.join(buildDir, 'zephyr', 'zephyr.dts'));
+    const facts = {
+        config: parseMergedConfig(configText),
+        compatibles: dtsText ? sweepCompatibles(dtsText) : [],
+    };
+    const all = evaluateSecurityRules(facts);
+    const waiverPath = findWaiverFile(runner.readFile, cwd);
+    const { waivers, error: waiverError } = parseWaiverFile(waiverPath ? runner.readFile(waiverPath) : undefined);
+    const waivedByRule = new Map(waivers.map((w) => [w.rule, w]));
+    const findings = all.filter((f) => !waivedByRule.has(f.rule));
+    const deviations = all
+        .filter((f) => waivedByRule.has(f.rule))
+        .map((f) => ({ ...f, ...waivedByRule.get(f.rule) }));
+    const report = buildAuditReport({ buildDir, facts, findings, deviations, waiverFile: waiverPath });
+    // Sidecar first (best-effort, never fatal), then the human/JSON surface.
+    try {
+        mkdirSync(buildDir, { recursive: true });
+        writeFileSync(path.join(buildDir, 'security-audit.json'), JSON.stringify(report, null, 2) + '\n');
+    }
+    catch {
+        /* best-effort sidecar */
+    }
+    // --strict: unwaived high/medium findings fail. Waived findings are
+    // recorded deviations, not failures.
+    const failing = findings.filter((f) => f.severity === 'high' || f.severity === 'medium');
+    if (options.strict && failing.length > 0) {
+        process.exitCode = 1;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    ui.printHeader();
+    ui.printStep('Auditing the merged build configuration (security baseline)');
+    let boardTarget;
+    try {
+        boardTarget = loadTypecadConfig(process.cwd())?.buildTarget;
+    }
+    catch {
+        /* best-effort */
+    }
+    if (boardTarget)
+        ui.printInfo(`board ............. ${boardTarget}`);
+    const s = report.summary;
+    ui.printInfo(`surface ........... console ${s.console} · shell ${s.shell ? 'ON' : 'off'} · net ${s.network ? 'ON' : 'off'} · ` +
+        `BLE ${s.bluetooth ? 'ON' : 'off'} · USB device ${s.usbDevice ? 'ON' : 'off'}`);
+    ui.printInfo(`underpinnings ..... entropy ${s.entropy ? 'ok' : 'OFF'} · watchdog ${s.watchdog ? 'ok' : 'OFF'} · ` +
+        `${s.hardware.length} wired compatible(s)`);
+    if (waiverError)
+        ui.printWarning(`waiver file: ${waiverError}`);
+    for (const f of findings)
+        printFinding(f);
+    for (const d of deviations) {
+        printFinding(d, `${d.justification}${d.date ? ` (${d.date})` : ''}`);
+    }
+    if (all.length === 0) {
+        ui.printSuccess(`baseline clean — ${report.rulesEvaluated} rules evaluated, 0 findings.`);
+    }
+    else {
+        ui.printWarning(`${findings.length} finding(s) (${failing.length} unwaived high/medium), ` +
+            `${deviations.length} waived deviation(s).`);
+    }
+    if (waiverPath) {
+        ui.printInfo(`waivers .......... ${waiverPath}`);
+    }
+    ui.printInfo(`sidecar .......... ${path.join(buildDir, 'security-audit.json')}`);
+    if (options.strict) {
+        ui.printInfo(failing.length > 0
+            ? '--strict .......... FAIL (unwaived high/medium findings above)'
+            : '--strict .......... pass');
+    }
+}

package/dist/boardgen.js

@@ -947,21 +947,43 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
     if (wdtNodeLabel)
         ts.push(`export { Watchdog } from '@typecad/hal/core';`);
     if (siliconPwm.length > 0 || pwmLedSpecs.length > 0 || pwmMatrix)
-        ts.push(`export { PWM } from '@typecad/hal/core';`);
+        ts.push(`export { PWM, Servo } from '@typecad/hal/core';`);
     if (siliconAdc.length > 0)
         ts.push(`export { ADC } from '@typecad/hal/core';`);
     if (siliconDac.length > 0)
         ts.push(`export { DAC } from '@typecad/hal/core';`);
+    // The responder rides the same wired-bus fact as I2CTarget — target-mode
+    // support is a controller-driver property discovered at registration
+    // (-ENOSYS prints loudly), never a board-name gate.
     if (buses.i2c.length > 0)
-        ts.push(`export { I2CTarget } from '@typecad/hal/core';`);
+        ts.push(`export { I2CTarget, I2CResponder } from '@typecad/hal/core';`);
     if (buses.spi.length > 0)
         ts.push(`export { SPITarget } from '@typecad/hal/core';`);
     if (buses.uart.length > 0)
         ts.push(`export { UART } from '@typecad/hal/core';`);
     if (hwtimerControllers.length > 0)
         ts.push(`export { Counter } from '@typecad/hal/core';`);
+    // Clock rides the same free-counter facts (the zephyr,rtc-counter shim
+    // wraps the counter when the board ships no hardware rtc alias).
+    if (hwtimerControllers.length > 0)
+        ts.push(`export { Clock } from '@typecad/hal/core';`);
+    // CAN rides the harvested controller nodes (ESP32 TWAI, STM32 bxCAN,
+    // NXP FlexCAN…); a SoC with none exports nothing.
+    if ((entry.canNodes ?? []).length > 0)
+        ts.push(`export { CAN } from '@typecad/hal/core';`);
+    // I2S rides the harvested i2s@ controllers.
+    if ((entry.i2sNodes ?? []).length > 0)
+        ts.push(`export { I2S } from '@typecad/hal/core';`);
+    // Power rides the SoC's declared cpu-power-states (both the ESP32 family's
+    // standby + soft-off pair and STM32's suspend-to-idle count; a SoC with no
+    // declared states exports nothing).
+    if ((entry.powerStates ?? []).length > 0)
+        ts.push(`export { Power } from '@typecad/hal/core';`);
+    // KEY/MOUSE are ungated token tables — the derived always-available
+    // re-export line above already carries them on every board; only the HID
+    // device classes ride the USB gate.
     if (hasUsb)
-        ts.push(`export { USBConsole } from '@typecad/hal/core';`);
+        ts.push(`export { USBConsole, Keyboard, Mouse } from '@typecad/hal/core';`);
     // Store/File: a persisted backend needs a storage region — either the
     // board's own storage_partition (harvested reg) or a synthesizable one
     // (flash size known, no existing partition to collide with).
@@ -1077,12 +1099,15 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         // GPIO driver API (`gpio_pin_configure` flags + `gpio_pin_interrupt_configure`):
         // every GPIO controller implements them, so they are universally true —
         // a platform fact, not a per-pad one. Analog/PWM ride the harvested
-        // silicon routes (honest per-pad facts).
+        // silicon routes (honest per-pad facts); PWM counts both route kinds —
+        // fixed pinctrl routes AND any-pad matrices (ESP32 LEDC, nRF psel), the
+        // same set union the pin JSDoc and the PWM export gate read, so the
+        // hover annotation and the capability flag cannot disagree.
         constants[`pins.all.${i}.capabilities.digitalInput`] = true;
         constants[`pins.all.${i}.capabilities.digitalOutput`] = true;
         constants[`pins.all.${i}.capabilities.analogInput`] = siliconAdcPins.has(p.halPin);
         constants[`pins.all.${i}.capabilities.analogOutput`] = siliconDacPins.has(p.halPin);
-        constants[`pins.all.${i}.capabilities.pwm`] = siliconPwmPins.has(p.halPin);
+        constants[`pins.all.${i}.capabilities.pwm`] = siliconPwmPins.has(p.halPin) || (matrixPwmPins?.has(p.halPin) ?? false);
         constants[`pins.all.${i}.capabilities.interrupt`] = true;
         constants[`pins.all.${i}.capabilities.pullUp`] = true;
         constants[`pins.all.${i}.capabilities.pullDown`] = true;
@@ -1091,6 +1116,39 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         constants[`pins.all.${i}.capabilities.touch`] = false;
         constants[`pins.all.${i}.capabilities.openDrain`] = true;
     });
+    // CPU power states — the harvested PM capability facts (which levels
+    // exist, their idle timing, and whether the automatic policy may enter
+    // them; ESP32's soft-off is explicit-entry only).
+    const powerStates = entry.powerStates ?? [];
+    powerStates.forEach((ps, i) => {
+        constants[`zephyr.power.states.${i}.name`] = ps.name;
+        if (ps.minResidencyUs !== undefined)
+            constants[`zephyr.power.states.${i}.minResidencyUs`] = ps.minResidencyUs;
+        if (ps.exitLatencyUs !== undefined)
+            constants[`zephyr.power.states.${i}.exitLatencyUs`] = ps.exitLatencyUs;
+        constants[`zephyr.power.states.${i}.enabled`] = ps.enabled;
+    });
+    if (powerStates.length > 0) {
+        constants['zephyr.power.softOff'] = powerStates.some((ps) => ps.name === 'soft-off');
+    }
+    if (entry.rtcWakeTimer)
+        constants['zephyr.power.wakeTimer'] = true;
+    // CAN controllers — the harvested labeled nodes (the CAN class gate). The
+    // ESP32 TWAI pads ride along: loopback overlays route both TWAI functions
+    // onto the TX pad.
+    (entry.canNodes ?? []).forEach((c, i) => {
+        constants[`zephyr.can.controllers.${i}.nodeLabel`] = c.nodeLabel;
+        constants[`zephyr.can.controllers.${i}.compatible`] = c.compatible;
+        if (c.txPad !== undefined)
+            constants[`zephyr.can.controllers.${i}.txPad`] = c.txPad;
+        if (c.rxPad !== undefined)
+            constants[`zephyr.can.controllers.${i}.rxPad`] = c.rxPad;
+    });
+    // I2S controllers — the harvested labeled nodes (the I2S class gate).
+    (entry.i2sNodes ?? []).forEach((c, i) => {
+        constants[`zephyr.i2s.controllers.${i}.nodeLabel`] = c.nodeLabel;
+        constants[`zephyr.i2s.controllers.${i}.compatible`] = c.compatible;
+    });
     constants['peripherals.i2c.count'] = buses.i2c.length;
     constants['peripherals.spi.count'] = buses.spi.length;
     constants['peripherals.uart.count'] = buses.uart.length;

package/dist/chips/resolve.js

@@ -196,6 +196,23 @@ export function resolveChipFromBoard(bc) {
     // (+ optional vid/pid for the device descriptor).
     const usbController = bc.get('zephyr.usb.controller');
     const usbCdcInstances = bc.get('zephyr.usb.cdcInstances');
+    const wakeTimer = bc.get('zephyr.power.wakeTimer');
+    const i2sControllers = [];
+    for (let ii = 0; bc.get(`zephyr.i2s.controllers.${ii}.nodeLabel`) !== undefined; ii++) {
+        i2sControllers.push({
+            nodeLabel: String(bc.get(`zephyr.i2s.controllers.${ii}.nodeLabel`)),
+            compatible: String(bc.get(`zephyr.i2s.controllers.${ii}.compatible`)),
+        });
+    }
+    const canControllers = [];
+    for (let ci = 0; bc.get(`zephyr.can.controllers.${ci}.nodeLabel`) !== undefined; ci++) {
+        canControllers.push({
+            nodeLabel: String(bc.get(`zephyr.can.controllers.${ci}.nodeLabel`)),
+            compatible: String(bc.get(`zephyr.can.controllers.${ci}.compatible`)),
+            ...(bc.get(`zephyr.can.controllers.${ci}.txPad`) !== undefined ? { txPad: Number(bc.get(`zephyr.can.controllers.${ci}.txPad`)) } : {}),
+            ...(bc.get(`zephyr.can.controllers.${ci}.rxPad`) !== undefined ? { rxPad: Number(bc.get(`zephyr.can.controllers.${ci}.rxPad`)) } : {}),
+        });
+    }
     const usbVid = bc.get('zephyr.usb.vid');
     const usbPid = bc.get('zephyr.usb.pid');
     // Optional 1200-baud touch-to-reset data (BOSSA-bootloader boards).
@@ -327,6 +344,9 @@ export function resolveChipFromBoard(bc) {
         ...(storageOffset != null && storageSize != null
             ? { storage: { offset: storageOffset, size: storageSize, ...(storagePreexisting ? { preexisting: true } : {}) } }
             : {}),
+        ...(wakeTimer ? { powerWakeTimer: true } : {}),
+        ...(canControllers.length > 0 ? { can: { controllers: canControllers } } : {}),
+        ...(i2sControllers.length > 0 ? { i2s: { controllers: i2sControllers } } : {}),
         ...(usbController && usbCdcInstances && usbCdcInstances > 0
             ? {
                 usb: {