Adding a new UserID to existing key pair is apparently impossible.

[Mihara]

So I have a key pair, and I need to add a new userID to it and self-sign it.

Can this be done at all?

There is no obvious API call do to that, so I was about to try building the packets manually, only...

Both Key.signAllUsers() and Key.signPrimaryUser() call User.certify(), and only operate on otherCertifications, thus cannot be used to produce a self-signed UserID. In fact, User is apparently not exported at all, so I can't even call new User -- which is in the documentation for some reason. Or import createSignaturePacket. Or do a number of other things.

I'm currently digging through the internals in hopes of finding any way to do that anyway, but I would very much appreciate some insight.

Looking at the rest of the discussion section, it doesn't look like I'll get an answer though.

[larabr]

The simplest way is to call reformatKey with the UserID you want to add.
Reformatting creates a new key object, but it will also potentially change e.g. the algo preferences, to match the values you'd get using generateKey.

If you need to preserve the original key preferences and signatures, you can take the reformatted key, and copy the new user info from there, e.g.:

const { publicKey: temporaryKeyWithNewUsers } = await reformatKey({
            privateKey: originalKey,
            userIDs: [...],
            date: originalKey.getCreationTime(),
            format: 'object',
});
originalKey.users = originalKey.users.concat(temporaryKeyWithNewUsers.users.map((newUser) => {
            const destUser = newUser.clone();
            destUser.mainKey = updatedKey;
            return destUser;
}));

[Mihara]

Thanks, that was sufficient insight and better than the thing I cooked up with which strung together bits of internals -- it produces apparently valid signatures, but misses all the key settings completely.

For the record, my method was something like this:

    const newUser = publicKey.users[0].clone();
    newUser.selfCertifications = [];
    newUser.otherCertifications = [];
    newUser.revocationSignatures = [];
    newUser.userID = UserIDPacket.fromObject({
        name: "New Spiffy User ID",
    });

    // Now we basically duplicate bits of User.certify:

    const primaryKey = newUser.mainKey.keyPacket;
    const dataToSign = {
        userID: newUser.userID,
        userAttribute: newUser.userAttribute,
        key: primaryKey,
    };
    const signingKey = await privateKey.getSigningKey();

    // Then we need to partially recreate createSignaturePacket, which isn't exported *either*.
    const signaturePacket = new SignaturePacket();
    Object.assign(signaturePacket, {
        signatureType: enums.signature.certGeneric,
        keyFlags: [enums.keyFlags.certifyKeys | enums.keyFlags.signData],
    });

    signaturePacket.publicKeyAlgorithm = signingKey.keyPacket.algorithm;
    // We can set the hash manually without trying to dig into getPreferredHashAlgo,
    // which isn't exported either.
    signaturePacket.hashAlgorithm = enums.hash.sha512;
    signaturePacket.rawNotations = [];
    await signaturePacket.sign(signingKey.keyPacket, dataToSign); // detached is false by default.

    newUser.selfCertifications = [signaturePacket];

    // Since this is a totally new userid, we don't need to care about merging
    // sig blocks, so we just need to stick it back onto the key.

    publicKey.users.push(newUser);

Just in case someone comes looking, however, something to keep in mind:

reformatKey consumes {name: '...', 'emai': '...', ....} objects, and creates a complete key object entirely missing old User objects. While you can feed it a date/name combination that should result in an identical signature, (although I'm not sure about RSA keys...) third party signatures you happen to have on those User IDs will be lost.

Creating a temporary key and pulling the new User out of it to tack onto the list of existing ones is apparently the least problematic way to get there.

[larabr]

User management is complex so I wouldn't recommend manually re-implementing it, also because since low-level functions and props are involved, breaking changes might be introduced in minor releases as well.

[Mihara]

reformatKey method still looks very much like a hack, though:

    // One extra ohno moment: If I only add one userid this way, it will have a
    // "primary" flag, which means *two* userids will be primary in the final key.
    // This is undesirable!
    const temporaryKeyPair = await reformatKey({
        privateKey: key,
        userIDs: [{ name: "dummy" }, { name: "New Spiffy UserID" }],
        format: "object",
    });

    // Copy out the *second* user from the rebuilt key and stick it into the old key.
    const newUser = (temporaryKeyPair.privateKey.users[1] as any).clone();
    newUser.mainKey = (key.users[0] as any).mainKey;
    key.users.push(newUser);