toolroll 0.9.43 → 0.9.45

package/dist/operate-remote.d.ts

@@ -0,0 +1,98 @@
+import type { Store } from "./store.js";
+import type { LedgerSource } from "./action-ledger.js";
+import { type CommandRow } from "./surface.js";
+/** Who a remote call is, as the transport proved it from an `so_` token. */
+export type Principal = {
+    kind: "person";
+    account: string;
+    /** The account's credential generation when the token was checked. */
+    generation: number;
+    scope: "read" | "act";
+    tokenId: string;
+    /** The projects the person may use (null: all of them). */
+    projects: string[] | null;
+};
+export type RemoteSource = Extract<LedgerSource, "api" | "mcp">;
+export { activeRemote, withRemote, type RemoteRun } from "./remote-run.js";
+/** Thrown where a remote run reaches something only this machine's owner may use; the command ends refused. */
+export declare class RemoteRefusal extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+export declare const REMOTE_MESSAGES: {
+    readonly "step-up": "Approvals, people and policy changes aren't taken from a token: approve in the console or chat.";
+    readonly no: "That command only runs on the server's own machine, not for a remote caller.";
+    readonly unknown: "That isn't a command a remote caller can run.";
+    readonly read: "Your token reads only. Use an act token for this command.";
+    readonly stale: "Your sign-in changed since this token was checked. Sign in again.";
+    readonly credential: "Remote commands run as your token's person: leave out --as, --token, --db and other credential or file flags.";
+    readonly project: "Name a project you have access to with --repo (its path on the server).";
+    readonly installation: "This command covers every project; it needs access to all projects.";
+    readonly files: "Send that file with the request; the server reads no paths of its own for you.";
+};
+/**
+ * How a "yes" command finds the project it touches, before it runs. Any --repo given is checked too.
+ *  installation — reads or acts across every project: only for someone with access to all of them.
+ *  listing — lists across projects: someone with access to all of them sees everything, as locally; anyone else
+ *    sees only their own projects (the run's `lens`), with every count taken over those projects alone.
+ *  repo — needs --repo, naming a project the server knows and the person may use.
+ *  references — the audited arguments resolve every resource to its stored project before dispatch.
+ *  self — the command already narrows to the person's own projects (their access is passed in).
+ *  global — touches no project's data.
+ */
+export type RemoteScope = {
+    kind: "installation";
+} | {
+    kind: "listing";
+} | {
+    kind: "repo";
+} | {
+    kind: "references";
+} | {
+    kind: "self";
+} | {
+    kind: "global";
+};
+/** Every "yes" row's scope. The remote test holds this to the guide's "yes" rows exactly. */
+export declare const REMOTE_SCOPES: ReadonlyMap<string, RemoteScope>;
+/**
+ * Why each "installation" row still needs access to every project rather than listing a person's own. The remote
+ * test holds this to the table's "installation" rows exactly, so a newly allowed cross-project command has to be
+ * scoped as a listing or stated here; it cannot skip project scoping by omission.
+ */
+export declare const REMOTE_ALL_PROJECTS_ONLY: ReadonlyMap<string, "installation-wide" | "not yet scoped">;
+/** The projects a listing or task reference may disclose: null for someone with access to all of them. */
+export declare function remoteLensOf(store: Store, scope: RemoteScope, allows: (repo: string | null) => boolean): readonly string[] | null;
+/** Flags a remote caller never passes: who they are comes from the token, and the server reads and writes no paths for them. */
+export declare const REMOTE_REFUSED_FLAGS: ReadonlySet<string>;
+/**
+ * The guide row an argv is: the longest invocation its command and leading positionals spell. A command with no
+ * row of its own runs nowhere remotely (backup, restore, storage, ledger, policy and the rest).
+ */
+export declare function remoteRowOf(command: string, positional: readonly string[]): CommandRow | null;
+/**
+ * Re-prove the principal now, against the store: the account still stands at the same generation, the token is
+ * the person's, unrevoked and unexpired, and the scope is no wider than the token's or the person's role.
+ */
+export declare function reproveRemote(store: Store, principal: Principal, now: Date): {
+    ok: true;
+    scope: "read" | "act";
+    tokenName: string;
+} | {
+    ok: false;
+};
+/** Whether the person may use `repo`: inside their token's projects and their account's current access. Null is "every project". */
+export declare function remoteAllows(store: Store, principal: Principal, repo: string | null): boolean;
+/** The project a command touches, or why it may not run: --repo must be a project the server knows, by its exact path. */
+export declare function remoteProjectOf(store: Store, run: {
+    allows: (repo: string | null) => boolean;
+}, scope: RemoteScope, positional: readonly string[], repos: readonly string[], invocation: string, flags: ReadonlyMap<string, string | true>, files: Readonly<Record<string, string>>): {
+    ok: true;
+    repo: string | null;
+    taskId: string | null;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export declare function remoteSecret(): string;

package/dist/operate-remote.js

@@ -0,0 +1,145 @@
+/**
+ * Running a command on a central server for a person who signed in with their own API token
+ * (`runOperateAs` in operate.ts). The machine contract is the allowlist: every row states `remote`
+ * (src/surface.ts), and only "yes" rows run. This module holds what that boundary decides before any
+ * command code runs — which row an argv is, whether the person and token still stand, and which
+ * project the command touches — and the per-run state the credential paths in operate.ts consult so
+ * a remote run is always the person and never this machine's owner.
+ */
+import { randomBytes } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { COMMAND_GUIDE } from "./surface.js";
+import { remoteArgumentsOf, REMOTE_NOT_FOUND } from "./operate-remote-arguments.js";
+export { activeRemote, withRemote } from "./remote-run.js";
+/** Thrown where a remote run reaches something only this machine's owner may use; the command ends refused. */
+export class RemoteRefusal extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+export const REMOTE_MESSAGES = {
+    "step-up": "Approvals, people and policy changes aren't taken from a token: approve in the console or chat.",
+    no: "That command only runs on the server's own machine, not for a remote caller.",
+    unknown: "That isn't a command a remote caller can run.",
+    read: "Your token reads only. Use an act token for this command.",
+    stale: "Your sign-in changed since this token was checked. Sign in again.",
+    credential: "Remote commands run as your token's person: leave out --as, --token, --db and other credential or file flags.",
+    project: "Name a project you have access to with --repo (its path on the server).",
+    installation: "This command covers every project; it needs access to all projects.",
+    files: "Send that file with the request; the server reads no paths of its own for you.",
+};
+const installation = { kind: "installation" }, repo = { kind: "repo" }, self = { kind: "self" }, global = { kind: "global" };
+const references = { kind: "references" }, listing = { kind: "listing" };
+/** Every "yes" row's scope. The remote test holds this to the guide's "yes" rows exactly. */
+export const REMOTE_SCOPES = new Map([
+    ["status", listing], ["integrations", installation], ["ready", listing], ["grants", installation], ["sync", installation],
+    ["gaps", repo], ["task add", repo],
+    ...["ask", "checks", "add-tests", "show", "wait", "complete", "revise", "state", "block", "unblock", "next", "steer", "assign", "scope", "plan", "hold",
+        "unhold", "require", "requeue", "review", "repair", "route", "reopen", "stop", "resume"].map(action => [`task ${action}`, references]),
+    ["check-progress", references],
+    ["task list", listing],
+    ["runner list", installation], ["coordinator list", installation], ["outbox list", installation], ["incident list", installation], ["incident resolve", installation],
+    ["cap list", repo], ["cap add", repo],
+    ...["list", "show", "add", "refresh", "pause", "resume", "run-now"].map(action => [`routine ${action}`, installation]),
+    ["config show", installation], ["verify show", repo], ["intake show", installation], ["intake run", installation], ["intake preview", installation],
+    ["intake pr-comments", installation], ["template list", installation], ["template show", installation], ["contest show", installation],
+    ["contest exclude", installation], ["webhook status", installation], ["webhook test", installation], ["review show", installation],
+    ["chat-approval show", self], ["chat-approval off", self],
+    ["knowledge search", repo], ["knowledge impact", repo], ["knowledge refresh", repo],
+    ...["search", "decisions", "show", "decide", "retire", "review", "status"].map(action => [`memory ${action}`, self]),
+    ...["list", "show", "export", "create", "edit", "trigger add", "trigger pause", "trigger resume", "trigger remove", "card add", "archive"]
+        .map(action => [`flows ${action}`, self]),
+    ["models status", global], ["models list", global],
+]);
+/**
+ * Why each "installation" row still needs access to every project rather than listing a person's own. The remote
+ * test holds this to the table's "installation" rows exactly, so a newly allowed cross-project command has to be
+ * scoped as a listing or stated here; it cannot skip project scoping by omission.
+ */
+export const REMOTE_ALL_PROJECTS_ONLY = new Map([
+    // Settings, connections and acts that belong to the installation as a whole, not to any one project.
+    ...["integrations", "grants", "sync", "incident resolve", "routine add", "routine refresh", "routine pause", "routine resume", "routine run-now",
+        "config show", "intake run", "contest exclude", "webhook status", "webhook test"].map(row => [row, "installation-wide"]),
+    // Cross-project lists and reads a limited person is still refused; scoping them is later work.
+    ...["runner list", "coordinator list", "outbox list", "incident list", "routine list", "routine show", "intake show", "intake preview",
+        "intake pr-comments", "template list", "template show", "contest show", "review show"].map(row => [row, "not yet scoped"]),
+]);
+/** The projects a listing or task reference may disclose: null for someone with access to all of them. */
+export function remoteLensOf(store, scope, allows) {
+    if ((scope.kind !== "listing" && scope.kind !== "references") || allows(null))
+        return null;
+    return Object.freeze(store.knownRepos().filter(repo => allows(repo)));
+}
+/** Flags a remote caller never passes: who they are comes from the token, and the server reads and writes no paths for them. */
+export const REMOTE_REFUSED_FLAGS = new Set([
+    "db", "as", "token", "token-file", "token-env", "password", "key-file", "credentials", "containment", "out", "project-root", "bin", "port", "host",
+]);
+/**
+ * The guide row an argv is: the longest invocation its command and leading positionals spell. A command with no
+ * row of its own runs nowhere remotely (backup, restore, storage, ledger, policy and the rest).
+ */
+export function remoteRowOf(command, positional) {
+    for (let words = Math.min(positional.length, 2); words >= 0; words -= 1) {
+        const invocation = [command, ...positional.slice(0, words)].join(" ");
+        const row = COMMAND_GUIDE.find(one => one.invocation === invocation && one.invocation !== "");
+        if (row !== undefined)
+            return row;
+    }
+    return null;
+}
+/**
+ * Re-prove the principal now, against the store: the account still stands at the same generation, the token is
+ * the person's, unrevoked and unexpired, and the scope is no wider than the token's or the person's role.
+ */
+export function reproveRemote(store, principal, now) {
+    if (principal === null || typeof principal !== "object" || principal.kind !== "person" || typeof principal.account !== "string" || typeof principal.tokenId !== "string")
+        return { ok: false };
+    const account = store.accountOf(principal.account);
+    if (account === null || account.revokedAt !== null || account.generation !== principal.generation)
+        return { ok: false };
+    const token = store.apiTokenSecret(principal.tokenId)?.row ?? null;
+    if (token === null || token.account !== principal.account || token.revokedAt !== null || Date.parse(token.expiresAt) <= now.getTime())
+        return { ok: false };
+    const scope = principal.scope === "act" && token.access === "act" && account.role === "approver" ? "act" : "read";
+    return { ok: true, scope, tokenName: token.name };
+}
+/** Whether the person may use `repo`: inside their token's projects and their account's current access. Null is "every project". */
+export function remoteAllows(store, principal, repo) {
+    if (principal.projects !== null && (repo === null || !principal.projects.includes(repo)))
+        return false;
+    return store.accountCanAccess(principal.account, repo);
+}
+/** The project a command touches, or why it may not run: --repo must be a project the server knows, by its exact path. */
+export function remoteProjectOf(store, run, scope, positional, repos, invocation, flags, files) {
+    const known = store.knownRepos();
+    // The local parser keeps the last raw --repo as well as a split repoList. Require those identities
+    // to agree: comma lists and repeated project flags cannot authorize one path and dispatch another.
+    const rawRepo = flags.get("repo");
+    if (rawRepo !== undefined && (repos.length !== 1 || rawRepo !== repos[0]))
+        return { ok: false, reason: "unknown-project", message: REMOTE_MESSAGES.project };
+    for (const given of repos) {
+        if (!isAbsolute(given) || !known.includes(given) || !run.allows(given))
+            return { ok: false, reason: "unknown-project", message: REMOTE_MESSAGES.project };
+    }
+    const named = repos[0] ?? null;
+    const checked = remoteArgumentsOf(store, run.allows, invocation, positional, flags, named, files);
+    if (!checked.ok)
+        return checked;
+    switch (scope.kind) {
+        case "global":
+        case "self":
+        case "listing":
+            return checked;
+        case "installation":
+            return run.allows(null) ? { ok: true, repo: named, taskId: null } : { ok: false, reason: "all-projects", message: REMOTE_MESSAGES.installation };
+        case "repo":
+            return named === null ? { ok: false, reason: "unknown-project", message: REMOTE_MESSAGES.project } : checked;
+        case "references":
+            return checked.repo === null ? REMOTE_NOT_FOUND : checked;
+    }
+}
+export function remoteSecret() {
+    return `remote:${randomBytes(24).toString("base64url")}`;
+}

package/dist/operate.d.ts

@@ -8,6 +8,7 @@ import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
 import { type TelegramTransport } from "./telegram.js";
 import { type MateCliSeams } from "./mate-cli.js";
+import { type Principal, type RemoteSource } from "./operate-remote.js";
 import { type PublishExec } from "./publish.js";
 import { type Runner as CommandRunner } from "./builder.js";
 import { type ReleaseIo } from "./releases.js";
@@ -123,6 +124,26 @@ export declare function parseOperateArgs(argv: readonly string[], ownValues?: Re
 };
 /** Route an `operate` command. Returns the process exit code. */
 export declare function runOperate(command: string, argv: readonly string[], write: Write, options?: OperateOptions): Promise<number>;
+export type { Principal };
+/**
+ * Run one command on this server for a person who signed in with their own API token (the transport and MCP
+ * gateway prove the `so_` token and refuse browser origins; this is everything after). The command's row in the
+ * machine contract decides first: "no" and "step-up" rows, and commands with no row, are refused before any
+ * command code runs. The principal is re-proved against the store, a read token runs only reads, and the project
+ * the command touches must be one the person may use, named by --repo where a local run would use the working
+ * directory. The command then runs as that person: every credential check resolves to them, nothing prompts, and
+ * this machine's saved login and lead token are never read. Files are only those sent in `files`, keyed by the
+ * argument that names them. Every call is in the action history as the person, from source `api` (or `mcp`),
+ * with the token's name. The store is the caller's and stays open.
+ */
+export declare function runOperateAs(argv: string[], opts: {
+    principal: Principal;
+    store: Store;
+    write: (s: string) => void;
+    files?: Record<string, string>;
+    source?: RemoteSource;
+    options?: OperateOptions;
+}): Promise<number>;
 /** Durably create the login file BEFORE the bootstrap commits (arc 2
  * finding 27): exclusive, 0600, fsynced — file and directory both — so the
  * row only ever follows a durable secret. Throws on any failure. */
@@ -142,4 +163,3 @@ export declare function readUpConsoleUrl(dir: string): string | null;
  * missing credentials stay a usage refusal, exactly as before.
  */
 export declare const PROPOSALS_ACTIONS: readonly ["list", "confirm", "dismiss"];
-export {};