Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ jobs:
checks:
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
id-token: write

steps:
- name: checkout
Expand All @@ -47,7 +50,16 @@ jobs:
run: npm run format

- name: test
run: npm run test:cov
run: npm run test:cov -- --coverage.reporter=text --coverage.reporter=lcov

# Coverage report to Codecov (OIDC, no token). Never fails the build: forks get no OIDC token.
- name: codecov
if: always() && !cancelled()
uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
with:
use_oidc: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}
files: ./coverage/lcov.info
fail_ci_if_error: false

- name: build
run: npm run build
Expand Down
28 changes: 23 additions & 5 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,12 +58,22 @@ jobs:
permissions:
contents: read
id-token: write
env:
TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}

steps:
# Release tags are vX.Y.Z; anything else (e.g. a mistyped workflow_dispatch input) stops the job.
- name: validate-tag
run: |
if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::Invalid release tag: must match ^v[0-9]+\.[0-9]+\.[0-9]+\$"
exit 1
fi

- name: checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}
ref: ${{ env.TAG }}
persist-credentials: false

- name: setup-node
Expand Down Expand Up @@ -106,8 +116,8 @@ jobs:
path: ${{ steps.pack.outputs.file }}
retention-days: 5

# Release assets: CycloneDX SBOM of the production dependency tree, the npm tarball and its
# signed build provenance (Sigstore bundle from actions/attest-build-provenance).
# Release assets: CycloneDX SBOM of the production dependency tree (bootgs-utils-<version>.cdx.json),
# the npm tarball and its signed build provenance (Sigstore bundle from actions/attest-build-provenance).
sbom:
needs: [release-please, publish]
if: >-
Expand All @@ -122,6 +132,14 @@ jobs:
TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || needs.release-please.outputs.tag_name }}

steps:
# Release tags are vX.Y.Z; anything else (e.g. a mistyped workflow_dispatch input) stops the job.
- name: validate-tag
run: |
if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::Invalid release tag: must match ^v[0-9]+\.[0-9]+\.[0-9]+\$"
exit 1
fi

- name: checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
Expand All @@ -137,7 +155,7 @@ jobs:
run: npm ci --ignore-scripts

- name: sbom
run: npm sbom --sbom-format cyclonedx --omit dev > sbom.cdx.json
run: npm sbom --sbom-format cyclonedx --omit dev > "bootgs-utils-${TAG#v}.cdx.json"

