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
(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;
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(),
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
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
/**