@josephomills/esign 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mills
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @josephomills/esign
+
+Reusable, host-agnostic **document e-signing** for Next.js + Prisma/Drizzle apps.
+
+Send a PDF to people for online signing **without them logging in**, place the
+signature with a drag-drop designer, capture a simple electronic signature, and
+return a **Level-1 cryptographically-sealed PDF** — the final flattened bytes are
+SHA-256 hashed and an appended audit-certificate page records a hash-chained
+event log. Track who has / hasn't signed, version documents and resend, detect
+subjects added after a send (coverage), and surface stats.
+
+The package owns the engine; the host injects everything domain-specific through
+ports — exactly like `@firstlovecenter/milestone-grid`:
+
+```ts
+import { configureEsign } from "@josephomills/esign/server";
+import { createPrismaPersistence } from "@josephomills/esign/server/prisma"; // E1
+
+export const esign = configureEsign({
+  persistence: createPrismaPersistence(prisma),
+  storage,     // StoragePort  — wraps your R2/S3
+  notifier,    // NotifierPort — wraps your email/WhatsApp senders
+  auth,        // AuthPort
+  subjects,    // SubjectsPort — registerSubjectTypes([...]) for group targeting
+  hooks,       // optional — onRequestSigned → mark a milestone-grid requirement
+});
+```
+
+## Install
+
+```sh
+pnpm add @josephomills/esign
+```
+
+Then paste the model fragment into your `schema.prisma` and migrate:
+
+```prisma
+// node_modules/@josephomills/esign/prisma/esign-models.prisma
+```
+
+`subjectId` is host-managed (= your `profileId`) and intentionally has no foreign
+key — pass any opaque string. `scopeId` is optional (estate / country / none).
+
+## Status
+
+Built in phases (see the host app's plan). **E0** ships the contract: ports,
+DTOs, the token helper, the signing state machine, and the Prisma fragment.
+
+## License
+
+MIT © Joseph Mills

package/dist/ports-DtICqgEf.d.cts

@@ -0,0 +1,553 @@
+import { z } from 'zod';
+
+/**
+ * Lifecycle of a single signing request. PENDING/VIEWED are the only active
+ * states; SIGNED/DECLINED/EXPIRED/REVOKED are terminal. The submit handler is
+ * idempotent, so a no-op transition to the same state is always allowed.
+ */
+type EsignStatus = "PENDING" | "VIEWED" | "SIGNED" | "DECLINED" | "EXPIRED" | "REVOKED";
+declare const ESIGN_STATUSES: readonly EsignStatus[];
+/** Active (still-actionable) states — eligible for view/sign/decline. */
+declare const ACTIVE_STATUSES: readonly EsignStatus[];
+/** Terminal states — no further transitions. */
+declare const TERMINAL_STATUSES: readonly EsignStatus[];
+declare function isActive(status: EsignStatus): boolean;
+declare function isTerminal(status: EsignStatus): boolean;
+/** Whether `from → to` is a legal move (a same-state no-op counts as legal). */
+declare function canTransition(from: EsignStatus, to: EsignStatus): boolean;
+/** Throw `EsignError('CONFLICT')` on an illegal transition. */
+declare function assertTransition(from: EsignStatus, to: EsignStatus): void;
+
+type EsignChannel = "EMAIL" | "TELEGRAM" | "SMS" | "WHATSAPP";
+declare const ESIGN_CHANNELS: readonly EsignChannel[];
+declare const esignChannelSchema: z.ZodEnum<["EMAIL", "TELEGRAM", "SMS", "WHATSAPP"]>;
+interface Placement {
+    page: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+declare const placementSchema: z.ZodObject<{
+    page: z.ZodNumber;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    page: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, {
+    page: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+/** A resolved recipient — the only thing the fan-out needs. subjectId = the host's profileId. */
+interface Recipient {
+    name: string;
+    email?: string | null;
+    /** Phone for SMS (and WhatsApp when `whatsapp` is absent). */
+    phone?: string | null;
+    whatsapp?: string | null;
+    subjectType: string;
+    subjectId: string;
+    /** Snapshot of the targeted classification, persisted as SigningRequest.subjectGroup. */
+    group?: string | null;
+}
+/** A subject row rendered by the targeting picker. */
+interface SubjectSummary {
+    subjectType: string;
+    subjectId: string;
+    label: string;
+    sublabel?: string;
+    group?: string | null;
+    groupLabel?: string | null;
+    eligible: boolean;
+    ineligibleReason?: string;
+}
+/** A subject that could not be sent to at resolve time. */
+interface SkippedSubject {
+    subjectType: string;
+    subjectId: string;
+    label: string;
+    reason: string;
+}
+/** A declarative filter facet the picker renders as a control. */
+interface SubjectFilterField {
+    key: string;
+    label: string;
+    kind: "enum" | "boolean" | "text" | "scope";
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+type SubjectFilter = Record<string, string | boolean | string[] | undefined>;
+/**
+ * How a target is expressed. "all" sends to the whole group (optionally a
+ * classification + filters); "ids" sends to an explicit subset.
+ */
+type SubjectSelection = {
+    mode: "all";
+    type: string;
+    group?: string;
+    filter?: SubjectFilter;
+} | {
+    mode: "ids";
+    type: string;
+    subjectIds: string[];
+};
+declare const subjectSelectionSchema: z.ZodType<SubjectSelection>;
+/** Restrict a resend to a subset of the live group, diffed against existing requests. */
+type ResendPolicy = "all" | "outstanding" | "olderVersion" | "uncovered";
+/** Whether a green-check requires the current version or any version. */
+type VersionPolicy = "current" | "any";
+interface SigningDocumentDTO {
+    id: string;
+    scopeId: string | null;
+    documentType: string | null;
+    title: string;
+    audience: SubjectSelection | null;
+    currentVersionId: string | null;
+    createdById: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SigningDocumentVersionDTO {
+    id: string;
+    documentId: string;
+    version: number;
+    sourceObjectKey: string;
+    sourceSha256: string;
+    placement: Placement;
+    changeNote: string | null;
+    createdById: string | null;
+    createdAt: string;
+}
+interface SigningCampaignDTO {
+    id: string;
+    documentId: string;
+    documentVersionId: string;
+    scopeId: string | null;
+    note: string | null;
+    emailReceipt: boolean;
+    targeting: SubjectSelection;
+    expiresAt: string;
+    createdById: string | null;
+    createdAt: string;
+}
+interface SigningRequestDTO {
+    id: string;
+    campaignId: string;
+    documentId: string;
+    documentVersionId: string;
+    scopeId: string | null;
+    subjectType: string;
+    subjectId: string;
+    subjectGroup: string | null;
+    recipientName: string;
+    recipientEmail: string | null;
+    recipientWhatsapp: string | null;
+    channels: EsignChannel[];
+    status: EsignStatus;
+    viewedAt: string | null;
+    signedAt: string | null;
+    declinedAt: string | null;
+    expiresAt: string;
+    revokedAt: string | null;
+    sealedObjectKey: string | null;
+    sealedSha256: string | null;
+    createdAt: string;
+}
+interface SigningAuditEventDTO {
+    id: string;
+    requestId: string;
+    seq: number;
+    type: string;
+    payload: unknown;
+    prevHash: string | null;
+    hash: string;
+    occurredAt: string;
+}
+type SubjectSigningState = "NONE" | "PENDING" | "VIEWED" | "SIGNED" | "DECLINED" | "NEEDS_RESIGN";
+interface SubjectSigningStatus {
+    state: SubjectSigningState;
+    signedAt: string | null;
+    signedVersion: number | null;
+    requestId: string | null;
+    sealedObjectKey: string | null;
+}
+type StatusCountMap = Record<EsignStatus, number>;
+interface OutstandingRequest {
+    id: string;
+    campaignId: string;
+    documentId: string;
+    subjectType: string;
+    subjectId: string;
+    recipientName: string;
+    channels: EsignChannel[];
+    status: Extract<EsignStatus, "PENDING" | "VIEWED">;
+    viewedAt: string | null;
+    createdAt: string;
+    expiresAt: string;
+}
+interface GroupBreakdown {
+    group: string | null;
+    counts: StatusCountMap;
+    total: number;
+}
+interface CampaignStatsRow {
+    campaignId: string;
+    counts: StatusCountMap;
+    total: number;
+    viewedNotSigned: number;
+    completionRate: number;
+    avgTimeToSignMs: number | null;
+    byGroup: GroupBreakdown[];
+    outstanding: OutstandingRequest[];
+}
+interface DocumentStatsRow {
+    documentId: string;
+    counts: StatusCountMap;
+    total: number;
+    completionRate: number;
+    byGroup: GroupBreakdown[];
+    bySubjectType: {
+        subjectType: string;
+        counts: StatusCountMap;
+        total: number;
+    }[];
+}
+interface ScopeStatsRow {
+    campaignsSent: number;
+    requestsSent: number;
+    counts: StatusCountMap;
+    completionRate: number;
+    bySubjectType: {
+        subjectType: string;
+        counts: StatusCountMap;
+        total: number;
+    }[];
+    oldestOutstanding: OutstandingRequest[];
+}
+interface StatsRange {
+    from?: Date;
+    to?: Date;
+}
+/** documentCoverage() result — re-derived from the live group every call. */
+interface CoverageReport {
+    documentId: string;
+    totalNow: number;
+    signed: number;
+    outstanding: number;
+    needsResign: number;
+    uncovered: SubjectSummary[];
+    departed: {
+        subjectType: string;
+        subjectId: string;
+    }[];
+}
+/** A drawn or typed signature, as a PNG data URL produced by the signer UI. */
+declare const submitSignatureSchema: z.ZodObject<{
+    signaturePng: z.ZodString;
+    signerName: z.ZodString;
+    consent: z.ZodLiteral<true>;
+}, "strict", z.ZodTypeAny, {
+    signaturePng: string;
+    signerName: string;
+    consent: true;
+}, {
+    signaturePng: string;
+    signerName: string;
+    consent: true;
+}>;
+type SubmitSignatureInput = z.infer<typeof submitSignatureSchema>;
+declare const declineSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    reason?: string | undefined;
+}, {
+    reason?: string | undefined;
+}>;
+type DeclineInput = z.infer<typeof declineSchema>;
+
+interface AuthPort<S> {
+    /** Resolve the request's principal, or throw EsignError('UNAUTHENTICATED'). */
+    requireAuth(req: Request): Promise<S>;
+    /** True when the scope may manage documents / send campaigns. */
+    isAdmin(scope: S): boolean;
+    /** Opaque user id used to attribute documents, versions, campaigns. */
+    userId(scope: S): string;
+    /** Optional opaque scope key (estate id / country id) for row scoping. */
+    scopeId?(scope: S): string | null;
+}
+interface StoragePort {
+    /** Short-lived signed PUT URL for the browser to upload a source PDF. */
+    presignPut(input: {
+        objectKey: string;
+        contentType: string;
+        ttlS: number;
+    }): Promise<{
+        uploadUrl: string;
+    }>;
+    /** Read an object's bytes (source PDF for sealing / serving). null = 404. */
+    get(objectKey: string): Promise<{
+        bytes: Uint8Array;
+        contentType?: string;
+    } | null>;
+    /** Write bytes server-side (the sealed PDF). */
+    put(input: {
+        objectKey: string;
+        bytes: Uint8Array;
+        contentType: string;
+    }): Promise<void>;
+    /** Best-effort delete. */
+    delete(objectKey: string): Promise<void>;
+    /** HMAC-stamp a fresh source-upload key so a presigned key can't be reused elsewhere. */
+    stampKey(parts: {
+        scopeId?: string | null;
+        documentId: string;
+        contentType: string;
+    }): string;
+    /** Verify a stamped key matches the expected document. */
+    verifyKey(stampedKey: string, parts: {
+        documentId: string;
+    }): boolean;
+    /** Deterministic key for a sealed request PDF. */
+    sealedKey(parts: {
+        scopeId?: string | null;
+        campaignId: string;
+        requestId: string;
+    }): string;
+    /** Optional upper bound for an uploaded source PDF (bytes). */
+    maxBytes?(): number;
+}
+interface NotifierAttachment {
+    filename: string;
+    content: Uint8Array;
+    contentType: string;
+}
+interface NotifierPort {
+    send(input: {
+        channel: EsignChannel;
+        recipient: string;
+        subject: string;
+        body: string;
+        actionUrl?: string;
+        idempotencyKey: string;
+        attachments?: NotifierAttachment[];
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Channels with live credentials — the targeting UI offers only these. */
+    configuredChannels(): EsignChannel[];
+}
+interface SubjectTypeDescriptor {
+    type: string;
+    label: string;
+    pluralLabel?: string;
+    /** The primary classification facet (e.g. missionary support tier, employment type). */
+    groupField?: SubjectFilterField;
+    /** Secondary facets rendered as filter controls. */
+    filterFields?: SubjectFilterField[];
+    /** Paginated, channel-aware enumeration for the picker. */
+    listSubjects(args: {
+        scopeId?: string | null;
+        group?: string;
+        filter?: SubjectFilter;
+        channels?: EsignChannel[];
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        subjects: SubjectSummary[];
+        nextCursor?: string;
+        total?: number;
+    }>;
+    /** Lean id-only enumeration for coverage diffs. */
+    listSubjectIds(args: {
+        scopeId?: string | null;
+        selection: SubjectSelection;
+    }): Promise<string[]>;
+    /** Counts for the review step without materializing recipients. */
+    countSubjects(args: {
+        scopeId?: string | null;
+        selection: SubjectSelection;
+        channels?: EsignChannel[];
+    }): Promise<{
+        total: number;
+        eligible: number;
+        ineligible: number;
+    }>;
+    /** Authoritative send-time resolution: who to send to, and who was skipped. */
+    resolveRecipients(args: {
+        scopeId?: string | null;
+        selection: SubjectSelection;
+        channels?: EsignChannel[];
+    }): Promise<{
+        recipients: Recipient[];
+        skipped: SkippedSubject[];
+    }>;
+}
+interface SubjectsPort {
+    types: SubjectTypeDescriptor[];
+    get(type: string): SubjectTypeDescriptor | undefined;
+}
+interface NewRequestRow {
+    /** Minted by the engine (createRequests returns void), so the fan-out knows it. */
+    id: string;
+    campaignId: string;
+    documentId: string;
+    documentVersionId: string;
+    scopeId: string | null;
+    subjectType: string;
+    subjectId: string;
+    subjectGroup: string | null;
+    recipientName: string;
+    recipientEmail: string | null;
+    recipientWhatsapp: string | null;
+    channels: EsignChannel[];
+    tokenHash: string;
+    expiresAt: Date;
+}
+interface NewAuditEventRow {
+    requestId: string;
+    seq: number;
+    type: string;
+    payload: unknown;
+    prevHash: string | null;
+    hash: string;
+}
+interface RequestSummary {
+    subjectId: string;
+    status: EsignStatus;
+    version: number;
+    signedAt: string | null;
+}
+interface PersistencePort {
+    createDocument(input: {
+        scopeId: string | null;
+        documentType: string | null;
+        title: string;
+        audience: SubjectSelection | null;
+        createdById: string | null;
+    }): Promise<SigningDocumentDTO>;
+    getDocument(id: string): Promise<SigningDocumentDTO | null>;
+    updateDocument(id: string, patch: Partial<Pick<SigningDocumentDTO, "title" | "audience" | "currentVersionId">>): Promise<SigningDocumentDTO>;
+    listDocuments(opts: {
+        scopeId?: string | null;
+        documentType?: string;
+    }): Promise<SigningDocumentDTO[]>;
+    createVersion(input: {
+        documentId: string;
+        version: number;
+        sourceObjectKey: string;
+        sourceSha256: string;
+        placement: Placement;
+        changeNote: string | null;
+        createdById: string | null;
+    }): Promise<SigningDocumentVersionDTO>;
+    getVersion(id: string): Promise<SigningDocumentVersionDTO | null>;
+    listVersions(documentId: string): Promise<SigningDocumentVersionDTO[]>;
+    latestVersion(documentId: string): Promise<SigningDocumentVersionDTO | null>;
+    createCampaign(input: {
+        documentId: string;
+        documentVersionId: string;
+        scopeId: string | null;
+        note: string | null;
+        emailReceipt: boolean;
+        targeting: SubjectSelection;
+        expiresAt: Date;
+        createdById: string | null;
+    }): Promise<SigningCampaignDTO>;
+    getCampaign(id: string): Promise<SigningCampaignDTO | null>;
+    listCampaigns(documentId: string): Promise<SigningCampaignDTO[]>;
+    createRequests(rows: NewRequestRow[]): Promise<void>;
+    getRequest(id: string): Promise<SigningRequestDTO | null>;
+    findRequestByTokenHash(tokenHash: string): Promise<SigningRequestDTO | null>;
+    updateRequest(id: string, patch: Partial<{
+        status: EsignStatus;
+        viewedAt: Date;
+        signedAt: Date;
+        declinedAt: Date;
+        declineReason: string;
+        revokedAt: Date;
+        signerName: string;
+        signerIp: string;
+        signerUserAgent: string;
+        sealedObjectKey: string;
+        sealedSha256: string;
+        finalAuditHash: string;
+    }>): Promise<SigningRequestDTO>;
+    listRequests(opts: {
+        campaignId?: string;
+        documentId?: string;
+        subjectType?: string;
+        subjectId?: string;
+    }): Promise<SigningRequestDTO[]>;
+    /** Latest request per subject for a document — powers coverage + version-aware status. */
+    requestSummaryBySubject(documentId: string): Promise<RequestSummary[]>;
+    appendAuditEvent(row: NewAuditEventRow): Promise<SigningAuditEventDTO>;
+    listAuditEvents(requestId: string): Promise<SigningAuditEventDTO[]>;
+    lastAuditHash(requestId: string): Promise<{
+        seq: number;
+        hash: string;
+    } | null>;
+    subjectSigningStatus(args: {
+        subjectType: string;
+        subjectId: string;
+        documentId?: string;
+        documentType?: string;
+        versionPolicy: VersionPolicy;
+    }): Promise<SubjectSigningStatus>;
+    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[]>;
+}
+interface HooksPort {
+    onRequestViewed?(req: SigningRequestDTO): Promise<void> | void;
+    onRequestSigned?(event: {
+        subjectType: string;
+        subjectId: string;
+        documentId: string;
+        documentType: string | null;
+        requestId: string;
+        sealedObjectKey: string;
+        signedAt: string;
+    }): Promise<void> | void;
+    onRequestDeclined?(req: SigningRequestDTO): Promise<void> | void;
+}
+interface Clock {
+    now(): Date;
+}
+interface EsignConfig<S> {
+    persistence: PersistencePort;
+    storage: StoragePort;
+    notifier: NotifierPort;
+    auth: AuthPort<S>;
+    subjects: SubjectsPort;
+    hooks?: HooksPort;
+    clock?: Clock;
+    /** Absolute origin used to build the `/sign/<token>` link, e.g. https://estates.app. */
+    baseUrl: string;
+    /** Base path the host mounts the package routes under. Default `/api/esign`. */
+    routeBasePath?: string;
+    /** TTL (seconds) for presigned source-PDF uploads. Default 900. */
+    presignTtlS?: number;
+    /** Default signing-link lifetime in days. Default 30. */
+    defaultExpiryDays?: number;
+}
+
+export { submitSignatureSchema as $, ACTIVE_STATUSES as A, type StatusCountMap as B, type Clock as C, type DocumentStatsRow as D, type EsignChannel as E, type SubjectFilter as F, type GroupBreakdown as G, type HooksPort as H, type SubjectFilterField as I, type SubjectSigningState as J, type SubjectSummary as K, type SubmitSignatureInput as L, assertTransition as M, type NotifierPort as N, type OutstandingRequest as O, type PersistencePort as P, canTransition as Q, type ResendPolicy as R, type SubjectSelection as S, TERMINAL_STATUSES as T, declineSchema as U, type VersionPolicy as V, esignChannelSchema as W, isActive as X, isTerminal as Y, placementSchema as Z, subjectSelectionSchema as _, type SubjectsPort as a, type SkippedSubject as b, type Placement as c, type StoragePort as d, type SigningDocumentVersionDTO as e, type SigningDocumentDTO as f, type SigningRequestDTO as g, type EsignConfig as h, type SubjectSigningStatus as i, type CoverageReport as j, type CampaignStatsRow as k, type StatsRange as l, type ScopeStatsRow as m, type SubjectTypeDescriptor as n, type AuthPort as o, type DeclineInput as p, ESIGN_CHANNELS as q, ESIGN_STATUSES as r, type EsignStatus as s, type NewAuditEventRow as t, type NewRequestRow as u, type NotifierAttachment as v, type Recipient as w, type RequestSummary as x, type SigningAuditEventDTO as y, type SigningCampaignDTO as z };