@datalayer/core 1.1.60 → 1.2.10

package/lib/api/iam/mcpPolicy.js

@@ -0,0 +1,168 @@
+/*
+ * 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 MCP policy layer IAM holds for one organization, team or person.
+ *
+ * Distinct from the *effective* policy the gateway answers, which is every
+ * layer intersected with, per rule, the layer that decided it. That one is
+ * the read: "what may my agent do, and who said so". This one is the write:
+ * "what does my organization narrow".
+ *
+ * Only four kinds of rule can be stored, and IAM refuses anything else —
+ * so a policy page cannot promise something the gateway never enforces, and
+ * `toolDenyList` comes back as a typo rather than being kept as a setting
+ * that does nothing.
+ *
+ * **Writes carry the version that was read.** A policy is small and read
+ * whole, so a write replaces rather than merges; without the version, two
+ * owners editing the same policy would each silently overwrite the other,
+ * and the loser would not know. IAM answers `409` instead, and the caller
+ * re-reads.
+ *
+ * @module api/iam/mcpPolicy
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/**
+ * 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 const MCP_POLICY_SCOPES = ['organization', 'team', 'personal'];
+/**
+ * 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 const MCP_POLICY_RULES = [
+    'toolDenylist',
+    'toolAllowlist',
+    'allowedClients',
+    'maxCallsPerMinute',
+    'maxCreditsPerDay',
+    'maxConcurrentSandboxes',
+    'gpuHoursPerMonth',
+    'storageBytes',
+    'sessionMaxHours',
+    'ssoAdmitsWithoutConsent',
+];
+/** Raised when the policy changed between the read and the write. */
+export class McpPolicyConflict extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'McpPolicyConflict';
+    }
+}
+/** `suffix` is appended verbatim: a query string, or a further path segment. */
+const policyUrl = (baseUrl, scope, subjectUid, suffix = '') => `${baseUrl}${API_BASE_PATHS.IAM}/mcp-policies/${encodeURIComponent(scope)}` +
+    `/${encodeURIComponent(subjectUid)}${suffix}`;
+/**
+ * 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 const getMcpPolicy = async (token, scope, subjectUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    try {
+        return await requestDatalayerAPI({
+            url: policyUrl(baseUrl, scope, subjectUid),
+            method: 'GET',
+            token,
+        });
+    }
+    catch (error) {
+        // A layer nobody has written is a `404`, and it is an ordinary answer
+        // rather than a failure — most organizations have never written one.
+        if (isNotFound(error)) {
+            return null;
+        }
+        throw error;
+    }
+};
+/**
+ * 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 const setMcpPolicy = async (token, scope, subjectUid, rules, options = {}, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const query = options.expectedVersion === undefined
+        ? ''
+        : `?expected_version=${encodeURIComponent(String(options.expectedVersion))}`;
+    try {
+        const response = await requestDatalayerAPI({
+            url: policyUrl(baseUrl, scope, subjectUid, query),
+            method: 'PUT',
+            token,
+            body: rules,
+        });
+        return response.policy ?? {};
+    }
+    catch (error) {
+        if (isConflict(error)) {
+            throw new McpPolicyConflict('This policy changed while you were editing it. Read it again and ' +
+                'reapply your change — otherwise one of the two edits is lost, and ' +
+                'whoever loses it is not told.');
+        }
+        throw error;
+    }
+};
+/** Remove one layer, so it narrows nothing again. */
+export const deleteMcpPolicy = async (token, scope, subjectUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    await requestDatalayerAPI({
+        url: policyUrl(baseUrl, scope, subjectUid),
+        method: 'DELETE',
+        token,
+    });
+};
+const statusOf = (error) => {
+    const candidate = error;
+    return candidate?.status ?? candidate?.response?.status;
+};
+const isNotFound = (error) => statusOf(error) === 404;
+const isConflict = (error) => statusOf(error) === 409;
+const admittedFromWire = (wire) => ({
+    entry: wire.entry ?? '',
+    kind: wire.kind === 'hostname' || wire.kind === 'url' ? wire.kind : 'unusable',
+    hostname: wire.hostname || undefined,
+    resolved: wire.resolved,
+    clientName: wire.client_name || undefined,
+    clientHostname: wire.client_hostname || undefined,
+    clientUri: wire.client_uri || undefined,
+    localhostOnly: wire.localhost_only,
+    detail: wire.detail || undefined,
+});
+/**
+ * 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 const getAdmittedClients = async (token, scope, subjectUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: policyUrl(baseUrl, scope, subjectUid, '/admitted-clients'),
+        method: 'GET',
+        token,
+    });
+    return {
+        allowlisted: response.allowlisted === true,
+        clients: (response.clients ?? []).map(admittedFromWire),
+        detail: response.detail || undefined,
+    };
+};

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

@@ -0,0 +1,13 @@
+export interface OrganizationTeam {
+    uid: string;
+    handle: string;
+    name: string;
+}
+/**
+ * One organization's teams.
+ *
+ * A team with no uid is dropped rather than rendered: it addresses no
+ * policy layer, so a row for it would offer a form whose every write is a
+ * `404`.
+ */
+export declare const listOrganizationTeams: (token: string, orgUid: string, baseUrl?: string) => Promise<OrganizationTeam[]>;

