Skip to main content
Concept · access

Use when

You share part of a project with a client, an agent or a key, or you need to know what a limited credential can read.

Looking for something else?

A group of Files (card Collection). Who has access, what their agents may do and what they did (card Brain). Which credential you hold (card Credential).

​
For

A View names part of a project: collections and single Files, Shapes, and the entity and relationship types to show. A person, an API key or an agent that is limited to a View reads only that part and can never write. Each read leaves a read receipt. Everyone else reads the whole project as their role allows. The limit belongs to the person, key or agent, and not to a URL. You publish a View as numbered versions. A limit either follows the newest version or stays on one version you pinned. A Brain gives a View a name, agents and a list of who has access (card brain). Use a View alone when the person needs only the limit.

​
Use when

  • A client, an agent or a key must read some Files and entities, and nothing else.
  • You must tell the person exactly what a limited credential can read.
  • A limited credential reads less than the person expects.

​
Not this

  • A group of Files you extract from or search together: use a collection (card Collection).
  • Naming the agents, the instructions and the people who have access to one View: use a Brain (card Brain).
  • Finding out which credential you hold: use card Credential.

​
Rules

  1. view.1 You publish a View as numbered versions, and a limit reads only published versions. Your job: an edit to the draft with penumbra context slice update changes nothing for anyone until you run penumbra context slice publish. A new definition replaces the old one in full, so repeat every collection, Shape and type that must stay.
  2. view.2 A View limits Files only when it names a collection or a File. Your job: name at least one collection or File. A View with neither shows every File in the project, even when it limits types. Penumbra publishes such a View without a warning. penumbra context slice show prints its scope as “the whole project” only when the View names nothing. A View that names only types or Shapes prints those, and still shows every File.
  3. view.3 Collections are read when someone reads, and types are fixed when you publish. Your job: a File that joins an included collection appears at once, and a File that leaves it disappears at once (card rule collection.9). A type that a Shape gains later stays hidden until you publish the View again (problem view-needs-republish).
  4. view.4 A limit follows the newest published version unless you pin it. Your job: pass --version <number|id> to penumbra access attach, penumbra keys create or penumbra kits connections create only when the person wants the content frozen. A pinned limit ignores later publishes.
  5. view.5 The graph mode decides which entities a limited credential sees. Your job: leave the default backed, which shows an entity with no File citations or with at least one citation inside the View. Choose types only when the person accepts that an entity of those types may repeat text from a File outside the View. Both modes hide citations to Files outside the View.
  6. view.6 A limited credential can only read. Enforced: attaching a View to a key or agent with a write scope is refused with view_requires_read_only. Giving a limited credential a write scope, or raising a limited login above viewer, is refused with view_bounded_read_only. Your job: remove the limit first only when the person means to widen access (rule view.10).
  7. view.7 Only a client can be limited. Enforced: a member of the organization is refused with view_requires_client, and a project editor or admin is refused with view_requires_viewer. A client is a project viewer who belongs to no organization.
  8. view.8 Creating, editing and publishing a View take more than read access. Enforced: a person below editor is refused with view_change_requires_editor. A key or agent without the scope context.view.write is refused with view_change_requires_scope. A publish by a key or agent also waits for approval (card approval).
  9. view.9 Attaching, removing, retiring and reading read receipts take a signed-in person who manages access. Enforced: a key or agent is refused with human_session_required, and any other person with permission_denied. Managers are organization owners and admins, and project owners and admins who belong to the organization.
  10. view.10 Removing a limit widens access. Enforced: penumbra access remove returns the key, agent or login to whole-project reads at once, and it asks to confirm. Without a terminal it needs --yes and otherwise exits with confirmation_required. Your job: to end someone’s access, use penumbra brains remove-door or penumbra keys revoke, never penumbra access remove.
  11. view.11 Retiring a View cuts off everyone limited to it. Enforced: penumbra context slice retire asks to confirm. After it, every read by a limited credential fails with view_unavailable until you publish the View again. Publishing a retired View restores it.
  12. view.12 A publish is refused when a type name inside the View is also the name of a type outside it. Enforced: the refusal is semantic_scope_ambiguous, and its message names the labels. Your job: rename one of the types in its Shape, or choose the Shapes and types so that the names differ.
  13. view.13 Some reads are not part of any View. Enforced: a limited credential is refused with view_operation_unavailable for Graph workspaces, extraction runs, Graph history, the project ontology, Shape authoring and ad hoc Context. Your job: do that work with an unlimited credential.
  14. view.14 When a View limits types, a limited credential reads only the Shapes the View names. Your job: name the Shape, and not only its types, when the client’s agent must read it. A View that names types without a Shape makes no Shape readable. A readable Shape shows its whole definition, including types the View leaves out.
  15. view.15 An item outside the View reads as missing. Your job: never tell the person that a File or entity does not exist when a limited credential could not find it (problem hidden-reads-as-missing).
  16. view.16 Each read by a limited credential leaves a read receipt. Your job: use penumbra access receipts <limit-id> to show what was read. Take <limit-id> from the id that penumbra access list prints under “Limited to a View”. A receipt holds the operation, the interface that made the read (the CLI prints it as door), the version and the count returned. It does not hold the question. Clients cannot read their own read receipts.

​
Failure signs

​
Doors

No CLI command invites a client. Ask the person to invite the client in the App under Give access, and choose Invite a client.

​
The CLI word

The CLI calls a View a Context Slice. The usage lines of penumbra access receipts and penumbra access remove call the id of a limit <boundary-id>. penumbra access list prints it under “Limited to a View”.

​
HTTP reference

​
Keep going

Collection · Brain · Credential · Share part of a project with a View · A View does not follow a Shape change until it is published again · Something outside the View reads as not found · You do not know what your credential can see