Compare commits

...

4 Commits

15 changed files with 4931 additions and 2960 deletions

View File

@ -6,8 +6,8 @@ on:
- '**'
env:
IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
IMAGE: code.foss.global/host.today/ht-docker-node:npmci
NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
@ -26,7 +26,7 @@ jobs:
- name: Install pnpm and npmci
run: |
pnpm install -g pnpm
pnpm install -g @shipzone/npmci
pnpm install -g @ship.zone/npmci
- name: Run npm prepare
run: npmci npm prepare

View File

@ -6,8 +6,8 @@ on:
- '*'
env:
IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
IMAGE: code.foss.global/host.today/ht-docker-node:npmci
NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@/${{gitea.repository}}.git
NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
@ -26,7 +26,7 @@ jobs:
- name: Prepare
run: |
pnpm install -g pnpm
pnpm install -g @shipzone/npmci
pnpm install -g @ship.zone/npmci
npmci npm prepare
- name: Audit production dependencies
@ -54,7 +54,7 @@ jobs:
- name: Prepare
run: |
pnpm install -g pnpm
pnpm install -g @shipzone/npmci
pnpm install -g @ship.zone/npmci
npmci npm prepare
- name: Test stable
@ -82,7 +82,7 @@ jobs:
- name: Prepare
run: |
pnpm install -g pnpm
pnpm install -g @shipzone/npmci
pnpm install -g @ship.zone/npmci
npmci npm prepare
- name: Release
@ -104,7 +104,7 @@ jobs:
- name: Prepare
run: |
pnpm install -g pnpm
pnpm install -g @shipzone/npmci
pnpm install -g @ship.zone/npmci
npmci npm prepare
- name: Code quality

3
.gitignore vendored
View File

@ -3,7 +3,6 @@
# artifacts
coverage/
public/
pages/
# installs
node_modules/
@ -17,4 +16,4 @@ node_modules/
dist/
dist_*/
# custom
#------# custom

View File

@ -1,4 +1,4 @@
Copyright (C) 2016, Lossless GmbH
Copyright (C) 2016, Task Venture Capital GmbH
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

124
changelog.md Normal file
View File

