用于 TypeScript / Node.js 的更改 SDK

正式类型SDK 换行 ——AI代理的特权准入管理:金库证书,默认拒绝政策下至参数,对风险电话的审批政策,以及每一次通过Alter通话的审计线索.

提供商通过 Alter 代理执行呼叫 。 全权证书留在Alter,在那里执行政策和批准要求.

安装

npm install @alter-ai/alter-sdk

在Node.js 20+上运行,用于服务器侧环境. 关于浏览器侧面 OAuth 弹出流量,请参见 @alter-ai/connect。 。 。 .

快速实例

制作一个经过认证的API呼叫——任何符号都不会触碰应用程序代码.

import { App, HttpMethod } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: "<api-key>" });
try {
  let response = await app.proxyRequest({ method: HttpMethod.POST, url: "https://api.example.com/resource", grantId: "<grant-id>",
      json: { example: "payload" }, });
  if ("status" in response) {
    for (const gate of response.gates) {
      console.log("Approval required:", gate.approvalUrl);
    }
    response = await app.awaitApproval(response.approvalId);
  }
  console.log(response.statusCode, await response.bodyJson());
} finally {
  await app.close();
}

需要全面走过——注册、密钥薄荷、奥奥特——请参看 快速启动。 。 。 .

供应商电话

使用 app.proxy_request(...) (毕 app.proxyRequest({...}) (TypeScript)用于提供商呼叫. 后端持有证书,执行请求,并返回提供者的结果.

• app.proxyUploadRequest(...) ——大型请求机体的代理模式:机体由大小和SHA-256宣布,每条政策运行,然后发送一次,没有Alter持有. app.deliverApprovedUpload(...) 发送一个需要批准.
• app.proxyStreamRequest(...) ——下载和服务器-恒星事件代理模式:提供方字节流通过后压. 二进制请求机构最多为5个米B. 也不能等待批准.

代理模式返回一个 ApprovalResult 与 statusCode,反应头/体, bodyTruncated,以及 durationMs (提供方往返毫秒; null 页:1 老年工人创造的成果)。 管理机密的副主管/村长 注射和AWS SigV4——包括查询参数、原始/JSON体和 临时会话符号——由后端注入.

见 服务商呼叫 用于执行边界.

政策规则助手

contentMatchRule(...) 建立操作意识请求规则 withConstraints({ rule }) 在第一次API呼叫前进行本地验证。 它接受操作ids(一个编目提供者的认证ids,或者IDs一个自定义集成开发者映射)和/或操作家族,可选参数条件,以及三种效果之一: deny, (中文(简体) ), redact,或 step_up。自定义集成的操作项目中,只有请求的查询字符串参数,与文本相比较,所以任何其他参数条件(正文、标题或路径参数,或数字比较)都否认匹配请求;a redact 规定只拒绝自定义操作,通过一个家庭到达的编辑拒绝请求。 已命名的外出请求- 机构字段; 需要升级 maxSessionAgeSeconds 作为整数从 1 结束 86400参数条件与 equals,光标运算符 any_in 编号 : not_subset_of (何处) *, (中文(简体) ), ? 财务报告和审定财务报表 [...] 他们的双胞胎 in 编号 : not_all_in (与字面上比较的相同的数组,对大小写不敏感—— in 当任何成员被列入名单时, not_all_in 当并非所有成员都是成员时; 将它们用于文字声明、 ids 和通道时, 存在运算符 exists (布尔: true 当请求带有参数时起火, false 当它没有的时候,数字 gt 编号 : gte 编号 : lt 编号 : lte,以及 outside_windows。 。 。 .

operationAllowlistRule(...) 是积极的对应:它构建一个 operation_allowlist 请求规则,根据规则,只可运行列出的操作ID和/或操作家族。 每个其它的分类操作都被拒绝,任何请求目录都不能分类. 一个链上有几个允许列表相互交叉,因此每个请求允许列表只能缩小访问范围. 至少其中一个 operations 编号 : families 需要时间.

import { operationAllowlistRule } from "@alter-ai/alter-sdk";

const readOnly = app.withConstraints({
  rule: operationAllowlistRule({ operations: ["query", "generalledger/query_a_report"] }),
});

追回遗失赠款错误

当请求因用户尚未授权提供商而失败时,SDK会从打出的错误上暴露恢复上下文,这样您就可以在不从呼叫站点重新找到任何东西的情况下驱动重新同意的流量:

import { Agent, HttpMethod, NoDelegatedGrantError } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: "<agent-api-key>" });
try {
  try {
    await agent.proxyRequest({ method: HttpMethod.GET, url: "https://api.example.com/v1/resources", provider: "<provider-id>",
      userToken: jwt, });
  } catch (e) {
    if (e instanceof NoDelegatedGrantError) {
      const session = await agent.createConnectSessionForError(e, {
        allowedOrigin: "https://app.example.com",
      });
      // Surface session.connectUrl to the user, then wait for consent.
      const results = await agent.pollConnectSession(session.sessionToken);
      let response = await agent.proxyRequest({ method: HttpMethod.GET, url: "https://api.example.com/v1/resources", grantId: results[0].grantId, userToken: jwt });
      if ("status" in response) {
        for (const gate of response.gates) {
          console.log("Approval required:", gate.approvalUrl);
        }
        response = await agent.awaitApproval(response.approvalId);
      }
      console.log(response.statusCode);
    } else {
      // Re-throw every other error class so network errors and
      // programming bugs aren't silently swallowed.
      throw e;
    }
  }
} finally {
  await agent.close();
}

createConnectSessionForError 财务报告和审定财务报表 pollConnectSession 两者均可查阅 App 财务报告和审定财务报表 Agent 这样渔获区块就可以从任何客户中恢复. 对于 CredentialRevokedError,帮助将会话绑定到错误的精确度 赠款。 成功的修复报告 operation === "reauth" 和同样的 grantId ——与返回已连接的赠款的完成一样: "reauth" 也就是说,现在的一笔赠款 带着它保存的id回来了,而不是 一定是断了 给目标取名是一种优化,而不是要求: 错误不包含 赠款 id(一个较老的后端), 补助金 调用者无法地址(通过) userToken )或不再使用的赠款 活动全部返回到报告正常会话 operation === "creation" 带有新的 grantId读取结果的ID.