- name: download-package
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
Expand All @@ -158,4 +176,4 @@ jobs:
run: |
tgz=$(ls package/*.tgz)
cp "$BUNDLE" "$tgz.sigstore.json"
gh release upload "$TAG" sbom.cdx.json "$tgz" "$tgz.sigstore.json" --clobber --repo "$GITHUB_REPOSITORY"
gh release upload "$TAG" "bootgs-utils-${TAG#v}.cdx.json" "$tgz" "$tgz.sigstore.json" --clobber --repo "$GITHUB_REPOSITORY"
41 changes: 37 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Great that you are here and you want to contribute to **@bootgs/utils**!
- [2. PR Specific Requirements](#2-pr-specific-requirements)
- [Test Suite](#test-suite)
- [README Translations](#readme-translations)
- [Dependencies](#dependencies)
- [License](#license)

<!-- TOC -->
Expand All @@ -44,6 +45,8 @@ The project is organized as follows:
- [**`src/`**](src/) — Source code of the library. Organized into logical modules like `appsscript/`, `lang/`, `net/`, etc.
- [**`test/`**](test/) — Test suites mirroring the `src` structure.

How the modules in `src/` fit together is described in [Design](docs/design.md).

## Development Setup

### Requirements
Expand All @@ -61,16 +64,16 @@ The project is organized as follows:
1. **Fork** the repository on GitHub.
2. **Clone** your fork locally:
```bash
git clone https://github.com/<your_username>/apps-script-utils.git
cd @bootgs/utils
git clone https://github.com/<your_username>/utils.git
cd utils
```
3. **Add upstream remote**:
```bash
git remote add upstream https://github.com/bootgs/utils.git
```
4. **Install dependencies**:
4. **Install dependencies** from the lockfile:
```bash
npm install
npm ci
```
5. **Build the project**:
```bash
Expand Down Expand Up @@ -280,6 +283,36 @@ Chinese (`zh-TW`). Corrections from native speakers are welcome as ordinary pull
a different number of `##`/`###` headings than `README.md`, or its note names a version other than the one in
`package.json`. It does not compare wording.

## Dependencies

**Obtaining.** Dependencies come from the npm registry. `package-lock.json` is committed and pins every direct and
transitive version with its integrity hash; install with `npm ci`, which installs exactly what the lockfile says.
Commit `package.json` and `package-lock.json` together whenever a dependency changes.

**Selecting.** The published package has no runtime dependencies: `package.json` declares only `devDependencies`
(build, lint, test, documentation), and none of them is shipped. A new dependency needs a reason in the issue or
pull request and must be:

- free/open-source software; a runtime dependency must use a licence on the CI allow-list: `Apache-2.0`, `MIT`,
`BSD-2-Clause`, `BSD-3-Clause`, `ISC` or `0BSD` (the `licences` step in [ci.yml](.github/workflows/ci.yml) fails
otherwise);
- actively maintained (recent releases, issues answered) and without known high or critical vulnerabilities;
- small for what it does: prefer a few lines of our own code over a package for a trivial helper. Adding the first
runtime dependency is a larger change and starts with an issue (see [GOVERNANCE.md](GOVERNANCE.md#decision-making)).

**Tracking.**

- [Dependabot](.github/dependabot.yml) checks npm packages and GitHub Actions weekly and opens pull requests against
`develop`. Minor and patch updates of development dependencies are grouped into one pull request
(`dev-dependencies`); other npm updates and GitHub Actions updates arrive as one pull request each. Dependabot
security updates are enabled for the repository.
- CI runs `npm audit --omit=dev --audit-level=high` on every pull request and push to `main` and `develop`, so a
known high or critical vulnerability in a runtime dependency fails the build.
- GitHub Actions in workflows are pinned to full commit SHAs, with the version in a comment.
- [OpenSSF Scorecard](.github/workflows/scorecard.yml) runs weekly and on pushes to `main`, and reports supply-chain
issues such as unpinned dependencies to code scanning.
- Each GitHub release carries a CycloneDX SBOM of the runtime dependency tree.

## License

By contributing to **@bootgs/utils**, you agree that your contributions will be licensed under
Expand Down
6 changes: 6 additions & 0 deletions GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,12 @@ discussions — may be invited to become maintainers. You can also ask: open a d
maintainer. New maintainers are added to [MAINTAINERS.md](MAINTAINERS.md) through a pull request and receive
access step by step (triage, then write, then release).

Before anyone receives write or admin access to the repository or organisation, or npm publishing rights, the lead
maintainer reviews them: a track record of merged contributions, two-factor authentication on their GitHub and npm
accounts, and agreement to handle vulnerabilities as described in [SECURITY.md](SECURITY.md). Access is reviewed
whenever a role changes and removed when it is no longer needed. Current access is listed in
[MAINTAINERS.md](MAINTAINERS.md#access-to-sensitive-resources).

Maintainers who are inactive for 12 months may be moved to emeritus status, with thanks.

## Continuity
Expand Down
13 changes: 13 additions & 0 deletions MAINTAINERS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,17 @@
| :-------------- | :--------------------------------------------------- | :-------------- |
| Maksym Stoianov | [@MaksymStoianov](https://github.com/MaksymStoianov) | Lead maintainer |

## Access to sensitive resources

| Resource | Who has access |
| :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub organisation `bootgs` and repository `bootgs/utils` | Owner/admin: @MaksymStoianov |
| npm package `@bootgs/utils` (publishing) | npm account `maksymstoianov` (@MaksymStoianov), the only maintainer on the registry. CI publishes with npm trusted publishing (OIDC) from the `publish` job of `release-please.yml` in the environment `npm`, which deploys only from `main`; no npm token is stored in GitHub |
| GitHub Actions secrets | None are stored in the repository or its environments. Workflows use only the per-run `GITHUB_TOKEN` (`release-please.yml` passes it to release-please and to `gh release upload`, `docs.yml` uses it to push the `docs-archive` branch), with permissions declared per job; Codecov uploads use OIDC |
| Documentation site [bootgs.github.io/utils](https://bootgs.github.io/utils/) | Deployed by `docs.yml` through GitHub Pages in the environment `github-pages`, which deploys only from `main`; repository admins |
| Security advisories and private vulnerability reports | Maintainers listed above (repository admins) |
| Emergency access to the organisation and the npm package | A trusted backup person, only to keep the project available (see [Continuity](GOVERNANCE.md#continuity)) |

Access is granted and reviewed as described in [GOVERNANCE.md](GOVERNANCE.md#becoming-a-maintainer).

See [GOVERNANCE.md](GOVERNANCE.md) for how decisions are made and how to become a maintainer.
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,14 @@
</small>
</p>

**English** | [Українська](docs/readme/README.uk.md) | [Русский](docs/readme/README.ru.md) | [Deutsch](docs/readme/README.de.md) | [Français](docs/readme/README.fr.md) | [Español](docs/readme/README.es.md) | [Português](docs/readme/README.pt.md) | [Italiano](docs/readme/README.it.md) | [Nederlands](docs/readme/README.nl.md) | [Polski](docs/readme/README.pl.md) | [Čeština](docs/readme/README.cs.md) | [Türkçe](docs/readme/README.tr.md) | [العربية](docs/readme/README.ar.md) | [Bahasa Indonesia](docs/readme/README.id.md) | [Tiếng Việt](docs/readme/README.vi.md) | [日本語](docs/readme/README.ja.md) | [한국어](docs/readme/README.ko.md) | [简体中文](docs/readme/README.zh.md) | [繁體中文](docs/readme/README.zh-TW.md)
**English** | [العربية](docs/readme/README.ar.md) | [Čeština](docs/readme/README.cs.md) | [Deutsch](docs/readme/README.de.md) | [Español](docs/readme/README.es.md) | [Français](docs/readme/README.fr.md) | [Bahasa Indonesia](docs/readme/README.id.md) | [Italiano](docs/readme/README.it.md) | [日本語](docs/readme/README.ja.md) | [한국어](docs/readme/README.ko.md) | [Nederlands](docs/readme/README.nl.md) | [Polski](docs/readme/README.pl.md) | [Português](docs/readme/README.pt.md) | [Русский](docs/readme/README.ru.md) | [Türkçe](docs/readme/README.tr.md) | [Українська](docs/readme/README.uk.md) | [Tiếng Việt](docs/readme/README.vi.md) | [简体中文](docs/readme/README.zh.md) | [繁體中文](docs/readme/README.zh-TW.md)

# Utilities for Google Apps Script™

<p align="left">
<a href="https://github.com/bootgs/utils/actions/workflows/ci.yml"><img src="https://github.com/bootgs/utils/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
<a href="https://github.com/bootgs/utils/actions/workflows/codeql.yml"><img src="https://github.com/bootgs/utils/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL"></a>
<a href="https://codecov.io/gh/bootgs/utils"><img src="https://codecov.io/gh/bootgs/utils/graph/badge.svg" alt="Codecov"></a>
<a href="https://scorecard.dev/viewer/?uri=github.com/bootgs/utils"><img src="https://api.scorecard.dev/projects/github.com/bootgs/utils/badge" alt="OpenSSF Scorecard"></a>
<a href="https://api.reuse.software/info/github.com/bootgs/utils"><img src="https://api.reuse.software/badge/github.com/bootgs/utils" alt="REUSE status"></a>
<a href="https://www.bestpractices.dev/projects/16865"><img src="https://www.bestpractices.dev/projects/16865/badge" alt="OpenSSF Best Practices"></a>
Expand Down
63 changes: 63 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,69 @@ Out of scope: vulnerabilities in Google Apps Script itself or other Google servi
upstream; we will update the dependency), and in scripts built with the library that are caused by their own code
or configuration.

## Verifying a Release

**npm package.** After installing, check the registry signatures (and provenance attestations, where present) of
your dependency tree:

```bash
npm audit signatures
```

The release workflow publishes new versions from GitHub Actions with
[npm provenance](https://docs.npmjs.com/generating-provenance-statements); the provenance shown on
[npmjs.com/package/@bootgs/utils](https://www.npmjs.com/package/@bootgs/utils) names the repository `bootgs/utils`,
the workflow `.github/workflows/release-please.yml` and the commit the version was built from. `3.0.0`, the first
version under the new name, was published by hand and has a registry signature but no npm provenance; its tarball
is the same file as the attested GitHub release asset below (compare `npm view @bootgs/utils@3.0.0 dist.shasum` with
`shasum bootgs-utils-3.0.0.tgz`).

**GitHub release assets.** Releases from `v3.0.0` on carry the npm tarball `bootgs-utils-<version>.tgz` and its
Sigstore build provenance `bootgs-utils-<version>.tgz.sigstore.json`, plus a CycloneDX SBOM of the runtime
dependency tree (`sbom.cdx.json` in `v3.0.0`, `bootgs-utils-<version>.cdx.json` in later releases). Earlier
releases have no assets. Verify a downloaded tarball with the [GitHub CLI](https://cli.github.com/):

```bash
gh attestation verify bootgs-utils-<version>.tgz --repo bootgs/utils \
--signer-workflow bootgs/utils/.github/workflows/release-please.yml
```

Add `--bundle bootgs-utils-<version>.tgz.sigstore.json` to verify against the downloaded bundle instead of fetching
the attestation from GitHub. The attestation is valid only if it was signed by the `release-please.yml` workflow of
`bootgs/utils`, which runs on pushes to `main` (or a manual run for an existing tag).

## Secrets and Credentials

- No long-lived publishing credential exists: npm publishing uses
[trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC) from the `npm` environment.
- No secrets are stored in the repository or its environments. Workflows use only the per-run `GITHUB_TOKEN`, with
permissions declared per job (`release-please.yml` and `docs.yml` reference `secrets.GITHUB_TOKEN`; no other
secret is referenced). Codecov uploads authenticate with OIDC.
- If a secret becomes necessary, it is stored only as a GitHub Actions secret scoped to an environment, is
accessible to maintainers only, and is rotated at least once a year and immediately on suspected exposure.
- GitHub secret scanning and push protection are enabled for the repository.
- Who has access to these resources: [MAINTAINERS.md](MAINTAINERS.md#access-to-sensitive-resources).

## Dependency and Code Scanning Policy

**Software composition analysis (SCA).**
[ci.yml](.github/workflows/ci.yml) runs on every pull request and on pushes to `main` and `develop`:

- `npm audit --omit=dev --audit-level=high` — a high or critical vulnerability in a runtime dependency fails the
`checks` job;
- the `licences` step — a runtime dependency outside the allow-list (`Apache-2.0`, `MIT`, `BSD-2-Clause`,
`BSD-3-Clause`, `ISC`, `0BSD`) fails the `checks` job.

`checks` is a required status check for pull requests into `develop`, so either failure blocks merging. Moderate
and low findings are fixed within 30 days or before the next release, whichever comes first, usually through
[Dependabot](.github/dependabot.yml) updates. No release is made while an SCA violation is open.

**Static analysis (SAST).** [CodeQL](.github/workflows/codeql.yml) analyses JavaScript/TypeScript and GitHub Actions
on every pull request and push to `main` and `develop` and weekly; ESLint with `eslint-plugin-security` runs in the
`checks` job. High and critical CodeQL alerts are fixed before merging, medium ones before the next release. A
finding may be dismissed only as a false positive or not exploitable, with the reason written in the alert. CodeQL
is not a required status check; these thresholds are applied through maintainer review of every pull request.

## Security Best Practices for Users

1. **Keep dependencies updated:** use the latest `@bootgs/utils` release and keep other packages current.
Expand Down
15 changes: 15 additions & 0 deletions codecov.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Codecov: https://docs.codecov.com/docs/codecov-yaml
coverage:
status:
project:
default:
target: auto
threshold: 1%
patch:
default:
target: auto
threshold: 1%

comment:
layout: "diff, files"
require_changes: true
Loading
Loading