HPPR Repository Admin and Join Conventions

Tags: repo, workflow

© R.A.Sol

This spec defines repository-service operational conventions: repository bootstrap, request/reply workflow, join flows, and ring0-proxy.

Content route conventions live in 100-CONTENT-ROUTES.md. Packet link and chunk conventions live in 070-LINKS-AND-CHUNKS.md.

Bootstrap

A repository needs only the canonical packet families below to operate. Do not bootstrap convenience scaffolding or workflow placeholders.

Bootstrap sequence:

  1. Load or generate repo-owned signing secret in local operational storage.
  2. Derive repo verifier from that local signing secret.
  3. Write //repo/admin/identity//root/| — self-signed Seal carrying Repo-Name.
  4. Write Ring1 ring0 auth config at: //repo/admin/ring1//ring0/auth/| — signed by repo verifier; Ring1-Name: ring0
  5. Write Ring1 ring0 members at: //repo/admin/ring1//ring0/members/|/seal/<repo-verifier> — at least one initial Member verifier (see Initial Token below)
  6. Write Ring1 ring0 policy at: //repo/admin/ring1//ring0/policy/| — signed by repo verifier; ACL-Rule headers defining ring0 access
  7. Write Ring1 anyone auth config at: //repo/admin/ring1//anyone/auth/| — signed by repo verifier; Ring1-Name: anyone
  8. Write Ring1 anyone policy at: //repo/admin/ring1//anyone/policy/| — signed by repo verifier; ACL-Rule headers for public/unauthenticated access

Do not bootstrap:

Default anyone Policy

ACL-Rule: .w. //repo/admin/request//join/
ACL-Rule: r.l //u/

Initial ring0 Token

The default initial ring0 member derives from token init:

secret = "init/ring0/<repo-verifier>"

signing_secret = derive_secret_from_text(secret)

Implementations MAY accept an explicit bootstrap token at repository creation, for example hpprd --default-password <password> or HPPRD_DEFAULT_PASSWORD. Packaged services that listen on public interfaces MUST use a random explicit bootstrap token instead of init.

Rotate the initial member to durable operator-controlled signing material after first connection.

Request/Reply Convention

Administrative request flows use:

<kind> names the workflow. Join flows use join.

Reply packets are expected to include:

Clients use Request-Status for state. +Link gives exact request linkage.

Workflow packets are ordinary stored packets subject to policy. They are not auth or policy state.

Joining a Repository

Standard Ring1 join flow uses <kind> = join:

  1. user watches reply path: //repo/admin/request//join/<name>/reply/|
  2. user writes request to: //repo/admin/request//join/<name>/|
  3. admin approves or denies in reply packet
  4. if approved, admin creates Ring1 auth config, members, and policy packets
  5. user derives signing material and reconnects

Provisional Access

An anyone request gets provisional read/list access to its matching reply path:

//repo/admin/request//join/<name>/reply/|

<name> must match first segment from request Key.

This is repository-service runtime code, not a packetized permission.

Joining a Group

Ring2 join flow uses <kind> = join:

  1. user watches reply path: //<group>/admin/request//join/<requester-verifier>/reply/|
  2. user writes request to: //<group>/admin/request//join/|/seal/<requester-verifier>
  3. admin approves or denies in reply packet

A common client flow derives <requester-verifier> locally from <group>/<username>/<password> as defined in 052-RING2.md. This works before contacting any repo. The password remains local to the client.

Recommended non-member join ACLs:

ACL-Rule: .w. //<group>/admin/request//join/|/seal/
ACL-Rule: r.l //<group>/admin/request//join/

Request headers:

Ring0-Proxy Convention

Ring1 may request a ring0-mediated action.

Request path:

//repo/admin/ring1//<ring1-name>/🖧<COMMAND>/|

Reply path:

//repo/admin/ring1//<ring1-name>/🖧<COMMAND>/reply/|

Supported commands:

🖧GET is excluded. Use 🖧HEADERS to obtain hash, then fetch blob by hash.