@mintlify/cli 4.0.1701 → 4.0.1703

package/__test__/agent-auth.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  discoverAgentAuth,
+  exchangeAgentToken,
+  getAgentIdentity,
+  registerAgent,
+} from '../src/agent-auth.js';
+import { agentRequest, AgentApiError } from '../src/agent-http.js';
+
+const issuer = 'https://auth.example.com';
+const discovery = {
+  issuer,
+  token_endpoint: `${issuer}/oauth2/token`,
+  agent_auth: {
+    identity_endpoint: `${issuer}/agent/identity`,
+    claim_endpoint: `${issuer}/agent/identity/claim`,
+    identity_types_supported: ['anonymous'],
+  },
+};
+const credentials = {
+  registrationId: 'reg_1',
+  issuer,
+  assertion: 'assertion-secret',
+  claimToken: 'claim-secret',
+};
+function respond(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), { status });
+}
+afterEach(() => vi.unstubAllGlobals());
+
+describe('agent authentication', () => {
+  it('preserves caller cancellation alongside the request timeout', async () => {
+    const controller = new AbortController();
+    let requestSignal: AbortSignal | undefined;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (_url, init: RequestInit) => {
+        requestSignal = init.signal ?? undefined;
+        return respond({});
+      })
+    );
+    await agentRequest('https://api.example.com', { signal: controller.signal });
+    expect(requestSignal?.aborted).toBe(false);
+    controller.abort();
+    expect(requestSignal?.aborted).toBe(true);
+  });
+  it('discovers endpoints from Mintlify and validates their origin', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce(respond({ authorization_servers: [issuer] }))
+      .mockResolvedValueOnce(respond(discovery));
+    vi.stubGlobal('fetch', request);
+    expect(await discoverAgentAuth('https://api.example.com')).toEqual(discovery);
+    expect(request.mock.calls[0]?.[0]).toBe(
+      'https://api.example.com/api/agent/.well-known/oauth-protected-resource'
+    );
+  });
+  it('does not send credentials to endpoints on a different origin', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi
+        .fn()
+        .mockResolvedValueOnce(respond({ authorization_servers: [issuer] }))
+        .mockResolvedValueOnce(
+          respond({ ...discovery, token_endpoint: 'https://other.example.com/token' })
+        )
+    );
+    await expect(discoverAgentAuth('https://api.example.com')).rejects.toThrow('do not match');
+  });
+  it('parses the hosted registration response and exchanges without resource', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce(
+        respond({
+          id: 'reg_1',
+          identity: { assertion: credentials.assertion },
+          claim: { token: credentials.claimToken },
+        })
+      )
+      .mockResolvedValueOnce(
+        respond({ access_token: 'access', token_type: 'Bearer', expires_in: 300 })
+      );
+    vi.stubGlobal('fetch', request);
+    expect(await registerAgent(discovery)).toEqual(credentials);
+    expect((await exchangeAgentToken(discovery, credentials)).accessToken).toBe('access');
+    const body = request.mock.calls[1]?.[1].body;
+    expect(body.get('assertion')).toBe(credentials.assertion);
+    expect(body.has('resource')).toBe(false);
+  });
+  it('sends the agent token without reading human credentials', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValue(respond({ registrationId: 'reg_1', identityType: 'anonymous' }));
+    vi.stubGlobal('fetch', request);
+    await getAgentIdentity('https://api.example.com', 'agent-token');
+    expect(request.mock.calls[0]?.[1].headers.Authorization).toBe('Bearer agent-token');
+  });
+  it('does not register again on outages or print upstream secrets', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValue(respond({ error: 'unavailable', message: credentials.assertion }, 503));
+    vi.stubGlobal('fetch', request);
+    await expect(exchangeAgentToken(discovery, credentials)).rejects.toThrow(AgentApiError);
+    expect(request).toHaveBeenCalledTimes(1);
+  });
+  it('rejects malformed successful responses without exposing them', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(respond({ assertion: credentials.assertion }))
+    );
+    await expect(registerAgent(discovery)).rejects.toThrow('unexpected response');
+  });
+});

