JacobLinCool / JacobLinCool/particeps

Add immutable signed join links and QR import

Open
#15 0 comments 0 reactions 0 assignees View on GitHub
area: android area: protocol P1
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.