JacobLinCool / JacobLinCool/particeps
Support researcher-authored interactive web tasks
- Dominant language
- Kotlin
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Add researcher-authored HTML/JavaScript games, cognitive tasks, and other interactive activities as a constrained `web_task` intervention action.
The implementation must support both reproducible offline packages and HTTPS-hosted tasks without turning WebView into an unrestricted extension mechanism. It builds on the occurrence/action foundation in #1 and the dual participant identity model in #2.
## Task sources
### Offline package
- Introduce a study distribution container that can carry the signed configuration and bounded web assets.
- Keep the task manifest in the signed Protocol v1 configuration, including:
- package digest;
- entry point;
- declared event/result schema;
- storage/network/identity capabilities;
- byte and event-rate limits.
- Verify the package digest before import or execution.
- Reject path traversal, duplicate archive entries, symlinks, compression bombs, unsupported content, and assets beyond declared/absolute size limits.
- Serve verified assets through an application-controlled HTTPS-like origin such as `WebViewAssetLoader`; do not use unrestricted `file://` access.
### HTTPS URL
- Require an HTTPS entry URL.
- Declare allowed origins and navigation behavior in the signed configuration.
- Block cleartext HTTP, undeclared origins, external schemes, popups, downloads, and cross-origin navigation unless explicitly supported by a future capability.
- Do not silently fall back from an unavailable offline package to a remote URL, or vice versa.
## WebView isolation
- Use a dedicated, hardened WebView surface and lifecycle.
- Disable file/content access, password saving, debugging in release builds, arbitrary intent launches, geolocation, media capture, and other Android capabilities by default.
- Grant no Android permission merely because a page requests it.
- Clear task-scoped cookies, cache, DOM storage, service workers, and other origin state according to the declared task lifecycle.
- Define a strict Content Security Policy for offline content and enforce the configured origin policy for hosted content.
- Prevent task content from navigating to configuration/participant screens or invoking internal app APIs outside the bridge.
## JavaScript bridge
Expose a narrow, versioned bridge for:
- task opened/started;
- bounded progress/research events;
- local result submission;
- task completion or explicit abandonment;
- explicitly authorized participant context.
Requirements:
- Validate every message against the task manifest's declared event/result schema.
- Enforce per-message size, total-byte, event-count, and rate limits.
- Reject unknown event names and fields.
- Preserve event order and append accepted local events to the encrypted study stream.
- Do not expose generic reflection, filesystem, network, Android Context, or arbitrary method invocation.
- Make completion/submission idempotent per occurrence.
## Data destination and participant context
- **Local collection:** the default. Task events/results cross the bridge and are stored in the app's encrypted event stream.
- **External collection:** allowed only when configuration and consent identify the receiving origins and disclosed data. The app records task lifecycle, while the external service owns its submitted payload.
- Never place participant identifiers in URL query parameters, fragments, referrers, notification payloads, or logs.
- Expose an opaque identifier through the bridge only when the signed task capability explicitly requests it and the consent flow discloses it.
- Use the model from #2:
- instance ID remains the import/device discriminator;
- assigned participant ID is optional and must remain protected unless external disclosure is explicitly configured.
- Record exactly which identity capability and destination were consented to.
## Lifecycle events
Record bounded, encrypted events for:
- `web_task_opened`;
- `web_task_started`;
- declared progress/research events;
- `web_task_completed`;
- `web_task_abandoned`;
- `web_task_failed`.
Each event includes stable task, intervention, and occurrence IDs. Failure events use fixed reason codes and must not include page content, JavaScript exceptions containing study data, URLs with sensitive values, or submitted answers.
## Researcher and participant surfaces
- Add offline-package/HTTPS task configuration to the researcher Web UI with manifest validation and a permission/data-destination summary.
- Show task source, network destinations, locally/external collected data, identity disclosure, and capabilities during participant consent.
- Open the exact task occurrence from its notification or rule-triggered action.
- Provide clear exit/abandon behavior and prevent a task from trapping the participant.
- Update English and Traditional Chinese UI.
## Acceptance criteria
- A hash-pinned offline task runs without network access and fails closed when any asset changes.
- A hosted task can reach only its declared HTTPS origin set.
- Undeclared navigation, schemes, downloads, permissions, bridge calls, fields, oversized messages, and excessive event rates are blocked.
- Local results appear once in encrypted export/upload output and never in logs or cleartext storage.
- External mode discloses its destination and identity capability before consent and does not leak identity through URL/referrer surfaces.
- Duplicate bridge submission, rotation, process death, back navigation, and repeated notification taps do not duplicate completion/results.
- WebView state is isolated between task occurrences and studies.
- Hostile archive, origin, bridge, JavaScript, and lifecycle tests are included.
- Researcher tooling, canonical Kotlin/TypeScript validation, app UI, docs, and threat model agree on the manifest.
## Documentation
Update the researcher guide, participant guide, study distribution format, system design, data dictionary, threat model, consent guidance, and a minimal offline and HTTPS example task.
## Dependencies
- Blocked by the intervention action and occurrence foundation in #1.
- Participant context and identity disclosure must use the dual-ID model in #2.
- Event rules in #4 may trigger web-task actions after this action type is available.
## Roadmap coordination: mutable hosted-content exception
Hosted HTTPS task content is the sole explicit exception to the product's no-remote-adjustment rule.
- The signed Protocol v1 task manifest remains immutable and fixes the entry URL, allowed origins and navigation, bridge event/result schema, network destinations, identity capability, per-message/total size and rate limits, schedule/trigger, and task lifecycle capabilities.
- Hosted HTML/JavaScript and its same-policy resources may change between occurrences, but hosted content cannot modify the accepted app configuration, collector set, Android permissions, signed destinations, intervention schedule, consent, or study lifecycle.
- For every hosted execution, append encrypted lifecycle provenance containing the final entry-document URL, `ETag` and `Last-Modified` when present, and SHA-256 of the fetched entry-document bytes.
- The entry-document digest is provenance for later reproduction; it is not a content pin and must not prevent a later occurrence from loading changed hosted content within the same signed capability boundary.
- Tests must prove that mutable content cannot navigate or bridge beyond the signed manifest, request new Android capabilities, change collection/destinations/scheduling, or invoke internal lifecycle/configuration APIs.
- Protocol v1 manifest encoding, canonicalization, signatures, platform targeting, and fail-closed behavior are defined by #8.
Contributor guide
Research direction
Start by reading the occurrence/action foundation in #1, the dual participant identity model in #2, and the Protocol v1 manifest rules in #8. Trace the WebViewAssetLoader, researcher and participant UI, bridge validation, encrypted event stream, and lifecycle tests described here. Done means offline and hosted tasks fail closed, enforce the signed manifest, isolate state, protect identity and results, and include the required documentation and hostile-case tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, javascript, kotlin, typescript
- Domain
- documentation, frontend, mobile, security, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 18/100