@datalayer/core 1.1.60 → 1.2.10

package/lib/api/iam/mcpAlertRules.js

@@ -0,0 +1,198 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The alert rules an organization asked to be told about.
+ *
+ * A rule is a condition over a number the gateway already counts, checked
+ * once a minute, firing at most once per condition per window. IAM stores
+ * them; the gateway's evaluator reads the enabled ones on its tick.
+ *
+ * **A rule the evaluator cannot evaluate is refused when it is written**,
+ * not at the tick. That is the whole reason the vocabulary below is
+ * exported: a rule that never fires because of a typo is indistinguishable
+ * from a condition that never happened, and the second is what somebody will
+ * believe. A form built from these lists cannot produce one.
+ *
+ * @module api/iam/mcpAlertRules
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/**
+ * What a rule may be about.
+ *
+ * Each name is answered by one reader in the gateway. `measurable` says
+ * whether a reader exists *today*: a condition with none is counted
+ * unreadable and never fires, which is exactly the silence rules are written
+ * to avoid — so a form shows it as not yet available rather than offering it
+ * as though it worked.
+ */
+export const ALERT_CONDITIONS = [
+    {
+        name: 'tasks.open',
+        label: 'Open tasks',
+        help: 'Runs still going. A backlog that is not draining.',
+        measurable: true,
+    },
+    {
+        name: 'tasks.failed',
+        label: 'Failed tasks',
+        help: 'Runs that ended badly in the window.',
+        measurable: true,
+    },
+    {
+        name: 'spend.budget_fraction',
+        label: 'Share of the daily budget spent',
+        help: 'A fraction: 0.8 is 80%. Prefer this to a credit figure — it follows ' +
+            'the budget, so raising the budget does not silently move the alert.',
+        measurable: true,
+    },
+    {
+        name: 'spend.credits',
+        label: 'Credits spent',
+        help: 'An absolute figure. Raising the budget leaves this rule where it ' +
+            'was, and you will be told at a share you did not choose.',
+        measurable: true,
+    },
+    {
+        name: 'audit.write_failures',
+        label: 'Audit writes that failed',
+        help: 'A gap in the record. Worth knowing about immediately.',
+        measurable: true,
+    },
+    {
+        name: 'sli.availability',
+        label: 'Availability',
+        help: 'The share of calls that did not fail, as a fraction. An organization ' +
+            'with no calls has no availability, and is not alerted on.',
+        measurable: true,
+    },
+    {
+        name: 'sli.latency',
+        label: 'Latency (p95)',
+        help: 'The 95th percentile call duration, in milliseconds, read from the ' +
+            'audit — which is never sampled, so it is the more complete source. ' +
+            'A very busy window holds more rows than one reading takes, and is ' +
+            'reported as unreadable rather than as a percentile of the newest ' +
+            'slice; Test says so straight away.',
+        measurable: true,
+    },
+    {
+        name: 'sandbox.lost',
+        label: 'Sandboxes lost',
+        help: 'Sessions whose sandbox was found gone. Relaunched ones count: a ' +
+            'provider losing sandboxes steadily and quietly relaunching them is ' +
+            'invisible from the outside precisely because it recovers.',
+        measurable: true,
+    },
+    {
+        name: 'dependency.down',
+        label: 'Dependencies down',
+        help: 'How many of the services the gateway needs are not answering. A ' +
+            'service nobody configured is not counted. This is about the ' +
+            'platform rather than your organization, and is your outage anyway.',
+        measurable: true,
+    },
+];
+/** How a reading is compared with the threshold. */
+export const ALERT_OPERATORS = [
+    { name: 'gt', label: 'is above' },
+    { name: 'gte', label: 'is at or above' },
+    { name: 'lt', label: 'is below' },
+    { name: 'lte', label: 'is at or below' },
+    { name: 'eq', label: 'equals' },
+];
+export const ALERT_SEVERITIES = ['info', 'warning', 'critical'];
+/** What a rule is measured over. */
+export const ALERT_SCOPE_KINDS = ['organization', 'team', 'user', 'agent'];
+const fromWire = (rule) => ({
+    uid: rule.uid,
+    orgUid: rule.org_uid ?? '',
+    condition: rule.condition ?? '',
+    operator: rule.operator ?? 'gt',
+    threshold: rule.threshold ?? 0,
+    severity: rule.severity ?? 'warning',
+    windowSeconds: rule.window_seconds ?? 3600,
+    scopeKind: rule.scope_kind ?? 'organization',
+    scopeUid: rule.scope_uid ?? '',
+    enabled: rule.enabled ?? true,
+    version: rule.version ?? undefined,
+});
+const toWire = (rule) => ({
+    condition: rule.condition,
+    operator: rule.operator,
+    threshold: rule.threshold,
+    severity: rule.severity,
+    window_seconds: rule.windowSeconds,
+    scope_kind: rule.scopeKind,
+    scope_uid: rule.scopeUid,
+    enabled: rule.enabled,
+});
+/** Raised when the evaluator could not evaluate the rule as written. */
+export class AlertRuleInvalid extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AlertRuleInvalid';
+    }
+}
+const rulesUrl = (baseUrl, orgUid, suffix = '') => `${baseUrl}${API_BASE_PATHS.IAM}/mcp-alert-rules/${encodeURIComponent(orgUid)}${suffix}`;
+export const listAlertRules = async (token, orgUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: rulesUrl(baseUrl, orgUid),
+        method: 'GET',
+        token,
+    });
+    return (response.rules ?? []).map(fromWire);
+};
+export const createAlertRule = async (token, orgUid, rule, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await withRefusal(() => requestDatalayerAPI({
+        url: rulesUrl(baseUrl, orgUid),
+        method: 'POST',
+        token,
+        body: toWire(rule),
+    }));
+    return fromWire(response.rule ?? { uid: '' });
+};
+export const updateAlertRule = async (token, orgUid, uid, rule, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await withRefusal(() => requestDatalayerAPI({
+        url: rulesUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}`),
+        method: 'PUT',
+        token,
+        body: toWire(rule),
+    }));
+    return fromWire(response.rule ?? { uid });
+};
+/** Remove one rule. What it watched is unwatched from the next tick. */
+export const deleteAlertRule = async (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    await requestDatalayerAPI({
+        url: rulesUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}`),
+        method: 'DELETE',
+        token,
+    });
+};
+/**
+ * Turn IAM's refusal into one the form can show beside the field.
+ *
+ * `422` here is never a bug in the client: it is the evaluator saying it
+ * could not evaluate this rule, and its message names what is wrong. Losing
+ * it behind a generic failure would leave somebody guessing at the one thing
+ * the platform already knows.
+ */
+const withRefusal = async (call) => {
+    try {
+        return await call();
+    }
+    catch (error) {
+        const candidate = error;
+        const status = candidate?.status ?? candidate?.response?.status;
+        if (status === 422) {
+            throw new AlertRuleInvalid(candidate.message || 'The evaluator could not evaluate this rule.');
+        }
+        throw error;
+    }
+};

