@devries-cameron20 / composio Mirror · read-only / commits / 84a3a074b
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 21:00 UTC

feat(connected-accounts): surface accountType + per-user ACL on SHARED connections

Adds SDK wrappers for Hermes #9860, #9882, #9902 — three Apollo-side features that previously had no high-level surface. Existing call sites are unchanged; new fields/methods are opt-in. - `link()` accepts `accountType` ('PRIVATE' | 'SHARED') and ACL fields (`allowAllUsers`, `allowedUserIds`, `notAllowedUserIds`) to create a SHARED connection in one call. - `get()` / `list()` responses now expose `accountType`. ACL fields are forwarded when present (backend hides them for non-creator/non-API-key callers — left as undefined in the SDK shape). - New `updateAcl(nanoid, params)` method wires the existing `client.connectedAccounts.patch` (PATCH /connected_accounts/{id}) for ACL writes. PATCH semantics: omit a field to leave unchanged; pass empty array to clear an allow/deny list. At least one field required. - New error classes: `ComposioSharedAccessDeniedError` (403), `ComposioAclOnlyForSharedError` (400), `ComposioSharedConnectionNotAccessibleError` (400). The wire-level fields (account_type, allow_all_users, etc.) are not yet in @composio/client@0.1.0-alpha.70's typed surface — they'll land when Stainless regenerates against the post-merge backend spec. Two narrow local types (`LinkCreateBodyWithAcl`, `ConnectedAccountPatchBodyWithAcl`) + boundary casts paper over the gap until then; remove once the client is bumped. Verified: pnpm typecheck clean, build clean, 899 tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 10, 2026 at 11:53 UTC 84a3a074b3135b41846cbebcc8c2bd8401e013e6
5 files changed +343 -6
.changeset/connected-accounts-acl.md new
+29
@@ -0,0 +1,29 @@
1 +---
2 +'@composio/core': minor
3 +---
4 +
5 +Add `accountType` and per-user ACL support for SHARED connected accounts (Hermes #9860, #9882, #9902).
6 +
7 +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).
13 +
14 +ACL resolution rule (deny wins):
15 +
16 +1. requesting `userId` ∈ `notAllowedUserIds` → DENY
17 +2. `allowAllUsers === true` → ALLOW
18 +3. requesting `userId` ∈ `allowedUserIds` → ALLOW
19 +4. otherwise → DENY (deny-by-default)
20 +
21 +New error classes:
22 +
23 +- `ComposioSharedAccessDeniedError` (403) — surfaces from direct `connectedAccountId` execution paths when the requesting user fails the ACL.
24 +- `ComposioAclOnlyForSharedError` (400) — sent ACL fields on a PRIVATE row.
25 +- `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.
26 +
27 +No breaking changes. Existing `link()` callers without `accountType` get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.
28 +
29 +Python SDK gets the matching change in the same release train.
ts/packages/core/src/errors/ConnectedAccountsErrors.ts
+80
@@ -5,6 +5,9 @@ export const ConnectedAccountErrorCodes = {
5 MULTIPLE_CONNECTED_ACCOUNTS: 'MULTIPLE_CONNECTED_ACCOUNTS',
6 FAILED_TO_CREATE_CONNECTED_ACCOUNT_LINK: 'FAILED_TO_CREATE_CONNECTED_ACCOUNT_LINK',
7 LEGACY_CONNECTED_ACCOUNTS_ENDPOINT_RETIRED: 'LEGACY_CONNECTED_ACCOUNTS_ENDPOINT_RETIRED',
8 + SHARED_ACCESS_DENIED: 'SHARED_ACCESS_DENIED',
9 + ACL_ONLY_FOR_SHARED: 'ACL_ONLY_FOR_SHARED',
10 + SHARED_CONNECTION_NOT_ACCESSIBLE: 'SHARED_CONNECTION_NOT_ACCESSIBLE',
11 } as const;
12
13 export class ComposioConnectedAccountNotFoundError extends ComposioError {
@@ -66,6 +69,83 @@ export class ComposioFailedToCreateConnectedAccountLink extends ComposioError {
69 *
70 * See: https://docs.composio.dev/docs/changelog/2026/04/24
71 */
72 +/**
73 + * Thrown when a tool execution attempts to use a SHARED connected account
74 + * but the requesting `userId` is not allowed by the connection's ACL.
75 + *
76 + * Surfaces from the matching layer when a SHARED connection is reached
77 + * directly (e.g. via `composio.tools.execute(slug, { connectedAccountId })`)
78 + * without going through a tool-router session that already pre-flighted the
79 + * ACL at session-create time.
80 + *
81 + * Backend response: 403 with code `ConnectedAccount_SharedAccessDenied`.
82 + */
83 +export class ComposioSharedAccessDeniedError extends ComposioError {
84 + constructor(
85 + message: string = 'Access denied: this SHARED connected account is not available to the requesting user',
86 + options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
87 + ) {
88 + super(message, {
89 + ...options,
90 + code: ConnectedAccountErrorCodes.SHARED_ACCESS_DENIED,
91 + statusCode: 403,
92 + possibleFixes: options.possibleFixes || [
93 + "Ask the connection's creator to grant access via composio.connectedAccounts.updateAcl() — set allowAllUsers, add the userId to allowedUserIds, or remove it from notAllowedUserIds.",
94 + ],
95 + });
96 + this.name = 'ComposioSharedAccessDeniedError';
97 + }
98 +}
99 +
100 +/**
101 + * Thrown when ACL fields (`allowAllUsers`, `allowedUserIds`,
102 + * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create time
103 + * or via PATCH. ACL is only meaningful for `SHARED` connections; the
104 + * matching layer never reads it for PRIVATE.
105 + *
106 + * Backend response: 400 with code `ConnectedAccount_AclOnlyForShared`.
107 + */
108 +export class ComposioAclOnlyForSharedError extends ComposioError {
109 + constructor(
110 + message: string = 'ACL fields are only valid on SHARED connected accounts',
111 + options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
112 + ) {
113 + super(message, {
114 + ...options,
115 + code: ConnectedAccountErrorCodes.ACL_ONLY_FOR_SHARED,
116 + statusCode: 400,
117 + possibleFixes: options.possibleFixes || [
118 + 'Set accountType: "SHARED" at create time, or omit ACL fields when creating/updating a PRIVATE connection.',
119 + ],
120 + });
121 + this.name = 'ComposioAclOnlyForSharedError';
122 + }
123 +}
124 +
125 +/**
126 + * Thrown by tool-router session create / PATCH when the session's `userId`
127 + * cannot use a pinned SHARED connection — caught at session-create time so
128 + * the session never enters a state that 4xxs mid-execution.
129 + *
130 + * Backend response: 400 with code `ToolRouterV2_SharedConnectionNotAccessible`.
131 + */
132 +export class ComposioSharedConnectionNotAccessibleError extends ComposioError {
133 + constructor(
134 + message: string = 'A SHARED connected account pinned in the session config is not accessible to the session user',
135 + options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
136 + ) {
137 + super(message, {
138 + ...options,
139 + code: ConnectedAccountErrorCodes.SHARED_CONNECTION_NOT_ACCESSIBLE,
140 + statusCode: 400,
141 + possibleFixes: options.possibleFixes || [
142 + "Grant the session user access via composio.connectedAccounts.updateAcl() on the pinned connection, or pin a different connection the user can use.",
143 + ],
144 + });
145 + this.name = 'ComposioSharedConnectionNotAccessibleError';
146 + }
147 +}
148 +
149 export class ComposioLegacyConnectedAccountsEndpointRetiredError extends ComposioError {
150 constructor(
151 message: string = 'POST /api/v3/connected_accounts is no longer supported for Composio-managed OAuth auth configs. Use composio.connectedAccounts.link() instead.',
ts/packages/core/src/models/ConnectedAccounts.ts
+113 -6
@@ -29,6 +29,8 @@ import {
29 ConnectedAccountRefreshOptionsSchema,
30 UpdateConnectedAccountParams,
31 UpdateConnectedAccountParamsSchema,
32 + UpdateConnectedAccountAclParams,
33 + UpdateConnectedAccountAclParamsSchema,
34 } from '../types/connectedAccounts.types';
35 import { ConnectionRequest } from '../types/connectionRequest.types';
36 import { createConnectionRequest } from './ConnectionRequest';
@@ -50,6 +52,33 @@ 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.
59 +type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never
60 + ? never
61 + : Record<string, unknown> & {
62 + auth_config_id: string;
63 + user_id: string;
64 + alias?: string;
65 + callback_url?: string;
66 + account_type?: 'PRIVATE' | 'SHARED';
67 + allow_all_users?: boolean;
68 + allowed_user_ids?: string[];
69 + not_allowed_user_ids?: string[];
70 + };
71 +
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.
75 +type ConnectedAccountPatchBodyWithAcl = {
76 + alias?: string;
77 + allow_all_users?: boolean;
78 + allowed_user_ids?: string[];
79 + not_allowed_user_ids?: string[];
80 +};
81 +
82 /**
83 * ConnectedAccounts class
84 *
@@ -366,13 +395,26 @@ export class ConnectedAccounts {
395 );
396 }
397
398 + const opts = requestOptions.data;
399 + const body: LinkCreateBodyWithAcl = {
400 + auth_config_id: authConfigId,
401 + user_id: userId,
402 + ...(opts.callbackUrl && { callback_url: opts.callbackUrl }),
403 + ...(opts.alias != null && { alias: opts.alias }),
404 + ...(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 + }),
410 + };
411 +
412 try {
370 - const response = await this.client.link.create({
371 - auth_config_id: authConfigId,
372 - user_id: userId,
373 - ...(requestOptions?.data.callbackUrl && { callback_url: requestOptions.data.callbackUrl }),
374 - ...(requestOptions?.data.alias != null && { alias: requestOptions.data.alias }),
375 - });
413 + // Cast retained until @composio/client adds account_type / ACL fields
414 + // to LinkCreateParams.
415 + const response = await this.client.link.create(body as unknown as Parameters<
416 + typeof this.client.link.create
417 + >[0]);
418
419 const connectionRequest = createConnectionRequest(
420 this.client,
@@ -594,4 +636,69 @@ export class ConnectedAccounts {
636
637 return this.client.connectedAccounts.updateStatus(nanoid, parsedParams.data);
638 }
639 +
640 + /**
641 + * Update the per-user ACL on a SHARED connected account.
642 + *
643 + * Only meaningful for SHARED connections — the backend rejects ACL writes
644 + * on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). Auth gate is
645 + * creator-or-API-key (a non-creator project member updating an alias on a
646 + * SHARED row still works via {@link update}, but ACL writes do not).
647 + *
648 + * PATCH semantics: omit a field to leave it unchanged; pass an empty array
649 + * to clear an allow/deny list. At least one field must be provided.
650 + *
651 + * Resolution rule (deny wins):
652 + * 1. requesting userId in `notAllowedUserIds` → DENY
653 + * 2. `allowAllUsers === true` → ALLOW
654 + * 3. requesting userId in `allowedUserIds` → ALLOW
655 + * 4. otherwise → DENY
656 + *
657 + * @example
658 + * ```typescript
659 + * // Open access to everyone in the project
660 + * await composio.connectedAccounts.updateAcl('ca_abc', { allowAllUsers: true });
661 + *
662 + * // Everyone except a specific user
663 + * await composio.connectedAccounts.updateAcl('ca_abc', {
664 + * allowAllUsers: true,
665 + * notAllowedUserIds: ['user_bob'],
666 + * });
667 + *
668 + * // Targeted allow
669 + * await composio.connectedAccounts.updateAcl('ca_abc', {
670 + * allowedUserIds: ['user_alice', 'user_bob'],
671 + * });
672 + *
673 + * // Revoke a previously-granted allow list (back to deny-by-default)
674 + * await composio.connectedAccounts.updateAcl('ca_abc', { allowedUserIds: [] });
675 + * ```
676 + */
677 + async updateAcl(nanoid: string, params: UpdateConnectedAccountAclParams): Promise<void> {
678 + const parsedParams = UpdateConnectedAccountAclParamsSchema.safeParse(params);
679 + if (!parsedParams.success) {
680 + throw new ValidationError('Failed to parse connected account ACL update params', {
681 + cause: parsedParams.error,
682 + });
683 + }
684 +
685 + 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 + }),
695 + };
696 +
697 + // Cast retained until @composio/client adds ACL fields to
698 + // ConnectedAccountPatchParams.
699 + await this.client.connectedAccounts.patch(
700 + nanoid,
701 + body as unknown as Parameters<typeof this.client.connectedAccounts.patch>[1]
702 + );
703 + }
704 }
ts/packages/core/src/types/connectedAccounts.types.ts
+106
@@ -27,6 +27,60 @@ export type ConnectedAccountStatus =
27 (typeof ConnectedAccountStatuses)[keyof typeof ConnectedAccountStatuses];
28 export type ConnectedAccountStatusEnum = z.infer<typeof ConnectedAccountStatusSchema>;
29
30 +/**
31 + * Sharing model for a connected account.
32 + *
33 + * - `PRIVATE` (default): only the owning `userId` can use the connection.
34 + * - `SHARED`: reachable from a tool-router session by other users in the
35 + * project, but only when explicitly pinned in the session config and only
36 + * when the requesting `userId` passes the connection's ACL (see
37 + * `allowAllUsers` / `allowedUserIds` / `notAllowedUserIds`). Set at create
38 + * time only — cannot be changed later.
39 + */
40 +export const ConnectedAccountTypes = {
41 + PRIVATE: 'PRIVATE',
42 + SHARED: 'SHARED',
43 +} as const;
44 +export const ConnectedAccountTypeSchema = z.enum([
45 + ConnectedAccountTypes.PRIVATE,
46 + ConnectedAccountTypes.SHARED,
47 +]);
48 +export type ConnectedAccountType =
49 + (typeof ConnectedAccountTypes)[keyof typeof ConnectedAccountTypes];
50 +
51 +/**
52 + * Per-user access control for a SHARED connected account. Inert for PRIVATE.
53 + *
54 + * Resolution rule (deny wins):
55 + * 1. requesting userId in `notAllowedUserIds` → DENY
56 + * 2. `allowAllUsers === true` → ALLOW
57 + * 3. requesting userId in `allowedUserIds` → ALLOW
58 + * 4. otherwise → DENY (deny-by-default)
59 + *
60 + * Default state (`allowAllUsers=false`, both arrays empty) means only the
61 + * connection's creator can use it. The creator must grant access explicitly.
62 + *
63 + * Lists are capped at 1000 entries each by the backend.
64 + */
65 +const ACL_LIST_LIMIT = 1000;
66 +export const ConnectedAccountAclSchema = z.object({
67 + allowAllUsers: z
68 + .boolean()
69 + .optional()
70 + .describe('Wildcard "any user_id in the project" allow toggle. Default false.'),
71 + allowedUserIds: z
72 + .array(z.string())
73 + .max(ACL_LIST_LIMIT)
74 + .optional()
75 + .describe('Explicit allow list (developer-assigned user_id strings). Default [].'),
76 + notAllowedUserIds: z
77 + .array(z.string())
78 + .max(ACL_LIST_LIMIT)
79 + .optional()
80 + .describe('Explicit deny list. Wins over allow on conflict. Default [].'),
81 +});
82 +export type ConnectedAccountAcl = z.infer<typeof ConnectedAccountAclSchema>;
83 +
84 export const CreateConnectedAccountParamsSchema = z.object({
85 authConfig: z.object({
86 id: z.string(),
@@ -108,6 +162,10 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
162 isDisabled: boolean;
163 createdAt: string;
164 updatedAt: string;
165 + accountType?: ConnectedAccountType;
166 + allowAllUsers?: boolean;
167 + allowedUserIds?: string[];
168 + notAllowedUserIds?: string[];
169 }> = z.object({
170 id: z.string(),
171 authConfig: ConnectedAccountAuthConfigSchema,
@@ -131,6 +189,13 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
189 isDisabled: z.boolean(),
190 createdAt: z.string(),
191 updatedAt: z.string(),
192 + 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(),
199 });
200
201 export type ConnectedAccountRetrieveResponse = z.infer<
@@ -205,6 +270,25 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
270 * `multiAccount` config to disambiguate at execution time.
271 */
272 allowMultiple: z.boolean().optional(),
273 + /**
274 + * Sharing model for the new connection. `PRIVATE` (default) is usable only by
275 + * the owning `userId`. `SHARED` is reachable from a tool-router session by
276 + * other users in the project — but only when explicitly pinned and only when
277 + * the requesting `userId` passes the connection's ACL. Set at create time
278 + * only.
279 + */
280 + accountType: ConnectedAccountTypeSchema.optional(),
281 + /**
282 + * ACL for SHARED connections. Ignored when `accountType !== 'SHARED'`; the
283 + * backend rejects ACL fields on a `PRIVATE` connection with `AclOnlyForShared`.
284 + *
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.
288 + */
289 + allowAllUsers: ConnectedAccountAclSchema.shape.allowAllUsers,
290 + allowedUserIds: ConnectedAccountAclSchema.shape.allowedUserIds,
291 + notAllowedUserIds: ConnectedAccountAclSchema.shape.notAllowedUserIds,
292 });
293 export type CreateConnectedAccountLinkOptions = z.infer<
294 typeof CreateConnectedAccountLinkOptionsSchema
@@ -229,3 +313,25 @@ export type { ConnectedAccountUpdateStatusParams as UpdateConnectedAccountParams
313 export const UpdateConnectedAccountParamsSchema = z.object({
314 enabled: z.boolean(),
315 });
316 +
317 +/**
318 + * Params for `composio.connectedAccounts.updateAcl()`.
319 + *
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).
323 + *
324 + * Each field is optional, but at least one must be provided — passing an
325 + * empty object is rejected as a no-op.
326 + */
327 +export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclSchema.refine(
328 + acl =>
329 + acl.allowAllUsers !== undefined ||
330 + acl.allowedUserIds !== undefined ||
331 + acl.notAllowedUserIds !== undefined,
332 + {
333 + message:
334 + 'At least one of allowAllUsers, allowedUserIds, or notAllowedUserIds must be provided',
335 + }
336 +);
337 +export type UpdateConnectedAccountAclParams = z.infer<typeof UpdateConnectedAccountAclParamsSchema>;
ts/packages/core/src/utils/transformers/connectedAccounts.ts
+15
@@ -18,6 +18,13 @@ 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.
24 + account_type?: 'PRIVATE' | 'SHARED';
25 + allow_all_users?: boolean;
26 + allowed_user_ids?: string[];
27 + not_allowed_user_ids?: string[];
28 };
29
30 /**
@@ -70,6 +77,14 @@ export function transformConnectedAccountResponse(
77 createdAt: response.created_at,
78 updatedAt: response.updated_at,
79 testRequestEndpoint: response.test_request_endpoint,
80 + 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,
88 }));
89 }
90