Consent System

​

Core principles

1. Explicit consent — every data-collection or upload operation requires an explicit grant.
2. Granular control — module-level booleans plus per-channel flags.
3. Revocable — consent can be withdrawn at any time; the runtime stops within the next cycle.
4. Cloud-verified — when the consent service is configured, a valid JWT is required, not just a local boolean.
5. Enforced — missing consent silently drops samples and uploads at the runtime seam; nothing fakes the data.

​

Three-layer authority

​

Consent types

​

Granular channels

​

Consent tiers

​

Consent status

​

Consent flow

​

1. Initial consent request

await Synheart.initialize(
  config: SynheartConfig(
    appId: 'com.example.app',
    subjectId: 'anon_user_123',
    consentConfig: ConsentConfig(
      appId: 'com.example.app',
      appApiKey: appApiKey,
    ),
  ),
);

bool ready = await Synheart.hasConsent('biosignals');
if (!ready) {
  // Show your consent UI, then submit:
  final result = await Synheart.consentSubmitForm(
    deviceId: deviceId,
    platform: 'ios',
    formJson: jsonEncode(consentForm),
  );
  // result.token is the issued JWT; consent module stores it automatically.
}

​

2. Granting

• Local grant — Synheart.grantConsent(...) mutates the local snapshot. Useful for unit tests and dev. In production with a configured consent service, the runtime will still report pending until a JWT is issued.
• Cloud submit — Synheart.consentSubmitForm(...) sends a signed form to the consent service and stores the returned JWT. This is the production path.

​

3. Storage

• The local ConsentSnapshot (per-type booleans, channels, tier, timestamps).
• The cached ConsentToken (JWT, profile id, expiry, scopes).
• Per-platform storage keys are scoped per subject_id.

• Private keys (those live in the Secure Enclave / Keystore via synheart-auth).
• Raw form input fields beyond the consent submission.

​

4. Revocation

await Synheart.revokeConsentType('biosignals');   // single type
await Synheart.revokeConsent();                   // all types

• Each module checks consent before pushing samples; revoked modules’ samples are silently dropped at the runtime engine seam.
• Cloud uploads stop on the next flush — the runtime’s connector hook reads the consent state before draining the queue.
• Local data is not deleted automatically. Use Synheart.wipeLocalData() if you need a hard wipe.

​

What happens mid-session

• Sample ingest stops at the seam. Modules continue running, but samples for revoked types are dropped before they reach inference. Your onHSIUpdate / onStateUpdate streams keep firing — they just stop containing fields derived from revoked data, and confidence on affected axes drops.
• In-flight cloud uploads continue; queued ones don’t. Whatever is already on the wire when the user revokes will complete. Anything still in the local queue is held until consent is re-granted, or discarded on wipeLocalData().
• Already-emitted HSI events are not retroactively recalled. If your app has buffered HSI envelopes from before the revocation, that data is yours to delete or retain per your own policy.
• No app-level callback fires. Observe consent state via Synheart.onConsentChange if you need to react (pause UI, surface a “consent required” banner, etc.).

​

Enforcement

​

hasConsent semantics

hasConsent(type) =
  if cloudConsentConfigured AND consentStatus != granted:
    return false
  return localSnapshot.allows(type)

​

Per-action gates

​

Account-deletion override

​

Cold-start consent buffer

• The auto-enqueue bridge buffers up to 8 pending HSI windows when consent is pending.
• On granted, the buffer drains and replays into the upload queue.
• If consent never lands, the oldest buffered windows drop FIFO.

​

API reference

​

Querying state

// Snapshot summary (booleans + timestamp).
final snapshot = Synheart.shared.currentConsent;

// Coarse status enum.
final status = Synheart.getConsentStatus();
// Returns: ConsentStatus.granted | .pending | .denied | .expired

// Raw status map (status string + last-updated timestamp).
final raw = Synheart.consentStatus();

// True when the JWT expires within 5 minutes.
final needsRefresh = Synheart.consentNeedsTokenRefresh();

// Single-type query.
final ok = await Synheart.hasConsent('biosignals');

​

Mutating state

// Grant per channel (named-bool form is the canonical signature).
await Synheart.grantConsent(
  biosignals: true,
  behavior: true,
  phoneContext: false,
  cloudUpload: false,
);

await Synheart.revokeConsentType('biosignals');
await Synheart.revokeConsent();      // revoke every channel

​

Cloud submission

// Get the editable form (built from cached profile + current snapshot).
final form = await Synheart.consentGetEditableForm();

// Submit and receive a JWT. Signed by the device key automatically.
final result = await Synheart.consentSubmitForm(
  deviceId: deviceId,
  platform: 'ios',
  userId: userId,           // optional
  formJson: jsonEncode(updatedForm),
);

// Force a token refresh if needed.
await Synheart.ensureCloudConsentReady();

​

Privacy invariants

• The SDK never collects content (no text, no clipboard payloads, no notification bodies, no audio).
• Raw subject_id never leaves the device — only subject_hash.
• Token material is in-memory only; never persisted in plaintext.
• Revocation pauses outbound traffic on the next flush, not on a timer.

​

Related

• Cloud Protocol — what cloudUpload actually authorises.
• Capability System — the second authority alongside consent.
• Synheart Auth — Signing — how consent submissions are device-signed.
• Synheart Behavior — Threat Model — what behavior consent unlocks at the SDK layer.