Compartments API¶
compartments ¶
Compartments: a code-enforced store for masked information.
A :class:Keeper is the only way in. It enforces grants, encrypts values with
an injected :class:Cipher, audits every attempt, and releases a value toward
the owner only through a single-use :class:ReleaseTicket.
Keeper ¶
Keeper(
db_path: str | Path,
*,
cipher_for: Callable[[str], Cipher],
is_owner_turn: Callable[[str], Awaitable[bool]],
clock: Callable[[], datetime] = _utc_now,
ticket_ttl_s: float = 300,
)
Grants, encrypted records, an audit trail and single-use release tickets.
Every failure raises. Every refusal is audited in the same transaction that decides it, before the error reaches the caller. Logs name records and actors; values, labels and ticket ids never reach them. Assistant and compartment names must fit the identifier grammar, and a record id the shape the keeper issues; anything else is refused without being repeated anywhere.
The keeper takes every actor name on trust, and does not verify
approved_by or confirmed_by. Actor names must come from the runtime,
and grant, revoke, redeem and audit must never be model tools.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
db_path
|
str | Path
|
The SQLite file. |
required |
cipher_for
|
Callable[[str], Cipher]
|
Returns the cipher for a compartment. Required: there is no plaintext default. |
required |
is_owner_turn
|
Callable[[str], Awaitable[bool]]
|
Says whether a turn id is the owner's turn in progress. It
must refuse anything else: the keeper does not check freshness, so a
callback that accepts any past owner message accepts a stale turn.
Anything but a literal |
required |
clock
|
Callable[[], datetime]
|
Returns the current time, timezone-aware. |
_utc_now
|
ticket_ttl_s
|
float
|
How long a release ticket works. |
300
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
ValueError
|
If |
Source code in orqest/compartments/keeper.py
grant
async
¶
Give assistant access to compartment, replacing any earlier grant.
A replacement without read access spends the assistant's open tickets on this compartment.
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
If |
ValueError
|
If |
Source code in orqest/compartments/keeper.py
revoke
async
¶
Remove a grant and spend the assistant's open tickets on this compartment.
Effective for the next call, and a later grant does not revive the tickets. No grant to remove is not an error.
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
If a name is malformed. |
Source code in orqest/compartments/keeper.py
grants_for
async
¶
The grants assistant holds, by compartment name.
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
If |
Source code in orqest/compartments/keeper.py
write
async
¶
Store a new record. Needs a write grant.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
assistant
|
str
|
The writer. |
required |
compartment
|
str
|
Where to store it. |
required |
label
|
str
|
A plaintext name, visible without any grant. A label holding one of the value's matchable strings is refused. |
required |
value
|
dict[str, Any]
|
Strict-JSON data with string keys, encrypted before it is stored. |
required |
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
Without a write grant, for a malformed name, or if the label holds a string from the value. |
TypeError
|
If |
ValueError
|
If |
RuntimeError
|
If the cipher fails or does not encrypt. |
Source code in orqest/compartments/keeper.py
read
async
¶
read(
assistant: str,
compartment: str,
*,
record_id: str | None = None,
limit: int = 20,
) -> list[Record]
Working access: an assistant's own use of a compartment, newest first.
One corrupt record fails the whole read. Each record returned gets its own audit event.
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
Without a read grant, or for a malformed name. |
KeyError
|
If |
CompartmentCorrupt
|
If a record cannot be decrypted. |
ValueError
|
If |
Source code in orqest/compartments/keeper.py
pointers
async
¶
Labels only, newest first. Needs no grant, and is not audited.
There is no actor to name and no value is touched: knowing that a compartment holds something is allowed by design. Only a refusal is audited.
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
If |
CompartmentCorrupt
|
If a stored timestamp cannot be read. Nothing else is checked here: an altered label shows only on a read through the cipher. |
Source code in orqest/compartments/keeper.py
delete
async
¶
Remove a record for real. Needs a write grant on its compartment.
Spends any open ticket on the record, overwrites the freed space
(secure_delete) and truncates the write-ahead log, so neither the label
nor the ciphertext stays on disk. The audit trail keeps the record's id.
Another connection reading the file can keep the log from being truncated.
The record is gone and this still returns, but its bytes stay in the log
until the next truncating checkpoint: a later delete (one that finds no
such record included), the next write, the next keeper opened on the file,
or the last connection closing. An ordinary checkpoint does not remove them.
The audit trail says the purge is pending, and a warning names the record.
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
Without a write grant, or for a malformed name. |
KeyError
|
If there is no such record. |
Source code in orqest/compartments/keeper.py
prepare_release
async
¶
prepare_release(
requester: str,
compartment: str,
record_id: str,
*,
owner_turn_id: str,
) -> ReleaseTicket
Prepare a release to the owner. No value is touched here.
The keeper only stores owner_turn_id and asks is_owner_turn about it.
It does not check freshness: refusing anything but the turn in progress is
the callback's job, and the caller must take the id from the triggering
message, never from a model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
requester
|
str
|
The assistant asking. Needs a read grant. |
required |
compartment
|
str
|
The record's compartment. |
required |
record_id
|
str
|
The record. |
required |
owner_turn_id
|
str
|
The turn that asked; |
required |
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
Without a read grant, for a malformed name, or if this is not an owner turn. |
KeyError
|
If the record is not in this compartment. |
Source code in orqest/compartments/keeper.py
refuse_release
async
¶
Audit a release refused before :meth:prepare_release: no owner message at all.
Records the attempt and does nothing else: no ticket, no grant check, no error. A malformed or unknown name is blanked as in any other refusal, and the reason is the keeper's own, so nothing a model typed reaches the audit or logs.
Source code in orqest/compartments/keeper.py
redeem
async
¶
Release a record. The caller must send it to the screen, never to a model.
The application's own authenticated endpoint returns the value in its response,
and nowhere else. It must never go into a view, artifact, state or message: all
of them persist, and render_view serves a view or an artifact's snapshot with
no ticket and no passkey. Orqest has no release event, so this is on the caller.
The ticket id is a bearer credential and confirmed_by is taken on trust:
the keeper verifies neither who holds the id nor who confirmed. The
application must verify the owner first, and call this only from its own
verified channel. Never expose this as a model tool.
A release spends the ticket in the same transaction as its audit event, so a
crash after the commit loses that one release. A refusal for a blank
confirmation or a corrupt record leaves the ticket usable until it expires.
revoke, a grant without read access and delete also spend tickets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ticket_id
|
str
|
From :meth: |
required |
confirmed_by
|
str
|
Who confirmed, as the channel verified it. |
required |
Raises:
| Type | Description |
|---|---|
TicketInvalid
|
If the ticket is unknown, spent or expired, the confirmation is blank, or the requester's grant is gone. |
CompartmentCorrupt
|
If the record or ticket cannot be read intact. |
Source code in orqest/compartments/keeper.py
leak_check
async
¶
Labels whose stored strings appear in text.
Looks only in compartments assistant can read, at string values and
dict keys of six characters or more. Both sides are compared in NFKC form,
casefolded, with runs of whitespace collapsed. Each stored string must
appear whole: a fragment of a longer value passes, as do paraphrases and
numbers. A short common value also hits inside a longer word, so active
refuses inactive. A hit is audited against its record. A corrupt record
raises rather than passing the text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
assistant
|
str
|
Whose compartments to look in. |
required |
text
|
str
|
The text to check. |
required |
match_keys
|
bool
|
Whether a record's dict keys count as stored strings. Leave
this on for anything crossing to someone else. Off suits a text full
of structural words, where a record's |
True
|
Raises:
| Type | Description |
|---|---|
CompartmentDenied
|
If |
CompartmentCorrupt
|
If a record cannot be decrypted. |
Source code in orqest/compartments/keeper.py
audit
async
¶
Audited attempts, newest first, optionally for one compartment.
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in orqest/compartments/keeper.py
AccessEvent ¶
One audited attempt, allowed or denied.
Attributes:
| Name | Type | Description |
|---|---|---|
at |
datetime
|
When it happened. |
actor |
str | None
|
Who attempted it, as the caller named them. For |
action |
str
|
|
compartment |
str | None
|
The compartment. |
record_id |
str | None
|
The record, when the attempt concerned one that exists or one named on the keeper's own ticket. |
allowed |
bool
|
Whether it went ahead. A |
reason |
str
|
Why, in the keeper's own words. Never contains a value. |
Cipher ¶
Encrypts one compartment's values, and must be authenticated.
decrypt must raise on a wrong key or altered bytes
(cryptography.fernet.Fernet fits as it is). Without that, only the JSON
envelope stands between damaged data and a garbage value, and it can be forged.
Give each compartment its own key.
encrypt ¶
CompartmentCorrupt ¶
A stored record cannot be decrypted (wrong key or altered data).
Names the record and never carries any of its content.
CompartmentDenied ¶
The actor may not do this. The attempt has been audited.
Grant ¶
Permission for one assistant to use one compartment.
Attributes:
| Name | Type | Description |
|---|---|---|
assistant |
str
|
The assistant holding the grant. |
compartment |
str
|
The compartment it covers. |
access |
Access
|
|
approved_by |
str
|
Who approved it. |
at |
datetime
|
When it was granted. |
Pointer ¶
What may be known about a record without any access to it.
Attributes:
| Name | Type | Description |
|---|---|---|
record_id |
str
|
The record's id. |
compartment |
str
|
Its compartment. |
label |
str
|
A plaintext name. Labels must not contain the secret. |
created_at |
datetime
|
When it was written. |
created_by |
str
|
The assistant that wrote it. |
Record ¶
A decrypted record.
value is left out of repr and str, so logging a record or
showing one in a traceback does not reveal it. Dumping the model does.
Attributes:
| Name | Type | Description |
|---|---|---|
pointer |
Pointer
|
The record's pointer. |
value |
dict[str, Any]
|
The decrypted value. |
ReleaseTicket ¶
A single-use, time-limited permission to release one record to the owner.
ticket_id is left out of repr and str: it is a bearer credential.
Attributes:
| Name | Type | Description |
|---|---|---|
ticket_id |
str
|
The credential to pass to |
compartment |
str
|
The record's compartment. |
record_id |
str
|
The record to release. |
requester |
str
|
The assistant that prepared the release. |
owner_turn_id |
str
|
The owner turn it was prepared in. |
expires_at |
datetime
|
The moment the ticket stops working. |
TicketInvalid ¶
A release ticket cannot be redeemed. The attempt has been audited.