package/lib/api/iam/mcpAuditSettings.d.ts

@@ -0,0 +1,46 @@
+/** Where a copy of the audit can be shipped. */
+export declare const AUDIT_DESTINATION_KINDS: readonly ["https", "s3"];
+export type AuditDestinationKind = (typeof AUDIT_DESTINATION_KINDS)[number];
+export interface McpAuditSettings {
+    /** How long rows are kept. Rows a sweep deletes do not come back. */
+    retentionDays?: number;
+    /** Empty when nothing is forwarded, which is the default. */
+    destinationKind: string;
+    destinationUrl: string;
+    /** The *reference* to a signing secret, never the secret. */
+    destinationSecretRef: string;
+    /** An endpoint a fired alert is POSTed to, beside the in-app notice. */
+    alertWebhookUrl: string;
+    /** A Slack incoming webhook. Its own field: Slack gets Block Kit. */
+    alertSlackWebhookUrl: string;
+    /** Who is emailed, comma-separated. */
+    alertEmails: string;
+    version?: number;
+}
+/** Raised when IAM refused a setting, carrying its reason. */
+export declare class AuditSettingInvalid extends Error {
+    constructor(message: string);
+}
+/**
+ * One organization's settings, or `null` where it has none.
+ *
+ * `null` is an ordinary answer: an organization with no settings is neither
+ * swept nor forwarded, which is the default rather than a failure.
+ */
+export declare const getAuditSettings: (token: string, orgUid: string, baseUrl?: string) => Promise<McpAuditSettings | null>;
+/**
+ * Change some of the settings. Only what is passed is sent.
+ *
+ * A partial write, deliberately: IAM merges, so a page that only edits the
+ * alert destinations must not send an empty retention and clear it.
+ */
+export declare const setAuditSettings: (token: string, orgUid: string, settings: Partial<{
+    retentionDays: number;
+    destinationKind: string;
+    destinationUrl: string;
+    alertWebhookUrl: string;
+    alertSlackWebhookUrl: string;
+    alertEmails: string;
+}>, options?: {
+    expectedVersion?: number;
+}, baseUrl?: string) => Promise<McpAuditSettings>;

