Channels: Source authentication

[stuartc]

User story

We need to authenticate inbound requests to a channel using the channel's configured source credential, so that only authorised clients can send data through the proxy.

Details

Design discussion needed. The credential association model and supported credential types need further discussion before implementation begins. See open questions below.

Build an authentication layer for inbound channel requests. The channel's source credential determines how the client is authenticated. Lightning's credential system is generic (webhook auth, API credentials, database credentials, OAuth, etc.), so Channels needs:

1. A facade/abstraction that can associate a credential with a channel and extract the relevant auth parameters regardless of credential type
2. A supported-type allowlist — only credential types that map to HTTP authentication should be usable as channel source credentials (e.g., webhook auth methods like API key and Basic Auth). Types like Postgres, DHIS2, etc. must be rejected at configuration time, not at request time.
3. Potentially a join table or similar mechanism if the association is more complex than a single FK to project_credentials

For MVP, the two concrete auth methods are both webhook auth patterns:

• API key (via header, e.g., X-API-Key)
• HTTP Basic Auth

But the design should account for the credential system's diversity rather than hardcoding these two methods.

Implementation notes

Dependencies: #4399 (channel + credential associations), #4401 (plug pipeline exists)

Key technical considerations:

• Credentials decrypted via existing Cloak-based credential infrastructure — never accessed as plaintext
• Basic Auth parsing must handle missing : separator gracefully (no crash)
• Client identity extracted and stored on conn.assigns for downstream use
• Auth errors should return JSON error bodies consistent with Lightning's API style

Open questions (need design discussion):

• How do we associate credentials with channels? Current schema has a simple FK to project_credentials — is that sufficient or do we need a join table with metadata (e.g., which header to check, auth scheme)?
• How do we determine which credential types are valid for source auth? Allowlist on the credential schema type? A behaviour/protocol on the credential module?
• Channel with no source credential configured: allow unauthenticated access, or return 401?
• Do we want to support the same credential types for source and sink auth, or are they different sets?

Release notes

N/A — internal authentication layer, not directly user-facing.

User acceptance criteria

• Design for credential association model agreed and documented
• Unsupported credential types (e.g., Postgres, DHIS2) rejected at channel configuration time with a clear error
• API key auth: request must include matching key in a configured header; 401 if missing, 403 if invalid
• Basic Auth: Authorization: Basic <base64> header decoded and verified; 401 if missing, 403 if invalid
• Credentials decrypted via Lightning's existing Cloak-based credential infrastructure
• Client identity extracted and stored on conn.assigns for downstream use
• Channel with no source credential configured: behaviour decided and implemented
• Auth errors return JSON error bodies consistent with Lightning's API style