@datalayer/core 1.1.66 → 1.2.10

package/lib/api/evals/types.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

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

@@ -37,3 +37,32 @@ export declare const disconnectAgent: (token: string, grantUid: string, baseUrl?
     success: boolean;
     message?: string;
 }>;
+/**
+ * Disconnect every agent this person has connected — sign out everywhere.
+ *
+ * **This is also how a forced re-consent is done.** A grant *is* the consent,
+ * so ending them all sends the next authorization through the consent screen
+ * rather than letting it be answered from what was agreed before; there is no
+ * separate "ask again" flag to keep in step with this one.
+ *
+ * Always the caller's own. A person cannot end somebody else's sessions here
+ * — an organization taking back what it granted is deprovisioning, which runs
+ * when a membership ends.
+ */
+export declare const disconnectEveryAgent: (token: string, baseUrl?: string) => Promise<{
+    success: boolean;
+    revoked: number;
+    message?: string;
+}>;
+/**
+ * Disconnect every agent connected while acting for one team.
+ *
+ * For the people who may manage that team: ending a team's sessions is the
+ * same kind of authority as removing somebody from it. It never touches a
+ * personal agent or another team's — the same narrowness deprovisioning has.
+ */
+export declare const disconnectEveryAgentInTeam: (token: string, teamUid: string, baseUrl?: string) => Promise<{
+    success: boolean;
+    revoked: number;
+    message?: string;
+}>;

package/lib/api/iam/connectedAgents.js

@@ -50,3 +50,38 @@ export const disconnectAgent = async (token, grantUid, baseUrl = DEFAULT_SERVICE
     method: 'DELETE',
     token,
 });
