# Hanzo Sign ## Overview The Open Source DocuSign Alternative. ## Tech Stack - **Language**: TypeScript/JavaScript ## Build & Run ```bash npm install && npm run build npm test ``` ## Structure ``` sign/ AGENTS.md ARCHITECTURE.md CLA.md CODE_OF_CONDUCT.md CODE_STYLE.md CONTRIBUTING.md LICENSE LLM.md MANIFEST.md README.md SIGNING.md WRITING_STYLE.md apps/ assets/ build.log ``` ## Key Files - `README.md` -- Project documentation - `package.json` -- Dependencies and scripts ## Routes: everything is /v1 Every route is served and called under /v1; `npm run lint:paths`, the first step of the gate, fails on any other API prefix. The mount is `apps/remix/server/router.ts`: | path | what | |---|---| | `/v1/rest/*` | resource API, the ts-rest contract (`packages/api/v1`), spec at `/v1/rest/openapi.json` | | `/v1/rpc/*` | operation API, ZAP over JSON-over-HTTP (`server/zap/http-api.ts`), spec at `/v1/rpc/openapi.json` | | `/v1/auth/*` | session auth (`packages/auth/server`) | | `/v1/files/*`, `/v1/ai/*`, `/v1/jobs/*` | uploads and downloads, AI detection, the job runner | | `/v1/health`, `/v1/limits`, `/v1/locale`, `/v1/theme`, … | RR7 resource routes (`app/routes/v1+`) | | `/auth/callback` | Hanzo IAM sign-in return | | `/zap` | the browser's ZAP WebSocket | The two REST surfaces are named for what they are, not versioned, so neither shadows the other. `/auth/callback` is the one browser callback path IAM derives for every host in universe `charts/app/values/hanzo/iam-provision.yaml`, so the Hanzo sign-in needs no per-app redirect_uri; other OAuth providers return to `/v1/auth/callback/`. ## Inside a transaction, only `tx` Base SQLite serves one write connection. `prisma.$transaction(async (tx) => …)` holds it for as long as the callback runs, so a call in the callback that reaches the global Prisma client queues behind a lock that call is itself blocking. It waits out the busy timeout and the transaction dies with `P2028 Transaction already closed` — at runtime, on a green build. This is what stopped every document creation at 0.1.4. Mail and other calls out of the process do not deadlock, but they hold that one connection open across the network: every other write waits on a mail server, and a slow send reaches the same timeout by a longer road. Jobs, webhooks, notifications and mail are side effects of committed state: return what they need from the callback and fire them after the commit. A failed send therefore no longer rolls back the record it announces — the record stands, and the send is reported where it happens. Where a transaction wrapped one write and a send, it was doing nothing: keep the order, drop the transaction, and a single write is still atomic on its own. `packages/eslint-config/transaction.cjs` holds the rule. Two callers read it: the shared config, so an editor says it while you type, and `npm run lint:tx`, which runs it alone over every package and app in seconds and is the first thing the CI gate does. `npm test -w @hanzo/esign-eslint-config` proves the rule still fires, so it cannot rot into a no-op. It asks three questions of a callback: is the client called `tx`, does the callback name a client that is not `tx`, and does it await a call it did not hand `tx`. The third is the general one — handing `tx` on is how a call says it joins the transaction, so awaiting one that never mentions it is awaiting the world outside while holding the door. That covers jobs, webhooks, mail and any other I/O under one question, and it sees through a helper the earlier name-matching could not: what is checked is the call site's shape, not its callee's name. ## In-process cloud fold (HIP-0106, task #100) The core server-side e-signature flow is ALSO shipped as a self-contained, ESM-free **goja bundle** so the unified `hanzoai/cloud` binary runs it in-process (TS-on-`dop251/goja` + Hanzo Base/SQLite) — no Next.js/Remix, no Prisma, no Postgres. This replaces the standalone esign pod. - `goja/bundle.js` — the ported domain: documents, recipients, fields, the signing flow/state machine, audit trail and completion. Exposes `globalThis.handle({route,method,params,body,tenant})`. It carries LOGIC only. - `embed.go` / `go.mod` — a std-lib-only Go module (`github.com/hanzoai/esign`, `Bundle()`) that cloud imports to `go:embed` the bundle. - `goja/README.md` — the host contract. It runs on the reusable `hanzoai/cloud/clients/gojabase` RW-Base host: persistence (`globalThis.__db`, per-tenant SQLite, one txn per dispatch) + `__newId`/`__now` come from gojabase; the PDF/PKI seal primitives (`globalThis.__pdf`: pdfcpu render + x509/PKCS#7 sign) are injected by `clients/sign` via gojabase `Config.HostFns`. Only the crypto/PDF primitive is Go; the flow + seal orchestration stay here in JS. Edit a server-side rule? Mirror it in `goja/bundle.js` (the cloud path) as well as the Remix/tRPC handlers. ## Several recipients, and what a send needs in production - cmdk 1 writes `data-disabled="false"` on every enabled item. `CommandItem` (`packages/ui/primitives/command.tsx`) disables only on `data-[disabled=true]`; matching the bare attribute made every combobox item ignore the mouse, so the fields step could not select a second recipient and the send refused for want of their signature field. - The recipients form learns server ids only on a step change. The editor provider keeps them by the row's `formId`, sent as `clientId` and echoed back (`envelope.recipient.set`), so a recipient created by one autosave is updated, not deleted and recreated, by the next. `envelope-recipients.spec.ts` ("several recipients in one visit") holds both. - A recipient has no account. The `/zap` socket opens without a session for the app's own pages as an anonymous connection (`mint.ts`), and the dispatcher lets it reach only `publicRoutes` (`zap/server/public-routes.ts`: the routes tRPC served as public procedures, each authorised by the token it carries; their handlers take `ZapConnectionContext`). Before this the socket refused them and no recipient without an account could sign a field. `/v1/rpc` still needs a token. `packages/trpc/__tests__/anonymous.test.ts` holds it. - Sealing a completed document signs it with the certificate the local signer reads: `NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS` (base64 p12) and `NEXT_PRIVATE_SIGNING_PASSPHRASE`, from KMS `hanzo/sign@prod`. The image has none; without them every completion fails at the seal. An unset `NEXT_PRIVATE_SIGNING_TRANSPORT` is `local` for the signer and for `/v1/health` alike. - Mail goes through notify (`packages/email/transports/notify.ts`): the sender is the org's credential (no-reply@send.hanzo.ai), and notify carries no attachment and no reply-to. The completed email reaches every recipient with its download link (`/sign//complete`), not the PDF attached. ## The look: hanzo.ai's - Tokens are `packages/ui/styles/theme.css`, values from @hanzo/ui DESIGN.md: dark is a #000 page, #0a0a0a surfaces, #171717 raised, #ededf1 ink, hairlines at white 10% (a control's edge 15%); light is white, #0a0a0a ink, black 10% and 15%. Every value is an opaque `H S% L%` triplet, because the Tailwind colours are `hsl(var(--x))` and an alpha inside the variable breaks every `/50` modifier. Monochrome: the recipient tones and the destructive red are the only colour, and both are functional. - Type is Zen and Zen Mono from `@hanzo/font` (`app.css` imports `@hanzo/font/css`), with Zen's weight ladder in `packages/tailwind-config` (normal 497, medium 606, semibold 680, bold 760). The server-side PDF renderers keep their own Inter files in `public/fonts`. - Buttons are pills (`packages/ui/primitives/button.tsx`); the primary is the ink colour, white on black or black on white. A tall option card built from a Button says `rounded-2xl` itself. - The brand is the wordmark alone, as text: `BrandingLogo` renders `NEXT_PUBLIC_APP_NAME` (default "Hanzo eSign", `components/branding/brand.ts`) and is sized by the caller's `text-*` class, so no tenant name is clipped. There is no mark. Emails and the sealed PDF's certificate and audit log draw `public/static/logo.png` (copy in `packages/assets/static`), a raster of the same wordmark in Zen; redraw it if the default name changes. - `PublicHeader` (in `app-header.tsx`) and `AppFooter` frame every page a visitor without a session sees: sign-in and the other unauthenticated pages, a recipient's result pages (`/sign//complete`, expired, rejected, waiting) and public profiles. The signing and direct-template pages keep their own bar and no footer. - Theme: a stored choice (`/v1/theme`) wins; with none, remix-themes follows the device, dark unless it asks for light, as hanzo.ai does. - Prettier's Tailwind plugin finds the hoisted Tailwind 4 and fails on this tree; format with a config that sets `tailwindConfig` to `apps/remix/tailwind.config.ts`. ## One way in: an IAM application's token People sign in; the API is for services. A call without a session carries a Hanzo IAM ACCESS token (`tokenType` access-token, never a sign-in's id_token) that an APPLICATION minted for this app: signed by a key in hanzo.id's JWKS, issued by hanzo.id, `aud` = `IAM_CLIENT_ID` (RFC 8707 `resource`), unexpired (`server-only/iam/token.ts`, `verifyIamToken`). `public-api/get-bearer.ts` is the one resolver behind `/v1/rpc` (mint.ts), `/v1/rest` and the download routes, and this server mints no tokens of its own. `IAM_APP_TEAMS` (`:`, comma-separated) is the whole grant: the token's `azp` must be listed, and the application acts for exactly that one team, as its organisation owner, audited under its IAM subject (`admin/hanzo-cloud`). Since `resource` lets any authenticated client mint `aud` = this app, the audience proves nothing alone; the list does. Empty is nobody. The other way round, this app calls the Hanzo API as itself: `Machine` mints its client_credentials token for the Hanzo API (`resource` https://api.hanzo.ai), never for itself, and refuses any bearer its own client minted. notify takes it, and so does a webhook whose team and exact URL `HANZO_WEBHOOKS` lists together (`=`; `webhooks/send.ts`, the one sender for sends and resends, following no redirect), so the receiver verifies eSign against hanzo.id and holds no secret; what it answers is not kept for the team to read. A webhook anywhere else is sent no identity, only its own secret: a team chooses where its webhook points. Zapier, which could only carry an API token, is gone. An API token is still read in exactly one place: embed authoring signs its presign token with one (`embedding-presign/api-token.ts`). ## Shipping and what is still broken - The pin is universe `charts/app/values/hanzo/sign.yaml` (image `oci.hanzo.ai/hanzoai/esign:@`; CI publishes `ghcr.io/hanzoai/esign:` and `sha--amd64` through the door). CD syncs `hanzo-sign` only by hand: `POST /v1/platform/apps/sign/sync?org=hanzo` as admin. The signing certificate is the KMSSecret `sign-env-kms-sync` (KMS hanzo `/sign@prod`), read by the operator under its grant in `kms-grants.yaml`. - The investor SAFE template is built from hanzoai/deck `safe/`; the intake that sends it is hanzo-inc/cloud `POST /v1/marketing/leads` (program `investor`), calling `/v1/rpc` as cloud's own IAM application, which `IAM_APP_TEAMS` maps to the team that holds the template. The team's webhook posts back to `/v1/marketing/leads/esign` as this app's IAM identity. - Broken, found and not fixed: deleting an account fails ("Deleted account service account not found"): the SQLite `0_init` never created the deleted-account service user the delete hands envelopes to. `/admin/documents/` answers 500. On `/v1/rpc` the admin routes' operationIds (`admin.documentDelete`) are not the handler names (`admin.document.delete`), so they 404; the socket reaches them.