package/lib/api/iam/mcpAuditSettings.js

@@ -0,0 +1,120 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * An organization's audit retention, forwarding, and where alerts go.
+ *
+ * Three things on one document, and they are together because they are all
+ * "what this organization has decided about its own record": how long rows
+ * are kept, where a copy is shipped, and who is told when a rule fires.
+ *
+ * The alert destinations live here rather than on each rule because a URL
+ * repeated on twenty rules is nineteen places to forget when it rotates,
+ * and the rules would disagree about where the organization is reachable.
+ *
+ * **Writes merge, they do not replace.** Retention and forwarding are set by
+ * different people at different times, and making somebody resend a
+ * destination in order to change a retention is how a destination gets
+ * resent wrong.
+ *
+ * @module api/iam/mcpAuditSettings
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/** Where a copy of the audit can be shipped. */
+export const AUDIT_DESTINATION_KINDS = ['https', 's3'];
+const fromWire = (settings) => ({
+    retentionDays: settings.retention_days ?? undefined,
+    destinationKind: settings.destination_kind ?? '',
+    destinationUrl: settings.destination_url ?? '',
+    destinationSecretRef: settings.destination_secret_ref ?? '',
+    alertWebhookUrl: settings.alert_webhook_url ?? '',
+    alertSlackWebhookUrl: settings.alert_slack_webhook_url ?? '',
+    alertEmails: settings.alert_emails ?? '',
+    version: settings.version ?? undefined,
+});
+/** Raised when IAM refused a setting, carrying its reason. */
+export class AuditSettingInvalid extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuditSettingInvalid';
+    }
+}
+const settingsUrl = (baseUrl, orgUid, query = '') => `${baseUrl}${API_BASE_PATHS.IAM}/mcp-audit-settings/${encodeURIComponent(orgUid)}${query}`;
+/**
+ * One organization's settings, or `null` where it has none.
+ *
+ * `null` is an ordinary answer: an organization with no settings is neither
+ * swept nor forwarded, which is the default rather than a failure.
+ */
+export const getAuditSettings = async (token, orgUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    try {
+        const response = await requestDatalayerAPI({
+            url: settingsUrl(baseUrl, orgUid),
+            method: 'GET',
+            token,
+        });
+        return fromWire(response.settings ?? {});
+    }
+    catch (error) {
+        if (statusOf(error) === 404) {
+            return null;
+        }
+        throw error;
+    }
+};
+/**
+ * Change some of the settings. Only what is passed is sent.
+ *
+ * A partial write, deliberately: IAM merges, so a page that only edits the
+ * alert destinations must not send an empty retention and clear it.
+ */
+export const setAuditSettings = async (token, orgUid, settings, options = {}, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const body = {};
+    if (settings.retentionDays !== undefined) {
+        body.retention_days = settings.retentionDays;
+    }
+    if (settings.destinationKind !== undefined) {
+        body.destination_kind = settings.destinationKind;
+    }
+    if (settings.destinationUrl !== undefined) {
+        body.destination_url = settings.destinationUrl;
+    }
+    if (settings.alertWebhookUrl !== undefined) {
+        body.alert_webhook_url = settings.alertWebhookUrl;
+    }
+    if (settings.alertSlackWebhookUrl !== undefined) {
+        body.alert_slack_webhook_url = settings.alertSlackWebhookUrl;
+    }
+    if (settings.alertEmails !== undefined) {
+        body.alert_emails = settings.alertEmails;
+    }
+    const query = options.expectedVersion === undefined
+        ? ''
+        : `?expected_version=${encodeURIComponent(String(options.expectedVersion))}`;
+    try {
+        const response = await requestDatalayerAPI({
+            url: settingsUrl(baseUrl, orgUid, query),
+            method: 'PUT',
+            token,
+            body,
+        });
+        return fromWire(response.settings ?? {});
+    }
+    catch (error) {
+        if (statusOf(error) === 422) {
+            throw new AuditSettingInvalid(error.message ||
+                'IAM refused one of these settings.');
+        }
+        throw error;
+    }
+};
+const statusOf = (error) => {
+    const candidate = error;
+    return candidate?.status ?? candidate?.response?.status;
+};

package/lib/api/iam/mcpPolicy.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Which layer a policy belongs to.
+ *
+ * The names IAM stores, exactly: `personal`, not `user`. It refuses an
+ * unknown scope with a `422`, so getting this wrong is not a subtle
+ * mis-scoping — it is every read and every write of that layer failing.
+ * Held against IAM's own `POLICY_SCOPES` by a test in the gateway's suite.
+ */
+export declare const MCP_POLICY_SCOPES: readonly ["organization", "team", "personal"];
+export type McpPolicyScope = (typeof MCP_POLICY_SCOPES)[number];
+/**
+ * The rules a layer may set. Every one is optional: a layer that sets
+ * nothing narrows nothing.
+ */
+export interface McpPolicyRules {
+    /** Tools this layer forbids. Unions across layers — a layer may add a
+     *  denial, never lift one. */
+    toolDenylist?: string[];
+    /**
+     * Tools this layer permits, to the exclusion of the rest.
+     *
+     * An empty array **as written** is not an allowlist. A setting somebody
+     * created and has not filled in would otherwise refuse every tool in the
+     * organization, and the first conclusion drawn would be that the gateway
+     * is down.
+     */
+    toolAllowlist?: string[];
+    /** CIMD URLs or hostnames this layer admits. Empty is not an allowlist,
+     *  for the same reason. */
+    allowedClients?: string[];
+    /** Calls a minute. **At least 1**: see `maxCallsPerMinute` below. */
+    maxCallsPerMinute?: number;
+    /** Credits a day, across the layer's agents. */
+    maxCreditsPerDay?: number;
+    /** Sandboxes at once. Counted per scope — a team's counts the team's. */
+    maxConcurrentSandboxes?: number;
+    /**
+     * GPU-hours over the last 30 days. Refuses a launch on a **GPU**
+     * environment; a CPU sandbox is unaffected.
+     *
+     * Not expressible as credits: the credits a GPU hour costs differ per
+     * environment, so neither number can be derived from the other.
+     *
+     * A trailing 30 days, not a calendar month — a limit that resets on the
+     * 1st can be spent twice inside 48 hours, once each side of the reset.
+     * And it counts **every** GPU-hour billed to the scope, agents' or not:
+     * the agent dimension lives on a child document in the ledger and cannot
+     * be a clause of the sum. A form must say both.
+     */
+    gpuHoursPerMonth?: number;
+    /**
+     * Bytes stored. Refuses **every** launch when reached, not only one that
+     * attaches content — every sandbox can write, so unlike the GPU-hour limit
+     * there is nothing to condition on.
+     *
+     * In **bytes**, not gigabytes. A number whose unit is implied is one
+     * somebody eventually reads as the other, and this is compared against a
+     * figure Contents reports in bytes; a form converts for the reader.
+     *
+     * Counted over every live object *version* rather than every object: an
+     * object's recorded size is its current version's, and a scope keeping a
+     * hundred versions of a one-gigabyte file stores a hundred gigabytes.
+     */
+    storageBytes?: number;
+    /**
+     * How long a connection may go on being refreshed before the person signs
+     * in and consents again. Hours, because that is the unit it is set in.
+     *
+     * Enforced by **IAM**, at its token endpoint, rather than by the gateway:
+     * a session's age is a fact about the grant, and the grant is IAM's. The
+     * gateway never sees it.
+     */
+    sessionMaxHours?: number;
+    /**
+     * Whether this organization's own identity provider may stand in for the
+     * consent screen, for a client it already admits.
+     *
+     * Narrow by construction, and off unless turned on: it applies only to a
+     * session that came through one of this organization's own enabled
+     * providers, only for a client named on `allowedClients`, and only when
+     * that list is not empty. Every other session still sees the screen.
+     *
+     * Not "require SSO": it does not stop anybody signing in another way.
+     */
+    ssoAdmitsWithoutConsent?: boolean;
+}
+/** A stored layer, with the version a write must carry back. */
+export interface McpPolicy extends McpPolicyRules {
+    /**
+     * What was read. Passed to the next write so a change made in between is
+     * a `409` rather than a silent overwrite.
+     *
+     * Absent when nobody has written this layer yet.
+     */
+    version?: number;
+}
+/**
+ * Every rule name IAM will store, in the order a form should show them.
+ *
+ * Exported so a form cannot drift from what the gateway enforces: a rule
+ * rendered here and unknown to IAM is refused at the write, which reads to
+ * the person filling it in as the page being broken.
+ */
+export declare const MCP_POLICY_RULES: readonly ["toolDenylist", "toolAllowlist", "allowedClients", "maxCallsPerMinute", "maxCreditsPerDay", "maxConcurrentSandboxes", "gpuHoursPerMonth", "storageBytes", "sessionMaxHours", "ssoAdmitsWithoutConsent"];
+/** Raised when the policy changed between the read and the write. */
+export declare class McpPolicyConflict extends Error {
+    constructor(message: string);
+}
+/**
+ * One layer's rules, or `null` where nobody has written it.
+ *
+ * `null` rather than an empty object, and the difference is the whole point:
+ * "this organization narrows nothing" and "this organization has no policy"
+ * are the same in effect and different to edit. A form that cannot tell them
+ * apart offers **Remove** for a policy that does not exist.
+ */
+export declare const getMcpPolicy: (token: string, scope: McpPolicyScope, subjectUid: string, baseUrl?: string) => Promise<McpPolicy | null>;
+/**
+ * Replace one layer's rules.
+ *
+ * Replace, not merge: a policy is read whole and small, and merging would
+ * leave no way to express *removing* a rule — an owner clearing a denylist
+ * would find it still there.
+ */
+export declare const setMcpPolicy: (token: string, scope: McpPolicyScope, subjectUid: string, rules: McpPolicyRules, options?: {
+    expectedVersion?: number;
+}, baseUrl?: string) => Promise<McpPolicy>;
+/** Remove one layer, so it narrows nothing again. */
+export declare const deleteMcpPolicy: (token: string, scope: McpPolicyScope, subjectUid: string, baseUrl?: string) => Promise<void>;
+/**
+ * One `allowedClients` entry, as the server can describe it.
+ *
+ * Three states, kept apart deliberately — collapsing any two of them is the
+ * mistake this shape exists to prevent.
+ */
+export interface AdmittedClient {
+    /** Exactly as it is stored, so somebody can find the line they typed. */
+    entry: string;
+    /**
+     * `hostname` admits every client that host publishes and has no document
+     * to read. `url` names one client document. `unusable` matches nothing —
+     * almost always a URL pasted without its scheme.
+     */
+    kind: 'hostname' | 'url' | 'unusable';
+    hostname?: string;
+    /**
+     * Only for `url`. `false` means the document could not be read, which is
+     * an entry that silently admits nobody — and reads to the vendor whose
+     * agent is refused as a deliberate decision.
+     */
+    resolved?: boolean;
+    clientName?: string;
+    clientHostname?: string;
+    clientUri?: string;
+    /** Every redirect goes to the reader's own machine. */
+    localhostOnly?: boolean;
+    /** Why it cannot be read, or what a hostname entry admits. */
+    detail?: string;
+}
+export interface AdmittedClients {
+    /**
+     * Whether this layer names an allowlist **at all**.
+     *
+     * `false` for an absent or empty list, and it is not a detail: an empty
+     * list is not an allowlist, and the gateway admits every client through a
+     * layer that has not filled one in. A page rendering "0 clients admitted"
+     * over `false` would state the opposite of what is enforced.
+     */
+    allowlisted: boolean;
+    clients: AdmittedClient[];
+    detail?: string;
+}
+/**
+ * What this layer's admitted-client entries actually name.
+ *
+ * Its own call rather than part of `getMcpPolicy`, because that one is what
+ * the gateway reads on every uncached tool call and this may fetch a client
+ * document per entry — which is exactly what must never happen on the
+ * enforcement path.
+ */
+export declare const getAdmittedClients: (token: string, scope: McpPolicyScope, subjectUid: string, baseUrl?: string) => Promise<AdmittedClients>;