package/lib/api/iam/organizationTeams.js

@@ -0,0 +1,43 @@
+/*
+ * 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 teams inside one organization.
+ *
+ * Only what the MCP console needs of them: a name to show and a uid to
+ * address a policy layer with. Team membership, invitations and the rest
+ * belong to the organization's own settings, not here.
+ *
+ * @module api/iam/organizationTeams
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/**
+ * One organization's teams.
+ *
+ * A team with no uid is dropped rather than rendered: it addresses no
+ * policy layer, so a row for it would offer a form whose every write is a
+ * `404`.
+ */
+export const listOrganizationTeams = async (token, orgUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.IAM}/organizations/` +
+            `${encodeURIComponent(orgUid)}/teams`,
+        method: 'GET',
+        token,
+    });
+    return (response.teams ?? [])
+        .filter(team => Boolean(team.uid))
+        .map(team => ({
+        uid: team.uid,
+        handle: team.handle_s ?? '',
+        // The handle is the fallback rather than the uid: a person picking a
+        // team from a list knows `data-science`, not `01ARZ3ND…`.
+        name: team.name_t || team.handle_s || team.uid,
+    }));
+};

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

@@ -1,4 +1,4 @@
-import { MembershipsResponse, ShareablePrincipalsResponse, UserMeResponse, WhoAmIResponse } from '../../models/IAM';
+import { MembershipsResponse, PrincipalSearchResponse, PrincipalSearchUser, ShareablePrincipalsResponse, UserMeResponse, WhoAmIResponse } from '../../models/IAM';
 /**
  * Get current authenticated user profile
  * @param token - Authentication token (required)
@@ -28,3 +28,19 @@ export declare const memberships: (token: string, baseUrl?: string) => Promise<M
  * @param baseUrl - Base URL for the API (defaults to production IAM URL)
  */
 export declare const principalsShareable: (token: string, baseUrl?: string) => Promise<ShareablePrincipalsResponse>;
+/**
+ * Search the people, teams and organizations the caller may name: what the
+ * sharing dialogs search, and whom a comment mentions or assigns (B4-02).
+ *
+ * @param token - Authentication token (required)
+ * @param query - What is typed: part of a handle or of a name
+ * @param principalTypes - What to search; people only by default
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ */
+export declare const searchPrincipals: (token: string, query: string, principalTypes?: Array<"user" | "team" | "organization">, baseUrl?: string) => Promise<PrincipalSearchResponse>;
+/** A person `searchPrincipals` found, as a comment or a report names them. */
+export declare const personOfPrincipalUser: (user: PrincipalSearchUser) => {
+    uid: string;
+    handle: string;
+    name: string | null;
+};

package/lib/api/iam/profile.js

@@ -69,3 +69,30 @@ export const principalsShareable = async (token, baseUrl = DEFAULT_SERVICE_URLS.
         token,
     });
 };
+/**
+ * Search the people, teams and organizations the caller may name: what the
+ * sharing dialogs search, and whom a comment mentions or assigns (B4-02).
+ *
+ * @param token - Authentication token (required)
+ * @param query - What is typed: part of a handle or of a name
+ * @param principalTypes - What to search; people only by default
+ * @param baseUrl - Base URL for the API (defaults to production IAM URL)
+ */
+export const searchPrincipals = async (token, query, principalTypes = ['user'], baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.IAM}/principals/search`,
+        method: 'POST',
+        body: { query, principalTypes },
+        token,
+    });
+};
+/** A person `searchPrincipals` found, as a comment or a report names them. */
+export const personOfPrincipalUser = (user) => ({
+    uid: user.uid,
+    handle: user.handle_s,
+    name: `${user.first_name_t ?? ''} ${user.last_name_t ?? ''}`.trim() ||
+        user.display_name_t ||
+        user.display_name ||
+        null,
+});

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

