docs: SUI-1605 - add authentication baseline security model note

[IgiCodes]

Summary

This PR adds a new design note that formalises the current authentication baseline for the active service scope. It is intended to sit alongside the existing Authentication and API Edge Strategy note and provide implementation-oriented guidance for organisation-level authentication, claims/scopes, canonical organisation identity, searcher/custodian role separation, and the split between gateway validation and application-level authorisation.

Changes

• Document the baseline auth model for organisation-level authentication, trusted auth context, canonical organisation_id, high-level scopes/roles, and gateway versus application responsibilities
• Capture open assumptions, non-goals, current implementation notes, and immediate follow-on implementation themes to support implementation tickets

Validation

• Docs-only change; no code/runtime validation required

[robshakespeare]

Excellent document, lots of information and clearly captures the current state. Very good thinking around Baseline Auth Context 👍 Good to capture things like the baseline permission model too.

Great Mermaid diagram too, very helpful and clear.

---

One thing I'm wondering... I think we should somehow hi-light the difference between Inbound Auth and Outbound Auth.

Inbound auth is what we control, and is how we auth requests that the Custodians make to us - e.g. start search / get results / get results / version 2 polling (claim job / submit results).

Outbound auth I don't think we control, this is how we can make authenticated calls to Custodians, for version 1 fan-out, and for fetch.

In the language used in this document, Outbound auth is "SUI service -> Custodian"

I think we should keep Outbound auth out of scope too? Since that is only mainly concerned with simulating and stubbing Custodians, and version 1 fan-out which is currently de-scoped. Worth noting, it is looking like version 1 will be repurposed as webhooks, but in that case we would probably use some form of HMAC Signatures / Payload Signing (so that the consumer can verify it is actually us that has called them).

I think this document probably implies that "SUI service -> Custodian" is out of scope, but I think its worth trying to just capture the gist/summary of what I'm saying here!

Maybe only the effect is that technically the whole of FETCH is actually out of scope? Because it is fine to continue using the current mock auth for this specific purpose. I think that would help separate inbound from outbound, which currently is confusing (I often muddle it up).

I'm happy to have a chat about this all, it feels like it would be helpful to discuss it and bounce ideas about.

[IgiCodes]

Excellent document, lots of information and clearly captures the current state. Very good thinking around Baseline Auth Context 👍 Good to capture things like the baseline permission model too.

Great Mermaid diagram too, very helpful and clear.

One thing I'm wondering... I think we should somehow hi-light the difference between Inbound Auth and Outbound Auth.

Inbound auth is what we control, and is how we auth requests that the Custodians make to us - e.g. start search / get results / get results / version 2 polling (claim job / submit results).

Outbound auth I don't think we control, this is how we can make authenticated calls to Custodians, for version 1 fan-out, and for fetch.

In the language used in this document, Outbound auth is "SUI service -> Custodian"

I think we should keep Outbound auth out of scope too? Since that is only mainly concerned with simulating and stubbing Custodians, and version 1 fan-out which is currently de-scoped. Worth noting, it is looking like version 1 will be repurposed as webhooks, but in that case we would probably use some form of HMAC Signatures / Payload Signing (so that the consumer can verify it is actually us that has called them).

I think this document probably implies that "SUI service -> Custodian" is out of scope, but I think its worth trying to just capture the gist/summary of what I'm saying here!

Maybe only the effect is that technically the whole of FETCH is actually out of scope? Because it is fine to continue using the current mock auth for this specific purpose. I think that would help separate inbound from outbound, which currently is confusing (I often muddle it up).

I'm happy to have a chat about this all, it feels like it would be helpful to discuss it and bounce ideas about.

I agree the note needed to separate inbound auth from outbound auth more explicitly. I’ve updated it so the baseline here is clearly the inbound Searcher/Custodian -> SUI service model, and so that SUI service -> Custodian auth is called out as a separate outbound problem rather than something implied by this note.

I did not move FETCH fully out of scope, because that would conflict with the existing auth strategy note, which still keeps minimal FETCH support in scope where needed to preserve current E2E flows. Instead, I’ve clarified that only the inbound-facing FETCH boundary is covered here, while outbound proxied FETCH, fan-out, and future webhook auth remain follow-on design work.

I’ve also added outbound auth as an explicit later-work item so it doesn’t just disappear into an implicit gap.

[robshakespeare]

Thank you for taking in and applying the feedback related to the inbound vs outbound auth topic.

The other updates all make sense and look good too.

This is an excellent document. Lots of information and clearly captures the current state. Very good thinking around Baseline Auth Context. Good to capture things like the baseline permission model too. Great Mermaid diagram too, very helpful and clear.

This forms a great basis for moving the auth to be more production ready 👍