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;
022import java.net.URI;
023import java.time.Instant;
024import java.util.Optional;
025import java.util.Set;
026
027/**
028 * Immutable context for one bounded MCP subscription authorization check.
029 * <p>
030 * The initial request context is historical admission evidence and never
031 * becomes current authority. The application context reflects initial
032 * admission for the first check and the latest successful authorization result
033 * thereafter. Candidate notification families and targets describe the initial
034 * request before acknowledgement; renewal checks describe the acknowledged
035 * subscription and cannot expand it. Exact 2025-era resource grants use the
036 * real {@code resources/subscribe} admission context and one selected URI;
037 * their catalog-family flags are false and task-ID set is empty. A later
038 * successful subscribe replaces historical evidence for subsequent checks
039 * without extending the original total grant lifetime. GET admission remains
040 * independent and does not manufacture an RPC request context.
041 *
042 * @author <a href="https://www.revetkn.com">Mark Allen</a>
043 */
044@ThreadSafe
045public interface McpSubscriptionAuthorizationContext {
046        /**
047         * Returns the immutable request context from original subscription admission,
048         * or the latest successful exact 2025-era subscribe for a resource grant.
049         * It is historical evidence, including the original immutable HTTP request
050         * and identity; the authorizer must check current application authority.
051         *
052         * @return retained subscription admission request context
053         */
054        @NonNull
055        McpRequestContext getInitialRequestContext();
056
057        /**
058         * Returns the current application authorization context. Absence is a valid
059         * replacement and does not retain an older context implicitly.
060         *
061         * @return current application context, when present
062         */
063        @NonNull
064        Optional<@NonNull Object> getApplicationContext();
065
066        /**
067         * Returns the previous effective, server-capped authorization expiration.
068         * This is empty for the initial check and is historical information during
069         * reconciliation, not proof of a currently active grant.
070         *
071         * @return previous effective expiration, when one exists
072         */
073        @NonNull
074        Optional<@NonNull Instant> getPreviousValidUntil();
075
076        /**
077         * Returns the fixed wall-clock representation of this check's queue-inclusive
078         * deadline. This is neither credential expiry nor the maximum validity an
079         * authorizer may request.
080         *
081         * @return this authorization check's deadline
082         */
083        @NonNull
084        Instant getDeadline();
085
086        /** @return whether tool-list-change delivery is included */
087        @NonNull
088        Boolean isToolsListChangedIncluded();
089
090        /** @return whether prompt-list-change delivery is included */
091        @NonNull
092        Boolean isPromptsListChangedIncluded();
093
094        /** @return whether resource-list-change delivery is included */
095        @NonNull
096        Boolean isResourcesListChangedIncluded();
097
098        /**
099         * Returns an immutable set of unique resource-subscription URIs. Membership,
100         * not iteration order, is semantically significant.
101         *
102         * @return immutable resource-subscription URI set, possibly empty
103         */
104        @NonNull
105        Set<@NonNull URI> getResourceSubscriptionUris();
106
107        /**
108         * Returns an immutable set of unique task IDs. IDs identify tasks rather than
109         * subscription handles; membership, not iteration order, is semantically
110         * significant.
111         *
112         * @return immutable task-ID set, possibly empty
113         */
114        @NonNull
115        Set<@NonNull String> getTaskIds();
116}