@wabicloud/turborepo-remote-cache-serverless 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wabicloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @wabicloud/turborepo-remote-cache-serverless
+
+An AWS CDK construct that deploys a fully serverless Turborepo remote cache using S3, Lambda, and Secrets Manager. No servers to manage, scales to zero, costs almost nothing for small teams.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @wabicloud/turborepo-remote-cache-serverless
+```
+
+### Add to your CDK stack
+
+```typescript
+import { TurborepoRemoteCache } from "@wabicloud/turborepo-remote-cache-serverless";
+
+const cache = new TurborepoRemoteCache(this, "TurboCache");
+
+new cdk.CfnOutput(this, "TurboCacheUrl", {
+  value: cache.functionUrl.url,
+});
+```
+
+### Deploy
+
+```bash
+cdk deploy
+```
+
+### Generate a token
+
+```bash
+npx wabicloud-turbo-cache generate-token \
+  --team team_myproject \
+  --secret-name turborepo/cache-token \
+  --region us-east-1
+```
+
+### Configure Turborepo
+
+```bash
+export TURBO_API="https://<your-function-url>"
+export TURBO_TOKEN="<generated-token>"
+export TURBO_TEAM="team_myproject"
+
+pnpm turbo build --preflight
+```
+
+## Configuration
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `expiration` | `Duration` | 30 days | How long cached artifacts are kept |
+| `secretName` | `string` | `turborepo/cache-token` | Secrets Manager secret name |
+
+```typescript
+new TurborepoRemoteCache(this, "TurboCache", {
+  expiration: cdk.Duration.days(7),
+  secretName: "my-project/turbo-token",
+});
+```
+
+## How It Works
+
+The construct creates:
+
+- **S3 bucket** - stores cached build artifacts with automatic expiration
+- **Lambda function** with a public Function URL - handles Turborepo's remote cache API
+- **Secrets Manager secret** - holds the JWT signing key for token authentication
+
+Turborepo uses `--preflight` mode: it sends an OPTIONS request to get a presigned S3 URL, then uploads/downloads directly to S3. This means the Lambda only handles lightweight auth + URL generation, while S3 handles the heavy lifting.
+
+## CLI Reference
+
+```
+wabicloud-turbo-cache generate-token
+
+Flags:
+  --team          Team ID (must start with "team_")       [required]
+  --secret-name   Secrets Manager secret name              [default: turborepo/cache-token]
+  --region        AWS region                               [default: us-east-1]
+```
+
+Uses the standard AWS credential chain. Set `AWS_PROFILE` for named profiles.
+
+## Exposed Properties
+
+The construct exposes these for further customization:
+
+- `cache.functionUrl` - Lambda Function URL (use `.url` for the endpoint)
+- `cache.secret` - Secrets Manager secret
+- `cache.bucket` - S3 bucket
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+// bin/cli.ts
+import { SignJWT } from "jose";
+import {
+  SecretsManagerClient,
+  GetSecretValueCommand
+} from "@aws-sdk/client-secrets-manager";
+function usage() {
+  console.error(`Usage: turborepo-remote-cache-serverless generate-token \\
+  --team <team_id> \\
+  --secret-name <secret_name> \\
+  --region <aws_region>
+
+Flags:
+  --team         Team ID (must start with "team_"), e.g. team_myproject
+  --secret-name  Secrets Manager secret name (default: turborepo/cache-token)
+  --region       AWS region (default: us-east-1)
+
+Uses the standard AWS credential chain (env vars, profiles, instance roles).
+Set AWS_PROFILE to use a named profile.`);
+  process.exit(1);
+}
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  if (args[0] !== "generate-token") {
+    console.error(`Unknown command: ${args[0] ?? "(none)"}`);
+    usage();
+  }
+  let team;
+  let secretName = "turborepo/cache-token";
+  let region = "us-east-1";
+  for (let i = 1; i < args.length; i++) {
+    switch (args[i]) {
+      case "--team":
+        team = args[++i];
+        break;
+      case "--secret-name":
+        secretName = args[++i];
+        break;
+      case "--region":
+        region = args[++i];
+        break;
+      default:
+        console.error(`Unknown flag: ${args[i]}`);
+        usage();
+    }
+  }
+  if (!team) {
+    console.error("Error: --team is required");
+    usage();
+  }
+  if (!/^team_\w+$/.test(team)) {
+    console.error(
+      'Error: Team ID must start with "team_" followed by alphanumeric characters'
+    );
+    console.error("Example: team_wabicloud, team_myproject");
+    process.exit(1);
+  }
+  return { team, secretName, region };
+}
+async function main() {
+  const { team, secretName, region } = parseArgs(process.argv);
+  const client = new SecretsManagerClient({ region });
+  const response = await client.send(
+    new GetSecretValueCommand({ SecretId: secretName })
+  );
+  const jwtSecret = response.SecretString;
+  if (!jwtSecret) {
+    console.error(
+      "Error: Could not retrieve JWT secret from Secrets Manager"
+    );
+    process.exit(1);
+  }
+  const secretKey = new TextEncoder().encode(jwtSecret);
+  const token = await new SignJWT({ teamId: team }).setProtectedHeader({ alg: "HS256" }).setIssuedAt().sign(secretKey);
+  console.log("\n=== Turborepo Remote Cache Token ===\n");
+  console.log(`Team: ${team}
+`);
+  console.log("Add these to your environment:\n");
+  console.log(`export TURBO_TOKEN="${token}"`);
+  console.log(`export TURBO_TEAM="${team}"`);
+  console.log(
+    "\nSet TURBO_API to your Function URL, then run: pnpm turbo build --preflight\n"
+  );
+}
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/dist/handler/index.mjs

@@ -0,0 +1 @@
+import{S3Client as h,HeadObjectCommand as p}from"@aws-sdk/client-s3";import{S3RequestPresigner as y}from"@aws-sdk/s3-request-presigner";import{Hash as C}from"@smithy/hash-node";import{HttpRequest as w}from"@smithy/protocol-http";import{parseUrl as E}from"@smithy/url-parser";import{formatUrl as S}from"@aws-sdk/util-format-url";import{SecretsManagerClient as T,GetSecretValueCommand as b}from"@aws-sdk/client-secrets-manager";import{fromNodeProviderChain as P}from"@aws-sdk/credential-providers";import*as f from"jose";var R=new h({}),N=new T({}),g=process.env.CACHE_BUCKET,l=process.env.AWS_REGION||"eu-central-1",I=process.env.TURBO_TOKEN_SECRET_ARN,U=3600,d=null;async function A(){return d||(d=(await N.send(new b({SecretId:I}))).SecretString,d)}async function O(e,n){let r=e.replace("Bearer ",""),s=new TextEncoder().encode(n),{payload:o}=await f.jwtVerify(r,s),t=o.teamId;if(!t||!/^team_\w+$/.test(t))throw new Error("Invalid token: missing or invalid teamId");return{teamId:t}}async function q(e,n,r){let s=new y({credentials:P(),region:l,sha256:C.bind(null,"sha256")}),o=E(`https://${g}.s3.${l}.amazonaws.com/${n}`),t=new w({...o,method:e});t.query={...t.query,slug:r};let a=await s.presign(t,{expiresIn:U});return S(a).replace("&slug="+encodeURIComponent(r),"")}var k=async e=>{let{method:n,path:r}=e.requestContext.http;if(n==="GET"&&r==="/v8/artifacts/status")return{statusCode:200,body:JSON.stringify({enabled:!0})};if(n==="POST"&&r==="/v8/artifacts/events")return{statusCode:200,body:"{}"};let s=r.match(/^\/v8\/artifacts\/([a-f0-9]+)$/);if(!s)return{statusCode:404,body:"Not found"};let o=await A(),t=e.headers.authorization||"",a;try{a=(await O(t,o)).teamId}catch{return{statusCode:401,body:"Unauthorized"}}let u=s[1],m=`${a}/${u}`;if(n==="OPTIONS"){let i=e.headers["access-control-request-method"]||e.headers["Access-Control-Request-Method"];if(i==="GET")try{await R.send(new p({Bucket:g,Key:m}))}catch(c){if(c instanceof Error&&(c.name==="NotFound"||c.name==="NoSuchKey"))return{statusCode:404,body:"Not found"};throw c}return i==="GET"||i==="PUT"?{statusCode:200,headers:{location:await q(i,m,a),"Access-Control-Allow-Origin":"*","Access-Control-Allow-Methods":"GET, PUT, OPTIONS","Access-Control-Allow-Headers":"Content-Type, User-Agent, x-artifact-duration, x-artifact-tag"},body:""}:{statusCode:404,body:"Not found"}}return{statusCode:404,body:"Not found"}};export{k as handler};

