@atlasauth/pca-doctor 0.0.0-stage → 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @atlasauth/pca-doctor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Checks the assumptions a Proof-Carrying Authority deployment depends on, against the live deployment, and prints pass /
+warn / fail with a remediation for each check. The protocol can be correct while the deployment around it is not: a
+skewed clock, a replay store that is not atomic or not durable, a proxy configuration that trusts forged forwarding
+headers, or a suite / post-quantum pin policy that accepts more than intended.
+
+> Status: **0.4.2, unaudited.**
+
+## Install
+
+```sh
+npm i -D @atlasauth/pca-doctor
+```
+
+## Run it
+
+```sh
+npx pca-doctor --url https://api.example.com
+```
+
+Check groups: `clock`, `store`, `proxy`, `suites`, `caveats` (select with `--only a,b` or `--skip a,b`).
+
+- **clock**: skew against a reference clock (`--reference`, default an HTTPS endpoint; `--max-skew-ms`, default 60000).
+- **store**: atomicity and durability of your replay store, using an adapter module in the
+  [`@atlasauth/pca-store-conformance`](https://www.npmjs.com/package/@atlasauth/pca-store-conformance) interface
+  (`--store ./my-adapter.js`, `--store-option k=v`).
+- **proxy**: the trusted-proxy settings against the real number of hops; it sends forged forwarding headers to see whether
+  the deployment believes them (`--no-probe` to skip sending them).
+- **suites**: the allowed signature suites and post-quantum key pins.
+- **caveats**: that the installed `@atlasauth/pca` enforces root caveats (`--pca-dir` points at the deployed application).
+
+Configuration can also come from a JSON or JS file (`--config`) or the environment (`PCA_DOCTOR_URL`,
+`TRUSTED_PROXY_COUNT`, `PCA_ALLOWED_SUITES`, `PCA_PQ_PINS`, ...); flags override both. `--strict` makes warnings fail,
+`--json` prints machine-readable output. Run `npx pca-doctor --help` for every option.
+
+## In CI
+
+Run it against a staging deployment after each deploy, with `--strict --json`, and fail the pipeline on a non-zero exit.
+
+## Programmatic use
+
+```ts
+import { runDoctor } from '@atlasauth/pca-doctor';
+
+const results = await runDoctor({ url: 'https://api.example.com' });
+```

package/dist/caveats.d.ts

@@ -0,0 +1,24 @@
+import type { CheckResult, DoctorConfig } from './types';
+/** The parts of @atlasauth/pca the probe uses (typed loosely: any version may be loaded). */
+export type PcaLike = Record<string, any>;
+export interface LoadedPca {
+    module: PcaLike;
+    version: string;
+    path: string;
+}
+/** Load @atlasauth/pca as resolved from `dir` (the deployed application), or the doctor's own copy. */
+export declare function loadPca(dir?: string): LoadedPca;
+/** -1 / 0 / 1 for a < b / = / > over major.minor.patch (pre-release tags ignored); NaN parts compare as -1. */
+export declare function compareVersion(a: string, b: string): number;
+export declare const ROOT_CAVEAT_MIN_VERSION = "0.4.1";
+export declare const CAVEAT_REMEDIATION = "Upgrade @atlasauth/pca to >= 0.4.1 in the deployed application (root caveats outside the envelope are enforced from 0.4.1), redeploy, and re-run pca-doctor with --pca-dir pointing at the application.";
+/** Decide a payment of `amount` USD under a root grant carrying `rootCaveat`; returns the decision. */
+export declare function probeDecision(m: PcaLike, rootCaveat: Record<string, unknown>, amount: number, now?: number): {
+    allowed: boolean;
+    reasons: string[];
+};
+export declare function checkRootCaveats(cfg: DoctorConfig, deps?: {
+    loadPca?: (dir?: string) => LoadedPca;
+}): CheckResult;
+export declare const DEFAULT_REQUIRED: string[];
+export declare function checkEnforcement(cfg: DoctorConfig): CheckResult;

package/dist/caveats.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REQUIRED = exports.CAVEAT_REMEDIATION = exports.ROOT_CAVEAT_MIN_VERSION = void 0;
+exports.loadPca = loadPca;
+exports.compareVersion = compareVersion;
+exports.probeDecision = probeDecision;
+exports.checkRootCaveats = checkRootCaveats;
+exports.checkEnforcement = checkEnforcement;
+/**
+ * Root-caveat enforcement (0.4.1 security fix). There is NO switch that turns it off in 0.4.1: decide() / verifyPCActn /
+ * requirePCA always evaluate the caveats on the root grant. What can leave a deployment without it is an OLDER library
+ * (< 0.4.1, where root caveats outside the envelope were signed but ignored) or a verifier that skips enforcement. So:
+ *  - the installed @atlasauth/pca version (the deployment's own, via verifier.pcaDir) must be >= 0.4.1;
+ *  - a functional probe through THAT library: a root max_spend of 100 must deny 150 and allow 50, and an unknown root
+ *    caveat type must deny (fail closed);
+ *  - requirePCA must not run with insecureAllowUnenforced, and a custom `require` list should keep the defaults.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Load @atlasauth/pca as resolved from `dir` (the deployed application), or the doctor's own copy. */
+function loadPca(dir) {
+    // With `paths`, require.resolve falls back to the GLOBAL folders (NODE_PATH, which pnpm's bin shims set to the store's
+    // hoisted node_modules, and ~/.node_modules) when nothing under `dir` has the package, and would silently probe some
+    // other copy (e.g. the doctor's own) instead of the application's. So `dir` must itself install it: the nearest
+    // ancestor holding node_modules/@atlasauth/pca is the resolution base, and none is an error.
+    let base;
+    if (dir) {
+        for (let d = (0, node_path_1.resolve)(dir);; d = (0, node_path_1.dirname)(d)) {
+            if ((0, node_fs_1.existsSync)((0, node_path_1.join)(d, 'node_modules', '@atlasauth', 'pca', 'package.json'))) {
+                base = d;
+                break;
+            }
+            if ((0, node_path_1.dirname)(d) === d)
+                break;
+        }
+        if (base === undefined)
+            throw new Error(`@atlasauth/pca is not installed in ${dir} or any parent node_modules`);
+    }
+    const opts = base ? { paths: [base] } : undefined;
+    const pkgPath = require.resolve('@atlasauth/pca/package.json', opts);
+    const main = require.resolve('@atlasauth/pca', opts);
+    return { module: require(main), version: String(require(pkgPath).version), path: (0, node_path_1.dirname)(pkgPath) };
+}
+/** -1 / 0 / 1 for a < b / = / > over major.minor.patch (pre-release tags ignored); NaN parts compare as -1. */
+function compareVersion(a, b) {
+    const pa = a.split(/[.+-]/).slice(0, 3).map(Number);
+    const pb = b.split(/[.+-]/).slice(0, 3).map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = Number.isFinite(pa[i]) ? pa[i] : -1;
+        const y = Number.isFinite(pb[i]) ? pb[i] : -1;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+exports.ROOT_CAVEAT_MIN_VERSION = '0.4.1';
+exports.CAVEAT_REMEDIATION = 'Upgrade @atlasauth/pca to >= 0.4.1 in the deployed application (root caveats outside the envelope are enforced from 0.4.1), redeploy, and re-run pca-doctor with --pca-dir pointing at the application.';
+/** Decide a payment of `amount` USD under a root grant carrying `rootCaveat`; returns the decision. */
+function probeDecision(m, rootCaveat, amount, now = Date.now()) {
+    const principal = m.generateKeyPair();
+    const pPub = m.encodeKey(principal.publicKey);
+    const { grant: g0 } = m.mintGrant({
+        principalSecret: principal.secretKey,
+        principalPublic: pPub,
+        holder: pPub,
+        goal: 'pca-doctor root caveat probe',
+        envelope: { predicates: [{ verb: 'pay', resource: 'invoice:*' }], caveats: [{ type: 'expires', at: now + 3_600_000 }], agent_binding: {}, risk_policy: m.DEFAULT_RISK_POLICY },
+    });
+    const grant = m.mintRoot({ principalSecret: principal.secretKey, principalPublic: pPub, holder: pPub, caveats: [...g0.caveats, rootCaveat] });
+    const agent = m.generateKeyPair();
+    const task = m.delegate(grant, m.encodeKey(agent.publicKey), [], principal.secretKey);
+    const d = m.decide({
+        grant,
+        chain: [grant, task],
+        action: { action: { verb: 'pay', resource: 'invoice:42', params: { amount, currency: 'usd' }, reversibility_class: 'reversible' } },
+        risk: { reversibility: 1, blastRadius: 0, confidence: 1, semanticDistance: 0, taint: 0 },
+        budget: { B: 1e9, tau: now, asOf: now },
+        now,
+    });
+    return { allowed: d.releaseGuardianShare === true, reasons: Array.isArray(d.reasons) ? d.reasons.map(String) : [] };
+}
+function checkRootCaveats(cfg, deps = {}) {
+    const id = 'caveats.root';
+    let pca;
+    try {
+        pca = (deps.loadPca ?? loadPca)(cfg.verifier?.pcaDir);
+    }
+    catch (e) {
+        return { id, status: 'fail', detail: `cannot load @atlasauth/pca${cfg.verifier?.pcaDir ? ` from ${cfg.verifier.pcaDir}` : ''}: ${e.message}`, remediation: exports.CAVEAT_REMEDIATION };
+    }
+    const where = `@atlasauth/pca ${pca.version} at ${pca.path}`;
+    if (compareVersion(pca.version, exports.ROOT_CAVEAT_MIN_VERSION) < 0) {
+        return { id, status: 'fail', detail: `${where}: root caveats outside the envelope are NOT enforced before ${exports.ROOT_CAVEAT_MIN_VERSION} (legacy behaviour)`, remediation: exports.CAVEAT_REMEDIATION };
+    }
+    let over, under, unknown;
+    try {
+        over = probeDecision(pca.module, { type: 'max_spend', usd: 100 }, 150);
+        under = probeDecision(pca.module, { type: 'max_spend', usd: 100 }, 50);
+        unknown = probeDecision(pca.module, { type: 'pca-doctor-unknown-caveat' }, 50);
+    }
+    catch (e) {
+        return { id, status: 'fail', detail: `${where}: the enforcement probe could not run: ${e.message}`, remediation: exports.CAVEAT_REMEDIATION };
+    }
+    const observed = { version: pca.version, over, under, unknown };
+    if (over.allowed || unknown.allowed) {
+        return {
+            id,
+            status: 'fail',
+            detail: `${where}: a root caveat was NOT enforced (${over.allowed ? 'max_spend 100 allowed a 150 payment' : 'an unknown root caveat type was allowed'})`,
+            remediation: exports.CAVEAT_REMEDIATION,
+            observed,
+        };
+    }
+    if (!under.allowed) {
+        return { id, status: 'warn', detail: `${where}: inconclusive: the control payment within the root max_spend was denied too (${under.reasons.join('; ')})`, observed };
+    }
+    return { id, status: 'pass', detail: `${where}: root caveats enforced (max_spend 100 denies 150, allows 50; an unknown root caveat type denies)`, observed };
+}
+exports.DEFAULT_REQUIRED = ['counter', 'revocation', 'plan_root_authorized', 'audience', 'validity', 'grant_ref_bound'];
+function checkEnforcement(cfg) {
+    const id = 'verifier.enforcement';
+    const v = cfg.verifier;
+    if (!v)
+        return { id, status: 'skip', detail: 'no verifier configuration given (config verifier.*)' };
+    if (v.insecureAllowUnenforced === true) {
+        return { id, status: 'fail', detail: 'requirePCA runs with insecureAllowUnenforced: required checks that are not enforced do not deny', remediation: 'Remove insecureAllowUnenforced and supply the stores the required checks need (counter / revocation / budget).' };
+    }
+    if (v.require !== undefined) {
+        const missing = exports.DEFAULT_REQUIRED.filter((c) => !v.require.includes(c));
+        if (missing.length > 0) {
+            return { id, status: 'warn', detail: `the require list drops default check(s): ${missing.join(', ')}`, remediation: `Keep every default required check (${exports.DEFAULT_REQUIRED.join(', ')}) and add to it.` };
+        }
+    }
+    return { id, status: 'pass', detail: v.require ? `require = ${v.require.join(', ')}` : 'default required checks; insecureAllowUnenforced off' };
+}
+//# sourceMappingURL=caveats.js.map

package/dist/caveats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caveats.js","sourceRoot":"","sources":["../src/caveats.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/** pca-doctor: check a live PCA deployment's assumptions. Exit 1 on any fail (and on warn with --strict), 2 on usage errors. */
+import { type CheckGroup } from './doctor';
+import type { DoctorConfig } from './types';
+export declare const USAGE: string;
+export interface DoctorArgs {
+    config?: string;
+    flags: DoctorConfig;
+    only: CheckGroup[];
+    json: boolean;
+    strict: boolean;
+    help: boolean;
+}
+export declare function parseDoctorArgs(argv: readonly string[]): DoctorArgs;
+export declare function main(argv: readonly string[], env?: Record<string, string | undefined>, print?: (s: string) => void, printErr?: (s: string) => void): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = void 0;
+exports.parseDoctorArgs = parseDoctorArgs;
+exports.main = main;
+/** pca-doctor: check a live PCA deployment's assumptions. Exit 1 on any fail (and on warn with --strict), 2 on usage errors. */
+const doctor_1 = require("./doctor");
+exports.USAGE = `pca-doctor [--url <deployment>] [options]
+
+  --url URL              the live deployment (base URL of the API that verifies PCActns)
+  --config FILE          JSON or JS config (see the pca-doctor guide); env and flags override it
+  --store MODULE         replay-store adapter module (store conformance kit interface) for the atomicity / durability checks
+  --store-option k=v     passed to the adapter factory (repeatable)
+  --reference URL|local  clock reference (default https://www.google.com/generate_204)
+  --max-skew-ms N        clock fail threshold (default 60000)
+  --trusted-proxy-count N, --proxy-header H, --proxy-hops N   the deployment's proxy settings and the real hop count
+  --pca-dir DIR          the deployed application's directory (its installed @atlasauth/pca is probed)
+  --only a,b | --skip a,b   check groups: ${doctor_1.CHECK_GROUPS.join(', ')}
+  --no-probe             do not send forged forwarding headers to the deployment
+  --strict               warnings fail too
+  --json                 machine-readable output
+
+Env: PCA_DOCTOR_URL, PCA_DOCTOR_REFERENCE_URL, PCA_DOCTOR_STORE, TRUSTED_PROXY_COUNT, TRUSTED_PROXY_HEADER, PCA_TRUSTED_PROXY_HOPS,
+     PCA_ALLOWED_SUITES (comma list), PCA_PQ_PINS (JSON), PCA_ALLOW_UNBOUND_PQ.`;
+const groups = (flag, v) => {
+    const g = (v ?? '').split(',').filter(Boolean);
+    const bad = g.filter((x) => !doctor_1.CHECK_GROUPS.includes(x));
+    if (bad.length || g.length === 0)
+        throw new Error(`${flag}: unknown check group(s) ${bad.join(', ') || '(none given)'}`);
+    return g;
+};
+const num = (flag, v) => {
+    const n = Number(v);
+    if (v === undefined || v === '' || !Number.isFinite(n))
+        throw new Error(`${flag} needs a number`);
+    return n;
+};
+function parseDoctorArgs(argv) {
+    const a = { flags: {}, only: [...doctor_1.CHECK_GROUPS], json: false, strict: false, help: false };
+    const f = a.flags;
+    for (let i = 0; i < argv.length; i++) {
+        const k = argv[i];
+        const next = () => argv[++i];
+        switch (k) {
+            case '--url':
+                f.url = next();
+                break;
+            case '--config':
+                a.config = next();
+                break;
+            case '--store':
+                f.store = { ...f.store, adapter: next() };
+                break;
+            case '--store-option': {
+                const kv = next() ?? '';
+                const eq = kv.indexOf('=');
+                if (eq < 1)
+                    throw new Error('--store-option needs k=v');
+                f.store = { ...f.store, options: { ...f.store?.options, [kv.slice(0, eq)]: kv.slice(eq + 1) } };
+                break;
+            }
+            case '--reference':
+                f.clock = { ...f.clock, referenceUrl: next() };
+                break;
+            case '--max-skew-ms':
+                f.clock = { ...f.clock, maxSkewMs: num(k, next()) };
+                break;
+            case '--trusted-proxy-count':
+                f.proxy = { ...f.proxy, trustedProxyCount: num(k, next()) };
+                break;
+            case '--proxy-header':
+                f.proxy = { ...f.proxy, header: next() };
+                break;
+            case '--proxy-hops':
+                f.proxy = { ...f.proxy, hops: num(k, next()) };
+                break;
+            case '--no-probe':
+                f.proxy = { ...f.proxy, probe: false };
+                break;
+            case '--pca-dir':
+                f.verifier = { ...f.verifier, pcaDir: next() };
+                break;
+            case '--only':
+                a.only = groups(k, next());
+                break;
+            case '--skip': {
+                const s = groups(k, next());
+                a.only = a.only.filter((g) => !s.includes(g));
+                break;
+            }
+            case '--strict':
+                a.strict = true;
+                break;
+            case '--json':
+                a.json = true;
+                break;
+            case '-h':
+            case '--help':
+                a.help = true;
+                break;
+            default:
+                throw new Error(`unknown argument ${k}`);
+        }
+    }
+    return a;
+}
+async function main(argv, env = process.env, print = console.log, printErr = console.error) {
+    let a;
+    let cfg;
+    try {
+        a = parseDoctorArgs(argv);
+        if (a.help) {
+            print(exports.USAGE);
+            return 0;
+        }
+        cfg = (0, doctor_1.mergeConfig)(a.config ? await (0, doctor_1.loadConfigFile)(a.config) : {}, (0, doctor_1.configFromEnv)(env), a.flags);
+    }
+    catch (e) {
+        printErr(`${e.message}\n\n${exports.USAGE}`);
+        return 2;
+    }
+    const results = await (0, doctor_1.runDoctor)(cfg, a.only);
+    const verdict = (0, doctor_1.verdictOf)(results, a.strict);
+    print(a.json ? JSON.stringify({ target: cfg.url ?? null, verdict, results }, null, 2) : (0, doctor_1.formatResults)(results, cfg.url, a.strict));
+    return verdict === 'fail' ? 1 : 0;
+}
+// Stryker disable next-line all: process entry glue
+if (require.main === module)
+    void main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/clock.d.ts

@@ -0,0 +1,28 @@
+import type { CheckResult, DoctorConfig } from './types';
+export type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    redirect?: 'manual';
+}) => Promise<{
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+export declare const DEFAULT_REFERENCE_URL = "https://www.google.com/generate_204";
+export interface DateReading {
+    /** Remote clock minus local clock (ms). */
+    offsetMs: number;
+    uncertaintyMs: number;
+}
+/** One reading of a server's clock relative to `now()` from its Date header. */
+export declare function readDate(url: string, fetchImpl: FetchLike, now: () => number, timeoutMs: number): Promise<DateReading | {
+    error: string;
+}>;
+export declare const CLOCK_REMEDIATION = "Synchronise every verifier, issuer and replay-store host with NTP (chrony or systemd-timesyncd) and alert on drift. PCA tolerates at most 60 s between any two clocks (PCACTN_MAX_SKEW_MS); replay retention is exp + skew, so a clock outside that bound can free a nonce early or reject fresh actions.";
+export declare function checkClock(cfg: DoctorConfig, deps: {
+    fetch: FetchLike;
+    now?: () => number;
+}): Promise<CheckResult>;

package/dist/clock.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOCK_REMEDIATION = exports.DEFAULT_REFERENCE_URL = void 0;
+exports.readDate = readDate;
+exports.checkClock = checkClock;
+/**
+ * Clock skew of the deployment against a reference, from HTTP `Date` headers. `Date` has one-second resolution and is
+ * truncated, so each reading carries +-0.5 s plus half the round trip; the verdict uses that uncertainty: FAIL only when
+ * the skew is beyond the limit even at the favourable end of the interval, WARN when it is above the warning fraction or
+ * could be beyond the limit.
+ */
+const pca_1 = require("@atlasauth/pca");
+exports.DEFAULT_REFERENCE_URL = 'https://www.google.com/generate_204';
+/** One reading of a server's clock relative to `now()` from its Date header. */
+async function readDate(url, fetchImpl, now, timeoutMs) {
+    const t0 = now();
+    let res;
+    try {
+        res = await fetchImpl(url, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+    }
+    catch (e) {
+        return { error: `request failed: ${e.message}` };
+    }
+    const t1 = now();
+    const date = res.headers.get('date');
+    const d = date === null ? NaN : Date.parse(date);
+    if (!Number.isFinite(d))
+        return { error: date === null ? 'no Date header' : `unparseable Date header '${date}'` };
+    return { offsetMs: d + 500 - (t0 + t1) / 2, uncertaintyMs: 500 + (t1 - t0) / 2 };
+}
+const s = (ms) => `${ms >= 0 ? '+' : '-'}${(Math.abs(ms) / 1000).toFixed(1)} s`;
+exports.CLOCK_REMEDIATION = 'Synchronise every verifier, issuer and replay-store host with NTP (chrony or systemd-timesyncd) and alert on drift. PCA tolerates at most 60 s between any two clocks (PCACTN_MAX_SKEW_MS); replay retention is exp + skew, so a clock outside that bound can free a nonce early or reject fresh actions.';
+async function checkClock(cfg, deps) {
+    const now = deps.now ?? Date.now;
+    if (!cfg.url)
+        return { id: 'clock', status: 'skip', detail: 'no deployment URL given (--url)' };
+    const max = cfg.clock?.maxSkewMs ?? pca_1.PCACTN_MAX_SKEW_MS;
+    const warnAt = max * (cfg.clock?.warnFraction ?? 0.25);
+    const timeout = cfg.clock?.timeoutMs ?? 10_000;
+    const dep = await readDate(cfg.url, deps.fetch, now, timeout);
+    if ('error' in dep) {
+        return {
+            id: 'clock',
+            status: 'warn',
+            detail: `cannot observe the deployment's clock at ${cfg.url}: ${dep.error}`,
+            remediation: `Make the deployment answer with a Date header (RFC 9110 requires one from an origin with a clock), or check its clock on the host. ${exports.CLOCK_REMEDIATION}`,
+        };
+    }
+    const refUrl = cfg.clock?.referenceUrl ?? exports.DEFAULT_REFERENCE_URL;
+    let ref = { offsetMs: 0, uncertaintyMs: 0 };
+    let refName = "this machine's clock";
+    let refNote = '';
+    if (refUrl !== 'local') {
+        const r = await readDate(refUrl, deps.fetch, now, timeout);
+        if ('error' in r)
+            refNote = ` (reference ${refUrl} unusable: ${r.error}; compared with this machine's clock instead)`;
+        else {
+            ref = r;
+            refName = refUrl;
+        }
+    }
+    const skew = dep.offsetMs - ref.offsetMs;
+    const unc = dep.uncertaintyMs + ref.uncertaintyMs;
+    const lower = Math.abs(skew) - unc;
+    const upper = Math.abs(skew) + unc;
+    const status = lower > max ? 'fail' : Math.abs(skew) > warnAt || upper > max ? 'warn' : 'pass';
+    const detail = `deployment clock ${s(skew)} relative to ${refName}${refNote} (+-${(unc / 1000).toFixed(1)} s: Date has 1 s resolution, plus round trips); ` +
+        `fail beyond ${max / 1000} s, warn above ${warnAt / 1000} s. The Date header is written by whatever answers the request (a CDN or proxy may set it).`;
+    return {
+        id: 'clock',
+        status,
+        detail,
+        ...(status === 'pass' ? {} : { remediation: exports.CLOCK_REMEDIATION }),
+        observed: { skewMs: skew, uncertaintyMs: unc, maxSkewMs: max, warnAtMs: warnAt, reference: refName },
+    };
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"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"}

package/dist/doctor.d.ts

@@ -0,0 +1,21 @@
+import { type LoadedPca } from './caveats';
+import { type FetchLike } from './clock';
+import type { CheckResult, DoctorConfig } from './types';
+export declare const CHECK_GROUPS: readonly ["clock", "store", "proxy", "suites", "caveats"];
+export type CheckGroup = (typeof CHECK_GROUPS)[number];
+export interface DoctorDeps {
+    fetch?: FetchLike;
+    now?: () => number;
+    loadPca?: (dir?: string) => LoadedPca;
+}
+export declare function runDoctor(cfg: DoctorConfig, only?: readonly CheckGroup[], deps?: DoctorDeps): Promise<CheckResult[]>;
+export type Verdict = 'pass' | 'warn' | 'fail';
+/** fail if any check failed; warn if any warned (fail under --strict); else pass. */
+export declare function verdictOf(results: readonly CheckResult[], strict?: boolean): Verdict;
+export declare function formatResults(results: readonly CheckResult[], target: string | undefined, strict?: boolean): string;
+/** The deployment's own environment variable names (as the API and the guides use them). */
+export declare function configFromEnv(env: Record<string, string | undefined>): DoctorConfig;
+/** Two-level merge: later sources win per field inside each section. */
+export declare function mergeConfig(...cs: DoctorConfig[]): DoctorConfig;
+/** A JSON file, or a JS module whose default export is the config object. */
+export declare function loadConfigFile(path: string): Promise<DoctorConfig>;

package/dist/doctor.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHECK_GROUPS = void 0;
+exports.runDoctor = runDoctor;
+exports.verdictOf = verdictOf;
+exports.formatResults = formatResults;
+exports.configFromEnv = configFromEnv;
+exports.mergeConfig = mergeConfig;
+exports.loadConfigFile = loadConfigFile;
+/** Run every check, merge configuration (file < env < flags), and format the results. */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const caveats_1 = require("./caveats");
+const clock_1 = require("./clock");
+const proxy_1 = require("./proxy");
+const store_1 = require("./store");
+const suites_1 = require("./suites");
+exports.CHECK_GROUPS = ['clock', 'store', 'proxy', 'suites', 'caveats'];
+async function runDoctor(cfg, only = exports.CHECK_GROUPS, deps = {}) {
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const out = [];
+    if (only.includes('clock'))
+        out.push(await (0, clock_1.checkClock)(cfg, { fetch: fetchImpl, now: deps.now }));
+    if (only.includes('store'))
+        out.push(...(await (0, store_1.checkStore)(cfg)));
+    if (only.includes('proxy'))
+        out.push((0, proxy_1.checkProxyConfig)(cfg), await (0, proxy_1.checkProxyProbe)(cfg, { fetch: fetchImpl }));
+    if (only.includes('suites'))
+        out.push((0, suites_1.checkAllowedSuites)(cfg), (0, suites_1.checkPqBinding)(cfg));
+    if (only.includes('caveats'))
+        out.push((0, caveats_1.checkRootCaveats)(cfg, { loadPca: deps.loadPca }), (0, caveats_1.checkEnforcement)(cfg));
+    return out;
+}
+/** fail if any check failed; warn if any warned (fail under --strict); else pass. */
+function verdictOf(results, strict = false) {
+    if (results.some((r) => r.status === 'fail'))
+        return 'fail';
+    if (results.some((r) => r.status === 'warn'))
+        return strict ? 'fail' : 'warn';
+    return 'pass';
+}
+function formatResults(results, target, strict = false) {
+    const lines = [`pca-doctor${target ? `: ${target}` : ''}`];
+    for (const r of results) {
+        lines.push(`  ${r.status.toUpperCase().padEnd(4)}  ${r.id.padEnd(20)} ${r.detail}`);
+        if (r.remediation)
+            lines.push(`  ${''.padEnd(4)}  ${''.padEnd(20)} fix: ${r.remediation}`);
+    }
+    const n = (s) => results.filter((r) => r.status === s).length;
+    lines.push(`Summary: ${n('pass')} pass, ${n('warn')} warn, ${n('fail')} fail, ${n('skip')} skip -> ${verdictOf(results, strict).toUpperCase()}`);
+    return lines.join('\n');
+}
+const bool = (v) => (v === undefined ? undefined : /^(1|true|yes|on)$/i.test(v));
+const int = (v) => (v === undefined || v === '' ? undefined : Number(v));
+/** The deployment's own environment variable names (as the API and the guides use them). */
+function configFromEnv(env) {
+    const c = {};
+    if (env.PCA_DOCTOR_URL)
+        c.url = env.PCA_DOCTOR_URL;
+    if (env.PCA_DOCTOR_REFERENCE_URL)
+        c.clock = { referenceUrl: env.PCA_DOCTOR_REFERENCE_URL };
+    if (env.PCA_DOCTOR_STORE)
+        c.store = { adapter: env.PCA_DOCTOR_STORE };
+    const proxy = {};
+    if (env.TRUSTED_PROXY_COUNT !== undefined)
+        proxy.trustedProxyCount = int(env.TRUSTED_PROXY_COUNT);
+    if (env.TRUSTED_PROXY_HEADER)
+        proxy.header = env.TRUSTED_PROXY_HEADER;
+    if (env.PCA_TRUSTED_PROXY_HOPS !== undefined)
+        proxy.hops = int(env.PCA_TRUSTED_PROXY_HOPS);
+    if (Object.keys(proxy).length)
+        c.proxy = proxy;
+    const v = {};
+    if (env.PCA_ALLOWED_SUITES !== undefined)
+        v.allowedSuites = env.PCA_ALLOWED_SUITES.split(',').map((s) => s.trim()).filter(Boolean);
+    if (env.PCA_PQ_PINS)
+        v.pqPins = JSON.parse(env.PCA_PQ_PINS);
+    if (env.PCA_ALLOW_UNBOUND_PQ !== undefined)
+        v.allowUnboundPq = bool(env.PCA_ALLOW_UNBOUND_PQ);
+    if (Object.keys(v).length)
+        c.verifier = v;
+    return c;
+}
+/** Two-level merge: later sources win per field inside each section. */
+function mergeConfig(...cs) {
+    const out = {};
+    for (const c of cs) {
+        for (const [k, val] of Object.entries(c)) {
+            if (val === undefined)
+                continue;
+            out[k] = val && typeof val === 'object' && !Array.isArray(val) ? { ...(out[k] ?? {}), ...val } : val;
+        }
+    }
+    return out;
+}
+/** A JSON file, or a JS module whose default export is the config object. */
+async function loadConfigFile(path) {
+    if (path.endsWith('.json'))
+        return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    const m = (await import((0, node_url_1.pathToFileURL)((0, node_path_1.resolve)(path)).href));
+    return (m.default ?? m);
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":";;;AAoBA,8BASC;AAKD,8BAIC;AAED,sCASC;AAMD,sCAgBC;AAGD,kCASC;AAGD,wCAIC;AA1FD,yFAAyF;AACzF,qCAAuC;AACvC,yCAAoC;AACpC,uCAAyC;AACzC,uCAA+E;AAC/E,mCAAqD;AACrD,mCAA4D;AAC5D,mCAAqC;AACrC,qCAA8D;AAGjD,QAAA,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAS/E,KAAK,UAAU,SAAS,CAAC,GAAiB,EAAE,OAA8B,oBAAY,EAAE,OAAmB,EAAE;IAClH,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,IAAK,UAAU,CAAC,KAA8B,CAAC;IAC3E,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,MAAM,IAAA,kBAAU,EAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACjG,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,IAAA,kBAAU,EAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,IAAA,wBAAgB,EAAC,GAAG,CAAC,EAAE,MAAM,IAAA,uBAAe,EAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IAC9G,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,IAAA,2BAAkB,EAAC,GAAG,CAAC,EAAE,IAAA,uBAAc,EAAC,GAAG,CAAC,CAAC,CAAC;IACpF,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,GAAG,CAAC,IAAI,CAAC,IAAA,0BAAgB,EAAC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAA,0BAAgB,EAAC,GAAG,CAAC,CAAC,CAAC;IAChH,OAAO,GAAG,CAAC;AACb,CAAC;AAID,qFAAqF;AACrF,SAAgB,SAAS,CAAC,OAA+B,EAAE,MAAM,GAAG,KAAK;IACvE,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAC5D,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,aAAa,CAAC,OAA+B,EAAE,MAA0B,EAAE,MAAM,GAAG,KAAK;IACvG,MAAM,KAAK,GAAG,CAAC,aAAa,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3D,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACpF,IAAI,CAAC,CAAC,WAAW;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,CAAwB,EAAU,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7F,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,YAAY,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACjJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,CAAqB,EAAuB,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1H,MAAM,GAAG,GAAG,CAAC,CAAqB,EAAsB,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjH,4FAA4F;AAC5F,SAAgB,aAAa,CAAC,GAAuC;IACnE,MAAM,CAAC,GAAiB,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,cAAc;QAAE,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,cAAc,CAAC;IACnD,IAAI,GAAG,CAAC,wBAAwB;QAAE,CAAC,CAAC,KAAK,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,wBAAwB,EAAE,CAAC;IAC3F,IAAI,GAAG,CAAC,gBAAgB;QAAE,CAAC,CAAC,KAAK,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,gBAAgB,EAAE,CAAC;IACtE,MAAM,KAAK,GAAuC,EAAE,CAAC;IACrD,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS;QAAE,KAAK,CAAC,iBAAiB,GAAG,GAAG,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAClG,IAAI,GAAG,CAAC,oBAAoB;QAAE,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,oBAAmC,CAAC;IACrF,IAAI,GAAG,CAAC,sBAAsB,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;IAC3F,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM;QAAE,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC;IAC/C,MAAM,CAAC,GAA0C,EAAE,CAAC;IACpD,IAAI,GAAG,CAAC,kBAAkB,KAAK,SAAS;QAAE,CAAC,CAAC,aAAa,GAAG,GAAG,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnI,IAAI,GAAG,CAAC,WAAW;QAAE,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,CAA2B,CAAC;IACtF,IAAI,GAAG,CAAC,oBAAoB,KAAK,SAAS;QAAE,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC9F,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM;QAAE,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC1C,OAAO,CAAC,CAAC;AACX,CAAC;AAED,wEAAwE;AACxE,SAAgB,WAAW,CAAC,GAAG,EAAkB;IAC/C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACnB,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACzC,IAAI,GAAG,KAAK,SAAS;gBAAE,SAAS;YAChC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAE,GAAG,CAAC,CAAC,CAAY,IAAI,EAAE,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QACnH,CAAC;IACH,CAAC;IACD,OAAO,GAAmB,CAAC;AAC7B,CAAC;AAED,6EAA6E;AACtE,KAAK,UAAU,cAAc,CAAC,IAAY;IAC/C,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,IAAI,EAAE,MAAM,CAAC,CAAiB,CAAC;IAC1F,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,IAAA,wBAAa,EAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAA+B,CAAC;IAC1F,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAiB,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/** @atlasauth/pca-doctor: check a live PCA deployment's assumptions (see the pca-doctor guide). */
+export * from './types';
+export * from './clock';
+export * from './store';
+export * from './proxy';
+export * from './suites';
+export * from './caveats';
+export * from './doctor';
+export { main, parseDoctorArgs, USAGE } from './cli';

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = exports.parseDoctorArgs = exports.main = void 0;
+/** @atlasauth/pca-doctor: check a live PCA deployment's assumptions (see the pca-doctor guide). */
+__exportStar(require("./types"), exports);
+__exportStar(require("./clock"), exports);
+__exportStar(require("./store"), exports);
+__exportStar(require("./proxy"), exports);
+__exportStar(require("./suites"), exports);
+__exportStar(require("./caveats"), exports);
+__exportStar(require("./doctor"), exports);
+var cli_1 = require("./cli");
+Object.defineProperty(exports, "main", { enumerable: true, get: function () { return cli_1.main; } });
+Object.defineProperty(exports, "parseDoctorArgs", { enumerable: true, get: function () { return cli_1.parseDoctorArgs; } });
+Object.defineProperty(exports, "USAGE", { enumerable: true, get: function () { return cli_1.USAGE; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mGAAmG;AACnG,0CAAwB;AACxB,0CAAwB;AACxB,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,4CAA0B;AAC1B,2CAAyB;AACzB,6BAAqD;AAA5C,2FAAA,IAAI,OAAA;AAAE,sGAAA,eAAe,OAAA;AAAE,4FAAA,KAAK,OAAA"}

package/dist/proxy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * TRUSTED_PROXY_COUNT / TRUSTED_PROXY_HEADER sanity. Two parts:
+ *  - config: the stated values against the stated number of appending proxies (`hops`);
+ *  - live probe: forged forwarding headers sent to a public rate-limited path, watching `RateLimit-Remaining`. If a forged
+ *    request lands in a FRESH bucket while plain requests keep draining one bucket, the deployment derives the client
+ *    address from client-written entries (count too large, or a proxy that passes the header through untouched).
+ * What cannot be observed from one vantage point: a count that is too LOW (every client merged into the proxy's bucket
+ * looks the same as one client), the socket-address fallback, and anything the deployment does not reflect in headers.
+ */
+import type { FetchLike } from './clock';
+import type { CheckResult, DoctorConfig } from './types';
+export declare const PROXY_REMEDIATION = "Set TRUSTED_PROXY_COUNT to exactly the number of reverse proxies in front of the API that APPEND to the trusted header (1 behind one load balancer / ingress; 0 when clients connect directly), and TRUSTED_PROXY_HEADER to the header they write. Too high lets a client pick its own rate-limit bucket with extra X-Forwarded-For entries; too low merges every client into the proxy's bucket.";
+export declare function checkProxyConfig(cfg: DoctorConfig): CheckResult;
+/** A random documentation address (RFC 5737 TEST-NET-2 / -3): never a real client. */
+export declare function testNetIp(rand?: () => number): string;
+/** Forged values for all three headers at once (the server trusts at most one of them). */
+export declare function forgedHeaders(rand?: () => number): Record<string, string>;
+export declare function checkProxyProbe(cfg: DoctorConfig, deps: {
+    fetch: FetchLike;
+    rand?: () => number;
+}): Promise<CheckResult>;

package/dist/proxy.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROXY_REMEDIATION = void 0;
+exports.checkProxyConfig = checkProxyConfig;
+exports.testNetIp = testNetIp;
+exports.forgedHeaders = forgedHeaders;
+exports.checkProxyProbe = checkProxyProbe;
+exports.PROXY_REMEDIATION = 'Set TRUSTED_PROXY_COUNT to exactly the number of reverse proxies in front of the API that APPEND to the trusted header (1 behind one load balancer / ingress; 0 when clients connect directly), and TRUSTED_PROXY_HEADER to the header they write. Too high lets a client pick its own rate-limit bucket with extra X-Forwarded-For entries; too low merges every client into the proxy\'s bucket.';
+function checkProxyConfig(cfg) {
+    const p = cfg.proxy;
+    const n = p?.trustedProxyCount;
+    if (n === undefined)
+        return { id: 'proxy.config', status: 'skip', detail: 'TRUSTED_PROXY_COUNT not given (config proxy.trustedProxyCount or env TRUSTED_PROXY_COUNT)' };
+    const header = p?.header ?? 'x-forwarded-for';
+    const fail = (detail) => ({ id: 'proxy.config', status: 'fail', detail, remediation: exports.PROXY_REMEDIATION });
+    if (!Number.isInteger(n) || n < 0 || n > 16)
+        return fail(`TRUSTED_PROXY_COUNT=${String(n)} is not an integer in 0..16`);
+    if (header === 'x-real-ip' && n === 0)
+        return fail('TRUSTED_PROXY_HEADER=x-real-ip needs TRUSTED_PROXY_COUNT >= 1 (with 0 every forwarding header is ignored)');
+    if (p?.hops === undefined) {
+        return {
+            id: 'proxy.config',
+            status: n === 0 ? 'pass' : 'warn',
+            detail: `TRUSTED_PROXY_COUNT=${n} (${header}); the real number of appending proxies was not stated (proxy.hops / PCA_TRUSTED_PROXY_HOPS), so it cannot be compared`,
+            ...(n === 0 ? {} : { remediation: exports.PROXY_REMEDIATION }),
+        };
+    }
+    if (n > p.hops)
+        return fail(`TRUSTED_PROXY_COUNT=${n} is larger than the ${p.hops} proxies in front of the API: a client chooses its own address (and rate-limit bucket) with extra ${header} entries`);
+    if (n < p.hops) {
+        return { id: 'proxy.config', status: 'warn', detail: `TRUSTED_PROXY_COUNT=${n} is smaller than the ${p.hops} proxies in front of the API: clients are keyed by a proxy's address and share its bucket`, remediation: exports.PROXY_REMEDIATION };
+    }
+    return { id: 'proxy.config', status: 'pass', detail: `TRUSTED_PROXY_COUNT=${n} (${header}) matches the stated ${p.hops} appending proxies` };
+}
+/** A random documentation address (RFC 5737 TEST-NET-2 / -3): never a real client. */
+function testNetIp(rand = Math.random) {
+    return `${rand() < 0.5 ? '198.51.100' : '203.0.113'}.${1 + Math.floor(rand() * 254)}`;
+}
+/** Forged values for all three headers at once (the server trusts at most one of them). */
+function forgedHeaders(rand = Math.random) {
+    const chain = Array.from({ length: 17 }, () => testNetIp(rand));
+    return { 'x-forwarded-for': chain.join(', '), forwarded: chain.map((ip) => `for=${ip}`).join(', '), 'x-real-ip': testNetIp(rand) };
+}
+async function remaining(fetchImpl, url, headers, timeoutMs) {
+    const r = await fetchImpl(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+    await r.arrayBuffer().catch(() => undefined);
+    const v = r.headers.get('ratelimit-remaining');
+    const n = v === null ? NaN : Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+async function checkProxyProbe(cfg, deps) {
+    const id = 'proxy.probe';
+    if (!cfg.url)
+        return { id, status: 'skip', detail: 'no deployment URL given (--url)' };
+    if (cfg.proxy?.probe === false)
+        return { id, status: 'skip', detail: 'disabled (--no-probe)' };
+    const url = new URL(cfg.proxy?.probePath ?? '/v1/pca/suites', cfg.url).href;
+    const t = cfg.clock?.timeoutMs ?? 10_000;
+    let seq;
+    try {
+        const a = await remaining(deps.fetch, url, {}, t);
+        const b = await remaining(deps.fetch, url, {}, t);
+        const f = await remaining(deps.fetch, url, forgedHeaders(deps.rand), t);
+        const c = await remaining(deps.fetch, url, {}, t);
+        seq = [a, b, f, c];
+    }
+    catch (e) {
+        return { id, status: 'warn', detail: `probe request to ${url} failed: ${e.message}`, remediation: 'Set proxy.probePath to a public, rate-limited path of the deployment, or run with --no-probe.' };
+    }
+    const observed = { url, remaining: seq };
+    if (seq.some((x) => x === undefined)) {
+        return { id, status: 'skip', detail: `not observable remotely: ${url} does not return a RateLimit-Remaining header on every response`, observed };
+    }
+    const [a, b, f, c] = seq;
+    if (!(b < a && c < b)) {
+        return { id, status: 'warn', detail: `inconclusive: the plain requests' bucket did not drain monotonically (${a}, ${b}, then ${c}): a window rollover, a shared bucket or concurrent traffic. Re-run.`, observed };
+    }
+    if (f > b) {
+        return {
+            id,
+            status: 'fail',
+            detail: `a request with FORGED forwarding headers got a fresh rate-limit bucket (remaining ${f}, while the plain requests' bucket was at ${b}): the deployment trusts client-written forwarding entries`,
+            remediation: exports.PROXY_REMEDIATION,
+            observed,
+        };
+    }
+    return { id, status: 'pass', detail: `forged X-Forwarded-For / Forwarded / X-Real-IP did not move the client to another bucket (remaining ${a}, ${b}, forged ${f}, ${c}). A count that is too LOW is not observable from one client.`, observed };
+}
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Replay / counter store checks through the conformance kit's adapter interface: a REAL concurrent conflicting write
+ * (many clients consume one fresh key at once: exactly one may win; counters race on one stream) and durability (write,
+ * close, restart when the adapter can, read back). Short by design; the full kit (`pca-store-conformance`) goes further.
+ */
+import { loadAdapter as kitLoadAdapter } from '@atlasauth/pca-store-conformance';
+import type { CheckResult, DoctorConfig } from './types';
+export declare const ATOMICITY_REMEDIATION = "Make consumeOnce / advance one atomic operation on the shared store, e.g. Postgres INSERT .. ON CONFLICT (key) DO UPDATE .. WHERE until < $now RETURNING and UPDATE .. WHERE counter < $n RETURNING, Redis SET key NX PX or a Lua compare-and-set; never read, then write. Then run the full kit: pca-store-conformance --adapter <your adapter>.";
+export declare const DURABILITY_REMEDIATION = "Keep consumed keys and counters in a store with synchronous, persistent commits (Postgres synchronous_commit=on; Redis appendfsync always and maxmemory-policy noeviction), shared by every verifier instance. An in-memory store is only correct for a single process whose lifetime covers the action lifetime.";
+export declare function checkStore(cfg: DoctorConfig, deps?: {
+    loadAdapter?: typeof kitLoadAdapter;
+}): Promise<CheckResult[]>;

package/dist/store.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DURABILITY_REMEDIATION = exports.ATOMICITY_REMEDIATION = void 0;
+exports.checkStore = checkStore;
+/**
+ * Replay / counter store checks through the conformance kit's adapter interface: a REAL concurrent conflicting write
+ * (many clients consume one fresh key at once: exactly one may win; counters race on one stream) and durability (write,
+ * close, restart when the adapter can, read back). Short by design; the full kit (`pca-store-conformance`) goes further.
+ */
+const pca_store_conformance_1 = require("@atlasauth/pca-store-conformance");
+const OP = { consume: 'consumeOnce', advance: 'advance' };
+exports.ATOMICITY_REMEDIATION = 'Make consumeOnce / advance one atomic operation on the shared store, e.g. Postgres INSERT .. ON CONFLICT (key) DO UPDATE .. WHERE until < $now RETURNING and UPDATE .. WHERE counter < $n RETURNING, Redis SET key NX PX or a Lua compare-and-set; never read, then write. Then run the full kit: pca-store-conformance --adapter <your adapter>.';
+exports.DURABILITY_REMEDIATION = 'Keep consumed keys and counters in a store with synchronous, persistent commits (Postgres synchronous_commit=on; Redis appendfsync always and maxmemory-policy noeviction), shared by every verifier instance. An in-memory store is only correct for a single process whose lifetime covers the action lifetime.';
+function firstCounterexample(h) {
+    const v = h.violations[0];
+    return v ? ` First violating key ${v.key}: ${(0, pca_store_conformance_1.formatOps)(v.counterexample ?? []).join(' | ')}` : '';
+}
+async function checkStore(cfg, deps = {}) {
+    const spec = cfg.store?.adapter;
+    if (!spec) {
+        const detail = 'no store adapter given (--store ./adapter.mjs); the replay store cannot be exercised remotely';
+        return [
+            { id: 'store.atomicity', status: 'skip', detail },
+            { id: 'store.durability', status: 'skip', detail },
+        ];
+    }
+    let adapter;
+    try {
+        adapter = await (deps.loadAdapter ?? pca_store_conformance_1.loadAdapter)(spec, cfg.store?.options ?? {});
+    }
+    catch (e) {
+        return [{ id: 'store.atomicity', status: 'fail', detail: `cannot load the store adapter ${spec}: ${e.message}`, remediation: 'Point --store at a module exporting a store adapter (see the store conformance kit guide).' }];
+    }
+    try {
+        const kinds = await (0, pca_store_conformance_1.detectKinds)(adapter);
+        return [await atomicity(adapter, kinds, cfg), await durability(adapter, kinds)];
+    }
+    catch (e) {
+        return [{ id: 'store.atomicity', status: 'fail', detail: `the store adapter failed: ${e.message}`, remediation: exports.ATOMICITY_REMEDIATION }];
+    }
+    finally {
+        await adapter.teardown?.();
+    }
+}
+async function atomicity(adapter, kinds, cfg) {
+    const clients = cfg.store?.concurrency ?? 32;
+    const rounds = cfg.store?.rounds ?? 10;
+    const parts = [];
+    const observed = {};
+    let status = 'pass';
+    let cx = '';
+    for (const kind of kinds) {
+        const w = await (0, pca_store_conformance_1.runBurst)(adapter, kind, { clients, rounds, values: 8 });
+        const h = (0, pca_store_conformance_1.checkHistory)(w.ops);
+        const winners = new Set(w.ops.filter((o) => o.res === 'true').map((o) => o.key)).size;
+        observed[kind] = { ops: h.ops, keys: h.keys, outcomes: h.outcomes, violations: h.violations.length, unresolved: h.unresolved.length };
+        const definite = h.outcomes.true + h.outcomes.false;
+        if (h.violations.length > 0) {
+            status = 'fail';
+            cx ||= firstCounterexample(h);
+            parts.push(`${OP[kind]}: ${h.violations.length} of ${rounds} same-key rounds NOT linearizable (${clients} concurrent clients)`);
+        }
+        else if (definite === 0 || h.unresolved.length > 0) {
+            if (status === 'pass')
+                status = 'warn';
+            parts.push(`${OP[kind]}: inconclusive (${w.errors} of ${h.ops} calls failed or timed out${h.unresolved.length ? `, ${h.unresolved.length} key(s) undecided` : ''})`);
+        }
+        else {
+            parts.push(`${OP[kind]}: ${rounds} rounds of ${clients} concurrent conflicting calls linearizable${kind === 'consume' ? ` (${winners} of ${rounds} rounds had exactly one TRUE)` : ''}${w.errors ? `, ${w.errors} calls failed closed` : ''}`);
+        }
+    }
+    return {
+        id: 'store.atomicity',
+        status,
+        detail: `${adapter.name}: ${parts.join('; ')}.${cx}`,
+        ...(status === 'pass' ? {} : { remediation: exports.ATOMICITY_REMEDIATION }),
+        observed,
+    };
+}
+async function durability(adapter, kinds) {
+    if (adapter.capabilities?.durable === false) {
+        return { id: 'store.durability', status: 'warn', detail: `${adapter.name} declares itself non-durable: a restart forgets consumed nonces`, remediation: exports.DURABILITY_REMEDIATION };
+    }
+    const parts = [];
+    let status = 'pass';
+    let cx = '';
+    for (const kind of kinds) {
+        const w = await (0, pca_store_conformance_1.runDurability)(adapter, kind);
+        const h = (0, pca_store_conformance_1.checkHistory)(w.ops);
+        if (h.violations.length > 0) {
+            status = 'fail';
+            cx ||= firstCounterexample(h);
+            parts.push(`${OP[kind]}: state LOST across close/restart`);
+        }
+        else if (h.outcomes.true + h.outcomes.false < w.ops.length) {
+            if (status === 'pass')
+                status = 'warn';
+            parts.push(`${OP[kind]}: inconclusive (${w.errors} calls failed)`);
+        }
+        else {
+            parts.push(`${OP[kind]}: survived`);
+        }
+    }
+    const how = adapter.restart ? 'write, close, restart() the backend, read back' : 'write, close, re-open (no restart() hook: the backend itself was not restarted)';
+    return {
+        id: 'store.durability',
+        status,
+        detail: `${adapter.name} (${how}): ${parts.join('; ')}.${cx}`,
+        ...(status === 'pass' ? {} : { remediation: exports.DURABILITY_REMEDIATION }),
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/suites.d.ts

@@ -0,0 +1,5 @@
+import type { CheckResult, DoctorConfig } from './types';
+export declare const SUITES_REMEDIATION = "Set the verifier's allowedSuites to exactly the suites your issuers sign with (names from SIG_SUITES), e.g. ['ed25519'] or ['hybrid-ed25519-ml-dsa-65'].";
+export declare const PQ_REMEDIATION = "Never set allowUnboundPq. For pure-PQ or hybrid roots, configure pqPins (issuer Ed25519 identity -> PQ public key, from pqPinFor) or verify against your stored root grant (trustedRoot; requirePCA / verifyPCActnCore do this).";
+export declare function checkAllowedSuites(cfg: DoctorConfig, registry?: Readonly<Record<string, unknown>>): CheckResult;
+export declare function checkPqBinding(cfg: DoctorConfig): CheckResult;

package/dist/suites.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PQ_REMEDIATION = exports.SUITES_REMEDIATION = void 0;
+exports.checkAllowedSuites = checkAllowedSuites;
+exports.checkPqBinding = checkPqBinding;
+/** allowedSuites / pqPins / allowUnboundPq sanity against the library's closed suite registry. */
+const pca_1 = require("@atlasauth/pca");
+const B64U = /^[A-Za-z0-9_-]+$/;
+const ED25519_ID = /^[A-Za-z0-9_-]{43}$/;
+exports.SUITES_REMEDIATION = "Set the verifier's allowedSuites to exactly the suites your issuers sign with (names from SIG_SUITES), e.g. ['ed25519'] or ['hybrid-ed25519-ml-dsa-65'].";
+exports.PQ_REMEDIATION = 'Never set allowUnboundPq. For pure-PQ or hybrid roots, configure pqPins (issuer Ed25519 identity -> PQ public key, from pqPinFor) or verify against your stored root grant (trustedRoot; requirePCA / verifyPCActnCore do this).';
+const isPq = (alg) => !!pca_1.SIG_SUITES[alg]?.needsPqPk;
+function checkAllowedSuites(cfg, registry = pca_1.SIG_SUITES) {
+    const id = 'suites.allowed';
+    const v = cfg.verifier;
+    if (!v)
+        return { id, status: 'skip', detail: 'no verifier configuration given (config verifier.*)' };
+    const list = v.allowedSuites;
+    const known = Object.keys(registry);
+    if (list === undefined) {
+        return { id, status: 'warn', detail: `allowedSuites is unset: every registered suite is accepted (${known.length}: ${known.join(', ')})`, remediation: exports.SUITES_REMEDIATION };
+    }
+    if (!Array.isArray(list) || list.length === 0) {
+        return { id, status: 'fail', detail: 'allowedSuites is empty or not a list: no PCActn can verify', remediation: exports.SUITES_REMEDIATION };
+    }
+    const unknown = list.filter((s) => typeof s !== 'string' || !Object.prototype.hasOwnProperty.call(registry, s));
+    if (unknown.length > 0) {
+        return { id, status: 'fail', detail: `allowedSuites names suite(s) outside the registry: ${unknown.map(String).join(', ')} (known: ${known.join(', ')})`, remediation: exports.SUITES_REMEDIATION };
+    }
+    return { id, status: 'pass', detail: `allowedSuites = ${list.join(', ')}` };
+}
+function checkPqBinding(cfg) {
+    const id = 'suites.pq-binding';
+    const v = cfg.verifier;
+    if (!v)
+        return { id, status: 'skip', detail: 'no verifier configuration given (config verifier.*)' };
+    const fail = (detail) => ({ id, status: 'fail', detail, remediation: exports.PQ_REMEDIATION });
+    if (v.allowUnboundPq === true)
+        return fail('allowUnboundPq is set: PQ keys are read from the artifact, so a hybrid gives no protection against an Ed25519 forger and a pure-PQ hop can be signed by any key');
+    const pins = v.pqPins;
+    if (pins !== undefined) {
+        if (!pins || typeof pins !== 'object' || Array.isArray(pins))
+            return fail('pqPins is not an object of { ed25519 identity: pq public key }');
+        const bad = Object.entries(pins).filter(([k, val]) => !ED25519_ID.test(k) || typeof val !== 'string' || !B64U.test(val));
+        if (bad.length > 0)
+            return fail(`pqPins has malformed entries (key must be a 43-char base64url Ed25519 identity, value a base64url PQ key): ${bad.map(([k]) => k).join(', ')}`);
+    }
+    const pq = (v.allowedSuites ?? Object.keys(pca_1.SIG_SUITES)).filter(isPq);
+    if (pq.length === 0)
+        return { id, status: 'pass', detail: 'no post-quantum suite is accepted (Ed25519 only: no PQ binding needed, and no PQ protection)' };
+    const pinned = pins !== undefined && Object.keys(pins).length > 0;
+    if (!pinned && v.trustedRoot !== true) {
+        return {
+            id,
+            status: 'warn',
+            detail: `post-quantum suite(s) accepted (${pq.join(', ')}) with neither pqPins nor a stored trustedRoot: a non-Ed25519 root is refused (fail closed) or its PQ key is not pinned`,
+            remediation: exports.PQ_REMEDIATION,
+        };
+    }
+    return { id, status: 'pass', detail: `PQ suites (${pq.join(', ')}) are bound: ${pinned ? `${Object.keys(pins).length} pin(s)` : 'stored trustedRoot'}; allowUnboundPq off` };
+}
+//# sourceMappingURL=suites.js.map

package/dist/suites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suites.js","sourceRoot":"","sources":["../src/suites.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/** pca-doctor result and configuration types. */
+export type CheckStatus = 'pass' | 'warn' | 'fail' | 'skip';
+export interface CheckResult {
+    /** Stable id, e.g. `clock`, `store.atomicity`. */
+    id: string;
+    status: CheckStatus;
+    /** What was observed (or why nothing could be). */
+    detail: string;
+    /** What to do about a warn / fail. */
+    remediation?: string;
+    /** Raw observations for --json. */
+    observed?: Record<string, unknown>;
+}
+export type ProxyHeader = 'x-forwarded-for' | 'forwarded' | 'x-real-ip';
+export interface DoctorConfig {
+    /** Base URL of the live deployment (the API that verifies PCActns). */
+    url?: string;
+    clock?: {
+        /** HTTPS URL whose Date header is the reference, or 'local' for this machine's clock. Default https://www.google.com/generate_204. */
+        referenceUrl?: string;
+        /** Fail beyond this skew (default PCACTN_MAX_SKEW_MS = 60 s). */
+        maxSkewMs?: number;
+        /** Warn beyond this fraction of maxSkewMs (default 0.25). */
+        warnFraction?: number;
+        /** Per-request timeout (default 10 s). */
+        timeoutMs?: number;
+    };
+    store?: {
+        /** Adapter module path or builtin:<name> (the store conformance kit's adapter interface). */
+        adapter?: string;
+        options?: Record<string, string>;
+        /** Concurrent clients for the conflicting-write probe (default 32). */
+        concurrency?: number;
+        /** Same-key rounds (default 10). */
+        rounds?: number;
+    };
+    proxy?: {
+        /** The deployment's TRUSTED_PROXY_COUNT. */
+        trustedProxyCount?: number;
+        /** The deployment's TRUSTED_PROXY_HEADER (default x-forwarded-for). */
+        header?: ProxyHeader;
+        /** How many reverse proxies really sit in front of the API and append to the header (operator's statement). */
+        hops?: number;
+        /** Send forged forwarding headers to the live URL and watch the rate-limit bucket (default true when url is set). */
+        probe?: boolean;
+        /** A public, rate-limited path on the deployment (default /v1/pca/suites). */
+        probePath?: string;
+    };
+    verifier?: {
+        /** The verifier's allowedSuites option (absent = unset). */
+        allowedSuites?: string[];
+        /** The verifier's pqPins (issuer Ed25519 identity -> PQ public key, base64url). */
+        pqPins?: Record<string, string>;
+        /** The verifier supplies its stored root grant as trustedRoot (verifyPCActnCore / requirePCA do). */
+        trustedRoot?: boolean;
+        allowUnboundPq?: boolean;
+        /** requirePCA's insecureAllowUnenforced. */
+        insecureAllowUnenforced?: boolean;
+        /** requirePCA's `require` list (absent = the defaults). */
+        require?: string[];
+        /** Directory of the deployed application, to load ITS installed @atlasauth/pca (default: the doctor's own). */
+        pcaDir?: string;
+    };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+"use strict";
+/** pca-doctor result and configuration types. */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA,iDAAiD"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@atlasauth/pca-doctor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.2",
+  "description": "pca-doctor: check a live PCA deployment's assumptions (clock skew, replay-store atomicity and durability, trusted-proxy config, suite / PQ-pin policy, root-caveat enforcement) and print pass / warn / fail with a remediation per check.",
+  "keywords": [
+    "doctor",
+    "deployment check",
+    "proof-carrying authority",
+    "pca"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Atlas-Authorization/pca#readme",
+  "bugs": {
+    "url": "https://github.com/Atlas-Authorization/pca/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atlas-Authorization/pca.git",
+    "directory": "packages/pca-doctor"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pca-doctor": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.4.2",
+    "@atlasauth/pca-store-conformance": "0.4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }