app.api-founder-suite-monolith

Pactena Founder Intelligence API

Standalone Elysia host for Pactena Founder, Executive, and Talent Intelligence. The PostgreSQL and independent AuthOS layers are live; optional email and AI capabilities remain truthfully blocked until their provider credentials exist.

Environment

Server-only variables:

• PACTENA_DATABASE_URL
• PACTENA_DATABASE_RUNTIME_ROLE pins the exact non-owner login expected by startup and readiness. The role must own no tables and must not create roles, databases, or schema objects, replicate, or bypass RLS. Runtime readiness verifies public schema structure and grants but leaves the forced-RLS SEO seed inspection to the explicit migration-owner verification lane.
• PACTENA_WAITLIST_DATABASE_URL (low-privilege waitlist writer)
• DATABASE_URL is never accepted. The waitlist credential must resolve to the same protocol/host/port/database identity as PACTENA_DATABASE_URL.
• BETTER_AUTH_SECRET
• BETTER_AUTH_BASE_URL (defaults to https://api.pactena.run)
• APP_WEB_BASE_URL (defaults to https://app.pactena.run)
• MARKETING_WEB_BASE_URL (defaults to https://www.pactena.run)
• PACTENA_LSSM_RP_ENABLED, PACTENA_LSSM_RP_SECURITY_REVIEW_REF, and PACTENA_LSSM_RP_CLIENT_SECRET for the reviewed central LSSM OIDC relying party. Enablement without review evidence or a 32+ character secret fails startup closed.
• PACTENA_MEMBERSHIP_PROVISION_TOKEN is the 32+ character, server-only token used by central AuthOS to idempotently create an app_pactena membership. Product routes require that local membership even when a Better Auth session exists.
• PACTENA_GOVERNED_DATA_DATABASE_URL selects the separate product-local encrypted projection-copy store. PACTENA_GOVERNED_RECOVERY_TOKEN is its distinct 32+ character central-worker bearer; PACTENA_GOVERNED_DATA_AUTO_MIGRATE=true and PACTENA_GOVERNED_DATA_SSL_MODE=require|allow|prefer control explicit schema activation and transport. Do not enable the central Pactena recovery origin until every governed projection copy uses this canonical store. Export stays unavailable until a Pactena source exporter is bound.
• PACTENA_GOVERNED_DATA_REGION and the secret-manager JSON value PACTENA_GOVERNED_MATERIALIZATION_BINDINGS jointly enable encrypted-copy admission at /internal/governed-data/materializations/:sourceApplicationId. Each array record has exact keys sourceApplicationId and bearerToken, and each source-to-Pactena pair uses a distinct 32+ character bearer. Omit both to keep materialization unavailable while recovery remains active. Partial topology, unknown sources, purpose/field/region/expiry/retention/key drift, and plaintext fail closed before persistence. Production also requires the receiver key service and retention cleanup to be qualified.
• PACTENA_VAULT_ENCRYPTION_KEY
• PACTENA_WAITLIST_TOKEN_SECRET
• CRON_SECRET
• OPENAI_API_KEY and optional PACTENA_OPENAI_MODEL (gpt-5.6-luna)
• MISTRAL_API_KEY and optional PACTENA_MISTRAL_MODEL (mistral-small-2603)
• RESEND_API_KEY and AUTH_EMAIL_FROM
• PACTENA_FORMS_MILESTONES (forms.v0 by default, or all)
• PACTENA_FORMS_VERIFICATION_ENDPOINT, bearer token, and channel list
• PACTENA_FORMS_AI_ENDPOINT, bearer token, provider ID, and self-hosted flag
• PACTENA_FORMS_DEFENSE_ENDPOINT, bearer token, and identifier secret for distributed fail-closed abuse control
• COMPANY_OS_METRICS_API_ORIGIN, COMPANY_OS_METRICS_PACTENA_ISSUER, and COMPANY_OS_METRICS_PACTENA_SHARED_SECRET for short-lived, scope-bound CompanyOS metric session exchange

The /api/v1/company-metrics peer proxy has an explicit operation allowlist, requires the Pactena application origin and an idempotency key for mutations, and derives company scope from fresh session authority. Founder-private scope is not representable by this proxy.

No provider key or database URL has a fixture fallback in production.

Conversations, notifications and calendar

The CommunicationOS BFF under /api/v1/communication-os/* exchanges the session for a scoped CommunicationOS bearer and forwards an explicit operation allowlist. It includes the canonical contract send POST /api/v1/communication-os/communication/message/send/v3.0.0 used by the shared client: the app origin, a matching idempotency-key header and body idempotencyKey, and the session-derived workspace and space are required, so a retry replays the original message and a founder-private room never accepts a company-scoped send. Reconnect uses POST .../v2/auth/realtime-ticket and cursor replay through GET .../v2/events.

GET and POST /api/v1/notification-preferences are the Pactena preference center over @lssm-tech/lib.notification/product-channels: in-app is always on and updates are revision-checked. An update sends expectedRevision, globalEnabled, enabledChannels and consentedChannels; the BFF mints each consent ref from the session (person, channel and new revision), so email is enabled only with that explicit consent and a client never supplies consent evidence. Responses list consentedChannels, never the refs. A stale revision answers 409 idempotency_conflict, the conflict code of the Pactena error vocabulary. POST /api/v1/calendar/intake imports upcoming founder-private calendar meetings the founder has not declined as digest-only OPA meeting workspaces through the shared intake materializer, and answers only its counts. Both mutations require the app origin and x-csrf-token equal to the session id, like the meeting workspace, and cap the body (8 KB for preferences, 1 KB for intake, which takes none); the CommunicationOS send reads at most 64 KB even for chunked uploads. Both answer 503 dependency_unavailable until a preference store and CommunicationOS admission host, or a calendar connection host and intake materializer, are bound; nothing is bound in the deployed host today.

Public signup remains disabled. Direct magic links resolve existing invited emails only. When the reviewed LSSM relying party is enabled, the local Pactena identity may be projected from a centrally authenticated email only after the central app_pactena entitlement gate succeeds; the exact product scope is requested and no ecosystem cookie is shared with Pactena. Central activation also unregisters Pactena's local magic-link plugin and email callback. Disabling the RP restores that existing-email path as the explicit rollback authority; the two authorities are never enabled together.

Forms management is exposed at /forms, public forms at /f/{opaqueToken}, and the API at /api/forms/v1. Migrations 0003_forms_platform.sql and 0004_forms_scope_hardening.sql are the Pactena-owned immutable Forms schema and row-bound public-access upgrade.

Database lifecycle

Database changes never run during startup or request handling. Operators use the explicit database:plan, database:bootstrap:fresh, database:adopt-0001, database:migrate, database:verify, database:snapshot:verify, database:reset:nonlive, and database:prove:postgres scripts. Mutating lanes require an evidence reference; the non-live reset additionally requires a typed allowlisted fingerprint, a fresh encrypted snapshot receipt, provider effects disabled, and approved same-task Connect decision plus passed replay artifacts.

Migration 0001 remains immutable at sha256:216989309872df7873bb983ec37439c68c93bb8e0165035b93eadb4e6f86daff. Pactena-owned migration 0002 creates the fresh-only 31-table OPA v2 schema, pins all 28 owner tables to product_ref='pactena', and records both versions in pactena_owned_migration_ledger. Adoption verifies the exact 0001 catalog before recording provenance. Full reset/adoption execution remains blocked until external database, snapshot, and Connect authority exists.

Migration 0005 installs the forced-RLS governed meeting workspace tables; 0007 adds digest-only public access grants and 0008 adds owner-scoped calendar occurrence mappings plus immutable recorder-review evidence. 0009 adds recurring intake definitions and expiring, token-fenced execution leases. The Elysia host mounts the nineteen exact /api/v2/opa/meeting-* and /api/v2/opa/smart-meetings/* operations with Better Auth session-derived organization scope. Mutations require the Pactena app origin and the current session id as CSRF evidence. Meeting content is recovered from an encrypted, optimistically versioned owner aggregate; approval, artifact, dispatch, CRDT, share, recorder, and outbox evidence remains on the dedicated SQL surfaces.

The current fresh schema contains exactly 84 public tables: 18 immutable Pactena baseline tables, 52 OPA tables, 12 Forms tables, pactena_product_memberships, and pactena_owned_migration_ledger. Forms verification is pinned to the 12 tables created by immutable migrations 0003/0004; newer shared Forms features require an explicit Pactena migration. It deliberately preserves unrelated tables. Reset authorization, snapshot proof, and Connect replay remain pending; this inventory does not authorize execution.

The read-only readiness probe reports bounded verification phases (ledger, tables, inventory, rls, grants, products, or seed) and a safe SQLSTATE. It never logs SQL, credentials, connection details, or provider error messages. Privilege repairs must use the explicit same-database PACTENA_DATABASE_MIGRATION_URL; never grant ledger access to PUBLIC.