feat(auth): OPTIONAL_AUTH route level across all service macros

[JedimEmO]

What

Adds a third auth level, OPTIONAL_AUTH, to all four service macros (rest_service!, file_service!, jsonrpc_service!, jsonrpc_bidirectional_service!).

RAS endpoints were previously binary: UNAUTHORIZED (no caller, ever) or WITH_PERMISSIONS([...]) (caller required, else 401). There was no way to express "anonymous is allowed, but if a valid credential is present, identify the caller and hand it to the handler" — a common "public but richer when signed in" shape (per-document ACLs, personalization, author-preview).

An OPTIONAL_AUTH route is public — never rejected for auth reasons — but opportunistically identifies its caller. The handler receives a ras_auth_core::Caller as its first argument:

GET OPTIONAL_AUTH feed() -> FeedResponse,   // handler: async fn get_feed(&self, caller: Caller) -> ...

pub enum Caller { Anonymous, Authenticated(AuthenticatedUser) }

Design

• Why a Caller enum, not unsafe — the footgun (easy to forget the anonymous case) is handled with a self-describing, #[must_use] type passed as an explicit parameter, not by abusing unsafe (which is a memory-safety marker, would break downstream #![forbid(unsafe_code)], and enforces nothing).
• Fully lenient — a missing, invalid, or expired credential, or a cookie that fails CSRF on an unsafe method, resolves to Caller::Anonymous rather than a 401/403. A forged/stale credential simply executes as the public path.
• resolve_caller in ras-auth-core is the non-rejecting counterpart to authorize_request, reusing the same credential/CSRF/authenticate plumbing.
• file_service reuses its existing FileRequestContext (already Option<&AuthenticatedUser>) rather than changing its handler signature.
• bidirectional surfaces the connection's optional user; OPTIONAL_AUTH on outbound server_to_client calls is a hard parse error (no inbound caller to deliver).

Changes

• ras-auth-core: Caller enum, resolve_caller, From<Option<AuthenticatedUser>>.
• ras-permission-manifest: new AuthRequirementInfo::Optional; SCHEMA_VERSION bumped 1 → 2 (older pinned consumers will fail to deserialize "type":"optional").
• OpenAPI emits security: [{}, {bearerAuth: []}]; OpenRPC emits x-authentication { required: false }.
• Macro docstrings, ras-auth-core README, and CHANGELOG updated.

Compatibility

Existing UNAUTHORIZED / WITH_PERMISSIONS behavior is unchanged.

Tests

New e2e coverage in every macro (anonymous / valid-token / invalid-token-lenient), including the versioned/legacy REST handler arm and a parse-rejection test for OPTIONAL_AUTH on bidirectional server_to_client calls.

• cargo build --workspace ✓
• cargo clippy --workspace --all-targets ✓ (zero warnings)
• 194 tests pass across the affected crates; example consumers green.

🤖 Generated with Claude Code