RFC: Turborepo CLI BYOK Artifact Encryption

[gaspar09]

Motivation

Turborepo CLI caches build artifacts locally. When linked to a remote cache, Turborepo will upload those artifacts so that they can be downloaded by teammates. The contents of artifacts can range from compiled code to event logs emitted during build. Assuming the remote cache itself is not encrypted, if the remote cache is compromised by an adversary, the adversary will be able to read all artifacts and possibly write artifacts on the remote cache themselves.

We would like to provide a mechanism to encrypt the artifacts before they are uploaded to any remote cache and ensure integrity of artifacts downloaded by users.

Related Artifact Signatures RFC

Terminologies Used in this RFC

• BYOK: Bring your own keys, The secret key is provided by the client using Turborepo

Goals

• Turborepo CLI encrypts artifacts before they are uploaded to the remote cache.
• Turborepo verifies the integrity of artifacts before they are applied.
• BYOK: Users of Turborepo CLI can provide their own secret keys that are used for encryption.

Non-Goals

• Turborepo CLI encrypts artifact metadata that is included in headers when uploading to the remote cache.
• The Remote Cache will support Key Rotations. On the assumption that older artifacts aren't downloaded frequently, it's easier to expire artifacts encrypted on the old keys.
• Figure out how to do secret key distribution for teams

Proposal

Option 1: Turborepo CLI request encryption from key manager

We assume that Turborepo CLI is authenticated to request encryption and decryption from an external key manager.

graph TD;

    K[KeyManagerService]
    C[(Remote Cache)]
    S[User 1]
    R2[User 2]

    AD[\artifact\]
    D2("Decrypt(key, E(key, artifact)")

    K-.->|"key, E(kms, key)"|S
    S-->|"E(key, artifact), E(kms, key)"|C
    C --> |"E(key, artifact), E(kms, key)"|R2
    R2-.-> D2 -.-> |decrypted| AD
    S-.->|request secret key|K

    K-.->|key|R2
    R2-.->|"request decryption E(kms,key)"|K

This process uses encryption and decryption by a key manager service. The flowchart outlines the following:

1. On behalf of User 1, Turborepo CLI will request from the key manager a secret key to encrypt and decrypt the artifacts. This key is served as a plaintext key and encrypted E(kms,key) by the service.
2. Turborepo CLI uses the plaintext key to encrypt the artifact.
3. Turborepo CLI uploads the encrypted E(key,artifact) and E(kms,key) to the remote cache.
4. On behalf of User 2, Turborepo CLI downloads E(key,artifact) and E(kms,key) from the remote cache.
5. Turborepo CLI requests the key manager to decrypt E(kms,key) to derive key
6. Turborepo CLI uses key to decrypt E(key,artifact) to derive artifact

Option 2: Turborepo CLI accepts per user public-private keys

We assume that Turborepo CLI is using a strong Public-Private key pairs associated with individual users and certified by the Team. Teams using Turborepo CLI will be responsible for establishing the authenticity of Public Keys.

For each artifact Turborepo CLI will generate a secure symmetric key artifact-secret. The artifact-secret is the AES key used to encrypt and decrypt the uploaded artifact. The artifact-secret will be encrypted with all teammates public keys and uploaded to the remote cache alongside the encrypted artifact. For N members of a team, the artifact-secret will be encrypted N times and all versions of the encrypted artifact-secret will be uploaded to the remote cache.

Additionally, the user that generated the artifact will send the signature over the SHA256 of the artifact. This is signed using the sender’s secret key.

Receivers should decrypt the artifact-secret using their own secret key and verify the signature using the sender’s public key.

graph TD;
    p1s((p1))---|Public-Private key: User 1|s1s((s1))
    p2s((p2))---|Public-Private key: User 2|s2s((s2))
    p3s((p3))---|Public-Private key: User 3|s3s((s3))

    A[\artifact\] -.-> S[User 1]
    s1((s1)) -.-> S
    p2((p2)) -.-> S
    p3((p3)) -.-> S
    ak((ak)) -.-> S

    s2((s2)) -.-> R2[User 2]
    p12((p1)) -.-> R2

    s3((s3)) -.-> R3[User 3]
    p13((p1)) -.-> R3

graph LR;
    S[User 1]
    C[(Remote Cache)]
    R2[User 2]
    R3[User 3]
    AD[\artifact\]
    V2("Verify(p1,Sign(s1, SHA(artifact)))")
    D2("Decrypt(Decrypt(s2, E(p2,ak)), E(ak, artifact))")
    D3("Decrypt(Decrypt(s3, E(p3,ak)), E(ak, artifact))")
    V3("Verify(p1,Sign(s1, SHA(artifact)))")

    S-->|"E(ak, artifact) <br/> E(p1, ak) <br/> E(p2, ak) <br/> E(p3, ak) <br/> Sign(s1, SHA(artifact))"|C
    C-->|"E(ak, artifact) <br/> E(p1, ak) <br/> E(p2, ak) <br/> E(p3, ak) <br/> Sign(s1, SHA(artifact))"|R2
    C-->|"E(ak, artifact) <br/> E(p1, ak) <br/> E(p2, ak) <br/> E(p3, ak) <br/> Sign(s1, SHA(artifact))"|R3
    
    R2-.->V2-.->|verified|AD
    R2-.->D2-.->|decrypted|AD
    R3-.->D3-.->|decrypted|AD
    R3-.->V3-.->|verified|AD