+/**
+ * Disconnect every agent this person has connected — sign out everywhere.
+ *
+ * **This is also how a forced re-consent is done.** A grant *is* the consent,
+ * so ending them all sends the next authorization through the consent screen
+ * rather than letting it be answered from what was agreed before; there is no
+ * separate "ask again" flag to keep in step with this one.
+ *
+ * Always the caller's own. A person cannot end somebody else's sessions here
+ * — an organization taking back what it granted is deprovisioning, which runs
+ * when a membership ends.
+ */
+export const disconnectEveryAgent = async (token, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: connectedAgentsUrl(baseUrl),
+        method: 'DELETE',
+        token,
+    });
+    return { ...response, revoked: response.revoked ?? 0 };
+};
+/**
+ * Disconnect every agent connected while acting for one team.
+ *
+ * For the people who may manage that team: ending a team's sessions is the
+ * same kind of authority as removing somebody from it. It never touches a
+ * personal agent or another team's — the same narrowness deprovisioning has.
+ */
+export const disconnectEveryAgentInTeam = async (token, teamUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.IAM}/oauth/teams/${encodeURIComponent(teamUid)}/connected-agents`,
+        method: 'DELETE',
+        token,
+    });
+    return { ...response, revoked: response.revoked ?? 0 };
+};

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

@@ -0,0 +1,76 @@
+/** A role a group mapping may grant, at the organization or at a team. */
+export declare const ORGANIZATION_ROLES: readonly ["organization_owner", "organization_security_auditor", "organization_user_reviewer", "organization_member"];
+export declare const TEAM_ROLES: readonly ["team_owner", "team_member"];
+export type OrganizationRole = (typeof ORGANIZATION_ROLES)[number];
+export type TeamRole = (typeof TEAM_ROLES)[number];
+/** One `groups` claim mapped onto one role, at the organization or a team. */
+export interface RoleMapping {
+    /** The group, exactly as the token names it. */
+    group: string;
+    role: OrganizationRole | TeamRole;
+    /** Which team, when `role` is a team role; empty for an organization role. */
+    teamUid: string;
+}
+export interface IdentityProvider {
+    uid: string;
+    orgUid: string;
+    name: string;
+    protocol: 'oidc';
+    issuer: string;
+    clientId: string;
+    /** The *name* of a secret in this organization's store — never the secret. */
+    clientSecretRef: string;
+    /** Domains this provider claims. Claiming is free; see `verifiedDomains`. */
+    domains: string[];
+    /** The claimed domains proved by DNS. Only these route a sign-in. */
+    verifiedDomains: string[];
+    groupClaim: string;
+    /** Whether a sign-in may adopt a Datalayer account that already exists
+     * with the asserted address, rather than being refused. Off by default:
+     * see the module and provisioning notes for why. */
+    allowEmailLinking: boolean;
+    roleMappings: RoleMapping[];
+    enabled: boolean;
+    createdBy?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    version?: number;
+}
+/**
+ * A provider as it is written. Everything but what the route already names
+ * and `verifiedDomains` — which is never sent, only ever read: it is set
+ * exclusively by `verifyDomain` checking DNS, and a draft that could set it
+ * directly would be a way to claim verification without proving anything.
+ */
+export type IdentityProviderDraft = Omit<IdentityProvider, 'uid' | 'orgUid' | 'verifiedDomains' | 'createdBy' | 'createdAt' | 'updatedAt' | 'version'>;
+export interface DomainVerification {
+    host: string;
+    type: 'TXT';
+    value: string;
+}
+/** Raised when the registry refused a provider as written — a bad issuer, an
+ * unowned domain, an unknown role in a mapping. The message is IAM's own. */
+export declare class IdentityProviderInvalid extends Error {
+    constructor(message: string);
+}
+export declare const listIdentityProviders: (token: string, orgUid: string, baseUrl?: string) => Promise<IdentityProvider[]>;
+export declare const getIdentityProvider: (token: string, orgUid: string, uid: string, baseUrl?: string) => Promise<IdentityProvider>;
+export declare const createIdentityProvider: (token: string, orgUid: string, provider: IdentityProviderDraft, baseUrl?: string) => Promise<IdentityProvider>;
+export declare const updateIdentityProvider: (token: string, orgUid: string, uid: string, provider: IdentityProviderDraft, baseUrl?: string) => Promise<IdentityProvider>;
+export declare const enableIdentityProvider: (token: string, orgUid: string, uid: string, baseUrl?: string) => Promise<IdentityProvider>;
+export declare const disableIdentityProvider: (token: string, orgUid: string, uid: string, baseUrl?: string) => Promise<IdentityProvider>;
+/** Remove a registration outright. Prefer disabling one that has been used:
+ * this keeps no trace for the sign-in rows that name it. */
+export declare const deleteIdentityProvider: (token: string, orgUid: string, uid: string, baseUrl?: string) => Promise<void>;
+/** What to publish in DNS to prove this organization holds `domain`. */
+export declare const getDomainVerification: (token: string, orgUid: string, uid: string, domain: string, baseUrl?: string) => Promise<{
+    verification: DomainVerification;
+    verified: boolean;
+}>;
+/**
+ * Check DNS now and, if the record is there, make the domain route sign-in.
+ *
+ * Until this succeeds the domain routes nothing at all, whatever was typed
+ * when the provider was registered.
+ */
+export declare const verifyDomain: (token: string, orgUid: string, uid: string, domain: string, baseUrl?: string) => Promise<IdentityProvider>;

package/lib/api/iam/identityProviders.js

@@ -0,0 +1,187 @@
+/*
+ * 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 own identity provider.
+ *
+ * Enterprise sign-in used to be one Okta for the whole deployment. This is
+ * the registry that replaces it: an organization registers an OIDC provider
+ * — issuer, client id, the email domains it claims — and a sign-in is routed
+ * to it by domain.
+ *
+ * **A claim is not proof.** Registering a domain here does not route
+ * anything: only a domain proved by a DNS TXT record does, because a domain
+ * that only had to be typed would let one organization receive another's
+ * sign-ins. `getDomainVerification` reads what to publish; `verifyDomain`
+ * checks it and is the only call that turns a claim into a route.
+ *
+ * **The client secret never appears here.** The record names a secret in the
+ * organization's own secret store (`clientSecretRef`); this client never
+ * reads or writes a secret's value.
+ *
+ * @module api/iam/identityProviders
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/** A role a group mapping may grant, at the organization or at a team. */
+export const ORGANIZATION_ROLES = [
+    'organization_owner',
+    'organization_security_auditor',
+    'organization_user_reviewer',
+    'organization_member',
+];
+export const TEAM_ROLES = ['team_owner', 'team_member'];
+const roleMappingFromWire = (mapping) => ({
+    group: mapping.group ?? '',
+    role: mapping.role ?? 'organization_member',
+    teamUid: mapping.team_uid ?? '',
+});
+const roleMappingToWire = (mapping) => ({
+    group: mapping.group,
+    role: mapping.role,
+    team_uid: mapping.teamUid,
+});
+const fromWire = (provider) => ({
+    uid: provider.uid,
+    orgUid: provider.org_uid ?? '',
+    name: provider.name ?? '',
+    protocol: 'oidc',
+    issuer: provider.issuer ?? '',
+    clientId: provider.client_id ?? '',
+    clientSecretRef: provider.client_secret_ref ?? '',
+    domains: provider.domains ?? [],
+    verifiedDomains: provider.verified_domains ?? [],
+    groupClaim: provider.group_claim ?? 'groups',
+    allowEmailLinking: provider.allow_email_linking ?? false,
+    roleMappings: (provider.role_mappings ?? []).map(roleMappingFromWire),
+    enabled: provider.enabled ?? true,
+    createdBy: provider.created_by ?? undefined,
+    createdAt: provider.created_at ?? undefined,
+    updatedAt: provider.updated_at ?? undefined,
+    version: provider.version ?? undefined,
+});
+const toWire = (provider) => ({
+    name: provider.name,
+    protocol: provider.protocol,
+    issuer: provider.issuer,
+    client_id: provider.clientId,
+    client_secret_ref: provider.clientSecretRef,
+    domains: provider.domains,
+    group_claim: provider.groupClaim,
+    allow_email_linking: provider.allowEmailLinking,
+    role_mappings: provider.roleMappings.map(roleMappingToWire),
+    enabled: provider.enabled,
+});
+/** Raised when the registry refused a provider as written — a bad issuer, an
+ * unowned domain, an unknown role in a mapping. The message is IAM's own. */
+export class IdentityProviderInvalid extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityProviderInvalid';
+    }
+}
+const providersUrl = (baseUrl, orgUid, suffix = '') => `${baseUrl}${API_BASE_PATHS.IAM}/organizations/${encodeURIComponent(orgUid)}/identity-providers${suffix}`;
+export const listIdentityProviders = async (token, orgUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid),
+        method: 'GET',
+        token,
+    });
+    return (response.providers ?? []).map(fromWire);
+};
+export const getIdentityProvider = async (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}`),
+        method: 'GET',
+        token,
+    });
+    return fromWire(response.provider ?? { uid });
+};
+export const createIdentityProvider = async (token, orgUid, provider, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await withRefusal(() => requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid),
+        method: 'POST',
+        token,
+        body: toWire(provider),
+    }));
+    return fromWire(response.provider ?? { uid: '' });
+};
+export const updateIdentityProvider = async (token, orgUid, uid, provider, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await withRefusal(() => requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}`),
+        method: 'PUT',
+        token,
+        body: toWire(provider),
+    }));
+    return fromWire(response.provider ?? { uid });
+};
+const setEnabled = async (token, orgUid, uid, enabled, baseUrl) => {
+    const response = await requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}/${enabled ? 'enable' : 'disable'}`),
+        method: 'POST',
+        token,
+    });
+    return fromWire(response.provider ?? { uid });
+};
+export const enableIdentityProvider = (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => setEnabled(token, orgUid, uid, true, baseUrl);
+export const disableIdentityProvider = (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => setEnabled(token, orgUid, uid, false, baseUrl);
+/** Remove a registration outright. Prefer disabling one that has been used:
+ * this keeps no trace for the sign-in rows that name it. */
+export const deleteIdentityProvider = async (token, orgUid, uid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    await requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}`),
+        method: 'DELETE',
+        token,
+    });
+};
+/** What to publish in DNS to prove this organization holds `domain`. */
+export const getDomainVerification = async (token, orgUid, uid, domain, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}/domains/${encodeURIComponent(domain)}/verification`),
+        method: 'GET',
+        token,
+    });
+    return {
+        verification: response.verification ?? { host: '', type: 'TXT', value: '' },
+        verified: response.verified ?? false,
+    };
+};
+/**
+ * Check DNS now and, if the record is there, make the domain route sign-in.
+ *
+ * Until this succeeds the domain routes nothing at all, whatever was typed
+ * when the provider was registered.
+ */
+export const verifyDomain = async (token, orgUid, uid, domain, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await withRefusal(() => requestDatalayerAPI({
+        url: providersUrl(baseUrl, orgUid, `/${encodeURIComponent(uid)}/domains/${encodeURIComponent(domain)}/verify`),
+        method: 'POST',
+        token,
+    }));
+    return fromWire(response.provider ?? { uid });
+};
+/**
+ * Turn IAM's `400` into one the form can show beside the field.
+ *
+ * A `400` here is never a bug in the client: it is the registry saying it
+ * refused what was written, and its message names why — an `http` issuer, a
+ * domain somebody else already verified, an unknown role in a mapping.
+ */
+const withRefusal = async (call) => {
+    try {
+        return await call();
+    }
+    catch (error) {
+        const candidate = error;
+        const status = candidate?.status ?? candidate?.response?.status;
+        if (status === 400) {
+            throw new IdentityProviderInvalid(candidate.message || 'This identity provider was refused.');
+        }
+        throw error;
+    }
+};

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