@ -0,0 +1,124 @@
# Changelog
## 2025-04-27 - 5.1.0 - feat(smartacme)
Implement exponential backoff retry logic and graceful shutdown handling in SmartAcme; update acme-client dependency to v5.4.0
- Added retry helper with exponential backoff for ACME client operations
- Introduced retryOptions in ISmartAcmeOptions for configurable retry parameters
- Enhanced graceful shutdown handling by cleaning up pending DNS challenges on signal
- Updated acme-client dependency from v4.2.5 to v5.4.0
## 2025-04-26 - 5.0.1 - fix(build)
Update CI workflows, bump dependency versions, and refine import and TypeScript configuration
- Changed CI workflow image and npmci package from '@shipzone/npmci' to '@ship.zone/npmci', and updated repository URLs
- Bumped several dependency versions in package.json (e.g. @api.global/typedserver, @push.rocks/lik, @push.rocks/smartdata, @push.rocks/smartdns, @tsclass/tsclass) to newer releases
- Adjusted smartdns import to use the smartdnsClient module for proper module resolution
- Updated tsconfig.json to add emitDecoratorMetadata and baseUrl settings
- Minor markdown and formatting tweaks in readme and gitignore files, and slight improvements in test async handling
## 2024-06-16 - 5.0.0 - No significant changes
This release contains no userfacing changes.
## 2024-06-16 - 4.0.8 - Structure and configuration updates
- BREAKING CHANGE(structure): renamed classes to avoid confusion
- update description
- update tsconfig
- update npmextra.json: githost
## 2024-01-28 - 4.0.74.0.6 - Internal fixes and updates
- A series of releases with routine bug fixes and maintenance updates.
## 2023-07-21 - 4.0.54.0.4 - Internal fixes and updates
- Multiple releases addressing internal issues and maintenance improvements.
## 2023-07-10 - 4.0.3 - Organizational changes
- switch to new org scheme
## 2022-09-27 - 4.0.04.0.2 - Internal fixes and updates
- Routine maintenance and internal bug fixes.
## 2022-09-27 - 3.0.15 - Breaking changes
- BREAKING CHANGE(core): update
## 2021-01-22 - 3.0.93.0.14 - Internal fixes and updates
- A range of releases focused on routine internal updates.
## 2020-11-18 - 3.0.03.0.8 - Internal fixes and updates
- Routine maintenance and internal bug fixes.
## 2020-02-10 - 2.1.2 - Breaking changes
- BREAKING CHANGE(core): streamline scope to certificate retrieval using dns challenge
## 2020-02-10 - 2.1.02.1.1 - Internal fixes and updates
- Routine fixes and updates.
## 2019-02-06 - 2.0.36 - New feature
- feat(Cert): now has validity check
## 2019-01-18 - 2.0.22.0.35 - Internal fixes and updates
- Routine internal updates and maintenance.
## 2018-10-07 - 2.0.02.0.1 - Internal fixes and updates
- Routine internal updates and maintenance.
## 2018-10-07 - 1.1.4 - Breaking changes
- BREAKING CHANGE(scope): change to @pushrocks
## 2018-08-12 - 1.1.1 - NPM publishing fix
- fix(npm publishing): update
## 2018-08-11 - 1.1.0 - Certificate issuance update
- fix(core): now creating certs all right
## 2018-08-11 - 1.0.11 - Feature update
- feat(swaitch to acme-v2): switch to letsencrypt v2
## 2017-04-28 - 1.0.10 - CI improvements
- add updated ci config
## 2017-04-28 - 1.0.9 - Standards update
- update to latest standards
## 2017-01-27 - 1.0.8 - Basic functionality
- basic functionality
## 2017-01-25 - 1.0.7 - Response and validation improvements
- now getting a valid response
- update validation
- improve README
## 2017-01-15 - 1.0.6 - Async and documentation improvements
- improve README
- add async checkDNS
## 2017-01-15 - 1.0.5 - Standards and process updates
- update to new standards
- now has working requestValidation method
- fix som things
- start better segregation of concerns
- start with certificate signing process
## 2017-01-01 - 1.0.4 - Certificate acquisition improvements
- now getting certificates
- can now agree to TOS
- remove test keys
## 2017-01-01 - 1.0.3 - NPM extra configuration
- add npmextra.json
## 2017-01-01 - 1.0.2 - README and integration update
- add better readme
- switch to rawacme for more basic letsencrypt access
## 2016-11-17 - 1.0.1 - Promise fix
- fix promise
## 2016-11-17 - 1.0.0 - Major initial release changes
- remove superflouous key creation
- switch to acme core
- prepare switch to leacmecore
- improve upon keyCreation
- update to use more promises
- add README
- first version

View File

@ -1,6 +1,6 @@
{
"name": "@push.rocks/smartacme",
"version": "5.0.0",
"version": "5.1.0",
"private": false,
"description": "A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power.",
"main": "dist_ts/index.js",
@ -32,35 +32,35 @@
"certificate renewal",
"wildcard certificates"
],
"author": "Lossless GmbH",
"author": "Task Venture Capital GmbH",
"license": "MIT",
"bugs": {
"url": "https://gitlab.com/umbrellazone/smartacme/issues"
"url": "https://code.foss.global/push.rocks/smartacme/issues"
},
"homepage": "https://code.foss.global/push.rocks/smartacme",
"homepage": "https://code.foss.global/push.rocks/smartacme#readme",
"dependencies": {
"@api.global/typedserver": "^3.0.50",
"@push.rocks/lik": "^6.0.15",
"@push.rocks/smartdata": "^5.2.4",
"@api.global/typedserver": "^3.0.74",
"@push.rocks/lik": "^6.2.2",
"@push.rocks/smartdata": "^5.15.1",
"@push.rocks/smartdelay": "^3.0.5",
"@push.rocks/smartdns": "^5.0.2",
"@push.rocks/smartdns": "^6.2.2",
"@push.rocks/smartlog": "^3.0.7",
"@push.rocks/smartpromise": "^4.0.3",
"@push.rocks/smartrequest": "^2.0.22",
"@push.rocks/smartpromise": "^4.2.3",
"@push.rocks/smartrequest": "^2.1.0",
"@push.rocks/smartstring": "^4.0.15",
"@push.rocks/smarttime": "^4.0.6",
"@push.rocks/smarttime": "^4.1.1",
"@push.rocks/smartunique": "^3.0.9",
"@tsclass/tsclass": "^4.0.58",
"acme-client": "^4.2.5"
"@tsclass/tsclass": "^9.0.0",
"acme-client": "^5.4.0"
},
"devDependencies": {
"@apiclient.xyz/cloudflare": "^6.0.3",
"@git.zone/tsbuild": "^2.1.80",
"@git.zone/tsrun": "^1.2.44",
"@git.zone/tstest": "^1.0.90",
"@push.rocks/qenv": "^6.0.5",
"@push.rocks/tapbundle": "^5.0.23",
"@types/node": "^20.14.2"
"@apiclient.xyz/cloudflare": "^6.3.2",
"@git.zone/tsbuild": "^2.3.2",
"@git.zone/tsrun": "^1.3.3",
"@git.zone/tstest": "^1.0.96",
"@push.rocks/qenv": "^6.1.0",
"@push.rocks/tapbundle": "^5.6.3",
"@types/node": "^22.15.2"
},
"files": [
"ts/**/*",
@ -76,5 +76,9 @@
],
"browserslist": [
"last 1 chrome versions"
]
],
"packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6",
"pnpm": {
"overrides": {}
}
}