如果 Alter 观察会话待决, 但不会在本地之前收到回话 截止或服务器过期,投票投放 ConnectTimeoutError检查 error.details.reason (单位:千美元)poll_deadline_elapsed 或者说 session_expired) (中文(简体) ). 一个提供者 可能将授权错误保留在自己的页面上,并且永远不重定向,所以 例外列表 : 而不是声称一个确切的提供者错误 Alter 没有收到.

如果新的供应商授权无法启动, pollConnectSession 掷出 ConnectConfigError。这包括输入 provider_configuration_unavailable 财务报告和审定财务报表 shared_dev_credential_unavailable 终端; 显示错误的安全消息到 调用并请求应用程序管理员纠正提供者可用性 在创建新会话之前。 现有的赠款仍然可以使用.

ConnectConfigError 还有第三个航站楼, managed_oauth_scope_approval_required,抛出 createConnectSession (HTTP 409号文件) pollConnectSession: 申请的范围 请求超过 Alter 管理的 OAuth 客户端的核准。 应用程序 管理员不能扩大范围——联系Alter以便批准范围,或 将应用程序的配置范围缩小到已核准的套件, 并且只有那时 创建新会话。 反应是 retryable: false所以每个新鲜的 在批准更改之前,会话同样失败。 打开 createConnectSession 路径错误 details 是全反应机构,所以 details.details.unapproved_scopes 确切的哪些范围需要批准.

第四个终端, agent_allowlist_exceeded (HTTP 422) 拒绝连接 (b) 向代理人代表的届会agent键,或 代理用户自己的密钥 ),当代理机的能力允许列表不能使用用户将使用什么 赠款. createConnectSession (和 connect(),创建会话 在用户发送到提供者之前扔出,支票在 details.details.detail_reason (单位:千美元)provider_not_allowlisted, (中文(简体) ), scopes_not_allowlisted 或者说 grant_scopes_malformed和 每个被拒绝的提供者在 details.details.uncovered_providers。 。 。 . pollConnectSession 在用户之前缩小许可列表时丢出 完成; 仅带失败 details.error_code管理员 扩大代理许可列表,或者应用程序缩小其范围 请求或通过一个封面 scopeConstraint在新的会议之前。 A 类 既不提供会话名称 allowedProviders 也没有 requiredScopes 当代理设备无法使用时,则将其删除,并列入 ConnectSession.droppedProviders (单位:千美元)providerId, (中文(简体) ), check) (中文(简体) ). 继续 delegate() 掷出 BackendError 同一个代码.

