feat(serenity): Track producer-source passthrough + can_track gate (PROTOTYPE, SITES-47870)

[aliciadriani]

DRAFT / RFC — prototype for discussion, not for merge. From the PR #2867 thread, making @jjenscodee's Serenity-path note concrete. Stacked on claude/wp-s2-source (WP-S2).

Problem

The Serenity create path injects a fixed PROXY_CREATE_SOURCE_VALUE = 'config' on every prompt. The SR "Track" flow in Serenity mode writes through the same path, but those prompts genuinely originate from semrush / gsc / citation-attempt / synthetic-personas cards — so they collapse to source = config. And /serenity/prompts has no prompts row for the SITES-47870 read-side treatment to derive from, so it needs a fix at the write site.

Commits (3)

1. Injector seam — makePromptTagInjector honours a per-item input.source override (canonicalized, config fallback, memoized per (project, source)).
2. Track wiring — POST /serenity/prompts accepts a top-level assertSource: true opt-in; when set, each item's source is threaded through. Without it, a body source is ignored (default surface stays closed, §1 item 6).
3. Capability gate — assertSource is gated on a FACS producer capability <product>/can_track (e.g. llmo/can_track), distinct from llmo/can_configure. Enforced in the controller via authInfo.hasFacsPermission; non-FACS sessions (admin/internal/s2s) bypass, mirroring the ReBAC pattern in brands.js. A flag set without the capability is dropped (→ config) and logged — not a hard 403 — so a mixed batch still writes.

What's here

• handlers/prompts.js, handlers/prompts-subworkspace.js — injector seam + assertSource wiring (twins).
• controllers/serenity.js — the capability gate (body sanitized before dispatch).
• docs/openapi/schemas.yaml — assertSource + per-item source + the capability note.
• Tests: injector (5) + flat handler (4) + subworkspace handler (2) + controller gate (3) — override, canonicalization, closed-by-default, unparseable-fallback, (project,source) caching, honoured-with-cap / dropped+warned-without / non-FACS-bypass. Full suite green (15,425), coverage gate met.

Open items for the design sync (@dzehnder / @jjenscodee)

1. ✅ Where does the Track flow supply the source? — per-item source under assertSource.
2. ✅ Which principals may set assertSource? — gated on <product>/can_track. Sub-decisions remain: (a) register can_track in the MAC capability catalog; (b) reject-vs-ignore an unpermitted flag (this prototype ignores); (c) confirm can_track is the right capability name/granularity.
3. Alignment with the /prompts strip vs SITES-47870 — this should match so Serenity-mode and brandalf orgs behave the same.
4. Should source also accept a tag id, not just a bare value?

