Mandate schema
Specification versionv0.1.1JSON Schema of a mandate and its rules.
SHA-256 6b1452c1…c7b7 ShowHide
6b1452c1070780ce841d0158116bf4cf2fa08a41e2fc966ac359636ddb72c7b7Implement the Home-Mandate Specification
Everything you need to build a home guard, an agent integration or a validator – and to show that it conforms.
Who talks to whom
An agent never talks to a device directly. It sends its request to the implementation, which decides with the household’s mandate and only then passes a command on to the smart-home platform. The specification defines the solid lines; how the dashed ones work is up to the implementation.
Read section 1.1 of the specAgentan assistant, a script, …
request: resource + actione.g. MCP · HTTPS · OAuth 2.1
Implementation
PEPthe home guard: receives requests, enforces decisions
AuthZEN request(section 6)
allow / ask / deny
PDPevaluation rule
entries(section 9)
Audit log
command via the platform’s API
Smart-home platforme.g. Home Assistant, Matter
on ask: approval(section 11.1)
sets the mandate(section 3)
Humanthe household
Data model at a glance
A mandate belongs to one agent and holds rules. Each rule names resources (a device, a category or an area), actions and a decision. Rule order never matters: of all matching rules, the strictest decision wins.
Read section 3 of the spec| Field | Type |
|---|---|
| type | "https://home-mandate.org/mandate/v0" |
| id | string |
| name | string? |
| principal | string |
| agent | {client_id, display_name} |
| enforce | false? |
| rules | Rule[] |
| default | "deny" |
| approval | Approval |
| limits | {max_actions_per_hour} |
| valid_from | date-time |
| expires | date-time? |
| issuer | uri? |
| audience | uri? |
| version | integer? |
| created_by | string |
| created_at | date-time |
A mandate holds 0 to 200 rules.
| Field | Type |
|---|---|
| id | string |
| resource | Resource |
| actions | string[] |
| decision | allow|ask|deny |
| note | string? |
| conditions | Conditions? |
| constraints | Constraints? |
| approval | Approval? |
| allow_critical | true? |
? marks an optional field. Generated from the JSON Schema of the mandate.
Conformance classes
An implementation conforms to one or more classes. It conforms to a class of a version if it passes all cases of that class.
- evaluator basis
Evaluator
Validates mandates, computes their digests and evaluates requests (sections 3 and 4).
478 test cases
- selection optional
Selection
Selects the mandate to evaluate among several stored ones (section 4.3).
29 test cases
- signatures optional
Signatures
Verifies signed mandates and the succession of mandate versions (sections 3.5 and 7).
58 test cases
- audit optional
Audit
Verifies the hash chain of audit logs and computes entry digests (section 9.4).
217 test cases
- audit-anchored optional
Anchored audit
Additionally verifies the signed checkpoints of a log (section 9.5).
11 test cases
- pdp optional
PDP
Answers AuthZEN requests from its own mandate store and resource directory (sections 4.3 and 6).
valid evaluator and selection cases, over HTTP
Evaluator is the basis: anything that claims to evaluate mandates conforms to it. The obligations of the guard (section 11) cannot be tested from outside yet; an implementation states how it meets them.
Install and test
The test tool mandate-conformance contains the cases of its version and plays them against your implementation, whatever its language: through a small harness that reads and writes one JSON line per request, or over HTTP for a PDP. Its report names the version, the classes and the manifest.
Section 10 of the spec describes both ways.
Install the test tool (needs Go)
go install github.com/home-mandate/spec/cmd/mandate-conformance@v0.1.1Test through your harness
mandate-conformance -report report.json -exec ./your-harnessTest a PDP over HTTP
mandate-conformance -report report.json -authzen https://pdp.test -control https://pdp.test/test/stateDownloads
Verify files with the SHA-256 checksum. Each format is also named by an address of its own: mandate, audit log entry and audit checkpoint.
Vocabulary
Specification versionv0.1.113 device categories, their actions and which actions are critical.
SHA-256 954b4dfc…3222 ShowHide
954b4dfc9ccec520c4d2c90dc55a74e8eec67790a643c1c91719904d338b3222Audit schema
Specification versionv0.1.1JSON Schema of an audit log entry.
SHA-256 0571f424…0ed2 ShowHide
0571f424d81fbd74c5ca82a5c2489101d526fd4bcafec11074eabfc1e8390ed2