@@ -0,0 +1,79 @@
+/** A SCIM credential as the console may see it — never the secret or its hash. */
+export interface ScimToken {
+    uid: string;
+    orgUid: string;
+    /** What an administrator called it, to tell two directories apart. */
+    name: string;
+    /**
+     * Revoked rather than deleted, so the rows a provisioning run wrote can
+     * still name the token that wrote them.
+     */
+    revoked: boolean;
+    /**
+     * When the secret was last replaced. A token that has never been rotated
+     * carries its creation moment here.
+     */
+    rotatedAt?: string;
+    /**
+     * When it last authenticated a SCIM call, or empty for never. Written best
+     * effort — a provisioning call is never failed for the bookkeeping.
+     */
+    lastUsedAt?: string;
+    createdBy?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * A freshly minted credential: the record, and the secret **this once**.
+ *
+ * The two are separate fields rather than one merged object on purpose. The
+ * secret does not belong in anything the console stores, renders twice, or
+ * puts in a list, and a shape that carried it alongside every other field
+ * invites exactly that.
+ */
+export interface MintedScimToken {
+    token: ScimToken;
+    /** Shown once. Not retrievable, by construction — only a hash is stored. */
+    secret: string;
+}
+export declare const listScimTokens: (token: string, orgUid: string, baseUrl?: string) => Promise<ScimToken[]>;
+/**
+ * Mint one. The secret is in this answer and nowhere else, ever again.
+ *
+ * The caller must put it in front of somebody before the next render. There
+ * is no second chance and no call that would provide one.
+ */
+export declare const createScimToken: (token: string, orgUid: string, name: string, baseUrl?: string) => Promise<MintedScimToken>;
+/**
+ * A new secret for the same record; the old one stops at once.
+ *
+ * Rotation rather than delete-and-recreate because the record's uid is what
+ * the provisioning rows name. Replacing it would leave them pointing at
+ * nothing.
+ */
+export declare const rotateScimToken: (token: string, orgUid: string, uid: string, baseUrl?: string) => Promise<MintedScimToken>;
+/** Stop a token, keeping the rows that name it readable. */
+export declare const revokeScimToken: (token: string, orgUid: string, uid: string, baseUrl?: string) => Promise<ScimToken>;
+/**
+ * The base URL a directory is configured with.
+ *
+ * Built here rather than typed into the page, because it is half of what an
+ * administrator copies into Okta or Entra and a typo in it looks like an
+ * outage on the directory's side. The directory appends `/Users` itself;
+ * RFC 7644 fixes everything after this.
+ */
+export declare const scimBaseUrl: (baseUrl?: string) => string;
+/**
+ * Whether this organization can actually be provisioned into right now.
+ *
+ * A list with tokens in it is not the same as a working integration, and the
+ * distinction is the one an administrator most needs: every token revoked
+ * reads, in a table, almost exactly like a healthy setup. `neverUsed` is the
+ * other quiet state — configured, live, and never once called, which is what
+ * a directory that was set up and never switched on looks like.
+ */
+export declare const scimStatus: (tokens: ScimToken[]) => {
+    state: "none" | "revoked" | "never-used" | "active";
+    live: ScimToken[];
+    lastUsedAt?: string;
+};

package/lib/api/iam/scimTokens.js

@@ -0,0 +1,141 @@
+/*
+ * 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 credentials an organization's directory provisions with, over SCIM.
+ *
+ * The identity provider registry beside this one made a directory able to
+ * *sign somebody in*. SCIM is the half that does not wait for them to turn
+ * up: the directory says who exists when they join and, far more
+ * importantly, who has left.
+ *
+ * **The token is the tenant.** Every SCIM call resolves its organization
+ * from the bearer credential before it looks at anything else, so these
+ * records are not a convenience — each one *is* an organization's provisioning
+ * authority, and there is nothing else identifying the caller.
+ *
+ * **The secret is answered once and never again.** `createScimToken` and
+ * `rotateScimToken` return it; nothing reads it back, because only a SHA-256
+ * of it is stored. A console that offered to show it later would be
+ * promising something the server cannot do — so this client has no call that
+ * could, and the UI has to say "copy it now" and mean it.
+ *
+ * `lastUsedAt` is the column worth reading. A directory configured once and
+ * forgotten looks exactly like a live one in every other field, and the
+ * difference matters most for deprovisioning: the integration that has not
+ * called in a month is not removing anybody.
+ *
+ * @module api/iam/scimTokens
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+const fromWire = (wire) => ({
+    uid: wire.uid ?? '',
+    orgUid: wire.org_uid ?? '',
+    name: wire.name ?? '',
+    // A record with no `revoked` field is a live one: absence is not
+    // revocation, and reading it as one would show every token as stopped.
+    revoked: wire.revoked === true,
+    rotatedAt: wire.rotated_at || undefined,
+    lastUsedAt: wire.last_used_at || undefined,
+    createdBy: wire.created_by || undefined,
+    createdAt: wire.created_at || undefined,
+    updatedAt: wire.updated_at || undefined,
+});
+const tokensUrl = (baseUrl, orgUid, suffix = '') => `${baseUrl}${API_BASE_PATHS.IAM}/organizations/${encodeURIComponent(orgUid)}` +
+    `/scim-tokens${suffix}`;
+export const listScimTokens = async (token, orgUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: tokensUrl(baseUrl, orgUid),
+        method: 'GET',
+        token,
+    });
+    return (response.tokens ?? []).map(fromWire);
+};
+/**
+ * Mint one. The secret is in this answer and nowhere else, ever again.
+ *
+ * The caller must put it in front of somebody before the next render. There
+ * is no second chance and no call that would provide one.
+ */
+export const createScimToken = async (token, orgUid, name, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: tokensUrl(baseUrl, orgUid),
+        method: 'POST',
+        token,
+        body: { name },
+    });
+    return {
+        token: fromWire(response.token ?? {}),
+        secret: response.token?.token ?? '',
+    };
+};
+/**
+ * A new secret for the same record; the old one stops at once.
+ *
+ * Rotation rather than delete-and-recreate because the record's uid is what
+ * the provisioning rows name. Replacing it would leave them pointing at
+ * nothing.
+ */
+export const rotateScimToken = async (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: tokensUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}/rotate`),
+        method: 'POST',
+        token,
+    });
+    return {
+        token: fromWire(response.token ?? {}),
+        secret: response.token?.token ?? '',
+    };
+};
+/** Stop a token, keeping the rows that name it readable. */
+export const revokeScimToken = async (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: tokensUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}`),
+        method: 'DELETE',
+        token,
+    });
+    return fromWire(response.token ?? {});
+};
+/**
+ * The base URL a directory is configured with.
+ *
+ * Built here rather than typed into the page, because it is half of what an
+ * administrator copies into Okta or Entra and a typo in it looks like an
+ * outage on the directory's side. The directory appends `/Users` itself;
+ * RFC 7644 fixes everything after this.
+ */
+export const scimBaseUrl = (baseUrl = DEFAULT_SERVICE_URLS.IAM) => `${baseUrl}/api/iam/scim/v2`;
+/**
+ * Whether this organization can actually be provisioned into right now.
+ *
+ * A list with tokens in it is not the same as a working integration, and the
+ * distinction is the one an administrator most needs: every token revoked
+ * reads, in a table, almost exactly like a healthy setup. `neverUsed` is the
+ * other quiet state — configured, live, and never once called, which is what
+ * a directory that was set up and never switched on looks like.
+ */
+export const scimStatus = (tokens) => {
+    const live = tokens.filter(entry => !entry.revoked);
+    if (tokens.length === 0) {
+        return { state: 'none', live };
+    }
+    if (live.length === 0) {
+        return { state: 'revoked', live };
+    }
+    const used = live
+        .map(entry => entry.lastUsedAt)
+        .filter((value) => Boolean(value))
+        .sort();
+    const lastUsedAt = used.length > 0 ? used[used.length - 1] : undefined;
+    return {
+        state: lastUsedAt ? 'active' : 'never-used',
+        live,
+        lastUsedAt,
+    };
+};

