HRC protocol and permission proposal#

Draft 2, 31 October 2026. Product plan · HyperNet contract

This document defines the permission model and records the original design targets. The wire specification, storage runtime, clock boundary, MLS runtime, endpoint lifecycle and federation runtime specify the selected implementation contracts. This document is not qualification evidence. The product plan and its scope amendment remain authoritative. Linux first, service-readable community rooms, encrypted confidential direct conversations and encrypted private groups are confirmed scope. The pilot allocation, retention/retry defaults and future-only encrypted history default were accepted on 31 October 2026; the product plan records their exact scope. Values still labelled proposed are design or qualification targets, not supported-capacity claims. Where a runtime document selects a concrete representation or bound, use that contract.

1. Trust and ownership#

HyperNet authenticates admitted application transport and enforces its current stream authority. HRC owns account bindings, room rights, delegation, ordering and storage. A verified stream principal is not proof that a human typed a message. Network transport failure never enables direct Internet fallback. Missing privacy evidence produces an explicit unknown state, never an inferred protection badge.

Each room has one designated home HRC service. That service owns the authoritative room sequence and evaluates effects against its current state. Federation adds explicit remote admission and restrictions; it does not create multi-writer history, cluster replication, leader election or failover. Home unavailability preserves permitted drafts and retained copies without claiming delivery.

2. Identifiers and validated types#

Endpoint enrolment requires an already authorised account controller, proof of possession of the new endpoint key, the exact transport-principal binding and explicit confirmation. Account classification, device enrolment and an agent's right to act are separate records. First-account enrolment uses an explicit admission/invitation policy, not an unauthenticated nickname claim. Account recovery requires the pre-enrolled owner-held recovery key, with no administrator override. Losing both all authorised devices and that key requires a new account. The recovery credential authorises account control; it cannot decrypt previous encrypted messages.

3. Sessions and operation envelope#

After HyperNet handoff, Session.Open proposes a protocol version and bounded capabilities. The server verifies its expected network/service context and returns negotiated limits, session identity, retry-window validity and clock/permission status that it can actually establish. Session.Resume creates a fresh session after current checks; it cannot restore expired transport authority. The application protocol label is hrc/1; it is distinct from HyperNet transport protocol 7.

Every effect carries an OperationId, operation kind, exact target, actor mode, immutable content, relevant expected revisions and optional approval reference. The authenticated endpoint is bound to this session. A federated Action also signs its origin account/network/incarnation, endpoint-enrolment generation, exact endpoint-binding digest and agreement ID/revision/digest. Surrounding gateway or attestor objects must match those signed values. The server rejects payload attempts to substitute actor, home service or origin. The native wire profile fixes the deterministic CBOR objects, COSE envelopes, domain separation and extension rules. Signatures and hashes bind those exact bytes. The integration profile defines the verified transport and origin-evidence boundaries.

Unknown critical capabilities or fields fail with UnsupportedVersion or UnsupportedFeature. Optional ignorable fields are explicitly enumerated per operation. Capability negotiation cannot remove required permission, privacy or encryption rules. A client that cannot process a room's required encryption/group-policy version cannot join it.

The native wire profile has no compressed application frames. Its integer bounds, duplicate-field rejection and canonical encoding also apply to signed federation actions and approvals.

Inspect responses expose effective operations, rooms, history bounds, expiry, agent mode and pending approvals. They do not substitute for a fresh effect check. CLI structured output, TUI commands, GUI controls and agent APIs call these same domain contracts. /me, /motd, mentions and completion are typed interaction conveniences, not alternate permission paths.

4. Delegation and exact approval#

A grant binds owner, agent endpoint/account, receiving home service/network, room IDs or exact recipients, operations, history interval, mode, validity, rate/cost limits and revision. Allowed operations distinguish read, reply, initiate, mark handled and each moderation action. Delegation creation and further delegation are excluded from agent scope. A purpose description is explanatory text; it grants nothing.

