Flow 2 – RSA-2048 Stream Sign / Verify (Detached JWS)

/*
 * Copyright 2025 ANKATech Solutions Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package co.ankatech.ankasecure.sdk.examples;

import co.ankatech.ankasecure.sdk.AuthenticatedSdk;
import co.ankatech.ankasecure.sdk.model.SignResult;
import co.ankatech.ankasecure.sdk.model.VerifySignatureResult;
import co.ankatech.ankasecure.sdk.util.FileIO;

import java.nio.file.Path;
import java.text.MessageFormat;
import java.util.Properties;

import static co.ankatech.ankasecure.sdk.examples.ExampleUtil.*;

/**
 * Scenario&nbsp;2 &mdash; RSA-2048 <em>Streaming</em> Sign / Verify.
 *
 * <p>This walkthrough illustrates a detached-JWS workflow on a
 * <strong>pre-provisioned</strong> key (the SDK is data-plane-only — it does not
 * create keys):</p>
 * <ol>
 *   <li><strong>Key resolution</strong> &mdash; resolve a pre-provisioned
 *       RSA-2048 key from the demo playground.</li>
 *   <li><strong>Streaming sign</strong> &mdash; the SDK uploads the file in chunks
 *       and receives a <em>detached JWS</em>: flattened JWS JSON
 *       {@code {"protected", "signature"}} with RFC&nbsp;7797 {@code "b64": false},
 *       carrying no {@code payload} member.</li>
 *   <li><strong>Streaming verify</strong> &mdash; the same detached signature is
 *       verified against the binary payload with constant memory.</li>
 * </ol>
 *
 * <p><b>Rule of thumb</b>:</p>
 * <ul>
 *   <li><em>Non-streaming</em> &rarr; compact&nbsp;JWS / compact&nbsp;JWE</li>
 *   <li><em>Streaming</em>      &rarr; detached&nbsp;JWS / detached&nbsp;JWE</li>
 * </ul>
 *
 * <p>All artefacts are written under <kbd>temp_files/</kbd>.</p>
 *
 * <p><b>Implementation notes (Java&nbsp;21+):</b></p>
 * <ul>
 *   <li>File handling relies on the {@link java.nio.file.Path} API.</li>
 *   <li>UTF-8 is enforced explicitly for deterministic encoding.</li>
 *   <li>Directory creation delegates to {@link ExampleUtil#ensureTempDir(java.nio.file.Path)}.</li>
 * </ul>
 *
 * <p><b>Thread-safety:</b> the class is stateless and immutable; all variables
 * are confined to the current thread.</p>
 *
 * @see ExampleUtil
 * @see ExamplePlaygroundKeys
 * @see AuthenticatedSdk
 */
public final class ExampleScenario2 {

    /** No instantiation &mdash; this class only exposes {@link #main(String[])}. */
    private ExampleScenario2() { }

    /**
     * Runs the RSA-2048 streaming sign/verify scenario.
     *
     * <p>Loads CLI properties, authenticates against ANKASecure&copy;,
     * and delegates to the scenario logic. On any unrecoverable error
     * the JVM terminates via
     * {@link ExampleUtil#fatal(String, Throwable)}.</p>
     *
     * @param args command-line arguments (ignored)
     */
    public static void main(final String[] args) {

        System.out.println("===== SCENARIO 2 START =====");
        System.out.println("""
                Purpose :
                  * RSA-2048 streaming signature data-plane round-trip
                  * Demonstrates detached-JWS pipeline (sign -> verify) on a
                    pre-provisioned playground key
                Steps   :
                  1) Resolve pre-provisioned RSA-2048 key
                  2) Create sample payload
                  3) Sign payload (detached JWS)
                  4) Verify signature
                  5) Report result
                --------------------------------------------------------------""");

        try {
            prepareWorkingDir();

            Properties            props      = loadProperties();
            AuthenticatedSdk      sdk        = authenticate(props);
            ExamplePlaygroundKeys playground = ExamplePlaygroundKeys.from(props, sdk);

            runScenario(sdk, playground);

        } catch (Exception ex) {
            fatal("Scenario 2 failed", ex);
        }

        System.out.println("===== SCENARIO 2 END =====");
    }

    /**
     * Executes the 4-step RSA-2048 streaming sign/verify scenario on a
     * pre-provisioned key.
     *
     * <ol>
     *   <li>Create sample document.</li>
     *   <li>Resolve a pre-provisioned RSA-2048 signing key.</li>
     *   <li>Stream-sign to detached JWS.</li>
     *   <li>Stream-verify signature and report result.</li>
     * </ol>
     *
     * @param sdk        an authenticated {@link AuthenticatedSdk} instance; must not be {@code null}
     * @param playground the pre-provisioned playground key resolver; must not be {@code null}
     * @throws Exception if any operation fails
     */
    private static void runScenario(final AuthenticatedSdk sdk,
                                    final ExamplePlaygroundKeys playground) throws Exception {

        /* 1 -- create sample document --------------------------------------- */
        Path doc = TEMP_DIR.resolve("scenario2_doc.txt");
        FileIO.writeUtf8(doc,
                "Scenario-2 - RSA-2048 detached-JWS streaming sign & verify.");
        System.out.println("[1] Document ready          -> " + doc.toAbsolutePath());

        /* 2 -- resolve pre-provisioned key (data-plane SDK: no key creation) */
        final String kid = playground.kidForAlgorithmAndOp("RSA-2048", "sign");
        System.out.println("[2] Using pre-provisioned key -> kid = " + kid);

        /* 3 -- streaming sign (detached JWS) -------------------------------- */
        Path sig = TEMP_DIR.resolve("scenario2.sig");
        SignResult signMeta = sdk.signFileStream(kid, doc, sig);
        System.out.println("[3] File signed             -> " + sig.toAbsolutePath());
        printSignMeta(signMeta);

        /* 4 -- streaming verify --------------------------------------------- */
        VerifySignatureResult verifyMeta = sdk.verifySignatureStream(doc, sig);
        System.out.println(MessageFormat.format(
                "[4] Signature valid         : {0}", verifyMeta.isValid()));
        printVerifyMeta(verifyMeta);

        System.out.println(verifyMeta.isValid()
                ? "SUCCESS - signature verified."
                : "FAILURE - signature verification failed.");
    }
}