001/*
002 * Copyright 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.revetsec.oauth;
018
019import com.revetsec.BrowserBinding;
020import com.revetsec.StateSealer;
021import org.jspecify.annotations.NonNull;
022import org.jspecify.annotations.Nullable;
023
024import javax.annotation.concurrent.Immutable;
025
026import static java.util.Objects.requireNonNull;
027
028/**
029 * A browser-bound source for completing one authorization. A sealed form must come from the browser cookie set at
030 * begin; a store source uses that browser's binding. Neither variant exposes a state-only completion path.
031 *
032 * @author <a href="https://www.revetkn.com">Mark Allen</a>
033 * @since 1.0.0
034 */
035@Immutable
036public final class PendingAuthorizationSource {
037        private final @Nullable String sealedForm;
038        private final @Nullable StateSealer sealer;
039        private final @Nullable String context;
040        private final @Nullable PendingAuthorizationStore store;
041        private final @Nullable String browserBinding;
042
043        private PendingAuthorizationSource(@Nullable String sealedForm, @Nullable StateSealer sealer,
044                        @Nullable String context, @Nullable PendingAuthorizationStore store, @Nullable String browserBinding) {
045                this.sealedForm = sealedForm;
046                this.sealer = sealer;
047                this.context = context;
048                this.store = store;
049                this.browserBinding = browserBinding;
050        }
051
052        /**
053         * Uses a sealed pending-authorization cookie under an exact application context.
054         *
055         * @param sealedForm browser cookie value
056         * @param sealer sealing and verification keys
057         * @param context fixed application context
058         * @return the source
059         * @since 1.0.0
060         */
061        public static @NonNull PendingAuthorizationSource fromSealedForm(@NonNull String sealedForm,
062                        @NonNull StateSealer sealer, @NonNull String context) {
063                return new PendingAuthorizationSource(requireNonNull(sealedForm), requireNonNull(sealer),
064                                requireNonNull(context), null, null);
065        }
066
067        /**
068         * Uses a trusted store with a browser-specific binding. The store must consume atomically and protect
069         * confidentiality/integrity of plaintext pending records and bindings. The unkeyed binding digest is not a MAC.
070         *
071         * @param store the store
072         * @param browserBinding browser-specific secret
073         * @return the source
074         * @since 1.0.0
075         */
076        public static @NonNull PendingAuthorizationSource fromStore(@NonNull PendingAuthorizationStore store,
077                        @NonNull BrowserBinding browserBinding) {
078                return fromStore(requireNonNull(store), requireNonNull(browserBinding).toSecretString());
079        }
080
081        static @NonNull PendingAuthorizationSource fromStore(@NonNull PendingAuthorizationStore store,
082                        @NonNull String browserBinding) {
083                if (requireNonNull(browserBinding).isEmpty())
084                        throw new IllegalArgumentException("A browser binding must not be empty.");
085                return new PendingAuthorizationSource(null, null, null, requireNonNull(store), browserBinding);
086        }
087
088        @Nullable String sealedForm() { return this.sealedForm; }
089        @Nullable StateSealer sealer() { return this.sealer; }
090        @Nullable String context() { return this.context; }
091        @Nullable PendingAuthorizationStore store() { return this.store; }
092        @Nullable String browserBinding() { return this.browserBinding; }
093
094        /**
095         * Redacts the source and its browser binding.
096         *
097         * @return a redacted description
098         * @since 1.0.0
099         */
100        @Override
101        public @NonNull String toString() { return "PendingAuthorizationSource{secrets=<redacted>}"; }
102}