@embedpdf/plugin-signature 3.0.0-next.14 → 3.0.0-next.16

package/README.md

@@ -1,6 +1,6 @@
 # @embedpdf/plugin-signature
 
-Document-scoped digital signing for EmbedPDF v3: sign a signature field with a
+Document-scoped digital signing for EmbedPDF: sign a signature field with a
 **mark** (a stamp-library asset — drawn, typed, uploaded — or bytes you bring)
 through a **signer port** you configure; fill a field visually without
 sealing; validate what is signed; and drop an armed mark onto a field.
@@ -10,23 +10,29 @@ The plugin owns the act and nothing else:
 - marks are the stamp plugin's (`@embedpdf/plugin-stamp`) — one library of kind
   `signatures` per person, holding a `signature` asset and optional `initials`;
 - the key is a `SignerPort` from `@embedpdf/core-signature` (`webCryptoSigner`,
-  `remoteSigner`, `personalSigner`), resolved per signing;
+  `remoteSigner`, `personalSigner`), the `key` setting, resolved per signing;
 - the engine draws the mark's page into the field and seals the bytes
   (`doc.signatures.prepare` → CMS → `complete`); on the cloud the server
   publishes the new version.
 
 ```ts
-import { signaturePlugin, personalSigner, indexedDbKeyStore } from '@embedpdf/plugin-signature';
+import { toFieldRef } from '@embedpdf/plugin-form';
+import {
+  signaturePlugin,
+  SignatureToken,
+  personalSigner,
+  indexedDbKeyStore,
+} from '@embedpdf/plugin-signature';
 
 signaturePlugin({
-  signer: () => personalSigner({ subject: 'Ada Lovelace', store: indexedDbKeyStore('keys') }),
+  key: () => personalSigner({ subject: 'Ada Lovelace', store: indexedDbKeyStore('keys') }),
   trust: { anchors: async () => [rootCertificateDer] },
-  mode: 'sign', // 'sign' (default with a signer) | 'visual' (default without) | 'ask'
+  mode: 'sign', // 'sign' (the default with a key) | 'visual' (the default without) | 'ask'
 });
 
 const signature = ctx.get(SignatureToken);
-await signature.placeMark({ assetId }, { field: { kind: 'fqn', name: 'sig' } }); // sign / fill / ask, by mode
-await signature.placeMark({ assetId }, { pageObjectNumber, at: { x: 120, y: 90 } }); // elsewhere: a stamp
+await signature.placeMark({ assetId }, { field: toFieldRef('approval') }); // sign / fill / ask, by mode
+await signature.placeMark({ assetId }, { page, center: { x: 120, y: 90 } }); // elsewhere: a stamp
 ```
 
 With the interaction hub and the stamp plugin present, a mark armed from a
@@ -35,4 +41,4 @@ the field; anywhere else it is placed as a stamp.
 
 Requires `@embedpdf/plugin-form`; optional `@embedpdf/plugin-stamp`,
 `@embedpdf/plugin-annotation`, `@embedpdf/plugin-interaction`. See the docs
-page `headless/plugins/signature` for the full contract.
+page `headless/forms/signatures` for the full contract.

package/dist/contract-Bu7_S84K.cjs

@@ -0,0 +1,99 @@
+//#region src/token.ts
+/** The package token, created once here and re-exported by `contract.ts`. */
+const SignatureToken = (0, require("@embedpdf/core").createCapabilityToken)("signature", {
+	hint: `add signaturePlugin() from '@embedpdf/plugin-signature' to your plugins list`,
+	promises: {
+		sign: true,
+		prepareSignature: true,
+		completeSignature: true,
+		cancelPending: true,
+		fillField: true,
+		clearField: true,
+		placeMark: true,
+		refresh: true,
+		validate: true,
+		validateField: true,
+		analyzeChanges: true,
+		readRevision: true
+	}
+});
+//#endregion
+//#region src/contract.ts
+/** What the signature settings are when the app registers none. */
+const SIGNATURE_DEFAULTS = {
+	key: null,
+	mode: null,
+	trust: null,
+	allowCertify: false
+};
+/** The stamp-library kind that holds people's marks: one library per person. */
+const SIGNATURES_LIBRARY_KIND = "signatures";
+/** The asset identifiers inside a signatures library: the full signature and the initials. */
+const SIGNATURE_MARK_NAME = "signature";
+const INITIALS_MARK_NAME = "initials";
+/** Which mark an asset of a signatures library is (anything not named `initials` is a signature). */
+const markRoleOf = (asset) => asset.name === "initials" ? "initials" : "signature";
+/**
+* The people whose marks the stamp plugin holds, one row per library of kind
+* `signatures`, in the order of `libraries`: give it the stamp plugin's
+* `listLibraries({ kind: SIGNATURES_LIBRARY_KIND })` and `listAssets()`. A
+* pure derivation: rename, delete and export are the stamp plugin's library
+* verbs, and nothing is stored beyond the library's file.
+*/
+function signerRowsOf(libraries, assets) {
+	return libraries.filter((library) => library.kind === SIGNATURES_LIBRARY_KIND).map((library) => {
+		const own = assets.filter((asset) => asset.libraryId === library.id);
+		return {
+			libraryId: library.id,
+			name: library.name,
+			library,
+			signatures: own.filter((asset) => markRoleOf(asset) === "signature"),
+			initials: own.find((asset) => markRoleOf(asset) === "initials") ?? null
+		};
+	});
+}
+//#endregion
+Object.defineProperty(exports, "INITIALS_MARK_NAME", {
+	enumerable: true,
+	get: function() {
+		return INITIALS_MARK_NAME;
+	}
+});
+Object.defineProperty(exports, "SIGNATURES_LIBRARY_KIND", {
+	enumerable: true,
+	get: function() {
+		return SIGNATURES_LIBRARY_KIND;
+	}
+});
+Object.defineProperty(exports, "SIGNATURE_DEFAULTS", {
+	enumerable: true,
+	get: function() {
+		return SIGNATURE_DEFAULTS;
+	}
+});
+Object.defineProperty(exports, "SIGNATURE_MARK_NAME", {
+	enumerable: true,
+	get: function() {
+		return SIGNATURE_MARK_NAME;
+	}
+});
+Object.defineProperty(exports, "SignatureToken", {
+	enumerable: true,
+	get: function() {
+		return SignatureToken;
+	}
+});
+Object.defineProperty(exports, "markRoleOf", {
+	enumerable: true,
+	get: function() {
+		return markRoleOf;
+	}
+});
+Object.defineProperty(exports, "signerRowsOf", {
+	enumerable: true,
+	get: function() {
+		return signerRowsOf;
+	}
+});
+
+//# sourceMappingURL=contract-Bu7_S84K.cjs.map

