@push.rocks/smartacme 9.5.0 → 9.7.0

package/ts/acme/acme.classes.http-client.ts

@@ -20,7 +20,7 @@ export class AcmeHttpClient {
   private httpsAgent: https.Agent;
   private httpAgent: http.Agent;
 
-  constructor(directoryUrl: string, accountKeyPem: string, logger?: TAcmeLogger) {
+  constructor(directoryUrl: string, accountKeyPem: string, logger?: TAcmeLogger, public readonly signal?: AbortSignal) {
     this.directoryUrl = directoryUrl;
     this.accountKeyPem = accountKeyPem;
     this.logger = logger;
@@ -199,6 +199,7 @@ export class AcmeHttpClient {
         method,
         headers: requestHeaders,
         agent: isHttps ? this.httpsAgent : this.httpAgent,
+        signal: this.signal,
       };
 
       const req = lib.request(options, (res) => {

package/ts/acme/acme.classes.order.ts

@@ -1,5 +1,6 @@
 import { AcmeCrypto } from './acme.classes.crypto.js';
 import { AcmeError } from './acme.classes.error.js';
+import { setTimeout as delay } from 'node:timers/promises';
 import type { AcmeHttpClient } from './acme.classes.http-client.js';
 import type {
   IAcmeAuthorization,
@@ -33,6 +34,12 @@ export class AcmeOrderManager {
     return order;
   }
 
+  /** Read an acknowledged order without creating or finalizing another one. */
+  async get(url: string): Promise<IAcmeOrder> {
+    const response = await this.httpClient.signedRequest(url, null);
+    return { ...response.data as IAcmeOrder, url };
+  }
+
   /**
    * Retrieve all authorizations for an order (POST-as-GET each authorization URL)
    */
@@ -117,9 +124,13 @@ export class AcmeOrderManager {
       const retryAfter = parseInt(response.headers['retry-after'] || '0', 10);
       const delay =
         retryAfter > 0 ? retryAfter * 1000 : Math.min(initialDelay * Math.pow(2, i), 30000);
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await this.wait(delay);
     }
 
     throw new Error(`Timeout waiting for valid status after ${maxAttempts} attempts`);
   }
+
+  private async wait(milliseconds: number): Promise<void> {
+    await delay(milliseconds, undefined, { signal: this.httpClient.signal });
+  }
 }

package/ts/classes.exact-certificate-issuer.ts

@@ -0,0 +1,408 @@
+import * as plugins from './plugins.js';
+import type {
+  IExactCertificate,
+  IExactCertificateIdentity,
+  IExactCertificateRequest,
+  IExactIssuanceInfo,
+  IExactIssuanceRecord,
+  IExactIssuanceRecoveryRequest,
+  IExactIssuanceStore,
+  TExactCertificateResult,
+} from './interfaces/exact-issuance.js';
+
+export function normalizeCertificateIdentifiers(input: readonly string[]): string[] {
+  if (!Array.isArray(input) || input.length < 1 || input.length > 100) {
+    throw new Error('Between one and 100 explicit DNS identifiers are required');
+  }
+  return [...new Set(Array.from(input, (value) => {
+    if (typeof value !== 'string' || value.length > 1024) throw new Error('Invalid DNS identifier');
+    const trimmed = value.trim().toLowerCase().replace(/\.$/, '');
+    if (/[/\\:@?#%\s]/.test(trimmed)) throw new Error('Invalid DNS identifier');
+    const wildcard = trimmed.startsWith('*.');
+    const name = plugins.url.domainToASCII(wildcard ? trimmed.slice(2) : trimmed);
+    if (!name || plugins.net.isIP(name) !== 0 || name.length > 253 || name.split('.').length < 2
+      || name.split('.').some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))) {
+      throw new Error('Invalid DNS identifier');
+    }
+    return `${wildcard ? '*.' : ''}${name}`;
+  }))].sort();
+}
+
+export interface IExactCertificateIssuerOptions {
+  store: IExactIssuanceStore;
+  client: plugins.acme.AcmeClient;
+  directoryUrl: string;
+  accountThumbprint: string;
+  dns: plugins.smartdnsClient.Smartdns;
+  handlers: plugins.handlers.IChallengeHandler<plugins.tsclass.network.IDnsChallenge>[];
+  signal: AbortSignal;
+  /** Explicit propagation grace period, including for custom ACME authorities. */
+  dnsPropagationDelayMs: number;
+}
+
+/** Owns exact-name issuance and recovery; the embedding service supplies storage. */
+export class ExactCertificateIssuer {
+  constructor(private options: IExactCertificateIssuerOptions) {}
+
+  public identity(request: IExactCertificateRequest): IExactCertificateIdentity {
+    if (typeof request.namespace !== 'string' || !/^[\x21-\x7e]{1,200}$/.test(request.namespace)) {
+      throw new Error('A nonempty printable isolation namespace of at most 200 characters is required');
+    }
+    const identifiers = normalizeCertificateIdentifiers(request.identifiers);
+    const binding = {
+      namespace: request.namespace,
+      identifiers,
+      directoryUrl: this.options.directoryUrl,
+      accountThumbprint: this.options.accountThumbprint,
+    };
+    return {
+      ...binding,
+      certificateKey: `exact-v1:${plugins.crypto.createHash('sha256').update(JSON.stringify(binding)).digest('hex')}`,
+    };
+  }
+
+  public async status(request: IExactCertificateRequest): Promise<IExactIssuanceInfo | null> {
+    const identity = this.identity(request);
+    const record = await this.options.store.getIssuance(identity.certificateKey);
+    if (record) this.validateRecord(record, identity);
+    return record ? this.info(record) : null;
+  }
+
+  /** Validate the cache before taking any issuance or CA rate-limit slot. */
+  public async cached(request: IExactCertificateRequest): Promise<TExactCertificateResult | null> {
+    const identity = this.identity(request);
+    const certificate = await this.options.store.getCertificate(identity.certificateKey);
+    if (!certificate) return null;
+    this.validateCertificate(certificate, identity);
+    const record = await this.options.store.getIssuance(identity.certificateKey);
+    if (record?.status !== 'ready' || certificate.id !== record.issuanceId
+      || Date.now() >= certificate.renewAfter || Date.now() >= certificate.validUntil) return null;
+    this.validateRecord(record, identity);
+    return { status: 'ready', certificate, issuance: this.info(record) };
+  }
+
+  public async run(request: IExactCertificateRequest): Promise<TExactCertificateResult> {
+    this.options.signal.throwIfAborted();
+    const identity = this.identity(request);
+    let record = await this.options.store.getIssuance(identity.certificateKey);
+    const cached = await this.options.store.getCertificate(identity.certificateKey);
+    if (cached) {
+      this.validateCertificate(cached, identity);
+      if (record?.status === 'ready' && cached.id === record.issuanceId && Date.now() < cached.renewAfter) {
+        this.validateRecord(record, identity);
+        return { status: 'ready', certificate: cached, issuance: this.info(record) };
+      }
+    }
+    if (record?.status === 'ready' && !cached) {
+      this.validateRecord(record, identity);
+      return await this.advance(record, true);
+    }
+    if (!record || record.status === 'ready') {
+      const [privateKey, csr] = await plugins.acme.AcmeCrypto.createCsr({
+        commonName: identity.identifiers[0], altNames: identity.identifiers.slice(1),
+      });
+      const next: IExactIssuanceRecord = {
+        ...identity, issuanceId: plugins.crypto.randomUUID(), revision: (record?.revision ?? -1) + 1,
+        status: 'prepared', createdAt: Date.now(), updatedAt: Date.now(), privateKey, csr,
+        pendingChallenges: [],
+      };
+      this.options.signal.throwIfAborted();
+      if (!await this.options.store.compareAndSetIssuance(identity.certificateKey, record?.revision ?? null, next)) {
+        const current = await this.requiredRecord(identity.certificateKey);
+        return { status: 'pending', issuance: this.info(current) };
+      }
+      record = next;
+    }
+    this.validateRecord(record, identity);
+    return await this.advance(record, false);
+  }
+
+  public async recover(request: IExactIssuanceRecoveryRequest): Promise<TExactCertificateResult> {
+    if (!['recheck', 'retry-proven-unapplied', 'abandon'].includes(request.action)
+      || !Number.isSafeInteger(request.expectedRevision) || request.expectedRevision < 0
+      || typeof request.issuanceId !== 'string' || !request.issuanceId) {
+      throw new Error('Invalid issuance recovery request');
+    }
+    const identity = this.identity(request);
+    let record = await this.requiredRecord(identity.certificateKey);
+    this.validateRecord(record, identity);
+    if (record.issuanceId !== request.issuanceId || record.revision !== request.expectedRevision) {
+      throw new Error('Issuance recovery revision conflict');
+    }
+    if (request.action === 'abandon') {
+      if (record.status === 'ready') throw new Error('A completed issuance cannot be abandoned');
+      record = await this.save(record, { status: 'abandoned_unverified' });
+      await this.cleanup(record);
+      return { status: 'pending', issuance: this.info(await this.requiredRecord(record.certificateKey)) };
+    }
+    if (record.status === 'abandoned_unverified') {
+      throw new Error('Abandoned issuance requires external resolution; new issuance remains blocked');
+    }
+    if (request.action === 'retry-proven-unapplied') {
+      // Only an acknowledged rejection of newOrder proves no order was created.
+      if (record.order || record.status !== 'failed' || record.errorCode !== 'rate_limited') {
+        throw new Error('The previous external effect is not proven unapplied');
+      }
+      if (record.retryAfter && record.retryAfter > Date.now()) {
+        return { status: 'pending', issuance: this.info(record) };
+      }
+      record = await this.save(record, { status: 'prepared', errorCode: undefined, retryAfter: undefined });
+      return await this.advance(record, false);
+    }
+    return await this.advance(record, true);
+  }
+
+  private async advance(initial: IExactIssuanceRecord, recheckOnly: boolean): Promise<TExactCertificateResult> {
+    let record = initial;
+    this.options.signal.throwIfAborted();
+    if (record.status === 'abandoned_unverified' || record.status === 'failed') {
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    if (record.status === 'creating' || (record.status === 'indeterminate' && !record.order)) {
+      record = await this.save(record, { status: 'indeterminate', errorCode: 'order_outcome_unknown' });
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    if (record.status === 'prepared') {
+      if (recheckOnly) return { status: 'pending', issuance: this.info(record) };
+      // Prove challenge support before creating an irreversible CA order.
+      await this.handler(record);
+      record = await this.save(record, { status: 'creating' });
+      let order: plugins.acme.IAcmeOrder;
+      try {
+        this.options.signal.throwIfAborted();
+        order = await this.options.client.createOrder({
+          identifiers: record.identifiers.map((value) => ({ type: 'dns', value })),
+        });
+      } catch (error) {
+        const rejected = error instanceof plugins.acme.AcmeError && error.isRateLimited;
+        record = await this.save(record, {
+          status: rejected ? 'failed' : 'indeterminate',
+          errorCode: rejected ? 'rate_limited' : 'order_outcome_unknown',
+          retryAfter: rejected ? Date.now() + Math.max(error.retryAfter, 60) * 1000 : undefined,
+        });
+        return { status: 'pending', issuance: this.info(record) };
+      }
+      if (!order.url) {
+        record = await this.save(record, { status: 'indeterminate', errorCode: 'order_outcome_unknown' });
+        return { status: 'pending', issuance: this.info(record) };
+      }
+      record = await this.save(record, { order, status: 'authorizing' });
+    }
+    if (!record.order) throw new Error('Issuance record has no acknowledged order');
+    const observed = await this.options.client.getOrder(record.order.url);
+    this.validateOrder(observed, record);
+    record = await this.save(record, { order: observed, errorCode: undefined });
+    if (observed.status === 'invalid' || observed.status === 'expired' || observed.status === 'revoked') {
+      record = await this.save(record, { status: 'failed', errorCode: 'order_invalid' });
+      await this.cleanup(record);
+      return { status: 'pending', issuance: this.info(await this.requiredRecord(record.certificateKey)) };
+    }
+    if (observed.status === 'valid') return await this.finish(record);
+    if (recheckOnly) {
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    if (record.status === 'finalizing' || record.status === 'indeterminate') {
+      // Acknowledged processing/ready observations do not prove a previous
+      // finalize request was unapplied. Never send a new CSR on uncertainty.
+      record = await this.save(record, { status: 'indeterminate', errorCode: 'order_outcome_unknown' });
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    if (observed.status === 'pending') {
+      record = await this.authorize(record);
+      if (record.status === 'failed') return { status: 'pending', issuance: this.info(record) };
+    }
+    const ready = await this.options.client.getOrder(record.order!.url);
+    this.validateOrder(ready, record);
+    record = await this.save(record, { order: ready });
+    if (ready.status === 'valid') return await this.finish(record);
+    if (ready.status !== 'ready') {
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    record = await this.save(record, { status: 'finalizing' });
+    try {
+      this.options.signal.throwIfAborted();
+      await this.options.client.finalizeOrder(structuredClone(ready), record.csr);
+    } catch {
+      // Preserve the acknowledged order and original key/CSR for safe recheck.
+      record = await this.save(record, { status: 'indeterminate', errorCode: 'order_outcome_unknown' });
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    const finalized = await this.options.client.getOrder(ready.url);
+    this.validateOrder(finalized, record);
+    record = await this.save(record, { order: finalized });
+    return finalized.status === 'valid'
+      ? await this.finish(record)
+      : { status: 'pending', issuance: this.info(record) };
+  }
+
+  private async authorize(initial: IExactIssuanceRecord): Promise<IExactIssuanceRecord> {
+    let record = initial;
+    const handler = await this.handler(record);
+    const authorizations = await this.options.client.getAuthorizations(record.order!);
+    for (const authorization of authorizations) {
+      this.options.signal.throwIfAborted();
+      const identifier = `${authorization.wildcard ? '*.' : ''}${authorization.identifier.value}`;
+      if (authorization.identifier.type !== 'dns' || !record.identifiers.includes(identifier)) {
+        throw new Error('CA authorization is outside the requested identifiers');
+      }
+      if (authorization.status === 'valid') continue;
+      if (authorization.status !== 'pending') {
+        return await this.save(record, { status: 'failed', errorCode: 'authorization_failed' });
+      }
+      const challenge = authorization.challenges.find((value) => value.type === 'dns-01');
+      if (!challenge) throw new Error('The CA did not offer DNS-01');
+      const input = {
+        hostName: `_acme-challenge.${authorization.identifier.value}`,
+        challenge: this.options.client.getChallengeKeyAuthorization(challenge),
+      };
+      if (!record.pendingChallenges.some((value) => value.hostName === input.hostName && value.challenge === input.challenge)) {
+        record = await this.save(record, { pendingChallenges: [...record.pendingChallenges, input] });
+      }
+      try {
+        await handler.prepare(input, this.challengeContext(record));
+        if (handler.verify) {
+          await handler.verify(input, this.challengeContext(record));
+        } else {
+          let visible = false;
+          for (let attempt = 0; attempt < 100; attempt++) {
+            this.options.signal.throwIfAborted();
+            const records = await this.options.dns.getRecords(input.hostName, 'TXT', 0);
+            if (records.some((value) => value.value === input.challenge)) { visible = true; break; }
+            await plugins.timers.setTimeout(1000, undefined, { signal: this.options.signal });
+          }
+          if (!visible) throw new Error('DNS-01 propagation timed out');
+        }
+        await plugins.timers.setTimeout(this.options.dnsPropagationDelayMs, undefined, { signal: this.options.signal });
+        await this.options.client.completeChallenge(challenge);
+        await this.options.client.waitForValidStatus(challenge);
+      } finally {
+        // Persist cleanup intent until cleanup actually succeeds, including
+        // failure during prepare, process shutdown, or certificate retrieval.
+        await handler.cleanup(input, this.challengeContext(record));
+        record = await this.save(record, {
+          pendingChallenges: record.pendingChallenges.filter((value) => value.hostName !== input.hostName || value.challenge !== input.challenge),
+        });
+      }
+    }
+    return record;
+  }
+
+  private async finish(initial: IExactIssuanceRecord): Promise<TExactCertificateResult> {
+    let record = initial;
+    if (!record.order?.certificate) throw new Error('Completed order has no certificate URL');
+    const pem = await this.options.client.getCertificate(record.order);
+    const x509 = new plugins.crypto.X509Certificate(pem);
+    const validFrom = new Date(x509.validFrom).getTime();
+    const validUntil = new Date(x509.validTo).getTime();
+    const certificate: IExactCertificate = {
+      ...this.identity(record), id: record.issuanceId, created: Date.now(),
+      privateKey: record.privateKey, csr: record.csr, publicKey: pem, validFrom, validUntil,
+      renewAfter: validUntil - Math.min(10 * 86400000, (validUntil - validFrom) / 3),
+    };
+    try {
+      this.validateCertificate(certificate, record);
+      if (validUntil <= Date.now()) throw new Error('CA returned an expired certificate');
+    } catch {
+      record = await this.save(record, { status: 'failed', errorCode: 'certificate_invalid' });
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    await this.cleanup(record);
+    record = await this.requiredRecord(record.certificateKey);
+    if (record.status === 'abandoned_unverified') {
+      return { status: 'pending', issuance: this.info(record) };
+    }
+    await this.options.store.storeCertificate(certificate);
+    record = await this.save(record, { status: 'ready', errorCode: undefined });
+    return { status: 'ready', certificate, issuance: this.info(record) };
+  }
+
+  private async handler(record: IExactCertificateIdentity) {
+    const handler = this.options.handlers.find((value) => value.getSupportedTypes().includes('dns-01'));
+    if (!handler) throw new Error('Exact issuance requires DNS-01');
+    for (const identifier of record.identifiers) {
+      if (!await handler.checkWetherDomainIsSupported(identifier.replace(/^\*\./, ''))) {
+        throw new Error('DNS-01 ownership is unavailable for a requested identifier');
+      }
+    }
+    return handler;
+  }
+
+  private async cleanup(initial: IExactIssuanceRecord): Promise<void> {
+    let record = initial;
+    if (!record.pendingChallenges.length) return;
+    const handler = this.options.handlers.find((value) => value.getSupportedTypes().includes('dns-01'));
+    if (!handler) throw new Error('DNS-01 cleanup handler is unavailable');
+    for (const input of [...record.pendingChallenges]) {
+      await handler.cleanup(input, this.challengeContext(record));
+      record = await this.save(record, {
+        pendingChallenges: record.pendingChallenges.filter((value) => value.hostName !== input.hostName || value.challenge !== input.challenge),
+      });
+    }
+  }
+
+  private challengeContext(record: IExactIssuanceRecord): plugins.handlers.IChallengeContext {
+    return { operationId: plugins.crypto.createHash('sha256')
+      .update(JSON.stringify(['smartacme-exact-challenge-v1', record.certificateKey, record.issuanceId])).digest('hex') };
+  }
+
+  private validateRecord(record: IExactIssuanceRecord, identity: IExactCertificateIdentity): void {
+    if (record.certificateKey !== identity.certificateKey
+      || this.identity(record).certificateKey !== identity.certificateKey
+      || record.accountThumbprint !== identity.accountThumbprint || record.directoryUrl !== identity.directoryUrl) {
+      throw new Error('Issuance storage identity mismatch');
+    }
+  }
+
+  private validateOrder(order: plugins.acme.IAcmeOrder, record: IExactIssuanceRecord): void {
+    if (!order.url || order.identifiers.some((value) => value.type !== 'dns')
+      || JSON.stringify(normalizeCertificateIdentifiers(order.identifiers.map((value) => value.value))) !== JSON.stringify(record.identifiers)) {
+      throw new Error('CA order identifiers do not match the certificate request');
+    }
+  }
+
+  private validateCertificate(certificate: IExactCertificate, identity: IExactCertificateIdentity): void {
+    if (certificate.certificateKey !== identity.certificateKey
+      || this.identity(certificate).certificateKey !== identity.certificateKey
+      || certificate.accountThumbprint !== identity.accountThumbprint || certificate.directoryUrl !== identity.directoryUrl) {
+      throw new Error('Certificate storage identity mismatch');
+    }
+    const parsed = new plugins.x509.X509Certificate(certificate.publicKey);
+    const names = parsed.getExtension(plugins.x509.SubjectAlternativeNameExtension)?.names.toJSON();
+    if (!names || names.some((value) => value.type !== 'dns')
+      || JSON.stringify(normalizeCertificateIdentifiers(names.map((value) => value.value))) !== JSON.stringify(identity.identifiers)) {
+      throw new Error('Certificate identifiers exceed or differ from the requested scope');
+    }
+    const x509 = new plugins.crypto.X509Certificate(certificate.publicKey);
+    if (x509.ca || !x509.checkPrivateKey(plugins.crypto.createPrivateKey(certificate.privateKey))
+      || new Date(x509.validFrom).getTime() !== certificate.validFrom
+      || new Date(x509.validTo).getTime() !== certificate.validUntil
+      || certificate.validFrom > Date.now() + 300000
+      || !Number.isFinite(certificate.renewAfter) || certificate.renewAfter >= certificate.validUntil) {
+      throw new Error('Invalid certificate key, lifetime, or constraints');
+    }
+  }
+
+  private info(record: IExactIssuanceRecord): IExactIssuanceInfo {
+    return {
+      certificateKey: record.certificateKey, issuanceId: record.issuanceId,
+      identifiers: [...record.identifiers], status: record.status, revision: record.revision,
+      createdAt: record.createdAt, updatedAt: record.updatedAt,
+      errorCode: record.errorCode, retryAfter: record.retryAfter,
+    };
+  }
+
+  private async requiredRecord(key: string): Promise<IExactIssuanceRecord> {
+    const record = await this.options.store.getIssuance(key);
+    if (!record) throw new Error('Issuance recovery record is missing');
+    return record;
+  }
+
+  private async save(record: IExactIssuanceRecord, patch: Partial<Pick<IExactIssuanceRecord,
+    'status' | 'order' | 'pendingChallenges' | 'errorCode' | 'retryAfter'>>): Promise<IExactIssuanceRecord> {
+    const next = { ...record, ...patch, revision: record.revision + 1, updatedAt: Date.now() };
+    if (!await this.options.store.compareAndSetIssuance(record.certificateKey, record.revision, next)) {
+      throw new Error('Issuance changed concurrently; reload its durable state before proceeding');
+    }
+    return next;
+  }
+}

package/ts/handlers/IChallengeHandler.ts

@@ -1,3 +1,9 @@
+/** Stable resource owner across preparation, retries, cleanup and exact recovery. */
+export interface IChallengeContext {
+  /** Opaque identity for one order attempt; never reuse resources across owners. */
+  operationId: string;
+}
+
 /**
  * Pluggable interface for ACME challenge handlers.
  * Supports DNS-01, HTTP-01, TLS-ALPN-01, or custom challenge types.
@@ -10,15 +16,15 @@ export interface IChallengeHandler<T> {
   /**
    * Prepare the challenge: set DNS record, start HTTP/TLS server, etc.
    */
-  prepare(ch: T): Promise<void>;
+  prepare(ch: T, context?: IChallengeContext): Promise<void>;
   /**
    * Optional extra verify step (HTTP GET, ALPN handshake).
    */
-  verify?(ch: T): Promise<void>;
+  verify?(ch: T, context?: IChallengeContext): Promise<void>;
   /**
    * Clean up resources: remove DNS record, stop server.
    */
-  cleanup(ch: T): Promise<void>;
+  cleanup(ch: T, context?: IChallengeContext): Promise<void>;
 
   checkWetherDomainIsSupported(domainArg: string): Promise<boolean>;
-}
+}

package/ts/handlers/index.ts

@@ -1,5 +1,5 @@
-export type { IChallengeHandler } from './IChallengeHandler.js';
+export type { IChallengeHandler, IChallengeContext } from './IChallengeHandler.js';
 // Removed legacy handler adapter
 export { Dns01Handler } from './Dns01Handler.js';
 export { Http01Webroot } from './Http01Handler.js';
-export { Http01MemoryHandler } from './Http01MemoryHandler.js';
+export { Http01MemoryHandler } from './Http01MemoryHandler.js';

package/ts/index.ts

@@ -1,6 +1,8 @@
 export * from './smartacme.classes.smartacme.js';
 export { SmartacmeCert as Cert } from './smartacme.classes.cert.js';
 export type { ICertManager } from './interfaces/certmanager.js';
+export type * from './interfaces/exact-issuance.js';
+export { normalizeCertificateIdentifiers } from './classes.exact-certificate-issuer.js';
 
 // certmanagers
 import * as certmanagers from './certmanagers/index.js';

package/ts/interfaces/exact-issuance.ts

@@ -0,0 +1,104 @@
+import type { IAcmeOrder } from '../acme/acme.interfaces.js';
+
+/** Explicit identifiers never inherit parent or wildcard coverage. */
+export interface IExactCertificateRequest {
+  namespace: string;
+  identifiers: string[];
+}
+
+export interface IExactCertificateIdentity extends IExactCertificateRequest {
+  certificateKey: string;
+  directoryUrl: string;
+  accountThumbprint: string;
+}
+
+export interface IExactCertificate extends IExactCertificateIdentity {
+  id: string;
+  privateKey: string;
+  publicKey: string;
+  csr: string;
+  created: number;
+  validFrom: number;
+  validUntil: number;
+  renewAfter: number;
+}
+
+export type TExactIssuanceStatus =
+  | 'prepared'
+  | 'creating'
+  | 'authorizing'
+  | 'finalizing'
+  | 'ready'
+  | 'failed'
+  | 'indeterminate'
+  | 'abandoned_unverified';
+
+export type TExactIssuanceErrorCode =
+  | 'order_outcome_unknown'
+  | 'order_invalid'
+  | 'authorization_failed'
+  | 'certificate_invalid'
+  | 'challenge_cleanup_pending'
+  | 'rate_limited'
+  | 'transport_unavailable';
+
+export interface IExactDnsChallenge {
+  hostName: string;
+  challenge: string;
+}
+
+/** Sensitive durable state. Never return this record through a status API. */
+export interface IExactIssuanceRecord extends IExactCertificateIdentity {
+  issuanceId: string;
+  revision: number;
+  status: TExactIssuanceStatus;
+  createdAt: number;
+  updatedAt: number;
+  privateKey: string;
+  csr: string;
+  order?: IAcmeOrder;
+  pendingChallenges: IExactDnsChallenge[];
+  errorCode?: TExactIssuanceErrorCode;
+  retryAfter?: number;
+}
+
+/**
+ * Storage must acknowledge durable writes and atomically compare revisions.
+ * A null revision means insert only if absent. No filesystem fallback is used.
+ * Keep unresolved records until their external outcome has been reconciled.
+ */
+export interface IExactIssuanceStore {
+  getAccountKey(accountId: string): Promise<string | null>;
+  createAccountKey(accountId: string, privateKey: string): Promise<boolean>;
+  getIssuance(certificateKey: string): Promise<IExactIssuanceRecord | null>;
+  compareAndSetIssuance(
+    certificateKey: string,
+    expectedRevision: number | null,
+    record: IExactIssuanceRecord,
+  ): Promise<boolean>;
+  getCertificate(certificateKey: string): Promise<IExactCertificate | null>;
+  storeCertificate(certificate: IExactCertificate): Promise<void>;
+}
+
+/** Safe status projection; contains neither keys nor challenge material. */
+export interface IExactIssuanceInfo {
+  certificateKey: string;
+  issuanceId: string;
+  identifiers: string[];
+  status: TExactIssuanceStatus;
+  revision: number;
+  createdAt: number;
+  updatedAt: number;
+  errorCode?: TExactIssuanceErrorCode;
+  retryAfter?: number;
+}
+
+export type TExactCertificateResult =
+  | { status: 'ready'; certificate: IExactCertificate; issuance: IExactIssuanceInfo }
+  | { status: 'pending'; issuance: IExactIssuanceInfo };
+
+export interface IExactIssuanceRecoveryRequest extends IExactCertificateRequest {
+  issuanceId: string;
+  expectedRevision: number;
+  action: 'recheck' | 'retry-proven-unapplied' | 'abandon';
+}

package/ts/plugins.ts

@@ -3,10 +3,14 @@ import 'reflect-metadata';
 
 // node native
 import * as crypto from 'node:crypto';
+import * as url from 'node:url';
+import * as net from 'node:net';
+import * as timers from 'node:timers/promises';
+import * as x509 from '@peculiar/x509';
 import * as fs from 'fs';
 import * as path from 'path';
 
-export { crypto, fs, path };
+export { crypto, fs, path, url, net, timers, x509 };
 
 // @apiclient.xyz scope
 import * as cloudflare from '@apiclient.xyz/cloudflare';