Subject. apps/oshun/bff/src/assistant/workbench-kit-read.ts — the ONE
generic read tool Eve offers over studio workbenches, composed on the workbench
kit's S4 router (@oshun/workbench-kit/router, S4.1), the canonical actor
resolver (S4.2), object authorization (S4.3), limits (S4.10) and audit (S4.12).
Threat-modelled BEFORE registration (this file), with every abuse case landed as
an executable refusal in workbench-kit-read.spec.ts (43 cases, the threat
family named per test) and as advisory cases in the builder deck
(deck-builder-cases.ts, builder-adv-kit-read-*).
Method. The S4 abuse cases the kit was built against (cross-tenant ids, scope escalation, enumeration/IDOR, mass-assignment, payload bombs, rate floods, unknown surfaces, fabricated success) are each mapped to the kit pipeline step that must refuse them, and the spec asserts the kit's PREFIX property there — a request refused at step N ran exactly steps 1..N and nothing after — plus the store-touch count (the boundary double counts every method it is reached by). A harness with no negative control proves it ran, not that it can fail, so two deliberately broken inputs run beside the positives: a registry with a handler removed (must be refused at construction) and a metadata resolver that ignores its scope (must be caught as a fault, never served).
How a call runs#
tool args ──► closed-object validation + view lookup
──► canonical actor/tenant/scope pre-eligibility (no store touch)
──► [eligible object views] METADATA pre-load, tenant-scoped at the store
──► kit pipeline (sync decision):
trace → transport-limit → authenticate → resolve-scope →
route-authorize → actor-limit → validate → object-authorize →
idempotency → concurrency → handler(=PLAN) + audit finaliser
──► only a plan that reached `handler`: execute the read through the
SAME store methods / derivations the HTTP routes serve
──► host audit row (served | refused | execution-failed) keyed by the
RAW user id, carrying the kit actor, tenants, steps, correlation
The kit's router is synchronous by design; the BFF store is asynchronous. Before
the asynchronous metadata load, the host invokes the SAME canonical actor
resolver and requires the route's studio-operator role. That is a privacy
pre-gate only; the router remains the authorization authority and emits the
exact refusal and audit. Eligible object reads load through the tenant-bound
store into ObjectMetadata — a type that has nowhere to put content.
Abuse cases → refusal step → evidence#
| # | Abuse case (S4 family) | Refused at | Caller sees | Store touched | Spec / deck |
|---|---|---|---|---|---|
| 1 | Cross-tenant session — a valid admin session bound to tenant acme reads tara-workbench (store tenant v1-studio) |
authenticate — resolveCanonicalActor compares the claim tenant with requestTenant = the store's bound tenant → cross-tenant → tenancy.tenant_mismatch |
"your session is bound to a different tenant than this workbench (cross-tenant) — refused" | no | spec CROSS-TENANT; steps [trace, transport-limit, authenticate, safe-error, audit] |
| 2 | Scope escalation — a member (domain:*) or a non-studio admin (admin:support) asks for workbench data |
host pre-eligibility prevents even an object metadata load; the router then refuses at route-authorize — the descriptor names the ONE role studio-operator, granted only for admin:* | admin:studio → authorization.scope_missing |
"this view needs the studio admin scope" | no, including object views | specs SCOPE ESCALATION ×2 + PRELOAD PRIVACY; deck builder-adv-kit-read-member (tool not offered to members) |
| 3 | Enumeration / IDOR by id — guessing concept ids | object-authorize — absent ⇒ conceal ⇒ state.subject_absent; the content read never runs; every probe is audited and rate-limited (case 6) |
"not found — no such object in this workbench" | metadata probe only (1 call), no dossier | spec ENUMERATION / IDOR ×2; deck builder-adv-kit-read-bogus-concept |
| 4 | Presence oracle — telling "not yours" from "not there" | object-authorize — the kit's absent and concealed decisions share disposition, message key and remediation; the spec strips the correlation id and asserts the two operator messages are byte-identical |
identical text | no | spec ABSENT and CONCEALED are the same |
| 5 | Scope-ignoring resolver (the WHERE id = $1 with the tenant predicate left off) |
object-authorize — loadObject compares the returned tenant with the scope ⇒ faulty: resolver-ignored-its-scope ⇒ unavailable + retry-after; the fault is written to the host audit row for the operator, the caller learns nothing |
"the object metadata store did not answer — retry" | no | spec resolver FAULT (control) |
| 6 | Rate flood / enumeration by volume | actor-limit — kit consume over declared rules: actor 30/60s, tenant 120/60s, route 60/60s (KIT_READ_RATE_RULES), tenant bucket checked first, windowed counter charged only on within |
"rate limited … retry after 60s" | exactly permitted calls |
spec RATE |
| 7 | Mass filter / vocabulary abuse — an unknown status, limit: 999, a non-uuid id, an unregistered bundle state |
validate — each view's check is the contract seam; lists cap at 50 and DECLARE truncation (total/returned/truncated) so a partial answer never reads complete |
"a parameter is invalid" | no | spec VALIDATION |
| 8 | Payload bomb — 20 KB in a filter | transport-limit — declaredBytes vs maxRequestBytes (16 KiB) before readBody is ever called |
"the params are larger than the kit accepts" | no | spec PAYLOAD |
| 9 | Unknown surface — "read the veritas newsroom workbench" | before the kit — the registry refuses and names the registered views (its own catalog, not data); no audit row because nothing ran | "unknown_view … Registered views — …" | no | spec UNKNOWN SURFACE; deck builder-adv-kit-read-unknown-workbench |
| 10 | Fabricated success on an unbound deployment | handler — a tara view with no store bound returns a typed dependency.not_configured refusal (audited); the capability probe reports not_configured with the missing setting, never configured |
"the workbench store is not bound on this deployment" | n/a | spec ABSENCE IS NEVER SUCCESS + capability-probe case |
| 11 | Registry drift — a view declared without a handler, a route for an undeclared capability, a colliding path | construction — createWorkbenchRouter refuses (route-without-binding, route-capability-undeclared, route-collision); the tool throws kit_router_refused rather than serving a partial surface |
n/a | n/a | spec CONTROL: registry with a view that has no handler is REFUSED |
| 12 | Content in the decision path — script bodies, premises | by type — ObjectMetadata carries stage/owner/tenant/classification only; the dossier omits scriptJson; the spec asserts the revision secret never appears in the result |
— | — | spec object read pre-loads METADATA only |
| 13 | Mass assignment / writes | the tool schema is a closed object (additionalProperties: false) and the binding independently rejects unknown top-level fields/non-object params; every route is GET, every binding command: null, and no write seam is bound |
a correctable invalid_input |
no | tool-shape/argument-validation specs; 7.4 mutations are per-case, card-gated, and NOT this tool |
Decisions recorded#
- Session tenant = the workbench store's bound tenant. The tara routes serve
a single studio tenant (
v1-studio,server.ts). Both Eve and the HTTPguarded()chain now refuse an explicitly different session tenant before a workbench read; a missing tenant retains the established route behavior. - Principal mapping is host-supplied (
STUDIO_PRINCIPAL_MAPPING): the 12 canonical Studio roles → kit principals; the kit'soperatorprincipal is never granted (it means cross-tenant platform ops and may not read tenant content).admin:studiowithout a creator role reads as acontributor, exactly asguarded()lets it read on the routes. - Object-level authorization engages for object views only (
concept). The tara plane carries no per-object ACL metadata (no assignees, holds, protected flags), so the kit's ladder decides on tenant + absence today; the metadata shape is complete so a workbench with real ACLs joins the sweep with no change to the pipeline. - Launch-readiness-governance has no persisted state — its route serves a
vocabulary and a pure evaluator. The two views are honest about that:
vocabularyandevaluate(platform-scoped; the evaluator is the route's own parser + function, exported rather than duplicated). - Audit lands in the admin audit store the tara mutations already write to
(
adminAuditEventsStore), keyed by the raw BFF user id with the derived kit actor id (actor:<segment>) beside it; refusals are rows, not logs. - Audit rows go to the REGISTRATION-TIME store. The first live battery found
zero kit rows in a 39 KB feed:
server.tsinjects a durable-backed audit store intocreateApp, the audit-log feed reads that instance, and the tool had written to the in-memory module singleton. Fixed at the seam —app.tsnow passesauditEventsStoreto the tara route registration (it never had; the workbench's own mutation audits were landing in the same unread singleton — a second pre-existing route-layer gap, closed by the same line), the routes expose it (getTaraWorkbenchAuditEvents), andkitReadDepsFromRuntime()writes there. Locked by a unit case that binds a registration store and asserts the runtime deps use it. Registration bindings are identity-tokened and cleared on Fastify close; closing an older coexisting app cannot clear a newer app's binding. - Derived ids. A BFF user id is an arbitrary string; the kit segment is
derived deterministically (
kitIdSegment) and NEVER replaces the raw id in host records. - Expiry. The BFF resolver is the authority on token expiry (it refused an
expired token before any tool ran); the kit claim carries the token's
expwhen present, else a one-hour session horizon — a documented approximation nothing downstream reads except the kit's own belt-and-braces check.
Sweep seams (7.3.1–7.3.6, 2026-08-22) — hathor records and isis reads#
The alphabetical sweep surveyed the 57 remaining studio workbenches page → component → endpoint → route → store → persistence class before registering anything. Two carry real server state and joined the tool; the rest are recorded as verdicts on the TODO checkboxes. The abuse cases the two new seams add, and where they die:
| # | Abuse case | Refused at | Caller sees | Spec |
|---|---|---|---|---|
| 14 | Cross-owner read — "show me operator X's quest drafts" (hathor records are per-owner, not per-tenant) | by construction — no hathor view accepts an owner parameter; execute runs the route's own listDurably(actorUserId) keyed by the kit-resolved actor's raw id, so another operator's rows have no path to the reply |
their OWN rows (or an honest empty), never another's | OWNERSHIP |
| 15 | Fabricated success on an undurable deployment — durability required at boot, no snapshot sink bound | execute — the store's own *PersistenceError (the route's 503) is rethrown as persistence_unavailable; the host audit row is execution-failed; the capability probe states the sink binding (durable sink N/4) instead of guessing |
"the … store's durable repository did not answer" | ABSENCE IS NEVER SUCCESS (hathor); probe case |
| 16 | Scope superset — an admin:workspace:isis-only session (the isis HTTP routes serve it) |
route-authorize — the descriptor still names the ONE role studio-operator (admin:* | admin:studio); Eve is stricter than the route, never looser |
"this view needs the studio admin scope" | SCOPE (recorded finding) |
| 17 | Bulk leak through a read — embeddings (≤4,096 dims), sample texts (≤16 KB), raw signal sets, IP matches | by projection — sized (embeddingDimensions, predictedLength, signalKeys, ipMatchCount) while every verdict field stays; rows paged ≤50 with the truncation stated; aggregates over the FULL set as the route computes them |
totals first, a bounded page, the route's own rollup | isis projections SIZE what a reply cannot carry |
| 18 | Parameter guessing — the model cannot see why a call was refused | validate — the refusal now carries the view's own parser detail (the same text the HTTP 400 body returns) so the next call is corrected, not guessed |
"validation.field_invalid: … — limit must be an integer between 1 and 50" | VALIDATION DETAIL |
Decisions: hathor and the fourteen classic isis admin views are
platform-scoped (scopeBinding: null) because those stores do not carry a
tenant discriminator — a hathor row is addressed by its owner and the classic
isis rows are platform-admin data. The post-sweep curated gallery is the
exception: its records carry tenantId, so its view is tenant-scoped and binds
the raw authenticated tenant (case 29). listDurably is the route's read
semantics — it touches lastAccessedAt for retention and persists that touch —
so the view inherits a read-that-writes-access-time exactly as the page does; it
is named here so the audit row's "read" is not mistaken for a pure read at the
store.
Card-gated mutations (7.4, user-decided 2026-08-22) — the write path#
Five commands (tara_capture_spark, tara_promote_spark, tara_archive_spark,
tara_transition_concept, tara_schedule_concept) mount on the SAME plugin and
router as the read views, each with a kit CommandSchema (precondition field
if-match, idempotency key idempotency-key, retry: idempotent-replay). A
command is two phases on the confirm bridge: card time (prepareKitCommand
— parameters parse, store bound, scope and the route's permission hold, the
subject exists, the route's own 409s do not fire, the subject's revision is
captured, the sentence names the row) and confirm time (runKitCommand —
the subject is loaded AGAIN, the kit pipeline decides with the idempotency claim
and the revision precondition, and only a plan that reached handler executes
the route's own write through the lifted route constructors). Abuse cases, and
where they die (workbench-kit-write.spec.ts, 20 cases):
| # | Abuse case | Refused at | Caller sees | Spec |
|---|---|---|---|---|
| 19 | Write on the model's say-so — run without a card |
the binding — card_required; the runner never calls run before confirmSummary (EVE-VIS-277), and the binding refuses even if it did, because the revision the kit compares IS the one on the card |
"no confirmation card was shown for this call" | NO CARD |
| 20 | Stale card — the row changed between card and confirm (another operator, the page, an agent) | concurrency — the card-time revision (derived from updatedAt) against a FRESH read → conflict.revision_stale; store untouched; the host row carries both revisions |
"the row changed after the card was shown — nothing was written" | STALE REVISION |
| 21 | Double execution — a retried confirm of an accepted request | idempotency — the claim (tenant, client, operation, key, target + request digest) is completed → the kit replays the stored result with idempotent-replay: true; no second write |
replayed result | IDEMPOTENT REPLAY |
| 22 | Permission escalation — studio scope present, the route's permission (schedule-publish) absent |
handler — the route's own requirePermission gate, re-decided with the CONFIRMING session's roles → authorization.scope_missing naming the permission; also refused at card time |
"this action requires the 'schedule-publish' studio permission" | PERMISSION |
| 23 | Scope / tenant — a member, a cross-tenant admin | card time refuses before loading a row; confirm time's canonical pre-eligibility also prevents the fresh subject read, then the router refuses at route-authorize / authenticate and audits the exact terminal step |
as cases 1–2 | SCOPE; card-time preload privacy |
| 24 | A card for a write that will fail — archived spark, taken slug, blocked stage move, killed concept | card time — the route's own 409s (illegal_spark_transition, slug_taken, illegal_transition with the evaluator's blockers, concept_killed) refuse BEFORE any card (EVE-VIS-208); re-checked at execute |
the route's refusal, in the model's own loop | refuses the route's own 409s BEFORE any card |
| 25 | Registry drift on the write side — a command declared without a precondition | construction — command-schema-rejected; the tool throws kit_router_refused rather than serving a write that two callers could both win |
n/a | CONTROL (write) |
| 26 | Write argument smuggling — an undeclared tenant/owner/control field | before card time and again at kit validate — each command derives its closed allowlist from its advertised schema (additionalProperties: false), so the schema and runtime cannot drift |
invalid_input naming the unexpected field |
rejects undeclared fields |
| 27 | Unbounded process state / stale authority — abandoned cards, expired replay records, actor churn | TTL sweep — card entries expire after 10 minutes, replay records after 24 hours, and inactive rate buckets after the longest declared window; the specs advance the clock and assert the entries are removed | expired card: card_required; expired replay needs a live card path |
expiry/eviction cases in both specs |
| 28 | Half-promotion — concept write succeeds and spark backlink fails | persistence — HTTP and Eve both call TaraWorkbenchStore.putPromotedSpark, which validates and writes both contract rows in one PostgreSQL interactive transaction; an invalid second row rolls back the first |
no acknowledged partial promotion | real-Postgres atomic rollback integration case |
| 29 | Curated-gallery cross-tenant/filtered-total leak — a caller asks Eve for another tenant's lesson assets, or learns their count through total |
tenant-scoped kit route + the consumer route's own parser/projection — a missing tenant is tenancy.tenant_missing; the handler receives only the raw authenticated tenant and queryCuratedLessonGallery filters authorization before pagination or totals |
only the caller tenant's eligible items and total; missing tenant is refused | kit-read curated-lesson-gallery tenant/missing/malformed cases; curated route 4-case suite; tenant-bound live drawer probe |
Decisions: the revision is DERIVED from updatedAt (the tara rows carry no
revision column; every route write touches updatedAt, which is all the
precondition needs); creates evaluate their precondition at apply (there is no
subject revision before the id exists) and are irreversible in the idempotency
record, subject commands at submit; the idempotency records live per process,
expire after 24 hours, and are swept globally (the bridge is one-shot, so a
replay is a retried confirm of the SAME live request; process loss invalidates
the pending card and executes nothing); both audit rows land in the
registration-time store — the kit's
(eve.workbench-kit-write.executed|refused|replayed|execution-failed) and the
one the HTTP route would have written (studio.tara_workbench.<event>, with
via and the kit correlation), so the two trails join.
Case 29 was added by the 2026-08-30 completion delta audit. The curated consumer
route landed after the original alphabetical sweep and is a real server-state
read over the durable output-gallery store. It is now the fifteenth isis view
(31 total views): its query parser is exported from the HTTP route, both hosts
call the same queryCuratedLessonGallery projection, and the kit does not
accept a tenant argument. A tenantless canonical host session is represented as
a platform principal only for platform reads; the tenant-scoped descriptor
therefore refuses it instead of fabricating a public tenant. The live admin
probe used a tenant-bound bearer, grounded the exact total against
POST /v1/isis/curated-lesson-gallery/query, and found the served view in the
durable audit feed.
What this does NOT claim#
- No production usage has run through the tool yet (7.3 pilot is the first).
- The kit's
loadObjectscope re-check is tautological for the tara store (every row it returns is its bound tenant by construction); the control in case 5 proves the CHECK works, not that the tara store can fail it. - Rate rules are declared, not measured: 30/60/120 per minute are ceilings a drawer turn cannot reach honestly (the agent loop caps tool calls per turn); they exist so an enumeration loop is bounded by DATA, not by hope.