package/__test__/agent-credentials.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const entries = new Map<string, string>();
+const keytar = vi.hoisted(() => ({ getPassword: vi.fn(), setPassword: vi.fn() }));
+vi.mock('../src/keyring.js', () => ({ getKeytar: async () => keytar }));
+
+import { loadAgentCredentials, saveAgentCredentials } from '../src/agent-credentials.js';
+
+const credentials = {
+  registrationId: 'reg_1',
+  issuer: 'https://auth.example.com',
+  assertion: 'assertion',
+  claimToken: 'claim',
+};
+
+describe('agent credentials', () => {
+  beforeEach(() => {
+    entries.clear();
+    vi.resetAllMocks();
+    keytar.getPassword.mockImplementation(
+      async (service, account) => entries.get(`${service}/${account}`) ?? null
+    );
+    keytar.setPassword.mockImplementation(async (service, account, value) => {
+      entries.set(`${service}/${account}`, value);
+    });
+  });
+
+  it('isolates projects and environments from each other and human credentials', async () => {
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    expect(await loadAgentCredentials('https://api.example.com', '/docs')).toEqual(credentials);
+    expect(await loadAgentCredentials('https://dev.example.com', '/docs')).toBeNull();
+    expect(await loadAgentCredentials('https://api.example.com', '/other')).toBeNull();
+    expect([...entries.keys()].every((key) => key.startsWith('mintlify-agent/'))).toBe(true);
+  });
+
+  it('retains old registrations when the current project starts a new site', async () => {
+    await saveAgentCredentials('https://api.example.com', '/docs', credentials);
+    await saveAgentCredentials('https://api.example.com', '/docs', {
+      ...credentials,
+      registrationId: 'reg_2',
+    });
+    expect((await loadAgentCredentials('https://api.example.com', '/docs'))?.registrationId).toBe(
+      'reg_2'
+    );
+    expect(entries.has('mintlify-agent/https://api.example.com:reg_1')).toBe(true);
+  });
+
+  it('does not switch the project pointer when storing the credential fails', async () => {
+    keytar.setPassword.mockRejectedValueOnce(new Error('locked'));
+    await expect(
+      saveAgentCredentials('https://api.example.com', '/docs', credentials)
+    ).rejects.toThrow('locked');
+    expect(keytar.setPassword).toHaveBeenCalledTimes(1);
+  });
+
+  it('preserves read failures instead of treating them as an absent registration', async () => {
+    keytar.getPassword.mockRejectedValueOnce(new Error('locked'));
+    await expect(loadAgentCredentials('https://api.example.com', '/docs')).rejects.toThrow(
+      'locked'
+    );
+  });
+});

package/__test__/agent-deployment.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { getAgentWriteToken, provisionAgentSite } from '../src/agent-deployment.js';
+
+vi.mock('node:timers/promises', () => ({ setTimeout: vi.fn().mockResolvedValue(undefined) }));
+const ready = {
+  status: 'ready',
+  deploymentId: 'deployment',
+  subdomain: 'actual-name',
+  remote: 'https://git.example.com/repo.git',
+  branch: 'main',
+  expiresAt: '2026-12-01T00:00:00.000Z',
+};
+const existing = { ...ready, code: 'deployment_already_exists' };
+const provision = () =>
+  provisionAgentSite('https://api.example.com', 'access', {
+    subdomain: 'requested',
+    orgName: 'Docs',
+  });
+function response(body: unknown, status: number) {
+  return new Response(JSON.stringify(body), { status });
+}
+afterEach(() => vi.unstubAllGlobals());
+
+describe('agent deployment API', () => {
+  it('sends root content layout and uses the allocated subdomain', async () => {
+    const request = vi.fn().mockResolvedValue(response(ready, 201));
+    vi.stubGlobal('fetch', request);
+    expect(await provision()).toEqual({ ...ready, created: true });
+    expect(JSON.parse(request.mock.calls[0]?.[1].body)).toEqual({
+      subdomain: 'requested',
+      orgName: 'Docs',
+      docsPath: '',
+    });
+  });
+  it('returns an existing site as an update, not a new creation', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(response(existing, 409)));
+    expect(await provision()).toEqual({ ...existing, created: false });
+  });
+  it('retries provisioning even when no deployment ID exists yet', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce(response({ status: 'provisioning', code: existing.code }, 409))
+      .mockResolvedValueOnce(response(existing, 409));
+    vi.stubGlobal('fetch', request);
+    expect((await provision()).status).toBe('ready');
+    expect(request).toHaveBeenCalledTimes(2);
+  });
+  it('bounds provisioning retries', async () => {
+    const request = vi
+      .fn()
+      .mockImplementation(async () =>
+        response({ status: 'provisioning', code: existing.code }, 409)
+      );
+    vi.stubGlobal('fetch', request);
+    await expect(provision()).rejects.toThrow('still provisioning');
+    expect(request).toHaveBeenCalledTimes(4);
+  });
+  it('distinguishes confirmed expiry from upstream failure', async () => {
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce(response({ ...existing, status: 'expired' }, 409))
+      .mockResolvedValueOnce(response({ error: 'unavailable' }, 503));
+    vi.stubGlobal('fetch', request);
+    expect((await provision()).status).toBe('expired');
+    await expect(provision()).rejects.toThrow('503');
+  });
+  it('requests a write token without a caller-selected deployment', async () => {
+    const credential = {
+      remote: ready.remote,
+      branch: 'main',
+      token: 'write-secret',
+      tokenExpiresAt: ready.expiresAt,
+    };
+    const request = vi.fn().mockResolvedValue(response(credential, 200));
+    vi.stubGlobal('fetch', request);
+    expect(await getAgentWriteToken('https://api.example.com', 'access')).toEqual(credential);
+    expect(request.mock.calls[0]?.[1].body).toBeUndefined();
+  });
+});

