@embedpdf/core-signature 3.0.0-next.13 → 3.0.0-next.15

package/dist/index.d.ts

@@ -31,6 +31,8 @@ interface ParsedCmsInternal {
   certificates: pkijs.Certificate[];
   /** DER of the signing-certificate-v2 attribute's first certHash, when present. */
   essCertHash: Uint8Array | null;
+  /** A timestamp token's encapsulated TSTInfo (`content: 'tst-info'`); null for a detached CMS. */
+  eContent: Uint8Array | null;
 }
 /** Parse a detached CMS SignedData with exactly one signer. Throws `CmsError`. */
 declare function parseDetachedCms(cms: Uint8Array): ParsedCms;
@@ -81,6 +83,11 @@ interface BuildDetachedCmsInput {
 declare function buildDetachedCms(input: BuildDetachedCmsInput): Promise<Uint8Array>;
 //#endregion
 //#region src/gate.d.ts
+/**
+ * The shape the CMS must have: a PDF signature's (`pkcs7`, `cades-b`), or a
+ * document timestamp's RFC 3161 token (`timestamp`).
+ */
+type CompletionProfile = SignatureProfile | 'timestamp';
 type CompletionRefusal = 'malformed' | 'too-large' | 'algorithm-mismatch' | 'digest-mismatch' | 'signature-invalid' | 'profile-violation';
 type CompletionGate = {
   ok: true;
@@ -100,7 +107,7 @@ type CompletionGate = {
 declare function verifyForCompletion(input: {
   cms: Uint8Array;
   prepared: SignaturePrepared;
-  profile: SignatureProfile;
+  profile: CompletionProfile;
 }): Promise<CompletionGate>;
 //#endregion
 //#region src/trust.d.ts
@@ -144,26 +151,36 @@ declare function validateChain(cms: Uint8Array | ParsedCmsInternal, trust: Trust
 /** A service that turns a digest into a finished detached CMS (most hosted signing APIs). */
 interface CmsSigner {
   readonly kind: 'cms';
+  /**
+   * The CMS for a digest: a detached signature, or for `'ETSI.RFC3161'` (a
+   * document timestamp) the RFC 3161 token a timestamp authority returns.
+   */
   sign(input: {
     digest: Uint8Array;
     algorithm: Exclude<DigestAlgorithm, 'sha1'>;
-    subFilter: SignatureSubFilter;
+    subFilter: SignatureSubFilter | 'ETSI.RFC3161';
   }): Promise<Uint8Array>;
 }
 type SignerPort = CmsSigner | RawSigner;
-type SignInput = Omit<SignaturePrepareInput, 'kind'> & {
-  signer: SignerPort;
+/**
+ * What `prepare` takes, plus the key that signs the digest. For a document
+ * timestamp (`kind: 'timestamp'`) the key is a timestamp authority: a CMS
+ * key that returns an RFC 3161 token.
+ */
+type SignInput = SignaturePrepareInput & {
+  key: SignerPort;
 };
-declare class SigningError extends Error {
-  readonly reason: CompletionRefusal;
-  constructor(reason: CompletionRefusal, detail: string);
-}
+/**
+ * The CMS shape a `/SubFilter` promises (`'timestamp'` for an RFC 3161
+ * token); `InvalidArg` for one this package doesn't know.
+ */
 declare function profileFor(subFilter: SignatureSubFilter): SignatureProfile;
+declare function profileFor(subFilter: SignatureSubFilter | 'ETSI.RFC3161'): CompletionProfile;
 /**
- * Sign a field in one call: `prepare` on the engine, the signer turns the
+ * Sign a field in one call: `prepare` on the engine, the key turns the
  * digest into a CMS (or a raw signature this package wraps), the gate
  * checks the CMS matches what was prepared, `complete` installs it. Any
- * failure aborts the candidate and rethrows; the document is never left
+ * failure cancels the candidate and rethrows; the document is never left
  * with a pending signing.
  */
 declare function sign(doc: DocumentHandle, input: SignInput): Promise<SignatureCompleteResult>;
@@ -218,7 +235,7 @@ interface ValidateSignaturesOptions {
  * Validate every signature of a document: integrity from the engine's
  * bytes, cryptography from the CMS, trust from the caller's anchors.
  */
-declare function validateSignatures(doc: DocumentHandle, opts?: ValidateSignaturesOptions): Promise<SignatureVerdict[]>;
+declare function validateSignatures(doc: DocumentHandle, options?: ValidateSignaturesOptions): Promise<SignatureVerdict[]>;
 //#endregion
 //#region src/signers/webcrypto.d.ts
 /**
@@ -241,30 +258,44 @@ interface TestSigner extends RawSigner {
  * self-signed certificate, never persisted. Trust it with
  * `{ anchors: async () => [signer.certificate] }`.
  */
-declare function createTestSigner(opts?: {
+declare function createTestSigner(options?: {
   commonName?: string;
   algorithm?: 'RSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
   hash?: 'sha256' | 'sha384' | 'sha512';
 }): Promise<TestSigner>;
+interface TestTimestampAuthority extends CmsSigner {
+  /** DER of the authority's self-signed certificate. */
+  readonly certificate: Uint8Array;
+}
+/**
+ * A throwaway RFC 3161 timestamp authority for tests and demos: it stamps
+ * whatever digest it is given with the current time, signed by a fresh
+ * self-signed key. The key for `sign(doc, { kind: 'timestamp', key })`;
+ * never use it to stamp a real document.
+ */
+declare function createTestTimestampAuthority(options?: {
+  commonName?: string;
+}): Promise<TestTimestampAuthority>;
 /** A WebCrypto signing key pair; `extractable: false` keeps the private key inside the runtime for good. */
 declare function generateSigningKeyPair(algorithm: 'RSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA', hash: 'sha256' | 'sha384' | 'sha512', extractable: boolean): Promise<CryptoKeyPair>;
 //#endregion
 //#region src/signers/remote.d.ts
 /**
- * A `CmsSigner` over the customer's own signing service or HSM: the engine's
- * digest goes out, a finished detached CMS comes back. Nothing but the
- * digest (and which hash and profile it is for) ever leaves the runtime.
+ * A `CmsSigner` over the customer's own signing service, HSM or timestamp
+ * authority: the engine's digest goes out, a finished detached CMS (or, for
+ * `'ETSI.RFC3161'`, an RFC 3161 token) comes back. Nothing but the digest
+ * (and which hash and profile it is for) ever leaves the runtime.
  */
 declare function remoteSigner(input: {
   sign: (request: {
     digest: Uint8Array;
     algorithm: 'sha256' | 'sha384' | 'sha512';
-    subFilter: 'adbe.pkcs7.detached' | 'ETSI.CAdES.detached';
+    subFilter: 'adbe.pkcs7.detached' | 'ETSI.CAdES.detached' | 'ETSI.RFC3161';
   }) => Promise<Uint8Array>;
 }): CmsSigner;
 //#endregion
 //#region src/signers/personal.d.ts
-/** What a personal signer keeps: a NON-extractable private key and its self-signed certificate. */
+/** What a personal signer keeps: a non-extractable private key and its self-signed certificate. */
 interface PersonalKeyRecord {
   privateKey: CryptoKey;
   certificate: Uint8Array;
@@ -302,7 +333,7 @@ declare function memoryKeyStore(): PersonalKeyStore;
  * itself (structured clone), so the key survives reloads without ever
  * existing as bytes.
  */
-declare function indexedDbKeyStore(dbName: string, opts?: {
+declare function indexedDbKeyStore(dbName: string, options?: {
   storeName?: string;
 }): PersonalKeyStore;
 //#endregion
@@ -324,5 +355,5 @@ declare function selfSignedCertificate(input: {
 /** The subject common name of a DER certificate, or null when it has none. */
 declare function certificateCommonName(der: Uint8Array): string | null;
 //#endregion
-export { type BuildDetachedCmsInput, CmsError, type CmsSigner, type CompletionGate, type CompletionRefusal, type CryptographyVerdict, type IntegrityVerdict, type ModificationsVerdict, type ParsedCms, type PersonalKeyRecord, type PersonalKeyStore, type PersonalSigner, type RawSignatureAlgorithm, type RawSigner, type SignInput, type SignatureProfile, type SignatureVerdict, type SignerPort, SigningError, type TestSigner, type TrustPort, type TrustStatus, type TrustVerdict, type ValidateSignaturesOptions, type ValidationTime, buildDetachedCms, certificateCommonName, createTestSigner, generateSigningKeyPair, indexedDbKeyStore, memoryKeyStore, parseDetachedCms, personalSigner, profileFor, remoteSigner, selfSignedCertificate, sign, validateChain, validateSignatures, verifyCmsSignature, verifyForCompletion, webCryptoSigner };
+export { type BuildDetachedCmsInput, CmsError, type CmsSigner, type CompletionGate, type CompletionProfile, type CompletionRefusal, type CryptographyVerdict, type IntegrityVerdict, type ModificationsVerdict, type ParsedCms, type PersonalKeyRecord, type PersonalKeyStore, type PersonalSigner, type RawSignatureAlgorithm, type RawSigner, type SignInput, type SignatureProfile, type SignatureVerdict, type SignerPort, type TestSigner, type TestTimestampAuthority, type TrustPort, type TrustStatus, type TrustVerdict, type ValidateSignaturesOptions, type ValidationTime, buildDetachedCms, certificateCommonName, createTestSigner, createTestTimestampAuthority, generateSigningKeyPair, indexedDbKeyStore, memoryKeyStore, parseDetachedCms, personalSigner, profileFor, remoteSigner, selfSignedCertificate, sign, validateChain, validateSignatures, verifyCmsSignature, verifyForCompletion, webCryptoSigner };
 //# sourceMappingURL=index.d.ts.map