@secondlayer/sentinel 0.1.0

package/dist/credentials.d.ts

@@ -0,0 +1,29 @@
+export declare const CREDITS_API_URL = "https://api.secondlayer.tools";
+export type Session = {
+    token: string;
+    email: string;
+    accountId: string;
+    expiresAt: string;
+};
+export type TokenFile = {
+    token: string;
+    email?: string;
+};
+export type CredentialSource = "env" | "flag" | "token file" | "secondlayer session";
+export type Credential = {
+    token: string;
+    source: CredentialSource;
+};
+/** The secondlayer server whose session Sentinel shares. Same override env as the secondlayer CLI. */
+export declare const creditsUrl: () => string;
+export declare const sessionPath: () => string;
+export declare const tokenFilePath: () => string;
+export declare function readSession(url?: string): Promise<Session | null>;
+export declare function writeSession(session: Session, url?: string): Promise<void>;
+export declare function clearSession(url?: string): Promise<void>;
+export declare function readTokenFile(): Promise<TokenFile | null>;
+export declare const writeTokenFile: (file: TokenFile) => Promise<void>;
+export declare const clearTokenFile: () => Promise<void>;
+/** The credential to use, or null when there is none anywhere. `flag` is the CLI's --token. */
+export declare function resolveToken(flag?: string): Promise<Credential | null>;
+export declare const NOT_LOGGED_IN = "Not logged in. Run: sentinel login";

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** The package's SDK entry (`@secondlayer/sentinel`): the API client and the credential helpers. */
+export * from "./credentials";
+export * from "./sentinel-client";

package/dist/index.js