package/__test__/deploy-instructions.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createAgentClaimLink } from '../src/agent-claim.js';
+import { DASHBOARD_URL } from '../src/constants.js';
+import { deploymentInstructions, DEPLOY_HELP } from '../src/deploy-instructions.js';
+import { renderWelcome } from '../src/welcome.js';
+
+vi.mock('../src/agent-auth.js', () => ({
+  discoverAgentAuth: async () => ({
+    issuer: 'https://auth.example.com',
+    agent_auth: { claim_endpoint: 'https://auth.example.com/agent/identity/claim' },
+  }),
+}));
+afterEach(() => vi.unstubAllGlobals());
+const credentials = {
+  registrationId: 'reg',
+  issuer: 'https://auth.example.com',
+  assertion: 'assertion-secret',
+  claimToken: 'claim-secret',
+};
+const site = {
+  status: 'ready' as const,
+  deploymentId: 'id',
+  subdomain: 'docs',
+  remote: 'https://git.example.com/repo',
+  branch: 'main' as const,
+  expiresAt: '2026-12-01T00:00:00.000Z',
+};
+
+describe('deploy help and claim handoff', () => {
+  it('uses the actual claim attempt API and returns its human-facing link', async () => {
+    const request = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          attempt: {
+            verification_uri:
+              'https://auth.example.com/verify?token=attempt%2Btoken%26value&other=ignored',
+          },
+        })
+      )
+    );
+    vi.stubGlobal('fetch', request);
+    expect(
+      await createAgentClaimLink('https://api.example.com', credentials, 'user@example.com')
+    ).toBe(`${DASHBOARD_URL}/agent-claim?token=attempt%2Btoken%26value`);
+    expect(JSON.parse(request.mock.calls[0]?.[1].body)).toEqual({
+      type: 'service_auth',
+      claim_token: 'claim-secret',
+      login_hint: 'user@example.com',
+    });
+  });
+  it('rejects a verification link without an attempt token', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            attempt: { verification_uri: 'https://auth.example.com/verify' },
+          })
+        )
+      )
+    );
+    await expect(
+      createAgentClaimLink('https://api.example.com', credentials, 'user@example.com')
+    ).rejects.toThrow();
+  });
+  it('keeps Git operations with the agent and omits identity credentials', () => {
+    const text = deploymentInstructions(
+      {
+        status: 'ready',
+        created: true,
+        site,
+        credentials,
+        write: {
+          remote: site.remote,
+          branch: site.branch,
+          token: 'write-secret',
+          tokenExpiresAt: site.expiresAt,
+        },
+      },
+      'https://app.example.com/claim'
+    );
+    expect(text).toContain('Do not force-push');
+    expect(text).toContain('docs.json');
+    expect(text).toContain('https://app.example.com/claim');
+    expect(text).not.toContain('assertion-secret');
+    expect(text).not.toContain('claim-secret');
+    expect(text).not.toContain('write-secret');
+  });
+  it('documents the command in root help and explains that it does not push files', () => {
+    expect(renderWelcome({ packageName: 'mint', signedIn: false })).toContain('deploy');
+    expect(DEPLOY_HELP).toContain('Commit and push the documentation yourself');
+    expect(DEPLOY_HELP).toContain('--new');
+    expect(DEPLOY_HELP).toContain('ask the user for their email');
+  });
+});

