AWS powertools medium security documentation change
Summary
Added documentation for reserving npm package names using temporary placeholders and Trusted Publishing, updated E2E testing instructions, and added navigation links for Data Masking and Signer features
Security assessment
The change introduces security documentation for npm package publishing using short-lived tokens and Trusted Publishing with GitHub Actions OIDC to prevent long-lived credential risks. It explicitly warns against committing tokens and emphasizes revocation, addressing credential exposure vulnerabilities.
Diff
diff --git a/powertools/typescript/latest/maintainers.md b/powertools/typescript/latest/maintainers.md index 0a8c36252..6e4f8d350 100644 --- a//powertools/typescript/latest/maintainers.md +++ b//powertools/typescript/latest/maintainers.md @@ -55,0 +56 @@ Event Handler + * [ Data Masking ](../features/data-masking/) @@ -56,0 +58 @@ Event Handler + * [ Signer ](../features/signer/) @@ -81,0 +84 @@ Event Handler + * Reserving a package name on npm @@ -120,0 +124 @@ Table of contents + * Reserving a package name on npm @@ -303,0 +308,94 @@ Some examples using our initial and new RFC templates: [#447](https://github.com +### Reserving a package name on npm¶ + +When a brand-new package is about to be merged into `main` for the first time (e.g. a new utility), its name must be manually published to npm **once** , ahead of its first real release. + +Important + +The `Make Release` workflow publishes packages using [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) via GitHub Actions OIDC, so we get provenance/attestation without storing a long-lived `NPM_TOKEN`. + +Trusted publishers can only be configured for a package that **already exists** on npm (under `npmjs.com/package/<name>/access`), so a package can't reserve its own name this way the first time around. + +A maintainer must publish an initial placeholder version manually to reserve the name and unlock Trusted Publishing for it. + +Follow these steps before the new package's first real release: + + 1. **Create a temporary local package** using the same placeholder shape adopted by every utility before its first release, for example: + +package.json +--- + + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + 10 + 11 + 12 + 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20 + +| + + { + "name": "@aws-lambda-powertools/<name>", + "version": "0.0.0", + "description": "The <name> package for the Powertools for AWS Lambda (TypeScript) library", + "author": { "name": "Amazon Web Services", "url": "https://aws.amazon.com" }, + "publishConfig": { "access": "public" }, + "homepage": "https://github.com/aws-powertools/powertools-lambda-typescript", + "license": "MIT-0", + "main": "./lib/index.js", + "types": "./lib/index.d.ts", + "files": ["lib"], + "repository": { + "type": "git", + "url": "git+https://github.com/aws-powertools/powertools-lambda-typescript.git" + }, + "bugs": { "url": "https://github.com/aws-powertools/powertools-lambda-typescript/issues" }, + "dependencies": {}, + "keywords": ["aws", "lambda", "powertools", "handler", "nodejs", "serverless"], + "devDependencies": {} + } + + +Add a `README.md` with the same "do not use this in production yet" disclaimer used by other placeholders (see [`@aws-lambda-powertools/[email protected]`](https://www.npmjs.com/package/@aws-lambda-powertools/validation/v/0.0.0) as a reference). + +Also add a `lib/index.js`/`lib/index.d.ts` pair, where the former only logs that it's a placeholder used to reserve the name. + + 2. **Authenticate locally** as an npm user who's a member of the `@aws-lambda-powertools` org with publish rights. Use a short-lived, least-privilege token and never commit it to `.npmrc` \- remove and rotate/revoke it as soon as you're done. + + 3. **Publish with the`pre` dist-tag**, not `latest`: + + 1 + +| + + npm publish --access public --tag pre + + +---|--- + +Note + +npm always assigns `latest` to the very first version ever published for a package, regardless of `--tag`. This means `0.0.0` will briefly carry both `latest` and `pre`. This is expected and self-corrects: the next real release (published without an explicit tag) will move `latest` forward, while `pre` stays pinned to `0.0.0` as a permanent marker of the placeholder. + + 4. **Configure Trusted Publishing** for the new package: go to `https://www.npmjs.com/package/<name>/access`, add a Trusted Publisher for GitHub Actions, and point it at this repository and the `make-release.yml` workflow. This is what lets `Make Release` publish real versions of this package with OIDC/provenance going forward, without ever needing an `NPM_TOKEN`. + + 5. Make sure the PR adding the new package also adds it to the `workspaces` array in the root `package.json`, and to any workflow that enumerates packages individually (e.g. `reusable-run-linting-check-and-unit-tests.yml`, `run-e2e-tests.yml`), so it's picked up by CI and by the next `Make Release` run. + + + + +Once these steps are done, the new package is released like any other in the normal release process the next time `Make Release` runs. + @@ -435,5 +533 @@ This will kick off the [Post Release workflow](https://github.com/aws-powertools -Note - -We are planning to automate this process in the future so that tests are run automatically when a PR is merged, see [#1149](https://github.com/aws-powertools/powertools-lambda-typescript/issues/1149) - -E2E tests should be ran before every merge to `main` or manually via [Run e2e Tests workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/run-e2e-tests.yml) before making a release. +E2E tests must be ran before making a release, manually via the [Run e2e Tests workflow](https://github.com/aws-powertools/powertools-lambda-typescript/actions/workflows/run-e2e-tests.yml). Maintainers should also run them manually for large contributions authored by maintainers before merging to `main`. @@ -523 +617 @@ In the rare cases where both parties don't have the bandwidth or expertise to co -2026-05-27 +2026-07-10