NoDelegatedGrantError 财务报告和审定财务报表 GrantNotFoundError 携带 providerId 编号 : agentId 编号 : appUserId 原始搜索为身份模式时的恢复上下文; CredentialRevokedError 携带 providerId 编号 : appUserId见 引用错误 为整个地表.

打开 代理人 路径, a grant_not_found 明确 grantId 表面为 AgentDelegationMissingError - 一个子类 GrantNotFoundError基地级的渔获物仍然在燃烧 这意味着赠款没有下放给该代理人,或者在需要代理人自己授权身份时,通过用户/基地赠款ID(从 agent.listGrants) (中文(简体) ). 通过Connect( 连接) 授权代理恢复agent.createConnectSession),或由提供者解决而不是通过 grantId。 。 。 .

管理机密连接:用户自己的密钥,或代表团

一个连接会话名称为管理下的秘密提供者( O)provider,提供商的"涕")和用户. shall是每个app独有的:几个提供者可以共享一个模板或显示名称,因此shall而不是模板名称选择一个. 当用户对提供者不持有赠款时,主机页面会询问自己的API密钥;当他们这样做时,会让他们批准其使用. 与 agent,用户的访问也授权给该代理人:

import { App } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: "<app-api-key>" });

const session = await app.createManagedSecretConnectSession({
  provider: "<provider-slug>",
  userToken: "<user-jwt>",
  agent: "<agent-id-or-name>", // optional: omit for the application's own use
  requestedGrant: { label: "<label>" }, // optional: names the key's grant
});
// Open session.connectUrl in the user's browser (a popup, the system browser
// or the @alter-ai/connect widget). session.path is "key_entry" when the user
// will enter a key, "fast_path" when they already hold a grant.

用户签入,输入密钥(或取出赠出),可自行设定使用限额并进行确认. 关键是用户自己的授权:应用程序可以撤销但不能编辑. 通过赠款,将它作为OAuth赠款使用: grantId,或 provider 与用户的代号,解决一次赠与。 几笔相应的赠款 AmbiguousGrantError (HTTP 409电话) ambiguous_grant); 以 label 或者说 account,或通过 grantId。一旦用户设定了限制,则使用 proxyRequest() (单位:千美元)request() 掷出 RestrictedGrantRequiresProxyError) (中文(简体) ). repairGrantId 让用户替换其密钥到位( 相同 ) grantId) (中文(简体) ).

一个特工自求多福 agent.createManagedSecretConnectSession,不需要目标:

import { Agent } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: "<agent-api-key>" });

const session = await agent.createManagedSecretConnectSession({
  provider: "<provider-slug>",
  userToken: "<user-jwt>",
  delegable: true, // optional: ask that this agent may share the access onward
});
// On approval the page delivers the delegation id this agent passes as
// grantId to agent.proxyRequest() (a delegation is proxy-only).

用户决定是否可以继续分享代表团:对于代理商自己的请求,页面的复选框会从一个新的代表团开始,所以用户会选择代理人进入;对于现有的代表团,它会从存储的设置开始. session.delegableRequested 呼应所请.

ConnectConfigError 系指管理员或应用程序必须先更改某事; error.details.error 说吧secret_not_found, (中文(简体) ), secret_template_mismatch, (中文(简体) ), idp_signin_not_configured, (中文(简体) ), binding_hosts_required, (中文(简体) ), provider_contract_repair_required, (中文(简体) ), no_eligible_grants) (中文(简体) ). 相对于一个在调用之前的替代后端, SDK 投出 ServerFeatureUnsupportedError。 。 。 . templateSlug 财务报告和审定财务报表 delegatedAgentId 已贬值的化名 provider 财务报告和审定财务报表 agent:他们仍然工作并发射 DeprecationWarning。 。 。 .