package/lib/api/iam/secrets.js

@@ -9,21 +9,6 @@
 import { requestDatalayerAPI } from '../DatalayerApi.js';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
 import { validateToken, validateRequiredString } from '../utils/validation.js';
-/**
- * Helper function to Base64 encode a value (cross-platform).
- * @param value - Plain text value to encode
- * @returns Base64 encoded string
- */
-function encodeValue(value) {
-    if (typeof Buffer !== 'undefined') {
-        // Node.js environment
-        return Buffer.from(value).toString('base64');
-    }
-    else {
-        // Browser environment
-        return btoa(value);
-    }
-}
 /**
  * Create a new secret.
  * Creates a new encrypted secret for the authenticated user.
@@ -52,7 +37,10 @@ export const createSecret = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.I
         variant: data.variant || 'generic',
         name: data.name,
         description: data.description || '',
-        value: encodeValue(data.value),
+        // As it is. A secret has one representation end to end (PLAN_ENVS.md
+        // E3-05): this used to base64-encode, and nothing on the read side undid
+        // it, so a build secret arrived at its build encoded and opened nothing.
+        value: data.value,
     };
     try {
         return await requestDatalayerAPI({
@@ -64,7 +52,7 @@ export const createSecret = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.I
     }
     catch (error) {
         if (error.response?.status === 409) {
-            throw new Error(`Secret with name '${data.name}' already exists. Please use a different name.`);
+            throw new Error(`Secret with name '${data.name}' already exists. Please use a different name.`, { cause: error });
         }
         throw error;
     }
@@ -118,7 +106,7 @@ export const getSecret = async (token, secretId, baseUrl = DEFAULT_SERVICE_URLS.
     }
     catch (error) {
         if (error.response?.status === 404) {
-            throw new Error(`Secret '${secretId}' not found.`);
+            throw new Error(`Secret '${secretId}' not found.`, { cause: error });
         }
         throw error;
     }
@@ -147,7 +135,7 @@ export const updateSecret = async (token, secretId, data, baseUrl = DEFAULT_SERV
     // Base64 encode value if provided
     const requestBody = { ...data };
     if (data.value) {
-        requestBody.value = encodeValue(data.value);
+        requestBody.value = data.value;
     }
     try {
         return await requestDatalayerAPI({
@@ -159,7 +147,7 @@ export const updateSecret = async (token, secretId, data, baseUrl = DEFAULT_SERV
     }
     catch (error) {
         if (error.response?.status === 404) {
-            throw new Error(`Secret '${secretId}' not found.`);
+            throw new Error(`Secret '${secretId}' not found.`, { cause: error });
         }
         throw error;
     }
@@ -189,7 +177,7 @@ export const deleteSecret = async (token, secretId, baseUrl = DEFAULT_SERVICE_UR
     }
     catch (error) {
         if (error.response?.status === 404) {
-            throw new Error(`Secret '${secretId}' not found.`);
+            throw new Error(`Secret '${secretId}' not found.`, { cause: error });
         }
         throw error;
     }

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

@@ -0,0 +1,68 @@
+/**
+ * What a service agent may be granted.
+ *
+ * A subset of the OAuth scopes, and deliberately not all of them: the ones
+ * about a *person* — reading their profile, acting as them — mean nothing
+ * for a principal that is not one, and IAM refuses them. Offering one would
+ * invite somebody to grant something that silently does nothing.
+ */
+export declare const SERVICE_AGENT_SCOPES: readonly ["runtimes:read", "runtimes:write", "data:read", "sandboxes:manage"];
+export type ServiceAgentScope = (typeof SERVICE_AGENT_SCOPES)[number];
+export interface ServiceAgent {
+    uid: string;
+    name: string;
+    description: string;
+    /** The team it belongs to, where it is a team's rather than the organization's. */
+    teamUid: string;
+    /** Space-separated, as the token's `scope` claim carries them. */
+    scopes: string;
+    /**
+     * Revoked rather than removed. Its audit rows name it, and a uid that
+     * resolves to nothing makes a year-old row unreadable — so this is a
+     * state to render, never a reason to hide the row.
+     */
+    revoked: boolean;
+    createdBy: string;
+    createdAt?: string | null;
+    /** When the key was last replaced, so a listing can show a stale one. */
+    keyRotatedAt?: string | null;
+}
+/**
+ * A service agent as it comes back from a write, with the key.
+ *
+ * The key is present exactly twice in this API — creating and rotating —
+ * and nowhere else, ever.
+ */
+export interface ServiceAgentWithKey extends ServiceAgent {
+    key: string;
+}
+/**
+ * One organization's service agents, revoked ones included.
+ *
+ * Included because hiding them makes a revoked agent invisible to whoever
+ * is deciding whether it is still needed, while its audit rows still name
+ * it. Any member of the organization may read this; only owners may write.
+ */
+export declare const listServiceAgents: (token: string, orgUid: string, baseUrl?: string) => Promise<ServiceAgent[]>;
+/**
+ * Create one. **The key is in this answer and in no other.**
+ *
+ * Scopes are sent as the array the caller holds; IAM joins and validates
+ * them, and refuses one that is not grantable to a principal that is not a
+ * person.
+ */
+export declare const createServiceAgent: (token: string, orgUid: string, agent: {
+    name: string;
+    scopes: string[];
+    description?: string;
+    teamUid?: string;
+}, baseUrl?: string) => Promise<ServiceAgentWithKey>;
+/**
+ * Replace the agent's key. The old one stops working with this call.
+ *
+ * No grace period, which is the point of rotating: a leaked key that still
+ * works for an hour is a leaked key that still works.
+ */
+export declare const rotateServiceAgentKey: (token: string, orgUid: string, agentUid: string, baseUrl?: string) => Promise<ServiceAgentWithKey>;
+/** Stop the agent, keeping it readable for its audit. */
+export declare const revokeServiceAgent: (token: string, orgUid: string, agentUid: string, baseUrl?: string) => Promise<ServiceAgent>;