@devries-cameron20 / composio-1 / commits / 752efd886
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

refactor(connected-accounts): nest ACL under aclConfigForShared, match merged 9902 contract

The original draft built against 9902's PR description shape — three flat top-level ACL fields (`allow_all_users`, `allowed_user_ids`, `not_allowed_user_ids`). The merged design (deployed to staging now) collapsed them into a single JSONB column and exposes them on the wire as a nested `acl_config_for_shared` object. This commit reshapes the SDK to match. Wire contract changes verified against staging-backend.composio.dev: POST /connected_accounts/link body: account_type, acl_config_for_shared POST /connected_accounts body.connection.{account_type, acl_config_for_shared} PATCH /connected_accounts/{id} body: alias, connection, acl_config_for_shared GET /connected_accounts item.{account_type, acl_config_for_shared?} GET /connected_accounts/{id} response.{account_type, acl_config_for_shared?} POST /tool_router/session/{id}/link body: account_type, acl_config_for_shared SDK changes: - types: `ConnectedAccountAclSchema` → `ConnectedAccountAclConfigSchema` (input — all fields optional) + `ConnectedAccountAclConfigResponseSchema` (output — all fields populated when block is visible). Added per-user_id length cap (1..256) matching aclConfig.ts. `link()` options exposes `aclConfigForShared?` instead of three flat fields. Retrieve response exposes `aclConfigForShared?` (undefined when caller can't see ACL). - model: `link()` and `updateAcl()` serialize the SDK's flat camelCase ACL params into the nested snake_case `acl_config_for_shared` wire block via a new `serializeAclConfigForWire` helper. Local body types updated to match. - transformer: maps `acl_config_for_shared` (nested) → `aclConfigForShared` (nested camelCase). Forwards `undefined` when the block is absent. - ToolRouterSession.authorize() options gain `accountType` + `aclConfigForShared` — the `/tool_router/session/{id}/link` endpoint accepts the same fields. - changeset rewritten to document the nested shape. Verified: pnpm typecheck clean, build clean, 899 tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 11, 2026 at 18:52 UTC 752efd886324e75591db81f1d3950d7edfb58aeb
5 files changed +163 -80
.changeset/connected-accounts-acl.md
+6 -3
@@ -8,8 +8,9 @@ Surfaces three Apollo-side features that previously had no SDK wrappers:
8
9 - **`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.
10 - **`accountType` on retrieve**: `get()` and `list()` responses now include `accountType` (`'PRIVATE' | 'SHARED'`).
11 -- **`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.
12 -- **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).
11 +- **`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"*.
12 +- **`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.
13 +- **`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.
14
15 ACL resolution rule (deny wins):
16
@@ -18,12 +19,14 @@ ACL resolution rule (deny wins):
19 3. requesting `userId` ∈ `allowedUserIds` → ALLOW
20 4. otherwise → DENY (deny-by-default)
21
22 +Backend caps: each ACL list ≤1000 entries; each `userId` 1..256 chars. The SDK enforces these caps via Zod at the input boundary.
23 +
24 New error classes:
25
26 - `ComposioSharedAccessDeniedError` (403) — surfaces from direct `connectedAccountId` execution paths when the requesting user fails the ACL.
27 - `ComposioAclOnlyForSharedError` (400) — sent ACL fields on a PRIVATE row.
28 - `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.
29
27 -No breaking changes. Existing `link()` callers without `accountType` get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.
30 +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.
31
32 Python SDK gets the matching change in the same release train.
ts/packages/core/src/models/ConnectedAccounts.ts
+43 -28
@@ -52,10 +52,17 @@ import { ConnectionData } from '../types/connectedAccountAuthStates.types';
52 // warning on every initiate() call.
53 let _legacyInitiateWarningEmitted = false;
54
55 -// Wire-level fields added by Hermes #9860 / #9882 (account_type) and #9902
56 -// (ACL). Once @composio/client is regenerated against a backend spec that
57 -// includes these, this local extension can be removed and we can rely on the
58 -// generated `LinkCreateParams` directly.
55 +// Wire-level fields added by Hermes #9860 / #9882 (account_type) and
56 +// merged #9902 (ACL). 9902 nests ACL under a single `acl_config_for_shared`
57 +// object (single JSONB column under the hood). Once @composio/client is
58 +// regenerated against the post-9902 backend spec, this local extension can
59 +// be removed and we can rely on the generated `LinkCreateParams` directly.
60 +type AclConfigWireShape = {
61 + allow_all_users?: boolean;
62 + allowed_user_ids?: string[];
63 + not_allowed_user_ids?: string[];
64 +};
65 +
66 type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never
67 ? never
68 : Record<string, unknown> & {
@@ -64,21 +71,40 @@ type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never
71 alias?: string;
72 callback_url?: string;
73 account_type?: 'PRIVATE' | 'SHARED';
67 - allow_all_users?: boolean;
68 - allowed_user_ids?: string[];
69 - not_allowed_user_ids?: string[];
74 + acl_config_for_shared?: AclConfigWireShape;
75 };
76
72 -// Wire-level body for PATCH /connected_accounts/{id} with ACL fields
73 -// (Hermes #9902). Mirrors the same forward-compat pattern as
74 -// `LinkCreateBodyWithAcl` above.
77 +// Wire-level body for PATCH /connected_accounts/{id} with ACL.
78 type ConnectedAccountPatchBodyWithAcl = {
79 alias?: string;
77 - allow_all_users?: boolean;
78 - allowed_user_ids?: string[];
79 - not_allowed_user_ids?: string[];
80 + acl_config_for_shared?: AclConfigWireShape;
81 };
82
83 +/**
84 + * Serialise the SDK's `aclConfigForShared` (camelCase, top-level optional)
85 + * to the wire's `acl_config_for_shared` block. Returns `undefined` when the
86 + * caller didn't pass anything (PATCH-style "don't touch ACL"); returns
87 + * `{}` when the caller passed an explicit empty object (also "no fields to
88 + * change", but encodes the explicit intent — the backend treats both the
89 + * same way today).
90 + */
91 +function serializeAclConfigForWire(
92 + acl:
93 + | {
94 + allowAllUsers?: boolean;
95 + allowedUserIds?: string[];
96 + notAllowedUserIds?: string[];
97 + }
98 + | undefined
99 +): AclConfigWireShape | undefined {
100 + if (acl === undefined) return undefined;
101 + return {
102 + ...(acl.allowAllUsers !== undefined && { allow_all_users: acl.allowAllUsers }),
103 + ...(acl.allowedUserIds !== undefined && { allowed_user_ids: acl.allowedUserIds }),
104 + ...(acl.notAllowedUserIds !== undefined && { not_allowed_user_ids: acl.notAllowedUserIds }),
105 + };
106 +}
107 +
108 /**
109 * ConnectedAccounts class
110 *
@@ -396,17 +422,14 @@ export class ConnectedAccounts {
422 }
423
424 const opts = requestOptions.data;
425 + const aclWire = serializeAclConfigForWire(opts.aclConfigForShared);
426 const body: LinkCreateBodyWithAcl = {
427 auth_config_id: authConfigId,
428 user_id: userId,
429 ...(opts.callbackUrl && { callback_url: opts.callbackUrl }),
430 ...(opts.alias != null && { alias: opts.alias }),
431 ...(opts.accountType !== undefined && { account_type: opts.accountType }),
405 - ...(opts.allowAllUsers !== undefined && { allow_all_users: opts.allowAllUsers }),
406 - ...(opts.allowedUserIds !== undefined && { allowed_user_ids: opts.allowedUserIds }),
407 - ...(opts.notAllowedUserIds !== undefined && {
408 - not_allowed_user_ids: opts.notAllowedUserIds,
409 - }),
432 + ...(aclWire !== undefined && { acl_config_for_shared: aclWire }),
433 };
434
435 try {
@@ -683,18 +706,10 @@ export class ConnectedAccounts {
706 }
707
708 const body: ConnectedAccountPatchBodyWithAcl = {
686 - ...(parsedParams.data.allowAllUsers !== undefined && {
687 - allow_all_users: parsedParams.data.allowAllUsers,
688 - }),
689 - ...(parsedParams.data.allowedUserIds !== undefined && {
690 - allowed_user_ids: parsedParams.data.allowedUserIds,
691 - }),
692 - ...(parsedParams.data.notAllowedUserIds !== undefined && {
693 - not_allowed_user_ids: parsedParams.data.notAllowedUserIds,
694 - }),
709 + acl_config_for_shared: serializeAclConfigForWire(parsedParams.data),
710 };
711
697 - // Cast retained until @composio/client adds ACL fields to
712 + // Cast retained until @composio/client adds acl_config_for_shared to
713 // ConnectedAccountPatchParams.
714 await this.client.connectedAccounts.patch(
715 nanoid,
ts/packages/core/src/models/ToolRouterSession.ts
+39 -4
@@ -26,7 +26,11 @@ import {
26 import { SessionMetaToolOptions } from '../types/modifiers.types';
27 import { ConnectionRequest } from '../types/connectionRequest.types';
28 import { createConnectionRequest } from './ConnectionRequest';
29 -import { ConnectedAccountStatuses } from '../types/connectedAccounts.types';
29 +import {
30 + ConnectedAccountStatuses,
31 + ConnectedAccountType,
32 + ConnectedAccountAclConfig,
33 +} from '../types/connectedAccounts.types';
34 import { transform } from '../utils/transform';
35 import { ToolkitConnectionStateSchema } from '../types/toolRouter.types';
36 import { ValidationError } from '../errors';
@@ -303,16 +307,47 @@ export class ToolRouterSession<
307 /**
308 * Initiate an authorization flow for a toolkit.
309 * Returns a ConnectionRequest with a redirect URL for the user.
310 + *
311 + * `accountType` and `aclConfigForShared` (Hermes #9860, #9902) let the
312 + * caller create a SHARED connection with a per-user ACL in one flow.
313 + * Default behaviour (omit both) creates a PRIVATE connection.
314 */
315 async authorize(
316 toolkit: string,
309 - options?: { callbackUrl?: string; alias?: string }
317 + options?: {
318 + callbackUrl?: string;
319 + alias?: string;
320 + accountType?: ConnectedAccountType;
321 + aclConfigForShared?: ConnectedAccountAclConfig;
322 + }
323 ): Promise<ConnectionRequest> {
311 - const response = await this.client.toolRouter.session.link(this.sessionId, {
324 + const aclWire =
325 + options?.aclConfigForShared === undefined
326 + ? undefined
327 + : {
328 + ...(options.aclConfigForShared.allowAllUsers !== undefined && {
329 + allow_all_users: options.aclConfigForShared.allowAllUsers,
330 + }),
331 + ...(options.aclConfigForShared.allowedUserIds !== undefined && {
332 + allowed_user_ids: options.aclConfigForShared.allowedUserIds,
333 + }),
334 + ...(options.aclConfigForShared.notAllowedUserIds !== undefined && {
335 + not_allowed_user_ids: options.aclConfigForShared.notAllowedUserIds,
336 + }),
337 + };
338 + // Cast retained until @composio/client adds account_type +
339 + // acl_config_for_shared to SessionLinkParams (Hermes #9860 + #9902).
340 + const body = {
341 toolkit,
342 ...(options?.callbackUrl && { callback_url: options.callbackUrl }),
343 ...(options?.alias != null && { alias: options.alias }),
315 - });
344 + ...(options?.accountType !== undefined && { account_type: options.accountType }),
345 + ...(aclWire !== undefined && { acl_config_for_shared: aclWire }),
346 + };
347 + const response = await this.client.toolRouter.session.link(
348 + this.sessionId,
349 + body as unknown as Parameters<typeof this.client.toolRouter.session.link>[1]
350 + );
351
352 return createConnectionRequest(
353 this.client,
ts/packages/core/src/types/connectedAccounts.types.ts
+55 -32
@@ -51,35 +51,58 @@ export type ConnectedAccountType =
51 /**
52 * Per-user access control for a SHARED connected account. Inert for PRIVATE.
53 *
54 + * On the wire this lives under `acl_config_for_shared` — a single JSONB
55 + * column on `connected_accounts`. The SDK exposes the inner shape as
56 + * `aclConfigForShared` on inputs and responses (omit the block to mean
57 + * "don't touch ACL" on create / PATCH; absence on a response means the
58 + * caller isn't allowed to see the ACL).
59 + *
60 * Resolution rule (deny wins):
61 * 1. requesting userId in `notAllowedUserIds` → DENY
62 * 2. `allowAllUsers === true` → ALLOW
63 * 3. requesting userId in `allowedUserIds` → ALLOW
64 * 4. otherwise → DENY (deny-by-default)
65 *
60 - * Default state (`allowAllUsers=false`, both arrays empty) means only the
61 - * connection's creator can use it. The creator must grant access explicitly.
66 + * Default state (block omitted or `{}`) means only the connection's creator
67 + * can use it. The creator must grant access explicitly.
68 *
63 - * Lists are capped at 1000 entries each by the backend.
69 + * Backend caps: each list ≤1000 entries; each user_id 1..256 chars.
70 */
65 -const ACL_LIST_LIMIT = 1000;
66 -export const ConnectedAccountAclSchema = z.object({
71 +const ACL_LIST_MAX_LENGTH = 1000;
72 +const ACL_USER_ID_MAX_LENGTH = 256;
73 +const aclUserIdString = z.string().min(1).max(ACL_USER_ID_MAX_LENGTH);
74 +
75 +export const ConnectedAccountAclConfigSchema = z.object({
76 allowAllUsers: z
77 .boolean()
78 .optional()
79 .describe('Wildcard "any user_id in the project" allow toggle. Default false.'),
80 allowedUserIds: z
72 - .array(z.string())
73 - .max(ACL_LIST_LIMIT)
81 + .array(aclUserIdString)
82 + .max(ACL_LIST_MAX_LENGTH)
83 .optional()
84 .describe('Explicit allow list (developer-assigned user_id strings). Default [].'),
85 notAllowedUserIds: z
77 - .array(z.string())
78 - .max(ACL_LIST_LIMIT)
86 + .array(aclUserIdString)
87 + .max(ACL_LIST_MAX_LENGTH)
88 .optional()
89 .describe('Explicit deny list. Wins over allow on conflict. Default [].'),
90 });
82 -export type ConnectedAccountAcl = z.infer<typeof ConnectedAccountAclSchema>;
91 +export type ConnectedAccountAclConfig = z.infer<typeof ConnectedAccountAclConfigSchema>;
92 +
93 +/**
94 + * Resolved ACL as it appears on responses (creator / API-key callers).
95 + * All three fields are populated when the block is visible; the block
96 + * itself is absent for non-creator cookie callers.
97 + */
98 +export const ConnectedAccountAclConfigResponseSchema = z.object({
99 + allowAllUsers: z.boolean(),
100 + allowedUserIds: z.array(z.string()),
101 + notAllowedUserIds: z.array(z.string()),
102 +});
103 +export type ConnectedAccountAclConfigResponse = z.infer<
104 + typeof ConnectedAccountAclConfigResponseSchema
105 +>;
106
107 export const CreateConnectedAccountParamsSchema = z.object({
108 authConfig: z.object({
@@ -163,9 +186,7 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
186 createdAt: string;
187 updatedAt: string;
188 accountType?: ConnectedAccountType;
166 - allowAllUsers?: boolean;
167 - allowedUserIds?: string[];
168 - notAllowedUserIds?: string[];
189 + aclConfigForShared?: ConnectedAccountAclConfigResponse;
190 }> = z.object({
191 id: z.string(),
192 authConfig: ConnectedAccountAuthConfigSchema,
@@ -190,12 +211,12 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
211 createdAt: z.string(),
212 updatedAt: z.string(),
213 accountType: ConnectedAccountTypeSchema.optional(),
193 - // ACL fields are only present on responses when the caller is the creator
194 - // or is using a project/org API key — cookie callers who can use the
195 - // connection but aren't its creator see the row without these fields.
196 - allowAllUsers: z.boolean().optional(),
197 - allowedUserIds: z.array(z.string()).optional(),
198 - notAllowedUserIds: z.array(z.string()).optional(),
214 + // `acl_config_for_shared` is only present on responses when the caller is
215 + // the connection's creator or is using a project/org API key. Non-creator
216 + // cookie callers see the row without this block — left as `undefined`
217 + // here so callers can distinguish "I can't see the ACL" from "ACL is the
218 + // default deny-by-default state".
219 + aclConfigForShared: ConnectedAccountAclConfigResponseSchema.optional(),
220 });
221
222 export type ConnectedAccountRetrieveResponse = z.infer<
@@ -279,16 +300,16 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
300 */
301 accountType: ConnectedAccountTypeSchema.optional(),
302 /**
282 - * ACL for SHARED connections. Ignored when `accountType !== 'SHARED'`; the
283 - * backend rejects ACL fields on a `PRIVATE` connection with `AclOnlyForShared`.
303 + * Per-user ACL for SHARED connections. Only valid when
304 + * `accountType === 'SHARED'` — the backend rejects ACL on a PRIVATE
305 + * connection with `ComposioAclOnlyForSharedError` (400).
306 *
285 - * Default (deny-by-default): only the creator can use the connection. Grant
286 - * access by setting `allowAllUsers: true` or by listing user IDs in
287 - * `allowedUserIds`. `notAllowedUserIds` always wins over allow.
307 + * Omit the block (or pass `{}`) to keep the deny-by-default state: only the
308 + * creator can use the connection. Grant access by setting
309 + * `allowAllUsers: true` or listing user IDs in `allowedUserIds`.
310 + * `notAllowedUserIds` always wins over allow.
311 */
289 - allowAllUsers: ConnectedAccountAclSchema.shape.allowAllUsers,
290 - allowedUserIds: ConnectedAccountAclSchema.shape.allowedUserIds,
291 - notAllowedUserIds: ConnectedAccountAclSchema.shape.notAllowedUserIds,
312 + aclConfigForShared: ConnectedAccountAclConfigSchema.optional(),
313 });
314 export type CreateConnectedAccountLinkOptions = z.infer<
315 typeof CreateConnectedAccountLinkOptionsSchema
@@ -315,16 +336,18 @@ export const UpdateConnectedAccountParamsSchema = z.object({
336 });
337
338 /**
318 - * Params for `composio.connectedAccounts.updateAcl()`.
339 + * Params for `composio.connectedAccounts.updateAcl()`. Mirrors the inner
340 + * shape of the wire's `acl_config_for_shared` block — the SDK adds the
341 + * outer nesting at the boundary, so callers pass the three fields flat.
342 *
320 - * PATCH-style semantics — omit a field to leave it unchanged; pass an empty
321 - * array to clear an allow/deny list. Backend rejects ACL writes on a
322 - * `PRIVATE` connection with `AclOnlyForShared` (400).
343 + * PATCH-style semantics — omit a field to leave it unchanged; pass an
344 + * empty array to clear an allow/deny list. Backend rejects ACL writes on
345 + * a PRIVATE connection with `ComposioAclOnlyForSharedError` (400).
346 *
347 * Each field is optional, but at least one must be provided — passing an
348 * empty object is rejected as a no-op.
349 */
327 -export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclSchema.refine(
350 +export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclConfigSchema.refine(
351 acl =>
352 acl.allowAllUsers !== undefined ||
353 acl.allowedUserIds !== undefined ||
ts/packages/core/src/utils/transformers/connectedAccounts.ts
+20 -13
@@ -18,13 +18,15 @@ type RawConnectedAccountResponseWithLabels = (
18 ) & {
19 word_id?: string | null;
20 alias?: string | null;
21 - // account_type / ACL fields are added by Hermes #9860, #9882, #9902.
22 - // Cast lives here until @composio/client regenerates against a backend
23 - // spec that contains them.
21 + // account_type / acl_config_for_shared are added by Hermes #9860, #9882,
22 + // and the merged #9902. Cast lives here until @composio/client regenerates
23 + // against a backend spec that contains them.
24 account_type?: 'PRIVATE' | 'SHARED';
25 - allow_all_users?: boolean;
26 - allowed_user_ids?: string[];
27 - not_allowed_user_ids?: string[];
25 + acl_config_for_shared?: {
26 + allow_all_users: boolean;
27 + allowed_user_ids: string[];
28 + not_allowed_user_ids: string[];
29 + };
30 };
31
32 /**
@@ -78,13 +80,18 @@ export function transformConnectedAccountResponse(
80 updatedAt: response.updated_at,
81 testRequestEndpoint: response.test_request_endpoint,
82 accountType: responseWithLabels.account_type,
81 - // ACL fields are conditionally visible — backend strips them for
82 - // non-creator/non-API-key callers. Forward `undefined` when absent
83 - // rather than synthesising defaults, so callers can distinguish "I
84 - // can't see the ACL" from "ACL is empty".
85 - allowAllUsers: responseWithLabels.allow_all_users,
86 - allowedUserIds: responseWithLabels.allowed_user_ids,
87 - notAllowedUserIds: responseWithLabels.not_allowed_user_ids,
83 + // `acl_config_for_shared` is conditionally visible — backend strips
84 + // the whole block for non-creator/non-API-key callers. Forward
85 + // `undefined` when absent rather than synthesising defaults, so
86 + // callers can distinguish "I can't see the ACL" from "ACL is the
87 + // default deny-by-default state".
88 + aclConfigForShared: responseWithLabels.acl_config_for_shared
89 + ? {
90 + allowAllUsers: responseWithLabels.acl_config_for_shared.allow_all_users,
91 + allowedUserIds: responseWithLabels.acl_config_for_shared.allowed_user_ids,
92 + notAllowedUserIds: responseWithLabels.acl_config_for_shared.not_allowed_user_ids,
93 + }
94 + : undefined,
95 }));
96 }
97