package/dist/contract-Bu7_S84K.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-Bu7_S84K.cjs","names":[],"sources":["../src/token.ts","../src/contract.ts"],"sourcesContent":["/** The package token, created once here and re-exported by `contract.ts`. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { SignatureCapability } from './contract';\n\nexport const SignatureToken = createCapabilityToken<SignatureCapability>('signature', {\n  hint: `add signaturePlugin() from '@embedpdf/plugin-signature' to your plugins list`,\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    sign: true,\n    prepareSignature: true,\n    completeSignature: true,\n    cancelPending: true,\n    fillField: true,\n    clearField: true,\n    placeMark: true,\n    refresh: true,\n    validate: true,\n    validateField: true,\n    analyzeChanges: true,\n    readRevision: true,\n  },\n});\n","/**\n * @embedpdf/plugin-signature/contract: the public signature vocabulary: the\n * act of signing (one-shot and two-phase), visual fills, validation, the\n * sign-here flow, and the facts about a document's signatures.\n */\nimport type {\n  EventHook,\n  EventOrigin,\n  OperationOptions,\n  ResourceStatus,\n  SettingsApi,\n} from '@embedpdf/core';\nimport type {\n  SignatureVerdict,\n  SignerPort,\n  TrustPort,\n  ValidationTime,\n} from '@embedpdf/core-signature';\nimport type {\n  AnalyzeInput,\n  AnnotationRef,\n  BinarySource,\n  ChangeAnalysis,\n  DigestAlgorithm,\n  DocMdpPermission,\n  DocumentProtection,\n  FieldLockSpec,\n  FormFieldRef,\n  FormWidget,\n  SignatureCompleteResult,\n  SignatureDTO,\n  SignaturePrepared,\n  SignatureSignerInput,\n  SignatureSnapshot,\n  SignatureSubFilter,\n} from '@embedpdf/engine-core/runtime';\nimport type { StampPlacement } from '@embedpdf/plugin-annotation/contract';\nimport type { StampAsset, StampLibrary } from '@embedpdf/plugin-stamp/contract';\n\nexport { SignatureToken } from './token';\nexport type {\n  AnalyzeInput,\n  ChangeAnalysis,\n  DocMdpPermission,\n  DocumentProtection,\n  FieldLockSpec,\n  FormFieldRef,\n  SignatureCompleteResult,\n  SignatureDTO,\n  SignaturePrepared,\n  SignatureSnapshot,\n} from '@embedpdf/engine-core/runtime';\nexport type {\n  SignatureVerdict,\n  SignerPort,\n  TrustPort,\n  ValidationTime,\n} from '@embedpdf/core-signature';\n\n/**\n * What placing a mark on a signature field does:\n *   - `sign`    seal the field with the configured key (the mark is the appearance);\n *   - `visual`  draw the mark into the field without sealing (Preview's \"signature\");\n *   - `ask`     neither: `onSignRequested` fires so the chrome can open its dialog and decide.\n */\nexport type SignatureMode = 'sign' | 'visual' | 'ask';\n\n/** The key that signs: a signer port, or a function that returns one when someone signs. */\nexport type SignatureKey = SignerPort | (() => SignerPort | Promise<SignerPort>);\n\n/**\n * The signature plugin's settings. `signaturePlugin(config)` registers them\n * over {@link SIGNATURE_DEFAULTS}, and `updateSettings()` changes them for\n * every document while the app runs. Each is one value: a change replaces a\n * key or a trust port whole.\n */\nexport interface SignatureSettings {\n  /** The key: a raw signer (the CMS is built here) or a CMS signer (a service builds it); `null` for none. */\n  readonly key: SignatureKey | null;\n  /** What a mark does in a field; `null` is `'sign'` with a key, else `'visual'`. */\n  readonly mode: SignatureMode | null;\n  /** The certificates you trust, for checking signatures. Without them a verdict is at best `valid-untrusted`. */\n  readonly trust: TrustPort | null;\n  /** Let a first signature be a certification (still needs `doc.sign.certify`). */\n  readonly allowCertify: boolean;\n}\n\n/** What the signature settings are when the app registers none. */\nexport const SIGNATURE_DEFAULTS: SignatureSettings = {\n  key: null,\n  mode: null,\n  trust: null,\n  allowCertify: false,\n};\n\n/** What `signaturePlugin(config)` takes: any of the settings. */\nexport type SignatureConfig = Partial<SignatureSettings>;\n\n/** The mark: a stamp-plugin asset, or bytes the embedder brings (PNG, JPEG, or a one-page PDF). */\nexport type Mark = { assetId: string } | { source: BinarySource };\n\n/**\n * How a signature field is addressed: its field ref, or its widget, by\n * annotation ref or as a signature names it (`SignatureDTO.widget`).\n */\nexport type SignatureFieldAddress = FormFieldRef | AnnotationRef | FormWidget;\n\nexport interface SignFieldInput {\n  field: FormFieldRef;\n  mark: Mark;\n  /** A per-call key; the `key` setting otherwise. */\n  key?: SignatureKey;\n  /** What the signature dictionary says about the signer; the name defaults to the certificate's subject. */\n  signer?: SignatureSignerInput;\n  /** Instead of the mark: a ready one-page appearance PDF the embedder composed itself. */\n  appearance?: BinarySource;\n  certify?: { permission: DocMdpPermission };\n  lock?: FieldLockSpec;\n}\n\n/** Two-phase signing, step one: everything but the key. The digest comes back; a CMS goes in. */\nexport interface PrepareSignatureInput {\n  field: FormFieldRef;\n  mark?: Mark;\n  appearance?: BinarySource;\n  signer?: SignatureSignerInput;\n  certify?: { permission: DocMdpPermission };\n  lock?: FieldLockSpec;\n  subFilter?: SignatureSubFilter;\n  digest?: Exclude<DigestAlgorithm, 'sha1'>;\n}\n\n/** The parked half of a two-phase signing (`prepareSignature` → `completeSignature`). */\nexport type PreparedSignature = SignaturePrepared;\n\n/** The stamp-library kind that holds people's marks: one library per person. */\nexport const SIGNATURES_LIBRARY_KIND = 'signatures';\n/** The asset identifiers inside a signatures library: the full signature and the initials. */\nexport const SIGNATURE_MARK_NAME = 'signature';\nexport const INITIALS_MARK_NAME = 'initials';\nexport type MarkRole = 'signature' | 'initials';\n/** Which mark an asset of a signatures library is (anything not named `initials` is a signature). */\nexport const markRoleOf = (asset: Pick<StampAsset, 'name'>): MarkRole =>\n  asset.name === INITIALS_MARK_NAME ? 'initials' : 'signature';\n\n/** One person in a signatures picker: a library of kind `signatures`, with its marks split by role. */\nexport interface SignerRow {\n  readonly libraryId: string;\n  readonly name: string;\n  readonly library: StampLibrary;\n  /** Every full signature of the person, in the library's order. */\n  readonly signatures: StampAsset[];\n  /** The person's initials, or `null` when the library has none. */\n  readonly initials: StampAsset | null;\n}\n\n/**\n * The people whose marks the stamp plugin holds, one row per library of kind\n * `signatures`, in the order of `libraries`: give it the stamp plugin's\n * `listLibraries({ kind: SIGNATURES_LIBRARY_KIND })` and `listAssets()`. A\n * pure derivation: rename, delete and export are the stamp plugin's library\n * verbs, and nothing is stored beyond the library's file.\n */\nexport function signerRowsOf(\n  libraries: readonly StampLibrary[],\n  assets: readonly StampAsset[],\n): SignerRow[] {\n  return libraries\n    .filter((library) => library.kind === SIGNATURES_LIBRARY_KIND)\n    .map((library) => {\n      const own = assets.filter((asset) => asset.libraryId === library.id);\n      return {\n        libraryId: library.id,\n        name: library.name,\n        library,\n        signatures: own.filter((asset) => markRoleOf(asset) === 'signature'),\n        initials: own.find((asset) => markRoleOf(asset) === 'initials') ?? null,\n      };\n    });\n}\n\n/** A signature prepared in two steps and not completed yet. */\nexport interface SignaturePending {\n  readonly signingId: string;\n  readonly field: FormFieldRef;\n}\n\n/** A signed field's facts, with its verdict from the last check (`null` until one ran). */\nexport interface SignatureInfo extends SignatureDTO {\n  readonly verdict: SignatureVerdict | null;\n}\n\n/** What `placeMark` did: sealed, drawn, handed to the chrome (mode `ask`), or placed as a stamp. */\nexport type PlaceMarkResult =\n  | { kind: 'signed'; field: FormFieldRef; result: SignatureCompleteResult }\n  | { kind: 'filled'; field: FormFieldRef }\n  | { kind: 'requested'; field: FormFieldRef }\n  | { kind: 'placed'; annotation: AnnotationRef };\n\n// ── events ──\n/** A signing completed, in this session or another: the confirmed `signatures.completed` fact. */\nexport interface SignatureSignedEvent {\n  /** The sealed field, by its durable object-number ref. */\n  readonly field: FormFieldRef;\n  readonly result: SignatureCompleteResult;\n  readonly origin: EventOrigin;\n}\n/** This session's `fillField()` drew a mark into a field. */\nexport interface SignatureFilledEvent {\n  readonly field: FormFieldRef;\n}\n/** This session's `clearField()` took a drawn mark out of a field. */\nexport interface SignatureClearedEvent {\n  readonly field: FormFieldRef;\n}\nexport interface SignatureValidatedEvent {\n  readonly verdicts: readonly SignatureVerdict[];\n}\nexport interface SignatureProtectionChangedEvent {\n  readonly protection: DocumentProtection;\n}\n/** An unsaved edit just turned a signature that held into one a save would invalidate. Once per edge. */\nexport interface SignatureInvalidationPredictedEvent {\n  readonly field: FormFieldRef;\n  readonly detail: string;\n}\nexport interface SignatureTargetChangedEvent {\n  readonly field: FormFieldRef | null;\n}\n/** Mode `ask`: a mark met a field and the chrome decides (open its dialog, then `sign` / `fillField`). */\nexport interface SignatureSignRequestedEvent {\n  readonly field: FormFieldRef;\n  readonly mark: Mark;\n}\n/** A signed field was activated: show what its signature says. */\nexport interface SignatureInspectionRequestedEvent {\n  readonly field: FormFieldRef;\n}\n\n/** Options for `validate()` and `validateField()`. */\nexport interface SignatureValidateOptions extends OperationOptions {\n  /** The moment the certificates are judged at; now by default. */\n  readonly at?: ValidationTime;\n  /** `'persisted'` checks the file as it was opened; `'working-copy'` (the default) counts unsaved changes. */\n  readonly until?: 'persisted' | 'working-copy';\n}\n\n/**\n * Signing, visual fills and checking signatures for one document. Every verb\n * rejects with a `PluginError`, and every async verb takes a `signal`. Its\n * settings belong to the plugin, not to a document.\n */\nexport interface SignatureCapability extends SettingsApi<SignatureSettings> {\n  // ── reading ──\n  /** Every signature field and its facts, the file's versions and `protection`. The same object until it changes. */\n  getSnapshot(): SignatureSnapshot | null;\n  /** Whether the signatures are read. */\n  getStatus(): ResourceStatus;\n  /** The signed fields, in document order, each with its verdict once checked. The same array until one changes. */\n  listSignatures(): readonly SignatureInfo[];\n  /** Signature fields still to sign, in document order. The same array until one changes. */\n  listUnsignedFields(): readonly FormFieldRef[];\n  /** One signature field's facts, signed or not, by its ref or its widget's, or `null`. */\n  getSignature(field: SignatureFieldAddress): SignatureDTO | null;\n  /** Every verdict from the last check; `null` before the first. */\n  listVerdicts(): readonly SignatureVerdict[] | null;\n  /** One signed field's verdict from the last check, or `null`. */\n  getVerdict(field: SignatureFieldAddress): SignatureVerdict | null;\n  /** What the document's signatures allow, or `null` before they're read. */\n  getProtection(): DocumentProtection | null;\n  /** A signature prepared in two steps and not completed: the document can't be changed until it is, or is cancelled. */\n  getPending(): SignaturePending | null;\n  /** Whether a signing or a fill is running. */\n  isBusy(): boolean;\n  /** The mode in effect: the `mode` setting, or its default. */\n  getMode(): SignatureMode;\n  /** The field the next picked mark goes to, or `null`. */\n  getTarget(): FormFieldRef | null;\n\n  // ── signing ──\n  /**\n   * Sign a field: the mark becomes what it shows, the key seals the document,\n   * and the signed document is a new version. A signal that fires before the\n   * seal leaves nothing signed. Fires `onSigned`. Rejects `permission-denied`\n   * for a field you may not sign (`canSign`), or without `doc.sign.certify`\n   * to certify, `invalid-input` without a key, `not-found`,\n   * `operation-cancelled`.\n   */\n  sign(input: SignFieldInput, options?: OperationOptions): Promise<SignatureCompleteResult>;\n  /**\n   * Signing in two steps, the first: resolves the digest for your key to sign,\n   * and keeps the document from changing until `completeSignature()` or\n   * `cancelPending()`. Rejects like `sign()`.\n   */\n  prepareSignature(\n    input: PrepareSignatureInput,\n    options?: OperationOptions,\n  ): Promise<PreparedSignature>;\n  /** Signing in two steps, the second: the key's CMS seals the document. Fires `onSigned`. Rejects `not-found` for a signing this session didn't prepare. */\n  completeSignature(\n    signingId: string,\n    cms: Uint8Array,\n    options?: OperationOptions,\n  ): Promise<SignatureCompleteResult>;\n  /** Give up a signature prepared in two steps, so the document can be changed again. */\n  cancelPending(options?: OperationOptions): Promise<void>;\n  /**\n   * Draw a mark into a field without signing. Fires `onFilled`. Rejects\n   * `permission-denied` for a field you may not fill in (`canFill`),\n   * `conflict` on a signed field.\n   */\n  fillField(field: FormFieldRef, mark: Mark, options?: OperationOptions): Promise<void>;\n  /** Take a drawn mark out of a field. Fires `onCleared`. Rejects like `fillField()`. */\n  clearField(field: FormFieldRef, options?: OperationOptions): Promise<void>;\n  /**\n   * Do what a click with an armed mark does: in a field, sign, fill or ask\n   * (`onSignRequested`), by `mode`; anywhere else, place it as a stamp.\n   * Rejects like the verb it runs.\n   */\n  placeMark(\n    mark: Mark,\n    target: { field: FormFieldRef } | StampPlacement,\n    options?: OperationOptions,\n  ): Promise<PlaceMarkResult>;\n  /** Make a field the target, where the next mark the person picks goes; `null` clears. Fires `onTargetChanged`. */\n  setTarget(field: FormFieldRef | null): void;\n  /** Ask your UI to show a signed field's details, as clicking it does. Fires `onInspectionRequested`. */\n  requestInspection(field: FormFieldRef): void;\n\n  // ── checking ──\n  /** Read the signatures again; resolves the snapshot. */\n  refresh(options?: OperationOptions): Promise<SignatureSnapshot | null>;\n  /**\n   * Check every signature again and resolve the verdicts. Unsaved changes\n   * count, so the verdict is the one the downloaded file will get;\n   * `until: 'persisted'` checks the file as it was opened. Fires `onValidated`.\n   */\n  validate(options?: SignatureValidateOptions): Promise<readonly SignatureVerdict[]>;\n  /** Check one signed field. Rejects `not-found` for an unsigned or unknown field. */\n  validateField(\n    field: SignatureFieldAddress,\n    options?: SignatureValidateOptions,\n  ): Promise<SignatureVerdict>;\n  /** What changed after a signature or a version of the file, rule by rule. */\n  analyzeChanges(input: AnalyzeInput, options?: OperationOptions): Promise<ChangeAnalysis>;\n  /**\n   * The exact bytes of the file version a signature covers. Rejects\n   * `permission-denied` without `doc.download`, `not-found` for an unsigned\n   * field.\n   */\n  readRevision(\n    target: SignatureFieldAddress | { revisionIndex: number },\n    options?: OperationOptions,\n  ): Promise<Uint8Array>;\n\n  // ── permissions ──\n  /**\n   * Whether signing this field is allowed: `doc.sign`, or a `fields:sign`\n   * permission for its group. `false` for a field the form doesn't have. A\n   * per-call key or two-step signing needs no `key` setting.\n   */\n  canSign(field: FormFieldRef): boolean;\n  /**\n   * Whether drawing a mark into this field without signing is allowed:\n   * `doc.forms.fill`, or a `fields:fill` permission for its group.\n   */\n  canFill(field: FormFieldRef): boolean;\n  /** Whether a certification may be offered: the `allowCertify` setting and `doc.sign.certify`. */\n  canCertify(): boolean;\n  /** Whether the signed bytes may be read: `doc.download`. */\n  canReadRevision(): boolean;\n\n  // ── events ──\n  /** A field was signed, whoever signed it; fires once the facts show the sealed field. */\n  readonly onSigned: EventHook<SignatureSignedEvent>;\n  /** A mark was drawn into a field. */\n  readonly onFilled: EventHook<SignatureFilledEvent>;\n  /** A drawn mark was taken out of a field. */\n  readonly onCleared: EventHook<SignatureClearedEvent>;\n  /** The signatures were checked. */\n  readonly onValidated: EventHook<SignatureValidatedEvent>;\n  /** What the signatures allow changed. */\n  readonly onProtectionChanged: EventHook<SignatureProtectionChangedEvent>;\n  /** A change would break a signature once saved. */\n  readonly onInvalidationPredicted: EventHook<SignatureInvalidationPredictedEvent>;\n  /** A field became the target, or the target was cleared. */\n  readonly onTargetChanged: EventHook<SignatureTargetChangedEvent>;\n  /** In `'ask'` mode, a mark was dropped on a field. */\n  readonly onSignRequested: EventHook<SignatureSignRequestedEvent>;\n  /** A signed field was clicked. */\n  readonly onInspectionRequested: EventHook<SignatureInspectionRequestedEvent>;\n}\n"],"mappings":";;AAKA,MAAa,kBAAA,2BAAA,CAAA,CAAA,sBAAA,CAA4D,aAAa;CACpF,MAAM;CAGN,UAAU;EACR,MAAM;EACN,kBAAkB;EAClB,mBAAmB;EACnB,eAAe;EACf,WAAW;EACX,YAAY;EACZ,WAAW;EACX,SAAS;EACT,UAAU;EACV,eAAe;EACf,gBAAgB;EAChB,cAAc;CAChB;AACF,CAAC;;;;ACiED,MAAa,qBAAwC;CACnD,KAAK;CACL,MAAM;CACN,OAAO;CACP,cAAc;AAChB;;AA2CA,MAAa,0BAA0B;;AAEvC,MAAa,sBAAsB;AACnC,MAAa,qBAAqB;;AAGlC,MAAa,cAAc,UACzB,MAAM,SAAA,aAA8B,aAAa;;;;;;;;AAoBnD,SAAgB,aACd,WACA,QACa;CACb,OAAO,UACJ,QAAQ,YAAY,QAAQ,SAAS,uBAAuB,CAAC,CAC7D,KAAK,YAAY;EAChB,MAAM,MAAM,OAAO,QAAQ,UAAU,MAAM,cAAc,QAAQ,EAAE;EACnE,OAAO;GACL,WAAW,QAAQ;GACnB,MAAM,QAAQ;GACd;GACA,YAAY,IAAI,QAAQ,UAAU,WAAW,KAAK,MAAM,WAAW;GACnE,UAAU,IAAI,MAAM,UAAU,WAAW,KAAK,MAAM,UAAU,KAAK;EACrE;CACF,CAAC;AACL"}

