@happyvertical/signatures 0.80.0

package/AGENT.md

@@ -0,0 +1,49 @@
+# @happyvertical/signatures
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Provider-neutral e-signature workflows with a BoldSign adapter
+
+## Package Map
+- Package: `@happyvertical/signatures`
+- Hierarchy path: `@happyvertical/sdk > packages > signatures`
+- Workspace position: `25 of 32` local packages
+- Internal dependencies: none
+- Internal dependents: none
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/signatures build
+pnpm --filter @happyvertical/signatures test
+pnpm --filter @happyvertical/signatures typecheck
+pnpm --filter @happyvertical/signatures clean
+```
+
+## Agent Correction Loops
+- If Vite or TypeScript reports missing packages, run `pnpm install` at the repo root and rerun `pnpm --filter @happyvertical/signatures build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/signatures clean` followed by `pnpm --filter @happyvertical/signatures build` and `pnpm --filter @happyvertical/signatures test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Provider-neutral e-signature workflows with a BoldSign adapter
+- Implements: BoldSign
+- Requires: none
+- Stability: experimental (Marked as preview or experimental in package guidance.)
+<!-- END AGENT:GENERATED -->
+
+
+## Package Status
+
+Experimental while the first downstream agreement workflow validates the provider-neutral contract.
+
+## Adapters
+
+- BoldSign (`type: 'boldsign'`) uses the regional v1 document API, HMAC-verified webhooks, and PDF artifact endpoints.
+
+## Security Boundaries
+
+- Construct one adapter per tenant credential and webhook secret set.
+- Preserve the raw webhook request body until HMAC verification completes.
+- Persist provider event IDs and creation idempotency keys under durable unique constraints; BoldSign does not advertise provider-enforced send idempotency.
+- Download signed documents and audit trails only after the normalized request reaches `completed`, consume each single-use stream into immutable storage, then await and persist its SHA-256 digest.

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+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,129 @@
+# @happyvertical/signatures
+
+Provider-neutral e-signature request, lifecycle, verified-webhook, and execution-evidence contracts. BoldSign is the first adapter.
+
+## Status
+
+This package is experimental while the first downstream agreement workflow validates the provider-neutral contract.
+
+## Install
+
+```bash
+pnpm add @happyvertical/signatures
+```
+
+## BoldSign quick start
+
+Create one adapter per tenant credential and webhook signing secret. HappyVertical deployments use BoldSign's Canadian region by default.
+
+```typescript
+import { createSignatureProvider } from '@happyvertical/signatures';
+
+const signatures = await createSignatureProvider({
+  type: 'boldsign',
+  tenantId: 'tenant_123',
+  apiKey: process.env.BOLDSIGN_API_KEY!,
+  webhookSecrets: [process.env.BOLDSIGN_WEBHOOK_SECRET!],
+  region: 'ca',
+});
+
+const request = await signatures.createRequest({
+  tenantId: 'tenant_123',
+  idempotencyKey: 'referral-agreement:version_456',
+  title: 'Referral Agreement',
+  documents: [
+    {
+      name: 'referral-agreement.pdf',
+      mediaType: 'application/pdf',
+      data: generatedPdf,
+    },
+  ],
+  signers: [
+    {
+      name: 'Alex Example',
+      email: 'alex@example.com',
+      authentication: { method: 'email_otp' },
+      fields: [
+        {
+          id: 'referrer_signature',
+          type: 'signature',
+          page: 3,
+          bounds: { x: 72, y: 620, width: 180, height: 36 },
+        },
+      ],
+    },
+  ],
+  expiresInDays: 30,
+});
+```
+
+## Adapters
+
+- BoldSign (`type: 'boldsign'`) uses the regional v1 document API, HMAC-verified webhooks, and PDF artifact endpoints.
+
+The package sends JSON with base64 documents to BoldSign's asynchronous `POST /v1/document/send` API. A successful create response means BoldSign accepted processing; the verified `Sent` or `SendFailed` webhook is authoritative for the next transition.
+
+## Webhooks and replay protection
+
+Pass the exact raw UTF-8 request body and `X-BoldSign-Signature` header. Do not parse and re-serialize the body before verification.
+
+```typescript
+const event = signatures.parseWebhook({
+  payload: rawBody,
+  signature: request.headers.get('x-boldsign-signature')!,
+});
+```
+
+The adapter verifies BoldSign's HMAC-SHA256 signature using constant-time comparison and rejects timestamps outside the configured tolerance (five minutes by default). It also requires the signed payload's `hvTenantId` metadata to match the adapter tenant. Persist `event.id` under a unique constraint before applying an event; the SDK intentionally does not pretend an in-memory replay cache is durable.
+
+Configure the webhook for `Sent`, `Signed`, `Completed`, `Viewed`, `Declined`, `Revoked`, `Expired`, `DeliveryFailed`, and `SendFailed`. Other signed event types are rejected until the provider-neutral contract defines their semantics.
+
+BoldSign sends an unsigned `Verification` callback while a webhook endpoint is configured. Acknowledge that control request before calling `parseWebhook`; do not treat it as a document event.
+
+## Idempotency and ambiguous failures
+
+`createRequest` requires an idempotency key and stores it in BoldSign metadata as `hvIdempotencyKey`. BoldSign's public send-document contract does not advertise an atomic idempotency header, so `capabilities.providerEnforcedIdempotency` is `false`. The durable application layer must claim the tenant/key before sending and persist the returned document ID. When `SignatureProviderError.requestMayHaveSucceeded` is true, reconcile rather than blindly sending a duplicate agreement.
+
+## Execution evidence
+
+Artifacts are available only after the normalized request status is `completed`:
+
+```typescript
+const signed = await signatures.downloadArtifact({
+  tenantId: 'tenant_123',
+  requestId: request.id,
+  kind: 'signed_document',
+});
+
+const audit = await signatures.downloadArtifact({
+  tenantId: 'tenant_123',
+  requestId: request.id,
+  kind: 'audit_trail',
+});
+
+await immutableAssets.put(signed.filename, signed.stream);
+const signedSha256 = await signed.sha256;
+```
+
+Each artifact exposes a single-use byte stream and a SHA-256 promise that resolves after that stream is consumed. Persist the stream to immutable/versioned storage, then await and record the digest together with the provider request ID, event ID, tenant, signer identity, retrieval time, and agreement version. The provider is a retrieval source, not the system of record for an executed agreement.
+
+## Operations and security
+
+- Keep API keys, OAuth tokens, access codes, and webhook secrets in the SDK/SMRT secret store; never put them in agreement metadata or logs.
+- Scope an adapter instance to exactly one tenant. Reads, mutations, downloads, and webhooks all enforce that tenant binding.
+- For secret rotation, configure both valid webhook secrets temporarily. BoldSign may also include both `s0` and `s1` signatures in its header.
+- `cancelRequest` requires a reason. `extendExpiry` verifies tenant ownership first and only accepts a future date.
+- API credentials may use either `X-API-KEY` or an OAuth bearer token, never both.
+- Use the sandbox for contract testing, but do not treat its watermarked PDFs as legal artifacts.
+
+## Provider references
+
+- [Regional API base URLs](https://developers.boldsign.com/api-overview/versioning/)
+- [Send document](https://developers.boldsign.com/documents/send-document/)
+- [Document details and status](https://developers.boldsign.com/documents/document-details-and-status)
+- [Revoke document](https://developers.boldsign.com/documents/revoke-document/)
+- [Extend document expiry](https://developers.boldsign.com/documents/extend-document-expiry/)
+- [Verify webhook events](https://developers.boldsign.com/webhooks/verify-webhook-events/)
+- [Webhook event metadata](https://developers.boldsign.com/webhooks/event-metadata/)
+- [Download signed document](https://developers.boldsign.com/documents/download-document/)
+- [Download audit trail](https://developers.boldsign.com/documents/download-audit-trail/)

package/dist/adapters/boldsign.d.ts

@@ -0,0 +1,48 @@
+import { SignatureFetch } from '../shared.js';
+import { CancelSignatureRequestInput, CreateSignatureRequestInput, DownloadSignatureArtifactInput, ExtendSignatureRequestExpiryInput, ParseSignatureWebhookInput, SignatureArtifact, SignatureProvider, SignatureProviderCapabilities, SignatureRequest, SignatureRequestReference, SignatureWebhookEvent } from '../types.js';
+export declare const BOLDSIGN_PROVIDER_ID = "boldsign";
+export declare const BOLDSIGN_TENANT_METADATA_KEY = "hvTenantId";
+export declare const BOLDSIGN_IDEMPOTENCY_METADATA_KEY = "hvIdempotencyKey";
+export type BoldSignRegion = 'us' | 'eu' | 'ca' | 'au';
+export interface BoldSignAdapterOptions {
+    /** Bind one adapter and its credential/webhook secret to one tenant. */
+    tenantId: string;
+    apiKey?: string;
+    accessToken?: string;
+    /** Defaults to Canada for HappyVertical's first deployment. */
+    region?: BoldSignRegion;
+    apiBaseUrl?: string;
+    webhookSecrets?: string | readonly string[];
+    webhookToleranceSeconds?: number;
+    fetch?: SignatureFetch;
+    /** Testable wall clock used for replay checks and evidence timestamps. */
+    now?: () => Date;
+}
+export declare class BoldSignAdapter implements SignatureProvider {
+    readonly capabilities: SignatureProviderCapabilities;
+    private readonly tenantId;
+    private readonly apiKey?;
+    private readonly accessToken?;
+    private readonly apiBaseUrl;
+    private readonly webhookSecrets;
+    private readonly webhookToleranceSeconds;
+    private readonly fetch;
+    private readonly now;
+    constructor(options: BoldSignAdapterOptions);
+    createRequest(input: CreateSignatureRequestInput): Promise<SignatureRequest>;
+    getRequest(input: SignatureRequestReference): Promise<SignatureRequest>;
+    cancelRequest(input: CancelSignatureRequestInput): Promise<SignatureRequest>;
+    extendExpiry(input: ExtendSignatureRequestExpiryInput): Promise<SignatureRequest>;
+    downloadArtifact(input: DownloadSignatureArtifactInput): Promise<SignatureArtifact>;
+    parseWebhook(input: ParseSignatureWebhookInput): SignatureWebhookEvent;
+    private assertTenant;
+    private assertProviderTenant;
+    private request;
+}
+export interface VerifyBoldSignWebhookSignatureInput extends ParseSignatureWebhookInput {
+    secrets: string | readonly string[];
+    toleranceSeconds?: number;
+    now?: Date;
+}
+export declare function verifyBoldSignWebhookSignature(input: VerifyBoldSignWebhookSignatureInput): void;
+//# sourceMappingURL=boldsign.d.ts.map

package/dist/adapters/boldsign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boldsign.d.ts","sourceRoot":"","sources":["../../src/adapters/boldsign.ts"],"names":[],"mappings":"AAUA,OAAO,EAWL,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,8BAA8B,EAC9B,iCAAiC,EACjC,0BAA0B,EAC1B,iBAAiB,EAIjB,iBAAiB,EACjB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,EAKzB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAC/C,eAAO,MAAM,4BAA4B,eAAe,CAAC;AACzD,eAAO,MAAM,iCAAiC,qBAAqB,CAAC;AAsBpE,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AASvD,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC5C,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAUD,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,QAAQ,CAAC,YAAY,EAAE,6BAA6B,CAAC;IAErD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoB;IACnD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;gBAErB,OAAO,EAAE,sBAAsB;IAsErC,aAAa,CACjB,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,gBAAgB,CAAC;IAuDtB,UAAU,CACd,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,gBAAgB,CAAC;IAgBtB,aAAa,CACjB,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,gBAAgB,CAAC;IA2BtB,YAAY,CAChB,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,gBAAgB,CAAC;IAsDtB,gBAAgB,CACpB,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAAC,iBAAiB,CAAC;IA2C7B,YAAY,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB;IAmFtE,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,oBAAoB;YAWd,OAAO;CA+EtB;AAED,MAAM,WAAW,mCACf,SAAQ,0BAA0B;IAClC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,mCAAmC,GACzC,IAAI,CAgGN"}