Turborepo CLI will computes the following for each artifact and append the values as headers to the Remote Cache uploads.

• x-artifact-artifact-secret-keys
  • A mapping of userIds to public-key encrypted symmetric key.
• x-artifact-signature
  • The signature of the SHA256 of the artifact. Signed using the secret key from the user that generated the artifact.

Option 3: Turborepo CLI accepts versioned symmetric keys

We should use AES-GCM with 256 bit symmetric keys. This is the NIST recommended method for authenticated encryption with associated data. Turborepo is written in GO, and there is a standard crypto library implementation of this algorithm that can be used to encrypt and decrypt artifacts. AES-GCM allows for authenticating plaintext Associated Data on the ciphertext which is used below.

The impact here is that the symmetric key used to encrypt and decrypt the artifacts will need to be distributed to teammates using Turborepo CLI.

Enable Encryption on Turborepo CLI

Turborepo will specify an enableEncryption: boolean flag on the turbo.json config. When this flag is present, all uploaded and downloaded artifacts are expected to be encrypted.

Aside Out of Scope: The Vercel Remote Cache API, can go a step further and minimally reject any unencrypted artifacts sent by clients. This can be done by verifying the associated data on the encrypted artifact and rejecting if it’s not valid. This would be configured by a user who is Vercel Admin. Note Vercel backend doesn’t need the secret key to inspect the Associated Data since it is plaintext. This is not strictly secure, but could be used to catch mistakes made on the Turborepo CLI config side if a user accidentally disabled their encryption.

Turborepo CLI Accepts User provided secret keys

Getting the Key

Yet to be determined what will be easiest for users to expose the secret key from their machine to the Turborepo CLI. Some options include:

1. turbo.json path to local file config where keys are stored
2. turbo.json configured environment variable where key is accessible
3. Turborepo CLI accepts the key as a command line input on each run
4. Turborepo CLI asks for key once and stores it on global config store on the user machine.

Alternatively, the CLI can follow a pattern like Viper and support decreasing precedence lookups for the token.

From Greg:
Libraries like https://github.com/spf13/viper support, in order of decreasing precedence, command line flags, environment variables, and config files.

We could take a similar approach. Require a key in turbo.json with a path, and apply overrides as appropriate. Teams that don’t want to use a file can put in a bogus path and override via environment or command line.

Key Format

The BYOK secret key must be a 32 byte (256 bit) AES key.
Turborepo will version secret keys used in encryption. This version will be stored on the turbo.json config. The version is semver style major.minor. Note that the secret key is not stored on the turbo.json config, only the version. This version can be attached to the associated data on the encrypted artifact. This is useful for processing key rotations and signaling to users that they’re using an expired secret key.

This means that technically Turborepo CLI can support re-encryption of downloaded artifacts after key-rotation, though this may not be desired.

If the secret key is rotated, Turborepo can take advantage of secret key versioning to decrypt artifacts that were encrypted using the old key. When any new artifacts are created they will always be encrypted with the most recent version specified on the turbo.json config.

Turborepo CLI handles Decryption

If an artifact is downloaded and the secret-key version on the associated data is a version used to the decrypt the artifact, then it must successfully decrypt. Otherwise, Turborepo CLI should throw an error.

If the secret key version of a downloaded artifact is more recent than the version on the turbo.json config then an error is thrown with message indicating they don’t have most recent key.

If the secret key version of a downloaded artifact is older than the most recent version of the key on the turbo.json we can either:

• Decrypt the artifact if the user has the older versioned secret key.
• Ignore the artifact even if the user has the older versioned secret key.

Whether or not Turborepo CLI decrypts is based on the difference in versions. If the artifact is a major version away then the artifact is not decrypted. If the artifact is only a minor version away, then the artifact can be decrypted if the Turborepo CLI has access to the key.

[Xenfo]

On top of BYOK we could have a command to generate a key for the computer/project automatically for users that don't necessarily care what key is used.

[gaspar09]

Thank you @Xenfo .

So far the scope assumes that a key is provided. I don't think it will be too difficult to do something like this in the future. Once the initial part lands, I can cycle back.

[weyert]

Thanks for this proposal, looks interesting. Will you also document how to leverage BYOK for users that uses their own custom cache server? For example, https://github.com/Tapico/tapico-turborepo-remote-cache