Not to be merged until the prompts.source contract (esp. item 2's sub-decisions + item 3) is settled.

---

Drafted MAC capability-catalog entry (llmo/can_track)

The api-service-side catalog doc block in facs-capabilities.js is updated in this PR. The authoritative catalog lives in mysticat-architecture/platform/decisions/mac-state-layer.md §"Capability catalog" (not in this repo) — here is the entry to register there:

Field	Value
Capability	llmo/can_track
Product	LLMO
Resource scope	brand (same as the POST .../serenity/prompts route)
Grants	Assert the producing source on a Serenity "Track" prompt write — set assertSource: true + a per-item source on POST /v2/orgs/:spaceCatId/brands/:brandId/serenity/prompts.
Relation to can_configure	Strictly additional / narrower. can_configure (still the route requirement) lets a caller create/edit prompts; it does not permit attributing a producing system. can_track is checked in addition, at runtime.
Enforcement	Runtime, in the serenity controller via authInfo.hasFacsPermission('llmo/can_track') — not a route entry in PRODUCTS_ROUTES. Non-FACS sessions (admin / internal / s2s) bypass.
Denied behaviour	Fail-safe: an assertSource set without the grant is dropped (source → config) and logged; no 403.
Granted to	The SR "Track" feature's identity only. TBD (design sync): which persona/role binding carries it, and whether to switch denied behaviour to a hard 403.

Once registered + granted, context.attributes.authInfo.hasFacsPermission('llmo/can_track') returns true for Track callers and the prototype gate lights up end-to-end.

---

Drafted state-layer binding grant (llmo/can_track)

can_track is now listed in PRODUCTS_CAPABILITIES.LLMO (this PR) so the grant validates through createMapping/patchMapping and appears in GET /product/capabilities. The binding grants can_track to the SR "Track" feature identity, scoped to brand. Baseline llmo/can_view is auto-added by ensureBaselineCanView. The grant must be performed by a caller holding llmo/can_manage_users for the resource.

A. Via api-service (preferred) — new binding

POST /state/access-mappings
x-product: LLMO
Authorization: Bearer <manager token holding llmo/can_manage_users>
Content-Type: application/json

{
  "subjectType": "user",
  "subjectId": "<track-identity>@<authSrc>",
  "resourceType": "brand",
  "resourceId": "<brandId>",
  "grantedCapabilities": ["llmo/can_track"]
}

Add to an EXISTING binding instead (set-semantics): PATCH /state/access-mappings/:id with { "grantedCapabilities": ["llmo/can_configure", "llmo/can_track"] }.

B. Via the set-capabilities RPC (existing mapping id)

SELECT * FROM wrpc_set_facs_access_mapping_capabilities(
  '<mapping-id>'::uuid,
  '<imsOrgId>',
  'LLMO',
  ARRAY['llmo/can_view', 'llmo/can_track']   -- full desired set (replace, not append)
);

C. Raw row (reference only — bypasses controller validation)

INSERT INTO facs_access_mappings
  (subject_type, subject_id, resource_type, resource_id, ims_org_id, product,
   granted_capabilities, created_by)
VALUES
  ('user', '<track-identity>@<authSrc>', 'brand', '<brandId>', '<imsOrgId>', 'LLMO',
   ARRAY['llmo/can_view', 'llmo/can_track'], 'system');

Open (design sync): the Track identity + subject granularity — per-user vs an org-scoped binding (subjectType: "org", subjectId = <imsOrgId>, org-wide resourceId) if Track acts for the whole org rather than per brand. And whether the grant is provisioned automatically when a brand enables Track, or issued manually.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

This PR will trigger a minor release when merged.

[aliciadriani]

/review-pr — self-review of this prototype

Summary. Per-item source injector seam + assertSource opt-in + runtime FACS can_track gate + catalog entries + grant round-trip test (9 files, +403/−22). Well-tested, lint/docs-lint clean. One security-model issue must be settled before this could merge; the rest are should/nit.

Must Fix (before merge)

• Fail-OPEN non-FACS bypass (serenity.js). assertSourceAllowed = !facs?.enabled || hasFacsPermission('…/can_track'). Per the brands.js precedent, facs.enabled is false not only for admin/internal/s2s but for non-FACS-enrolled orgs — so a regular IMS user in a non-enrolled org inherits the bypass and can assert an arbitrary source, crossing the "no client write surface" line (source-dimension.md §1 item 6) for those orgs. Should be fail-closed: allow only when the caller holds can_track or is an admin.

Should Fix

• Gate and enforcement in different layers. The controller decides; the handlers honour body.assertSource. A future caller reaching handleCreatePrompts/…Subworkspace without going through createPrompts bypasses the gate. Make the handler require an explicit trusted-caller signal, not just a body field.
• No known-vocabulary observability. A permitted caller can assert any canonicalizable source; a typo (semrsh) silently resolve-or-creates a junk producer tag. source is open (don't reject), but log when a per-item source isn't in SOURCE_VALUES.

Nits

• serenity.js evaluates ctx.data || {} twice.
• Missing a handler-level test: assertSource: true + an item with no source → falls back to config.

What's Good

Value-level fail-safe (unparseable/absent → config, never raw); default surface stays closed without the flag (tested in both twins); cache correctly re-keyed to (project, source); thorough symmetric tests + spec-referenced comments.

---

Addressing all of the above now (fail-closed, explicit handler opt-in, unknown-source warn, both nits); inline notes will follow on each fixed line.

[aliciadriani]

Applied every finding from the self-review (commit 51cca38). Inline notes on each fixed line. Full suite green (15,430), lint + docs-lint clean.

[aliciadriani]

Fixed (must-fix: fail-OPEN → fail-CLOSED). assertSource is now honoured only when the caller explicitly holds <product>/can_track OR is an admin. The prior !facs?.enabled term was fail-open — a non-FACS-enrolled org's regular IMS users inherited the bypass and could assert an arbitrary producer, crossing source-dimension.md §1 item 6 for those orgs. Denied-by-default now.

[aliciadriani]

Fixed (should-fix: layer split). The gate result is passed to the handler as an explicit allowAssertSource option, not by rewriting body. Combined with the handler-side change, the producer surface can only be enabled via this capability-checked controller path.

[aliciadriani]

Fixed (should-fix: layer split). The opt-in now requires BOTH options.allowAssertSource (set only by the trusted controller) AND the body flag. A future caller that reaches this handler without going through the capability-checked controller cannot enable the producer surface with a bare body field.

[aliciadriani]

Fixed (should-fix: unknown-producer observability). Logs when a per-item source is not in SOURCE_VALUES. It is NOT rejected — source is an OPEN dimension, so a genuinely-new producer must still resolve — but a typo like semrsh that would resolve-or-create a junk producer tag is now observable instead of silent.

[aliciadriani]

Fixed (should-fix: layer split). Subworkspace twin of the flat-handler gate — requires BOTH the trusted controller's allowAssertSource option AND the body flag.

[aliciadriani]

/review-pr iteration 1 — Suggestion (test coverage)

The capability gate is defence-in-depth: the controller drops assertSource when unpermitted, AND the handler requires options.allowAssertSource === true before honouring a per-item source. The handler side has requires the body flag too (allowAssertSource true + no body flag → config) but no test for the mirror, security-relevant case: a denied caller (allowAssertSource: false) that does set body.assertSource:true + a real source must still fall back to config. That's the assertion proving a caller reaching handleCreatePrompts with a bare body can't open the producer surface. Adding it.

(No must/should bugs found this pass — the fail-closed gate, explicit-option coupling, and unknown-producer warn from the prior review are all in place.)

[aliciadriani]

Iteration 1 fix (the one suggestion). Inline note on the added test.

[aliciadriani]

Fixed (suggestion: test coverage). Added the denied-caller handler test: allowAssertSource:false + body.assertSource:true + a real per-item source → still config. Complements requires the body flag too (the true+no-flag case), so both halves of the AND-gate are pinned and the capability gate is proven un-bypassable at the handler boundary.

[aliciadriani]

/review-pr iteration 2 — converged. Re-reviewed after the iteration-1 fix (528a27a2): no remaining must/should fixes, nits, or suggestions. The prototype's capability gate is fail-closed + defence-in-depth, and coverage now pins both halves of the AND-gate (allowed/denied) plus the controller gate, unknown-producer warn, canonicalization, and the grant round-trip. Ending the review loop. (Still draft / not-for-merge pending the WP-S4 + MAC-catalog + Track-identity decisions noted earlier.)

[aliciadriani]

⚠️ Provisioning gap: llmo/can_track can't be granted via the state-layer as this stands

While planning rollout I traced how can_track is actually evaluated vs. how it can be granted. They don't line up — flagging before anyone tries to provision it.

Finding

The gate here is JWT-only:

• serenity.js checks authInfo.hasFacsPermission('<product>/can_track') || authInfo.isAdmin().
• hasFacsPermission() (spacecat-shared-http-utils auth-info.js) reads only profile.facs_permissions — the JWT claim.
• can_track is intentionally not a facsWrapper route requirement (facs-capabilities.js — "Enforced at RUNTIME in the serenity controller (hasFacsPermission), NOT as a route requirement"). So the wrapper's JWT ∪ state-layer union never runs for can_track, and the wrapper doesn't backfill authInfo.

Where the JWT comes from — confirmed in spacecat-auth-service (src/ims/login.js): facs_permissions is populated solely from MacGiver (macGiverClient.checkAllPermission({ userId, imsOrgId, namespaces:[product] })), gated by the FT_MAC_FACS_PERMISSIONS[<product>] LD flag. There are zero references to facs_access_mappings / granted_capabilities in auth-service — state-layer grants are never folded into the JWT.

Impact

can_track is catalogued (PRODUCTS_CAPABILITIES.LLMO) and therefore accepted by POST /state/access-mappings (createMapping) — which strongly implies the intended admin/UI grant path is the state layer. But a state-layer grant of can_track never reaches the JWT, and this gate never reads the state layer, so that grant silently no-ops — the caller still falls back to source=config.

As written, the gate is satisfiable only by:

• admin (is_admin), or
• a MacGiver namespace policy that grants llmo/can_track (→ JWT at next login), with FT_MAC_FACS_PERMISSIONS[LLMO] ON in that env.

i.e. provisioning is a MacGiver policy change, not an access-mappings call.

Two remediation options (if we want the state-layer/UI grant path to work)

Option A — make can_track a facsWrapper-evaluated capability.
Add it to the route's FACS capability handling so the wrapper performs the JWT ∪ state-layer union (as it already does for can_view/can_configure). Pro: the access-mappings grant path "just works," consistent with every other capability; admins grant via the existing UI/API. Con: it becomes a route-level gate (or a second wrapper-resolved value), a bit more than "one extra check on one body field," and needs the per-brand resource resolution the wrapper already does.

Option B — have the serenity controller consult the state layer directly.
Keep the in-controller gate but union the JWT check with a state-layer read, e.g. findFacsResourceBinding (spacecat-shared-http-utils facs-state-layer.js) for <product>/can_track on the request's brand. Pro: minimal blast radius, route requirement stays can_configure, the "additional gate on one body field" framing holds. Con: duplicates a slice of the wrapper's union logic in-controller; must match the wrapper's subject/resource resolution to avoid drift.

Either option makes POST /state/access-mappings grants of can_track actually effective. Without one of them, document that can_track is MacGiver/admin-only so no one wastes time granting it via the state layer.

Near-term (prototype)

isAdmin() already satisfies the gate, so admin sessions can smoke-test the Track flow today without any provisioning. For a non-admin pilot, a MacGiver grant in the llmo namespace is the only current lever.

[aliciadriani]

Resolved: implemented Option B (58046eb8)

Following the provisioning-gap analysis above, went with Option B — union the in-controller can_track check with a per-brand FACS state-layer read, so a POST /state/access-mappings grant is now honoured (not just MacGiver-JWT/admin).

• New callerHasStateLayerCapability (src/support/facs-identity.js) checks the two subject scopes facsWrapper unions — the caller's user-subject row and org-subject row — keyed on canonical IMS org + uppercase product + brand resource. Fail-closed: any missing dependency or read error → not granted (the assert is dropped, never a 500).
• No key drift: the org/subject resolvers (resolveCallerImsOrgIdentBare / resolveCallerUserIdent) were extracted into the shared module and are now consumed by both this READ path and the state-access-mappings WRITE path; normalizeImsOrgId / findFacsResourceBinding are the shared http-utils ones. Verified the representations line up: resolveBrandUuid returns the same UUID as the route :brandId (== wrapper resource_id == stored resource_id), and subject = profile.sub everywhere.
• Gate still short-circuits on JWT/admin first (no DB read on the common path); the state-layer read only runs when body.assertSource opted in and the JWT denied.

Tests: test/support/facs-identity.test.js (both scopes, keying, fail-closed, guards) + serenity controller wiring (state-layer grant honoured, short-circuits, no read when not opted in). type-check + lint clean; 360 unit tests pass.

Net effect: can_track is now grantable via the state-layer admin/UI path or MacGiver or admin — the access-mappings route is no longer a silent no-op.

[aliciadriani]

Closing: the can_track gate is superseded by shipped allowlist governance

This PR (PROTOTYPE, SITES-47870) gated the per-item producing source behind a can_track capability. After tracing what actually consumes source downstream, we're closing it — the gate duplicates-and-contradicts a governance model already shipped to main, on a path being deprecated, and protects no real trust boundary.

What reads source downstream

• Prompt uniqueness key (brand_id, lower(text), sorted_regions, source) — identity/dedup.
• LLMO usage report (get-prompt-usage.js, internal Slack) — one column per source; analytics/ops.
• DRS / brand-presence (TRACKED_PROMPT_SOURCES) — which pipeline produced a prompt.
• v2 prompt list (prompts-storage.js) — filter/sort + DTO display.

Nothing keys off source for billing, entitlement, quota, or auth. So source is consequential for identity + analytics, not a security/financial boundary — the condition that would justify a capability gate isn't met.

The governance already exists — and it isn't a capability gate

#2810 shipped assertPermittedSource (an allowlist write-chokepoint) on the go-forward v2 path (prompts-storage.js), and the serenity path already validates against SOURCE_VALUES. Both write paths already reject unregistered/garbage sources — which is the only thing that actually corrupts the identity key, the usage-report columns, or DRS routing.

A can_track capability adds nothing to that integrity: a holder can still pick a wrong-but-registered source; a non-holder just defaults to config. The gate blocks legitimate attribution, not corruption — and corruption is already blocked by the allowlist.

Why closing rather than merging

1. Contradicts the shipped model. The product already chose allowlist-validated-but-ungated source (feat(prompts): source-aware upsertPrompts + reject unregistered sources #2810 on the go-forward path; feat(serenity): per-item source passthrough for SR Track flow (LLMO-6556) #2959 relaxed "server-owned" so elmo sets it). This PR re-imposes a capability gate on the legacy serenity path only, creating a two-path inconsistency for the same concept.
2. The gated path is being deprecated ("slated for removal once every brand is migrated to sub-workspaces"; v2 is go-forward). A per-env-provisioned capability + a standing attribution-regression hazard is poor ROI on a path being deleted.
3. The invariant it enforces is already settled the other way (feat(serenity): per-item source passthrough for SR Track flow (LLMO-6556) #2959 + feat(prompts): source-aware upsertPrompts + reject unregistered sources #2810 accept client-set registered sources).

Cleanup / no loose ends

• Behavior in prod is unchanged: feat(serenity): per-item source passthrough for SR Track flow (LLMO-6556) #2959's validated passthrough + feat(prompts): source-aware upsertPrompts + reject unregistered sources #2810's allowlist remain the governance.
• Merged elmo project-elmo-ui#2681 is inert against the ungated server (it sends assertSource; the server ignores it) — no cleanup required; optionally revert for tidiness.
• No llmo/can_track provisioning needed anywhere → the deploy-ordering hazard is gone.
• The llmo/can_track catalog entry can stay harmlessly or be reverted.

Not a quality issue

The conflict resolution, the Option B state-layer union (callerHasStateLayerCapability), and the unit + CI-green integration tests were all sound — this is a product-scope decision, not a code problem. If a future requirement makes producer attribution a real trust boundary, callerHasStateLayerCapability (in src/support/facs-identity.js) is the reusable seam to revive.