From 1c6ebfef1bd81b31409123e8fb8d84ca50c0adcd Mon Sep 17 00:00:00 2001
From: "JDS-WORKSTATION\\jspah" <44337821+jspahn80134@users.noreply.github.com>
Date: Fri, 28 Aug 2026 12:42:32 -0600
Subject: [PATCH 1/4] Enable HTTPS capture uploads
Compile the Rust capture HTTP client with minreq HTTPS support so token validation and event uploads can reach the AWS CaptureWebService endpoint.
Add the student-facing capture token setup guide and link it from the main README and VS Code extension README.
Document the SecretStorage token flow, local spool behavior, AWS ingestion path, and verified capture event coverage in the implementation notes and changelog.
---
CHANGELOG.md | 6 +-
README.md | 7 +
docs/capture-token-setup-guide.html | 521 ++++++++++++++++++++++++++++
docs/implementation.md | 17 +-
extensions/VSCode/Cargo.lock | 120 +++++++
extensions/VSCode/README.md | 7 +
server/Cargo.lock | 15 +
server/Cargo.toml | 2 +-
8 files changed, 692 insertions(+), 3 deletions(-)
create mode 100644 docs/capture-token-setup-guide.html
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fea2287d..18e59c4b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,7 +22,11 @@ Changelog
[Github master](https://github.com/bjones1/CodeChat_Editor)
-----------------------------------------------------------
-* No changes.
+* Fix capture token validation and event upload against HTTPS capture service
+ endpoints by enabling HTTPS support in the Rust HTTP client.
+* Add a student-facing CodeChat Capture token setup guide.
+* Document the capture token storage, upload spool, AWS service path, and
+ CaptureWebService-only database boundary.
Version 0.2.1 -- 2026-Jul-26
----------------------------
diff --git a/README.md b/README.md
index 92e7af1b..98d8cfeb 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,9 @@ Capture** or **CodeChat Editor: Enter Capture Token** from the command palette,
paste the token, then turn on consent and recording from the same capture
manager.
+For detailed student/tester setup steps, see the
+[CodeChat Capture Token Setup Guide](docs/capture-token-setup-guide.html).
+
The token is imported through the VS Code UI and persisted only in VS Code
SecretStorage. It is never written to workspace settings, repository files, or a
JSON configuration file. The extension asks CaptureWebService for token status;
@@ -60,6 +63,10 @@ again. The capture service endpoint can be changed in the user-level
for this token-bearing endpoint. Token-bearing requests require HTTPS except for
localhost development endpoints.
+Developer builds must keep the Rust `minreq` dependency compiled with HTTPS
+support. Without that feature, token validation and event upload to the AWS
+capture service report as unavailable even when the service itself is healthy.
+
Structure
---------
diff --git a/docs/capture-token-setup-guide.html b/docs/capture-token-setup-guide.html
new file mode 100644
index 00000000..0b5da6d2
--- /dev/null
+++ b/docs/capture-token-setup-guide.html
@@ -0,0 +1,521 @@
+
+
+
+ CodeChat Capture Token Setup Guide
+
+
+
+
+ Mississippi State University | Department of Electrical & Computer Engineering
+ CodeChat Capture Token Setup Guide
+
+ Use this guide to obtain a CodeChat Capture access token, store it in the
+ CodeChat VS Code extension, and turn on dissertation study capture.
+
+
+ Current environment: AWS dev/test deployment. This system is not production yet.
+ Last updated: August 28, 2026.
+
+
+
+
+
+ Before You Start
+
+ You need a Mississippi State email address, the class code supplied by
+ the instructor, and the CodeChat Editor extension installed in Visual
+ Studio Code.
+
+
+
+
+
+
+ 1
+ Request A Token
+
+ Open the registration portal in a browser.
+ Enter your Mississippi State email address.
+ Enter the class code exactly as provided: ECE9990.
+ Select Email Access Token .
+ Check your email for the CodeChat Capture token message.
+
+
+ The token begins with cccap_v1_. Copy the whole token,
+ including that prefix.
+
+
+
+
+ 2
+ Enter The Token In CodeChat
+
+ Open Visual Studio Code.
+ Open the Command Palette with Ctrl+Shift+P.
+ Run Manage CodeChat Editor Capture .
+ Select Enter Capture Token .
+ Paste the token from the email and press Enter.
+
+
+ You can also run CodeChat Editor: Enter Capture Token
+ directly from the Command Palette.
+
+
+
+
+ 3
+ Validate The Token
+
+ After the token is entered, CodeChat attempts to validate it.
+ Look for a message saying CodeChat capture token accepted.
+ If you are unsure, open Manage CodeChat Editor Capture again.
+ Select Validate Capture Token .
+
+
+ A valid token should produce a participant ID and an instance ID in
+ the capture status details.
+
+
+
+
+ 4
+ Turn Capture On
+
+ Open the Command Palette with Ctrl+Shift+P.
+ Run Manage CodeChat Editor Capture .
+ Select Give Consent and Record Study Events .
+ Enable the CodeChat Editor if it is not already running.
+ Open, edit, and save a study file normally.
+
+
+ Consent persists. Record Study Events is session-local,
+ so turn it on again after reopening VS Code.
+
+
+
+
+
+ What A Successful Setup Looks Like
+
+ When capture is ready, the CodeChat capture status bar item should show
+ one of the active states below. You can click the status bar item or run
+ Manage CodeChat Editor Capture to see more detail.
+
+
+
+
+
+ Status
+ Meaning
+ What To Do
+
+
+
+
+ Capture: Remote Capture is on and events are reaching the remote capture system.
+ Continue working normally.
+
+
+ Capture: Uploading CodeChat is actively uploading queued capture events.
+ Continue working normally.
+
+
+ Capture: Queued Events are stored locally and waiting to upload.
+ Check your network connection if this does not clear.
+
+
+ Capture: Starting The local CodeChat server is starting or reconnecting.
+ Wait a few seconds, then recheck the status.
+
+
+
+
+
+
+ Verify In VS Code
+
+ Open View > Output .
+ Select CodeChat Capture from the Output dropdown.
+ Look for a line similar to this after token validation:
+
+ capture token status: accepted participant_id=... instance_id=...
+ After turning capture on and editing a file, the same output channel
+ should show queued capture events such as session_start,
+ save, write_doc, or write_code,
+ depending on the activity performed.
+
+
+
+
+ Token Privacy
+
+ The email contains the clear access token. Treat it like a password.
+ Do not paste the token into source code, assignments, screenshots, chat messages, or bug reports.
+ CodeChat stores the token in VS Code SecretStorage, not in workspace settings or repository files.
+ The database stores only an HMAC token hash in capture_admin.instances.token_hash.
+ The capture system stores and checks only a protected hash of the token.
+
+
+
+
+ Troubleshooting
+
+
+
+ Symptom
+ Likely Cause
+ Fix
+
+
+
+
+ No token email arrives.
+ The email address was mistyped, the message went to junk mail, or the current AWS dev email service is limited to verified recipients.
+ Confirm the email address, check junk mail, then request another token.
+
+
+ The portal rejects the request.
+ The email is not an msstate.edu address, or the class code is wrong.
+ Use your Mississippi State email address and enter ECE9990 exactly.
+
+
+ Capture: Waiting for token No accepted token is stored in VS Code.
+ Run Manage CodeChat Editor Capture , then Enter Capture Token .
+
+
+ Capture: Waiting for consent Recording was turned on before consent.
+ Run Give Consent and Record Study Events , or turn consent on separately.
+
+
+ Capture: Paused Consent is on, but Record Study Events is off for this VS Code session.
+ Run Manage CodeChat Editor Capture , then Turn Record Study Events On .
+
+
+ Capture: Token rejected The pasted token is wrong, incomplete, or revoked.
+ Clear the token, paste it again from the email, then validate it.
+
+
+ Capture: Disabled by portal The participant or instance is disabled in the capture database.
+ Contact the instructor or research team.
+
+
+ Capture: Service unavailable The network or remote capture system is temporarily unavailable.
+ Keep working. If the same token was previously accepted, CodeChat will keep matching events queued locally and upload them when the service returns. If this status does not clear, update to the current CodeChat build.
+
+
+
+
+
+
+ End-To-End Checklist
+
+ Portal accepted the Mississippi State email address and class code.
+ Token email arrived.
+ Token was pasted into CodeChat through the VS Code UI.
+ CodeChat reported that the token was accepted.
+ Status details show a participant ID and instance ID.
+ Give Consent and Record Study Events was selected.The capture status bar shows an active, queued, or uploading state.
+ The CodeChat Capture output channel shows capture activity.
+
+
+
+
+ CodeChat Capture dev/test setup guide. Do not include real capture tokens in shared copies of this document.
+
+
+
+
diff --git a/docs/implementation.md b/docs/implementation.md
index fbe9c541..ec74f723 100644
--- a/docs/implementation.md
+++ b/docs/implementation.md
@@ -90,7 +90,10 @@ The service endpoint is read only from the user/application-level
`CodeChatEditor.Capture.ServiceBaseUrl` setting; workspace values are ignored so
a repository cannot redirect a stored token. Bearer-token requests require
HTTPS, with `http://localhost` and `http://127.0.0.1` allowed only for local
-development.
+development. The bundled Rust HTTP client uses `minreq` with the `https`
+feature enabled; without that feature, AWS HTTPS status checks and event uploads
+fail before reaching CaptureWebService and the extension reports the service as
+unavailable.
The upload worker deletes spooled events only after the service returns `202`.
After a token has been accepted at least once, transient service or network
@@ -102,6 +105,18 @@ configured again. Authentication failures pause upload until a valid token is
entered, malformed or oversized events are moved to the spool quarantine
directory, and blocking service calls use bounded request timeouts.
+The AWS end-to-end path exercised during integration testing is:
+
+```
+VS Code extension -> local CodeChat server -> CaptureWebService HTTPS API
+ -> API Gateway/Lambda -> SQS -> writer Lambda -> capture.events
+```
+
+The verified extension-generated event stream includes `session_start`,
+`write_doc`, `reflection_prompt_inserted`, and `save`. Additional service
+contract tests submit representative well-formed event batches for optional
+study/debug/build event types through the same public HTTPS API.
+
Before You Start
Email address must end in msstate.edu.
- Current class code is ECE9990. It is case-sensitive.
- Current registration portal: http://3.146.138.182/capture-registration/
+ The class code is supplied by your instructor or research team and is case-sensitive.
+ Use only the HTTPS registration portal link provided for your class or study.
@@ -316,15 +316,14 @@ Before You Start
1
Request A Token
- Open the registration portal in a browser.
+ Open the HTTPS registration portal link provided by your instructor or research team in a browser.
Enter your Mississippi State email address.
- Enter the class code exactly as provided: ECE9990.
+ Enter the class code exactly as provided.
Select Email Access Token .
Check your email for the CodeChat Capture token message.
- The token begins with cccap_v1_. Copy the whole token,
- including that prefix.
+ Copy the entire token from the email exactly as shown.
@@ -377,10 +376,10 @@ Turn Capture On
- What A Successful Setup Looks Like
+ Capture Status Reference
- When capture is ready, the CodeChat capture status bar item should show
- one of the active states below. You can click the status bar item or run
+ The CodeChat capture status bar item shows the current capture state.
+ You can click the status bar item or run
Manage CodeChat Editor Capture to see more detail.
@@ -413,6 +412,21 @@ What A Successful Setup Looks Like
The local CodeChat server is starting or reconnecting.
Wait a few seconds, then recheck the status.
+
+ Capture: Waiting CodeChat is checking capture readiness or waiting for a server response.
+ Wait a few seconds, then validate the token if this status does not clear.
+
+
+ Capture: Off Capture recording is off for the current VS Code session.
+ Run Manage CodeChat Editor Capture , then turn recording on.
+
+
+ Capture: Error CodeChat encountered a local or remote capture error.
+ Open the CodeChat Capture output channel and contact the instructor or research team if it persists.
+
@@ -424,7 +438,7 @@ Verify In VS Code
Select CodeChat Capture from the Output dropdown.
Look for a line similar to this after token validation:
- capture token status: accepted participant_id=... instance_id=...capture token status: Accepted participant_id=... instance_id=...
After turning capture on and editing a file, the same output channel
should show queued capture events such as session_start,
@@ -439,7 +453,6 @@
Token Privacy
The email contains the clear access token. Treat it like a password.
Do not paste the token into source code, assignments, screenshots, chat messages, or bug reports.
CodeChat stores the token in VS Code SecretStorage, not in workspace settings or repository files.
- The database stores only an HMAC token hash in capture_admin.instances.token_hash.
The capture system stores and checks only a protected hash of the token.
@@ -463,7 +476,7 @@ Troubleshooting
The portal rejects the request.
The email is not an msstate.edu address, or the class code is wrong.
- Use your Mississippi State email address and enter ECE9990 exactly.
+ Use your Mississippi State email address and enter the class code exactly as provided.
Capture: Waiting for token