@splitin/verification-postgres 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SplitInTech
+
+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/NOTICE

@@ -0,0 +1,32 @@
+Verification Adapter SDK
+Copyright (c) 2026 SplitInTech
+
+This product is licensed under the MIT License. See LICENSE.
+
+Third-party notices
+===================
+
+This project redistributes no vendor identity SDKs in its core or server
+packages. Optional peer dependencies used by browser plugins:
+
+- `@stripe/stripe-js` — Stripe, Inc. (MIT). Used only by the Stripe Identity
+  browser plugin via dynamic import. Stripe is a trademark of Stripe, Inc.
+- `persona` — Persona Identities, Inc. Used only by the Persona browser plugin
+  via dynamic import.
+- `react-plaid-link` — Plaid Inc. (MIT). Used only by the Plaid Identity
+  Verification browser plugin via dynamic import. Plaid is a trademark of
+  Plaid Inc.
+
+Server adapters speak HTTPS to provider APIs with an injected Fetch
+implementation. They do not bundle Stripe, Persona, or Plaid Node SDKs.
+
+Runtime and tooling (declared in package.json; not vendored):
+
+- `ajv` — MIT
+- `jose` — MIT (Plaid webhook JWT verification)
+- `pg` — MIT (optional PostgreSQL executor)
+- TypeScript, tsup, vitest, Changesets — Apache-2.0 / MIT as published by
+  their authors
+
+This project provides engineering primitives. It is not a legal, KYC, KYB, or
+regulatory compliance certification.

package/QUERY_PLANS.md

@@ -0,0 +1,90 @@
+# Query plan notes for schema `verification`
+
+Live `EXPLAIN (FORMAT JSON)` coverage runs in `tests/live.test.ts` when
+`VERIFICATION_DATABASE_URL` is set (CI PostgreSQL 15 and 16). Hosts should
+still capture `EXPLAIN (ANALYZE, BUFFERS)` against production-like data after
+applying `001_init.sql` and `003_retention.sql`.
+
+## Route selection
+
+```sql
+SELECT *
+FROM verification.routes
+WHERE tenant_key = $1
+  AND environment = $2
+  AND package_code = $3
+  AND lifecycle = 'active'
+  AND (country_code IS NULL OR country_code = $4)
+ORDER BY priority, id;
+```
+
+Intended index: `routes_active_selection_idx` (partial on `lifecycle = 'active'`).
+The planner should perform an index range scan on `(tenant_key, environment, package_code)`
+and filter country/cohort/window in memory. Do not sequential-scan `routes`.
+
+## Active attempts
+
+```sql
+SELECT *
+FROM verification.attempts
+WHERE tenant_key = $1
+  AND subject_hash = $2
+  AND package_code = $3
+  AND canonical_status IN (
+    'created', 'pending_user_input', 'paused', 'processing', 'manual_review_required'
+  )
+ORDER BY updated_at DESC;
+```
+
+Intended index: `attempts_active_idx`. Partial index keeps live rows only.
+
+## Valid decisions
+
+```sql
+SELECT *
+FROM verification.decisions
+WHERE tenant_key = $1
+  AND subject_hash = $2
+  AND package_code = $3
+  AND status = 'verified'
+  AND revoked_at IS NULL
+  AND (expires_at IS NULL OR expires_at > now())
+ORDER BY effective_at DESC
+LIMIT 1;
+```
+
+Intended index: `decisions_valid_idx`. Provider health and circuit state must not
+appear in this plan; unexpired verified decisions are reused independently.
+
+## Pending webhook / reconcile / redaction jobs
+
+Workers claim with:
+
+```sql
+SELECT *
+FROM verification.reconciliation_jobs
+WHERE tenant_key = $1
+  AND state IN ('scheduled', 'retryable')
+  AND next_attempt_at <= now()
+ORDER BY next_attempt_at, id
+FOR UPDATE SKIP LOCKED
+LIMIT $2;
+```
+
+Intended indexes: `reconciliation_pending_idx`, `redaction_pending_idx`,
+`webhook_leases_work_idx`. `FOR UPDATE SKIP LOCKED` avoids lock waits under
+bounded concurrency. Never `SELECT FOR UPDATE` without `SKIP LOCKED` on the
+worker path.
+
+## Idempotency before provider I/O
+
+```sql
+INSERT INTO verification.idempotency_claims (tenant_key, claim_key, operation, attempt_id, state)
+VALUES ($1, $2, $3, $4, 'claimed')
+ON CONFLICT (tenant_key, claim_key) DO NOTHING
+RETURNING *;
+```
+
+Primary key `(tenant_key, claim_key)` makes this an index unique insert.
+Commit this transaction **before** the provider HTTP call. Bind the provider
+resource in a second short transaction.

package/README.md

@@ -0,0 +1,13 @@
+PostgreSQL persistence for `@splitin/verification-engine`. Schema name is
+fixed to `verification`. Hosts inject a `query(sql, params)` executor
+compatible with `pg` and serverless clients. `pg` is an optional peer
+dependency.
+
+```ts
+import { createPostgresStore, createPostgresQueue } from '@splitin/verification-postgres';
+```
+
+Subject and resource references are HMAC-hashed with an injected secret
+before they cross the database boundary. Raw webhooks, launch credentials,
+hosted URLs, documents, selfies, and expanded identity outputs are never
+persisted.