package/dist/contract-GUWa_aBY.d.ts

@@ -0,0 +1,299 @@
+import { EventHook, EventOrigin, OperationOptions, ResourceStatus, SettingsApi } from "@embedpdf/core";
+import { StampPlacement } from "@embedpdf/plugin-annotation/contract";
+import { StampAsset, StampLibrary } from "@embedpdf/plugin-stamp/contract";
+import { AnalyzeInput, AnalyzeInput as AnalyzeInput$1, AnnotationRef, BinarySource, ChangeAnalysis, ChangeAnalysis as ChangeAnalysis$1, DigestAlgorithm, DocMdpPermission, DocMdpPermission as DocMdpPermission$1, DocumentProtection, DocumentProtection as DocumentProtection$1, FieldLockSpec, FieldLockSpec as FieldLockSpec$1, FormFieldRef, FormFieldRef as FormFieldRef$1, FormWidget, SignatureCompleteResult, SignatureCompleteResult as SignatureCompleteResult$1, SignatureDTO, SignatureDTO as SignatureDTO$1, SignaturePrepared, SignaturePrepared as SignaturePrepared$1, SignatureSignerInput, SignatureSnapshot, SignatureSnapshot as SignatureSnapshot$1, SignatureSubFilter } from "@embedpdf/engine-core/runtime";
+import { SignatureVerdict, SignatureVerdict as SignatureVerdict$1, SignerPort, SignerPort as SignerPort$1, TrustPort, TrustPort as TrustPort$1, ValidationTime, ValidationTime as ValidationTime$1 } from "@embedpdf/core-signature";
+//#region src/token.d.ts
+declare const SignatureToken: import("@embedpdf/core").CapabilityToken<SignatureCapability>;
+//#endregion
+//#region src/contract.d.ts
+/**
+ * What placing a mark on a signature field does:
+ *   - `sign`    seal the field with the configured key (the mark is the appearance);
+ *   - `visual`  draw the mark into the field without sealing (Preview's "signature");
+ *   - `ask`     neither: `onSignRequested` fires so the chrome can open its dialog and decide.
+ */
+type SignatureMode = 'sign' | 'visual' | 'ask';
+/** The key that signs: a signer port, or a function that returns one when someone signs. */
+type SignatureKey = SignerPort | (() => SignerPort | Promise<SignerPort>);
+/**
+ * The signature plugin's settings. `signaturePlugin(config)` registers them
+ * over {@link SIGNATURE_DEFAULTS}, and `updateSettings()` changes them for
+ * every document while the app runs. Each is one value: a change replaces a
+ * key or a trust port whole.
+ */
+interface SignatureSettings {
+  /** The key: a raw signer (the CMS is built here) or a CMS signer (a service builds it); `null` for none. */
+  readonly key: SignatureKey | null;
+  /** What a mark does in a field; `null` is `'sign'` with a key, else `'visual'`. */
+  readonly mode: SignatureMode | null;
+  /** The certificates you trust, for checking signatures. Without them a verdict is at best `valid-untrusted`. */
+  readonly trust: TrustPort | null;
+  /** Let a first signature be a certification (still needs `doc.sign.certify`). */
+  readonly allowCertify: boolean;
+}
+/** What the signature settings are when the app registers none. */
+declare const SIGNATURE_DEFAULTS: SignatureSettings;
+/** What `signaturePlugin(config)` takes: any of the settings. */
+type SignatureConfig = Partial<SignatureSettings>;
+/** The mark: a stamp-plugin asset, or bytes the embedder brings (PNG, JPEG, or a one-page PDF). */
+type Mark = {
+  assetId: string;
+} | {
+  source: BinarySource;
+};
+/**
+ * How a signature field is addressed: its field ref, or its widget, by
+ * annotation ref or as a signature names it (`SignatureDTO.widget`).
+ */
+type SignatureFieldAddress = FormFieldRef | AnnotationRef | FormWidget;
+interface SignFieldInput {
+  field: FormFieldRef;
+  mark: Mark;
+  /** A per-call key; the `key` setting otherwise. */
+  key?: SignatureKey;
+  /** What the signature dictionary says about the signer; the name defaults to the certificate's subject. */
+  signer?: SignatureSignerInput;
+  /** Instead of the mark: a ready one-page appearance PDF the embedder composed itself. */
+  appearance?: BinarySource;
+  certify?: {
+    permission: DocMdpPermission;
+  };
+  lock?: FieldLockSpec;
+}
+/** Two-phase signing, step one: everything but the key. The digest comes back; a CMS goes in. */
+interface PrepareSignatureInput {
+  field: FormFieldRef;
+  mark?: Mark;
+  appearance?: BinarySource;
+  signer?: SignatureSignerInput;
+  certify?: {
+    permission: DocMdpPermission;
+  };
+  lock?: FieldLockSpec;
+  subFilter?: SignatureSubFilter;
+  digest?: Exclude<DigestAlgorithm, 'sha1'>;
+}
+/** The parked half of a two-phase signing (`prepareSignature` → `completeSignature`). */
+type PreparedSignature = SignaturePrepared;
+/** The stamp-library kind that holds people's marks: one library per person. */
+declare const SIGNATURES_LIBRARY_KIND = "signatures";
+/** The asset identifiers inside a signatures library: the full signature and the initials. */
+declare const SIGNATURE_MARK_NAME = "signature";
+declare const INITIALS_MARK_NAME = "initials";
+type MarkRole = 'signature' | 'initials';
+/** Which mark an asset of a signatures library is (anything not named `initials` is a signature). */
+declare const markRoleOf: (asset: Pick<StampAsset, "name">) => MarkRole;
+/** One person in a signatures picker: a library of kind `signatures`, with its marks split by role. */
+interface SignerRow {
+  readonly libraryId: string;
+  readonly name: string;
+  readonly library: StampLibrary;
+  /** Every full signature of the person, in the library's order. */
+  readonly signatures: StampAsset[];
+  /** The person's initials, or `null` when the library has none. */
+  readonly initials: StampAsset | null;
+}
+/**
+ * The people whose marks the stamp plugin holds, one row per library of kind
+ * `signatures`, in the order of `libraries`: give it the stamp plugin's
+ * `listLibraries({ kind: SIGNATURES_LIBRARY_KIND })` and `listAssets()`. A
+ * pure derivation: rename, delete and export are the stamp plugin's library
+ * verbs, and nothing is stored beyond the library's file.
+ */
+declare function signerRowsOf(libraries: readonly StampLibrary[], assets: readonly StampAsset[]): SignerRow[];
+/** A signature prepared in two steps and not completed yet. */
+interface SignaturePending {
+  readonly signingId: string;
+  readonly field: FormFieldRef;
+}
+/** A signed field's facts, with its verdict from the last check (`null` until one ran). */
+interface SignatureInfo extends SignatureDTO {
+  readonly verdict: SignatureVerdict | null;
+}
+/** What `placeMark` did: sealed, drawn, handed to the chrome (mode `ask`), or placed as a stamp. */
+type PlaceMarkResult = {
+  kind: 'signed';
+  field: FormFieldRef;
+  result: SignatureCompleteResult;
+} | {
+  kind: 'filled';
+  field: FormFieldRef;
+} | {
+  kind: 'requested';
+  field: FormFieldRef;
+} | {
+  kind: 'placed';
+  annotation: AnnotationRef;
+};
+/** A signing completed, in this session or another: the confirmed `signatures.completed` fact. */
+interface SignatureSignedEvent {
+  /** The sealed field, by its durable object-number ref. */
+  readonly field: FormFieldRef;
+  readonly result: SignatureCompleteResult;
+  readonly origin: EventOrigin;
+}
+/** This session's `fillField()` drew a mark into a field. */
+interface SignatureFilledEvent {
+  readonly field: FormFieldRef;
+}
+/** This session's `clearField()` took a drawn mark out of a field. */
+interface SignatureClearedEvent {
+  readonly field: FormFieldRef;
+}
+interface SignatureValidatedEvent {
+  readonly verdicts: readonly SignatureVerdict[];
+}
+interface SignatureProtectionChangedEvent {
+  readonly protection: DocumentProtection;
+}
+/** An unsaved edit just turned a signature that held into one a save would invalidate. Once per edge. */
+interface SignatureInvalidationPredictedEvent {
+  readonly field: FormFieldRef;
+  readonly detail: string;
+}
+interface SignatureTargetChangedEvent {
+  readonly field: FormFieldRef | null;
+}
+/** Mode `ask`: a mark met a field and the chrome decides (open its dialog, then `sign` / `fillField`). */
+interface SignatureSignRequestedEvent {
+  readonly field: FormFieldRef;
+  readonly mark: Mark;
+}
+/** A signed field was activated: show what its signature says. */
+interface SignatureInspectionRequestedEvent {
+  readonly field: FormFieldRef;
+}
+/** Options for `validate()` and `validateField()`. */
+interface SignatureValidateOptions extends OperationOptions {
+  /** The moment the certificates are judged at; now by default. */
+  readonly at?: ValidationTime;
+  /** `'persisted'` checks the file as it was opened; `'working-copy'` (the default) counts unsaved changes. */
+  readonly until?: 'persisted' | 'working-copy';
+}
+/**
+ * Signing, visual fills and checking signatures for one document. Every verb
+ * rejects with a `PluginError`, and every async verb takes a `signal`. Its
+ * settings belong to the plugin, not to a document.
+ */
+interface SignatureCapability extends SettingsApi<SignatureSettings> {
+  /** Every signature field and its facts, the file's versions and `protection`. The same object until it changes. */
+  getSnapshot(): SignatureSnapshot | null;
+  /** Whether the signatures are read. */
+  getStatus(): ResourceStatus;
+  /** The signed fields, in document order, each with its verdict once checked. The same array until one changes. */
+  listSignatures(): readonly SignatureInfo[];
+  /** Signature fields still to sign, in document order. The same array until one changes. */
+  listUnsignedFields(): readonly FormFieldRef[];
+  /** One signature field's facts, signed or not, by its ref or its widget's, or `null`. */
+  getSignature(field: SignatureFieldAddress): SignatureDTO | null;
+  /** Every verdict from the last check; `null` before the first. */
+  listVerdicts(): readonly SignatureVerdict[] | null;
+  /** One signed field's verdict from the last check, or `null`. */
+  getVerdict(field: SignatureFieldAddress): SignatureVerdict | null;
+  /** What the document's signatures allow, or `null` before they're read. */
+  getProtection(): DocumentProtection | null;
+  /** A signature prepared in two steps and not completed: the document can't be changed until it is, or is cancelled. */
+  getPending(): SignaturePending | null;
+  /** Whether a signing or a fill is running. */
+  isBusy(): boolean;
+  /** The mode in effect: the `mode` setting, or its default. */
+  getMode(): SignatureMode;
+  /** The field the next picked mark goes to, or `null`. */
+  getTarget(): FormFieldRef | null;
+  /**
+   * Sign a field: the mark becomes what it shows, the key seals the document,
+   * and the signed document is a new version. A signal that fires before the
+   * seal leaves nothing signed. Fires `onSigned`. Rejects `permission-denied`
+   * for a field you may not sign (`canSign`), or without `doc.sign.certify`
+   * to certify, `invalid-input` without a key, `not-found`,
+   * `operation-cancelled`.
+   */
+  sign(input: SignFieldInput, options?: OperationOptions): Promise<SignatureCompleteResult>;
+  /**
+   * Signing in two steps, the first: resolves the digest for your key to sign,
+   * and keeps the document from changing until `completeSignature()` or
+   * `cancelPending()`. Rejects like `sign()`.
+   */
+  prepareSignature(input: PrepareSignatureInput, options?: OperationOptions): Promise<PreparedSignature>;
+  /** Signing in two steps, the second: the key's CMS seals the document. Fires `onSigned`. Rejects `not-found` for a signing this session didn't prepare. */
+  completeSignature(signingId: string, cms: Uint8Array, options?: OperationOptions): Promise<SignatureCompleteResult>;
+  /** Give up a signature prepared in two steps, so the document can be changed again. */
+  cancelPending(options?: OperationOptions): Promise<void>;
+  /**
+   * Draw a mark into a field without signing. Fires `onFilled`. Rejects
+   * `permission-denied` for a field you may not fill in (`canFill`),
+   * `conflict` on a signed field.
+   */
+  fillField(field: FormFieldRef, mark: Mark, options?: OperationOptions): Promise<void>;
+  /** Take a drawn mark out of a field. Fires `onCleared`. Rejects like `fillField()`. */
+  clearField(field: FormFieldRef, options?: OperationOptions): Promise<void>;
+  /**
+   * Do what a click with an armed mark does: in a field, sign, fill or ask
+   * (`onSignRequested`), by `mode`; anywhere else, place it as a stamp.
+   * Rejects like the verb it runs.
+   */
+  placeMark(mark: Mark, target: {
+    field: FormFieldRef;
+  } | StampPlacement, options?: OperationOptions): Promise<PlaceMarkResult>;
+  /** Make a field the target, where the next mark the person picks goes; `null` clears. Fires `onTargetChanged`. */
+  setTarget(field: FormFieldRef | null): void;
+  /** Ask your UI to show a signed field's details, as clicking it does. Fires `onInspectionRequested`. */
+  requestInspection(field: FormFieldRef): void;
+  /** Read the signatures again; resolves the snapshot. */
+  refresh(options?: OperationOptions): Promise<SignatureSnapshot | null>;
+  /**
+   * Check every signature again and resolve the verdicts. Unsaved changes
+   * count, so the verdict is the one the downloaded file will get;
+   * `until: 'persisted'` checks the file as it was opened. Fires `onValidated`.
+   */
+  validate(options?: SignatureValidateOptions): Promise<readonly SignatureVerdict[]>;
+  /** Check one signed field. Rejects `not-found` for an unsigned or unknown field. */
+  validateField(field: SignatureFieldAddress, options?: SignatureValidateOptions): Promise<SignatureVerdict>;
+  /** What changed after a signature or a version of the file, rule by rule. */
+  analyzeChanges(input: AnalyzeInput, options?: OperationOptions): Promise<ChangeAnalysis>;
+  /**
+   * The exact bytes of the file version a signature covers. Rejects
+   * `permission-denied` without `doc.download`, `not-found` for an unsigned
+   * field.
+   */
+  readRevision(target: SignatureFieldAddress | {
+    revisionIndex: number;
+  }, options?: OperationOptions): Promise<Uint8Array>;
+  /**
+   * Whether signing this field is allowed: `doc.sign`, or a `fields:sign`
+   * permission for its group. `false` for a field the form doesn't have. A
+   * per-call key or two-step signing needs no `key` setting.
+   */
+  canSign(field: FormFieldRef): boolean;
+  /**
+   * Whether drawing a mark into this field without signing is allowed:
+   * `doc.forms.fill`, or a `fields:fill` permission for its group.
+   */
+  canFill(field: FormFieldRef): boolean;
+  /** Whether a certification may be offered: the `allowCertify` setting and `doc.sign.certify`. */
+  canCertify(): boolean;
+  /** Whether the signed bytes may be read: `doc.download`. */
+  canReadRevision(): boolean;
+  /** A field was signed, whoever signed it; fires once the facts show the sealed field. */
+  readonly onSigned: EventHook<SignatureSignedEvent>;
+  /** A mark was drawn into a field. */
+  readonly onFilled: EventHook<SignatureFilledEvent>;
+  /** A drawn mark was taken out of a field. */
+  readonly onCleared: EventHook<SignatureClearedEvent>;
+  /** The signatures were checked. */
+  readonly onValidated: EventHook<SignatureValidatedEvent>;
+  /** What the signatures allow changed. */
+  readonly onProtectionChanged: EventHook<SignatureProtectionChangedEvent>;
+  /** A change would break a signature once saved. */
+  readonly onInvalidationPredicted: EventHook<SignatureInvalidationPredictedEvent>;
+  /** A field became the target, or the target was cleared. */
+  readonly onTargetChanged: EventHook<SignatureTargetChangedEvent>;
+  /** In `'ask'` mode, a mark was dropped on a field. */
+  readonly onSignRequested: EventHook<SignatureSignRequestedEvent>;
+  /** A signed field was clicked. */
+  readonly onInspectionRequested: EventHook<SignatureInspectionRequestedEvent>;
+}
+//#endregion
+export { SignaturePrepared$1 as A, SignerPort$1 as B, SignatureFilledEvent as C, SignatureKey as D, SignatureInvalidationPredictedEvent as E, SignatureSnapshot$1 as F, signerRowsOf as G, TrustPort$1 as H, SignatureTargetChangedEvent as I, SignatureToken as K, SignatureValidateOptions as L, SignatureSettings as M, SignatureSignRequestedEvent as N, SignatureMode as O, SignatureSignedEvent as P, SignatureValidatedEvent as R, SignatureFieldAddress as S, SignatureInspectionRequestedEvent as T, ValidationTime$1 as U, SignerRow as V, markRoleOf as W, SignatureCapability as _, FieldLockSpec$1 as a, SignatureConfig as b, Mark as c, PrepareSignatureInput as d, PreparedSignature as f, SignFieldInput as g, SIGNATURE_MARK_NAME as h, DocumentProtection$1 as i, SignatureProtectionChangedEvent as j, SignaturePending as k, MarkRole as l, SIGNATURE_DEFAULTS as m, ChangeAnalysis$1 as n, FormFieldRef$1 as o, SIGNATURES_LIBRARY_KIND as p, DocMdpPermission$1 as r, INITIALS_MARK_NAME as s, AnalyzeInput$1 as t, PlaceMarkResult as u, SignatureClearedEvent as v, SignatureInfo as w, SignatureDTO$1 as x, SignatureCompleteResult$1 as y, SignatureVerdict$1 as z };
+//# sourceMappingURL=contract-GUWa_aBY.d.ts.map