7536
pnpm-lock.yaml generated

File diff suppressed because it is too large Load Diff

View File

@ -1,4 +1,4 @@
```markdown
````markdown
# @push.rocks/smartacme
A TypeScript-based ACME client with an easy yet powerful interface for LetsEncrypt certificate management.
@ -10,6 +10,7 @@ To install `@push.rocks/smartacme`, you can use npm or yarn. Run one of the foll
```bash
npm install @push.rocks/smartacme --save
```
````
or
@ -265,11 +266,12 @@ tap.start();
This comprehensive guide ensures you can set up, manage, and test ACME certificates efficiently and effectively using `@push.rocks/smartacme`.
---
```
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
@ -279,9 +281,10 @@ This project is owned and maintained by Task Venture Capital GmbH. The names and
### Company Information
Task Venture Capital GmbH
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
```

View File

@ -3,7 +3,7 @@ import { Qenv } from '@push.rocks/qenv';
import * as cloudflare from '@apiclient.xyz/cloudflare';
const testQenv = new Qenv('./', './.nogit/');
const testCloudflare = new cloudflare.CloudflareAccount(testQenv.getEnvVarOnDemand('CF_TOKEN'));
const testCloudflare = new cloudflare.CloudflareAccount(await testQenv.getEnvVarOnDemand('CF_TOKEN'));
import * as smartacme from '../ts/index.js';
@ -14,9 +14,9 @@ tap.test('should create a valid instance of SmartAcme', async () => {
accountEmail: 'domains@lossless.org',
accountPrivateKey: null,
mongoDescriptor: {
mongoDbName: testQenv.getEnvVarRequired('MONGODB_DATABASE'),
mongoDbPass: testQenv.getEnvVarRequired('MONGODB_PASSWORD'),
mongoDbUrl: testQenv.getEnvVarRequired('MONGODB_URL'),
mongoDbName: await testQenv.getEnvVarOnDemand('MONGODB_DATABASE'),
mongoDbPass: await testQenv.getEnvVarOnDemand('MONGODB_PASSWORD'),
mongoDbUrl: await testQenv.getEnvVarOnDemand('MONGODB_URL'),
},
removeChallenge: async (dnsChallenge) => {
testCloudflare.convenience.acmeRemoveDnsChallenge(dnsChallenge);

View File

@ -1,8 +1,8 @@
/**
* autocreated commitinfo by @pushrocks/commitinfo
* autocreated commitinfo by @push.rocks/commitinfo
*/
export const commitinfo = {
name: '@push.rocks/smartacme',
version: '5.0.0',
version: '5.1.0',
description: 'A TypeScript-based ACME client for LetsEncrypt certificate management with a focus on simplicity and power.'
}

View File

@ -1,2 +1,2 @@
export * from './smartacme.classes.smartacme.js';
export { SmartacmeCert as Cert } from './smartacme.classes.cert.js';
export { SmartacmeCert as Cert } from './smartacme.classes.cert.js';

View File

@ -22,7 +22,7 @@ export class SmartacmeCertManager {
smartAcmeArg: SmartAcme,
optionsArg: {
mongoDescriptor: plugins.smartdata.IMongoDescriptor;
}
},
) {
this.mongoDescriptor = optionsArg.mongoDescriptor;
}

View File

@ -14,6 +14,19 @@ export interface ISmartAcmeOptions {
setChallenge: (dnsChallengeArg: plugins.tsclass.network.IDnsChallenge) => Promise<any>;
removeChallenge: (dnsChallengeArg: plugins.tsclass.network.IDnsChallenge) => Promise<any>;
environment: 'production' | 'integration';
/**
* Optional retry/backoff configuration for transient failures
*/
retryOptions?: {
/** number of retry attempts */
retries?: number;
/** backoff multiplier */
factor?: number;
/** initial delay in milliseconds */
minTimeoutMs?: number;
/** maximum delay cap in milliseconds */
maxTimeoutMs?: number;
};
}
/**
@ -30,8 +43,8 @@ export class SmartAcme {
private options: ISmartAcmeOptions;
// the acme client
private client: any;
private smartdns = new plugins.smartdns.Smartdns({});
private client: plugins.acme.Client;
private smartdns = new plugins.smartdnsClient.Smartdns({});
public logger: plugins.smartlog.Smartlog;
// the account private key
@ -44,10 +57,23 @@ export class SmartAcme {
// certmanager
private certmanager: SmartacmeCertManager;
private certmatcher: SmartacmeCertMatcher;
// retry/backoff configuration (resolved with defaults)
private retryOptions: { retries: number; factor: number; minTimeoutMs: number; maxTimeoutMs: number };
// track pending DNS challenges for graceful shutdown
private pendingChallenges: plugins.tsclass.network.IDnsChallenge[] = [];
constructor(optionsArg: ISmartAcmeOptions) {
this.options = optionsArg;
this.logger = plugins.smartlog.Smartlog.createForCommitinfo(commitinfo);
// enable console output for structured logging
this.logger.enableConsole();
// initialize retry/backoff options
this.retryOptions = {
retries: optionsArg.retryOptions?.retries ?? 3,
factor: optionsArg.retryOptions?.factor ?? 2,
minTimeoutMs: optionsArg.retryOptions?.minTimeoutMs ?? 1000,
maxTimeoutMs: optionsArg.retryOptions?.maxTimeoutMs ?? 30000,
};
}
/**
@ -88,11 +114,55 @@ export class SmartAcme {
termsOfServiceAgreed: true,
contact: [`mailto:${this.options.accountEmail}`],
});
// Setup graceful shutdown handlers
process.on('SIGINT', () => this.handleSignal('SIGINT'));
process.on('SIGTERM', () => this.handleSignal('SIGTERM'));
}
public async stop() {
await this.certmanager.smartdataDb.close();
}
public async stop() {
await this.certmanager.smartdataDb.close();
}
/** Retry helper with exponential backoff */
private async retry<T>(operation: () => Promise<T>, operationName: string = 'operation'): Promise<T> {
let attempt = 0;
let delay = this.retryOptions.minTimeoutMs;
while (true) {
try {
return await operation();
} catch (err) {
attempt++;
if (attempt > this.retryOptions.retries) {
await this.logger.log('error', `Operation ${operationName} failed after ${attempt} attempts`, err);
throw err;
}
await this.logger.log('warn', `Operation ${operationName} failed on attempt ${attempt}, retrying in ${delay}ms`, err);
await plugins.smartdelay.delayFor(delay);
delay = Math.min(delay * this.retryOptions.factor, this.retryOptions.maxTimeoutMs);
}
}
}
/** Clean up pending challenges and shut down */
private async handleShutdown(): Promise<void> {
for (const challenge of [...this.pendingChallenges]) {
try {
await this.removeChallenge(challenge);
await this.logger.log('info', 'Removed pending challenge during shutdown', challenge);
} catch (err) {
await this.logger.log('error', 'Failed to remove pending challenge during shutdown', err);
}
}
this.pendingChallenges = [];
await this.stop();
}
/** Handle process signals for graceful shutdown */
private handleSignal(sig: string): void {
this.logger.log('info', `Received signal ${sig}, shutting down gracefully`);
this.handleShutdown()
.then(() => process.exit(0))
.catch((err) => {
this.logger.log('error', 'Error during shutdown', err).then(() => process.exit(1));
});
}
/**
* gets a certificate
@ -128,54 +198,54 @@ export class SmartAcme {
// lets make sure others get the same interest
const currentDomainInterst = await this.certmanager.interestMap.addInterest(certDomainName);
/* Place new order */
const order = await this.client.createOrder({
/* Place new order with retry */
const order = await this.retry(() => this.client.createOrder({
identifiers: [
{ type: 'dns', value: certDomainName },
{ type: 'dns', value: `*.${certDomainName}` },
],
});
}), 'createOrder');
/* Get authorizations and select challenges */
const authorizations = await this.client.getAuthorizations(order);
const authorizations = await this.retry(() => this.client.getAuthorizations(order), 'getAuthorizations');
for (const authz of authorizations) {
console.log(authz);
await this.logger.log('debug', 'Authorization received', authz);
const fullHostName: string = `_acme-challenge.${authz.identifier.value}`;
const dnsChallenge: string = authz.challenges.find((challengeArg) => {
const dnsChallenge = authz.challenges.find((challengeArg) => {
return challengeArg.type === 'dns-01';
});
// process.exit(1);
const keyAuthorization: string = await this.client.getChallengeKeyAuthorization(dnsChallenge);
// prepare DNS challenge record and track for cleanup
const challengeRecord: plugins.tsclass.network.IDnsChallenge = { hostName: fullHostName, challenge: keyAuthorization };
this.pendingChallenges.push(challengeRecord);
try {
/* Satisfy challenge */
await this.setChallenge({
hostName: fullHostName,
challenge: keyAuthorization,
});
await this.retry(() => this.setChallenge(challengeRecord), 'setChallenge');
await plugins.smartdelay.delayFor(30000);
await this.smartdns.checkUntilAvailable(fullHostName, 'TXT', keyAuthorization, 100, 5000);
console.log('Cool down an extra 60 second for region availability');
await this.retry(() => this.smartdns.checkUntilAvailable(fullHostName, 'TXT', keyAuthorization, 100, 5000), 'dnsCheckUntilAvailable');
await this.logger.log('info', 'Cooling down extra 60 seconds for DNS regional propagation');
await plugins.smartdelay.delayFor(60000);
/* Verify that challenge is satisfied */
await this.client.verifyChallenge(authz, dnsChallenge);
await this.retry(() => this.client.verifyChallenge(authz, dnsChallenge), 'verifyChallenge');
/* Notify ACME provider that challenge is satisfied */
await this.client.completeChallenge(dnsChallenge);
await this.retry(() => this.client.completeChallenge(dnsChallenge), 'completeChallenge');
/* Wait for ACME provider to respond with valid status */
await this.client.waitForValidStatus(dnsChallenge);
await this.retry(() => this.client.waitForValidStatus(dnsChallenge), 'waitForValidStatus');
} finally {
/* Clean up challenge response */
try {
await this.removeChallenge({
hostName: fullHostName,
challenge: keyAuthorization,
});
} catch (e) {
console.log(e);
await this.retry(() => this.removeChallenge(challengeRecord), 'removeChallenge');
} catch (err) {
await this.logger.log('error', 'Error removing DNS challenge', err);
} finally {
// remove from pending list
this.pendingChallenges = this.pendingChallenges.filter(c => c !== challengeRecord);
}
}
}
@ -186,8 +256,8 @@ export class SmartAcme {
altNames: [certDomainName],
});
await this.client.finalizeOrder(order, csr);
const cert = await this.client.getCertificate(order);
await this.retry(() => this.client.finalizeOrder(order, csr), 'finalizeOrder');
const cert = await this.retry(() => this.client.getCertificate(order), 'getCertificate');
/* Done */

View File

@ -7,7 +7,7 @@ export { typedserver };
import * as lik from '@push.rocks/lik';
import * as smartdata from '@push.rocks/smartdata';
import * as smartdelay from '@push.rocks/smartdelay';
import * as smartdns from '@push.rocks/smartdns';
import * as smartdnsClient from '@push.rocks/smartdns/client';
import * as smartlog from '@push.rocks/smartlog';
import * as smartpromise from '@push.rocks/smartpromise';
import * as smartrequest from '@push.rocks/smartrequest';
@ -19,7 +19,7 @@ export {
lik,
smartdata,
smartdelay,
smartdns,
smartdnsClient,
smartlog,
smartpromise,
smartrequest,

View File

@ -1,14 +1,17 @@
{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"useDefineForClassFields": false,
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"esModuleInterop": true,
"verbatimModuleSyntax": true
"verbatimModuleSyntax": true,
"baseUrl": ".",
"paths": {}
},
"exclude": [
"dist_*/**/*.d.ts"
]
}
}