@push.rocks/smartacme 9.5.0 → 9.7.0

package/ts/smartacme.classes.smartacme.ts

@@ -3,6 +3,12 @@ import type { ICertManager } from './interfaces/certmanager.js';
 import { SmartacmeCertMatcher } from './smartacme.classes.certmatcher.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { SmartacmeCert } from './smartacme.classes.cert.js';
+import { ExactCertificateIssuer } from './classes.exact-certificate-issuer.js';
+import type {
+  IExactCertificateIdentity,
+  IExactCertificateRequest, IExactIssuanceRecoveryRequest, IExactIssuanceStore,
+  IExactIssuanceInfo, TExactCertificateResult,
+} from './interfaces/exact-issuance.js';
 
 // ── Types & constants for certificate issuance task ──────────────────────────
 
@@ -12,6 +18,7 @@ interface ICertIssuanceInput {
   isWildcardRequest: boolean;
   includeWildcard: boolean;
   forceRenew: boolean;
+  exact?: { request: IExactCertificateRequest; recovery?: IExactIssuanceRecoveryRequest };
 }
 
 const CERT_ISSUANCE_STEPS = [
@@ -33,6 +40,14 @@ export interface ISmartAcmeOptions {
   certManager: ICertManager;
   // Removed legacy setChallenge/removeChallenge in favor of `challengeHandlers`
   environment: 'production' | 'integration';
+  /** Optional explicit ACME directory, for private CAs and isolated integration. */
+  directoryUrl?: string;
+  /** Enables isolated explicit-identifier issuance with durable recovery. */
+  exactIssuanceStore?: IExactIssuanceStore;
+  /** Bounded number of admitted exact-identity operations (default 64). */
+  maxPendingExactRequests?: number;
+  /** DNS propagation grace period for explicit issuance; defaults to 60 seconds. */
+  exactDnsPropagationDelayMs?: number;
   /**
    * Optional retry/backoff configuration for transient failures
    */
@@ -92,6 +107,10 @@ export class SmartAcme {
 
   // the account private key
   private privateKey!: string;
+  private exactIssuer?: ExactCertificateIssuer;
+  private exactRequests = new Map<string, Promise<TExactCertificateResult>>();
+  private lifecycleAbort = new AbortController();
+  private started = false;
 
 
   // certificate manager for persistence (implements ICertManager)
@@ -104,7 +123,7 @@ export class SmartAcme {
   // 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[] = [];
+  private pendingChallenges: { input: any; context: plugins.handlers.IChallengeContext }[] = [];
   // priority order of challenge types
   private challengePriority: string[];
   // TaskManager for coordinating concurrent certificate requests
@@ -124,6 +143,12 @@ export class SmartAcme {
 
   constructor(optionsArg: ISmartAcmeOptions) {
     this.options = optionsArg;
+    if (!Number.isSafeInteger(optionsArg.maxPendingExactRequests ?? 64)
+      || (optionsArg.maxPendingExactRequests ?? 64) < 1
+      || !Number.isSafeInteger(optionsArg.exactDnsPropagationDelayMs ?? 60000)
+      || (optionsArg.exactDnsPropagationDelayMs ?? 60000) < 0) {
+      throw new Error('Invalid explicit issuance admission or propagation limits');
+    }
     this.logger = plugins.smartlog.Smartlog.createForCommitinfo(commitinfo);
     // enable console output for structured logging
     this.logger.enableConsole();
@@ -156,9 +181,11 @@ export class SmartAcme {
       maxConcurrent: 1,
       resultSharingMode: 'share-latest',
       constraintKeyForExecution: (_task, input?: ICertIssuanceInput) => {
+        if (input?.exact) return null;
         return input?.certDomainName ?? null;
       },
       shouldExecute: async (_task, input?: ICertIssuanceInput) => {
+        if (input?.exact) return true;
         if (!input?.certDomainName || !this.certmanager) return true;
         if (input.forceRenew) return true;
         // Safety net: if a valid cert is already cached, skip re-issuance
@@ -188,6 +215,12 @@ export class SmartAcme {
     });
 
     this.taskManager.addConstraintGroup(certDomainMutex);
+    // One fixed key reserves a bounded share of global capacity for testing.
+    // Exact results contain private keys and must never enter result-sharing caches.
+    this.taskManager.addConstraintGroup(new plugins.taskbuffer.TaskConstraintGroup({
+      name: 'exact-issuance-concurrency', maxConcurrent: 2,
+      constraintKeyForExecution: (_task, input?: ICertIssuanceInput) => input?.exact ? 'exact' : null,
+    }));
     this.taskManager.addConstraintGroup(acmeGlobalConcurrency);
     this.taskManager.addConstraintGroup(acmeAccountRateLimit);
 
@@ -196,6 +229,12 @@ export class SmartAcme {
       name: 'cert-issuance',
       steps: CERT_ISSUANCE_STEPS,
       taskFunction: async (input: ICertIssuanceInput) => {
+        if (input.exact) {
+          const issuer = this.requireExactIssuer();
+          return input.exact.recovery
+            ? issuer.recover(input.exact.recovery)
+            : issuer.run(input.exact.request);
+        }
         return this.performCertificateIssuance(input);
       },
     });
@@ -210,8 +249,31 @@ export class SmartAcme {
    * ```
    */
   public async start() {
+    if (this.started) throw new Error('SmartAcme is already started');
+    this.lifecycleAbort = new AbortController();
     this.privateKey =
       this.options.accountPrivateKey || plugins.acme.AcmeCrypto.createRsaPrivateKey();
+    const directoryUrl = this.options.directoryUrl ?? (this.options.environment === 'production'
+      ? plugins.acme.ACME_DIRECTORY_URLS.letsencrypt.production
+      : plugins.acme.ACME_DIRECTORY_URLS.letsencrypt.staging);
+    const directory = new URL(directoryUrl);
+    if (directory.username || directory.password || directory.hash
+      || (directory.protocol !== 'https:' && !(directory.protocol === 'http:'
+        && ['localhost', '127.0.0.1', '[::1]'].includes(directory.hostname)))) {
+      throw new Error('An HTTPS ACME directory or an explicit loopback test directory is required');
+    }
+    if (this.options.exactIssuanceStore && !this.options.accountPrivateKey) {
+      const accountId = plugins.crypto.createHash('sha256')
+        .update(JSON.stringify([directoryUrl, this.options.accountEmail.trim().toLowerCase()])).digest('hex');
+      const store = this.options.exactIssuanceStore;
+      let storedKey = await store.getAccountKey(accountId);
+      if (!storedKey) {
+        await store.createAccountKey(accountId, this.privateKey);
+        storedKey = await store.getAccountKey(accountId);
+      }
+      if (!storedKey) throw new Error('ACME account key could not be retained durably');
+      this.privateKey = storedKey;
+    }
 
     // Initialize certificate manager
     if (!this.options.certManager) {
@@ -225,14 +287,9 @@ export class SmartAcme {
 
     // ACME Client
     this.client = new plugins.acme.AcmeClient({
-      directoryUrl: (() => {
-        if (this.options.environment === 'production') {
-          return plugins.acme.ACME_DIRECTORY_URLS.letsencrypt.production;
-        } else {
-          return plugins.acme.ACME_DIRECTORY_URLS.letsencrypt.staging;
-        }
-      })(),
+      directoryUrl,
       accountKeyPem: this.privateKey,
+      signal: this.lifecycleAbort.signal,
       logger: (level, message, data) => {
         this.logger.log(level as any, message, data);
       },
@@ -246,6 +303,15 @@ export class SmartAcme {
 
     // Start the task manager
     await this.taskManager.start();
+    if (this.options.exactIssuanceStore) {
+      this.exactIssuer = new ExactCertificateIssuer({
+        store: this.options.exactIssuanceStore, client: this.client, directoryUrl,
+        accountThumbprint: plugins.acme.AcmeCrypto.getJwkThumbprint(plugins.acme.AcmeCrypto.getJwk(this.privateKey)),
+        dns: this.smartdns, handlers: this.challengeHandlers, signal: this.lifecycleAbort.signal,
+        dnsPropagationDelayMs: this.options.exactDnsPropagationDelayMs ?? 60000,
+      });
+    }
+    this.started = true;
 
     // Setup graceful shutdown handlers (store references for removal in stop())
     this.boundSigintHandler = () => this.handleSignal('SIGINT');
@@ -258,6 +324,8 @@ export class SmartAcme {
    * Stops the SmartAcme instance and closes certificate store connections.
    */
   public async stop() {
+    this.started = false;
+    this.lifecycleAbort.abort();
     // Remove signal handlers so the process can exit cleanly
     if (this.boundSigintHandler) {
       process.removeListener('SIGINT', this.boundSigintHandler);
@@ -267,8 +335,13 @@ export class SmartAcme {
       process.removeListener('SIGTERM', this.boundSigtermHandler);
       this.boundSigtermHandler = null;
     }
-    // Stop the task manager
+    // Observe active requests before rejecting queued work. The task manager
+    // must close its queue before we drain callers waiting on that queue.
+    const pendingExactRequests = Promise.allSettled([...this.exactRequests.values()]);
     await this.taskManager.stop();
+    await pendingExactRequests;
+    this.exactRequests.clear();
+    this.exactIssuer = undefined;
     // Destroy ACME HTTP transport (closes keep-alive sockets)
     if (this.client) {
       this.client.destroy();
@@ -281,6 +354,64 @@ export class SmartAcme {
       await (this.certmanager as any).close();
     }
   }
+
+  /** Bind durable work to the current account and issuer without creating an order. */
+  public getCertificateIdentity(request: IExactCertificateRequest): IExactCertificateIdentity {
+    return this.requireExactIssuer().identity(request);
+  }
+
+  /** Ensure a certificate whose SANs exactly match the explicit identifiers. */
+  public async getCertificateForIdentifiers(request: IExactCertificateRequest): Promise<TExactCertificateResult> {
+    return await this.runExact(request);
+  }
+
+  public async getCertificateIssuanceStatus(request: IExactCertificateRequest): Promise<IExactIssuanceInfo | null> {
+    return await this.requireExactIssuer().status(request);
+  }
+
+  /** Administrative recovery; embedding services must authorize the caller. */
+  public async recoverCertificateIssuance(request: IExactIssuanceRecoveryRequest): Promise<TExactCertificateResult> {
+    return await this.runExact(request, request);
+  }
+
+  private requireExactIssuer(): ExactCertificateIssuer {
+    if (!this.started || !this.exactIssuer) throw new Error('SmartAcme explicit issuance is not running or configured');
+    return this.exactIssuer;
+  }
+
+  private async runExact(request: IExactCertificateRequest, recovery?: IExactIssuanceRecoveryRequest): Promise<TExactCertificateResult> {
+    const issuer = this.requireExactIssuer();
+    const identity = issuer.identity(request);
+    const recoverySnapshot = recovery ? {
+      namespace: identity.namespace, identifiers: [...identity.identifiers],
+      issuanceId: recovery.issuanceId, expectedRevision: recovery.expectedRevision, action: recovery.action,
+    } : undefined;
+    const existing = this.exactRequests.get(identity.certificateKey);
+    if (existing) {
+      if (recovery) throw new Error('Issuance is running; recover after its current operation completes');
+      return await existing;
+    }
+    if (this.exactRequests.size >= (this.options.maxPendingExactRequests ?? 64)) {
+      throw new Error('Explicit issuance admission limit reached');
+    }
+    const operation = (async (): Promise<TExactCertificateResult> => {
+      if (!recovery) {
+        const cached = await issuer.cached(identity);
+        if (cached) return cached;
+      }
+      this.lifecycleAbort.signal.throwIfAborted();
+      const result = await this.taskManager.triggerTaskConstrained(this.certIssuanceTask, {
+        certDomainName: identity.certificateKey, domainArg: identity.identifiers[0],
+        isWildcardRequest: false, includeWildcard: false, forceRenew: false,
+        exact: { request: { namespace: identity.namespace, identifiers: identity.identifiers }, recovery: recoverySnapshot },
+      } satisfies ICertIssuanceInput) as TExactCertificateResult | undefined;
+      if (!result) throw new Error('Explicit issuance completed without a result');
+      return result;
+    })();
+    this.exactRequests.set(identity.certificateKey, operation);
+    try { return await operation; }
+    finally { this.exactRequests.delete(identity.certificateKey); }
+  }
     /** Retry helper with exponential backoff and AcmeError awareness */
     private async retry<T>(operation: () => Promise<T>, operationName: string = 'operation'): Promise<T> {
       let attempt = 0;
@@ -315,12 +446,12 @@ export class SmartAcme {
     }
     /** Clean up pending challenges and shut down */
     private async handleShutdown(): Promise<void> {
-      for (const input of [...this.pendingChallenges]) {
+      for (const { input, context } of [...this.pendingChallenges]) {
         const type: string = (input as any).type;
         const handler = this.challengeHandlers.find((h) => h.getSupportedTypes().includes(type));
         if (handler) {
           try {
-            await handler.cleanup(input);
+            await handler.cleanup(input, { ...context });
             await this.logger.log('info', `Removed pending ${type} challenge during shutdown`, input);
           } catch (err) {
             await this.logger.log('error', `Failed to remove pending ${type} challenge during shutdown`, err);
@@ -457,6 +588,11 @@ export class SmartAcme {
       identifiers,
     }), 'createOrder');
 
+    const challengeContext: plugins.handlers.IChallengeContext = {
+      operationId: plugins.crypto.createHash('sha256')
+        .update(JSON.stringify(['smartacme-legacy-challenge-v1', order.url])).digest('hex'),
+    };
+
     // ── Step: authorize ───────────────────────────────────────────────────
     this.certIssuanceTask.notifyStep('authorize');
 
@@ -498,9 +634,9 @@ export class SmartAcme {
       } else {
         challengeInput = { type, keyAuthorization: keyAuth, ...selectedChallengeArg };
       }
-      this.pendingChallenges.push(challengeInput);
+      this.pendingChallenges.push({ input: challengeInput, context: challengeContext });
       try {
-        await this.retry(() => handler.prepare(challengeInput), `${type}.prepare`);
+        await this.retry(() => handler.prepare(challengeInput, { ...challengeContext }), `${type}.prepare`);
         if (type === 'dns-01') {
           const dnsInput = challengeInput as { hostName: string; challenge: string };
           await this.retry(
@@ -528,11 +664,11 @@ export class SmartAcme {
         }
       } finally {
         try {
-          await this.retry(() => handler.cleanup(challengeInput), `${type}.cleanup`);
+          await this.retry(() => handler.cleanup(challengeInput, { ...challengeContext }), `${type}.cleanup`);
         } catch (err) {
           await this.logger.log('error', `Error during ${type}.cleanup`, err);
         } finally {
-          this.pendingChallenges = this.pendingChallenges.filter((c) => c !== challengeInput);
+          this.pendingChallenges = this.pendingChallenges.filter((c) => c.input !== challengeInput);
         }
       }
     }

package/readme.hints.md

@@ -1,81 +0,0 @@
-- this repo is dependent on letsencrypt and its limits
-- to simpify the outside API, smartacme is stateful, meaning it works with a mongodb and a collection called 'SmartacmeCert'.
-
-## Certificate Request Behavior
-
-As of v7.4.0, SmartAcme no longer automatically requests wildcard certificates for all domain requests. This change was made to fix issues with HTTP-01 only configurations which cannot validate wildcard domains.
-
-- By default, `getCertificateForDomain('example.com')` only requests a certificate for `example.com`
-- To request both regular and wildcard certificates, use `getCertificateForDomain('example.com', { includeWildcard: true })`
-- Wildcard certificates require a DNS-01 challenge handler to be configured
-- Direct wildcard requests like `getCertificateForDomain('*.example.com')` only request the wildcard certificate
-
-This change ensures HTTP-01 only configurations work properly while still allowing wildcard certificates when needed and supported.
-
-## ACME Protocol Implementation
-
-As of v8.1.0, the `acme-client` npm package has been replaced with a custom OOP implementation under `ts/acme/`. This uses `node:crypto` for all cryptographic operations and `@peculiar/x509` solely for CSR generation. The implementation follows RFC 8555.
-
-Key files:
-- `ts/acme/acme.classes.client.ts` — Top-level facade (`AcmeClient`), accepts optional `logger` callback
-- `ts/acme/acme.classes.crypto.ts` — Key gen, JWK, JWS signing, CSR (`AcmeCrypto`)
-- `ts/acme/acme.classes.http-client.ts` — JWS-signed HTTP transport with nonce management and logging
-- `ts/acme/acme.classes.error.ts` — Structured `AcmeError` with type URN, subproblems, Retry-After, `isRetryable`/`isRateLimited`
-- `ts/acme/acme.classes.account.ts` — Account registration
-- `ts/acme/acme.classes.order.ts` — Order lifecycle + polling
-- `ts/acme/acme.classes.challenge.ts` — Key authorization + challenge completion
-- `ts/acme/acme.classes.directory.ts` — CA directory URL constants (`ACME_DIRECTORY_URLS`)
-
-Usage in `ts/plugins.ts`: `import * as acme from './acme/index.js'` (replaces `acme-client`)
-
-## Concurrency & Rate Limiting (taskbuffer integration)
-
-As of v9.1.0, `@push.rocks/lik.InterestMap` was replaced with `@push.rocks/taskbuffer.TaskManager` for coordinating concurrent certificate requests. This provides:
-
-- **Per-domain mutex** (`cert-domain-mutex`): Only one ACME issuance per TLD at a time, with `resultSharingMode: 'share-latest'` so queued callers get the same result without re-issuing.
-- **Global concurrency cap** (`acme-global-concurrency`): Limits total parallel ACME operations (default 5, configurable via `maxConcurrentIssuances`).
-- **Account-level rate limiting** (`acme-account-rate-limit`): Sliding-window rate limit (default 250 orders per 3 hours, configurable via `maxOrdersPerWindow`/`orderWindowMs`) to stay under Let's Encrypt limits.
-- **Step-based progress**: The cert issuance task uses `notifyStep()` for prepare/authorize/finalize/store phases, observable via `smartAcme.certIssuanceEvents`.
-
-Key implementation details:
-- A single reusable `Task` named `cert-issuance` handles all domains via `triggerTaskConstrained()` with different inputs.
-- The `shouldExecute` callback on the domain mutex checks the certmanager cache as a safety net.
-- `TaskManager.start()` is called in `SmartAcme.start()` and `TaskManager.stop()` in `SmartAcme.stop()`.
-- The "no cronjobs specified" log messages during tests come from taskbuffer's internal CronManager polling — harmless noise when no cron tasks are scheduled.
-
-## ACME Directory Server (ts_server/)
-
-As of v9.2.0, a built-in ACME Directory Server lives under `ts_server/`. This is a full RFC 8555-compliant CA server that allows running your own Certificate Authority.
-
-Key files:
-- `ts_server/server.classes.acmeserver.ts` — Top-level `AcmeServer` facade (start/stop/config)
-- `ts_server/server.classes.ca.ts` — Self-signed root CA generation + certificate signing via `@peculiar/x509`
-- `ts_server/server.classes.jws.verifier.ts` — JWS signature verification (inverse of `AcmeCrypto.createJws`)
-- `ts_server/server.classes.router.ts` — Minimal HTTP router with `:param` support using raw `node:http`
-- `ts_server/server.classes.nonce.ts` — Single-use replay nonce management
-- `ts_server/server.classes.challenge.verifier.ts` — HTTP-01/DNS-01 verification (with bypass mode)
-- `ts_server/server.classes.account.store.ts` — In-memory account storage
-- `ts_server/server.classes.order.store.ts` — In-memory order/authz/challenge/cert storage
-- `ts_server/server.handlers.*.ts` — Route handlers for each ACME endpoint
-
-Design decisions:
-- Uses raw `node:http` (no framework dependency — `@api.global/typedserver` was explicitly removed in v8.1.0)
-- Zero new dependencies: uses `node:crypto`, `@peculiar/x509`, and existing project deps
-- Reuses `AcmeCrypto` for JWK thumbprint/base64url, ACME interfaces for response types, `AcmeError` patterns
-- `AcmeCrypto.getAlg()` was made public (was private) for use by the JWS verifier
-- Storage interfaces (`IServerAccountStore`, `IServerOrderStore`) are pluggable, with in-memory defaults
-- `challengeVerification: false` option auto-approves challenges for testing
-- `tsbuild tsfolders` automatically compiles `ts_server/` to `dist_ts_server/`
-
-## Dependency Notes
-
-- `acme-client` was replaced with custom implementation in `ts/acme/` + `@peculiar/x509` for CSR generation
-- `@push.rocks/smartfile`, `@api.global/typedserver`, `@push.rocks/smartrequest`, `@push.rocks/smartpromise` were removed as unused dependencies in v8.1.0
-- The `@apiclient.xyz/cloudflare` `convenience` namespace is deprecated but still functional. The `Dns01Handler` accepts an `IConvenientDnsProvider` interface which remains stable.
-- Test imports use `@git.zone/tstest/tapbundle` (not `@push.rocks/tapbundle`)
-- Build uses `tsbuild tsfolders` (v4.4.0+) — auto-discovers and compiles `ts/` and `ts_server/` directories
-- `@peculiar/x509` v2.0.0 removed `reflect-metadata` from its dependencies. Since `tsyringe` (used internally by `@peculiar/x509`) requires the Reflect polyfill, `reflect-metadata` is now a direct dependency and imported in `ts/acme/acme.classes.crypto.ts` and `ts_server/server.classes.ca.ts`.
-- `@push.rocks/taskbuffer` upgraded from v6 to v8 (required by smartdata 7.1.3). API surface is backward-compatible.
-- TypeScript 6 (via tsbuild 4.4.0) requires `"types": ["node"]` in tsconfig.json for `ts_server/` compilation to resolve `@types/node`.
-- TypeScript 6 deprecated `baseUrl` in tsconfig — removed it since `paths` was empty.
-- Config file renamed from `npmextra.json` to `.smartconfig.json` (ecosystem convention change).

package/readme.plan.md

@@ -1,3 +0,0 @@
-## Plan
-
-Move the