feat(auth): expose :specify-id via private-intel scope

[ereteog]

Related https://cisco-sbg.atlassian.net/browse/XDR-52722

Summary

Exposes the :specify-id capability through a dedicated top-level OAuth2 scope and closes the cross-tenant overwrite gap that surfaces when caller-supplied IDs become reachable outside the static admin role.

What changes

Dedicated ctia-specify-id scope

A new sibling root scope is added in src/ctia/auth/jwt.clj:

• ctia-specify-id:write — confers #{:specify-id} and nothing else
• ctia-specify-id (no access) — confers nothing
• ctia-specify-id:read — confers nothing

The scope is intentionally NOT a subscope of private-intel (or any entity-root scope), so granting private-intel:write does not implicitly carry :specify-id. Least-privilege provisioning: a client that should be able to specify entity IDs holds exactly this one scope, and gains no entity read/write/delete authority from it.

Scope name is configurable via ctia.auth.specify-id.scope (default "ctia-specify-id"), following the same pattern as entity-root-scope / casebook-root-scope / assets-root-scope.

Flow-layer collision check on caller-supplied :id

:specify-id only gates the capability to name an entity at create time. It does not by itself protect against a caller supplying an ID that already exists and belongs to another org — handle-create writes via an ES upsert and does not check the existing document's ACL.

src/ctia/flows/crud.clj find-create-entity-id now performs a pre-existence lookup whenever a caller supplies :id. If the ID resolves to an existing document, the flow rejects the create with :id-collision-error. The same prev-entity + :get-fn plumbing update-flow already uses is reused; both POST /ctia/{entity} and POST /ctia/bundle/import traverse the new check.

Why

Today :specify-id is reachable only via the static admin role — no OAuth2 scope maps to it. A dedicated narrow scope lets operators grant just this capability without conferring full admin identity or any entity-level write authority.

Trade-offs

• The flow-layer check costs one additional store read per caller-supplied :id on the create path. Bundle imports without :id (the common case) are unaffected.
• The check uses the same access-controlled read as the existing flow; if a TLP=red document owned by another org is unreadable to the caller, the collision is currently not detected. This is a residual gap consistent with the existing ACL posture and is called out as a known limitation, not a regression introduced here.

Out of scope

• valid-short-id? validates format only; it does not bind IDs to a tenant or hostname.
• Operator documentation and changelog beyond what is in this PR.

QA

No QA is needed. Covered by scopes-to-capabilities-test and find-create-entity-id-collision-test, plus end-to-end JWT integration coverage in ctia.entity.web-test/bundle-import-with-jwt-specify-id-test and single-entity-post-with-caller-supplied-id-test.

Release Notes

intern: :specify-id is now conferred by the dedicated ctia-specify-id:write OAuth2 scope (previously admin-only). Caller-supplied :id on create is now rejected when it collides with an existing document the caller is not authorized to write.

[yogsototh]

Note

Automated review -- a fresh pass runs within ~1h of each push.
Clean PRs at risk:low/risk:medium (or labeled BOT_APPROVABLE) are approved automatically; risk:high+ needs a human.

---

Verdict: APPROVED -- 0 CRITICAL, 0 HIGH, 1 MEDIUM

Findings

• MEDIUM [cross-cutting] -- Intra-batch duplicate IDs bypass collision check: prev-entity pre-fetches existing docs at flow start, so two entities in the same bundle sharing a fresh caller-supplied :id both pass the guard and ES last-write-wins applies. Not a regression (the upsert existed before), and the PR doesn't claim to handle it, but worth noting as a residual gap if :specify-id callers ever batch-import with duplicate IDs. (src/ctia/flows/crud.clj:create-flow)

PASS: Security, Correctness, Code Quality, Tests, Style

The scope mapping is strict (ctia-specify-id:write only, path-length-1 only), the collision guard is correctly wired through both single-entity POST and bundle import paths, the cond-> fix for callers without :get-fn is correct, and test coverage is comprehensive (unit + integration, cross-org, same-org reuse, happy-path regression).

Non-blocking follow-ups

• The TLP=red visibility gap (acknowledged in the PR) means a cross-org attacker who knows a TLP=red doc's ID can still overwrite it via :specify-id. Closing this requires a store-layer ACL-bypass read -- a wider change, correctly out-of-scope here.
• Consider whether intra-batch duplicate-ID detection (a simple (frequencies (keep :id entities)) check at flow entry) is worth adding as a fast-fail before the store round-trip.

-- auto-review-team (BOT_APPROVABLE gate)

[yogsototh]

Note

Automated review -- a fresh pass runs within ~1h of each push.
Clean PRs at risk:low/risk:medium (or labeled BOT_APPROVABLE) are approved automatically; risk:high+ needs a human.

Re-review (10 commits, +491/-66)

Clean. No blocking issues found.

What this PR does

• Adds a dedicated ctia-specify-id:write OAuth2 scope that confers only :specify-id (decoupled from private-intel:write)
• Adds a flow-layer collision guard in find-create-entity-id: caller-supplied :id that resolves to an existing document is rejected with :id-collision-error (prevents cross-tenant overwrite via the ES upsert)
• Adds intra-batch duplicate detection (detect-duplicate-ids) to catch two entities in the same create batch sharing a fresh ID (which would bypass the pre-fetched get-prev-entity)
• Comprehensive test coverage: unit (find-create-entity-id-collision-test, detect-duplicate-ids-test), integration (bundle import + single-entity POST), cross-org and same-org reuse assertions

Design notes (not blocking)

• The acknowledged TLP-red visibility gap (a doc invisible to the caller's read bypasses the collision check) is a pre-existing ACL limitation, not a regression. Closing it requires a store-layer ACL-bypass read -- reasonable to leave out of scope.
• find-create-entity-id declares :- s/Str but can return an error map -- this is a pre-existing pattern in that function (the "Invalid entity ID" branch already returns a map). Not introduced here.
• The prev-entity closure pre-fetches once at flow start, so the guard is O(1) per entity after the initial batch read. Good trade-off for the common case (most creates don't supply :id).

-- auto-review-team (BOT_APPROVABLE gate)

[yogsototh]

Note

Automated review -- a fresh pass runs within ~1h of each push.
Clean PRs at risk:low/risk:medium (or labeled BOT_APPROVABLE) are approved automatically; risk:high+ needs a human.

Clean on re-review. The scope design, collision guard, and test coverage all look solid.

• Scope isolation -- ctia-specify-id:write confers only :specify-id; bare scope and :read confer nothing; not reachable via private-intel:write. Correct and minimal.
• Collision guard -- find-create-entity-id now rejects caller-supplied :id when a document already exists at that ID, closing the ES-upsert cross-tenant overwrite gap on the create path.
• Intra-batch dedup -- detect-duplicate-ids catches two entities sharing the same fresh :id within a single bundle import (where pre-fetch would see both as "new").
• Backward compat -- :get-prev-entity is optional (cond-> only assocs it when get-fn is provided), so callers not passing :get-fn retain legacy behavior.
• TOCTOU residual -- acknowledged in the PR body; the flow-layer check is defense-in-depth, not a distributed lock. Acceptable tradeoff.
• Test coverage -- unit tests for both pure functions plus end-to-end integration tests covering bundle-import and single-entity POST across same-org re-create, cross-org attack, and fresh-id regression.

No blocking findings.

-- auto-review-team (BOT_APPROVABLE gate)