1
0
Fork 0

feat(okf): the mapping class gets one expressible form, typed and allowlisted

OKF v0.2 writes its whole trust and provenance layer as mappings, and T2 gave
the mapping class no expressible form. A consumer measured 0 of 53 upstream
concepts through the gate on 0.3.4, 1.0.0 and 1.1.0. That was a contract
collision, not a calibration setting: SPEC.md @ 62432a09 uses flow mappings in
its own 5.1/5.2 examples, and 11 carries a hard MUST for consumers ("MUST treat
a bare `verified` mapping as a one-element list") that presupposes they parse.

Admitted: a flow mapping, as a value or as a block-list item, whose every key is
on a nine-name allowlist and whose every leaf is a plain scalar run through the
unchanged dangerous-value and mapping-construct predicates. The form is safe
because the allowlist inspects every key -- the blanket refusal was the
enforcement, not the point.

Refused, each on its own rule and ground-truthed against PyYAML 6.0.3: a key off
the allowlist, a nested collection, a quoted leaf, a duplicate key, an empty or
unclosed mapping, trailing junk, and {a:b} (which PyYAML reads as the KEY a:b).
A refused mapping still raises rather than degrading into a string, so the 1.1.0
type-confusion defect is not reopened, and the block, dotted and inline-colon
routes still raise.

`resource` is deliberately off the allowlist though SPEC.md 5.1 names it inside
a `sources` entry: it is a pointer rather than a label and the only key T3
exists for, so admitting it would let `executor: { resource: skills/run.md }`
carry an executable-code pointer through in typed clothes -- the door-C route
closed in 1.1.0. It costs nothing today, because the conformant carrier for
sources[].resource is a block sequence of block mappings, which stays refused.

Mapping leaves are scanned like every other frontmatter value (T1). Coverage
matrix 130/130 (new row: the off-allowlist key). No exported surface, detector
behaviour or calibration changed.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-21 21:04:51 +02:00
commit 58704834b6
7 changed files with 432 additions and 43 deletions

View file

@ -40,16 +40,27 @@ items; this is the full list, each with the mechanism.
(an injection in a directory listing is caught) rather than path-rejecting the
conformant bundle. A front-end materialising individual uploads keeps the opposite
rule (`allow_reserved=False`): a reserved basename is a listing-shadow and refused.
- **OKF frontmatter is a restricted grammar: the mapping class has no expressible
form.** Gate T2 accepts a line-oriented subset deliberately — full YAML is a larger
parse-attack surface than a write-time gate needs. Nested mappings and flow
collections (`[a, b]`, `{k: v}`) are *rejected outright*, which fails secure.
**All four routes to a mapping fail, each on a different rule** — flow (`{k: v}`)
on the disallowed value-start indicator, block (`k:\n sub: v`) on the
nested-mapping check, dotted keys (`k.sub: v`) on the key pattern, and the inline
second colon (`k: sub: v`) on the mapping-construct check — so the mapping *class*
has no expressible form, rather than one form being preferable to another. What
survives is scalars and flat lists of strings. **Two of those routes used to
- **OKF frontmatter is a restricted grammar: the mapping class has exactly one
expressible form.** Gate T2 accepts a line-oriented subset deliberately — full YAML
is a larger parse-attack surface than a write-time gate needs. Flow sequences
(`[a, b]`) and nested mappings are *rejected outright*, which fails secure.
**Three of the four routes to a mapping fail, each on a different rule** — block
(`k:\n sub: v`) on the nested-mapping check, dotted keys (`k.sub: v`) on the key
pattern, and the inline second colon (`k: sub: v`) on the mapping-construct check.
**The fourth, the flow form, is admitted only when every key is on an allowlist**
(`by`, `at`, `from`, `to`, `id`, `title`, `author`, `usage_count`,
`last_modified` — the keys SPEC.md @ `62432a09` §5.1/§5.2 names inside a mapping)
and every leaf is a plain scalar, itself run through the same value predicates as a
top-level scalar. Nested collections, quoted leaves, duplicate keys, an empty or
unclosed mapping, and `{a:b}` (which PyYAML 6.0.3 reads as the *key* `a:b`, not as
a scalar) all raise. The form is expressible, never trusted: the allowlist
inspects every key, which is the property that carried the security when the
blanket refusal was doing the enforcing. **`resource` is deliberately off the
allowlist** although §5.1 names it inside a `sources` entry — it is a pointer
rather than a label and the only key T3 exists for, so admitting it would let
`executor: { resource: skills/run.md }` carry an executable-code pointer through a
key the https allowlist never inspects. What else survives is scalars and flat
lists of strings. **Two routes used to
degrade into a string instead of failing, and that defect is closed in `1.1.0`**:
a block-sequence item carrying exactly one key (`sources:\n - uri: https://e.com/a`
yielded the *string* `'uri: https://e.com/a'`) and the inline second colon
@ -74,13 +85,19 @@ items; this is the full list, each with the mechanism.
door A/B persist path, so frontmatter that fails secure on import passes
`screen_output` unremarked. The grammar therefore bounds what a consumer can *receive*,
never what a producer can *emit*. Verified identical on 0.2.0 and 0.3.1.
- **Consequence: an OKF v0.2 concept cannot traverse the external-import path.** Both
of v0.2's backward-breaking migration targets are nested — `timestamp``generated.at`,
and body `# Citations` → a `sources` block list of mappings — so a conformant v0.2
concept fails secure at the frontmatter gate. This is the correct direction but it is
a compatibility wall, not a policy: v0.2 support requires a deliberate parse-safety
decision about widening the grammar, and the dangling-or-substituted `executor`/
`attester` pointer question only becomes live once that decision is made.
- **An OKF v0.2 concept traverses the external-import path only if its `sources` are
flat.** The wall used to be total: both of v0.2's backward-breaking migration targets
are mappings — `timestamp``generated.at`, and body `# Citations` → a `sources`
block list of mappings — and a consumer measured **0 of 53** upstream concepts
through the gate. The trust and provenance layer now passes in its spec form
(`generated`, `verified` bare or listed, `usage_window`), so `generated.at` is no
longer a wall. **`sources` still is**: SPEC.md writes each entry as a block mapping
under a block sequence (`- id: …\n resource: …`), and that carrier stays refused —
it is the shape whose one-key degradation smuggled a pointer before `1.1.0`, and
reopening it is a separate parse-safety decision, not a corollary of the flow form.
A concept whose `sources` are flat strings, or absent, imports. The
dangling-or-substituted `executor`/`attester` pointer question stays out of reach
for the same reason: both are mappings whose payload key is `resource`.
- **A persist gate cannot cover execution risk.** OKF v0.2 introduces concepts whose
purpose is to *name code to be run* (`runtime`, `executor.resource`,
`attester.resource`). This library answers "is this safe to **store**"; executable