Source preview guide · 0.1.0
Source and client authority
Understand the separate decisions that let a client request work and a scanner read source.
An editor connection, an authorized source root and an approved protected repository answer different questions. CodeSecurity checks each at the boundary where it matters. A project name or a path submitted by a client does not by itself authorize source access.
Separate the owner’s decisions
Client authority
- Browser session
Paired HttpOnly session; mutations also require the exact Origin and CSRF value.
- IDE capability
Approval binds the intended profile and authority generation.
Request admission
- Route and ownership checks
The client must satisfy the route scope and its operation-specific checks.
- Source authorization
Explicit host-owner action exposes only reviewed narrow roots or supported snapshots.
Repository protection
- Repository-member approval
The intended editor generation receives permission for the exact repository.
- Host application
Explicit Apply changes the local clone; requested state alone is not installation.
Connections
Browser session to Route and ownership checks
Browser membership does not bypass operation-specific ownership.
IDE capability to Route and ownership checks
Only the exact capability allowlist is admitted.
Route and ownership checks to Source authorization
Selecting or registering a project does not itself grant host source access.
Route and ownership checks to Repository-member approval
Ordinary IDE membership does not grant repository-member permission.
Repository-member approval to Host application
The approved setting still needs explicit application to the intended clone.
| Decision | What it permits | What remains separate |
|---|---|---|
| Browser authentication | Use the local control application through its session boundary | Unsafe requests still require the allowed origin and CSRF protection. |
| IDE membership | Use the routes allowed by the capability’s scopes and active generation | Workspace Trust, source access and repository-protection approval. |
| Workspace Trust | Allow supported editor actions for that workspace | A wider container source mount or a new owner’s approval. |
| Source-root authorization | Mount an existing, narrow source root read-only | Registration of a project and each scan’s selected scope. |
| Snapshot admission | Retain a bounded source generation with a checked identity | Arbitrary host filesystem access or execution of uploaded source. |
| Git-protection approval | Let the exact approved editor generation manage the selected repository’s protection | Proof that the host hook is applied, current push evidence or server-side enforcement. |
Browser and editor authority can be revoked independently. IDE requests are checked against exact route scopes and the active capability generation. The control API is not a generic API-key service. The authentication guide explains the supported client flow.
The request boundary also validates Host and Origin and refuses credential material in URLs. Authentication is not a substitute for route-specific ownership checks. See the security middleware and IDE authorization.
Mounted source is an explicit host boundary
For supported POSIX and Remote WSL workflows, the owner selects existing narrow source roots. The host helper canonicalizes the path and rejects broad roots, unsafe path forms and values that cannot be serialized literally into the Compose environment. It allows at most 32 distinct configured roots. Compose does not create a missing bind source to make a request succeed.
The API does not have the project-source mount. Its preview checks whether the requested path is within the configured authority and returns a decision without creating a project or job. Project creation records that source identity. At execution, the scanner independently checks the real path and uses constrained source-reading operations rather than treating the API’s lexical path check as proof of safe access.
Selected-file and selected-directory scans remain within the authorized repository. The scanner validates the target and captures its source view for tool execution. A request cannot turn a selected directory into permission to read outside that root.
Implementation entry points are source-root validation, source preview and project creation and descriptor-relative source reads.
Snapshots carry source, not a wider mount
Supported native-Windows workflows and immutable Git-tree checks use the dedicated snapshot store. The API validates file paths, counts, sizes and content identity before publishing a sealed generation. A snapshot-backed scan must name the exact expected digest; a mounted-source project cannot silently substitute an uploaded snapshot.
| Bound | Pinned implementation |
|---|---|
| Snapshot payload | At most 5,000 files, 8 MiB per file and 64 MiB of source content. |
| Retained or interrupted generations | At most 256. |
| Store inventory | At most 65,536 filesystem entries and 64 source-directory levels. |
| Aggregate snapshot storage | At most 2 GiB, with filesystem allocation and metadata overhead accounted for. |
| Free-space admission | New allocation plus a further 2 GiB reserve must be available. |
Publication and explicit deletion share a private no-follow lock. A concurrent writer receives snapshot_storage_busy; unsafe or unreadable storage returns snapshot_storage_unavailable; capacity refusal returns snapshot_storage_full. These refusals do not queue a hidden retry or automatically delete older evidence.
An identical sealed generation is validated and reused without allocating another copy, including when new-write admission is full. Interrupted publication still consumes the storage budget. Only explicitly reviewed, matching source generations are eligible for deletion. Other processes can consume host disk space, so these local bounds cannot promise that the entire disk will never fill.
See snapshot admission and the storage contract. Capture limits are distinct from the scanner’s smaller eligible-text analysis limit, explained in scanning.
Bind source navigation to current evidence
A finding’s file path is evidence, not an instruction to open an arbitrary file. Source-opening commands bind the selected IDE capability generation, finding revision and findings-collection revision. Stale or ambiguous recipients require reconciliation.
Committed-tree findings have a stricter limit: the API refuses to open an assumed matching current workspace file. The current working tree may differ from the historical source that produced the finding. Review the captured finding details instead. This refusal is explicit in IDE source commands.
Preserve the boundary when integrating
Use the supported browser or IDE authority model and perform the resource’s additional ownership checks. Do not widen source roots to resolve a stale capability, treat a path preview as scanner completion or infer native platform qualification from the existence of a snapshot implementation. Actual platform behavior needs evidence from the exact source, image and client being used.