Skip to content

Spec: a trust model page #418

Open
Open

Description

@cuibonobo

Problem

What a stack's data is protected from, and what it isn't, is spread across the spec or not written down at all:

  • access-control.md § The write bit: a recoverability trust model says direct adapter access is full trust.
  • wire-format.md § Identity is trusted on transport says a client's belief about whose stack it's talking to rests on TLS and the URL.
  • identity.md says key custody is not this library's job.
  • Nothing says that whoever runs the server can read every Record, or that core does not encrypt at rest.

A group choosing a host can't see the trade it's making without reading the whole spec. Access control is detailed, but it defends against apps, visitors and members, not against the host.

Decision

A new docs/spec/trust-model.md, listed in the table in docs/spec.md. It states the system as it is and links to the sections that carry each rule:

  • The host can read everything. Core does not encrypt. That includes metadata: types, timestamps, associations, permissions and authorship. Only holding the host protects them.
  • Direct adapter access is full trust, outside every Stack invariant.
  • Discovery identity is trusted on transport, and what ownerEntityId does and doesn't add.
  • What access control defends against (contained apps, visitors, members reaching too far) and what it doesn't (the host, anyone with the file, a seized device).
  • A table of deployment shapes: who can read the data, and what loss looks like.
Shape Who can read the data What loss looks like
Local only The owner The device dies
Home server + relay The owner (the relay sees traffic metadata) The house or the storage fails
Hosted The owner and the host The host disappears

Only facts that stay true go in. Limitations with a planned fix (moving hosts, key rotation) are described in their own issues and written into the spec when they land.

Actions

  • docs/spec/trust-model.md as above.
  • A row for it in the table in docs/spec.md.
  • Link it from the sections it summarizes where that helps a reader; pnpm run check:refs must pass.
  • No changeset: docs only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions