@josephomills/esign 0.2.2

package/dist/server/index.d.ts

@@ -0,0 +1,357 @@
+import { S as SubjectSelection, E as EsignChannel, R as ResendPolicy, P as PersistencePort, a as SubjectsPort, N as NotifierPort, C as Clock, b as SkippedSubject, c as Placement, d as StoragePort, e as SigningDocumentVersionDTO, f as SigningDocumentDTO, g as SigningRequestDTO, H as HooksPort, h as EsignConfig, V as VersionPolicy, i as SubjectSigningStatus, j as CoverageReport, k as CampaignStatsRow, D as DocumentStatsRow, l as StatsRange, m as ScopeStatsRow, O as OutstandingRequest, n as SubjectTypeDescriptor } from '../ports-DtICqgEf.js';
+export { A as ACTIVE_STATUSES, o as AuthPort, p as DeclineInput, q as ESIGN_CHANNELS, r as ESIGN_STATUSES, s as EsignStatus, G as GroupBreakdown, t as NewAuditEventRow, u as NewRequestRow, v as NotifierAttachment, w as Recipient, x as RequestSummary, y as SigningAuditEventDTO, z as SigningCampaignDTO, B as StatusCountMap, F as SubjectFilter, I as SubjectFilterField, J as SubjectSigningState, K as SubjectSummary, L as SubmitSignatureInput, T as TERMINAL_STATUSES, M as assertTransition, Q as canTransition, U as declineSchema, W as esignChannelSchema, X as isActive, Y as isTerminal, Z as placementSchema, _ as subjectSelectionSchema, $ as submitSignatureSchema } from '../ports-DtICqgEf.js';
+import { PDFDocument } from 'pdf-lib';
+import { ZodType } from 'zod';
+
+/**
+ * Tamper-evident audit log (Level-1 seal). Every signing request accumulates an
+ * append-only chain of events (CREATED → NOTIFIED → VIEWED → CONSENTED → SIGNED
+ * → SEALED). Each link's `hash` covers the previous hash plus this link's
+ * contents, so altering any earlier event invalidates every hash after it. The
+ * chain is rendered onto the sealed PDF's certificate page and re-checkable with
+ * `verifyChain`.
+ */
+interface AuditEventInput {
+    type: string;
+    payload: Record<string, unknown>;
+    /** ISO instant; passed in (never `Date.now()`) so seals are reproducible. */
+    occurredAt: string;
+}
+interface AuditLink extends AuditEventInput {
+    seq: number;
+    prevHash: string | null;
+    hash: string;
+}
+/** Deterministic JSON: object keys sorted, `undefined` normalized to null. */
+declare function canonicalize(value: unknown): string;
+/** The hash bound into a link: sha256(prevHash | seq | type | occurredAt | payload). */
+declare function linkHash(prevHash: string | null, seq: number, type: string, occurredAt: string, payload: unknown): string;
+/** Append one event to a chain (or start it when `prev` is null). */
+declare function appendEvent(prev: AuditLink | null, input: AuditEventInput): AuditLink;
+/** Fold a list of events into a verified chain. */
+declare function buildChain(inputs: AuditEventInput[]): AuditLink[];
+/** Recompute every hash; `brokenAt` is the seq of the first bad link, else null. */
+declare function verifyChain(links: AuditLink[]): {
+    ok: boolean;
+    brokenAt: number | null;
+};
+
+/**
+ * Persist one audit link and return it, so the caller can thread the chain tip
+ * into the next event. Shared by the fan-out here and the signer submit handler.
+ */
+declare function recordEvent(persistence: PersistencePort, requestId: string, prev: AuditLink | null, input: AuditEventInput): Promise<AuditLink>;
+interface ChannelContent {
+    subject: string;
+    body: string;
+}
+type CampaignContentBuilder = (ctx: {
+    documentTitle: string;
+    note: string | null;
+    recipientName: string;
+}) => ChannelContent;
+interface CreateCampaignDeps {
+    persistence: PersistencePort;
+    subjects: SubjectsPort;
+    notifier: NotifierPort;
+    clock: Clock;
+    baseUrl: string;
+    defaultExpiryDays: number;
+    content?: CampaignContentBuilder;
+}
+interface CreateCampaignArgs {
+    /** Opaque host scope (estate id / country id / null) — already authorized by the route. */
+    scopeId?: string | null;
+    documentVersionId: string;
+    selection: SubjectSelection;
+    channels: EsignChannel[];
+    note?: string | null;
+    emailReceipt?: boolean;
+    expiresInDays?: number;
+    resendPolicy?: ResendPolicy;
+    createdById?: string | null;
+}
+interface CreateCampaignResult {
+    /** null when the (filtered) target group resolved to nobody — e.g. "uncovered" with no new subjects. */
+    campaignId: string | null;
+    sent: number;
+    skipped: SkippedSubject[];
+}
+/**
+ * Send a version to a target group. Resolves recipients server-side via the
+ * SubjectsPort, applies the resend policy by diffing against existing requests,
+ * mints no-login tokens, creates the request rows, and fans out one notification
+ * per recipient × channel — recording a CREATED + per-send NOTIFIED audit chain.
+ */
+declare function createCampaign(deps: CreateCampaignDeps, args: CreateCampaignArgs): Promise<CreateCampaignResult>;
+
+interface CreateDocumentInput {
+    scopeId?: string | null;
+    documentType?: string | null;
+    title: string;
+    audience?: SubjectSelection | null;
+    createdById?: string | null;
+}
+declare function createDocument(persistence: PersistencePort, input: CreateDocumentInput): Promise<SigningDocumentDTO>;
+/** A new version supplies its PDF either by an already-uploaded key or raw bytes. */
+type VersionSource = {
+    objectKey: string;
+} | {
+    pdfBytes: Uint8Array;
+    scopeId?: string | null;
+};
+interface AddVersionInput {
+    documentId: string;
+    placement: Placement;
+    source: VersionSource;
+    changeNote?: string | null;
+    createdById?: string | null;
+}
+/**
+ * Add an immutable version to a document: validate + hash the source PDF, store
+ * it (when bytes were passed), persist the next-numbered version, and point the
+ * document at it as current.
+ */
+declare function addVersion(deps: {
+    persistence: PersistencePort;
+    storage: StoragePort;
+}, input: AddVersionInput): Promise<SigningDocumentVersionDTO>;
+
+interface SignDeps {
+    persistence: PersistencePort;
+    storage: StoragePort;
+    clock: Clock;
+    notifier: NotifierPort;
+    hooks?: HooksPort;
+}
+interface SigningView {
+    request: SigningRequestDTO;
+    /** Source PDF object key + placement for the signer page to render. */
+    sourceObjectKey: string;
+    placement: Placement;
+    documentTitle: string;
+}
+/**
+ * Data for the public signing page. Returns null for unknown / expired / revoked
+ * / already-finished requests so the host shows one "unavailable" screen.
+ */
+declare function getSigningView(deps: Pick<SignDeps, "persistence" | "clock">, token: string): Promise<SigningView | null>;
+/** Mark first view PENDING→VIEWED, recording a VIEWED audit event. Idempotent. */
+declare function recordView(deps: Pick<SignDeps, "persistence" | "clock" | "hooks">, token: string): Promise<void>;
+interface SubmitInput {
+    token: string;
+    signaturePng: Uint8Array;
+    signerName: string;
+    ip: string | null;
+    userAgent: string | null;
+}
+interface SubmitResult {
+    requestId: string;
+    sealedObjectKey: string;
+    alreadySigned: boolean;
+}
+/**
+ * The signer submit: consent → seal → store → persist SIGNED → fire hook →
+ * optional emailed receipt. Idempotent — a re-submit of a signed request returns
+ * the existing sealed key instead of re-sealing.
+ */
+declare function submitSignature(deps: SignDeps, input: SubmitInput): Promise<SubmitResult>;
+interface DeclineRequestInput {
+    token: string;
+    reason: string | null;
+}
+/** Signer declines: PENDING/VIEWED → DECLINED, recording a DECLINED event. */
+declare function declineRequest(deps: Pick<SignDeps, "persistence" | "clock" | "hooks">, input: DeclineRequestInput): Promise<void>;
+
+type RouteCtx$1 = {
+    params: {
+        token: string;
+    } | Promise<{
+        token: string;
+    }>;
+};
+/**
+ * POST the signer action. `?action=decline` declines; otherwise it submits the
+ * signature (consent → seal → SIGNED). Mount at `app/sign/[token]/submit/route.ts`.
+ */
+declare function createSignActionsRoute(deps: SignDeps): {
+    POST: (req: Request, ctx: RouteCtx$1) => Promise<Response>;
+};
+
+type RouteCtx = {
+    params: {
+        token: string;
+    } | Promise<{
+        token: string;
+    }>;
+};
+interface SignServeDeps {
+    persistence: PersistencePort;
+    storage: StoragePort;
+    clock: Clock;
+}
+/**
+ * GET the source PDF for the signer page, gated only by the (unguessable) token.
+ * Bad / expired / revoked / finished tokens all 404 the same way (no oracle).
+ * Mount at `app/api/esign/source/[token]/route.ts`; the host should rate-limit.
+ */
+declare function createSignServeRoute(deps: SignServeDeps): {
+    GET: (req: Request, ctx: RouteCtx) => Promise<Response>;
+};
+
+/**
+ * No-login signer token. We follow the share-link convention from the host
+ * apps: generate a random token, return the cleartext exactly once (it goes
+ * only into the `/sign/<token>` URL), and persist nothing but its sha256. A
+ * leaked database never yields a usable link.
+ */
+interface SigningToken {
+    /** Goes into the signer URL only — never stored. */
+    cleartext: string;
+    /** sha256(cleartext) — the value stored in `SigningRequest.tokenHash`. */
+    tokenHash: string;
+}
+/** sha256 of a string or bytes, lowercase hex (64 chars). */
+declare function sha256Hex(input: string | Uint8Array): string;
+/** A fresh signing token. `bytes` of entropy, base64url-encoded cleartext. */
+declare function newSigningToken(bytes?: number): SigningToken;
+
+type ResolvedEsignConfig<S> = EsignConfig<S> & Required<Pick<EsignConfig<S>, "routeBasePath" | "presignTtlS" | "defaultExpiryDays" | "clock">>;
+interface SubjectSigningStatusArgs {
+    subjectType: string;
+    subjectId: string;
+    documentId?: string;
+    documentType?: string;
+    versionPolicy: VersionPolicy;
+}
+/**
+ * The wired runtime: every engine function bound to the host's ports, plus the
+ * route-handler factories the host mounts. Mirrors milestone-grid's
+ * `configureMilestoneGrid(...) → { routes, ... }`.
+ */
+interface EsignRuntime<S> {
+    config: ResolvedEsignConfig<S>;
+    newSigningToken: typeof newSigningToken;
+    createDocument(input: CreateDocumentInput): Promise<SigningDocumentDTO>;
+    addVersion(input: AddVersionInput): Promise<SigningDocumentVersionDTO>;
+    createCampaign(args: CreateCampaignArgs): Promise<CreateCampaignResult>;
+    getSigningView(token: string): Promise<SigningView | null>;
+    recordView(token: string): Promise<void>;
+    submitSignature(input: SubmitInput): Promise<SubmitResult>;
+    declineRequest(input: DeclineRequestInput): Promise<void>;
+    subjectSigningStatus(args: SubjectSigningStatusArgs): Promise<SubjectSigningStatus>;
+    documentCoverage(documentId: string): Promise<CoverageReport>;
+    campaignStats(campaignId: string): Promise<CampaignStatsRow>;
+    documentStats(documentId: string): Promise<DocumentStatsRow>;
+    scopeStats(scopeId: string | null, range?: StatsRange): Promise<ScopeStatsRow>;
+    outstandingRequests(filter: {
+        scopeId?: string | null;
+        documentId?: string;
+        campaignId?: string;
+        now: Date;
+        limit?: number;
+    }): Promise<OutstandingRequest[]>;
+    routes: {
+        signServe: ReturnType<typeof createSignServeRoute>;
+        signActions: ReturnType<typeof createSignActionsRoute>;
+    };
+}
+declare function configureEsign<S>(opts: EsignConfig<S>): EsignRuntime<S>;
+
+/**
+ * Build a SubjectsPort from a list of host-defined subject-type descriptors.
+ * The package renders targeting from `groupField` / `filterFields` and calls
+ * the descriptor's enumeration/resolution methods; it never learns what a
+ * "MISSIONARY" or "APARTMENT" actually is.
+ */
+declare function registerSubjectTypes(types: SubjectTypeDescriptor[]): SubjectsPort;
+
+/**
+ * A 16-char unique id, matching the host `@db.VarChar(16)` convention. The
+ * package generates ids in code (the Prisma fragment carries no `@default`), so
+ * every esign-owned row gets a uid the same way across dhm-estates / flc-missions
+ * / flc-hr. Rejection sampling keeps the distribution uniform (no modulo bias).
+ */
+declare function uid(size?: number): string;
+
+/**
+ * Human-readable signature certificate appended as the final page of every
+ * sealed PDF. It prints the signer, the document content SHA-256, the audit
+ * chain tip, and the full event log — so the seal is verifiable by eye, and the
+ * printed hashes let anyone re-check integrity out of band.
+ */
+interface CertInfo {
+    documentTitle: string;
+    signerName: string;
+    signedAt: string;
+    signerIp: string | null;
+    requestId: string;
+    /** sha256 of the flattened, signature-stamped content (pre-certificate). */
+    documentSha256: string;
+    /** The audit chain tip (SigningRequest.finalAuditHash). */
+    finalHash: string;
+    links: AuditLink[];
+}
+declare function renderAuditCertificatePage(pdf: PDFDocument, info: CertInfo): Promise<void>;
+
+/**
+ * The Level-1 seal. Loads the version's source PDF, stamps the signature within
+ * the manager's placement box, appends SIGNED + SEALED audit links, renders the
+ * certificate page, and returns the flattened bytes plus the content hash and
+ * chain tip. Pure + deterministic: a fixed input (incl. `signedAt`) yields
+ * byte-identical output, so `sealedSha256` is reproducible and testable.
+ *
+ * `documentSha256` is the hash of the stamped content *before* the certificate
+ * page (the bytes that were actually signed); `sealedSha256` covers the final
+ * file. A future Level-2 PAdES seal wraps the returned `sealedPdf` unchanged.
+ */
+interface SealInput {
+    sourcePdf: Uint8Array;
+    /** PNG bytes of the drawn or typed signature. */
+    signaturePng: Uint8Array;
+    placement: Placement;
+    signerName: string;
+    /** ISO instant — also pins the PDF metadata dates for reproducibility. */
+    signedAt: string;
+    signerIp: string | null;
+    documentTitle: string;
+    requestId: string;
+    /** Existing chain (CREATED…CONSENTED). SIGNED + SEALED are appended here. */
+    priorChain: AuditLink[];
+}
+interface SealResult {
+    sealedPdf: Uint8Array;
+    sealedSha256: string;
+    documentSha256: string;
+    finalHash: string;
+    /** The SIGNED and SEALED links — the caller persists them. */
+    newLinks: AuditLink[];
+}
+declare function sealPdf(input: SealInput): Promise<SealResult>;
+
+interface CoverageDeps {
+    persistence: PersistencePort;
+    subjects: SubjectsPort;
+}
+/**
+ * Re-derive a document's coverage from the LIVE group (via the stored audience
+ * selection) so subjects added after a send are detected. Buckets every subject
+ * into signed / outstanding / needs-resign / uncovered / departed.
+ */
+declare function documentCoverage(deps: CoverageDeps, documentId: string): Promise<CoverageReport>;
+
+declare function parseBody<T>(req: Request, schema: ZodType<T>): Promise<T>;
+declare function ok(data: unknown, init?: ResponseInit): Response;
+/** Best-effort client IP from forwarding headers (for the audit trail). */
+declare function clientIp(req: Request): string | null;
+
+type EsignErrorCode = "UNAUTHENTICATED" | "FORBIDDEN" | "NOT_FOUND" | "INVALID_INPUT" | "CONFLICT" | "GONE" | "RATE_LIMITED" | "PAYLOAD_TOO_LARGE" | "STORAGE_ERROR" | "INTERNAL";
+declare class EsignError extends Error {
+    readonly code: EsignErrorCode;
+    readonly details?: unknown;
+    readonly status: number;
+    constructor(code: EsignErrorCode, message: string, details?: unknown);
+}
+declare function toErrorResponse(err: unknown): Response;
+
+export { type AddVersionInput, type AuditEventInput, type AuditLink, type CampaignContentBuilder, CampaignStatsRow, type CertInfo, type ChannelContent, Clock, type CoverageDeps, CoverageReport, type CreateCampaignArgs, type CreateCampaignDeps, type CreateCampaignResult, type CreateDocumentInput, type DeclineRequestInput, DocumentStatsRow, EsignChannel, EsignConfig, EsignError, type EsignErrorCode, type EsignRuntime, HooksPort, NotifierPort, OutstandingRequest, PersistencePort, Placement, ResendPolicy, type ResolvedEsignConfig, ScopeStatsRow, type SealInput, type SealResult, type SignDeps, type SignServeDeps, SigningDocumentDTO, SigningDocumentVersionDTO, SigningRequestDTO, type SigningToken, type SigningView, SkippedSubject, StatsRange, StoragePort, SubjectSelection, SubjectSigningStatus, type SubjectSigningStatusArgs, SubjectTypeDescriptor, SubjectsPort, type SubmitInput, type SubmitResult, VersionPolicy, type VersionSource, addVersion, appendEvent, buildChain, canonicalize, clientIp, configureEsign, createCampaign, createDocument, createSignActionsRoute, createSignServeRoute, declineRequest, documentCoverage, getSigningView, linkHash, newSigningToken, ok, parseBody, recordEvent, recordView, registerSubjectTypes, renderAuditCertificatePage, sealPdf, sha256Hex, submitSignature, toErrorResponse, uid, verifyChain };