进一步授权(代理人)

持有赠款的代理人可以向另一代理人转交一份范围缩小的复制件——而不要求证书所有人再次表示同意。 使用 agent.delegate() 向第二名代理人发放儿童补助金:

import { Agent, GrantNotDelegableError } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: "<agent-api-key>" });

try {
  const result = await agent.delegate(
    "<grant-id>",                // a grant this agent already holds
    "<other-agent-id>",          // the agent that should receive access
    {
      scopeConstraint: ["resource:write"], // optional: narrow to fewer scopes
      ttlSeconds: 3600,                // optional: shorten the lifetime
    },
  );
  console.log(result.grantId, result.depth, result.expiresAt);
} catch (e) {
  if (e instanceof GrantNotDelegableError) {
    // e.detailReason says why: "holder_not_delegable" (the user did not allow
    // onward sharing), "ceiling_off" (the operator ceiling is off), ...
    console.warn("cannot share onward:", e.detailReason);
  } else {
    throw e;
  }
} finally {
  await agent.close();
}

持有的赠款必须是作为 可删除:用户在批准时允许继续共享(与 delegable: true —— 管理下的秘密提供者授权政策或OAuth提供者的代理人共享设置—— 仍然必须允许每次通话。 儿童只能缩小范围——缩小范围,缩短寿命——永远不会扩大。 赠款数额减少 scopeConstraint 仅使用代理服务器 : agent.proxyRequest(...)。每跳一次就选择代表团:通过 delegable: true 只有在应允许受援方进一步授权的情况下。 奥米 delegable (a) 保持现有代表团的设置,然后,新的代表团就成为一席之地,而再次将权力交给同一机构则保持目前的设置不变 delegable: false 使代表团关闭.

delegate() 还要 rules, (中文(简体) ), tags 财务报告和审定财务报表 label: 规则是与孩子一起创建的,并且只能缩小,标记从父母的开始,接受者通过 label 打开 proxyRequest() 财务报告和审定财务报表 listGrants()。结果 approverWarnings 名称 require_approval 规定其批准人未对照目录进行核查。 应用程序标记现有赠款 app.updateGrantTags(grantId, tags),将整个地图替换,并将新地图标记为 tags 打开 createConnectSession(), (中文(简体) ), createManagedSecretConnectSession() 或者说 mintGrant()。 。 。 .

agent.listGrants() 返回每笔赠款 parentGrantId (赠款是根据该赠款计算的,或 null 用于根)和 depth (它与根相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去.

OpenTeleometry 微量传播

当应用程序运行 OpenTeleometry SDK 时, Alter 请求自动携带活动跨度的 W3C traceparent因此,审计线索——以及任何跨越组织流到自己的OTLP收集器的线索——加入了应用程序的痕迹. 不需要配置 : @opentelemetry/api 是一个 选项 sDK从未安装或要求的对等依赖性——当应用程序拥有它时,SDK使用它(包括在pnpm的孤立模式下和Yarn PnP下);没有它(或没有活动跨度),SDK的行为与以前完全一样.

import { trace } from "@opentelemetry/api";
import { App, HttpMethod } from "@alter-ai/alter-sdk";

const tracer = trace.getTracer("the-application");

const tracedApp = new App({ apiKey: "<api-key>" });
try {
  await tracer.startActiveSpan("handle-user-request", async (span) => {
    try {
      // This call's audit events share the surrounding trace's ids.
      let response = await tracedApp.proxyRequest({ method: HttpMethod.GET, url: "https://api.example.com/v1/resources", grantId: "<grant-id>" });
      if ("status" in response) {
        for (const gate of response.gates) {
          console.log("Approval required:", gate.approvalUrl);
        }
        response = await tracedApp.awaitApproval(response.approvalId);
      }
      console.log(response.statusCode);
    } finally {
      span.end();
    }
  });
} finally {
  await tracedApp.close();
}

文档

完整文件已经 https://docs.alterauth.com (中文(简体) )。 。 。 .

许可证

麻省理工学院. 见 LICENSE。 。 。 .

支助

电子邮件 创建者@ alterauth.com 或打开一个问题在 https://github.com/alter-ai/alter-vault 页面存档备份,存于互联网档案馆。 。 。 .