Effective permission is the intersection of current transport authority, endpoint binding, represented account rights, grant, room policy, recipient restrictions and federation policy. An agent receives no access through a represented account's ban. Changing to its independent identity does not convert a denied delegated request into success; distinct independent participation still needs independent room admission and applicable ban policy.

Approval.Prepare stores or identifies the complete immutable action, including operation ID, actor/represented identity, grant revision, room/recipient, content bytes, attachments if later supported, expiry and expected policy/epoch. The trusted owner interface renders that exact candidate. Approve binds its exact digest and a one-use approval ID; execution atomically consumes it with the outcome. Repeating the same operation returns its old result, while reusing an approval for another operation fails.

For encrypted sends, the server cannot inspect approved plaintext. The owner's authorised endpoint must independently decrypt and validate the exact candidate ciphertext and bound metadata before approving its digest. An unverified agent-supplied plaintext preview is insufficient. The state and recovery specification defines one transactional decryption and a private pending-approval record, followed by matching delivery without a second ratchet advance. Exact ciphertext is retained for retries. If the owner cannot verify the candidate, approval is unavailable.

Pause/revoke is owned by the receiving home service, including remote grants. Its durable acknowledgement means no later action in that service's evaluation order can use the old permission. Queued work is rechecked at the serial authorisation point immediately preceding its durable transaction; draft time and connection time confer no priority. The integration profile distinguishes that decision from physical storage completion and preserves uncertain outcomes. Effects already committed are retained with attribution. Revocation does not erase disclosed content or instantly remove an endpoint's old decryption keys.

5. Ordering, durability and recovery#

The selected storage contract uses SQLCipher and one home-service serial commit order spans room effects and security-control changes. Each room exposes its own monotonic sequence; the serial authorisation point checks relevant current grant, agreement and room revisions, and the resulting durable transaction precedes publication. Cross-room pause therefore has one service-owned boundary without requiring a global order between independently administered services. Server receive time and commit time are recorded distinctly; client time is advisory only.

The event stores its ID, room sequence, authenticated actor, optional represented account/grant, policy references, content or ciphertext, parent/reply reference and server timestamp semantics. Membership, moderation and epoch transitions share that room's order. Unknown database or clock health prevents acceptance; monotonic timers bound work, and uncertainty near authority expiry refuses an effect. The clock boundary defines clock-health and restart handling. A fresh action-bound HyperNet check must remain valid at the authorisation point. If durability completes later than its expiry, preserve the real outcome; a timeout cannot retroactively reject a committed event. See the integration profile for the bounded revocation race and control-acknowledgement boundary.

The selected durable acknowledgement means the event, authoritative access transition, deduplication outcome and required recovery metadata have committed to crash-durable storage before Committed is sent. One-host media loss is outside that guarantee. Search indexes may be rebuilt, but a result cannot be returned from an index beyond its committed visibility point. Disk exhaustion returns Overloaded/StorageQuota before a success acknowledgement.

The accepted retry-window limit is 24 hours. The home service issues and durably stores each window with a non-reused ID and expiry. Accepted outcome records last at least seven days and beyond their window expiry. The deduplication key includes authenticated actor and operation ID; immutable action bytes are compared before any new effect. New requests using a closed/missing window are rejected even after its deduplication rows are purged. A client cannot extend its window by changing a timestamp.

Operation.Resolve returns Committed, Rejected, Pending, AbsentInOpenWindow or ExpiredUnknown. It can disclose a minimal result for that actor's own request without restoring room-content access. Existing committed outcomes remain committed after revocation. An absent ID in an open window may be resubmitted with identical bytes and fresh current permission. An expired unknown outcome is never automatically resent under a new ID. Reconnect resolves uncertain operations, then obtains current subscriptions and resumes authorised cursors.

Only authenticated, admitted requests receive durable outcomes. Invalid framing and failed account authentication cannot allocate outcome rows. RateLimited or Overloaded before admission leaves the operation absent and permits a later identical retry within its window. A terminal rejection after admitted evaluation is retained; it is not silently reevaluated as a new effect.