@@ -12,6 +12,7 @@ export * as healthz from './healthz';
 export * as usage from './usage';
 export * as secrets from './secrets';
 export * as connectedAgents from './connectedAgents';
+export * as trials from './trials';
 export { login, logout, checkAuth } from './authentication';
 export { getOAuth2AuthzUrl, getOAuth2AuthzUrlForLink, handleGitHubOAuth2Callback, handleLinkedInOAuth2Callback, handleOktaOAuth2Callback, type OAuth2Provider, type OAuth2AuthzUrlResponse, type OAuth2CallbackParams, type OAuth2CallbackResponse, } from './oauth2';
 export { me, whoami } from './profile';

package/lib/api/iam/index.js

@@ -16,6 +16,7 @@ export * as healthz from './healthz.js';
 export * as usage from './usage.js';
 export * as secrets from './secrets.js';
 export * as connectedAgents from './connectedAgents.js';
+export * as trials from './trials.js';
 // For backward compatibility, export the old API structure
 export { login, logout, checkAuth } from './authentication.js';
 export { getOAuth2AuthzUrl, getOAuth2AuthzUrlForLink, handleGitHubOAuth2Callback, handleLinkedInOAuth2Callback, handleOktaOAuth2Callback, } from './oauth2.js';

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

@@ -34,6 +34,55 @@ export interface McpPolicyRules {
     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 {
@@ -52,7 +101,7 @@ export interface McpPolicy extends McpPolicyRules {
  * 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"];
+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);
@@ -78,3 +127,55 @@ export declare const setMcpPolicy: (token: string, scope: McpPolicyScope, subjec
 }, 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>;

package/lib/api/iam/mcpPolicy.js

@@ -52,6 +52,10 @@ export const MCP_POLICY_RULES = [
     'maxCallsPerMinute',
     'maxCreditsPerDay',
     'maxConcurrentSandboxes',
+    'gpuHoursPerMonth',
+    'storageBytes',
+    'sessionMaxHours',
+    'ssoAdmitsWithoutConsent',
 ];
 /** Raised when the policy changed between the read and the write. */
 export class McpPolicyConflict extends Error {
@@ -60,8 +64,9 @@ export class McpPolicyConflict extends Error {
         this.name = 'McpPolicyConflict';
     }
 }
-const policyUrl = (baseUrl, scope, subjectUid, query = '') => `${baseUrl}${API_BASE_PATHS.IAM}/mcp-policies/${encodeURIComponent(scope)}` +
-    `/${encodeURIComponent(subjectUid)}${query}`;
+/** `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.
  *
@@ -130,3 +135,34 @@ const statusOf = (error) => {
 };
 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/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,
+});