# HE Signs 0.7 — capabilities and activation

This release is implemented and tested locally. The intended public domain is `hesigns.homeequal.ai`. Source, customer data, infrastructure and DNS remain local under the owner's instruction. Google Workspace is the first company sign-in provider. No specific hosting region has been selected or provisioned.

## What a sender can use

| Area | Implemented behavior | Current boundary |
|---|---|---|
| Agreements | Upload and reorder multiple PDFs; retain original files; download the combined signed PDF or individual signed PDFs | 10 source PDFs, 8 MiB combined, 100 pages, 200 fields, 25 recipients |
| Preparation | Eight field types, editable text/anchor suggestions, repeat initials, drag/resize/keyboard placement, undo, reusable versioned templates | Every placement needs sender review; rotated pages are rejected |
| Scanned documents | Local OCR proposes fields from raster pages | Bundled English model; at most 10 scanned pages per pass, bounded process and timeout; no cloud OCR upload |
| Fields and routing | Optional answer fields, conditions on another answer, parallel/sequential/group signing | Conditions are exact comparisons against an unconditional input of the same recipient; no arbitrary scripts or branching approval graph |
| Delegation | Sender opts in per person; transfer revokes old links and embedded sessions, sends the new invitation and records the chain in proof | At most three transfers; mailbox/link possession is recorded, not a government identity check |
| Supporting files | Request up to three labeled PDF/PNG/JPEG files per signer; required files block completion; hashes and originals travel with the proof kit | 4 MiB each, 8 MiB across the agreement; files are visible to all recipients with the completed proof kit; no antivirus certification |
| Bulk agreements | Download a CSV guide, review recipients, choose invitation delivery, queue one private agreement per row, inspect failures and cancel waiting rows | 1,000 rows per job; immutable template version; three active jobs per workspace; ordinary account quotas apply |
| Background exports | Freeze completed agreement IDs, build individual portable proof kits, download a paginated checksum manifest and resume downloads | 10,000 agreements per job, 64 MiB per part; job payload/download expiry 24 hours; no single huge in-memory archive |
| Privacy operations | Register a request, record authority review, find related records, export requester data, restrict new processing, erase workspace profile, schedule eligible agreement deletion and record a response | Workspace scope; legal holds and seven-day deletion grace remain enforced. Backups, other workspaces, external copies and global account closure require operator work. Signed contracts are not silently rewritten |
| API integration | Scoped expiring keys, idempotent writes, cursor pages, durable signed callbacks, embedded sessions, JavaScript/Python/.NET clients | Automated local clients have passed; an unrelated customer has not completed production acceptance |

Use `/workspace` for database-backed bulk, privacy, team and security features. The older `/studio/...` demo uses a file store and does not include the database account workflows.

### Beginner path

1. Open **Send for signature** and use the practice PDF or upload your own harmless test files.
2. Put the PDFs in the order recipients should read them. Add people, choose their language and signing order, and optionally require an email code or supporting files.
3. Open the field editor. Use suggested fields or **Read a scanned PDF**, review every suggestion, assign each to a recipient, and correct positions on the actual page.
4. Clear the readiness messages, create the agreement, and send invitations. Recipient progress and delivery status show different facts: SMTP acceptance is not inbox receipt.
5. Complete signing from the recipient link. Save the signed document and portable proof kit. Verify the proof with a public key trusted through a separate channel.
6. Save repeated preparations as a template. **Batches & exports** provides a template-specific CSV guide and per-row progress. **Privacy requests** is available to authorized administrators.

## Google Workspace and provisioning

Create a Google web OAuth client in an account controlled by the operator. Register the exact redirect URI `https://hesigns.homeequal.ai/auth/google/callback` and configure the consent screen. Mount a private JSON file and set `HE_SIGNS_GOOGLE_CONFIG_FILE` to its path:

```json
{
  "client_id": "REPLACE.apps.googleusercontent.com",
  "client_secret": "REPLACE_WITH_PROVIDER_SECRET",
  "workspaces": {
    "customer_workspace_id": {
      "domain": "customer.example",
      "auto_provision_role": "sender",
      "require_sso": true
    }
  }
}
```

Enroll a domain only after confirming company authorization. Each domain maps to one workspace. Use `viewer` for read-only enrollment or `null` to require existing membership/provisioning. Google issuer, signature, audience, expiry, verified email, exact hosted domain, nonce, PKCE and one-use browser-bound state are checked. Existing MFA requirements remain effective. Disabling an employee blocks automatic reenrollment. Keep an administrator recovery procedure outside public self-signup.

SCIM endpoints under `/v2/scim` support user discovery, create/read/update, add/replace patches, `userName eq "email"` filtering, paging and deactivation. Use an expiring credential with only `provisioning:manage` in `Authorization: Bearer ...`. Deactivation revokes workspace sessions and outstanding invitations. Elevated owners/admins require deliberate role transfer. Groups, arbitrary role mapping, SCIM bulk, password changes and email renames are unsupported and are not advertised as supported. The actual company provisioning connector must still be configured and tested; Google OAuth does not itself synchronize employee deletion.