Accepted history defaults are 30 days with a 10 GiB service quota and seven days/512 MiB for local archives. The implementation must qualify these limits; acceptance of the policy is not a measured capacity claim. Current access and expiry exclude content immediately; index/preview removal completes within a proposed 60-second cleanup bound. Quota exhaustion does not silently shorten an agreed retention window. Exports require deliberate selection; diagnostic logs exclude message bodies, decrypted drafts and keys.

Backups preserve identity, committed history, deduplication windows/outcomes, grant and agreement revisions, device policy, monotonic recovery markers and encrypted local key state where applicable. Restoring an older backup must not silently accept previously committed operations as new. The storage specification requires an independently retained continuity guard or a proven complete current log before active service restart. An old snapshot may support an isolated recovery view, but cannot resume effects under the previous identity when continuity is lost. Backups remain disabled until their destination, retention and disclosure policy are configured.

Resume cursors are opaque and bind home service, room, room sequence, authorised history window and current access/filter revisions. They never grant access. Membership/policy changes cause reevaluation, not continuation under old rights. Missing retained history returns ResynchronisationRequired with the permitted earliest point, without exposing inaccessible event existence. Search uses the same current access predicate and recipient ignore filter as live delivery; pagination remains bounded and cancellable.

6. Text and presentation boundaries#

Protocol text is UTF-8; malformed sequences fail during bounded decoding. Original message bytes are preserved. The proposal separates maximum bytes, graphemes and display width; cursor motion and editing use grapheme boundaries. The text profile selects Unicode17 and pinned segmentation/width data, with conformance and presentation qualification still required. RFC 3629 and UAX #29 provide the encoding/segmentation reference.

Lookup uses the text profile's versioned canonical-normalisation/full-fold key while preserving display spelling; ambiguous identities never resolve by choosing the first result. Opaque IDs decide authority. Identity displays reveal directional/invisible controls and distinguish origin. Terminal rendering treats control/escape sequences as inert visible text; it cannot execute remote commands or hyperlinks automatically. Encrypted search is confined to authorised locally decrypted indexes, protected and retained like their content. The service never claims plaintext search without keys.

The service enforces frame/ciphertext and visible-metadata bounds for encrypted rooms; authorised endpoints enforce plaintext text/grapheme limits after decryption. Signed bytes are never normalised after verification. Oversized or invalid decrypted content is rejected locally without allowing unbounded rendering or a response storm. A committed application event receives a durable rejected-delivery outcome and cursor progress under the state specification; it cannot trap reconnect at the same message. Cryptographic failure rolls back tentative MLS changes, while authenticated application-content rejection consumes its receive generation. Invalid membership transitions remain frozen.

Ignore removes matching recipient deliveries, notifications, preview requests and agent triggers before enqueueing, and filters that recipient's history/search. It does not erase shared history. Local mute changes presentation/notifications only. Room silence denies send publication; kick removes membership; ban also blocks readmission under the declared subject/operator policy. These effects carry scope, duration and moderator attribution. Enforcement logs and notices share bounded budgets.

7. Confidential direct conversations and private groups#

Use OpenMLS 0.9.1 for both modes, with distinct endpoints as group members, under the persistent conversation lifecycle. MLS supplies group key agreement; HRC still supplies identity authentication, delivery and policy. MLS supports two-client groups, and its architecture leaves application-specific behaviour to the surrounding system. RFC 9420 · RFC 9750

Each device or agent endpoint has independent keys and explicit enrolment. HRC identity and credential records bind endpoint, account/operator, permitted represented identity and current enrolment generation. Clients validate those bindings against accepted authentication authorities and visible device confirmations. Authentication-service compromise is a distinct threat. Retain the initial account identity anchor and its controller-authorised continuity chain; account recovery uses the enrolled owner-held key. The MLS runtime defines exact credential bytes; the local client guide defines explicit first-contact trust and continuity checks. The server sees routing, size, timing and required membership metadata; encryption does not promise metadata concealment.

