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
25 changes: 10 additions & 15 deletions .github/workflows/release-please.yml
Original file line number Diff line number Diff line change
@@ -1,23 +1,18 @@
# NOTHING MAY BE PUBLISHED before Alex's explicit approval and the 2026-11-01 Didit release
# (docs/DESIGN.md section 13). The GitHub environment `npm` used by the publish job must
# require a reviewer, so that every upload to npm waits for an explicit approval.
#
# Run by hand only, so nothing is cut by accident:
# 1. The first run opens the release pull request (version bump and the generated
# CHANGELOG.md).
# Runs on every push to main (and by hand):
# 1. It keeps the release pull request (version bump and the generated CHANGELOG.md) up to date.
# 2. Once that pull request is merged, the next run creates the vX.Y.Z tag and the GitHub
# release; the publish job then waits for the `npm` environment approval, re-runs the
# checks on the tag and publishes with npm provenance (trusted publishing, OIDC).
# release, and the publish job re-runs the checks on the tag and publishes to npm with
# trusted publishing (OIDC) and provenance.
# The publish job is part of this workflow, so it runs whatever token created the release.
#
# Token: a release pull request opened with the default GITHUB_TOKEN gets no CI (GitHub
# does not start workflows from events caused by GITHUB_TOKEN). Add a repository secret
# RELEASE_PLEASE_TOKEN (a fine-grained token with Contents, Issues and Pull requests read
# and write on this repository only) to fix that; without it the workflow falls back to
# GITHUB_TOKEN, and CI on the release pull request must be started by hand.
# Optional: a RELEASE_PLEASE_TOKEN secret (fine-grained, Contents, Issues and Pull requests read
# and write on this repository only) gives the release pull request CI; without it the workflow
# uses GITHUB_TOKEN and the release pull request's checks run on merge.
name: Release

on:
push:
branches: [main]
workflow_dispatch:

permissions:
Expand Down Expand Up @@ -59,7 +54,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 20
environment:
# Must require a reviewer (Settings > Environments > npm > Required reviewers).
# Holds the npm trusted-publishing binding; no required reviewers (merging the release PR is the approval).
name: npm
url: https://www.npmjs.com/package/@didit-protocol/sdk-node
permissions:
Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Didit TypeScript / JavaScript SDK (`sdk-node`)

The official Didit server-side library for TypeScript / JavaScript: `@didit-protocol/sdk-node` on npm.
Status: in development, not released.
Status: released (1.0.0 on 2026-10-29). Merging the release-please pull request publishes the next version.

## Read first

