@devries-cameron20 / composio-1 / commits / eba561f77
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.

docs(connected-accounts): sanitize public docstrings — remove internal references

Addresses 4 review comments from @abir-taheer on #3392: - transformers/connectedAccounts.ts:21 — remove Hermes PR references - types/connectedAccounts.types.ts:79 — users don't belong to projects - types/connectedAccounts.types.ts:55 — drop backend storage detail - models/ToolRouterSession.ts:330 — remove internal information Swept the full PR diff for similar leaks rather than just the four flagged lines, since the same patterns repeat across the new files: - Removed Hermes PR numbers (#9860 / #9882 / #9902) from inline comments and JSDoc in transformers, types, model, test describe block, and changeset. - Removed "JSONB column on `connected_accounts`" storage detail. - Reworded "any user_id in the project" / "users in the project" / "project member" / "project/org API key" — users don't belong to a project entity in Composio's data model, so the wording was misleading. Replaced with phrasing focused on the mechanism (pinning in a tool-router session, authorisation via creator or API key) and on the `userId` identifier. - Removed "Backend response: 400 with code `ConnectedAccount_...`" blocks from error class JSDoc — surfacing the internal error code name leaked implementation details. - Cleaned up the augmented `RawConnectedAccountResponseWithLabels` intersection — `account_type` and `acl_config_for_shared` are now on the regenerated `@composio/client@0.1.0-alpha.71` types, so the manual augmentation lines (which carried the Hermes refs) can be deleted entirely. Field access still works through the existing intersection used for `word_id` / `alias`. Also tightened a pre-existing leak I introduced earlier in the PR's own JSDoc on `update()` — dropped the "historical JSDoc mentioning alias/credentials" callout since that's internal noise. No behaviour changes — pure docstring / comment / changeset cleanup. Verified: pnpm typecheck clean, 915 tests pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 12, 2026 at 01:08 UTC eba561f771bd279293951f0302441aa9b980672a
7 files changed +89 -111
.changeset/connected-accounts-acl.md
+7 -9
@@ -2,14 +2,12 @@
2 '@composio/core': minor
3 ---
4
5 -Add `accountType` and per-user ACL support for SHARED connected accounts (Hermes #9860, #9882, #9902).
5 +Add `accountType` and per-user ACL support for SHARED connected accounts.
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.
7 +- **`accountType` on create**: `composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' })` creates a SHARED connection. Default remains `PRIVATE`. A SHARED connection can be used by other `userId`s, but only when the connection is explicitly pinned in a tool-router session's config and only when the requesting `userId` passes the connection's ACL.
8 - **`accountType` on retrieve**: `get()` and `list()` responses now include `accountType` (`'PRIVATE' | 'SHARED'`).
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.
9 +- **`aclConfigForShared` on create + retrieve**: per-user ACL block — `{ allowAllUsers, allowedUserIds, notAllowedUserIds }`. On responses the field is `undefined` when the caller isn't authorised to see the ACL, so callers can distinguish *"I can't see the ACL"* from *"ACL is the default deny-by-default state"*.
10 +- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the ACL via `PATCH`. PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required. Calling on a PRIVATE connection raises `ComposioAclOnlyForSharedError` (400).
11 - **`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.
12
13 ACL resolution rule (deny wins):
@@ -19,14 +17,14 @@ ACL resolution rule (deny wins):
17 3. requesting `userId` ∈ `allowedUserIds` → ALLOW
18 4. otherwise → DENY (deny-by-default)
19
22 -Backend caps: each ACL list ≤1000 entries; each `userId` 1..256 chars. The SDK enforces these caps via Zod at the input boundary.
20 +Limits: each ACL list accepts up to 1000 entries; each `userId` is 1..256 characters. The SDK enforces these caps at the input boundary.
21
22 New error classes:
23
24 - `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.
25 +- `ComposioAclOnlyForSharedError` (400) — ACL fields sent on a PRIVATE connection.
26 - `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.
27
28 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.
29
32 -The Python SDK mirror ships in a separate PR — same wire contract, same release train.
30 +The Python SDK mirror ships in a separate PR.
ts/packages/core/src/errors/ConnectedAccountsErrors.ts
+7 -15
@@ -60,12 +60,9 @@ export class ComposioFailedToCreateConnectedAccountLink extends ComposioError {
60 * Thrown when a tool execution attempts to use a SHARED connected account
61 * but the requesting `userId` is not allowed by the connection's ACL.
62 *
63 - * Surfaces from the matching layer when a SHARED connection is reached
64 - * directly (e.g. via `composio.tools.execute(slug, { connectedAccountId })`)
65 - * without going through a tool-router session that already pre-flighted the
66 - * ACL at session-create time.
67 - *
68 - * Backend response: 403 with code `ConnectedAccount_SharedAccessDenied`.
63 + * Surfaces when a SHARED connection is reached directly (e.g. via
64 + * `composio.tools.execute(slug, { connectedAccountId })`) without going
65 + * through a tool-router session.
66 */
67 export class ComposioSharedAccessDeniedError extends ComposioError {
68 constructor(
@@ -86,11 +83,8 @@ export class ComposioSharedAccessDeniedError extends ComposioError {
83
84 /**
85 * Thrown when ACL fields (`allowAllUsers`, `allowedUserIds`,
89 - * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create time
90 - * or via PATCH. ACL is only meaningful for `SHARED` connections; the
91 - * matching layer never reads it for PRIVATE.
92 - *
93 - * Backend response: 400 with code `ConnectedAccount_AclOnlyForShared`.
86 + * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create
87 + * time or via PATCH. ACL is only meaningful for `SHARED` connections.
88 */
89 export class ComposioAclOnlyForSharedError extends ComposioError {
90 constructor(
@@ -111,10 +105,8 @@ export class ComposioAclOnlyForSharedError extends ComposioError {
105
106 /**
107 * Thrown by tool-router session create / PATCH when the session's `userId`
114 - * cannot use a pinned SHARED connection — caught at session-create time so
115 - * the session never enters a state that 4xxs mid-execution.
116 - *
117 - * Backend response: 400 with code `ToolRouterV2_SharedConnectionNotAccessible`.
108 + * cannot use a pinned SHARED connection — caught at session-create time
109 + * so the session never enters a state that fails mid-execution.
110 */
111 export class ComposioSharedConnectionNotAccessibleError extends ComposioError {
112 constructor(
ts/packages/core/src/models/ConnectedAccounts.ts
+22 -25
@@ -57,12 +57,12 @@ import { ConnectionData } from '../types/connectedAccountAuthStates.types';
57 let _legacyInitiateWarningEmitted = false;
58
59 /**
60 - * Serialise the SDK's `aclConfigForShared` (camelCase, top-level optional)
61 - * to the wire's `acl_config_for_shared` block. Returns `undefined` when the
62 - * caller didn't pass anything (PATCH-style "don't touch ACL"); returns
63 - * `{}` when the caller passed an explicit empty object (the backend treats
64 - * both the same way today — deny-by-default — but the explicit form is
65 - * preserved so the intent is visible in network traces).
60 + * Serialise the SDK's `aclConfigForShared` (camelCase) to the wire's
61 + * `acl_config_for_shared` block. Returns `undefined` when the caller
62 + * didn't pass anything (PATCH-style "don't touch ACL"); returns `{}`
63 + * when the caller passed an explicit empty object — both mean
64 + * deny-by-default, but the explicit form preserves the caller's intent
65 + * in network traces.
66 */
67 function serializeAclConfigForWire(
68 acl:
@@ -419,9 +419,8 @@ export class ConnectedAccounts {
419 );
420 return connectionRequest;
421 } catch (error) {
422 - // Backend rejects ACL fields on PRIVATE connections with a 400 +
423 - // `ConnectedAccount_AclOnlyForShared`. Surface it as a typed error so
424 - // callers can `instanceof` instead of grepping messages.
422 + // The server rejects ACL on PRIVATE connections — surface that as a
423 + // typed error so callers can `instanceof` instead of grepping messages.
424 if (
425 error instanceof BadRequestError &&
426 typeof error.message === 'string' &&
@@ -616,11 +615,9 @@ export class ConnectedAccounts {
615 }
616
617 /**
619 - * Enable or disable a connected account (wraps the `/status` endpoint
620 - * — accepts only `{ enabled: boolean }` despite the historical JSDoc
621 - * mentioning "alias and/or credentials"). For ACL writes on SHARED
622 - * connections, see {@link updateAcl}. Alias / credential PATCH isn't
623 - * surfaced on the SDK yet.
618 + * Enable or disable a connected account. Accepts `{ enabled: boolean }`.
619 + *
620 + * For ACL writes on SHARED connections, see {@link updateAcl}.
621 *
622 * @param {string} nanoid - The unique identifier of the connected account
623 * @param {UpdateConnectedAccountParams} params - The update parameters
@@ -649,23 +646,23 @@ export class ConnectedAccounts {
646 /**
647 * Update the per-user ACL on a SHARED connected account.
648 *
652 - * Only meaningful for SHARED connections — the backend rejects ACL writes
653 - * on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). Auth gate is
654 - * creator-or-API-key (a non-creator project member updating an alias on a
655 - * SHARED row still works via {@link update}, but ACL writes do not).
649 + * Only meaningful for SHARED connections — calling this on a PRIVATE
650 + * connection raises `ComposioAclOnlyForSharedError` (400). ACL writes
651 + * require the connection's creator or an API key; alias edits via
652 + * {@link update} are governed separately.
653 *
654 * PATCH semantics: omit a field to leave it unchanged; pass an empty array
655 * to clear an allow/deny list. At least one field must be provided.
656 *
657 * Resolution rule (deny wins):
661 - * 1. requesting userId in `notAllowedUserIds` → DENY
662 - * 2. `allowAllUsers === true` → ALLOW
663 - * 3. requesting userId in `allowedUserIds` → ALLOW
664 - * 4. otherwise → DENY
658 + * 1. requesting `userId` in `notAllowedUserIds` → DENY
659 + * 2. `allowAllUsers === true` → ALLOW
660 + * 3. requesting `userId` in `allowedUserIds` → ALLOW
661 + * 4. otherwise → DENY
662 *
663 * @example
664 * ```typescript
668 - * // Open access to everyone in the project
665 + * // Allow every userId to use this connection
666 * await composio.connectedAccounts.updateAcl('ca_abc', { allowAllUsers: true });
667 *
668 * // Everyone except a specific user
@@ -714,8 +711,8 @@ export class ConnectedAccounts {
711 try {
712 return await this.client.connectedAccounts.patch(nanoid, body);
713 } catch (error) {
717 - // Same `AclOnlyForShared` 400 the create path can hit — backend
718 - // rejects ACL writes on a PRIVATE row at PATCH-time too.
714 + // Same ACL-on-PRIVATE rejection the create path can hit — surface
715 + // it as a typed error.
716 if (
717 error instanceof BadRequestError &&
718 typeof error.message === 'string' &&
ts/packages/core/src/models/ToolRouterSession.ts
+11 -13
@@ -76,9 +76,9 @@ export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
76 * Options accepted by {@link ToolRouterSession.authorize}.
77 *
78 * Validated at the SDK boundary so callers get clear `ValidationError`s for
79 - * oversized ACL lists or invalid user IDs — same Zod caps as the equivalent
79 + * oversized ACL lists or invalid `userId`s — same caps as the equivalent
80 * `composio.connectedAccounts.link()` path (≤1000 entries per list, each
81 - * user_id 1..256 chars). Caught Bugbot review.
81 + * `userId` 1..256 characters).
82 */
83 const AuthorizeOptionsSchema = z.object({
84 callbackUrl: z.string().optional(),
@@ -327,15 +327,14 @@ export class ToolRouterSession<
327 * Initiate an authorization flow for a toolkit.
328 * Returns a ConnectionRequest with a redirect URL for the user.
329 *
330 - * `accountType` and `aclConfigForShared` (Hermes #9860, #9902) let the
331 - * caller create a SHARED connection with a per-user ACL in one flow.
332 - * Default behaviour (omit both) creates a PRIVATE connection.
330 + * Use `accountType` and `aclConfigForShared` to create a SHARED connection
331 + * with a per-user ACL in one flow. Default behaviour (omit both) creates
332 + * a PRIVATE connection.
333 *
334 - * `aclConfigForShared` is validated through `ConnectedAccountAclConfigSchema`
335 - * — same Zod caps as `composio.connectedAccounts.link()` (≤1000 entries
336 - * per list, each user_id 1..256 chars). Invalid input throws
337 - * `ValidationError` at the SDK boundary instead of hitting an opaque
338 - * backend 400.
334 + * `aclConfigForShared` is validated against the same caps as
335 + * `composio.connectedAccounts.link()` (≤1000 entries per list, each
336 + * `userId` 1..256 characters). Invalid input throws `ValidationError`
337 + * at the SDK boundary.
338 */
339 async authorize(
340 toolkit: string,
@@ -379,9 +378,8 @@ export class ToolRouterSession<
378 try {
379 response = await this.client.toolRouter.session.link(this.sessionId, body);
380 } catch (error) {
382 - // Backend rejects ACL fields on PRIVATE connections with a 400 +
383 - // `ConnectedAccount_AclOnlyForShared`. Surface it as a typed error
384 - // mirroring `composio.connectedAccounts.link()`.
381 + // The server rejects ACL on PRIVATE connections — surface that as a
382 + // typed error mirroring `composio.connectedAccounts.link()`.
383 if (
384 error instanceof BadRequestError &&
385 typeof error.message === 'string' &&
ts/packages/core/src/types/connectedAccounts.types.ts
+36 -34
@@ -31,11 +31,11 @@ export type ConnectedAccountStatusEnum = z.infer<typeof ConnectedAccountStatusSc
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.
34 + * - `SHARED`: can be used by other `userId`s, but only when the connection
35 + * is explicitly pinned in a tool-router session's config and only when
36 + * the requesting `userId` passes the connection's ACL (see
37 + * `allowAllUsers` / `allowedUserIds` / `notAllowedUserIds`). Set at
38 + * creation time only — cannot be changed later.
39 */
40 export const ConnectedAccountTypes = {
41 PRIVATE: 'PRIVATE',
@@ -49,24 +49,26 @@ export type ConnectedAccountType =
49 (typeof ConnectedAccountTypes)[keyof typeof ConnectedAccountTypes];
50
51 /**
52 - * Per-user access control for a SHARED connected account. Inert for PRIVATE.
52 + * Per-user access control for a SHARED connected account. Ignored for
53 + * PRIVATE.
54 *
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).
55 + * Pass `aclConfigForShared` on create / PATCH to grant access; omit it
56 + * to leave the ACL unchanged (on PATCH) or to keep the default
57 + * deny-by-default state (on create). On responses, the field is
58 + * `undefined` when the caller isn't authorised to see the ACL —
59 + * distinguish that from an empty/default state explicitly.
60 *
61 * 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)
62 + * 1. requesting `userId` in `notAllowedUserIds` → DENY
63 + * 2. `allowAllUsers === true` → ALLOW
64 + * 3. requesting `userId` in `allowedUserIds` → ALLOW
65 + * 4. otherwise → DENY (deny-by-default)
66 *
66 - * Default state (block omitted or `{}`) means only the connection's creator
67 - * can use it. The creator must grant access explicitly.
67 + * Default state (block omitted or `{}`) means only the connection's
68 + * creator can use it. The creator must grant access explicitly.
69 *
69 - * Backend caps: each list ≤1000 entries; each user_id 1..256 chars.
70 + * Limits: each list accepts up to 1000 entries; each `userId` is
71 + * 1..256 characters.
72 */
73 const ACL_LIST_MAX_LENGTH = 1000;
74 const ACL_USER_ID_MAX_LENGTH = 256;
@@ -76,24 +78,24 @@ export const ConnectedAccountAclConfigSchema = z.object({
78 allowAllUsers: z
79 .boolean()
80 .optional()
79 - .describe('Wildcard "any user_id in the project" allow toggle. Default false.'),
81 + .describe('When true, any `userId` may use this SHARED connection (subject to the deny list). Default false.'),
82 allowedUserIds: z
83 .array(aclUserIdString)
84 .max(ACL_LIST_MAX_LENGTH)
85 .optional()
84 - .describe('Explicit allow list (developer-assigned user_id strings). Default [].'),
86 + .describe('Explicit list of `userId` strings allowed to use this SHARED connection. Default [].'),
87 notAllowedUserIds: z
88 .array(aclUserIdString)
89 .max(ACL_LIST_MAX_LENGTH)
90 .optional()
89 - .describe('Explicit deny list. Wins over allow on conflict. Default [].'),
91 + .describe('Explicit list of `userId` strings denied access. Wins over allow on conflict. Default [].'),
92 });
93 export type ConnectedAccountAclConfig = z.infer<typeof ConnectedAccountAclConfigSchema>;
94
95 /**
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.
96 + * Resolved ACL as it appears on responses. All three fields are populated
97 + * when the field is visible; the field itself is `undefined` for callers
98 + * not authorised to see it.
99 */
100 export const ConnectedAccountAclConfigResponseSchema = z.object({
101 allowAllUsers: z.boolean(),
@@ -211,11 +213,11 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
213 createdAt: z.string(),
214 updatedAt: z.string(),
215 accountType: ConnectedAccountTypeSchema.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".
216 + // `aclConfigForShared` is only present on the response when the caller
217 + // is authorised to see the ACL — otherwise the block is absent and the
218 + // field is `undefined`. Callers can distinguish "I can't see the ACL"
219 + // from "ACL is the default deny-by-default state" by checking for the
220 + // presence of the field.
221 aclConfigForShared: ConnectedAccountAclConfigResponseSchema.optional(),
222 });
223
@@ -292,11 +294,11 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
294 */
295 allowMultiple: z.boolean().optional(),
296 /**
295 - * Sharing model for the new connection. `PRIVATE` (default) is usable only by
296 - * the owning `userId`. `SHARED` is reachable from a tool-router session by
297 - * other users in the project — but only when explicitly pinned and only when
298 - * the requesting `userId` passes the connection's ACL. Set at create time
299 - * only.
297 + * Sharing model for the new connection. `PRIVATE` (default) is usable only
298 + * by the owning `userId`. `SHARED` can be used by other `userId`s — but
299 + * only when the connection is explicitly pinned in a tool-router session's
300 + * config and only when the requesting `userId` passes the connection's
301 + * ACL. Set at creation time only.
302 */
303 accountType: ConnectedAccountTypeSchema.optional(),
304 /**
ts/packages/core/src/utils/transformers/connectedAccounts.ts
+5 -14
@@ -18,15 +18,6 @@ type RawConnectedAccountResponseWithLabels = (
18 ) & {
19 word_id?: string | null;
20 alias?: string | null;
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 - acl_config_for_shared?: {
26 - allow_all_users: boolean;
27 - allowed_user_ids: string[];
28 - not_allowed_user_ids: string[];
29 - };
21 };
22
23 /**
@@ -80,11 +71,11 @@ export function transformConnectedAccountResponse(
71 updatedAt: response.updated_at,
72 testRequestEndpoint: response.test_request_endpoint,
73 accountType: responseWithLabels.account_type,
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".
74 + // `acl_config_for_shared` is conditionally visible — the field is
75 + // absent when the caller isn't authorised to see it. Forward
76 + // `undefined` rather than synthesising defaults so callers can
77 + // distinguish "I can't see the ACL" from "ACL is the default
78 + // deny-by-default state".
79 aclConfigForShared: responseWithLabels.acl_config_for_shared
80 ? {
81 allowAllUsers: responseWithLabels.acl_config_for_shared.allow_all_users,
ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
+1 -1
@@ -1521,7 +1521,7 @@ describe('ConnectedAccounts', () => {
1521 });
1522 });
1523
1524 - describe('link with accountType + ACL (Hermes #9860, #9902)', () => {
1524 + describe('link with accountType + ACL', () => {
1525 beforeEach(() => {
1526 extendedMockClient.connectedAccounts.list.mockResolvedValue({
1527 items: [],