@embedpdf/core-signature 3.0.0-next.13

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+import * as pkijs from "pkijs";
+import { DigestAlgorithm, DocumentHandle, SignatureCompleteResult, SignatureDTO, SignaturePrepareInput, SignaturePrepared, SignatureSubFilter } from "@embedpdf/engine-core/runtime";
+//#region src/cms/parse.d.ts
+/** What a detached CMS says about itself. Nothing here is verified. */
+interface ParsedCms {
+  digestAlgorithm: DigestAlgorithm;
+  /** The `message-digest` signed attribute: what the signer claims the content hashes to. */
+  messageDigest: Uint8Array;
+  /** The CMS `signing-time` signed attribute, when present (PAdES forbids it; the PDF's `/M` is the claim there). */
+  signingTime: Date | null;
+  /** DER of the signer's certificate. */
+  signerCertificate: Uint8Array;
+  /** DER of every certificate carried by the CMS, signer first. */
+  certificates: Uint8Array[];
+  /** The signature algorithm OID (`1.2.840.113549.1.1.11` = sha256WithRSAEncryption, …). */
+  signatureAlgorithm: string;
+  /** The ESS `signing-certificate-v2` attribute is present (a CAdES requirement). */
+  signingCertificateV2: boolean;
+  /** DER of an RFC 3161 timestamp token carried as an unsigned attribute, when present. */
+  timestampToken: Uint8Array | null;
+}
+declare class CmsError extends Error {
+  readonly reason: 'malformed' | 'unsupported';
+  constructor(reason: 'malformed' | 'unsupported', message: string);
+}
+interface ParsedCmsInternal {
+  parsed: ParsedCms;
+  signedData: pkijs.SignedData;
+  signerInfo: pkijs.SignerInfo;
+  signerCertificate: pkijs.Certificate;
+  certificates: pkijs.Certificate[];
+  /** DER of the signing-certificate-v2 attribute's first certHash, when present. */
+  essCertHash: Uint8Array | null;
+}
+/** Parse a detached CMS SignedData with exactly one signer. Throws `CmsError`. */
+declare function parseDetachedCms(cms: Uint8Array): ParsedCms;
+//#endregion
+//#region src/cms/verify.d.ts
+type CryptographyVerdict = 'valid' | 'invalid' | 'unsupported';
+/**
+ * Does the CMS's signature verify with the certificate it names, over the
+ * attributes it signed? Says nothing about the content: the message digest
+ * is compared by the caller (`validateSignatures`, `verifyForCompletion`).
+ * `unsupported` means the algorithm is unknown to this engine, which is
+ * never `invalid`.
+ */
+declare function verifyCmsSignature(cms: Uint8Array | ParsedCmsInternal): Promise<CryptographyVerdict>;
+//#endregion
+//#region src/cms/build.d.ts
+type SignatureProfile = 'pkcs7' | 'cades-b';
+type RawSignatureAlgorithm = 'RSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
+/**
+ * Something that signs bytes with a private key it never hands out: a
+ * WebCrypto key, an HSM, a smart card. `sign` receives the DER of the CMS
+ * signed attributes and returns the raw signature (for ECDSA: `r || s`,
+ * as WebCrypto produces it; the CMS encoding is done here).
+ */
+interface RawSigner {
+  readonly kind: 'raw';
+  /** DER certificates, the signer's first, then its issuers. */
+  readonly certificateChain: Uint8Array[];
+  readonly algorithm: RawSignatureAlgorithm;
+  readonly hash: Exclude<DigestAlgorithm, 'sha1'>;
+  sign(signedAttributesDer: Uint8Array): Promise<Uint8Array>;
+}
+interface BuildDetachedCmsInput {
+  /** The digest the engine prepared (over the `/ByteRange`). */
+  digest: Uint8Array;
+  hash: Exclude<DigestAlgorithm, 'sha1'>;
+  profile: SignatureProfile;
+  signer: RawSigner;
+  /** `pkcs7` only: the CMS `signing-time` attribute. PAdES (`cades-b`) never carries one. */
+  signingTime?: Date;
+}
+/**
+ * Build a detached CMS SignedData around a raw signature: content-type,
+ * message-digest, and for CAdES-B the ESS signing-certificate-v2 attribute;
+ * the signer's certificate chain; one SignerInfo identified by issuer and
+ * serial number.
+ */
+declare function buildDetachedCms(input: BuildDetachedCmsInput): Promise<Uint8Array>;
+//#endregion
+//#region src/gate.d.ts
+type CompletionRefusal = 'malformed' | 'too-large' | 'algorithm-mismatch' | 'digest-mismatch' | 'signature-invalid' | 'profile-violation';
+type CompletionGate = {
+  ok: true;
+} | {
+  ok: false;
+  reason: CompletionRefusal;
+  detail: string;
+};
+/**
+ * The gate between a signer's answer and `signatures.complete`: the CMS
+ * must fit the reserved room, hash with the prepared algorithm, carry the
+ * prepared digest as its message digest, verify with its own certificate,
+ * and match the profile the `/SubFilter` promises (CAdES: ESS
+ * signing-certificate-v2 present, no CMS signing-time). A bad CMS never
+ * reaches the document.
+ */
+declare function verifyForCompletion(input: {
+  cms: Uint8Array;
+  prepared: SignaturePrepared;
+  profile: SignatureProfile;
+}): Promise<CompletionGate>;
+//#endregion
+//#region src/trust.d.ts
+/**
+ * Where trust comes from. The engine has no opinion: an application
+ * supplies its anchors (a company root, a national trust list, the AATL).
+ */
+interface TrustPort {
+  /** DER certificates trusted as anchors. */
+  anchors(): Promise<Uint8Array[]>;
+}
+/**
+ * When a chain is judged. `now` is the honest default; `timestamp` is only
+ * legitimate for a verified RFC 3161 token, which is why it carries the
+ * proof flag. The signature's own `/M` is a claim and never a validation
+ * time.
+ */
+type ValidationTime = {
+  kind: 'now';
+} | {
+  kind: 'timestamp';
+  genTime: Date;
+  tokenVerified: true;
+};
+type TrustStatus = 'trusted' | 'untrusted' | 'unknown';
+interface TrustVerdict {
+  status: TrustStatus;
+  /** Why, when not trusted. */
+  reason?: string;
+  /** DER certificates of the validated path, anchor last, when trusted. */
+  path?: Uint8Array[];
+}
+/**
+ * Build and validate the certificate path from the CMS's signer to one
+ * of the port's anchors at `at`. No port, or a port with no anchors, is
+ * `unknown`: nothing was checked, and nothing was refused.
+ */
+declare function validateChain(cms: Uint8Array | ParsedCmsInternal, trust: TrustPort | null | undefined, at?: ValidationTime): Promise<TrustVerdict>;
+//#endregion
+//#region src/sign.d.ts
+/** A service that turns a digest into a finished detached CMS (most hosted signing APIs). */
+interface CmsSigner {
+  readonly kind: 'cms';
+  sign(input: {
+    digest: Uint8Array;
+    algorithm: Exclude<DigestAlgorithm, 'sha1'>;
+    subFilter: SignatureSubFilter;
+  }): Promise<Uint8Array>;
+}
+type SignerPort = CmsSigner | RawSigner;
+type SignInput = Omit<SignaturePrepareInput, 'kind'> & {
+  signer: SignerPort;
+};
+declare class SigningError extends Error {
+  readonly reason: CompletionRefusal;
+  constructor(reason: CompletionRefusal, detail: string);
+}
+declare function profileFor(subFilter: SignatureSubFilter): SignatureProfile;
+/**
+ * Sign a field in one call: `prepare` on the engine, the signer 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
+ * with a pending signing.
+ */
+declare function sign(doc: DocumentHandle, input: SignInput): Promise<SignatureCompleteResult>;
+//#endregion
+//#region src/verdict.d.ts
+type IntegrityVerdict = 'valid' | 'invalid' | 'indeterminate';
+type ModificationsVerdict = 'unchanged' | 'permitted' | 'forbidden' | 'indeterminate';
+/**
+ * Four independent facts and a summary, never one boolean — the shape
+ * Acrobat reports ("signature valid", "signer unknown", "document changed,
+ * changes allowed") and the shape a UI can explain.
+ */
+interface SignatureVerdict {
+  signature: SignatureDTO;
+  /** The sealed bytes are intact: whole-revision coverage and the CMS message digest matches them. */
+  integrity: IntegrityVerdict;
+  /** The CMS verifies with its own certificate. */
+  cryptography: CryptographyVerdict;
+  /** The certificate chains to one of the caller's anchors. */
+  trust: TrustStatus;
+  trustReason?: string;
+  validatedAt: ValidationTime;
+  /**
+   * What changed after the signature, and which bytes were judged: the loaded
+   * file (`persisted`), or the session's unsaved edits snapshotted as one
+   * more revision (`working-copy` — only when such edits existed).
+   */
+  modifications: {
+    verdict: ModificationsVerdict;
+    detail?: string;
+    basis: 'persisted' | 'working-copy';
+    /** Revisions appended after the one this signature sealed (present when there are any). */
+    laterRevisions?: number;
+    /** Some object was changed after the signature and holds the sealed value again. */
+    undone?: boolean;
+  };
+  /** `invalid` only on positive evidence; `indeterminate` whenever a fact could not be established. */
+  summary: 'valid' | 'valid-untrusted' | 'invalid' | 'indeterminate';
+  cms: ParsedCms | null;
+}
+interface ValidateSignaturesOptions {
+  trust?: TrustPort | null;
+  at?: ValidationTime;
+  /**
+   * `persisted` (default): the loaded bytes — what a file on disk says.
+   * `working-copy`: unsaved edits are judged too, as the revision a save would
+   * write — what the file a save produces will say. A viewer shows this one.
+   */
+  until?: 'persisted' | 'working-copy';
+}
+/**
+ * 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[]>;
+//#endregion
+//#region src/signers/webcrypto.d.ts
+/**
+ * A `RawSigner` over a WebCrypto private key: the key never leaves the
+ * runtime. The algorithm and hash come from the key itself.
+ */
+declare function webCryptoSigner(input: {
+  privateKey: CryptoKey;
+  certificateChain: Uint8Array[];
+  /** Required for ECDSA keys (the key carries no hash); ignored for RSA keys. */
+  hash?: Exclude<DigestAlgorithm, 'sha1'>;
+}): RawSigner;
+interface TestSigner extends RawSigner {
+  /** DER of the self-signed certificate — also the only trust anchor that validates it. */
+  readonly certificate: Uint8Array;
+  readonly privateKey: CryptoKey;
+}
+/**
+ * A throwaway signer for tests and demos: a fresh key pair and a
+ * self-signed certificate, never persisted. Trust it with
+ * `{ anchors: async () => [signer.certificate] }`.
+ */
+declare function createTestSigner(opts?: {
+  commonName?: string;
+  algorithm?: 'RSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
+  hash?: 'sha256' | 'sha384' | 'sha512';
+}): Promise<TestSigner>;
+/** 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.
+ */
+declare function remoteSigner(input: {
+  sign: (request: {
+    digest: Uint8Array;
+    algorithm: 'sha256' | 'sha384' | 'sha512';
+    subFilter: 'adbe.pkcs7.detached' | 'ETSI.CAdES.detached';
+  }) => 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. */
+interface PersonalKeyRecord {
+  privateKey: CryptoKey;
+  certificate: Uint8Array;
+}
+/** Where personal keys live. Keys are structured-cloneable, so a store can keep the `CryptoKey` itself. */
+interface PersonalKeyStore {
+  load(subject: string): Promise<PersonalKeyRecord | null>;
+  save(subject: string, record: PersonalKeyRecord): Promise<void>;
+  remove(subject: string): Promise<void>;
+}
+interface PersonalSigner extends RawSigner {
+  /** DER of the self-signed certificate — the only anchor that validates it. */
+  readonly certificate: Uint8Array;
+  readonly subject: string;
+}
+/**
+ * One self-signed identity per subject (a person's name), persisted in the
+ * caller's store and created on first use. The private key is generated
+ * non-extractable: it can sign, it can be stored by the browser, it can
+ * never be read out. This is Preview's "sign with your own signature"
+ * experience with real cryptography behind it — a reader who trusts the
+ * certificate validates the signature; every other reader sees "validity
+ * unknown", which is the honest answer for a self-issued identity.
+ */
+declare function personalSigner(input: {
+  subject: string;
+  store: PersonalKeyStore;
+  algorithm?: 'RSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
+  hash?: 'sha256' | 'sha384' | 'sha512';
+}): Promise<PersonalSigner>;
+/** An in-memory store: tests, and runtimes without IndexedDB. */
+declare function memoryKeyStore(): PersonalKeyStore;
+/**
+ * An IndexedDB store: the browser keeps the non-extractable `CryptoKey`
+ * itself (structured clone), so the key survives reloads without ever
+ * existing as bytes.
+ */
+declare function indexedDbKeyStore(dbName: string, opts?: {
+  storeName?: string;
+}): PersonalKeyStore;
+//#endregion
+//#region src/signers/self-signed.d.ts
+/**
+ * A self-signed certificate over a WebCrypto key pair: the shape a personal
+ * signer, a test signer, and a demo all need. It is its own trust anchor and
+ * nothing else's — Acrobat shows a signature made with it as "validity
+ * unknown" until the reader trusts the certificate explicitly.
+ */
+declare function selfSignedCertificate(input: {
+  publicKey: CryptoKey;
+  privateKey: CryptoKey;
+  commonName: string;
+  hash: 'sha256' | 'sha384' | 'sha512';
+  /** Validity in days; default one year. */
+  validityDays?: number;
+}): Promise<Uint8Array>;
+/** 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 };
+//# sourceMappingURL=index.d.ts.map