@blacksandscyber/mcp-server-bursar 0.5.0

package/build/shared/errors.d.ts

@@ -0,0 +1,50 @@
+/** MCP-compatible error types. */
+export declare class ShieldError extends Error {
+    code: number;
+    details?: unknown | undefined;
+    constructor(message: string, code?: number, details?: unknown | undefined);
+}
+export declare class AuthenticationError extends ShieldError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends ShieldError {
+    constructor(resource: string, id: string);
+}
+export declare class ValidationError extends ShieldError {
+    constructor(message: string, details?: unknown);
+}
+export declare class RateLimitError extends ShieldError {
+    constructor(retryAfter?: number);
+}
+/**
+ * Phases of `bursar_install_agent_remotely` that can fail. The phase name
+ * is included in every InstallError so callers know where rollback starts.
+ */
+export type InstallPhase = "issue-cert" | "mint-token" | "connect-transport" | "write-files" | "apply-config" | "restart-agent" | "verify-handshake" | "rollback" | "precheck";
+export interface InstallErrorDetails {
+    phase: InstallPhase;
+    clientName?: string;
+    transport?: "ssh" | "bootstrap-token" | "aws-ssm";
+    next_steps?: string[];
+    rollback?: {
+        performed: boolean;
+        steps: string[];
+        errors?: string[];
+    };
+    cause?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Thrown by `bursar_install_agent_remotely`. `phase` tells callers which
+ * stage of the install failed; `next_steps` gives the operator concrete
+ * remediation to surface up to the calling agent.
+ */
+export declare class InstallError extends ShieldError {
+    readonly phase: InstallPhase;
+    constructor(message: string, details: InstallErrorDetails, code?: number);
+}
+/** Format any error into MCP tool result text. */
+export declare function formatError(err: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/build/shared/errors.js

@@ -0,0 +1,69 @@
+"use strict";
+/** MCP-compatible error types. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstallError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.ShieldError = void 0;
+exports.formatError = formatError;
+class ShieldError extends Error {
+    code;
+    details;
+    constructor(message, code = 500, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ShieldError";
+    }
+}
+exports.ShieldError = ShieldError;
+class AuthenticationError extends ShieldError {
+    constructor(message = "Authentication failed") {
+        super(message, 401);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class NotFoundError extends ShieldError {
+    constructor(resource, id) {
+        super(`${resource} '${id}' not found`, 404);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ValidationError extends ShieldError {
+    constructor(message, details) {
+        super(message, 400, details);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+class RateLimitError extends ShieldError {
+    constructor(retryAfter) {
+        super(`Rate limited${retryAfter ? `, retry after ${retryAfter}s` : ""}`, 429);
+        this.name = "RateLimitError";
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Thrown by `bursar_install_agent_remotely`. `phase` tells callers which
+ * stage of the install failed; `next_steps` gives the operator concrete
+ * remediation to surface up to the calling agent.
+ */
+class InstallError extends ShieldError {
+    phase;
+    constructor(message, details, code = 500) {
+        super(message, code, details);
+        this.name = "InstallError";
+        this.phase = details.phase;
+    }
+}
+exports.InstallError = InstallError;
+/** Format any error into MCP tool result text. */
+function formatError(err) {
+    if (err instanceof ShieldError) {
+        return JSON.stringify({ error: err.name, message: err.message, code: err.code, details: err.details });
+    }
+    if (err instanceof Error) {
+        return JSON.stringify({ error: "InternalError", message: err.message });
+    }
+    return JSON.stringify({ error: "UnknownError", message: String(err) });
+}
+//# sourceMappingURL=errors.js.map

package/build/shared/linkBuilder.d.ts

@@ -0,0 +1,93 @@
+/**
+ * linkBuilder — Shield Portal deep links for tool results (U1, Phase S).
+ *
+ * Tools that produce a posture-relevant result append a single markdown line:
+ *
+ *   "Posture preview: 62/100 — view full report → https://shield…/r/<token>"
+ *
+ * Two flavors:
+ *   - Account-bound tools (bursar_get_posture, bursar_provision_app,
+ *     bursar_compliance_report, …) link straight to the portal.
+ *   - The FREE local scan (bursar_scan_codebase with no account) POSTs its
+ *     ANONYMIZED summary to the public Shield API claim endpoint
+ *     (POST /v1/claims) and links to the returned claim URL. If the API is
+ *     unreachable/offline the scan result is returned unchanged — no link,
+ *     no error. The golden path must never make the free tool worse.
+ *
+ * Env:
+ *   SHIELD_PORTAL_URL     portal base (default https://shield.beta.blacksandscyber.online)
+ *   SHIELD_CLAIM_API_URL  Shield API base for POST /v1/claims (default = portal host's API;
+ *                         when unset we fall back to SHIELD_API_URL, then the beta API URL)
+ *   SHIELD_CLAIM_DISABLED set to "true" to suppress claim posting entirely
+ */
+export declare const DEFAULT_PORTAL_URL = "https://shield.beta.blacksandscyber.online";
+export declare const DEFAULT_CLAIM_API_URL = "https://shield-api.beta.blacksandscyber.online";
+/** Portal base URL, env-overridable, no trailing slash. */
+export declare function portalBaseUrl(env?: NodeJS.ProcessEnv): string;
+/** Shield API base used for the public claim POST, no trailing slash. */
+export declare function claimApiBaseUrl(env?: NodeJS.ProcessEnv): string;
+/** Build a portal URL for a path ('/', '/r/<token>', …). */
+export declare function buildPortalUrl(path: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The one-line markdown footer. Score is clamped to 0–100; pass null/undefined
+ * to omit the numeric preview ("View full report → …").
+ */
+export declare function postureLine(score: number | null | undefined, url: string): string;
+/**
+ * Derive a preview score from a severity summary (free local scan has no
+ * server-computed posture). Deliberately simple and stable: start at 100,
+ * subtract per finding by severity, clamp to [5, 100] — a project with
+ * findings never shows 0 (demoralizing) or 100 (wrong).
+ */
+export declare function previewScoreFromSeverity(bySeverity: Partial<Record<"critical" | "high" | "medium" | "low" | "info", number>> | null | undefined): number;
+export interface ClaimSummaryInput {
+    score: number;
+    highestSeverity?: string;
+    bySeverity?: Record<string, number>;
+    framework?: {
+        name?: string;
+        language?: string;
+        packageManager?: string;
+    };
+    counts?: {
+        endpoints?: number;
+        piiFields?: number;
+        externalServices?: number;
+        dataStores?: number;
+    };
+    findings?: Array<{
+        title: string;
+        severity?: string;
+        category?: string;
+        recommendation?: string;
+    }>;
+    source?: string;
+}
+export interface ClaimResult {
+    claimUrl: string;
+    claimToken: string;
+    score: number;
+    expiresAt?: string;
+}
+/**
+ * POST the anonymized summary to the public claim endpoint. Returns the claim
+ * URL on success, or null on ANY failure (offline, non-2xx, timeout, bad
+ * JSON) — callers degrade gracefully to "no link". Never throws.
+ */
+export declare function postClaimSummary(summary: ClaimSummaryInput, opts?: {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<ClaimResult | null>;
+/**
+ * Build the claim footer for a free local scan result: posts the summary,
+ * returns the markdown line, or null when the claim could not be created.
+ */
+export declare function buildClaimLine(summary: ClaimSummaryInput, opts?: {
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<string | null>;
+/** Footer for org-bound tools: deep link to the Posture Home. */
+export declare function portalHomeLine(score?: number | null, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=linkBuilder.d.ts.map

package/build/shared/linkBuilder.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * linkBuilder — Shield Portal deep links for tool results (U1, Phase S).
+ *
+ * Tools that produce a posture-relevant result append a single markdown line:
+ *
+ *   "Posture preview: 62/100 — view full report → https://shield…/r/<token>"
+ *
+ * Two flavors:
+ *   - Account-bound tools (bursar_get_posture, bursar_provision_app,
+ *     bursar_compliance_report, …) link straight to the portal.
+ *   - The FREE local scan (bursar_scan_codebase with no account) POSTs its
+ *     ANONYMIZED summary to the public Shield API claim endpoint
+ *     (POST /v1/claims) and links to the returned claim URL. If the API is
+ *     unreachable/offline the scan result is returned unchanged — no link,
+ *     no error. The golden path must never make the free tool worse.
+ *
+ * Env:
+ *   SHIELD_PORTAL_URL     portal base (default https://shield.beta.blacksandscyber.online)
+ *   SHIELD_CLAIM_API_URL  Shield API base for POST /v1/claims (default = portal host's API;
+ *                         when unset we fall back to SHIELD_API_URL, then the beta API URL)
+ *   SHIELD_CLAIM_DISABLED set to "true" to suppress claim posting entirely
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLAIM_API_URL = exports.DEFAULT_PORTAL_URL = void 0;
+exports.portalBaseUrl = portalBaseUrl;
+exports.claimApiBaseUrl = claimApiBaseUrl;
+exports.buildPortalUrl = buildPortalUrl;
+exports.postureLine = postureLine;
+exports.previewScoreFromSeverity = previewScoreFromSeverity;
+exports.postClaimSummary = postClaimSummary;
+exports.buildClaimLine = buildClaimLine;
+exports.portalHomeLine = portalHomeLine;
+const logger_1 = require("./logger");
+exports.DEFAULT_PORTAL_URL = "https://shield.beta.blacksandscyber.online";
+exports.DEFAULT_CLAIM_API_URL = "https://shield-api.beta.blacksandscyber.online";
+const CLAIM_TIMEOUT_MS = 4000;
+/** Portal base URL, env-overridable, no trailing slash. */
+function portalBaseUrl(env = process.env) {
+    const raw = env.SHIELD_PORTAL_URL || exports.DEFAULT_PORTAL_URL;
+    return raw.replace(/\/+$/, "");
+}
+/** Shield API base used for the public claim POST, no trailing slash. */
+function claimApiBaseUrl(env = process.env) {
+    const raw = env.SHIELD_CLAIM_API_URL || env.SHIELD_API_URL || exports.DEFAULT_CLAIM_API_URL;
+    return raw.replace(/\/+$/, "");
+}
+/** Build a portal URL for a path ('/', '/r/<token>', …). */
+function buildPortalUrl(path, env = process.env) {
+    const base = portalBaseUrl(env);
+    if (!path || path === "/")
+        return `${base}/`;
+    return `${base}${path.startsWith("/") ? "" : "/"}${path}`;
+}
+/**
+ * The one-line markdown footer. Score is clamped to 0–100; pass null/undefined
+ * to omit the numeric preview ("View full report → …").
+ */
+function postureLine(score, url) {
+    if (score === null || score === undefined || !Number.isFinite(score)) {
+        return `View full report → ${url}`;
+    }
+    const clamped = Math.max(0, Math.min(100, Math.round(score)));
+    return `Posture preview: ${clamped}/100 — view full report → ${url}`;
+}
+/**
+ * Derive a preview score from a severity summary (free local scan has no
+ * server-computed posture). Deliberately simple and stable: start at 100,
+ * subtract per finding by severity, clamp to [5, 100] — a project with
+ * findings never shows 0 (demoralizing) or 100 (wrong).
+ */
+function previewScoreFromSeverity(bySeverity) {
+    if (!bySeverity)
+        return 100;
+    const weights = { critical: 15, high: 8, medium: 3, low: 1, info: 0 };
+    let score = 100;
+    let findings = 0;
+    for (const sev of Object.keys(weights)) {
+        const count = Number(bySeverity[sev] ?? 0);
+        if (!Number.isFinite(count) || count <= 0)
+            continue;
+        findings += count;
+        score -= weights[sev] * count;
+    }
+    if (findings === 0)
+        return 100;
+    return Math.max(5, Math.min(99, Math.round(score)));
+}
+/**
+ * POST the anonymized summary to the public claim endpoint. Returns the claim
+ * URL on success, or null on ANY failure (offline, non-2xx, timeout, bad
+ * JSON) — callers degrade gracefully to "no link". Never throws.
+ */
+async function postClaimSummary(summary, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (String(env.SHIELD_CLAIM_DISABLED).toLowerCase() === "true")
+        return null;
+    const fetchImpl = opts.fetchImpl ?? (typeof fetch === "function" ? fetch : null);
+    if (!fetchImpl)
+        return null;
+    const url = `${claimApiBaseUrl(env)}/v1/claims`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? CLAIM_TIMEOUT_MS);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ summary }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            logger_1.logger.debug?.("Claim POST returned non-2xx; skipping link", { status: res.status });
+            return null;
+        }
+        const body = await res.json();
+        if (!body?.claim_url || !body?.claim_token)
+            return null;
+        return {
+            claimUrl: String(body.claim_url),
+            claimToken: String(body.claim_token),
+            score: Number(body.score ?? summary.score ?? 0),
+            expiresAt: body.expires_at,
+        };
+    }
+    catch (err) {
+        // Offline / DNS failure / abort — the free scan must keep working.
+        logger_1.logger.debug?.("Claim POST failed; returning no link", { error: err?.message });
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Build the claim footer for a free local scan result: posts the summary,
+ * returns the markdown line, or null when the claim could not be created.
+ */
+async function buildClaimLine(summary, opts = {}) {
+    const claim = await postClaimSummary(summary, opts);
+    if (!claim)
+        return null;
+    return postureLine(claim.score, claim.claimUrl);
+}
+/** Footer for org-bound tools: deep link to the Posture Home. */
+function portalHomeLine(score, env = process.env) {
+    return postureLine(score ?? null, buildPortalUrl("/", env));
+}
+//# sourceMappingURL=linkBuilder.js.map

package/build/shared/logger.d.ts

@@ -0,0 +1,10 @@
+/** Stderr-only logger — stdout is reserved for MCP JSON-RPC transport. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare const logger: {
+    debug: (msg: string, data?: Record<string, unknown>) => void;
+    info: (msg: string, data?: Record<string, unknown>) => void;
+    warn: (msg: string, data?: Record<string, unknown>) => void;
+    error: (msg: string, data?: Record<string, unknown>) => void;
+    setLevel: (level: LogLevel) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/build/shared/logger.js

@@ -0,0 +1,28 @@
+"use strict";
+/** Stderr-only logger — stdout is reserved for MCP JSON-RPC transport. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+let currentLevel = process.env.LOG_LEVEL || "info";
+function shouldLog(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[currentLevel];
+}
+function log(level, msg, data) {
+    if (!shouldLog(level))
+        return;
+    const entry = {
+        timestamp: new Date().toISOString(),
+        level,
+        msg,
+        ...(data && { data }),
+    };
+    process.stderr.write(JSON.stringify(entry) + "\n");
+}
+exports.logger = {
+    debug: (msg, data) => log("debug", msg, data),
+    info: (msg, data) => log("info", msg, data),
+    warn: (msg, data) => log("warn", msg, data),
+    error: (msg, data) => log("error", msg, data),
+    setLevel: (level) => { currentLevel = level; },
+};
+//# sourceMappingURL=logger.js.map

package/build/shield/bootRole.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Boot-time role resolution for MCP tool registration.
+ *
+ * Why this isn't an awaited API call:
+ *   The "right" way to know the cert's role is to call GET /v1/mcp/identity
+ *   on Shield API. But that requires the broker handshake to complete first
+ *   (cert+password → Authorizer → service-list), which takes 2-6 seconds in
+ *   the steady state. Claude Desktop has a ~4-8s window to respond to the
+ *   `initialize` MCP message, and tools must be registered synchronously
+ *   during that window. Awaiting the broker handshake at boot pushes us
+ *   close to that limit and makes the server fragile in slow-network
+ *   conditions.
+ *
+ *   Resolution: read the role from a fast local source (env var or local
+ *   hint file) at boot and rely on the Shield API's requireMcpRole
+ *   middleware (shipped in the prior commit) as the authoritative
+ *   defense-in-depth. A stale or tampered local hint can't actually
+ *   exfiltrate admin actions — the API still 403s.
+ *
+ * Resolution order (first match wins)
+ * ───────────────────────────────────
+ *   1. process.env.SHIELD_ROLE     — explicit override, highest precedence.
+ *                                    Useful for tests and for power users
+ *                                    who want to show all tools in local-
+ *                                    only mode for debugging.
+ *
+ *   2. ~/.blacksands/mcp-certs/.role  — written by setup.js when a cert is
+ *                                    issued. Captures the role chosen at
+ *                                    issuance time (which could be
+ *                                    'consumer' for developer/CI agents).
+ *
+ *   3. Mode-derived default        — local-only mode → 'consumer' (no
+ *                                    cert means no admin authority).
+ *                                    Other modes (stdio with bundle,
+ *                                    http-service) → 'master' for
+ *                                    backward compatibility — every cert
+ *                                    issued before migration 006 defaults
+ *                                    to master in the DB anyway.
+ *
+ * The local hint file is best-effort: if it's missing, malformed, or
+ * unreadable, fall through to the next resolution step rather than failing
+ * the boot. The API's requireMcpRole catches any mismatch.
+ */
+import type { Role } from "./identity";
+import type { DeploymentMode } from "../config";
+export interface BootRoleResolution {
+    role: Role;
+    source: "env" | "file" | "mode-default";
+    /** Plain-language string for the startup log so operators can see why. */
+    rationale: string;
+}
+/**
+ * Resolve the MCP server's role at boot time. Synchronous (no API call).
+ *
+ * The returned role drives which tools get registered. The Shield API
+ * still enforces RBAC at call-time via requireMcpRole, so a wrong answer
+ * here at worst surfaces extra tools to the LLM — never extra capability.
+ */
+export declare function resolveBootRole(mode: DeploymentMode): BootRoleResolution;
+//# sourceMappingURL=bootRole.d.ts.map

package/build/shield/bootRole.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Boot-time role resolution for MCP tool registration.
+ *
+ * Why this isn't an awaited API call:
+ *   The "right" way to know the cert's role is to call GET /v1/mcp/identity
+ *   on Shield API. But that requires the broker handshake to complete first
+ *   (cert+password → Authorizer → service-list), which takes 2-6 seconds in
+ *   the steady state. Claude Desktop has a ~4-8s window to respond to the
+ *   `initialize` MCP message, and tools must be registered synchronously
+ *   during that window. Awaiting the broker handshake at boot pushes us
+ *   close to that limit and makes the server fragile in slow-network
+ *   conditions.
+ *
+ *   Resolution: read the role from a fast local source (env var or local
+ *   hint file) at boot and rely on the Shield API's requireMcpRole
+ *   middleware (shipped in the prior commit) as the authoritative
+ *   defense-in-depth. A stale or tampered local hint can't actually
+ *   exfiltrate admin actions — the API still 403s.
+ *
+ * Resolution order (first match wins)
+ * ───────────────────────────────────
+ *   1. process.env.SHIELD_ROLE     — explicit override, highest precedence.
+ *                                    Useful for tests and for power users
+ *                                    who want to show all tools in local-
+ *                                    only mode for debugging.
+ *
+ *   2. ~/.blacksands/mcp-certs/.role  — written by setup.js when a cert is
+ *                                    issued. Captures the role chosen at
+ *                                    issuance time (which could be
+ *                                    'consumer' for developer/CI agents).
+ *
+ *   3. Mode-derived default        — local-only mode → 'consumer' (no
+ *                                    cert means no admin authority).
+ *                                    Other modes (stdio with bundle,
+ *                                    http-service) → 'master' for
+ *                                    backward compatibility — every cert
+ *                                    issued before migration 006 defaults
+ *                                    to master in the DB anyway.
+ *
+ * The local hint file is best-effort: if it's missing, malformed, or
+ * unreadable, fall through to the next resolution step rather than failing
+ * the boot. The API's requireMcpRole catches any mismatch.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveBootRole = resolveBootRole;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const HOME = os.homedir();
+const ROLE_HINT_FILE = path.join(HOME, ".blacksands", "mcp-certs", ".role");
+function sanitizeRole(raw) {
+    if (!raw)
+        return null;
+    const v = raw.trim().toLowerCase();
+    if (v === "master" || v === "consumer")
+        return v;
+    return null;
+}
+function readRoleHintFile() {
+    try {
+        if (!fs.existsSync(ROLE_HINT_FILE))
+            return null;
+        const text = fs.readFileSync(ROLE_HINT_FILE, "utf8");
+        return sanitizeRole(text);
+    }
+    catch {
+        // File exists but unreadable, or read failed — fall through.
+        return null;
+    }
+}
+/**
+ * Resolve the MCP server's role at boot time. Synchronous (no API call).
+ *
+ * The returned role drives which tools get registered. The Shield API
+ * still enforces RBAC at call-time via requireMcpRole, so a wrong answer
+ * here at worst surfaces extra tools to the LLM — never extra capability.
+ */
+function resolveBootRole(mode) {
+    // 1. Explicit env override.
+    const envRole = sanitizeRole(process.env.SHIELD_ROLE);
+    if (envRole) {
+        return {
+            role: envRole,
+            source: "env",
+            rationale: `SHIELD_ROLE=${envRole} in environment`,
+        };
+    }
+    // 2. Local hint file written by setup.js at cert-issuance time.
+    const fileRole = readRoleHintFile();
+    if (fileRole) {
+        return {
+            role: fileRole,
+            source: "file",
+            rationale: `${ROLE_HINT_FILE} reads "${fileRole}"`,
+        };
+    }
+    // 3. Mode-derived default.
+    if (mode === "local-only") {
+        return {
+            role: "consumer",
+            source: "mode-default",
+            rationale: "local-only mode has no cert; consumer is the safer default for an unauthenticated agent",
+        };
+    }
+    return {
+        role: "master",
+        source: "mode-default",
+        rationale: `${mode} mode with no SHIELD_ROLE / role-hint file; defaulting to master for backward compatibility (existing certs default to master via migration 006)`,
+    };
+}
+//# sourceMappingURL=bootRole.js.map