The selected membership flow is: a home-ordered change authorises exact endpoint additions/removals; an eligible client prepares the MLS transition; the home serialises a single candidate from the expected epoch; clients validate the commit and policy before applying it. Pending membership changes block affected application sends. Conflicting candidates resynchronise. Welcome is released only after the winning commit is accepted. MLS requires a defined commit-conflict rule and careful tentative-state handling. RFC 9420 §14

A home delivery acknowledgement does not prove that every recipient validated the MLS transition. The state specification requires an eligible endpoint to durably verify and acknowledge the exact removal epoch before the home lifts its send barrier. Other endpoints verify before use. Invalid or inconsistent transitions suspend sending; an explicit fresh-group recovery has a new identity and current membership. Public handshakes let the service check exposed policy and signatures, but not the private confirmation value.

Removal, agent read-scope withdrawal and federation-member withdrawal suspend new ciphertext publication until the removal epoch is accepted. Recipients reject content against an obsolete membership policy. A paused agent with read permission removed also needs this barrier. If no authorised endpoint can complete the transition, the conversation remains unavailable for new sends. Already disclosed plaintext and old keys cannot be retracted. This service barrier does not constrain malicious recipients communicating outside HRC.

The accepted default for new or recovered devices is future encrypted messages only, in both direct conversations and private groups. New agents likewise receive no historical keys by default. Existing authorised devices retain their permitted local archives. Owner-key recovery replaces the account endpoint set and requires removal of old encrypted memberships; it does not restore old history automatically. Prior-history access is strictly optional and disabled by default. Any future archive-transfer or recovery mechanism requires deliberate, separately authorised disclosure and a defined recipient, history scope and retention policy; neither enrolment nor ordinary login enables it. No such mechanism or key-backup policy has yet been selected. MLS itself does not give a newly added device historical messages. RFC 9750 §§6.6–6.7

Client persistence must atomically retain outbound ciphertext and advanced crypto state before transmission; uncertain sends retry identical bytes, never reuse a nonce or recreate a message under an old state. The MLS runtime selects credential bytes, sender-ratchet bounds, erasure and update rules. The state specification selects the library, ciphersuite, public handshake profile, owner recovery key and zero old-epoch-secret retention. These contracts require their stated integration and recovery qualification. Suite Mail is an integration reference, not this lifecycle.

Agents receive no user private keys. A read grant for a private group requires its own visibly enrolled endpoint and the corresponding membership transition. External model disclosure needs a separate permitted destination and consent. Service-side content moderation is available only where the service can read content; an encrypted-room moderation agent is a visible authorised participant.

MLS membership exposes the group's messages for the epochs whose secrets an endpoint holds. Do not enrol an agent when its grant permits only selected messages or a narrower context within an epoch. Such access needs a separately authorised, encrypted disclosure of the selected context to that agent's own endpoint, or an explicit refusal until that disclosure contract exists. A server-side filter does not narrow cryptographic possession of an epoch key.

8. First federation profile#

Proposal: bilateral shared rooms, one home service, two independently administered HyperNets, no onward forwarding. An agreement binds both network/incarnation identities, home service/rooms, exact gateway endpoints and authentication keys, origin-attestation authority, remote account admission rules, moderator scopes, history/retention/storage, privacy/crypto mode, expiry and withdrawal procedure. Both administrators accept the same immutable agreement and each affected room explicitly enables it.

Transport arrangement: each gateway has a locally admitted source-side endpoint and a separately admitted application principal/companion in the destination network for the destination HRC service. The agreement binds these distinct identities; no foreign HyperNet membership is inferred. Destination owner/application consent and purpose-specific grants are required independently. Each direction has its own admissions and target map. A gateway stream authenticates the gateway, not every multiplexed remote account.