package/__test__/deploy.test.ts

@@ -0,0 +1,155 @@
+import path from 'node:path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import * as auth from '../src/agent-auth.js';
+import * as storage from '../src/agent-credentials.js';
+import * as deployment from '../src/agent-deployment.js';
+import * as config from '../src/config.js';
+import { prepareAgentDeployment, formatDeployment } from '../src/deploy.js';
+
+vi.mock('../src/agent-auth.js');
+vi.mock('../src/agent-credentials.js');
+vi.mock('../src/agent-deployment.js');
+vi.mock('../src/config.js');
+
+const credentials = {
+  registrationId: 'reg_1',
+  issuer: 'https://auth.example.com',
+  assertion: 'assertion',
+  claimToken: 'claim',
+};
+const site = {
+  status: 'ready' as const,
+  created: true,
+  deploymentId: 'id',
+  subdomain: 'allocated',
+  remote: 'https://git.example.com/repo',
+  branch: 'main' as const,
+  expiresAt: '2026-12-01T00:00:00.000Z',
+};
+const write = {
+  remote: site.remote,
+  branch: site.branch,
+  token: 'write',
+  tokenExpiresAt: site.expiresAt,
+};
+const options = {
+  apiUrl: 'https://api.example.com',
+  directory: path.resolve('docs'),
+  subdomain: 'requested',
+};
+const warn = vi.fn();
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.mocked(storage.loadAgentCredentials).mockResolvedValue(null);
+  vi.mocked(storage.saveAgentCredentials).mockResolvedValue(undefined);
+  vi.mocked(auth.registerAgent).mockResolvedValue(credentials);
+  vi.mocked(auth.exchangeAgentToken).mockImplementation(async (_, value) => ({
+    ...value,
+    accessToken: 'access',
+  }));
+  vi.mocked(auth.getAgentIdentity).mockResolvedValue({
+    registrationId: 'reg_1',
+    identityType: 'anonymous',
+  });
+  vi.mocked(deployment.provisionAgentSite).mockResolvedValue(site);
+  vi.mocked(deployment.getAgentWriteToken).mockResolvedValue(write);
+  vi.mocked(config.setAgentSiteMetadata).mockResolvedValue(undefined);
+});
+
+describe('mint deploy', () => {
+  it.each([
+    ['https://leaves.mintlify.com', 'https://allocated.mintlify.site/'],
+    ['https://leaves-dev.mintlify.com', 'https://allocated.mint-dev.mintlify.me/'],
+  ])('prints the site URL for %s', async (apiUrl, siteUrl) => {
+    const result = await prepareAgentDeployment({ ...options, apiUrl }, warn);
+    expect(formatDeployment(result, apiUrl)).toContain(`Site: ${siteUrl}`);
+  });
+  it('continues provisioning after keyring save failure', async () => {
+    vi.mocked(storage.saveAgentCredentials).mockRejectedValue(new Error('locked'));
+    const result = await prepareAgentDeployment(options, warn);
+    expect(result.status).toBe('ready');
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('Continuing for this run'));
+    expect(formatDeployment(result, options.apiUrl)).toContain('https://allocated.mintlify.site');
+  });
+  it('persists the exchanged access token for later commands', async () => {
+    await prepareAgentDeployment(options, warn);
+    expect(storage.saveAgentCredentials).toHaveBeenLastCalledWith(
+      options.apiUrl,
+      options.directory,
+      { ...credentials, accessToken: 'access' }
+    );
+  });
+  it('reuses the current registration and the saved site name', async () => {
+    vi.mocked(storage.loadAgentCredentials).mockResolvedValue(credentials);
+    vi.mocked(config.getAgentSiteMetadata).mockReturnValue({
+      registrationId: 'reg_1',
+      subdomain: 'allocated',
+    });
+    await prepareAgentDeployment({ ...options, subdomain: undefined }, warn);
+    expect(auth.registerAgent).not.toHaveBeenCalled();
+    expect(deployment.provisionAgentSite).toHaveBeenCalledWith(options.apiUrl, 'access', {
+      subdomain: 'allocated',
+      orgName: undefined,
+    });
+  });
+  it('starts a new registration only when explicitly requested or the site expired', async () => {
+    vi.mocked(storage.loadAgentCredentials).mockResolvedValue(credentials);
+    await prepareAgentDeployment({ ...options, newSite: true }, warn);
+    expect(storage.loadAgentCredentials).not.toHaveBeenCalled();
+    expect(auth.registerAgent).toHaveBeenCalledTimes(1);
+  });
+  it('requires an explicit site name for --new even when a previous name is saved', async () => {
+    vi.mocked(config.getAgentSiteMetadata).mockReturnValue({
+      registrationId: 'reg_1',
+      subdomain: 'allocated',
+    });
+    await expect(
+      prepareAgentDeployment({ ...options, newSite: true, subdomain: undefined }, warn)
+    ).rejects.toThrow('Choose a site name with --subdomain');
+    expect(auth.discoverAgentAuth).not.toHaveBeenCalled();
+    expect(auth.registerAgent).not.toHaveBeenCalled();
+    expect(storage.saveAgentCredentials).not.toHaveBeenCalled();
+    expect(deployment.provisionAgentSite).not.toHaveBeenCalled();
+  });
+  it('starts again on confirmed deployment expiry', async () => {
+    vi.mocked(storage.loadAgentCredentials).mockResolvedValue(credentials);
+    vi.mocked(deployment.provisionAgentSite).mockResolvedValueOnce({
+      status: 'expired',
+      created: false,
+      code: 'deployment_already_exists',
+      deploymentId: 'old',
+      subdomain: 'old',
+    });
+    await prepareAgentDeployment(options, warn);
+    expect(auth.registerAgent).toHaveBeenCalledTimes(1);
+    expect(deployment.provisionAgentSite).toHaveBeenCalledTimes(2);
+  });
+  it('does not provision for a claimed identity', async () => {
+    vi.mocked(auth.getAgentIdentity).mockResolvedValue({
+      registrationId: 'reg_1',
+      identityType: 'user_bound',
+      userId: 'user',
+      orgId: 'org',
+    });
+    const result = await prepareAgentDeployment(options, warn);
+    expect(formatDeployment(result, options.apiUrl)).toContain('--new');
+    expect(deployment.provisionAgentSite).not.toHaveBeenCalled();
+  });
+  it('does not replace an existing identity after an authentication outage', async () => {
+    vi.mocked(storage.loadAgentCredentials).mockResolvedValue(credentials);
+    vi.mocked(auth.getAgentIdentity).mockRejectedValue(new Error('unavailable'));
+    await expect(prepareAgentDeployment(options, warn)).rejects.toThrow('unavailable');
+    expect(auth.registerAgent).not.toHaveBeenCalled();
+  });
+  it('does not create a site after failing to read known credentials', async () => {
+    vi.mocked(config.getAgentSiteMetadata).mockReturnValue({
+      registrationId: 'reg_1',
+      subdomain: 'allocated',
+    });
+    vi.mocked(storage.loadAgentCredentials).mockRejectedValue(new Error('locked'));
+    await expect(prepareAgentDeployment(options, warn)).rejects.toThrow('Could not read');
+    expect(auth.registerAgent).not.toHaveBeenCalled();
+  });
+});