package/dist/contract-NW5jPVqt.js

@@ -0,0 +1,59 @@
+import { createCapabilityToken } from "@embedpdf/core";
+//#region src/token.ts
+/** The package token, created once here and re-exported by `contract.ts`. */
+const SignatureToken = createCapabilityToken("signature", {
+	hint: `add signaturePlugin() from '@embedpdf/plugin-signature' to your plugins list`,
+	promises: {
+		sign: true,
+		prepareSignature: true,
+		completeSignature: true,
+		cancelPending: true,
+		fillField: true,
+		clearField: true,
+		placeMark: true,
+		refresh: true,
+		validate: true,
+		validateField: true,
+		analyzeChanges: true,
+		readRevision: true
+	}
+});
+//#endregion
+//#region src/contract.ts
+/** What the signature settings are when the app registers none. */
+const SIGNATURE_DEFAULTS = {
+	key: null,
+	mode: null,
+	trust: null,
+	allowCertify: false
+};
+/** The stamp-library kind that holds people's marks: one library per person. */
+const SIGNATURES_LIBRARY_KIND = "signatures";
+/** The asset identifiers inside a signatures library: the full signature and the initials. */
+const SIGNATURE_MARK_NAME = "signature";
+const INITIALS_MARK_NAME = "initials";
+/** Which mark an asset of a signatures library is (anything not named `initials` is a signature). */
+const markRoleOf = (asset) => asset.name === "initials" ? "initials" : "signature";
+/**
+* The people whose marks the stamp plugin holds, one row per library of kind
+* `signatures`, in the order of `libraries`: give it the stamp plugin's
+* `listLibraries({ kind: SIGNATURES_LIBRARY_KIND })` and `listAssets()`. A
+* pure derivation: rename, delete and export are the stamp plugin's library
+* verbs, and nothing is stored beyond the library's file.
+*/
+function signerRowsOf(libraries, assets) {
+	return libraries.filter((library) => library.kind === SIGNATURES_LIBRARY_KIND).map((library) => {
+		const own = assets.filter((asset) => asset.libraryId === library.id);
+		return {
+			libraryId: library.id,
+			name: library.name,
+			library,
+			signatures: own.filter((asset) => markRoleOf(asset) === "signature"),
+			initials: own.find((asset) => markRoleOf(asset) === "initials") ?? null
+		};
+	});
+}
+//#endregion
+export { markRoleOf as a, SIGNATURE_MARK_NAME as i, SIGNATURES_LIBRARY_KIND as n, signerRowsOf as o, SIGNATURE_DEFAULTS as r, SignatureToken as s, INITIALS_MARK_NAME as t };
+
+//# sourceMappingURL=contract-NW5jPVqt.js.map