Original actor evidence therefore needs an HRC contract beyond today's SDK. Remote submission contains the exact agreement/revision, home room, origin account/endpoint, represented account and home-owned grant if delegated, original Action and authentication, origin endpoint-binding statement, a one-use home challenge and a fresh origin admission assertion. The agreed origin HRC authority attests which currently admitted transport endpoint made the request; the actor authenticates the immutable action with its enrolled HRC endpoint key. Pin the origin authority and endpoint binding through explicit agreement/enrolment. A payload account ID, gateway transport identity or old stream metadata alone proves none of this.

The home verifies gateway admission, agreement, origin binding, action authentication, challenge, destination restrictions and its own current grant/room policy before committing. An altered room, actor, represented account, content, grant or agreement invalidates the evidence. Replays resolve through home deduplication. Foreign event IDs retain origin; only the home assigns the canonical room sequence. Exchange of committed home events cannot create a second send effect or trigger onward federation.

The gateway's HRC enrolment permits only its designated federation operation family. It cannot submit an ordinary direct/independent actor request for an arbitrary account or bypass remote evidence checks by changing the envelope kind.

This profile explicitly trusts the accepted origin HRC attestor for source-side admission statements. It is not a portable HyperNet quorum-proof verifier. The federation runtime specifies the signed envelope, identity lifecycle propagation and bilateral setup. Real two-network qualification remains required before claiming supported remote admission.

Federation uses HyperNet's existing bounded freshness model, refined in the integration profile. The home challenge lasts at most five seconds end to end and binds the exact action; source evidence and credential expiry can shorten it. A source authority change can occur between assertion and home authorisation. Forwarding cannot restart the original lifetime. Local home-owned HRC pause/revoke remains strictly ordered because the receiving service owns it. A coordinated home withdrawal barrier states when that home has stopped; no timestamp proves instantaneous global revocation. The exact evidence schema, conservative clock conversion and real interoperability still require qualification.

On withdrawal, each side immediately stops its own new exchange and requests a durable home barrier. The home acknowledges the order after which it rejects that agreement, including queued effects, and suspends affected encrypted rooms for rekey. The UI distinguishes WithdrawalRequested from WithdrawnAtHome; a disconnected peer cannot be reported as globally stopped. Agreement expiry fails closed under the defined clock policy. The first-release acceptance rule must use the agreed effective barrier and declared freshness bound, not an unachievable instantaneous global observation.

9. Accepted pilot target and proposed work budgets#

The following stream allocation is accepted as the initial qualification target. It is not measured throughput or a supported-capacity claim. One companion supports at most 16 active incoming/outgoing streams combined. Allocation per home: eight interactive endpoint streams, two agent streams and two federation-direction streams; reserve two operator streams and two transition slots. Additional devices consume slots; multiplexed remote actors still consume independent application budgets. Other work budgets below remain proposed. Up to 32 room accounts and 64 encrypted endpoints per room are proposed; these membership limits do not imply 64 simultaneous transport connections.

The native load workflow also measures end-to-end recovery from the end of hostile work, including the availability of its HyperNet dependencies. Failure to restore authority or transport fails that whole workflow. It does not measure HRC-only recovery after healthy authority and transport; reports must distinguish these intervals. Message-exchange latency and scheduled-to-observed client completion remain separate measurements, with complete cohort coverage shown.

Per-queue limits are subordinate to the global byte ceiling; they are not preallocated independently. At most sixteen 512-KiB output queues account for 8 MiB of that ceiling. Crypto buffers, parsers, indexes, storage caches and process overhead also need explicit accounting against the measured RSS target. Service-wide cost rejection happens before fan-out/model work. E2EE recipient work needs its own endpoint budgets; a bounded server alone cannot protect clients from malicious MLS state growth.

Fresh HyperNet checks share one admission scheduler with at most four active exchanges and 32 tickets including active work. The service classifies verified operations: messages and mutations, cancellation, outcome resolution and session controls use the interactive class; view/history/search reads use the read class. Each class has at most three active exchanges and 24 total tickets, reserving one active slot and eight ticket places for the other class. A homogeneous workload therefore uses at most three exchanges, even when the fourth slot is idle. Eligible accounts alternate classes and take round-robin turns; one account's own requests retain FIFO order. An account has at most one active exchange and four tickets. New accounts join the back of the turn order rather than overtaking existing waiters.

