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, 03:37 UTC
docs: clarify credential control and retention choices (#5456)
## Summary Security reviewers need to distinguish control of tool logic, OAuth apps, tokens, runtime, and stored payloads. Existing docs already disclose Cloud custody and retention tradeoffs. This draft organizes those facts and preserves the limits. Related: [DEVREL-315](https://linear.app/composio/issue/DEVREL-315/cloud-stores-tokens-and-payloads-by-default), [PRO-3750](https://linear.app/composio/issue/PRO-3750/document-control-over-tools-credentials-and-deployment-as-explicit). These issues remain open; this does not establish that their Gauge acceptance criteria have passed. Designated reviewer: @jkomyno. Product/security questions are below for Brendan to route. ## Changes - Add a seven-row table of controls to the existing token-custody page, with links to each documented control and its limits. - Add a short payload-location and retention summary, including log/file lifetimes and ZDR exclusions. - Link the table from the own-tools auth guide and B2B architecture, keeping the custody page as the single reference. - Replace the vendor-review page's retired **Don't store data** name with current ZDR guidance. Link its training explanation to the existing payload and de-identified metadata policy. | Before | After | | --- | --- | | Control choices spread across authentication, security, and B2B pages | One linked table distinguishes app control, Composio operation, and limits | | Custody page links out for all retention lifetimes | Short, sourced summary preserves the detailed policy links | | Vendor review uses a retired setting name and only a blanket training caution | Current ZDR name and explicit first-party policy, with metadata and downstream-provider qualifications | ## Existing facts and sources Sources below are pinned to the unchanged `next` revision used for this draft. Each new factual statement links to existing docs in the page itself. This is an inventory of documented behavior, not a backend security audit. | Area | Source | What the source establishes | | --- | --- | --- | | Cloud credentials and provider calls | [Existing custody flow](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/token-custody.mdx#L7) | Composio stores credentials and uses them server-side. Encryption and response redaction do not remove that custody. | | Application-owned tools and provider permissions | [Own-tools auth](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/authentication/managed-auth-for-custom-tools.mdx#L7); [Proxy permission](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx#L255) | Tool definitions and business logic can stay in the app. Proxy Execute still uses Composio and requires its own permission. | | OAuth app ownership | [Managed vs custom auth](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/authentication/custom-app-vs-managed-app.mdx#L18) | Branding, scopes, and provider quota change; token custody does not. | | Connection ownership and experimental APIs | [B2B ownership](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/b2b-agents.mdx#L9); [Shared connections](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/extending-sessions/shared-connections.mdx#L1); [Local tools](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/extending-sessions/local-tools-and-toolkits.mdx#L1) | The app maps tenants/members and authorizes callers. Shared connections and optional session extensions remain experimental. | | Credential retrieval and exit | [Credential masking](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/auth-configuration/connected-accounts.mdx#L258); [Existing export boundary](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/token-custody.mdx#L91) | Get/List account responses redact secrets and are not a supported raw-token export workflow. No migration or no-reconsent guarantee is added. | | Payloads and retention | [Data policy](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/data-retention.mdx#L15) | Default payload logging; logs up to one year; execution logs deleted within 30 days of organization deletion; staged files deleted after 24 hours, separately from URL expiry. | | ZDR coverage and exclusions | [ZDR policy](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/zero-data-retention.mdx#L7) | Paid-plan/Enterprise availability, new covered calls only, audit metadata retained, managed OAuth coverage only on Enterprise, and separate trigger/sandbox/file/search/third-party limits. | | Training | [Model-training policy](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/data-retention.mdx#L27) | Payloads excluded on every plan; de-identified execution metadata may train models and be retained indefinitely. Third-party terms remain separate. | | Deployment and customer-managed keys | [Existing deployment table](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/token-custody.mdx#L115); [SDK public transfer-key API](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/ts/packages/core/src/models/Keyring.ts#L31) | Existing Cloud/private VPC/self-hosted/customer-managed-key descriptions are preserved. The SDK proves public transfer-key retrieval, not operator access or plaintext boundaries. Current orderability and deployment details need product/security confirmation. | ## Relationship to the security and BYOC work - Builds on merged [#5372](https://github.com/ComposioHQ/composio/pull/5372). Its Security and Compliance navigation, routes, and existing policy pages remain in place. - [#5254](https://github.com/ComposioHQ/composio/pull/5254) is open and unmerged as inspected November 18. It owns the BYOC launch guide, customer-operated Helm retirement wording, deployment-table replacement, and detailed operator responsibilities. - **No merge dependency on #5254.** This change targets `next`, adds no BYOC route or launch promise, and leaves the deployment table unchanged. Applying #5254's token-custody patch over this edit passes `git apply --check`. Its replacement table remains the place for deployment availability when it lands. Recheck the combined wording before either PR ships. - No competitor comparison, landing-site change, SDK behavior change, manual deployment, or production/customer-data mutation. No Gauge rerun was performed; no preference improvement or resolved security objection is claimed. ## How Has This Been Tested? Run from `docs/` with Bun 1.4.2 and Node 24.22.1: - `bun install --frozen-lockfile`: passed; no lockfile change. - `bun run lint:links`: passed, 0 errored files / 0 errors for site and SDK links. - `bun run lint`: passed, with warnings in unchanged site files. - `bun run test --timeout 30000`: 838 passed, 0 failed across 80 files. - `git diff --check`: passed. - `GITHUB_ACTIONS=true timeout 20m bun run build`: passed under the shared build lock. MDX compilation, TypeScript, and generation of 2,662 static pages passed. Removed this worktree's 759 MB `.next` output afterward. An independent read-only agent checked the source inventory and final prose diff and found no blocking factual inaccuracies. No new tests are needed for prose-only changes; existing documentation checks cover links, MDX, and site behavior. ## NEEDS BRENDAN - **Product/security:** Which private VPC, customer-operated self-hosted, and customer-managed-key options are currently orderable? Confirm the boundary between current offerings and #5254's pending BYOC launch, including supported regions, control-plane location, operator/support access, keys, logs/backups, and required outbound traffic. The existing deployment descriptions are retained, not newly verified product promises. - **Security:** Where does Cloud store credentials, payloads, files, logs, and backups geographically? What are the credential and backup retention/deletion schedules after disconnect or organization deletion? The documented 30-day execution-log deletion window does not establish credential deletion. - **Security:** Reconcile ZDR's [no-PII statement](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/zero-data-retention.mdx#L103) with the [audit-log email/IP fields](https://github.com/ComposioHQ/composio/blob/a5e0df351efd25693b630ddec2feffade283ee95/docs/content/docs/security/audit-logs.mdx#L28) and provider error text in telemetry. What retention and redaction guarantees apply to those records? This draft does not repeat the blanket no-PII claim. - **Product/security:** Is any credential-transfer/exit process supported by agreement? Confirm provider/client ownership, possible re-consent, deletion/revocation of old copies, and migration steps before promising export or a seamless exit. ## Type of change - [x] Documentation ## Checklist - [x] Agent reviewed the full diff and preserved unrelated work. - [x] New claims trace to existing docs; unverified claims stay in owner questions. - [x] Existing security disclosures and third-party limits retained. - [x] No changeset required for documentation-only changes. - [ ] Brendan has reviewed every line. - [ ] Product/security has answered the questions above. ## In plain language You can keep your own tool logic and OAuth app while Composio still holds the tokens and sends provider requests. The docs now show those choices together and explain what ZDR changes, what stays stored, and which deployment questions need a specific agreement. <!-- sdk-release-note-exempt: This pull request changes only documentation and does not change published SDK behavior. -->