From 12f41d0ed0ddf1ccdd4d8acdf30f2dfef1081eae Mon Sep 17 00:00:00 2001 From: Alexander Tartmin Date: Sun, 13 Sep 2026 00:07:17 +0300 Subject: [PATCH] chore(release): prepare 0.1.0-beta.3 --- .github/workflows/release.yml | 9 +++ AGENTS.md | 2 +- CHANGELOG.md | 19 +++++- README.md | 14 +++-- SECURITY.md | 9 ++- docs/src/content.config.ts | 5 +- docs/src/content/docs/index.mdx | 2 +- .../content/docs/project/release-integrity.md | 62 +++++++++++++++++++ docs/src/content/docs/project/versioning.md | 4 +- .../docs/reference/apple-compatibility.md | 2 +- docs/src/content/i18n/en.json | 1 + package-lock.json | 4 +- package.json | 2 +- 13 files changed, 117 insertions(+), 18 deletions(-) create mode 100644 docs/src/content/docs/project/release-integrity.md create mode 100644 docs/src/content/i18n/en.json diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 778e7d5..d264146 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -101,6 +101,15 @@ jobs: with: subject-path: release/${{ steps.package.outputs.tarball }} + - name: Sign and verify every release asset + uses: sigstore/gh-action-sigstore-python@790bc6befb9d733738f18d8f895854b453640ec9 # v3.5.0 + with: + inputs: release/* + verify: true + verify-cert-identity: https://github.com/${{ github.workflow_ref }} + verify-oidc-issuer: https://token.actions.githubusercontent.com + release-signing-artifacts: false + - name: Upload immutable release bundle uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: diff --git a/AGENTS.md b/AGENTS.md index c99272a..558869f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This file is the durable engineering context for humans and coding agents workin ## Product intent -Build a small, framework-agnostic, server-side TypeScript core for Apple Profile Service profile generation, optional signing, CMS response verification, and lossless response parsing. The current release target is `0.1.0-beta.1` under the npm scope `@udid-tools`. +Build a small, framework-agnostic, server-side TypeScript core for Apple Profile Service profile generation, optional signing, CMS response verification, and lossless response parsing. The current release target is `0.1.0-beta.3` under the npm scope `@udid-tools`. MDM is a separate product boundary. Do not add MDM enrollment, APNs, check-in, commands, declarative management, SCEP orchestration, profile delivery state machines, HTTP servers, persistence, or UI code here. A future MDM package may reuse stable low-level primitives without changing this package’s Profile Service contract. diff --git a/CHANGELOG.md b/CHANGELOG.md index c148819..71edd29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,22 @@ Versioning]. Prereleases use npm's `beta` distribution tag. ## [Unreleased] +## [0.1.0-beta.3] - 2026-09-13 + +### Changed + +- Updated the runtime XML parser to `fast-xml-parser` 5.11.1 and refreshed the verified + documentation toolchain. +- Improved the documentation layout and standardized live npm, CI, security, coverage, + deployment, OpenSSF, and license badges. + +### Security + +- Added a second human CODEOWNER and conventional commit and pull-request title enforcement. +- Added keyless Sigstore signatures and verification bundles for every GitHub Release asset, in + addition to the existing checksum, CycloneDX SBOM, GitHub artifact attestation, and npm + provenance. + ## [0.1.0-beta.2] - 2026-08-24 ### Fixed @@ -30,6 +46,7 @@ Versioning]. Prereleases use npm's `beta` distribution tag. [keep a changelog]: https://keepachangelog.com/en/1.1.0/ [semantic versioning]: https://semver.org/spec/v2.0.0.html -[unreleased]: https://github.com/udid-tools/core/compare/v0.1.0-beta.2...HEAD +[unreleased]: https://github.com/udid-tools/core/compare/v0.1.0-beta.3...HEAD +[0.1.0-beta.3]: https://github.com/udid-tools/core/compare/v0.1.0-beta.2...v0.1.0-beta.3 [0.1.0-beta.2]: https://github.com/udid-tools/core/compare/v0.1.0-beta.1...v0.1.0-beta.2 [0.1.0-beta.1]: https://github.com/udid-tools/core/releases/tag/v0.1.0-beta.1 diff --git a/README.md b/README.md index b58059e..2ed96d0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # `@udid-tools/core` -[![npm version](https://img.shields.io/npm/v/%40udid-tools%2Fcore)](https://www.npmjs.com/package/@udid-tools/core) +[![npm beta version](https://img.shields.io/npm/v/%40udid-tools%2Fcore/beta?label=npm%20beta)](https://www.npmjs.com/package/@udid-tools/core) [![CI](https://github.com/udid-tools/core/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/udid-tools/core/actions/workflows/ci.yml) [![Security](https://github.com/udid-tools/core/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/udid-tools/core/actions/workflows/security.yml) [![Coverage](https://codecov.io/gh/udid-tools/core/branch/main/graph/badge.svg)](https://codecov.io/gh/udid-tools/core) @@ -11,7 +11,7 @@ Security-first TypeScript primitives for Apple Profile Service profiles: generate XML, optionally produce attached CMS/PKCS#7 SignedData, verify device responses, and parse every returned plist field without losing unknown data. -> **Beta:** `0.1.0-beta.2` is ready for evaluation. Its public API follows semantic versioning, but beta releases may still contain breaking changes. MDM is intentionally out of scope. +> **Beta:** `0.1.0-beta.3` is ready for evaluation. Its public API follows semantic versioning, but beta releases may still contain breaking changes. MDM is intentionally out of scope. ## Install @@ -101,7 +101,7 @@ The default verification mode checks RSA/SHA-1 and RSA/SHA-256 signature integri ## Capability matrix -| Capability | `0.1.0-beta.2` | +| Capability | `0.1.0-beta.3` | | ------------------------------------------- | ---------------------------------------------------------------------------------- | | Apple Profile Service payload | Supported | | Documented attributes | `UDID`, `VERSION`, `PRODUCT`, `SERIAL`, `MEID`, `IMEI`, `ICCID`, `MAC_ADDRESS_EN0` | @@ -161,6 +161,12 @@ The package deliberately defines no environment-variable contract. A consuming a Read and validate them in the application, then pass their values to `signing`. This keeps secret managers, rotation, and deployment policy outside the reusable core. +## Verify a release + +Every GitHub release includes the npm tarball, its SHA-256 checksum, a CycloneDX SBOM, and a keyless Sigstore bundle for each asset. npm also displays provenance produced by the protected GitHub Actions workflow. + +Follow the complete [release verification guide](https://udid-tools.github.io/core/project/release-integrity/) to verify the checksum, Sigstore identity, transparency-log inclusion, and GitHub artifact attestation before installation. + ## Documentation and project policy - Documentation site: @@ -169,7 +175,7 @@ Read and validate them in the application, then pass their values to `signing`. - Security policy: [`SECURITY.md`](./SECURITY.md) - Changelog: [`CHANGELOG.md`](./CHANGELOG.md) -The repository includes CI, CodeQL, dependency review, Scorecard, secret scanning guidance, release attestations, SBOM generation, npm provenance, GitHub Packages publishing, issue forms, and an algorithm-request template. Releases use semantic versioning; prereleases are published under the `beta` dist-tag. +The repository includes CI, CodeQL, dependency review, Scorecard, secret scanning guidance, keyless Sigstore release signatures, GitHub artifact attestations, SBOM generation, npm provenance, GitHub Packages publishing, issue forms, and an algorithm-request template. Releases use semantic versioning; prereleases are published under the `beta` dist-tag. ## Apple references diff --git a/SECURITY.md b/SECURITY.md index b7c1687..57fb5a4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -75,7 +75,10 @@ the detailed guarantees, exclusions, and residual risks. Official releases are produced only by the protected GitHub Actions release environment. npm publishing uses trusted publishing with OIDC; GitHub Packages uses the job-scoped `GITHUB_TOKEN`. Releases are built once and the same tarball -is published to both registries. Long-lived registry tokens must not be used. +is published to both registries. Every GitHub Release asset is keylessly signed +with Sigstore and accompanied by a verification bundle; the tarball also has a +GitHub artifact attestation and npm provenance. Long-lived registry tokens must +not be used. -Consumers should verify package provenance and pin dependencies according to -their risk model. +Consumers should follow the documented release-integrity checks and pin +dependencies according to their risk model. diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts index 7fbcf2c..2588d18 100644 --- a/docs/src/content.config.ts +++ b/docs/src/content.config.ts @@ -1,7 +1,8 @@ import { defineCollection } from "astro:content"; -import { docsLoader } from "@astrojs/starlight/loaders"; -import { docsSchema } from "@astrojs/starlight/schema"; +import { docsLoader, i18nLoader } from "@astrojs/starlight/loaders"; +import { docsSchema, i18nSchema } from "@astrojs/starlight/schema"; export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), + i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }), }; diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index abb811a..e1e71dd 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -75,5 +75,5 @@ Signing is selected by providing a complete nested `signing` object. Parsing ver - Read the [security model](/core/concepts/security-model/) before exposing an endpoint to the internet. :::caution[Beta software] -Version `0.1.0-beta.2` supports PKCS#12 RSA identities with SHA-256. Review the capability matrix before using the package in production. +Version `0.1.0-beta.3` supports PKCS#12 RSA identities with SHA-256. Review the capability matrix before using the package in production. ::: diff --git a/docs/src/content/docs/project/release-integrity.md b/docs/src/content/docs/project/release-integrity.md new file mode 100644 index 0000000..72a48cf --- /dev/null +++ b/docs/src/content/docs/project/release-integrity.md @@ -0,0 +1,62 @@ +--- +title: Release integrity +description: Verify checksums, Sigstore signatures, attestations, and npm provenance. +--- + +Official releases come only from protected, maintainer-signed annotated `v*` tags. The release +workflow builds one npm tarball, smoke-tests it as an installed consumer, and publishes those exact +bytes to npm and GitHub Packages. + +Each GitHub Release contains: + +- the package tarball; +- a SHA-256 checksum for the tarball; +- a CycloneDX SBOM; +- a `.sigstore.json` bundle beside every release asset. + +The workflow also records a GitHub artifact attestation for the tarball. npm Trusted Publishing +adds registry provenance without a long-lived npm token. + +## Verify version 0.1.0-beta.3 + +Download the immutable release assets: + +```bash +gh release download v0.1.0-beta.3 --repo udid-tools/core --dir core-release +cd core-release +``` + +Verify the tarball checksum on Linux: + +```bash +sha256sum --check udid-tools-core-0.1.0-beta.3.tgz.sha256 +``` + +On macOS, use the compatible checksum command: + +```bash +shasum --algorithm 256 --check udid-tools-core-0.1.0-beta.3.tgz.sha256 +``` + +Verify the tarball's keyless Sigstore signature, certificate identity, and transparency-log proof: + +```bash +cosign verify-blob udid-tools-core-0.1.0-beta.3.tgz \ + --bundle udid-tools-core-0.1.0-beta.3.tgz.sigstore.json \ + --certificate-identity \ + "https://github.com/udid-tools/core/.github/workflows/release.yml@refs/tags/v0.1.0-beta.3" \ + --certificate-oidc-issuer "https://token.actions.githubusercontent.com" +``` + +Repeat `cosign verify-blob` with each SBOM or checksum file and its adjacent bundle when consuming +those assets directly. Verify the GitHub artifact attestation independently: + +```bash +gh attestation verify udid-tools-core-0.1.0-beta.3.tgz \ + --repo udid-tools/core +``` + +On the npm package page, the provenance indicator must link the published version to this +repository and its protected release workflow. Treat a missing bundle, checksum mismatch, +unexpected certificate identity, failed attestation, or missing npm provenance as a release +integrity failure. diff --git a/docs/src/content/docs/project/versioning.md b/docs/src/content/docs/project/versioning.md index 78de2bd..e28e2b8 100644 --- a/docs/src/content/docs/project/versioning.md +++ b/docs/src/content/docs/project/versioning.md @@ -7,6 +7,6 @@ The package follows Semantic Versioning. The initial version is `0.1.0-beta.1`; During beta, a release may intentionally break an experimental contract, but every change is documented and versioned. The design still prefers additive fields and variants so real integrations do not churn. After a stable release, incompatible public API or behavior changes require a major version. -Release automation validates that the Git tag exactly matches `package.json`, runs all quality/security/docs checks, builds one allow-listed tarball, records SHA-256, produces a CycloneDX SBOM, attests the artifact, publishes the same bytes to npm and GitHub Packages, and creates a GitHub release. +Release automation validates that the signed Git tag exactly matches `package.json`, runs all quality/security/docs checks, builds one allow-listed tarball, records SHA-256, produces a CycloneDX SBOM, keylessly signs and verifies every release asset with Sigstore, attests the tarball, publishes the same bytes to npm and GitHub Packages, and creates a GitHub release. -npm publication uses Trusted Publishing/OIDC and provenance. GitHub Packages uses `GITHUB_TOKEN`. The protected `release` environment, registry trust relationship, branch/ruleset, secret scanning, and other settings require one-time repository-owner configuration documented in `.github/REPOSITORY_SETTINGS.md`. +npm publication uses Trusted Publishing/OIDC and provenance. GitHub Packages uses `GITHUB_TOKEN`. Verification instructions and the expected workflow identity are documented in [Release integrity](./release-integrity/). The protected `release` environment, registry trust relationship, branch/ruleset, secret scanning, and other settings require one-time repository-owner configuration documented in `.github/REPOSITORY_SETTINGS.md`. diff --git a/docs/src/content/docs/reference/apple-compatibility.md b/docs/src/content/docs/reference/apple-compatibility.md index 953cf73..84dde5b 100644 --- a/docs/src/content/docs/reference/apple-compatibility.md +++ b/docs/src/content/docs/reference/apple-compatibility.md @@ -9,7 +9,7 @@ The special Profile Service protocol is primarily documented in Apple’s archiv 2. **Observed:** verified on specified platform versions with reproducible fixtures. 3. **Extension:** accepted losslessly but not yet normalized or claimed as Apple-defined. -`0.1.0-beta.2` types the documented attribute names `UDID`, `VERSION`, `PRODUCT`, `SERIAL`, `MEID`, `IMEI`, `ICCID`, and `MAC_ADDRESS_EN0`. Availability depends on device hardware, OS, privacy behavior, and enrollment context. A requested value is not automatically guaranteed. +`0.1.0-beta.3` types the documented attribute names `UDID`, `VERSION`, `PRODUCT`, `SERIAL`, `MEID`, `IMEI`, `ICCID`, and `MAC_ADDRESS_EN0`. Availability depends on device hardware, OS, privacy behavior, and enrollment context. A requested value is not automatically guaranteed. Apple Profile Service responses may use RSA/SHA-1. Apple's archived guide requires a signed CMS response but does not prescribe the digest algorithm. Response verification accepts both RSA/SHA-1 and RSA/SHA-256. diff --git a/docs/src/content/i18n/en.json b/docs/src/content/i18n/en.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/docs/src/content/i18n/en.json @@ -0,0 +1 @@ +{} diff --git a/package-lock.json b/package-lock.json index ba7587b..6be345f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@udid-tools/core", - "version": "0.1.0-beta.2", + "version": "0.1.0-beta.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@udid-tools/core", - "version": "0.1.0-beta.2", + "version": "0.1.0-beta.3", "license": "MIT", "dependencies": { "asn1js": "3.0.10", diff --git a/package.json b/package.json index e1c1701..8b92700 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@udid-tools/core", - "version": "0.1.0-beta.2", + "version": "0.1.0-beta.3", "description": "Framework-agnostic TypeScript SDK for Apple Profile Service profiles, CMS signing, verification, and device response parsing.", "keywords": [ "apple",