Expand Down Expand Up @@ -29,7 +29,7 @@ Development needs Node.js 22.18 or later (the generator runs TypeScript directly
- `openapi/verification.json`, `openapi/account.json` and `openapi/webhook-vectors.json` are upstream copies; never edit them by hand. Only the spec sync workflow updates them.
- Keep the SDKs in sync (HARD RULE). Any public API change in `service-didit-verification` or `service-didit-auth` must reach the OpenAPI documents in mintlify-docs, and from there every server SDK through the spec sync pull request. A change to hand-written core behaviour that DESIGN.md describes (client options, errors, retries, pagination, webhooks, Authentication) is made in all seven SDK repositories, one pull request each, and DESIGN.md is updated in all seven in the same words.
- Feature parity across languages: a capability shipped in one server SDK ships in the other six.
- Never publish a package, push a release tag or make this repository public without Alex's explicit approval; nothing is released before the 2026-11-01 Didit release.
- Releases publish straight from this repository (Alex, 2026-10-29): merging the release-please pull request is the release approval, and the release workflow then creates the vX.Y.Z tag and publishes to the registry. Never push a release tag, create a release or publish by hand outside that flow, and never store a registry token where trusted publishing works.
- Unit tests never touch the network. Live smoke tests run only when `DIDIT_SANDBOX_API_KEY` is set.
- Never commit secrets, API keys or real customer data. Fixtures are synthetic.
- `CHANGELOG.md` is generated by release-please from conventional commits; never edit it by hand.
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Didit TypeScript / JavaScript SDK (`sdk-node`)

The official Didit server-side library for TypeScript / JavaScript: `@didit-protocol/sdk-node` on npm.
Status: in development, not released.
Status: released (1.0.0 on 2026-10-29). Merging the release-please pull request publishes the next version.

## Read first

Expand Down Expand Up @@ -29,7 +29,7 @@ Development needs Node.js 22.18 or later (the generator runs TypeScript directly
- `openapi/verification.json`, `openapi/account.json` and `openapi/webhook-vectors.json` are upstream copies; never edit them by hand. Only the spec sync workflow updates them.
- Keep the SDKs in sync (HARD RULE). Any public API change in `service-didit-verification` or `service-didit-auth` must reach the OpenAPI documents in mintlify-docs, and from there every server SDK through the spec sync pull request. A change to hand-written core behaviour that DESIGN.md describes (client options, errors, retries, pagination, webhooks, Authentication) is made in all seven SDK repositories, one pull request each, and DESIGN.md is updated in all seven in the same words.
- Feature parity across languages: a capability shipped in one server SDK ships in the other six.
- Never publish a package, push a release tag or make this repository public without Alex's explicit approval; nothing is released before the 2026-11-01 Didit release.
- Releases publish straight from this repository (Alex, 2026-10-29): merging the release-please pull request is the release approval, and the release workflow then creates the vX.Y.Z tag and publishes to the registry. Never push a release tag, create a release or publish by hand outside that flow, and never store a registry token where trusted publishing works.
- Unit tests never touch the network. Live smoke tests run only when `DIDIT_SANDBOX_API_KEY` is set.
- Never commit secrets, API keys or real customer data. Fixtures are synthetic.
- `CHANGELOG.md` is generated by release-please from conventional commits; never edit it by hand.
Expand Down
14 changes: 7 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,19 +63,19 @@ Every pull request says whether the same change is needed in the other six SDK r

## Releases

Nothing is published before Alex's explicit approval and the 2026-11-01 Didit release. Until then the version stays 0.x.
1.0.0 was released on 2026-10-29. Merging the release pull request is the release approval (Alex, 2026-10-29); nobody tags or publishes by hand.

1. Run the **Release** workflow (`.github/workflows/release-please.yml`) by hand. It opens the release pull request: the version bump in `package.json` and `src/core/version.ts`, and `CHANGELOG.md` generated from the commits (never edit it by hand).
2. Merge the release pull request, then run the **Release** workflow again. It creates the `vX.Y.Z` tag and the GitHub release, and its `publish` job waits for a reviewer of the GitHub environment `npm`.
3. Once approved, the job checks that the tag matches the package version, re-runs the generator check, the type check, the tests and the package checks on the tag, and publishes to npm with provenance.
1. The **Release** workflow (`.github/workflows/release-please.yml`) runs on every push to `main` and keeps the release pull request open: the version bump in `package.json` and `src/core/version.ts`, and `CHANGELOG.md` generated from the commits (never edit it by hand).
2. Merge the release pull request. The next run creates the `vX.Y.Z` tag and the GitHub release, and its `publish` job runs in the GitHub environment `npm` (no required reviewers).
3. The job checks that the tag matches the package version, re-runs the generator check, the type check, the tests and the package checks on the tag, and publishes to npm with provenance.

One-time setup before the first release (a repository admin):
One-time setup (done for 1.0.0; kept for reference):

1. **Public repository.** npm publishes with provenance only from a public repository, so the publish job refuses to run while this one is private. On release day, after the full-history secret scan (the `Secret scan` CI job), make the repository public, then publish.
2. **npm.** Make sure the `@didit-protocol` organization exists on npmjs.com and that the publishers have 2FA. The package name `@didit-protocol/sdk-node` is free until the first publish.
3. **GitHub environment.** Create the environment `npm` (Settings, Environments) with required reviewers (Alex), and allow only the `main` branch and `v*` tags to deploy to it.
3. **GitHub environment.** The environment `npm` holds the trusted-publishing binding; it has no required reviewers.
4. **First publish.** npm lets you configure a trusted publisher only for a package that exists. For the first release, add an environment secret `NPM_TOKEN` (a granular access token with publish rights on the `@didit-protocol` scope, short expiry) to the `npm` environment; the publish job uses it, still with provenance.
5. **Trusted publishing.** After the first publish, on npmjs.com open the package settings and add a trusted publisher: GitHub Actions, organization `didit-protocol`, repository `sdk-node`, workflow `release-please.yml`, environment `npm`. Then delete `NPM_TOKEN`, and set the package's publishing access to require 2FA and disallow tokens.
5. **Trusted publishing.** After the first publish, on npmjs.com open the package settings and add a trusted publisher: GitHub Actions, organization `didit-protocol`, repository `sdk-node`, workflow `release-please.yml`, environment `npm`. Tick "Allow npm publish" (by default a trusted publisher may only stage versions for manual approval). Then delete `NPM_TOKEN` and revoke it. Done on 2026-10-29: the trusted publisher allows `npm publish` and no npm token is stored.
6. **Tokens for CI on bot pull requests (optional).** `RELEASE_PLEASE_TOKEN` and `SPEC_SYNC_TOKEN`: fine-grained tokens limited to this repository (Contents, Issues, Pull requests read and write), so that the release and spec sync pull requests get CI.
7. **Code owners.** Give the `@didit-protocol/backend` team write access (or change `.github/CODEOWNERS`).
8. **Security reports.** When the repository goes public, enable private vulnerability reporting (Settings, Code security), which `SECURITY.md` points to; GitHub offers it only on public repositories.
2 changes: 0 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@
The official Didit TypeScript and JavaScript library.
Identity verification (KYC), business verification (KYB), AML screening, biometrics, transaction monitoring, Travel Rule and customer authentication, from your backend.

> In development. Not released yet: the first release is planned with the 2026-11-01 Didit release.

- Every server endpoint of the [Didit API](https://docs.didit.me), with full types, generated from the OpenAPI contract.
- Webhook verification with typed events, and Didit Authentication token verification.
- No runtime dependencies. Runs on Node.js 18 or later, Bun, Deno and edge runtimes with `fetch` and Web Crypto (Cloudflare Workers, Vercel Edge).
Expand Down
12 changes: 6 additions & 6 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,8 @@ The Maven group `me.didit` is the one `sdk-android` already publishes under.

PyPI `didit` belongs to an unrelated project from 2013.
PyPI `didit-sdk` is a community package by Agustin Saiz (MIT, unofficial, sessions only).
Didit is asking him to transfer the `didit-sdk` project to Didit, so the official SDK ships under that name.
Until the transfer is confirmed, keep `didit-sdk` as the distribution name in `pyproject.toml` and do not publish.
The fallback name, if the transfer does not happen, is `didit-python`.
He transferred the `didit-sdk` project to Didit, and the official SDK published 1.0.0 under that name on 2026-10-29.
As agreed with him, his releases 0.1.0 to 0.4.0 stay published, his PyPI user stays on the project, and the 1.0.0 release notes credit the initial community versions.

## 3. Source of truth: the OpenAPI contract

Expand Down Expand Up @@ -247,9 +246,10 @@ Ruby: `net/http` from the standard library, `jwt` only for Authentication.

- Semantic versioning; a breaking change to the public SDK surface is a major version.
- Releases are cut by release-please from conventional commits; `CHANGELOG.md` is generated and never edited by hand.
- Release workflows publish with trusted publishing or provenance where the registry supports it (PyPI and RubyGems trusted publishing, npm provenance, Maven Central via the Central Portal with signed artifacts, NuGet with a scoped key and the `Didit` prefix reserved, Packagist auto-update from tags, Go module tags).
- Nothing is published before Alex approves the first release, and not before the 2026-11-01 release; until then versions stay `0.x` pre-release in the repository.
- The repository stays private until that first release.
- Release workflows publish with trusted publishing where the registry supports it (PyPI, npm with provenance, RubyGems and NuGet), Maven Central through the Central Portal with signed artifacts (token and signing key in the `maven-central` environment), Packagist through its GitHub hook, and Go module tags announced to proxy.golang.org.
- 1.0.0 shipped on 2026-10-29 with Alex's approval, and the repositories are public.
- Every release after that publishes straight from the repository: merging the release-please pull request is the approval, and the workflow creates the vX.Y.Z tag and publishes.
- A release created with `GITHUB_TOKEN` does not trigger other workflows, so a repository that publishes from a separate `release.yml` has release-please start it with `workflow_dispatch` for the new tag. No personal access token is stored.

## 14. Documentation and positioning

Expand Down
Loading