001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.ThreadSafe;
022
023/**
024 * Resolves the stable application owner of a freshly admitted MCP session use.
025 * Applies only to endpoints explicitly enabling sessions for MCP
026 * {@code 2025-06-18} or {@code 2025-11-25}; Soklet's {@code 2026-07-28}
027 * implementation does not use this callback.
028 * <p>
029 * Implementations must be fast, local, nonblocking, and safe for concurrent
030 * invocation. Soklet invokes the resolver inside the operation's bounded
031 * application execution after fresh admission. Remote authorization belongs
032 * in the admission controller, not this mapping.
033 * <p>
034 * The key must distinguish subjects, including issuer and tenant where
035 * relevant. A principal's equality, an authorization partition, or a rate-limit
036 * partition need not identify one subject. Keys are never emitted in Soklet's
037 * responses, logs, or metric labels. Anonymous owners are resolved only when
038 * explicitly enabled in {@link McpSessionConfig}, under a separate internal
039 * namespace. A constant anonymous key deliberately shares one owner quota;
040 * generating a new key per initialization must not bypass that quota.
041 *
042 * @author <a href="https://www.revetkn.com">Mark Allen</a>
043 */
044@ThreadSafe
045@FunctionalInterface
046public interface McpSessionOwnerKeyResolver {
047        /**
048         * Resolves one opaque, stable owner key from the current admitted identity.
049         * The key must be nonblank and at most 256 UTF-8 bytes. Null, invalid values,
050         * failure, or timeout fail closed.
051         *
052         * @param admissionIdentity freshly admitted identity
053         * @return stable, nonblank opaque owner key
054         * @throws Exception if an owner cannot be established
055         */
056        @NonNull
057        String resolve(@NonNull McpAdmissionIdentity admissionIdentity) throws Exception;
058}