logicsrc/docs/opencontext/permissions.md

Permissions and scopes

Authorization precedes relevance. An object a consumer may not read is removed before freshness, ranking, or compilation ever sees it — so it cannot reach a ranker, a prompt, a bundle, or even an explanation.

Deny overrides allow, everywhere and unconditionally.

Scope is opt-in

A role with no include list sees nothing. There is no "everything except" mode, because a scope defined by subtraction silently grows every time someone adds context.

roles:
  support:
    include:
      - mission
      - policies.*
      - procedures.*

Patterns

Wildcards always match whole dotted segments, never substrings.

Pattern	Matches	Does not match
*	everything	—
mission	mission	mission.statement
products.*	products, products.enterprise, products.enterprise.pricing	products-internal
customers.*.churn-risk	customers.acme.churn-risk	customers.acme.eu.churn-risk

The asymmetry between the last two is deliberate. A trailing wildcard is how people express "this subtree". An interior wildcard is how they express "this field, whichever record it belongs to". Collapsing them into one rule would make the second silently grant the first.

products-internal never matching products.* is the property that matters most: substring matching here would be an access-control bug.

Evaluation order

For each object, in order — the first failure is what gets reported:

1. Explicit deny. permissions.deny names the consumer or one of its roles → denied.
2. Scope exclusion. A role exclude pattern matches → denied.
3. Object read grant. permissions.read exists and does not name the consumer → denied.
4. Scope inclusion. No include pattern matches → not in scope.
5. Classification ceiling. Object classification exceeds the role's → denied.

# denied to support, even though policies.* includes it
id: policies.internal.margins
classification: confidential

roles:
  support:
    include: [policies.*]
    exclude: [policies.internal.*]

Classification

public < internal < confidential < restricted

max_classification bounds a role. An object above the ceiling is denied even when an include pattern matches it. The default is internal, so confidential and restricted context requires an explicit grant.

roles:
  support:
    include: [docs.*]
    max_classification: internal      # denied docs.litigation
  legal:
    include: [docs.*]
    max_classification: restricted    # allowed

Ceilings and inheritance

Two rules, because the two situations mean different things.

Within an inheritance chain, the most specific declaration wins. A role that says max_classification: confidential means it, even when it inherits a base role capped at internal.

roles:
  everyone:
    include: [mission]
    max_classification: internal
  finance:
    inherits: [everyone]
    include: [policies.*]
    max_classification: confidential   # finance really does get confidential

The alternative — taking the minimum across the chain — makes a single ceiling on a shared everyone role silently cap every role in the repository, so a finance role explicitly granted confidential quietly receives nothing above internal. That is a denial nobody can see in the manifest.

Across independently requested roles, the lowest wins. Holding two roles at once must never grant more than either does alone.

opencontext resolve --role support --role finance    # capped at the lower of the two

Both are safe under review, because a ceiling is written by whoever edits the manifest — never by the context being read.

Inheritance

roles:
  everyone:
    include: [mission, glossary]
  support:
    inherits: [everyone]
    include: [policies.*]
    exclude: [policies.internal.*]
  intern:
    inherits: [support]
    exclude: [customers.*]

Includes, excludes, permissions, and redactions all union. An inherited exclusion follows the child, so intern cannot see policies.internal.* either. Cycles are a validation error.

Object-level permissions

id: policies.payroll
classification: confidential
permissions:
  read: [finance]
  write: [finance-admin]
  deny: [contractor]

read narrows a role that would otherwise include the object — useful for one sensitive item inside an otherwise open collection. deny overrides every grant, including read: ["*"].

Principals are matched against the consumer id and its roles, so a grant can name a specific agent or a whole role. * and a trailing .* are supported.

A name here that is neither a defined role nor a defined agent is reported:

⚠ invalid-permission: policies.payroll grants access to "finanace", which is neither
  a defined role nor a defined agent.
    → Define roles.finanace, or correct the name — a typo here silently denies access.

Reads never imply writes

permissions:
  read: [support]     # support can read
  write: [support]    # and only this line lets support write

An agent that can read context does not thereby gain the ability to change it. See writes below.

Redaction

Redaction runs after authorization: the consumer is entitled to the object and still does not receive every field.

roles:
  support:
    include: [customers.*]
    max_classification: confidential
    redact:
      - path: ssn
        mode: remove
        reason: PII, never needed to resolve a ticket
      - path: payment.card
        mode: mask
        replacement: "[REDACTED]"
      - path: contacts[*].email
        mode: hash

Mode	Effect
remove	Deletes the key. Default.
mask	Replaces the value with replacement.
hash	Replaces it with a sha256 digest, so equality stays testable without disclosure — two records with the same email still match, and neither email is readable.

Path syntax

Paths address the object's content.

ssn                  a top-level field
payment.card         nested
contacts[*].email    every element of an array
contacts[0].email    one element
contacts.email       a wildcard-free path applied to an array means every element
customer.ssn         a leading segment naming the object's type or id is optional

That last rule is what makes a repository-wide rule like customer.ssn behave the way an author expects on a customer object whose content has ssn.

Rules from the manifest, the role, and the object all apply — they union, and the union is applied.

The bundle reports that redaction happened, never what was redacted:

{
  "id": "customers.acme",
  "content": { "name": "ACME Inc.", "payment": { "card": "[REDACTED]" } },
  "redacted": ["ssn", "payment.card", "contacts[*].email"]
}

Redaction paths address structured content. Prose content has no structure to address, so a structured rule against a Markdown body matches nothing — do not rely on it for PII in free text.

Permissions as capabilities

roles:
  support:
    permissions: [customer.read, ticket.read, ticket.write]

These are transported and scoped by OpenContext, and carried through into the bundle for your runtime to enforce. OpenContext does not itself perform your application's actions.

Writes

Core resolution is read-only. Mutation is a deliberately narrow exception:

opencontext add policies.returns --type policy --content "Within 14 days."
opencontext supersede policies.refunds --content "Within 60 days."

Three rules:

1. Writes are never implicit. permissions.write must name the consumer.
2. Validate before persisting. Authorization and schema are checked first, so a malformed or unauthorized write never reaches disk.
3. Promotion is explicit. Assigning canonical or approved authority requires --promote (CLI) or allowPromotion: true (SDK). An agent cannot launder its own observation into policy.

✗ Refusing to write policies.new with authority "canonical". Promotion to canonical or
  approved is an explicit governance act — pass --promote if that is what you mean.

Adding an object that already exists is refused: durable context is superseded, never silently overwritten.

Denied reads look like missing objects

opencontext get policies.payroll --role support

No context object "policies.payroll" is available to this consumer.

A denied read and a nonexistent object are reported identically, so probing for ids reveals nothing about what exists. list and search apply the same filter before returning any metadata — a search that leaked titles of restricted documents would defeat the scoping model entirely.

Secrets

Secrets must not live in context. A context repository is usually far more widely readable than the systems it describes.

validate fails on committed credentials:

✗ secret-detected: policies.deploy appears to contain a AWS access key id.
    → Remove it and reference a secret manager instead.

Reference an external provider instead, and let your runtime resolve it at use time.