[CAP-71] Authentication delegation for custom accounts

[dmkozh]

Discussion thread for CAP-71

The motivation behind this change is described in details in CAP, but here is the gist of it.

Since inception of Soroban, custom (contract-based) accounts could delegate authentication to other accounts (Addresses) by using require_auth_for_args within the __check_auth function that performs custom account authentication.

The approach works, but it has drawbacks:

• Hard to simulate delegated __check_auth calls (requires manually building signature payload).
• Each delegated signer needs a separate authorization entry, which increases the tx XDR size and complexity
• It's hard and expensive to pass the authorization context to the delegated signer

This is inspired by the work on CAP-72 (https://github.com/orgs/stellar/discussions/1763), which allows any G-account to use delegated contract signers. Without this proposal the developer experience of using this functionality would likely be too cumbersome to get wide adoption.

Most of the issues can be fixed with a small protocol change proposed in the CAP. It introduces a new authorization host fn, and a new type of credentials that support the delegated signers explicitly. This allows users to sign a single authorization entry using different addresses, each of which may have its own authentication logic.

See details in the CAP itself.

[leighmcculloch]

• Hard to simulate delegated __check_auth calls (requires manually building signature payload).

It only requires manually building signature payloads because the soroban-simulation, soroban-env-host, and the surrounding tooling (contract specs, etc) do not support a way to do iterative auth discovery where auths are nested.

I think we should explore ways to address that before complicating the auth interface by adding another way to do auth with delegates, given delegates seem like they could be supported by the existing auth framework.

[leighmcculloch]

I read this before reading CAP-72, and as a way to enable CAP-72 it is particularly convenient, but if we fixed the issues with nested require_auth and simulation, CAP-72 could also leverage nested auth.

[dmkozh]

Well, this CAP fixes the issues with nested require_auth at a fundamental level. As I've mentioned in the motivation section, nesting require_auth within check_auth was never intentional. Besides the simulation issues, it's also really tricky to pass the context properly, and I don't like that, especially for CAP-72 (which was what motivated me to come up with CAP-71 in the first place). Besides making simulation more straightforward, this avoids a lot of duplication in the auth payloads, which I think is pretty meaningful.

I think we should explore ways to address that before complicating the auth interface by adding another way to do auth with delegates

This complication only concerns the custom account implementations on the contract side, so I think it's tolerable. As for the client tooling, it needs support for the delegation either way, and similarly to the auth framework itself, I think it's easier to implement support for the standard approach once, rather than to follow a bespoke standard that is only compatible with one particular custom account implementation. As for the 'legacy' nesting approach, I'm not aware of it being widely adopted, so I think it's likely safe to just discourage using it and migrate existing implementations (if there are such).

[brozorec]

This CAP is a welcome step toward providing the prerequisites for the more intuitive usage of custom accounts in some more complex cases.

As the motivation of the CAP explains, the main drawbacks in the current flow of nesting require_auths in __check_auth are:

1. manually crafting a separate authorization entry for every Address we require_auth on,
2. running two simulations before sending the transaction.

This CAP addresses only the first drawback and lays the groundwork for the CAP-72.

Below I focus only on how CAP-71 may change or improve the implementation and usability of smart accounts in the OpenZeppelin library, which currently relies on this nesting pattern.

Smart Account Overview

In the OpenZeppelin library, a smart account contains multiple rules. Each rule defines a context and a set of signers authorized for that context. Signers can be:

• Address signers (other smart contracts or G-accounts)
• Signers defined by a cryptographic key

Implementation

In our current implementation, the smart account branches the authentication logic based on the type of the signer. I’m providing here a slightly modified and simplified example for demonstration purposes:

#[contractype]
pub enum Singer {
  Crypto(Bytes),
  Addr(Address)
}

fn __check_auth(
    e: Env,
    signature_payload: Hash<32>,
    signatures: Map<Signer, Bytes>,
    auth_contexts: Vec<Context>,
) -> Result<(), SmartAccountError> {
      for (signer, _) in signatures.iter() {
        check_signer_is_allowed(signer);
        match signer {
            Signer::Crypto(pub_key) => { /* verify signature */ }
            Signer::Addr(addr) => {
                let payload = (signature_payload.clone(),).into_val(e);
                addr.require_auth_for_args(payload);
            }
        }
    }

    Ok(())
}

With CAP-71 addr.require_auth_for_args(payload) will be replaced with addr.delegate_account_auth().

  ...
    match signer {
      Signer::Crypto(pub_key) => { /* verify signature */ }
      Signer::Addr(addr) => {
        addr.delegate_account_auth();
      }
    }
...

This change is positive: the signer will receive the whole context for free (although we don’t use it in the previous example), enabling more fine-grained authorization controls within that signer.

Usability

The example below demonstrates the current client authorization flow for a smart account with only one signer (Signer::Addr) who authorizes and send a transaction:

async function signAndSendTx(contract: string, fnName: string, fnArgs: ScVal[], signer: Keypair) {
    const baseTx = new TransactionBuilder(...)
        .addOperation(
            Operation.invokeContractFunction({ contract, function: fnName, args: fnArgs }),
        )
        .setTimeout(60)
        .build();

    const simTx = await server.simulateTransaction(baseTx);
    // assume only one authorization is returned
    const simAuth = simTx.result.auth[0];
    
    const signedAuths: SorobanAuthorizationEntry[] = [];

    // construct `sigMap` to fit `Map<Signer, Bytes>` with `Signer::Addr(Address)`
    simAuth.credentials().address().signature(sigMap);
    simAuth.credentials().address().signatureExpirationLedger(validUntil);
    signedAuths.push(simAuth);

    const payload = HashIdPreimage.envelopeTypeSorobanAuthorization(
        new HashIdPreimageSorobanAuthorization({
            networkId,
            nonce: simAuth.credentials().address().nonce(),
            signatureExpirationLedger: validUntil,
            invocation: simAuth.rootInvocation(),
        }),
    ).toXDR();
    const hashed_payload = hash(payload);

    const signedEntry = await signInvocation(
        signer,
        contract,
        "__check_auth",
        [ScVal.scvBytes(hashed_payload)],
    );
    signedAuths.push(signedEntry);
    
    // rebuild transaction with both auth entries in signedAuths
    // sign and send
}

async function signInvocation(
    signer: Keypair,
    contract: string,
    functionName: string,
    fnArgs: ScVal[],
): Promise<SorobanAuthorizationEntry> {
    const contractAddress = Address.fromString(contract).toScAddress();

    const args = new InvokeContractArgs({ contractAddress, functionName, args: fnArgs });
    const invocation = new SorobanAuthorizedInvocation({
        function: SorobanAuthorizedFunction.sorobanAuthorizedFunctionTypeContractFn(args),
        subInvocations: [],
    });

    return await authorizeInvocation(
        signer,
        validUntil,
        invocation,
        signer.publicKey(),
        Networks.TESTNET,
    );
}

We manually craft and sign a second SorobanAuthorizationEntry which authorizes a call to __check_auth and the only reference to the actual function that’s invoked is indirect through signed_hashed. That’s not quite intuitive and could be confusing for users when they are prompted to sign such a payload.

After CAP-71:

async function signAndSendTx(contract: string, fnName: string, fnArgs: ScVal[], signer: Keypair) {
    let baseTx = new TransactionBuilder(...)
        .addOperation(
            Operation.invokeContractFunction({ contract, function: fnName, args: fnArgs }),
        )
        .setTimeout(60)
        .build();

    const simTx = await server.simulateTransaction(baseTx);
    // assume only one authorization is returned
    const simAuth = simTx.result.auth[0];
    
    const payload = HashIdPreimage.envelopeTypeSorobanAuthorizationWithAddress(
        new HashIdPreimageSorobanAuthorizationWithAddress({
            networkId,
            address: Address.fromString(contract).toScAddress(), // <-- new field
            nonce: simAuth.credentials().address().nonce(),
            signatureExpirationLedger: validUntil,
            invocation: simAuth.rootInvocation(),
        }),
    ).toXDR();
    const hashed_payload = hash(payload);
    const delegateSignature = keypair.sign(hashed_payload);
    
    // construct `sigMap` to fit `Map<Signer, Bytes>` with `Signer::Addr(Address)`
    simAuth.credentials().address().signature(sigMap);
    simAuth.credentials().address().signatureExpirationLedger(validUntil);
    
    simAuth.delegates([delegateSignature]);
    
    // rebuild transaction with a single signed auth entry
    // sign and send
}

We still need a second simulation round, but we eliminate the need for an extra authorization entry and the confusing authorization to __check_auth, which is great improvement.

If the examples above correctly reflect CAP-71, it should deliver tangible benefits to both users and developers in implementation, usability, and readability, alongside the resource optimizations not covered here.

Do these examples and explanations accurately capture the intention behind CAP-71?

[dmkozh]

Thanks for providing the additional context and motivation!

These examples do capture the intention, I only wanted to pointed out that thanks to get_delegated_signers_for_current_auth_check host function your examples could be simplified even further:

      Signer::Addr(addr) => {
        addr.delegate_account_auth();
      }

You no longer need a separate signature type for the delegates, instead you can iterate get_delegated_signers_for_current_auth_check output (of course you still need to make sure that a signer belongs to the account).

    // construct `sigMap` to fit `Map<Signer, Bytes>` with `Signer::Addr(Address)`
    simAuth.credentials().address().signature(sigMap);

Same here, the signature map only needs to contain crypto signers, so in case of delegated-only auth it can be empty. These two changes further reduce the transaction size.

An additional benefit of this CAP is that the context is forwarded properly within the delegated auth call. In the original example you had just the payload being authorized:

let payload = (signature_payload.clone(),).into_val(e);
addr.require_auth_for_args(payload);

so the delegate auth contract will lose the context of the original authorization, which might be restricting for the possible implementations.

[brozorec]

Thanks for those precisions, they make even clearer that CAP-71 will be very beneficial in our case. On the implementation side, the logic for Signer::Addr will be managed on a protocol level (with the additional benefit of context forwarding), but the biggest gain imo is that the CAP-71 defines a straightforward way for how clients interact with smart accounts and set the stage for a wider adoption.

[leighmcculloch]

An attribute of this proposal is it introduces function colouring to some degree for auth.

I am using the term function colouring here in a way that is not so common since it is usually used to refer to functions that are only usable in asynchronous or synchronous contexts, and not the other. But the concept matches.

For example:

When a dev wants to auth outside a __check_auth they call addr.require_auth().

When a dev wants to auth inside a __check_auth they call addr.delegate_auth().

This means if a dev is building a library that initially gets used only in call trees outside __check_auth, it will not be usable inside call trees that come from __check_auth.

[dmkozh]

This means if a dev is building a library that initially gets used only in call trees outside __check_auth, it will not be usable inside call trees that come from __check_auth.

It will still be usable, there are no changes to require_auth functionality. E.g. if you wanted to include a token transfer in your __check_auth for whatever reason (I believe Tyler has experimented with this for some Soroban challenges), you still will be able to do that.
You won't be able to do the opposite, i.e. use a library for custom accounts that uses delegate_account_auth, but I have hard time imagining a use case where that matters. This asymmetry is intentional and similar to how __check_auth function itself behaves: you can't invoke it directly in any context, so if you need to authorize a function on the account itself, you call env.current_contract_address().require_auth() instead of just calling __check_auth within the current context. The delegation function itself is a part of __check_auth implementation details and thus can only be invoked indirectly as a part of require_auth flow.

[leighmcculloch]

How does this proposal interact with cross-contract calls where __check_auth makes a cross contract call and that cross contract call requests auth on another address?

[dmkozh]

This logic is unchanged and the call still can be authorized following the regular Soroban auth semantics. This CAP only extends the capabilities for creating the custom accounts (that will also work nicely with G-account customization), but it doesn't change/restrict any of the existing features.

[leighmcculloch]

Hmm, so we'll still have the same issues with nesting auth in the cases where the nested auth is via a cross contract call within the __check_auth?

[dmkozh]

Sure, but I wouldn't consider these to be issues anymore as there is a clear path towards avoiding them by using the appropriate host functionality. I don't think there will be a need for nesting require_auth for the custom accounts that want to use auth delegation. But one still will be able to do something weird like a transfer if they wanted to.
This kind of issue exists for the auth framework as a whole - it's in no way enforced and technically users could avoid using require_auth altogether (as long as they don't stick to the standards, that is). The same goes for the delegation functionality - you can avoid it if you want to, but that's not the standard/default approach.