package/bin/agent-auth.js

@@ -0,0 +1,103 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { z } from 'zod';
+import { agentRequest, agentResponse } from './agent-http.js';
+const resourceSchema = z.object({ authorization_servers: z.array(z.url()).min(1) });
+const discoverySchema = z.object({
+    issuer: z.url(),
+    token_endpoint: z.url(),
+    agent_auth: z.object({
+        identity_endpoint: z.url(),
+        claim_endpoint: z.url(),
+        identity_types_supported: z.array(z.string()),
+    }),
+});
+const registrationSchema = z.object({
+    id: z.string().min(1),
+    identity: z.object({ assertion: z.string().min(1) }),
+    claim: z.object({ token: z.string().min(1) }),
+});
+const tokenSchema = z.object({
+    access_token: z.string().min(1),
+    expires_in: z.number().positive(),
+    token_type: z.string().regex(/^bearer$/i),
+});
+const identitySchema = z.discriminatedUnion('identityType', [
+    z.object({ registrationId: z.string(), identityType: z.literal('anonymous') }),
+    z.object({
+        registrationId: z.string(),
+        identityType: z.literal('user_bound'),
+        userId: z.string(),
+        orgId: z.string(),
+    }),
+]);
+export function discoverAgentAuth(apiUrl) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const resource = yield agentResponse(yield agentRequest(`${apiUrl}/api/agent/.well-known/oauth-protected-resource`), resourceSchema);
+        const issuer = resource.authorization_servers[0];
+        if (!issuer || new URL(issuer).protocol !== 'https:')
+            throw new Error('Agent authentication requires an HTTPS issuer.');
+        const discovery = yield agentResponse(yield agentRequest(`${issuer.replace(/\/$/, '')}/.well-known/oauth-authorization-server`), discoverySchema);
+        const origin = new URL(issuer).origin;
+        if ([
+            discovery.issuer,
+            discovery.token_endpoint,
+            discovery.agent_auth.identity_endpoint,
+            discovery.agent_auth.claim_endpoint,
+        ].some((url) => new URL(url).origin !== origin)) {
+            throw new Error('Agent authentication endpoints do not match the configured issuer.');
+        }
+        return discovery;
+    });
+}
+export function registerAgent(discovery) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!discovery.agent_auth.identity_types_supported.includes('anonymous')) {
+            throw new Error('Anonymous registration is not enabled for this environment.');
+        }
+        const result = yield agentResponse(yield agentRequest(discovery.agent_auth.identity_endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ type: 'anonymous' }),
+        }), registrationSchema);
+        return {
+            registrationId: result.id,
+            issuer: discovery.issuer,
+            assertion: result.identity.assertion,
+            claimToken: result.claim.token,
+        };
+    });
+}
+export function exchangeAgentToken(discovery, credentials) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if (new URL(credentials.issuer).origin !== new URL(discovery.issuer).origin) {
+            throw new Error('Saved agent credentials belong to another issuer.');
+        }
+        if (credentials.accessToken && ((_a = credentials.accessTokenExpiresAt) !== null && _a !== void 0 ? _a : 0) > Date.now() + 30000) {
+            return Object.assign(Object.assign({}, credentials), { accessToken: credentials.accessToken });
+        }
+        const token = yield agentResponse(yield agentRequest(discovery.token_endpoint, {
+            method: 'POST',
+            body: new URLSearchParams({
+                grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+                assertion: credentials.assertion,
+            }),
+        }), tokenSchema);
+        return Object.assign(Object.assign({}, credentials), { accessToken: token.access_token, accessTokenExpiresAt: Date.now() + token.expires_in * 1000 });
+    });
+}
+export function getAgentIdentity(apiUrl, accessToken) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return agentResponse(yield agentRequest(`${apiUrl}/api/agent/identity`, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        }), identitySchema);
+    });
+}

package/bin/agent-claim.js

@@ -0,0 +1,39 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { z } from 'zod';
+import { discoverAgentAuth } from './agent-auth.js';
+import { agentRequest, agentResponse } from './agent-http.js';
+import { DASHBOARD_URL } from './constants.js';
+const claimAttemptSchema = z.object({ attempt: z.object({ verification_uri: z.url() }) });
+export function createAgentClaimLink(apiUrl, credentials, email) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const loginHint = z.email().parse(email);
+        const discovery = yield discoverAgentAuth(apiUrl);
+        if (new URL(discovery.issuer).origin !== new URL(credentials.issuer).origin) {
+            throw new Error('Saved agent credentials belong to another issuer.');
+        }
+        const claim = yield agentResponse(yield agentRequest(discovery.agent_auth.claim_endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                type: 'service_auth',
+                claim_token: credentials.claimToken,
+                login_hint: loginHint,
+            }),
+        }), claimAttemptSchema);
+        const token = z
+            .string()
+            .min(1)
+            .parse(new URL(claim.attempt.verification_uri).searchParams.get('token'));
+        const claimUrl = new URL('/agent-claim', DASHBOARD_URL);
+        claimUrl.searchParams.set('token', token);
+        return claimUrl.toString();
+    });
+}