Identity comes from the authenticated account, not a nickname, endpoint, relay IP or caller-supplied priority. Delegated requests also share their verified owner's active and ticket limits. A nonblocking Home acquisition and at most 25 ms of read-only lookup may establish that binding through the existing current identity and grant checks. Unknown, invalid or unavailable owner evidence stays grouped under the authenticated actor; it never charges a claimed owner's queue. This lookup grants no permission and reserves no business budget. Gateway requests before full remote actor verification are conservatively grouped by the verified transport principal; unclassified foreign actions use the read class. The source service still accounts for its authenticated initiating account.

Admission waits at most 1,000 ms, clipped by the original enclosing deadline. Release wakes eligible waiters; shutdown, cancellation and stream availability are checked at least every 25 ms and again before the exchange. Every admitted operation still obtains its own fresh action-bound authority check and passes the existing current identity, grant, room, clock and final-effect guards. Neither queue position nor a successful owner lookup is an authority lease.

The service serialises Home access through one FIFO with at most 32 tickets, including its single holder. Each acquisition waits at most 1,000 ms. For local and federated operations after a fresh transport check, the original enclosing deadline and receipt lifetime can only shorten this wait. Release wakes the next waiter. Wait intervals are capped at 25 ms between shutdown, cancellation, stream validity and current-authority checks; these checks repeat before effects. The signed clock is sampled after acquisition. Existing domain checks and final commit guards remain authoritative; waiting neither refreshes authority nor repeats an operation. Handshake and other blocking Home users join the same bounded queue. Nonblocking screening and maintenance cannot overtake queued work. Saturation or wait-budget exhaustion returns OperationBusy; poison and expired or invalid authority fail closed. Queued tickets contain no additional action payload copies.

Message exchange latency starts when an already encoded message is written to an established authenticated stream and ends at complete committed-acknowledgement payload receipt. The sample is accepted only after exact response verification. Connection setup, client queueing, local persistence, encoding/decoding and UI time are separate measurements. Scheduled-offer-to-observed-commit delay remains usability evidence, not this latency metric. Throughput, missing acknowledgements and recovery remain explicit gates; a fast subset cannot qualify the offered workload.

Saturation returns bounded RateLimited or Overloaded, or closes only the affected stream. Never send automatic replies to errors/replies. No model call belongs in the admission path. Pre-HRC connection attacks and link saturation still require HyperNet/host controls. Qualification must include malformed frames, Unicode extremes, churn, joins, slow readers, costly searches, federation replay, agent loops and notification storms. Failed targets require smaller published limits or design changes, not relabelling a pass.

10. Error boundary#

Stable HRC categories are InvalidInput, Denied, Expired, Conflict, Unavailable, UnsupportedVersion, UnsupportedFeature, RateLimited, Overloaded and ResynchronisationRequired. Detail codes describe public recovery actions, not keys, raw database errors or sensitive existence. Errors bind the operation ID when authenticated. Retry hints are finite, capped and advisory. The version-2 companion distinguishes fresh certified denied from unavailable, expired and notActive. Map only validated current results to their HRC transport detail; a certified transport denial is not itself an HRC grant revocation. Generic preparation refusal or EOF remains transport unavailability/unknown outcome and never proves that no HRC event committed. The integration profile defines the exact source boundary and lifetime.

11. Worked interaction traces#

12. Ownership and acceptance#

The runtime documents now select signed wire objects, credential bytes, clock recovery, encrypted-state transactions, MLS parameters and federation evidence. The HRC Rust adapter and smallest local conversation have representative real HyperNet integration evidence. That evidence does not qualify the complete client, confidential-conversation or federation workflows. Complete those workflows, measure the accepted pilot and retention boundaries, and resolve any remaining proposed budget differences before release. The contract map identifies the upstream source boundary. Passing source or domain checks alone does not establish the release acceptance scenarios above.