JacobLinCool / JacobLinCool/particeps

Implement Swift Protocol v1 conformance and platform-specific authoring

Open
#20 0 comments 0 reactions 0 assignees View on GitHub
area: ios area: protocol P3
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

Implement a standalone Swift package for the final Particeps Protocol v1 and add explicit Android/iOS targeting to researcher authoring.

Android and iOS may share an `experiment_id`, but they must use separately signed artifacts with unique `configuration_id` values, platform-specific collector scope, consent, access requirements, and minimum client version. Do not use silent capability negotiation or make a Kotlin Multiplatform rewrite a prerequisite.

## Requirements

### Swift Protocol v1 package

- Implement strict Protocol v1 configuration and export types without importing Kotlin/JVM or Tink wire representations.
- Use CryptoKit for:
- Ed25519 signing and verification through `Curve25519.Signing`;
- raw X25519 key handling;
- RFC 9180 HPKE with the exact X25519/HKDF-SHA-256/AES-256-GCM suite, mode, context, and constants defined by #8;
- AES-GCM content encryption/decryption where specified.
- Encode Ed25519/X25519 public keys as unpadded base64url raw 32-byte values.
- Implement RFC 8785 canonical JSON, strict decimal-string 64-bit values, integer physical-unit configuration, complete bounds, duplicate/unknown-field behavior, frame parsing, and fail-closed legacy-v1 rejection.
- Consume the exact shared valid/hostile conformance corpus from #8; do not translate fixtures into Swift-specific equivalents.
- Expose typed APIs for configuration verification, bundle encryption/decryption, receipt validation, registry/capability lookup, and stable error classification.
- Avoid library-default algorithm identifiers or contexts that could diverge from the normative wire contract.

### Cross-language conformance

- Verify every shared canonicalization, signature, digest, HPKE, framing, receipt, and hostile-input vector.
- Add Android/Kotlin → Swift decrypt/verify tests.
- Add Swift → Kotlin and Swift → Python decrypt/verify tests.
- Include wrong-key, wrong-context, wrong-configuration, malformed-frame, trailing-byte, Unicode, numeric-bound, and old-artifact rejection cases.
- Make these cross-language tests required CI gates.

### Platform-specific researcher authoring

- Require the researcher to choose Android or iOS when creating a configuration.
- Permit a research project to reuse an `experiment_id` across platforms, but generate a fresh `configuration_id` and signature for every platform artifact.
- Bind the selected platform, minimum client version, collector availability, access requirements, intervention scope, data disclosure, and consent text into the signed artifact.
- Generate allowed collector/control choices and an Android/iOS parity matrix from #10.
- Refuse to sign a configuration containing an unsupported required collector or platform feature.
- Do not silently omit, substitute, downgrade, or reinterpret a collector when changing targets.
- Make platform differences visible before signing and in exported provenance.

## Acceptance criteria

- Swift passes the complete #8 valid and hostile corpus byte-for-byte.
- Android-produced bundles decrypt and verify in Swift; Swift-produced bundles decrypt and verify in Kotlin and Python.
- Raw key, signature, canonical JSON, HPKE context, framing, and receipt encodings have no Swift-only variant.
- Old Protocol v1/Tink artifacts and unsupported algorithms fail closed; no legacy fallback exists.
- Two platform configurations may share an experiment ID but cannot share a configuration ID or signature.
- Web authoring cannot sign an iOS configuration containing an Android-only required collector, or vice versa.
- Switching the authoring target never silently alters a previously signed artifact.
- The parity matrix, Web controls, Swift types, Kotlin types, and Python schemas agree with the same registry digest.
- The implementation does not require or begin a Kotlin Multiplatform rewrite.

## Documentation

Add Swift package/API documentation, CryptoKit mapping, cross-language conformance instructions, platform-authoring guide, parity matrix, key-handling guidance, error taxonomy, and Protocol v1 implementation notes.

Reference: [CryptoKit HPKE](https://developer.apple.com/documentation/cryptokit/hpke).

## Dependencies

Blocked by #8 (Protocol v1), #9 (final exact-replay upload/receipt contract), and #10 (collector/event registry).

Contributor guide

Open the contributing guide

Research direction

Start by reviewing dependencies #8, #9, and #10, then use the exact shared conformance corpus from #8 as the entry point for the standalone Swift package. Add the required Android/Kotlin-to-Swift and Swift-to-Kotlin/Python verification and hostile-input CI gates, followed by platform-specific authoring and documentation. Done means the listed cross-language, fail-closed, unique-ID/signature, parity-matrix, and documentation acceptance criteria pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin, python, swift
Domain
cryptography, documentation, mobile, security, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.