@@ -0,0 +1,306 @@
+// client/credentials.ts
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var CREDITS_API_URL = "https://api.secondlayer.tools";
+var creditsUrl = () => (process.env.SL_CREDITS_API_URL ?? CREDITS_API_URL).replace(/\/+$/, "");
+var dir = () => join(process.env.HOME || homedir(), ".secondlayer");
+var sessionPath = () => join(dir(), "session.json");
+var tokenFilePath = () => join(dir(), "sentinel.json");
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writePrivate(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.${process.pid}.tmp`);
+  await writeFile(tmp, `${JSON.stringify(data, null, 2)}
+`, { mode: 384, encoding: "utf8" });
+  await chmod(tmp, 384);
+  await rename(tmp, path);
+}
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isSession = (v) => isRecord(v) && typeof v.token === "string" && v.token !== "" && typeof v.email === "string";
+async function readSessionFile() {
+  const raw = await readJson(sessionPath());
+  if (isRecord(raw) && isRecord(raw.sessions))
+    return { sessions: raw.sessions };
+  if (isSession(raw))
+    return { sessions: { [CREDITS_API_URL]: raw } };
+  return { sessions: {} };
+}
+async function readSession(url = creditsUrl()) {
+  const s = (await readSessionFile()).sessions[url.replace(/\/+$/, "")];
+  return isSession(s) ? s : null;
+}
+async function writeSession(session, url = creditsUrl()) {
+  const file = await readSessionFile();
+  file.sessions[url.replace(/\/+$/, "")] = session;
+  await writePrivate(sessionPath(), file);
+}
+async function clearSession(url = creditsUrl()) {
+  const file = await readSessionFile();
+  delete file.sessions[url.replace(/\/+$/, "")];
+  if (Object.keys(file.sessions).length === 0)
+    await rm(sessionPath(), { force: true });
+  else
+    await writePrivate(sessionPath(), file);
+}
+async function readTokenFile() {
+  const raw = await readJson(tokenFilePath());
+  return isRecord(raw) && typeof raw.token === "string" && raw.token !== "" ? { token: raw.token, email: typeof raw.email === "string" ? raw.email : undefined } : null;
+}
+var writeTokenFile = (file) => writePrivate(tokenFilePath(), file);
+var clearTokenFile = () => rm(tokenFilePath(), { force: true });
+async function resolveToken(flag) {
+  const env = process.env.SENTINEL_API_KEY;
+  if (env)
+    return { token: env, source: "env" };
+  if (flag)
+    return { token: flag, source: "flag" };
+  const file = await readTokenFile();
+  if (file)
+    return { token: file.token, source: "token file" };
+  const session = await readSession();
+  return session ? { token: session.token, source: "secondlayer session" } : null;
+}
+var NOT_LOGGED_IN = "Not logged in. Run: sentinel login";
+// client/sentinel-client.ts
+var DEFAULT_BASE_URL = "https://api.runsentinel.app";
+
+class SentinelError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SentinelError";
+  }
+}
+var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : `asset:${s.asset}`;
+function subjectName(s, units) {
+  if (s.kind === "fn")
+    return s.fn;
+  if (units?.symbol)
+    return units.symbol;
+  if (s.asset.toLowerCase() === "stx")
+    return "STX";
+  return s.asset.split("::")[1] ?? s.asset;
+}
+
+class SubjectError extends Error {
+  candidates;
+  constructor(message, candidates) {
+    super(message);
+    this.candidates = candidates;
+    this.name = "SubjectError";
+  }
+}
+function groupSubjects(watches) {
+  const out = new Map;
+  for (const w of watches) {
+    const key = subjectKey(w.subject);
+    const g = out.get(key) ?? { key, name: subjectName(w.subject, w.units), watches: [] };
+    g.watches.push(w);
+    out.set(key, g);
+  }
+  return [...out.values()];
+}
+function resolveSubject(watches, name) {
+  const groups = groupSubjects(watches);
+  const q = name.trim().toLowerCase();
+  const hits = groups.filter((g) => {
+    const s = g.watches[0].subject;
+    const asset = s.kind === "asset" ? s.asset.toLowerCase() : null;
+    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || asset === q || asset !== null && asset.split("::")[1] === q;
+  });
+  if (hits.length === 1)
+    return hits[0];
+  if (hits.length === 0) {
+    const names = groups.map((g) => g.name);
+    throw new SubjectError(`No watched subject called "${name}". Watched: ${names.join(", ") || "nothing yet"}`, names);
+  }
+  const names = hits.map((g) => g.key);
+  throw new SubjectError(`"${name}" matches more than one subject: ${names.join(", ")}`, names);
+}
+var group = (digits) => digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+function toUnits(base, decimals) {
+  if (!/^\d+$/.test(base))
+    return base;
+  const digits = base.replace(/^0+(?=\d)/, "");
+  if (decimals === 0)
+    return group(digits);
+  const padded = digits.padStart(decimals + 1, "0");
+  const whole = padded.slice(0, padded.length - decimals);
+  const frac = padded.slice(padded.length - decimals).replace(/0+$/, "");
+  return frac ? `${group(whole)}.${frac}` : group(whole);
+}
+function amountText(base, units) {
+  return units ? `${toUnits(base, units.decimals)} ${units.symbol}` : `${group(base)} base units`;
+}
+var WINDOWS = { 720: "1 hour", 4320: "6 hours", 17280: "1 day" };
+var windowText = (blocks) => WINDOWS[blocks] ?? `${blocks.toLocaleString("en-US")} blocks`;
+function ruleSummary(rule, units) {
+  switch (rule.kind) {
+    case "signature":
+      return `verified finding: ${rule.findingTitle}`;
+    case "audit":
+      return rule.triggerClass === "governance.proposal_submitted" ? "reviews each governance proposal" : "reviews each upgrade";
+    case "callerAllowlist":
+      return rule.allow.length ? `any call from outside ${rule.allow.length} allowed principal(s)` : "any call";
+    case "outflowSingle":
+      return rule.amount ? `a single outflow of ${amountText(rule.amount, units)} or more` : "every outflow";
+    case "outflowWindow":
+      return `${amountText(rule.amount, units)} or more out within ${windowText(rule.blocks)}`;
+    case "valueNewActor":
+      return `${amountText(rule.amount, units)} or more to or from a new actor`;
+    case "actor": {
+      const names = {
+        newCaller: "a new caller",
+        firstCall: "a first call",
+        roleChange: "a role change"
+      };
+      return `${rule.signals.map((x) => names[x]).join(", ")}${rule.allow.length ? ` (outside ${rule.allow.length} allowed)` : ""}`;
+    }
+  }
+}
+function kindTag(rule) {
+  switch (rule.kind) {
+    case "signature":
+      return "finding";
+    case "outflowSingle":
+    case "outflowWindow":
+    case "valueNewActor":
+      return "outflow";
+    case "callerAllowlist":
+    case "actor":
+      return "who-acts";
+    case "audit":
+      return rule.triggerClass === "governance.proposal_submitted" ? "governance" : "upgrade";
+  }
+}
+function subjectStatus(ws) {
+  const st = ws.map((w) => w.status);
+  if (st.includes("live"))
+    return "live";
+  return st.length > 0 && st.every((x) => x === "paused") ? "paused" : "suggested";
+}
+var isMutableRule = (rule) => rule.kind !== "signature" && rule.kind !== "audit";
+function mutedUntilOf(w, now = Date.now()) {
+  const at = w.delivery.mutedUntil;
+  return at && Date.parse(at) > now ? at : null;
+}
+function createClient(opts) {
+  const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const authHeader = () => ({ authorization: `Bearer ${opts.token}` });
+  async function call(method, path, body) {
+    const res = await doFetch(`${baseUrl}${path}`, {
+      method,
+      headers: {
+        ...authHeader(),
+        ...body === undefined ? {} : { "content-type": "application/json" }
+      },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok)
+      throw new SentinelError(res.status, data?.error ?? `HTTP ${res.status}`);
+    return data;
+  }
+  const plan = (id) => `/v1/plans/${encodeURIComponent(id)}`;
+  const appPlan = (id) => `/plan/${encodeURIComponent(id)}`;
+  return {
+    me: () => call("GET", "/v1/me"),
+    plans: async () => (await call("GET", "/v1/plans")).plans,
+    plan: (id) => call("GET", plan(id)),
+    finding: (id, n) => call("GET", `${plan(id)}/findings/${n}`),
+    runs: async (id) => (await call("GET", `${plan(id)}/runs`)).runs,
+    alerts: async (contract) => (await call("GET", contract ? `/v1/alerts?contract=${encodeURIComponent(contract)}` : "/v1/alerts")).alerts,
+    reverify: (id) => call("POST", `/plan/${encodeURIComponent(id)}/reverify`),
+    reproduce: (id, finding) => call("POST", `/plan/${encodeURIComponent(id)}/reproduce`, { finding }),
+    challenge: (id, finding, reason) => call("POST", `${appPlan(id)}/challenge`, { finding, reason }),
+    replay: (id, finding) => call("POST", `${appPlan(id)}/replay`, { finding }),
+    directed: (id, prompt) => call("POST", `${appPlan(id)}/directed`, { prompt }),
+    testsFromRepo: (id) => call("POST", `${appPlan(id)}/tests`, { fromRepo: true }),
+    previewPlan: (contractId) => call("POST", "/plan/preview", { contractId }),
+    createPlan: (contractId) => call("POST", "/plan", { contractId }),
+    billing: () => call("GET", "/billing"),
+    watches: (planId) => call("GET", `${appPlan(planId)}/watches`),
+    setRule: (planId, watchId, rule) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/rule`, { rule }),
+    addRule: (planId, subject, rule) => call("POST", `${appPlan(planId)}/watches`, { subject, rule }),
+    setWatches: (planId, watchIds, on) => call("POST", `${appPlan(planId)}/watches/state`, {
+      watchIds,
+      on
+    }),
+    mute: (planId, watchId, mutedUntil) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { mutedUntil }),
+    muteAlert: (alertId, hours) => call("POST", `/alerts/${encodeURIComponent(alertId)}/mute`, { hours }),
+    parseRule: (planId, subject, text) => call("POST", `${appPlan(planId)}/rules/parse`, { subject, text }),
+    monitorSettings: (planId, settings) => call("POST", `${appPlan(planId)}/monitor`, settings),
+    testAlert: (planId, dest = {}) => call("POST", `${appPlan(planId)}/testalert`, dest),
+    watchContract: (contractId) => call("POST", "/contracts/watch", {
+      contractId
+    }),
+    stopMonitoring: (planId) => call("DELETE", `${appPlan(planId)}/monitor`)
+  };
+}
+var HOUR_MS = 3600000;
+var muteEnd = (hours) => new Date(Date.now() + Math.min(hours * HOUR_MS, 7 * 24 * HOUR_MS - 60000)).toISOString();
+async function watchContext(client, planId) {
+  const plan = await client.plan(planId);
+  return {
+    planId,
+    contractId: plan.contractId,
+    access: plan.access,
+    watches: (await client.watches(planId)).watches
+  };
+}
+async function savedMonitor(client, planId) {
+  const m = (await client.plan(planId)).monitor;
+  if (!m?.status)
+    throw new SentinelError(409, "Turn monitoring on first.");
+  return m;
+}
+var savedChoices = async (client, planId) => (await savedMonitor(client, planId)).watches;
+async function planOfContract(client, contractId) {
+  const me = await client.me();
+  const hit = [...me.watching ?? [], ...me.claims ?? []].find((c) => c.contractId === contractId);
+  if (!hit)
+    throw new SentinelError(404, `You aren't monitoring ${contractId}.`);
+  return hit.planId;
+}
+export {
+  CREDITS_API_URL,
+  DEFAULT_BASE_URL,
+  NOT_LOGGED_IN,
+  SentinelError,
+  SubjectError,
+  clearSession,
+  clearTokenFile,
+  createClient,
+  creditsUrl,
+  groupSubjects,
+  isMutableRule,
+  kindTag,
+  muteEnd,
+  mutedUntilOf,
+  planOfContract,
+  readSession,
+  readTokenFile,
+  resolveSubject,
+  resolveToken,
+  ruleSummary,
+  savedChoices,
+  savedMonitor,
+  sessionPath,
+  subjectKey,
+  subjectName,
+  subjectStatus,
+  toUnits,
+  tokenFilePath,
+  watchContext,
+  writeSession,
+  writeTokenFile
+};