JacobLinCool / JacobLinCool/particeps
Add immutable signed join links and QR import
- Dominant language
- Kotlin
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
> **Renamed by #23.** This issue was written while the project was called Android Data
> Collector. Its terminology has been updated to the Particeps identity now in force. The
> old spellings are rejected inputs, not an earlier dialect.
## Summary
Add a bounded `particeps://join` Protocol v1 URI and QR-code flow that transports an immutable signed configuration into the existing fingerprint and consent experience.
A join host is only a byte transport. It cannot update, replace, or remotely adjust a configuration after the participant accepts it.
## Requirements
### Join URI
- Define one canonical `particeps://join` v1 URI representation containing:
- one HTTPS artifact URL;
- the complete artifact SHA-256;
- the expected Ed25519 signer fingerprint;
- the join-format version.
- Define strict length, character, percent-encoding, duplicate-parameter, unknown-parameter, URL, host, port, and fragment rules.
- Do not include `assigned_participant_id`, `participant_instance_id`, names, roster codes, tokens with embedded identity, or configuration contents in the URI.
- For personalized configurations, require an opaque cryptographically random artifact path. Do not place the roster/assigned code in URL paths, queries, logs, analytics, or QR labels.
- Generate and consume the same canonical URI in Web tooling, Android, tests, and future iOS support.
### Import behavior
- Support OS deep-link/open-with handling, paste/import, and camera/QR entry without granting the hosted artifact any application capability.
- Download the artifact exactly once into bounded staging storage.
- Require HTTPS and disable redirects of every kind.
- Enforce content length and absolute size bounds while streaming.
- Verify the complete SHA-256 before parsing, then verify canonical Protocol v1 structure and Ed25519 signature against the expected fingerprint.
- Continue through the existing signer-fingerprint confirmation, capability/access disclosure, and explicit consent flow only after all integrity checks pass.
- Generate a fresh `participant_instance_id` at accepted import; never obtain one from the link.
- Clear staging bytes after successful import or any failure.
- Reject join when an active study already exists.
### No remote adjustment
- Do not poll, refresh, replace, revoke, or background-update a configuration.
- Do not retain the URL as an authority after import.
- A host changing bytes at the same URL must result in digest failure, not an update prompt or fallback.
- Network failure must leave no partially accepted study and must not fall back to unsigned/local alternate content.
## Acceptance criteria
- Web-generated links and QR codes parse identically on Android and in Protocol v1 fixtures.
- Redirect, downgrade, wrong digest, wrong signer, modified bytes, oversized content, duplicate/unknown parameters, and malformed encoding fail before consent.
- Personalized join URLs and logs reveal no assigned participant/roster identifier.
- Importing the same artifact on two clean devices creates distinct participant-instance IDs.
- An active study cannot be replaced through a join link.
- Changing the hosted artifact after a participant imports it has no effect on the active study.
- Successful and failed imports leave no staged configuration bytes, temporary tokens, or sensitive URL logs.
- There is no polling, refresh, remote replacement, or background network job associated with a joined configuration.
## Documentation
Add the normative join-URI contract, QR generation/import guide, personalized-distribution guidance, participant flow, host security requirements, redaction rules, threat-model cases, and hostile fixtures.
## Dependencies
Blocked by #8, which defines the final signed Protocol v1 configuration, artifact digest, and signer fingerprint.
Contributor guide
Research direction
Start with dependency #8, then inspect the existing fingerprint and consent experience, Web tooling, Android entry points, and Protocol v1 fixtures named in the issue. Done means the bounded canonical join URI and QR/import flow meet the listed integrity, privacy, failure, and no-remote-adjustment acceptance criteria, with the required documentation and hostile fixtures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- android, kotlin
- Domain
- api, cryptography, mobile-dev, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100