Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
refactor(connected-accounts): nest ACL under aclConfigForShared, match merged 9902 contract
venkat82752efd886324
diff --git a/.changeset/connected-accounts-acl.md b/.changeset/connected-accounts-acl.mdindex 044eb0e74..83bcaf958 100644--- a/.changeset/connected-accounts-acl.md+++ b/.changeset/connected-accounts-acl.md@@ -8,8 +8,9 @@ Surfaces three Apollo-side features that previously had no SDK wrappers:- **`accountType` on create**: `composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' })` creates a SHARED connection. Default remains `PRIVATE`. SHARED is reachable from a tool-router session by other users in the project, but only when explicitly pinned and only when the requesting `userId` passes the connection's ACL.- **`accountType` on retrieve**: `get()` and `list()` responses now include `accountType` (`'PRIVATE' | 'SHARED'`).-- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the per-user ACL on a SHARED connection via `PATCH /connected_accounts/{id}`. Backend rejects ACL writes on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list.-- **ACL fields on retrieve**: `get()` and `list()` responses expose `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` when the caller is the connection's creator or is using a project/org API key. Other callers see the row without these fields (left as `undefined` in the SDK shape).+- **`aclConfigForShared` on create + retrieve**: per-user ACL block — `{ allowAllUsers, allowedUserIds, notAllowedUserIds }`. On responses the whole block is `undefined` for non-creator/non-API-key callers (the backend strips it), so callers can distinguish *"I can't see the ACL"* from *"ACL is the default deny-by-default state"*.+- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the ACL via `PATCH /connected_accounts/{id}` (the SDK serialises to the wire's `acl_config_for_shared` block). Backend rejects ACL writes on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required.+- **`ToolRouterSession.authorize()` options gain `accountType` + `aclConfigForShared`**, so a SHARED connection with an ACL can be created in one call from inside a tool-router session.ACL resolution rule (deny wins):@@ -18,12 +19,14 @@ ACL resolution rule (deny wins):3. requesting `userId` ∈ `allowedUserIds` → ALLOW4. otherwise → DENY (deny-by-default)+Backend caps: each ACL list ≤1000 entries; each `userId` 1..256 chars. The SDK enforces these caps via Zod at the input boundary.+New error classes:- `ComposioSharedAccessDeniedError` (403) — surfaces from direct `connectedAccountId` execution paths when the requesting user fails the ACL.- `ComposioAclOnlyForSharedError` (400) — sent ACL fields on a PRIVATE row.- `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.-No breaking changes. Existing `link()` callers without `accountType` get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.+No breaking changes. Existing `link()` callers without the new options get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.Python SDK gets the matching change in the same release train.diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.tsindex 93c79ae10..7b50c19d2 100644--- a/ts/packages/core/src/models/ConnectedAccounts.ts+++ b/ts/packages/core/src/models/ConnectedAccounts.ts@@ -52,10 +52,17 @@ import { ConnectionData } from '../types/connectedAccountAuthStates.types';// warning on every initiate() call.let _legacyInitiateWarningEmitted = false;-// Wire-level fields added by Hermes #9860 / #9882 (account_type) and #9902-// (ACL). Once @composio/client is regenerated against a backend spec that-// includes these, this local extension can be removed and we can rely on the-// generated `LinkCreateParams` directly.+// Wire-level fields added by Hermes #9860 / #9882 (account_type) and+// merged #9902 (ACL). 9902 nests ACL under a single `acl_config_for_shared`+// object (single JSONB column under the hood). Once @composio/client is+// regenerated against the post-9902 backend spec, this local extension can+// be removed and we can rely on the generated `LinkCreateParams` directly.+type AclConfigWireShape = {+ allow_all_users?: boolean;+ allowed_user_ids?: string[];+ not_allowed_user_ids?: string[];+};+type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never? never: Record<string, unknown> & {@@ -64,21 +71,40 @@ type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends neveralias?: string;callback_url?: string;account_type?: 'PRIVATE' | 'SHARED';- allow_all_users?: boolean;- allowed_user_ids?: string[];- not_allowed_user_ids?: string[];+ acl_config_for_shared?: AclConfigWireShape;};-// Wire-level body for PATCH /connected_accounts/{id} with ACL fields-// (Hermes #9902). Mirrors the same forward-compat pattern as-// `LinkCreateBodyWithAcl` above.+// Wire-level body for PATCH /connected_accounts/{id} with ACL.type ConnectedAccountPatchBodyWithAcl = {alias?: string;- allow_all_users?: boolean;- allowed_user_ids?: string[];- not_allowed_user_ids?: string[];+ acl_config_for_shared?: AclConfigWireShape;};+/**+ * Serialise the SDK's `aclConfigForShared` (camelCase, top-level optional)+ * to the wire's `acl_config_for_shared` block. Returns `undefined` when the+ * caller didn't pass anything (PATCH-style "don't touch ACL"); returns+ * `{}` when the caller passed an explicit empty object (also "no fields to+ * change", but encodes the explicit intent — the backend treats both the+ * same way today).+ */+function serializeAclConfigForWire(+ acl:+ | {+ allowAllUsers?: boolean;+ allowedUserIds?: string[];+ notAllowedUserIds?: string[];+ }+ | undefined+): AclConfigWireShape | undefined {+ if (acl === undefined) return undefined;+ return {+ ...(acl.allowAllUsers !== undefined && { allow_all_users: acl.allowAllUsers }),+ ...(acl.allowedUserIds !== undefined && { allowed_user_ids: acl.allowedUserIds }),+ ...(acl.notAllowedUserIds !== undefined && { not_allowed_user_ids: acl.notAllowedUserIds }),+ };+}+/*** ConnectedAccounts class*@@ -396,17 +422,14 @@ export class ConnectedAccounts {}const opts = requestOptions.data;+ const aclWire = serializeAclConfigForWire(opts.aclConfigForShared);const body: LinkCreateBodyWithAcl = {auth_config_id: authConfigId,user_id: userId,...(opts.callbackUrl && { callback_url: opts.callbackUrl }),...(opts.alias != null && { alias: opts.alias }),...(opts.accountType !== undefined && { account_type: opts.accountType }),- ...(opts.allowAllUsers !== undefined && { allow_all_users: opts.allowAllUsers }),- ...(opts.allowedUserIds !== undefined && { allowed_user_ids: opts.allowedUserIds }),- ...(opts.notAllowedUserIds !== undefined && {- not_allowed_user_ids: opts.notAllowedUserIds,- }),+ ...(aclWire !== undefined && { acl_config_for_shared: aclWire }),};try {@@ -683,18 +706,10 @@ export class ConnectedAccounts {}const body: ConnectedAccountPatchBodyWithAcl = {- ...(parsedParams.data.allowAllUsers !== undefined && {- allow_all_users: parsedParams.data.allowAllUsers,- }),- ...(parsedParams.data.allowedUserIds !== undefined && {- allowed_user_ids: parsedParams.data.allowedUserIds,- }),- ...(parsedParams.data.notAllowedUserIds !== undefined && {- not_allowed_user_ids: parsedParams.data.notAllowedUserIds,- }),+ acl_config_for_shared: serializeAclConfigForWire(parsedParams.data),};- // Cast retained until @composio/client adds ACL fields to+ // Cast retained until @composio/client adds acl_config_for_shared to// ConnectedAccountPatchParams.await this.client.connectedAccounts.patch(nanoid,diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex 52c5b9afe..ee12f5356 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -26,7 +26,11 @@ import {import { SessionMetaToolOptions } from '../types/modifiers.types';import { ConnectionRequest } from '../types/connectionRequest.types';import { createConnectionRequest } from './ConnectionRequest';-import { ConnectedAccountStatuses } from '../types/connectedAccounts.types';+import {+ ConnectedAccountStatuses,+ ConnectedAccountType,+ ConnectedAccountAclConfig,+} from '../types/connectedAccounts.types';import { transform } from '../utils/transform';import { ToolkitConnectionStateSchema } from '../types/toolRouter.types';import { ValidationError } from '../errors';@@ -303,16 +307,47 @@ export class ToolRouterSession</*** Initiate an authorization flow for a toolkit.* Returns a ConnectionRequest with a redirect URL for the user.+ *+ * `accountType` and `aclConfigForShared` (Hermes #9860, #9902) let the+ * caller create a SHARED connection with a per-user ACL in one flow.+ * Default behaviour (omit both) creates a PRIVATE connection.*/async authorize(toolkit: string,- options?: { callbackUrl?: string; alias?: string }+ options?: {+ callbackUrl?: string;+ alias?: string;+ accountType?: ConnectedAccountType;+ aclConfigForShared?: ConnectedAccountAclConfig;+ }): Promise<ConnectionRequest> {- const response = await this.client.toolRouter.session.link(this.sessionId, {+ const aclWire =+ options?.aclConfigForShared === undefined+ ? undefined+ : {+ ...(options.aclConfigForShared.allowAllUsers !== undefined && {+ allow_all_users: options.aclConfigForShared.allowAllUsers,+ }),+ ...(options.aclConfigForShared.allowedUserIds !== undefined && {+ allowed_user_ids: options.aclConfigForShared.allowedUserIds,+ }),+ ...(options.aclConfigForShared.notAllowedUserIds !== undefined && {+ not_allowed_user_ids: options.aclConfigForShared.notAllowedUserIds,+ }),+ };+ // Cast retained until @composio/client adds account_type ++ // acl_config_for_shared to SessionLinkParams (Hermes #9860 + #9902).+ const body = {toolkit,...(options?.callbackUrl && { callback_url: options.callbackUrl }),...(options?.alias != null && { alias: options.alias }),- });+ ...(options?.accountType !== undefined && { account_type: options.accountType }),+ ...(aclWire !== undefined && { acl_config_for_shared: aclWire }),+ };+ const response = await this.client.toolRouter.session.link(+ this.sessionId,+ body as unknown as Parameters<typeof this.client.toolRouter.session.link>[1]+ );return createConnectionRequest(this.client,diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.tsindex 9f9157fca..be5e9d41f 100644--- a/ts/packages/core/src/types/connectedAccounts.types.ts+++ b/ts/packages/core/src/types/connectedAccounts.types.ts@@ -51,35 +51,58 @@ export type ConnectedAccountType =/*** Per-user access control for a SHARED connected account. Inert for PRIVATE.*+ * On the wire this lives under `acl_config_for_shared` — a single JSONB+ * column on `connected_accounts`. The SDK exposes the inner shape as+ * `aclConfigForShared` on inputs and responses (omit the block to mean+ * "don't touch ACL" on create / PATCH; absence on a response means the+ * caller isn't allowed to see the ACL).+ ** Resolution rule (deny wins):* 1. requesting userId in `notAllowedUserIds` → DENY* 2. `allowAllUsers === true` → ALLOW* 3. requesting userId in `allowedUserIds` → ALLOW* 4. otherwise → DENY (deny-by-default)*- * Default state (`allowAllUsers=false`, both arrays empty) means only the- * connection's creator can use it. The creator must grant access explicitly.+ * Default state (block omitted or `{}`) means only the connection's creator+ * can use it. The creator must grant access explicitly.*- * Lists are capped at 1000 entries each by the backend.+ * Backend caps: each list ≤1000 entries; each user_id 1..256 chars.*/-const ACL_LIST_LIMIT = 1000;-export const ConnectedAccountAclSchema = z.object({+const ACL_LIST_MAX_LENGTH = 1000;+const ACL_USER_ID_MAX_LENGTH = 256;+const aclUserIdString = z.string().min(1).max(ACL_USER_ID_MAX_LENGTH);++export const ConnectedAccountAclConfigSchema = z.object({allowAllUsers: z.boolean().optional().describe('Wildcard "any user_id in the project" allow toggle. Default false.'),allowedUserIds: z- .array(z.string())- .max(ACL_LIST_LIMIT)+ .array(aclUserIdString)+ .max(ACL_LIST_MAX_LENGTH).optional().describe('Explicit allow list (developer-assigned user_id strings). Default [].'),notAllowedUserIds: z- .array(z.string())- .max(ACL_LIST_LIMIT)+ .array(aclUserIdString)+ .max(ACL_LIST_MAX_LENGTH).optional().describe('Explicit deny list. Wins over allow on conflict. Default [].'),});-export type ConnectedAccountAcl = z.infer<typeof ConnectedAccountAclSchema>;+export type ConnectedAccountAclConfig = z.infer<typeof ConnectedAccountAclConfigSchema>;++/**+ * Resolved ACL as it appears on responses (creator / API-key callers).+ * All three fields are populated when the block is visible; the block+ * itself is absent for non-creator cookie callers.+ */+export const ConnectedAccountAclConfigResponseSchema = z.object({+ allowAllUsers: z.boolean(),+ allowedUserIds: z.array(z.string()),+ notAllowedUserIds: z.array(z.string()),+});+export type ConnectedAccountAclConfigResponse = z.infer<+ typeof ConnectedAccountAclConfigResponseSchema+>;export const CreateConnectedAccountParamsSchema = z.object({authConfig: z.object({@@ -163,9 +186,7 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{createdAt: string;updatedAt: string;accountType?: ConnectedAccountType;- allowAllUsers?: boolean;- allowedUserIds?: string[];- notAllowedUserIds?: string[];+ aclConfigForShared?: ConnectedAccountAclConfigResponse;}> = z.object({id: z.string(),authConfig: ConnectedAccountAuthConfigSchema,@@ -190,12 +211,12 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{createdAt: z.string(),updatedAt: z.string(),accountType: ConnectedAccountTypeSchema.optional(),- // ACL fields are only present on responses when the caller is the creator- // or is using a project/org API key — cookie callers who can use the- // connection but aren't its creator see the row without these fields.- allowAllUsers: z.boolean().optional(),- allowedUserIds: z.array(z.string()).optional(),- notAllowedUserIds: z.array(z.string()).optional(),+ // `acl_config_for_shared` is only present on responses when the caller is+ // the connection's creator or is using a project/org API key. Non-creator+ // cookie callers see the row without this block — left as `undefined`+ // here so callers can distinguish "I can't see the ACL" from "ACL is the+ // default deny-by-default state".+ aclConfigForShared: ConnectedAccountAclConfigResponseSchema.optional(),});export type ConnectedAccountRetrieveResponse = z.infer<@@ -279,16 +300,16 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({*/accountType: ConnectedAccountTypeSchema.optional(),/**- * ACL for SHARED connections. Ignored when `accountType !== 'SHARED'`; the- * backend rejects ACL fields on a `PRIVATE` connection with `AclOnlyForShared`.+ * Per-user ACL for SHARED connections. Only valid when+ * `accountType === 'SHARED'` — the backend rejects ACL on a PRIVATE+ * connection with `ComposioAclOnlyForSharedError` (400).*- * Default (deny-by-default): only the creator can use the connection. Grant- * access by setting `allowAllUsers: true` or by listing user IDs in- * `allowedUserIds`. `notAllowedUserIds` always wins over allow.+ * Omit the block (or pass `{}`) to keep the deny-by-default state: only the+ * creator can use the connection. Grant access by setting+ * `allowAllUsers: true` or listing user IDs in `allowedUserIds`.+ * `notAllowedUserIds` always wins over allow.*/- allowAllUsers: ConnectedAccountAclSchema.shape.allowAllUsers,- allowedUserIds: ConnectedAccountAclSchema.shape.allowedUserIds,- notAllowedUserIds: ConnectedAccountAclSchema.shape.notAllowedUserIds,+ aclConfigForShared: ConnectedAccountAclConfigSchema.optional(),});export type CreateConnectedAccountLinkOptions = z.infer<typeof CreateConnectedAccountLinkOptionsSchema@@ -315,16 +336,18 @@ export const UpdateConnectedAccountParamsSchema = z.object({});/**- * Params for `composio.connectedAccounts.updateAcl()`.+ * Params for `composio.connectedAccounts.updateAcl()`. Mirrors the inner+ * shape of the wire's `acl_config_for_shared` block — the SDK adds the+ * outer nesting at the boundary, so callers pass the three fields flat.*- * PATCH-style semantics — omit a field to leave it unchanged; pass an empty- * array to clear an allow/deny list. Backend rejects ACL writes on a- * `PRIVATE` connection with `AclOnlyForShared` (400).+ * PATCH-style semantics — omit a field to leave it unchanged; pass an+ * empty array to clear an allow/deny list. Backend rejects ACL writes on+ * a PRIVATE connection with `ComposioAclOnlyForSharedError` (400).** Each field is optional, but at least one must be provided — passing an* empty object is rejected as a no-op.*/-export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclSchema.refine(+export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclConfigSchema.refine(acl =>acl.allowAllUsers !== undefined ||acl.allowedUserIds !== undefined ||diff --git a/ts/packages/core/src/utils/transformers/connectedAccounts.ts b/ts/packages/core/src/utils/transformers/connectedAccounts.tsindex c6f21dd68..c831535ca 100644--- a/ts/packages/core/src/utils/transformers/connectedAccounts.ts+++ b/ts/packages/core/src/utils/transformers/connectedAccounts.ts@@ -18,13 +18,15 @@ type RawConnectedAccountResponseWithLabels = () & {word_id?: string | null;alias?: string | null;- // account_type / ACL fields are added by Hermes #9860, #9882, #9902.- // Cast lives here until @composio/client regenerates against a backend- // spec that contains them.+ // account_type / acl_config_for_shared are added by Hermes #9860, #9882,+ // and the merged #9902. Cast lives here until @composio/client regenerates+ // against a backend spec that contains them.account_type?: 'PRIVATE' | 'SHARED';- allow_all_users?: boolean;- allowed_user_ids?: string[];- not_allowed_user_ids?: string[];+ acl_config_for_shared?: {+ allow_all_users: boolean;+ allowed_user_ids: string[];+ not_allowed_user_ids: string[];+ };};/**@@ -78,13 +80,18 @@ export function transformConnectedAccountResponse(updatedAt: response.updated_at,testRequestEndpoint: response.test_request_endpoint,accountType: responseWithLabels.account_type,- // ACL fields are conditionally visible — backend strips them for- // non-creator/non-API-key callers. Forward `undefined` when absent- // rather than synthesising defaults, so callers can distinguish "I- // can't see the ACL" from "ACL is empty".- allowAllUsers: responseWithLabels.allow_all_users,- allowedUserIds: responseWithLabels.allowed_user_ids,- notAllowedUserIds: responseWithLabels.not_allowed_user_ids,+ // `acl_config_for_shared` is conditionally visible — backend strips+ // the whole block for non-creator/non-API-key callers. Forward+ // `undefined` when absent rather than synthesising defaults, so+ // callers can distinguish "I can't see the ACL" from "ACL is the+ // default deny-by-default state".+ aclConfigForShared: responseWithLabels.acl_config_for_shared+ ? {+ allowAllUsers: responseWithLabels.acl_config_for_shared.allow_all_users,+ allowedUserIds: responseWithLabels.acl_config_for_shared.allowed_user_ids,+ notAllowedUserIds: responseWithLabels.acl_config_for_shared.not_allowed_user_ids,+ }+ : undefined,}));}