@secondlayer/sentinel 0.1.0

package/dist/sentinel-client.d.ts

@@ -0,0 +1,384 @@
+/**
+ * Client for the Sentinel v1 API (docs/api.md). Shared by the MCP server and the CLI. No dependencies:
+ * global fetch. Auth is one function, `authHeader`, so another credential can be swapped in later.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.runsentinel.app";
+export declare class SentinelError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export type RunEvent = {
+    at: number;
+    kind: string;
+    state?: string;
+    name?: string;
+    detail?: string;
+};
+export type Claim = {
+    contractId: string;
+    planId: string;
+    createdAt: string;
+    access: "verified" | "claimed";
+    status: string;
+    watches: number;
+    monitoring: string;
+    finishedAt: string | null;
+    evidence: {
+        tiles: string[];
+        worst: {
+            severity: string;
+            evidence: string;
+        } | null;
+    };
+};
+export type RunSummary = {
+    id: string;
+    kind: string;
+    status: string;
+    startedAt: string;
+    finishedAt: string | null;
+    events: RunEvent[];
+};
+export type Finding = {
+    title: string;
+    headline?: string;
+    severity: string;
+    class: string;
+    verdict: string;
+    disposition: string;
+    poc?: string;
+    [field: string]: unknown;
+};
+/** A plan at the caller's access level: `access` is absent on the teaser. */
+export type PlanView = {
+    view: string;
+    access?: "verified" | "claimed";
+    id: string;
+    contractId: string;
+    status: string;
+    report?: {
+        findings?: Finding[];
+        plan?: {
+            watches?: unknown[];
+        };
+        [field: string]: unknown;
+    } | null;
+    runs?: RunSummary[];
+    [field: string]: unknown;
+};
+export type Alert = {
+    id: string;
+    contractId: string;
+    level: string;
+    severity: string;
+    summary: string;
+    createdAt: string;
+    read: boolean;
+    [field: string]: unknown;
+};
+/** A watch's rule. Amounts are token base units, as digit strings. */
+export type WatchRule = {
+    kind: "signature";
+    findingTitle: string;
+    severity: string;
+    asset?: string;
+    precondition?: string;
+} | {
+    kind: "callerAllowlist";
+    allow: string[];
+} | {
+    kind: "outflowSingle";
+    amount: string | null;
+} | {
+    kind: "audit";
+    triggerClass: string;
+} | {
+    kind: "outflowWindow";
+    amount: string;
+    blocks: number;
+} | {
+    kind: "actor";
+    signals: ("newCaller" | "firstCall" | "roleChange")[];
+    allow: string[];
+} | {
+    kind: "valueNewActor";
+    amount: string;
+};
+/** The rule kinds a caller can add or edit (the others come from a verified finding or governance). */
+export type EditableRule = Exclude<WatchRule, {
+    kind: "signature" | "audit";
+}>;
+export type WatchSubject = {
+    kind: "fn";
+    fn: string;
+} | {
+    kind: "asset";
+    asset: string;
+};
+export type WatchStatus = "suggested" | "live" | "paused";
+export type Units = {
+    decimals: number;
+    symbol: string;
+};
+export type WatchDelivery = {
+    severity: string;
+    routes: string[];
+    cooldownBlocks: number;
+    mutedUntil: string | null;
+};
+/** One of the caller's own watches on a plan's contract, as `GET /plan/:id/watches` returns it. */
+export type StoredWatch = {
+    id: string;
+    contractId: string;
+    subject: WatchSubject;
+    rule: WatchRule;
+    suggestedRule: WatchRule | null;
+    delivery: WatchDelivery;
+    provenance: {
+        kind: string;
+        ref: string;
+        note?: string;
+    }[];
+    status: WatchStatus;
+    title: string;
+    reason: string;
+    createdAt: string;
+    updatedAt: string;
+    units: Units | null;
+};
+export type WatchesView = {
+    watches: StoredWatch[];
+    events: {
+        id: string;
+        watchId: string;
+        action: "proposed" | "applied" | "rejected" | "muted" | "cooldown";
+        rule: WatchRule | null;
+        note: string | null;
+        createdAt: string;
+    }[];
+    seed: Record<string, {
+        historyCalls: number;
+        throughBlock: number | null;
+        seededAt: string;
+    }>;
+};
+/** What starting to monitor a contract (`POST /contracts/watch`) answers: the account's own set. */
+export type StartedMonitoring = {
+    contractId: string;
+    planId: string;
+    status: "draft" | "requested" | "live";
+    watches: StoredWatchView[];
+    webhookUrl: string | null;
+    slackUrl: string | null;
+    emailAlerts: boolean;
+    hasSigningSecret: boolean;
+};
+type StoredWatchView = Pick<StoredWatch, "id" | "subject" | "rule" | "status" | "title">;
+export type WatchChoice = {
+    watchId?: string;
+    fn: string;
+    on: boolean;
+    threshold?: string;
+};
+export type MonitorSettingsInput = {
+    deployer?: string;
+    watches?: WatchChoice[];
+    webhookUrl?: string;
+    slackUrl?: string;
+    emailAlerts?: boolean;
+};
+export type ParsedRules = {
+    rules: EditableRule[];
+    elsewhere: {
+        phrase: string;
+        subjectKey: string;
+    }[];
+};
+export type DeliveryResult = {
+    to: "email" | "webhook" | "slack";
+    ok: boolean;
+    detail: string;
+};
+export declare const subjectKey: (s: WatchSubject) => string;
+/** The subject's display name: the fn name, or the token's symbol (never the raw token id). */
+export declare function subjectName(s: WatchSubject, units: Units | null): string;
+type HasSubject = {
+    subject: WatchSubject;
+    units: Units | null;
+};
+export type SubjectMatch<W extends HasSubject> = {
+    key: string;
+    name: string;
+    watches: W[];
+};
+/** Thrown when a name matches no subject, or more than one. `candidates` are the display names to choose from. */
+export declare class SubjectError extends Error {
+    readonly candidates: string[];
+    constructor(message: string, candidates: string[]);
+}
+/** The watches grouped by subject, in first-seen order. */
+export declare function groupSubjects<W extends HasSubject>(watches: W[]): SubjectMatch<W>[];
+/**
+ * The watches on the subject `name` points at: its display name (fn name, token symbol, or the part
+ * after `::`), its subjectKey (`fn:…` / `asset:…`) or a full asset id, case-insensitive. A name that
+ * matches nothing, or more than one subject, throws a SubjectError listing the candidates.
+ */
+export declare function resolveSubject<W extends HasSubject>(watches: W[], name: string): SubjectMatch<W>;
+/** `("1200000000000", 6)` → `"1,200,000"`. Anything that isn't a digit string comes back as it was. */
+export declare function toUnits(base: string, decimals: number): string;
+/** One line for a rule, in token units where the decimals are known. */
+export declare function ruleSummary(rule: WatchRule, units: Units | null): string;
+export type WatchKindTag = "finding" | "outflow" | "who-acts" | "governance" | "upgrade";
+/** The plain tag a rule is listed under. */
+export declare function kindTag(rule: WatchRule): WatchKindTag;
+/** A subject's status from its rules: live if any is, else paused if all are, else suggested. */
+export declare function subjectStatus(ws: {
+    status: WatchStatus;
+}[]): WatchStatus;
+/** Whether a rule's watch can be muted: a verified finding's and a governance review's can't. */
+export declare const isMutableRule: (rule: WatchRule) => boolean;
+/** The watch's mute end while it is in the future, else null. */
+export declare function mutedUntilOf(w: {
+    delivery: WatchDelivery;
+}, now?: number): string | null;
+/** `POST /plan/preview`: what a paste would plan. Nothing starts and nothing is charged. */
+export type PlanPreview = {
+    kind: "deployed" | "prelaunch";
+    contractId: string;
+    planId: string | null;
+    owned: boolean;
+    [field: string]: unknown;
+};
+/** `GET /billing`: balance and the prices the API charges (USD). Null until the account is linked. */
+export type BillingView = {
+    enabled: boolean;
+    linked: boolean;
+    balanceUsd: number | null;
+    prices: {
+        run: number;
+        deepAudit: number;
+        monitoredEvent: number;
+    } | null;
+    unavailable: boolean;
+    [field: string]: unknown;
+};
+export type StartedRun = {
+    planId: string;
+    existing?: boolean;
+};
+export type ClientOptions = {
+    baseUrl?: string;
+    token: string;
+    fetch?: typeof globalThis.fetch;
+};
+export declare function createClient(opts: ClientOptions): {
+    me: () => Promise<Record<string, unknown>>;
+    plans: () => Promise<Claim[]>;
+    plan: (id: string) => Promise<PlanView>;
+    finding: (id: string, n: number) => Promise<Finding>;
+    runs: (id: string) => Promise<RunSummary[]>;
+    alerts: (contract?: string) => Promise<Alert[]>;
+    reverify: (id: string) => Promise<{
+        planId: string;
+        existing?: boolean;
+    }>;
+    reproduce: (id: string, finding: number) => Promise<{
+        planId: string;
+        existing?: boolean;
+    }>;
+    challenge: (id: string, finding: number, reason: string) => Promise<StartedRun>;
+    replay: (id: string, finding: number) => Promise<StartedRun>;
+    directed: (id: string, prompt: string) => Promise<StartedRun>;
+    /** Run the Clarinet suite from a pre-launch plan's repo in the sandbox. */
+    testsFromRepo: (id: string) => Promise<StartedRun>;
+    /** What a paste would plan. Writes and charges nothing. */
+    previewPlan: (contractId: string) => Promise<PlanPreview>;
+    /** Start a plan for a contract. Spends balance (charged only if it finishes), so preview first. */
+    createPlan: (contractId: string) => Promise<{
+        planId: string;
+        status: string;
+        cached: boolean;
+    }>;
+    billing: () => Promise<BillingView>;
+    watches: (planId: string) => Promise<WatchesView>;
+    /** Set a new rule for a watch. Applies now. */
+    setRule: (planId: string, watchId: string, rule: EditableRule) => Promise<{
+        watch: StoredWatch;
+    }>;
+    /** Add a rule kind to a subject Sentinel already watches. Applies now. */
+    addRule: (planId: string, subject: WatchSubject, rule: EditableRule) => Promise<{
+        watch: StoredWatch;
+    }>;
+    /** Turn watches on or off. Applies now. Every other choice is kept. */
+    setWatches: (planId: string, watchIds: string[], on: boolean) => Promise<{
+        monitoring: string | null;
+    }>;
+    /** Mute a watch until a time (at most 7 days out), or clear its mute with null. Takes effect at once. */
+    mute: (planId: string, watchId: string, mutedUntil: string | null) => Promise<{
+        watch: StoredWatch;
+    }>;
+    /** Mute the watch behind an alert for 1, 24 or 168 hours; 0 clears. */
+    muteAlert: (alertId: string, hours: 0 | 1 | 24 | 168) => Promise<{
+        mutedUntil: string | null;
+        watchTitle: string;
+    }>;
+    /** Read a sentence as rule proposals for one subject. Writes nothing. */
+    parseRule: (planId: string, subject: WatchSubject, text: string) => Promise<ParsedRules>;
+    monitorSettings: (planId: string, settings: MonitorSettingsInput) => Promise<{
+        monitoring: string | null;
+        signingSecret?: string;
+    }>;
+    /** Send a sample alert to email plus the saved (or given) webhook and Slack. */
+    testAlert: (planId: string, dest?: {
+        webhookUrl?: string;
+        slackUrl?: string;
+        emailAlerts?: boolean;
+    }) => Promise<{
+        results: DeliveryResult[];
+    }>;
+    /** Start monitoring a deployed contract (idempotent): its plan id is where to manage it. */
+    watchContract: (contractId: string) => Promise<StartedMonitoring | {
+        planId: string;
+        status: string;
+    }>;
+    /** Stop monitoring a plan's contract: your watches, alerts and settings for it are removed. */
+    stopMonitoring: (planId: string) => Promise<{
+        ok: boolean;
+    }>;
+};
+export type SentinelClient = ReturnType<typeof createClient>;
+/** A mute end `hours` out, a minute inside the 7-day limit so clock skew can't tip it over. */
+export declare const muteEnd: (hours: number) => string;
+/** What a plan's watches are to this caller: the account's own set on that contract. */
+export type WatchContext = {
+    planId: string;
+    contractId: string;
+    /** The plan's access level for this caller; a claimed one hides exploit detail. */
+    access: PlanView["access"];
+    watches: StoredWatch[];
+};
+/** The caller's watches for a plan. */
+export declare function watchContext(client: SentinelClient, planId: string): Promise<WatchContext>;
+export type SavedMonitor = {
+    status: string | null;
+    watches: {
+        watchId?: string;
+        fn: string;
+        on: boolean;
+        threshold?: string;
+    }[] | null;
+    webhookUrl: string | null;
+    slackUrl: string | null;
+    emailAlerts: boolean;
+};
+/** The account's saved monitoring settings (on the plan view). Refuses before monitoring is turned on. */
+export declare function savedMonitor(client: SentinelClient, planId: string): Promise<SavedMonitor>;
+export declare const savedChoices: (client: SentinelClient, planId: string) => Promise<{
+    watchId?: string;
+    fn: string;
+    on: boolean;
+    threshold?: string;
+}[] | null>;
+/** The plan id of a contract the account claims or monitors, from its own list. */
+export declare function planOfContract(client: SentinelClient, contractId: string): Promise<string>;
+export {};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@secondlayer/sentinel",
+  "version": "0.1.0",
+  "description": "Sentinel from a terminal or an agent: the CLI, an MCP server and a client for your Stacks contract monitoring.",
+  "license": "MIT",
+  "repository": "https://runsentinel.app/docs",
+  "homepage": "https://runsentinel.app/docs",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "sentinel": "dist/cli.js",
+    "sentinel-mcp": "dist/mcp.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  }
+}