Official references: [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect), [Google token verification](https://developers.google.com/identity/gsi/web/guides/verify-google-id-token), [SCIM protocol](https://www.rfc-editor.org/rfc/rfc7644.html).

## International operation and regional storage

The signing ceremony offers English, Spanish, French and Arabic, including RTL layout, localized dates and recorded consent language. A template can choose a default language per role; the signer can change it. Document contents, names and sender-written prompts retain their original language. The entire sender/admin portal and every API/error message are not translated. Professional review of translations and jurisdiction-specific consent is pending.

The document renderer accepts an explicitly configured licensed font through `HE_SIGNS_PDF_FONT_FILE` and rejects missing glyphs. Local tests cover accented Latin, Cyrillic, Arabic, Hebrew and Greek with a locally licensed font. This does not establish coverage of every script or correct typography for every mixed-script document. No system font from this computer is redistributed.

Deploy a separate API, worker, database, secrets and backup policy in each approved region. Set `HE_SIGNS_DATA_REGION` to that deployment's real identifier. Tenants are pinned to it; mismatched API credentials and account sessions are rejected, and production startup refuses a database containing other-region or unassigned tenants. Existing tenants require an operator-reviewed migration/backfill before production startup. A region label does not prove physical location: the operator must verify database, replicas, backups, logs, email, timestamps and other subprocessors. There is no automatic global replication or provisioned worldwide hosting.

## Signature assurance

- Optional `email_otp` verifies current access to the assigned mailbox before document access and completion. Codes expire in 10 minutes, have five guesses, a resend cooldown and a request limit; verified sessions last 30 minutes. This is not government identity verification. Third-party cookie restrictions can prevent a code session from working inside a cross-site iframe; open the signing session in a top-level window for that flow.
- Set `HE_SIGNS_PDF_CERTIFICATE_FILE` to an RSA PKCS#12 service certificate and `HE_SIGNS_PDF_CERTIFICATE_PASSWORD_FILE` to its password file. The runtime requires a matching private key and currently valid certificate. Completed PDFs, including individual packet files, receive detached CMS signatures embedded in the PDF. This is a **service seal**, not a personal qualified signature. CA trust, revocation and Adobe trust-list recognition depend on the real certificate and must be tested separately.
- Set `HE_SIGNS_TIMESTAMP_URL` and `HE_SIGNS_TIMESTAMP_CA_FILE` for an approved HTTPS RFC3161 authority; optionally set `HE_SIGNS_OPENSSL_PATH`. The runtime checks imprint, nonce and trusted chain before accepting a timestamp. A failed configured seal/timestamp prevents completion and rolls back the database transaction. Requests, responses and verification instructions are included in the proof kit. Local testing uses a temporary test authority; no commercial authority has been activated.
- The offline browser verifier checks signed evidence and artifact hashes. Certificate and timestamp chain validation is a separate step using the included instructions and independently trusted roots. No claim is made of QES, PAdES long-term validation, notarization, independent identity verification or universal legal acceptance.

Operator dependencies: a real certificate, trusted timestamp contract/root, renewal and revocation procedures, protected key custody, and country-specific acceptance review. [PDF signature library](https://github.com/vbuch/node-signpdf), [OpenSSL timestamp verification](https://docs.openssl.org/3.6/man1/openssl-ts/).

## API details for the new workflows

`GET /v2/envelopes?limit=100&cursor=...` returns `data`, `has_more`, `next_cursor`. Cursors are opaque. `documents` and legacy `document` are mutually exclusive. Field page numbers address the final combined PDF. Reordering sources changes the customer authorization manifest.

`POST /v2/bulk` takes `template_id`, exact `version`, `rows`, `confirm:true` and explicit `send_invitations`. Each row supplies a unique `client_reference` and `assignments` keyed by template role. Use a persistent `Idempotency-Key`. Template roles control language, authentication, delegation and attachment policy; assignment objects cannot weaken them.

For customer-authorized bulk work, call `POST /v2/bulk/prepare-row` with the **same batch Idempotency-Key**, `template_id`, `version`, zero-based `row_index` and `row`. Sign the returned canonical manifest with the customer-held Ed25519 private key, then place its base64 signature in that row's `sender_authorization.signature`. Submit the identical ordering/assignments in the batch. Keys are deterministic per tenant, batch key and row index. The service never receives the customer private key. The CSV UI does not hold customer signing keys; enrolled customers use this server integration flow.

`POST /v2/exports/jobs` takes either `{"all":true}` or `{"ids":[...]}` and an Idempotency-Key. Poll the returned job using `GET /v2/exports/jobs/{id}`. Iterate result pages with numeric `after=next_cursor`; download `/parts/{item}` and verify the returned manifest hash. Node `sdk/download-export.mjs` and Python `download_export` resume existing valid files and reject changed files. Failed rows remain explicit. Deleting an agreement revokes its export copies.

The generated OpenAPI contract documents 73 paths, new scopes and policy inputs. Download the .NET client from `/sdk/dotnet.zip`. Keep SDK credentials on the customer's server. Provider activation, external acceptance, deployment image validation and independent security review remain launch gates.