Incident controls

Switch off one action, route, interface, driver or agent, put the app in read-only mode, or sign everyone out, in seconds and without a deploy.

incident:
  kill: []
  read-only: false
  read-only-allow: [/api/auth/*, /api/webhooks/*]
  sessions-after: null
  tenants: {}
  expires: {}

import { incident } from "mainsdk";

// what is switched off right now, from memory
const state = incident.status();
console.log(state.controls.length);

// from an admin screen: needs incident.manage and a fresh passkey sign-in
await incident.set(req, { kill: ["action:orders.refund"] }, { reason: "refund abuse, ticket 812", expires: "4h" });

incident:
  driver: builtin

Quick start

incident:
  kill: []
  read-only: false
  read-only-allow: [/api/auth/*, /api/webhooks/*]
  sessions-after: null
  tenants: {}
  expires: {}

import { incident } from "mainsdk";

declare const req: Request;   // the request of your admin route

// what is switched off right now, from memory
const state = incident.status();
console.log(state.controls.length);

// from an admin screen: needs incident.manage and a fresh passkey sign-in
await incident.set(req, { kill: ["action:orders.refund"] }, { reason: "refund abuse, ticket 812", expires: "4h" });

Configuration

Deployed values are usually empty; controls arrive as main.incident.* pushes. See the incident.* rows in main.yaml reference.

What you get

• A control only tightens what main.yaml allows; a push cannot open anything
• Reaches every instance through the config store and survives restarts
• Audited with who, why and when; cleared by deleting it
• Never reads the store in a request; fail static

Calls

What a control does

A kill target is action:<name>, route:<path>, interface:<name>, driver:<id>, agent:<name> or tool:<name>. Some interfaces cannot be killed, because the app needs them to run and to recover. An unknown or malformed target is MAIN-INCIDENT-0004.

Only tighter

Controls arrive as pushes of main.incident.* through the config driver, which needs a write call. A push is accepted only if it is tighter than or equal to what main.yaml allows: adding kill targets, read-only: true, a later sessions-after, and expiry instants that do not move earlier. A push that would open something is refused with MAIN-CONFIG-0021, and a malformed one with MAIN-CONFIG-0020; the app keeps the value it had. So a leaked push credential cannot use incident controls to loosen the app.

Every change is audited as an incident.control record with the control, target, reason, actor and env, and is also written as a security event. A control with no expires that has been in force for 24 hours is MAIN-INCIDENT-0007 (a warning in mainsdk check, and in the log once an hour).

CLI

mainsdk incident on kill action:orders.refund --reason "refund abuse, ticket 812" --expires 4h --env prod
mainsdk incident on read-only --reason "session store copied"
mainsdk incident on sign-out --tenant tnt_01JD --reason "leaked token"
mainsdk incident off kill action:orders.refund --reason "fixed"
mainsdk incident status --json

The command refuses without --reason (MAIN-INCIDENT-0005) and prints when the change will have reached every instance: within 5 seconds for a driver with a change stream, else within the driver's refresh interval.

Fail static

A control is held in memory on each instance and the request path reads memory only. If the config store is down, instances keep the controls they last had, and a restart reloads them from the last good value. No incident control ever makes a request wait on the store.

Errors and checks

A push that would loosen what main.yaml allows is MAIN-CONFIG-0021; a malformed one is MAIN-CONFIG-0020. See check codes and errors for all of them.

Swapping drivers

There is one driver, builtin, and it pushes through the config driver. Controls reach other instances through whichever config driver the app uses (files, local or redis); a driver with no write method makes mainsdk incident on fail with MAIN-INCIDENT-0005. See Swap a driver.

Testing

createTestApp accepts a configDriver, so two apps can share one in-memory store. Push main.incident.kill to it, refresh both apps and the killed action is refused with MAIN-INCIDENT-0001. The spec's criteria are covered this way in packages/sdk/test/incident-controls.test.ts.

Next

• Config and secrets
• Security events
• Main.yaml reference