package/dist/index.cjs

@@ -0,0 +1,106 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TurborepoRemoteCache: () => TurborepoRemoteCache
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/construct.ts
+var cdk = __toESM(require("aws-cdk-lib"), 1);
+var s3 = __toESM(require("aws-cdk-lib/aws-s3"), 1);
+var lambda = __toESM(require("aws-cdk-lib/aws-lambda"), 1);
+var logs = __toESM(require("aws-cdk-lib/aws-logs"), 1);
+var secretsmanager = __toESM(require("aws-cdk-lib/aws-secretsmanager"), 1);
+var import_constructs = require("constructs");
+var import_node_path = require("path");
+var TurborepoRemoteCache = class extends import_constructs.Construct {
+  /** The Lambda Function URL endpoint (use as TURBO_API). */
+  functionUrl;
+  /** The Secrets Manager secret holding the JWT signing key. */
+  secret;
+  /** The S3 bucket storing cached artifacts. */
+  bucket;
+  constructor(scope, id, props = {}) {
+    super(scope, id);
+    const {
+      expiration = cdk.Duration.days(30),
+      secretName = "turborepo/cache-token"
+    } = props;
+    this.bucket = new s3.Bucket(this, "CacheBucket", {
+      encryption: s3.BucketEncryption.S3_MANAGED,
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      lifecycleRules: [{ expiration }],
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      autoDeleteObjects: true,
+      cors: [
+        {
+          allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.PUT],
+          allowedOrigins: ["*"],
+          allowedHeaders: ["*"],
+          maxAge: 3e3
+        }
+      ]
+    });
+    this.secret = new secretsmanager.Secret(this, "TurboToken", {
+      secretName,
+      generateSecretString: {
+        excludePunctuation: true,
+        passwordLength: 32
+      }
+    });
+    const cacheHandler = new lambda.Function(this, "CacheHandler", {
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambda.Code.fromAsset((0, import_node_path.join)(__dirname, "handler")),
+      memorySize: 1024,
+      timeout: cdk.Duration.seconds(30),
+      environment: {
+        CACHE_BUCKET: this.bucket.bucketName,
+        TURBO_TOKEN_SECRET_ARN: this.secret.secretArn
+      }
+    });
+    new logs.LogGroup(this, "CacheHandlerLogGroup", {
+      logGroupName: `/aws/lambda/${cacheHandler.functionName}`,
+      retention: logs.RetentionDays.ONE_MONTH,
+      removalPolicy: cdk.RemovalPolicy.DESTROY
+    });
+    this.bucket.grantReadWrite(cacheHandler);
+    this.secret.grantRead(cacheHandler);
+    this.functionUrl = cacheHandler.addFunctionUrl({
+      authType: lambda.FunctionUrlAuthType.NONE
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TurborepoRemoteCache
+});

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import * as cdk from 'aws-cdk-lib';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import { Construct } from 'constructs';
+
+interface TurborepoRemoteCacheProps {
+    /**
+     * How long cached artifacts are kept before automatic deletion.
+     * @default Duration.days(30)
+     */
+    readonly expiration?: cdk.Duration;
+    /**
+     * Name of the Secrets Manager secret that stores the JWT signing key.
+     * @default 'turborepo/cache-token'
+     */
+    readonly secretName?: string;
+}
+declare class TurborepoRemoteCache extends Construct {
+    /** The Lambda Function URL endpoint (use as TURBO_API). */
+    readonly functionUrl: lambda.FunctionUrl;
+    /** The Secrets Manager secret holding the JWT signing key. */
+    readonly secret: secretsmanager.Secret;
+    /** The S3 bucket storing cached artifacts. */
+    readonly bucket: s3.Bucket;
+    constructor(scope: Construct, id: string, props?: TurborepoRemoteCacheProps);
+}
+
+export { TurborepoRemoteCache, type TurborepoRemoteCacheProps };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import * as cdk from 'aws-cdk-lib';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import { Construct } from 'constructs';
+
+interface TurborepoRemoteCacheProps {
+    /**
+     * How long cached artifacts are kept before automatic deletion.
+     * @default Duration.days(30)
+     */
+    readonly expiration?: cdk.Duration;
+    /**
+     * Name of the Secrets Manager secret that stores the JWT signing key.
+     * @default 'turborepo/cache-token'
+     */
+    readonly secretName?: string;
+}
+declare class TurborepoRemoteCache extends Construct {
+    /** The Lambda Function URL endpoint (use as TURBO_API). */
+    readonly functionUrl: lambda.FunctionUrl;
+    /** The Secrets Manager secret holding the JWT signing key. */
+    readonly secret: secretsmanager.Secret;
+    /** The S3 bucket storing cached artifacts. */
+    readonly bucket: s3.Bucket;
+    constructor(scope: Construct, id: string, props?: TurborepoRemoteCacheProps);
+}
+
+export { TurborepoRemoteCache, type TurborepoRemoteCacheProps };

package/dist/index.js

@@ -0,0 +1,76 @@
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
+// src/construct.ts
+import * as cdk from "aws-cdk-lib";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as logs from "aws-cdk-lib/aws-logs";
+import * as secretsmanager from "aws-cdk-lib/aws-secretsmanager";
+import { Construct } from "constructs";
+import { join } from "path";
+var TurborepoRemoteCache = class extends Construct {
+  /** The Lambda Function URL endpoint (use as TURBO_API). */
+  functionUrl;
+  /** The Secrets Manager secret holding the JWT signing key. */
+  secret;
+  /** The S3 bucket storing cached artifacts. */
+  bucket;
+  constructor(scope, id, props = {}) {
+    super(scope, id);
+    const {
+      expiration = cdk.Duration.days(30),
+      secretName = "turborepo/cache-token"
+    } = props;
+    this.bucket = new s3.Bucket(this, "CacheBucket", {
+      encryption: s3.BucketEncryption.S3_MANAGED,
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      lifecycleRules: [{ expiration }],
+      removalPolicy: cdk.RemovalPolicy.DESTROY,
+      autoDeleteObjects: true,
+      cors: [
+        {
+          allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.PUT],
+          allowedOrigins: ["*"],
+          allowedHeaders: ["*"],
+          maxAge: 3e3
+        }
+      ]
+    });
+    this.secret = new secretsmanager.Secret(this, "TurboToken", {
+      secretName,
+      generateSecretString: {
+        excludePunctuation: true,
+        passwordLength: 32
+      }
+    });
+    const cacheHandler = new lambda.Function(this, "CacheHandler", {
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "index.handler",
+      code: lambda.Code.fromAsset(join(__dirname, "handler")),
+      memorySize: 1024,
+      timeout: cdk.Duration.seconds(30),
+      environment: {
+        CACHE_BUCKET: this.bucket.bucketName,
+        TURBO_TOKEN_SECRET_ARN: this.secret.secretArn
+      }
+    });
+    new logs.LogGroup(this, "CacheHandlerLogGroup", {
+      logGroupName: `/aws/lambda/${cacheHandler.functionName}`,
+      retention: logs.RetentionDays.ONE_MONTH,
+      removalPolicy: cdk.RemovalPolicy.DESTROY
+    });
+    this.bucket.grantReadWrite(cacheHandler);
+    this.secret.grantRead(cacheHandler);
+    this.functionUrl = cacheHandler.addFunctionUrl({
+      authType: lambda.FunctionUrlAuthType.NONE
+    });
+  }
+};
+export {
+  TurborepoRemoteCache
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@wabicloud/turborepo-remote-cache-serverless",
+  "version": "0.1.0",
+  "description": "AWS CDK construct for deploying a Turborepo remote cache backed by S3 and Lambda",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "bin": {
+    "wabicloud-turbo-cache": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "turborepo",
+    "remote-cache",
+    "aws",
+    "cdk",
+    "serverless",
+    "s3",
+    "lambda"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0"
+  },
+  "dependencies": {
+    "jose": "^6.0.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/client-secrets-manager": "^3.0.0",
+    "@aws-sdk/credential-providers": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@aws-sdk/util-format-url": "^3.0.0",
+    "@smithy/hash-node": "^4.0.0",
+    "@smithy/protocol-http": "^5.0.0",
+    "@smithy/url-parser": "^4.0.0",
+    "@types/node": "^25.3.0",
+    "aws-cdk-lib": "^2.0.0",
+    "constructs": "^10.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}