package/dist/contract-NW5jPVqt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-NW5jPVqt.js","names":[],"sources":["../src/token.ts","../src/contract.ts"],"sourcesContent":["/** The package token, created once here and re-exported by `contract.ts`. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { SignatureCapability } from './contract';\n\nexport const SignatureToken = createCapabilityToken<SignatureCapability>('signature', {\n  hint: `add signaturePlugin() from '@embedpdf/plugin-signature' to your plugins list`,\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    sign: true,\n    prepareSignature: true,\n    completeSignature: true,\n    cancelPending: true,\n    fillField: true,\n    clearField: true,\n    placeMark: true,\n    refresh: true,\n    validate: true,\n    validateField: true,\n    analyzeChanges: true,\n    readRevision: true,\n  },\n});\n","/**\n * @embedpdf/plugin-signature/contract: the public signature vocabulary: the\n * act of signing (one-shot and two-phase), visual fills, validation, the\n * sign-here flow, and the facts about a document's signatures.\n */\nimport type {\n  EventHook,\n  EventOrigin,\n  OperationOptions,\n  ResourceStatus,\n  SettingsApi,\n} from '@embedpdf/core';\nimport type {\n  SignatureVerdict,\n  SignerPort,\n  TrustPort,\n  ValidationTime,\n} from '@embedpdf/core-signature';\nimport type {\n  AnalyzeInput,\n  AnnotationRef,\n  BinarySource,\n  ChangeAnalysis,\n  DigestAlgorithm,\n  DocMdpPermission,\n  DocumentProtection,\n  FieldLockSpec,\n  FormFieldRef,\n  FormWidget,\n  SignatureCompleteResult,\n  SignatureDTO,\n  SignaturePrepared,\n  SignatureSignerInput,\n  SignatureSnapshot,\n  SignatureSubFilter,\n} from '@embedpdf/engine-core/runtime';\nimport type { StampPlacement } from '@embedpdf/plugin-annotation/contract';\nimport type { StampAsset, StampLibrary } from '@embedpdf/plugin-stamp/contract';\n\nexport { SignatureToken } from './token';\nexport type {\n  AnalyzeInput,\n  ChangeAnalysis,\n  DocMdpPermission,\n  DocumentProtection,\n  FieldLockSpec,\n  FormFieldRef,\n  SignatureCompleteResult,\n  SignatureDTO,\n  SignaturePrepared,\n  SignatureSnapshot,\n} from '@embedpdf/engine-core/runtime';\nexport type {\n  SignatureVerdict,\n  SignerPort,\n  TrustPort,\n  ValidationTime,\n} from '@embedpdf/core-signature';\n\n/**\n * What placing a mark on a signature field does:\n *   - `sign`    seal the field with the configured key (the mark is the appearance);\n *   - `visual`  draw the mark into the field without sealing (Preview's \"signature\");\n *   - `ask`     neither: `onSignRequested` fires so the chrome can open its dialog and decide.\n */\nexport type SignatureMode = 'sign' | 'visual' | 'ask';\n\n/** The key that signs: a signer port, or a function that returns one when someone signs. */\nexport type SignatureKey = SignerPort | (() => SignerPort | Promise<SignerPort>);\n\n/**\n * The signature plugin's settings. `signaturePlugin(config)` registers them\n * over {@link SIGNATURE_DEFAULTS}, and `updateSettings()` changes them for\n * every document while the app runs. Each is one value: a change replaces a\n * key or a trust port whole.\n */\nexport interface SignatureSettings {\n  /** The key: a raw signer (the CMS is built here) or a CMS signer (a service builds it); `null` for none. */\n  readonly key: SignatureKey | null;\n  /** What a mark does in a field; `null` is `'sign'` with a key, else `'visual'`. */\n  readonly mode: SignatureMode | null;\n  /** The certificates you trust, for checking signatures. Without them a verdict is at best `valid-untrusted`. */\n  readonly trust: TrustPort | null;\n  /** Let a first signature be a certification (still needs `doc.sign.certify`). */\n  readonly allowCertify: boolean;\n}\n\n/** What the signature settings are when the app registers none. */\nexport const SIGNATURE_DEFAULTS: SignatureSettings = {\n  key: null,\n  mode: null,\n  trust: null,\n  allowCertify: false,\n};\n\n/** What `signaturePlugin(config)` takes: any of the settings. */\nexport type SignatureConfig = Partial<SignatureSettings>;\n\n/** The mark: a stamp-plugin asset, or bytes the embedder brings (PNG, JPEG, or a one-page PDF). */\nexport type Mark = { assetId: string } | { source: BinarySource };\n\n/**\n * How a signature field is addressed: its field ref, or its widget, by\n * annotation ref or as a signature names it (`SignatureDTO.widget`).\n */\nexport type SignatureFieldAddress = FormFieldRef | AnnotationRef | FormWidget;\n\nexport interface SignFieldInput {\n  field: FormFieldRef;\n  mark: Mark;\n  /** A per-call key; the `key` setting otherwise. */\n  key?: SignatureKey;\n  /** What the signature dictionary says about the signer; the name defaults to the certificate's subject. */\n  signer?: SignatureSignerInput;\n  /** Instead of the mark: a ready one-page appearance PDF the embedder composed itself. */\n  appearance?: BinarySource;\n  certify?: { permission: DocMdpPermission };\n  lock?: FieldLockSpec;\n}\n\n/** Two-phase signing, step one: everything but the key. The digest comes back; a CMS goes in. */\nexport interface PrepareSignatureInput {\n  field: FormFieldRef;\n  mark?: Mark;\n  appearance?: BinarySource;\n  signer?: SignatureSignerInput;\n  certify?: { permission: DocMdpPermission };\n  lock?: FieldLockSpec;\n  subFilter?: SignatureSubFilter;\n  digest?: Exclude<DigestAlgorithm, 'sha1'>;\n}\n\n/** The parked half of a two-phase signing (`prepareSignature` → `completeSignature`). */\nexport type PreparedSignature = SignaturePrepared;\n\n/** The stamp-library kind that holds people's marks: one library per person. */\nexport const SIGNATURES_LIBRARY_KIND = 'signatures';\n/** The asset identifiers inside a signatures library: the full signature and the initials. */\nexport const SIGNATURE_MARK_NAME = 'signature';\nexport const INITIALS_MARK_NAME = 'initials';\nexport type MarkRole = 'signature' | 'initials';\n/** Which mark an asset of a signatures library is (anything not named `initials` is a signature). */\nexport const markRoleOf = (asset: Pick<StampAsset, 'name'>): MarkRole =>\n  asset.name === INITIALS_MARK_NAME ? 'initials' : 'signature';\n\n/** One person in a signatures picker: a library of kind `signatures`, with its marks split by role. */\nexport interface SignerRow {\n  readonly libraryId: string;\n  readonly name: string;\n  readonly library: StampLibrary;\n  /** Every full signature of the person, in the library's order. */\n  readonly signatures: StampAsset[];\n  /** The person's initials, or `null` when the library has none. */\n  readonly initials: StampAsset | null;\n}\n\n/**\n * The people whose marks the stamp plugin holds, one row per library of kind\n * `signatures`, in the order of `libraries`: give it the stamp plugin's\n * `listLibraries({ kind: SIGNATURES_LIBRARY_KIND })` and `listAssets()`. A\n * pure derivation: rename, delete and export are the stamp plugin's library\n * verbs, and nothing is stored beyond the library's file.\n */\nexport function signerRowsOf(\n  libraries: readonly StampLibrary[],\n  assets: readonly StampAsset[],\n): SignerRow[] {\n  return libraries\n    .filter((library) => library.kind === SIGNATURES_LIBRARY_KIND)\n    .map((library) => {\n      const own = assets.filter((asset) => asset.libraryId === library.id);\n      return {\n        libraryId: library.id,\n        name: library.name,\n        library,\n        signatures: own.filter((asset) => markRoleOf(asset) === 'signature'),\n        initials: own.find((asset) => markRoleOf(asset) === 'initials') ?? null,\n      };\n    });\n}\n\n/** A signature prepared in two steps and not completed yet. */\nexport interface SignaturePending {\n  readonly signingId: string;\n  readonly field: FormFieldRef;\n}\n\n/** A signed field's facts, with its verdict from the last check (`null` until one ran). */\nexport interface SignatureInfo extends SignatureDTO {\n  readonly verdict: SignatureVerdict | null;\n}\n\n/** What `placeMark` did: sealed, drawn, handed to the chrome (mode `ask`), or placed as a stamp. */\nexport type PlaceMarkResult =\n  | { kind: 'signed'; field: FormFieldRef; result: SignatureCompleteResult }\n  | { kind: 'filled'; field: FormFieldRef }\n  | { kind: 'requested'; field: FormFieldRef }\n  | { kind: 'placed'; annotation: AnnotationRef };\n\n// ── events ──\n/** A signing completed, in this session or another: the confirmed `signatures.completed` fact. */\nexport interface SignatureSignedEvent {\n  /** The sealed field, by its durable object-number ref. */\n  readonly field: FormFieldRef;\n  readonly result: SignatureCompleteResult;\n  readonly origin: EventOrigin;\n}\n/** This session's `fillField()` drew a mark into a field. */\nexport interface SignatureFilledEvent {\n  readonly field: FormFieldRef;\n}\n/** This session's `clearField()` took a drawn mark out of a field. */\nexport interface SignatureClearedEvent {\n  readonly field: FormFieldRef;\n}\nexport interface SignatureValidatedEvent {\n  readonly verdicts: readonly SignatureVerdict[];\n}\nexport interface SignatureProtectionChangedEvent {\n  readonly protection: DocumentProtection;\n}\n/** An unsaved edit just turned a signature that held into one a save would invalidate. Once per edge. */\nexport interface SignatureInvalidationPredictedEvent {\n  readonly field: FormFieldRef;\n  readonly detail: string;\n}\nexport interface SignatureTargetChangedEvent {\n  readonly field: FormFieldRef | null;\n}\n/** Mode `ask`: a mark met a field and the chrome decides (open its dialog, then `sign` / `fillField`). */\nexport interface SignatureSignRequestedEvent {\n  readonly field: FormFieldRef;\n  readonly mark: Mark;\n}\n/** A signed field was activated: show what its signature says. */\nexport interface SignatureInspectionRequestedEvent {\n  readonly field: FormFieldRef;\n}\n\n/** Options for `validate()` and `validateField()`. */\nexport interface SignatureValidateOptions extends OperationOptions {\n  /** The moment the certificates are judged at; now by default. */\n  readonly at?: ValidationTime;\n  /** `'persisted'` checks the file as it was opened; `'working-copy'` (the default) counts unsaved changes. */\n  readonly until?: 'persisted' | 'working-copy';\n}\n\n/**\n * Signing, visual fills and checking signatures for one document. Every verb\n * rejects with a `PluginError`, and every async verb takes a `signal`. Its\n * settings belong to the plugin, not to a document.\n */\nexport interface SignatureCapability extends SettingsApi<SignatureSettings> {\n  // ── reading ──\n  /** Every signature field and its facts, the file's versions and `protection`. The same object until it changes. */\n  getSnapshot(): SignatureSnapshot | null;\n  /** Whether the signatures are read. */\n  getStatus(): ResourceStatus;\n  /** The signed fields, in document order, each with its verdict once checked. The same array until one changes. */\n  listSignatures(): readonly SignatureInfo[];\n  /** Signature fields still to sign, in document order. The same array until one changes. */\n  listUnsignedFields(): readonly FormFieldRef[];\n  /** One signature field's facts, signed or not, by its ref or its widget's, or `null`. */\n  getSignature(field: SignatureFieldAddress): SignatureDTO | null;\n  /** Every verdict from the last check; `null` before the first. */\n  listVerdicts(): readonly SignatureVerdict[] | null;\n  /** One signed field's verdict from the last check, or `null`. */\n  getVerdict(field: SignatureFieldAddress): SignatureVerdict | null;\n  /** What the document's signatures allow, or `null` before they're read. */\n  getProtection(): DocumentProtection | null;\n  /** A signature prepared in two steps and not completed: the document can't be changed until it is, or is cancelled. */\n  getPending(): SignaturePending | null;\n  /** Whether a signing or a fill is running. */\n  isBusy(): boolean;\n  /** The mode in effect: the `mode` setting, or its default. */\n  getMode(): SignatureMode;\n  /** The field the next picked mark goes to, or `null`. */\n  getTarget(): FormFieldRef | null;\n\n  // ── signing ──\n  /**\n   * Sign a field: the mark becomes what it shows, the key seals the document,\n   * and the signed document is a new version. A signal that fires before the\n   * seal leaves nothing signed. Fires `onSigned`. Rejects `permission-denied`\n   * for a field you may not sign (`canSign`), or without `doc.sign.certify`\n   * to certify, `invalid-input` without a key, `not-found`,\n   * `operation-cancelled`.\n   */\n  sign(input: SignFieldInput, options?: OperationOptions): Promise<SignatureCompleteResult>;\n  /**\n   * Signing in two steps, the first: resolves the digest for your key to sign,\n   * and keeps the document from changing until `completeSignature()` or\n   * `cancelPending()`. Rejects like `sign()`.\n   */\n  prepareSignature(\n    input: PrepareSignatureInput,\n    options?: OperationOptions,\n  ): Promise<PreparedSignature>;\n  /** Signing in two steps, the second: the key's CMS seals the document. Fires `onSigned`. Rejects `not-found` for a signing this session didn't prepare. */\n  completeSignature(\n    signingId: string,\n    cms: Uint8Array,\n    options?: OperationOptions,\n  ): Promise<SignatureCompleteResult>;\n  /** Give up a signature prepared in two steps, so the document can be changed again. */\n  cancelPending(options?: OperationOptions): Promise<void>;\n  /**\n   * Draw a mark into a field without signing. Fires `onFilled`. Rejects\n   * `permission-denied` for a field you may not fill in (`canFill`),\n   * `conflict` on a signed field.\n   */\n  fillField(field: FormFieldRef, mark: Mark, options?: OperationOptions): Promise<void>;\n  /** Take a drawn mark out of a field. Fires `onCleared`. Rejects like `fillField()`. */\n  clearField(field: FormFieldRef, options?: OperationOptions): Promise<void>;\n  /**\n   * Do what a click with an armed mark does: in a field, sign, fill or ask\n   * (`onSignRequested`), by `mode`; anywhere else, place it as a stamp.\n   * Rejects like the verb it runs.\n   */\n  placeMark(\n    mark: Mark,\n    target: { field: FormFieldRef } | StampPlacement,\n    options?: OperationOptions,\n  ): Promise<PlaceMarkResult>;\n  /** Make a field the target, where the next mark the person picks goes; `null` clears. Fires `onTargetChanged`. */\n  setTarget(field: FormFieldRef | null): void;\n  /** Ask your UI to show a signed field's details, as clicking it does. Fires `onInspectionRequested`. */\n  requestInspection(field: FormFieldRef): void;\n\n  // ── checking ──\n  /** Read the signatures again; resolves the snapshot. */\n  refresh(options?: OperationOptions): Promise<SignatureSnapshot | null>;\n  /**\n   * Check every signature again and resolve the verdicts. Unsaved changes\n   * count, so the verdict is the one the downloaded file will get;\n   * `until: 'persisted'` checks the file as it was opened. Fires `onValidated`.\n   */\n  validate(options?: SignatureValidateOptions): Promise<readonly SignatureVerdict[]>;\n  /** Check one signed field. Rejects `not-found` for an unsigned or unknown field. */\n  validateField(\n    field: SignatureFieldAddress,\n    options?: SignatureValidateOptions,\n  ): Promise<SignatureVerdict>;\n  /** What changed after a signature or a version of the file, rule by rule. */\n  analyzeChanges(input: AnalyzeInput, options?: OperationOptions): Promise<ChangeAnalysis>;\n  /**\n   * The exact bytes of the file version a signature covers. Rejects\n   * `permission-denied` without `doc.download`, `not-found` for an unsigned\n   * field.\n   */\n  readRevision(\n    target: SignatureFieldAddress | { revisionIndex: number },\n    options?: OperationOptions,\n  ): Promise<Uint8Array>;\n\n  // ── permissions ──\n  /**\n   * Whether signing this field is allowed: `doc.sign`, or a `fields:sign`\n   * permission for its group. `false` for a field the form doesn't have. A\n   * per-call key or two-step signing needs no `key` setting.\n   */\n  canSign(field: FormFieldRef): boolean;\n  /**\n   * Whether drawing a mark into this field without signing is allowed:\n   * `doc.forms.fill`, or a `fields:fill` permission for its group.\n   */\n  canFill(field: FormFieldRef): boolean;\n  /** Whether a certification may be offered: the `allowCertify` setting and `doc.sign.certify`. */\n  canCertify(): boolean;\n  /** Whether the signed bytes may be read: `doc.download`. */\n  canReadRevision(): boolean;\n\n  // ── events ──\n  /** A field was signed, whoever signed it; fires once the facts show the sealed field. */\n  readonly onSigned: EventHook<SignatureSignedEvent>;\n  /** A mark was drawn into a field. */\n  readonly onFilled: EventHook<SignatureFilledEvent>;\n  /** A drawn mark was taken out of a field. */\n  readonly onCleared: EventHook<SignatureClearedEvent>;\n  /** The signatures were checked. */\n  readonly onValidated: EventHook<SignatureValidatedEvent>;\n  /** What the signatures allow changed. */\n  readonly onProtectionChanged: EventHook<SignatureProtectionChangedEvent>;\n  /** A change would break a signature once saved. */\n  readonly onInvalidationPredicted: EventHook<SignatureInvalidationPredictedEvent>;\n  /** A field became the target, or the target was cleared. */\n  readonly onTargetChanged: EventHook<SignatureTargetChangedEvent>;\n  /** In `'ask'` mode, a mark was dropped on a field. */\n  readonly onSignRequested: EventHook<SignatureSignRequestedEvent>;\n  /** A signed field was clicked. */\n  readonly onInspectionRequested: EventHook<SignatureInspectionRequestedEvent>;\n}\n"],"mappings":";;;AAKA,MAAa,iBAAiB,sBAA2C,aAAa;CACpF,MAAM;CAGN,UAAU;EACR,MAAM;EACN,kBAAkB;EAClB,mBAAmB;EACnB,eAAe;EACf,WAAW;EACX,YAAY;EACZ,WAAW;EACX,SAAS;EACT,UAAU;EACV,eAAe;EACf,gBAAgB;EAChB,cAAc;CAChB;AACF,CAAC;;;;ACiED,MAAa,qBAAwC;CACnD,KAAK;CACL,MAAM;CACN,OAAO;CACP,cAAc;AAChB;;AA2CA,MAAa,0BAA0B;;AAEvC,MAAa,sBAAsB;AACnC,MAAa,qBAAqB;;AAGlC,MAAa,cAAc,UACzB,MAAM,SAAA,aAA8B,aAAa;;;;;;;;AAoBnD,SAAgB,aACd,WACA,QACa;CACb,OAAO,UACJ,QAAQ,YAAY,QAAQ,SAAS,uBAAuB,CAAC,CAC7D,KAAK,YAAY;EAChB,MAAM,MAAM,OAAO,QAAQ,UAAU,MAAM,cAAc,QAAQ,EAAE;EACnE,OAAO;GACL,WAAW,QAAQ;GACnB,MAAM,QAAQ;GACd;GACA,YAAY,IAAI,QAAQ,UAAU,WAAW,KAAK,MAAM,WAAW;GACnE,UAAU,IAAI,MAAM,UAAU,WAAW,KAAK,MAAM,UAAU,KAAK;EACrE;CACF,CAAC;AACL"}